@boldvideo/bold-js 1.15.2 → 1.17.0

package/dist/index.js

@@ -4,9 +4,10 @@ import axios from "axios";
 // src/util/camelize.ts
 var isPlainObject = (value) => value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
 var snakeToCamel = (key) => key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
-function camelizeKeys(input) {
+function camelizeKeys(input, options = {}) {
+  const preserve = new Set(options.preserveKeys ?? []);
   if (Array.isArray(input)) {
-    return input.map((item) => camelizeKeys(item));
+    return input.map((item) => camelizeKeys(item, options));
   }
   if (!isPlainObject(input)) {
     return input;
@@ -14,12 +15,25 @@ function camelizeKeys(input) {
   const out = {};
   for (const [rawKey, value] of Object.entries(input)) {
     const key = snakeToCamel(rawKey);
-    out[key] = camelizeKeys(value);
+    if (preserve.has(rawKey) || preserve.has(key)) {
+      out[key] = value;
+      continue;
+    }
+    out[key] = camelizeKeys(value, options);
   }
   return out;
 }
 
 // src/lib/fetchers.ts
+function toQuery(params) {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0 && v !== null)
+      qs.set(k, String(v));
+  }
+  const s = qs.toString();
+  return s ? `?${s}` : "";
+}
 async function get(client, url) {
   try {
     const res = await client.get(url);
@@ -46,14 +60,44 @@ function fetchSettings(client) {
   };
 }
 function fetchVideos(client) {
-  return async (videoLimit = 12) => {
+  return async (arg = 12) => {
     try {
+      if (typeof arg === "number") {
+        return await get(
+          client,
+          `videos/latest${toQuery({ limit: arg })}`
+        );
+      }
+      const opts = arg;
+      const hasPage = "page" in opts && opts.page !== void 0;
+      if (hasPage && ("limit" in opts || "viewerId" in opts)) {
+        throw new Error(
+          "videos.list(): cannot use `page` with `limit` or `viewerId` (these belong to different endpoints)"
+        );
+      }
+      if (hasPage) {
+        const { page, tag: tag2, collectionId: collectionId2 } = opts;
+        return await get(
+          client,
+          `videos${toQuery({
+            page,
+            tag: tag2,
+            collection_id: collectionId2
+          })}`
+        );
+      }
+      const { limit, tag, collectionId, viewerId } = opts;
       return await get(
         client,
-        `videos/latest?limit=${videoLimit}`
+        `videos/latest${toQuery({
+          limit: limit ?? 12,
+          tag,
+          collection_id: collectionId,
+          viewer_id: viewerId
+        })}`
       );
     } catch (error) {
-      console.error(`Error fetching videos with limit: ${videoLimit}`, error);
+      console.error(`Error fetching videos`, error);
       throw error;
     }
   };
@@ -99,6 +143,154 @@ function fetchPlaylist(client) {
   };
 }
 
+// src/lib/viewers.ts
+import { AxiosError } from "axios";
+var VIEWER_CAMELIZE_OPTIONS = { preserveKeys: ["traits"] };
+var ViewerAPIError = class extends Error {
+  constructor(method, url, error) {
+    var __super = (...args) => {
+      super(...args);
+    };
+    if (error instanceof AxiosError) {
+      const status = error.response?.status;
+      const message = error.response?.data?.error || error.message;
+      __super(`${method} ${url} failed (${status}): ${message}`);
+      this.status = status;
+      this.originalError = error;
+    } else if (error instanceof Error) {
+      __super(`${method} ${url} failed: ${error.message}`);
+      this.originalError = error;
+    } else {
+      __super(`${method} ${url} failed: ${String(error)}`);
+    }
+    this.name = "ViewerAPIError";
+  }
+};
+async function get2(client, url, options) {
+  try {
+    const res = await client.get(url);
+    return camelizeKeys(res.data, options);
+  } catch (error) {
+    throw new ViewerAPIError("GET", url, error);
+  }
+}
+async function post(client, url, data, options) {
+  try {
+    const res = await client.post(url, data);
+    return camelizeKeys(res.data, options);
+  } catch (error) {
+    throw new ViewerAPIError("POST", url, error);
+  }
+}
+async function patch(client, url, data, options) {
+  try {
+    const res = await client.patch(url, data);
+    return camelizeKeys(res.data, options);
+  } catch (error) {
+    throw new ViewerAPIError("PATCH", url, error);
+  }
+}
+function fetchViewers(client) {
+  return async () => {
+    return get2(client, "viewers", VIEWER_CAMELIZE_OPTIONS);
+  };
+}
+function fetchViewer(client) {
+  return async (id) => {
+    if (!id)
+      throw new Error("Viewer ID is required");
+    return get2(client, `viewers/${id}`, VIEWER_CAMELIZE_OPTIONS);
+  };
+}
+function lookupViewer(client) {
+  return async (params) => {
+    const qs = new URLSearchParams();
+    if ("externalId" in params && params.externalId) {
+      qs.set("external_id", params.externalId);
+    }
+    if ("email" in params && params.email) {
+      qs.set("email", params.email);
+    }
+    if (!qs.toString()) {
+      throw new Error("Either externalId or email is required");
+    }
+    return get2(client, `viewers/lookup?${qs.toString()}`, VIEWER_CAMELIZE_OPTIONS);
+  };
+}
+function createViewer(client) {
+  return async (data) => {
+    if (!data.name)
+      throw new Error("Viewer name is required");
+    return post(client, "viewers", {
+      viewer: {
+        name: data.name,
+        email: data.email,
+        external_id: data.externalId,
+        traits: data.traits
+      }
+    }, VIEWER_CAMELIZE_OPTIONS);
+  };
+}
+function updateViewer(client) {
+  return async (id, data) => {
+    if (!id)
+      throw new Error("Viewer ID is required");
+    const body = {};
+    if (data.name !== void 0)
+      body.name = data.name;
+    if (data.email !== void 0)
+      body.email = data.email;
+    if (data.externalId !== void 0)
+      body.external_id = data.externalId;
+    if (data.traits !== void 0)
+      body.traits = data.traits;
+    return patch(client, `viewers/${id}`, { viewer: body }, VIEWER_CAMELIZE_OPTIONS);
+  };
+}
+function fetchViewerProgress(client) {
+  return async (viewerId, options) => {
+    if (!viewerId)
+      throw new Error("Viewer ID is required");
+    const params = new URLSearchParams();
+    if (options?.completed !== void 0)
+      params.set("completed", String(options.completed));
+    if (options?.collectionId)
+      params.set("collection_id", options.collectionId);
+    const query = params.toString();
+    const url = query ? `viewers/${viewerId}/progress?${query}` : `viewers/${viewerId}/progress`;
+    return get2(client, url);
+  };
+}
+function fetchProgress(client) {
+  return async (viewerId, videoId) => {
+    if (!viewerId)
+      throw new Error("Viewer ID is required");
+    if (!videoId)
+      throw new Error("Video ID is required");
+    return get2(client, `viewers/${viewerId}/progress/${videoId}`);
+  };
+}
+function saveProgress(client) {
+  return async (viewerId, videoId, data) => {
+    if (!viewerId)
+      throw new Error("Viewer ID is required");
+    if (!videoId)
+      throw new Error("Video ID is required");
+    if (!Number.isFinite(data.currentTime) || data.currentTime < 0) {
+      throw new Error("currentTime must be a non-negative number");
+    }
+    if (!Number.isFinite(data.duration) || data.duration <= 0) {
+      throw new Error("duration must be a positive number");
+    }
+    return post(client, `viewers/${viewerId}/progress/${videoId}`, {
+      progress: {
+        current_time: data.currentTime,
+        duration: data.duration
+      }
+    });
+  };
+}
+
 // src/util/throttle.ts
 var throttle = (fn, delay) => {
   let wait = false;
@@ -421,6 +613,16 @@ function createClient(apiKey, options = {}) {
       list: fetchPlaylists(apiClient),
       get: fetchPlaylist(apiClient)
     },
+    viewers: {
+      list: fetchViewers(apiClient),
+      get: fetchViewer(apiClient),
+      lookup: lookupViewer(apiClient),
+      create: createViewer(apiClient),
+      update: updateViewer(apiClient),
+      listProgress: fetchViewerProgress(apiClient),
+      getProgress: fetchProgress(apiClient),
+      saveProgress: saveProgress(apiClient)
+    },
     ai: createAI(aiConfig),
     trackEvent: trackEvent(apiClient, userId, { debug }),
     trackPageView: trackPageView(apiClient, userId, { debug })
@@ -429,5 +631,6 @@ function createClient(apiKey, options = {}) {
 export {
   DEFAULT_API_BASE_URL,
   DEFAULT_INTERNAL_API_BASE_URL,
+  ViewerAPIError,
   createClient
 };

package/docs/plans/2026-01-22-docs-enhance-llms-txt-for-ai-consumption-plan.md

@@ -0,0 +1,393 @@
+---
+title: "docs: Enhance llms.txt for AI consumption"
+type: docs
+date: 2026-01-22
+---
+
+# docs: Enhance llms.txt for AI consumption
+
+## Overview
+
+Rewrite the existing `llms.txt` file to be crystal clear for LLMs to understand and use the Bold JS SDK. The current file (121 lines) covers basics but lacks critical information LLMs need to generate correct code.
+
+## Problem Statement / Motivation
+
+LLMs reading the current `llms.txt` will generate broken code because:
+
+1. **Missing `{ data: T }` wrapper** - Content methods return `{ data: Video[] }`, not `Video[]`. Every generated code snippet will fail to access data.
+2. **Incomplete AIEvent types** - Only `text_delta` shown; 5 other event types undocumented
+3. **No error handling guidance** - LLMs cannot generate production-ready code
+4. **`getConversation()` missing** - Multi-turn conversation flow incomplete
+5. **Segment type absent** - Cannot work with sources/citations correctly
+6. **Browser-only tracking undocumented** - Node.js users will hit runtime errors
+
+The llmstxt.org specification recommends keeping files under 10KB while being comprehensive. Our current file is ~4KB with significant gaps.
+
+## Proposed Solution
+
+Rewrite `llms.txt` to ~8KB with these sections:
+
+1. **Header** - SDK name, purpose, installation
+2. **Quick Start** - Working example showing `{ data }` destructuring
+3. **Client Configuration** - `createClient()` with `ClientOptions`
+4. **Content Methods** - Videos, Playlists, Settings with return types
+5. **AI Methods** - All methods including `getConversation()`
+6. **AI Streaming** - Complete `AIEvent` union with all 6 types
+7. **Core Types** - `Video`, `Segment`, `Recommendation` inline
+8. **Error Handling** - HTTP errors, streaming errors, common issues
+9. **Analytics** - Browser-only warning, supported events
+10. **Links** - GitHub, npm, API docs
+
+## Technical Approach
+
+### File Structure
+
+```
+llms.txt (~8KB)
+├── # Bold Video JavaScript SDK (H1)
+├── ## Installation
+├── ## Quick Start (with correct { data } pattern)
+├── ## Client Configuration
+│   ├── createClient(apiKey, options?)
+│   └── ClientOptions type inline
+├── ## Content Methods
+│   ├── bold.settings()
+│   ├── bold.videos.list(limit?)
+│   ├── bold.videos.get(id)  // Note: accepts ID or slug
+│   ├── bold.videos.search(query)
+│   ├── bold.playlists.list()
+│   └── bold.playlists.get(id)
+├── ## AI Methods
+│   ├── bold.ai.chat(options)
+│   ├── bold.ai.search(options)
+│   ├── bold.ai.recommendations(options)
+│   ├── bold.ai.getConversation(id)  // NEW
+│   └── Deprecated aliases note
+├── ## AI Streaming Events (AIEvent)
+│   ├── message_start
+│   ├── sources
+│   ├── text_delta
+│   ├── recommendations
+│   ├── message_complete
+│   └── error
+├── ## AI Options
+│   ├── ChatOptions
+│   ├── SearchOptions
+│   └── RecommendationsOptions
+├── ## Core Types
+│   ├── Video (inline definition)
+│   ├── Segment (inline definition)
+│   ├── Recommendation (inline definition)
+│   └── Others listed by name
+├── ## Error Handling
+│   ├── HTTP Errors (401, 403, 429, 500)
+│   ├── Streaming Errors (AIEvent error type)
+│   └── Common Issues
+├── ## Analytics (Browser Only)
+│   ├── trackEvent(video, event)
+│   └── trackPageView(title)
+└── ## Links
+```
+
+### Key Changes
+
+| Section | Current | Enhanced |
+|---------|---------|----------|
+| Quick Start | `await bold.videos.list()` | `const { data } = await bold.videos.list()` |
+| AI Methods | 3 methods | 4 methods (add `getConversation`) |
+| AIEvent | Mentioned | Full 6-type union with fields |
+| Types | Listed names | Video, Segment, Recommendation inline |
+| Errors | None | HTTP codes + streaming errors |
+| Analytics | 2 lines | Browser-only warning + details |
+
+## Acceptance Criteria
+
+### Content Requirements
+
+- [x] Quick Start shows `{ data }` destructuring pattern
+- [x] `ClientOptions` type shown with `baseURL`, `debug`, `headers`
+- [x] `videos.get(id)` documents ID or slug acceptance
+- [x] `videos.list(limit?)` shows optional limit parameter
+- [x] `getConversation(id)` documented under AI Methods
+- [x] All 6 AIEvent types shown with their fields
+- [x] `Segment` type shown inline (replaces deprecated `Source`)
+- [x] Error handling section with HTTP codes and streaming errors
+- [x] Analytics section marked "Browser Only"
+- [x] File size under 10KB (actual: 6.6KB)
+
+### Code Examples Must Work
+
+- [x] Client initialization compiles
+- [x] Video listing with `{ data }` works
+- [x] AI streaming loop handles all event types
+- [x] Error handling pattern catches both sync and async errors
+
+### Format Requirements
+
+- [x] Follows llmstxt.org Markdown conventions
+- [x] H1 title, H2 sections, H3 subsections
+- [x] Code blocks with `typescript` syntax highlighting
+- [x] Consistent terminology (use "Segment" not "Source")
+
+## Success Metrics
+
+1. **LLM Code Generation Accuracy** - Generated code runs without immediate type/property errors
+2. **File Size** - Under 10KB (target: ~8KB)
+3. **Section Coverage** - All 10 planned sections present
+4. **Zero Missing Criticals** - No undocumented critical paths
+
+## Dependencies & Risks
+
+### Dependencies
+- None - this is documentation only
+
+### Risks
+| Risk | Mitigation |
+|------|------------|
+| File too large (>10KB) | Keep types minimal; link to types.ts for full definitions |
+| Breaking existing LLM workflows | Maintain same structure/sections; additions only |
+| Missing edge cases | SpecFlow analysis identified gaps; review against it |
+
+## Implementation Checklist
+
+### llms.txt
+
+```markdown
+# Bold Video JavaScript SDK
+
+> TypeScript client for the Bold Video API. Fetch videos, playlists, settings. Stream AI responses. Track analytics.
+
+## Installation
+
+npm install @boldvideo/bold-js
+
+## Quick Start
+
+import { createClient } from '@boldvideo/bold-js';
+
+const bold = createClient('your-api-key');
+
+// Content methods return { data: T }
+const { data: videos } = await bold.videos.list();
+const { data: video } = await bold.videos.get('video-id-or-slug');
+
+// AI streaming (default)
+const stream = await bold.ai.chat({ prompt: 'How do I price my SaaS?' });
+for await (const event of stream) {
+  switch (event.type) {
+    case 'text_delta': process.stdout.write(event.delta); break;
+    case 'sources': console.log('Found:', event.sources.length); break;
+    case 'message_complete': console.log('Done:', event.conversationId); break;
+    case 'error': console.error(event.message); break;
+  }
+}
+
+// AI non-streaming
+const response = await bold.ai.recommendations({
+  topics: ['sales', 'negotiation'],
+  stream: false
+});
+console.log(response.guidance);
+
+## Client Configuration
+
+createClient(apiKey: string, options?: ClientOptions)
+
+interface ClientOptions {
+  baseURL?: string;              // Default: 'https://app.boldvideo.io/api/v1/'
+  debug?: boolean;               // Log requests (default: false)
+  headers?: Record<string, string>; // Additional headers
+}
+
+## Content Methods
+
+All content methods return Promise<{ data: T }>.
+
+- bold.settings(videoLimit?) - Channel settings, menus, featured playlists
+- bold.videos.list(limit?) - List videos (default: 12)
+- bold.videos.get(id) - Get video by ID or slug
+- bold.videos.search(query) - Search videos
+- bold.playlists.list() - List playlists
+- bold.playlists.get(id) - Get playlist with videos
+
+## AI Methods
+
+All AI methods return AsyncIterable<AIEvent> (streaming) or Promise<AIResponse> (non-streaming).
+Default is streaming (stream: true).
+
+- bold.ai.chat(options: ChatOptions) - Conversational Q&A (library-wide or video-scoped)
+- bold.ai.search(options: SearchOptions) - Semantic search with AI summary
+- bold.ai.recommendations(options: RecommendationsOptions) - Topic-based video recommendations
+- bold.ai.getConversation(id: string) - Retrieve conversation history by ID
+
+Deprecated aliases (still work):
+- bold.ai.ask() -> use chat()
+- bold.ai.coach() -> use chat()
+- bold.ai.recommend() -> use recommendations()
+
+## AI Streaming Events
+
+type AIEvent =
+  | { type: "message_start"; conversationId?: string; videoId?: string }
+  | { type: "sources"; sources: Segment[] }
+  | { type: "text_delta"; delta: string }
+  | { type: "recommendations"; recommendations: Recommendation[] }
+  | { type: "message_complete";
+      conversationId?: string;
+      content: string;
+      citations: Segment[];
+      responseType: "answer" | "clarification";
+      usage?: AIUsage;
+      context?: AIContextMessage[];
+      recommendations?: Recommendation[];
+      guidance?: string }
+  | { type: "error"; code: string; message: string; retryable: boolean }
+
+## AI Options
+
+### ChatOptions
+{
+  prompt: string;              // Required
+  stream?: boolean;            // Default: true
+  videoId?: string;            // Scope to specific video
+  currentTime?: number;        // Playback position (with videoId)
+  conversationId?: string;     // Continue conversation
+  collectionId?: string;       // Filter to collection
+  tags?: string[];             // Filter by tags
+}
+
+### SearchOptions
+{
+  prompt: string;              // Required
+  stream?: boolean;            // Default: true
+  limit?: number;              // Max results
+  collectionId?: string;
+  videoId?: string;            // Search within video
+  tags?: string[];
+  context?: AIContextMessage[];
+}
+
+### RecommendationsOptions
+{
+  topics: string[];            // Required (max: 10)
+  stream?: boolean;            // Default: true
+  limit?: number;              // Max per topic (default: 5, max: 20)
+  collectionId?: string;
+  tags?: string[];
+  includeGuidance?: boolean;   // Default: true
+  context?: AIContextMessage[];
+}
+
+## Core Types
+
+### Video
+{
+  id: string;
+  slug?: string;
+  title: string;
+  description: string | null;
+  duration: number;
+  publishedAt: string;
+  playbackId: string;
+  streamUrl: string;
+  thumbnail: string;
+  tags?: string[];
+  metaData: { title: string; description: string; image: string | null };
+  chapters?: string;
+  attachments?: VideoAttachment[];
+  transcript?: { text: string; json: any };
+}
+
+### Segment (for sources/citations)
+{
+  id: string;
+  videoId: string;
+  title: string;
+  text: string;              // Transcript excerpt
+  timestamp: number;         // Start seconds
+  timestampEnd: number;      // End seconds
+  playbackId: string;
+  speaker?: string;
+  cited?: boolean;
+}
+
+### Recommendation
+{
+  topic: string;
+  videos: Array<{
+    videoId: string;
+    title: string;
+    playbackId: string;
+    relevance: number;
+    reason: string;
+  }>;
+}
+
+### Other types exported
+Playlist, Settings, Portal, MenuItem, AIResponse, AIUsage, AIContextMessage,
+Conversation, ConversationMessage, RecommendationsResponse
+
+## Error Handling
+
+### HTTP Errors
+SDK throws on non-2xx responses:
+- 401: Invalid API key
+- 403: Forbidden (check permissions)
+- 429: Rate limited (retry with backoff)
+- 500: Server error (retry)
+
+try {
+  const { data } = await bold.videos.list();
+} catch (error) {
+  if (error.response?.status === 401) {
+    console.error('Invalid API key');
+  }
+}
+
+### Streaming Errors
+Handle error events in stream:
+
+for await (const event of stream) {
+  if (event.type === 'error') {
+    console.error(`[${event.code}] ${event.message}`);
+    if (event.retryable) { /* retry logic */ }
+  }
+}
+
+## Analytics (Browser Only)
+
+These methods require browser globals (window, document, navigator).
+Do not use in Node.js.
+
+- bold.trackEvent(video, event) - Track video playback
+  video: { id, title, duration }
+  event: DOM Event (play, pause, timeupdate, loadedmetadata)
+  Note: timeupdate throttled to 5 seconds
+
+- bold.trackPageView(title: string) - Track page views
+
+## 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: https://github.com/boldvideo/bold-js/blob/main/src/lib/types.ts
+```
+
+## References & Research
+
+### Internal References
+- Current llms.txt: `/llms.txt`
+- Types source: `/src/lib/types.ts`
+- Client factory: `/src/lib/client.ts`
+- AI methods: `/src/lib/ai.ts`
+- README: `/README.md`
+
+### External References
+- [llmstxt.org specification](https://llmstxt.org/) - Official format guide
+- [llms.txt Best Practices (Rankability)](https://www.rankability.com/guides/llms-txt-best-practices/) - Implementation guide
+- [Mintlify llms.txt](https://www.mintlify.com/blog/simplifying-docs-with-llms-txt) - Platform adoption examples
+
+### Industry Adoption
+- Over 844,000 websites use llms.txt (BuiltWith, Oct 2025)
+- Anthropic, Cloudflare, Stripe all use this format