@osmapi/osmtalk-sdk 0.3.0 → 0.4.0

package/README.md

@@ -2,11 +2,15 @@
 
 Official TypeScript / JavaScript SDK for the [osmTalk](https://osmtalk.com) voice AI platform.
 
+[![npm](https://img.shields.io/npm/v/@osmapi/osmtalk-sdk.svg)](https://www.npmjs.com/package/@osmapi/osmtalk-sdk)
+
 ```bash
 npm install @osmapi/osmtalk-sdk
 # or: pnpm add @osmapi/osmtalk-sdk
 ```
 
+Works in **Node 18+, Deno, Bun, Cloudflare Workers, and browsers**.
+
 ## Quick start
 
 ```ts
@@ -34,11 +38,32 @@ console.log("Call started:", call.callId);
 | Resource | Operations |
 |---|---|
 | `client.agents` | `list`, `get`, `create`, `update`, `delete`, `connect`, `publishVersion`, `listVersions`, `getVersion`, `rollbackToVersion` |
-| `client.calls` | `list`, `get`, `outbound`, `end`, `transfer` |
+| `client.calls` | `list` (paginated), `get`, `outbound`, `end`, `transfer`, `waitUntilEnded` |
 | `client.campaigns` | `list`, `get`, `create`, `update`, `delete`, `start`, `pause`, `resume`, `stop`, `report`, `uploadLeadsCsv`, `uploadLeads`, `listLeads` |
+| `client.phoneNumbers` | `list`, `update` |
 | `client.dnc` | `list`, `add`, `bulkAdd`, `remove` |
 | `client.eval` | `simulate`, `createTestCase`, `listTestCases`, `runTestCase`, `runAll`, `listRuns`, `getRun` |
 | `client.settings` | `get`, `getStorage`, `updateStorage`, `getWebhook`, `updateWebhook`, `getCompliance`, `updateCompliance` |
+| `client.platform` | `getRates`, `listProviders`, `getPresets`, `getModelHealth`, `getTemplates`, `getTemplate`, `saveTemplate`, `deleteTemplate` |
+
+Plus the standalone helpers `verifyWebhookSignature` / `verifyWebhookSignatureAsync` (see below).
+
+## What's new in 0.4.0
+
+- **Breaking**: `client.calls.list()` now returns `Paginated<CallRecord>` — `{ data, total, limit, offset }` — not a raw array. The server always returned this shape; the prior type was wrong. See [CHANGELOG.md](./CHANGELOG.md) for a one-line migration.
+- **New `client.phoneNumbers`** resource — `list()` and `update()` for managing org-owned numbers.
+- **`calls.list()` accepts filters**: `status`, `agentId`, `channel`, `from`, `to`, `search`, `limit`, `offset`.
+
+## What's new in 0.3.0
+
+- **Auto-retry** on 5xx, 429, and network errors with `Retry-After` honored and exponential backoff. No more hand-rolling retry wrappers.
+- **`client.calls.waitUntilEnded(callId)`** — one-line polling helper for the "place call → wait → get result" pattern.
+- **`AbortSignal`** support on every method via `RequestOptions.signal`.
+- **`User-Agent`** header sent automatically.
+- **Per-org request override** via `RequestOptions.organizationId`.
+- **`OsmtalkError.isRetryable` / `.isClientError` / `.retryAttempts`** for cleaner error branching.
+
+Full version history: [CHANGELOG.md](./CHANGELOG.md).
 
 ## Examples
 
@@ -68,6 +93,61 @@ const report = await client.campaigns.report(camp.id);
 console.log(report.counts.byStatus);
 ```
 
+### Listing recent calls with filters
+
+```ts
+const { data, total } = await client.calls.list({
+  status: "completed",
+  channel: "phone",
+  from: "2026-05-01",
+  limit: 25,
+});
+
+console.log(`Showing ${data.length} of ${total} matching calls`);
+for (const call of data) {
+  console.log(call.id, call.durationSeconds, "s", call.disposition);
+}
+```
+
+### Wait for a call to finish (without writing a poll loop)
+
+```ts
+const { callId } = await client.calls.outbound({
+  agentId: "agent_xxx",
+  phoneNumberId: "pn_xxx",
+  destination: "+919876543210",
+});
+
+// Default: poll every 5s, give up after 30 minutes. All configurable.
+const final = await client.calls.waitUntilEnded(callId, {
+  pollIntervalMs: 5_000,
+  timeoutMs: 15 * 60 * 1000,
+});
+
+console.log("Final status:", final.status);
+console.log("Duration:    ", final.durationSeconds, "s");
+console.log("Disposition: ", final.disposition);
+console.log("Recording:   ", final.recordingUrl);
+```
+
+For production, prefer webhooks — see the receiver example below.
+
+### Cancel an in-flight request
+
+```ts
+const ctrl = new AbortController();
+setTimeout(() => ctrl.abort(), 2_000);
+
+try {
+  await client.agents.list({ signal: ctrl.signal });
+} catch (err) {
+  if (ctrl.signal.aborted) console.log("Cancelled by us");
+  else throw err;
+}
+```
+
+`signal`, `timeoutMs`, and `organizationId` are accepted on every method via the trailing `RequestOptions` argument.
+
 ### Publish a new agent version and A/B test
 
 ```ts
@@ -75,7 +155,12 @@ console.log(report.counts.byStatus);
 const v2 = await client.agents.publishVersion("agent_xxx", { label: "Tighter qualifier" });
 
 // Call with v2 explicitly
-await client.calls.outbound({ agentId: "agent_xxx", phoneNumberId: "pn_xxx", destination: "+919876543210", agentVersion: v2.version });
+await client.calls.outbound({
+  agentId: "agent_xxx",
+  phoneNumberId: "pn_xxx",
+  destination: "+919876543210",
+  agentVersion: v2.version,
+});
 ```
 
 ### Simulate before going live
@@ -91,33 +176,54 @@ for (const turn of sim.transcript) {
 }
 ```
 
-### Handle the webhook in Node.js
+### Verify webhooks (Node, sync)
 
 ```ts
-import crypto from "node:crypto";
 import express from "express";
+import { verifyWebhookSignature } from "@osmapi/osmtalk-sdk";
 
 const app = express();
-app.use(express.raw({ type: "application/json" }));
+// IMPORTANT: use express.raw() — NOT express.json(). The signature was
+// computed over the exact bytes; re-serialized JSON will not match.
+app.use("/webhooks/osmtalk", express.raw({ type: "application/json" }));
 
 app.post("/webhooks/osmtalk", (req, res) => {
-  const sig = req.header("X-OsmTalk-Signature") ?? "";
-  const [algo, hex] = sig.split("=");
-  const expected = crypto
-    .createHmac("sha256", process.env.OSMTALK_WEBHOOK_SECRET!)
-    .update(req.body)
-    .digest("hex");
-  if (algo !== "sha256" || !crypto.timingSafeEqual(Buffer.from(hex, "hex"), Buffer.from(expected, "hex"))) {
-    return res.sendStatus(401);
-  }
+  const ok = verifyWebhookSignature(
+    req.body,
+    req.header("x-osmtalk-signature"),
+    process.env.OSMTALK_WEBHOOK_SECRET!,
+  );
+  if (!ok) return res.status(401).end();
+
   const event = JSON.parse(req.body.toString());
-  if (event.event === "campaign.lead_completed" && event.lead.disposition === "qualified") {
-    console.log("Hot lead:", event.lead.variables.first_name);
+  if (event.event === "call.completed") {
+    console.log("Call ended:", event.call.id, event.analysis?.disposition);
   }
   res.json({ ok: true });
 });
 ```
 
+### Verify webhooks in Workers / Deno / Bun (async, WebCrypto)
+
+```ts
+import { verifyWebhookSignatureAsync } from "@osmapi/osmtalk-sdk";
+
+export default {
+  async fetch(req: Request) {
+    const raw = await req.text();
+    const ok = await verifyWebhookSignatureAsync(
+      raw,
+      req.headers.get("x-osmtalk-signature"),
+      env.OSMTALK_WEBHOOK_SECRET,
+    );
+    if (!ok) return new Response("invalid signature", { status: 401 });
+    const event = JSON.parse(raw);
+    // …handle event
+    return new Response("ok");
+  },
+};
+```
+
 ## Error handling
 
 ```ts
@@ -128,32 +234,61 @@ try {
 } catch (err) {
   if (err instanceof OsmtalkError) {
     console.log("HTTP", err.status, err.body);
+    console.log("Retries attempted:", err.retryAttempts);
+    if (err.isRetryable) console.log("Server might recover — try again later.");
+    if (err.isClientError) console.log("Bad input — check err.body.details.");
   } else {
     throw err;
   }
 }
 ```
 
-| Status | Meaning |
-|---|---|
-| 400 | Validation — `err.body.details` has zod field errors |
-| 401 | Bad API key |
-| 402 | Insufficient credits |
-| 404 | Resource not found |
-| 429 | Concurrency or rate limit |
-| 5xx | Server error / provider outage |
+| Status | Meaning | `OsmtalkError` flag |
+|---|---|---|
+| 400 | Validation — `err.body.details` has zod field errors | `isClientError` |
+| 401 | Bad API key | `isClientError` |
+| 402 | Insufficient credits | `isClientError` |
+| 404 | Resource not found | `isClientError` |
+| 408 | Request timeout | `isRetryable` |
+| 429 | Concurrency or rate limit | `isRetryable` |
+| 5xx | Server error / provider outage | `isRetryable` |
+
+The SDK already auto-retries 408/429/5xx and network errors twice by default. Mutating requests (POST/PUT/DELETE) are only retried when you pass `idempotencyKey` so the SDK never silently double-charges.
 
 ## Options
 
 ```ts
 new Osmtalk({
-  apiKey: "...",
-  baseUrl: "https://api.osmtalk.com",    // optional override
-  timeoutMs: 30_000,                     // per-request timeout
-  fetch: customFetch,                    // optional (Node 18+ has global fetch)
+  apiKey: "osm_live_…",
+  baseUrl: "https://api.osmtalk.com",  // default
+  timeoutMs: 30_000,                    // per-request, 0 to disable
+  maxRetries: 2,                        // auto-retry count for 5xx/429
+  retryInitialDelayMs: 250,             // doubles per retry, jittered
+  organizationId: "org_xxx",            // for multi-org accounts
+  defaultHeaders: { "X-Trace-Id": "…" },// added to every request
+  fetch: customFetch,                   // optional, defaults to global fetch
+});
+```
+
+Per-request overrides:
+
+```ts
+await client.calls.outbound(input, {
+  idempotencyKey: `dest-${destination}-${date}`,
+  signal: controller.signal,
+  timeoutMs: 60_000,
+  organizationId: "org_yyy",
 });
 ```
 
+## Runnable examples
+
+See [github.com/osm-API/osmtalk-examples](https://github.com/osm-API/osmtalk-examples) for three end-to-end projects:
+
+1. **Personalized outbound call** — dynamic per-user prompts
+2. **Bulk campaign from CSV** — scale to thousands
+3. **Verified webhook receiver** — close the loop with `verifyWebhookSignature`
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -10,8 +10,24 @@
  *     dynamicVariables: { first_name: "Arjun" },
  *   });
  */
-/** Bumped on every release — surfaced in the User-Agent header. */
-declare const SDK_VERSION = "0.3.0";
+/**
+ * Current SDK version, sent in the User-Agent header and useful for
+ * runtime version checks (e.g. logging which SDK build is talking to the
+ * API, or feature-detecting against minimum versions in shared code).
+ */
+declare const SDK_VERSION = "0.4.0";
+/**
+ * Paginated list envelope returned by some endpoints (currently
+ * `calls.list`; more list resources will migrate to this shape over
+ * future minor versions). Lets consumers build pagination UIs without
+ * a second count request.
+ */
+interface Paginated<T> {
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 interface OsmtalkOptions {
     apiKey: string;
     baseUrl?: string;
@@ -41,8 +57,25 @@ interface OsmtalkOptions {
      */
     organizationId?: string;
 }
-interface RequestOptions {
-    idempotencyKey?: string;
+/** Extra options accepted by paginated list endpoints. */
+interface ListOptions extends RequestOptionsBase {
+    limit?: number;
+    offset?: number;
+}
+/** Filters accepted by `client.calls.list()`. */
+interface CallListOptions extends ListOptions {
+    status?: string;
+    agentId?: string;
+    channel?: "phone" | "web" | "chat" | "whatsapp_call" | "whatsapp_message" | (string & {});
+    /** ISO date (e.g. "2026-05-13"); filters by call started_at ≥ this date. */
+    from?: string;
+    /** ISO date; filters by call started_at on or before this date (end-of-day). */
+    to?: string;
+    /** Free-text search across room name + agent name. */
+    search?: string;
+}
+/** Internal base — RequestOptions adds idempotencyKey on top. */
+interface RequestOptionsBase {
     /** AbortSignal for caller-side cancellation. Combined with the SDK's timeout signal. */
     signal?: AbortSignal;
     /** Per-call override of the global timeout. */
@@ -50,6 +83,9 @@ interface RequestOptions {
     /** Per-call override of the org ID. */
     organizationId?: string;
 }
+interface RequestOptions extends RequestOptionsBase {
+    idempotencyKey?: string;
+}
 interface DynamicVariables {
     [key: string]: string | number | boolean;
 }
@@ -253,12 +289,33 @@ declare class AgentsResource {
         callId: string;
     }>;
 }
-/** Call.status values that mean "no more state changes are coming". */
+/**
+ * Call statuses that mean "no more state changes are coming" — the
+ * record is final and safe to consume. `waitUntilEnded()` polls until
+ * the call's status matches one of these.
+ *
+ * Exported so downstream code can mirror the SDK's definition of "done"
+ * without copy-pasting strings (e.g. when reacting to webhook events or
+ * filtering call lists in a dashboard).
+ */
 declare const TERMINAL_CALL_STATUSES: readonly ["completed", "failed", "ended", "cancelled"];
 declare class CallsResource {
     private readonly http;
     constructor(http: HttpClient);
-    list(opts?: RequestOptions): Promise<CallRecord[]>;
+    /**
+     * List calls. Returns a paginated envelope (NOT a raw array) so you
+     * can drive UI pagination without a separate count query.
+     *
+     *   const { data, total, limit, offset } = await client.calls.list({ limit: 50 });
+     *
+     * Filters supported: `status`, `agentId`, `channel`, `from`, `to`,
+     * `search`, plus standard `limit`/`offset`. See {@link CallListOptions}.
+     *
+     * Breaking change in SDK 0.4.0: prior versions typed this as
+     * `Promise<CallRecord[]>` but the server has always returned an
+     * envelope. The type now matches reality.
+     */
+    list(opts?: CallListOptions): Promise<Paginated<CallRecord>>;
     get(id: string, opts?: RequestOptions): Promise<CallRecord>;
     /**
      * Place an outbound call. Pass `idempotencyKey` so a retry within 24h
@@ -495,6 +552,36 @@ declare class CampaignsResource {
         offset?: number;
     }): Promise<Record<string, unknown>[]>;
 }
+interface PhoneNumberRecord {
+    id: string;
+    phoneNumber: string;
+    name?: string | null;
+    countryCode?: string | null;
+    inboundAgentId?: string | null;
+    outboundAgentId?: string | null;
+    /** Joined from the agents table; convenience when rendering UIs. */
+    inboundAgentName?: string | null;
+    sipProvider?: string | null;
+    monthlyRental?: string | null;
+    isActive: boolean;
+    createdAt?: string | null;
+    [key: string]: unknown;
+}
+declare class PhoneNumbersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List phone numbers owned by your org.
+     * Returns a plain array (not yet paginated server-side).
+     */
+    list(opts?: RequestOptions): Promise<PhoneNumberRecord[]>;
+    /** Update the friendly name and/or agent bindings on a number. */
+    update(id: string, input: {
+        name?: string;
+        inboundAgentId?: string | null;
+        outboundAgentId?: string | null;
+    }, opts?: RequestOptions): Promise<PhoneNumberRecord>;
+}
 declare class DncResource {
     private readonly http;
     constructor(http: HttpClient);
@@ -583,6 +670,7 @@ declare class Osmtalk {
     readonly agents: AgentsResource;
     readonly calls: CallsResource;
     readonly campaigns: CampaignsResource;
+    readonly phoneNumbers: PhoneNumbersResource;
     readonly dnc: DncResource;
     readonly eval: EvalResource;
     readonly settings: SettingsResource;
@@ -590,4 +678,4 @@ declare class Osmtalk {
     constructor(opts: OsmtalkOptions);
 }
 
-export { type AgentRecord, type AgentTemplateResult, type AssistantOverride, type CallRecord, type CallStartRequest, type CampaignCreateRequest, type CampaignRecord, type DynamicVariables, type LeadRow, Osmtalk, OsmtalkError, type OsmtalkErrorBody, type OsmtalkOptions, type PresetCostEstimate, type PresetWithCost, type ProviderHealth, type RequestOptions, SDK_VERSION, TERMINAL_CALL_STATUSES, Osmtalk as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+export { type AgentRecord, type AgentTemplateResult, type AssistantOverride, type CallListOptions, type CallRecord, type CallStartRequest, type CampaignCreateRequest, type CampaignRecord, type DynamicVariables, type LeadRow, type ListOptions, Osmtalk, OsmtalkError, type OsmtalkErrorBody, type OsmtalkOptions, type Paginated, type PhoneNumberRecord, type PresetCostEstimate, type PresetWithCost, type ProviderHealth, type RequestOptions, SDK_VERSION, TERMINAL_CALL_STATUSES, Osmtalk as default, verifyWebhookSignature, verifyWebhookSignatureAsync };

package/dist/index.d.ts

@@ -10,8 +10,24 @@
  *     dynamicVariables: { first_name: "Arjun" },
  *   });
  */
-/** Bumped on every release — surfaced in the User-Agent header. */
-declare const SDK_VERSION = "0.3.0";
+/**
+ * Current SDK version, sent in the User-Agent header and useful for
+ * runtime version checks (e.g. logging which SDK build is talking to the
+ * API, or feature-detecting against minimum versions in shared code).
+ */
+declare const SDK_VERSION = "0.4.0";
+/**
+ * Paginated list envelope returned by some endpoints (currently
+ * `calls.list`; more list resources will migrate to this shape over
+ * future minor versions). Lets consumers build pagination UIs without
+ * a second count request.
+ */
+interface Paginated<T> {
+    data: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
 interface OsmtalkOptions {
     apiKey: string;
     baseUrl?: string;
@@ -41,8 +57,25 @@ interface OsmtalkOptions {
      */
     organizationId?: string;
 }
-interface RequestOptions {
-    idempotencyKey?: string;
+/** Extra options accepted by paginated list endpoints. */
+interface ListOptions extends RequestOptionsBase {
+    limit?: number;
+    offset?: number;
+}
+/** Filters accepted by `client.calls.list()`. */
+interface CallListOptions extends ListOptions {
+    status?: string;
+    agentId?: string;
+    channel?: "phone" | "web" | "chat" | "whatsapp_call" | "whatsapp_message" | (string & {});
+    /** ISO date (e.g. "2026-05-13"); filters by call started_at ≥ this date. */
+    from?: string;
+    /** ISO date; filters by call started_at on or before this date (end-of-day). */
+    to?: string;
+    /** Free-text search across room name + agent name. */
+    search?: string;
+}
+/** Internal base — RequestOptions adds idempotencyKey on top. */
+interface RequestOptionsBase {
     /** AbortSignal for caller-side cancellation. Combined with the SDK's timeout signal. */
     signal?: AbortSignal;
     /** Per-call override of the global timeout. */
@@ -50,6 +83,9 @@ interface RequestOptions {
     /** Per-call override of the org ID. */
     organizationId?: string;
 }
+interface RequestOptions extends RequestOptionsBase {
+    idempotencyKey?: string;
+}
 interface DynamicVariables {
     [key: string]: string | number | boolean;
 }
@@ -253,12 +289,33 @@ declare class AgentsResource {
         callId: string;
     }>;
 }
-/** Call.status values that mean "no more state changes are coming". */
+/**
+ * Call statuses that mean "no more state changes are coming" — the
+ * record is final and safe to consume. `waitUntilEnded()` polls until
+ * the call's status matches one of these.
+ *
+ * Exported so downstream code can mirror the SDK's definition of "done"
+ * without copy-pasting strings (e.g. when reacting to webhook events or
+ * filtering call lists in a dashboard).
+ */
 declare const TERMINAL_CALL_STATUSES: readonly ["completed", "failed", "ended", "cancelled"];
 declare class CallsResource {
     private readonly http;
     constructor(http: HttpClient);
-    list(opts?: RequestOptions): Promise<CallRecord[]>;
+    /**
+     * List calls. Returns a paginated envelope (NOT a raw array) so you
+     * can drive UI pagination without a separate count query.
+     *
+     *   const { data, total, limit, offset } = await client.calls.list({ limit: 50 });
+     *
+     * Filters supported: `status`, `agentId`, `channel`, `from`, `to`,
+     * `search`, plus standard `limit`/`offset`. See {@link CallListOptions}.
+     *
+     * Breaking change in SDK 0.4.0: prior versions typed this as
+     * `Promise<CallRecord[]>` but the server has always returned an
+     * envelope. The type now matches reality.
+     */
+    list(opts?: CallListOptions): Promise<Paginated<CallRecord>>;
     get(id: string, opts?: RequestOptions): Promise<CallRecord>;
     /**
      * Place an outbound call. Pass `idempotencyKey` so a retry within 24h
@@ -495,6 +552,36 @@ declare class CampaignsResource {
         offset?: number;
     }): Promise<Record<string, unknown>[]>;
 }
+interface PhoneNumberRecord {
+    id: string;
+    phoneNumber: string;
+    name?: string | null;
+    countryCode?: string | null;
+    inboundAgentId?: string | null;
+    outboundAgentId?: string | null;
+    /** Joined from the agents table; convenience when rendering UIs. */
+    inboundAgentName?: string | null;
+    sipProvider?: string | null;
+    monthlyRental?: string | null;
+    isActive: boolean;
+    createdAt?: string | null;
+    [key: string]: unknown;
+}
+declare class PhoneNumbersResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List phone numbers owned by your org.
+     * Returns a plain array (not yet paginated server-side).
+     */
+    list(opts?: RequestOptions): Promise<PhoneNumberRecord[]>;
+    /** Update the friendly name and/or agent bindings on a number. */
+    update(id: string, input: {
+        name?: string;
+        inboundAgentId?: string | null;
+        outboundAgentId?: string | null;
+    }, opts?: RequestOptions): Promise<PhoneNumberRecord>;
+}
 declare class DncResource {
     private readonly http;
     constructor(http: HttpClient);
@@ -583,6 +670,7 @@ declare class Osmtalk {
     readonly agents: AgentsResource;
     readonly calls: CallsResource;
     readonly campaigns: CampaignsResource;
+    readonly phoneNumbers: PhoneNumbersResource;
     readonly dnc: DncResource;
     readonly eval: EvalResource;
     readonly settings: SettingsResource;
@@ -590,4 +678,4 @@ declare class Osmtalk {
     constructor(opts: OsmtalkOptions);
 }
 
-export { type AgentRecord, type AgentTemplateResult, type AssistantOverride, type CallRecord, type CallStartRequest, type CampaignCreateRequest, type CampaignRecord, type DynamicVariables, type LeadRow, Osmtalk, OsmtalkError, type OsmtalkErrorBody, type OsmtalkOptions, type PresetCostEstimate, type PresetWithCost, type ProviderHealth, type RequestOptions, SDK_VERSION, TERMINAL_CALL_STATUSES, Osmtalk as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+export { type AgentRecord, type AgentTemplateResult, type AssistantOverride, type CallListOptions, type CallRecord, type CallStartRequest, type CampaignCreateRequest, type CampaignRecord, type DynamicVariables, type LeadRow, type ListOptions, Osmtalk, OsmtalkError, type OsmtalkErrorBody, type OsmtalkOptions, type Paginated, type PhoneNumberRecord, type PresetCostEstimate, type PresetWithCost, type ProviderHealth, type RequestOptions, SDK_VERSION, TERMINAL_CALL_STATUSES, Osmtalk as default, verifyWebhookSignature, verifyWebhookSignatureAsync };

package/dist/index.js

@@ -29,7 +29,7 @@ __export(index_exports, {
   verifyWebhookSignatureAsync: () => verifyWebhookSignatureAsync
 });
 module.exports = __toCommonJS(index_exports);
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.4.0";
 var OsmtalkError = class extends Error {
   status;
   body;
@@ -273,8 +273,38 @@ var CallsResource = class {
     this.http = http;
   }
   http;
+  /**
+   * List calls. Returns a paginated envelope (NOT a raw array) so you
+   * can drive UI pagination without a separate count query.
+   *
+   *   const { data, total, limit, offset } = await client.calls.list({ limit: 50 });
+   *
+   * Filters supported: `status`, `agentId`, `channel`, `from`, `to`,
+   * `search`, plus standard `limit`/`offset`. See {@link CallListOptions}.
+   *
+   * Breaking change in SDK 0.4.0: prior versions typed this as
+   * `Promise<CallRecord[]>` but the server has always returned an
+   * envelope. The type now matches reality.
+   */
   list(opts) {
-    return this.http.request("GET", "/api/calls", void 0, void 0, void 0, opts);
+    const qs = new URLSearchParams();
+    if (opts?.status) qs.set("status", opts.status);
+    if (opts?.agentId) qs.set("agentId", opts.agentId);
+    if (opts?.channel) qs.set("channel", String(opts.channel));
+    if (opts?.from) qs.set("from", opts.from);
+    if (opts?.to) qs.set("to", opts.to);
+    if (opts?.search) qs.set("search", opts.search);
+    if (opts?.limit !== void 0) qs.set("limit", String(opts.limit));
+    if (opts?.offset !== void 0) qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs}` : "";
+    return this.http.request(
+      "GET",
+      `/api/calls${suffix}`,
+      void 0,
+      void 0,
+      void 0,
+      opts
+    );
   }
   get(id, opts) {
     return this.http.request("GET", `/api/calls/${id}`, void 0, void 0, void 0, opts);
@@ -519,6 +549,37 @@ var CampaignsResource = class {
     return this.http.request("GET", `/api/campaigns/${id}/leads${suffix}`);
   }
 };
+var PhoneNumbersResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * List phone numbers owned by your org.
+   * Returns a plain array (not yet paginated server-side).
+   */
+  list(opts) {
+    return this.http.request(
+      "GET",
+      "/api/phone-numbers",
+      void 0,
+      void 0,
+      void 0,
+      opts
+    );
+  }
+  /** Update the friendly name and/or agent bindings on a number. */
+  update(id, input, opts) {
+    return this.http.request(
+      "PUT",
+      `/api/phone-numbers/${id}`,
+      input,
+      void 0,
+      opts?.idempotencyKey,
+      opts
+    );
+  }
+};
 var DncResource = class {
   constructor(http) {
     this.http = http;
@@ -602,6 +663,7 @@ var Osmtalk = class {
   agents;
   calls;
   campaigns;
+  phoneNumbers;
   dnc;
   eval;
   settings;
@@ -611,6 +673,7 @@ var Osmtalk = class {
     this.agents = new AgentsResource(http);
     this.calls = new CallsResource(http);
     this.campaigns = new CampaignsResource(http);
+    this.phoneNumbers = new PhoneNumbersResource(http);
     this.dnc = new DncResource(http);
     this.eval = new EvalResource(http);
     this.settings = new SettingsResource(http);

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.4.0";
 var OsmtalkError = class extends Error {
   status;
   body;
@@ -243,8 +243,38 @@ var CallsResource = class {
     this.http = http;
   }
   http;
+  /**
+   * List calls. Returns a paginated envelope (NOT a raw array) so you
+   * can drive UI pagination without a separate count query.
+   *
+   *   const { data, total, limit, offset } = await client.calls.list({ limit: 50 });
+   *
+   * Filters supported: `status`, `agentId`, `channel`, `from`, `to`,
+   * `search`, plus standard `limit`/`offset`. See {@link CallListOptions}.
+   *
+   * Breaking change in SDK 0.4.0: prior versions typed this as
+   * `Promise<CallRecord[]>` but the server has always returned an
+   * envelope. The type now matches reality.
+   */
   list(opts) {
-    return this.http.request("GET", "/api/calls", void 0, void 0, void 0, opts);
+    const qs = new URLSearchParams();
+    if (opts?.status) qs.set("status", opts.status);
+    if (opts?.agentId) qs.set("agentId", opts.agentId);
+    if (opts?.channel) qs.set("channel", String(opts.channel));
+    if (opts?.from) qs.set("from", opts.from);
+    if (opts?.to) qs.set("to", opts.to);
+    if (opts?.search) qs.set("search", opts.search);
+    if (opts?.limit !== void 0) qs.set("limit", String(opts.limit));
+    if (opts?.offset !== void 0) qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs}` : "";
+    return this.http.request(
+      "GET",
+      `/api/calls${suffix}`,
+      void 0,
+      void 0,
+      void 0,
+      opts
+    );
   }
   get(id, opts) {
     return this.http.request("GET", `/api/calls/${id}`, void 0, void 0, void 0, opts);
@@ -489,6 +519,37 @@ var CampaignsResource = class {
     return this.http.request("GET", `/api/campaigns/${id}/leads${suffix}`);
   }
 };
+var PhoneNumbersResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * List phone numbers owned by your org.
+   * Returns a plain array (not yet paginated server-side).
+   */
+  list(opts) {
+    return this.http.request(
+      "GET",
+      "/api/phone-numbers",
+      void 0,
+      void 0,
+      void 0,
+      opts
+    );
+  }
+  /** Update the friendly name and/or agent bindings on a number. */
+  update(id, input, opts) {
+    return this.http.request(
+      "PUT",
+      `/api/phone-numbers/${id}`,
+      input,
+      void 0,
+      opts?.idempotencyKey,
+      opts
+    );
+  }
+};
 var DncResource = class {
   constructor(http) {
     this.http = http;
@@ -572,6 +633,7 @@ var Osmtalk = class {
   agents;
   calls;
   campaigns;
+  phoneNumbers;
   dnc;
   eval;
   settings;
@@ -581,6 +643,7 @@ var Osmtalk = class {
     this.agents = new AgentsResource(http);
     this.calls = new CallsResource(http);
     this.campaigns = new CampaignsResource(http);
+    this.phoneNumbers = new PhoneNumbersResource(http);
     this.dnc = new DncResource(http);
     this.eval = new EvalResource(http);
     this.settings = new SettingsResource(http);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osmapi/osmtalk-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Official TypeScript SDK for the osmTalk voice AI platform",
   "homepage": "https://docs.osmtalk.com",
   "repository": {