@boldvideo/bold-js 1.15.2 → 1.17.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @boldvideo/bold-js
 
+## 1.17.0
+
+### Minor Changes
+
+- 563730d: Add full options support to `videos.list()` for tag, collectionId, viewerId, and page filtering
+
+  **New features:**
+
+  - Filter videos by `tag` and `collectionId` on both endpoints
+  - Include watch progress with `viewerId` parameter
+  - Access paginated `/videos` endpoint using `page` parameter
+
+  **Usage:**
+
+  ```typescript
+  // Latest videos with filters
+  await bold.videos.list({ limit: 20, tag: "sales", collectionId: "col_123" });
+
+  // Include viewer watch progress
+  await bold.videos.list({ limit: 20, viewerId: "viewer_123" });
+
+  // Paginated index (uses /videos endpoint)
+  await bold.videos.list({ page: 2, tag: "sales" });
+  ```
+
+  **Breaking:** None. Existing `bold.videos.list()` and `bold.videos.list(12)` calls work unchanged.
+
+## 1.16.0
+
+### Minor Changes
+
+- 06c8abc: Add Viewers API for managing external users and tracking video progress
+
+  New methods on the `viewers` namespace:
+
+  - `viewers.list()` - List all viewers
+  - `viewers.get(id)` - Get a viewer by ID
+  - `viewers.lookup({ externalId } | { email })` - Find viewer by external ID or email
+  - `viewers.create(data)` - Create a new viewer
+  - `viewers.update(id, data)` - Update a viewer
+  - `viewers.listProgress(viewerId, options?)` - List progress for a viewer
+  - `viewers.getProgress(viewerId, videoId)` - Get progress for a video
+  - `viewers.saveProgress(viewerId, videoId, data)` - Save/update progress
+
+  Also fixes `camelizeKeys` to preserve user-defined trait keys (e.g., `company_name` stays as-is instead of becoming `companyName`).
+
 ## 1.15.2
 
 ### Patch Changes

package/README.md

@@ -59,9 +59,27 @@ console.log(recs.guidance);
 ### Videos
 
 ```typescript
-// List latest videos
+// List latest videos (default: 12)
 const videos = await bold.videos.list();
 
+// With limit (backwards compatible)
+const videos = await bold.videos.list(20);
+
+// With filters
+const videos = await bold.videos.list({ 
+  limit: 20,
+  tag: 'sales',
+  collectionId: 'col_123',
+  viewerId: 'viewer_123'  // Include watch progress
+});
+
+// Paginated index (uses /videos endpoint)
+const videos = await bold.videos.list({ 
+  page: 2,
+  tag: 'sales',
+  collectionId: 'col_123'
+});
+
 // Get a single video by ID or slug
 const video = await bold.videos.get('video-id');
 const videoBySlug = await bold.videos.get('my-video-slug');
@@ -101,6 +119,65 @@ settings.menuItems.forEach(item => {
 
 ---
 
+## Viewers API
+
+Manage external users and track their video watch progress. Ideal for course platforms integrating with Bold Video.
+
+### Viewer Management
+
+```typescript
+// Create a viewer (e.g., when user signs up)
+const { data: viewer } = await bold.viewers.create({
+  name: 'John Doe',
+  externalId: 'user_123',  // Your platform's user ID
+  email: 'john@example.com',
+  traits: { plan: 'pro', company_name: 'Acme Inc' }
+});
+
+// Find viewer by external ID (common for syncing users)
+const { data: viewer } = await bold.viewers.lookup({ externalId: 'user_123' });
+
+// Or find by email
+const { data: viewer } = await bold.viewers.lookup({ email: 'john@example.com' });
+
+// Update viewer
+await bold.viewers.update(viewer.id, { 
+  traits: { plan: 'enterprise' }  // Note: traits are replaced, not merged
+});
+
+// List all viewers
+const { data: viewers } = await bold.viewers.list();
+```
+
+### Progress Tracking
+
+```typescript
+// Save progress as video plays (call every 5-10 seconds)
+await bold.viewers.saveProgress(viewerId, videoId, {
+  currentTime: 120,  // seconds
+  duration: 600      // total video duration
+});
+
+// Mark video complete by setting currentTime = duration
+await bold.viewers.saveProgress(viewerId, videoId, {
+  currentTime: 600,
+  duration: 600
+});
+
+// Get progress for a specific video
+const { data: progress } = await bold.viewers.getProgress(viewerId, videoId);
+console.log(`${progress.percentage}% complete`);
+
+// List all progress for a viewer (e.g., for a course dashboard)
+const { data: progress, meta } = await bold.viewers.listProgress(viewerId, {
+  collectionId: 'course-collection-id',  // Filter to a course
+  completed: false  // Only in-progress videos
+});
+console.log(`Completed ${meta.completed} of ${meta.total} videos`);
+```
+
+---
+
 ## AI Methods
 
 All AI methods support both streaming (default) and non-streaming modes.
@@ -294,7 +371,14 @@ import type {
   Recommendation,
   Conversation,
   ConversationMessage,
-  Source
+  Source,
+  Viewer,
+  ViewerProgress,
+  ViewerLookupParams,
+  ListProgressOptions,
+  ListVideosOptions,
+  ListVideosLatestOptions,
+  ListVideosIndexOptions
 } from '@boldvideo/bold-js';
 ```
 

package/dist/index.cjs

@@ -32,19 +32,21 @@ var src_exports = {};
 __export(src_exports, {
   DEFAULT_API_BASE_URL: () => DEFAULT_API_BASE_URL,
   DEFAULT_INTERNAL_API_BASE_URL: () => DEFAULT_INTERNAL_API_BASE_URL,
+  ViewerAPIError: () => ViewerAPIError,
   createClient: () => createClient
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/lib/client.ts
-var import_axios = __toESM(require("axios"), 1);
+var import_axios2 = __toESM(require("axios"), 1);
 
 // 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;
@@ -52,12 +54,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);
@@ -84,14 +99,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;
     }
   };
@@ -137,6 +182,154 @@ function fetchPlaylist(client) {
   };
 }
 
+// src/lib/viewers.ts
+var import_axios = require("axios");
+var VIEWER_CAMELIZE_OPTIONS = { preserveKeys: ["traits"] };
+var ViewerAPIError = class extends Error {
+  constructor(method, url, error) {
+    var __super = (...args) => {
+      super(...args);
+    };
+    if (error instanceof import_axios.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;
@@ -438,7 +631,7 @@ function createClient(apiKey, options = {}) {
   };
   let apiClient;
   try {
-    apiClient = import_axios.default.create(apiClientOptions);
+    apiClient = import_axios2.default.create(apiClientOptions);
   } catch (error) {
     console.error("Error creating API client", error);
     throw error;
@@ -459,6 +652,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 })
@@ -468,5 +671,6 @@ function createClient(apiKey, options = {}) {
 0 && (module.exports = {
   DEFAULT_API_BASE_URL,
   DEFAULT_INTERNAL_API_BASE_URL,
+  ViewerAPIError,
   createClient
 });

package/dist/index.d.ts

@@ -390,6 +390,127 @@ interface Conversation {
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Viewer represents an external user from a course platform
+ */
+type Viewer = {
+    id: string;
+    name: string;
+    email?: string;
+    externalId?: string;
+    /** Key-value metadata. Keys must start with letter/underscore, contain only alphanumeric/underscore */
+    traits?: Record<string, unknown>;
+    insertedAt: string;
+    updatedAt: string;
+};
+/**
+ * Progress record for a viewer-video pair
+ */
+type ViewerProgress = {
+    id: string;
+    viewerId: string;
+    videoId: string;
+    /** Current playback position in seconds */
+    currentTime: number;
+    /** Total video duration in seconds */
+    duration: number;
+    /** Calculated: (currentTime / duration) * 100 */
+    percentage: number;
+    completed: boolean;
+    completedAt?: string;
+    insertedAt: string;
+    updatedAt: string;
+};
+/**
+ * Options for listing viewer progress
+ */
+type ListProgressOptions = {
+    /** Filter by completion status */
+    completed?: boolean;
+    /** Filter to videos in a specific collection */
+    collectionId?: string;
+};
+/**
+ * Data for creating a new viewer
+ */
+type CreateViewerData = {
+    /** Display name (required) */
+    name: string;
+    /** Email address for lookup */
+    email?: string;
+    /** Your platform's user ID for lookup */
+    externalId?: string;
+    /** Key-value metadata. Keys must start with letter/underscore, contain only alphanumeric/underscore */
+    traits?: Record<string, unknown>;
+};
+/**
+ * Data for updating an existing viewer
+ */
+type UpdateViewerData = {
+    name?: string;
+    email?: string;
+    externalId?: string;
+    /** Note: traits are replaced entirely, not merged */
+    traits?: Record<string, unknown>;
+};
+/**
+ * Data for saving video progress
+ */
+type SaveProgressData = {
+    /** Current playback position in seconds (must be non-negative) */
+    currentTime: number;
+    /** Total video duration in seconds (must be positive) */
+    duration: number;
+};
+/**
+ * Metadata returned with progress list
+ */
+type ProgressListMeta = {
+    /** Total number of progress records */
+    total: number;
+    /** Number of completed videos */
+    completed: number;
+    /** Number of in-progress videos */
+    inProgress: number;
+};
+/**
+ * Options for listing videos from /videos/latest endpoint
+ */
+type ListVideosLatestOptions = {
+    /** Max videos to return (default: 12) */
+    limit?: number;
+    /** Filter by tag */
+    tag?: string;
+    /** Filter to videos in a specific collection */
+    collectionId?: string;
+    /** Viewer UUID for watch progress */
+    viewerId?: string;
+};
+/**
+ * Options for listing videos from /videos (index) endpoint with pagination
+ */
+type ListVideosIndexOptions = {
+    /** Page number for pagination */
+    page?: number;
+    /** Filter by tag */
+    tag?: string;
+    /** Filter to videos in a specific collection */
+    collectionId?: string;
+};
+/**
+ * Combined options for bold.videos.list()
+ *
+ * If `page` is provided, uses /videos (index) endpoint.
+ * Otherwise, uses /videos/latest endpoint.
+ *
+ * Note: `page` and `limit`/`viewerId` are mutually exclusive.
+ */
+type ListVideosOptions = (ListVideosLatestOptions & {
+    page?: never;
+}) | (ListVideosIndexOptions & {
+    limit?: never;
+    viewerId?: never;
+});
 
 /**
  * AI client interface for type-safe method overloading
@@ -503,6 +624,19 @@ interface AIClient {
     getConversation(conversationId: string): Promise<Conversation>;
 }
 
+declare class ViewerAPIError extends Error {
+    readonly status?: number;
+    readonly originalError?: Error;
+    constructor(method: string, url: string, error: unknown);
+}
+type ViewerLookupParams = {
+    externalId: string;
+    email?: never;
+} | {
+    email: string;
+    externalId?: never;
+};
+
 type ClientOptions = {
     baseURL?: string;
     debug?: boolean;
@@ -513,7 +647,7 @@ declare function createClient(apiKey: string, options?: ClientOptions): {
         data: Settings;
     }>;
     videos: {
-        list: (videoLimit?: number) => Promise<{
+        list: (arg?: number | ListVideosOptions) => Promise<{
             data: Video[];
         }>;
         get: (id: string) => Promise<{
@@ -531,6 +665,33 @@ declare function createClient(apiKey: string, options?: ClientOptions): {
             data: Playlist;
         }>;
     };
+    viewers: {
+        list: () => Promise<{
+            data: Viewer[];
+        }>;
+        get: (id: string) => Promise<{
+            data: Viewer;
+        }>;
+        lookup: (params: ViewerLookupParams) => Promise<{
+            data: Viewer;
+        }>;
+        create: (data: CreateViewerData) => Promise<{
+            data: Viewer;
+        }>;
+        update: (id: string, data: UpdateViewerData) => Promise<{
+            data: Viewer;
+        }>;
+        listProgress: (viewerId: string, options?: ListProgressOptions | undefined) => Promise<{
+            data: ViewerProgress[];
+            meta: ProgressListMeta;
+        }>;
+        getProgress: (viewerId: string, videoId: string) => Promise<{
+            data: ViewerProgress;
+        }>;
+        saveProgress: (viewerId: string, videoId: string, data: SaveProgressData) => Promise<{
+            data: ViewerProgress;
+        }>;
+    };
     ai: AIClient;
     trackEvent: (video: any, event: Event) => void;
     trackPageView: (title: string) => void;
@@ -545,4 +706,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, AnalyticsProvider, AskOptions, AssistantConfig, ChatOptions, Citation, ClientOptions, Conversation, ConversationMessage, ConversationMetadata, CustomRedirect, DEFAULT_API_BASE_URL, DEFAULT_INTERNAL_API_BASE_URL, MenuItem, Playlist, Portal, PortalDisplay, PortalHero, PortalLayout, PortalNavigation, PortalTheme, RecommendOptions, RecommendResponse, Recommendation, RecommendationVideo, RecommendationsOptions, RecommendationsResponse, SearchOptions, Segment, Settings, Source, ThemeColors, ThemeConfig, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, createClient };
+export { AIContextMessage, AIEvent, AIResponse, AIUsage, Account, AccountAI, AnalyticsProvider, AskOptions, AssistantConfig, ChatOptions, Citation, ClientOptions, Conversation, ConversationMessage, ConversationMetadata, CreateViewerData, CustomRedirect, DEFAULT_API_BASE_URL, DEFAULT_INTERNAL_API_BASE_URL, ListProgressOptions, ListVideosIndexOptions, ListVideosLatestOptions, ListVideosOptions, MenuItem, Playlist, Portal, PortalDisplay, PortalHero, PortalLayout, PortalNavigation, PortalTheme, ProgressListMeta, RecommendOptions, RecommendResponse, Recommendation, RecommendationVideo, RecommendationsOptions, RecommendationsResponse, SaveProgressData, SearchOptions, Segment, Settings, Source, ThemeColors, ThemeConfig, UpdateViewerData, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, Viewer, ViewerAPIError, ViewerLookupParams, ViewerProgress, createClient };