@dialgem/sdk 0.1.0-beta.0 → 0.1.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.1.0-beta.2
+
+### Not in this SDK, on purpose
+Campaigns, webhook endpoint management, usage, billing, analytics, and contact erasure / do-not-call are dashboard-only. See the surface policy in the Python SDK's `docs/api-surface.md`.
+
+### Breaking changes
+- **The API address is fixed at `https://api.dialgem.com`.** The `baseURL` option and the `DIALGEM_BASE_URL` environment variable are gone. Passing `baseURL` now throws rather than being ignored, so a leftover staging or local URL cannot quietly send your key to production. `DEFAULT_BASE_URL` is renamed `BASE_URL`.
+- **Webhook signatures are timestamped.** `x-dialgem-signature` is now `v=<timestamp_ms>,d=<hex>`, where the HMAC covers the raw body plus the timestamp. `verify` and `constructEvent` also reject signatures more than 5 minutes old; set `toleranceMs` or `now` to change that. Signatures from 0.1.0-beta.0 no longer verify.
+- **Webhook payloads carry the full call record.** Every event is `{ event, call_id, agent_id, call }`. The flat fields (`status`, `duration_s`, `analysis`) now live under `call`.
+- **`calls.list` pages are cursor-based.** A page is `{ data, has_more, pagination_key }`. `page`, `page_size` and `total` are gone; use `limit`.
+
+### Added
+- `sessions.say(sessionId, { text, interrupt? })` and `sessions.release(sessionId)`: make the agent speak a line on a live call, and hand a taken-over call back. Off unless the deployment enables live control (`live_control_disabled`). Listening in and taking over run over a WebSocket this SDK does not wrap. `sessions.update` now reaches a call on any service instance.
+
+- `sessions.update(sessionId, { system_prompt?, dynamic_variables? })`: change a live call's prompt and/or variables from the agent's next turn. `sessionId` is the session's id or the call's `call_id`. Only that call changes and it is not saved.
+- **Saved LLMs.** `llms` (`create`, `list`, `retrieve`, `update`, `delete`): a prompt and model set up once, attached with `llm_id` on `agents.create` / `agents.update`. Attaching copies the values; later edits or deletion do not change the agent, and `llm_id` cannot be sent with the fields it carries.
+- `agents.mcpServers.listTools(agentId, serverId)`: the server's tools with descriptions and argument schemas, from a live connection; stores nothing.
+- **Saved flows.** `flows` (`create`, `list`, `retrieve`, `update`, `delete`): build and check a conversation flow once, then attach it with `flow_id` on `agents.create` / `agents.update`. Attaching copies the flow; later edits or deletion do not change the agent.
+- **Chats.** `chats` (`create`, `list`, `retrieve`, `update`, `delete`, `sendMessage`, `end`, `rerunAnalysis`): text conversations with a prompt agent, with the agent's own prompt, model and functions.
+- Chats are billed per agent reply (a spent balance is a 402 `insufficient_credit`); `Chat.chat_cost` shows the spend (`null` for a team-member session). Webhook events `chat_started`, `chat_ended` and `chat_analyzed` are in the `WebhookEvent` union (`ChatStartedEvent`, `ChatEndedEvent`, `ChatAnalyzedEvent`); they carry `chat_id` and `chat`, not `call_id`, so narrow on `event` before reading `call`.
+- `calls.rerunAnalysis(callId)`, `contacts.retrieveByPhone(phone, { default_country })` and `apiKey.retrieve()` (who this key is; works for any scope).
+- **Agent simulations.** `simulations.createSuite`, `createCase`, `run` and `retrieveRun` (with the rest of `listSuites`, `retrieveSuite`, `updateSuite`, `deleteSuite`, `updateCase`, `deleteCase`, `listRuns`, `cancelRun`): save conversations a simulated caller has with your agent, run them in text against the draft or a published version, and check what it said and did. A suite's `publish_gate` can warn or block publishing a version until the draft has passed. Nothing is dialled or billed and the agent's tools are never really called.
+- **Inbound routing webhook.** `phoneNumbers.update(id, { inbound_webhook_url })` sets (or, with `null`, removes) a URL Dialgem asks, before an inbound call is answered, which agent should take it, with variables or metadata, or to reject it. `phoneNumbers.testInboundWebhook(id)` sends one signed test request; `phoneNumbers.rotateInboundWebhookSecret(id)` replaces the signing secret. `PhoneNumber` gains `inbound_webhook_url` and `inbound_webhook_secret_hint`, and `inbound_webhook_secret` in the one response that creates or rotates it.
+- `calls.update` (replace metadata), `calls.delete` and `calls.stop`.
+- `metadata` on `createPhoneCall` and `register`.
+- New call record fields: `metadata`, `dynamic_variables`, `start_timestamp`, `end_timestamp`, `ended_at`, `duration_ms`, `transcript_text`, `in_voicemail` and `latency` (per-stage p50/p90/p95/p99). Post-call analysis gains `call_summary` and `in_voicemail`.
+- `calls.list` filters: `agent_id`, `status` (one or several), `direction`, `call_type`, `disconnection_reason`, `from_number`, `to_number`, `user_sentiment`, `call_successful`, `start_after`, `start_before`, `metadata`, `sort_order`.
+- `webhooks.constructFunctionCall` verifies and parses signed requests to your custom functions (`{ name, call, args }`).
+- `AgentFunction.args_at_root`.
+- **Voice cloning.** `voices.clone({ name, files, consent_confirmed: true })` uploads audio and returns a voice private to your organization; `voices.delete(voiceId)` removes it at the provider and here. `Voice` gains `is_custom` and `created_by`. The upload is never retried, whatever `maxRetries` says.
+- `phoneNumbers.retrieve(phoneNumber)` looks a number up by its E.164 value.
+- **`agent_version: "latest_published"`** on a phone number and on `createPhoneCall` / `register`: a pointer that follows the newest publish rather than naming a version. A call still reports the concrete version it ran.
+- **Contacts.** `contacts` (`create`, `list`, `retrieve`, `update`, `delete`, `calls`), `contactLists` (`list`, `create`, `retrieve`, `update`, `delete`, `addContacts`, `removeContact`) and CSV import under `contacts.imports` (`inspect`, `create`, `list`, `retrieve`, `errors`, `commit`, `cancel`). A contact is keyed on its phone number, stored in E.164 however it is written (pass `default_country` for numbers without a `+`). `do_not_call` on a contact is read from your do-not-call list, not stored on it. Imports run in the background: start one with `dry_run: true`, poll `retrieve` until it is `previewed`, then `commit`. `contacts.list` pages by cursor like `calls.list`. CSV downloads (the export, and the rejected-rows report) are available over the REST API only.
+- **Browser calls.** `webCalls.create({ agent_id, metadata, dialgem_llm_dynamic_variables })` creates a call for one visitor and returns a one-use `access_token` (60 seconds) for `@dialgem/client`, so a web page can talk to an agent without your API key ever reaching the browser. Allow the pages that may start calls with `webCalls.updateSettings({ allowed_origins })` (`retrieveSettings` reads them back); `create` answers 409 `web_origins_not_configured` until at least one is set.
+- **Agent versions.** `agents.versions.publish` freezes an agent — its configuration, functions and MCP servers — as an immutable numbered snapshot; `list` and `retrieve` read them back. Pin one with `inbound_agent_version` / `outbound_agent_version` on a phone number, or `agent_version` on `createPhoneCall` and `register`. The version a call ran is reported as `agent_version` on the call record and in every webhook. The agent itself is the draft, version 0, and stays what every unpinned call runs.
+
 ## 0.1.0-beta.0 (unreleased)
 
 The first release.

package/README.md

@@ -1,11 +1,45 @@
-# @dialgem/sdk
+<div align="center">
 
-The official TypeScript SDK for the [Dialgem](https://dialgem.com) voice AI API. Use it from your backend to create voice agents, put them on phone numbers, place and register calls, pull transcripts, and verify webhooks.
+# Dialgem for TypeScript
 
-- Written in TypeScript. Request bodies are typed from the API's own schema, including the full conversation-flow node union.
-- Zero runtime dependencies. Ships ESM and CommonJS builds.
-- Node.js 20+. It also runs on Bun, Deno and serverless runtimes that provide `fetch` and Web Crypto.
-- Server-side only. Your API key grants full access to your organization.
+**The official TypeScript SDK for the [Dialgem](https://dialgem.com) voice AI API.**
+
+Build voice agents, put them on phone numbers, place calls, steer them live, and read transcripts, all from your backend.
+
+[![npm](https://img.shields.io/npm/v/@dialgem/sdk?include_prereleases&color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@dialgem/sdk)
+[![Node](https://img.shields.io/node/v/@dialgem/sdk?logo=node.js&logoColor=white)](https://www.npmjs.com/package/@dialgem/sdk)
+[![CI](https://img.shields.io/github/actions/workflow/status/DialgemAI/dialgem-sdk-typescript/ci.yml?branch=main&label=CI&logo=github)](https://github.com/DialgemAI/dialgem-sdk-typescript/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-typed-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Stars](https://img.shields.io/github/stars/DialgemAI/dialgem-sdk-typescript?style=flat&logo=github)](https://github.com/DialgemAI/dialgem-sdk-typescript/stargazers)
+
+[Website](https://dialgem.com) · [Issues](https://github.com/DialgemAI/dialgem-sdk-typescript/issues) · [Changelog](CHANGELOG.md) · [Python SDK](https://github.com/DialgemAI/dialgem-sdk-python)
+
+</div>
+
+---
+
+```ts
+import { Dialgem } from "@dialgem/sdk"
+
+const dialgem = new Dialgem() // reads DIALGEM_API_KEY
+
+const agent = await dialgem.agents.create({ name: "Front desk", system_prompt: "You answer for Acme Dental." })
+const { call_id } = await dialgem.calls.createPhoneCall({ from_: "+14155550100", to: "+14155550123", agent_id: agent.id })
+```
+
+## Why this SDK
+
+- **Typed end to end.** Request bodies are typed from the API's own schema, including the full conversation-flow node union, and webhook events are a discriminated union you can `switch` on.
+- **Zero runtime dependencies.** ESM and CommonJS builds, so it works from any Node project.
+- **Runs anywhere with `fetch`.** Node.js 20+, Bun, Deno and serverless runtimes that provide `fetch` and Web Crypto.
+- **Safe by default.** `POST` is never retried (a retry could ring someone twice), other requests retry with backoff and `Retry-After`, and redirects are never followed so your key can't be sent elsewhere.
+- **Everything a backend needs.** Agents (with tools, knowledge, MCP servers and versions), phone numbers, calls and chats, saved flows and LLMs, voices, contacts, live call control, and webhook signature verification.
+- **Server-side only.** Your API key grants full access to your organization. To talk to an agent from a web page, use [`@dialgem/client`](https://github.com/DialgemAI/dialgem-client-sdk).
+
+## Contents
+
+[Install](#install) · [Quickstart](#quickstart) · [Recipes](#recipes) · [Live call control](#live-call-control) · [Errors](#errors) · [Retries](#retries) · [Coverage](#coverage) · [Development](#development) · [License](#license)
 
 ## Install
 
@@ -37,7 +71,6 @@ const agent = await dialgem.agents.create({
 | Option | Default | |
 |---|---|---|
 | `apiKey` | `process.env.DIALGEM_API_KEY` | Organization API key. |
-| `baseURL` | `process.env.DIALGEM_BASE_URL`, then `https://api.dialgem.com` | Point at a self-hosted or local stack. |
 | `timeout` | `60000` | Milliseconds per attempt. |
 | `maxRetries` | `2` | See [Retries](#retries). |
 | `fetch` | global `fetch` | Custom implementation (proxy agent, instrumentation). |
@@ -94,9 +127,18 @@ const { call_id } = await dialgem.calls.createPhoneCall({
   to: "+14155550199",
   agent_id: agent.id,
   dialgem_llm_dynamic_variables: { customer_name: "Sam" },
+  metadata: { crm_id: "42" }, // your own data; returned on the call and in every webhook
 })
 ```
 
+Manage it afterwards:
+
+```ts
+await dialgem.calls.update(call_id, { metadata: { crm_id: "42", campaign: "renewals" } })
+await dialgem.calls.stop(call_id) // end it now; disconnection_reason becomes "manual_stopped"
+await dialgem.calls.delete(call_id) // a finished call: record, transcript and recording
+```
+
 ### 3. Bring your own Twilio number
 
 Point your Twilio number's Voice webhook at your backend. Register the call there, then return TwiML that connects Twilio's media stream to Dialgem:
@@ -118,7 +160,13 @@ Your Twilio credentials are never shared with Dialgem. `stream_url` is signed an
 
 ### 4. Verify webhooks
 
-Set `webhook_url`, `webhook_events` and `webhook_signing_secret` on the agent. Dialgem then POSTs `call_started`, `call_ended` and `call_analyzed` events, each signed with HMAC-SHA256 in the `x-dialgem-signature` header.
+Set `webhook_url`, `webhook_events` and `webhook_signing_secret` on the agent (and, optionally, `webhook_timeout_ms`, 1000–30000, default 10000, to bound how long each delivery attempt waits for your server). Dialgem then POSTs the events you subscribe to: `call_started`, `call_ended`, `call_analyzed`, `transcript_updated`, `transfer_started`, `transfer_bridged`, `transfer_cancelled` and `transfer_ended`. Each body is `{ event, call_id, agent_id, call }`, where `call` is the full call record; `transcript_updated` also carries `role`, `turn_index` and the `transcript` so far, and the transfer events carry `transfer: { target?, mode?, reason? }`. Each request is signed:
+
+```
+x-dialgem-signature: v=<timestamp_ms>,d=<hex>      hex = HMAC-SHA256(secret, raw_body + timestamp_ms)
+```
+
+`constructEvent` and `verify` check the HMAC and reject signatures more than 5 minutes old, so a captured request cannot be replayed. `call_ended` arrives as soon as the call ends; `call_analyzed` follows once the summary, sentiment and your extracted variables are ready. `transcript_updated` is sent per turn and may be retried out of order, so keep the highest `turn_index`. For a cold transfer, `transfer_bridged` is sent when the transferred leg finishes, followed by `transfer_ended`.
 
 > **Verify the raw body.** The signature covers the exact bytes Dialgem sent. A body that was parsed and re-serialized, for example by `express.json()`, will never verify, even when the JSON is identical.
 
@@ -130,7 +178,7 @@ import { Dialgem, WebhookVerificationError } from "@dialgem/sdk"
 app.post("/webhooks/dialgem", express.raw({ type: "application/json" }), async (req, res) => {
   try {
     const event = await Dialgem.webhooks.constructEvent(req.body, req.header("x-dialgem-signature"), SECRET)
-    if (event.event === "call_analyzed") await crm.update(event.call_id, event.analysis.variables)
+    if (event.event === "call_analyzed") await crm.update(event.call.metadata.crm_id, event.call.analysis?.variables)
     res.sendStatus(204)
   } catch (err) {
     if (err instanceof WebhookVerificationError) return res.status(400).send(err.message)
@@ -155,26 +203,109 @@ export async function POST(request: Request) {
 
 **Fastify**: register a buffer parser for `application/json` on the webhook route. See `examples/webhook-fastify.ts`.
 
-`event` is a discriminated union, so `switch (event.event)` narrows the payload type. A failed delivery is retried once, so make your handler idempotent on `(event, call_id)`. Respond within 10 seconds and queue any slow work. `webhooks.verify(body, signature, secret)` returns a boolean if you prefer to handle rejection yourself.
+`event` is a discriminated union, so `switch (event.event)` narrows the payload type. A failed delivery is retried up to three times; every attempt carries the same `x-dialgem-delivery` header, so drop an id you have already processed. Respond within 10 seconds and queue any slow work. `webhooks.verify(body, signature, secret)` returns a boolean if you prefer to handle rejection yourself.
+
+**Verifying your custom functions.** When the agent calls one of your functions, the request is signed the same way, and its body is `{ name, call, args }`:
+
+```ts
+app.post("/functions/lookup-order", express.raw({ type: "application/json" }), async (req, res) => {
+  const { args, call } = await Dialgem.webhooks.constructFunctionCall<{ order_id: string }>(
+    req.body, req.header("x-dialgem-signature"), SECRET,
+  )
+  res.json(await orders.find(args.order_id, call.metadata.crm_id))
+})
+```
+
+A function created with `args_at_root: true` receives the arguments object alone instead.
 
 ### 5. Export calls and transcripts
 
 `calls.list()` returns one page when you `await` it. Iterate over it with `for await` to walk every page:
 
 ```ts
-const cutoff = "2026-09-01T00:00:00"
-for await (const call of dialgem.calls.list({ page_size: 50 })) {
-  if (call.started_at < cutoff) break // newest first: the rest are older
-  console.log(call.id, call.duration_s, call.analysis?.call_successful, call.transcript)
+const since = Date.parse("2026-09-01T00:00:00Z")
+for await (const call of dialgem.calls.list({ start_after: since, status: "completed", limit: 50 })) {
+  console.log(call.id, call.duration_ms, call.analysis?.call_summary, call.transcript_text)
 }
 
-const page = await dialgem.calls.list({ page_size: 50 })
+const page = await dialgem.calls.list({ agent_id: agent.id, metadata: { crm_id: "42" }, limit: 50 })
 page.data // Call[]
-page.total // number
 if (page.hasNextPage()) await page.getNextPage()
 ```
 
-Pages are offset-based and ordered newest first. A call that starts mid-export shifts later pages by one, so de-duplicate on `id` if exactness matters.
+Filters: `agent_id`, `status`, `direction`, `call_type`, `disconnection_reason`, `from_number`, `to_number`, `user_sentiment`, `call_successful`, `start_after` / `start_before` (epoch ms), `metadata`, `search` and `sort_order`. Pages are cursor-based, so walking them is stable while new calls arrive.
+
+### 6. Ship a change without touching live calls
+
+The agent you edit is the **draft**. Publishing freezes it — configuration, functions and MCP servers — as a numbered version that never changes afterwards:
+
+```ts
+const v1 = await dialgem.agents.versions.publish(agent.id, { title: "Refund flow" })
+v1.version // 1
+
+// Point production at the frozen copy, then keep editing the draft freely.
+await dialgem.phoneNumbers.assign(number.id, { agent_id: agent.id, agent_version: v1.version })
+await dialgem.agents.update(agent.id, { system_prompt: "…work in progress…" })
+
+await dialgem.agents.versions.list(agent.id) // one page, newest first
+await dialgem.agents.versions.retrieve(agent.id, 1) // with its snapshot
+
+// Nothing prunes versions, so the list is paged. `listPage` keeps `has_more`.
+const { versions, has_more } = await dialgem.agents.versions.listPage(agent.id, { limit: 20 })
+```
+
+A number can also follow the newest publish instead of naming a version, so shipping moves it with nothing to update:
+
+```ts
+await dialgem.phoneNumbers.assign(number.id, {
+  agent_id: agent.id,
+  agent_version: "latest_published",
+})
+```
+
+A version is also pinnable per call — `createPhoneCall({ …, agent_id, agent_version: 1 })` and `register({ …, agent_version: 1 })` — and the version a call ran comes back on the call record as `agent_version`, so a recording, its transcript and its analysis all name the configuration that produced them. Version `0` everywhere means the draft, which is what an unpinned call runs.
+
+### 7. Give an agent a cloned voice
+
+```ts
+import { readFile } from "node:fs/promises"
+
+const voice = await dialgem.voices.clone({
+  name: "Ada",
+  files: [new Blob([await readFile("./sample.mp3")], { type: "audio/mpeg" })],
+  // You are asserting that you hold the rights to this audio and have the
+  // speaker's consent. It is recorded against your API identity.
+  consent_confirmed: true,
+})
+
+await dialgem.agents.update(agent.id, { voice_id: voice.provider_voice_id })
+```
+
+The new voice is private to your organization — it never appears in another
+one's catalog, and `voices.list()` puts yours first. ElevenLabs (the default)
+takes up to 25 files; **Cartesia takes exactly one** and refuses more rather
+than quietly picking one.
+
+`voices.delete(voice.id)` removes it at the provider and here. It refuses with a
+409 while an agent still uses it, rather than leaving that agent without a voice.
+
+
+## Live call control
+
+Steer a call while it is happening. `sessionId` is the session's id from `sessions.list()` or the call's own `call_id`, and the call can be on any service instance.
+
+```ts
+// Change this call's prompt or variables from the agent's next turn (not saved, only this call).
+await dialgem.sessions.update(call_id, { dynamic_variables: { plan: "pro" } })
+
+// Make the agent say a line in its own voice; interrupt: true cuts in now.
+await dialgem.sessions.say(call_id, { text: "One moment while I check that." })
+
+// Give a taken-over call back to the agent.
+await dialgem.sessions.release(call_id)
+```
+
+`say` and `release` are **off unless your deployment enables live control** (`PermissionDeniedError` with `errCode` `live_control_disabled`), and are for owners, admins and API keys only. Listening in and taking a call over run over a WebSocket (`/v1/agent/sessions/{id}/live`), which this SDK does not wrap.
 
 ## Errors
 
@@ -223,13 +354,20 @@ The SDK never follows redirects. The API does not issue them, and following one
 | `agents.functions` | `list`, `create`, `update`, `delete`, `reorder` |
 | `agents.knowledge` | `list`, `create`, `delete` |
 | `agents.mcpServers` | `list`, `create`, `update`, `delete`, `test` |
-| `calls` | `list`, `retrieve`, `createPhoneCall`, `register` |
-| `phoneNumbers` | `create`, `list`, `update`, `assign`, `delete` |
-| `voices` | `list` |
+| `agents.versions` | `publish`, `list`, `listPage`, `retrieve` |
+| `calls` | `list`, `retrieve`, `update`, `delete`, `stop`, `rerunAnalysis`, `createPhoneCall`, `register` |
+| `phoneNumbers` | `create`, `list`, `retrieve`, `update`, `assign`, `delete` |
+| `voices` | `list`, `clone`, `delete` |
 | `flowTemplates`, `promptTemplates` | `list`, `retrieve` |
-| `webhooks` | `verify`, `constructEvent` |
+| `llms` | `create`, `list`, `retrieve`, `update`, `delete` |
+| `flows` | `create`, `list`, `retrieve`, `update`, `delete` |
+| `chats` | `create`, `list`, `retrieve`, `update`, `delete`, `sendMessage`, `end`, `rerunAnalysis` |
+| `sessions` | `list`, `update`, `say`, `release` |
+| `apiKey` | `retrieve` |
+| `contacts` | `retrieveByPhone` (and the rest: see the reference) |
+| `webhooks` | `verify`, `constructEvent`, `constructFunctionCall` |
 
-In-browser web calls are not part of this package.
+In-browser web calls are not part of this package: see [`@dialgem/client`](https://github.com/DialgemAI/dialgem-client-sdk).
 
 ## Development
 
@@ -245,7 +383,20 @@ pnpm sync:openapi --from https://api.dialgem.com/openapi.json
 pnpm gen:types
 
 # Against a running API, with an organization key:
-DIALGEM_API_KEY=zk_… DIALGEM_BASE_URL=http://localhost:8002 pnpm test:live
+DIALGEM_API_KEY=zk_… pnpm test:live   # runs against api.dialgem.com — use a test org's key
+```
+
+The API address is fixed at `https://api.dialgem.com` and `baseURL` is refused,
+so a key can never start hitting production by accident. To exercise the SDK
+against a local or staging stack, pass a `fetch` that rewrites the origin — it
+is explicit, it stays in your test setup, and it cannot be switched on by an
+environment variable someone forgot to unset:
+
+```ts
+const local = new Dialgem({
+  apiKey: "zk_local",
+  fetch: (url, init) => fetch(String(url).replace("https://api.dialgem.com", "http://localhost:8002"), init),
+})
 ```
 
 Request-body types are generated from `openapi/openapi.json`. Response types in `src/types/` are written by hand, so a change to a response shape needs a matching edit there.
@@ -255,3 +406,11 @@ To release, bump `version` in `package.json` and `src/version.ts`, add a CHANGEL
 ## License
 
 Apache-2.0
+
+---
+
+<div align="center">
+
+If this SDK saves you time, a ⭐ on [GitHub](https://github.com/DialgemAI/dialgem-sdk-typescript) helps other developers find it.
+
+</div>