@boldvideo/bold-js 0.7.0 → 0.8.0

package/AGENTS.md

@@ -0,0 +1,105 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents working with this repository.
+
+## Project Overview
+
+This is the Bold JavaScript SDK (`@boldvideo/bold-js`) - a TypeScript client library for interacting with the Bold Video API. The SDK provides methods for fetching videos, playlists, channel settings, and tracking analytics events.
+
+## Tech Stack
+
+- Language: TypeScript 4.9+ (strict mode enabled)
+- Build Tool: tsup (outputs both ESM and CommonJS)
+- Package Manager: pnpm
+- Target: ES2020
+- Runtime: Node.js 20+
+- Dependencies: axios (only runtime dependency)
+
+## Commands
+
+```bash
+pnpm install          # Install dependencies
+pnpm run build        # Build to dist/ (ESM + CJS + type declarations)
+pnpm run lint         # Type checking with tsc
+pnpm changeset        # Create a changeset for versioning
+pnpm changeset version   # Apply changesets and bump versions
+pnpm changeset publish   # Publish to npm
+```
+
+## Project Structure
+
+```
+/src
+  index.ts              # Main entry point - exports createClient and all types
+  /lib
+    client.ts           # Client factory (createClient function)
+    fetchers.ts         # API endpoint implementations (videos, playlists, settings)
+    ai.ts               # AI streaming endpoints (coach, ask) using native fetch + SSE
+    types.ts            # TypeScript interfaces (Video, Playlist, Settings, etc.)
+    tracking.ts         # Analytics event tracking with throttling
+    constants.ts        # Shared constants (API base URLs)
+  /util
+    throttle.ts         # Rate limiting utility for high-frequency events
+/dist                   # Build output (generated)
+```
+
+## Architecture
+
+The SDK uses a **factory pattern** where `createClient(apiKey)` returns an object with namespaced methods:
+
+```typescript
+const bold = createClient('API_KEY');
+
+// Available methods:
+bold.settings()           // Fetch channel settings
+bold.videos.list()        // List latest videos
+bold.videos.get(id)       // Get single video
+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.trackEvent()         // Track video events
+bold.trackPageView()      // Track page views
+```
+
+## Code Style
+
+- Use functional patterns (factory functions, not classes)
+- Export all public types from `src/index.ts`
+- All API methods return Promises
+- Use TypeScript strict mode
+- camelCase for functions and variables
+- PascalCase for types and interfaces
+- Wrap API calls with try/catch and log errors
+
+## API Integration
+
+- Base URL: `https://app.boldvideo.io/api/v1/`
+- Authentication: API key in Authorization header
+- All responses wrapped in `{ data: T }` structure
+
+## Testing
+
+- Run `pnpm run lint` before committing
+- Ensure TypeScript compilation succeeds with no errors
+- No test framework currently configured - manual testing required
+
+## Boundaries
+
+**Always:**
+- Ensure TypeScript types are properly defined in `types.ts`
+- Support both ESM and CommonJS consumers
+- Follow existing patterns in the codebase
+- Run `pnpm run lint` before committing
+- Keep the SDK lightweight (minimal dependencies)
+
+**Ask first:**
+- Adding new dependencies
+- Changing the public API surface
+- Major architectural changes
+
+**Never:**
+- Commit API keys or secrets
+- Remove or change existing public type exports without versioning
+- Add test files without setting up a test framework first

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @boldvideo/bold-js
 
+## 0.8.0
+
+### Minor Changes
+
+- b0c770d: Add streaming AI endpoints
+
+  - `bold.ai.coach()` - Library-wide RAG assistant with conversation support
+  - `bold.ai.ask()` - Video-specific Q&A
+
+  Both return `AsyncIterable<CoachEvent>` for type-safe streaming. New types: `CoachEvent`, `CoachOptions`, `AskOptions`, `Citation`, `Usage`.
+
+  Also includes:
+
+  - Custom headers support via `createClient(key, { headers })`
+  - Exported `DEFAULT_API_BASE_URL` constant
+
+## 0.7.1
+
+### Patch Changes
+
+- Fix: Add thoughts directory to .npmignore to prevent publishing internal planning files
+
 ## 0.7.0
 
 ### Minor Changes

package/llms.txt

@@ -0,0 +1,45 @@
+# Bold Video JavaScript SDK
+
+> TypeScript client for the Bold Video API. Fetch videos, playlists, settings. Stream AI responses. Track analytics.
+
+## Quick Start
+
+```typescript
+import { createClient } from '@boldvideo/bold-js';
+
+const bold = createClient('your-api-key');
+
+// Fetch videos
+const videos = await bold.videos.list();
+const video = await bold.videos.get('video-id');
+
+// AI streaming
+const stream = await bold.ai.coach({ message: "How do I price my SaaS?" });
+for await (const event of stream) {
+  if (event.type === 'token') process.stdout.write(event.content);
+}
+```
+
+## API Reference
+
+- `createClient(apiKey, options?)` - Create SDK instance
+- `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
+- `bold.trackPageView(data)` - Track page views
+
+## Types
+
+Key types exported: `Video`, `Playlist`, `Settings`, `Portal`, `CoachEvent`, `CoachOptions`, `AskOptions`, `Citation`
+
+## Links
+
+- [GitHub](https://github.com/boldvideo/bold-js)
+- [npm](https://www.npmjs.com/package/@boldvideo/bold-js)
+- [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": "0.7.0",
+  "version": "0.8.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,7 @@
     "axios": "^1.3.6"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "build": "tsup src/index.ts --format cjs,esm --dts --target es2020",
     "lint": "tsc"
   }
 }

package/dist/index.cjs

@@ -1,299 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __defProps = Object.defineProperties;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
-    }
-  return a;
-};
-var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __async = (__this, __arguments, generator) => {
-  return new Promise((resolve, reject) => {
-    var fulfilled = (value) => {
-      try {
-        step(generator.next(value));
-      } catch (e) {
-        reject(e);
-      }
-    };
-    var rejected = (value) => {
-      try {
-        step(generator.throw(value));
-      } catch (e) {
-        reject(e);
-      }
-    };
-    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
-    step((generator = generator.apply(__this, __arguments)).next());
-  });
-};
-
-// src/index.ts
-var src_exports = {};
-__export(src_exports, {
-  createClient: () => createClient
-});
-module.exports = __toCommonJS(src_exports);
-
-// src/lib/client.ts
-var import_axios = __toESM(require("axios"), 1);
-
-// src/lib/fetchers.ts
-function get(client, url) {
-  return __async(this, null, function* () {
-    try {
-      const res = yield client.get(url);
-      if (res.status !== 200) {
-        throw new Error(`Unexpected response status: ${res.status}`);
-      }
-      return res.data;
-    } catch (error) {
-      console.error(`Error fetching data from URL: ${url}`, error);
-      throw error;
-    }
-  });
-}
-function fetchSettings(client) {
-  return (videoLimit = 12) => __async(this, null, function* () {
-    try {
-      return yield get(
-        client,
-        `settings?limit=${videoLimit}`
-      );
-    } catch (error) {
-      console.error(`Error fetching settings with limit: ${videoLimit}`, error);
-      throw error;
-    }
-  });
-}
-function fetchVideos(client) {
-  return (videoLimit = 12) => __async(this, null, function* () {
-    try {
-      return yield get(
-        client,
-        `videos/latest?limit=${videoLimit}`
-      );
-    } catch (error) {
-      console.error(`Error fetching videos with limit: ${videoLimit}`, error);
-      throw error;
-    }
-  });
-}
-function searchVideos(client) {
-  return (term) => __async(this, null, function* () {
-    try {
-      return yield get(client, `videos?query=${term}`);
-    } catch (error) {
-      console.error(`Error searching for videos with term: ${term}`, error);
-      throw error;
-    }
-  });
-}
-function fetchVideo(client) {
-  return (id) => __async(this, null, function* () {
-    try {
-      return yield get(client, `videos/${id}`);
-    } catch (error) {
-      console.error(`Error fetching video with ID: ${id}`, error);
-      throw error;
-    }
-  });
-}
-function fetchPlaylists(client) {
-  return () => __async(this, null, function* () {
-    try {
-      return yield get(client, "playlists");
-    } catch (error) {
-      console.error("Error fetching playlists", error);
-      throw error;
-    }
-  });
-}
-function fetchPlaylist(client) {
-  return (id) => __async(this, null, function* () {
-    try {
-      return yield get(client, `playlists/${id}`);
-    } catch (error) {
-      console.error(`Error fetching playlist with ID: ${id}`, error);
-      throw error;
-    }
-  });
-}
-
-// src/util/throttle.ts
-var throttle = (fn, delay) => {
-  let wait = false;
-  let timeout;
-  let cancelled = false;
-  return [
-    (...args) => {
-      if (cancelled)
-        return void 0;
-      if (wait)
-        return void 0;
-      const val = fn(...args);
-      wait = true;
-      timeout = window.setTimeout(() => {
-        wait = false;
-      }, delay);
-      return val;
-    },
-    () => {
-      cancelled = true;
-      clearTimeout(timeout);
-    }
-  ];
-};
-
-// src/lib/tracking.ts
-function sendEvent(client, eventName, data, debug) {
-  const payload = {
-    n: eventName,
-    u: data.url,
-    usr: data.userId,
-    d: data.domain,
-    ua: data.userAgent,
-    w: data.deviceWidth,
-    vid: (data == null ? void 0 : data.videoId) || void 0,
-    vt: data.title,
-    vdur: (data == null ? void 0 : data.videoDuration) || void 0,
-    time: (data == null ? void 0 : data.currentTime) || void 0
-  };
-  if (debug)
-    console.log(`Bold SDK - Logging event '${eventName}'`, payload);
-  client.post("/event", payload);
-}
-var [throttledSendEvent] = throttle(sendEvent, 5e3);
-function trackEvent(client, userId, options) {
-  return (video, event) => {
-    var _a;
-    const eventDetails = __spreadProps(__spreadValues({}, basicInfos()), {
-      userId,
-      videoId: video.id,
-      title: video.title,
-      videoDuration: video.duration,
-      currentTime: ((_a = event.target) == null ? void 0 : _a.currentTime) || 0
-    });
-    if (event.type == "timeupdate" || event.type == "time-update") {
-      throttledSendEvent(
-        client,
-        getEventName(event),
-        eventDetails,
-        options.debug
-      );
-    } else {
-      sendEvent(client, getEventName(event), eventDetails, options.debug);
-    }
-  };
-}
-function trackPageView(client, userId, options) {
-  return (title) => {
-    const eventDetails = __spreadProps(__spreadValues({}, basicInfos()), {
-      userId,
-      title
-    });
-    sendEvent(client, "page_view", eventDetails, options.debug);
-  };
-}
-function getEventName(event) {
-  switch (event.type) {
-    case "pause":
-      return "video_pause";
-    case "play":
-      return "video_resume";
-    case "loadedmetadata":
-    case "loaded-metadata":
-      return "video_load";
-    case "time-update":
-    case "timeupdate":
-      return "video_progress";
-    default:
-      return "unknown_event";
-  }
-}
-function basicInfos() {
-  return {
-    url: location.href,
-    domain: location.hostname,
-    referrer: document.referrer || null,
-    deviceWidth: window.innerWidth,
-    userAgent: navigator.userAgent
-  };
-}
-
-// src/lib/client.ts
-function createClient(apiKey, options = { debug: false }) {
-  var _a;
-  if (!apiKey || typeof apiKey !== "string") {
-    throw new Error("API key is missing or invalid");
-  }
-  const { debug } = options;
-  const apiClientOptions = {
-    baseURL: (_a = options.baseURL) != null ? _a : "https://app.boldvideo.io/api/v1/",
-    headers: {
-      Authorization: apiKey
-    }
-  };
-  let apiClient;
-  try {
-    apiClient = import_axios.default.create(apiClientOptions);
-  } catch (error) {
-    console.error("Error creating API client", error);
-    throw error;
-  }
-  const userId = [...Array(30)].map(() => Math.random().toString(36)[2]).join("");
-  return {
-    settings: fetchSettings(apiClient),
-    videos: {
-      list: fetchVideos(apiClient),
-      get: fetchVideo(apiClient),
-      search: searchVideos(apiClient)
-    },
-    playlists: {
-      list: fetchPlaylists(apiClient),
-      get: fetchPlaylist(apiClient)
-    },
-    trackEvent: trackEvent(apiClient, userId, { debug }),
-    trackPageView: trackPageView(apiClient, userId, { debug })
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  createClient
-});

package/dist/index.d.ts

@@ -1,197 +0,0 @@
-type VideoAttachment = {
-    id: string;
-    title: string;
-    file_url: string;
-    file_size?: number;
-    file_type?: string;
-};
-type VideoDownloadUrls = {
-    mp4?: string;
-    audio?: string;
-    legacy_mp4?: string;
-};
-type VideoSubtitles = {
-    label: string;
-    url: string;
-    engine?: string;
-    language: string;
-};
-type VideoTranscript = {
-    text: string;
-    json: any;
-};
-type VideoMetadata = {
-    description: string;
-    title: string;
-    image: string | null;
-};
-type Video = {
-    captions: string;
-    captions_label: string;
-    captions_lang: string;
-    description: string | null;
-    duration: number;
-    id: string;
-    imported_from: string | null;
-    legacy_video_url: string | null;
-    playback_id: string;
-    published_at: string;
-    stream_url: string;
-    teaser: string | null;
-    thumbnail: string;
-    title: string;
-    type: string;
-    meta_data: VideoMetadata;
-    chapters?: string;
-    attachments?: VideoAttachment[];
-    cta?: any | null;
-    download_urls?: VideoDownloadUrls;
-    internal_id?: string;
-    playback_speed?: number;
-    subtitles?: VideoSubtitles;
-    tags?: string[];
-    transcript?: VideoTranscript;
-};
-type Playlist = {
-    description?: string;
-    id: string;
-    is_private: boolean;
-    title: string;
-    type: string;
-    videos: Video[];
-};
-type MenuItem = {
-    icon: string;
-    is_ext: boolean;
-    label: string;
-    url: string;
-};
-type PortalDisplay = {
-    show_chapters: boolean;
-    show_transcripts: boolean;
-};
-type AssistantConfig = {
-    headline: string;
-    subheadline: string;
-    suggestions: string[];
-};
-type PortalLayout = {
-    assistant_config: AssistantConfig | null;
-    show_playlists: boolean;
-    type: string;
-    videos_limit: number;
-};
-type PortalNavigation = {
-    show_ai_search: boolean;
-    show_header: boolean;
-    show_search: boolean;
-};
-type PortalTheme = {
-    background: string;
-    font_body: string;
-    font_header: string;
-    foreground: string;
-    logo_height: number;
-    logo_url: string;
-    logo_width: number;
-    primary: string;
-};
-type Portal = {
-    color_scheme?: 'toggle' | 'light' | 'dark';
-    display: PortalDisplay;
-    layout: PortalLayout;
-    navigation: PortalNavigation;
-    theme: PortalTheme;
-};
-type ThemeColors = {
-    background: string;
-    border: string;
-    card: string;
-    "card-foreground": string;
-    destructive: string;
-    "destructive-foreground": string;
-    foreground: string;
-    input: string;
-    muted: string;
-    "muted-foreground": string;
-    popover: string;
-    "popover-foreground": string;
-    primary: string;
-    "primary-foreground": string;
-    ring: string;
-    secondary: string;
-    "secondary-foreground": string;
-};
-type ThemeConfig = {
-    dark: ThemeColors;
-    light: ThemeColors;
-    radius: string;
-};
-type AccountAI = {
-    avatar_url: string;
-    enabled: boolean;
-    greeting: string;
-    name: string;
-};
-type Account = {
-    ai: AccountAI;
-    name: string;
-    slug: string;
-};
-type Settings = {
-    featured_playlists: Playlist[];
-    menu_items: MenuItem[];
-    ai_avatar: string;
-    ai_name: string;
-    ai_greeting?: string;
-    has_ai: boolean;
-    account: Account;
-    favicon_url?: string;
-    logo_dark_url?: string;
-    logo_url?: string;
-    meta_data: {
-        channel_name: string;
-        description: string;
-        image: string | null;
-        no_seo: boolean;
-        social_graph_image_url?: string;
-        title: string;
-        title_suffix: string;
-    };
-    portal: Portal;
-    theme_config: ThemeConfig;
-    version: string;
-};
-
-type ClientOptions = {
-    baseURL?: string;
-    debug: boolean;
-};
-declare function createClient(apiKey: string, options?: ClientOptions): {
-    settings: (videoLimit?: number) => Promise<{
-        data: Settings;
-    }>;
-    videos: {
-        list: (videoLimit?: number) => Promise<{
-            data: Video[];
-        }>;
-        get: (id: string) => Promise<{
-            data: Video;
-        }>;
-        search: (term: string) => Promise<{
-            data: Video[];
-        }>;
-    };
-    playlists: {
-        list: () => Promise<{
-            data: Playlist[];
-        }>;
-        get: (id: string) => Promise<{
-            data: Playlist;
-        }>;
-    };
-    trackEvent: (video: any, event: Event) => void;
-    trackPageView: (title: string) => void;
-};
-
-export { Account, AccountAI, AssistantConfig, MenuItem, Playlist, Portal, PortalDisplay, PortalLayout, PortalNavigation, PortalTheme, Settings, ThemeColors, ThemeConfig, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, createClient };