diff --git a/README.md b/README.md index d92a9f4..2a01440 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![npm](https://img.shields.io/npm/v/pixelvault-cli)](https://www.npmjs.com/package/pixelvault-cli) [![CI](https://github.com/pixelvault-dev/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/pixelvault-dev/cli/actions/workflows/ci.yml) -CLI for [PixelVault](https://pixelvault.dev) — agent-first image, PDF, and video hosting for developers and AI coding agents. +CLI for [PixelVault](https://pixelvault.dev) — agent-first media hosting for developers and AI coding agents. ## Install @@ -54,6 +54,12 @@ pixelvault upload demo.mp4 --social # Convert an existing hosted video pixelvault optimize-video vid_xyz +# Upload a local MP4, enrich it, wait, and print original/transcript/storyboard URLs +pixelvault enrich-video demo.mp4 + +# Resume the same server job without uploading again +pixelvault enrich-video vid_xyz + # List your images pixelvault list @@ -84,6 +90,7 @@ The CLI is designed for AI coding agents. Output contract: - `upload` prints **only the URL** to stdout for images, PDFs, and MP4 videos. PDFs are served as forced downloads and do not support image transforms. Add `--optimized` for the smaller WebP/AVIF image variant; it falls back to the original URL for SVG, GIF, PDF, and private images - `upload` streams local MP4 files and automatically switches to multipart upload above 100 MB. It also accepts public MP4 URLs and has PixelVault import them directly. `--private [--expires 12h]` returns signed video and poster URLs. `--social` requests a separate H.264/AAC fast-start copy, waits for it, and prints the post-ready URL while preserving the original; `--json` returns both `original_url` and `social_ready_url`. Every video response includes duration, dimensions, codecs, fast-start status, and social-compatibility warnings. Video limits: Free 25 MB, Starter 100 MB, Pro 250 MB - `optimize-video` converts an existing upload, waits for the derived social-ready URL, and prints only that URL; `--no-wait` enqueues and returns, while `--json` returns the full state +- `enrich-video` uploads a local MP4 or reuses an existing `vid_` asset, starts or resumes transcript + storyboard enrichment, and reports the stable asset/job IDs before bounded polling - Image and PDF uploads support `--idempotency-key` and `--dedupe`; folder, image optimization, reuse, metadata, and AI-description options are rejected for MP4 files and URLs - `list` outputs one URL per line - `meta` prints the stored metadata as JSON @@ -119,6 +126,7 @@ npx pixelvault-cli upload build-output.png | `describe ` | Write an AI description (alt text, caption, OCR, tags) for an image you already uploaded | | `optimize ` | Compress images locally — no account needed (resize, convert, strip metadata; never writes a bigger file) | | `optimize-video ` | Preserve a hosted MP4 and create a social-ready H.264/AAC fast-start copy | +| `enrich-video ` | Upload or resume transcript + storyboard enrichment, with bounded polling and structured artifact access data | | `get ` | Get an image's URL/metadata, or download it (optionally transformed) | | `meta ` | Replace an image's custom metadata (`--meta k=v`, `--metadata ''`, or `--clear`) | | `delete ` | Delete an image | @@ -174,6 +182,37 @@ an already-compatible original is returned unchanged, a running job is reused, and a completed derivative is returned without another conversion. Failed jobs refund their reserved seconds. +### Video Enrichment Options + +```bash +pixelvault enrich-video demo.mp4 # upload + enrich + wait +pixelvault enrich-video demo.mp4 --private # private original and signed artifacts +pixelvault enrich-video demo.mp4 --no-wait --json +pixelvault enrich-video vid_xyz # resume/reuse an existing job +pixelvault enrich-video vid_xyz --timeout 1200 --json +``` + +The command accepts a local MP4 or an existing PixelVault video asset ID. URL +sources are intentionally rejected: import one with `pixelvault upload +--json`, then pass the returned `vid_` ID. Enrichment accepts sources from 1 +second through 10 minutes and at most 100 MB. It is idempotent while queued, +running, or complete; retrying a failed job creates a new job ID. + +Polling backs off from one to ten seconds and stops after 600 seconds by default +(`--timeout` changes the local bound). A timeout exits non-zero but does not +cancel the server job; rerun the printed resume command. `--no-wait` returns the +queued/running state immediately. Human output keeps URLs on stdout and progress, +asset/job IDs, artifact types, visibility, and signed-link expiry on stderr. +`--json` returns one object with `asset_id`, `job_id`, explicit state, +`resume_command`, and only the artifact URLs that currently exist. Private +artifacts inherit the video's privacy; the command never changes an existing +asset's visibility. + +Videos without audio return a skipped transcript and still produce a storyboard. +Quota, duration, size, unavailable-metadata, failed-job, and local-timeout states +exit explicitly. Monthly source minutes are Free 2, Starter 30, and Pro 120; +check `pixelvault usage` for the current allowance and reset. + ### Generate Options ```bash @@ -352,7 +391,7 @@ pixelvault config get api_key # Get a value ## Learn more -- [PixelVault](https://pixelvault.dev) — agent-first image hosting +- [PixelVault](https://pixelvault.dev) — agent-first media hosting - [API docs](https://pixelvault.dev/docs/) — full REST reference + OpenAPI 3.1 - [Guide: Image hosting for AI agents](https://pixelvault.dev/blog/image-hosting-for-ai-agents/) - [The simplest image hosting API](https://pixelvault.dev/image-hosting-api/) diff --git a/package-lock.json b/package-lock.json index 10f77b1..34aa3d8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "pixelvault-cli", - "version": "0.22.0", + "version": "0.23.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "pixelvault-cli", - "version": "0.22.0", + "version": "0.23.0", "license": "MIT", "dependencies": { "citty": "^0.1.6" diff --git a/package.json b/package.json index 00ad4fb..fb1f734 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "pixelvault-cli", - "version": "0.22.0", - "description": "CLI for PixelVault — agent-first image, PDF, and video hosting", + "version": "0.23.0", + "description": "CLI for PixelVault — agent-first media hosting for images, PDFs, and video", "type": "module", "bin": { "pixelvault": "bin/pixelvault.mjs" diff --git a/src/commands/enrich-video.ts b/src/commands/enrich-video.ts new file mode 100644 index 0000000..56f53b7 --- /dev/null +++ b/src/commands/enrich-video.ts @@ -0,0 +1,226 @@ +import { existsSync } from "node:fs"; +import { extname } from "node:path"; +import { defineCommand } from "citty"; +import { ApiRequestError, apiRequest } from "../lib/client.js"; +import { requireApiKey } from "../lib/config.js"; +import { parseExpires } from "../lib/duration.js"; +import { CliError } from "../lib/errors.js"; +import { + enrichmentState, + videoArtifacts, + waitForVideoEnrichment, + type VideoArtifact, +} from "../lib/video-enrichment.js"; +import { jsonOut, stderr, stdout } from "../lib/output.js"; +import { + isRemoteVideoUrl, + uploadVideoFile, + type VideoData, + type VideoEnrichmentStatus, +} from "../lib/video-upload.js"; + +const DEFAULT_TIMEOUT_SECONDS = 600; + +function isVideoId(value: string): boolean { + return /^vid_[A-Za-z0-9_-]+$/.test(value); +} + +function timeoutMilliseconds(value: unknown): number { + const seconds = Number(value ?? DEFAULT_TIMEOUT_SECONDS); + if (!Number.isFinite(seconds) || seconds <= 0) { + throw new CliError("--timeout must be a positive number of seconds."); + } + return Math.ceil(seconds * 1_000); +} + +function startError(error: unknown, assetId: string): CliError { + const resume = `Re-run pixelvault enrich-video ${assetId}; active or completed jobs are reused.`; + if (!(error instanceof ApiRequestError)) { + const message = error instanceof Error ? error.message : String(error); + return new CliError(`${message} The uploaded asset is preserved. ${resume}`); + } + + switch (error.code) { + case "enrichment_limit_reached": + return new CliError(`${error.message} Check pixelvault usage for the reset date or plan allowance.`); + case "enrichment_source_too_large": + return new CliError(`${error.message} The original video remains hosted as ${assetId}.`); + case "enrichment_duration_too_long": + case "video_duration_unavailable": + return new CliError(`${error.message} Enrichment supports MP4 sources from 1 second through 10 minutes.`); + case "video_metadata_unavailable": + return new CliError(`${error.message} The original video remains hosted as ${assetId}.`); + default: + return new CliError(`${error.message} The uploaded asset is preserved. ${resume}`); + } +} + +function accessLabel(artifact: VideoArtifact): string { + if (artifact.signed_url_expiry.status === "known") { + return `private; signed URL expires ${artifact.signed_url_expiry.expires_at}`; + } + if (artifact.signed_url_expiry.status === "unknown") { + return "private; signed URL expiry was not reported"; + } + return "public; no signed-URL expiry"; +} + +function printReadable(artifacts: VideoArtifact[]): void { + for (const artifact of artifacts) { + const sheet = artifact.sheet_index === undefined ? "" : `[${artifact.sheet_index}]`; + stderr(`${artifact.type}${sheet} (${accessLabel(artifact)}): ${artifact.url}`); + stdout(artifact.url); + } +} + +function statusLabel(status: VideoEnrichmentStatus): string { + if (status === "pending") return "queued"; + if (status === "processing") return "running"; + return status; +} + +export default defineCommand({ + meta: { + name: "enrich-video", + description: "Upload or resume an MP4 transcript + storyboard job", + }, + args: { + source: { + type: "positional", + description: "Local .mp4 path or existing PixelVault video ID (vid_...)", + required: true, + }, + private: { + type: "boolean", + description: "Upload a local MP4 privately; generated artifacts inherit privacy", + default: false, + }, + expires: { + type: "string", + description: "Signed-link lifetime for a new private upload (for example 12h or 7d)", + }, + wait: { + type: "boolean", + description: "Wait for a terminal enrichment state", + default: true, + }, + timeout: { + type: "string", + description: `Maximum seconds to wait locally (default: ${DEFAULT_TIMEOUT_SECONDS})`, + default: String(DEFAULT_TIMEOUT_SECONDS), + }, + json: { + type: "boolean", + description: "Output structured asset, job, state, access, and artifact data as JSON", + default: false, + }, + }, + async run({ args }) { + const apiKey = requireApiKey(); + const source = String(args.source); + const existingAsset = isVideoId(source); + + if (isRemoteVideoUrl(source)) { + throw new CliError( + "enrich-video accepts a local MP4 or an existing vid_ asset ID, not a URL. " + + "Import it first with pixelvault upload --json, then pass the returned video ID.", + ); + } + if (!existingAsset && extname(source).toLowerCase() !== ".mp4") { + throw new CliError("enrich-video accepts only a local .mp4 path or an existing vid_ asset ID."); + } + if (!existingAsset && !existsSync(source)) { + throw new CliError(`Video file not found: ${source}`); + } + if (existingAsset && (args.private || args.expires !== undefined)) { + throw new CliError( + "--private and --expires apply only when enrich-video uploads a local MP4. " + + "An existing asset keeps its current visibility.", + ); + } + if (args.expires !== undefined && !args.private) { + throw new CliError("--expires requires --private and controls signed-link expiry, not asset deletion."); + } + + const timeoutMs = timeoutMilliseconds(args.timeout); + const signExpiresIn = args.private ? parseExpires(String(args.expires ?? "7d")) : null; + let assetId = source; + + if (!existingAsset) { + const uploaded = await uploadVideoFile(source, apiKey, { + private: Boolean(args.private), + signExpiresIn, + }); + if (args.private && uploaded.visibility !== "private") { + throw new CliError("The API did not confirm private visibility; refusing to continue."); + } + assetId = uploaded.id; + stderr(`Uploaded video asset ${assetId}. Original: ${uploaded.original_url}`); + } else { + stderr(`Using existing video asset ${assetId}.`); + } + stderr(`Resume safely with: pixelvault enrich-video ${assetId}`); + + let video: VideoData; + try { + ({ data: video } = await apiRequest<{ data: VideoData }>({ + method: "POST", + path: `/v1/videos/${encodeURIComponent(assetId)}/enrich`, + auth: apiKey, + })); + } catch (error) { + throw startError(error, assetId); + } + + const jobId = video.enrichment.job_id; + if (jobId) { + stderr(`Enrichment job ${jobId}: ${statusLabel(video.enrichment.status)}.`); + } else { + stderr(`Enrichment ${statusLabel(video.enrichment.status)}; resume with asset ID ${assetId}.`); + } + + let timedOut = false; + if (args.wait && (video.enrichment.status === "pending" || video.enrichment.status === "processing")) { + const result = await waitForVideoEnrichment(video, apiKey, { + timeoutMs, + onStatus(status) { + stderr(`Enrichment ${statusLabel(status)} (${video.enrichment.job_id ?? assetId}).`); + }, + }); + video = result.video; + timedOut = result.timedOut; + } + + const artifacts = videoArtifacts(video); + const output = { + asset_id: video.id, + ...(video.enrichment.job_id ? { job_id: video.enrichment.job_id } : {}), + state: enrichmentState(video.enrichment.status, timedOut), + server_status: video.enrichment.status, + resume_command: `pixelvault enrich-video ${video.id}`, + visibility: video.visibility, + artifacts, + enrichment: video.enrichment, + }; + + if (args.json) jsonOut(output); + else printReadable(artifacts); + + if (timedOut) { + throw new CliError( + `Timed out after ${Number(args.timeout)}s while job ${video.enrichment.job_id ?? "(ID unavailable)"} ` + + `was ${statusLabel(video.enrichment.status)}. The server job was not cancelled. ` + + `Resume with pixelvault enrich-video ${video.id}.`, + ); + } + if (video.enrichment.status === "failed") { + throw new CliError( + `Enrichment job ${video.enrichment.job_id ?? "(ID unavailable)"} failed: ` + + (video.enrichment.error?.message ?? "The video could not be enriched."), + ); + } + if (video.enrichment.status === "not_requested") { + throw new CliError(`The server did not start an enrichment job. Retry with pixelvault enrich-video ${video.id}.`); + } + }, +}); diff --git a/src/index.ts b/src/index.ts index c0fb1b1..66a13f9 100644 --- a/src/index.ts +++ b/src/index.ts @@ -6,7 +6,7 @@ const main = defineCommand({ meta: { name: "pixelvault", version: VERSION, - description: "CLI for PixelVault — agent-first image, PDF, and video hosting", + description: "CLI for PixelVault — agent-first media hosting", }, subCommands: { register: () => import("./commands/register.js").then((m) => m.default), @@ -18,6 +18,7 @@ const main = defineCommand({ describe: () => import("./commands/describe.js").then((m) => m.default), optimize: () => import("./commands/optimize.js").then((m) => m.default), "optimize-video": () => import("./commands/optimize-video.js").then((m) => m.default), + "enrich-video": () => import("./commands/enrich-video.js").then((m) => m.default), get: () => import("./commands/get.js").then((m) => m.default), meta: () => import("./commands/meta.js").then((m) => m.default), delete: () => import("./commands/delete.js").then((m) => m.default), diff --git a/src/lib/client.ts b/src/lib/client.ts index 9dd30f1..92b95ad 100644 --- a/src/lib/client.ts +++ b/src/lib/client.ts @@ -18,7 +18,7 @@ interface ApiError { // this channel (server reads X-PixelVault-Client at register/device-login — see // pixelvault docs/specs/lead-attribution.md). Keep the version in sync with // package.json on release (tests/lib/version.test.ts fails if they drift). -export const VERSION = "0.22.0"; +export const VERSION = "0.23.0"; const CLIENT_ID = `pixelvault-cli/${VERSION}`; /** CliError carrying the API's machine-readable error details. */ diff --git a/src/lib/video-enrichment.ts b/src/lib/video-enrichment.ts new file mode 100644 index 0000000..2e5cac9 --- /dev/null +++ b/src/lib/video-enrichment.ts @@ -0,0 +1,134 @@ +import { setTimeout as delay } from "node:timers/promises"; +import type { VideoData, VideoEnrichmentStatus } from "./video-upload.js"; +import { getVideo } from "./video-optimization.js"; + +const INITIAL_POLL_DELAY_MS = 1_000; +const MAX_POLL_DELAY_MS = 10_000; + +export type EnrichmentState = "not_started" | "queued" | "running" | "complete" | "failed" | "timeout"; + +export type VideoArtifactType = + | "original_video" + | "transcript_text" + | "transcript_vtt" + | "transcript_segments" + | "storyboard_index" + | "storyboard_sheet"; + +export type SignedUrlExpiry = + | { status: "not_applicable" } + | { status: "known"; expires_at: string } + | { status: "unknown" }; + +export interface VideoArtifact { + type: VideoArtifactType; + url: string; + visibility: "public" | "private"; + signed_url_expiry: SignedUrlExpiry; + sheet_index?: number; +} + +export interface WaitForVideoEnrichmentResult { + video: VideoData; + timedOut: boolean; +} + +interface WaitForVideoEnrichmentOptions { + timeoutMs: number; + sleep?: (milliseconds: number) => Promise; + now?: () => number; + fetchVideo?: (id: string, apiKey: string) => Promise; + onStatus?: (status: VideoEnrichmentStatus) => void; +} + +function isActive(status: VideoEnrichmentStatus): boolean { + return status === "pending" || status === "processing"; +} + +export function enrichmentState( + status: VideoEnrichmentStatus, + timedOut = false, +): EnrichmentState { + if (timedOut) return "timeout"; + if (status === "pending") return "queued"; + if (status === "processing") return "running"; + if (status === "not_requested") return "not_started"; + return status; +} + +export async function waitForVideoEnrichment( + initial: VideoData, + apiKey: string, + options: WaitForVideoEnrichmentOptions, +): Promise { + const sleep = options.sleep ?? delay; + const now = options.now ?? Date.now; + const fetchVideo = options.fetchVideo ?? getVideo; + const deadline = now() + options.timeoutMs; + let pollDelayMs = INITIAL_POLL_DELAY_MS; + let video = initial; + let previousStatus = video.enrichment.status; + + while (isActive(video.enrichment.status)) { + const remainingMs = deadline - now(); + if (remainingMs <= 0) return { video, timedOut: true }; + + await sleep(Math.min(pollDelayMs, remainingMs)); + video = await fetchVideo(video.id, apiKey); + if (video.enrichment.status !== previousStatus) { + previousStatus = video.enrichment.status; + options.onStatus?.(previousStatus); + } + pollDelayMs = Math.min(Math.ceil(pollDelayMs * 1.5), MAX_POLL_DELAY_MS); + } + + return { video, timedOut: false }; +} + +function signedUrlExpiry(video: VideoData): SignedUrlExpiry { + if (video.visibility === "public") return { status: "not_applicable" }; + if (video.signed_expires === undefined || !Number.isFinite(video.signed_expires)) { + return { status: "unknown" }; + } + return { + status: "known", + expires_at: new Date(video.signed_expires * 1_000).toISOString(), + }; +} + +export function videoArtifacts(video: VideoData): VideoArtifact[] { + const artifacts: VideoArtifact[] = []; + const signed_url_expiry = signedUrlExpiry(video); + const common = { visibility: video.visibility, signed_url_expiry }; + artifacts.push({ type: "original_video", url: video.original_url, ...common }); + + const transcript = video.enrichment.transcript; + if (transcript?.status === "complete") { + if (transcript.text_url) { + artifacts.push({ type: "transcript_text", url: transcript.text_url, ...common }); + } + if (transcript.vtt_url) { + artifacts.push({ type: "transcript_vtt", url: transcript.vtt_url, ...common }); + } + if (transcript.segments_url) { + artifacts.push({ type: "transcript_segments", url: transcript.segments_url, ...common }); + } + } + + const storyboard = video.enrichment.storyboard; + if (storyboard?.index_url) { + artifacts.push({ type: "storyboard_index", url: storyboard.index_url, ...common }); + } + for (const [sheet_index, sheet] of (storyboard?.sheets ?? []).entries()) { + if (sheet.url) { + artifacts.push({ + type: "storyboard_sheet", + url: sheet.url, + sheet_index, + ...common, + }); + } + } + + return artifacts; +} diff --git a/src/lib/video-upload.ts b/src/lib/video-upload.ts index 7a9abab..79f82e4 100644 --- a/src/lib/video-upload.ts +++ b/src/lib/video-upload.ts @@ -15,6 +15,43 @@ export interface VideoSocialOptimization { error?: { code: string; message: string }; } +export type VideoEnrichmentStatus = + | "not_requested" + | "pending" + | "processing" + | "complete" + | "failed"; + +export interface VideoEnrichment { + job_id?: string; + status: VideoEnrichmentStatus; + requested_at?: string; + completed_at?: string | null; + transcript?: { + status: "complete" | "skipped"; + text_url?: string; + vtt_url?: string; + segments_url?: string; + language?: string | null; + languages?: string[]; + model?: string | null; + segment_count?: number; + reason?: "no_audio"; + }; + storyboard?: { + status: "complete"; + index_url?: string; + frame_count: number; + sheets: { + url?: string; + start_seconds: number; + end_seconds: number; + frame_count: number; + }[]; + } | null; + error?: { code: string; message: string }; +} + export interface VideoData { id: string; kind: "video"; @@ -38,6 +75,7 @@ export interface VideoData { social_compatible: boolean | null; compatibility_warnings: { code: string; message: string }[]; social_optimization: VideoSocialOptimization; + enrichment: VideoEnrichment; } interface UploadSession { diff --git a/tests/commands/enrich-video.test.ts b/tests/commands/enrich-video.test.ts new file mode 100644 index 0000000..eaac6b0 --- /dev/null +++ b/tests/commands/enrich-video.test.ts @@ -0,0 +1,213 @@ +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import type { VideoData, VideoEnrichmentStatus } from "../../src/lib/video-upload.js"; + +vi.mock("../../src/lib/config.js", () => ({ + requireApiKey: () => "pv_live_test", + getApiUrl: () => "https://api.test.pixelvault.dev", +})); + +const originalFetch = globalThis.fetch; +const temporaryDirectories: string[] = []; + +afterEach(() => { + globalThis.fetch = originalFetch; + vi.useRealTimers(); + vi.restoreAllMocks(); + for (const directory of temporaryDirectories.splice(0)) { + rmSync(directory, { recursive: true, force: true }); + } +}); + +function video(status: VideoEnrichmentStatus, visibility: "public" | "private" = "public"): VideoData { + return { + id: "vid_1", + kind: "video", + url: "https://img.pixelvault.dev/proj_1/vid_1.mp4", + original_url: "https://img.pixelvault.dev/proj_1/vid_1.mp4", + visibility, + mime_type: "video/mp4", + size: 1_000, + filename: "clip.mp4", + created_at: "2026-11-16T10:00:00.000Z", + signed_expires: visibility === "private" ? 1_795_000_000 : undefined, + width: 640, + height: 360, + duration_seconds: 12, + video_codec: "h264", + audio_codec: "aac", + has_audio: true, + fast_start: true, + social_compatible: true, + compatibility_warnings: [], + social_optimization: { preset: "social", status: "not_requested" }, + enrichment: { job_id: "ven_1", status }, + }; +} + +interface FakeResponse { + status?: number; + body: unknown; +} + +function fakeApi(responses: FakeResponse[]) { + const calls: { url: string; init: RequestInit }[] = []; + globalThis.fetch = vi.fn(async (url: string | URL | Request, init: RequestInit = {}) => { + calls.push({ url: String(url), init }); + const response = responses.shift(); + if (!response) throw new Error("Unexpected API request"); + return new Response(JSON.stringify(response.body), { + status: response.status ?? 200, + headers: { "Content-Type": "application/json" }, + }); + }) as typeof fetch; + const out = vi.spyOn(process.stdout, "write").mockImplementation(() => true); + const err = vi.spyOn(process.stderr, "write").mockImplementation(() => true); + return { + calls, + stdout: () => out.mock.calls.map((call) => String(call[0])).join(""), + stderr: () => err.mock.calls.map((call) => String(call[0])).join(""), + }; +} + +async function run(args: Record) { + const { default: command } = await import("../../src/commands/enrich-video.js"); + const runnable = command as unknown as { + run(context: { args: Record }): Promise; + }; + await runnable.run({ + args: { + source: "vid_1", + private: false, + wait: true, + timeout: "600", + json: false, + ...args, + }, + }); +} + +describe("enrich-video command", () => { + it("returns typed private artifacts and stable resume identifiers as JSON", async () => { + const complete = video("complete", "private"); + complete.original_url = "https://img.pixelvault.dev/private/original?token=one"; + complete.enrichment.transcript = { + status: "complete", + text_url: "https://img.pixelvault.dev/private/transcript.txt?token=two", + }; + complete.enrichment.storyboard = { + status: "complete", + index_url: "https://img.pixelvault.dev/private/storyboard.json?token=three", + frame_count: 1, + sheets: [], + }; + const api = fakeApi([{ body: { data: complete } }]); + + await run({ json: true }); + + expect(api.calls[0].url).toBe("https://api.test.pixelvault.dev/v1/videos/vid_1/enrich"); + expect(api.calls[0].init.method).toBe("POST"); + expect(JSON.parse(api.stdout())).toMatchObject({ + asset_id: "vid_1", + job_id: "ven_1", + state: "complete", + server_status: "complete", + resume_command: "pixelvault enrich-video vid_1", + artifacts: [ + { type: "original_video", visibility: "private", signed_url_expiry: { status: "known" } }, + { type: "transcript_text", visibility: "private", signed_url_expiry: { status: "known" } }, + { type: "storyboard_index", visibility: "private", signed_url_expiry: { status: "known" } }, + ], + }); + expect(api.stderr()).toContain("Using existing video asset vid_1"); + expect(api.stderr()).toContain("Enrichment job ven_1: complete"); + }); + + it("uploads a local MP4 once and exposes IDs before returning the queued state", async () => { + const directory = mkdtempSync(join(tmpdir(), "pixelvault-enrich-")); + temporaryDirectories.push(directory); + const file = join(directory, "clip.mp4"); + writeFileSync(file, Buffer.from("small-fixture")); + const uploaded = video("not_requested"); + const queued = video("pending"); + const api = fakeApi([ + { status: 201, body: { data: uploaded } }, + { status: 202, body: { data: queued } }, + ]); + + await run({ source: file, wait: false, json: true }); + + expect(api.calls.map(({ url }) => url)).toEqual([ + "https://api.test.pixelvault.dev/v1/videos", + "https://api.test.pixelvault.dev/v1/videos/vid_1/enrich", + ]); + expect(JSON.parse(api.stdout())).toMatchObject({ + asset_id: "vid_1", + job_id: "ven_1", + state: "queued", + artifacts: [{ type: "original_video" }], + }); + expect(api.stderr()).toContain("Uploaded video asset vid_1"); + expect(api.stderr()).toContain("Resume safely with: pixelvault enrich-video vid_1"); + expect(api.stderr()).toContain("Enrichment job ven_1: queued"); + }); + + it("reports failed jobs as structured output and exits non-zero", async () => { + const failed = video("failed"); + failed.enrichment.error = { code: "storyboard_failed", message: "Storyboard generation failed." }; + const api = fakeApi([{ body: { data: failed } }]); + + await expect(run({ json: true })).rejects.toThrow("Storyboard generation failed"); + expect(JSON.parse(api.stdout())).toMatchObject({ + asset_id: "vid_1", + job_id: "ven_1", + state: "failed", + artifacts: [{ type: "original_video" }], + }); + }); + + it("times out locally without claiming the server job was cancelled", async () => { + vi.useFakeTimers(); + const api = fakeApi([ + { status: 202, body: { data: video("pending") } }, + { body: { data: video("processing") } }, + ]); + + const pending = run({ timeout: "0.001", json: true }); + await vi.advanceTimersByTimeAsync(2); + await expect(pending).rejects.toThrow("server job was not cancelled"); + expect(JSON.parse(api.stdout())).toMatchObject({ + asset_id: "vid_1", + job_id: "ven_1", + state: "timeout", + server_status: "processing", + }); + }); + + it("explains quota failures without retrying or losing the asset ID", async () => { + const api = fakeApi([{ + status: 402, + body: { + error: { + code: "enrichment_limit_reached", + message: "Monthly video enrichment limit reached (2 minutes on free).", + }, + }, + }]); + + await expect(run({})).rejects.toThrow("Check pixelvault usage for the reset date"); + expect(api.calls).toHaveLength(1); + expect(api.stderr()).toContain("Resume safely with: pixelvault enrich-video vid_1"); + }); + + it("rejects URL and non-MP4 sources before any upload", async () => { + const api = fakeApi([]); + await expect(run({ source: "https://example.com/clip.mp4" })).rejects.toThrow( + "Import it first with pixelvault upload", + ); + await expect(run({ source: "clip.mov" })).rejects.toThrow("local .mp4 path"); + expect(api.calls).toHaveLength(0); + }); +}); diff --git a/tests/lib/video-enrichment.test.ts b/tests/lib/video-enrichment.test.ts new file mode 100644 index 0000000..b3202ba --- /dev/null +++ b/tests/lib/video-enrichment.test.ts @@ -0,0 +1,119 @@ +import { describe, expect, it } from "vitest"; +import { + enrichmentState, + videoArtifacts, + waitForVideoEnrichment, +} from "../../src/lib/video-enrichment.js"; +import type { VideoData, VideoEnrichmentStatus } from "../../src/lib/video-upload.js"; + +function video(status: VideoEnrichmentStatus): VideoData { + return { + id: "vid_1", + kind: "video", + url: "https://img.pixelvault.dev/proj_1/vid_1.mp4", + original_url: "https://img.pixelvault.dev/proj_1/vid_1.mp4", + visibility: "public", + mime_type: "video/mp4", + size: 1_000, + filename: "clip.mp4", + created_at: "2026-11-16T10:00:00.000Z", + width: 640, + height: 360, + duration_seconds: 12, + video_codec: "h264", + audio_codec: "aac", + has_audio: true, + fast_start: true, + social_compatible: true, + compatibility_warnings: [], + social_optimization: { preset: "social", status: "not_requested" }, + enrichment: { job_id: "ven_1", status }, + }; +} + +describe("waitForVideoEnrichment", () => { + it("backs off while queued/running and stops at completion", async () => { + let now = 0; + const waits: number[] = []; + const statuses: VideoEnrichmentStatus[] = []; + const responses = [video("processing"), video("complete")]; + + const result = await waitForVideoEnrichment(video("pending"), "pv_live_test", { + timeoutMs: 10_000, + now: () => now, + sleep: async (milliseconds) => { + waits.push(milliseconds); + now += milliseconds; + }, + fetchVideo: async () => responses.shift()!, + onStatus: (status) => statuses.push(status), + }); + + expect(result).toEqual({ video: expect.objectContaining({ enrichment: { job_id: "ven_1", status: "complete" } }), timedOut: false }); + expect(waits).toEqual([1_000, 1_500]); + expect(statuses).toEqual(["processing", "complete"]); + }); + + it("returns the last server state when the local deadline expires", async () => { + let now = 0; + const waits: number[] = []; + const result = await waitForVideoEnrichment(video("pending"), "pv_live_test", { + timeoutMs: 1_200, + now: () => now, + sleep: async (milliseconds) => { + waits.push(milliseconds); + now += milliseconds; + }, + fetchVideo: async () => video("processing"), + }); + + expect(result.timedOut).toBe(true); + expect(result.video.enrichment.status).toBe("processing"); + expect(waits).toEqual([1_000, 200]); + expect(enrichmentState(result.video.enrichment.status, true)).toBe("timeout"); + }); +}); + +describe("videoArtifacts", () => { + it("returns only existing URLs with inherited privacy and exact signed expiry", () => { + const complete = video("complete"); + complete.visibility = "private"; + complete.signed_expires = 1_795_000_000; + complete.original_url = "https://img.pixelvault.dev/private/original?token=one"; + complete.enrichment.transcript = { + status: "complete", + text_url: "https://img.pixelvault.dev/private/transcript.txt?token=two", + vtt_url: "https://img.pixelvault.dev/private/transcript.vtt?token=three", + }; + complete.enrichment.storyboard = { + status: "complete", + index_url: "https://img.pixelvault.dev/private/storyboard.json?token=four", + frame_count: 2, + sheets: [ + { + url: "https://img.pixelvault.dev/private/sheet-0.jpg?token=five", + start_seconds: 0, + end_seconds: 12, + frame_count: 2, + }, + ], + }; + + const artifacts = videoArtifacts(complete); + expect(artifacts.map(({ type }) => type)).toEqual([ + "original_video", + "transcript_text", + "transcript_vtt", + "storyboard_index", + "storyboard_sheet", + ]); + expect(artifacts).not.toEqual(expect.arrayContaining([ + expect.objectContaining({ type: "transcript_segments" }), + ])); + expect(artifacts.every(({ visibility }) => visibility === "private")).toBe(true); + expect(artifacts[0].signed_url_expiry).toEqual({ + status: "known", + expires_at: new Date(1_795_000_000_000).toISOString(), + }); + }); +});