@craftedxp/sdk-node 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,434 @@
+interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof fetch;
+    onRequest?: (info: {
+        method: string;
+        url: string;
+        status: number;
+        durationMs: number;
+        attempt: number;
+    }) => void;
+}
+interface HttpRequest {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    formData?: FormData;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+}
+declare const createHttpClient: (opts: HttpClientOptions) => {
+    request: <T>(req: HttpRequest) => Promise<T>;
+};
+type HttpClient = ReturnType<typeof createHttpClient>;
+
+type TtsProvider = 'pockettts' | 'cartesia' | 'fish-audio' | 'gemini';
+type SttProvider = 'deepgram';
+type LlmProvider = 'gemini' | 'openai' | 'anthropic';
+type EndpointingMode = 'smart' | 'simple';
+interface AgentVoice {
+    provider: TtsProvider;
+    voiceId?: string;
+    language?: string;
+}
+interface AgentTranscriber {
+    provider: SttProvider;
+    model: string;
+    language?: string;
+}
+interface AgentModel {
+    provider: LlmProvider;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    systemPromptOverride?: string;
+    apiKey?: string;
+    hasApiKey?: boolean;
+}
+interface AgentEndpointing {
+    silenceThresholdMs: number;
+    mode: EndpointingMode;
+}
+interface AgentHttpTool {
+    toolId?: string;
+    type: 'http';
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH';
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+type AgentTool = AgentHttpTool;
+interface AgentRecording {
+    enabled: boolean;
+    retentionDays?: number;
+}
+interface Agent {
+    agentId: string;
+    orgId: string;
+    name: string;
+    systemPrompt: string;
+    firstMessage: string;
+    voice: AgentVoice;
+    transcriber: AgentTranscriber;
+    model: AgentModel;
+    endpointing: AgentEndpointing;
+    maxDurationSeconds: number;
+    silenceTimeoutSeconds: number;
+    tools?: AgentTool[];
+    knowledgeBaseId?: string;
+    recording?: AgentRecording;
+    structuredDataSchema?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+interface AgentCreateInput {
+    name: string;
+    systemPrompt: string;
+    firstMessage?: string;
+    voice?: AgentVoice;
+    transcriber?: AgentTranscriber;
+    model?: AgentModel;
+    endpointing?: AgentEndpointing;
+    maxDurationSeconds?: number;
+    silenceTimeoutSeconds?: number;
+    tools?: AgentTool[];
+    knowledgeBaseId?: string;
+    recording?: AgentRecording;
+    structuredDataSchema?: Record<string, unknown>;
+}
+type AgentUpdateInput = Partial<AgentCreateInput>;
+type CallStatus = 'queued' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'no_answer';
+type EndReason = 'caller_hung_up' | 'agent_ended' | 'max_duration' | 'silence_timeout' | 'error';
+interface TranscriptTurn {
+    role: 'user' | 'assistant';
+    text: string;
+    startMs: number;
+    endMs: number;
+}
+interface CostBreakdown {
+    sttCents: number;
+    llmCents: number;
+    ttsCents: number;
+    infraCents: number;
+    totalCents: number;
+}
+interface RecordingMeta {
+    ready: boolean;
+    sampleRate: number;
+    callerGsUri?: string;
+    agentGsUri?: string;
+    mixedGsUri?: string;
+    callerBytes?: number;
+    agentBytes?: number;
+    mixError?: string;
+}
+interface CallRecord {
+    callId: string;
+    orgId: string;
+    agentId: string;
+    direction: 'inbound' | 'outbound';
+    from: string;
+    to: string;
+    status: CallStatus;
+    startedAt: number;
+    answeredAt?: number;
+    endedAt?: number;
+    durationSeconds?: number;
+    endReason?: EndReason;
+    transcript?: TranscriptTurn[];
+    summary?: string;
+    structuredData?: Record<string, unknown>;
+    recording?: RecordingMeta;
+    costBreakdown?: CostBreakdown;
+    errorMessage?: string;
+    metadata?: Record<string, string>;
+}
+interface CallListFilters {
+    agentId?: string;
+    status?: CallStatus;
+    limit?: number;
+}
+type CallSummary = Omit<CallRecord, 'transcript'> & {
+    turnCount?: number;
+};
+interface CallRecordingUrlResponse {
+    url: string;
+    ready: boolean;
+    artifact: 'mixed' | 'caller-raw';
+    mixError?: string;
+}
+interface KnowledgeBase {
+    kbId: string;
+    orgId: string;
+    name: string;
+    status: 'processing' | 'ready' | 'error';
+    fileCount: number;
+    chunkCount: number;
+    embeddingModel: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface KnowledgeBaseFile {
+    fileId: string;
+    kbId: string;
+    orgId: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    status: 'processing' | 'ready' | 'error';
+    chunkCount: number;
+    uploadedAt: number;
+    processedAt?: number;
+    errorMessage?: string;
+}
+interface LedgerEntry {
+    entryId: string;
+    orgId: string;
+    type: 'debit' | 'credit';
+    amountCents: number;
+    description: string;
+    callId?: string;
+    balanceAfterCents: number;
+    createdAt: number;
+    meta?: Record<string, string>;
+}
+interface CallTokenMintInput {
+    agentId: string;
+    ttlSeconds?: number;
+    /**
+     * Phase 12: arbitrary nested-JSON context. The server lowers this into
+     * the agent's effective system prompt at session open. Use when your
+     * per-call data doesn't fit `vars`'s flat primitive shape (action
+     * lists, structured user state, fresh data the agent should know).
+     * Wins over `vars` server-side when both are supplied.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Phase 12: opaque key/value pairs round-tripped on the `call.ended`
+     * webhook payload. NOT lowered into the system prompt — the LLM never
+     * sees these. Use for routing / billing / device identifiers your
+     * backend wants to correlate post-call (`deviceId`, `tier`,
+     * `experimentArm`). Capped at 1 KB total at mint validation; mint
+     * fails with HTTP 400 if you exceed it.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Stable end-user identifier baked into the token. Round-tripped to
+     * the server as `contactId` for cross-call memory. 1–128 chars.
+     */
+    contactId?: string;
+    /**
+     * Legacy flat key/value rendered into `{{placeholders}}` in the
+     * agent's static system prompt. Phase 12 superseded by `context` for
+     * new integrations. Kept for backward compat with 0.1.x SDK
+     * consumers.
+     */
+    vars?: Record<string, string | number | boolean>;
+    allowedOrigins?: string[];
+}
+interface CallTokenMintResult {
+    tokenId: string;
+    token: string;
+    agentId: string;
+    expiresAt: number;
+    allowedOrigins?: string[];
+}
+interface CallTokenSummary {
+    tokenId: string;
+    agentId: string;
+    createdAt: number;
+    expiresAt: number;
+    lastUsedAt?: number;
+    revoked: boolean;
+    allowedOrigins?: string[];
+}
+type PlatformEventName = 'call.started' | 'call.ended' | 'transcript.updated' | 'call.summary.ready' | 'tool.call.requested' | 'tool.call.completed' | 'tool.call.failed' | 'credits.low';
+interface WebhookConfig {
+    webhookId: string;
+    orgId: string;
+    agentId: string;
+    url: string;
+    events: PlatformEventName[];
+    active: boolean;
+    createdAt: number;
+    updatedAt: number;
+    secret?: string;
+}
+interface WebhookCreateInput {
+    url: string;
+    events: PlatformEventName[];
+    active?: boolean;
+}
+type WebhookUpdateInput = Partial<WebhookCreateInput>;
+interface WebhookDelivery {
+    deliveryId: string;
+    orgId: string;
+    agentId: string;
+    webhookId: string;
+    event: PlatformEventName;
+    callId?: string;
+    url: string;
+    status: 'pending' | 'delivered' | 'failed';
+    attempts: Array<{
+        attempt: number;
+        startedAt: number;
+        durationMs: number;
+        statusCode?: number;
+        errorMessage?: string;
+    }>;
+    createdAt: number;
+    completedAt?: number;
+    requestBodyPreview: string;
+    lastResponseBodyPreview?: string;
+}
+interface MeResponse {
+    orgId: string;
+    name: string;
+    email: string;
+    plan: 'free' | 'paid';
+    creditBalance: number;
+}
+
+declare const createMeResource: (http: HttpClient) => {
+    get: () => Promise<MeResponse>;
+};
+type MeResource = ReturnType<typeof createMeResource>;
+
+declare const createAgentWebhooksResource: (http: HttpClient, agentId: string) => {
+    create: (input: WebhookCreateInput) => Promise<WebhookConfig>;
+    list: () => Promise<WebhookConfig[]>;
+    get: (webhookId: string) => Promise<WebhookConfig>;
+    update: (webhookId: string, patch: WebhookUpdateInput) => Promise<WebhookConfig>;
+    delete: (webhookId: string) => Promise<void>;
+    test: (webhookId: string) => Promise<WebhookDelivery>;
+};
+type AgentWebhooksResource = ReturnType<typeof createAgentWebhooksResource>;
+
+declare const createAgentsResource: (http: HttpClient) => {
+    create: (input: AgentCreateInput) => Promise<Agent>;
+    list: () => Promise<Agent[]>;
+    listAll: () => AsyncIterable<Agent>;
+    get: (agentId: string) => Promise<Agent>;
+    update: (agentId: string, patch: AgentUpdateInput) => Promise<Agent>;
+    delete: (agentId: string) => Promise<void>;
+    webhooks: (agentId: string) => AgentWebhooksResource;
+};
+type AgentsResource = ReturnType<typeof createAgentsResource>;
+
+declare const createCallsResource: (http: HttpClient) => {
+    list: (filters?: CallListFilters) => Promise<CallSummary[]>;
+    listAll: (filters?: CallListFilters) => AsyncIterable<CallSummary>;
+    get: (callId: string) => Promise<CallRecord>;
+    transcript: (callId: string) => Promise<{
+        callId: string;
+        transcript: TranscriptTurn[];
+    }>;
+    recording: (callId: string) => Promise<CallRecordingUrlResponse>;
+};
+type CallsResource = ReturnType<typeof createCallsResource>;
+
+declare const createKnowledgeBasesResource: (http: HttpClient) => {
+    create: (name: string) => Promise<KnowledgeBase>;
+    list: () => Promise<KnowledgeBase[]>;
+    get: (kbId: string) => Promise<KnowledgeBase>;
+    delete: (kbId: string) => Promise<void>;
+    uploadFile: (kbId: string, source: {
+        path: string;
+        filename?: string;
+        mimeType?: string;
+    } | {
+        data: Buffer | Uint8Array;
+        filename: string;
+        mimeType?: string;
+    }) => Promise<KnowledgeBaseFile>;
+    listFiles: (kbId: string) => Promise<KnowledgeBaseFile[]>;
+    deleteFile: (kbId: string, fileId: string) => Promise<void>;
+};
+type KnowledgeBasesResource = ReturnType<typeof createKnowledgeBasesResource>;
+
+declare const createCreditsResource: (http: HttpClient) => {
+    getBalance: () => Promise<{
+        orgId: string;
+        balanceCents: number;
+    }>;
+    getLedger: (opts?: {
+        limit?: number;
+    }) => Promise<LedgerEntry[]>;
+    getLedgerAll: (opts?: {
+        limit?: number;
+    }) => AsyncIterable<LedgerEntry>;
+};
+type CreditsResource = ReturnType<typeof createCreditsResource>;
+
+declare const createCallTokensResource: (http: HttpClient) => {
+    mint: (input: CallTokenMintInput) => Promise<CallTokenMintResult>;
+    list: (opts?: {
+        includeRevoked?: boolean;
+        includeExpired?: boolean;
+        limit?: number;
+    }) => Promise<CallTokenSummary[]>;
+    revoke: (tokenId: string) => Promise<{
+        tokenId: string;
+        revoked: boolean;
+        alreadyRevoked?: boolean;
+    }>;
+};
+type CallTokensResource = ReturnType<typeof createCallTokensResource>;
+
+declare const createWebhooksResource: (http: HttpClient) => {
+    deliveries: (filters?: {
+        agentId?: string;
+        webhookId?: string;
+        callId?: string;
+        limit?: number;
+    }) => Promise<WebhookDelivery[]>;
+};
+type WebhooksResource = ReturnType<typeof createWebhooksResource>;
+
+interface PlatformClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    fetch?: HttpClientOptions['fetch'];
+    onRequest?: HttpClientOptions['onRequest'];
+}
+declare class PlatformClient {
+    readonly me: MeResource;
+    readonly agents: AgentsResource;
+    readonly calls: CallsResource;
+    readonly knowledgeBases: KnowledgeBasesResource;
+    readonly credits: CreditsResource;
+    readonly callTokens: CallTokensResource;
+    readonly webhooks: WebhooksResource;
+    constructor(options: PlatformClientOptions);
+}
+
+type ApiErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'bad_request' | 'conflict' | 'rate_limited' | 'payment_required' | 'internal_error' | 'unknown';
+declare class PlatformError extends Error {
+    readonly code: ApiErrorCode;
+    readonly status: number;
+    readonly field?: string;
+    readonly docsUrl?: string;
+    readonly body?: unknown;
+    constructor(params: {
+        code: ApiErrorCode;
+        message: string;
+        status: number;
+        field?: string;
+        docsUrl?: string;
+        body?: unknown;
+    });
+    toJSON(): Record<string, unknown>;
+}
+
+declare const verifyWebhookSignature: (rawBody: Buffer | string, signatureHeader: string, secret: string) => boolean;
+
+export { type Agent, type AgentCreateInput, type AgentEndpointing, type AgentHttpTool, type AgentModel, type AgentRecording, type AgentTool, type AgentTranscriber, type AgentUpdateInput, type AgentVoice, type AgentWebhooksResource, type AgentsResource, type ApiErrorCode, type CallListFilters, type CallRecord, type CallRecordingUrlResponse, type CallStatus, type CallSummary, type CallTokenMintInput, type CallTokenMintResult, type CallTokenSummary, type CallTokensResource, type CallsResource, type CostBreakdown, type CreditsResource, type EndReason, type EndpointingMode, type KnowledgeBase, type KnowledgeBaseFile, type KnowledgeBasesResource, type LedgerEntry, type LlmProvider, type MeResource, type MeResponse, PlatformClient, type PlatformClientOptions, PlatformError, type PlatformEventName, type RecordingMeta, type SttProvider, type TranscriptTurn, type TtsProvider, type WebhookConfig, type WebhookCreateInput, type WebhookDelivery, type WebhookUpdateInput, type WebhooksResource, verifyWebhookSignature };