@dialgem/sdk 0.1.0-beta.1 → 0.1.0-beta.3

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
-## 0.1.0-beta.1 (unreleased)
+## 0.1.0-beta.3
+
+### Added
+- `phoneNumbers.search({ country?, type?, area_code?, contains?, limit? })` lists numbers that can be bought, with the monthly price, and `phoneNumbers.buy({ phone_number, type?, nickname? })` buys one. **Buying spends the organization's credit**: the first month is debited when you buy and the rental renews monthly until the number is released; nothing is charged if the purchase fails. Both need the deployment to have number purchasing switched on (`search` throws `NotFoundError`, `number_purchase_disabled`, otherwise). Types: `PhoneNumberSearchParams`, `PhoneNumberBuyParams`, `AvailablePhoneNumbers`, `PurchasedPhoneNumber`.
+- A number looked up with `phoneNumbers.retrieve` now carries `own_twilio` (whether it is on a Twilio account you connected yourself). Connecting your own Twilio account and importing its numbers is a dashboard feature; it is not in the SDK, because it handles your Twilio credentials.
+
+## 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`.
@@ -9,6 +18,17 @@
 - **`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`.
@@ -18,6 +38,8 @@
 - **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)

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
 
@@ -126,13 +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 body is `{ event, call_id, agent_id, call }`, where `call` is the full call record, and each request is signed:
+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.
+`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.
 
@@ -255,6 +289,24 @@ 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
 
 Every error extends `DialgemError`. When the API returns an HTTP error, the SDK throws an `APIError` subclass chosen by status code:
@@ -303,13 +355,19 @@ The SDK never follows redirects. The API does not issue them, and following one
 | `agents.knowledge` | `list`, `create`, `delete` |
 | `agents.mcpServers` | `list`, `create`, `update`, `delete`, `test` |
 | `agents.versions` | `publish`, `list`, `listPage`, `retrieve` |
-| `calls` | `list`, `retrieve`, `update`, `delete`, `stop`, `createPhoneCall`, `register` |
+| `calls` | `list`, `retrieve`, `update`, `delete`, `stop`, `rerunAnalysis`, `createPhoneCall`, `register` |
 | `phoneNumbers` | `create`, `list`, `retrieve`, `update`, `assign`, `delete` |
 | `voices` | `list`, `clone`, `delete` |
 | `flowTemplates`, `promptTemplates` | `list`, `retrieve` |
+| `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
 
@@ -328,6 +386,19 @@ pnpm gen:types
 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.
 
 To release, bump `version` in `package.json` and `src/version.ts`, add a CHANGELOG entry, merge to `main`, and push a matching tag (`git tag v0.1.0 && git push origin v0.1.0`). A version with a hyphen (`0.2.0-beta.1`) publishes to the `next` dist-tag.
@@ -335,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>