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

package/dist/index.cjs

@@ -106,7 +106,7 @@ function isErrorBody(body) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0-beta.0";
+var VERSION = "0.1.0-beta.1";
 
 // src/core/http.ts
 var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET", "PATCH", "DELETE"]);
@@ -132,6 +132,16 @@ var HttpClient = class {
   post(path2, body, options) {
     return this.request("POST", path2, { body, options });
   }
+  /**
+   * POST a `FormData` body — file uploads.
+   *
+   * The body is sent as-is and `Content-Type` is left unset, because only
+   * `fetch` knows the multipart boundary it is about to generate. Setting the
+   * header ourselves produces a request no server can parse.
+   */
+  postForm(path2, form, options) {
+    return this.request("POST", path2, { body: form, options });
+  }
   patch(path2, body, options) {
     return this.request("PATCH", path2, { body, options });
   }
@@ -140,10 +150,11 @@ var HttpClient = class {
   }
   async request(method, path2, { query, body, options = {} }) {
     const url = this.buildURL(path2, query);
-    const headers = this.buildHeaders(body !== void 0, options.headers);
-    const payload = body === void 0 ? void 0 : JSON.stringify(body);
+    const isForm = isFormData(body);
+    const headers = this.buildHeaders(body !== void 0 && !isForm, options.headers);
+    const payload = body === void 0 ? void 0 : isForm ? body : JSON.stringify(body);
     const timeout = options.timeout ?? this.#timeout;
-    const maxRetries = options.maxRetries ?? (RETRYABLE_METHODS.has(method) ? this.#maxRetries : 0);
+    const maxRetries = isForm ? 0 : options.maxRetries ?? (RETRYABLE_METHODS.has(method) ? this.#maxRetries : 0);
     assertTimeout(timeout);
     assertMaxRetries(maxRetries);
     for (let attempt = 0; ; attempt++) {
@@ -197,7 +208,7 @@ var HttpClient = class {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(query)) {
       if (value === void 0 || value === null) continue;
-      params.append(key, String(value));
+      for (const item of Array.isArray(value) ? value : [value]) params.append(key, String(item));
     }
     const qs = params.toString();
     return qs ? `${url}?${qs}` : url;
@@ -220,6 +231,9 @@ var HttpClient = class {
     return Object.fromEntries(merged.values());
   }
 };
+function isFormData(value) {
+  return typeof FormData !== "undefined" && value instanceof FormData;
+}
 function assertTimeout(value) {
   if (!Number.isInteger(value) || value <= 0) {
     throw new DialgemError(`\`timeout\` must be a positive integer of milliseconds, got ${String(value)}.`);
@@ -316,11 +330,14 @@ var Agents = class extends APIResource {
   knowledge;
   /** Remote MCP servers whose tools are exposed to the agent. */
   mcpServers;
+  /** Frozen snapshots of the agent that a number or a call can pin. */
+  versions;
   constructor(client) {
     super(client);
     this.functions = new AgentFunctions(client);
     this.knowledge = new AgentKnowledge(client);
     this.mcpServers = new AgentMCPServers(client);
+    this.versions = new AgentVersions(client);
   }
   /** Create an agent. Only `name` is required; everything else has a server default. */
   create(body, options) {
@@ -341,6 +358,48 @@ var Agents = class extends APIResource {
     return this._client.delete(path`/v1/agents/${agentId}`, options);
   }
 };
+var AgentVersions = class extends APIResource {
+  /** Freeze the agent as it is now. Returns the new version, snapshot included. */
+  publish(agentId, body = {}, options) {
+    return this._client.post(path`/v1/agents/${agentId}/versions`, body, options);
+  }
+  /**
+     * One page of published versions, newest first, without their snapshots.
+     *
+     * Returns the array. When you need to page — an agent published on every
+     * deploy accumulates versions, and nothing prunes them — read `has_more` from
+     * {@link listPage} instead and pass the last `version` as `before_version`.
+     */
+  async list(agentId, params, options) {
+    return (await this.listPage(agentId, params, options)).versions;
+  }
+  /** {@link list} with the `has_more` flag, for paging. */
+  listPage(agentId, params, options) {
+    return this._client.get(
+      path`/v1/agents/${agentId}/versions`,
+      // Spread into a plain query record: an `interface` has no index
+      // signature, so it does not structurally satisfy `Query`.
+      { ...params },
+      options
+    );
+  }
+  /** One version with its full snapshot. Version 0 is the draft: use `agents.retrieve`. */
+  retrieve(agentId, version, options) {
+    return this._client.get(
+      path`/v1/agents/${agentId}/versions/${versionSegment(version)}`,
+      void 0,
+      options
+    );
+  }
+};
+function versionSegment(version) {
+  if (!Number.isInteger(version) || version < 1) {
+    throw new DialgemError(
+      `Expected a published version number (a positive integer), got ${JSON.stringify(version)}. Version 0 is the draft \u2014 read it with agents.retrieve().`
+    );
+  }
+  return String(version);
+}
 var AgentFunctions = class extends APIResource {
   list(agentId, options) {
     return this._client.get(path`/v1/agents/${agentId}/functions`, void 0, options);
@@ -393,35 +452,33 @@ var AgentMCPServers = class extends APIResource {
 // src/core/pagination.ts
 var Page = class _Page {
   data;
-  total;
-  page;
-  page_size;
+  has_more;
+  pagination_key;
   #fetchPage;
   constructor(data, fetchPage) {
     this.data = data.data;
-    this.total = data.total;
-    this.page = data.page;
-    this.page_size = data.page_size;
+    this.has_more = data.has_more;
+    this.pagination_key = data.pagination_key;
     this.#fetchPage = fetchPage;
   }
   hasNextPage() {
-    return this.data.length > 0 && this.page * this.page_size < this.total;
+    return this.has_more && this.pagination_key !== null;
   }
   async getNextPage() {
     if (!this.hasNextPage()) throw new DialgemError("No next page; check hasNextPage() first.");
-    return new _Page(await this.#fetchPage(this.page + 1), this.#fetchPage);
+    return new _Page(await this.#fetchPage(this.pagination_key), this.#fetchPage);
   }
 };
 var PagePromise = class {
   #fetchPage;
-  #startPage;
+  #startKey;
   #first;
-  constructor(fetchPage, startPage) {
+  constructor(fetchPage, startKey = null) {
     this.#fetchPage = fetchPage;
-    this.#startPage = startPage;
+    this.#startKey = startKey;
   }
   #firstPage() {
-    this.#first ??= this.#fetchPage(this.#startPage).then((data) => new Page(data, this.#fetchPage));
+    this.#first ??= this.#fetchPage(this.#startKey).then((data) => new Page(data, this.#fetchPage));
     return this.#first;
   }
   then(onfulfilled, onrejected) {
@@ -446,24 +503,50 @@ var PagePromise = class {
 // src/resources/calls.ts
 var Calls = class extends APIResource {
   /**
-   * Calls, newest first. Await for one page, or iterate for every call:
+   * Calls, newest first by default. Await for one page, or iterate for every call:
    *
-   *   const page = await dialgem.calls.list({ page_size: 50 })
-   *   for await (const call of dialgem.calls.list({ status: "completed" })) {
-   *     if (call.started_at < cutoff) break // newest first: everything after is older
-   *   }
+   *   const page = await dialgem.calls.list({ limit: 50 })
+   *   for await (const call of dialgem.calls.list({ status: "completed", start_after: since })) { ... }
    */
   list(params = {}, options) {
-    const fetchPage = async (page) => {
-      const res = await this._client.get("/v1/calls", { ...params, page }, options);
-      return { data: res.calls, total: res.total, page: res.page, page_size: res.page_size };
+    const query = toQuery(params);
+    const fetchPage = async (paginationKey) => {
+      const res = await this._client.get(
+        "/v1/calls",
+        { ...query, pagination_key: paginationKey ?? void 0 },
+        options
+      );
+      return { data: res.calls, has_more: res.has_more, pagination_key: res.pagination_key };
     };
-    return new PagePromise(fetchPage, params.page ?? 1);
+    return new PagePromise(fetchPage);
   }
-  /** One call, including its transcript, analysis and recording URL. */
+  /** One call, including its transcript, analysis, latency and recording URL. */
   retrieve(callId, options) {
     return this._client.get(path`/v1/calls/${callId}`, void 0, options);
   }
+  /** Replace the call's `metadata`. */
+  update(callId, body, options) {
+    return this._client.patch(path`/v1/calls/${callId}`, body, options);
+  }
+  /**
+   * Permanently delete a finished call: its record, transcript, analysis and
+   * recording. A call still in progress is refused with `ConflictError`; stop it first.
+   */
+  delete(callId, options) {
+    return this._client.delete(path`/v1/calls/${callId}`, options);
+  }
+  /**
+   * End an ongoing call now, as if the agent had hung up. The call becomes
+   * `completed` with `disconnection_reason: "manual_stopped"` a moment later, and
+   * the usual `call_ended` webhook follows.
+   *
+   * `ConflictError` with `errCode` `call_not_ongoing` if it already ended, or
+   * `call_not_connected` if no agent is on the call yet (e.g. still ringing).
+   * Not retried by default.
+   */
+  stop(callId, options) {
+    return this._client.post(path`/v1/calls/${callId}/stop`, void 0, options);
+  }
   /**
    * Dial `to` from one of your organization's numbers, with `agent_id` (or the
    * number's outbound agent) on the line.
@@ -483,13 +566,70 @@ var Calls = class extends APIResource {
     return this._client.post("/v1/calls/register", body, options);
   }
 };
+function toQuery(params) {
+  const { metadata, ...rest } = params;
+  const query = { ...rest };
+  query["limit"] = params.limit ?? 10;
+  for (const [key, value] of Object.entries(metadata ?? {})) {
+    query[`metadata.${key}`] = String(value);
+  }
+  return query;
+}
 
 // src/resources/catalog.ts
 var Voices = class extends APIResource {
-  /** Voices available to agents, by name. Put a voice's `provider_voice_id` in an agent's `voice_id`. */
+  /**
+   * Voices available to agents: the shared catalog plus the ones your
+   * organization cloned, yours first. Put a voice's `provider_voice_id` in an
+   * agent's `voice_id`.
+   */
   list(params = {}, options) {
     return this._client.get("/v1/voices", params, options);
   }
+  /**
+   * Clone a voice from audio you upload. The new voice is private to your
+   * organization and never appears in another one's catalog.
+   *
+   * Consent is required: you are asserting that you hold the rights to the
+   * audio and have the speaker's consent, and that assertion is recorded
+   * against your API identity.
+   *
+   * The upload is never retried, whatever `maxRetries` says — a retried
+   * multipart body can send truncated audio, and a clone built from half the
+   * recording succeeds and sounds wrong.
+   */
+  clone(params, options) {
+    const { name, files, consent_confirmed, engine, description, language, filenames } = params;
+    if (!consent_confirmed) {
+      throw new DialgemError(
+        "consent_confirmed must be true: you are asserting that you hold the rights to this audio and have the speaker's consent to clone their voice."
+      );
+    }
+    if (!files?.length) {
+      throw new DialgemError("At least one audio file is required to clone a voice.");
+    }
+    const form = new FormData();
+    form.append("name", name);
+    form.append("consent_confirmed", "true");
+    if (engine) form.append("engine", engine);
+    if (description) form.append("description", description);
+    if (language) form.append("language", language);
+    files.forEach((file, i) => {
+      const fallback = file.name || `clip-${i + 1}.wav`;
+      form.append("files", file, filenames?.[i] ?? fallback);
+    });
+    return this._client.postForm("/v1/voices/clone", form, options);
+  }
+  /**
+   * Delete a voice your organization cloned, at the provider and here.
+   *
+   * Only your own cloned voices: the shared catalog is not deletable, and a
+   * voice an agent still uses is refused with a 409 rather than leaving that
+   * agent without one.
+   */
+  delete(voiceId, options) {
+    return this._client.delete(path`/v1/voices/${voiceId}`, options);
+  }
 };
 var FlowTemplates = class extends APIResource {
   /** Built-in conversation-flow templates (summaries, without `flow_config`). */
@@ -520,6 +660,20 @@ var PhoneNumbers = class extends APIResource {
   list(options) {
     return this._client.get("/v1/phone-numbers", void 0, options);
   }
+  /**
+   * One number by its E.164 value, e.g. `+14155550123`.
+   *
+   * Keyed on the number rather than on `id`, because the number is what you
+   * have when you are asking whether it is registered at all. Throws
+   * `NotFoundError` when it is not.
+   */
+  retrieve(phoneNumber, options) {
+    return this._client.get(
+      path`/v1/phone-numbers/by-number/${phoneNumber}`,
+      void 0,
+      options
+    );
+  }
   /**
    * Partial update.
    *
@@ -544,52 +698,84 @@ var PhoneNumbers = class extends APIResource {
 // src/webhooks.ts
 var WEBHOOK_SIGNATURE_HEADER = "x-dialgem-signature";
 var WEBHOOK_EVENT_HEADER = "x-dialgem-event";
+var WEBHOOK_DELIVERY_HEADER = "x-dialgem-delivery";
+var DEFAULT_SIGNATURE_TOLERANCE_MS = 5 * 60 * 1e3;
 var encoder = new TextEncoder();
 var decoder = new TextDecoder();
+var SIGNATURE_RE = /^v=(\d{10,16}),d=([0-9a-f]{64})$/;
 var Webhooks = class {
   /**
-   * Returns whether `signature` is the HMAC-SHA256 of `payload` under `secret`.
-   * Constant-time. Returns `false` for a missing or malformed signature; throws only
-   * if `secret` is empty, which is a configuration error rather than a bad request.
+   * Returns whether `signature` is a current, valid signature of `payload` under
+   * `secret`. Constant-time. Returns `false` for a missing, malformed, tampered or
+   * stale signature; throws only if `secret` is empty, which is a configuration
+   * error rather than a bad request.
    */
-  async verify(payload, signature, secret) {
+  async verify(payload, signature, secret, options = {}) {
     if (!secret) {
       throw new DialgemError(
         "Webhook secret is empty. Set the agent's `webhook_signing_secret` and pass the same value here."
       );
     }
-    const received = firstHeader(signature)?.trim().toLowerCase();
-    if (!received || !/^[0-9a-f]{64}$/.test(received)) return false;
-    const expected = await hmacSha256Hex(secret, toBytes(payload));
+    const match = SIGNATURE_RE.exec(firstHeader(signature)?.trim().toLowerCase() ?? "");
+    if (!match) return false;
+    const [, timestamp, received] = match;
+    const now = options.now ?? Date.now();
+    if (Math.abs(now - Number(timestamp)) > (options.toleranceMs ?? DEFAULT_SIGNATURE_TOLERANCE_MS)) {
+      return false;
+    }
+    const body = toBytes(payload);
+    const message = new Uint8Array(body.length + timestamp.length);
+    message.set(body, 0);
+    message.set(encoder.encode(timestamp), body.length);
+    const expected = await hmacSha256Hex(secret, message);
     return timingSafeEqual(expected, received);
   }
   /**
-   * Verifies the signature, then parses the body.
+   * Verifies a webhook's signature, then parses its body.
    *
-   * @throws WebhookVerificationError if the signature is missing or does not match.
+   * @throws WebhookVerificationError if the signature is missing, invalid or stale.
    */
-  async constructEvent(payload, signature, secret) {
+  async constructEvent(payload, signature, secret, options = {}) {
+    const parsed = await this.#verifiedJson(payload, signature, secret, options);
+    if (typeof parsed !== "object" || parsed === null || typeof parsed.event !== "string") {
+      throw new WebhookVerificationError("Webhook body has no `event` field.");
+    }
+    return parsed;
+  }
+  /**
+   * Verifies a request Dialgem made to one of your custom functions, then parses
+   * its body. For functions with `args_at_root`, the body is the arguments object
+   * alone; use `verify` and parse it yourself.
+   *
+   * @throws WebhookVerificationError if the signature is missing, invalid or stale.
+   */
+  async constructFunctionCall(payload, signature, secret, options = {}) {
+    const parsed = await this.#verifiedJson(payload, signature, secret, options);
+    const body = parsed;
+    if (!body || typeof body.name !== "string" || typeof body.call !== "object" || body.call === null) {
+      throw new WebhookVerificationError(
+        "Function request body has no `name` and `call`. Does this function have args_at_root set?"
+      );
+    }
+    return body;
+  }
+  async #verifiedJson(payload, signature, secret, options) {
     if (!firstHeader(signature)) {
       throw new WebhookVerificationError(
         `Missing ${WEBHOOK_SIGNATURE_HEADER} header. Is a webhook_signing_secret set on the agent?`
       );
     }
-    if (!await this.verify(payload, signature, secret)) {
+    if (!await this.verify(payload, signature, secret, options)) {
       throw new WebhookVerificationError(
-        "Webhook signature does not match the body. Check the secret, and that the body was not re-serialized before verification."
+        "Signature is invalid or older than the allowed tolerance. Check the secret, the server clock, and that the body was not re-serialized before verification."
       );
     }
     const text = typeof payload === "string" ? payload : decoder.decode(toBytes(payload));
-    let parsed;
     try {
-      parsed = JSON.parse(text);
+      return JSON.parse(text);
     } catch {
-      throw new WebhookVerificationError("Webhook body is signed but is not valid JSON.");
+      throw new WebhookVerificationError("Body is signed but is not valid JSON.");
     }
-    if (typeof parsed !== "object" || parsed === null || typeof parsed.event !== "string") {
-      throw new WebhookVerificationError("Webhook body has no `event` field.");
-    }
-    return parsed;
   }
 };
 var webhooks = new Webhooks();
@@ -619,11 +805,11 @@ function timingSafeEqual(a, b) {
 }
 
 // src/client.ts
-var DEFAULT_BASE_URL = "https://api.dialgem.com";
+var BASE_URL = "https://api.dialgem.com";
 var DEFAULT_TIMEOUT_MS = 6e4;
 var DEFAULT_MAX_RETRIES = 2;
 var Dialgem = class {
-  static DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+  static BASE_URL = BASE_URL;
   /** Webhook verification without a client instance: `Dialgem.webhooks.constructEvent(...)`. */
   static webhooks = webhooks;
   agents;
@@ -633,8 +819,14 @@ var Dialgem = class {
   flowTemplates;
   promptTemplates;
   webhooks = webhooks;
-  baseURL;
+  /** Always `https://api.dialgem.com`. */
+  baseURL = BASE_URL;
   constructor(options = {}) {
+    if ("baseURL" in options) {
+      throw new DialgemError(
+        "`baseURL` is not an option: the SDK always talks to https://api.dialgem.com. Remove it."
+      );
+    }
     if (isBrowser() && !options.dangerouslyAllowBrowser) {
       throw new DialgemError(
         "The Dialgem SDK is for server-side use: running it in a browser exposes your API key to every visitor. Call Dialgem from your backend instead, or pass `dangerouslyAllowBrowser: true` if you understand the risk."
@@ -651,10 +843,9 @@ var Dialgem = class {
     assertTimeout(timeout);
     assertMaxRetries(maxRetries);
     const fetchImpl = options.fetch ?? defaultFetch();
-    this.baseURL = (options.baseURL ?? readEnv("DIALGEM_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     const http = new HttpClient({
       apiKey,
-      baseURL: this.baseURL,
+      baseURL: BASE_URL,
       timeout,
       maxRetries,
       fetch: fetchImpl,
@@ -690,9 +881,10 @@ exports.APIConnectionTimeoutError = APIConnectionTimeoutError;
 exports.APIError = APIError;
 exports.APIUserAbortError = APIUserAbortError;
 exports.AuthenticationError = AuthenticationError;
+exports.BASE_URL = BASE_URL;
 exports.BadRequestError = BadRequestError;
 exports.ConflictError = ConflictError;
-exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.DEFAULT_SIGNATURE_TOLERANCE_MS = DEFAULT_SIGNATURE_TOLERANCE_MS;
 exports.Dialgem = Dialgem;
 exports.DialgemError = DialgemError;
 exports.InternalServerError = InternalServerError;
@@ -703,6 +895,7 @@ exports.PermissionDeniedError = PermissionDeniedError;
 exports.RateLimitError = RateLimitError;
 exports.UnprocessableEntityError = UnprocessableEntityError;
 exports.VERSION = VERSION;
+exports.WEBHOOK_DELIVERY_HEADER = WEBHOOK_DELIVERY_HEADER;
 exports.WEBHOOK_EVENT_HEADER = WEBHOOK_EVENT_HEADER;
 exports.WEBHOOK_SIGNATURE_HEADER = WEBHOOK_SIGNATURE_HEADER;
 exports.WebhookVerificationError = WebhookVerificationError;