@boldvideo/bold-js 1.5.1 → 1.6.1

package/AGENTS.md

@@ -96,7 +96,10 @@ bold.videos.search(query) // Search videos
 bold.playlists.list()     // List playlists
 bold.playlists.get(id)    // Get single playlist
 bold.ai.coach(opts)       // AI RAG assistant (streaming)
-bold.ai.ask(videoId, opts)// Video Q&A (streaming)
+bold.ai.ask(opts)         // AI RAG assistant (alias for coach)
+bold.ai.search(opts)      // Semantic search with synthesis
+bold.ai.chat(videoId, opts) // Video-scoped Q&A
+bold.ai.recommend(opts)   // AI-powered recommendations
 bold.trackEvent()         // Track video events
 bold.trackPageView()      // Track page views
 ```

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @boldvideo/bold-js
 
+## 1.6.1
+
+### Patch Changes
+
+- 7aff057: Align SDK with API specification
+
+  - Renamed `synthesize` to `includeGuidance` in `RecommendOptions` to match API
+  - Renamed `why` to `reason` in `RecommendationVideo` type to match API response
+  - Added `tags` filter to `AskOptions` and `SearchOptions`
+  - Added `currentTime` to `ChatOptions` for playback context
+
+## 1.6.0
+
+### Minor Changes
+
+- 71b3437: Add `bold.ai.recommend()` for AI-powered video recommendations
+
+  - New method `bold.ai.recommend({ topics, ...options })` returns personalized video recommendations based on topics
+  - Supports both streaming (default) and non-streaming modes
+  - Includes AI-generated guidance for learning paths
+  - New types: `RecommendOptions`, `RecommendResponse`, `Recommendation`, `RecommendationVideo`, `TopicInput`
+  - New `recommendations` event type in `AIEvent` union for streaming responses
+
 ## 1.5.1
 
 ### Patch Changes

package/README.md

@@ -26,86 +26,248 @@
   </a>
 </p>
 
-## Usage
+---
 
-First, install the library:
+## Installation
 
-```sh
+```bash
 npm install @boldvideo/bold-js
 ```
 
-Next, instantiate the client to establish a connection to your Bold Channel:
-```js
-import { createClient } from "@boldvideo/bold-js";
+## Quick Start
 
-const bold = createClient('YOUR_API_KEY');
+```typescript
+import { createClient } from '@boldvideo/bold-js';
+
+const bold = createClient('your-api-key');
+
+// Fetch videos
+const videos = await bold.videos.list();
+
+// Get AI-powered recommendations
+const recs = await bold.ai.recommend({ 
+  topics: ['sales', 'negotiation'],
+  stream: false 
+});
+console.log(recs.guidance);
 ```
 
-Now you're able to query any of your resources from Bold. For exmaple:
-```js
-// fetches your channel settings, menus and featured playlists
-const settings = await bold.settings();
+---
+
+## API Reference
+
+### Videos
 
-// fetches the latest videos
+```typescript
+// List latest videos
 const videos = await bold.videos.list();
 
-// fetches the latest playlists
+// Get a single video
+const video = await bold.videos.get('video-id');
+
+// Search videos
+const results = await bold.videos.search('pricing strategies');
+```
+
+### Playlists
+
+```typescript
+// List all playlists
 const playlists = await bold.playlists.list();
 
+// Get a single playlist with videos
+const playlist = await bold.playlists.get('playlist-id');
+```
+
+### Settings
+
+```typescript
+// Fetch channel settings, menus, and featured playlists
+const settings = await bold.settings();
+```
+
+---
+
+## AI Methods
+
+All AI methods support both streaming (default) and non-streaming modes.
+
+### Recommend
+
+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({ 
+  topics: ['contract law', 'ethics', 'client management'],
+  context: 'I failed these topics on my certification exam'
+});
+
+for await (const event of stream) {
+  if (event.type === 'recommendations') {
+    event.recommendations.forEach(rec => {
+      console.log(`${rec.topic}:`);
+      rec.videos.forEach(v => console.log(`  - ${v.title} (${v.relevance})`));
+    });
+  }
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta); // AI guidance
+  }
+}
+
+// Non-streaming
+const response = await bold.ai.recommend({ 
+  topics: ['sales', 'marketing'],
+  stream: false 
+});
+console.log(response.guidance);
+console.log(response.recommendations);
 ```
 
-### AI Search with Conversation Context
+**Options:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `topics` | `string[]` \| `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.
 
-Use the `context` parameter to enable multi-turn conversations:
+```typescript
+// Streaming
+const stream = await bold.ai.coach({ prompt: 'How do I price my SaaS?' });
 
-```js
-// First question
+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);
+```
+
+### Search
+
+Semantic search with light synthesis.
+
+```typescript
+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`);
+  }
+}
+```
+
+### Chat
+
+Video-scoped conversation for Q&A about a specific video.
+
+```typescript
+const stream = await bold.ai.chat('video-id', { 
+  prompt: 'What is discussed at the 5 minute mark?' 
+});
+
+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', { 
+  prompt: 'What does she mean by that?',
+  currentTime: 847  // seconds
+});
+```
+
+### Multi-turn Conversations
+
+Use the `context` parameter for follow-up questions:
+
+```typescript
 const first = await bold.ai.search({ 
-  prompt: "How do indie designers find clients?",
+  prompt: 'How do indie designers find clients?',
   stream: false 
 });
-console.log(first.content);
 
-// Follow-up with context from previous response
 const followUp = await bold.ai.search({
-  prompt: "What about cold outreach specifically?",
+  prompt: 'What about cold outreach specifically?',
   context: first.context,
   stream: false
 });
-console.log(followUp.content);
 ```
 
-## Related Links
+---
 
-- **[Bold API Documentation](https://docs.boldvideo.io/docs/api)**
+## Analytics
 
-## Contributing
+Track video events and page views for analytics.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
+```typescript
+// Track video events (play, pause, complete, etc.)
+bold.trackEvent({
+  type: 'play',
+  videoId: 'video-id',
+  timestamp: 0
+});
 
-## Security
+// Track page views
+bold.trackPageView({
+  path: '/videos/my-video',
+  referrer: document.referrer
+});
+```
 
-### For Maintainers
+---
 
-The automated release process is secure by default:
-- NPM_TOKEN is only accessible to workflows on the main branch
-- External contributors' PRs cannot access secrets
-- Only maintainers with write access can merge to main
-- The changeset-release workflow only runs after merge to main
+## TypeScript
 
-### Recommended Branch Protection
+All types are exported for full TypeScript support:
 
-For additional security, enable these branch protection rules for `main`:
-- Require pull request reviews before merging
-- Dismiss stale pull request approvals when new commits are pushed
-- Require status checks to pass (CI workflow)
-- Require branches to be up to date before merging
-- Include administrators in these restrictions
+```typescript
+import type { 
+  Video, 
+  Playlist, 
+  Settings,
+  AIEvent,
+  AIResponse,
+  RecommendOptions,
+  RecommendResponse,
+  Recommendation,
+  Source
+} from '@boldvideo/bold-js';
+```
 
-## More Resources
+---
 
-### Support
+## Related Links
+
+- **[Bold API Documentation](https://docs.boldvideo.io/docs/api)**
+- **[GitHub Repository](https://github.com/boldvideo/bold-js)**
+- **[npm Package](https://www.npmjs.com/package/@boldvideo/bold-js)**
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
+
+## Security
 
-- Bugs or Feature Requests? [Submit an issue](/../../issues/new).
+See [SECURITY.md](SECURITY.md) for security policies and reporting vulnerabilities.
 
+## License
 
+MIT

package/dist/index.cjs

@@ -306,6 +306,8 @@ function createAI(config) {
     const body = { prompt: options.prompt };
     if (options.collectionId)
       body.collection_id = options.collectionId;
+    if (options.tags)
+      body.tags = options.tags;
     if (options.stream === false) {
       body.stream = false;
       return jsonRequest(path, body, config);
@@ -324,6 +326,8 @@ function createAI(config) {
       body.collection_id = options.collectionId;
     if (options.videoId)
       body.video_id = options.videoId;
+    if (options.tags)
+      body.tags = options.tags;
     if (options.context)
       body.context = options.context;
     if (options.stream === false) {
@@ -335,6 +339,27 @@ function createAI(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";
+    const body = { topics: options.topics };
+    if (options.limit)
+      body.limit = options.limit;
+    if (options.collectionId)
+      body.collection_id = options.collectionId;
+    if (options.tags)
+      body.tags = options.tags;
+    if (options.includeGuidance !== void 0)
+      body.include_guidance = options.includeGuidance;
+    if (options.context)
+      body.context = options.context;
     if (options.stream === false) {
       body.stream = false;
       return jsonRequest(path, body, config);
@@ -345,7 +370,8 @@ function createAI(config) {
     ask,
     coach,
     search,
-    chat
+    chat,
+    recommend
   };
 }
 

package/dist/index.d.ts

@@ -223,6 +223,9 @@ type AIEvent = {
 } | {
     type: "clarification";
     questions: string[];
+} | {
+    type: "recommendations";
+    recommendations: Recommendation[];
 } | {
     type: "message_complete";
     content: string;
@@ -257,6 +260,7 @@ interface AskOptions {
     stream?: boolean;
     conversationId?: string;
     collectionId?: string;
+    tags?: string[];
 }
 /**
  * Conversation message for AI context
@@ -274,6 +278,7 @@ interface SearchOptions {
     limit?: number;
     collectionId?: string;
     videoId?: string;
+    tags?: string[];
     context?: AIContextMessage[];
 }
 /**
@@ -287,6 +292,53 @@ interface ChatOptions {
     prompt: string;
     stream?: boolean;
     conversationId?: string;
+    currentTime?: number;
+}
+/**
+ * A recommended video with relevance score
+ */
+interface RecommendationVideo {
+    video_id: string;
+    title: string;
+    playback_id: string;
+    relevance: number;
+    reason: string;
+}
+/**
+ * A topic recommendation with its videos
+ */
+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()
+ */
+interface RecommendOptions {
+    topics: TopicInput[] | string;
+    stream?: boolean;
+    limit?: number;
+    collectionId?: string;
+    tags?: string[];
+    includeGuidance?: boolean;
+    context?: string;
+}
+/**
+ * Non-streaming response for recommend endpoint
+ */
+interface RecommendResponse {
+    id: string;
+    recommendations: Recommendation[];
+    guidance: string;
+    sources: Source[];
 }
 
 /**
@@ -357,6 +409,28 @@ interface AIClient {
         stream?: true;
     }): Promise<AsyncIterable<AIEvent>>;
     chat(videoId: string, options: ChatOptions): Promise<AsyncIterable<AIEvent> | AIResponse>;
+    /**
+     * Recommend - AI-powered video recommendations
+     *
+     * @example
+     * // Streaming (default)
+     * const stream = await bold.ai.recommend({ 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 });
+     * console.log(response.guidance);
+     */
+    recommend(options: RecommendOptions & {
+        stream: false;
+    }): Promise<RecommendResponse>;
+    recommend(options: RecommendOptions & {
+        stream?: true;
+    }): Promise<AsyncIterable<AIEvent>>;
+    recommend(options: RecommendOptions): Promise<AsyncIterable<AIEvent> | RecommendResponse>;
 }
 
 type ClientOptions = {
@@ -401,4 +475,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, SearchOptions, Settings, Source, ThemeColors, ThemeConfig, 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, SearchOptions, Settings, Source, ThemeColors, ThemeConfig, TopicInput, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, createClient };

package/dist/index.js

@@ -268,6 +268,8 @@ function createAI(config) {
     const body = { prompt: options.prompt };
     if (options.collectionId)
       body.collection_id = options.collectionId;
+    if (options.tags)
+      body.tags = options.tags;
     if (options.stream === false) {
       body.stream = false;
       return jsonRequest(path, body, config);
@@ -286,6 +288,8 @@ function createAI(config) {
       body.collection_id = options.collectionId;
     if (options.videoId)
       body.video_id = options.videoId;
+    if (options.tags)
+      body.tags = options.tags;
     if (options.context)
       body.context = options.context;
     if (options.stream === false) {
@@ -297,6 +301,27 @@ function createAI(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";
+    const body = { topics: options.topics };
+    if (options.limit)
+      body.limit = options.limit;
+    if (options.collectionId)
+      body.collection_id = options.collectionId;
+    if (options.tags)
+      body.tags = options.tags;
+    if (options.includeGuidance !== void 0)
+      body.include_guidance = options.includeGuidance;
+    if (options.context)
+      body.context = options.context;
     if (options.stream === false) {
       body.stream = false;
       return jsonRequest(path, body, config);
@@ -307,7 +332,8 @@ function createAI(config) {
     ask,
     coach,
     search,
-    chat
+    chat,
+    recommend
   };
 }
 

package/llms.txt

@@ -13,33 +13,112 @@ const bold = createClient('your-api-key');
 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 });
+console.log(recs.guidance);
+
 // AI streaming
-const stream = await bold.ai.coach({ message: "How do I price my SaaS?" });
+const stream = await bold.ai.coach({ prompt: 'How do I price my SaaS?' });
 for await (const event of stream) {
-  if (event.type === 'token') process.stdout.write(event.content);
+  if (event.type === 'text_delta') process.stdout.write(event.delta);
 }
 ```
 
 ## API Reference
 
+### Client
+
 - `createClient(apiKey, options?)` - Create SDK instance
+
+### Content
+
 - `bold.settings()` - Channel settings, menus, featured playlists
 - `bold.videos.list()` - List videos
 - `bold.videos.get(id)` - Get video by ID
 - `bold.videos.search(query)` - Search videos
 - `bold.playlists.list()` - List playlists
 - `bold.playlists.get(id)` - Get playlist by ID
-- `bold.ai.coach(options)` - AI RAG assistant, returns `AsyncIterable<CoachEvent>`
-- `bold.ai.ask(videoId, options)` - Video Q&A, returns `AsyncIterable<CoachEvent>`
-- `bold.trackEvent(event)` - Track video analytics
+
+### AI Methods
+
+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.search(options)` - Semantic search with synthesis
+- `bold.ai.chat(videoId, options)` - Video-scoped Q&A conversation
+
+### Analytics
+
+- `bold.trackEvent(event)` - Track video events (play, pause, complete)
 - `bold.trackPageView(data)` - Track page views
 
+## 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
+
+```typescript
+{
+  prompt: string;             // Question to ask (required)
+  stream?: boolean;           // Default: true
+  conversationId?: string;    // Continue existing conversation
+  collectionId?: string;      // Filter to collection
+  tags?: string[];            // Filter by tags
+}
+```
+
+### SearchOptions
+
+```typescript
+{
+  prompt: string;             // Search query (required)
+  stream?: boolean;           // Default: true
+  limit?: number;             // Max results
+  collectionId?: string;      // Filter to collection
+  videoId?: string;           // Search within specific video
+  tags?: string[];            // Filter by tags
+  context?: AIContextMessage[]; // Conversation context
+}
+```
+
+### ChatOptions
+
+```typescript
+{
+  prompt: string;             // Question about the video (required)
+  stream?: boolean;           // Default: true
+  conversationId?: string;    // Continue existing conversation
+  currentTime?: number;       // Current playback position in seconds
+}
+```
+
 ## Types
 
-Key types exported: `Video`, `Playlist`, `Settings`, `Portal`, `CoachEvent`, `CoachOptions`, `AskOptions`, `Citation`
+Key types exported:
+
+- `Video`, `Playlist`, `Settings`, `Portal`
+- `AIEvent`, `AIResponse`, `Source`, `AIUsage`
+- `AskOptions`, `SearchOptions`, `ChatOptions`
+- `RecommendOptions`, `RecommendResponse`, `Recommendation`, `RecommendationVideo`, `TopicInput`
 
 ## Links
 
 - [GitHub](https://github.com/boldvideo/bold-js)
 - [npm](https://www.npmjs.com/package/@boldvideo/bold-js)
+- [API Docs](https://docs.boldvideo.io/docs/api)
 - [Types Source](https://github.com/boldvideo/bold-js/blob/main/src/lib/types.ts)

package/package.json

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