@osmapi/osmtalk-sdk 0.2.0

package/README.md

@@ -0,0 +1,159 @@
+# @osmapi/osmtalk-sdk
+
+Official TypeScript / JavaScript SDK for the [osmTalk](https://osmtalk.com) voice AI platform.
+
+```bash
+npm install @osmapi/osmtalk-sdk
+# or: pnpm add @osmapi/osmtalk-sdk
+```
+
+## Quick start
+
+```ts
+import { Osmtalk } from "@osmapi/osmtalk-sdk";
+
+const client = new Osmtalk({ apiKey: process.env.OSMTALK_API_KEY! });
+
+// Place an outbound call with per-call personalization
+const call = await client.calls.outbound({
+  agentId: "agent_xxx",
+  phoneNumberId: "pn_xxx",
+  destination: "+919876543210",
+  dynamicVariables: {
+    first_name: "Arjun",
+    company: "Acme",
+    renewal_date: "May 28, 2026",
+  },
+});
+
+console.log("Call started:", call.callId);
+```
+
+## Resources
+
+| Resource | Operations |
+|---|---|
+| `client.agents` | `list`, `get`, `create`, `update`, `delete`, `connect`, `publishVersion`, `listVersions`, `getVersion`, `rollbackToVersion` |
+| `client.calls` | `list`, `get`, `outbound`, `end`, `transfer` |
+| `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` |
+
+## Examples
+
+### Run an outbound campaign
+
+```ts
+const camp = await client.campaigns.create({
+  name: "Q2 Renewals",
+  agentId: "agent_xxx",
+  phoneNumberId: "pn_xxx",
+  maxConcurrent: 5,
+  schedule: { timezone: "Asia/Kolkata", windowStart: "10:00", windowEnd: "18:00" },
+  retryPolicy: { maxAttempts: 3, backoffMinutes: 60, retryOn: ["no_answer", "busy"] },
+  webhookUrl: "https://your-crm/webhooks/osmtalk",
+});
+
+await client.campaigns.uploadLeadsCsv(camp.id, `
+phone,first_name,renewal_date
++919876543210,Arjun,2026-05-28
++919876543211,Meera,2026-06-02
+`.trim());
+
+await client.campaigns.start(camp.id);
+
+// Poll the report
+const report = await client.campaigns.report(camp.id);
+console.log(report.counts.byStatus);
+```
+
+### Publish a new agent version and A/B test
+
+```ts
+// Publish current draft as v2
+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 });
+```
+
+### Simulate before going live
+
+```ts
+const sim = await client.eval.simulate("agent_xxx", [
+  { role: "user", content: "Hi, who's calling?" },
+  { role: "user", content: "Sure, tell me more about renewal options" },
+]);
+
+for (const turn of sim.transcript) {
+  console.log(`${turn.role}: ${turn.content}`);
+}
+```
+
+### Handle the webhook in Node.js
+
+```ts
+import crypto from "node:crypto";
+import express from "express";
+
+const app = express();
+app.use(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 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);
+  }
+  res.json({ ok: true });
+});
+```
+
+## Error handling
+
+```ts
+import { Osmtalk, OsmtalkError } from "@osmapi/osmtalk-sdk";
+
+try {
+  await client.calls.outbound({ /* ... */ });
+} catch (err) {
+  if (err instanceof OsmtalkError) {
+    console.log("HTTP", err.status, err.body);
+  } 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 |
+
+## 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)
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,520 @@
+/**
+ * osmTalk TypeScript SDK
+ *
+ *   import { Osmtalk } from "@osmapi/osmtalk-sdk";
+ *   const client = new Osmtalk({ apiKey: process.env.OSMTALK_API_KEY! });
+ *   const call = await client.calls.outbound({
+ *     agentId: "agent_xxx",
+ *     phoneNumberId: "pn_xxx",
+ *     destination: "+919876543210",
+ *     dynamicVariables: { first_name: "Arjun" },
+ *   });
+ */
+interface OsmtalkOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    /** Custom fetch implementation (e.g. for testing). */
+    fetch?: typeof fetch;
+}
+interface DynamicVariables {
+    [key: string]: string | number | boolean;
+}
+interface AssistantOverride {
+    systemPrompt?: string;
+    welcomeMessage?: string;
+    llmProvider?: string;
+    llmModel?: string;
+    sttProvider?: string;
+    sttModel?: string;
+    sttLanguage?: string;
+    ttsProvider?: string;
+    ttsModel?: string;
+    ttsVoice?: string;
+    settings?: Record<string, unknown>;
+}
+interface CallStartRequest {
+    agentId: string;
+    phoneNumberId: string;
+    destination: string;
+    agentVersion?: number;
+    dynamicVariables?: DynamicVariables;
+    assistantOverride?: AssistantOverride;
+    metadata?: Record<string, unknown>;
+}
+interface CallRecord {
+    id: string;
+    agentId: string;
+    status: string;
+    channel: string;
+    startedAt: string;
+    endedAt?: string | null;
+    durationSeconds?: number | null;
+    recordingUrl?: string | null;
+    recordingMultiChannelUrl?: string | null;
+    transcript?: unknown;
+    analysis?: unknown;
+    analysisStatus?: string | null;
+    dynamicVariables?: DynamicVariables | null;
+    agentVersion?: number | null;
+    campaignId?: string | null;
+    campaignLeadId?: string | null;
+    disposition?: string | null;
+    metadata?: Record<string, unknown> | null;
+    [key: string]: unknown;
+}
+interface AgentRecord {
+    id: string;
+    name: string;
+    systemPrompt: string;
+    welcomeMessage?: string | null;
+    llmProvider: string;
+    llmModel: string;
+    sttProvider: string;
+    sttModel: string;
+    ttsProvider: string;
+    ttsModel: string;
+    ttsVoice?: string | null;
+    tools?: unknown;
+    settings?: unknown;
+    pronunciationDictionary?: unknown;
+    boostedKeywords?: unknown;
+    postCallAnalysis?: unknown;
+    currentVersion?: number | null;
+    isActive: boolean;
+    [key: string]: unknown;
+}
+interface CampaignRecord {
+    id: string;
+    name: string;
+    description?: string | null;
+    agentId: string;
+    agentVersion?: number | null;
+    phoneNumberId?: string | null;
+    status: "draft" | "scheduled" | "running" | "paused" | "completed" | "failed" | string;
+    totalLeads: number;
+    completedLeads: number;
+    qualifiedLeads: number;
+    failedLeads: number;
+    dncBlockedLeads: number;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    scheduledStartAt?: string | null;
+    schedule?: Record<string, unknown> | null;
+    retryPolicy?: Record<string, unknown> | null;
+    maxConcurrent?: number | null;
+    webhookUrl?: string | null;
+    [key: string]: unknown;
+}
+interface CampaignCreateRequest {
+    name: string;
+    agentId: string;
+    phoneNumberId?: string;
+    agentVersion?: number;
+    description?: string;
+    scheduledStartAt?: string;
+    maxConcurrent?: number;
+    schedule?: {
+        timezone?: string;
+        windowStart?: string;
+        windowEnd?: string;
+        weekdays?: number[];
+    };
+    retryPolicy?: {
+        maxAttempts?: number;
+        backoffMinutes?: number;
+        retryOn?: Array<"no_answer" | "busy" | "failed" | "voicemail">;
+    };
+    webhookUrl?: string;
+}
+interface LeadRow {
+    phoneNumber: string;
+    variables?: Record<string, string | number | boolean>;
+}
+interface OsmtalkErrorBody {
+    error?: string;
+    message?: string;
+    code?: string;
+    details?: unknown;
+    [key: string]: unknown;
+}
+declare class OsmtalkError extends Error {
+    readonly status: number;
+    readonly body: OsmtalkErrorBody;
+    constructor(status: number, body: OsmtalkErrorBody);
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: OsmtalkOptions);
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>, idempotencyKey?: string): Promise<T>;
+}
+declare class AgentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<AgentRecord[]>;
+    get(id: string): Promise<AgentRecord>;
+    create(input: Partial<AgentRecord>): Promise<AgentRecord>;
+    update(id: string, input: Partial<AgentRecord>): Promise<AgentRecord>;
+    delete(id: string): Promise<{
+        success: true;
+    }>;
+    publishVersion(id: string, opts?: {
+        label?: string;
+        notes?: string;
+    }): Promise<{
+        id: string;
+        version: number;
+        label?: string;
+        notes?: string;
+        snapshot: unknown;
+    }>;
+    listVersions(id: string): Promise<{
+        id: string;
+        version: number;
+        label?: string;
+        notes?: string;
+        snapshot: unknown;
+    }[]>;
+    getVersion(id: string, version: number): Promise<{
+        id: string;
+        version: number;
+        snapshot: unknown;
+    }>;
+    rollbackToVersion(id: string, version: number): Promise<{
+        success: true;
+        version: number;
+    }>;
+    connect(id: string, opts?: {
+        dynamicVariables?: DynamicVariables;
+        assistantOverride?: AssistantOverride;
+        agentVersion?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        roomName: string;
+        token: string;
+        livekitUrl: string;
+        callId: string;
+    }>;
+}
+declare class CallsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<CallRecord[]>;
+    get(id: string): Promise<CallRecord>;
+    /**
+     * Place an outbound call. Optionally pass `idempotencyKey` so retries
+     * within 24h return the same response instead of placing a duplicate call.
+     */
+    outbound(input: CallStartRequest, opts?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        callId: string;
+        roomName: string;
+    }>;
+    end(id: string): Promise<{
+        success: true;
+    }>;
+    transfer(id: string, destination: string, summary?: string): Promise<{
+        success: true;
+    }>;
+}
+declare class PlatformResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Live platform constants — USD-to-INR rate and the minimum charge per call. */
+    getRates(): Promise<{
+        usdToInr: number;
+        minCallChargeInr: number;
+    }>;
+    /** Catalog of available LLM/STT/TTS providers + models. */
+    listProviders(): Promise<{
+        llm: Record<string, unknown>;
+        stt: Record<string, unknown>;
+        tts: Record<string, unknown>;
+        languages: Array<{
+            id: string;
+            name: string;
+        }>;
+    }>;
+    /**
+     * Quality presets (Fast / Balanced / Premium) with live per-minute
+     * cost estimates derived from the same rate tables we bill with.
+     * `costEstimate.{low, typical, high}` are INR per minute and account
+     * for typical 250 / 900 / 2500 prompt-token usage patterns.
+     *
+     * @param channel "phone" (default) includes SIP minutes; "web" or
+     *                "chat" exclude SIP for cheaper web-only deployments.
+     */
+    getPresets(channel?: "phone" | "whatsapp_call" | "web" | "chat"): Promise<{
+        global: Record<string, PresetWithCost>;
+        india: Record<string, PresetWithCost>;
+    }>;
+    /**
+     * Per-provider health snapshot. Cached server-side for 60s.
+     * Use this before launching a call to detect "sometimes works"
+     * provider issues (key revoked, region outage, ToS not accepted).
+     */
+    getModelHealth(): Promise<Record<string, string | ProviderHealth>>;
+    /**
+     * Industry-organized agent templates (support, sales, healthcare,
+     * real-estate, etc.). When called with a valid session/API key, the
+     * response includes your org's custom-saved templates merged ahead
+     * of the built-ins; anonymous calls return built-ins only.
+     */
+    getTemplates(params?: {
+        category?: string;
+        q?: string;
+    }): Promise<{
+        categories: Array<{
+            id: string;
+            label: string;
+        }>;
+        templates: AgentTemplateResult[];
+    }>;
+    getTemplate(id: string): Promise<AgentTemplateResult>;
+    /** Save a custom template (org-scoped, requires auth). */
+    saveTemplate(data: {
+        label: string;
+        name: string;
+        tagline?: string;
+        category?: string;
+        recommendedPreset?: "fast" | "balanced" | "premium";
+        tags?: string[];
+        systemPrompt: string;
+        welcomeMessage?: string;
+    }): Promise<AgentTemplateResult>;
+    deleteTemplate(id: string): Promise<{
+        success: boolean;
+    }>;
+}
+interface AgentTemplateResult {
+    id: string;
+    label: string;
+    category: string;
+    name: string;
+    tagline: string;
+    recommendedPreset: "fast" | "balanced" | "premium";
+    tags: string[];
+    systemPrompt: string;
+    welcomeMessage: string;
+    /** True when this is a custom template saved by the caller's org. */
+    isCustom?: boolean;
+}
+interface PresetCostEstimate {
+    /** INR per minute — light usage (FAQ, short prompts) */
+    low: number;
+    /** INR per minute — most agents land here */
+    typical: number;
+    /** INR per minute — verbose, large system prompt */
+    high: number;
+    currency: "INR";
+    /** Component-level breakdown for the typical scenario */
+    typicalBreakdown: {
+        llm: number;
+        stt: number;
+        tts: number;
+        sip: number;
+        platform: number;
+        total: number;
+        currency: "INR";
+    };
+    /** Whether SIP minutes were included */
+    includesSip: boolean;
+}
+interface PresetWithCost {
+    id: "fast" | "balanced" | "premium";
+    label: string;
+    description: string;
+    latencyMs: string;
+    llmProvider: string;
+    llmModel: string;
+    sttProvider: string;
+    sttModel: string;
+    ttsProvider: string;
+    ttsModel: string;
+    ttsVoice?: string;
+    costEstimate: PresetCostEstimate;
+}
+interface ProviderHealth {
+    status: "ok" | "degraded" | "down" | "unconfigured";
+    latencyMs: number | null;
+    error?: string;
+}
+/**
+ * Verify an osmTalk webhook signature.
+ *
+ * Pass the RAW request body (string or Buffer) — NOT the parsed JSON —
+ * along with the value of the `X-OsmTalk-Signature` header and the
+ * shared secret you configured under Settings → Webhook. Uses a
+ * constant-time comparison so attackers can't time-probe the signature.
+ *
+ * @example
+ *   import { verifyWebhookSignature } from "@osmapi/osmtalk-sdk";
+ *
+ *   app.post("/webhooks/osmtalk", async (req, res) => {
+ *     const raw = await readRawBody(req); // do NOT use express.json() before this
+ *     const sig = req.headers["x-osmtalk-signature"];
+ *     if (!verifyWebhookSignature(raw, sig, process.env.OSMTALK_WEBHOOK_SECRET!)) {
+ *       return res.status(401).end();
+ *     }
+ *     const payload = JSON.parse(raw);
+ *     // ... handle payload
+ *     res.status(200).end();
+ *   });
+ *
+ * Works in Node 18+, Deno, Bun, and Cloudflare Workers (uses WebCrypto
+ * when `node:crypto` isn't available).
+ */
+declare function verifyWebhookSignature(rawBody: string | Uint8Array, signatureHeader: string | string[] | undefined, secret: string): boolean;
+/** WebCrypto-based async variant for Deno / Bun / Workers. */
+declare function verifyWebhookSignatureAsync(rawBody: string | Uint8Array, signatureHeader: string | string[] | undefined, secret: string): Promise<boolean>;
+declare class CampaignsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(opts?: {
+        status?: string;
+    }): Promise<CampaignRecord[]>;
+    get(id: string): Promise<CampaignRecord>;
+    create(input: CampaignCreateRequest): Promise<CampaignRecord>;
+    update(id: string, input: Partial<CampaignCreateRequest>): Promise<{
+        success: true;
+    }>;
+    delete(id: string): Promise<{
+        success: true;
+    }>;
+    start(id: string): Promise<{
+        success: true;
+        status: string;
+    }>;
+    pause(id: string): Promise<{
+        success: true;
+        status: string;
+    }>;
+    resume(id: string): Promise<{
+        success: true;
+        status: string;
+    }>;
+    stop(id: string): Promise<{
+        success: true;
+        status: string;
+    }>;
+    report(id: string): Promise<{
+        campaign: CampaignRecord;
+        counts: {
+            byStatus: Record<string, number>;
+            byDisposition: Record<string, number>;
+        };
+    }>;
+    uploadLeadsCsv(id: string, csv: string): Promise<{
+        inserted: number;
+        csvErrors: string[];
+    }>;
+    uploadLeads(id: string, leads: LeadRow[]): Promise<{
+        inserted: number;
+        csvErrors: string[];
+    }>;
+    listLeads(id: string, opts?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Record<string, unknown>[]>;
+}
+declare class DncResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<Record<string, unknown>[]>;
+    add(phoneNumber: string, opts?: {
+        reason?: string;
+        source?: string;
+        notes?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    bulkAdd(entries: Array<{
+        phoneNumber: string;
+        reason?: string;
+        source?: string;
+        notes?: string;
+    }>): Promise<{
+        inserted: number;
+    }>;
+    remove(id: string): Promise<{
+        success: true;
+    }>;
+}
+declare class EvalResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    simulate(agentId: string, mockTurns: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>, opts?: {
+        dynamicVariables?: Record<string, string>;
+        agentVersion?: number;
+    }): Promise<{
+        transcript: Array<{
+            role: string;
+            content: string;
+        }>;
+        durationMs: number;
+    }>;
+    createTestCase(agentId: string, input: {
+        name: string;
+        description?: string;
+        mockTurns: Array<{
+            role: "user" | "assistant";
+            content: string;
+        }>;
+        expectedOutcome?: string;
+        judgePrompt?: string;
+        dynamicVariables?: Record<string, string>;
+    }): Promise<{
+        id: string;
+    }>;
+    listTestCases(agentId: string): Promise<Record<string, unknown>[]>;
+    runTestCase(agentId: string, testCaseId: string): Promise<Record<string, unknown>>;
+    runAll(agentId: string): Promise<{
+        runs: string[];
+        passed: number;
+        failed: number;
+        total: number;
+    }>;
+    listRuns(agentId: string): Promise<Record<string, unknown>[]>;
+    getRun(runId: string): Promise<Record<string, unknown>>;
+}
+declare class SettingsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    get(): Promise<Record<string, unknown>>;
+    getStorage(): Promise<Record<string, unknown>>;
+    updateStorage(input: Record<string, unknown>): Promise<Record<string, unknown>>;
+    getWebhook(): Promise<{
+        defaultWebhookUrl?: string | null;
+        defaultWebhookSecret?: string | null;
+    }>;
+    updateWebhook(input: {
+        defaultWebhookUrl?: string | null;
+        defaultWebhookSecret?: string | null;
+    }): Promise<{
+        success: true;
+    }>;
+    getCompliance(): Promise<Record<string, unknown>>;
+    updateCompliance(input: Record<string, unknown>): Promise<{
+        success: true;
+    }>;
+}
+declare class Osmtalk {
+    readonly agents: AgentsResource;
+    readonly calls: CallsResource;
+    readonly campaigns: CampaignsResource;
+    readonly dnc: DncResource;
+    readonly eval: EvalResource;
+    readonly settings: SettingsResource;
+    readonly platform: PlatformResource;
+    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 };