@osmapi/osmtalk-sdk 0.2.0

package/dist/index.d.ts

@@ -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 };