@synap-core/pod-client

Shared pod lifecycle client — create, poll, delete managed pods via the Synap Control Plane.

Scope: this package owns the pod row's lifecycle only. It does NOT own auth (see @synap-core/auth), IS provisioning (see @synap-core/intelligence-connect), or pod classification (see @synap-core/platform-flow).

Why separate

• platform-flow = pure classification (Node-safe, no fetch)
• auth = session + pod handshake (credentials)
• intelligence-connect = IS provisioning (tier-2, on existing pod)
• pod-client = CP lifecycle management (this package)

Usage

import {
  createAndStartManagedPod,
  fetchPodStatus,
  pollPodStatus,
  deletePod,
  type PodClientConfig,
} from "@synap-core/pod-client";

const config: PodClientConfig = {
  cpBaseUrl: "https://api.synap.live",
  getBearerToken: async () => sessionStore.get("cp-token"),
};

// From a user-initiated confirm dialog:
const { podId } = await createAndStartManagedPod(config);

// Show a loader that polls until terminal:
const final = await pollPodStatus(config, podId, {
  onUpdate: (s) => console.log(s.phase, s.statusMessage),
});

React hosts use the hook subpath:

import { usePodStatus } from "@synap-core/pod-client/react";

const { status, isPolling, error, cancel } = usePodStatus(config, podId, {
  onReady: (s) => router.push(`/pod/${s.id}`),
});

Cancel semantics

CP returns 409 Conflict on DELETE /pods/:id when the pod is in an active provisioning state (pending, creating_server, configuring_dns, waiting_dns, deploying_services, waiting_health, syncing_intelligence, sending_invitation).

UI callers should:

• Disable the cancel button during those states (tooltip: "wait ~30s")
• Enable it when status.phase === 'pending' or status.phase === 'errored'
• On confirmed delete, call deletePod(config, podId) and handle the { success: false, status: 409 } case gracefully (user cancelled right as the first step started).

Phase derivation

phase is derived client-side on every fetch. Callers should switch on phase not status — the CP status enum is owned by CP and will grow.