ugcinc 4.19.1 → 4.21.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,84 @@ 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 });
+```
+
+`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.
+
+## Video inspection
+
+```ts
+const frames = await client.media.extractFrames({url: videoUrl, timestampsMs: [0, 1500, 3000]});
+const scenes = await client.media.detectScenes({url: videoUrl});
+// Recover a pending job without submitting another analysis:
+const status = await client.media.getMediaAnalysis({jobId});
+```
 
-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.
+These methods use authenticated `POST /media/analysis/extract-frames`,
+`POST /media/analysis/detect-scenes` and `POST /media/analysis/status`.
+They require an organization and `content:analyze`. Agent tools are `extract_frames`,
+`detect_scenes` and the supporting `get_media_analysis` status operation.
+
+Extraction accepts either `timestampsMs` (1–48 values, including timestamps from other
+analysis results) or `range: {startMs,endMs,intervalMs}` (end exclusive, maximum 48
+samples). `selection` is `nearest` (default; ties choose the earlier frame), `before`
+or `after`. Times are milliseconds from the first displayed video frame. Out-of-range
+requests fail; `after` fails if no later frame exists. Returned frames include requested
+and actual times, original integer PTS as a string, decoded frame index, dimensions
+and owned PNG URL. Rotation and sample aspect ratio are applied; outputs fit within
+1280 pixels on each axis without upscaling. `contactSheet` defaults to true and returns
+a labeled sheet with cell boxes linked to the individual images. Duplicate requests
+retain their order and may reference the same decoded frame.
+
+Scene detection reuses the existing adaptive and brightness/pHash detector and returns
+source-time ranges, frame indices and detector settings. It does not export split MP4s.
+Ranges end exclusively. The last scene ends at video duration; its endPts is null when
+there is no following frame. Boundaries are detector estimates, especially for fades,
+not a guarantee of semantic scenes or an exact creative edit point.
+
+Both operations run as bounded worker jobs. SDK/tool calls make up to 180 status polls, spaced two seconds apart;
+check `data.status`: pending/processing includes `jobId` for subsequent status calls,
+completed includes `result`, and failed includes an explicit error. A successful HTTP
+response does not imply job completion. Status handles belong to their organization
+and expire after seven days. Each submission analyzes the current source bytes rather
+than caching by URL. Results include source SHA-256, encoded/display dimensions,
+rotation, time base, source starting PTS, decoded frame count and an owned manifest.
+Video URLs must be public HTTPS sources. Limits: 100 MB, 30 minutes, 4096 pixels per
+encoded dimension, 120,000 decoded frames. Unsupported/malformed media fails explicitly.

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

@@ -333,18 +333,18 @@ export declare const nodeDefinitions: {
         __TOutputs: import("./screenshot-animation").ScreenshotAnimationNodeOutputs;
     };
     readonly 'remotion-composition': NodeDefinition<"remotion-composition", "generator", {
+        width: number;
+        height: number;
         source: string;
         outputMode: "per-input" | "single";
         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;
         }[];
-        width: number;
-        height: number;
         fps: number;
         durationInFrames: number;
         inputProps: Record<string, unknown>;

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

@@ -4,35 +4,35 @@ type Outputs = {
     output: VideoValue;
 };
 declare const defaults: {
+    width: number;
+    height: number;
     source: string;
     outputMode: "per-input" | "single";
     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;
     }[];
-    width: number;
-    height: number;
     fps: number;
     durationInFrames: number;
     inputProps: Record<string, unknown>;
 };
 declare const _default: import("./types").NodeDefinition<"remotion-composition", "generator", {
+    width: number;
+    height: number;
     source: string;
     outputMode: "per-input" | "single";
     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;
     }[];
-    width: number;
-    height: number;
     fps: number;
     durationInFrames: number;
     inputProps: Record<string, unknown>;

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,6 @@ 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';
+export type { ExtractFramesParams, DetectScenesParams, FramesResult, ScenesResult, MediaAnalysisResult, MediaAnalysisJob } from "./media-analysis";
+export { extractFramesSchema, detectScenesSchema, mediaAnalysisStatusSchema, mediaAnalysisResultSchema } from "./media-analysis";

package/dist/index.js

@@ -7,7 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasMissingTriggerError = exports.getPortErrorsForNode = exports.getErrorNodeIds = exports.validateWorkflow = exports.getCapturedNodes = exports.getNodesDownstreamOfSet = exports.getDownstreamNodes = exports.checkCrossContextViolation = exports.getForEachContext = exports.getConnectedSource = exports.cleanupStaleConnections = exports.removeNodeConnections = exports.removeConnection = exports.addConnection = exports.deriveConnections = exports.createNode = exports.getOutputSchema = exports.getNodeByType = exports.getAllNodes = exports.getInputPreviewValue = exports.computeAllNodePortsWithPreviews = exports.computeAllNodePorts = exports.computePortsWithPreviews = exports.computePortsForNode = exports.areTypesCompatible = exports.parseRemotionPropsJson = exports.REMOTION_COMPOSITION_IMPORTS = exports.remotionCompositionPortSchema = exports.remotionCompositionNodeSchema = exports.remotionCompositionSchema = exports.submitIMessageDmRenderJob = exports.submitInstagramDmRenderJob = exports.submitAutoCaptionRenderJob = exports.submitRemotionCompositionRenderJob = exports.submitScreenshotAnimationRenderJob = exports.submitSceneSplitJob = exports.submitDeduplicationJob = exports.getRenderJobStatus = exports.submitVideoRenderJob = exports.submitImageRenderJob = exports.BillingClient = exports.CommentsClient = exports.MediaClient = exports.AutomationsClient = exports.OrganizationClient = exports.StatsClient = exports.PostsClient = exports.TasksClient = exports.AccountsClient = exports.UGCClient = void 0;
 exports.parseOpenAPIOutputPath = exports.parseOpenAPIInputs = exports.mapOpenAPIType = exports.nodeConfigToCaptionStyle = exports.HttpMethods = exports.prepareImageComposerInput = exports.substituteVariables = exports.processTemplate = exports.extractTemplateVariables = exports.PortIdSchema = exports.normalizeToPortId = exports.portIdToTitle = exports.isValidPortId = exports.portId = exports.selectFromPool = exports.getModelDurations = exports.getModelAspectRatios = exports.ALL_VIDEO_MODELS = exports.getAvailableInputModes = exports.hasReferenceVariant = exports.getReferenceModelId = exports.hasFirstLastFrameVariant = exports.getFirstLastFrameModelId = exports.hasImageToVideoVariant = exports.getImageToVideoModelId = exports.isImageToVideoModel = exports.IMAGE_ASPECT_RATIOS = exports.ALL_IMAGE_MODELS = exports.getEditModelId = exports.isEditModel = exports.getCapturedSourceNodeTypes = exports.getFlowControlNodeTypes = exports.getAllNodeDefinitions = exports.getNodeDefinition = exports.isPortType = exports.formatPortType = exports.isAsyncExecutor = exports.internalNodeTypes = exports.nodeDefinitions = exports.extractWorkflowConfig = exports.generateNodeName = exports.shuffleNodePreview = exports.getPreviewValue = exports.removePreviewForConnection = exports.updatePreviewMapForConnection = exports.computePreviewMap = exports.computeAllNodePreviews = exports.resolveNodePreview = exports.getWorkflowOutputSchema = exports.hasMissingTerminalError = void 0;
-exports.prepareVideoComposerInput = exports.formatDateTag = exports.outputFieldsToZod = exports.outputFieldToZod = exports.LLMProviders = exports.applyLogicOperator = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToString = exports.indexExpressionToIndexes = exports.resolveUnknownPath = exports.getOutputTypeFromCategory = void 0;
+exports.mediaAnalysisResultSchema = exports.mediaAnalysisStatusSchema = exports.detectScenesSchema = exports.extractFramesSchema = exports.prepareVideoComposerInput = exports.formatDateTag = exports.outputFieldsToZod = exports.outputFieldToZod = exports.LLMProviders = exports.applyLogicOperator = exports.IfLogicOperators = exports.resolvePath = exports.indexExpressionToString = exports.indexExpressionToIndexes = exports.resolveUnknownPath = exports.getOutputTypeFromCategory = void 0;
 // =============================================================================
 // Client Exports
 // =============================================================================
@@ -174,3 +174,8 @@ var save_to_media_1 = require("./automations/nodes/save-to-media");
 Object.defineProperty(exports, "formatDateTag", { enumerable: true, get: function () { return save_to_media_1.formatDateTag; } });
 var video_composer_1 = require("./automations/nodes/video-composer");
 Object.defineProperty(exports, "prepareVideoComposerInput", { enumerable: true, get: function () { return video_composer_1.prepareVideoComposerInput; } });
+var media_analysis_1 = require("./media-analysis");
+Object.defineProperty(exports, "extractFramesSchema", { enumerable: true, get: function () { return media_analysis_1.extractFramesSchema; } });
+Object.defineProperty(exports, "detectScenesSchema", { enumerable: true, get: function () { return media_analysis_1.detectScenesSchema; } });
+Object.defineProperty(exports, "mediaAnalysisStatusSchema", { enumerable: true, get: function () { return media_analysis_1.mediaAnalysisStatusSchema; } });
+Object.defineProperty(exports, "mediaAnalysisResultSchema", { enumerable: true, get: function () { return media_analysis_1.mediaAnalysisResultSchema; } });