@boldvideo/bold-js 0.9.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @boldvideo/bold-js
 
+## 1.0.0
+
+### Major Changes
+
+- 8afb7b3: Breaking: Unified AI API
+
+  - New methods: `bold.ai.ask()`, `bold.ai.search()`, `bold.ai.chat(videoId, opts)`
+  - `bold.ai.coach()` is now an alias for `bold.ai.ask()`
+  - New parameter: `prompt` replaces `message`
+  - New parameter: `stream` (boolean, default: true) for non-streaming responses
+  - New event types: `message_start`, `text_delta`, `sources`, `message_complete`
+  - New types: `AIEvent`, `AIResponse`, `Source`, `AIUsage`, `SearchOptions`, `ChatOptions`
+  - Removed: `CoachEvent`, `Citation`, `Usage`, `CoachOptions` (old `AskOptions`)
+
 ## 0.9.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -247,7 +247,7 @@ async function* parseSSE(response) {
         try {
           const event = JSON.parse(json);
           yield event;
-          if (event.type === "complete") {
+          if (event.type === "message_complete" || event.type === "error") {
             await reader.cancel();
             return;
           }
@@ -259,9 +259,12 @@ async function* parseSSE(response) {
     reader.releaseLock();
   }
 }
+function buildURL(baseURL, path) {
+  const base = baseURL.endsWith("/") ? baseURL : `${baseURL}/`;
+  return new URL(path, base);
+}
 async function streamRequest(path, body, config) {
-  const baseURL = config.baseURL.endsWith("/") ? config.baseURL : `${config.baseURL}/`;
-  const url = new URL(path, baseURL);
+  const url = buildURL(config.baseURL, path);
   const response = await fetch(url, {
     method: "POST",
     headers: {
@@ -276,41 +279,66 @@ async function streamRequest(path, body, config) {
   }
   return parseSSE(response);
 }
-function createAI(config) {
-  return {
-    /**
-     * Coach - Library-wide RAG assistant
-     *
-     * Requires native fetch (Node 18+ or browser)
-     *
-     * @example
-     * const stream = await bold.ai.coach({ message: "How do I price my SaaS?" });
-     * for await (const event of stream) {
-     *   if (event.type === "token") console.log(event.content);
-     * }
-     */
-    async coach(options) {
-      const path = options.conversationId ? `coach/${options.conversationId}` : "coach";
-      const body = { message: options.message };
-      if (options.collectionId)
-        body.collection_id = options.collectionId;
-      return streamRequest(path, body, config);
+async function jsonRequest(path, body, config) {
+  const url = buildURL(config.baseURL, path);
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      ...config.headers
     },
-    /**
-     * Ask - Video-specific Q&A
-     *
-     * Requires native fetch (Node 18+ or browser)
-     *
-     * @example
-     * const stream = await bold.ai.ask("video-id", { message: "What is this about?" });
-     * for await (const event of stream) {
-     *   if (event.type === "token") console.log(event.content);
-     * }
-     */
-    async ask(videoId, options) {
-      const path = `videos/${videoId}/ask`;
-      return streamRequest(path, { message: options.message }, config);
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    throw new Error(`AI request failed: ${response.status} ${response.statusText}`);
+  }
+  return response.json();
+}
+function createAI(config) {
+  async function ask(options) {
+    const path = options.conversationId ? `ai/ask/${options.conversationId}` : "ai/ask";
+    const body = { prompt: options.prompt };
+    if (options.collectionId)
+      body.collection_id = options.collectionId;
+    if (options.stream === false) {
+      body.stream = false;
+      return jsonRequest(path, body, config);
     }
+    return streamRequest(path, body, config);
+  }
+  async function coach(options) {
+    return ask(options);
+  }
+  async function search(options) {
+    const path = "ai/search";
+    const body = { prompt: options.prompt };
+    if (options.limit)
+      body.limit = options.limit;
+    if (options.collectionId)
+      body.collection_id = options.collectionId;
+    if (options.videoId)
+      body.video_id = options.videoId;
+    if (options.stream === false) {
+      body.stream = false;
+      return jsonRequest(path, body, config);
+    }
+    return streamRequest(path, body, config);
+  }
+  async function chat(videoId, options) {
+    const path = options.conversationId ? `ai/videos/${videoId}/chat/${options.conversationId}` : `ai/videos/${videoId}/chat`;
+    const body = { prompt: options.prompt };
+    if (options.stream === false) {
+      body.stream = false;
+      return jsonRequest(path, body, config);
+    }
+    return streamRequest(path, body, config);
+  }
+  return {
+    ask,
+    coach,
+    search,
+    chat
   };
 }
 

package/dist/index.d.ts

@@ -162,49 +162,164 @@ type Settings = {
     theme_config: ThemeConfig;
     version: string;
 };
-interface Citation {
-    video: Pick<Video, 'internal_id' | 'title' | 'playback_id'>;
-    start_ms: number;
-    end_ms: number;
+/**
+ * Source citation from AI responses
+ */
+interface Source {
+    video_id: string;
+    title: string;
+    timestamp: number;
+    timestamp_end?: number;
     text: string;
+    playback_id?: string;
+    speaker?: string;
 }
-interface Usage {
-    input_tokens: number;
-    output_tokens: number;
+/**
+ * Token usage statistics
+ */
+interface AIUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
 }
-type CoachEvent = {
-    type: "conversation_created";
+/**
+ * SSE event types for AI streaming responses
+ */
+type AIEvent = {
+    type: "message_start";
     id: string;
-    status: "processing";
+    model?: string;
+} | {
+    type: "sources";
+    sources: Source[];
+} | {
+    type: "text_delta";
+    delta: string;
 } | {
     type: "clarification";
     questions: string[];
-    mode: "clarification";
-    needs_clarification: true;
 } | {
-    type: "token";
+    type: "message_complete";
     content: string;
-} | {
-    type: "answer";
-    content: string;
-    citations: Citation[];
-    usage: Usage;
+    sources: Source[];
+    usage: AIUsage;
 } | {
     type: "error";
+    code: string;
     message: string;
-    step?: string;
-    reason?: string;
-    timestamp: string;
-} | {
-    type: "complete";
+    retryable: boolean;
+    details?: Record<string, unknown>;
 };
-interface CoachOptions {
-    message: string;
+/**
+ * Non-streaming AI response
+ */
+interface AIResponse {
+    id: string;
+    content: string;
+    sources: Source[];
+    usage: AIUsage;
+    model?: string;
+}
+/**
+ * Options for bold.ai.ask() and bold.ai.coach()
+ */
+interface AskOptions {
+    prompt: string;
+    stream?: boolean;
     conversationId?: string;
     collectionId?: string;
 }
-interface AskOptions {
-    message: string;
+/**
+ * Options for bold.ai.search()
+ */
+interface SearchOptions {
+    prompt: string;
+    stream?: boolean;
+    limit?: number;
+    collectionId?: string;
+    videoId?: string;
+}
+/**
+ * Options for bold.ai.chat()
+ *
+ * conversationId: Pass to continue an existing conversation (multi-turn chat).
+ * If omitted, a new conversation is created. The id is returned in the
+ * message_start event - capture it to pass to subsequent requests.
+ */
+interface ChatOptions {
+    prompt: string;
+    stream?: boolean;
+    conversationId?: string;
+}
+
+/**
+ * AI client interface for type-safe method overloading
+ */
+interface AIClient {
+    /**
+     * Ask - Library-wide RAG assistant
+     *
+     * @example
+     * // Streaming (default)
+     * const stream = await bold.ai.ask({ prompt: "How do I price my SaaS?" });
+     * for await (const event of stream) {
+     *   if (event.type === "text_delta") process.stdout.write(event.delta);
+     * }
+     *
+     * @example
+     * // Non-streaming
+     * const response = await bold.ai.ask({ prompt: "How do I price my SaaS?", stream: false });
+     * console.log(response.content);
+     */
+    ask(options: AskOptions & {
+        stream: false;
+    }): Promise<AIResponse>;
+    ask(options: AskOptions & {
+        stream?: true;
+    }): Promise<AsyncIterable<AIEvent>>;
+    ask(options: AskOptions): Promise<AsyncIterable<AIEvent> | AIResponse>;
+    /**
+     * Coach - Alias for ask() (Library-wide RAG assistant)
+     */
+    coach(options: AskOptions & {
+        stream: false;
+    }): Promise<AIResponse>;
+    coach(options: AskOptions & {
+        stream?: true;
+    }): Promise<AsyncIterable<AIEvent>>;
+    coach(options: AskOptions): Promise<AsyncIterable<AIEvent> | AIResponse>;
+    /**
+     * Search - Semantic search with light synthesis
+     *
+     * @example
+     * const stream = await bold.ai.search({ prompt: "pricing strategies", limit: 10 });
+     * for await (const event of stream) {
+     *   if (event.type === "sources") console.log("Found:", event.sources.length, "results");
+     * }
+     */
+    search(options: SearchOptions & {
+        stream: false;
+    }): Promise<AIResponse>;
+    search(options: SearchOptions & {
+        stream?: true;
+    }): Promise<AsyncIterable<AIEvent>>;
+    search(options: SearchOptions): Promise<AsyncIterable<AIEvent> | AIResponse>;
+    /**
+     * Chat - Video-scoped conversation
+     *
+     * @example
+     * const stream = await bold.ai.chat("video-id", { prompt: "What is discussed at 5 minutes?" });
+     * for await (const event of stream) {
+     *   if (event.type === "text_delta") process.stdout.write(event.delta);
+     * }
+     */
+    chat(videoId: string, options: ChatOptions & {
+        stream: false;
+    }): Promise<AIResponse>;
+    chat(videoId: string, options: ChatOptions & {
+        stream?: true;
+    }): Promise<AsyncIterable<AIEvent>>;
+    chat(videoId: string, options: ChatOptions): Promise<AsyncIterable<AIEvent> | AIResponse>;
 }
 
 type ClientOptions = {
@@ -235,10 +350,7 @@ declare function createClient(apiKey: string, options?: ClientOptions): {
             data: Playlist;
         }>;
     };
-    ai: {
-        coach(options: CoachOptions): Promise<AsyncIterable<CoachEvent>>;
-        ask(videoId: string, options: AskOptions): Promise<AsyncIterable<CoachEvent>>;
-    };
+    ai: AIClient;
     trackEvent: (video: any, event: Event) => void;
     trackPageView: (title: string) => void;
 };
@@ -252,4 +364,4 @@ declare const DEFAULT_API_BASE_URL = "https://app.boldvideo.io/api/v1/";
  */
 declare const DEFAULT_INTERNAL_API_BASE_URL = "https://app.boldvideo.io/i/v1/";
 
-export { Account, AccountAI, AskOptions, AssistantConfig, Citation, ClientOptions, CoachEvent, CoachOptions, DEFAULT_API_BASE_URL, DEFAULT_INTERNAL_API_BASE_URL, MenuItem, Playlist, Portal, PortalDisplay, PortalLayout, PortalNavigation, PortalTheme, Settings, ThemeColors, ThemeConfig, Usage, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, createClient };
+export { AIEvent, AIResponse, AIUsage, Account, AccountAI, AskOptions, AssistantConfig, ChatOptions, ClientOptions, DEFAULT_API_BASE_URL, DEFAULT_INTERNAL_API_BASE_URL, MenuItem, Playlist, Portal, PortalDisplay, PortalLayout, PortalNavigation, PortalTheme, SearchOptions, Settings, Source, ThemeColors, ThemeConfig, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, createClient };

package/dist/index.js

@@ -209,7 +209,7 @@ async function* parseSSE(response) {
         try {
           const event = JSON.parse(json);
           yield event;
-          if (event.type === "complete") {
+          if (event.type === "message_complete" || event.type === "error") {
             await reader.cancel();
             return;
           }
@@ -221,9 +221,12 @@ async function* parseSSE(response) {
     reader.releaseLock();
   }
 }
+function buildURL(baseURL, path) {
+  const base = baseURL.endsWith("/") ? baseURL : `${baseURL}/`;
+  return new URL(path, base);
+}
 async function streamRequest(path, body, config) {
-  const baseURL = config.baseURL.endsWith("/") ? config.baseURL : `${config.baseURL}/`;
-  const url = new URL(path, baseURL);
+  const url = buildURL(config.baseURL, path);
   const response = await fetch(url, {
     method: "POST",
     headers: {
@@ -238,41 +241,66 @@ async function streamRequest(path, body, config) {
   }
   return parseSSE(response);
 }
-function createAI(config) {
-  return {
-    /**
-     * Coach - Library-wide RAG assistant
-     *
-     * Requires native fetch (Node 18+ or browser)
-     *
-     * @example
-     * const stream = await bold.ai.coach({ message: "How do I price my SaaS?" });
-     * for await (const event of stream) {
-     *   if (event.type === "token") console.log(event.content);
-     * }
-     */
-    async coach(options) {
-      const path = options.conversationId ? `coach/${options.conversationId}` : "coach";
-      const body = { message: options.message };
-      if (options.collectionId)
-        body.collection_id = options.collectionId;
-      return streamRequest(path, body, config);
+async function jsonRequest(path, body, config) {
+  const url = buildURL(config.baseURL, path);
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      ...config.headers
     },
-    /**
-     * Ask - Video-specific Q&A
-     *
-     * Requires native fetch (Node 18+ or browser)
-     *
-     * @example
-     * const stream = await bold.ai.ask("video-id", { message: "What is this about?" });
-     * for await (const event of stream) {
-     *   if (event.type === "token") console.log(event.content);
-     * }
-     */
-    async ask(videoId, options) {
-      const path = `videos/${videoId}/ask`;
-      return streamRequest(path, { message: options.message }, config);
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    throw new Error(`AI request failed: ${response.status} ${response.statusText}`);
+  }
+  return response.json();
+}
+function createAI(config) {
+  async function ask(options) {
+    const path = options.conversationId ? `ai/ask/${options.conversationId}` : "ai/ask";
+    const body = { prompt: options.prompt };
+    if (options.collectionId)
+      body.collection_id = options.collectionId;
+    if (options.stream === false) {
+      body.stream = false;
+      return jsonRequest(path, body, config);
     }
+    return streamRequest(path, body, config);
+  }
+  async function coach(options) {
+    return ask(options);
+  }
+  async function search(options) {
+    const path = "ai/search";
+    const body = { prompt: options.prompt };
+    if (options.limit)
+      body.limit = options.limit;
+    if (options.collectionId)
+      body.collection_id = options.collectionId;
+    if (options.videoId)
+      body.video_id = options.videoId;
+    if (options.stream === false) {
+      body.stream = false;
+      return jsonRequest(path, body, config);
+    }
+    return streamRequest(path, body, config);
+  }
+  async function chat(videoId, options) {
+    const path = options.conversationId ? `ai/videos/${videoId}/chat/${options.conversationId}` : `ai/videos/${videoId}/chat`;
+    const body = { prompt: options.prompt };
+    if (options.stream === false) {
+      body.stream = false;
+      return jsonRequest(path, body, config);
+    }
+    return streamRequest(path, body, config);
+  }
+  return {
+    ask,
+    coach,
+    search,
+    chat
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boldvideo/bold-js",
   "license": "MIT",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",