ugcinc 4.13.0 → 4.14.1

package/README.md

@@ -93,6 +93,28 @@ do {
 } while (cursor);
 ```
 
+For interactive tables, `posts.getPostsPage()` keeps filtering and sorting on the server and
+returns page-scoped latest stats plus `totalCount`, organization-wide `postTags`,
+`anyHasTitle`, and `matchingAccountIds`. It supports caption/title/account search; platform,
+post type, status, account, account-tag, post-tag, social-audio, and phone-type filters; and
+sorting by account, status, title, caption, tag, audio presence, scheduled time, or engagement:
+
+```typescript
+const page = await client.posts.getPostsPage({
+  search: "launch",
+  statuses: ["complete"],
+  postTags: ["fall-campaign"],
+  sortBy: "views",
+  sortDirection: "desc",
+  limit: 200,
+});
+
+if (page.ok) {
+  console.log(page.data.posts, page.data.stats, page.data.totalCount);
+  const next = page.data.nextCursor;
+}
+```
+
 ## Caption Overlays
 
 Video posts can carry text overlays to display on the video. Pass `captionOverlays` to

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { InputType } from './automations/nodes/types';
 export type { ClientConfig } from './base';
 export type { Account, AccountStatus, AccountStat, AccountTask, QuarantineAccountParams, ReleaseAccountParams, QuarantineAccountResponse, EditProfileInfo, GetAccountsParams, GetAccountStatsParams, GetAccountStatusParams, AccountInfoUpdate, UpdateAccountInfoParams, AccountInfoUpdateResult, UpdateAccountInfoResponse, AccountSocialUpdate, UpdateAccountSocialParams, AccountSocialUpdateResult, UpdateAccountSocialResponse, DeleteAccountPostsParams, DeleteAccountPostsResponse, ResetWarmupParams, ResetWarmupResponse, NicheSwitchUpdate, NicheSwitchParams, NicheSwitchResult, NicheSwitchResponse, CreateAccountInput, CreateAccountsParams, CreateAccountResult, CreateAccountsResponse, TroubleshootFailReason, TroubleshootAccount, TroubleshootParams, } from './accounts';
 export type { TaskType, Task, GetTasksParams } from './tasks';
-export type { PostType, PostStatus, Post, PostStat, CaptionOverlay, GetPostsParams, CreateDraftParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, UpdatePostParams, DeletePostsParams, DeletePostsResponse, RetryPostsParams, SetPostStatusParams, SetPostStatusResponse, PreviewScheduleEntry, PreviewScheduleParams, PreviewScheduleResult, } from './posts';
+export type { PostType, PostStatus, Post, PostStat, CaptionOverlay, GetPostsParams, GetPostsPageParams, PostsPage, PostSortField, PostSortDirection, CreateDraftParams, CreateSlideshowParams, GetPostStatsParams, GetPostStatusParams, CreateVideoParams, UpdatePostParams, DeletePostsParams, DeletePostsResponse, RetryPostsParams, SetPostStatusParams, SetPostStatusResponse, PreviewScheduleEntry, PreviewScheduleParams, PreviewScheduleResult, } from './posts';
 export type { RefreshStatsParams, RefreshStatsError, RefreshStatsResponse, RefreshStatsProgressResponse, RefreshStartEvent, RefreshProgressEvent, RefreshDoneEvent, RefreshStreamEvent, DailyAggregatedStat, GetDailyAggregatedStatsParams, DailyAccountStat, GetDailyAccountStatsParams, DailyPostStat, GetDailyPostStatsParams, DashboardDailyStat, GetDashboardDailyStatsParams, TopAccount, GetTopAccountsParams, TopPost, GetTopPostsParams, } from './stats';
 export type { Org, ApiKey, DeleteApiKeyParams, EditApiKeyParams, IntegrationKey, IntegrationProvider, UpsertIntegrationKeyParams, DeleteIntegrationKeyParams } from './org';
 export type { UserMedia, MediaUse, SocialAudio, Media, GetMediaParams, GetSocialAudioParams, UploadMediaParams, UploadMediaResponse, MediaTagUpdate, UpdateMediaTagsParams, MediaTagUpdateResult, UpdateMediaTagsResponse, UpdateMediaTagParams, UpdateMediaNameParams, DeleteMediaParams, DeleteMediaResponse, CreateSocialAudioParams, ImportTextParams, ImportTextResponse, CreateMediaFromUrlParams, GetMediaUseParams, GetMediaUseResponse, FilterMediaParams, FilterMediaResponse, PfpSearchParams, PfpSearchResponse, PfpCandidate, GetUploadTokenParams, UploadTokenResponse, } from './media';

package/dist/posts.d.ts

@@ -64,6 +64,37 @@ export interface GetPostsParams {
     limit?: number;
     /** Opaque cursor from a previous response's `nextCursor`, to fetch the next page. */
     cursor?: string;
+    /** Case-insensitive substring search across caption, title, and account username. */
+    search?: string;
+    platform?: 'tiktok' | 'instagram';
+    postType?: PostType;
+    statuses?: PostStatus[];
+    /** Match any comma-separated tag on the post's account. */
+    accountTags?: string[];
+    /** Match any comma-separated tag stored on the post. */
+    postTags?: string[];
+    socialAudioIds?: string[];
+    phoneTypes?: Array<'physical_iphone' | 'manual_iphone' | 'physical_android' | 'emulated_android' | 'social_api' | 'custom_provider' | 'tracking' | 'clipper'>;
+    sortBy?: PostSortField;
+    sortDirection?: PostSortDirection;
+}
+export type PostSortField = 'created' | 'account' | 'status' | 'title' | 'caption' | 'tag' | 'audio' | 'time' | 'views' | 'likes' | 'comments' | 'shares';
+export type PostSortDirection = 'asc' | 'desc';
+export interface GetPostsPageParams extends GetPostsParams {
+    /** Page size. Defaults to 200 and is capped at 500. */
+    limit?: number;
+}
+export interface PostsPage {
+    posts: Post[];
+    /** Latest stats only for posts in this page. */
+    stats: PostStat[];
+    totalCount: number;
+    /** Distinct comma-split post tags across the organization. */
+    postTags: string[];
+    anyHasTitle: boolean;
+    /** Accounts with a match when `accountIds` is ignored and all other filters remain active. */
+    matchingAccountIds: string[];
+    nextCursor: string | null;
 }
 export interface CreateSlideshowParams {
     accountId: string | null;
@@ -179,6 +210,11 @@ export declare class PostsClient extends BaseClient {
      * passed back as `cursor` to fetch the next page, ordered newest-first.
      */
     getPosts(params?: GetPostsParams): Promise<ApiResponse<Post[]>>;
+    /**
+     * Get one server-filtered/sorted page plus table metadata and page-scoped stats.
+     * Unlike getPosts(), this method never falls back to an unbounded response.
+     */
+    getPostsPage(params?: GetPostsPageParams): Promise<ApiResponse<PostsPage>>;
     /**
      * Create a draft post without assigning it to an account
      *

package/dist/posts.js

@@ -15,6 +15,13 @@ class PostsClient extends base_1.BaseClient {
     async getPosts(params) {
         return this.post('/post', params ?? {});
     }
+    /**
+     * Get one server-filtered/sorted page plus table metadata and page-scoped stats.
+     * Unlike getPosts(), this method never falls back to an unbounded response.
+     */
+    async getPostsPage(params = {}) {
+        return this.post('/post', { ...params, includePageMeta: true });
+    }
     /**
      * Create a draft post without assigning it to an account
      *

package/dist/render/compositions/IMessageDmComposition/types.d.ts

@@ -399,10 +399,10 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
     dynamicCrop: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     cropVerticalCenter: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
+    time?: string | undefined;
     backgroundColor?: string | undefined;
     lightMode?: boolean | undefined;
     username?: string | undefined;
-    time?: string | undefined;
     profilePicUrl?: string | undefined;
     messages?: {
         text: string;
@@ -582,10 +582,10 @@ export declare const iMessageDmPropsSchema: z.ZodObject<{
     readReceiptLeft?: number | undefined;
     readReceiptRight?: number | undefined;
 }, {
+    time?: string | undefined;
     backgroundColor?: string | undefined;
     lightMode?: boolean | undefined;
     username?: string | undefined;
-    time?: string | undefined;
     profilePicUrl?: string | undefined;
     messages?: {
         text: string;

package/package.json

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