@boldvideo/bold-js 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @boldvideo/bold-js
 
+## 1.18.0
+
+### Minor Changes
+
+- 48d8b40: Add Community API for posts, comments, and reactions
+
+  New `bold.community` namespace with full CRUD operations:
+
+  **Posts:**
+
+  - `bold.community.posts.list(opts?)` - List posts with category/limit/offset filters
+  - `bold.community.posts.get(id, viewerId?)` - Get single post with comments
+  - `bold.community.posts.create(viewerId, data)` - Create a post (markdown supported)
+  - `bold.community.posts.update(viewerId, id, data)` - Update post (owner/admin only)
+  - `bold.community.posts.delete(viewerId, id)` - Delete post (owner/admin only)
+  - `bold.community.posts.react(viewerId, id)` - Toggle reaction (like/unlike)
+
+  **Comments:**
+
+  - `bold.community.comments.create(viewerId, postId, data)` - Create comment with optional `parentId` for nested replies
+  - `bold.community.comments.delete(viewerId, id)` - Delete comment (owner/admin only)
+  - `bold.community.comments.react(viewerId, id)` - Toggle reaction
+
+  **New Types:**
+
+  - `Post`, `PostAuthor`, `Comment`, `ReactionResponse`
+  - `ListPostsOptions`, `CreatePostData`, `UpdatePostData`, `CreateCommentData`
+  - `CommunityAPIError` - Error class for Community API operations
+
+## 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');
@@ -160,6 +178,69 @@ console.log(`Completed ${meta.completed} of ${meta.total} videos`);
 
 ---
 
+## Community API
+
+Build community features with posts, comments, and reactions. All write operations require a `viewerId` (the viewer performing the action).
+
+### Posts
+
+```typescript
+// List posts (optionally filter by category)
+const { data: posts } = await bold.community.posts.list({ 
+  category: 'announcements',
+  limit: 20,
+  offset: 0,
+  viewerId: 'viewer-uuid'  // Include viewerReacted in response
+});
+
+// Get a single post with comments
+const { data: post } = await bold.community.posts.get('post-id', 'viewer-uuid');
+
+// Create a post (requires viewerId)
+const { data: newPost } = await bold.community.posts.create('viewer-uuid', {
+  content: 'Hello community! **Markdown** supported.',
+  category: 'general'
+});
+
+// Update a post (owner or admin only)
+await bold.community.posts.update('viewer-uuid', 'post-id', {
+  content: 'Updated content'
+});
+
+// Delete a post (owner or admin only)
+await bold.community.posts.delete('viewer-uuid', 'post-id');
+
+// React to a post (toggle like/unlike)
+const reaction = await bold.community.posts.react('viewer-uuid', 'post-id');
+console.log(reaction.reacted, reaction.reactionsCount);
+```
+
+### Comments
+
+```typescript
+// Create a comment on a post
+const { data: comment } = await bold.community.comments.create(
+  'viewer-uuid',
+  'post-id',
+  { content: 'Great post!' }
+);
+
+// Reply to a comment (nested)
+const { data: reply } = await bold.community.comments.create(
+  'viewer-uuid',
+  'post-id',
+  { content: 'I agree!', parentId: 'parent-comment-id' }
+);
+
+// Delete a comment (owner or admin only)
+await bold.community.comments.delete('viewer-uuid', 'comment-id');
+
+// React to a comment (toggle)
+const reaction = await bold.community.comments.react('viewer-uuid', 'comment-id');
+```
+
+---
+
 ## AI Methods
 
 All AI methods support both streaming (default) and non-streaming modes.
@@ -357,7 +438,19 @@ import type {
   Viewer,
   ViewerProgress,
   ViewerLookupParams,
-  ListProgressOptions
+  ListProgressOptions,
+  ListVideosOptions,
+  ListVideosLatestOptions,
+  ListVideosIndexOptions,
+  // Community API
+  Post,
+  PostAuthor,
+  Comment,
+  ReactionResponse,
+  ListPostsOptions,
+  CreatePostData,
+  UpdatePostData,
+  CreateCommentData
 } from '@boldvideo/bold-js';
 ```
 

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  CommunityAPIError: () => CommunityAPIError,
   DEFAULT_API_BASE_URL: () => DEFAULT_API_BASE_URL,
   DEFAULT_INTERNAL_API_BASE_URL: () => DEFAULT_INTERNAL_API_BASE_URL,
   ViewerAPIError: () => ViewerAPIError,
@@ -38,7 +39,7 @@ __export(src_exports, {
 module.exports = __toCommonJS(src_exports);
 
 // src/lib/client.ts
-var import_axios2 = __toESM(require("axios"), 1);
+var import_axios3 = __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);
@@ -64,6 +65,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 +100,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;
     }
   };
@@ -291,6 +331,188 @@ function saveProgress(client) {
   };
 }
 
+// src/lib/community.ts
+var import_axios2 = require("axios");
+var CommunityAPIError = class extends Error {
+  constructor(method, url, error) {
+    var __super = (...args) => {
+      super(...args);
+    };
+    if (error instanceof import_axios2.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 = "CommunityAPIError";
+  }
+};
+function requireViewerId(viewerId) {
+  if (!viewerId)
+    throw new Error("Viewer ID is required (X-Viewer-ID)");
+}
+function viewerHeaders(viewerId) {
+  return viewerId ? { "X-Viewer-ID": viewerId } : void 0;
+}
+function toQuery2(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 get3(client, url, viewerId) {
+  try {
+    const res = await client.get(url, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("GET", url, error);
+  }
+}
+async function post2(client, url, data, viewerId) {
+  try {
+    const res = await client.post(url, data, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("POST", url, error);
+  }
+}
+async function put(client, url, data, viewerId) {
+  try {
+    const res = await client.put(url, data, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("PUT", url, error);
+  }
+}
+async function del(client, url, viewerId) {
+  try {
+    const res = await client.delete(url, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("DELETE", url, error);
+  }
+}
+function listPosts(client) {
+  return async (opts = {}) => {
+    return get3(
+      client,
+      `community/posts${toQuery2({
+        category: opts.category,
+        limit: opts.limit,
+        offset: opts.offset
+      })}`,
+      opts.viewerId
+    );
+  };
+}
+function getPost(client) {
+  return async (id, viewerId) => {
+    if (!id)
+      throw new Error("Post ID is required");
+    return get3(client, `community/posts/${id}`, viewerId);
+  };
+}
+function createPost(client) {
+  return async (viewerId, data) => {
+    requireViewerId(viewerId);
+    if (!data?.content)
+      throw new Error("Post content is required");
+    return post2(
+      client,
+      "community/posts",
+      { post: { content: data.content, category: data.category } },
+      viewerId
+    );
+  };
+}
+function updatePost(client) {
+  return async (viewerId, id, data) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Post ID is required");
+    const body = {};
+    if (data.content !== void 0)
+      body.content = data.content;
+    if (data.category !== void 0)
+      body.category = data.category;
+    return put(
+      client,
+      `community/posts/${id}`,
+      { post: body },
+      viewerId
+    );
+  };
+}
+function deletePost(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Post ID is required");
+    return del(client, `community/posts/${id}`, viewerId);
+  };
+}
+function reactToPost(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Post ID is required");
+    return post2(
+      client,
+      `community/posts/${id}/react`,
+      void 0,
+      viewerId
+    );
+  };
+}
+function createComment(client) {
+  return async (viewerId, postId, data) => {
+    requireViewerId(viewerId);
+    if (!postId)
+      throw new Error("Post ID is required");
+    if (!data?.content)
+      throw new Error("Comment content is required");
+    const body = { content: data.content };
+    if (data.parentId)
+      body.parent_id = data.parentId;
+    return post2(
+      client,
+      `community/posts/${postId}/comments`,
+      { comment: body },
+      viewerId
+    );
+  };
+}
+function deleteComment(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Comment ID is required");
+    return del(client, `community/comments/${id}`, viewerId);
+  };
+}
+function reactToComment(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Comment ID is required");
+    return post2(
+      client,
+      `community/comments/${id}/react`,
+      void 0,
+      viewerId
+    );
+  };
+}
+
 // src/util/throttle.ts
 var throttle = (fn, delay) => {
   let wait = false;
@@ -592,7 +814,7 @@ function createClient(apiKey, options = {}) {
   };
   let apiClient;
   try {
-    apiClient = import_axios2.default.create(apiClientOptions);
+    apiClient = import_axios3.default.create(apiClientOptions);
   } catch (error) {
     console.error("Error creating API client", error);
     throw error;
@@ -624,12 +846,28 @@ function createClient(apiKey, options = {}) {
       saveProgress: saveProgress(apiClient)
     },
     ai: createAI(aiConfig),
+    community: {
+      posts: {
+        list: listPosts(apiClient),
+        get: getPost(apiClient),
+        create: createPost(apiClient),
+        update: updatePost(apiClient),
+        delete: deletePost(apiClient),
+        react: reactToPost(apiClient)
+      },
+      comments: {
+        create: createComment(apiClient),
+        delete: deleteComment(apiClient),
+        react: reactToComment(apiClient)
+      }
+    },
     trackEvent: trackEvent(apiClient, userId, { debug }),
     trackPageView: trackPageView(apiClient, userId, { debug })
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CommunityAPIError,
   DEFAULT_API_BASE_URL,
   DEFAULT_INTERNAL_API_BASE_URL,
   ViewerAPIError,

package/dist/index.d.ts

@@ -473,6 +473,136 @@ 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;
+});
+/**
+ * Author information for posts and comments
+ */
+type PostAuthor = {
+    id: string;
+    name: string;
+    email?: string;
+    isAdmin: boolean;
+};
+/**
+ * A comment on a community post
+ */
+type Comment = {
+    id: string;
+    content: string;
+    /** Nesting depth (0 = top-level) */
+    depth: number;
+    reactionsCount: number;
+    /** Whether current viewer has reacted (only present when X-Viewer-ID header sent) */
+    viewerReacted?: boolean;
+    viewer: PostAuthor;
+    /** Nested replies */
+    replies: Comment[];
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * A community post
+ */
+type Post = {
+    id: string;
+    content: string;
+    category: string;
+    pinned: boolean;
+    pinnedAt?: string | null;
+    reactionsCount: number;
+    commentsCount: number;
+    /** Whether current viewer has reacted (only present when X-Viewer-ID header sent) */
+    viewerReacted?: boolean;
+    viewer: PostAuthor;
+    /** Comments (only present on single post fetch) */
+    comments?: Comment[];
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * Response from react endpoints (toggle)
+ */
+type ReactionResponse = {
+    reacted: boolean;
+    reactionsCount: number;
+};
+/**
+ * Options for listing community posts
+ */
+type ListPostsOptions = {
+    /** Filter by category (e.g., "announcements", "general") */
+    category?: string;
+    /** Max posts to return (default: 20) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** Viewer ID to include viewerReacted in response */
+    viewerId?: string;
+};
+/**
+ * Data for creating a community post
+ */
+type CreatePostData = {
+    /** Post content (supports markdown) */
+    content: string;
+    /** Category for the post */
+    category?: string;
+};
+/**
+ * Data for updating a community post
+ */
+type UpdatePostData = {
+    /** Post content (supports markdown) */
+    content?: string;
+    /** Category for the post */
+    category?: string;
+};
+/**
+ * Data for creating a comment
+ */
+type CreateCommentData = {
+    /** Comment content */
+    content: string;
+    /** Parent comment ID for replies */
+    parentId?: string;
+};
 
 /**
  * AI client interface for type-safe method overloading
@@ -609,7 +739,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<{
@@ -655,6 +785,35 @@ declare function createClient(apiKey: string, options?: ClientOptions): {
         }>;
     };
     ai: AIClient;
+    community: {
+        posts: {
+            list: (opts?: ListPostsOptions) => Promise<{
+                data: Post[];
+            }>;
+            get: (id: string, viewerId?: string | undefined) => Promise<{
+                data: Post;
+            }>;
+            create: (viewerId: string, data: CreatePostData) => Promise<{
+                data: Post;
+            }>;
+            update: (viewerId: string, id: string, data: UpdatePostData) => Promise<{
+                data: Post;
+            }>;
+            delete: (viewerId: string, id: string) => Promise<{
+                data?: unknown;
+            }>;
+            react: (viewerId: string, id: string) => Promise<ReactionResponse>;
+        };
+        comments: {
+            create: (viewerId: string, postId: string, data: CreateCommentData) => Promise<{
+                data: Comment;
+            }>;
+            delete: (viewerId: string, id: string) => Promise<{
+                data?: unknown;
+            }>;
+            react: (viewerId: string, id: string) => Promise<ReactionResponse>;
+        };
+    };
     trackEvent: (video: any, event: Event) => void;
     trackPageView: (title: string) => void;
 };
@@ -668,4 +827,13 @@ 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 };
+/**
+ * Error thrown by Community API operations
+ */
+declare class CommunityAPIError extends Error {
+    readonly status?: number;
+    readonly originalError?: Error;
+    constructor(method: string, url: string, error: unknown);
+}
+
+export { AIContextMessage, AIEvent, AIResponse, AIUsage, Account, AccountAI, AnalyticsProvider, AskOptions, AssistantConfig, ChatOptions, Citation, ClientOptions, Comment, CommunityAPIError, Conversation, ConversationMessage, ConversationMetadata, CreateCommentData, CreatePostData, CreateViewerData, CustomRedirect, DEFAULT_API_BASE_URL, DEFAULT_INTERNAL_API_BASE_URL, ListPostsOptions, ListProgressOptions, ListVideosIndexOptions, ListVideosLatestOptions, ListVideosOptions, MenuItem, Playlist, Portal, PortalDisplay, PortalHero, PortalLayout, PortalNavigation, PortalTheme, Post, PostAuthor, ProgressListMeta, ReactionResponse, RecommendOptions, RecommendResponse, Recommendation, RecommendationVideo, RecommendationsOptions, RecommendationsResponse, SaveProgressData, SearchOptions, Segment, Settings, Source, ThemeColors, ThemeConfig, UpdatePostData, 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;
     }
   };
@@ -252,6 +291,188 @@ function saveProgress(client) {
   };
 }
 
+// src/lib/community.ts
+import { AxiosError as AxiosError2 } from "axios";
+var CommunityAPIError = class extends Error {
+  constructor(method, url, error) {
+    var __super = (...args) => {
+      super(...args);
+    };
+    if (error instanceof AxiosError2) {
+      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 = "CommunityAPIError";
+  }
+};
+function requireViewerId(viewerId) {
+  if (!viewerId)
+    throw new Error("Viewer ID is required (X-Viewer-ID)");
+}
+function viewerHeaders(viewerId) {
+  return viewerId ? { "X-Viewer-ID": viewerId } : void 0;
+}
+function toQuery2(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 get3(client, url, viewerId) {
+  try {
+    const res = await client.get(url, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("GET", url, error);
+  }
+}
+async function post2(client, url, data, viewerId) {
+  try {
+    const res = await client.post(url, data, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("POST", url, error);
+  }
+}
+async function put(client, url, data, viewerId) {
+  try {
+    const res = await client.put(url, data, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("PUT", url, error);
+  }
+}
+async function del(client, url, viewerId) {
+  try {
+    const res = await client.delete(url, { headers: viewerHeaders(viewerId) });
+    return camelizeKeys(res.data);
+  } catch (error) {
+    throw new CommunityAPIError("DELETE", url, error);
+  }
+}
+function listPosts(client) {
+  return async (opts = {}) => {
+    return get3(
+      client,
+      `community/posts${toQuery2({
+        category: opts.category,
+        limit: opts.limit,
+        offset: opts.offset
+      })}`,
+      opts.viewerId
+    );
+  };
+}
+function getPost(client) {
+  return async (id, viewerId) => {
+    if (!id)
+      throw new Error("Post ID is required");
+    return get3(client, `community/posts/${id}`, viewerId);
+  };
+}
+function createPost(client) {
+  return async (viewerId, data) => {
+    requireViewerId(viewerId);
+    if (!data?.content)
+      throw new Error("Post content is required");
+    return post2(
+      client,
+      "community/posts",
+      { post: { content: data.content, category: data.category } },
+      viewerId
+    );
+  };
+}
+function updatePost(client) {
+  return async (viewerId, id, data) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Post ID is required");
+    const body = {};
+    if (data.content !== void 0)
+      body.content = data.content;
+    if (data.category !== void 0)
+      body.category = data.category;
+    return put(
+      client,
+      `community/posts/${id}`,
+      { post: body },
+      viewerId
+    );
+  };
+}
+function deletePost(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Post ID is required");
+    return del(client, `community/posts/${id}`, viewerId);
+  };
+}
+function reactToPost(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Post ID is required");
+    return post2(
+      client,
+      `community/posts/${id}/react`,
+      void 0,
+      viewerId
+    );
+  };
+}
+function createComment(client) {
+  return async (viewerId, postId, data) => {
+    requireViewerId(viewerId);
+    if (!postId)
+      throw new Error("Post ID is required");
+    if (!data?.content)
+      throw new Error("Comment content is required");
+    const body = { content: data.content };
+    if (data.parentId)
+      body.parent_id = data.parentId;
+    return post2(
+      client,
+      `community/posts/${postId}/comments`,
+      { comment: body },
+      viewerId
+    );
+  };
+}
+function deleteComment(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Comment ID is required");
+    return del(client, `community/comments/${id}`, viewerId);
+  };
+}
+function reactToComment(client) {
+  return async (viewerId, id) => {
+    requireViewerId(viewerId);
+    if (!id)
+      throw new Error("Comment ID is required");
+    return post2(
+      client,
+      `community/comments/${id}/react`,
+      void 0,
+      viewerId
+    );
+  };
+}
+
 // src/util/throttle.ts
 var throttle = (fn, delay) => {
   let wait = false;
@@ -585,11 +806,27 @@ function createClient(apiKey, options = {}) {
       saveProgress: saveProgress(apiClient)
     },
     ai: createAI(aiConfig),
+    community: {
+      posts: {
+        list: listPosts(apiClient),
+        get: getPost(apiClient),
+        create: createPost(apiClient),
+        update: updatePost(apiClient),
+        delete: deletePost(apiClient),
+        react: reactToPost(apiClient)
+      },
+      comments: {
+        create: createComment(apiClient),
+        delete: deleteComment(apiClient),
+        react: reactToComment(apiClient)
+      }
+    },
     trackEvent: trackEvent(apiClient, userId, { debug }),
     trackPageView: trackPageView(apiClient, userId, { debug })
   };
 }
 export {
+  CommunityAPIError,
   DEFAULT_API_BASE_URL,
   DEFAULT_INTERNAL_API_BASE_URL,
   ViewerAPIError,

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).
@@ -88,6 +111,33 @@ const { data: progress, meta } = await bold.viewers.listProgress(viewer.id, { co
 console.log(`Completed ${meta.completed} of ${meta.total} videos`);
 ```
 
+## Community API
+
+Build community features with posts, comments, and reactions. Write operations require `viewerId`.
+
+### Posts
+
+- `bold.community.posts.list(opts?)` - List posts with optional filters
+- `bold.community.posts.get(id, viewerId?)` - Get post with comments
+- `bold.community.posts.create(viewerId, data)` - Create a post
+- `bold.community.posts.update(viewerId, id, data)` - Update post (owner/admin)
+- `bold.community.posts.delete(viewerId, id)` - Delete post (owner/admin)
+- `bold.community.posts.react(viewerId, id)` - Toggle reaction
+
+### Comments
+
+- `bold.community.comments.create(viewerId, postId, data)` - Create comment
+- `bold.community.comments.delete(viewerId, id)` - Delete comment (owner/admin)
+- `bold.community.comments.react(viewerId, id)` - Toggle reaction
+
+```typescript
+// Example
+const { data: posts } = await bold.community.posts.list({ category: 'general', limit: 20 });
+await bold.community.posts.create(viewerId, { content: 'Hello!', category: 'general' });
+await bold.community.posts.react(viewerId, posts[0].id);
+await bold.community.comments.create(viewerId, posts[0].id, { content: 'Great post!' });
+```
+
 ## AI Methods
 
 All AI methods return `AsyncIterable<AIEvent>` (streaming) or `Promise<AIResponse>` (non-streaming).
@@ -252,9 +302,44 @@ type AIEvent =
 }
 ```
 
+### Post
+
+```typescript
+{
+  id: string;
+  content: string;             // Markdown content
+  category: string;
+  pinned: boolean;
+  pinnedAt?: string | null;
+  reactionsCount: number;
+  commentsCount: number;
+  viewerReacted?: boolean;     // Only with X-Viewer-ID
+  viewer: PostAuthor;
+  comments?: Comment[];        // Only on single post fetch
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
+### Comment
+
+```typescript
+{
+  id: string;
+  content: string;
+  depth: number;               // Nesting level (0 = top-level)
+  reactionsCount: number;
+  viewerReacted?: boolean;
+  viewer: PostAuthor;
+  replies: Comment[];          // Nested replies
+  createdAt: string;
+  updatedAt: string;
+}
+```
+
 ### 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`, `Post`, `PostAuthor`, `Comment`, `ReactionResponse`, `ListPostsOptions`, `CreatePostData`, `UpdatePostData`, `CreateCommentData`, `CommunityAPIError`
 
 ## Error Handling
 

package/package.json

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