@socialseal/cli 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.1.5 - 2026-03-19
+- Add first-class tracked-video workflows with `video queue-analysis` and `video extract`.
+- Make `--video-id` the primary ergonomic selector for tracked-video analysis and asset extraction, while keeping `--search-result-id` as a fallback selector.
+- Support batch queueing/extraction payloads plus optional asset downloads for thumbnails, source video, and extracted key frames.
+
+## 0.1.4 - 2026-03-19
+- Add explicit `group_add_item` / `group_add_items` CLI aliases for tracking-group membership workflows.
+- Add `tracking resolve` / `get_by_value` so existing tracked searches can be resolved by value using the same duplicate-detection semantics as create.
+- Return operational duplicate metadata for tracking conflicts, including `existing_item_id`, `member_of_group_ids`, platform, region, workspace, and active state.
+
 ## 0.1.3 - 2026-03-19
 - Republish the current CLI release line after the successful `0.1.2` npm publish, keeping the internal and OSS package versions aligned.
 

package/README.md

@@ -49,6 +49,12 @@ Optional config file:
   - `socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>`
   - `socialseal tools call --function search-journey-run --body @payload.json --async --no-poll --workspace-id <uuid>`
 
+- Tracked video extraction:
+  - `socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>`
+  - `socialseal video extract --video-id 734829384 --workspace-id <uuid>`
+  - `socialseal video extract --video-uid <video_uid> --wait --workspace-id <uuid>`
+  - `socialseal video extract --body @payload.json --out-dir ./video-assets`
+
 - Data exports (provisional):
   - `socialseal data export-tracking --group-id 123 --time-period 30d --out out.csv`
   - `socialseal data export-report --report-type keyword_universe --format csv --payload @payload.json --out out.csv`
@@ -58,6 +64,9 @@ Optional config file:
 - `tools list` ships a stable built-in registry of supported direct-call function targets. It is not live backend enumeration.
 - `--timeout <ms>` controls HTTP request timeouts. Agent runs default to a 5-minute WebSocket inactivity timeout unless you set `--idle-timeout <ms>` (or the matching env/config value).
 - `search-journey-run` supports CLI-managed async polling: `--async` starts backend async mode, polling is on by default, `--no-poll` returns the initial `runId`, and `--poll-interval <ms>` controls the status polling cadence.
+- `video queue-analysis` wraps the tracked-video extraction backend in queue-only mode so you can queue one or many tracked videos without downloading assets first.
+- `video extract` wraps the same backend in extraction mode and returns a normalized JSON payload with resolved tracking context, structured analysis, thumbnail/frame assets, and optional local downloads under `--out-dir`.
+- `--video-id` is the primary ergonomic selector for video workflows. The backend tries it as `video_uid` first, then as platform video id. `--search-result-id` remains available when you are starting from a specific tracked rank row.
 - `socialseal agent run` now defaults to a fresh conversation. The CLI prints a continuation token to `stderr`; pass it back with `--continue <token>` to resume the same agent conversation explicitly.
 - Effective workspace precedence is: `--workspace-id` → `SOCIALSEAL_WORKSPACE_ID` → config `workspaceId` → backend personal-workspace fallback.
 - `socialseal workspace use ...` writes a local default workspace into `~/.config/socialseal/config.json`, which the CLI reuses for `agent`, `tools`, and `data` commands.

package/package.json

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

package/src/index.js

@@ -13,6 +13,7 @@ const WORKSPACE_HEADER = 'X-Workspace-Id';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 300000;
 const DEFAULT_POLL_INTERVAL_MS = 2000;
+const DEFAULT_FRAME_COUNT = 3;
 const MAX_TIMEOUT_MS = 900000;
 const LEGACY_ENABLED = process.env.SOCIALSEAL_ENABLE_LEGACY === '1';
 const STATIC_TOOL_REGISTRY_NOTE = 'This registry is shipped with the CLI for stable discovery. It is not live backend enumeration, so environment-specific availability can drift.';
@@ -62,6 +63,16 @@ const KNOWN_TOOLS = [
     knownLocalDevState: 'disabled_by_default',
     notes: 'group_id expects a numeric tracking_group id, not a brand_group UUID.',
   },
+  {
+    name: 'tracked-video-extract',
+    category: 'video',
+    description: 'Resolve tracked videos/results into structured analysis plus reference assets.',
+    objectType: 'tracked_video_extract',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items; can queue analysis and return/download asset URLs.',
+  },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
   { name: 'google-ai-search', category: 'search', description: 'Run Google AI search queries and fetch result snapshots.' },
   { name: 'instagram-geo-api', category: 'search', description: 'Query Instagram search and geo data.' },
@@ -76,8 +87,8 @@ const KNOWN_TOOLS = [
     transport: 'rest_edge_function',
     workspaceScoped: true,
     knownLocalDevState: 'disabled_by_default',
-    actionAliases: ['list', 'get', 'create', 'update', 'delete', 'refresh', 'list_items'],
-    notes: 'REST-style surface under /groups. Use action aliases via `tools call` or raw REST semantics.',
+    actionAliases: ['list', 'get', 'create', 'update', 'delete', 'refresh', 'list_items', 'add_item', 'group_add_item', 'add_items', 'group_add_items', 'remove_item', 'group_remove_item'],
+    notes: 'REST-style surface under /groups. `add_item`/`group_add_item` accepts an existing `item_id`; `add_items`/`group_add_items` accepts `item_ids` or item payloads for bulk membership adds.',
   },
   {
     name: 'tracking',
@@ -87,8 +98,8 @@ const KNOWN_TOOLS = [
     transport: 'rest_edge_function',
     workspaceScoped: true,
     knownLocalDevState: 'enabled',
-    actionAliases: ['list', 'get', 'create', 'update', 'delete', 'refresh'],
-    notes: 'REST-style surface. The CLI normalizes common action payloads for this tool.',
+    actionAliases: ['list', 'get', 'resolve', 'get_by_value', 'create', 'update', 'delete', 'refresh'],
+    notes: 'REST-style surface. `resolve`/`get_by_value` uses the same workspace/platform/region duplicate-detection lookup as create and returns inactive matches too.',
   },
   { name: 'journey-feedback', category: 'vnext', description: 'Record acceptance or rejection feedback for opportunity bundles.' },
   { name: 'opportunity-bundle-approve', category: 'vnext', description: 'Approve an opportunity bundle and create tracking coverage.' },
@@ -339,6 +350,273 @@ function mergeWorkspaceIdIntoPayload(payload, workspaceId) {
   return { ...payload, workspaceId };
 }
 
+function sanitizeFileComponent(value, fallback = 'item') {
+  const normalized = String(value || '')
+    .trim()
+    .replace(/[^a-z0-9._-]+/gi, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  return normalized || fallback;
+}
+
+function inferExtension(urlValue, contentType, fallback = '.bin') {
+  const normalizedType = String(contentType || '').toLowerCase();
+  if (normalizedType.includes('jpeg')) return '.jpg';
+  if (normalizedType.includes('png')) return '.png';
+  if (normalizedType.includes('webp')) return '.webp';
+  if (normalizedType.includes('gif')) return '.gif';
+  if (normalizedType.includes('mp4')) return '.mp4';
+  if (normalizedType.includes('quicktime')) return '.mov';
+
+  try {
+    const pathname = new URL(urlValue).pathname || '';
+    const ext = path.extname(pathname);
+    if (ext) return ext;
+  } catch {
+    // ignore parse failures
+  }
+  return fallback;
+}
+
+function normalizeVideoExtractBody(body) {
+  const normalized = { ...body };
+  const hasInlineIdentifier =
+    normalized.videoId !== undefined ||
+    normalized.searchResultId !== undefined ||
+    normalized.videoUid !== undefined ||
+    normalized.platformVideoId !== undefined;
+
+  if (!Array.isArray(normalized.items) && hasInlineIdentifier) {
+    normalized.items = [{
+      videoId: normalized.videoId,
+      searchResultId: normalized.searchResultId,
+      videoUid: normalized.videoUid,
+      platformVideoId: normalized.platformVideoId,
+      platformId: normalized.platformId,
+    }];
+    delete normalized.videoId;
+    delete normalized.searchResultId;
+    delete normalized.videoUid;
+    delete normalized.platformVideoId;
+    delete normalized.platformId;
+  }
+
+  return normalized;
+}
+
+function buildVideoExtractBody(opts, workspaceId) {
+  const parsed = opts.body
+    ? ensureJsonObject(parseJsonInput(opts.body, { label: 'body' }), 'body')
+    : {};
+  const normalized = normalizeVideoExtractBody(parsed);
+
+  if (!Array.isArray(normalized.items) || normalized.items.length === 0) {
+    const inlineItem = stripUndefinedEntries({
+      videoId: trimString(opts.videoId) || undefined,
+      searchResultId: opts.searchResultId !== undefined
+        ? coercePositiveInteger(opts.searchResultId, 'searchResultId')
+        : undefined,
+      videoUid: trimString(opts.videoUid) || undefined,
+      platformVideoId: trimString(opts.platformVideoId) || undefined,
+    });
+
+    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.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+
+    normalized.items = [inlineItem];
+  }
+
+  const bodyWithWorkspace = mergeWorkspaceIdIntoPayload(normalized, workspaceId);
+  if (!bodyWithWorkspace.workspaceId) {
+    throw new CliError('tracked-video extraction requires a workspace id.', {
+      code: 'WORKSPACE_REQUIRED',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, or configure a default workspace.',
+    });
+  }
+
+  const nextBody = { ...bodyWithWorkspace };
+  if (opts.wait) {
+    nextBody.ensureAnalysis = true;
+  } else if (opts.ensureAnalysis === true) {
+    nextBody.ensureAnalysis = true;
+  } else if (nextBody.ensureAnalysis === undefined) {
+    nextBody.ensureAnalysis = false;
+  }
+
+  if (opts.skipAssets === true) {
+    nextBody.includeAssets = false;
+  } else if (nextBody.includeAssets === undefined) {
+    nextBody.includeAssets = true;
+  }
+
+  if (opts.includeSourceVideo === true) {
+    nextBody.includeSourceVideo = true;
+  } else if (nextBody.includeSourceVideo === undefined) {
+    nextBody.includeSourceVideo = false;
+  }
+
+  if (opts.frameStrategy && nextBody.frameStrategy === undefined) {
+    nextBody.frameStrategy = opts.frameStrategy;
+  }
+  if (nextBody.frameStrategy === undefined) {
+    nextBody.frameStrategy = 'brief_shots';
+  }
+
+  if (nextBody.frameCount === undefined) {
+    nextBody.frameCount = opts.frameCount !== undefined
+      ? Number(opts.frameCount)
+      : DEFAULT_FRAME_COUNT;
+  }
+
+  if (nextBody.signedUrlSeconds === undefined) {
+    nextBody.signedUrlSeconds = opts.signedUrlSeconds !== undefined
+      ? Number(opts.signedUrlSeconds)
+      : 3600;
+  }
+
+  return nextBody;
+}
+
+function buildVideoQueueBody(opts, workspaceId) {
+  const body = buildVideoExtractBody(opts, workspaceId);
+  return {
+    ...body,
+    ensureAnalysis: true,
+    queueOnly: true,
+    includeAssets: false,
+    includeRawAnalysis: false,
+    includeSourceVideo: false,
+  };
+}
+
+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';
+  });
+}
+
+async function downloadAssetToFile({ url, outDir, stem, timeoutMs }) {
+  const response = await fetchWithTimeout(url, {
+    method: 'GET',
+    headers: { Accept: '*/*' },
+  }, timeoutMs);
+
+  if (!response.ok) {
+    throw new CliError(`Asset download failed: ${response.status}`, {
+      code: 'ASSET_DOWNLOAD_FAILED',
+      exitCode: EXIT_CODES.SERVER,
+      details: await response.text().catch(() => null),
+    });
+  }
+
+  const extension = inferExtension(url, response.headers.get('content-type'));
+  const absolutePath = path.resolve(outDir, `${stem}${extension}`);
+  fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+  const buffer = Buffer.from(await response.arrayBuffer());
+  fs.writeFileSync(absolutePath, buffer);
+  return {
+    path: absolutePath,
+    bytes: buffer.length,
+  };
+}
+
+async function downloadVideoExtractAssets(payload, outDir, timeoutMs) {
+  const results = Array.isArray(payload?.results) ? payload.results : [];
+  const absoluteBaseDir = path.resolve(outDir);
+  fs.mkdirSync(absoluteBaseDir, { recursive: true });
+
+  for (let index = 0; index < results.length; index += 1) {
+    const result = results[index];
+    const resolved = result?.resolved || {};
+    const videoKey = sanitizeFileComponent(
+      resolved.videoUid || resolved.platformVideoId || resolved.searchResultId || `item-${index + 1}`,
+      `item-${index + 1}`,
+    );
+    const itemDir = path.join(absoluteBaseDir, `${String(index + 1).padStart(2, '0')}-${videoKey}`);
+    const downloads = {
+      directory: itemDir,
+      thumbnail: null,
+      sourceVideo: null,
+      frames: [],
+    };
+
+    const thumbnailUrl = result?.assets?.thumbnail?.url;
+    if (typeof thumbnailUrl === 'string' && thumbnailUrl.length > 0) {
+      try {
+        downloads.thumbnail = await downloadAssetToFile({
+          url: thumbnailUrl,
+          outDir: itemDir,
+          stem: 'thumbnail',
+          timeoutMs,
+        });
+      } catch (error) {
+        downloads.thumbnail = {
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    const sourceVideoUrl = result?.assets?.sourceVideo?.signedUrl;
+    if (typeof sourceVideoUrl === 'string' && sourceVideoUrl.length > 0) {
+      try {
+        downloads.sourceVideo = await downloadAssetToFile({
+          url: sourceVideoUrl,
+          outDir: itemDir,
+          stem: 'source-video',
+          timeoutMs,
+        });
+      } catch (error) {
+        downloads.sourceVideo = {
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    const frames = Array.isArray(result?.assets?.frames) ? result.assets.frames : [];
+    for (let frameIndex = 0; frameIndex < frames.length; frameIndex += 1) {
+      const frame = frames[frameIndex];
+      const frameUrl = frame?.signedUrl;
+      if (typeof frameUrl !== 'string' || frameUrl.length === 0) continue;
+      const timestampToken = sanitizeFileComponent(frame?.timestamp || `frame-${frameIndex + 1}`, `frame-${frameIndex + 1}`);
+      try {
+        const download = await downloadAssetToFile({
+          url: frameUrl,
+          outDir: itemDir,
+          stem: `${frame?.kind || 'frame'}-${String(frameIndex + 1).padStart(2, '0')}-${timestampToken}`,
+          timeoutMs,
+        });
+        downloads.frames.push({
+          kind: frame?.kind || null,
+          timestamp: frame?.timestamp || null,
+          path: download.path,
+          bytes: download.bytes,
+        });
+      } catch (error) {
+        downloads.frames.push({
+          kind: frame?.kind || null,
+          timestamp: frame?.timestamp || null,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    result.downloads = downloads;
+  }
+
+  return {
+    ...payload,
+    downloadsRoot: absoluteBaseDir,
+    results,
+  };
+}
+
 function hasOwn(value, key) {
   return Boolean(value) && Object.prototype.hasOwnProperty.call(value, key);
 }
@@ -458,18 +736,40 @@ function normalizeTrackingPayload(payload, fallbackWorkspaceId) {
 
 function normalizeGroupManagementPayload(payload, fallbackWorkspaceId) {
   const groupId = firstDefined(payload, ['group_id', 'groupId', 'id']);
+  const itemId = firstDefined(payload, ['item_id', 'itemId']);
+  const itemIds = firstDefined(payload, ['item_ids', 'itemIds']);
+  const items = firstDefined(payload, ['items']);
   const limit = firstDefined(payload, ['limit']);
   const page = firstDefined(payload, ['page']);
   return stripUndefinedEntries({
     action: trimString(firstDefined(payload, ['action'])) || undefined,
     workspaceId: resolvePayloadWorkspaceId(payload, fallbackWorkspaceId),
     group_id: coercePositiveInteger(groupId, 'group_id'),
+    item_id: coercePositiveInteger(itemId, 'item_id'),
+    item_ids: Array.isArray(itemIds)
+      ? itemIds.map((value, index) => {
+        const parsed = coercePositiveInteger(value, `item_ids[${index}]`);
+        if (!parsed) {
+          throw new CliError(`Invalid item_ids[${index}]: expected a positive integer.`, {
+            code: 'INVALID_ARGUMENT',
+            exitCode: EXIT_CODES.USAGE,
+          });
+        }
+        return parsed;
+      })
+      : undefined,
+    items: Array.isArray(items) ? items : undefined,
     name: trimString(firstDefined(payload, ['name'])) || undefined,
     description: firstDefined(payload, ['description']),
     platform: trimString(firstDefined(payload, ['platform', 'groupPlatform'])) || undefined,
     refresh_frequency: trimString(firstDefined(payload, ['refresh_frequency', 'refreshFrequency'])) || undefined,
     next_refresh_at: firstDefined(payload, ['next_refresh_at', 'nextRefreshAt']) ?? undefined,
     brand_id: trimString(firstDefined(payload, ['brand_id', 'brandId'])) || undefined,
+    track_type: normalizeTrackingType(firstDefined(payload, ['track_type', 'trackType', 'type'])),
+    track_value: trimString(firstDefined(payload, ['track_value', 'trackValue', 'value'])) || undefined,
+    region: typeof firstDefined(payload, ['region']) === 'string'
+      ? trimString(firstDefined(payload, ['region'])) || undefined
+      : firstDefined(payload, ['region']),
     limit: limit !== undefined ? Number(limit) : undefined,
     page: page !== undefined ? Number(page) : undefined,
   });
@@ -512,6 +812,122 @@ function normalizeTrackingExportPayload(payload, fallbackWorkspaceId) {
   });
 }
 
+function buildGroupAddPayloadFromValue(rawValue, payload, label) {
+  const value = trimString(rawValue);
+  if (!value) {
+    throw new CliError(`Invalid ${label}: expected a non-empty tracking value.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+  if (!payload.track_type) {
+    throw new CliError(`${label} requires track_type/type when using raw values.`, {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+      hint: 'Use type=keyword/search, hashtag, or account/creator when adding items by value.',
+    });
+  }
+  return stripUndefinedEntries({
+    name: value,
+    track_type: payload.track_type,
+    track_value: value,
+    refresh_frequency: payload.refresh_frequency,
+    next_refresh_at: payload.next_refresh_at,
+    region: payload.region,
+    platform: payload.platform,
+  });
+}
+
+function buildGroupAddPayloadFromItem(rawItem, payload, label) {
+  if (typeof rawItem === 'number') {
+    return { item_id: coercePositiveInteger(rawItem, label) };
+  }
+
+  if (typeof rawItem === 'string') {
+    const trimmed = rawItem.trim();
+    if (/^\d+$/.test(trimmed)) {
+      return { item_id: coercePositiveInteger(trimmed, label) };
+    }
+    return buildGroupAddPayloadFromValue(rawItem, payload, label);
+  }
+
+  if (!rawItem || typeof rawItem !== 'object' || Array.isArray(rawItem)) {
+    throw new CliError(`Invalid ${label}: expected an item id, string value, or object payload.`, {
+      code: 'INVALID_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+
+  const itemId = coercePositiveInteger(firstDefined(rawItem, ['item_id', 'itemId', 'id']), `${label}.item_id`);
+  if (itemId) {
+    return { item_id: itemId };
+  }
+
+  const trackValue = trimString(firstDefined(rawItem, ['track_value', 'trackValue', 'value'])) || undefined;
+  const name = trimString(firstDefined(rawItem, ['name'])) || trackValue;
+  const trackType = normalizeTrackingType(firstDefined(rawItem, ['track_type', 'trackType', 'type'])) || payload.track_type;
+  const region = firstDefined(rawItem, ['region']) ?? payload.region;
+  const platform = trimString(firstDefined(rawItem, ['platform'])) || payload.platform;
+  const refreshFrequency = trimString(firstDefined(rawItem, ['refresh_frequency', 'refreshFrequency'])) || payload.refresh_frequency;
+  const nextRefreshAt = firstDefined(rawItem, ['next_refresh_at', 'nextRefreshAt']) ?? payload.next_refresh_at;
+
+  if (!name || !trackValue || !trackType) {
+    throw new CliError(`${label} requires item_id or name/track_value + track_type.`, {
+      code: 'MISSING_ARGUMENT',
+      exitCode: EXIT_CODES.USAGE,
+    });
+  }
+
+  return stripUndefinedEntries({
+    name,
+    track_type: trackType,
+    track_value: trackValue,
+    refresh_frequency: refreshFrequency,
+    next_refresh_at: nextRefreshAt,
+    region,
+    platform,
+  });
+}
+
+function buildSingleGroupAddBody(payload) {
+  if (payload.item_id) {
+    return { item_id: payload.item_id };
+  }
+  if (payload.track_value || payload.name) {
+    return buildGroupAddPayloadFromItem({
+      name: payload.name,
+      track_type: payload.track_type,
+      track_value: payload.track_value,
+      refresh_frequency: payload.refresh_frequency,
+      next_refresh_at: payload.next_refresh_at,
+      region: payload.region,
+      platform: payload.platform,
+    }, payload, 'group add item payload');
+  }
+  throw new CliError('group add_item requires item_id or a tracking payload.', {
+    code: 'MISSING_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Provide item_id to attach an existing tracking item, or provide track_type + track_value to create/link by value.',
+  });
+}
+
+function buildBulkGroupAddBody(payload) {
+  if (Array.isArray(payload.item_ids) && payload.item_ids.length > 0) {
+    return payload.item_ids.map((item_id) => ({ item_id }));
+  }
+  if (Array.isArray(payload.items) && payload.items.length > 0) {
+    return payload.items.map((item, index) => buildGroupAddPayloadFromItem(item, payload, `items[${index}]`));
+  }
+  if (payload.item_id || payload.track_value || payload.name) {
+    return [buildSingleGroupAddBody(payload)];
+  }
+  throw new CliError('group add_items requires item_ids, items, or a single item payload.', {
+    code: 'MISSING_ARGUMENT',
+    exitCode: EXIT_CODES.USAGE,
+    hint: 'Use item_ids to bulk attach existing tracking items, or use items with track_type/type for value-based adds.',
+  });
+}
+
 function translateTrackingAction(payload, workspaceId) {
   const action = payload.action ? payload.action.toLowerCase() : null;
   if (!action) {
@@ -572,6 +988,28 @@ function translateTrackingAction(payload, workspaceId) {
     };
   }
 
+  if (action === 'resolve' || action === 'item_resolve' || action === 'get_by_value' || action === 'item_get_by_value') {
+    if (!payload.track_type || !payload.track_value) {
+      throw new CliError('track_type and track_value are required for tracking resolve.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'GET',
+      pathSuffix: buildPathWithQuery('', {
+        workspace_id: workspaceId || undefined,
+        resolve: 'true',
+        track_type: payload.track_type,
+        track_value: payload.track_value,
+        platform: payload.platform,
+        region: payload.region,
+      }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
   if (action === 'create' || action === 'item_create') {
     return {
       method: 'POST',
@@ -644,7 +1082,7 @@ function translateTrackingAction(payload, workspaceId) {
   throw new CliError(`Unsupported tracking action: ${payload.action}`, {
     code: 'INVALID_ARGUMENT',
     exitCode: EXIT_CODES.USAGE,
-    hint: 'Supported tracking actions: list, get, create, update, delete, refresh.',
+    hint: 'Supported tracking actions: list, get, resolve, create, update, delete, refresh.',
   });
 }
 
@@ -791,10 +1229,59 @@ function translateGroupManagementAction(payload, workspaceId, originalMethod) {
     };
   }
 
+  if (action === 'add_item' || action === 'group_add_item') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group add_item.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items`, { workspace_id: workspaceId || undefined }),
+      body: buildSingleGroupAddBody(payload),
+      workspaceId,
+    };
+  }
+
+  if (action === 'add_items' || action === 'group_add_items') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    if (!groupId) {
+      throw new CliError('group_id is required for group add_items.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'POST',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items/bulk`, { workspace_id: workspaceId || undefined }),
+      body: buildBulkGroupAddBody(payload),
+      workspaceId,
+    };
+  }
+
+  if (action === 'remove_item' || action === 'group_remove_item') {
+    const groupId = coercePositiveInteger(payload.group_id, 'group_id');
+    const itemId = coercePositiveInteger(payload.item_id, 'item_id');
+    if (!groupId || !itemId) {
+      throw new CliError('group_id and item_id are required for group remove_item.', {
+        code: 'MISSING_ARGUMENT',
+        exitCode: EXIT_CODES.USAGE,
+      });
+    }
+    return {
+      method: 'DELETE',
+      pathSuffix: buildPathWithQuery(`/groups/${groupId}/items/${itemId}`, { workspace_id: workspaceId || undefined }),
+      body: undefined,
+      workspaceId,
+    };
+  }
+
   throw new CliError(`Unsupported group-management action: ${payload.action}`, {
     code: 'INVALID_ARGUMENT',
     exitCode: EXIT_CODES.USAGE,
-    hint: 'Supported group-management actions: list, get, create, update, delete, refresh, list_items.',
+    hint: 'Supported group-management actions: list, get, create, update, delete, refresh, list_items, add_item, add_items, remove_item.',
   });
 }
 
@@ -1947,6 +2434,160 @@ async function handleDataExportReport(opts) {
   process.stdout.write(JSON.stringify(json, null, opts.pretty ? 2 : 0) + '\n');
 }
 
+async function handleVideoExtract(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
+  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const body = buildVideoExtractBody(opts, resolvedWorkspaceId);
+  const path = useGateway ? '/cli/tools/tracked-video-extract' : '/functions/v1/tracked-video-extract';
+
+  emitWorkspaceContext(opts, {
+    workspaceId: body.workspaceId || resolvedWorkspaceId,
+    source: body.workspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    functionName: 'tracked-video-extract',
+    method: 'POST',
+  });
+
+  const requestOnce = async (remainingTimeoutMs) => {
+    const res = await callApi({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path,
+      method: 'POST',
+      body,
+      workspaceId: body.workspaceId || resolvedWorkspaceId,
+      timeoutMs: remainingTimeoutMs,
+    });
+
+    if (!res.ok) {
+      throw await buildHttpError(res, {
+        label: 'Tracked video extract',
+        functionName: 'tracked-video-extract',
+        method: 'POST',
+      });
+    }
+
+    const contentType = res.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      throw new CliError('tracked-video-extract returned a non-JSON response.', {
+        code: 'INVALID_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+      });
+    }
+
+    return await res.json();
+  };
+
+  let payload = await requestOnce(timeoutMs);
+
+  if (opts.wait) {
+    const pollIntervalMs = resolvePollIntervalMs(opts);
+    const deadline = Date.now() + timeoutMs;
+
+    while (hasPendingVideoExtractResults(payload)) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        throw new CliError('Timed out waiting for tracked video analysis completion.', {
+          code: 'ASYNC_WAIT_TIMEOUT',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Increase --timeout <ms> or omit --wait to return the current status immediately.',
+          details: truncateDetails(payload),
+        });
+      }
+
+      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 (opts.outDir) {
+    payload = await downloadVideoExtractAssets(payload, opts.outDir, timeoutMs);
+  }
+
+  emitJsonOutput(payload, opts.pretty);
+}
+
+async function handleVideoQueueAnalysis(opts) {
+  const config = loadConfig();
+  const apiKey = requireApiKey(opts, config);
+  const apiBase = resolveApiBase(opts, config);
+  const supabaseUrl = resolveLegacyUrl(resolveSupabaseUrl(opts, config), 'SOCIALSEAL_SUPABASE_URL');
+  const { resolvedApiBase, legacyUrl, useGateway } = resolveApiTarget({ apiBase, legacyUrl: supabaseUrl });
+  const timeoutMs = resolveTimeoutMs(opts, config);
+  const { workspaceId: resolvedWorkspaceId, source: workspaceSource } = resolveWorkspaceSelection(opts, config);
+
+  const body = buildVideoQueueBody(opts, resolvedWorkspaceId);
+  const path = useGateway ? '/cli/tools/tracked-video-extract' : '/functions/v1/tracked-video-extract';
+
+  emitWorkspaceContext(opts, {
+    workspaceId: body.workspaceId || resolvedWorkspaceId,
+    source: body.workspaceId === resolvedWorkspaceId ? workspaceSource : 'body',
+    functionName: 'tracked-video-extract',
+    method: 'POST',
+  });
+
+  const requestOnce = async (remainingTimeoutMs) => {
+    const res = await callApi({
+      apiBase: useGateway ? resolvedApiBase : legacyUrl,
+      apiKey,
+      path,
+      method: 'POST',
+      body,
+      workspaceId: body.workspaceId || resolvedWorkspaceId,
+      timeoutMs: remainingTimeoutMs,
+    });
+
+    if (!res.ok) {
+      throw await buildHttpError(res, {
+        label: 'Tracked video queue-analysis',
+        functionName: 'tracked-video-extract',
+        method: 'POST',
+      });
+    }
+
+    const contentType = res.headers.get('content-type') || '';
+    if (!contentType.includes('application/json')) {
+      throw new CliError('tracked-video-extract returned a non-JSON response.', {
+        code: 'INVALID_RESPONSE',
+        exitCode: EXIT_CODES.SERVER,
+      });
+    }
+
+    return await res.json();
+  };
+
+  let payload = await requestOnce(timeoutMs);
+
+  if (opts.wait) {
+    const pollIntervalMs = resolvePollIntervalMs(opts);
+    const deadline = Date.now() + timeoutMs;
+
+    while (hasPendingVideoExtractResults(payload)) {
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        throw new CliError('Timed out waiting for queued video analysis completion.', {
+          code: 'ASYNC_WAIT_TIMEOUT',
+          exitCode: EXIT_CODES.SERVER,
+          hint: 'Increase --timeout <ms> or omit --wait to return queue status immediately.',
+          details: truncateDetails(payload),
+        });
+      }
+
+      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()));
+    }
+  }
+
+  emitJsonOutput(payload, opts.pretty);
+}
+
 async function handleWorkspaceList(opts) {
   const config = loadConfig();
   const apiKey = requireApiKey(opts, config);
@@ -2103,7 +2744,7 @@ if (typeof program.showHelpAfterError === 'function') {
 if (typeof program.showSuggestionAfterError === 'function') {
   program.showSuggestionAfterError(true);
 }
-program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
+program.addHelpText('after', `\nExamples:\n  socialseal workspace list\n  socialseal workspace use <workspace-id>\n  socialseal agent run --message \"ping\"\n  socialseal tools list\n  socialseal tools call --function <tool> --body @payload.json\n  socialseal tools call --function search-journey-run --body @payload.json --async --workspace-id <uuid>\n  socialseal video queue-analysis --video-id 734829384 --workspace-id <uuid>\n  socialseal video extract --video-id 734829384 --wait --out-dir ./video-assets\n  socialseal data export-tracking --group-id 123 --time-period 30d\n`);
 
 program
   .command('agent')
@@ -2228,4 +2869,51 @@ data
   .option('--verbose', 'Show error details')
   .action((opts) => runCommand(handleDataExportReport, opts));
 
+const video = program.command('video').description('Tracked video extraction workflows');
+
+video
+  .command('queue-analysis')
+  .description('Queue video analysis for tracked videos or tracked search results')
+  .option('--video-id <id>', 'Tracked video id (tries video_uid first, then platform video id)')
+  .option('--search-result-id <id>', 'Tracked search result id')
+  .option('--video-uid <id>', 'Tracked video_uid')
+  .option('--platform-video-id <id>', 'Tracked platform video id')
+  .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch queueing')
+  .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)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleVideoQueueAnalysis, opts));
+
+video
+  .command('extract')
+  .description('Resolve tracked videos/results into structured analysis plus reference assets')
+  .option('--video-id <id>', 'Tracked video id (tries video_uid first, then platform video id)')
+  .option('--search-result-id <id>', 'Tracked search result id')
+  .option('--video-uid <id>', 'Tracked video_uid')
+  .option('--platform-video-id <id>', 'Tracked platform video id')
+  .option('--body <jsonOrFile>', 'JSON body or @payload.json for batch extraction')
+  .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')
+  .option('--skip-assets', 'Skip asset URL generation')
+  .option('--include-source-video', 'Include a signed source MP4 URL when available')
+  .option('--frame-strategy <strategy>', 'brief_shots|quartiles')
+  .option('--frame-count <n>', 'Number of still frames to return (1-5)')
+  .option('--signed-url-seconds <n>', 'Signed URL TTL in seconds')
+  .option('--out-dir <path>', 'Download returned assets into this local directory')
+  .option('--api-base <url>', 'API base URL (default https://api.socialseal.co)')
+  .option('--api-key <key>', 'CLI API key')
+  .option('--workspace-id <id>', 'Workspace id (for scoped keys)')
+  .option('--pretty', 'Pretty-print JSON')
+  .option('--json', 'Emit machine-readable errors')
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--verbose', 'Show error details')
+  .action((opts) => runCommand(handleVideoExtract, opts));
+
 program.parseAsync(process.argv);