@clipwright/core 0.34.0 → 0.35.0

package/dist/reference-analysis.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { assetId } from "./asset-identity.js";
+import { ASSET_VIDEO_MAX_SECONDS } from "./assets.js";
+import { referenceProfile } from "./reference-profile.js";
+/** Reference analysis (reference-to-video S1c): an MP4 asset read into a `reference_profile`. Its status lives at its own */
+/** path, as an asset's processing does; its money (#927) rides a run of skill `analyze_reference` that holds and settles it. */
+export const REFERENCE_ANALYSES_PATH = "/v1/reference-analyses";
+export const REFERENCE_ANALYSIS_PATH = "/v1/reference-analyses/:id";
+export const REFERENCE_ANALYSIS_QUOTE_PATH = "/v1/reference-analyses/quote";
+export const ANALYZE_REFERENCE_TASK = "analyze-reference";
+/** The run skill that carries an analysis's hold and charge; not a `SKILLS` entry, since no `/v1/skills` route starts it. */
+export const ANALYZE_REFERENCE_SKILL = "analyze_reference";
+export const referenceAnalysisId = z.string().regex(/^ref_[a-f0-9]{32}$/);
+/** The price of a delivered analysis (owner, 29.10, #800/#927): Argon video plus Flash stills cost us ≈ $0.23 today. */
+/** Argon's price doubles on 2026-12-01 (≈ $0.45, ≈ 135 credits at ×2.5): the owner reprices then; nothing changes it by itself. */
+export const REFERENCE_ANALYSIS_CREDITS = 70;
+/** New analyses per account per hour: each costs us vendor money even when it fails, so the cap stays beside the price. */
+export const REFERENCE_ANALYSIS_PER_HOUR = 10;
+export const REFERENCE_ANALYSIS_WINDOW_SECONDS = 3600;
+/** The worker stops its own work here, removes its temp copy and fails the analysis; under the task's ceiling. */
+export const REFERENCE_ANALYSIS_WORK_SECONDS = 420;
+export const REFERENCE_ANALYSIS_TASK_MAX_DURATION_SECONDS = 600;
+/** Past this a read calls an unfinished analysis failed: a task killed at its ceiling writes nothing. */
+export const REFERENCE_ANALYSIS_DEADLINE_SECONDS = 900;
+export const REFERENCE_ANALYSIS_STATES = ["queued", "analyzing", "succeeded", "failed"];
+export const REFERENCE_ANALYSIS_ERRORS = ["timed_out", "analysis_failed", "asset_gone", "enqueue_failed"];
+export const REFERENCE_ANALYSIS_ERROR_MESSAGES = {
+    timed_out: "the analysis did not finish in time and was stopped; start it again",
+    analysis_failed: "the reference could not be analysed; start it again or use another clip",
+    asset_gone: "the asset was deleted before the analysis began",
+    enqueue_failed: "the analysis could not be handed to the worker; start it again",
+};
+/** What the API hands the worker: ids only, so no file name or reference text reaches Trigger.dev's log. */
+export const analyzeReferencePayload = z.strictObject({ analysisId: referenceAnalysisId, accountId: z.string().min(1) });
+export const analyzeReferenceRequest = z.strictObject({
+    asset_id: assetId.describe(`asset_id of an MP4 asset of this account, at most ${ASSET_VIDEO_MAX_SECONDS} s and 100 MiB`),
+});
+export const referenceAnalysis = z.strictObject({
+    analysis_id: referenceAnalysisId,
+    asset_id: assetId,
+    state: z.enum(REFERENCE_ANALYSIS_STATES),
+    /** Set once the analysis succeeded, `null` before and on failure. */
+    reference_profile: referenceProfile.nullable(),
+    warnings: z.array(z.string()),
+    error: z.strictObject({ code: z.enum(REFERENCE_ANALYSIS_ERRORS), message: z.string().min(1) }).nullable(),
+    /** Held at the start; 0 for an analysis started before it was paid (#927). */
+    credits_reserved: z.number().int().nonnegative(),
+    /** Set at settlement: the price once succeeded, 0 once failed; `null` while it runs. */
+    credits_charged: z.number().int().nonnegative().nullable(),
+    /** The account's balance right after the settlement, read in its transaction; `null` until settled. */
+    balance_after_credits: z.number().int().nullable(),
+    created_at: z.string().datetime(),
+    finished_at: z.string().datetime().nullable(),
+});
+export const analysisQuoteResponse = z.strictObject({
+    asset_id: assetId,
+    /** What starting it now holds and, once it succeeds, charges: 0 when the asset already has a live analysis to answer. */
+    credits_estimate: z.number().int().nonnegative(),
+    /** The analysis a start would answer for free, or `null` when a start would begin a new, paid one. */
+    replays_analysis_id: referenceAnalysisId.nullable(),
+    warnings: z.array(z.string()),
+});
+/** What a client reads: a new state, error code or profile field must not break an installed client. */
+export const referenceAnalysisRead = referenceAnalysis.extend({
+    state: z.string(),
+    reference_profile: z.record(z.string(), z.unknown()).nullable(),
+    error: z.object({ code: z.string(), message: z.string() }).nullable(),
+    // A server from before #927 sends no money fields.
+    credits_reserved: referenceAnalysis.shape.credits_reserved.optional(),
+    credits_charged: referenceAnalysis.shape.credits_charged.optional(),
+    balance_after_credits: referenceAnalysis.shape.balance_after_credits.optional(),
+});
+/** Rule 3: every element we cannot draw is said in `warnings[]` too, not only inside the profile. */
+export function referenceAnalysisWarnings(profile) {
+    return [...profile.unmapped.map((entry) => `beat ${entry.beat_index}: ${entry.what} is not drawn by our templates; substitute: ${entry.suggested_substitute}`), ...profile.analysis.warnings ?? []];
+}
+export const ANALYZE_REFERENCE_DESCRIPTION = "Read a reference ad into a reference_profile: its beats (role, timing as shares of the clip, whether the presenter " +
+    "speaks, listens or is off screen), the graphics in our template vocabulary, captions, pacing, palette and music. " +
+    "What we cannot draw is in unmapped with a substitute and in warnings. Pass asset_id of an MP4 asset (create_asset " +
+    `with kind: "video"), at most ${ASSET_VIDEO_MAX_SECONDS} s and 100 MiB; there is no url input. ` +
+    `${REFERENCE_ANALYSIS_CREDITS} credits are held at the start and charged once it succeeds; a failed analysis costs ` +
+    `nothing. ${REFERENCE_ANALYSIS_PER_HOUR} new analyses per hour per account. Answers at once with state queued; call ` +
+    "get_reference_analysis every 10 seconds until succeeded (about a minute) or failed. The same asset returns the " +
+    "same analysis, free, unless it failed. The asset is not changed. The profile names techniques; it copies no face, voice, " +
+    "music or brand of the reference.";
+export const GET_REFERENCE_ANALYSIS_DESCRIPTION = "Read an analysis started by analyze_reference: state queued or analyzing, succeeded with reference_profile and " +
+    "warnings, or failed with error.code and error.message (timed_out, analysis_failed, asset_gone, enqueue_failed); " +
+    "credits_charged is the price once succeeded, 0 once failed. Free.";
+export const QUOTE_ANALYSIS_DESCRIPTION = "Price analyze_reference for an asset before starting it: credits_estimate is what a start holds and charges once it " +
+    "succeeds, 0 when the asset already has an analysis that a start would answer (replays_analysis_id). Free; starts nothing.";
+//# sourceMappingURL=reference-analysis.js.map

package/dist/reference-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-analysis.js","sourceRoot":"","sources":["../src/reference-analysis.ts"],"names":[],"mappings":"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"}

package/dist/reference-kinds.d.ts

@@ -0,0 +1,6 @@
+/** Our template kinds, media laid over or instead of the presenter, a split layout, and what we cannot draw yet. */
+export declare const REFERENCE_GRAPHIC_KINDS: readonly ["tag", "lower_third", "end_card", "title_card", "quote", "stat", "callout", "checklist", "phone_call", "compare", "notification", "progress", "rating", "overlay_media", "insert_media", "layout_split", "particles", "unmapped"];
+export type ReferenceGraphicKind = (typeof REFERENCE_GRAPHIC_KINDS)[number];
+/** The analyser's names for a graphic: its prompt's own list, plus ours. */
+export declare const REFERENCE_SOURCE_KINDS: readonly ["toggle_checklist", "phone_call", "notification", "before_after_split", "split_screen", "stat", "product_ui", "screenshot", "title_card", "end_card", "particles", "tag", "lower_third", "end_card", "title_card", "quote", "stat", "callout", "checklist", "phone_call", "compare", "notification", "progress", "rating", "overlay_media", "insert_media", "layout_split", "particles", "unmapped", "other"];
+export type ReferenceSourceKind = (typeof REFERENCE_SOURCE_KINDS)[number];

package/dist/reference-kinds.js

@@ -0,0 +1,8 @@
+import { TEMPLATE_KIND_IDS } from "./templates/index.js";
+// A reference graphic's kinds, shared by the profile's beats and its staging (#914): their own module, so neither imports the other.
+/** Our template kinds, media laid over or instead of the presenter, a split layout, and what we cannot draw yet. */
+export const REFERENCE_GRAPHIC_KINDS = [...TEMPLATE_KIND_IDS, "overlay_media", "insert_media", "layout_split", "particles", "unmapped"];
+/** The analyser's names for a graphic: its prompt's own list, plus ours. */
+export const REFERENCE_SOURCE_KINDS = ["toggle_checklist", "phone_call", "notification", "before_after_split", "split_screen", "stat", "product_ui",
+    "screenshot", "title_card", "end_card", "particles", ...REFERENCE_GRAPHIC_KINDS, "other"];
+//# sourceMappingURL=reference-kinds.js.map

package/dist/reference-kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-kinds.js","sourceRoot":"","sources":["../src/reference-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD,qIAAqI;AAErI,oHAAoH;AACpH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,GAAG,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,CAAU,CAAC;AAEjJ,4EAA4E;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,kBAAkB,EAAE,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY;IACjJ,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,uBAAuB,EAAE,OAAO,CAAU,CAAC"}