@spekoai/sdk 0.5.1 → 0.5.2

package/src/lib/http.ts

@@ -0,0 +1,442 @@
+import { SpekoApiError, SpekoAuthError, SpekoRateLimitError } from './errors.js';
+
+export interface HttpClientOptions {
+  baseUrl: string;
+  apiKey: string;
+  timeout: number;
+}
+
+const USER_AGENT = '@spekoai/sdk/0.5.2';
+
+export class HttpClient {
+  private readonly baseUrl: string;
+  private readonly authHeader: string;
+  private readonly jsonHeaders: Record<string, string>;
+  private readonly timeout: number;
+
+  constructor(options: HttpClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, '');
+    this.authHeader = `Bearer ${options.apiKey}`;
+    this.jsonHeaders = {
+      Authorization: this.authHeader,
+      'Content-Type': 'application/json',
+      'User-Agent': USER_AGENT,
+    };
+    this.timeout = options.timeout;
+  }
+
+  async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    externalSignal?: AbortSignal,
+    extraHeaders?: Record<string, string>,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const { signal, cleanup } = this.buildSignal(externalSignal);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: { ...this.jsonHeaders, ...extraHeaders },
+        body: body ? JSON.stringify(body) : undefined,
+        signal,
+      });
+
+      if (!response.ok) {
+        await this.handleError(response);
+      }
+
+      if (response.status === 204) return undefined as T;
+      return (await response.json()) as T;
+    } finally {
+      cleanup();
+    }
+  }
+
+  async get<T>(path: string, externalSignal?: AbortSignal): Promise<T> {
+    return this.request<T>('GET', path, undefined, externalSignal);
+  }
+
+  async post<T>(
+    path: string,
+    body: unknown,
+    externalSignal?: AbortSignal,
+    extraHeaders?: Record<string, string>,
+  ): Promise<T> {
+    return this.request<T>('POST', path, body, externalSignal, extraHeaders);
+  }
+
+  async put<T>(path: string, body: unknown, externalSignal?: AbortSignal): Promise<T> {
+    return this.request<T>('PUT', path, body, externalSignal);
+  }
+
+  async delete<T>(path: string, externalSignal?: AbortSignal): Promise<T> {
+    return this.request<T>('DELETE', path, undefined, externalSignal);
+  }
+
+  async patch<T>(path: string, body: unknown, externalSignal?: AbortSignal): Promise<T> {
+    return this.request<T>('PATCH', path, body, externalSignal);
+  }
+
+  /**
+   * Send raw bytes as the request body and parse a JSON response.
+   * Used by `speko.transcribe()` to upload audio and receive a transcript.
+   */
+  async requestRaw<T>(
+    method: string,
+    path: string,
+    bodyBytes: Uint8Array,
+    extraHeaders: Record<string, string>,
+    externalSignal?: AbortSignal,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const { signal, cleanup } = this.buildSignal(externalSignal);
+
+    try {
+      const headers: Record<string, string> = {
+        Authorization: this.authHeader,
+        'User-Agent': USER_AGENT,
+        ...extraHeaders,
+      };
+
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: bodyBytes as unknown as string,
+        signal,
+      });
+
+      if (!response.ok) {
+        await this.handleError(response);
+      }
+
+      return (await response.json()) as T;
+    } finally {
+      cleanup();
+    }
+  }
+
+  /**
+   * Send JSON and receive a binary response (e.g. synthesized audio).
+   * Returns the raw bytes plus the response headers so callers can read
+   * `Content-Type`, `X-Speko-Provider`, etc.
+   */
+  async requestBinary(
+    method: string,
+    path: string,
+    body: unknown,
+    externalSignal?: AbortSignal,
+  ): Promise<{ bytes: Uint8Array; headers: Record<string, string> }> {
+    const url = `${this.baseUrl}${path}`;
+    const { signal, cleanup } = this.buildSignal(externalSignal);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: this.jsonHeaders,
+        body: body ? JSON.stringify(body) : undefined,
+        signal,
+      });
+
+      if (!response.ok) {
+        await this.handleError(response);
+      }
+
+      const buffer = await response.arrayBuffer();
+      const headers: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        headers[key] = value;
+      });
+
+      return { bytes: new Uint8Array(buffer), headers };
+    } finally {
+      cleanup();
+    }
+  }
+
+  async *requestSse(
+    method: string,
+    path: string,
+    body: unknown,
+    externalSignal?: AbortSignal,
+    extraHeaders?: Record<string, string>,
+    /**
+     * Per-request override of the client timeout. Long-lived SSE responses
+     * (session observation) outlive the default 30 s, which would abort them
+     * mid-stream.
+     */
+    timeoutMs?: number,
+  ): AsyncIterableIterator<{ event: string; id?: string; data: unknown }> {
+    const url = `${this.baseUrl}${path}`;
+    const { signal, cleanup } = this.buildSignal(externalSignal, timeoutMs);
+    let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: { ...this.jsonHeaders, ...extraHeaders },
+        body: body ? JSON.stringify(body) : undefined,
+        signal,
+      });
+
+      if (!response.ok) {
+        await this.handleError(response);
+      }
+
+      if (!response.body) {
+        throw new SpekoApiError('Response body is empty', response.status, 'EMPTY_BODY');
+      }
+
+      reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const events = drainSseEvents(buffer);
+        buffer = events.remainder;
+        for (const event of events.items) {
+          yield event;
+        }
+      }
+
+      buffer += decoder.decode();
+      const events = drainSseEvents(buffer + '\n\n');
+      for (const event of events.items) {
+        yield event;
+      }
+    } finally {
+      reader?.releaseLock();
+      cleanup();
+    }
+  }
+
+  async requestRawSse(
+    method: string,
+    path: string,
+    bodyBytes: Uint8Array,
+    extraHeaders: Record<string, string>,
+    externalSignal?: AbortSignal,
+  ): Promise<AsyncIterableIterator<{ event: string; id?: string; data: unknown }>> {
+    const url = `${this.baseUrl}${path}`;
+    const { signal, cleanup } = this.buildSignal(externalSignal);
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: this.authHeader,
+        'User-Agent': USER_AGENT,
+        ...extraHeaders,
+      },
+      body: bodyBytes as unknown as string,
+      signal,
+    });
+
+    if (!response.ok) {
+      cleanup();
+      await this.handleError(response);
+    }
+
+    if (!response.body) {
+      cleanup();
+      throw new SpekoApiError('Response body is empty', response.status, 'EMPTY_BODY');
+    }
+
+    return this.readSseBody(response.body, cleanup);
+  }
+
+  async requestBinaryStream(
+    method: string,
+    path: string,
+    body: unknown,
+    externalSignal?: AbortSignal,
+    extraHeaders?: Record<string, string>,
+  ): Promise<{ chunks: AsyncIterableIterator<Uint8Array>; headers: Record<string, string> }> {
+    const url = `${this.baseUrl}${path}`;
+    const { signal, cleanup } = this.buildSignal(externalSignal);
+
+    const response = await fetch(url, {
+      method,
+      headers: { ...this.jsonHeaders, ...extraHeaders },
+      body: body ? JSON.stringify(body) : undefined,
+      signal,
+    });
+
+    if (!response.ok) {
+      cleanup();
+      await this.handleError(response);
+    }
+
+    if (!response.body) {
+      cleanup();
+      throw new SpekoApiError('Response body is empty', response.status, 'EMPTY_BODY');
+    }
+
+    const headers: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    return {
+      headers,
+      chunks: this.readBinaryBody(response.body, cleanup),
+    };
+  }
+
+  private async *readSseBody(
+    body: ReadableStream<Uint8Array>,
+    cleanup: () => void,
+  ): AsyncIterableIterator<{ event: string; id?: string; data: unknown }> {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const events = drainSseEvents(buffer);
+        buffer = events.remainder;
+        for (const event of events.items) {
+          yield event;
+        }
+      }
+
+      buffer += decoder.decode();
+      const events = drainSseEvents(buffer + '\n\n');
+      for (const event of events.items) {
+        yield event;
+      }
+    } finally {
+      reader.releaseLock();
+      cleanup();
+    }
+  }
+
+  private async *readBinaryBody(
+    body: ReadableStream<Uint8Array>,
+    cleanup: () => void,
+  ): AsyncIterableIterator<Uint8Array> {
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        yield value;
+      }
+    } finally {
+      reader.releaseLock();
+      cleanup();
+    }
+  }
+
+  /**
+   * Compose the internal timeout signal with an optional external signal so
+   * that callers can cancel in-flight requests (e.g. LiveKit Agents tearing
+   * down a session) while still enforcing the client's configured timeout.
+   */
+  private buildSignal(
+    externalSignal?: AbortSignal,
+    timeoutMs?: number,
+  ): {
+    signal: AbortSignal;
+    cleanup: () => void;
+  } {
+    const controller = new AbortController();
+    const effectiveTimeout = timeoutMs ?? this.timeout;
+    const timer =
+      effectiveTimeout > 0 ? setTimeout(() => controller.abort(), effectiveTimeout) : null;
+
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        controller.abort(externalSignal.reason);
+      } else {
+        const onAbort = () => controller.abort(externalSignal.reason);
+        externalSignal.addEventListener('abort', onAbort, { once: true });
+        return {
+          signal: controller.signal,
+          cleanup: () => {
+            if (timer) clearTimeout(timer);
+            externalSignal.removeEventListener('abort', onAbort);
+          },
+        };
+      }
+    }
+
+    return {
+      signal: controller.signal,
+      cleanup: () => {
+        if (timer) clearTimeout(timer);
+      },
+    };
+  }
+
+  private async handleError(response: Response): Promise<never> {
+    const text = await response.text();
+    let message: string;
+    let code: string;
+
+    try {
+      const json = JSON.parse(text) as { error?: string; code?: string };
+      message = json.error ?? text;
+      code = json.code ?? 'UNKNOWN';
+    } catch {
+      message = text || response.statusText;
+      code = 'UNKNOWN';
+    }
+
+    if (response.status === 401) {
+      throw new SpekoAuthError(message);
+    }
+
+    if (response.status === 429) {
+      const retryAfter = response.headers.get('Retry-After');
+      throw new SpekoRateLimitError(message, retryAfter ? parseInt(retryAfter, 10) : null);
+    }
+
+    throw new SpekoApiError(message, response.status, code);
+  }
+}
+
+function drainSseEvents(buffer: string): {
+  items: Array<{ event: string; id?: string; data: unknown }>;
+  remainder: string;
+} {
+  const items: Array<{ event: string; id?: string; data: unknown }> = [];
+  let cursor = 0;
+
+  while (true) {
+    const next = buffer.indexOf('\n\n', cursor);
+    if (next === -1) break;
+    const block = buffer.slice(cursor, next);
+    cursor = next + 2;
+    if (!block.trim()) continue;
+
+    let event = 'message';
+    let id: string | undefined;
+    const dataLines: string[] = [];
+    for (const line of block.split(/\r?\n/)) {
+      if (line.startsWith('event:')) {
+        event = line.slice('event:'.length).trim();
+      } else if (line.startsWith('id:')) {
+        id = line.slice('id:'.length).trim();
+      } else if (line.startsWith('data:')) {
+        dataLines.push(line.slice('data:'.length).trimStart());
+      }
+    }
+    const rawData = dataLines.join('\n');
+    let data: unknown = rawData;
+    try {
+      data = JSON.parse(rawData);
+    } catch {
+      // Keep non-JSON SSE payloads as strings.
+    }
+    items.push({ event, ...(id ? { id } : {}), data });
+  }
+
+  return { items, remainder: buffer.slice(cursor) };
+}

package/src/lib/resources/agents.ts

@@ -0,0 +1,211 @@
+import type { HttpClient } from '../http.js';
+import type {
+  AgentCallListPage,
+  AgentCallListParams,
+  AgentCreateParams,
+  AgentRow,
+  AgentToolCreateParams,
+  AgentToolRow,
+  AgentToolUpdateParams,
+  AgentUpdateParams,
+  ChatTool,
+  PhoneNumberRow,
+} from '../types/index.js';
+
+/**
+ * Per-org agent definitions — the system prompt, voice, intent, and
+ * routing constraints used when this agent answers (or places) a call.
+ *
+ * Every agent created via {@link create} auto-provisions a `Default`
+ * knowledge base, so callers can upload documents through
+ * {@link Speko.knowledgeBases} without an extra setup step.
+ *
+ * @example
+ * ```ts
+ * const agent = await speko.agents.create({
+ *   name: 'Support Bot',
+ *   systemPrompt: 'You are a helpful support agent for Acme.',
+ *   voice: 'sophia',
+ *   intent: { language: 'en', optimizeFor: 'latency' },
+ * });
+ *
+ * await speko.agents.attachPhoneNumber(agent.id, num.id);
+ * ```
+ */
+export class Agents {
+  readonly tools: AgentTools;
+
+  constructor(private readonly http: HttpClient) {
+    this.tools = new AgentTools(http);
+  }
+
+  list(): Promise<AgentRow[]> {
+    return this.http.get<AgentRow[]>('/v1/agents');
+  }
+
+  create(params: AgentCreateParams): Promise<AgentRow> {
+    return this.http.post<AgentRow>('/v1/agents', params);
+  }
+
+  get(agentId: string): Promise<AgentRow> {
+    return this.http.get<AgentRow>(`/v1/agents/${encodeURIComponent(agentId)}`);
+  }
+
+  update(agentId: string, params: AgentUpdateParams): Promise<AgentRow> {
+    return this.http.patch<AgentRow>(`/v1/agents/${encodeURIComponent(agentId)}`, params);
+  }
+
+  delete(agentId: string): Promise<{ deleted: boolean }> {
+    return this.http.delete<{ deleted: boolean }>(`/v1/agents/${encodeURIComponent(agentId)}`);
+  }
+
+  /**
+   * Bind a phone number to this agent so inbound calls hydrate the
+   * agent's pipeline config from the agent row. Internally calls
+   * `PATCH /v1/phone-numbers/:id` with `{ agentId }`.
+   */
+  attachPhoneNumber(agentId: string, phoneNumberId: string): Promise<PhoneNumberRow> {
+    return this.http.patch<PhoneNumberRow>(
+      `/v1/phone-numbers/${encodeURIComponent(phoneNumberId)}`,
+      { agentId },
+    );
+  }
+
+  /**
+   * Unlink a phone number from any agent. Inbound calls fall back to
+   * the number's `dispatchMetadataTemplate` (or fail if neither is
+   * configured). Internally calls `PATCH /v1/phone-numbers/:id` with
+   * `{ agentId: null }`.
+   */
+  detachPhoneNumber(phoneNumberId: string): Promise<PhoneNumberRow> {
+    return this.http.patch<PhoneNumberRow>(
+      `/v1/phone-numbers/${encodeURIComponent(phoneNumberId)}`,
+      { agentId: null },
+    );
+  }
+
+  /**
+   * List recent calls for an agent. Use `next_cursor` from the returned page
+   * as `cursor` to page backward in time.
+   */
+  listCalls(agentId: string, params: AgentCallListParams = {}): Promise<AgentCallListPage> {
+    const query = new URLSearchParams();
+    if (params.limit !== undefined) query.set('limit', String(params.limit));
+    if (params.cursor) query.set('cursor', params.cursor);
+    if (params.since) query.set('since', params.since);
+    const suffix = query.toString() ? `?${query}` : '';
+    return this.http.get<AgentCallListPage>(
+      `/v1/agents/${encodeURIComponent(agentId)}/calls${suffix}`,
+    );
+  }
+}
+
+/**
+ * Per-agent tool definitions exposed to the LLM mid-call. Four execution
+ * modes: `inline` (caller runs the tool), `webhook` (Speko POSTs to your URL
+ * with a Standard-Webhooks signature), `builtin` (Speko-managed tools like
+ * `search_knowledge_base`, `transfer_call`, `end_call`), and `integration`
+ * (an org-installed Speko app action such as Google Calendar or Slack).
+ *
+ * Webhook secrets are encrypted server-side at creation; the returned
+ * row carries a `secretRef` pointer instead of the plaintext.
+ *
+ * Every method accepts an optional trailing `AbortSignal` to cancel the
+ * in-flight request — useful when a calling framework tears down a session
+ * mid-call.
+ */
+export class AgentTools {
+  constructor(private readonly http: HttpClient) {}
+
+  /**
+   * @param opts.available When true, the server returns only tools the agent
+   *   can actually run right now — integration tools whose backing installation
+   *   is disconnected/missing are omitted. Use this on the runtime path so the
+   *   model is never offered a tool that would fail.
+   */
+  list(
+    agentId: string,
+    abortSignal?: AbortSignal,
+    opts?: { available?: boolean },
+  ): Promise<AgentToolRow[]> {
+    const query = opts?.available ? '?available=1' : '';
+    return this.http.get<AgentToolRow[]>(
+      `/v1/agents/${encodeURIComponent(agentId)}/tools${query}`,
+      abortSignal,
+    );
+  }
+
+  create(
+    agentId: string,
+    params: AgentToolCreateParams,
+    abortSignal?: AbortSignal,
+  ): Promise<AgentToolRow> {
+    return this.http.post<AgentToolRow>(
+      `/v1/agents/${encodeURIComponent(agentId)}/tools`,
+      params,
+      abortSignal,
+    );
+  }
+
+  get(agentId: string, toolId: string, abortSignal?: AbortSignal): Promise<AgentToolRow> {
+    return this.http.get<AgentToolRow>(
+      `/v1/agents/${encodeURIComponent(agentId)}/tools/${encodeURIComponent(toolId)}`,
+      abortSignal,
+    );
+  }
+
+  update(
+    agentId: string,
+    toolId: string,
+    params: AgentToolUpdateParams,
+    abortSignal?: AbortSignal,
+  ): Promise<AgentToolRow> {
+    return this.http.patch<AgentToolRow>(
+      `/v1/agents/${encodeURIComponent(agentId)}/tools/${encodeURIComponent(toolId)}`,
+      params,
+      abortSignal,
+    );
+  }
+
+  delete(
+    agentId: string,
+    toolId: string,
+    abortSignal?: AbortSignal,
+  ): Promise<{ deleted: boolean }> {
+    return this.http.delete<{ deleted: boolean }>(
+      `/v1/agents/${encodeURIComponent(agentId)}/tools/${encodeURIComponent(toolId)}`,
+      abortSignal,
+    );
+  }
+
+  /**
+   * Fetch this agent's registered tools and convert them into the
+   * {@link ChatTool}[] shape that {@link Speko.complete} accepts. Handles all
+   * four source kinds (`inline`, `webhook`, `builtin`, `integration`) — load
+   * once and pass the result straight to `speko.complete({ tools })`.
+   */
+  async listChatTools(
+    agentId: string,
+    abortSignal?: AbortSignal,
+    opts?: { available?: boolean },
+  ): Promise<ChatTool[]> {
+    const rows = await this.list(agentId, abortSignal, opts);
+    return rows.map(toChatTool);
+  }
+}
+
+/**
+ * Convert a serialized {@link AgentToolRow} into a {@link ChatTool}. The row's
+ * `source` is structurally identical to `ChatToolSource` for every kind, so the
+ * mapping is a direct passthrough; `executionMode` is derived from `source.kind`.
+ */
+function toChatTool(row: AgentToolRow): ChatTool {
+  return {
+    name: row.name,
+    description: row.description,
+    parameters: row.parameters,
+    executionMode: row.source.kind,
+    source: row.source,
+    ...(row.preToolSpeech !== undefined && { preToolSpeech: row.preToolSpeech }),
+  };
+}

package/src/lib/resources/callbacks.ts

@@ -0,0 +1,40 @@
+import type { HttpClient } from '../http.js';
+import type {
+  CancelScheduledCallbackParams,
+  ScheduledCallback,
+  ScheduledCallbacksListParams,
+} from '../types/index.js';
+
+export class Callbacks {
+  constructor(private readonly http: HttpClient) {}
+
+  list(params: ScheduledCallbacksListParams = {}): Promise<{ callbacks: ScheduledCallback[] }> {
+    const query = new URLSearchParams();
+    if (params.status) query.set('status', params.status);
+    if (params.sourceSessionId) query.set('source_session_id', params.sourceSessionId);
+    if (params.limit !== undefined) query.set('limit', String(params.limit));
+    const suffix = query.toString() ? `?${query}` : '';
+    return this.http.get<{ callbacks: ScheduledCallback[] }>(`/v1/callbacks${suffix}`);
+  }
+
+  get(callbackId: string): Promise<ScheduledCallback> {
+    return this.http.get<ScheduledCallback>(`/v1/callbacks/${encodeURIComponent(callbackId)}`);
+  }
+
+  cancel(
+    callbackId: string,
+    params: CancelScheduledCallbackParams = {},
+  ): Promise<ScheduledCallback> {
+    return this.http.post<ScheduledCallback>(
+      `/v1/callbacks/${encodeURIComponent(callbackId)}/cancel`,
+      params,
+    );
+  }
+
+  dispatch(callbackId: string): Promise<ScheduledCallback> {
+    return this.http.post<ScheduledCallback>(
+      `/v1/callbacks/${encodeURIComponent(callbackId)}/dispatch`,
+      {},
+    );
+  }
+}