@socialseal/cli 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.1.11 - 2026-06-12
+
+- Add ad hoc public video URL analysis parity for queue and extract workflows, including `--url` and `--allow-untracked` support.
+
 ## 0.1.10 - 2026-06-10
 
 - Clarify ranked search exports now include publish/observed dates and scoped tracked-search resurfacing history fields when the backend export template is deployed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialseal/cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",

package/src/index.js

@@ -144,7 +144,7 @@ const KNOWN_TOOLS = [
     transport: 'post_edge_function',
     workspaceScoped: true,
     knownLocalDevState: 'enabled',
-    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items; videoId means video_uid or platform-native video id, not a tracking item id.',
+    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items and public URL items with allowUntracked=true; videoId means video_uid or platform-native video id, not a tracking item id.',
   },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
   {
@@ -258,6 +258,23 @@ const TOOL_SCHEMA_HINTS = {
           jobId: '11111111-1111-4111-8111-111111111111',
         },
       },
+      {
+        action: 'status',
+        required: ['action=status', 'workspaceId or --workspace-id', 'items[] with videoUid or platformVideoId'],
+        optional: ['includeRawAnalysis'],
+        notes: 'Status polling is read-only and does not accept URL items; use videoUid or platformVideoId returned by the initial URL extraction response.',
+        example: {
+          action: 'status',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          items: [
+            {
+              videoUid: '11111111-1111-4111-8111-111111111111',
+            },
+          ],
+          includeAssets: false,
+          includeSourceVideo: false,
+        },
+      },
     ],
     cliExamples: [
       'socialseal tools call --function agent-tool-jobs --body \'{"action":"start","toolName":"search_videos","payload":{"query":"best africa safari itinerary","platform":"tiktok","region":"IN"}}\'',
@@ -376,6 +393,64 @@ const TOOL_SCHEMA_HINTS = {
       'socialseal tools call --function get-google-ai-search-results --body \'{"runId":6809,"includeCitations":true,"limit":10}\'',
     ],
   },
+  'tracked-video-extract': {
+    summary: 'Extract assets and queue/read analysis for tracked identifiers or ad hoc public video URLs.',
+    operations: [
+      {
+        action: 'extract',
+        required: ['workspaceId or --workspace-id', 'items[] with exactly one selector'],
+        optional: [
+          'items[].searchResultId',
+          'items[].videoId',
+          'items[].videoUid',
+          'items[].platformVideoId',
+          'items[].url',
+          'allowUntracked',
+          'ensureAnalysis',
+          'includeAssets',
+          'includeSourceVideo',
+          'frameStrategy',
+          'frameCount',
+          'signedUrlSeconds',
+        ],
+        notes: 'URL items require request-level allowUntracked:true. Supported selectors are url, searchResultId, videoId, videoUid, or platformVideoId.',
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          allowUntracked: true,
+          ensureAnalysis: true,
+          items: [
+            {
+              url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+            },
+          ],
+        },
+      },
+      {
+        action: 'queue-analysis',
+        required: ['workspaceId or --workspace-id', 'items[] with exactly one selector'],
+        optional: ['allowUntracked for URL items', 'queueOnly', 'includeRawAnalysis'],
+        notes: 'Set ensureAnalysis:true and queueOnly:true to enqueue analysis without asset URL generation.',
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          allowUntracked: true,
+          ensureAnalysis: true,
+          queueOnly: true,
+          includeAssets: false,
+          items: [
+            {
+              url: 'https://www.tiktok.com/@creator/video/7348293840000000000',
+            },
+          ],
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal video extract --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --allow-untracked --wait --out-dir ./video-assets --workspace-id <workspace-uuid>',
+      'socialseal video queue-analysis --url https://www.tiktok.com/@creator/video/7348293840000000000 --allow-untracked --wait --workspace-id <workspace-uuid>',
+      'socialseal video extract --video-uid <video-uuid> --wait --workspace-id <workspace-uuid>',
+      'socialseal tools call --function tracked-video-extract --workspace-id <workspace-uuid> --body \'{"allowUntracked":true,"items":[{"url":"https://www.instagram.com/reel/SHORTCODE/"}]}\'',
+    ],
+  },
   'group-management': {
     summary: 'Manage single-platform tracking groups and memberships.',
     operations: [
@@ -751,6 +826,7 @@ function inferExtension(urlValue, contentType, fallback = '.bin') {
 function normalizeVideoExtractBody(body) {
   const normalized = { ...body };
   const hasInlineIdentifier =
+    normalized.url !== undefined ||
     normalized.videoId !== undefined ||
     normalized.searchResultId !== undefined ||
     normalized.videoUid !== undefined ||
@@ -758,12 +834,14 @@ function normalizeVideoExtractBody(body) {
 
   if (!Array.isArray(normalized.items) && hasInlineIdentifier) {
     normalized.items = [{
+      url: normalized.url,
       videoId: normalized.videoId,
       searchResultId: normalized.searchResultId,
       videoUid: normalized.videoUid,
       platformVideoId: normalized.platformVideoId,
       platformId: normalized.platformId,
     }];
+    delete normalized.url;
     delete normalized.videoId;
     delete normalized.searchResultId;
     delete normalized.videoUid;
@@ -774,6 +852,11 @@ function normalizeVideoExtractBody(body) {
   return normalized;
 }
 
+function hasUrlVideoItems(body) {
+  const items = Array.isArray(body?.items) ? body.items : [];
+  return items.some((item) => typeof item?.url === 'string' && item.url.trim().length > 0);
+}
+
 function buildVideoExtractBody(opts, workspaceId) {
   const parsed = opts.body
     ? ensureJsonObject(parseJsonInput(opts.body, { label: 'body' }), 'body')
@@ -782,6 +865,7 @@ function buildVideoExtractBody(opts, workspaceId) {
 
   if (!Array.isArray(normalized.items) || normalized.items.length === 0) {
     const inlineItem = stripUndefinedEntries({
+      url: trimString(opts.url) || undefined,
       videoId: trimString(opts.videoId) || undefined,
       searchResultId: opts.searchResultId !== undefined
         ? coercePositiveInteger(opts.searchResultId, 'searchResultId')
@@ -791,10 +875,10 @@ function buildVideoExtractBody(opts, workspaceId) {
     });
 
     if (Object.keys(inlineItem).length === 0) {
-      throw new CliError('Provide --body or one of --video-id, --video-uid, --platform-video-id, or --search-result-id.', {
+      throw new CliError('Provide --body or one of --url, --video-id, --video-uid, --platform-video-id, or --search-result-id.', {
         code: 'MISSING_ARGUMENT',
         exitCode: EXIT_CODES.USAGE,
-        hint: '--video-id accepts a video_uid or platform video id. It does not accept tracking item ids.',
+        hint: '--url requires --allow-untracked. --video-id accepts a video_uid or platform video id; it does not accept tracking item ids.',
       });
     }
 
@@ -811,6 +895,17 @@ function buildVideoExtractBody(opts, workspaceId) {
   }
 
   const nextBody = { ...bodyWithWorkspace };
+  if (opts.allowUntracked === true) {
+    nextBody.allowUntracked = true;
+  }
+  if (hasUrlVideoItems(nextBody) && nextBody.allowUntracked !== true) {
+    throw new CliError('URL video analysis requires --allow-untracked or allowUntracked:true in --body.', {
+      code: 'ALLOW_UNTRACKED_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --allow-untracked for ad hoc public URL analysis. Existing tracked identifier flows do not need this flag.',
+    });
+  }
+
   if (opts.wait) {
     nextBody.ensureAnalysis = true;
   } else if (opts.ensureAnalysis === true) {
@@ -868,11 +963,60 @@ function buildVideoQueueBody(opts, workspaceId) {
 function hasPendingVideoExtractResults(payload) {
   const results = Array.isArray(payload?.results) ? payload.results : [];
   return results.some((result) => {
-    const status = String(result?.analysis?.status || '').trim().toLowerCase();
-    return status === 'pending' || status === 'processing';
+    const itemStatus = String(result?.status || '').trim().toLowerCase();
+    const analysisStatus = String(
+      result?.analysis?.normalizedStatus || result?.analysis?.status || '',
+    ).trim().toLowerCase();
+    const status = itemStatus || analysisStatus;
+    return ACTIVE_STATUS_VALUES.has(status);
   });
 }
 
+function buildVideoExtractStatusPollBody(originalBody, payload) {
+  const results = Array.isArray(payload?.results) ? payload.results : [];
+  const items = results
+    .map((result) => {
+      const resolved = isJsonObject(result?.resolvedVideo)
+        ? result.resolvedVideo
+        : (isJsonObject(result?.resolved) ? result.resolved : {});
+      const videoUid = trimString(resolved.videoUid || resolved.video_uid);
+      if (videoUid) return { videoUid };
+      const platformVideoId = trimString(
+        resolved.platformVideoId || resolved.platform_video_id,
+      );
+      if (platformVideoId) {
+        const item = { platformVideoId };
+        if (Number.isInteger(resolved.platformId)) {
+          item.platformId = resolved.platformId;
+        } else if (Number.isInteger(resolved.platform_id)) {
+          item.platformId = resolved.platform_id;
+        }
+        return item;
+      }
+      const request = isJsonObject(result?.request) ? result.request : null;
+      if (!request || request.url) return null;
+      return request;
+    })
+    .filter(Boolean);
+
+  if (items.length === 0) {
+    const originalHasUrl = Array.isArray(originalBody.items) &&
+      originalBody.items.some((item) => Boolean(item?.url));
+    if (originalHasUrl) return null;
+    return originalBody;
+  }
+
+  return {
+    workspaceId: originalBody.workspaceId,
+    action: 'status',
+    items,
+    includeRawAnalysis: originalBody.includeRawAnalysis === true,
+    includeAssets: false,
+    includeSourceVideo: false,
+    ensureAnalysis: false,
+  };
+}
+
 async function downloadAssetToFile({ url, outDir, stem, timeoutMs }) {
   const response = await fetchWithTimeout(url, {
     method: 'GET',
@@ -4448,13 +4592,13 @@ async function handleVideoExtract(opts) {
     method: 'POST',
   });
 
-  const requestOnce = async (remainingTimeoutMs) => {
+  const requestOnce = async (remainingTimeoutMs, requestBody = body) => {
     const res = await callApi({
       apiBase: useGateway ? resolvedApiBase : legacyUrl,
       apiKey,
       path,
       method: 'POST',
-      body,
+      body: requestBody,
       workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
@@ -4479,6 +4623,7 @@ async function handleVideoExtract(opts) {
   };
 
   let payload = await requestOnce(timeoutMs);
+  let pollBody = buildVideoExtractStatusPollBody(body, payload);
 
   if (opts.wait) {
     const pollIntervalMs = resolvePollIntervalMs(opts);
@@ -4497,7 +4642,16 @@ async function handleVideoExtract(opts) {
 
       emitInfo(opts, 'tracked-video-extract pending; polling for completion.');
       await sleep(Math.min(pollIntervalMs, remainingMs));
-      payload = await requestOnce(Math.max(1000, deadline - Date.now()));
+      if (!pollBody) {
+        throw new CliError('Cannot poll URL analysis without a resolved video identifier.', {
+          code: 'MISSING_RESOLVED_VIDEO_ID',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Retry without --wait, then poll with the returned videoUid or platformVideoId.',
+          details: truncateDetails(payload),
+        });
+      }
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()), pollBody);
+      pollBody = buildVideoExtractStatusPollBody(body, payload);
     }
   }
 
@@ -4536,13 +4690,13 @@ async function handleVideoQueueAnalysis(opts) {
     method: 'POST',
   });
 
-  const requestOnce = async (remainingTimeoutMs) => {
+  const requestOnce = async (remainingTimeoutMs, requestBody = body) => {
     const res = await callApi({
       apiBase: useGateway ? resolvedApiBase : legacyUrl,
       apiKey,
       path,
       method: 'POST',
-      body,
+      body: requestBody,
       workspaceId: effectiveWorkspaceId,
       timeoutMs: remainingTimeoutMs,
     });
@@ -4567,6 +4721,7 @@ async function handleVideoQueueAnalysis(opts) {
   };
 
   let payload = await requestOnce(timeoutMs);
+  let pollBody = buildVideoExtractStatusPollBody(body, payload);
 
   if (opts.wait) {
     const pollIntervalMs = resolvePollIntervalMs(opts);
@@ -4585,7 +4740,16 @@ async function handleVideoQueueAnalysis(opts) {
 
       emitInfo(opts, 'tracked-video queue-analysis pending; polling for completion.');
       await sleep(Math.min(pollIntervalMs, remainingMs));
-      payload = await requestOnce(Math.max(1000, deadline - Date.now()));
+      if (!pollBody) {
+        throw new CliError('Cannot poll URL analysis without a resolved video identifier.', {
+          code: 'MISSING_RESOLVED_VIDEO_ID',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Retry without --wait, then poll with the returned videoUid or platformVideoId.',
+          details: truncateDetails(payload),
+        });
+      }
+      payload = await requestOnce(Math.max(1000, deadline - Date.now()), pollBody);
+      pollBody = buildVideoExtractStatusPollBody(body, payload);
     }
   }
 
@@ -4967,12 +5131,14 @@ const video = program.command('video').description('Tracked video extraction wor
 
 video
   .command('queue-analysis')
-  .description('Queue video analysis for tracked videos or tracked search results')
+  .description('Queue video analysis for tracked videos, tracked search results, or ad hoc public URLs')
+  .option('--url <url>', 'Public TikTok, Instagram, or YouTube video URL (requires --allow-untracked)')
   .option('--video-id <id>', 'Tracked video identifier (video_uid first, then platform video id; not a tracking item id)')
   .option('--search-result-id <id>', 'Tracked search result id for a ranked result row')
   .option('--video-uid <id>', 'Canonical tracked video_uid')
   .option('--platform-video-id <id>', 'Platform-native video id')
   .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch queueing')
+  .option('--allow-untracked', 'Allow ad hoc public URL analysis for videos not already tracked')
   .option('--wait', 'Poll until queued/completing analyses settle')
   .option('--poll-interval <ms>', 'Polling interval in milliseconds when --wait is enabled')
   .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
@@ -4986,12 +5152,14 @@ video
 
 video
   .command('extract')
-  .description('Resolve tracked videos/results into structured analysis plus reference assets')
+  .description('Resolve tracked videos/results or ad hoc public URLs into structured analysis plus reference assets')
+  .option('--url <url>', 'Public TikTok, Instagram, or YouTube video URL (requires --allow-untracked)')
   .option('--video-id <id>', 'Tracked video identifier (video_uid first, then platform video id; not a tracking item id)')
   .option('--search-result-id <id>', 'Tracked search result id for a ranked result row')
   .option('--video-uid <id>', 'Canonical tracked video_uid')
   .option('--platform-video-id <id>', 'Platform-native video id')
   .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch extraction')
+  .option('--allow-untracked', 'Allow ad hoc public URL analysis for videos not already tracked')
   .option('--ensure-analysis', 'Queue analysis when it is missing')
   .option('--wait', 'Poll until queued/completing analyses settle')
   .option('--poll-interval <ms>', 'Polling interval in milliseconds when --wait is enabled')