vidspotai-shared 1.0.53 → 1.0.55

package/lib/services/aiGen/providers/pexels/pexels.service.js

@@ -0,0 +1,118 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PexelsProviderService = void 0;
+const axios_1 = __importDefault(require("axios"));
+const baseAiGenProvider_service_1 = require("../baseAiGenProvider.service");
+/**
+ * Pexels stock provider — T0 tier (free).
+ *
+ * Pexels' free API supports video + image search. We deliberately ignore the
+ * music API for now (it's photo-only on the free tier; music comes from a
+ * different stock provider in a later commit).
+ *
+ * Attribution: Pexels' license requires "Photos provided by Pexels" attribution
+ * when used in publication. Producer surfaces (storyboard, finished video page)
+ * must surface this — handled in the UI layer, not here.
+ */
+const PEXELS_VIDEO_URL = "https://api.pexels.com/videos/search";
+const PEXELS_IMAGE_URL = "https://api.pexels.com/v1/search";
+class PexelsProviderService extends baseAiGenProvider_service_1.BaseAiGenProviderService {
+    constructor() {
+        super(...arguments);
+        this.apiKey = process.env.PEXELS_API_KEY;
+    }
+    async searchStock(params) {
+        if (!this.apiKey) {
+            throw new Error("PEXELS_API_KEY not set — pexels provider cannot search");
+        }
+        if (params.kind === "music") {
+            throw new Error("Pexels does not provide stock music");
+        }
+        const headers = { Authorization: this.apiKey };
+        const perPage = Math.min(params.perPage ?? 15, 80);
+        if (params.kind === "video") {
+            const { data } = await axios_1.default.get(PEXELS_VIDEO_URL, {
+                headers,
+                timeout: 20000,
+                params: {
+                    query: params.query,
+                    per_page: perPage,
+                    orientation: this.aspectToOrientation(params.aspectRatio),
+                },
+            });
+            const filtered = data.videos.filter((v) => {
+                if (params.minDurationSec && v.duration < params.minDurationSec)
+                    return false;
+                if (params.maxDurationSec && v.duration > params.maxDurationSec)
+                    return false;
+                return true;
+            });
+            return {
+                assets: filtered.map((v) => ({
+                    id: String(v.id),
+                    url: this.pickBestVideoFile(v.video_files),
+                    thumbnailUrl: v.image,
+                    width: v.width,
+                    height: v.height,
+                    durationSec: v.duration,
+                    source: "pexels",
+                    attribution: { name: v.user.name, url: v.user.url },
+                })),
+                totalAvailable: data.total_results,
+            };
+        }
+        // image
+        const { data } = await axios_1.default.get(PEXELS_IMAGE_URL, {
+            headers,
+            timeout: 20000,
+            params: {
+                query: params.query,
+                per_page: perPage,
+                orientation: this.aspectToOrientation(params.aspectRatio),
+            },
+        });
+        return {
+            assets: data.photos.map((p) => ({
+                id: String(p.id),
+                url: p.src.original,
+                thumbnailUrl: p.src.medium,
+                width: p.width,
+                height: p.height,
+                source: "pexels",
+                attribution: { name: p.photographer, url: p.photographer_url },
+            })),
+            totalAvailable: data.total_results,
+        };
+    }
+    /** Free assets — registers as 0 credits regardless of model. */
+    getCreditUsed(_params) {
+        return 0;
+    }
+    aspectToOrientation(aspect) {
+        if (!aspect)
+            return undefined;
+        if (aspect === "9:16" || aspect === "4:5")
+            return "portrait";
+        if (aspect === "1:1")
+            return "square";
+        return "landscape";
+    }
+    pickBestVideoFile(files) {
+        // Prefer .mp4 1080p, fall back to highest-resolution mp4.
+        const mp4 = files.filter((f) => f.file_type === "video/mp4");
+        if (mp4.length === 0) {
+            const first = files[0];
+            if (!first)
+                throw new Error("Pexels video has no files");
+            return first.link;
+        }
+        const hd = mp4.find((f) => f.height >= 1000 && f.height <= 1200);
+        if (hd)
+            return hd.link;
+        return mp4.sort((a, b) => b.height - a.height)[0].link;
+    }
+}
+exports.PexelsProviderService = PexelsProviderService;

package/lib/services/aiGen/providers/runway/cameraAdapter.d.ts

@@ -0,0 +1,3 @@
+import type { CameraControl } from "../../canonicalAdapters/cameraControl.types";
+export declare function applyRunwayCameraControl(prompt: string | undefined, c: CameraControl): string;
+//# sourceMappingURL=cameraAdapter.d.ts.map

package/lib/services/aiGen/providers/runway/cameraAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cameraAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/runway/cameraAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAEd,MAAM,6CAA6C,CAAC;AAmCrD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,CAAC,EAAE,aAAa,GACf,MAAM,CAMR"}

package/lib/services/aiGen/providers/runway/cameraAdapter.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRunwayCameraControl = applyRunwayCameraControl;
+/**
+ * Runway gen4 doesn't expose a structured camera-control field — moves are
+ * inferred from prompt text. We translate the canonical preset/intensity into
+ * a short bracketed clause prepended to the prompt. Matches Runway's own
+ * cinematography vocabulary so the model parses it reliably.
+ */
+const PRESET_TO_PHRASE = {
+    static: "static camera",
+    pan_left: "camera pans left",
+    pan_right: "camera pans right",
+    tilt_up: "camera tilts up",
+    tilt_down: "camera tilts down",
+    zoom_in: "camera zooms in",
+    zoom_out: "camera zooms out",
+    dolly_in: "camera dollies in",
+    dolly_out: "camera dollies out",
+    orbit_left: "camera orbits left around subject",
+    orbit_right: "camera orbits right around subject",
+    roll_left: "camera rolls counter-clockwise",
+    roll_right: "camera rolls clockwise",
+    tracking: "tracking shot following subject",
+    handheld: "handheld camera",
+    push_in: "slow push in",
+    pull_out: "slow pull out",
+};
+function intensityWord(i) {
+    if (i === undefined)
+        return "";
+    if (i <= 0.33)
+        return "subtle ";
+    if (i >= 0.67)
+        return "strong ";
+    return "";
+}
+function applyRunwayCameraControl(prompt, c) {
+    if (!c.preset)
+        return prompt ?? "";
+    const phrase = PRESET_TO_PHRASE[c.preset];
+    if (!phrase)
+        return prompt ?? "";
+    const clause = `[${intensityWord(c.intensity)}${phrase}]`;
+    return prompt ? `${clause} ${prompt}` : clause;
+}

package/lib/services/analytics.service.d.ts

@@ -19,5 +19,15 @@ export interface RecordJobOutcomeParams {
  */
 export declare class AnalyticsService {
     static recordJobOutcome(p: RecordJobOutcomeParams): Promise<void>;
+    /**
+     * Records a "sample" video — i.e. the try-example short-circuit in the
+     * functions controller that returns a pre-generated video without actually
+     * invoking any provider. Tracked separately so dashboard "Jobs" remains a
+     * count of real provider-backed generations.
+     */
+    static recordSampleOutcome(p: {
+        modelKey: string;
+        finalizedAt?: Date;
+    }): Promise<void>;
 }
 //# sourceMappingURL=analytics.service.d.ts.map

package/lib/services/analytics.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.service.d.ts","sourceRoot":"","sources":["../../src/services/analytics.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAqB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAUpD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,eAAe,CAAC;IAC7B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,gBAAgB;WACd,gBAAgB,CAAC,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;CAqDxE"}
+{"version":3,"file":"analytics.service.d.ts","sourceRoot":"","sources":["../../src/services/analytics.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAqB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAUpD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,eAAe,CAAC;IAC7B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AAED;;;;;;GAMG;AACH,qBAAa,gBAAgB;WACd,gBAAgB,CAAC,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsDvE;;;;;OAKG;WACU,mBAAmB,CAAC,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAqB7F"}

package/lib/services/analytics.service.js

@@ -65,5 +65,32 @@ class AnalyticsService {
         batch.set(globalRef, globalPayload, { merge: true });
         await batch.commit();
     }
+    /**
+     * Records a "sample" video — i.e. the try-example short-circuit in the
+     * functions controller that returns a pre-generated video without actually
+     * invoking any provider. Tracked separately so dashboard "Jobs" remains a
+     * count of real provider-backed generations.
+     */
+    static async recordSampleOutcome(p) {
+        const date = dateKey(p.finalizedAt);
+        const inc = firestore_1.FieldValue.increment;
+        const perModelRef = firebase_1.firestore.collection(DAILY_COL).doc(`${date}_${p.modelKey}`);
+        const globalRef = firebase_1.firestore.collection(DAILY_GLOBAL_COL).doc(date);
+        const payload = {
+            date,
+            modelKey: p.modelKey,
+            samplesCompleted: inc(1),
+            updatedAt: firestore_1.FieldValue.serverTimestamp(),
+        };
+        const globalPayload = {
+            date,
+            samplesCompleted: inc(1),
+            updatedAt: firestore_1.FieldValue.serverTimestamp(),
+        };
+        const batch = firebase_1.firestore.batch();
+        batch.set(perModelRef, payload, { merge: true });
+        batch.set(globalRef, globalPayload, { merge: true });
+        await batch.commit();
+    }
 }
 exports.AnalyticsService = AnalyticsService;

package/lib/services/asr/assemblyai.service.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AssemblyAI ASR client. Supports submit + poll-to-completion (sync caller flow).
+ *
+ * Pricing: Universal-2 model is $0.15/hr (verified 2026-05-11 against
+ * https://www.assemblyai.com/pricing). Diarization (`speaker_labels`) adds
+ * ~$0.02/hr (≈ +13%). Long audio (>3 min) should go through the BullMQ async
+ * path; the inline poll here is bounded at 3 min to stay inside Firebase
+ * Functions HTTP timeout budgets.
+ */
+export interface TranscribeParams {
+    audioUrl: string;
+    /** Hint to AssemblyAI for language autodetect short-circuit (e.g. "en", "es"). */
+    languageCode?: string;
+    /** Diarization (speaker labels). Adds ~30% latency. */
+    speakerLabels?: boolean;
+    /** Auto-redact PII (SSN, credit cards, etc.). */
+    redactPii?: boolean;
+    /** Word-level timestamps in result. */
+    wordTimestamps?: boolean;
+}
+export interface TranscribeResult {
+    id: string;
+    status: "completed" | "queued" | "processing" | "error";
+    text?: string;
+    /** Audio duration in seconds; populated on completion. */
+    audioDuration?: number;
+    /** Per-word timestamps (start/end ms). */
+    words?: Array<{
+        text: string;
+        start: number;
+        end: number;
+        confidence: number;
+        speaker?: string;
+    }>;
+    /** Per-utterance segments when speakerLabels=true. */
+    utterances?: Array<{
+        text: string;
+        start: number;
+        end: number;
+        speaker: string;
+        confidence: number;
+    }>;
+    errorMessage?: string;
+}
+export declare class AssemblyAIService {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor();
+    private request;
+    /** Submit a transcription job. Returns the transcript id immediately. */
+    submit(params: TranscribeParams): Promise<{
+        id: string;
+    }>;
+    checkStatus(id: string): Promise<TranscribeResult>;
+    /**
+     * Submit and poll inline until completion. Use for short-to-medium audio.
+     * Bounded at `timeoutMs` (default 3 min) — caller should fall back to async
+     * BullMQ flow for longer audio.
+     */
+    transcribe(params: TranscribeParams, { timeoutMs, intervalMs }?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<TranscribeResult>;
+    /**
+     * Credit cost for transcription. Universal-2 = $0.15/hr; diarization
+     * (speakerLabels) adds $0.02/hr (≈ +13%). Routes through the same
+     * `getCreditsFromCost` helper as every other endpoint so the credit ↔ USD
+     * ratio (1 credit = $0.10) and the per-call floor stay consistent.
+     */
+    getCreditUsed(audioDurationSec: number, speakerLabels?: boolean): number;
+}
+//# sourceMappingURL=assemblyai.service.d.ts.map

package/lib/services/asr/assemblyai.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemblyai.service.d.ts","sourceRoot":"","sources":["../../../src/services/asr/assemblyai.service.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uCAAuC;IACvC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClG,sDAAsD;IACtD,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;;YASlB,OAAO;IAyBrB,yEAAyE;IACnE,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAWzD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAaxD;;;;OAIG;IACG,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,EAAE,SAAmB,EAAE,UAAiB,EAAE,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3F,OAAO,CAAC,gBAAgB,CAAC;IAc5B;;;;;OAKG;IACH,aAAa,CAAC,gBAAgB,EAAE,MAAM,EAAE,aAAa,UAAQ,GAAG,MAAM;CAMvE"}

package/lib/services/asr/assemblyai.service.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssemblyAIService = void 0;
+const axios_1 = __importDefault(require("axios"));
+const logger_1 = require("../../utils/logger");
+const helpers_1 = require("../../utils/helpers");
+class AssemblyAIService {
+    constructor() {
+        this.baseUrl = "https://api.assemblyai.com/v2";
+        if (!process.env.ASSEMBLYAI_API_KEY) {
+            throw new Error("Missing ASSEMBLYAI_API_KEY in environment variables");
+        }
+        this.apiKey = process.env.ASSEMBLYAI_API_KEY;
+    }
+    async request(endpoint, method, body) {
+        const config = {
+            method,
+            url: `${this.baseUrl}${endpoint}`,
+            headers: {
+                Authorization: this.apiKey,
+                "Content-Type": "application/json",
+            },
+            data: body,
+            timeout: 60000,
+            validateStatus: () => true,
+        };
+        const resp = await axios_1.default.request(config);
+        if (resp.status < 200 || resp.status >= 300) {
+            throw new Error(`AssemblyAI API Error: ${resp.status} ${resp.statusText} — ${JSON.stringify(resp.data)}`);
+        }
+        return resp.data;
+    }
+    /** Submit a transcription job. Returns the transcript id immediately. */
+    async submit(params) {
+        const body = {
+            audio_url: params.audioUrl,
+            ...(params.languageCode ? { language_code: params.languageCode } : { language_detection: true }),
+            ...(params.speakerLabels ? { speaker_labels: true } : {}),
+            ...(params.redactPii ? { redact_pii: true, redact_pii_policies: ["us_social_security_number", "credit_card_number", "email_address", "phone_number"] } : {}),
+        };
+        const resp = await this.request("/transcript", "POST", body);
+        return { id: resp.id };
+    }
+    async checkStatus(id) {
+        const resp = await this.request(`/transcript/${id}`, "GET");
+        return {
+            id: resp.id,
+            status: resp.status,
+            text: resp.text,
+            audioDuration: resp.audio_duration,
+            words: resp.words,
+            utterances: resp.utterances,
+            errorMessage: resp.error,
+        };
+    }
+    /**
+     * Submit and poll inline until completion. Use for short-to-medium audio.
+     * Bounded at `timeoutMs` (default 3 min) — caller should fall back to async
+     * BullMQ flow for longer audio.
+     */
+    async transcribe(params, { timeoutMs = 180000, intervalMs = 3000 } = {}) {
+        const { id } = await this.submit(params);
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, intervalMs));
+            const status = await this.checkStatus(id);
+            if (status.status === "completed" || status.status === "error")
+                return status;
+        }
+        logger_1.logger.warn("AssemblyAI transcribe timed out — returning processing status", { id });
+        return { id, status: "processing", errorMessage: "Transcription exceeded inline poll budget; use checkStatus(id) to fetch later." };
+    }
+    /**
+     * Credit cost for transcription. Universal-2 = $0.15/hr; diarization
+     * (speakerLabels) adds $0.02/hr (≈ +13%). Routes through the same
+     * `getCreditsFromCost` helper as every other endpoint so the credit ↔ USD
+     * ratio (1 credit = $0.10) and the per-call floor stay consistent.
+     */
+    getCreditUsed(audioDurationSec, speakerLabels = false) {
+        const ratePerSecond = 0.15 / 3600;
+        const multiplier = speakerLabels ? 1.133 : 1.0;
+        const cost = ratePerSecond * audioDurationSec * multiplier;
+        return (0, helpers_1.getCreditsFromCost)(cost);
+    }
+}
+exports.AssemblyAIService = AssemblyAIService;

package/lib/services/asr/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./assemblyai.service";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/asr/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/asr/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/lib/services/asr/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./assemblyai.service"), exports);

package/lib/services/assetCache.service.d.ts

@@ -0,0 +1,54 @@
+import { ICachedAssetModel } from "../models/cachedAsset.model";
+import { ICachedRawAssetModel } from "../models/cachedRawAsset.model";
+/**
+ * Asset cache + dedupe.
+ *
+ * Many agent runs ask for similar things — same VO line, same stock query,
+ * similar image prompt. Caching by a content-hashed key turns the second
+ * request into an instant lookup, which is a massive cost lever for bulk runs
+ * (where the same template variant is generated 100×) and serial creators.
+ *
+ * The cache is content-addressed: hash(provider + normalized-input) → the
+ * resulting asset URL + metadata. Any input change produces a different hash,
+ * so stale results are impossible.
+ *
+ * Backed by Firestore for V1; can move to Redis / GCS metadata index later
+ * without changing the API.
+ */
+export type CachedAsset = ICachedAssetModel;
+export interface AssetCacheKeyParts {
+    provider: string;
+    /** Stable input identity — must capture every parameter that affects output. */
+    input: Record<string, unknown>;
+}
+export declare class AssetCacheService {
+    /**
+     * Compute a stable cache key. Same input → same key, regardless of object
+     * key order. Use externally to derive the idempotency key for the upstream
+     * provider call so retries dedupe naturally.
+     */
+    static hashKey(parts: AssetCacheKeyParts): string;
+    static lookup(parts: AssetCacheKeyParts): Promise<CachedAsset | null>;
+    static store(parts: AssetCacheKeyParts, asset: Omit<CachedAsset, "key" | "createdAt" | "lastAccessedAt" | "hitCount">): Promise<CachedAsset>;
+}
+/**
+ * Raw payload cache — sibling to the asset URL cache for things that aren't
+ * a single asset URL: stock-search responses (lists), VO bytes, etc.
+ *
+ * Same content-hash key strategy. TTL is optional — stock results expire
+ * after 30 min, VOs are immutable so they live until evicted.
+ *
+ * Firestore doc cap is 1MB. Callers that may exceed it (VO base64) are
+ * responsible for skipping the store call when payloads get big.
+ */
+export interface RawCacheKeyParts extends AssetCacheKeyParts {
+    kind: ICachedRawAssetModel["kind"];
+}
+export declare class RawAssetCacheService {
+    static hashKey(parts: RawCacheKeyParts): string;
+    static lookup<T = unknown>(parts: RawCacheKeyParts): Promise<T | null>;
+    static store(parts: RawCacheKeyParts, payload: unknown, options?: {
+        ttlMs?: number;
+    }): Promise<void>;
+}
+//# sourceMappingURL=assetCache.service.d.ts.map

package/lib/services/assetCache.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assetCache.service.d.ts","sourceRoot":"","sources":["../../src/services/assetCache.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAGtE;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAE5C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,qBAAa,iBAAiB;IAC5B;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM;WAQpC,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;WAoB9D,KAAK,CAChB,KAAK,EAAE,kBAAkB,EACzB,KAAK,EAAE,IAAI,CACT,WAAW,EACX,KAAK,GAAG,WAAW,GAAG,gBAAgB,GAAG,UAAU,CACpD,GACA,OAAO,CAAC,WAAW,CAAC;CAaxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,qBAAa,oBAAoB;IAC/B,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM;WAIlC,MAAM,CAAC,CAAC,GAAG,OAAO,EAC7B,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;WAqBP,KAAK,CAChB,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,IAAI,CAAC;CAoBjB"}

package/lib/services/assetCache.service.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RawAssetCacheService = exports.AssetCacheService = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const firestore_service_1 = require("./firestore.service");
+class AssetCacheService {
+    /**
+     * Compute a stable cache key. Same input → same key, regardless of object
+     * key order. Use externally to derive the idempotency key for the upstream
+     * provider call so retries dedupe naturally.
+     */
+    static hashKey(parts) {
+        const normalized = JSON.stringify({
+            p: parts.provider,
+            i: sortedClone(parts.input),
+        });
+        return crypto_1.default.createHash("sha256").update(normalized).digest("hex");
+    }
+    static async lookup(parts) {
+        const key = AssetCacheService.hashKey(parts);
+        const doc = await firestore_service_1.FirestoreService.getDataById(firestore_service_1.FirestoreService.assetCacheCol, key);
+        if (!doc)
+            return null;
+        // Best-effort hit-count update; don't block on it.
+        void firestore_service_1.FirestoreService.updateData(firestore_service_1.FirestoreService.assetCacheCol, key, {
+            lastAccessedAt: new Date().toISOString(),
+            hitCount: (doc.hitCount ?? 0) + 1,
+        }).catch(() => undefined);
+        const { id: _id, ...stripped } = doc;
+        return stripped;
+    }
+    static async store(parts, asset) {
+        const key = AssetCacheService.hashKey(parts);
+        const now = new Date().toISOString();
+        const entry = {
+            ...asset,
+            key,
+            createdAt: now,
+            lastAccessedAt: now,
+            hitCount: 0,
+        };
+        await firestore_service_1.FirestoreService.addData(firestore_service_1.FirestoreService.assetCacheCol, key, entry);
+        return entry;
+    }
+}
+exports.AssetCacheService = AssetCacheService;
+class RawAssetCacheService {
+    static hashKey(parts) {
+        return AssetCacheService.hashKey(parts);
+    }
+    static async lookup(parts) {
+        const key = RawAssetCacheService.hashKey(parts);
+        const doc = await firestore_service_1.FirestoreService.getDataById(firestore_service_1.FirestoreService.assetCacheRawCol, key);
+        if (!doc)
+            return null;
+        if (doc.expiresAt && new Date(doc.expiresAt).getTime() < Date.now()) {
+            return null;
+        }
+        void firestore_service_1.FirestoreService.updateData(firestore_service_1.FirestoreService.assetCacheRawCol, key, {
+            lastAccessedAt: new Date().toISOString(),
+            hitCount: (doc.hitCount ?? 0) + 1,
+        }).catch(() => undefined);
+        return doc.payload;
+    }
+    static async store(parts, payload, options = {}) {
+        const key = RawAssetCacheService.hashKey(parts);
+        const now = new Date();
+        const entry = {
+            key,
+            kind: parts.kind,
+            payload,
+            createdAt: now.toISOString(),
+            lastAccessedAt: now.toISOString(),
+            hitCount: 0,
+        };
+        if (options.ttlMs) {
+            entry.expiresAt = new Date(now.getTime() + options.ttlMs).toISOString();
+        }
+        await firestore_service_1.FirestoreService.addData(firestore_service_1.FirestoreService.assetCacheRawCol, key, entry);
+    }
+}
+exports.RawAssetCacheService = RawAssetCacheService;
+function sortedClone(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(sortedClone);
+    const sorted = {};
+    for (const k of Object.keys(value).sort()) {
+        sorted[k] = sortedClone(value[k]);
+    }
+    return sorted;
+}

package/lib/services/audioAnalysis/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./onsetDetection.service";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/audioAnalysis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/audioAnalysis/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}

package/lib/services/audioAnalysis/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./onsetDetection.service"), exports);

package/lib/services/audioAnalysis/onsetDetection.service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Onset detection — finds the actual transient peaks in a music track so the
+ * agent can snap scene cuts to where a kick / snare / vocal entry actually
+ * lands, not just where a uniform BPM grid says they should.
+ *
+ * Backend: essentia.js (RhythmExtractor2013) — the same engine that powers
+ * Spotify's tempo estimation research. Industrial-strength for audio
+ * analysis.
+ *
+ * ╔═══════════════════════════════════════════════════════════════════════╗
+ * ║ LICENSING NOTE — essentia.js is AGPL-3 upstream.                       ║
+ * ║                                                                        ║
+ * ║ Until the MTG-UPF commercial license is signed, this module is         ║
+ * ║ STRICTLY BACKEND-ONLY:                                                 ║
+ * ║   - never bundle into the frontend                                     ║
+ * ║   - never include in any client-distributed artifact (Electron,        ║
+ * ║     desktop, mobile, downloadable build)                               ║
+ * ║   - never expose the .wasm via a public URL                            ║
+ * ║   - never reference essentia by name in customer-facing copy,          ║
+ * ║     marketing, blog posts, talks, job listings, or social posts        ║
+ * ║                                                                        ║
+ * ║ Theory of operation: the SaaS commercial license — once signed —       ║
+ * ║ covers VidSpot's use as the operator. Until then, do not amplify       ║
+ * ║ visibility. See backend/docs/licensing-essentia.md for the full        ║
+ * ║ constraint and contact (mtg-info@upf.edu).                             ║
+ * ║                                                                        ║
+ * ║ Operator switch: ENABLE_ONSET_DETECTION=true in env. Flip to false     ║
+ * ║ to disable the module across every environment in one change — snap    ║
+ * ║ pass falls back to BPM math safely.                                    ║
+ * ╚═══════════════════════════════════════════════════════════════════════╝
+ *
+ * Operationally:
+ *   - Lazy-loads the WASM module on first call (~5MB; once per worker boot)
+ *   - Downloads the audio file to memory, decodes via audio-decode (MIT)
+ *   - Mixes to mono (essentia algorithms expect a single channel)
+ *   - Runs RhythmExtractor2013 → returns { bpm, beats: number[] (seconds) }
+ *   - 12s hard timeout — long enough for a 3-min track on a cold WASM load,
+ *     short enough that the planner endpoint stays responsive on a miss
+ *   - In-memory cache keyed by URL — same music re-snaps for free
+ *
+ * Failure mode: returns undefined. Caller (snapPlanToBeats) falls back to
+ * uniform BPM math. Onset detection is enhancement, never a blocker.
+ */
+export interface OnsetAnalysis {
+    bpm: number;
+    /** Beat / onset timestamps in seconds, sorted ascending. */
+    onsets: number[];
+}
+export declare function detectOnsets(audioUrl: string): Promise<OnsetAnalysis | undefined>;
+//# sourceMappingURL=onsetDetection.service.d.ts.map

package/lib/services/audioAnalysis/onsetDetection.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onsetDetection.service.d.ts","sourceRoot":"","sources":["../../../src/services/audioAnalysis/onsetDetection.service.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAwFD,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAcvF"}