@sanqian-ai/cloud-client

Typed client SDK for the Sanqian Cloud managed gateway: login (GitHub OAuth / email code), account status and credits, streaming chat, embedding, speech-to-text, text-to-speech, billing (checkout / customer portal), and in-app feedback. Zero runtime dependencies; Node 18+.

D35 custody rule: application runtimes do not read the machine accountSession. The hub owns a full createCloudClient() for control-plane calls; provider hosts use createCloudManagedExecutionClient() plus a per-operation capability returned by ResourceStore.managed.prepare() (normally assembled for them by @sanqian/managed-executor).

import { createCloudManagedExecutionClient } from '@sanqian-ai/cloud-client'

const execution = createCloudManagedExecutionClient({
  // Optional allowlist; the prepared capability carries the broker-pinned
  // gatewayOrigin so hosts do not maintain a second endpoint config.
  allowedGatewayOrigins: ['https://api.sanqian.io'],
})
const prepared = await resourceStore.managed.prepare({
  connectionId, modelId, modality: 'chat', estimatedTokens,
})
let completed = false
try {
  const result = await execution.chatPrepared({ prepared, messages, onDelta })
  completed = true
  // consume result
} finally {
  // @sanqian/managed-executor does this automatically when its iterator is
  // abandoned. Direct consumers must release an unfinished capability too.
  if (!completed) await execution.cancelPrepared(prepared)
}

estimatedTokens on prepare is a client admission hint only. The gateway re-estimates the complete start/invoke request and atomically reserves that canonical amount before provider execution. Gateway-authoritative D35 terminals make finish/settle bounded audit ACKs; an ACK transport failure does not turn an already completed response into a duplicate provider retry. cancelPrepared() is execution-plane only: it uses the scoped sessionRef, never accountSession, and probes started-before-issued state idempotently. TTL is the final backstop, not the normal cleanup path.

Canonical integration guide: docs/cloud-product-integration.md; architecture decision: docs/decisions.md D35. Errors are stable-coded via CloudClientError.code.