@osmapi/osmtalk-sdk 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -10,12 +10,45 @@
  *     dynamicVariables: { first_name: "Arjun" },
  *   });
  */
+/** Bumped on every release — surfaced in the User-Agent header. */
+declare const SDK_VERSION = "0.3.0";
 interface OsmtalkOptions {
     apiKey: string;
     baseUrl?: string;
+    /** Per-request timeout. Default 30s. Set `0` to disable. */
     timeoutMs?: number;
     /** Custom fetch implementation (e.g. for testing). */
     fetch?: typeof fetch;
+    /**
+     * Maximum auto-retries on transient failures (5xx, 429, network
+     * errors). Default 2. Set to 0 to disable. Mutating requests (POST,
+     * PUT, DELETE) are only retried when an `idempotencyKey` is set on
+     * the call — otherwise a retry could double-charge or double-place
+     * a call.
+     */
+    maxRetries?: number;
+    /**
+     * Initial retry delay in ms. Doubled on each subsequent retry.
+     * Default 250ms → 500 → 1000. Server `Retry-After` headers take
+     * precedence when present.
+     */
+    retryInitialDelayMs?: number;
+    /** Extra headers added to every request (e.g. observability IDs). */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Org ID to send as `X-Organization-Id`. For users in multiple orgs;
+     * defaults to the API key's primary org if omitted.
+     */
+    organizationId?: string;
+}
+interface RequestOptions {
+    idempotencyKey?: string;
+    /** AbortSignal for caller-side cancellation. Combined with the SDK's timeout signal. */
+    signal?: AbortSignal;
+    /** Per-call override of the global timeout. */
+    timeoutMs?: number;
+    /** Per-call override of the org ID. */
+    organizationId?: string;
 }
 interface DynamicVariables {
     [key: string]: string | number | boolean;
@@ -141,15 +174,36 @@ interface OsmtalkErrorBody {
 declare class OsmtalkError extends Error {
     readonly status: number;
     readonly body: OsmtalkErrorBody;
-    constructor(status: number, body: OsmtalkErrorBody);
+    /** Number of retry attempts the SDK made before giving up. */
+    readonly retryAttempts: number;
+    constructor(status: number, body: OsmtalkErrorBody, retryAttempts?: number);
+    /** True for status codes the server might recover from on retry. */
+    get isRetryable(): boolean;
+    /** True for client mistakes (bad input, bad auth). */
+    get isClientError(): boolean;
 }
 declare class HttpClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryInitialDelayMs;
     private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly organizationId;
+    private readonly userAgent;
     constructor(opts: OsmtalkOptions);
-    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>, idempotencyKey?: string): Promise<T>;
+    /**
+     * Combine the caller's AbortSignal with the SDK's per-request timeout
+     * signal so EITHER firing cancels the fetch. We can't use
+     * `AbortSignal.any` (Node 18 doesn't have it), so we wire it manually.
+     */
+    private buildAbortSignal;
+    /** Parse the body once for both success and error paths. */
+    private static parseBody;
+    /** How long to wait before the next retry. Honors Retry-After. */
+    private retryDelay;
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>, idempotencyKey?: string, options?: RequestOptions): Promise<T>;
 }
 declare class AgentsResource {
     private readonly http;
@@ -199,27 +253,46 @@ declare class AgentsResource {
         callId: string;
     }>;
 }
+/** Call.status values that mean "no more state changes are coming". */
+declare const TERMINAL_CALL_STATUSES: readonly ["completed", "failed", "ended", "cancelled"];
 declare class CallsResource {
     private readonly http;
     constructor(http: HttpClient);
-    list(): Promise<CallRecord[]>;
-    get(id: string): Promise<CallRecord>;
+    list(opts?: RequestOptions): Promise<CallRecord[]>;
+    get(id: string, opts?: RequestOptions): Promise<CallRecord>;
     /**
-     * Place an outbound call. Optionally pass `idempotencyKey` so retries
-     * within 24h return the same response instead of placing a duplicate call.
+     * Place an outbound call. Pass `idempotencyKey` so a retry within 24h
+     * returns the same response instead of placing a duplicate call —
+     * required if you want this call to be retried on transient failures.
      */
-    outbound(input: CallStartRequest, opts?: {
-        idempotencyKey?: string;
-    }): Promise<{
+    outbound(input: CallStartRequest, opts?: RequestOptions): Promise<{
         callId: string;
         roomName: string;
     }>;
-    end(id: string): Promise<{
+    end(id: string, opts?: RequestOptions): Promise<{
         success: true;
     }>;
-    transfer(id: string, destination: string, summary?: string): Promise<{
+    transfer(id: string, destination: string, summary?: string, opts?: RequestOptions): Promise<{
         success: true;
     }>;
+    /**
+     * Poll a call until it reaches a terminal status (`completed`,
+     * `failed`, `ended`, `cancelled`) and return the final record.
+     *
+     * Saves consumers from writing the same loop in every script. Use
+     * webhooks instead in production — this is fine for scripts, demos,
+     * and one-off jobs but consumes API quota on every poll.
+     *
+     * @param opts.pollIntervalMs - default 5s
+     * @param opts.timeoutMs      - default 30min (rejects with
+     *                              `OsmtalkError` 408 on timeout)
+     * @param opts.signal         - abort externally
+     */
+    waitUntilEnded(id: string, opts?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<CallRecord>;
 }
 declare class PlatformResource {
     private readonly http;
@@ -517,4 +590,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, Osmtalk as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+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 };

package/dist/index.d.ts

@@ -10,12 +10,45 @@
  *     dynamicVariables: { first_name: "Arjun" },
  *   });
  */
+/** Bumped on every release — surfaced in the User-Agent header. */
+declare const SDK_VERSION = "0.3.0";
 interface OsmtalkOptions {
     apiKey: string;
     baseUrl?: string;
+    /** Per-request timeout. Default 30s. Set `0` to disable. */
     timeoutMs?: number;
     /** Custom fetch implementation (e.g. for testing). */
     fetch?: typeof fetch;
+    /**
+     * Maximum auto-retries on transient failures (5xx, 429, network
+     * errors). Default 2. Set to 0 to disable. Mutating requests (POST,
+     * PUT, DELETE) are only retried when an `idempotencyKey` is set on
+     * the call — otherwise a retry could double-charge or double-place
+     * a call.
+     */
+    maxRetries?: number;
+    /**
+     * Initial retry delay in ms. Doubled on each subsequent retry.
+     * Default 250ms → 500 → 1000. Server `Retry-After` headers take
+     * precedence when present.
+     */
+    retryInitialDelayMs?: number;
+    /** Extra headers added to every request (e.g. observability IDs). */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Org ID to send as `X-Organization-Id`. For users in multiple orgs;
+     * defaults to the API key's primary org if omitted.
+     */
+    organizationId?: string;
+}
+interface RequestOptions {
+    idempotencyKey?: string;
+    /** AbortSignal for caller-side cancellation. Combined with the SDK's timeout signal. */
+    signal?: AbortSignal;
+    /** Per-call override of the global timeout. */
+    timeoutMs?: number;
+    /** Per-call override of the org ID. */
+    organizationId?: string;
 }
 interface DynamicVariables {
     [key: string]: string | number | boolean;
@@ -141,15 +174,36 @@ interface OsmtalkErrorBody {
 declare class OsmtalkError extends Error {
     readonly status: number;
     readonly body: OsmtalkErrorBody;
-    constructor(status: number, body: OsmtalkErrorBody);
+    /** Number of retry attempts the SDK made before giving up. */
+    readonly retryAttempts: number;
+    constructor(status: number, body: OsmtalkErrorBody, retryAttempts?: number);
+    /** True for status codes the server might recover from on retry. */
+    get isRetryable(): boolean;
+    /** True for client mistakes (bad input, bad auth). */
+    get isClientError(): boolean;
 }
 declare class HttpClient {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryInitialDelayMs;
     private readonly fetchImpl;
+    private readonly defaultHeaders;
+    private readonly organizationId;
+    private readonly userAgent;
     constructor(opts: OsmtalkOptions);
-    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>, idempotencyKey?: string): Promise<T>;
+    /**
+     * Combine the caller's AbortSignal with the SDK's per-request timeout
+     * signal so EITHER firing cancels the fetch. We can't use
+     * `AbortSignal.any` (Node 18 doesn't have it), so we wire it manually.
+     */
+    private buildAbortSignal;
+    /** Parse the body once for both success and error paths. */
+    private static parseBody;
+    /** How long to wait before the next retry. Honors Retry-After. */
+    private retryDelay;
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>, idempotencyKey?: string, options?: RequestOptions): Promise<T>;
 }
 declare class AgentsResource {
     private readonly http;
@@ -199,27 +253,46 @@ declare class AgentsResource {
         callId: string;
     }>;
 }
+/** Call.status values that mean "no more state changes are coming". */
+declare const TERMINAL_CALL_STATUSES: readonly ["completed", "failed", "ended", "cancelled"];
 declare class CallsResource {
     private readonly http;
     constructor(http: HttpClient);
-    list(): Promise<CallRecord[]>;
-    get(id: string): Promise<CallRecord>;
+    list(opts?: RequestOptions): Promise<CallRecord[]>;
+    get(id: string, opts?: RequestOptions): Promise<CallRecord>;
     /**
-     * Place an outbound call. Optionally pass `idempotencyKey` so retries
-     * within 24h return the same response instead of placing a duplicate call.
+     * Place an outbound call. Pass `idempotencyKey` so a retry within 24h
+     * returns the same response instead of placing a duplicate call —
+     * required if you want this call to be retried on transient failures.
      */
-    outbound(input: CallStartRequest, opts?: {
-        idempotencyKey?: string;
-    }): Promise<{
+    outbound(input: CallStartRequest, opts?: RequestOptions): Promise<{
         callId: string;
         roomName: string;
     }>;
-    end(id: string): Promise<{
+    end(id: string, opts?: RequestOptions): Promise<{
         success: true;
     }>;
-    transfer(id: string, destination: string, summary?: string): Promise<{
+    transfer(id: string, destination: string, summary?: string, opts?: RequestOptions): Promise<{
         success: true;
     }>;
+    /**
+     * Poll a call until it reaches a terminal status (`completed`,
+     * `failed`, `ended`, `cancelled`) and return the final record.
+     *
+     * Saves consumers from writing the same loop in every script. Use
+     * webhooks instead in production — this is fine for scripts, demos,
+     * and one-off jobs but consumes API quota on every poll.
+     *
+     * @param opts.pollIntervalMs - default 5s
+     * @param opts.timeoutMs      - default 30min (rejects with
+     *                              `OsmtalkError` 408 on timeout)
+     * @param opts.signal         - abort externally
+     */
+    waitUntilEnded(id: string, opts?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<CallRecord>;
 }
 declare class PlatformResource {
     private readonly http;
@@ -517,4 +590,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, Osmtalk as default, verifyWebhookSignature, verifyWebhookSignatureAsync };
+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 };

package/dist/index.js

@@ -22,68 +22,196 @@ var index_exports = {};
 __export(index_exports, {
   Osmtalk: () => Osmtalk,
   OsmtalkError: () => OsmtalkError,
+  SDK_VERSION: () => SDK_VERSION,
+  TERMINAL_CALL_STATUSES: () => TERMINAL_CALL_STATUSES,
   default: () => index_default,
   verifyWebhookSignature: () => verifyWebhookSignature,
   verifyWebhookSignatureAsync: () => verifyWebhookSignatureAsync
 });
 module.exports = __toCommonJS(index_exports);
+var SDK_VERSION = "0.3.0";
 var OsmtalkError = class extends Error {
   status;
   body;
-  constructor(status, body) {
+  /** Number of retry attempts the SDK made before giving up. */
+  retryAttempts;
+  constructor(status, body, retryAttempts = 0) {
     super(body?.error || body?.message || `osmTalk API error: ${status}`);
     this.name = "OsmtalkError";
     this.status = status;
     this.body = body;
+    this.retryAttempts = retryAttempts;
   }
+  /** True for status codes the server might recover from on retry. */
+  get isRetryable() {
+    return this.status === 408 || this.status === 429 || this.status >= 500;
+  }
+  /** True for client mistakes (bad input, bad auth). */
+  get isClientError() {
+    return this.status >= 400 && this.status < 500;
+  }
+};
+function runtimeTag() {
+  const g = globalThis;
+  if (g.Deno?.version?.deno) return `deno/${g.Deno.version.deno}`;
+  if (g.Bun?.version) return `bun/${g.Bun.version}`;
+  if (g.process?.versions?.node) return `node/${g.process.versions.node}`;
+  if (typeof navigator !== "undefined" && navigator.userAgent) return "browser";
+  return "unknown";
+}
+var STATUS_TEXT = {
+  408: "Request Timeout",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
 };
-var HttpClient = class {
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var HttpClient = class _HttpClient {
   baseUrl;
   apiKey;
   timeoutMs;
+  maxRetries;
+  retryInitialDelayMs;
   fetchImpl;
+  defaultHeaders;
+  organizationId;
+  userAgent;
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://api.osmtalk.com").replace(/\/$/, "");
     this.timeoutMs = opts.timeoutMs ?? 3e4;
+    this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
+    this.retryInitialDelayMs = Math.max(0, opts.retryInitialDelayMs ?? 250);
+    this.defaultHeaders = opts.defaultHeaders ?? {};
+    this.organizationId = opts.organizationId;
+    this.userAgent = `@osmapi/osmtalk-sdk/${SDK_VERSION} ${runtimeTag()}`;
     this.fetchImpl = opts.fetch ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : void 0);
-    if (!this.fetchImpl) throw new Error("No fetch implementation available \u2014 provide one in OsmtalkOptions.fetch");
+    if (!this.fetchImpl) {
+      throw new Error("No fetch implementation available \u2014 provide one in OsmtalkOptions.fetch");
+    }
     if (!opts.apiKey) throw new Error("apiKey is required");
   }
-  async request(method, path, body, extraHeaders, idempotencyKey) {
+  /**
+   * Combine the caller's AbortSignal with the SDK's per-request timeout
+   * signal so EITHER firing cancels the fetch. We can't use
+   * `AbortSignal.any` (Node 18 doesn't have it), so we wire it manually.
+   */
+  buildAbortSignal(externalSignal, timeoutMs) {
     const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    const onAbort = () => ctrl.abort();
+    if (externalSignal) {
+      if (externalSignal.aborted) ctrl.abort();
+      else externalSignal.addEventListener("abort", onAbort, { once: true });
+    }
+    const timer = timeoutMs > 0 ? setTimeout(() => ctrl.abort(new Error("Request timed out")), timeoutMs) : null;
+    return {
+      signal: ctrl.signal,
+      cancel: () => {
+        if (timer) clearTimeout(timer);
+        if (externalSignal) externalSignal.removeEventListener("abort", onAbort);
+      }
+    };
+  }
+  /** Parse the body once for both success and error paths. */
+  static async parseBody(res) {
+    const text = await res.text();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  /** How long to wait before the next retry. Honors Retry-After. */
+  retryDelay(attempt, res) {
+    if (res) {
+      const retryAfter = res.headers.get("retry-after");
+      if (retryAfter) {
+        const secs = Number(retryAfter);
+        if (Number.isFinite(secs) && secs >= 0) return Math.min(secs * 1e3, 3e4);
+        const when = Date.parse(retryAfter);
+        if (!Number.isNaN(when)) return Math.max(0, Math.min(when - Date.now(), 3e4));
+      }
+    }
+    const base = this.retryInitialDelayMs * 2 ** attempt;
+    const jitter = Math.floor(Math.random() * (base / 4));
+    return Math.min(base + jitter, 3e4);
+  }
+  async request(method, path, body, extraHeaders, idempotencyKey, options) {
+    const reqOrgId = options?.organizationId ?? this.organizationId;
+    const reqTimeout = options?.timeoutMs ?? this.timeoutMs;
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
+      "User-Agent": this.userAgent,
+      Accept: "application/json",
       ...body !== void 0 ? { "Content-Type": "application/json" } : {},
       ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {},
+      ...reqOrgId ? { "X-Organization-Id": reqOrgId } : {},
+      ...this.defaultHeaders,
       ...extraHeaders ?? {}
     };
-    let res;
-    try {
-      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
-        method,
-        headers,
-        body: body === void 0 ? void 0 : typeof body === "string" ? body : JSON.stringify(body),
-        signal: ctrl.signal
-      });
-    } finally {
-      clearTimeout(timer);
-    }
-    const text = await res.text();
-    const parsed = text ? (() => {
+    const serializedBody = body === void 0 ? void 0 : typeof body === "string" ? body : JSON.stringify(body);
+    const canRetryMutation = SAFE_METHODS.has(method.toUpperCase()) || Boolean(idempotencyKey);
+    const url = `${this.baseUrl}${path}`;
+    let lastErr;
+    let lastRes = null;
+    const maxAttempts = this.maxRetries + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const { signal, cancel } = this.buildAbortSignal(options?.signal, reqTimeout);
+      let res = null;
       try {
-        return JSON.parse(text);
-      } catch {
-        return text;
+        res = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: serializedBody,
+          signal
+        });
+      } catch (err) {
+        lastErr = err;
+        cancel();
+        if (options?.signal?.aborted) throw err;
+        if (attempt < maxAttempts - 1 && canRetryMutation) {
+          await sleep(this.retryDelay(attempt, null));
+          continue;
+        }
+        throw err;
+      }
+      cancel();
+      if (res.ok) {
+        return await _HttpClient.parseBody(res);
       }
-    })() : null;
-    if (!res.ok) {
-      throw new OsmtalkError(res.status, parsed ?? { error: text });
+      const retryable = RETRYABLE_STATUSES.has(res.status);
+      if (retryable && canRetryMutation && attempt < maxAttempts - 1) {
+        try {
+          await res.text();
+        } catch {
+        }
+        await sleep(this.retryDelay(attempt, res));
+        lastRes = res;
+        continue;
+      }
+      const parsed = await _HttpClient.parseBody(res);
+      throw new OsmtalkError(
+        res.status,
+        parsed ?? { error: STATUS_TEXT[res.status] ?? `HTTP ${res.status}` },
+        attempt
+      );
+    }
+    if (lastRes) {
+      const parsed = await _HttpClient.parseBody(lastRes);
+      throw new OsmtalkError(
+        lastRes.status,
+        parsed ?? { error: STATUS_TEXT[lastRes.status] ?? "Server error" },
+        maxAttempts - 1
+      );
     }
-    return parsed;
+    throw lastErr ?? new Error("osmTalk SDK: request failed without details");
   }
 };
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var AgentsResource = class {
   constructor(http) {
     this.http = http;
@@ -139,20 +267,22 @@ var AgentsResource = class {
     );
   }
 };
+var TERMINAL_CALL_STATUSES = ["completed", "failed", "ended", "cancelled"];
 var CallsResource = class {
   constructor(http) {
     this.http = http;
   }
   http;
-  list() {
-    return this.http.request("GET", "/api/calls");
+  list(opts) {
+    return this.http.request("GET", "/api/calls", void 0, void 0, void 0, opts);
   }
-  get(id) {
-    return this.http.request("GET", `/api/calls/${id}`);
+  get(id, opts) {
+    return this.http.request("GET", `/api/calls/${id}`, void 0, void 0, void 0, opts);
   }
   /**
-   * Place an outbound call. Optionally pass `idempotencyKey` so retries
-   * within 24h return the same response instead of placing a duplicate call.
+   * Place an outbound call. Pass `idempotencyKey` so a retry within 24h
+   * returns the same response instead of placing a duplicate call —
+   * required if you want this call to be retried on transient failures.
    */
   outbound(input, opts) {
     return this.http.request(
@@ -160,14 +290,61 @@ var CallsResource = class {
       "/api/calls/outbound",
       input,
       void 0,
-      opts?.idempotencyKey
+      opts?.idempotencyKey,
+      opts
+    );
+  }
+  end(id, opts) {
+    return this.http.request(
+      "POST",
+      `/api/calls/${id}/end`,
+      void 0,
+      void 0,
+      opts?.idempotencyKey,
+      opts
     );
   }
-  end(id) {
-    return this.http.request("POST", `/api/calls/${id}/end`);
+  transfer(id, destination, summary, opts) {
+    return this.http.request(
+      "POST",
+      `/api/calls/${id}/transfer`,
+      { destination, summary },
+      void 0,
+      opts?.idempotencyKey,
+      opts
+    );
   }
-  transfer(id, destination, summary) {
-    return this.http.request("POST", `/api/calls/${id}/transfer`, { destination, summary });
+  /**
+   * Poll a call until it reaches a terminal status (`completed`,
+   * `failed`, `ended`, `cancelled`) and return the final record.
+   *
+   * Saves consumers from writing the same loop in every script. Use
+   * webhooks instead in production — this is fine for scripts, demos,
+   * and one-off jobs but consumes API quota on every poll.
+   *
+   * @param opts.pollIntervalMs - default 5s
+   * @param opts.timeoutMs      - default 30min (rejects with
+   *                              `OsmtalkError` 408 on timeout)
+   * @param opts.signal         - abort externally
+   */
+  async waitUntilEnded(id, opts) {
+    const pollInterval = Math.max(1e3, opts?.pollIntervalMs ?? 5e3);
+    const totalTimeout = opts?.timeoutMs ?? 30 * 60 * 1e3;
+    const deadline = Date.now() + totalTimeout;
+    const terminal = new Set(TERMINAL_CALL_STATUSES);
+    while (true) {
+      if (opts?.signal?.aborted) {
+        throw new OsmtalkError(0, { error: "Aborted by caller" });
+      }
+      const call = await this.get(id, { signal: opts?.signal });
+      if (terminal.has(call.status)) return call;
+      if (Date.now() >= deadline) {
+        throw new OsmtalkError(408, {
+          error: `waitUntilEnded: call ${id} did not reach a terminal state within ${totalTimeout}ms (last status: ${call.status})`
+        });
+      }
+      await sleep(Math.min(pollInterval, Math.max(0, deadline - Date.now())));
+    }
   }
 };
 var PlatformResource = class {
@@ -445,6 +622,8 @@ var index_default = Osmtalk;
 0 && (module.exports = {
   Osmtalk,
   OsmtalkError,
+  SDK_VERSION,
+  TERMINAL_CALL_STATUSES,
   verifyWebhookSignature,
   verifyWebhookSignatureAsync
 });

package/dist/index.mjs

@@ -1,61 +1,187 @@
 // src/index.ts
+var SDK_VERSION = "0.3.0";
 var OsmtalkError = class extends Error {
   status;
   body;
-  constructor(status, body) {
+  /** Number of retry attempts the SDK made before giving up. */
+  retryAttempts;
+  constructor(status, body, retryAttempts = 0) {
     super(body?.error || body?.message || `osmTalk API error: ${status}`);
     this.name = "OsmtalkError";
     this.status = status;
     this.body = body;
+    this.retryAttempts = retryAttempts;
   }
+  /** True for status codes the server might recover from on retry. */
+  get isRetryable() {
+    return this.status === 408 || this.status === 429 || this.status >= 500;
+  }
+  /** True for client mistakes (bad input, bad auth). */
+  get isClientError() {
+    return this.status >= 400 && this.status < 500;
+  }
+};
+function runtimeTag() {
+  const g = globalThis;
+  if (g.Deno?.version?.deno) return `deno/${g.Deno.version.deno}`;
+  if (g.Bun?.version) return `bun/${g.Bun.version}`;
+  if (g.process?.versions?.node) return `node/${g.process.versions.node}`;
+  if (typeof navigator !== "undefined" && navigator.userAgent) return "browser";
+  return "unknown";
+}
+var STATUS_TEXT = {
+  408: "Request Timeout",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
 };
-var HttpClient = class {
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var HttpClient = class _HttpClient {
   baseUrl;
   apiKey;
   timeoutMs;
+  maxRetries;
+  retryInitialDelayMs;
   fetchImpl;
+  defaultHeaders;
+  organizationId;
+  userAgent;
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.baseUrl = (opts.baseUrl ?? "https://api.osmtalk.com").replace(/\/$/, "");
     this.timeoutMs = opts.timeoutMs ?? 3e4;
+    this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
+    this.retryInitialDelayMs = Math.max(0, opts.retryInitialDelayMs ?? 250);
+    this.defaultHeaders = opts.defaultHeaders ?? {};
+    this.organizationId = opts.organizationId;
+    this.userAgent = `@osmapi/osmtalk-sdk/${SDK_VERSION} ${runtimeTag()}`;
     this.fetchImpl = opts.fetch ?? (typeof fetch !== "undefined" ? fetch.bind(globalThis) : void 0);
-    if (!this.fetchImpl) throw new Error("No fetch implementation available \u2014 provide one in OsmtalkOptions.fetch");
+    if (!this.fetchImpl) {
+      throw new Error("No fetch implementation available \u2014 provide one in OsmtalkOptions.fetch");
+    }
     if (!opts.apiKey) throw new Error("apiKey is required");
   }
-  async request(method, path, body, extraHeaders, idempotencyKey) {
+  /**
+   * Combine the caller's AbortSignal with the SDK's per-request timeout
+   * signal so EITHER firing cancels the fetch. We can't use
+   * `AbortSignal.any` (Node 18 doesn't have it), so we wire it manually.
+   */
+  buildAbortSignal(externalSignal, timeoutMs) {
     const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    const onAbort = () => ctrl.abort();
+    if (externalSignal) {
+      if (externalSignal.aborted) ctrl.abort();
+      else externalSignal.addEventListener("abort", onAbort, { once: true });
+    }
+    const timer = timeoutMs > 0 ? setTimeout(() => ctrl.abort(new Error("Request timed out")), timeoutMs) : null;
+    return {
+      signal: ctrl.signal,
+      cancel: () => {
+        if (timer) clearTimeout(timer);
+        if (externalSignal) externalSignal.removeEventListener("abort", onAbort);
+      }
+    };
+  }
+  /** Parse the body once for both success and error paths. */
+  static async parseBody(res) {
+    const text = await res.text();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  /** How long to wait before the next retry. Honors Retry-After. */
+  retryDelay(attempt, res) {
+    if (res) {
+      const retryAfter = res.headers.get("retry-after");
+      if (retryAfter) {
+        const secs = Number(retryAfter);
+        if (Number.isFinite(secs) && secs >= 0) return Math.min(secs * 1e3, 3e4);
+        const when = Date.parse(retryAfter);
+        if (!Number.isNaN(when)) return Math.max(0, Math.min(when - Date.now(), 3e4));
+      }
+    }
+    const base = this.retryInitialDelayMs * 2 ** attempt;
+    const jitter = Math.floor(Math.random() * (base / 4));
+    return Math.min(base + jitter, 3e4);
+  }
+  async request(method, path, body, extraHeaders, idempotencyKey, options) {
+    const reqOrgId = options?.organizationId ?? this.organizationId;
+    const reqTimeout = options?.timeoutMs ?? this.timeoutMs;
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
+      "User-Agent": this.userAgent,
+      Accept: "application/json",
       ...body !== void 0 ? { "Content-Type": "application/json" } : {},
       ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {},
+      ...reqOrgId ? { "X-Organization-Id": reqOrgId } : {},
+      ...this.defaultHeaders,
       ...extraHeaders ?? {}
     };
-    let res;
-    try {
-      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
-        method,
-        headers,
-        body: body === void 0 ? void 0 : typeof body === "string" ? body : JSON.stringify(body),
-        signal: ctrl.signal
-      });
-    } finally {
-      clearTimeout(timer);
-    }
-    const text = await res.text();
-    const parsed = text ? (() => {
+    const serializedBody = body === void 0 ? void 0 : typeof body === "string" ? body : JSON.stringify(body);
+    const canRetryMutation = SAFE_METHODS.has(method.toUpperCase()) || Boolean(idempotencyKey);
+    const url = `${this.baseUrl}${path}`;
+    let lastErr;
+    let lastRes = null;
+    const maxAttempts = this.maxRetries + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const { signal, cancel } = this.buildAbortSignal(options?.signal, reqTimeout);
+      let res = null;
       try {
-        return JSON.parse(text);
-      } catch {
-        return text;
+        res = await this.fetchImpl(url, {
+          method,
+          headers,
+          body: serializedBody,
+          signal
+        });
+      } catch (err) {
+        lastErr = err;
+        cancel();
+        if (options?.signal?.aborted) throw err;
+        if (attempt < maxAttempts - 1 && canRetryMutation) {
+          await sleep(this.retryDelay(attempt, null));
+          continue;
+        }
+        throw err;
+      }
+      cancel();
+      if (res.ok) {
+        return await _HttpClient.parseBody(res);
       }
-    })() : null;
-    if (!res.ok) {
-      throw new OsmtalkError(res.status, parsed ?? { error: text });
+      const retryable = RETRYABLE_STATUSES.has(res.status);
+      if (retryable && canRetryMutation && attempt < maxAttempts - 1) {
+        try {
+          await res.text();
+        } catch {
+        }
+        await sleep(this.retryDelay(attempt, res));
+        lastRes = res;
+        continue;
+      }
+      const parsed = await _HttpClient.parseBody(res);
+      throw new OsmtalkError(
+        res.status,
+        parsed ?? { error: STATUS_TEXT[res.status] ?? `HTTP ${res.status}` },
+        attempt
+      );
+    }
+    if (lastRes) {
+      const parsed = await _HttpClient.parseBody(lastRes);
+      throw new OsmtalkError(
+        lastRes.status,
+        parsed ?? { error: STATUS_TEXT[lastRes.status] ?? "Server error" },
+        maxAttempts - 1
+      );
     }
-    return parsed;
+    throw lastErr ?? new Error("osmTalk SDK: request failed without details");
   }
 };
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var AgentsResource = class {
   constructor(http) {
     this.http = http;
@@ -111,20 +237,22 @@ var AgentsResource = class {
     );
   }
 };
+var TERMINAL_CALL_STATUSES = ["completed", "failed", "ended", "cancelled"];
 var CallsResource = class {
   constructor(http) {
     this.http = http;
   }
   http;
-  list() {
-    return this.http.request("GET", "/api/calls");
+  list(opts) {
+    return this.http.request("GET", "/api/calls", void 0, void 0, void 0, opts);
   }
-  get(id) {
-    return this.http.request("GET", `/api/calls/${id}`);
+  get(id, opts) {
+    return this.http.request("GET", `/api/calls/${id}`, void 0, void 0, void 0, opts);
   }
   /**
-   * Place an outbound call. Optionally pass `idempotencyKey` so retries
-   * within 24h return the same response instead of placing a duplicate call.
+   * Place an outbound call. Pass `idempotencyKey` so a retry within 24h
+   * returns the same response instead of placing a duplicate call —
+   * required if you want this call to be retried on transient failures.
    */
   outbound(input, opts) {
     return this.http.request(
@@ -132,14 +260,61 @@ var CallsResource = class {
       "/api/calls/outbound",
       input,
       void 0,
-      opts?.idempotencyKey
+      opts?.idempotencyKey,
+      opts
+    );
+  }
+  end(id, opts) {
+    return this.http.request(
+      "POST",
+      `/api/calls/${id}/end`,
+      void 0,
+      void 0,
+      opts?.idempotencyKey,
+      opts
     );
   }
-  end(id) {
-    return this.http.request("POST", `/api/calls/${id}/end`);
+  transfer(id, destination, summary, opts) {
+    return this.http.request(
+      "POST",
+      `/api/calls/${id}/transfer`,
+      { destination, summary },
+      void 0,
+      opts?.idempotencyKey,
+      opts
+    );
   }
-  transfer(id, destination, summary) {
-    return this.http.request("POST", `/api/calls/${id}/transfer`, { destination, summary });
+  /**
+   * Poll a call until it reaches a terminal status (`completed`,
+   * `failed`, `ended`, `cancelled`) and return the final record.
+   *
+   * Saves consumers from writing the same loop in every script. Use
+   * webhooks instead in production — this is fine for scripts, demos,
+   * and one-off jobs but consumes API quota on every poll.
+   *
+   * @param opts.pollIntervalMs - default 5s
+   * @param opts.timeoutMs      - default 30min (rejects with
+   *                              `OsmtalkError` 408 on timeout)
+   * @param opts.signal         - abort externally
+   */
+  async waitUntilEnded(id, opts) {
+    const pollInterval = Math.max(1e3, opts?.pollIntervalMs ?? 5e3);
+    const totalTimeout = opts?.timeoutMs ?? 30 * 60 * 1e3;
+    const deadline = Date.now() + totalTimeout;
+    const terminal = new Set(TERMINAL_CALL_STATUSES);
+    while (true) {
+      if (opts?.signal?.aborted) {
+        throw new OsmtalkError(0, { error: "Aborted by caller" });
+      }
+      const call = await this.get(id, { signal: opts?.signal });
+      if (terminal.has(call.status)) return call;
+      if (Date.now() >= deadline) {
+        throw new OsmtalkError(408, {
+          error: `waitUntilEnded: call ${id} did not reach a terminal state within ${totalTimeout}ms (last status: ${call.status})`
+        });
+      }
+      await sleep(Math.min(pollInterval, Math.max(0, deadline - Date.now())));
+    }
   }
 };
 var PlatformResource = class {
@@ -416,6 +591,8 @@ var index_default = Osmtalk;
 export {
   Osmtalk,
   OsmtalkError,
+  SDK_VERSION,
+  TERMINAL_CALL_STATUSES,
   index_default as default,
   verifyWebhookSignature,
   verifyWebhookSignatureAsync

package/package.json

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