ugcinc 4.6.2 → 4.7.0

package/README.md

@@ -58,7 +58,7 @@ All client methods return the same response envelope:
 
 ```typescript
 type ApiResponse<T> =
-  | { ok: true; code: 200; message: string; data: T }
+  | { ok: true; code: 200; message: string; data: T; nextCursor?: string | null }
   | { ok: false; code: number; message: string };
 ```
 
@@ -74,6 +74,25 @@ if (posts.ok) {
 }
 ```
 
+## Pagination
+
+`accounts.getAccounts()` and `posts.getPosts()` support keyset pagination via `limit`/`cursor`.
+Omit `limit` to fetch everything matching your filters (the default, unpaginated behavior); pass
+`limit` to page through results newest-first, using each response's `nextCursor` to fetch the next
+page (`null`/absent means there are no more pages):
+
+```typescript
+let cursor: string | undefined;
+const allPosts = [];
+
+do {
+  const res = await client.posts.getPosts({ limit: 100, cursor });
+  if (!res.ok) break;
+  allPosts.push(...res.data);
+  cursor = res.nextCursor ?? undefined;
+} while (cursor);
+```
+
 ## Useful Exports
 
 - `UGCClient` for API access

package/dist/accounts.d.ts

@@ -74,6 +74,10 @@ export interface GetAccountsParams {
     org_group?: string;
     user_group?: string;
     status?: 'uninitialized' | 'pending' | 'initialized' | 'setup' | 'warming' | 'warmed' | 'needs_replacement' | 'replacing' | 'failed' | 'deleted' | 'reclaimed';
+    /** Max rows to return. Omit to fetch all matching accounts (no pagination). */
+    limit?: number;
+    /** Opaque cursor from a previous response's `nextCursor`, to fetch the next page. */
+    cursor?: string;
 }
 export interface GetAccountStatsParams {
     accountIds?: string[];
@@ -239,6 +243,9 @@ export interface TroubleshootParams {
 export declare class AccountsClient extends BaseClient {
     /**
      * Get accounts with optional filters
+     *
+     * Pass `limit` to paginate; the response's `nextCursor` (when present) can be
+     * passed back as `cursor` to fetch the next page, ordered newest-first.
      */
     getAccounts(params?: GetAccountsParams): Promise<ApiResponse<Account[]>>;
     /**

package/dist/accounts.js

@@ -8,6 +8,9 @@ const base_1 = require("./base");
 class AccountsClient extends base_1.BaseClient {
     /**
      * Get accounts with optional filters
+     *
+     * Pass `limit` to paginate; the response's `nextCursor` (when present) can be
+     * passed back as `cursor` to fetch the next page, ordered newest-first.
      */
     async getAccounts(params) {
         return this.post('/accounts', params ?? {});

package/dist/base.js

@@ -44,6 +44,7 @@ class BaseClient {
                     code: rawData.code,
                     message: rawData.message ?? 'Success',
                     data: rawData.data,
+                    ...(rawData.nextCursor !== undefined ? { nextCursor: rawData.nextCursor } : {}),
                 };
             }
             else {

package/dist/posts.d.ts

@@ -31,6 +31,11 @@ export interface GetPostsParams {
     postIds?: string[];
     startDate?: string;
     endDate?: string;
+    includeHidden?: boolean;
+    /** Max rows to return. Omit to fetch all matching posts (no pagination). */
+    limit?: number;
+    /** Opaque cursor from a previous response's `nextCursor`, to fetch the next page. */
+    cursor?: string;
 }
 export interface CreateSlideshowParams {
     accountId: string | null;
@@ -49,6 +54,7 @@ export interface GetPostStatsParams {
     postIds?: string[];
     startDate?: string;
     endDate?: string;
+    includeHidden?: boolean;
 }
 export interface GetPostStatusParams {
     postId: string;
@@ -129,6 +135,9 @@ export interface PreviewScheduleResult {
 export declare class PostsClient extends BaseClient {
     /**
      * Get posts with optional filters
+     *
+     * Pass `limit` to paginate; the response's `nextCursor` (when present) can be
+     * passed back as `cursor` to fetch the next page, ordered newest-first.
      */
     getPosts(params?: GetPostsParams): Promise<ApiResponse<Post[]>>;
     /**

package/dist/posts.js

@@ -8,6 +8,9 @@ const base_1 = require("./base");
 class PostsClient extends base_1.BaseClient {
     /**
      * Get posts with optional filters
+     *
+     * Pass `limit` to paginate; the response's `nextCursor` (when present) can be
+     * passed back as `cursor` to fetch the next page, ordered newest-first.
      */
     async getPosts(params) {
         return this.post('/post', params ?? {});

package/dist/stats.d.ts

@@ -140,6 +140,9 @@ export interface GetTopAccountsParams {
     tag?: string;
     org_group?: string;
     user_group?: string;
+    /** Optional ISO date window. When provided, ranks accounts by their latest stat within the range instead of all-time. */
+    startDate?: string;
+    endDate?: string;
 }
 export interface TopPost {
     post_id: string;
@@ -158,6 +161,9 @@ export interface GetTopPostsParams {
     metric: 'views' | 'likes' | 'comments' | 'shares';
     limit?: number;
     postIds?: string[];
+    /** Optional ISO date window. When provided, ranks posts by their latest stat within the range instead of all-time. */
+    startDate?: string;
+    endDate?: string;
 }
 export interface RefreshStartEvent {
     type: 'start';

package/dist/tools/accounts.js

@@ -11,6 +11,8 @@ exports.accountTools = [
             org_group: zod_1.z.string().optional().describe('Filter by org group'),
             user_group: zod_1.z.string().optional().describe('Filter by user group'),
             status: zod_1.z.enum(['uninitialized', 'pending', 'initialized', 'setup', 'warming', 'warmed', 'needs_replacement', 'replacing', 'failed', 'deleted']).optional().describe('Filter by account status'),
+            limit: zod_1.z.number().optional().describe('Max rows to return, for pagination'),
+            cursor: zod_1.z.string().optional().describe('Opaque cursor from a previous response\'s nextCursor, to fetch the next page'),
         }).optional().describe('Optional filters'),
         execute: async (client, params) => {
             return client.accounts.getAccounts(params ?? undefined);

package/dist/tools/posts.js

@@ -11,6 +11,8 @@ exports.postTools = [
             postIds: zod_1.z.array(zod_1.z.string()).optional().describe('Filter by specific post IDs'),
             startDate: zod_1.z.string().optional().describe('Start date (ISO 8601)'),
             endDate: zod_1.z.string().optional().describe('End date (ISO 8601)'),
+            limit: zod_1.z.number().optional().describe('Max rows to return, for pagination'),
+            cursor: zod_1.z.string().optional().describe('Opaque cursor from a previous response\'s nextCursor, to fetch the next page'),
         }).optional(),
         execute: async (client, params) => {
             return client.posts.getPosts(params ?? undefined);

package/dist/types.d.ts

@@ -6,6 +6,8 @@ export interface SuccessResponse<T> {
     message: string;
     data: T;
     ok: true;
+    /** Present on keyset-paginated endpoints (see `limit`/`cursor` params). Pass back as `cursor` to fetch the next page; `null`/absent means no more pages. */
+    nextCursor?: string | null;
 }
 export interface ErrorResponse {
     code: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugcinc",
-  "version": "4.6.2",
+  "version": "4.7.0",
   "description": "TypeScript/JavaScript client for the UGC Inc API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",