@osmapi/osmtalk-sdk 0.3.1 → 0.4.0

package/README.md

@@ -38,8 +38,9 @@ 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`, **`waitUntilEnded`** |
+| `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` |
@@ -47,6 +48,12 @@ console.log("Call started:", call.callId);
 
 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.
@@ -86,6 +93,22 @@ 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

package/dist/index.d.mts

@@ -15,7 +15,19 @@
  * 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.3.1";
+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;
@@ -45,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. */
@@ -54,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;
 }
@@ -270,7 +302,20 @@ declare const TERMINAL_CALL_STATUSES: readonly ["completed", "failed", "ended",
 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
@@ -507,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);
@@ -595,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;
@@ -602,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

@@ -15,7 +15,19 @@
  * 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.3.1";
+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;
@@ -45,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. */
@@ -54,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;
 }
@@ -270,7 +302,20 @@ declare const TERMINAL_CALL_STATUSES: readonly ["completed", "failed", "ended",
 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
@@ -507,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);
@@ -595,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;
@@ -602,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.1";
+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.1";
+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.1",
+  "version": "0.4.0",
   "description": "Official TypeScript SDK for the osmTalk voice AI platform",
   "homepage": "https://docs.osmtalk.com",
   "repository": {