@spekoai/sdk 0.4.3 → 0.5.2

package/src/lib/resources/calls.ts

@@ -0,0 +1,113 @@
+import type { HttpClient } from '../http.js';
+import type {
+  BlindTransferParams,
+  CallDetail,
+  CallEvent,
+  CallRecording,
+  CallReport,
+  CallTransfer,
+  CallTransferResponse,
+  CancelWarmTransferParams,
+  CompleteWarmTransferParams,
+  EndCallResult,
+  FinalizeCallReportParams,
+  FinalizeCallReportResult,
+  WarmTransferParams,
+  WebJoinParams,
+  WebJoinResult,
+} from '../types/index.js';
+
+export class Calls {
+  constructor(private readonly http: HttpClient) {}
+
+  get(callId: string): Promise<CallDetail> {
+    return this.http.get<CallDetail>(`/v1/calls/${encodeURIComponent(callId)}`);
+  }
+
+  events(callId: string): Promise<{ events: CallEvent[] }> {
+    return this.http.get<{ events: CallEvent[] }>(`/v1/calls/${encodeURIComponent(callId)}/events`);
+  }
+
+  report(callId: string): Promise<CallReport> {
+    return this.http.get<CallReport>(`/v1/calls/${encodeURIComponent(callId)}/report`);
+  }
+
+  finalizeReport(
+    callId: string,
+    params: FinalizeCallReportParams = {},
+  ): Promise<FinalizeCallReportResult> {
+    return this.http.post<FinalizeCallReportResult>(
+      `/v1/calls/${encodeURIComponent(callId)}/report/finalize`,
+      params,
+    );
+  }
+
+  recording(callId: string): Promise<CallRecording> {
+    return this.http.get<CallRecording>(`/v1/calls/${encodeURIComponent(callId)}/recording`);
+  }
+
+  /**
+   * Browser bridge-in: mint a short-lived token that joins THIS live call's
+   * room from a web client (pass `token`/`url` to `@spekoai/client`'s
+   * `VoiceConversation.create({ transportToken, transportUrl })`). Once the
+   * browser publishes audio the platform bridges it to the phone leg and
+   * mutes the agent; when the browser leaves, the agent resumes.
+   *
+   * Mint at click time — the token is short-TTL and a `409` means the call
+   * is no longer live. Concurrent/repeat joins are allowed (rejoin after a
+   * drop just calls this again).
+   */
+  webJoin(callId: string, params: WebJoinParams = {}): Promise<WebJoinResult> {
+    return this.http.post<WebJoinResult>(
+      `/v1/calls/${encodeURIComponent(callId)}/web-join`,
+      params,
+    );
+  }
+
+  /**
+   * End a live call now (kill switch): tears the room down, which hangs up
+   * every leg. Resolves with `status: 'ending'` once teardown is requested,
+   * or `status: 'already_ended'` if the call was over.
+   */
+  end(callId: string): Promise<EndCallResult> {
+    return this.http.post<EndCallResult>(`/v1/calls/${encodeURIComponent(callId)}/end`, {});
+  }
+
+  blindTransfer(callId: string, params: BlindTransferParams): Promise<CallTransfer> {
+    return this.http.post<CallTransfer>(
+      `/v1/calls/${encodeURIComponent(callId)}/transfers/blind`,
+      params,
+    );
+  }
+
+  warmTransfer(callId: string, params: WarmTransferParams): Promise<CallTransferResponse> {
+    return this.http.post<CallTransferResponse>(
+      `/v1/calls/${encodeURIComponent(callId)}/transfers/warm`,
+      params,
+    );
+  }
+
+  completeWarmTransfer(
+    callId: string,
+    transferId: string,
+    params: CompleteWarmTransferParams = {},
+  ): Promise<CallTransfer> {
+    return this.http.post<CallTransfer>(
+      `/v1/calls/${encodeURIComponent(callId)}/transfers/${encodeURIComponent(
+        transferId,
+      )}/complete`,
+      params,
+    );
+  }
+
+  cancelWarmTransfer(
+    callId: string,
+    transferId: string,
+    params: CancelWarmTransferParams = {},
+  ): Promise<CallTransferResponse> {
+    return this.http.post<CallTransferResponse>(
+      `/v1/calls/${encodeURIComponent(callId)}/transfers/${encodeURIComponent(transferId)}/cancel`,
+      params,
+    );
+  }
+}

package/src/lib/resources/complete.ts

@@ -0,0 +1,63 @@
+import { SpekoApiError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import type { CompleteParams, CompleteResult, CompleteStreamEvent } from '../types/index.js';
+
+export class Complete {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Run an LLM completion. The Speko router picks the best provider for your
+   * `(language, region, optimizeFor)` and falls over automatically.
+   *
+   * @example
+   * ```ts
+   * const { text, provider } = await speko.complete({
+   *   messages: [{ role: 'user', content: 'Hi!' }],
+   *   intent: { language: 'en' },
+   * });
+   * ```
+   */
+  async call(params: CompleteParams, abortSignal?: AbortSignal): Promise<CompleteResult> {
+    let done: CompleteResult | undefined;
+    for await (const event of this.stream(params, abortSignal)) {
+      if (event.type === 'done') {
+        done = {
+          text: event.text,
+          provider: event.provider,
+          model: event.model,
+          usage: event.usage,
+          failoverCount: event.failoverCount,
+          scoresRunId: event.scoresRunId,
+          ...(event.toolCalls && { toolCalls: event.toolCalls }),
+        };
+      } else if (event.type === 'error') {
+        throw new SpekoApiError(event.error, 200, event.code);
+      }
+    }
+    if (!done) {
+      throw new SpekoApiError('Complete stream ended without a done event', 200, 'STREAM_ENDED');
+    }
+    return done;
+  }
+
+  async *stream(
+    params: CompleteParams,
+    abortSignal?: AbortSignal,
+  ): AsyncIterableIterator<CompleteStreamEvent> {
+    const { sessionId, ...body } = params;
+    const trimmedSessionId = sessionId?.trim();
+    const headers = trimmedSessionId ? { 'x-session-id': trimmedSessionId } : undefined;
+    for await (const event of this.http.requestSse(
+      'POST',
+      '/v1/complete',
+      body,
+      abortSignal,
+      headers,
+    )) {
+      yield {
+        ...(event.data as Record<string, unknown>),
+        type: event.event,
+      } as CompleteStreamEvent;
+    }
+  }
+}

package/src/lib/resources/credits.ts

@@ -0,0 +1,41 @@
+import type { HttpClient } from '../http.js';
+import type {
+  CreditLedgerPage,
+  CreditLedgerQueryParams,
+  OrganizationBalance,
+} from '../types/index.js';
+
+/**
+ * Prepaid credit balance + append-only ledger. Balance is reported in USD.
+ */
+export class Credits {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * Current credit balance for the caller's organization.
+   *
+   * @example
+   * ```ts
+   * const { balanceUsd } = await speko.credits.getBalance();
+   * if (balanceUsd < 0.5) showLowBalanceBanner();
+   * ```
+   */
+  getBalance(): Promise<OrganizationBalance> {
+    return this.http.get<OrganizationBalance>('/v1/credits/balance');
+  }
+
+  /**
+   * Most-recent-first page of credit movements (grants, debits, topups,
+   * refunds, adjustments). `nextCursor` is the `createdAt` of the last
+   * entry on the current page — pass it back as `cursor` to fetch the
+   * next page; `null` means no more pages.
+   */
+  getLedger(params?: CreditLedgerQueryParams): Promise<CreditLedgerPage> {
+    const query = new URLSearchParams();
+    if (params?.limit) query.set('limit', String(params.limit));
+    if (params?.cursor) query.set('cursor', params.cursor);
+
+    const qs = query.toString();
+    return this.http.get<CreditLedgerPage>(`/v1/credits/ledger${qs ? `?${qs}` : ''}`);
+  }
+}

package/src/lib/resources/knowledge-bases.ts

@@ -0,0 +1,199 @@
+import { SpekoApiError } from '../errors.js';
+import type { HttpClient } from '../http.js';
+import type {
+  KnowledgeBaseCreateParams,
+  KnowledgeBaseDocumentCreateParams,
+  KnowledgeBaseDocumentCreateResult,
+  KnowledgeBaseDocumentPollOptions,
+  KnowledgeBaseDocumentRow,
+  KnowledgeBaseDocumentUploadParams,
+  KnowledgeBaseListParams,
+  KnowledgeBaseRow,
+} from '../types/index.js';
+
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_POLL_TIMEOUT_MS = 120_000;
+
+/**
+ * Per-agent knowledge bases. Each KB owns documents that get embedded
+ * into a PHALANX tenant so the agent can retrieve relevant chunks
+ * during a call. Every agent created via {@link Agents.create}
+ * auto-provisions a `Default` KB; additional KBs can be created
+ * explicitly with {@link KnowledgeBases.create}.
+ *
+ * @example
+ * ```ts
+ * const kb = await speko.knowledgeBases.create({
+ *   agentId: agent.id,
+ *   name: 'Product FAQ',
+ * });
+ *
+ * const doc = await speko.knowledgeBases.uploadDocument(kb.id, {
+ *   filename: 'faq.md',
+ *   contentType: 'text/markdown',
+ *   data: await readFile('faq.md'),
+ * });
+ *
+ * const ready = await speko.knowledgeBases.pollDocumentReady(kb.id, doc.id);
+ * ```
+ */
+export class KnowledgeBases {
+  constructor(private readonly http: HttpClient) {}
+
+  create(params: KnowledgeBaseCreateParams): Promise<KnowledgeBaseRow> {
+    return this.http.post<KnowledgeBaseRow>('/v1/knowledge-bases', params);
+  }
+
+  list(params: KnowledgeBaseListParams = {}): Promise<KnowledgeBaseRow[]> {
+    const query = new URLSearchParams();
+    if (params.agentId) query.set('agentId', params.agentId);
+    const qs = query.toString();
+    return this.http.get<KnowledgeBaseRow[]>(`/v1/knowledge-bases${qs ? `?${qs}` : ''}`);
+  }
+
+  get(kbId: string): Promise<KnowledgeBaseRow> {
+    return this.http.get<KnowledgeBaseRow>(`/v1/knowledge-bases/${encodeURIComponent(kbId)}`);
+  }
+
+  delete(kbId: string): Promise<{ deleted: boolean }> {
+    return this.http.delete<{ deleted: boolean }>(
+      `/v1/knowledge-bases/${encodeURIComponent(kbId)}`,
+    );
+  }
+
+  listDocuments(kbId: string): Promise<KnowledgeBaseDocumentRow[]> {
+    return this.http.get<KnowledgeBaseDocumentRow[]>(
+      `/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
+    );
+  }
+
+  getDocument(kbId: string, docId: string): Promise<KnowledgeBaseDocumentRow> {
+    return this.http.get<KnowledgeBaseDocumentRow>(
+      `/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}`,
+    );
+  }
+
+  createDocument(
+    kbId: string,
+    params: KnowledgeBaseDocumentCreateParams,
+  ): Promise<KnowledgeBaseDocumentCreateResult> {
+    return this.http.post<KnowledgeBaseDocumentCreateResult>(
+      `/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
+      params,
+    );
+  }
+
+  finalizeDocument(kbId: string, docId: string): Promise<KnowledgeBaseDocumentRow> {
+    return this.http.post<KnowledgeBaseDocumentRow>(
+      `/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}/finalize`,
+      {},
+    );
+  }
+
+  deleteDocument(kbId: string, docId: string): Promise<{ deleted: boolean }> {
+    return this.http.delete<{ deleted: boolean }>(
+      `/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}`,
+    );
+  }
+
+  /**
+   * Convenience wrapper: register a document, upload its bytes to the
+   * signed PUT URL the server mints, then call finalize. Returns the
+   * document with status flipped to `processing`. Call
+   * {@link pollDocumentReady} to wait for ingest completion.
+   *
+   * The server's signed upload URL expires 600 seconds after issuance,
+   * so do not hold the result of {@link createDocument} for long before
+   * uploading. This wrapper performs all three steps back-to-back.
+   */
+  async uploadDocument(
+    kbId: string,
+    params: KnowledgeBaseDocumentUploadParams,
+  ): Promise<KnowledgeBaseDocumentRow> {
+    const sizeBytes = byteLengthOf(params.data);
+
+    const { document, upload } = await this.createDocument(kbId, {
+      filename: params.filename,
+      contentType: params.contentType,
+      sizeBytes,
+      metadata: params.metadata,
+    });
+
+    const putResponse = await fetch(upload.url, {
+      method: upload.method,
+      headers: upload.headers,
+      body: toBodyInit(params.data),
+    });
+
+    if (!putResponse.ok) {
+      const text = await safeReadText(putResponse);
+      throw new SpekoApiError(
+        `Document upload failed: ${putResponse.status} ${text || putResponse.statusText}`,
+        putResponse.status,
+        'DOCUMENT_UPLOAD_FAILED',
+      );
+    }
+
+    return this.finalizeDocument(kbId, document.id);
+  }
+
+  /**
+   * Poll a document until it reaches `ready` or `failed` status, or the
+   * timeout elapses. Throws {@link SpekoApiError} on `failed` (with the
+   * server's `errorMessage`) or on timeout.
+   */
+  async pollDocumentReady(
+    kbId: string,
+    docId: string,
+    opts: KnowledgeBaseDocumentPollOptions = {},
+  ): Promise<KnowledgeBaseDocumentRow> {
+    const intervalMs = opts.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      const doc = await this.getDocument(kbId, docId);
+      if (doc.status === 'ready') return doc;
+      if (doc.status === 'failed') {
+        throw new SpekoApiError(
+          doc.errorMessage ?? 'Document ingest failed',
+          500,
+          'DOCUMENT_INGEST_FAILED',
+        );
+      }
+      await delay(intervalMs);
+    }
+
+    throw new SpekoApiError(
+      `Document ingest timed out after ${timeoutMs}ms`,
+      408,
+      'DOCUMENT_INGEST_TIMEOUT',
+    );
+  }
+}
+
+function byteLengthOf(data: ArrayBuffer | Uint8Array | Blob): number {
+  if (data instanceof Blob) return data.size;
+  if (data instanceof Uint8Array) return data.byteLength;
+  return data.byteLength;
+}
+
+function toBodyInit(data: ArrayBuffer | Uint8Array | Blob): Blob | ArrayBuffer {
+  if (data instanceof Blob) return data;
+  if (data instanceof Uint8Array) {
+    return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
+  }
+  return data;
+}
+
+async function safeReadText(r: Response): Promise<string> {
+  try {
+    return await r.text();
+  } catch {
+    return '';
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/lib/resources/phone-numbers.ts

@@ -0,0 +1,109 @@
+import type { HttpClient } from '../http.js';
+import type {
+  AvailablePhoneNumber,
+  PhoneNumberCreateParams,
+  PhoneNumberImportSipTrunkParams,
+  PhoneNumberKybDraftParams,
+  PhoneNumberKybOverview,
+  PhoneNumberKybSubmission,
+  PhoneNumberKybSubmitParams,
+  PhoneNumberRow,
+  PhoneNumberSearchParams,
+  PhoneNumberUpdateParams,
+} from '../types/index.js';
+
+/**
+ * Phone numbers Speko has provisioned as managed numbers or registered
+ * from your own SIP trunk. Each number can be used for outbound dialing
+ * and/or inbound, and carries an optional metadata template that's
+ * merged into the worker dispatch payload when the number is used.
+ *
+ * @example
+ * ```ts
+ * // List org's numbers
+ * const numbers = await speko.phoneNumbers.list();
+ *
+ * // Provision a new US local number
+ * const num = await speko.phoneNumbers.create({
+ *   e164: '+12015551234',
+ *   direction: 'both',
+ *   label: 'Sales line',
+ *   dispatchMetadataTemplate: {
+ *     intent: { language: 'en', optimizeFor: 'latency' },
+ *     systemPrompt: 'You are a helpful sales agent for Acme.',
+ *   },
+ * });
+ * ```
+ */
+export class PhoneNumbers {
+  constructor(private readonly http: HttpClient) {}
+
+  list(): Promise<PhoneNumberRow[]> {
+    return this.http.get<PhoneNumberRow[]>('/v1/phone-numbers');
+  }
+
+  /**
+   * Search the platform-managed pool for orderable US numbers. Filter by area code
+   * and/or locality. Results include cost so you can preview "$1 upfront +
+   * $1/month" before committing to {@link create}.
+   *
+   * @example
+   * ```ts
+   * const candidates = await speko.phoneNumbers.searchAvailable({ areaCode: '415' });
+   * console.log(candidates[0].friendlyName); // "+1 (415) 555-0123"
+   * ```
+   */
+  searchAvailable(params: PhoneNumberSearchParams = {}): Promise<AvailablePhoneNumber[]> {
+    const query = new URLSearchParams();
+    if (params.areaCode) query.set('areaCode', params.areaCode);
+    if (params.locality) query.set('locality', params.locality);
+    if (params.limit !== undefined) query.set('limit', String(params.limit));
+    const qs = query.toString();
+    return this.http.get<AvailablePhoneNumber[]>(
+      `/v1/phone-numbers/available${qs ? `?${qs}` : ''}`,
+    );
+  }
+
+  get(id: string): Promise<PhoneNumberRow> {
+    return this.http.get<PhoneNumberRow>(`/v1/phone-numbers/${encodeURIComponent(id)}`);
+  }
+
+  create(params: PhoneNumberCreateParams): Promise<PhoneNumberRow> {
+    return this.http.post<PhoneNumberRow>('/v1/phone-numbers', params);
+  }
+
+  importSipTrunk(params: PhoneNumberImportSipTrunkParams): Promise<PhoneNumberRow> {
+    return this.http.post<PhoneNumberRow>('/v1/phone-numbers/import', params);
+  }
+
+  update(id: string, params: PhoneNumberUpdateParams): Promise<PhoneNumberRow> {
+    return this.http.patch<PhoneNumberRow>(`/v1/phone-numbers/${encodeURIComponent(id)}`, params);
+  }
+
+  delete(id: string): Promise<{ released: boolean }> {
+    return this.http.delete<{ released: boolean }>(`/v1/phone-numbers/${encodeURIComponent(id)}`);
+  }
+
+  /**
+   * Read business verification state used to gate managed phone-number purchases.
+   * Includes the latest submission plus any SMS 10DLC-derived prefill.
+   */
+  getKyb(): Promise<PhoneNumberKybOverview> {
+    return this.http.get<PhoneNumberKybOverview>('/v1/phone-numbers/kyb');
+  }
+
+  /**
+   * Save a draft business verification submission without sending it for review.
+   */
+  saveKybDraft(params: PhoneNumberKybDraftParams): Promise<PhoneNumberKybSubmission> {
+    return this.http.put<PhoneNumberKybSubmission>('/v1/phone-numbers/kyb/draft', params);
+  }
+
+  /**
+   * Submit a business declaration for asynchronous review. A current minimal
+   * declaration enables purchasing immediately; the legacy full profile remains accepted.
+   */
+  submitKyb(params: PhoneNumberKybSubmitParams): Promise<PhoneNumberKybSubmission> {
+    return this.http.post<PhoneNumberKybSubmission>('/v1/phone-numbers/kyb/submit', params);
+  }
+}

package/src/lib/resources/realtime-globals.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Minimal ambient declarations for the WebSocket global. The SDK targets
+ * browsers primarily (audio capture needs a MediaStream), but lib.dom.d.ts
+ * conflicts with our fetch-with-Uint8Array body calls in http.ts. Declaring
+ * just the subset we need sidesteps the conflict.
+ */
+
+interface WebSocketMessageEvent<T = unknown> {
+  readonly data: T;
+}
+
+interface WebSocketCloseEvent {
+  readonly code: number;
+  readonly reason: string;
+}
+
+interface WebSocket {
+  readonly readyState: 0 | 1 | 2 | 3;
+  binaryType: 'arraybuffer' | 'blob';
+  send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: 'message', listener: (evt: WebSocketMessageEvent) => void): void;
+  addEventListener(type: 'close', listener: (evt: WebSocketCloseEvent) => void): void;
+  addEventListener(type: 'open' | 'error', listener: () => void): void;
+}
+
+interface WebSocketConstructor {
+  new (url: string, protocols?: string | string[]): WebSocket;
+}
+
+declare const WebSocket: WebSocketConstructor;