@socialseal/cli 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 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/package.json

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

package/src/index.js

@@ -76,8 +76,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 +87,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.' },
@@ -458,18 +458,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 +534,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 +710,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 +804,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 +951,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.',
   });
 }