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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.0-beta.1 (unreleased)
+
+### 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
+- `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.
+- **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

@@ -37,7 +37,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 +93,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 +126,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. 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:
+
+```
+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.
 
 > **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 +144,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 +169,91 @@ 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.
 
 ## Errors
 
@@ -223,11 +302,12 @@ 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`, `createPhoneCall`, `register` |
+| `phoneNumbers` | `create`, `list`, `retrieve`, `update`, `assign`, `delete` |
+| `voices` | `list`, `clone`, `delete` |
 | `flowTemplates`, `promptTemplates` | `list`, `retrieve` |
-| `webhooks` | `verify`, `constructEvent` |
+| `webhooks` | `verify`, `constructEvent`, `constructFunctionCall` |
 
 In-browser web calls are not part of this package.
 
@@ -245,7 +325,7 @@ 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
 ```
 
 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.