@boldvideo/bold-js 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @boldvideo/bold-js
 
+## 1.7.0
+
+### Minor Changes
+
+- e6fb51b: Align SDK with Bold AI API v1 specification
+
+  **Breaking Changes:**
+
+  - Video-scoped chat: pass `videoId` in options instead of as separate arg: `bold.ai.chat({ videoId, prompt })`
+  - `Source.timestamp_end` and `Source.playback_id` are now required (were optional)
+  - `AIUsage` now uses `input_tokens`/`output_tokens` (was `prompt_tokens`/`completion_tokens`/`total_tokens`)
+  - Removed `TopicInput` type - `RecommendationsOptions.topics` now only accepts `string[]`
+  - `RecommendationsOptions.context` is now `AIContextMessage[]` (was `string`)
+
+  **New:**
+
+  - `bold.ai.chat(opts)` - Single method for all chat (pass `videoId` to scope to a video)
+  - `bold.ai.recommendations(opts)` - AI-powered video recommendations (replaces `recommend`)
+  - `ChatOptions.videoId` - Scope chat to a specific video
+  - `ChatOptions.currentTime` - Pass current playback position for context
+
+  **Deprecated (still work, will be removed in v2):**
+
+  - `bold.ai.ask()` → use `bold.ai.chat()`
+  - `bold.ai.coach()` → use `bold.ai.chat()`
+  - `bold.ai.recommend()` → use `bold.ai.recommendations()`
+  - `AskOptions` type → use `ChatOptions`
+  - `RecommendOptions` type → use `RecommendationsOptions`
+  - `RecommendResponse` type → use `RecommendationsResponse`
+
+  **Type Changes:**
+
+  - Added `Source.id` field (chunk identifier)
+  - Added `conversation_id` and `video_id` to `message_start` event
+  - Added `conversation_id`, `recommendations`, `guidance` to `message_complete` event
+  - Simplified `clarification` event to include `content` field
+  - Removed legacy event types: `token`, `answer`, `complete`
+
 ## 1.6.1
 
 ### Patch Changes

package/README.md

@@ -44,8 +44,8 @@ const bold = createClient('your-api-key');
 // Fetch videos
 const videos = await bold.videos.list();
 
-// Get AI-powered recommendations
-const recs = await bold.ai.recommend({ 
+// AI-powered recommendations
+const recs = await bold.ai.recommendations({ 
   topics: ['sales', 'negotiation'],
   stream: false 
 });
@@ -92,15 +92,47 @@ const settings = await bold.settings();
 
 All AI methods support both streaming (default) and non-streaming modes.
 
-### Recommend
+### Chat
+
+Library-wide conversational AI for deep Q&A across your entire video library.
+
+```typescript
+// Streaming (default)
+const stream = await bold.ai.chat({ prompt: 'How do I price my SaaS?' });
+
+for await (const event of stream) {
+  if (event.type === 'text_delta') process.stdout.write(event.delta);
+  if (event.type === 'sources') console.log('Sources:', event.sources);
+}
+
+// Non-streaming
+const response = await bold.ai.chat({ 
+  prompt: 'What are the best closing techniques?',
+  stream: false 
+});
+console.log(response.content);
+```
+
+**Options:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prompt` | `string` | The user's question (required) |
+| `stream` | `boolean` | `true` (default) for SSE, `false` for JSON |
+| `videoId` | `string` | If provided, scope to this video instead of whole library |
+| `currentTime` | `number` | Current playback position (only with `videoId`) |
+| `conversationId` | `string` | Pass to continue existing conversation |
+| `collectionId` | `string` | Filter to a specific collection |
+| `tags` | `string[]` | Filter by tags |
+
+### Recommendations
 
 Get AI-powered video recommendations based on topics — ideal for personalized learning paths, exam prep, and content discovery.
 
 ```typescript
 // Streaming (default)
-const stream = await bold.ai.recommend({ 
+const stream = await bold.ai.recommendations({ 
   topics: ['contract law', 'ethics', 'client management'],
-  context: 'I failed these topics on my certification exam'
 });
 
 for await (const event of stream) {
@@ -116,7 +148,7 @@ for await (const event of stream) {
 }
 
 // Non-streaming
-const response = await bold.ai.recommend({ 
+const response = await bold.ai.recommendations({ 
   topics: ['sales', 'marketing'],
   stream: false 
 });
@@ -128,38 +160,17 @@ console.log(response.recommendations);
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `topics` | `string[]` \| `string` | Topics to find content for (required) |
+| `topics` | `string[]` | Topics to find content for (required) |
 | `stream` | `boolean` | `true` (default) for SSE, `false` for JSON |
 | `limit` | `number` | Max videos per topic (default: 5, max: 20) |
 | `collectionId` | `string` | Filter to a specific collection |
 | `tags` | `string[]` | Filter by tags |
 | `includeGuidance` | `boolean` | Include AI learning path narrative (default: true) |
-| `context` | `string` | User context for personalized guidance |
-
-### Coach / Ask
-
-Library-wide RAG assistant for answering questions across your entire video library.
-
-```typescript
-// Streaming
-const stream = await bold.ai.coach({ prompt: 'How do I price my SaaS?' });
-
-for await (const event of stream) {
-  if (event.type === 'text_delta') process.stdout.write(event.delta);
-  if (event.type === 'sources') console.log('Sources:', event.sources);
-}
-
-// Non-streaming
-const response = await bold.ai.ask({ 
-  prompt: 'What are the best closing techniques?',
-  stream: false 
-});
-console.log(response.content);
-```
+| `context` | `AIContextMessage[]` | Previous conversation turns for follow-ups |
 
 ### Search
 
-Semantic search with light synthesis.
+Fast semantic search with a brief AI-generated summary.
 
 ```typescript
 const stream = await bold.ai.search({ 
@@ -174,12 +185,13 @@ for await (const event of stream) {
 }
 ```
 
-### Chat
+### Video-Scoped Chat
 
-Video-scoped conversation for Q&A about a specific video.
+Chat about a specific video by passing `videoId`. Uses only that video's transcript as context.
 
 ```typescript
-const stream = await bold.ai.chat('video-id', { 
+const stream = await bold.ai.chat({ 
+  videoId: 'video-id',
   prompt: 'What is discussed at the 5 minute mark?' 
 });
 
@@ -187,8 +199,9 @@ for await (const event of stream) {
   if (event.type === 'text_delta') process.stdout.write(event.delta);
 }
 
-// With playback context - helps AI understand what viewer just watched
-const stream = await bold.ai.chat('video-id', { 
+// With playback context (coming soon)
+const stream = await bold.ai.chat({ 
+  videoId: 'video-id',
   prompt: 'What does she mean by that?',
   currentTime: 847  // seconds
 });
@@ -245,8 +258,10 @@ import type {
   Settings,
   AIEvent,
   AIResponse,
-  RecommendOptions,
-  RecommendResponse,
+  ChatOptions,
+  SearchOptions,
+  RecommendationsOptions,
+  RecommendationsResponse,
   Recommendation,
   Source
 } from '@boldvideo/bold-js';
@@ -254,6 +269,29 @@ import type {
 
 ---
 
+## Migration from v1.6.x
+
+### Method Changes
+
+| Old | New | Notes |
+|-----|-----|-------|
+| `bold.ai.ask(opts)` | `bold.ai.chat(opts)` | `ask()` still works but is deprecated |
+| `bold.ai.coach(opts)` | `bold.ai.chat(opts)` | `coach()` still works but is deprecated |
+| `bold.ai.chat(videoId, opts)` | `bold.ai.chat({ videoId, ...opts })` | Pass `videoId` in options |
+| `bold.ai.recommend(opts)` | `bold.ai.recommendations(opts)` | `recommend()` still works but is deprecated |
+
+### Type Renames
+
+| Old Type | New Type |
+|----------|----------|
+| `AskOptions` | `ChatOptions` |
+| `RecommendOptions` | `RecommendationsOptions` |
+| `RecommendResponse` | `RecommendationsResponse` |
+
+The old types are still exported as aliases for backward compatibility.
+
+---
+
 ## Related Links
 
 - **[Bold API Documentation](https://docs.boldvideo.io/docs/api)**

package/dist/index.cjs

@@ -250,7 +250,7 @@ async function* parseSSE(response) {
         try {
           const event = JSON.parse(json);
           yield event;
-          if (event.type === "complete" || event.type === "error") {
+          if (event.type === "message_complete" || event.type === "error") {
             await reader.cancel();
             return;
           }
@@ -301,21 +301,29 @@ async function jsonRequest(path, body, config) {
   return response.json();
 }
 function createAI(config) {
-  async function ask(options) {
-    const path = options.conversationId ? `ai/ask/${options.conversationId}` : "ai/ask";
+  async function chat(options) {
+    const isVideoScoped = !!options.videoId;
+    const basePath = isVideoScoped ? `ai/videos/${options.videoId}/chat` : "ai/chat";
+    const path = options.conversationId ? `${basePath}/${options.conversationId}` : basePath;
     const body = { prompt: options.prompt };
     if (options.collectionId)
       body.collection_id = options.collectionId;
     if (options.tags)
       body.tags = options.tags;
+    if (isVideoScoped && options.currentTime !== void 0) {
+      body.current_time = options.currentTime;
+    }
     if (options.stream === false) {
       body.stream = false;
       return jsonRequest(path, body, config);
     }
     return streamRequest(path, body, config);
   }
+  async function ask(options) {
+    return chat(options);
+  }
   async function coach(options) {
-    return ask(options);
+    return chat(options);
   }
   async function search(options) {
     const path = "ai/search";
@@ -336,19 +344,8 @@ function createAI(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.currentTime !== void 0)
-      body.current_time = options.currentTime;
-    if (options.stream === false) {
-      body.stream = false;
-      return jsonRequest(path, body, config);
-    }
-    return streamRequest(path, body, config);
-  }
-  async function recommend(options) {
-    const path = "ai/recommend";
+  async function recommendations(options) {
+    const path = "ai/recommendations";
     const body = { topics: options.topics };
     if (options.limit)
       body.limit = options.limit;
@@ -366,11 +363,15 @@ function createAI(config) {
     }
     return streamRequest(path, body, config);
   }
+  async function recommend(options) {
+    return recommendations(options);
+  }
   return {
+    chat,
     ask,
     coach,
     search,
-    chat,
+    recommendations,
     recommend
   };
 }

package/dist/index.d.ts

@@ -182,21 +182,21 @@ type Settings = {
  * Source citation from AI responses
  */
 interface Source {
+    id: string;
     video_id: string;
     title: string;
-    timestamp: number;
-    timestamp_end?: number;
     text: string;
-    playback_id?: string;
+    timestamp: number;
+    timestamp_end: number;
+    playback_id: string;
     speaker?: string;
 }
 /**
  * Token usage statistics
  */
 interface AIUsage {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
+    input_tokens: number;
+    output_tokens: number;
 }
 /**
  * SSE event types for AI streaming responses
@@ -204,42 +204,36 @@ interface AIUsage {
 type AIEvent = {
     type: "message_start";
     id: string;
-    model?: string;
+    conversation_id?: string;
+    video_id?: string;
 } | {
     type: "sources";
     sources: Source[];
-    query?: string;
 } | {
     type: "text_delta";
     delta: string;
-} | {
-    type: "token";
-    content: string;
-} | {
-    type: "answer";
-    content: string;
-    response_id?: string;
-    context?: AIContextMessage[];
 } | {
     type: "clarification";
+    content: string;
     questions: string[];
 } | {
     type: "recommendations";
     recommendations: Recommendation[];
 } | {
     type: "message_complete";
+    id: string;
+    conversation_id?: string;
     content: string;
     sources: Source[];
     usage?: AIUsage;
     context?: AIContextMessage[];
-} | {
-    type: "complete";
+    recommendations?: Recommendation[];
+    guidance?: string;
 } | {
     type: "error";
     code: string;
     message: string;
     retryable: boolean;
-    details?: Record<string, unknown>;
 };
 /**
  * Non-streaming AI response
@@ -253,15 +247,31 @@ interface AIResponse {
     context?: AIContextMessage[];
 }
 /**
- * Options for bold.ai.ask() and bold.ai.coach()
+ * Options for bold.ai.chat()
+ *
+ * If `videoId` is provided, scopes chat to that video (hits /ai/videos/:id/chat).
+ * Otherwise, searches your entire library (hits /ai/chat).
  */
-interface AskOptions {
+interface ChatOptions {
     prompt: string;
     stream?: boolean;
     conversationId?: string;
     collectionId?: string;
     tags?: string[];
+    /**
+     * If provided, scope chat to a specific video instead of the whole library.
+     */
+    videoId?: string;
+    /**
+     * Current playback position in seconds. Only used when videoId is set.
+     * Helps AI understand what the viewer just watched.
+     */
+    currentTime?: number;
 }
+/**
+ * @deprecated Use ChatOptions instead
+ */
+type AskOptions = ChatOptions;
 /**
  * Conversation message for AI context
  */
@@ -281,19 +291,6 @@ interface SearchOptions {
     tags?: string[];
     context?: AIContextMessage[];
 }
-/**
- * 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;
-    currentTime?: number;
-}
 /**
  * A recommended video with relevance score
  */
@@ -309,57 +306,75 @@ interface RecommendationVideo {
  */
 interface Recommendation {
     topic: string;
-    position: number;
     videos: RecommendationVideo[];
 }
 /**
- * Topic input format for recommendations
- */
-type TopicInput = string | {
-    q: string;
-    priority?: number;
-};
-/**
- * Options for bold.ai.recommend()
+ * Options for bold.ai.recommendations()
  */
-interface RecommendOptions {
-    topics: TopicInput[] | string;
+interface RecommendationsOptions {
+    topics: string[];
     stream?: boolean;
     limit?: number;
     collectionId?: string;
     tags?: string[];
     includeGuidance?: boolean;
-    context?: string;
+    context?: AIContextMessage[];
 }
 /**
- * Non-streaming response for recommend endpoint
+ * @deprecated Use RecommendationsOptions instead
+ */
+type RecommendOptions = RecommendationsOptions;
+/**
+ * Non-streaming response for recommendations endpoint
  */
-interface RecommendResponse {
+interface RecommendationsResponse {
     id: string;
     recommendations: Recommendation[];
     guidance: string;
     sources: Source[];
+    context?: AIContextMessage[];
+    usage?: AIUsage;
 }
+/**
+ * @deprecated Use RecommendationsResponse instead
+ */
+type RecommendResponse = RecommendationsResponse;
 
 /**
  * AI client interface for type-safe method overloading
  */
 interface AIClient {
     /**
-     * Ask - Library-wide RAG assistant
+     * Chat - Conversational AI for Q&A
+     *
+     * If `videoId` is provided, scopes to that video. Otherwise searches your entire library.
      *
      * @example
-     * // Streaming (default)
-     * const stream = await bold.ai.ask({ prompt: "How do I price my SaaS?" });
+     * // Library-wide Q&A
+     * const stream = await bold.ai.chat({ prompt: "How do I price my SaaS?" });
      * for await (const event of stream) {
      *   if (event.type === "text_delta") process.stdout.write(event.delta);
      * }
      *
      * @example
+     * // Video-scoped Q&A
+     * const stream = await bold.ai.chat({ videoId: "vid_xyz", prompt: "What does she mean?" });
+     *
+     * @example
      * // Non-streaming
-     * const response = await bold.ai.ask({ prompt: "How do I price my SaaS?", stream: false });
+     * const response = await bold.ai.chat({ prompt: "How do I price my SaaS?", stream: false });
      * console.log(response.content);
      */
+    chat(options: ChatOptions & {
+        stream: false;
+    }): Promise<AIResponse>;
+    chat(options: ChatOptions & {
+        stream?: true;
+    }): Promise<AsyncIterable<AIEvent>>;
+    chat(options: ChatOptions): Promise<AsyncIterable<AIEvent> | AIResponse>;
+    /**
+     * @deprecated Use chat() instead. Will be removed in a future version.
+     */
     ask(options: AskOptions & {
         stream: false;
     }): Promise<AIResponse>;
@@ -368,7 +383,7 @@ interface AIClient {
     }): Promise<AsyncIterable<AIEvent>>;
     ask(options: AskOptions): Promise<AsyncIterable<AIEvent> | AIResponse>;
     /**
-     * Coach - Alias for ask() (Library-wide RAG assistant)
+     * @deprecated Use chat() instead. Will be removed in a future version.
      */
     coach(options: AskOptions & {
         stream: false;
@@ -394,36 +409,30 @@ interface AIClient {
     }): 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>;
-    /**
-     * Recommend - AI-powered video recommendations
+     * Recommendations - AI-powered video recommendations
      *
      * @example
      * // Streaming (default)
-     * const stream = await bold.ai.recommend({ topics: ["sales", "negotiation"] });
+     * const stream = await bold.ai.recommendations({ topics: ["sales", "negotiation"] });
      * for await (const event of stream) {
      *   if (event.type === "recommendations") console.log(event.recommendations);
      * }
      *
      * @example
      * // Non-streaming
-     * const response = await bold.ai.recommend({ topics: ["sales"], stream: false });
+     * const response = await bold.ai.recommendations({ topics: ["sales"], stream: false });
      * console.log(response.guidance);
      */
+    recommendations(options: RecommendationsOptions & {
+        stream: false;
+    }): Promise<RecommendationsResponse>;
+    recommendations(options: RecommendationsOptions & {
+        stream?: true;
+    }): Promise<AsyncIterable<AIEvent>>;
+    recommendations(options: RecommendationsOptions): Promise<AsyncIterable<AIEvent> | RecommendationsResponse>;
+    /**
+     * @deprecated Use recommendations() instead. Will be removed in a future version.
+     */
     recommend(options: RecommendOptions & {
         stream: false;
     }): Promise<RecommendResponse>;
@@ -475,4 +484,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 { AIContextMessage, 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, RecommendOptions, RecommendResponse, Recommendation, RecommendationVideo, SearchOptions, Settings, Source, ThemeColors, ThemeConfig, TopicInput, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, createClient };
+export { AIContextMessage, 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, RecommendOptions, RecommendResponse, Recommendation, RecommendationVideo, RecommendationsOptions, RecommendationsResponse, SearchOptions, Settings, Source, ThemeColors, ThemeConfig, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, createClient };

package/dist/index.js

@@ -212,7 +212,7 @@ async function* parseSSE(response) {
         try {
           const event = JSON.parse(json);
           yield event;
-          if (event.type === "complete" || event.type === "error") {
+          if (event.type === "message_complete" || event.type === "error") {
             await reader.cancel();
             return;
           }
@@ -263,21 +263,29 @@ async function jsonRequest(path, body, config) {
   return response.json();
 }
 function createAI(config) {
-  async function ask(options) {
-    const path = options.conversationId ? `ai/ask/${options.conversationId}` : "ai/ask";
+  async function chat(options) {
+    const isVideoScoped = !!options.videoId;
+    const basePath = isVideoScoped ? `ai/videos/${options.videoId}/chat` : "ai/chat";
+    const path = options.conversationId ? `${basePath}/${options.conversationId}` : basePath;
     const body = { prompt: options.prompt };
     if (options.collectionId)
       body.collection_id = options.collectionId;
     if (options.tags)
       body.tags = options.tags;
+    if (isVideoScoped && options.currentTime !== void 0) {
+      body.current_time = options.currentTime;
+    }
     if (options.stream === false) {
       body.stream = false;
       return jsonRequest(path, body, config);
     }
     return streamRequest(path, body, config);
   }
+  async function ask(options) {
+    return chat(options);
+  }
   async function coach(options) {
-    return ask(options);
+    return chat(options);
   }
   async function search(options) {
     const path = "ai/search";
@@ -298,19 +306,8 @@ function createAI(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.currentTime !== void 0)
-      body.current_time = options.currentTime;
-    if (options.stream === false) {
-      body.stream = false;
-      return jsonRequest(path, body, config);
-    }
-    return streamRequest(path, body, config);
-  }
-  async function recommend(options) {
-    const path = "ai/recommend";
+  async function recommendations(options) {
+    const path = "ai/recommendations";
     const body = { topics: options.topics };
     if (options.limit)
       body.limit = options.limit;
@@ -328,11 +325,15 @@ function createAI(config) {
     }
     return streamRequest(path, body, config);
   }
+  async function recommend(options) {
+    return recommendations(options);
+  }
   return {
+    chat,
     ask,
     coach,
     search,
-    chat,
+    recommendations,
     recommend
   };
 }

package/llms.txt

@@ -14,11 +14,11 @@ const videos = await bold.videos.list();
 const video = await bold.videos.get('video-id');
 
 // AI-powered recommendations
-const recs = await bold.ai.recommend({ topics: ['sales', 'negotiation'], stream: false });
+const recs = await bold.ai.recommendations({ topics: ['sales', 'negotiation'], stream: false });
 console.log(recs.guidance);
 
 // AI streaming
-const stream = await bold.ai.coach({ prompt: 'How do I price my SaaS?' });
+const stream = await bold.ai.chat({ prompt: 'How do I price my SaaS?' });
 for await (const event of stream) {
   if (event.type === 'text_delta') process.stdout.write(event.delta);
 }
@@ -43,11 +43,14 @@ for await (const event of stream) {
 
 All AI methods return `AsyncIterable<AIEvent>` (streaming) or `Promise<AIResponse>` (non-streaming).
 
-- `bold.ai.recommend(options)` - AI-powered video recommendations based on topics
-- `bold.ai.coach(options)` - Library-wide RAG assistant (alias: `ask`)
-- `bold.ai.ask(options)` - Library-wide RAG assistant
+- `bold.ai.chat(options)` - Conversational AI for Q&A (pass `videoId` to scope to a video)
 - `bold.ai.search(options)` - Semantic search with synthesis
-- `bold.ai.chat(videoId, options)` - Video-scoped Q&A conversation
+- `bold.ai.recommendations(options)` - AI-powered video recommendations based on topics
+
+**Deprecated aliases** (still work but will be removed):
+- `bold.ai.ask(options)` → use `chat()`
+- `bold.ai.coach(options)` → use `chat()`
+- `bold.ai.recommend(options)` → use `recommendations()`
 
 ### Analytics
 
@@ -56,26 +59,14 @@ All AI methods return `AsyncIterable<AIEvent>` (streaming) or `Promise<AIRespons
 
 ## AI Options
 
-### RecommendOptions
-
-```typescript
-{
-  topics: string[] | string;  // Topics to find content for (required)
-  stream?: boolean;           // Default: true
-  limit?: number;             // Max videos per topic (default: 5, max: 20)
-  collectionId?: string;      // Filter to collection
-  tags?: string[];            // Filter by tags
-  includeGuidance?: boolean;  // Include AI learning path narrative (default: true)
-  context?: string;           // User context for personalization
-}
-```
-
-### AskOptions / CoachOptions
+### ChatOptions
 
 ```typescript
 {
   prompt: string;             // Question to ask (required)
   stream?: boolean;           // Default: true
+  videoId?: string;           // If set, scope to this video
+  currentTime?: number;       // Current playback position (with videoId)
   conversationId?: string;    // Continue existing conversation
   collectionId?: string;      // Filter to collection
   tags?: string[];            // Filter by tags
@@ -96,14 +87,17 @@ All AI methods return `AsyncIterable<AIEvent>` (streaming) or `Promise<AIRespons
 }
 ```
 
-### ChatOptions
+### RecommendationsOptions
 
 ```typescript
 {
-  prompt: string;             // Question about the video (required)
+  topics: string[];           // Topics to find content for (required)
   stream?: boolean;           // Default: true
-  conversationId?: string;    // Continue existing conversation
-  currentTime?: number;       // Current playback position in seconds
+  limit?: number;             // Max videos per topic (default: 5, max: 20)
+  collectionId?: string;      // Filter to collection
+  tags?: string[];            // Filter by tags
+  includeGuidance?: boolean;  // Include AI learning path narrative (default: true)
+  context?: AIContextMessage[]; // Previous conversation turns for follow-ups
 }
 ```
 
@@ -113,8 +107,8 @@ Key types exported:
 
 - `Video`, `Playlist`, `Settings`, `Portal`
 - `AIEvent`, `AIResponse`, `Source`, `AIUsage`
-- `AskOptions`, `SearchOptions`, `ChatOptions`
-- `RecommendOptions`, `RecommendResponse`, `Recommendation`, `RecommendationVideo`, `TopicInput`
+- `ChatOptions`, `SearchOptions`
+- `RecommendationsOptions`, `RecommendationsResponse`, `Recommendation`, `RecommendationVideo`
 
 ## Links
 

package/package.json

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