ugcinc 4.19.1 → 4.20.0

package/README.md

@@ -43,7 +43,7 @@ if (res.ok) {
 
 - `client.accounts`: list, create, update, troubleshoot, quarantine/release, and manage account lifecycle
 - `client.posts`: create video/slideshow posts, update them, retry failures, and preview schedule conflicts
-- `client.media`: upload media, create media records, manage tags/names, and work with social audio
+- `client.media`: upload media, create media records, search profile-picture candidates, search images and videos by keyword (`media.imageSearch`, cursor-paged), manage tags/names, and work with social audio
 - `client.stats`: fetch account/post analytics, daily aggregates, top performers, and refresh stats
 - `client.org`: manage organizations, API keys, and integration keys
 - `client.billing`: inspect subscription state and handle account deactivation, replacements, and refunds
@@ -74,6 +74,20 @@ if (posts.ok) {
 }
 ```
 
+## Posting failure quick reference
+
+`posts.getStatus()` returns `failure`; both `getPosts()` and `getPostsPage()` include it on each post. It is `null` when there is no current posting issue. A successful lookup still returns HTTP 200 even if the post failed.
+
+```typescript
+const result = await client.posts.getStatus({ postId: "post_123" });
+if (result.ok && result.data.failure) {
+  const { code, message, recovery, next_action } = result.data.failure;
+  console.log(code, message, recovery, next_action);
+}
+```
+
+See the posting failure reference below for recovery states and messages.
+
 ## Pagination
 
 `accounts.getAccounts()` and `posts.getPosts()` support keyset pagination via `limit`/`cursor`.
@@ -93,6 +107,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
@@ -144,6 +180,28 @@ await client.posts.createVideo({
 await client.posts.updatePost({ postId: "post_123", post_tag: "campaign-august" });
 ```
 
+When a post fails, its category is appended to the tag as `fail reason: <fail_category>` (for
+example `campaign-july fail reason: device_error`), so a post list shows why without a status call
+per post. The suffix is removed again when the post is retried.
+
+## Backup Audio
+
+A post can carry a second sound. If the platform refuses the primary sound at posting time, the
+backup becomes the post's `social_audio_id`, the post is re-attempted once, ` switched to backup
+audio` is appended to its `tag`, and `backup_audio_used_at` is set. With no backup left the post
+fails as `audio_unavailable` and is not retried. Set it with `backupSocialAudioId` on
+`posts.createVideo()`, `posts.createSlideshow()`, `posts.createDraft()`, and `posts.updatePost()`
+(`null` clears it on update).
+
+```typescript
+await client.posts.createSlideshow({
+  accountId: "acc_123",
+  imageUrls: ["https://example.com/img1.jpg"],
+  socialAudioId: "audio_primary",
+  backupSocialAudioId: "audio_fallback",
+});
+```
+
 ## Useful Exports
 
 - `UGCClient` for API access
@@ -162,6 +220,33 @@ For the full endpoint reference, all method signatures, data structures, and wor
 
 MIT
 
+## Posting failure reference
+
+The same `failure` object is returned by status and list responses. It contains a stable `code`, a fixed `message`, a `recovery` state, and `next_action`.
+
+| Recovery | Meaning |
+|---|---|
+| `retry_pending` | The existing post is waiting for another attempt; no execution time is guaranteed. |
+| `waiting` | The existing post is paused until a publishing issue is resolved. |
+| `verifying_publication` | Publication is being checked before another attempt is allowed. |
+| `stopped` | No automatic recovery is indicated. Follow `next_action`. |
+
+`next_action` is `wait`, `change_audio`, `change_audio_or_contact_support`, or `contact_support`. When it is `wait`, do not submit another copy. Account and publishing operations are handled by the service; these messages never ask customers to manage them.
+
+| Code | Message |
+|---|---|
+| `AUDIO_UNAVAILABLE` | The selected sound is unavailable. Choose another sound and retry. |
+| `BACKUP_AUDIO_RETRY_PENDING` | The selected sound was unavailable. Your post is waiting to be retried with its backup sound. |
+| `AUDIO_RETRY_PENDING` | The selected sound could not be loaded. Your post is waiting to be retried. |
+| `AUDIO_PREPARATION_FAILED` | The selected sound could not be prepared for this post. Choose another sound or contact support before retrying. |
+| `PUBLISHING_RETRY_PENDING` | Publishing was temporarily interrupted. Your post is waiting to be retried. No action is needed. |
+| `PUBLISHING_BLOCKED` | A publishing issue prevented this post from proceeding. Contact support for help with this post. |
+| `POST_PROCESSING_FAILED` | A processing error prevented this posting attempt from completing. Contact support before retrying. |
+| `PUBLICATION_CHECK_IN_PROGRESS` | We’re checking whether your post published. Please wait before submitting it again to avoid a duplicate. |
+| `PUBLICATION_UNCONFIRMED` | We couldn’t confirm whether your post published. Contact support before submitting it again to avoid a duplicate. |
+| `POST_RETRY_PENDING` | The previous posting attempt did not complete. Your post is waiting to be retried. No action is needed. |
+| `POST_FAILED` | The posting attempt failed, but we couldn’t determine the cause. Contact support before submitting it again. |
+
 ### Render a supplied Remotion composition
 
 `remotion-composition` accepts a TSX module whose default export is a React
@@ -196,11 +281,43 @@ status/logs to inspect failures and the returned video for preview.
 Server integrations can also call `submitRemotionCompositionRenderJob` and
 `getRenderJobStatus` with the configured render-worker origin.
 
-### Remotion composition PNG output
+## Social reference acquisition
+
+Quick reference:
+
+```ts
+const page = await client.media.listProfilePosts({ url: profileUrl, limit: 20 });
+const post = await client.media.downloadSocialPost({ url: postUrl });
+```
 
-The `remotion-composition` workflow node accepts `outputType: "image"` to render
-the first composition frame as a PNG. Its output port becomes `image`; video
-remains the default for existing workflows. Pass sound assets separately for
-photo posts because PNG files contain no audio. The public render helper
-`submitRemotionCompositionRenderJob({...composition, outputType: "image"})`
-supports the same option.
+`media.listProfilePosts({url, limit?, cursor?})` calls `POST /media/social/list-profile-posts`.
+Supported profiles are TikTok and Instagram. Limit defaults to 20 (1–50). Results include
+`profile`, `posts`, `nextCursor`, `coverage` and `warnings`. Pass `nextCursor` back with
+the same profile URL. Cursors expire after one hour and belong to the authenticated
+organization. Short pages may still have a cursor. Instagram combines posts and reels;
+ordering follows those feeds, not a guaranteed chronological snapshot. `exhausted`
+means the available feeds ended, not that all historical posts are visible. Thumbnail
+URLs are upstream references and may expire. Listing does not import media.
+
+`media.downloadSocialPost({url})` calls `POST /media/social/download-post` until the
+checkpointed import finishes. Inputs are TikTok video/photo or Instagram post/reel
+URLs, including supported share redirects. The raw HTTP endpoint returns `processing`
+while another continuation is needed; call it again with the same URL. The SDK/tool
+handles these calls. Imports have `complete`, `partial` or `failed` status, ordered
+`assets`, `failedAssets`, post metadata, sound attribution, provenance and an owned
+JSON `manifestUrl`. Assets contain owned URLs, media IDs, SHA-256 hashes, probed
+format/dimensions/duration and embedded audio presence. A successful API response can
+contain a partial/failed import; check `data.status` and `data.failedAssets`.
+
+Repeat a partial/failed import to retry missing assets. Successful imports are reused
+within the organization while their records/files remain available; import state is
+retained for 30 days. Original downloaded video bytes/audio are preserved. Photo
+carousels stay ordered images: this does not generate a slideshow video or download
+an attributed full music track. Absent metadata is null. Supported acquired formats
+are JPEG/PNG/WebP images and MP4/WebM video, limited to 50 assets, 100 MB per asset
+and 30 minutes per video. Limits are checked before accepting an asset. No guarantee
+of original upload quality or watermark removal is made.
+
+Both operations require an organization and `content:analyze` for scoped keys.
+Errors may include `errorCode` and `retryable`. Existing scraper credit/rate safeguards
+apply. Storage/provider errors do not imply that a post or profile was deleted.

package/dist/automations/nodes/index.d.ts

@@ -338,7 +338,7 @@ export declare const nodeDefinitions: {
         selectionMode: null;
         outputType: "video" | "image";
         inputs: {
-            type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+            type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
             id: string;
             isArray: boolean;
             required: boolean;

package/dist/automations/nodes/remotion-composition.d.ts

@@ -9,7 +9,7 @@ declare const defaults: {
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;
@@ -26,7 +26,7 @@ declare const _default: import("./types").NodeDefinition<"remotion-composition",
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;

package/dist/base.js

@@ -52,6 +52,8 @@ class BaseClient {
                     ok: false,
                     code: rawData.code,
                     message: rawData.message ?? 'Request failed',
+                    ...(typeof rawData.errorCode === 'string' ? { errorCode: rawData.errorCode } : {}),
+                    ...(typeof rawData.retryable === 'boolean' ? { retryable: rawData.retryable } : {}),
                 };
             }
         }

package/dist/index.d.ts

@@ -85,3 +85,4 @@ export type { SelectionMode, ExhaustionBehavior, SelectionConfig, SelectionState
 export type { SuccessResponse, ErrorResponse, ApiResponse, } from './types';
 export type { CropBoundary, CropAxisConfig, DynamicCropConfig, BorderRadiusConfig, VerticalAnchor, HorizontalAnchor, HorizontalSelfAnchor, VerticalSelfAnchor, RelativePositionConfigX, RelativePositionConfigY, } from './render/types';
 export type { PublicPostFailureCode, PublicPostRecovery, PublicPostNextAction, PublicPostFailure } from './post-failure';
+export type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult, SocialReferencePost, SocialReferenceAsset } from './social-acquisition';

package/dist/media.d.ts

@@ -1,4 +1,5 @@
 import { BaseClient } from './base';
+import type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult } from './social-acquisition';
 import type { ApiResponse } from './types';
 export interface UserMedia {
     id: string;
@@ -198,6 +199,10 @@ export interface OwnedUploadResponse {
  * Client for managing media files
  */
 export declare class MediaClient extends BaseClient {
+    /** List a bounded page of TikTok/Instagram references; does not download media. */
+    listProfilePosts(params: ListProfilePostsParams): Promise<ApiResponse<ListProfilePostsResult>>;
+    /** Import actual post assets to owned media. Continuations are checkpointed server-side. */
+    downloadSocialPost(params: DownloadSocialPostParams): Promise<ApiResponse<DownloadSocialPostResult>>;
     /**
      * Get media for the organization
      * Returns both user_media and social_audio combined

package/dist/media.js

@@ -6,6 +6,22 @@ const base_1 = require("./base");
  * Client for managing media files
  */
 class MediaClient extends base_1.BaseClient {
+    /** List a bounded page of TikTok/Instagram references; does not download media. */
+    async listProfilePosts(params) {
+        return this.post('/media/social/list-profile-posts', params);
+    }
+    /** Import actual post assets to owned media. Continuations are checkpointed server-side. */
+    async downloadSocialPost(params) {
+        for (let step = 0; step < 120; step++) {
+            const response = await this.post('/media/social/download-post', params);
+            if (!response.ok)
+                return response;
+            if (response.data.status !== 'processing')
+                return { ...response, data: response.data };
+            await new Promise(resolve => setTimeout(resolve, Math.min(5000, Math.max(100, response.data.status === 'processing' ? response.data.retryAfterMs ?? 250 : 250))));
+        }
+        return { ok: false, code: 504, message: 'Import is still pending. Repeat downloadSocialPost with the same URL to resume.', errorCode: 'IMPORT_PENDING', retryable: true };
+    }
     /**
      * Get media for the organization
      * Returns both user_media and social_audio combined

package/dist/render/types/remotion-composition.d.ts

@@ -29,12 +29,12 @@ export declare const remotionCompositionPortSchema: z.ZodObject<{
     isArray: z.ZodBoolean;
     required: z.ZodBoolean;
 }, "strict", z.ZodTypeAny, {
-    type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+    type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
     id: string;
     isArray: boolean;
     required: boolean;
 }, {
-    type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+    type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
     id: string;
     isArray: boolean;
     required: boolean;
@@ -54,22 +54,22 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
         isArray: z.ZodBoolean;
         required: z.ZodBoolean;
     }, "strict", z.ZodTypeAny, {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;
     }, {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;
     }>, "many">, {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;
     }[], {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;
@@ -82,7 +82,7 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;
@@ -97,7 +97,7 @@ export declare const remotionCompositionNodeSchema: z.ZodObject<{
     outputMode: "per-input" | "single";
     selectionMode: null;
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "audio" | "image" | "text";
+        type: "number" | "boolean" | "object" | "video" | "image" | "audio" | "text";
         id: string;
         isArray: boolean;
         required: boolean;

package/dist/social-acquisition.d.ts

@@ -0,0 +1,85 @@
+/** Reference acquisition; these operations use the organization's content:analyze permission. */
+export interface ListProfilePostsParams {
+    url: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface DownloadSocialPostParams {
+    url: string;
+}
+export interface SocialReferencePost {
+    id: string;
+    url: string;
+    type: 'video' | 'image' | 'carousel' | 'unknown';
+    caption: string | null;
+    publishedAt: string | null;
+    thumbnailUrl: string | null;
+    metrics: {
+        views: number | null;
+        likes: number | null;
+        comments: number | null;
+        shares: number | null;
+    };
+}
+export interface SocialReferenceWarning {
+    code: string;
+    message: string;
+}
+export interface ListProfilePostsResult {
+    profile: {
+        platform: 'tiktok' | 'instagram';
+        username: string;
+        url: string;
+    };
+    posts: SocialReferencePost[];
+    nextCursor: string | null;
+    coverage: 'partial' | 'exhausted';
+    warnings: SocialReferenceWarning[];
+}
+export interface SocialReferenceAsset {
+    index: number;
+    mediaId: string;
+    url: string;
+    type: 'image' | 'video';
+    mimeType: string;
+    width: number;
+    height: number;
+    durationMs: number | null;
+    audio: 'present' | 'absent' | 'not_applicable';
+    sha256: string;
+}
+export interface DownloadSocialPostResult {
+    status: 'complete' | 'partial' | 'failed';
+    post: SocialReferencePost & {
+        platform: 'tiktok' | 'instagram';
+        author: {
+            username: string | null;
+            profileUrl: string | null;
+        };
+    };
+    assets: SocialReferenceAsset[];
+    failedAssets: {
+        index: number;
+        code: string;
+        message: string;
+        retryable: boolean;
+    }[];
+    sound: {
+        id: string | null;
+        title: string | null;
+        artist: string | null;
+        sourceUrl: string | null;
+    } | null;
+    provenance: {
+        requestedUrl: string;
+        canonicalUrl: string;
+        retrievedAt: string;
+    };
+    manifestUrl: string | null;
+    warnings: SocialReferenceWarning[];
+}
+export interface SocialDownloadProgress {
+    status: 'processing';
+    retryAfterMs?: number;
+}
+export type SocialDownloadStep = DownloadSocialPostResult | SocialDownloadProgress;

package/dist/social-acquisition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/tools/media.js

@@ -3,6 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.mediaTools = void 0;
 const zod_1 = require("zod");
 exports.mediaTools = [
+    {
+        name: 'list_profile_posts',
+        description: 'List a page of TikTok or Instagram profile posts, with metadata and an opaque continuation cursor. Does not download files; provider-visible history may be incomplete.',
+        schema: zod_1.z.object({ url: zod_1.z.string().url(), limit: zod_1.z.number().int().min(1).max(50).optional(), cursor: zod_1.z.string().uuid().optional() }).strict(),
+        execute: async (client, params) => client.media.listProfilePosts(params),
+    },
+    {
+        name: 'download_social_post',
+        description: 'Download a TikTok or Instagram post into owned UGC media, preserving ordered photo/video assets and embedded video audio. Returns partial failures explicitly. Repeat the same URL to resume failed assets; sound attribution is not a separately downloaded soundtrack.',
+        schema: zod_1.z.object({ url: zod_1.z.string().url() }).strict(),
+        execute: async (client, params) => client.media.downloadSocialPost(params),
+    },
     {
         name: 'list_media',
         description: 'List all media (user media + social audio). Can filter by IDs or tag.',

package/dist/types.d.ts

@@ -14,6 +14,9 @@ export interface ErrorResponse {
     message: string;
     ok: false;
     data?: never;
+    errorCode?: string;
+    retryable?: boolean;
 }
 export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
 export type { PublicPostFailureCode, PublicPostRecovery, PublicPostNextAction, PublicPostFailure } from './post-failure';
+export type { ListProfilePostsParams, ListProfilePostsResult, DownloadSocialPostParams, DownloadSocialPostResult, SocialReferencePost, SocialReferenceAsset } from './social-acquisition';

package/package.json

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