@boldvideo/bold-js 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @boldvideo/bold-js
 
+## 1.19.0
+
+### Minor Changes
+
+- d423437: Redesign Community API types to eliminate N+1 queries
+
+  **Breaking changes to Post type:**
+
+  - `viewer` → `author` (creator of the post)
+  - `reactionsCount` → `reactions.count`
+  - `commentsCount` → `comments.count`
+  - `viewerReacted` → `reactions.viewer_has_reacted`
+  - `createdAt` → `created_at`
+
+  **New types:**
+
+  - `UserSummary` - minimal profile with `id`, `name`, `avatar_url`
+  - `ReactionSummary` - `{ count, reacted_by[], viewer_has_reacted? }`
+  - `CommentSummary` - `{ count, commented_by[], items? }`
+  - `CommentThread` and `Reply` - structured comment threading
+  - `PaginationMeta` and `PaginatedResponse<T>` - page-based pagination
+
+  **Pagination changes:**
+
+  - `posts.list()` now uses `page`/`pageSize` instead of `limit`/`offset`
+  - Returns `PaginatedResponse<Post>` with `data[]` and `meta`
+
+  **Benefits:**
+
+  - List endpoint now includes `reacted_by` and `commented_by` arrays (up to 10 users)
+  - Enables avatar display without fetching each post individually
+  - Consistent object shapes between list and detail views
+
 ## 1.18.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -407,8 +407,8 @@ function listPosts(client) {
       client,
       `community/posts${toQuery2({
         category: opts.category,
-        limit: opts.limit,
-        offset: opts.offset
+        page: opts.page,
+        page_size: opts.pageSize
       })}`,
       opts.viewerId
     );

package/dist/index.d.ts

@@ -512,16 +512,63 @@ type ListVideosOptions = (ListVideosLatestOptions & {
     viewerId?: never;
 });
 /**
- * Author information for posts and comments
+ * Minimal profile object for list contexts
  */
-type PostAuthor = {
+type UserSummary = {
     id: string;
     name: string;
+    avatar_url: string | null;
+};
+/**
+ * Author information for posts and comments (extended for admin context)
+ */
+type PostAuthor = UserSummary & {
     email?: string;
-    isAdmin: boolean;
+    isAdmin?: boolean;
+};
+/**
+ * Reaction summary with users who reacted
+ */
+type ReactionSummary = {
+    count: number;
+    /** Users who reacted (capped to 10 from API) */
+    reacted_by: UserSummary[];
+    /** Present when viewer context exists */
+    viewer_has_reacted?: boolean;
+};
+/**
+ * Comment summary with users who commented
+ */
+type CommentSummary = {
+    count: number;
+    /** Users who commented (capped to 10 from API) */
+    commented_by: UserSummary[];
+    /** Full comment threads (present in detail only) */
+    items?: CommentThread[];
+};
+/**
+ * A reply to a comment
+ */
+type Reply = {
+    id: string;
+    content: string;
+    created_at: string;
+    author: UserSummary;
+    parent_comment_id: string;
+};
+/**
+ * A top-level comment with replies
+ */
+type CommentThread = {
+    id: string;
+    content: string;
+    created_at: string;
+    author: UserSummary;
+    replies: Reply[];
 };
 /**
- * A comment on a community post
+ * @deprecated Use CommentThread instead
+ * A comment on a community post (legacy format)
  */
 type Comment = {
     id: string;
@@ -531,30 +578,38 @@ type Comment = {
     reactionsCount: number;
     /** Whether current viewer has reacted (only present when X-Viewer-ID header sent) */
     viewerReacted?: boolean;
+    /** @deprecated Use author instead */
     viewer: PostAuthor;
+    author: PostAuthor;
     /** Nested replies */
     replies: Comment[];
     createdAt: string;
     updatedAt: string;
 };
 /**
- * A community post
+ * A community post (list view)
  */
 type Post = {
     id: string;
     content: string;
-    category: string;
-    pinned: boolean;
+    category?: string;
+    pinned?: boolean;
     pinnedAt?: string | null;
-    reactionsCount: number;
-    commentsCount: number;
-    /** Whether current viewer has reacted (only present when X-Viewer-ID header sent) */
+    created_at: string;
+    author: PostAuthor;
+    reactions: ReactionSummary;
+    comments: CommentSummary;
+    /** @deprecated Use created_at */
+    createdAt?: string;
+    /** @deprecated Use reactions.count */
+    reactionsCount?: number;
+    /** @deprecated Use comments.count */
+    commentsCount?: number;
+    /** @deprecated Use reactions.viewer_has_reacted */
     viewerReacted?: boolean;
-    viewer: PostAuthor;
-    /** Comments (only present on single post fetch) */
-    comments?: Comment[];
-    createdAt: string;
-    updatedAt: string;
+    /** @deprecated Use author */
+    viewer?: PostAuthor;
+    updatedAt?: string;
 };
 /**
  * Response from react endpoints (toggle)
@@ -563,17 +618,37 @@ type ReactionResponse = {
     reacted: boolean;
     reactionsCount: number;
 };
+/**
+ * Pagination metadata from API
+ */
+type PaginationMeta = {
+    /** Current page (1-indexed) */
+    page: number;
+    /** Items per page */
+    page_size: number;
+    /** Total items across all pages */
+    total_entries: number;
+    /** Total number of pages */
+    total_pages: number;
+};
+/**
+ * Paginated response wrapper
+ */
+type PaginatedResponse<T> = {
+    data: T[];
+    meta: PaginationMeta;
+};
 /**
  * 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 */
+    /** Page number (1-indexed, default: 1) */
+    page?: number;
+    /** Items per page (default: 20, max: 100) */
+    pageSize?: number;
+    /** Viewer ID to include viewer_has_reacted in response */
     viewerId?: string;
 };
 /**
@@ -787,9 +862,7 @@ declare function createClient(apiKey: string, options?: ClientOptions): {
     ai: AIClient;
     community: {
         posts: {
-            list: (opts?: ListPostsOptions) => Promise<{
-                data: Post[];
-            }>;
+            list: (opts?: ListPostsOptions) => Promise<PaginatedResponse<Post>>;
             get: (id: string, viewerId?: string | undefined) => Promise<{
                 data: Post;
             }>;
@@ -836,4 +909,4 @@ declare class CommunityAPIError extends 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 };
+export { AIContextMessage, AIEvent, AIResponse, AIUsage, Account, AccountAI, AnalyticsProvider, AskOptions, AssistantConfig, ChatOptions, Citation, ClientOptions, Comment, CommentSummary, CommentThread, CommunityAPIError, Conversation, ConversationMessage, ConversationMetadata, CreateCommentData, CreatePostData, CreateViewerData, CustomRedirect, DEFAULT_API_BASE_URL, DEFAULT_INTERNAL_API_BASE_URL, ListPostsOptions, ListProgressOptions, ListVideosIndexOptions, ListVideosLatestOptions, ListVideosOptions, MenuItem, PaginatedResponse, PaginationMeta, Playlist, Portal, PortalDisplay, PortalHero, PortalLayout, PortalNavigation, PortalTheme, Post, PostAuthor, ProgressListMeta, ReactionResponse, ReactionSummary, RecommendOptions, RecommendResponse, Recommendation, RecommendationVideo, RecommendationsOptions, RecommendationsResponse, Reply, SaveProgressData, SearchOptions, Segment, Settings, Source, ThemeColors, ThemeConfig, UpdatePostData, UpdateViewerData, UserSummary, Video, VideoAttachment, VideoDownloadUrls, VideoMetadata, VideoSubtitles, VideoTranscript, Viewer, ViewerAPIError, ViewerLookupParams, ViewerProgress, createClient };

package/dist/index.js

@@ -367,8 +367,8 @@ function listPosts(client) {
       client,
       `community/posts${toQuery2({
         category: opts.category,
-        limit: opts.limit,
-        offset: opts.offset
+        page: opts.page,
+        page_size: opts.pageSize
       })}`,
       opts.viewerId
     );

package/llms.txt

@@ -117,8 +117,8 @@ Build community features with posts, comments, and reactions. Write operations r
 
 ### Posts
 
-- `bold.community.posts.list(opts?)` - List posts with optional filters
-- `bold.community.posts.get(id, viewerId?)` - Get post with comments
+- `bold.community.posts.list(opts?)` - List posts with pagination (returns `PaginatedResponse<Post>`)
+- `bold.community.posts.get(id, viewerId?)` - Get post with full 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)
@@ -131,11 +131,21 @@ Build community features with posts, comments, and reactions. Write operations r
 - `bold.community.comments.react(viewerId, id)` - Toggle reaction
 
 ```typescript
-// Example
-const { data: posts } = await bold.community.posts.list({ category: 'general', limit: 20 });
+// Example: List posts with pagination
+const response = await bold.community.posts.list({ page: 1, pageSize: 20, viewerId });
+// response.data = Post[]
+// response.meta = { page, page_size, total_entries, total_pages }
+
+// Access users who reacted/commented (for avatar display)
+const post = response.data[0];
+post.reactions.reacted_by;      // UserSummary[] (up to 10)
+post.comments.commented_by;     // UserSummary[] (up to 10)
+post.reactions.viewer_has_reacted; // boolean (when viewerId provided)
+
+// Create and interact
 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!' });
+await bold.community.posts.react(viewerId, post.id);
+await bold.community.comments.create(viewerId, post.id, { content: 'Great post!' });
 ```
 
 ## AI Methods
@@ -302,44 +312,94 @@ type AIEvent =
 }
 ```
 
+### UserSummary
+
+```typescript
+{
+  id: string;
+  name: string;
+  avatar_url: string | null;
+}
+```
+
 ### Post
 
 ```typescript
 {
   id: string;
   content: string;             // Markdown content
-  category: string;
-  pinned: boolean;
+  created_at: string;
+  author: PostAuthor;          // Creator of the post
+  reactions: ReactionSummary;  // { count, reacted_by, viewer_has_reacted? }
+  comments: CommentSummary;    // { count, commented_by, items? }
+  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;
+  updatedAt?: string;
+}
+```
+
+### ReactionSummary
+
+```typescript
+{
+  count: number;
+  reacted_by: UserSummary[];       // Capped to 10 from API
+  viewer_has_reacted?: boolean;    // Present when viewerId provided
+}
+```
+
+### CommentSummary
+
+```typescript
+{
+  count: number;
+  commented_by: UserSummary[];     // Capped to 10 from API
+  items?: CommentThread[];         // Full threads (detail view only)
 }
 ```
 
-### Comment
+### CommentThread
 
 ```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;
+  created_at: string;
+  author: UserSummary;
+  replies: Reply[];                // Nested replies
+}
+```
+
+### Reply
+
+```typescript
+{
+  id: string;
+  content: string;
+  created_at: string;
+  author: UserSummary;
+  parent_comment_id: string;
+}
+```
+
+### PaginatedResponse<T>
+
+```typescript
+{
+  data: T[];
+  meta: {
+    page: number;              // Current page (1-indexed)
+    page_size: number;
+    total_entries: number;
+    total_pages: number;
+  };
 }
 ```
 
 ### Other types exported
 
-`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`
+`Playlist`, `Settings`, `Portal`, `MenuItem`, `AIResponse`, `AIUsage`, `AIContextMessage`, `Conversation`, `ConversationMessage`, `RecommendationsResponse`, `Viewer`, `ViewerProgress`, `ViewerLookupParams`, `ListProgressOptions`, `ListVideosOptions`, `ListVideosLatestOptions`, `ListVideosIndexOptions`, `Post`, `PostAuthor`, `UserSummary`, `ReactionSummary`, `CommentSummary`, `CommentThread`, `Reply`, `Comment`, `ReactionResponse`, `ListPostsOptions`, `CreatePostData`, `UpdatePostData`, `CreateCommentData`, `PaginationMeta`, `PaginatedResponse`, `CommunityAPIError`
 
 ## Error Handling
 

package/package.json

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