TypeScript client

@sovran-ai/client is the client the Sovran CLI uses, packaged for your own Node.js code. It validates each request and result with the same contracts as the API. Every operation ID and its request and result are typed. Node.js 22 or later is required. The package has no runtime dependencies.

npm install @sovran-ai/client@0.1.0

Send a request

import { createSovranClient, SovranApiError } from '@sovran-ai/client'

const client = createSovranClient({ origin: 'https://sovran.ai', apiKey: process.env.SOVRAN_API_KEY! })
const projects = await client.request('get__projects', { query: { limit: 10 } })
console.log(projects.data.items.map(project => project.name))

Each request sends once. A change requires idempotencyKey. Save the key with the exact request before you send it, and reuse it only to read the saved result of that request after an unknown outcome. The client never retries by itself.

Errors are typed. SovranApiError has the HTTP status, error code, details, and requestId. Codes upstream_unavailable and rate_limited_upstream mean a gateway or platform page answered: the outcome of a change is unknown, so read the resource before you send it again. SovranClientInputError reports a request that failed validation before it was sent. SovranClientResponseError reports a result that failed validation; for a change, its payload keeps the accepted result so you do not lose the job ID.

Upload, wait, and download

import { createSovranClient, uploadAsset, waitForJob, downloadMedia } from '@sovran-ai/client'

const options = { origin: 'https://sovran.ai', apiKey: process.env.SOVRAN_API_KEY! }
const client = createSovranClient(options)
const upload = await uploadAsset({ ...options, client, projectId, type: 'video', filePath: 'clip.mp4', statePath: 'clip-state.json' })
const job = await waitForJob({ client, jobId, timeoutMs: 300_000 })
await downloadMedia({ client, source: { kind: 'render', id: renderId, aspectRatio: '9:16' }, outPath: 'finished.mp4' })

Uploads keep request tokens and transfer progress in the private statePath file. Run the same call with the same file and state to resume. waitForJob reads only while a job is queued, running, or waiting. Any other final status throws WorkflowStoppedError with the last result. Downloads stream one file to a new path and never send your API key to storage.

Run a named video workflow

runSovranTask runs the same named workflows as the MCP server and sovran task run. It takes the same arguments and returns guidance with the next calls and review stops.

import { createSovranClient, runSovranTask, listSovranTasks } from '@sovran-ai/client'

const origin = 'https://sovran.ai'
const client = createSovranClient({ origin, apiKey: process.env.SOVRAN_API_KEY! })
const created = await runSovranTask({ client, origin, name: 'create_video_variations',
  input: { projectId, body: { sourceAssetIds: [assetId] }, idempotencyKey } })
console.log(created.guidance.nextCalls)
console.log(listSovranTasks().map(task => task.name))

Creation tasks stop at editable drafts. Review them and the estimated cost before an export task.

Verify webhooks

import { verifyWebhookSignature } from '@sovran-ai/client'

// A Fetch API handler, such as a Next.js route.
export async function POST(request: Request) {
  const rawBody = new Uint8Array(await request.arrayBuffer())
  if (!verifyWebhookSignature(rawBody, request.headers.get('sovran-signature'), process.env.SOVRAN_WEBHOOK_SECRET!)) {
    return new Response(null, { status: 401 })
  }
  const event = JSON.parse(new TextDecoder().decode(rawBody))
  // Save the event durably, then acknowledge it.
  return new Response(null, { status: 204 })
}

In a Node.js http handler, read the header with request.headers['sovran-signature'] as string | undefined. Pass the exact raw body bytes before you parse JSON. The check rejects a timestamp more than five minutes from your server clock. See jobs and webhooks for delivery rules.

Versions

Each client version bundles the API catalog of its release, like the CLI. Upgrade for new operations. Server access checks, plan rules, and limits always apply.