@clipit-ai/cli 0.2.6 → 0.2.8

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.6';
+const VERSION = '0.2.8';
 const DEFAULT_BASE_URL = 'https://clipit.dev';
 const DEFAULT_SCOPES = [
   'clippy_agent',
@@ -466,12 +466,13 @@ function usage() {
     '  clipit mcp [stdio]',
     '  clipit run <functionName> [--params @file.json] [--clip-id id] [--video-id id] [--confirm] [--max-credits n]',
     '  clipit videos list|get|upload|abort-upload|import-url|transcribe|transcript|suggest-clips|delete ...',
-    '  clipit clips list|get|delivery-state|create|update|render|download|delete ...',
+    '  clipit clips list|get|delivery-state|create|update|initialize-snapshot|render|download|delete ...',
     '  clipit jobs get|wait <jobId>',
     '  clipit credits balance|usage|estimate ...',
     '  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 ...',
@@ -1239,18 +1240,28 @@ 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);
 
+  if (tool?.costBand === 'free') {
+    if (tool?.confirmation?.required) {
+      requireConfirm(options, `Running confirmation-gated tool ${functionName}`);
+    }
+    return null;
+  }
+
   let staticEstimates = null;
   if (!runEstimate && (limit !== null || needsConfirmationPreflight)) {
     staticEstimates = await buildStaticRunEstimates(config, options, functionName, parameters, payload);
@@ -1656,14 +1667,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;
       }
     }
   }
@@ -1703,6 +1726,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 = {
@@ -1719,16 +1749,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 }
@@ -2718,6 +2742,12 @@ async function clips(config, options, action, args) {
   }
   if (action === 'update') {
     if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    if (options.aspect !== undefined || options['aspect-ratio'] !== undefined) {
+      throw Object.assign(
+        new Error('clips update does not accept --aspect-ratio. Use clipit run setClipAspectRatio --clip-id <id> --params \'{"aspectRatio":"4:5"}\', then start an explicit render.'),
+        { exitCode: EXIT.USAGE },
+      );
+    }
     const body = options.params
       ? await readJsonOption(String(options.params))
       : {
@@ -2732,6 +2762,26 @@ async function clips(config, options, action, args) {
     output(await apiFetch(config, options, 'PATCH', `/api/v1/clips/${encodeURIComponent(args[0])}`, body), options);
     return;
   }
+  if (action === 'initialize-snapshot') {
+    if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    const body = options.params
+      ? await readJsonOption(String(options.params))
+      : compactObject({
+          aspectRatio: options.aspect || options['aspect-ratio'],
+          fitBackground: options['fit-background'],
+          quality: options.quality,
+          includeCaptions: options.captions === undefined ? undefined : boolOption(options.captions),
+          captionStyle: options['caption-style'],
+        });
+    output(await apiFetch(
+      config,
+      options,
+      'POST',
+      `/api/v1/clips/${encodeURIComponent(args[0])}/editor-snapshot/initialize`,
+      body,
+    ), options);
+    return;
+  }
   if (action === 'render') {
     if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
     const body = options.params
@@ -2919,7 +2969,6 @@ function defaultExportStartBody(clipId) {
       audioSampleRate: 48000,
     },
     format: 'mp4',
-    includeAudio: true,
   };
 }
 
@@ -3013,6 +3062,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)]))
@@ -3259,6 +3345,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);
@@ -3275,6 +3396,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')
@@ -3310,6 +3437,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');
@@ -3767,7 +3895,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',
@@ -4341,6 +4469,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.6",
+  "version": "0.2.8",
   "description": "ClipIt CLI for connecting shell-capable agents to ClipIt.",
   "type": "module",
   "bin": {