Status and streams

A payment or a KYC check does not finish when the tool call returns: the provider settles or decides later and reports it by webhook. These four methods correlate a tool_call_id (the one execute returns) back to the latest known disposition. Two poll; two hold an SSE stream open and resolve with the last envelope.

The streams share one lifecycle: the server pushes a snapshot event with the current state on open, an update per transition, a heartbeat every 15 seconds so proxies keep the connection, and a done event after a terminal state, followed by a 5-second grace period before it closes. The promise resolves with the last envelope seen, so a caller that only wants the terminal state can await without wiring onUpdate. The polling siblings stay available.

paymentStatus

The settlement state of a codespar_charge or codespar_pay call. payment_status is independent of the execute-time result in original_status: a successful execute can still be pending, and a settled payment can later be refunded. unknown means the call carried no idempotency key (a legacy or non-meta-tool call), so there is nothing to correlate.

let status = await session.paymentStatus("tc_0000000000000000");
while (status.payment_status === "pending") {
  await new Promise((r) => setTimeout(r, 2000));
  status = await session.paymentStatus("tc_0000000000000000");
}
console.log(status.payment_status, status.events.length);

interface PaymentStatusResult {
  tool_call_id: string;
  payment_status: "pending" | "succeeded" | "failed" | "refunded" | "updated" | "unknown";
  /** Null for legacy / non-meta-tool calls */
  idempotency_key: string | null;
  /** The execute-time status (success/error) */
  original_status: string;
  events: PaymentStatusEvent[];
}

interface PaymentStatusEvent {
  event_type: string;
  received_at: string;
  provider: string | null;
  provider_action: string | null;
  payment_id: string | null;
}

Throws a CodesparApiError on a non-2xx answer (a 404 for an id the caller's organization does not own) or a transport failure, a TimeoutError on timeout.

Related REST GET /v1/tool-calls/{id}/payment-status, Webhooks for the events this reads.

paymentStatusStream

The SSE sibling of paymentStatus. Every onUpdate receives the same envelope shape paymentStatus returns, so one renderer serves both. signal cancels from the caller side; the backend sees a normal disconnect. The timeout is an idle timeout that resets on every complete SSE frame, heartbeats included.

const ctrl = new AbortController();
const last = await session.paymentStatusStream("tc_0000000000000000", {
  onUpdate: (s) => console.log("payment:", s.payment_status),
  signal: ctrl.signal,
});
console.log("terminal:", last.payment_status);

interface PaymentStatusStreamOptions {
  onUpdate?: (envelope: PaymentStatusResult) => void;
  signal?: AbortSignal;
  /** Idle timeout in ms; overrides the client default */
  timeout?: number;
}

Throws the caller's abort reason when signal fires; a TimeoutError when no frame arrives within the idle timeout; a CodesparApiError when the response is not 2xx or the transport fails; a plain Error if the stream closes before its first snapshot.

Related REST GET /v1/tool-calls/{id}/payment-status/stream.

verificationStatus

The disposition of a codespar_kyc call. After the call returns, the subject completes the hosted flow off-platform; this reads the latest state the provider reported. Priority when several events exist: approved over rejected over review over expired over pending. hosted_url is the buyer-facing link when the rail has one, null for server-side scoring rails.

const kyc = await session.verificationStatus("tc_0000000000000000");
if (kyc.verification_status === "approved") {
  // proceed
} else if (kyc.hosted_url) {
  console.log("finish here:", kyc.hosted_url);
}

interface VerificationStatusResult {
  tool_call_id: string;
  verification_status: "pending" | "approved" | "rejected" | "expired" | "review" | "unknown";
  idempotency_key: string | null;
  original_status: string;
  /** Buyer-facing verification URL; null for server-side scoring rails */
  hosted_url: string | null;
  events: VerificationStatusEvent[];
}

interface VerificationStatusEvent {
  event_type: string;
  received_at: string;
  provider: string | null;
  verification_id: string | null;
}

Throws as paymentStatus.

Related REST GET /v1/tool-calls/{id}/verification-status, codespar_kyc.

verificationStatusStream

The SSE sibling of verificationStatus, with the same lifecycle as paymentStatusStream: snapshot on open, an update per change, close after a terminal disposition.

const last = await session.verificationStatusStream("tc_0000000000000000", {
  onUpdate: (s) => console.log("kyc:", s.verification_status),
});
console.log(last.verification_status);

interface VerificationStatusStreamOptions {
  onUpdate?: (envelope: VerificationStatusResult) => void;
  signal?: AbortSignal;
  /** Idle timeout in ms; overrides the client default */
  timeout?: number;
}

Throws as paymentStatusStream.

Related REST GET /v1/tool-calls/{id}/verification-status/stream.