ugcinc 4.26.1 → 4.27.0

package/README.md

@@ -357,6 +357,195 @@ 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.
 
+## Native iMessage conversations and PNG snapshots (staged)
+
+The native conversation API is implemented behind a rollout gate and is **not yet
+enabled on the public service**. Until rollout, submission returns a retryable 503.
+The existing still-image DM renderer remains available separately.
+
+Quick reference: `client.media.renderIMessageConversation(input)` queues a video by default;
+`client.media.getIMessageConversation({jobId})` polls its status.
+`client.media.cancelIMessageConversation({jobId})` requests cancellation and native cleanup.
+`compileIMessageConversation(input)` previews its deterministic timing plan locally.
+
+```ts
+import {UGCClient, compileIMessageConversation, type IMessageConversationInput} from 'ugcinc';
+
+const client = new UGCClient({apiKey: 'YOUR_API_KEY', orgId: 'YOUR_ORG_ID'});
+const input = {
+  idempotencyKey: 'conversation-v1',
+  contact: {name: 'Alex'},
+  theme: 'dark',
+  statusBar: {time: '12:34', wifiBars: 3, cellularBars: 4, batteryPercent: 85},
+  unreadCount: 12,
+  timestampText: 'Today 12:34 PM',
+  seed: 42,
+  timing: {charactersPerSecond: 7, pauseBeforeMs: 500, pauseBeforeSendMs: 200, incomingTypingDurationMs: 2400},
+  messages: [
+    {sender: 'recipient', text: 'Ready?', initial: true},
+    {sender: 'user', text: 'On my way 👋'},
+    {sender: 'recipient', text: 'See you soon!', timing: {incomingTypingDurationMs: 3200}},
+  ],
+} satisfies IMessageConversationInput;
+const plan = compileIMessageConversation(input);
+const submitted = await client.media.renderIMessageConversation(input);
+if (submitted.ok) {
+  const status = await client.media.getIMessageConversation({jobId: submitted.data.jobId});
+  if (status.ok && status.data.status === 'completed') console.log(status.data.url);
+}
+// A lossless frame from the same native scene. Omit atMs for its final frame.
+const still = await client.media.renderIMessageConversation({
+  ...input, idempotencyKey: 'conversation-png-v1', output: {kind: 'png', atMs: 500},
+});
+```
+
+API reference:
+
+- `POST /media/render/imessage`: authenticated organization-scoped submission.
+- `POST /media/render/imessage/status`: `{jobId}`; only jobs owned by that
+  organization can be queried.
+- `POST /media/render/imessage/cancel`: `{jobId}`; requests cancellation for an
+  owned job. Poll status until `cancelled` or another terminal status. A pending
+  request returns `cancelRequested: true`; it does not claim native cleanup has
+  finished. Completed jobs retain their result if cancellation arrives too late.
+  Scoped keys need `content:render` for all three routes.
+- These return the normal `ApiResponse`. Job data includes `jobId`,
+  `status: pending | processing | completed | failed | cancelled`, `progress`, `fps: 60`,
+  `durationMs` (planned timeline duration) and `durationInFrames`. Completed jobs
+  include an owned HTTPS `url`, `output` settings and `contentType` (`video/mp4`
+  or `image/png`). Failed jobs include a safe error and retryability.
+  Submission does not wait for completion.
+- Output uses the pinned `iphone-xs-ios18.6.2` UI, native text/emoji and native
+  conversation motion. Video is 60fps H264; it is not frame-interpolated.
+  Native frames are 1125×2436; MP4 adds one background-colored column for an
+  even 1126-pixel codec width. This profile does not represent newer iOS designs.
+- `output` defaults to `{kind: 'video'}`. `{kind: 'png', atMs: 500}` returns the
+  original 1125×2436 native full-frame PNG bytes at that exact millisecond timestamp;
+  omitting `atMs` selects the final authored frame. Times outside the planned
+  conversation reject. PNG uses the same native scene and transitions, with no
+  resizing, separate text renderer or lossy video-frame extraction. For PNG jobs,
+  `durationInFrames` is 1 while `durationMs` still describes the authored timeline;
+  the renderer completes outstanding native actions privately for clean teardown.
+- `contact.name` is the other person's display name/username. Optional
+  `contact.avatarPngBase64` is a PNG without a data-URL prefix, at most 512×512
+  and 65536 base64 characters; the native ContactsUI component crops it. It is
+  an in-memory render input and does not create or save a real contact.
+- `statusBar` supports `time` (H:mm/HH:mm, default `9:41`), `wifiBars` (0–3,
+  default 3), `cellularBars` (0–4, default 4), `wifiEnabled`/`cellularEnabled`
+  (default true), `batteryPercent` (0–100, default 100), `charging` and
+  `lowPowerMode` (default false). Capacity controls the native battery fill;
+  it does not turn on a numerical percentage label. These configure render
+  models, not the host phone's clock, network or battery settings.
+- `unreadCount` (0–9999, default 0) controls the native back-button badge.
+  The number of conversation messages is simply `messages.length`; there is
+  no second message-count field to keep in sync. Optional `timestampText`
+  replaces native date-header text, independently of the status-bar clock.
+- Provide `contact: {name}` or `group` (described below). `theme` defaults to `dark`, `keyboard` to `true`,
+  `fps` to `60` (the only supported rate), `seed` to `0`, and `endHoldMs` to `1500`
+  (350–10000). `showIncomingTyping` defaults to `true`.
+- Messages require a `sender` ID (`user | recipient` for direct chats, or a group participant ID) and either nonempty `text` (up to 2000
+  UTF-16 code units) or `imagePngBase64`. Image captions and mixed text/image
+  messages are rejected. An image must be a single-frame PNG, without a data URL
+  prefix, at most 2048×2048 and 8 MiB of base64 characters. The full request is
+  limited to 16 MiB; aggregate message image dimensions cannot exceed 16,777,216
+  pixels. Outgoing images enter the native composer before send; the plan reserves
+  its native attachment transition plus `pauseBeforeSendMs`. Initial and incoming
+  images do not open the local composer. `user` is outgoing. Optional IDs must be unique; otherwise
+  IDs are generated. `initial: true` supplies preexisting history and must be a
+  prefix. Incoming messages may override `showTyping`; their text is hidden
+  until arrival. Outgoing text appears in the composer.
+- Outgoing messages accept `receipt: none | delivered | read` (default `none`).
+  Read state requires `readAt`, an ISO timestamp with timezone. Animated receipts
+  appear `receiptDelayMs` after arrival (0–30000, default 500); history receipts
+  are present initially. As in Messages, the visible receipt belongs to the
+  latest outgoing message; older receipts disappear when a newer one is sent.
+  Delayed receipts extend the render duration so they are not truncated.
+- Default `timing`: `charactersPerSecond: 8` (0.5–60), `pauseBeforeMs: 450`
+  (0–30000), `pauseBeforeSendMs: 180` (0–10000), `punctuationPauseMs: 160`
+  (0–2000), `variation: 0.15` (0–0.75). Each message can override any setting.
+  Pauses use milliseconds. Typing speed counts complete visible grapheme clusters,
+  including a whole family emoji or combining-accent sequence as one character.
+  Variation uses the supplied seed. The plan reserves native transition completion
+  before starting the next message, then applies `pauseBeforeMs` before typing.
+- Outgoing emoji input is represented explicitly in the authoring timeline:
+  open the native emoji keyboard, focus an emoji, select it, then return to the
+  letter keyboard when subsequent text needs it. `timing.keyboardSwitchPauseMs`
+  (350–10000, default 450) controls the pause after switching keyboards;
+  `timing.emojiSelectionDelayMs` (100–10000, default 350) controls the pause before
+  selecting a focused emoji. These can be overridden per message. Complete
+  grapheme sequences are preserved. Incoming emoji text never opens the local
+  keyboard. Outgoing emoji interactions require `keyboard: true`. Emoji that require
+  an unsupported long-press skin-tone or family picker reject instead of being
+  inserted through an invisible shortcut.
+- Optional `timing.incomingTypingDurationMs` (0–30000) sets the exact interval
+  from the other person's typing indicator starting until their message arrives.
+  Set it globally or override it in an incoming message's `timing` (for example
+  2400 globally and 3200 for a longer reply). `pauseBeforeMs` still controls when
+  typing starts. This replaces the incoming duration calculated from character
+  speed, punctuation and the pre-send pause; outgoing composer speed is unchanged.
+  Omit it to retain the calculated duration. Zero is supported. With
+  `showTyping: false`, the same response delay applies without a visible indicator.
+  Setting this field on an outgoing message rejects.
+- `replyTo` on a message names an earlier message ID. Native thread identity,
+  quoted context and reply grouping are derived on the render host. Replies to
+  replies remain in their original thread, while the visible reply gesture targets
+  the exact message named by `replyTo`. For an animated local reply, the compiler
+  emits `reply.begin`, long-presses that message, opens its native menu, selects
+  **Reply**, and waits for the reply view before typing and sending inside it.
+  It emits `reply.end` after sending and closes the
+  reply view before the next local action. `pauseBeforeMs` occurs before the
+  gesture; the compiled `typingStartMs` records when typing actually starts after
+  the opening transition. Incoming replies and initial history show their reply
+  associations without operating the local reply controls. Animated local replies
+  require `keyboard: true`; incoming replies and history also work without it.
+- Use `contact` for a direct chat, or `group: {name, localParticipantId,
+  participants: [{id, name}]}` for a group. Provide exactly one. A group has
+  3–20 participants including the local participant; IDs are unique. Message
+  `sender` and reaction `actor` use those IDs. For direct chats they remain
+  `user` and `recipient`. Group names, sender labels, avatars and bubble
+  grouping use the native group conversation UI. Optional `group.avatarPngBase64`
+  and `participants[].avatarPngBase64` accept the same bounded PNG format as
+  `contact.avatarPngBase64`.
+- `statusBar.time` controls only the clock. Top-level `timestampText` controls
+  the first conversation separator independently. Optional message `sentAt`
+  sets the actual conversation date (ISO 8601 with timezone); provide it for
+  every message in chronological order when used. Native date-gap rules create
+  later separators. A message's optional `timestampText` forces a separator
+  before it and sets its displayed text, such as `Today 3:10 PM`. These dates
+  do not affect typing speed or make the rendered video wait through the gap.
+- A message's optional `reactions` array schedules reactions relative to that
+  message's arrival (or video start for initial history). Each entry takes an
+  `actor`, `delayMs` (0–60000, default 700), and either a classic `reaction:
+  love | like | dislike | laugh | emphasize | question` or one `emoji`.
+  Local actions open the native reaction picker, hold it for `menuDurationMs`
+  (400–10000, default 700), then select the reaction. They reserve the local
+  interaction timeline until dismissal completes before further typing or
+  another local reaction. `delayMs` is the earliest picker-open time for local
+  actions, and the arrival time for remote reactions. Remote reactions do not
+  show a local picker. Custom emoji currently work for remote participants;
+  local actions accept the six classic picker options. `action: remove`
+  selects the actor's current reaction again through the picker, and takes no
+  reaction/emoji value. Setting again replaces the actor's previous reaction.
+  At most 20 reaction events per message are accepted.
+- Optional `threads: [{messageId, openAtMs, durationMs}]` opens and closes the
+  native expanded reply view for reading. These explicit thread views run after
+  the conversation and its native transitions settle; typing/sending during
+  these read-only views is not supported. Animated local `replyTo` messages use
+  their own reply-composition flow described above. Duration is 600–30000ms, at most ten views, without
+  overlap. The original conversation returns when the view closes.
+- Maximum 30 messages, 6000 animated visible characters and a planned duration of
+  120 seconds. Invalid or excessive requests reject before device use. The local
+  compiler exposes message arrival times, events and frame count.
+- Optional `idempotencyKey` (1–128 characters) deduplicates submissions within an
+  organization. Reuse the same body/key to recover the same job; changing the body
+  returns 409. To retry a failed render, use a new key or omit it. Job ownership
+  records are retained for seven days.
+- This authoring API currently supports text/emoji, initial history and sequential
+  conversations with configurable chrome, receipts, reactions and replies. Image attachments,
+  carrier-name/network-type selection, numerical
+  battery-percentage display and arbitrary timeline seeking are not accepted
+  by this contract. Unknown input fields reject rather than silently approximating them.
+
 ## Video inspection
 
 ```ts

package/dist/automations/nodes/create-dm.d.ts

@@ -1,4 +1,5 @@
-import type { ImageValue, TextValue, BooleanValue } from '../types';
+import type { ImageValue, VideoValue, TextValue, BooleanValue } from '../types';
+import type { IMessageConversationInput } from '../../imessage-conversation';
 import { type InputType, type OutputMode, type SelectionMode } from './types';
 /** Create DM message structure */
 export interface CreateDmMessage {
@@ -8,6 +9,7 @@ export interface CreateDmMessage {
 }
 /** Create DM inputs - optional based on inputType settings */
 export interface CreateDmNodeInputs {
+    conversation?: IMessageConversationInput;
     platform?: TextValue;
     'light-mode'?: BooleanValue;
     username?: TextValue;
@@ -21,12 +23,15 @@ export interface CreateDmNodeInputs {
 }
 /** Create DM has a fixed 'output' port. */
 export interface CreateDmNodeOutputs {
-    output: ImageValue;
+    output: ImageValue | VideoValue;
 }
 export type DmPlatform = 'imessage' | 'instagram';
 declare const definition: import("./types").NodeDefinition<"create-dm", "generator", {
     platform: DmPlatform;
     platformInputType: InputType;
+    imessageRenderMode: "still" | "conversation";
+    imessageConversationInputType: InputType;
+    imessageConversation: IMessageConversationInput | undefined;
     lightMode: boolean;
     lightModeInputType: InputType;
     username: string;

package/dist/automations/nodes/create-dm.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const imessage_conversation_1 = require("../../imessage-conversation");
 const types_1 = require("./types");
 // =============================================================================
 // Node Definition
@@ -7,8 +8,8 @@ const types_1 = require("./types");
 const definition = (0, types_1.defineNode)({
     nodeId: 'create-dm',
     label: 'Create DM',
-    description: 'Create fake DM screenshots for iMessage or Instagram',
-    guide: 'Renders realistic DM/conversation screenshots (iMessage or Instagram). Best for videos that simulate a conversation—e.g. rizz help, dating advice, or "what would you reply" style content. Use cases: rizz help videos, conversation simulations, dating advice content. Configure platform, light/dark mode, messages, profile pic. Messages can be static or variable (from LLM). Output is an image for Image Composer or Auto Post. Supports dynamic crop to isolate specific messages.',
+    description: 'Create DM screenshots or native iMessage videos and snapshots',
+    guide: 'Still mode renders legacy iMessage or Instagram screenshots with optional dynamic cropping. Conversation mode renders a native 60fps iMessage video with visible outgoing typing, incoming typing indicators, replies, reactions, receipts and group participants. Set imessageRenderMode to conversation and provide imessageConversation using the public IMessageConversationInput schema; alternatively connect the conversation object input. Native output defaults to video; output {kind: png, atMs: 500} exports a lossless native frame at 500ms, or omit atMs for the final frame. Static native PNG settings expose an image port; dynamic conversation inputs expose image|video. It requires platform imessage with static platform selection. Legacy still mode remains unchanged.',
     type: 'generator',
     category: 'Generation',
     outputModes: ['per-input', 'single'],
@@ -16,6 +17,9 @@ const definition = (0, types_1.defineNode)({
     defaults: {
         platform: 'instagram',
         platformInputType: 'static',
+        imessageRenderMode: 'still',
+        imessageConversationInputType: 'static',
+        imessageConversation: undefined,
         lightMode: true,
         lightModeInputType: 'static',
         username: '',
@@ -48,7 +52,27 @@ const definition = (0, types_1.defineNode)({
         outputMode: 'per-input',
         selectionMode: null,
     },
+    validate: config => {
+        if (config.imessageRenderMode !== 'conversation')
+            return [];
+        if (config.platform !== 'imessage' || config.platformInputType === 'variable') {
+            return ['Conversation video mode requires iMessage with static platform selection.'];
+        }
+        if (config.imessageConversationInputType === 'variable')
+            return [];
+        const parsed = imessage_conversation_1.iMessageConversationSchema.safeParse(config.imessageConversation);
+        return parsed.success ? [] : parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`);
+    },
     computePorts: ({ config }) => {
+        if (config?.imessageRenderMode === 'conversation') {
+            return {
+                inputs: config.imessageConversationInputType === 'variable'
+                    ? [{ id: 'conversation', type: 'object', isArray: false, required: true }]
+                    : [],
+                outputs: [{ id: 'output', type: config.imessageConversationInputType === 'variable' ? ['image', 'video']
+                            : config.imessageConversation?.output?.kind === 'png' ? 'image' : 'video', isArray: false, required: true }],
+            };
+        }
         const inputs = [];
         if (config?.platformInputType === 'variable') {
             inputs.push({ id: 'platform', type: 'text', isArray: false, required: true });

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

@@ -101,6 +101,9 @@ export declare const nodeDefinitions: {
     readonly 'create-dm': NodeDefinition<"create-dm", "generator", {
         platform: import("./create-dm").DmPlatform;
         platformInputType: import("./types").InputType;
+        imessageRenderMode: "still" | "conversation";
+        imessageConversationInputType: import("./types").InputType;
+        imessageConversation: import("../..").IMessageConversationInput | undefined;
         lightMode: boolean;
         lightModeInputType: import("./types").InputType;
         username: string;
@@ -333,6 +336,8 @@ export declare const nodeDefinitions: {
         __TOutputs: import("./screenshot-animation").ScreenshotAnimationNodeOutputs;
     };
     readonly 'remotion-composition': NodeDefinition<"remotion-composition", "generator", {
+        fps: number;
+        durationInFrames: number;
         width: number;
         height: number;
         source: string;
@@ -340,13 +345,11 @@ export declare const nodeDefinitions: {
         selectionMode: null;
         outputType: "video" | "image";
         inputs: {
-            type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+            type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
             id: string;
             isArray: boolean;
             required: boolean;
         }[];
-        fps: number;
-        durationInFrames: number;
         inputProps: Record<string, unknown>;
     }, {
         [x: string]: import("../types").PortValue | import("../types").PortValue[];

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

@@ -4,6 +4,8 @@ type Outputs = {
     output: VideoValue;
 };
 declare const defaults: {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
@@ -11,16 +13,16 @@ declare const defaults: {
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
 };
 declare const _default: import("./types").NodeDefinition<"remotion-composition", "generator", {
+    fps: number;
+    durationInFrames: number;
     width: number;
     height: number;
     source: string;
@@ -28,13 +30,11 @@ declare const _default: import("./types").NodeDefinition<"remotion-composition",
     selectionMode: null;
     outputType: "video" | "image";
     inputs: {
-        type: "number" | "boolean" | "object" | "video" | "image" | "text" | "audio";
+        type: "number" | "boolean" | "object" | "text" | "video" | "image" | "audio";
         id: string;
         isArray: boolean;
         required: boolean;
     }[];
-    fps: number;
-    durationInFrames: number;
     inputProps: Record<string, unknown>;
 }, Inputs, Outputs, false> & {
     __TInputs: Inputs;