ugcinc 4.27.0 → 5.0.1

package/README.md

@@ -357,11 +357,11 @@ 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)
+## Native iMessage conversations and PNG snapshots
 
-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.
+These methods require a deployment with native rendering enabled. An unavailable
+native service 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.
@@ -474,9 +474,12 @@ API reference:
   `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.
+  keyboard. Outgoing emoji interactions require `keyboard: true`. Skin-tone
+  variants open the native variant selector and choose its visible option.
+  Supported family variants select each native tone row, then select the
+  configured family preview to commit. The selected native emoji must match the
+  requested sequence exactly; unavailable variants reject. Personal recents and
+  saved emoji preferences are not used or modified.
 - 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
@@ -540,11 +543,10 @@ API reference:
   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.
+- This authoring API supports text/emoji, PNG image messages, initial history and
+  sequential conversations with configurable chrome, receipts, reactions and replies.
+  Image captions, carrier-name/network-type selection, numerical battery-percentage
+  display and arbitrary low-level native event scripts are not accepted by this contract. Unknown input fields reject rather than silently approximating them.
 
 ## Video inspection
 
@@ -704,3 +706,45 @@ layout/readability, asset identity, procedural animation, CTA and audio handling
 It distinguishes measured facts from inference and requires verified public
 HTTPS previews. SAM-dependent capabilities remain deferred and are not advertised
 as available tools. A successful API call alone does not certify content quality.
+
+## Native iMessage workflows (5.0)
+
+All iMessage images and videos use the native service. The Remotion iMessage
+composition/player exports, `submitIMessageDmRenderJob` and its old payload types
+were removed; use authenticated `client.media.renderIMessageConversation`,
+`getIMessageConversation` and `cancelIMessageConversation`. Instagram remains
+unchanged. This is a major version because the old public exports were removed.
+
+Create DM uses explicit `imessageOutputType: "image" | "video"` independently of
+variable authoring data. Select `platform: "imessage"`, `platformInputType:
+"static"`, `imessageRenderMode: "conversation"`, and either set
+`imessageConversation` or connect `conversation` with
+`imessageConversationInputType: "variable"`. Static PNG timing still uses the
+conversation's `output: {kind:"png",atMs:...}`. Variable inputs declaring the
+opposite output kind reject instead of changing the connected output type.
+
+Saved screenshot inputs are translated at execution without database rewrites;
+existing message/avatar/attachment connections remain usable. Custom bubble
+colors, message-based cropping and free-text legacy receipts require explicit
+correction. Use the native editor for receipts and downstream composition for
+cropping. There is no fallback to the old renderer.
+
+Contact/group/participant `avatarUrl` and message `imageUrl` accept public HTTPS
+PNG/JPEG/WebP images. The API resolves them into bounded PNGs (avatar fits96px,
+message image fits2048px; at most12MiB source bytes per URL). Supply exactly one
+image source per avatar and one body per message. `imagePngBase64` and
+`avatarPngBase64` remain supported. URL resolution rejects private destinations,
+unsafe redirects, oversized/invalid media and requests exceeding image budgets.
+
+Agents can use `compile_imessage_conversation` locally, then
+`render_imessage_conversation`, `get_imessage_conversation` and
+`cancel_imessage_conversation`. Compile does not require an API key. Rendering
+needs an existing key authorized for `content:render` and the correct org.
+Submission returns immediately; poll to a terminal job state. See
+https://docs.ugc.inc/guides/imessage-conversations for the full contract.
+
+Install the bundled instructions with:
+
+```bash
+npx ugcinc@5.0.0 init --update imessage media content-automation automations
+```

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

@@ -31,6 +31,9 @@ declare const definition: import("./types").NodeDefinition<"create-dm", "generat
     platformInputType: InputType;
     imessageRenderMode: "still" | "conversation";
     imessageConversationInputType: InputType;
+    imessageOutputType: "video" | "image" | undefined;
+    imessageLegacyInputs: boolean;
+    imessageAttachmentMessageId: string;
     imessageConversation: IMessageConversationInput | undefined;
     lightMode: boolean;
     lightModeInputType: InputType;

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

@@ -1,15 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const imessage_conversation_1 = require("../../imessage-conversation");
+const imessage_workflow_1 = require("../../imessage-workflow");
 const types_1 = require("./types");
 // =============================================================================
 // Node Definition
 // =============================================================================
+function optionalOutput() { return undefined; }
 const definition = (0, types_1.defineNode)({
     nodeId: 'create-dm',
     label: 'Create DM',
     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.',
+    guide: 'iMessage uses the native service for both PNG images and 60fps videos. Set platform imessage, imessageRenderMode conversation, imessageOutputType image or video, and imessageConversation with public authoring JSON. Use imessageConversationInputType variable for the conversation object input. The output selector fixes the output port type. Connect profile-pic with profilePicInputType variable for a direct-chat avatar; connect image-attachment with imageAttachmentInputType variable and imessageAttachmentMessageId for a message image. Public HTTPS avatarUrl/imageUrl fields also resolve to bounded PNGs internally. Legacy screenshot nodes are adapted to native PNG with connections preserved; unsupported crop/bubble colors/read receipts require explicit correction. Instagram keeps its screenshot renderer.',
     type: 'generator',
     category: 'Generation',
     outputModes: ['per-input', 'single'],
@@ -19,6 +20,9 @@ const definition = (0, types_1.defineNode)({
         platformInputType: 'static',
         imessageRenderMode: 'still',
         imessageConversationInputType: 'static',
+        imessageOutputType: optionalOutput(),
+        imessageLegacyInputs: false,
+        imessageAttachmentMessageId: '',
         imessageConversation: undefined,
         lightMode: true,
         lightModeInputType: 'static',
@@ -53,25 +57,34 @@ const definition = (0, types_1.defineNode)({
         selectionMode: null,
     },
     validate: config => {
-        if (config.imessageRenderMode !== 'conversation')
+        if (config.platform !== 'imessage')
             return [];
-        if (config.platform !== 'imessage' || config.platformInputType === 'variable') {
-            return ['Conversation video mode requires iMessage with static platform selection.'];
-        }
-        if (config.imessageConversationInputType === 'variable')
+        const issues = (0, imessage_workflow_1.legacyIMessageIssues)(config);
+        if (issues.length)
+            return issues;
+        if (config.platformInputType === 'variable' && (0, imessage_workflow_1.iMessageWorkflowOutput)(config) === 'video')
+            return ['Native iMessage video requires static platform selection.'];
+        if (config.imessageRenderMode === 'conversation' && config.imessageConversationInputType === 'variable')
+            return [];
+        if (config.imessageRenderMode !== 'conversation' && [config.messagesInputType, config.usernameInputType, config.timeInputType, config.imageAttachmentInputType].includes('variable'))
+            return [];
+        try {
+            (0, imessage_workflow_1.prepareIMessageWorkflow)(config);
             return [];
-        const parsed = imessage_conversation_1.iMessageConversationSchema.safeParse(config.imessageConversation);
-        return parsed.success ? [] : parsed.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`);
+        }
+        catch (error) {
+            return [error instanceof Error ? error.message : 'Invalid iMessage conversation.'];
+        }
     },
     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 }],
-            };
+        if (config?.imessageRenderMode === 'conversation' && !config.imessageLegacyInputs) {
+            const inputs = config.imessageConversationInputType === 'variable'
+                ? [{ id: 'conversation', type: 'object', isArray: false, required: true }] : [];
+            if (config.profilePicInputType === 'variable')
+                inputs.push({ id: 'profile-pic', type: 'image', isArray: false, required: false });
+            if (config.imageAttachmentInputType === 'variable')
+                inputs.push({ id: 'image-attachment', type: 'image', isArray: false, required: true });
+            return { inputs, outputs: [{ id: 'output', type: (0, imessage_workflow_1.iMessageWorkflowOutput)(config), isArray: false, required: true }] };
         }
         const inputs = [];
         if (config?.platformInputType === 'variable') {
@@ -128,7 +141,7 @@ const definition = (0, types_1.defineNode)({
         });
         return {
             inputs,
-            outputs: [{ id: 'output', type: 'image', isArray: false, required: true }],
+            outputs: [{ id: 'output', type: config?.platform === 'imessage' ? (0, imessage_workflow_1.iMessageWorkflowOutput)(config) : 'image', isArray: false, required: true }],
         };
     },
     generatePreview: (_config, _ctx, cachedOutputs) => {

package/dist/cli.js

@@ -212,7 +212,7 @@ async function runTool(toolName, rawParams) {
         }));
         process.exit(1);
     }
-    const apiKey = loadEnvVar('UGC_API_KEY');
+    const apiKey = loadEnvVar('UGC_API_KEY') ?? (toolName === 'compile_imessage_conversation' ? 'local-compilation-only' : undefined);
     if (!apiKey) {
         console.error(JSON.stringify({
             ok: false,

package/dist/content-skills.js

@@ -3,8 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.contentSkillFiles = void 0;
 // Generated by scripts/build-skills.cjs; edit skills/** instead.
 exports.contentSkillFiles = {
-    "media/SKILL.md": "---\nname: media\ndescription: Acquire TikTok and Instagram posts and inspect images, video and audio with UGC Inc tools. Use for reference analysis, OCR, frames, scenes, transcription, colors, layout, text-style fitting, or media-library management.\nallowed-tools: Bash, Read\n---\n\nUse the installed UGC Inc CLI:\n\n```bash\nnpx ugcinc --list\nnpx ugcinc <tool_name> '<json_params>'\n```\n\nCredentials come from `UGC_API_KEY` or existing UGC configuration. Use the user's\norganization and a key with `content:analyze` for acquisition/analysis. If using\nan admin key, pass the authorized `orgId` in the JSON parameters. Do not print\ncredentials, copy an administrator key to another user's machine, or change\norganizations to bypass a denial. Confirm access with one small tool call.\nIf credentials already live in an app env file, set `UGC_ENV_FILE` to that file's\npath so the CLI reads the existing key without duplicating its contents. Set\n`UGC_ORG_ID` in that file or the process environment to scope calls to the user's\norganization; an explicit JSON `orgId` takes priority.\n\nRead [references/tools.md](references/tools.md) for request shapes, result fields\nand limits. The CLI lists names/descriptions; the reference explains parameters.\n\n## Choose the input and tools\n\n- A profile URL: `list_profile_posts` discovers a bounded page; follow its cursor\n  only as needed. Listing does not download media or guarantee complete history.\n- A post URL: `download_social_post` ingests its ordered assets into owned media.\n  Use returned asset URLs for analysis; the TikTok/Instagram HTML URL is not a\n  video file. Check complete/partial/failed status and failed assets.\n- A direct media URL: use the corresponding inspection tool directly.\n- Video: `detect_scenes`, `extract_frames`, `read_video_text`; audio tools accept\n  video too. Inspect multiple moments, including changes near the beginning/end.\n- Image: `read_image_text`, `sample_colors`, `measure_layout` using supplied\n  boxes/masks, and `match_text_style` for a specified text crop.\n- Audio: `transcribe_audio` and `measure_audio_levels`.\n\nThe SDK/CLI waits for processing automatically. Check both the outer response's\n`ok` and the returned job's `status`. Analysis is usable when\n`data.status === \"completed\"`; its content is `data.result`. If still pending or\nprocessing, keep its job ID and use `get_media_analysis` rather than resubmitting.\nUse bounded retries for retryable failures; report persistent errors/partial\ncoverage. A zero process exit code alone does not establish API success.\n\n## Interpret evidence accurately\n\n- Coordinates are display-oriented source pixels; times are source-relative\n  milliseconds. Use returned decoded timestamps, dimensions and coverage.\n- OCR is English, may miss stylized text, and can be empty on unreadable input.\n  `fast` video OCR leaves uninspected intervals. `frame_scan` is bounded and\n  cannot inspect an arbitrarily long clip in one request.\n- Speech timestamps are estimates; speaker labels/forced alignment are absent.\n  A transcript does not establish music, emotion, delivery or sound effects.\n- Color sampling measures decoded sRGB pixels, not guaranteed design hex values.\n  Layout measurement does not detect objects or recover original layer files.\n- Text-style matching returns supported UGC settings and visual residuals. Font\n  identity is unverified; inspect the preview before calling a fit accurate.\n  It has a restricted ASCII/font/style surface; the native TikTok renderer is a\n  separate bounded rendering capability, not proof that matching is exact.\n- SAM/object segmentation, automatic overlay detection, element/mask tracking,\n  motion measurement, extraction, media comparison/alignment and semantic search\n  are not available through this tool set. Do not invent those calls or install\n  SAM. Existing OCR text tracks remain available.\n\n## Review and share media\n\nOpen returned image/contact-sheet previews and review the relevant sequence.\nWhen the agent runtime can consume audio/video, use it. Otherwise use the\navailable transcript, audio preview and level measurements and explicitly state\nwhat was not listened to or inspected. Do not claim to have watched/listened\nbecause an analysis request succeeded.\n\nShare only verified browser-accessible HTTPS artifacts. Fetch without auth and\ncheck status, content type and decoding; for video also check byte-range support.\nUse the returned owned-media URLs. Local paths, localhost/private addresses and\nexpiring upstream CDN links are not deliverable previews. If an artifact needs\nuploading, use the supported owned storage path; do not claim a file is hosted\nbecause a media record was created for an arbitrary URL.\n\nFor building a reusable content format, use the `content-automation` skill.\n",
+    "media/SKILL.md": "---\nname: media\ndescription: Acquire TikTok and Instagram posts and inspect images, video and audio with UGC Inc tools. Use for reference analysis, OCR, frames, scenes, transcription, colors, layout, text-style fitting, or media-library management.\nallowed-tools: Bash, Read\n---\n\nUse the installed UGC Inc CLI:\n\n```bash\nnpx ugcinc --list\nnpx ugcinc <tool_name> '<json_params>'\n```\n\nCredentials come from `UGC_API_KEY` or existing UGC configuration. Use the user's\norganization and a key with `content:analyze` for acquisition/analysis. If using\nan admin key, pass the authorized `orgId` in the JSON parameters. Do not print\ncredentials, copy an administrator key to another user's machine, or change\norganizations to bypass a denial. Confirm access with one small tool call.\nIf credentials already live in an app env file, set `UGC_ENV_FILE` to that file's\npath so the CLI reads the existing key without duplicating its contents. Set\n`UGC_ORG_ID` in that file or the process environment to scope calls to the user's\norganization; an explicit JSON `orgId` takes priority.\n\nRead [references/tools.md](references/tools.md) for request shapes, result fields\nand limits. The CLI lists names/descriptions; the reference explains parameters.\n\n## Choose the input and tools\n\n- A profile URL: `list_profile_posts` discovers a bounded page; follow its cursor\n  only as needed. Listing does not download media or guarantee complete history.\n- A post URL: `download_social_post` ingests its ordered assets into owned media.\n  Use returned asset URLs for analysis; the TikTok/Instagram HTML URL is not a\n  video file. Check complete/partial/failed status and failed assets.\n- A direct media URL: use the corresponding inspection tool directly.\n- Video: `detect_scenes`, `extract_frames`, `read_video_text`; audio tools accept\n  video too. Inspect multiple moments, including changes near the beginning/end.\n- Image: `read_image_text`, `sample_colors`, `measure_layout` using supplied\n  boxes/masks, and `match_text_style` for a specified text crop.\n- Audio: `transcribe_audio` and `measure_audio_levels`.\n\nThe SDK/CLI waits for processing automatically. Check both the outer response's\n`ok` and the returned job's `status`. Analysis is usable when\n`data.status === \"completed\"`; its content is `data.result`. If still pending or\nprocessing, keep its job ID and use `get_media_analysis` rather than resubmitting.\nUse bounded retries for retryable failures; report persistent errors/partial\ncoverage. A zero process exit code alone does not establish API success.\n\n## Interpret evidence accurately\n\n- Coordinates are display-oriented source pixels; times are source-relative\n  milliseconds. Use returned decoded timestamps, dimensions and coverage.\n- OCR is English, may miss stylized text, and can be empty on unreadable input.\n  `fast` video OCR leaves uninspected intervals. `frame_scan` is bounded and\n  cannot inspect an arbitrarily long clip in one request.\n- Speech timestamps are estimates; speaker labels/forced alignment are absent.\n  A transcript does not establish music, emotion, delivery or sound effects.\n- Color sampling measures decoded sRGB pixels, not guaranteed design hex values.\n  Layout measurement does not detect objects or recover original layer files.\n- Text-style matching returns supported UGC settings and visual residuals. Font\n  identity is unverified; inspect the preview before calling a fit accurate.\n  It has a restricted ASCII/font/style surface; the native TikTok renderer is a\n  separate bounded rendering capability, not proof that matching is exact.\n- SAM/object segmentation, automatic overlay detection, element/mask tracking,\n  motion measurement, extraction, media comparison/alignment and semantic search\n  are not available through this tool set. Do not invent those calls or install\n  SAM. Existing OCR text tracks remain available.\n\n## Review and share media\n\nOpen returned image/contact-sheet previews and review the relevant sequence.\nWhen the agent runtime can consume audio/video, use it. Otherwise use the\navailable transcript, audio preview and level measurements and explicitly state\nwhat was not listened to or inspected. Do not claim to have watched/listened\nbecause an analysis request succeeded.\n\nShare only verified browser-accessible HTTPS artifacts. Fetch without auth and\ncheck status, content type and decoding; for video also check byte-range support.\nUse the returned owned-media URLs. Local paths, localhost/private addresses and\nexpiring upstream CDN links are not deliverable previews. If an artifact needs\nuploading, use the supported owned storage path; do not claim a file is hosted\nbecause a media record was created for an arbitrary URL.\n\nFor building a reusable content format, use the `content-automation` skill.\n\nFor native iMessage render jobs use the `imessage` skill and its separate\nsubmit/status/cancel tools. They require `content:render`, not `content:analyze`,\nand are not media-analysis jobs.\n",
     "media/references/tools.md": "# UGC media tool requests and results\n\nRun `npx ugcinc TOOL 'JSON'`. Shell quoting varies on Windows; if the shell\nchanges the JSON, use a small Node script with `UGCClient` and its `media`\nmethods instead of repeatedly sending malformed requests. For example:\n\n```js\nconst { UGCClient } = require('ugcinc');\nconst client = new UGCClient({\n  apiKey: process.env.UGC_API_KEY,\n  orgId: process.env.UGC_ORG_ID,\n});\n// Use admin:true only with an authorized administrator credential.\n```\n\nRequest URLs must be HTTPS. Analysis source URLs must not contain credentials\nor fragments. Image operations support still PNG/JPEG/WebP, at most4096pixels\nper side; the shared download limit is100MiB. Geometry must fit the actual\ndisplay-oriented source. Respect more restrictive operation limits below.\n\n## Acquisition\n\n| CLI tool / SDK method | Parameters | Result |\n| --- | --- | --- |\n| `list_profile_posts` / `media.listProfilePosts` | `{url, limit?, cursor?}`; TikTok/Instagram profile; limit1–50 | `data.posts`, profile metadata, continuation cursor. Follow the actual returned cursor, not a fabricated page number. |\n| `download_social_post` / `media.downloadSocialPost` | `{url}`; canonical TikTok/Instagram post URL | `data.status`, `assets[]` in order, `failedAssets[]`, `manifestUrl`, post/sound metadata. Each asset has `url`, `mediaId`, dimensions, type, duration, audio presence and hash. Repeat the same URL to resume retryable partial imports. |\n\nEmbedded video audio remains attached. Photo assets have no embedded soundtrack;\nsound attribution does not mean audio bytes were downloaded. Preserve sound\nID/link separately; never replace a post excerpt with the full sound-page track\nand call them identical. Partial imports are not a complete carousel.\n\n## Analysis\n\nThese return `{ok, data:{jobId,status,operation,result?,error?}}`. Use the completed\n`data.result` fields listed below. Failure can occur after successful submission.\n\n| CLI tool / SDK method | Parameters | Result content |\n| --- | --- | --- |\n| `extract_frames` / `media.extractFrames` | `{url,timestampsMs:[0,1500,3000],selection:\"nearest\",contactSheet:true}` OR `{url,range:{startMs,endMs,intervalMs}}`; choose exactly one selector, at most48samples | `frames[]` with requested/decoded time, source PTS, dimensions and URL; optional `contactSheet` with individual frame links; source metadata. |\n| `detect_scenes` / `media.detectScenes` | `{url}` | `scenes[]` with start/end milliseconds, frame indexes, source PTS; no split MP4 exports. |\n| `read_image_text` / `media.readImageText` | `{url}` | `regions[]` with text/rawText, polygons/boxes/confidence; inferred `lines[]`/reading order; `previewUrl`. |\n| `read_video_text` / `media.readVideoText` | `{url,mode:\"fast\",intervalMs:1000,range?:{startMs,endMs}}` OR `{url,mode:\"frame_scan\",range?:{startMs,endMs}}` | `frames[]`, text `tracks[]` with observations/positions; explicit `coverage.inspected` and `uninspected`. Maximum240inspected frames and120seconds per request. `intervalMs` only applies to fast mode. |\n| `transcribe_audio` / `media.transcribeAudio` | `{url,range?:{startMs,endMs},language?:\"auto\",timing?:\"word\",channel?:0}` | `status`, `text`, timed `segments[]` and estimated words, warnings, `audioPreviewUrl`. Range at most120seconds; timing `word` or `segment`; optional channel0/1. Empty/no-audio/no-speech states are distinct. |\n| `measure_audio_levels` / `media.measureAudioLevels` | `{url,range?:{startMs,endMs},windowMs?:100,silenceThresholdDbfs?:-50}` | Native-channel RMS/sample peaks, loudness timeline/LUFS, silence, possible clipping, `previewUrl`. Windows20–5000ms, threshold−100to−10dBFS, range at most120seconds. |\n| `sample_colors` / `media.sampleColors` | `{url,maxColors?:8,point?:{x,y},box?:{x,y,width,height},mask?}`; choose at most one selection | Observed RGBA point or palette/proportions, omitted mass, declared color policy, `previewUrl`. Palette1–32colors. |\n| `measure_layout` / `media.measureLayout` | `{url,elements:[{id,box:{x,y,width,height}}]}`; each element may instead have `mask` | Margins, centers, spacing/alignment deltas, intersections/IoU and `previewUrl`.1–32unique IDs. Boxes are supplied, not automatically detected. |\n| `match_text_style` / `media.matchTextStyle` | `{url,box:{x,y,width,height},text?}`; integer crop16–1536wide,16–512high; optional supplied text | `status`, candidates with real image-editor `element`/`previewConfig`, `maskIoU`, `foregroundMae`, `quality`, previews/comparison and warnings. Up to160printable ASCII characters/four lines; supported fonts Arial/TikTok/Apple. Missing/unsupported styles may be unavailable or approximations. |\n| `get_media_analysis` / `media.getMediaAnalysis` | `{jobId}` | Current status/result in the current organization; use when automatic waiting returned pending/processing. |\n\nBoxes are half-open source-pixel rectangles. For masks used by colors/layout:\n`{width,height,counts}` uses row-major binary RLE, alternating background then\nforeground. Counts must sum to width×height. This is not COCO's column-major\nconvention. Supply only masks you actually have; automatic segmentation is off.\n\n## Existing media library\n\n- `list_media({ids?,tag?})`, `list_social_audio({ids?,tag?})`.\n- `create_media_from_urls({urls,names?,tag?,sourceIds?,useName?})` registers URLs;\n  it does not turn an inaccessible local file into a public upload.\n- `import_text({texts:[{content,name?,tag?}]})`.\n- `create_social_audio({url,tag?})` imports social audio separately; do not use it\n  as proof of the exact soundtrack/mix/offset in a downloaded reference video.\n- `delete_media({ids})` removes media/storage; only use when deletion is requested.\n",
-    "content-automation/SKILL.md": "---\nname: content-automation\ndescription: Turn reference social posts or a rough content idea into a reusable UGC Inc workflow, with editable inputs and reviewed visual/audio output. Use for developing and validating content formats rather than scheduling existing finished posts.\nallowed-tools: Bash, Read\n---\n\nBuild the format the user wants and collaborate at the level they requested.\nWhen they want to discuss, compare or review a specific artifact, do that before\nmaking additional format decisions. Keep questions concise and ask only when a\nmissing answer prevents useful work. Do not impose a new per-video reference input\nwhen the user wants a fixed reusable visual format.\n\nUse the `media` skill for acquisition/inspection and the `automations` skill for\ncurrent workflow tool calls. Read [references/build-review.md](references/build-review.md)\nwhen constructing or reviewing a workflow. Use only shipped tools/nodes discovered\nthrough `npx ugcinc --list`, `list_node_types` and `get_node_type`.\n\n## Understand and specify the format\n\nAcquire a bounded set of real references and inspect full frames and changes over\ntime, including audio using available modalities. A contact sheet or transcript\nalone cannot establish all animation/pacing/music details. State uninspected\nparts instead of claiming playback. Distinguish reusable formats from variants;\nseveral posts may use the same structure with different assets, copy or timing.\n\nWrite a compact spec: what the viewer sees first, the sequence/reveal, required\ninputs, reusable assets/components, changing copy, audio source/timing and final\naction/CTA if required by this format. Separate measured facts from inference\nand user choices. Share a verified HTTPS reference/preview when the user needs\nto identify the parts they want changed.\n\nClassify assets by replacement behavior. A recognizable Mii, Wojak or other exact\nmeme image may need a static asset; an ordinary or newly generated face need not\nbe static just because it looks meme-like. Preserve a headshot's identity across\nvariants when requested, while making intended differences visibly meaningful.\n\n## Build reusable production behavior\n\nSeparate layout, data/assets and motion. Expose the inputs a normal run needs:\nasset pools/overrides, text pools, contact/destination, duration/timing and seed\nwhere appropriate. Keep canonical outputs independent of an operator's laptop.\nImplement procedural animations as reusable components rendered on demand;\ndo not substitute one pre-rendered clip when each run should vary. Randomness\nmust respect the intended visual roles and remain replayable from saved inputs.\n\nReuse existing nodes/compositions and actual public schemas. Analysis tools are\navailable as CLI/SDK operations; do not assume every one is a workflow node.\nValidate the graph before executing. Prefer a reviewable output over publishing\nor enabling recurring runs unless the user authorized those actions.\n\n## Make the content work\n\n- Keep the hierarchy clear: readable hook, focal content, then the intended CTA.\n  Give characters/subjects enough visual weight; align visible content within\n  its section instead of trusting transparent image bounds alone.\n- Measure margins, spacing, text wrapping and overlap. Check at phone viewing\n  size, not only on a large canvas. Keep important text away from platform UI;\n  inspect the relevant target presentation rather than assuming universal margins.\n- Use sampled reference colors and real render previews. Judge font, stroke,\n  kerning, line height and emoji spacing together. Treat text-style fitting as a\n  measured candidate, not proof of an exact font or pixel-perfect output.\n- Match the reference post's actual audio excerpt, mix, start and duration when\n  requested. Preserve attribution separately. Empty transcription can mean music\n  or unrecognized speech, not silence. Keep visual reveals and audio timing coherent.\n- Keep required CTA/contact copy present and legible across every requested\n  variant. Use the user's actual destination/formatting, not a number copied from\n  an old example. Vary copy intentionally without altering the required action.\n- Test with real content and multiple asset/copy lengths. A composition that\n  works with one face or one short headline is not a validated reusable format.\n  Inspect early, changing and final states; a still cannot certify a full video.\n\n## Deliver and describe the boundary\n\nProvide the workflow, its normal inputs, replayable example parameters, verified\nHTTPS previews, and any observed visual/audio limits. For videos verify decoding,\nduration/dimensions/audio and byte-range playback; images need correct content\ntype and decoding. Do not use local/localhost/private URLs as deliverables.\n\nSAM and automatic segmentation/overlay tracking are deferred. Use supplied\nassets, user-supplied boxes/masks or honest visual analysis; do not claim recovered\nsource layers or automatic clean cutouts. If the runtime cannot inspect a media\nmodality, record that limit and do not certify the uninspected property.\n",
-    "content-automation/references/build-review.md": "# Construct and review a reusable workflow\n\n## Discover the real interface\n\n`npx ugcinc list_node_types '{}'` lists current node metadata.\nUse `get_node_type '{\"nodeType\":\"...\"}'` for the nodes you choose and read the\nbundled `automations` skill for current tool parameters. These tools still need\na configured CLI key even when their own operation is local.\n\nConnections live on the target node, not a separate edges array:\n\n```json\n{\n  \"nodes\": [\n    {\n      \"id\": \"target\",\n      \"type\": \"node-type-from-discovery\",\n      \"config\": {},\n      \"inputs\": {\n        \"actual-input-port\": {\n          \"sourceNodeId\": \"source\",\n          \"sourceOutputId\": \"actual-output-port\"\n        }\n      }\n    }\n  ]\n}\n```\n\nUse actual IDs/configuration returned by discovery, not these placeholders.\nConfigure dynamic interfaces before wiring them. Re-check ports after config\nchanges. Current validation requires a terminal outcome; inspect pass-through,\nsave-to-media and posting nodes to choose the intended behavior. Publishing is\nnot required just to make a reviewable workflow output.\n\nFor reusable sub-workflows, configure their input/output contracts explicitly\nand inspect the Compose Workflow node's actual schema. For custom Remotion,\ninspect `remotion-composition`; use its supported composition/props/import\ncontract. Do not invent an upload/register API or rely on arbitrary packages.\n\nValidate using `validate_workflow` with the shape described by the installed\nautomation skill/tool. Execute only the intended single test scope, inspect its\nstatus/output, and retain resolved inputs and seed. Saving a template or receiving\na run ID alone does not prove the output renders correctly.\n\n## Review a representative run\n\nCheck the viewer's actual sequence: hook visibility, subject size, changing state,\ntext wrapping/CTA, transitions and finish. Compare the full frame before zooming\ninto details. Inspect multiple points around animation/text changes. Re-test a\nlonger caption and a different asset where those vary in normal runs.\n\nDistinguish observed pixels/timestamps from estimates. Examples: sRGB sampling\ndoes not recover design colors from compression, transcript word timestamps are\nestimated, sampled OCR leaves gaps, and bounding boxes are not exact ink bounds.\nManually supplied boxes are allowed; describe how they were determined.\n\nPreserve both soundtrack bytes and source attribution. Check whether music is\nembedded or only attributed, whether the output repeats/truncates it, and whether\nvisual changes coincide with the intended moments. Do not invent beat detection,\naudio separation, universal media comparison or other unavailable tools.\n\nWhen revising content, name the concrete issue and inspect the changed output.\nKeep reusable parameters instead of baking a correction into one reference\nimage. Report remaining defects plainly; avoid calling a draft production-ready\nbased only on successful API execution.\n"
+    "content-automation/SKILL.md": "---\nname: content-automation\ndescription: Turn reference social posts or a rough content idea into a reusable UGC Inc workflow, with editable inputs and reviewed visual/audio output. Use for developing and validating content formats rather than scheduling existing finished posts.\nallowed-tools: Bash, Read\n---\n\nBuild the format the user wants and collaborate at the level they requested.\nWhen they want to discuss, compare or review a specific artifact, do that before\nmaking additional format decisions. Keep questions concise and ask only when a\nmissing answer prevents useful work. Do not impose a new per-video reference input\nwhen the user wants a fixed reusable visual format.\n\nUse the `media` skill for acquisition/inspection and the `automations` skill for\ncurrent workflow tool calls. Read [references/build-review.md](references/build-review.md)\nwhen constructing or reviewing a workflow. Use only shipped tools/nodes discovered\nthrough `npx ugcinc --list`, `list_node_types` and `get_node_type`.\n\n## Understand and specify the format\n\nAcquire a bounded set of real references and inspect full frames and changes over\ntime, including audio using available modalities. A contact sheet or transcript\nalone cannot establish all animation/pacing/music details. State uninspected\nparts instead of claiming playback. Distinguish reusable formats from variants;\nseveral posts may use the same structure with different assets, copy or timing.\n\nWrite a compact spec: what the viewer sees first, the sequence/reveal, required\ninputs, reusable assets/components, changing copy, audio source/timing and final\naction/CTA if required by this format. Separate measured facts from inference\nand user choices. Share a verified HTTPS reference/preview when the user needs\nto identify the parts they want changed.\n\nClassify assets by replacement behavior. A recognizable Mii, Wojak or other exact\nmeme image may need a static asset; an ordinary or newly generated face need not\nbe static just because it looks meme-like. Preserve a headshot's identity across\nvariants when requested, while making intended differences visibly meaningful.\n\n## Build reusable production behavior\n\nSeparate layout, data/assets and motion. Expose the inputs a normal run needs:\nasset pools/overrides, text pools, contact/destination, duration/timing and seed\nwhere appropriate. Keep canonical outputs independent of an operator's laptop.\nImplement procedural animations as reusable components rendered on demand;\ndo not substitute one pre-rendered clip when each run should vary. Randomness\nmust respect the intended visual roles and remain replayable from saved inputs.\n\nReuse existing nodes/compositions and actual public schemas. Analysis tools are\navailable as CLI/SDK operations; do not assume every one is a workflow node.\nValidate the graph before executing. Prefer a reviewable output over publishing\nor enabling recurring runs unless the user authorized those actions.\n\n## Make the content work\n\n- Keep the hierarchy clear: readable hook, focal content, then the intended CTA.\n  Give characters/subjects enough visual weight; align visible content within\n  its section instead of trusting transparent image bounds alone.\n- Measure margins, spacing, text wrapping and overlap. Check at phone viewing\n  size, not only on a large canvas. Keep important text away from platform UI;\n  inspect the relevant target presentation rather than assuming universal margins.\n- Use sampled reference colors and real render previews. Judge font, stroke,\n  kerning, line height and emoji spacing together. Treat text-style fitting as a\n  measured candidate, not proof of an exact font or pixel-perfect output.\n- Match the reference post's actual audio excerpt, mix, start and duration when\n  requested. Preserve attribution separately. Empty transcription can mean music\n  or unrecognized speech, not silence. Keep visual reveals and audio timing coherent.\n- Keep required CTA/contact copy present and legible across every requested\n  variant. Use the user's actual destination/formatting, not a number copied from\n  an old example. Vary copy intentionally without altering the required action.\n- Test with real content and multiple asset/copy lengths. A composition that\n  works with one face or one short headline is not a validated reusable format.\n  Inspect early, changing and final states; a still cannot certify a full video.\n\n## Deliver and describe the boundary\n\nProvide the workflow, its normal inputs, replayable example parameters, verified\nHTTPS previews, and any observed visual/audio limits. For videos verify decoding,\nduration/dimensions/audio and byte-range playback; images need correct content\ntype and decoding. Do not use local/localhost/private URLs as deliverables.\n\nSAM and automatic segmentation/overlay tracking are deferred. Use supplied\nassets, user-supplied boxes/masks or honest visual analysis; do not claim recovered\nsource layers or automatic clean cutouts. If the runtime cannot inspect a media\nmodality, record that limit and do not certify the uninspected property.\n\nFor text-message formats, use the `imessage` skill and native Create DM for both\nPNG and video. Generate dialogue as structured authoring data, compile pacing,\nand review native output before combining with reaction footage, audio or CTA.\n",
+    "content-automation/references/build-review.md": "# Construct and review a reusable workflow\n\n## Discover the real interface\n\n`npx ugcinc list_node_types '{}'` lists current node metadata.\nUse `get_node_type '{\"nodeType\":\"...\"}'` for the nodes you choose and read the\nbundled `automations` skill for current tool parameters. These tools still need\na configured CLI key even when their own operation is local.\n\nConnections live on the target node, not a separate edges array:\n\n```json\n{\n  \"nodes\": [\n    {\n      \"id\": \"target\",\n      \"type\": \"node-type-from-discovery\",\n      \"config\": {},\n      \"inputs\": {\n        \"actual-input-port\": {\n          \"sourceNodeId\": \"source\",\n          \"sourceOutputId\": \"actual-output-port\"\n        }\n      }\n    }\n  ]\n}\n```\n\nUse actual IDs/configuration returned by discovery, not these placeholders.\nConfigure dynamic interfaces before wiring them. Re-check ports after config\nchanges. Current validation requires a terminal outcome; inspect pass-through,\nsave-to-media and posting nodes to choose the intended behavior. Publishing is\nnot required just to make a reviewable workflow output.\n\nFor reusable sub-workflows, configure their input/output contracts explicitly\nand inspect the Compose Workflow node's actual schema. For custom Remotion,\ninspect `remotion-composition`; use its supported composition/props/import\ncontract. Do not invent an upload/register API or rely on arbitrary packages.\n\nValidate using `validate_workflow` with the shape described by the installed\nautomation skill/tool. Execute only the intended single test scope, inspect its\nstatus/output, and retain resolved inputs and seed. Saving a template or receiving\na run ID alone does not prove the output renders correctly.\n\n## Review a representative run\n\nCheck the viewer's actual sequence: hook visibility, subject size, changing state,\ntext wrapping/CTA, transitions and finish. Compare the full frame before zooming\ninto details. Inspect multiple points around animation/text changes. Re-test a\nlonger caption and a different asset where those vary in normal runs.\n\nDistinguish observed pixels/timestamps from estimates. Examples: sRGB sampling\ndoes not recover design colors from compression, transcript word timestamps are\nestimated, sampled OCR leaves gaps, and bounding boxes are not exact ink bounds.\nManually supplied boxes are allowed; describe how they were determined.\n\nPreserve both soundtrack bytes and source attribution. Check whether music is\nembedded or only attributed, whether the output repeats/truncates it, and whether\nvisual changes coincide with the intended moments. Do not invent beat detection,\naudio separation, universal media comparison or other unavailable tools.\n\nWhen revising content, name the concrete issue and inspect the changed output.\nKeep reusable parameters instead of baking a correction into one reference\nimage. Report remaining defects plainly; avoid calling a draft production-ready\nbased only on successful API execution.\n",
+    "imessage/SKILL.md": "---\nname: imessage\ndescription: Create native iMessage conversation PNGs and videos, or wire messaging scenes into UGC Inc workflows. Use for synthetic text-message content, typing, replies, reactions, receipts, avatars and image attachments.\nallowed-tools: Bash, Read\n---\n\nUse the native service for every iMessage image and video. The old Remotion\ncomposition and iMessage player are removed. Instagram DM remains a separate\nscreenshot implementation. These are synthetic renders, never real messages.\n\nRead the current [authoring guide](https://docs.ugc.inc/guides/imessage-conversations.md)\nand [field contract](https://docs.ugc.inc/data-structures/imessage-conversation.md)\nfor optional appearance, group, reply/reaction and timing fields.\n\n## Author and inspect pacing\n\nGive the conversation one concrete situation, a readable opening, useful replies\nand a clear payoff. Preserve the user's requested tone and product capabilities;\nrendering success does not establish that the dialogue is good. Use stable IDs,\n`sender: \"user\"` for the phone owner and `\"recipient\"` for the other person\n(or declared group participant IDs). Give each bubble one thought. Separate\ncontent generation from reusable appearance/pacing settings.\n\n`compile_imessage_conversation` accepts the authoring JSON and returns duration,\ntyping/arrival schedule and events without submitting a render. Inspect the total\nlength and important pauses; adjust authoring timing before rendering. A long\nconversation at default typing speed may exceed the 120-second limit. Do not\nsubmit the compiled plan to the render endpoint.\n\nFor a populated still, mark all messages `initial: true` and use\n`output: {\"kind\":\"png\"}`. For an animated scene, put only existing history first\nwith `initial:true`; later messages animate. `output:{\"kind\":\"png\",\"atMs\":500}`\nrenders that native moment losslessly. Video defaults to 60fps. Emoji are complete\nUnicode graphemes and local typing uses the native keyboard.\n\n## Render and handle jobs\n\nUse existing UGC credentials/org; restricted keys need `content:render`.\n`render_imessage_conversation` submits authoring JSON and immediately returns a\njob. Check outer `ok`, save `data.jobId`, and poll `get_imessage_conversation`\nwith `{jobId}` until completed/failed/cancelled. Only completed output has a URL.\nUse a bounded polling deadline; on timeout retain the job instead of duplicating\nit. `cancel_imessage_conversation` requests cancellation; keep polling to terminal.\nThese jobs do not use `get_media_analysis`.\n\nAn idempotency key reuses identical input within the org; changing input needs a\nnew key. Status records are retained seven days. Report safe returned errors and\nretryability. Use the SDK methods when shell JSON quoting is awkward.\n\nImage bodies accept exactly one `text`, `imagePngBase64`, or public HTTPS\n`imageUrl`. Contact/group/participant avatars accept a PNG payload or `avatarUrl`.\nThe service resolves URL images; do not make agents build base64 blobs. Avatar\nconversion fits96px, attachment conversion fits2048px; media/request budgets\nstill apply. A document-name string is text, not an actual file attachment;\nrender a deliberate PNG asset if the format calls for an image of a document.\n\n## Workflow integration\n\nDiscover `create-dm` with `get_node_type`. Configure:\n\n```json\n{\n  \"platform\": \"imessage\",\n  \"platformInputType\": \"static\",\n  \"imessageRenderMode\": \"conversation\",\n  \"imessageOutputType\": \"video\",\n  \"imessageConversationInputType\": \"variable\"\n}\n```\n\nConnect the full authoring object to `conversation`. The output port is `output`;\n`imessageOutputType:\"image\"` fixes an image port, `\"video\"` fixes a video port.\nA variable input declaring the opposite output kind rejects. Static settings use\n`imessageConversation`. For a direct-chat avatar, set `profilePicInputType` to\n`variable` and connect `profile-pic`. To replace an image message, set\n`imageAttachmentInputType` to `variable`, set `imessageAttachmentMessageId` to the\ntarget ID and connect `image-attachment`. Input images retain normal `{url}` shape.\n\nSaved screenshot nodes retain their existing connections and resolve to native\npopulated PNGs. Custom bubble colors, message-based cropping and free-text legacy\nread receipts need explicit correction; do not silently discard them. Use native\nmessage receipt/readAt fields or downstream composition as appropriate.\n\nValidate the graph before running. Feed video into Video Composer alongside the\nreaction clip, soundtrack and required CTA; feed PNG into an image workflow.\nEnd with Save to Media or a Pass-Through output for review. Do not add posting\nor recurrence without authorization. Use the automations skill for graph details.\n\n## Review boundaries\n\nInspect PNGs and opening/changing/final video states at phone viewing size.\nUse the compiled schedule to choose moments around typing, arrival and payoff;\ncheck scrolling, emoji, attachments and end hold. Native video is1126×2436 with\none codec-padding column; PNG is1125×2436. Composite deliberately into the target\ncanvas. Audio is added separately; inspect the final mixed video's actual audio.\n\nThe profile is iPhone XS/iOS18.6.2, not the newest iOS UI. Full-screen/bubble-send\neffects, arbitrary fonts/coordinates and custom native dimensions/fps are absent.\nSeeded timing is repeatable, but independent reaction pixels can differ. Do not\npromise universal pixel parity. Share only decoded, verified public HTTPS previews,\nincluding video Range support. Describe uninspected playback/audio honestly.\n"
 };

package/dist/imessage-conversation.d.ts

@@ -35,29 +35,36 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
     contact: z.ZodOptional<z.ZodObject<{
         name: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
         avatarPngBase64: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        avatarUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     }, "strict", z.ZodTypeAny, {
         name: string;
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     }, {
         name: string;
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     }>>;
     group: z.ZodOptional<z.ZodObject<{
         name: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
         avatarPngBase64: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        avatarUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         localParticipantId: z.ZodDefault<z.ZodString>;
         participants: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             name: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
             avatarPngBase64: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+            avatarUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         }, "strict", z.ZodTypeAny, {
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }, {
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }>, "many">;
     }, "strict", z.ZodTypeAny, {
         name: string;
@@ -66,16 +73,20 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }[];
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     }, {
         name: string;
         participants: {
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }[];
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
         localParticipantId?: string | undefined;
     }>>;
     statusBar: z.ZodDefault<z.ZodObject<{
@@ -163,6 +174,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         sender: z.ZodString;
         text: z.ZodOptional<z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>>;
         imagePngBase64: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        imageUrl: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
         initial: z.ZodDefault<z.ZodBoolean>;
         showTyping: z.ZodOptional<z.ZodBoolean>;
         receipt: z.ZodDefault<z.ZodEnum<["none", "delivered", "read"]>>;
@@ -251,6 +263,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         showTyping?: boolean | undefined;
         readAt?: string | undefined;
         timing?: {
@@ -271,6 +284,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         initial?: boolean | undefined;
         showTyping?: boolean | undefined;
         receipt?: "none" | "delivered" | "read" | undefined;
@@ -313,6 +327,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         showTyping?: boolean | undefined;
         readAt?: string | undefined;
         timing?: {
@@ -333,6 +348,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         initial?: boolean | undefined;
         showTyping?: boolean | undefined;
         receipt?: "none" | "delivered" | "read" | undefined;
@@ -424,6 +440,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         showTyping?: boolean | undefined;
         readAt?: string | undefined;
         timing?: {
@@ -450,6 +467,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
     contact?: {
         name: string;
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     } | undefined;
     group?: {
         name: string;
@@ -458,8 +476,10 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }[];
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     } | undefined;
 }, {
     messages: {
@@ -467,6 +487,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         initial?: boolean | undefined;
         showTyping?: boolean | undefined;
         receipt?: "none" | "delivered" | "read" | undefined;
@@ -510,6 +531,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
     contact?: {
         name: string;
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     } | undefined;
     group?: {
         name: string;
@@ -517,8 +539,10 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }[];
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
         localParticipantId?: string | undefined;
     } | undefined;
     statusBar?: {
@@ -600,6 +624,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         showTyping?: boolean | undefined;
         readAt?: string | undefined;
         timing?: {
@@ -626,6 +651,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
     contact?: {
         name: string;
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     } | undefined;
     group?: {
         name: string;
@@ -634,8 +660,10 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }[];
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     } | undefined;
 }, {
     messages: {
@@ -643,6 +671,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
         id?: string | undefined;
         text?: string | undefined;
         imagePngBase64?: string | undefined;
+        imageUrl?: string | undefined;
         initial?: boolean | undefined;
         showTyping?: boolean | undefined;
         receipt?: "none" | "delivered" | "read" | undefined;
@@ -686,6 +715,7 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
     contact?: {
         name: string;
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
     } | undefined;
     group?: {
         name: string;
@@ -693,8 +723,10 @@ export declare const iMessageConversationSchema: z.ZodEffects<z.ZodObject<{
             id: string;
             name: string;
             avatarPngBase64?: string | undefined;
+            avatarUrl?: string | undefined;
         }[];
         avatarPngBase64?: string | undefined;
+        avatarUrl?: string | undefined;
         localParticipantId?: string | undefined;
     } | undefined;
     statusBar?: {
@@ -802,6 +834,7 @@ export interface IMessageConversationPlan {
         sender: string;
         text: string;
         imagePngBase64?: string;
+        imageUrl?: string;
         initial: boolean;
         receipt: 'none' | 'delivered' | 'read';
         readAt?: string;

package/dist/imessage-conversation.js

@@ -8,6 +8,10 @@ const avatarPng = zod_1.z.string().max(65536).regex(/^iVBORw0KGgo[A-Za-z0-9+/]*=
     .refine(value => value.length % 4 === 0, 'Expected a base64 PNG, without a data URL prefix.');
 const attachmentPng = zod_1.z.string().max(8 * 1024 * 1024).regex(/^iVBORw0KGgo[A-Za-z0-9+/]*={0,2}$/)
     .refine(value => value.length % 4 === 0, 'Expected a base64 PNG, without a data URL prefix.');
+const mediaUrl = zod_1.z.string().url().max(4096).refine(raw => {
+    const url = new URL(raw);
+    return url.protocol === 'https:' && !url.username && !url.password && !url.port && !url.hash;
+}, 'Use a public HTTPS image URL without credentials, ports or fragments.');
 const timingFields = {
     charactersPerSecond: zod_1.z.number().finite().min(0.5).max(60),
     pauseBeforeMs: zod_1.z.number().int().min(0).max(30000),
@@ -51,6 +55,7 @@ const messageSchema = zod_1.z.object({
     sender: zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),
     text: displayText.pipe(zod_1.z.string().min(1).max(2000)).optional(),
     imagePngBase64: attachmentPng.optional(),
+    imageUrl: mediaUrl.optional(),
     initial: zod_1.z.boolean().default(false),
     showTyping: zod_1.z.boolean().optional(),
     receipt: zod_1.z.enum(['none', 'delivered', 'read']).default('none'),
@@ -62,8 +67,8 @@ const messageSchema = zod_1.z.object({
     timestampText: displayText.pipe(zod_1.z.string().trim().min(1).max(80)).optional(),
     reactions: zod_1.z.array(reactionSchema).max(20).default([]),
 }).strict().superRefine((value, ctx) => {
-    if ((value.text === undefined) === (value.imagePngBase64 === undefined))
-        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'Provide exactly one text or imagePngBase64 message body; image captions are not supported.' });
+    if ([value.text, value.imagePngBase64, value.imageUrl].filter(body => body !== undefined).length !== 1)
+        ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'Provide exactly one text, imagePngBase64 or imageUrl body; image captions are not supported.' });
 });
 const outputSchema = zod_1.z.discriminatedUnion('kind', [
     zod_1.z.object({ kind: zod_1.z.literal('video') }).strict(),
@@ -76,15 +81,18 @@ exports.iMessageConversationSchema = zod_1.z.object({
     contact: zod_1.z.object({
         name: displayText.pipe(zod_1.z.string().trim().min(1).max(80)),
         avatarPngBase64: avatarPng.optional(),
+        avatarUrl: mediaUrl.optional(),
     }).strict().optional(),
     group: zod_1.z.object({
         name: displayText.pipe(zod_1.z.string().trim().min(1).max(80)),
         avatarPngBase64: avatarPng.optional(),
+        avatarUrl: mediaUrl.optional(),
         localParticipantId: zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,80}$/).default('user'),
         participants: zod_1.z.array(zod_1.z.object({
             id: zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),
             name: displayText.pipe(zod_1.z.string().trim().min(1).max(80)),
             avatarPngBase64: avatarPng.optional(),
+            avatarUrl: mediaUrl.optional(),
         }).strict()).min(3).max(20),
     }).strict().optional(),
     statusBar: statusBarSchema.default({}),
@@ -109,6 +117,10 @@ exports.iMessageConversationSchema = zod_1.z.object({
         ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'Conversation request exceeds the 16 MiB limit.' });
     if (!!value.contact === !!value.group)
         ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'Provide a contact or a group, exclusively.' });
+    for (const avatar of [value.contact, value.group, ...(value.group?.participants ?? [])]) {
+        if (avatar?.avatarUrl !== undefined && avatar.avatarPngBase64 !== undefined)
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, message: 'Provide avatarUrl or avatarPngBase64, not both.' });
+    }
     const localId = value.group?.localParticipantId ?? 'user';
     const participantIds = new Set(value.group?.participants.map(person => person.id) ?? ['user', 'recipient']);
     if (value.group && (participantIds.size !== value.group.participants.length || !participantIds.has(localId)))
@@ -186,7 +198,7 @@ function compileIMessageConversation(input) {
         t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
         return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     }
-    const messages = value.messages.map((m, i) => ({ id: m.id ?? `message-${i + 1}`, sender: m.sender, text: m.text ?? '', imagePngBase64: m.imagePngBase64, initial: m.initial, receipt: m.receipt, readAt: m.readAt, replyTo: m.replyTo, sentAt: m.sentAt, timestampText: m.timestampText }));
+    const messages = value.messages.map((m, i) => ({ id: m.id ?? `message-${i + 1}`, sender: m.sender, text: m.text ?? '', imagePngBase64: m.imagePngBase64, imageUrl: m.imageUrl, initial: m.initial, receipt: m.receipt, readAt: m.readAt, replyTo: m.replyTo, sentAt: m.sentAt, timestampText: m.timestampText }));
     const events = [];
     const schedule = [];
     let cursor = 0;
@@ -238,7 +250,7 @@ function compileIMessageConversation(input) {
             cursor += 1400;
         }
         const typingStartMs = cursor;
-        if (isLocal && message.imagePngBase64 !== undefined) {
+        if (isLocal && (message.imagePngBase64 !== undefined || message.imageUrl !== undefined)) {
             events.push({ type: 'composer.attach', atMs: cursor, messageId: resolved.id });
             cursor += 1000;
         }

package/dist/imessage-workflow.d.ts

@@ -0,0 +1,35 @@
+import { type IMessageConversationInput } from './imessage-conversation';
+import type { CreateDmMessage, CreateDmNodeInputs } from './automations/nodes/create-dm';
+export interface IMessageWorkflowConfig {
+    imessageLegacyInputs?: boolean;
+    imessageOutputType?: 'image' | 'video';
+    imessageRenderMode?: 'still' | 'conversation';
+    imessageConversation?: IMessageConversationInput;
+    imessageConversationInputType?: 'static' | 'variable';
+    imessageAttachmentMessageId?: string;
+    dynamicCrop?: unknown;
+    imessageSenderBubbleColor?: string;
+    messages?: CreateDmMessage[];
+    messagesInputType?: 'static' | 'variable';
+    username?: string;
+    usernameInputType?: 'static' | 'variable';
+    time?: string;
+    timeInputType?: 'static' | 'variable';
+    lightMode?: boolean;
+    lightModeInputType?: 'static' | 'variable';
+    profilePicUrl?: string;
+    profilePicInputType?: 'static' | 'variable';
+    imageAttachmentUrl?: string;
+    imageAttachmentInputType?: 'static' | 'variable';
+    imessageUnreadBadgeInputType?: 'static' | 'variable';
+    imessageUnreadBadgeText?: string;
+    imessageReadReceiptTimeInputType?: 'static' | 'variable';
+    imessageReadReceiptText?: string;
+    imessageShowReadReceipt?: boolean;
+    imessageMessageHeaderTimeInputType?: 'static' | 'variable';
+    imessageMessageHeaderTimestampText?: string;
+}
+export declare function iMessageWorkflowOutput(config: IMessageWorkflowConfig): 'image' | 'video';
+export declare function legacyIMessageIssues(config: IMessageWorkflowConfig): string[];
+/** Resolve saved screenshot fields and current workflow inputs without moving connections. */
+export declare function prepareIMessageWorkflow(config: IMessageWorkflowConfig, inputs?: CreateDmNodeInputs): IMessageConversationInput;