@clipwright/core 0.33.0 → 0.34.0

package/dist/assets.d.ts

@@ -1,7 +1,8 @@
 import { z } from "zod";
-/** Account assets (clipwright#724 F2): pictures kept until the customer deletes them, under a cap per account. */
+import { ASSET_KINDS, ASSET_MEDIA_TYPES, assetId } from "./asset-identity.js";
+/** Account assets (clipwright#724 F2): pictures and clips kept until the customer deletes them, under a cap per account. */
 export declare const ASSETS_PATH = "/v1/assets";
-/** Raw bytes of one picture, for the cabinet; role, name and the rights confirmation travel in the query. */
+/** Raw bytes of one picture or clip, for the cabinet; role, name and the rights confirmation travel in the query. */
 export declare const ASSET_BYTES_PATH = "/v1/assets/bytes";
 export declare const ASSET_ITEM_PATH = "/v1/assets/:id";
 export declare const ASSET_ACCOUNT_MAX_COUNT = 2000;
@@ -17,30 +18,78 @@ export declare const ASSET_URL_TTL_SECONDS = 3600;
 export declare const ASSET_DELETE_GRACE_DAYS = 7;
 export declare const ASSET_NAME_MAX_CHARS = 80;
 export declare const ASSET_LIST_MAX_LIMIT = 100;
+/** A customer clip (owner, 2026-10-20): up to 100 MiB and 120 s, a non-fragmented MP4 in h264 or hevc. */
+export declare const ASSET_VIDEO_MAX_BYTES: number;
+export declare const ASSET_VIDEO_MAX_SECONDS = 120;
+export declare const ASSET_VIDEO_CODECS: readonly ["h264", "hevc"];
+/** A clip sent as the body of `POST /v1/assets/bytes`: the API holds the body in memory before staging it. */
+export declare const ASSET_BYTES_ROUTE_VIDEO_MAX_BYTES: number;
+/** How long a clip in processing may take before reads call it failed: a 90 s download inside a 5 minute task. */
+export declare const ASSET_PROCESSING_SECONDS = 600;
+export declare const ASSET_VIDEO_DOWNLOAD_DEADLINE_MS = 90000;
+export declare const ASSET_INGEST_TASK_MAX_DURATION_SECONDS = 300;
+export declare const ASSET_PUT_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "video/mp4"];
+export type AssetPutMediaType = (typeof ASSET_PUT_MEDIA_TYPES)[number];
+/** The worker task that downloads or reads a staged file, checks it and publishes the asset. */
+export declare const INGEST_ASSET_MEDIA_TASK = "ingest-asset-media";
+/** The cabinet's preview of an asset (S4a): a WebP at `assets/<account>/<id>/preview.webp`, long side at most 512, no upscale. */
+export declare const ASSET_PREVIEW_TASK = "make-asset-preview";
+export declare const ASSET_PREVIEW_MAX_SIDE = 512;
+export declare const ASSET_PREVIEW_QUALITY = 75;
+export declare const ASSET_PREVIEW_SWEEP_BATCH = 200;
+/** Past this many attempts a row leaves the queue as `gave_up`: an OOM or a hung R2 never loops for ever. */
+export declare const ASSET_PREVIEW_MAX_ATTEMPTS = 6;
+/** How long creating an asset waits to queue its preview; past it the hourly sweep picks the row up. */
+export declare const ASSET_PREVIEW_ENQUEUE_TIMEOUT_MS = 2000;
+/** Terminal codes only; a passing failure throws, and the next attempt or the sweep repeats it. */
+export declare const ASSET_PREVIEW_ERRORS: readonly ["decode_failed", "size_mismatch", "empty_output", "gave_up"];
+export type AssetPreviewError = (typeof ASSET_PREVIEW_ERRORS)[number];
 export declare const ASSET_ROLES: readonly ["character", "location", "style", "prop", "other"];
 export type AssetRole = (typeof ASSET_ROLES)[number];
-export declare const ASSET_KINDS: readonly ["image", "video"];
+export { ASSET_KINDS, ASSET_MEDIA_TYPES, assetId };
 export type AssetKind = (typeof ASSET_KINDS)[number];
-/** WebP is kept only as a generation's own output: its dimensions are not read from customer bytes. */
-export declare const ASSET_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "video/mp4"];
 export type AssetMediaType = (typeof ASSET_MEDIA_TYPES)[number];
 export declare const ASSET_SOURCE_TYPES: readonly ["generation", "upload", "url", "base64", "bytes", "put"];
 export type AssetSourceType = (typeof ASSET_SOURCE_TYPES)[number];
-export declare const assetId: z.ZodString;
 export declare const assetName: z.ZodString;
-/** Where the asset's bytes come from: an own image generation, an own upload, a public https url, or inline base64. */
+/** A file the client PUTs itself: its type, exact size and sha256, checked against the bytes before the asset exists. */
+export declare const assetPutSource: z.ZodObject<{
+    media_type: z.ZodEnum<{
+        "image/jpeg": "image/jpeg";
+        "image/png": "image/png";
+        "video/mp4": "video/mp4";
+    }>;
+    bytes: z.ZodNumber;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+/** Where the asset's bytes come from: an own generation, an own upload, a public https url (`kind: "video"` for a clip), */
+/** inline base64, or a presigned PUT. */
 export declare const assetSource: z.ZodUnion<readonly [z.ZodObject<{
     run_id: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     upload_id: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     url: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        image: "image";
+        video: "video";
+    }>>;
 }, z.core.$strict>, z.ZodObject<{
     base64: z.ZodString;
     media_type: z.ZodEnum<{
         "image/jpeg": "image/jpeg";
         "image/png": "image/png";
     }>;
+}, z.core.$strict>, z.ZodObject<{
+    put: z.ZodObject<{
+        media_type: z.ZodEnum<{
+            "image/jpeg": "image/jpeg";
+            "image/png": "image/png";
+            "video/mp4": "video/mp4";
+        }>;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strict>;
 }, z.core.$strict>]>;
 export type AssetSource = z.infer<typeof assetSource>;
 /** `rights_confirmed` is required for the customer's own material and states once, at creation, that it may be used. */
@@ -51,12 +100,26 @@ export declare const createAssetRequest: z.ZodObject<{
         upload_id: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
         url: z.ZodString;
+        kind: z.ZodOptional<z.ZodEnum<{
+            image: "image";
+            video: "video";
+        }>>;
     }, z.core.$strict>, z.ZodObject<{
         base64: z.ZodString;
         media_type: z.ZodEnum<{
             "image/jpeg": "image/jpeg";
             "image/png": "image/png";
         }>;
+    }, z.core.$strict>, z.ZodObject<{
+        put: z.ZodObject<{
+            media_type: z.ZodEnum<{
+                "image/jpeg": "image/jpeg";
+                "image/png": "image/png";
+                "video/mp4": "video/mp4";
+            }>;
+            bytes: z.ZodNumber;
+            sha256: z.ZodString;
+        }, z.core.$strict>;
     }, z.core.$strict>]>;
     role: z.ZodEnum<{
         character: "character";
@@ -110,6 +173,7 @@ export declare const assetListQuery: z.ZodObject<{
 export type AssetListQuery = z.infer<typeof assetListQuery>;
 export declare const asset: z.ZodObject<{
     asset_id: z.ZodString;
+    state: z.ZodLiteral<"ready">;
     kind: z.ZodEnum<{
         image: "image";
         video: "video";
@@ -133,6 +197,8 @@ export declare const asset: z.ZodObject<{
     height: z.ZodNumber;
     duration_frames: z.ZodNullable<z.ZodNumber>;
     fps: z.ZodNullable<z.ZodNumber>;
+    codec: z.ZodNullable<z.ZodString>;
+    pix_fmt: z.ZodNullable<z.ZodString>;
     content_digest: z.ZodString;
     source_type: z.ZodEnum<{
         base64: "base64";
@@ -148,15 +214,191 @@ export declare const asset: z.ZodObject<{
     updated_at: z.ZodString;
 }, z.core.$strict>;
 export type Asset = z.infer<typeof asset>;
+/** Where a PUT goes: signed for 15 minutes with exactly these two headers, and finished within a day. */
+export declare const assetPutUpload: z.ZodObject<{
+    put_url: z.ZodString;
+    put_headers: z.ZodObject<{
+        "content-type": z.ZodEnum<{
+            "image/jpeg": "image/jpeg";
+            "image/png": "image/png";
+            "video/mp4": "video/mp4";
+        }>;
+        "content-length": z.ZodString;
+    }, z.core.$strict>;
+    expires_at: z.ZodString;
+    finish_by: z.ZodString;
+}, z.core.$strict>;
+/** An asset before it exists: waiting for its PUT, being checked by the worker, or refused with the reason. */
+export declare const ASSET_PENDING_STATES: readonly ["awaiting_upload", "processing", "failed"];
+export declare const pendingAsset: z.ZodObject<{
+    asset_id: z.ZodString;
+    state: z.ZodEnum<{
+        awaiting_upload: "awaiting_upload";
+        failed: "failed";
+        processing: "processing";
+    }>;
+    kind: z.ZodEnum<{
+        image: "image";
+        video: "video";
+    }>;
+    role: z.ZodEnum<{
+        character: "character";
+        location: "location";
+        other: "other";
+        prop: "prop";
+        style: "style";
+    }>;
+    name: z.ZodString;
+    source_type: z.ZodEnum<{
+        base64: "base64";
+        bytes: "bytes";
+        generation: "generation";
+        put: "put";
+        upload: "upload";
+        url: "url";
+    }>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    processing_deadline: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    upload: z.ZodOptional<z.ZodObject<{
+        put_url: z.ZodString;
+        put_headers: z.ZodObject<{
+            "content-type": z.ZodEnum<{
+                "image/jpeg": "image/jpeg";
+                "image/png": "image/png";
+                "video/mp4": "video/mp4";
+            }>;
+            "content-length": z.ZodString;
+        }, z.core.$strict>;
+        expires_at: z.ZodString;
+        finish_by: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PendingAsset = z.infer<typeof pendingAsset>;
+export declare const assetItem: z.ZodUnion<readonly [z.ZodObject<{
+    asset_id: z.ZodString;
+    state: z.ZodLiteral<"ready">;
+    kind: z.ZodEnum<{
+        image: "image";
+        video: "video";
+    }>;
+    role: z.ZodEnum<{
+        character: "character";
+        location: "location";
+        other: "other";
+        prop: "prop";
+        style: "style";
+    }>;
+    name: z.ZodString;
+    media_type: z.ZodEnum<{
+        "image/jpeg": "image/jpeg";
+        "image/png": "image/png";
+        "image/webp": "image/webp";
+        "video/mp4": "video/mp4";
+    }>;
+    bytes: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    duration_frames: z.ZodNullable<z.ZodNumber>;
+    fps: z.ZodNullable<z.ZodNumber>;
+    codec: z.ZodNullable<z.ZodString>;
+    pix_fmt: z.ZodNullable<z.ZodString>;
+    content_digest: z.ZodString;
+    source_type: z.ZodEnum<{
+        base64: "base64";
+        bytes: "bytes";
+        generation: "generation";
+        put: "put";
+        upload: "upload";
+        url: "url";
+    }>;
+    url: z.ZodString;
+    expires_at: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    asset_id: z.ZodString;
+    state: z.ZodEnum<{
+        awaiting_upload: "awaiting_upload";
+        failed: "failed";
+        processing: "processing";
+    }>;
+    kind: z.ZodEnum<{
+        image: "image";
+        video: "video";
+    }>;
+    role: z.ZodEnum<{
+        character: "character";
+        location: "location";
+        other: "other";
+        prop: "prop";
+        style: "style";
+    }>;
+    name: z.ZodString;
+    source_type: z.ZodEnum<{
+        base64: "base64";
+        bytes: "bytes";
+        generation: "generation";
+        put: "put";
+        upload: "upload";
+        url: "url";
+    }>;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    processing_deadline: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    upload: z.ZodOptional<z.ZodObject<{
+        put_url: z.ZodString;
+        put_headers: z.ZodObject<{
+            "content-type": z.ZodEnum<{
+                "image/jpeg": "image/jpeg";
+                "image/png": "image/png";
+                "video/mp4": "video/mp4";
+            }>;
+            "content-length": z.ZodString;
+        }, z.core.$strict>;
+        expires_at: z.ZodString;
+        finish_by: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+export type AssetItem = z.infer<typeof assetItem>;
+/** Why a pending asset failed, as `error.code`; these never come as an HTTP error of their own. */
+export declare const ASSET_INGEST_FAILURE_CODES: readonly ["upload_expired", "upload_size_mismatch", "upload_digest_mismatch", "unsupported_media_type", "invalid_image", "invalid_video", "payload_too_large", "url_fetch_refused", "url_fetch_failed", "asset_cap_exceeded", "asset_ingest_cap_exceeded", "url_import_disabled", "ingest_timed_out", "ingest_enqueue_failed", "ingest_failed"];
+export type AssetIngestFailureCode = (typeof ASSET_INGEST_FAILURE_CODES)[number];
+/** What the API hands the worker: which pending asset, and whether its bytes are at a url or already staged. */
+export declare const ingestAssetMediaPayload: z.ZodObject<{
+    assetId: z.ZodString;
+    accountId: z.ZodString;
+    source: z.ZodEnum<{
+        staging: "staging";
+        url: "url";
+    }>;
+}, z.core.$strict>;
+export type IngestAssetMediaPayload = z.infer<typeof ingestAssetMediaPayload>;
+/** The preview task takes the id only; it reads the account from the row. */
+export declare const assetPreviewPayload: z.ZodObject<{
+    assetId: z.ZodString;
+}, z.core.$strict>;
+export type AssetPreviewPayload = z.infer<typeof assetPreviewPayload>;
+/** One run per asset across every caller: created with `scope: "global"`, since a raw string inside a task is per run. */
+export declare const assetPreviewIdempotencyKey: (id: string) => string;
+export declare const assetPreviewKey: (accountId: string, id: string) => string;
 export declare const assetUsage: z.ZodObject<{
     count: z.ZodNumber;
     bytes: z.ZodNumber;
     max_count: z.ZodNumber;
     max_bytes: z.ZodNumber;
 }, z.core.$strict>;
+/** `pending` holds the account's assets still in progress and those refused within the day; the first page only. */
 export declare const assetList: z.ZodObject<{
     assets: z.ZodArray<z.ZodObject<{
         asset_id: z.ZodString;
+        state: z.ZodLiteral<"ready">;
         kind: z.ZodEnum<{
             image: "image";
             video: "video";
@@ -180,6 +422,8 @@ export declare const assetList: z.ZodObject<{
         height: z.ZodNumber;
         duration_frames: z.ZodNullable<z.ZodNumber>;
         fps: z.ZodNullable<z.ZodNumber>;
+        codec: z.ZodNullable<z.ZodString>;
+        pix_fmt: z.ZodNullable<z.ZodString>;
         content_digest: z.ZodString;
         source_type: z.ZodEnum<{
             base64: "base64";
@@ -194,6 +438,53 @@ export declare const assetList: z.ZodObject<{
         created_at: z.ZodString;
         updated_at: z.ZodString;
     }, z.core.$strict>>;
+    pending: z.ZodArray<z.ZodObject<{
+        asset_id: z.ZodString;
+        state: z.ZodEnum<{
+            awaiting_upload: "awaiting_upload";
+            failed: "failed";
+            processing: "processing";
+        }>;
+        kind: z.ZodEnum<{
+            image: "image";
+            video: "video";
+        }>;
+        role: z.ZodEnum<{
+            character: "character";
+            location: "location";
+            other: "other";
+            prop: "prop";
+            style: "style";
+        }>;
+        name: z.ZodString;
+        source_type: z.ZodEnum<{
+            base64: "base64";
+            bytes: "bytes";
+            generation: "generation";
+            put: "put";
+            upload: "upload";
+            url: "url";
+        }>;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strict>>;
+        processing_deadline: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+        upload: z.ZodOptional<z.ZodObject<{
+            put_url: z.ZodString;
+            put_headers: z.ZodObject<{
+                "content-type": z.ZodEnum<{
+                    "image/jpeg": "image/jpeg";
+                    "image/png": "image/png";
+                    "video/mp4": "video/mp4";
+                }>;
+                "content-length": z.ZodString;
+            }, z.core.$strict>;
+            expires_at: z.ZodString;
+            finish_by: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     next_cursor: z.ZodNullable<z.ZodString>;
     usage: z.ZodObject<{
         count: z.ZodNumber;
@@ -212,17 +503,82 @@ export declare const assetRead: z.ZodObject<{
     height: z.ZodNumber;
     duration_frames: z.ZodNullable<z.ZodNumber>;
     fps: z.ZodNullable<z.ZodNumber>;
+    codec: z.ZodNullable<z.ZodString>;
+    pix_fmt: z.ZodNullable<z.ZodString>;
     content_digest: z.ZodString;
     url: z.ZodString;
     expires_at: z.ZodString;
     created_at: z.ZodString;
     updated_at: z.ZodString;
+    state: z.ZodLiteral<"ready">;
     kind: z.ZodString;
     role: z.ZodString;
     media_type: z.ZodString;
     source_type: z.ZodString;
 }, z.core.$loose>;
 export type AssetRead = z.infer<typeof assetRead>;
+export declare const pendingAssetRead: z.ZodObject<{
+    asset_id: z.ZodString;
+    name: z.ZodString;
+    processing_deadline: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    state: z.ZodString;
+    kind: z.ZodString;
+    role: z.ZodString;
+    source_type: z.ZodString;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$loose>>;
+    upload: z.ZodOptional<z.ZodObject<{
+        put_url: z.ZodString;
+        expires_at: z.ZodString;
+        finish_by: z.ZodString;
+        put_headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type PendingAssetRead = z.infer<typeof pendingAssetRead>;
+export declare const assetItemRead: z.ZodUnion<readonly [z.ZodObject<{
+    asset_id: z.ZodString;
+    name: z.ZodString;
+    bytes: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    duration_frames: z.ZodNullable<z.ZodNumber>;
+    fps: z.ZodNullable<z.ZodNumber>;
+    codec: z.ZodNullable<z.ZodString>;
+    pix_fmt: z.ZodNullable<z.ZodString>;
+    content_digest: z.ZodString;
+    url: z.ZodString;
+    expires_at: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+    state: z.ZodLiteral<"ready">;
+    kind: z.ZodString;
+    role: z.ZodString;
+    media_type: z.ZodString;
+    source_type: z.ZodString;
+}, z.core.$loose>, z.ZodObject<{
+    asset_id: z.ZodString;
+    name: z.ZodString;
+    processing_deadline: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+    state: z.ZodString;
+    kind: z.ZodString;
+    role: z.ZodString;
+    source_type: z.ZodString;
+    error: z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$loose>>;
+    upload: z.ZodOptional<z.ZodObject<{
+        put_url: z.ZodString;
+        expires_at: z.ZodString;
+        finish_by: z.ZodString;
+        put_headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>]>;
+export type AssetItemRead = z.infer<typeof assetItemRead>;
 export declare const assetListRead: z.ZodObject<{
     next_cursor: z.ZodNullable<z.ZodString>;
     contract_version: z.ZodString;
@@ -234,16 +590,39 @@ export declare const assetListRead: z.ZodObject<{
         height: z.ZodNumber;
         duration_frames: z.ZodNullable<z.ZodNumber>;
         fps: z.ZodNullable<z.ZodNumber>;
+        codec: z.ZodNullable<z.ZodString>;
+        pix_fmt: z.ZodNullable<z.ZodString>;
         content_digest: z.ZodString;
         url: z.ZodString;
         expires_at: z.ZodString;
         created_at: z.ZodString;
         updated_at: z.ZodString;
+        state: z.ZodLiteral<"ready">;
         kind: z.ZodString;
         role: z.ZodString;
         media_type: z.ZodString;
         source_type: z.ZodString;
     }, z.core.$loose>>;
+    pending: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        asset_id: z.ZodString;
+        name: z.ZodString;
+        processing_deadline: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+        state: z.ZodString;
+        kind: z.ZodString;
+        role: z.ZodString;
+        source_type: z.ZodString;
+        error: z.ZodNullable<z.ZodObject<{
+            code: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$loose>>;
+        upload: z.ZodOptional<z.ZodObject<{
+            put_url: z.ZodString;
+            expires_at: z.ZodString;
+            finish_by: z.ZodString;
+            put_headers: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
     usage: z.ZodObject<{
         count: z.ZodNumber;
         bytes: z.ZodNumber;