supafone-labs 0.5.0 → 0.5.2

package/src/index.ts

@@ -287,16 +287,38 @@ export interface LabsVoiceProviderTraits {
   is_owner?: boolean | null;
 }
 
+/** Stable provider presentation metadata returned by the hosted catalog. */
+export interface LabsVoiceProviderBrand {
+  /** Canonical provider key used for filtering and grouping. */
+  key: string;
+  /** Human-readable provider/company name. */
+  name: string;
+  /** Stable local asset slug when Supafone has an official provider mark. */
+  logo_slug?: string | null;
+  /** Absolute, browser-ready provider logo URL. */
+  logo_url?: string | null;
+  /** Provider's official product or company website. */
+  website_url?: string | null;
+}
+
 export interface LabsVoiceCatalogItem {
   /** Stable runtime reference, including provider prefix when required. */
   id: string;
   voice_id: string;
   /** Human-readable provider display name. */
   provider: string;
+  /** Canonical brand display name for the synthesis provider. */
+  provider_label?: string;
+  /** Browser-ready official provider mark, or null for an unknown provider. */
+  provider_logo_url?: string | null;
+  /** Branding for the provider that renders the voice. */
+  provider_brand?: LabsVoiceProviderBrand;
   /** Canonical SDK/runtime provider key. */
   provider_key: string;
   /** Runtime adapter used to place the voice on an Ultravox call. */
   runtime_provider_key: string;
+  /** Branding for the realtime runtime, which can differ from synthesis. */
+  runtime_provider_brand?: LabsVoiceProviderBrand;
   /** Actual TTS engine behind the voice (can differ for Ultravox built-ins). */
   synthesis_provider_key: string;
   /** Raw identifier used by the provider API. */
@@ -980,6 +1002,30 @@ export interface LabsAgentLifecycleResponse {
   [extra: string]: unknown;
 }
 
+export interface LabsKnowledgeSyncRequest {
+  websiteUrl?: string;
+  website_url?: string;
+  url?: string;
+}
+
+export interface LabsKnowledgeSyncResponse {
+  agent: LabsAgentResponse;
+  chunks_indexed?: number;
+  scraped_ok?: boolean;
+  last_error?: string | null;
+  website_detached?: boolean;
+}
+
+export interface LabsKnowledgeChatTurn {
+  role: "user" | "assistant";
+  content: string;
+}
+
+export interface LabsKnowledgeChatResponse {
+  reply: string;
+  sources: string[];
+}
+
 export interface LabsCapabilitiesResponse {
   product: string;
   api_namespace: string;
@@ -1034,7 +1080,10 @@ export interface LabsVoiceListResponse {
     configured: boolean;
     voice_count: number;
     error?: string | null;
+    brand?: LabsVoiceProviderBrand;
   }>;
+  /** Distinct synthesis-provider brands represented in the complete result. */
+  provider_brands?: LabsVoiceProviderBrand[];
   provider_accounts?: Record<string, unknown>;
   errors?: Record<string, string>;
   catalog?: {
@@ -1942,6 +1991,37 @@ export class SupafoneLabs {
     }
   }
 
+  /** @internal Multipart upload to the Supafone product API with the Labs key. */
+  async requestSupafoneUpload<T>(
+    path: string,
+    file: Uint8Array | ArrayBuffer | Blob,
+    filename: string,
+  ): Promise<T> {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), Math.max(this.timeoutMs, 120_000));
+    try {
+      const safeFilename = filename.replace(/["\\\r\n]/g, "").slice(0, 120) || "document.txt";
+      const blob = file instanceof Blob ? file : new Blob([file as BlobPart]);
+      const form = new FormData();
+      form.append("file", blob, safeFilename);
+      const res = await fetch(this.supafoneApiBaseUrl + path, {
+        method: "POST",
+        signal: ctrl.signal,
+        headers: { Authorization: `Bearer ${this.supafoneApiKey}` },
+        body: form,
+      });
+      const text = await res.text();
+      const parsed = text ? safeJson(text) : {};
+      if (!res.ok) {
+        const detail = (parsed as { detail?: string })?.detail ?? text ?? `HTTP ${res.status}`;
+        throw new SupafoneLabsError(`POST ${path}: ${detail}`, res.status, parsed);
+      }
+      return parsed as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   /** @internal Authenticated binary request to the Supafone app API. */
   async requestSupafoneBinary(path: string): Promise<LabsVoicePreview> {
     const ctrl = new AbortController();
@@ -3153,6 +3233,26 @@ class LabsAgentsNamespace {
     );
   }
 
+  /** Scrape a website and rebuild this agent's managed knowledge corpus. */
+  syncKnowledge(
+    agentId: string,
+    input: LabsKnowledgeSyncRequest = {},
+  ): Promise<LabsKnowledgeSyncResponse> {
+    return this.sm.requestSupafoneApi<LabsKnowledgeSyncResponse>(
+      "POST",
+      `/api/v1/agents/${encodeURIComponent(agentId)}/sync-knowledge`,
+      { url: input.url ?? input.website_url ?? input.websiteUrl ?? "" },
+    );
+  }
+
+  /** Remove website knowledge while preserving uploaded documents and notes. */
+  detachWebsiteKnowledge(agentId: string): Promise<LabsKnowledgeSyncResponse> {
+    return this.sm.requestSupafoneApi<LabsKnowledgeSyncResponse>(
+      "DELETE",
+      `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/website`,
+    );
+  }
+
   /** Ask the managed server whether this agent is ready to activate. */
   readiness(agentKey: string, opts: GetLabsAgentOptions = {}): Promise<LabsAgentReadiness> {
     const q = new URLSearchParams();
@@ -3192,6 +3292,56 @@ class LabsAgentsNamespace {
     );
   }
 
+  /** Start the native provider-neutral browser voice session for this agent. */
+  startWebRtcCall(agentId: string): Promise<WebRtcCallResult> {
+    return this.sm.startWebRtcCall({ agentId });
+  }
+
+  /** Rebuild retrieval data from the agent's already saved knowledge sources. */
+  reindexKnowledge(agentId: string): Promise<Record<string, unknown>> {
+    return this.sm.requestSupafoneApi(
+      "POST",
+      `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/reindex`,
+    );
+  }
+
+  /** Upload and index a txt, md, csv, or PDF knowledge document. */
+  uploadKnowledgeDocument(
+    agentId: string,
+    file: Uint8Array | ArrayBuffer | Blob,
+    filename: string,
+  ): Promise<{ agent: LabsAgentResponse }> {
+    return this.sm.requestSupafoneUpload(
+      `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/upload`,
+      file,
+      filename,
+    );
+  }
+
+  /** Delete one document and rebuild the agent's managed corpus. */
+  deleteKnowledgeDocument(
+    agentId: string,
+    documentId: string,
+  ): Promise<{ agent: LabsAgentResponse }> {
+    return this.sm.requestSupafoneApi(
+      "DELETE",
+      `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge/docs/${encodeURIComponent(documentId)}`,
+    );
+  }
+
+  /** Ask a grounded question against the same corpus used during calls. */
+  chatKnowledge(
+    agentId: string,
+    message: string,
+    history: LabsKnowledgeChatTurn[] = [],
+  ): Promise<LabsKnowledgeChatResponse> {
+    return this.sm.requestSupafoneApi(
+      "POST",
+      `/api/v1/agents/${encodeURIComponent(agentId)}/knowledge-chat`,
+      { message, history },
+    );
+  }
+
   /** Delete an agent. Optionally ask the backend to release assigned numbers. */
   delete(agentKey: string, opts: DeleteLabsAgentOptions = {}): Promise<DeleteLabsAgentResponse> {
     const q = new URLSearchParams();
@@ -4206,6 +4356,9 @@ function languageProfilesPayload(
   input?: LabsLanguageVoiceProfile[],
 ): Record<string, unknown>[] | undefined {
   if (!Array.isArray(input)) return undefined;
+  if (input.length > 4) {
+    throw new SupafoneLabsError("languageProfiles supports at most four profiles");
+  }
   const profiles = input.map((profile) => compact({
     language: profile.language,
     language_hint: profile.language_hint ?? profile.languageHint,