blitzreels 0.1.5 → 0.1.7

package/dist/commands/clips.js

@@ -1,30 +1,78 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
 import { commandSpec } from "../command-metadata.js";
 export const CLIPS_COMMAND_SPECS = [
     commandSpec({
-        command: ["clips", "create"],
-        usage: "blitzreels clips create --source-type asset|youtube [--asset-id ID|--youtube-url URL] [--name NAME] [--selection-mode auto_best|suggestion|time_range] [--suggestion-id ID] [--start-seconds 52] [--end-seconds 64] [--min-duration 8] --max-duration 12 [--layout-mode auto|prefer_split|prefer_focus] [--content-type-hint auto|podcast|tutorial|generic] [--captions true] [--caption-style-id ID|null] [--qa-mode required|permissive] [--auto-export false]",
+        command: ["clips", "list"],
+        usage: "blitzreels clips list [--asset-id ID] [--project-id ID] [--status ready|exported|failed|needs_repair] [--limit 20] [--offset 0] [--json]",
         flags: [
-            "source-type",
             "asset-id",
+            "project-id",
+            {
+                name: "status",
+                enum: [
+                    "preparing_source",
+                    "awaiting_suggestions",
+                    "selecting_clip",
+                    "assembling",
+                    "qa_running",
+                    "needs_reselection",
+                    "needs_repair",
+                    "ready",
+                    "exporting",
+                    "exported",
+                    "failed",
+                ],
+            },
+            "limit",
+            "offset",
+        ],
+        description: "List managed clip runs with bounded output.",
+    }),
+    commandSpec({
+        command: ["clips", "create"],
+        usage: "blitzreels clips create [--asset-id ID|--youtube-url URL] [--output ./clips] [--count 5] [--idempotency-key KEY]",
+        flags: [
+            { name: "asset-id", enum: [] },
             "youtube-url",
-            "name",
-            "selection-mode",
-            "suggestion-id",
-            "start-seconds",
-            "end-seconds",
-            "min-duration",
-            "max-duration",
-            "layout-mode",
-            "content-type-hint",
-            "captions",
-            "caption-style-id",
-            "qa-mode",
-            "auto-export",
+            {
+                name: "output",
+                description: "Directory for exported MP4 downloads.",
+            },
+            "logo-asset-id",
+            {
+                name: "count",
+                type: "number",
+                default: 5,
+                description: "Maximum rendered clips to download from the batch.",
+            },
+            {
+                name: "preset",
+                enum: ["default", "high-retention", "formation-clipperz", "demo-focus"],
+                default: "default",
+                description: "Override clip preset.",
+                hidden: true,
+            },
+            {
+                name: "clip-preset-id",
+                enum: ["default", "high-retention", "formation-clipperz", "demo-focus"],
+                default: "default",
+                description: "Override clip preset id.",
+                hidden: false,
+            },
+            { name: "caption-theme-id" },
+            {
+                name: "idempotency-key",
+                description: "Stable retry key; reuse only with identical inputs.",
+            },
+            { name: "interval-ms", type: "number", hidden: true },
+            { name: "timeout-ms", type: "number", hidden: true },
         ],
-        description: "Create a managed clip job from a workspace asset or YouTube URL.",
+        description: "Create clips from a workspace asset or YouTube URL; with --output it exports 1080p MP4 files.",
         examples: [
-            'blitzreels clips create --source-type youtube --youtube-url https://youtube.com/watch?v=... --name "MKBHD hero loop" --min-duration 8 --max-duration 12 --qa-mode permissive',
-            "blitzreels clips create --source-type asset --asset-id ID --selection-mode time_range --start-seconds 52 --end-seconds 64 --max-duration 12",
+            "blitzreels clips create --asset-id ID --output ./clips",
+            "blitzreels clips create --asset-id ID --logo-asset-id LOGO_ID --output ./clips --count 5",
+            "blitzreels clips create --youtube-url https://youtube.com/watch?v=...",
         ],
     }),
     commandSpec({
@@ -41,31 +89,59 @@ export const CLIPS_COMMAND_SPECS = [
     }),
     commandSpec({
         command: ["clips", "reselect"],
-        usage: "blitzreels clips reselect --clip-id ID --selection-mode auto_best|suggestion|time_range [--suggestion-id ID] [--start-seconds 52] [--end-seconds 64] [--min-duration 8] [--max-duration 12]",
+        usage: "blitzreels clips reselect --clip-id ID [--suggestion-id ID | --start-seconds 52 --end-seconds 64]",
         flags: [
             "clip-id",
-            "selection-mode",
             "suggestion-id",
             "start-seconds",
             "end-seconds",
-            "min-duration",
-            "max-duration",
+            {
+                name: "selection-mode",
+                enum: ["auto_best", "suggestion", "time_range"],
+                hidden: true,
+            },
+            { name: "min-duration", hidden: true },
+            { name: "max-duration", hidden: true },
         ],
         description: "Choose a different suggestion or time range for a clip.",
         mutates: true,
     }),
     commandSpec({
         command: ["clips", "repair"],
-        usage: "blitzreels clips repair --clip-id ID [--repair-mode auto|prefer_split|prefer_focus|prefer_tutorial|move_captions_off_faces]",
-        flags: ["clip-id", "repair-mode"],
+        usage: "blitzreels clips repair --clip-id ID",
+        flags: [
+            "clip-id",
+            {
+                name: "repair-mode",
+                enum: [
+                    "auto",
+                    "prefer_split",
+                    "prefer_focus",
+                    "prefer_tutorial",
+                    "prefer_demo",
+                    "move_captions_off_faces",
+                ],
+                default: "auto",
+                hidden: true,
+            },
+        ],
         description: "Run a repair pass on an assembled clip.",
         mutates: true,
     }),
     commandSpec({
         command: ["clips", "export"],
-        usage: "blitzreels clips export --clip-id ID [--resolution 1080p] [--format mp4] [--allow-blocking-qa-bypass false]",
-        flags: ["clip-id", "resolution", "format", "allow-blocking-qa-bypass"],
-        description: "Export a managed clip, optionally accepting QA warnings.",
+        usage: "blitzreels clips export --clip-id ID",
+        flags: [
+            "clip-id",
+            {
+                name: "resolution",
+                enum: ["720p", "1080p"],
+                default: "1080p",
+                hidden: true,
+            },
+            { name: "format", enum: ["mp4", "mov"], default: "mp4", hidden: true },
+        ],
+        description: "Export a managed clip that has passed QA.",
         mutates: true,
     }),
 ];
@@ -81,8 +157,40 @@ async function handleClipsCommand({ context, helpers, }) {
     const action = context.args.command[1];
     const flags = context.args.flags;
     if (action === "create") {
-        const result = await context.client.clips.create(helpers.toCreateClipOptions({ flags }));
-        helpers.printClipResult({ context, result });
+        const result = await createClipWorkflow({ context, helpers });
+        helpers.printResult({
+            json: context.json,
+            value: result,
+            human: result.output_dir === null
+                ? [
+                    `Clip batch created: ${result.batch_id}`,
+                    `Status: ${result.status}`,
+                ]
+                : [
+                    `Clips created: ${result.summary.completed}/${result.summary.requested}`,
+                    `Output: ${result.output_dir}`,
+                ],
+        });
+        return true;
+    }
+    if (action === "list") {
+        const result = await context.client.clips.list({
+            assetId: helpers.getStringFlag({ flags, name: "asset-id" }),
+            projectId: helpers.getStringFlag({ flags, name: "project-id" }),
+            status: parseClipStatus({
+                value: helpers.getStringFlag({ flags, name: "status" }),
+            }),
+            limit: helpers.getNumberFlag({ flags, name: "limit" }),
+            offset: helpers.getNumberFlag({ flags, name: "offset" }),
+        });
+        helpers.printResult({
+            json: context.json,
+            value: result,
+            human: [
+                `Returned ${result.bounds.returned}/${result.bounds.total} clip(s).`,
+                ...result.clips.map((clip) => formatClipListLine({ clip })),
+            ],
+        });
         return true;
     }
     if (action === "get") {
@@ -98,23 +206,42 @@ async function handleClipsCommand({ context, helpers, }) {
         return true;
     }
     if (action === "reselect") {
+        const clipId = helpers.requireStringFlag({ flags, name: "clip-id" });
+        const selection = helpers.buildClipSelection({ flags });
+        const target = helpers.buildClipTarget({
+            flags,
+            requireMaxDuration: false,
+        });
+        const selectionMode = helpers.getStringFlag({
+            flags,
+            name: "selection-mode",
+        });
         const result = await context.client.clips.reselect({
-            clipId: helpers.requireStringFlag({ flags, name: "clip-id" }),
-            selection: helpers.buildClipSelection({ flags }),
-            target: helpers.buildClipTarget({
-                flags,
-                requireMaxDuration: false,
-            }),
+            clipId,
+            ...(selectionMode === undefined
+                ? {
+                    suggestionId: selection.suggestionId,
+                    startSeconds: selection.startSeconds,
+                    endSeconds: selection.endSeconds,
+                    target,
+                }
+                : {
+                    selection,
+                    target,
+                }),
         });
         helpers.printClipResult({ context, result });
         return true;
     }
     if (action === "repair") {
+        const repairMode = helpers.getStringFlag({ flags, name: "repair-mode" });
         const result = await context.client.clips.repair({
             clipId: helpers.requireStringFlag({ flags, name: "clip-id" }),
-            repairMode: helpers.parseClipRepairMode({
-                value: helpers.getStringFlag({ flags, name: "repair-mode" }),
-            }),
+            ...(repairMode === undefined
+                ? {}
+                : {
+                    repairMode: helpers.parseClipRepairMode({ value: repairMode }),
+                }),
         });
         helpers.printClipResult({ context, result });
         return true;
@@ -128,53 +255,101 @@ async function handleClipsCommand({ context, helpers, }) {
             format: helpers.parseClipExportFormat({
                 value: helpers.getStringFlag({ flags, name: "format" }),
             }),
-            allowBlockingQaBypass: helpers.getOptionalBooleanFlag({
-                flags,
-                name: "allow-blocking-qa-bypass",
-            }) ?? false,
+            allowBlockingQaBypass: false,
         });
         helpers.printClipResult({ context, result });
         return true;
     }
     return false;
 }
+function parseClipStatus({ value, }) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "preparing_source" ||
+        value === "awaiting_suggestions" ||
+        value === "selecting_clip" ||
+        value === "assembling" ||
+        value === "qa_running" ||
+        value === "needs_reselection" ||
+        value === "needs_repair" ||
+        value === "ready" ||
+        value === "exporting" ||
+        value === "exported" ||
+        value === "failed") {
+        return value;
+    }
+    throw new Error(`Unsupported clip status: ${value}`);
+}
+function formatClipListLine({ clip }) {
+    const clipId = String(clip.clip_id ?? "");
+    const status = String(clip.status ?? "");
+    const nextAction = String(clip.next_action ?? "");
+    const projectId = clip.project_id === null ? "-" : String(clip.project_id);
+    const exportRecord = clip.export !== null &&
+        typeof clip.export === "object" &&
+        !Array.isArray(clip.export)
+        ? clip.export
+        : {};
+    const exportId = exportRecord.export_id === null || exportRecord.export_id === undefined
+        ? "-"
+        : String(exportRecord.export_id);
+    return `${clipId} ${status} next=${nextAction} project=${projectId} export=${exportId}`;
+}
 function buildClipsDryRun({ context, spec, helpers, }) {
     const action = context.args.command[1];
     const flags = context.args.flags;
+    if (action === "list") {
+        return helpers.dryRunRequest({
+            spec,
+            method: "GET",
+            path: "/clips",
+            query: {
+                asset_id: helpers.getStringFlag({ flags, name: "asset-id" }),
+                project_id: helpers.getStringFlag({ flags, name: "project-id" }),
+                status: helpers.getStringFlag({ flags, name: "status" }),
+                limit: helpers.getNumberFlag({ flags, name: "limit" }),
+                offset: helpers.getNumberFlag({ flags, name: "offset" }),
+            },
+            body: undefined,
+        });
+    }
     if (action === "create") {
-        const options = helpers.toCreateClipOptions({ flags });
+        const options = parseClipWorkflowOptions({ flags, helpers });
         return helpers.dryRunRequest({
             spec,
             method: "POST",
             path: "/clips",
             body: {
-                project_name: options.projectName,
                 source: {
                     source_type: options.source.sourceType,
                     asset_id: options.source.assetId,
                     youtube_url: options.source.youtubeUrl,
+                    quality: null,
                 },
-                selection: toApiClipSelection({ selection: options.selection }),
-                target: {
-                    aspect_ratio: options.target.aspectRatio,
-                    min_duration_seconds: options.target.minDurationSeconds,
-                    max_duration_seconds: options.target.maxDurationSeconds,
-                },
-                layout: {
-                    layout_mode: options.layout.mode,
-                    content_type_hint: options.layout.contentTypeHint,
-                },
-                captions: {
-                    enabled: options.captions.enabled,
-                    style_id: options.captions.styleId,
-                },
-                qa: {
-                    qa_mode: options.qa.mode,
-                },
-                export: {
-                    auto_export: options.export.autoExport,
-                },
+                clip_preset_id: options.clipPresetId,
+                caption_theme_id: options.captionThemeId,
+                create_flow_options: {},
+                branding_options: buildClipWorkflowBrandingOptions({
+                    logoAssetId: options.logoAssetId,
+                }),
             },
+            followUpRequests: options.outputDir === null
+                ? []
+                : [
+                    {
+                        reason: "Poll the batch until rendered clips have download URLs.",
+                        method: "GET",
+                        path: "/clip-batches/{batch_id}",
+                        body: undefined,
+                    },
+                ],
+            notes: [
+                options.outputDir === null
+                    ? "Queues clips through the web app batch pipeline."
+                    : `Downloads up to ${options.count} rendered clips from the web app batch pipeline.`,
+                "Caption themes, AI edit, exports, and batch status follow /dashboard/clip defaults.",
+            ],
         });
     }
     if (action === "reselect") {
@@ -183,31 +358,56 @@ function buildClipsDryRun({ context, spec, helpers, }) {
             requireMaxDuration: false,
         });
         const selection = helpers.buildClipSelection({ flags });
+        const selectionMode = helpers.getStringFlag({
+            flags,
+            name: "selection-mode",
+        });
         return helpers.dryRunRequest({
             spec,
             method: "POST",
             path: `/clips/${encodeURIComponent(helpers.requireStringFlag({ flags, name: "clip-id" }))}/reselect`,
-            body: {
-                selection: toApiClipSelection({ selection }),
-                target: target === null
-                    ? null
-                    : {
-                        min_duration_seconds: target.minDurationSeconds,
-                        max_duration_seconds: target.maxDurationSeconds,
-                    },
-            },
+            body: selectionMode === undefined
+                ? {
+                    ...(selection.suggestionId === null
+                        ? {}
+                        : { suggestion_id: selection.suggestionId }),
+                    ...(selection.startSeconds === null
+                        ? {}
+                        : { start_seconds: selection.startSeconds }),
+                    ...(selection.endSeconds === null
+                        ? {}
+                        : { end_seconds: selection.endSeconds }),
+                    ...(target === null
+                        ? {}
+                        : {
+                            target: {
+                                min_duration_seconds: target.minDurationSeconds,
+                                max_duration_seconds: target.maxDurationSeconds,
+                            },
+                        }),
+                }
+                : {
+                    selection: toApiClipSelection({ selection }),
+                    target: target === null
+                        ? null
+                        : {
+                            min_duration_seconds: target.minDurationSeconds,
+                            max_duration_seconds: target.maxDurationSeconds,
+                        },
+                },
         });
     }
     if (action === "repair") {
+        const repairMode = helpers.getStringFlag({ flags, name: "repair-mode" });
         return helpers.dryRunRequest({
             spec,
             method: "POST",
             path: `/clips/${encodeURIComponent(helpers.requireStringFlag({ flags, name: "clip-id" }))}/repair`,
-            body: {
-                repair_mode: helpers.parseClipRepairMode({
-                    value: helpers.getStringFlag({ flags, name: "repair-mode" }),
-                }),
-            },
+            body: repairMode === undefined
+                ? {}
+                : {
+                    repair_mode: helpers.parseClipRepairMode({ value: repairMode }),
+                },
         });
     }
     if (action === "export") {
@@ -222,15 +422,198 @@ function buildClipsDryRun({ context, spec, helpers, }) {
                 format: helpers.parseClipExportFormat({
                     value: helpers.getStringFlag({ flags, name: "format" }),
                 }),
-                allow_blocking_qa_bypass: helpers.getOptionalBooleanFlag({
-                    flags,
-                    name: "allow-blocking-qa-bypass",
-                }) ?? false,
+                allow_blocking_qa_bypass: false,
             },
         });
     }
     return undefined;
 }
+function parseClipWorkflowOptions({ flags, helpers, }) {
+    const count = helpers.getNumberFlag({ flags, name: "count" }) ?? 5;
+    if (!Number.isInteger(count) || count < 1 || count > 10) {
+        throw new Error("--count must be an integer between 1 and 10.");
+    }
+    const assetId = helpers.getStringFlag({ flags, name: "asset-id" }) ?? null;
+    const youtubeUrl = helpers.getStringFlag({ flags, name: "youtube-url" }) ?? null;
+    if (assetId === null && youtubeUrl === null) {
+        throw new Error("Provide --asset-id or --youtube-url.");
+    }
+    if (assetId !== null && youtubeUrl !== null) {
+        throw new Error("Use only one of --asset-id or --youtube-url.");
+    }
+    if (helpers.getOptionalBooleanFlag({ flags, name: "no-captions" }) === true) {
+        throw new Error("--no-captions is not supported. Clip batches use captions like /dashboard/clip.");
+    }
+    return {
+        source: assetId !== null
+            ? {
+                sourceType: "asset",
+                assetId,
+                youtubeUrl: null,
+            }
+            : {
+                sourceType: "youtube",
+                assetId: null,
+                youtubeUrl: youtubeUrl ?? "",
+            },
+        logoAssetId: helpers.getStringFlag({ flags, name: "logo-asset-id" }) ?? null,
+        outputDir: helpers.getStringFlag({ flags, name: "output" }) ?? null,
+        count,
+        clipPresetId: normalizeClipPresetId({
+            value: helpers.getStringFlag({ flags, name: "clip-preset-id" }) ??
+                helpers.getStringFlag({ flags, name: "preset" }) ??
+                "default",
+        }),
+        captionThemeId: parseNullableWorkflowString({
+            value: helpers.getStringFlag({ flags, name: "caption-theme-id" }),
+        }),
+        idempotencyKey: helpers.getStringFlag({ flags, name: "idempotency-key" }) ?? null,
+    };
+}
+function normalizeClipPresetId({ value }) {
+    if (value === "high-retention") {
+        return "formation-clipperz";
+    }
+    if (value === "default" ||
+        value === "formation-clipperz" ||
+        value === "demo-focus") {
+        return value;
+    }
+    throw new Error("--clip-preset-id must be default, formation-clipperz, high-retention, or demo-focus.");
+}
+function parseNullableWorkflowString({ value, }) {
+    if (value === undefined || value === "null") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+async function createClipWorkflow({ context, helpers, }) {
+    const options = parseClipWorkflowOptions({
+        flags: context.args.flags,
+        helpers,
+    });
+    const created = await context.client.clips.create({
+        source: {
+            sourceType: options.source.sourceType,
+            assetId: options.source.assetId,
+            youtubeUrl: options.source.youtubeUrl,
+            quality: null,
+        },
+        clipPresetId: options.clipPresetId,
+        captionThemeId: options.captionThemeId,
+        createFlowOptions: {},
+        brandingOptions: buildClipWorkflowBrandingOptions({
+            logoAssetId: options.logoAssetId,
+        }),
+        idempotencyKey: options.idempotencyKey ?? undefined,
+    });
+    if (options.outputDir === null) {
+        return {
+            operation: "clips.create",
+            batch_id: created.batch.batch_id,
+            status: created.batch.status,
+            preset: options.clipPresetId,
+            caption_theme_id: options.captionThemeId,
+            output_dir: null,
+            summary: {
+                requested: options.count,
+                completed: created.batch.rendered_count,
+            },
+            clips: [],
+        };
+    }
+    const outputDir = resolve(options.outputDir);
+    await mkdir(outputDir, { recursive: true });
+    const readyBatch = await waitForClipBatchEnvelope({
+        context,
+        helpers,
+        batchId: created.batch.batch_id,
+    });
+    const renderedClips = readyBatch.batch.clips
+        .filter((clip) => clip.status === "rendered" && clip.download_url !== null)
+        .slice(0, options.count);
+    if (renderedClips.length === 0) {
+        throw new Error("Clip batch completed without rendered clips to download.");
+    }
+    const receipts = [];
+    for (let index = 0; index < renderedClips.length; index++) {
+        const clip = renderedClips[index];
+        if (clip === undefined || clip.download_url === null) {
+            continue;
+        }
+        const bytes = await downloadSignedClip({
+            url: clip.download_url,
+        });
+        const outputPath = join(outputDir, `${String(index + 1).padStart(2, "0")}-${slugifyFileName({
+            value: clip.title,
+        })}.mp4`);
+        await writeFile(outputPath, Buffer.from(bytes));
+        receipts.push({
+            clip_id: clip.clip_id,
+            project_id: clip.project_id,
+            suggestion_id: clip.suggestion_id,
+            export_id: clip.export_id,
+            output_path: outputPath,
+        });
+    }
+    return {
+        operation: "clips.create",
+        batch_id: readyBatch.batch.batch_id,
+        status: readyBatch.batch.status,
+        preset: options.clipPresetId,
+        caption_theme_id: options.captionThemeId,
+        output_dir: outputDir,
+        summary: {
+            requested: options.count,
+            completed: receipts.length,
+        },
+        clips: receipts,
+    };
+}
+async function waitForClipBatchEnvelope({ context, helpers, batchId, }) {
+    const timeoutMs = helpers.getNumberFlag({ flags: context.args.flags, name: "timeout-ms" }) ??
+        1_800_000;
+    const intervalMs = helpers.getNumberFlag({ flags: context.args.flags, name: "interval-ms" }) ??
+        5_000;
+    const startedAt = Date.now();
+    while (true) {
+        const batch = await context.client.clipBatches.get({ batchId });
+        if (batch.batch.status === "completed" ||
+            batch.batch.status === "completed_with_errors" ||
+            batch.batch.status === "failed") {
+            return batch;
+        }
+        if (Date.now() - startedAt > timeoutMs) {
+            throw new Error(`Timed out waiting for clip batch ${batchId}.`);
+        }
+        await new Promise((resolvePromise) => {
+            setTimeout(resolvePromise, intervalMs);
+        });
+    }
+}
+function buildClipWorkflowBrandingOptions({ logoAssetId, }) {
+    return {
+        logoOverlayEnabled: logoAssetId !== null,
+        logoMediaAssetId: logoAssetId,
+        logoPosition: "top-right",
+    };
+}
+async function downloadSignedClip({ url, }) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Download failed with ${response.status}.`);
+    }
+    return response.arrayBuffer();
+}
+function slugifyFileName({ value }) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 56);
+    return slug.length > 0 ? slug : "clip";
+}
 function toApiClipSelection({ selection, }) {
     return {
         selection_mode: selection.mode,