@boldvideo/bold-js 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @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

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');
@@ -357,7 +375,10 @@ import type {
   Viewer,
   ViewerProgress,
   ViewerLookupParams,
-  ListProgressOptions
+  ListProgressOptions,
+  ListVideosOptions,
+  ListVideosLatestOptions,
+  ListVideosIndexOptions
 } from '@boldvideo/bold-js';
 ```
 

package/dist/index.cjs

@@ -64,6 +64,15 @@ function camelizeKeys(input, options = {}) {
 }
 
 // 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);
@@ -90,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;
     }
   };

package/dist/index.d.ts

@@ -473,6 +473,44 @@ type ProgressListMeta = {
     /** 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
@@ -609,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<{
@@ -668,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, CreateViewerData, CustomRedirect, DEFAULT_API_BASE_URL, DEFAULT_INTERNAL_API_BASE_URL, ListProgressOptions, 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 };
+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 };

package/dist/index.js

@@ -25,6 +25,15 @@ function camelizeKeys(input, options = {}) {
 }
 
 // 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);
@@ -51,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;
     }
   };

package/llms.txt

@@ -55,12 +55,35 @@ interface ClientOptions {
 All content methods return `Promise<{ data: T }>`.
 
 - `bold.settings(videoLimit?)` - Channel settings, menus, featured playlists
-- `bold.videos.list(limit?)` - List videos (default limit: 12)
+- `bold.videos.list()` - List latest videos (default limit: 12)
+- `bold.videos.list(limit)` - List with numeric limit (backwards compatible)
+- `bold.videos.list(options)` - List with full options (see ListVideosOptions)
 - `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
 
+### ListVideosOptions
+
+```typescript
+// For /videos/latest endpoint (default)
+{
+  limit?: number;           // Max videos (default: 12)
+  tag?: string;             // Filter by tag
+  collectionId?: string;    // Filter to collection
+  viewerId?: string;        // Include watch progress
+}
+
+// For /videos (index) endpoint - use when you need pagination
+{
+  page?: number;            // Page number
+  tag?: string;
+  collectionId?: string;
+}
+```
+
+Note: If `page` is provided, SDK uses `/videos` (index); otherwise uses `/videos/latest`.
+
 ## Viewers API
 
 Manage external users and track video progress. Returns `Promise<{ data: T }>` (consistent with other SDK methods).
@@ -254,7 +277,7 @@ type AIEvent =
 
 ### Other types exported
 
-`Playlist`, `Settings`, `Portal`, `MenuItem`, `AIResponse`, `AIUsage`, `AIContextMessage`, `Conversation`, `ConversationMessage`, `RecommendationsResponse`, `Viewer`, `ViewerProgress`, `ViewerLookupParams`, `ListProgressOptions`
+`Playlist`, `Settings`, `Portal`, `MenuItem`, `AIResponse`, `AIUsage`, `AIContextMessage`, `Conversation`, `ConversationMessage`, `RecommendationsResponse`, `Viewer`, `ViewerProgress`, `ViewerLookupParams`, `ListProgressOptions`, `ListVideosOptions`, `ListVideosLatestOptions`, `ListVideosIndexOptions`
 
 ## Error Handling
 

package/package.json

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