@osmapi/osmtalk-sdk 0.3.0 → 0.3.1

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,25 @@ 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`, `get`, `outbound`, `end`, `transfer`, **`waitUntilEnded`** |
 | `client.campaigns` | `list`, `get`, `create`, `update`, `delete`, `start`, `pause`, `resume`, `stop`, `report`, `uploadLeadsCsv`, `uploadLeads`, `listLeads` |
 | `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.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 +86,45 @@ const report = await client.campaigns.report(camp.id);
 console.log(report.counts.byStatus);
 ```
 
+### 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 +132,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 +153,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 +211,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,12 @@
  *     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.3.1";
 interface OsmtalkOptions {
     apiKey: string;
     baseUrl?: string;
@@ -253,7 +257,15 @@ 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;

package/dist/index.d.ts

@@ -10,8 +10,12 @@
  *     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.3.1";
 interface OsmtalkOptions {
     apiKey: string;
     baseUrl?: string;
@@ -253,7 +257,15 @@ 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;

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.3.1";
 var OsmtalkError = class extends Error {
   status;
   body;

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.3.1";
 var OsmtalkError = class extends Error {
   status;
   body;

package/package.json

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