@clipit-ai/cli 0.2.7 → 0.2.9

package/README.md

@@ -110,6 +110,9 @@ clipit exports wait <jobId> --stream
 clipit exports download <jobId> --open
 clipit exports cancel <jobId> --confirm --json
 
+clipit deliverables create --export-id <exportId> --title "Client-ready clip" --confirm --json
+clipit deliverables list --status selected --json
+
 clipit assets list --json
 clipit assets upload ./brand-logo.png --kind image --confirm --json
 clipit assets delete <assetId> --confirm --json
@@ -131,6 +134,8 @@ clipit social get <postId> --json
 clipit social cancel <postId> --confirm --json
 ```
 
+For enterprise workspace profiles, create a ready delivery after the exact export completes, then send the returned `clientSelectionUrl` to the client. Publishing and scheduling remain blocked until that client selects the delivery. `clipit deliverables list --export-id <exportId> --json` shows the current delivery state; after selection, the social commands automatically pin the exact delivery ID and granted social account.
+
 ## Reliability And Spend Guards
 
 The CLI retries only idempotent `GET` requests, with at most two retries for network failures, `429`, `502`, `503`, and `504`. `Retry-After` is honored up to 10 seconds. `POST`, `PATCH`, and `DELETE` requests are never retried. Pass `--no-retry` to disable GET retries.
@@ -275,6 +280,7 @@ Only use `--allow-custom-host` for hosts you control or trust. It permits the CL
 | Credits | `credits balance`, `credits usage`, `credits estimate` | Estimate accepts `--metrics @file.json`. |
 | Analytics | `analytics overview`, `analytics top-clips`, `analytics post` | `overview` returns aggregate and by-platform metrics. |
 | Exports | `exports start/list/get/wait/download/cancel` | Export jobs poll through `/api/v1/exports/:jobId`; paid start requires `--confirm`. |
+| Enterprise deliveries | `deliverables list/create` | Workspace profiles can deliver exact exports and inspect client selection; only the client can select. |
 | Assets | `assets list/upload/delete` | Upload signs, PUTs the file to object storage, then finalizes the library asset. Delete requires `--confirm`. |
 | Thumbnails and B-Roll | `thumbnails generate/get/list`, `broll plan/generate/list/get` | Paid generation commands require `--confirm`. |
 | Social | `social accounts/post/schedule/posts/get/cancel` | Publish/schedule/cancel require `--confirm`; `x` maps to the server `twitter` platform. |

package/bin/clipit.mjs

@@ -9,7 +9,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-const VERSION = '0.2.7';
+const VERSION = '0.2.9';
 const DEFAULT_BASE_URL = 'https://clipit.dev';
 const DEFAULT_SCOPES = [
   'clippy_agent',
@@ -472,6 +472,7 @@ function usage() {
     '  clipit billing capabilities|catalog|create-attempt|attempt|receipt|subscription ...',
     '  clipit analytics overview|top-clips|post ...',
     '  clipit exports start|list|get|wait|download|cancel ...',
+    '  clipit deliverables list|create ...',
     '  clipit assets list|upload|delete ...',
     '  clipit thumbnails generate|get|list ...',
     '  clipit broll plan|generate|list|get ...',
@@ -483,6 +484,51 @@ function usage() {
   ].join('\n');
 }
 
+function commandUsage(command, subcommand) {
+  if (command === 'social' && subcommand === 'schedule') {
+    return [
+      'Usage:',
+      '  clipit social schedule --clip-id <id> --platforms <platform[,platform]> --caption <text> --at <ISO-8601> --confirm',
+      '',
+      'Required:',
+      '  --clip-id <id>       Clip to schedule',
+      '  --platforms <list>   Comma-separated destination platforms',
+      '  --caption <text>     Post caption',
+      '  --at <ISO-8601>      Scheduled publish time',
+      '  --confirm            Confirm the scheduling mutation',
+      '',
+      'Optional:',
+      '  --export-id <id>     Pin the exact completed export',
+      '  --account-ids <map>  Exact accounts as platform=accountId pairs',
+      '  --title <text>        Post title',
+      '  --hashtags <list>    Comma-separated hashtags',
+      '  --profile <name>     Named ClipIt credential profile',
+      '  --json               Emit machine-readable JSON',
+      '',
+      'Enterprise scheduling requires a client-selected deliverable and a granted connected account.',
+    ].join('\n');
+  }
+  if (command === 'deliverables' && subcommand === 'create') {
+    return [
+      'Usage:',
+      '  clipit deliverables create --export-id <id> --title <text> --confirm',
+      '',
+      'Required:',
+      '  --export-id <id>   Exact completed export to deliver',
+      '  --title <text>     Client-facing deliverable title',
+      '  --confirm          Confirm the delivery mutation',
+      '',
+      'Optional:',
+      '  --note <text>      Client-facing note',
+      '  --profile <name>   Named ClipIt credential profile',
+      '  --json             Emit machine-readable JSON',
+      '',
+      'The response includes clientSelectionUrl; the client must select the delivery before enterprise social publishing.',
+    ].join('\n');
+  }
+  return null;
+}
+
 function getBaseUrl(config, options) {
   const profile = profileData(config, options);
   const selected = profileIsAuthoritative(config, options);
@@ -1239,14 +1285,17 @@ async function enforceMaxCredits(config, options, commandKey, context = {}) {
   }
 }
 
-async function enforceRunMaxCredits(config, options, functionName, parameters = {}, payload = {}) {
+async function enforceRunMaxCredits(config, options, functionName, parameters = {}, payload = {}, catalogTool = null) {
   const limit = maxCreditsLimit(options);
   const needsConfirmationPreflight = !boolOption(options.confirm);
   if (limit === null && !needsConfirmationPreflight) return null;
 
-  const catalog = await apiFetch(config, options, 'GET', '/api/v1/agent/tools');
-  const tools = Array.isArray(catalog?.tools) ? catalog.tools : Array.isArray(catalog) ? catalog : [];
-  const tool = tools.find((item) => item.name === functionName);
+  let tool = catalogTool;
+  if (!tool) {
+    const catalog = await apiFetch(config, options, 'GET', '/api/v1/agent/tools');
+    const tools = Array.isArray(catalog?.tools) ? catalog.tools : Array.isArray(catalog) ? catalog : [];
+    tool = tools.find((item) => item.name === functionName);
+  }
   const runEstimate = tool?.estimate ?? tool?.confirmation?.estimate ?? tool?.confirmation?.costEstimate ?? null;
   const isMetered = Boolean(tool?.costBand && tool.costBand !== 'free');
   const isMeteredExempt = RUN_METERED_CONFIRMATION_EXEMPTIONS.has(functionName);
@@ -1663,14 +1712,26 @@ async function contextCommand(config, options, action) {
   throw Object.assign(new Error(`Unknown context command: ${action || ''}`), { exitCode: EXIT.USAGE });
 }
 
-function applyContextToAgentPayload(payload, parameters, context) {
+function toolAcceptsContextField(tool, field) {
+  return Boolean(
+    tool?.contextRequirements?.[field]
+    || tool?.parameters?.properties?.[field],
+  );
+}
+
+function applyContextToAgentPayload(payload, parameters, context, tool) {
   const canMutateParameters = parameters && typeof parameters === 'object' && !Array.isArray(parameters);
   const hadExplicitVideoId = canMutateParameters && parameters.videoId !== undefined;
   for (const field of ['videoId', 'clipId', 'projectId', 'sequenceId']) {
-    if (context[field] && !payload[field]) {
-      payload[field] = context[field];
-      if (canMutateParameters && parameters[field] === undefined) {
-        parameters[field] = context[field];
+    const value = payload[field] || context[field];
+    if (value) {
+      if (!payload[field]) payload[field] = value;
+      if (
+        canMutateParameters
+        && parameters[field] === undefined
+        && toolAcceptsContextField(tool, field)
+      ) {
+        parameters[field] = value;
       }
     }
   }
@@ -1710,6 +1771,13 @@ function normalizeAgentExecuteResult(result) {
 
 async function runTool(config, options, functionName) {
   if (!functionName) throw Object.assign(new Error('Function name is required.'), { exitCode: EXIT.USAGE });
+  if (RUN_CONFIRMATION_LABELS[functionName]) {
+    confirmPaid(options, RUN_CONFIRMATION_LABELS[functionName]);
+  }
+  const catalog = await apiFetch(config, options, 'GET', '/api/v1/agent/tools');
+  const tools = Array.isArray(catalog?.tools) ? catalog.tools : Array.isArray(catalog) ? catalog : [];
+  const tool = tools.find((item) => item.name === functionName);
+  if (!tool) throw Object.assign(new Error(`Tool not found: ${functionName}`), { exitCode: EXIT.USAGE });
   const parameters = await readJsonOption(options.params || options['params-json']);
   const context = await buildContext(config, options);
   const payload = {
@@ -1726,16 +1794,10 @@ async function runTool(config, options, functionName) {
     if (options[flag]) {
       const value = String(options[flag]);
       payload[field] = value;
-      if (parameters && typeof parameters === 'object' && !Array.isArray(parameters) && parameters[field] === undefined) {
-        parameters[field] = value;
-      }
     }
   }
-  applyContextToAgentPayload(payload, parameters, context);
-  if (RUN_CONFIRMATION_LABELS[functionName]) {
-    confirmPaid(options, RUN_CONFIRMATION_LABELS[functionName]);
-  }
-  const estimate = await enforceRunMaxCredits(config, options, functionName, parameters, payload);
+  applyContextToAgentPayload(payload, parameters, context, tool);
+  const estimate = await enforceRunMaxCredits(config, options, functionName, parameters, payload, tool);
   const result = normalizeAgentExecuteResult(await apiFetch(config, options, 'POST', '/api/v1/agent/execute', payload));
   const outputResult = estimate && result && typeof result === 'object' && !Array.isArray(result) && result.estimate === undefined
     ? { ...result, estimate }
@@ -2952,7 +3014,6 @@ function defaultExportStartBody(clipId) {
       audioSampleRate: 48000,
     },
     format: 'mp4',
-    includeAudio: true,
   };
 }
 
@@ -3046,6 +3107,43 @@ async function exportsCommand(config, options, action, args) {
   throw Object.assign(new Error(`Unknown exports command: ${action || ''}`), { exitCode: EXIT.USAGE });
 }
 
+function enterpriseClientSelectionUrl(config, options, selectionPath = '/enterprise?tab=delivered') {
+  return new URL(selectionPath, getBaseUrl(config, options)).toString();
+}
+
+async function deliverables(config, options, action) {
+  if (action === 'list') {
+    const result = await apiFetch(config, options, 'GET', `/api/v1/deliverables${queryString({
+      status: options.status,
+      exportId: options['export-id'],
+      limit: options.limit,
+      offset: options.offset,
+    })}`);
+    output({
+      ...result,
+      clientSelectionUrl: enterpriseClientSelectionUrl(config, options, result.clientSelectionPath),
+    }, options);
+    return;
+  }
+  if (action === 'create') {
+    const exportId = requiredString(options['export-id'], '--export-id');
+    const title = requiredString(options.title, '--title');
+    requireConfirm(options, 'Delivering an export to the enterprise client');
+    const result = await apiFetch(config, options, 'POST', '/api/v1/deliverables', {
+      exportId,
+      title,
+      note: options.note,
+    });
+    output({
+      ...result,
+      clientSelectionPath: '/enterprise?tab=delivered',
+      clientSelectionUrl: enterpriseClientSelectionUrl(config, options),
+    }, options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown deliverables command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
 async function putSignedUpload(uploadUrl, filePath, contentType, size, options, requiredHeaders) {
   const headers = requiredHeaders && typeof requiredHeaders === 'object'
     ? Object.fromEntries(Object.entries(requiredHeaders).map(([key, value]) => [key, String(value)]))
@@ -3292,6 +3390,41 @@ function socialAccountIdPins(value) {
   }));
 }
 
+async function resolveEnterpriseSelectedDelivery(config, options, clipId, exportId) {
+  if (profileData(config, options).scope?.enterprise !== true) return null;
+  const result = await apiFetch(
+    config,
+    options,
+    'GET',
+    `/api/v1/deliverables${queryString({ exportId, limit: 100, offset: 0 })}`,
+  );
+  const deliveries = Array.isArray(result?.deliverables) ? result.deliverables : [];
+  const selected = deliveries.find((delivery) => (
+    delivery?.clipId === clipId
+    && delivery?.exportId === exportId
+    && delivery?.status === 'selected'
+  ));
+  if (selected?.id) return selected;
+  const current = deliveries.find((delivery) => (
+    delivery?.clipId === clipId && delivery?.exportId === exportId
+  )) ?? null;
+  const clientSelectionPath = result?.clientSelectionPath || '/enterprise?tab=delivered';
+  throw Object.assign(
+    new Error('The client has not selected this delivered export for publishing.'),
+    {
+      exitCode: EXIT.USAGE,
+      data: {
+        clipId,
+        exportId,
+        currentDelivery: current,
+        clientSelectionPath,
+        clientSelectionUrl: enterpriseClientSelectionUrl(config, options, clientSelectionPath),
+        nextCommand: `clipit deliverables list --export-id ${shellQuote(exportId)} --json`,
+      },
+    },
+  );
+}
+
 async function socialPostBody(config, options, scheduled) {
   const clipId = requiredString(options['clip-id'], '--clip-id');
   const platforms = socialPlatformList(options.platforms);
@@ -3308,6 +3441,12 @@ async function socialPostBody(config, options, scheduled) {
     requestedExportId,
     requireReadyToPublish: true,
   });
+  const enterpriseDelivery = await resolveEnterpriseSelectedDelivery(
+    config,
+    options,
+    clipId,
+    selectedExport.exportId,
+  );
   const accountsResponse = await apiFetch(config, options, 'GET', '/api/v1/social/accounts');
   const connectedAccounts = Array.isArray(accountsResponse?.accounts)
     ? accountsResponse.accounts.filter((account) => account?.connected && typeof account?.accountId === 'string')
@@ -3343,6 +3482,7 @@ async function socialPostBody(config, options, scheduled) {
     expectedSnapshotId: editorState.snapshotId,
     expectedOutputObjectFingerprint: selectedExport.outputObjectFingerprint,
     expectedAccountIds,
+    enterpriseDeliverableId: enterpriseDelivery?.id,
     publishExactCurrentArtifact: true,
   });
   if (scheduled) body.scheduledFor = requiredString(options.at, '--at');
@@ -3800,7 +3940,7 @@ async function handleMcpRequest(config, options, message) {
       const result = await handleLocalMcpBillingTool(config, options, name, parameters);
       return { jsonrpc: '2.0', id, result: mcpTextResult(result, Boolean(result?.error)) };
     }
-    applyContextToAgentPayload(payload, parameters, await buildContext(config, options));
+    applyContextToAgentPayload(payload, parameters, await buildContext(config, options), tool);
     if (!confirmed && mcpToolRequiresConfirmation(tool, name)) {
       return {
         jsonrpc: '2.0',
@@ -4343,7 +4483,7 @@ async function main() {
     return;
   }
   if (!command || options.help) {
-    console.log(usage());
+    console.log(commandUsage(command, subcommand) ?? usage());
     return;
   }
   if (command === 'version' || command === '--version' || command === '-v') {
@@ -4374,6 +4514,7 @@ async function main() {
   if (command === 'billing') return billing(config, options, subcommand, rest);
   if (command === 'analytics') return analytics(config, options, subcommand, rest);
   if (command === 'exports') return exportsCommand(config, options, subcommand, rest);
+  if (command === 'deliverables') return deliverables(config, options, subcommand);
   if (command === 'assets') return assets(config, options, subcommand, rest);
   if (command === 'thumbnails') return thumbnails(config, options, subcommand, rest);
   if (command === 'broll') return broll(config, options, subcommand, rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipit-ai/cli",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "ClipIt CLI for connecting shell-capable agents to ClipIt.",
   "type": "module",
   "bin": {