vidspotai-shared 1.0.95 → 1.0.97

package/lib/services/avatarGen/providers/heygenAvatarProvider.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeyGenAvatarProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+const aiModels_1 = require("../../../globals/aiModels");
+const types_1 = require("../../../globals/types");
+const logger_1 = require("../../../utils/logger");
+const types_2 = require("../../aiGen/types");
+const IAvatarVideoProvider_1 = require("../IAvatarVideoProvider");
+/**
+ * HeyGen avatar engine — a HOSTED engine (the caller picks a HeyGen-hosted
+ * avatar + voice and supplies a script; HeyGen does its own TTS + lipsync).
+ *
+ * Contract (HeyGen API, verified 2026-06-26 against developers.heygen.com +
+ * the published OpenAPI spec; v2 endpoints supported through 2026-10-31):
+ *   • submit : POST  /v2/video/generate   → { data: { video_id } }
+ *   • status : GET   /v1/video_status.get?video_id=…  → { data: { status, video_url } }
+ *   • avatars: GET   /v2/avatars           → { data: { avatars: [...] } }
+ *   • voices : GET   /v2/voices            → { data: { voices: [...] } }
+ *   • auth   : X-Api-Key header
+ *
+ * This is a STANDALONE class (not an adapter over an existing service) because
+ * HeyGen has no representation in the generic video factory — avatar gen is its
+ * own concern (see IAvatarVideoProvider). Transport (auth + timeout + retry) is
+ * owned here, mirroring the per-provider pattern KlingService uses.
+ *
+ * Capabilities: inputMode "hosted", nativeTts true (HeyGen synthesizes), no
+ * multi-scene split (one render per script). It also exposes the hosted catalog
+ * (ISupportsHostedCatalog) so the UI / agent can list pickable avatars + voices.
+ */
+class HeyGenAvatarProvider {
+    constructor(modelKey = aiModels_1.EVideoGenModels.HEYGEN_AVATAR) {
+        this.modelKey = modelKey;
+        this.engine = IAvatarVideoProvider_1.EAvatarEngine.HEYGEN;
+        this.capabilities = HeyGenAvatarProvider.CAPABILITIES;
+        this.baseUrl = "https://api.heygen.com";
+        this.submitTimeout = 120000; // 2 min — submit can be slow under load
+        this.statusTimeout = 60000; // 1 min — status should be fast
+        if (!process.env.HEYGEN_API_KEY) {
+            throw new Error("Missing HEYGEN_API_KEY in environment variables");
+        }
+        this.apiKey = process.env.HEYGEN_API_KEY;
+    }
+    async generate(req) {
+        if (req.mode !== "hosted") {
+            throw new Error(`HeyGenAvatarProvider only supports hosted requests (got "${req.mode}")`);
+        }
+        // HeyGen renders a 16:9 720p by default; render mode bumps to 1080p on pro.
+        const dimension = req.renderMode === types_2.EVideoMode.PROFESSIONAL
+            ? { width: 1920, height: 1080 }
+            : { width: 1280, height: 720 };
+        const body = {
+            video_inputs: [
+                {
+                    character: {
+                        type: "avatar",
+                        avatar_id: req.hostedAvatarId,
+                        avatar_style: "normal",
+                    },
+                    voice: {
+                        type: "text",
+                        input_text: req.script,
+                        voice_id: req.hostedVoiceId,
+                    },
+                },
+            ],
+            dimension,
+        };
+        const data = await this.request("/v2/video/generate", "POST", body, this.submitTimeout);
+        const videoId = data?.data?.video_id;
+        if (!videoId) {
+            throw new Error(`HeyGen submit returned no video_id: ${JSON.stringify(data?.error ?? data)}`);
+        }
+        return { providerTaskId: videoId };
+    }
+    async checkStatus(query) {
+        const data = await this.requestWithRetry(`/v1/video_status.get?video_id=${encodeURIComponent(query.providerTaskId)}`, "GET", undefined, this.statusTimeout);
+        const providerStatus = data?.data?.status;
+        // HeyGen status enum: pending | waiting | processing | completed | failed.
+        if (providerStatus === "completed") {
+            return {
+                status: types_1.EVideoSceneStatus.COMPLETED,
+                videoUrl: data?.data?.video_url,
+            };
+        }
+        if (providerStatus === "failed") {
+            return {
+                status: types_1.EVideoSceneStatus.FAILED,
+                errorMessage: data?.data?.error?.message ?? data?.message ?? "HeyGen render failed",
+            };
+        }
+        return { status: types_1.EVideoSceneStatus.PENDING };
+    }
+    // ─── ISupportsHostedCatalog ───────────────────────────────────────────────
+    async listAvatars() {
+        const data = await this.requestWithRetry("/v2/avatars", "GET", undefined, this.statusTimeout);
+        return (data?.data?.avatars ?? []).map((a) => ({
+            id: a.avatar_id,
+            name: a.avatar_name ?? a.avatar_id,
+            previewUrl: a.preview_image_url,
+        }));
+    }
+    async listVoices() {
+        const data = await this.requestWithRetry("/v2/voices", "GET", undefined, this.statusTimeout);
+        return (data?.data?.voices ?? []).map((v) => ({
+            id: v.voice_id,
+            name: v.name ?? v.voice_id,
+            gender: this.normalizeGender(v.gender),
+            accent: v.language,
+            previewUrl: v.preview_audio,
+        }));
+    }
+    // ─── Transport ────────────────────────────────────────────────────────────
+    normalizeGender(g) {
+        const lower = (g ?? "").toLowerCase();
+        if (lower === "male")
+            return "male";
+        if (lower === "female")
+            return "female";
+        return "neutral";
+    }
+    async request(endpoint, method, body, timeout = this.submitTimeout) {
+        const config = {
+            method,
+            url: `${this.baseUrl}${endpoint}`,
+            headers: {
+                "X-Api-Key": this.apiKey,
+                "Content-Type": "application/json",
+            },
+            timeout,
+            data: body,
+        };
+        const response = await axios_1.default.request(config);
+        if (response.status < 200 || response.status >= 300) {
+            throw new Error(`HeyGen API Error: ${response.status} ${response.statusText} — ${JSON.stringify(response.data)}`);
+        }
+        return response.data;
+    }
+    /** Retries transient network/timeout/429 failures with a small backoff. */
+    async requestWithRetry(endpoint, method, body, timeout = this.statusTimeout, maxAttempts = 4) {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await this.request(endpoint, method, body, timeout);
+            }
+            catch (err) {
+                const e = err;
+                const httpStatus = e.response?.status;
+                const isTimeout = e.code === "ECONNABORTED" || (e.message?.includes("timeout") ?? false);
+                const isNetworkError = e.code === "ECONNRESET" ||
+                    e.code === "ECONNREFUSED" ||
+                    e.code === "ENOTFOUND" ||
+                    e.code === "ERR_NETWORK";
+                const isRateLimit = httpStatus === 429;
+                const isRetryable = isTimeout || isNetworkError || isRateLimit;
+                if (!isRetryable || attempt === maxAttempts) {
+                    logger_1.logger.error("HeyGen request failed (non-retryable or max attempts)", {
+                        endpoint,
+                        attempt,
+                        maxAttempts,
+                        httpStatus,
+                        errorCode: e.code,
+                        errorMessage: e.message,
+                    });
+                    throw err;
+                }
+                const backoffMs = isRateLimit ? 10000 : 1000;
+                logger_1.logger.warn("HeyGen request failed — retrying", {
+                    endpoint,
+                    attempt,
+                    maxAttempts,
+                    httpStatus,
+                    backoffMs,
+                });
+                await new Promise((r) => setTimeout(r, backoffMs));
+            }
+        }
+        throw new Error("Unreachable");
+    }
+}
+exports.HeyGenAvatarProvider = HeyGenAvatarProvider;
+/** Static so callers can branch on capability without constructing (which
+ *  would require HEYGEN_API_KEY just to read the input mode). */
+HeyGenAvatarProvider.CAPABILITIES = {
+    inputMode: "hosted",
+    nativeTts: true,
+    multiSceneSplit: false,
+};

package/lib/services/avatarGen/providers/klingAvatarProvider.d.ts

@@ -0,0 +1,32 @@
+import { EVideoGenModels } from "../../../globals/aiModels";
+import { AvatarCapabilities, AvatarGenerateRequest, AvatarStatusQuery, AvatarStatusResult, AvatarSubmitResult, EAvatarEngine, IAvatarVideoProvider } from "../IAvatarVideoProvider";
+/**
+ * Kling avatar engine, behind the IAvatarVideoProvider seam.
+ *
+ * This is intentionally a THIN ADAPTER over the existing `KlingService`, NOT a
+ * reimplementation: Kling's avatar endpoint shares the same JWT auth, IPv4-pinned
+ * agents, timeout/retry and status-stash transport as regular Kling video, so the
+ * avatar submit/poll logic stays exactly where it already lives and is proven
+ * (kling.service.ts `generateAvatarVideo` + klingStatus.ts `checkAvatarVideoStatus`).
+ * Migrating callers onto this class changes the seam, not Kling's behavior — that
+ * byte-for-byte preservation is the Phase 0a regression gate.
+ *
+ * Kling is "byo-media": caller supplies a face image; WE supply the audio (TTS is
+ * run by the orchestrator), so `nativeTts` is false. Long audio is split into
+ * scenes and stitched, so `multiSceneSplit` is true. It exposes no hosted catalog,
+ * replica training or dubbing — those optional capability interfaces are simply
+ * not implemented (ISP).
+ */
+export declare class KlingAvatarProvider implements IAvatarVideoProvider {
+    private readonly modelKey;
+    /** Static so callers can branch on capability without constructing (which
+     *  would require Kling API keys just to read the input mode). */
+    static readonly CAPABILITIES: AvatarCapabilities;
+    readonly engine = EAvatarEngine.KLING;
+    readonly capabilities: AvatarCapabilities;
+    private readonly kling;
+    constructor(modelKey?: EVideoGenModels);
+    generate(req: AvatarGenerateRequest): Promise<AvatarSubmitResult>;
+    checkStatus(query: AvatarStatusQuery): Promise<AvatarStatusResult>;
+}
+//# sourceMappingURL=klingAvatarProvider.d.ts.map

package/lib/services/avatarGen/providers/klingAvatarProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"klingAvatarProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/avatarGen/providers/klingAvatarProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAe5D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAd3B;qEACiE;IACjE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAI9C;IAEF,QAAQ,CAAC,MAAM,uBAAuB;IACtC,QAAQ,CAAC,YAAY,qBAAoC;IAEzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAGlB,QAAQ,GAAE,eAA8C;IAKrE,QAAQ,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqBjE,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAczE"}

package/lib/services/avatarGen/providers/klingAvatarProvider.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KlingAvatarProvider = void 0;
+const aiModels_1 = require("../../../globals/aiModels");
+const kling_service_1 = require("../../aiGen/providers/kling/kling.service");
+const IAvatarVideoProvider_1 = require("../IAvatarVideoProvider");
+const DEFAULT_OUTPUT_PATH = "avatar-videos";
+/**
+ * Kling avatar engine, behind the IAvatarVideoProvider seam.
+ *
+ * This is intentionally a THIN ADAPTER over the existing `KlingService`, NOT a
+ * reimplementation: Kling's avatar endpoint shares the same JWT auth, IPv4-pinned
+ * agents, timeout/retry and status-stash transport as regular Kling video, so the
+ * avatar submit/poll logic stays exactly where it already lives and is proven
+ * (kling.service.ts `generateAvatarVideo` + klingStatus.ts `checkAvatarVideoStatus`).
+ * Migrating callers onto this class changes the seam, not Kling's behavior — that
+ * byte-for-byte preservation is the Phase 0a regression gate.
+ *
+ * Kling is "byo-media": caller supplies a face image; WE supply the audio (TTS is
+ * run by the orchestrator), so `nativeTts` is false. Long audio is split into
+ * scenes and stitched, so `multiSceneSplit` is true. It exposes no hosted catalog,
+ * replica training or dubbing — those optional capability interfaces are simply
+ * not implemented (ISP).
+ */
+class KlingAvatarProvider {
+    constructor(modelKey = aiModels_1.EVideoGenModels.KLING_AVATAR) {
+        this.modelKey = modelKey;
+        this.engine = IAvatarVideoProvider_1.EAvatarEngine.KLING;
+        this.capabilities = KlingAvatarProvider.CAPABILITIES;
+        this.kling = new kling_service_1.KlingService();
+    }
+    async generate(req) {
+        if (req.mode !== "byo-media") {
+            throw new Error(`KlingAvatarProvider only supports byo-media requests (got "${req.mode}")`);
+        }
+        // Delegates to the existing Kling avatar path (routes on modelKey ===
+        // "kling-avatar" inside generateVideo, before any type-based dispatch — so
+        // `type` is intentionally omitted, matching the prior call site).
+        const result = await this.kling.generateVideo({
+            modelKey: this.modelKey,
+            inputImageUrl: req.faceImageUrl,
+            inputAudioUrl: req.audioUrl,
+            prompt: req.prompt,
+            mode: req.renderMode,
+        });
+        return { providerTaskId: result.task };
+    }
+    async checkStatus(query) {
+        const result = await this.kling.checkVideoStatus({
+            task: query.providerTaskId,
+            outputFilename: query.outputFilename,
+            outputFilePath: query.outputFilePath ?? DEFAULT_OUTPUT_PATH,
+            modelKey: this.modelKey,
+        });
+        return {
+            status: result.status,
+            videoUrl: result.videoUrl,
+            errorMessage: result.errorMessage,
+        };
+    }
+}
+exports.KlingAvatarProvider = KlingAvatarProvider;
+/** Static so callers can branch on capability without constructing (which
+ *  would require Kling API keys just to read the input mode). */
+KlingAvatarProvider.CAPABILITIES = {
+    inputMode: "byo-media",
+    nativeTts: false,
+    multiSceneSplit: true,
+};

package/lib/services/avatarGen/providers/tavusAvatarProvider.d.ts

@@ -0,0 +1,56 @@
+import { EVideoGenModels } from "../../../globals/aiModels";
+import { AvatarCapabilities, AvatarGenerateRequest, AvatarOption, AvatarStatusQuery, AvatarStatusResult, AvatarSubmitResult, ConsentRecord, EAvatarEngine, IAvatarVideoProvider, ISupportsHostedCatalog, ISupportsReplica, VoiceOption } from "../IAvatarVideoProvider";
+/**
+ * Tavus avatar engine — a HOSTED engine driven by a trained "replica"
+ * (Tavus's term for a likeness model). The caller supplies a replica_id + a
+ * script; Tavus synthesizes the voice (the replica's cloned voice) and lipsyncs
+ * natively. Tavus's differentiator is multilingual / dubbing — see the dubbing
+ * note at the bottom of this class.
+ *
+ * Contract (Tavus API, verified 2026-06-26 against docs.tavus.io):
+ *   • submit  : POST /v2/videos        { replica_id, script, video_name? }
+ *                                        → { video_id, status, hosted_url }
+ *   • status  : GET  /v2/videos/{id}    → { status: queued|generating|ready|
+ *                                            deleted|error, download_url,
+ *                                            stream_url, hosted_url, status_details }
+ *   • replicas: POST /v2/replicas       { train_video_url, consent_video_url?,
+ *                                          replica_name, callback_url? }
+ *                                        → { replica_id, status }
+ *               GET  /v2/replicas        → { data: [{ replica_id, replica_name,
+ *                                            status, thumbnail_video_url }] }
+ *   • auth    : x-api-key header
+ *
+ * For Tavus the hosted "avatar" IS the replica, so a hosted request maps
+ * `hostedAvatarId` → `replica_id` (`hostedVoiceId` is unused; the replica owns
+ * its voice). Standalone class — Tavus has no place in the generic video
+ * factory; avatar gen is its own concern (see IAvatarVideoProvider).
+ */
+export declare class TavusAvatarProvider implements IAvatarVideoProvider, ISupportsHostedCatalog, ISupportsReplica {
+    private readonly modelKey;
+    /** Static so callers can branch on capability without constructing (which
+     *  would require TAVUS_API_KEY just to read the input mode). */
+    static readonly CAPABILITIES: AvatarCapabilities;
+    readonly engine = EAvatarEngine.TAVUS;
+    readonly capabilities: AvatarCapabilities;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly submitTimeout;
+    private readonly statusTimeout;
+    constructor(modelKey?: EVideoGenModels);
+    generate(req: AvatarGenerateRequest): Promise<AvatarSubmitResult>;
+    checkStatus(query: AvatarStatusQuery): Promise<AvatarStatusResult>;
+    createReplica(trainingMediaUrl: string, consent: ConsentRecord): Promise<{
+        replicaId: string;
+    }>;
+    /** For Tavus the catalog of "avatars" is the account's trained replicas. */
+    listAvatars(): Promise<AvatarOption[]>;
+    /**
+     * Tavus voices are bound to the replica (its cloned voice), so there is no
+     * standalone voice catalog to pick from — return empty. Hosted requests leave
+     * `hostedVoiceId` unused for Tavus.
+     */
+    listVoices(): Promise<VoiceOption[]>;
+    private request;
+    private requestWithRetry;
+}
+//# sourceMappingURL=tavusAvatarProvider.d.ts.map

package/lib/services/avatarGen/providers/tavusAvatarProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tavusAvatarProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/avatarGen/providers/tavusAvatarProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACZ,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,mBACX,YAAW,oBAAoB,EAAE,sBAAsB,EAAE,gBAAgB;IAmBvE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjB3B;oEACgE;IAChE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAI9C;IAEF,QAAQ,CAAC,MAAM,uBAAuB;IACtC,QAAQ,CAAC,YAAY,qBAAoC;IAEzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAGrB,QAAQ,GAAE,eAA8C;IAQrE,QAAQ,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4BjE,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAiClE,aAAa,CACjB,gBAAgB,EAAE,MAAM,EACxB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA2BjC,4EAA4E;IACtE,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAgB5C;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YAM5B,OAAO;YA0BP,gBAAgB;CAiE/B"}

package/lib/services/avatarGen/providers/tavusAvatarProvider.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TavusAvatarProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+const aiModels_1 = require("../../../globals/aiModels");
+const types_1 = require("../../../globals/types");
+const logger_1 = require("../../../utils/logger");
+const IAvatarVideoProvider_1 = require("../IAvatarVideoProvider");
+/**
+ * Tavus avatar engine — a HOSTED engine driven by a trained "replica"
+ * (Tavus's term for a likeness model). The caller supplies a replica_id + a
+ * script; Tavus synthesizes the voice (the replica's cloned voice) and lipsyncs
+ * natively. Tavus's differentiator is multilingual / dubbing — see the dubbing
+ * note at the bottom of this class.
+ *
+ * Contract (Tavus API, verified 2026-06-26 against docs.tavus.io):
+ *   • submit  : POST /v2/videos        { replica_id, script, video_name? }
+ *                                        → { video_id, status, hosted_url }
+ *   • status  : GET  /v2/videos/{id}    → { status: queued|generating|ready|
+ *                                            deleted|error, download_url,
+ *                                            stream_url, hosted_url, status_details }
+ *   • replicas: POST /v2/replicas       { train_video_url, consent_video_url?,
+ *                                          replica_name, callback_url? }
+ *                                        → { replica_id, status }
+ *               GET  /v2/replicas        → { data: [{ replica_id, replica_name,
+ *                                            status, thumbnail_video_url }] }
+ *   • auth    : x-api-key header
+ *
+ * For Tavus the hosted "avatar" IS the replica, so a hosted request maps
+ * `hostedAvatarId` → `replica_id` (`hostedVoiceId` is unused; the replica owns
+ * its voice). Standalone class — Tavus has no place in the generic video
+ * factory; avatar gen is its own concern (see IAvatarVideoProvider).
+ */
+class TavusAvatarProvider {
+    constructor(modelKey = aiModels_1.EVideoGenModels.TAVUS_AVATAR) {
+        this.modelKey = modelKey;
+        this.engine = IAvatarVideoProvider_1.EAvatarEngine.TAVUS;
+        this.capabilities = TavusAvatarProvider.CAPABILITIES;
+        this.baseUrl = "https://tavusapi.com";
+        this.submitTimeout = 120000;
+        this.statusTimeout = 60000;
+        if (!process.env.TAVUS_API_KEY) {
+            throw new Error("Missing TAVUS_API_KEY in environment variables");
+        }
+        this.apiKey = process.env.TAVUS_API_KEY;
+    }
+    async generate(req) {
+        if (req.mode !== "hosted") {
+            throw new Error(`TavusAvatarProvider only supports hosted requests (got "${req.mode}")`);
+        }
+        const body = {
+            replica_id: req.hostedAvatarId, // Tavus: the hosted avatar IS the replica
+            script: req.script,
+            video_name: `vidspot-${req.hostedAvatarId}-${req.script.slice(0, 24)}`,
+        };
+        const data = await this.request("/v2/videos", "POST", body, this.submitTimeout);
+        const videoId = data?.video_id;
+        if (!videoId) {
+            throw new Error(`Tavus submit returned no video_id: ${JSON.stringify(data?.message ?? data)}`);
+        }
+        return { providerTaskId: videoId };
+    }
+    async checkStatus(query) {
+        const data = await this.requestWithRetry(`/v2/videos/${encodeURIComponent(query.providerTaskId)}`, "GET", undefined, this.statusTimeout);
+        // Tavus status enum: queued | generating | ready | deleted | error.
+        if (data?.status === "ready") {
+            return {
+                status: types_1.EVideoSceneStatus.COMPLETED,
+                // Prefer the direct download URL; fall back to stream/hosted.
+                videoUrl: data.download_url ?? data.stream_url ?? data.hosted_url,
+            };
+        }
+        if (data?.status === "error" || data?.status === "deleted") {
+            return {
+                status: types_1.EVideoSceneStatus.FAILED,
+                errorMessage: data.status_details ?? `Tavus render ${data.status}`,
+            };
+        }
+        return { status: types_1.EVideoSceneStatus.PENDING };
+    }
+    // ─── ISupportsReplica ─────────────────────────────────────────────────────
+    async createReplica(trainingMediaUrl, consent) {
+        const body = {
+            train_video_url: trainingMediaUrl,
+            replica_name: `vidspot-${consent.userId}-${consent.capturedAt}`,
+            // Tavus accepts a separate consent clip; we pass the same training media
+            // when no dedicated consent video exists (the statement is recorded in
+            // our own ConsentRecord audit trail regardless).
+            consent_video_url: trainingMediaUrl,
+        };
+        const data = await this.request("/v2/replicas", "POST", body, this.submitTimeout);
+        if (!data?.replica_id) {
+            throw new Error(`Tavus createReplica returned no replica_id: ${JSON.stringify(data)}`);
+        }
+        return { replicaId: data.replica_id };
+    }
+    // ─── ISupportsHostedCatalog ───────────────────────────────────────────────
+    /** For Tavus the catalog of "avatars" is the account's trained replicas. */
+    async listAvatars() {
+        const data = await this.requestWithRetry("/v2/replicas", "GET", undefined, this.statusTimeout);
+        return (data?.data ?? []).map((r) => ({
+            id: r.replica_id,
+            name: r.replica_name ?? r.replica_id,
+            previewUrl: r.thumbnail_video_url,
+        }));
+    }
+    /**
+     * Tavus voices are bound to the replica (its cloned voice), so there is no
+     * standalone voice catalog to pick from — return empty. Hosted requests leave
+     * `hostedVoiceId` unused for Tavus.
+     */
+    async listVoices() {
+        return [];
+    }
+    // ─── Transport ────────────────────────────────────────────────────────────
+    async request(endpoint, method, body, timeout = this.submitTimeout) {
+        const config = {
+            method,
+            url: `${this.baseUrl}${endpoint}`,
+            headers: {
+                "x-api-key": this.apiKey,
+                "Content-Type": "application/json",
+            },
+            timeout,
+            data: body,
+        };
+        const response = await axios_1.default.request(config);
+        if (response.status < 200 || response.status >= 300) {
+            throw new Error(`Tavus API Error: ${response.status} ${response.statusText} — ${JSON.stringify(response.data)}`);
+        }
+        return response.data;
+    }
+    async requestWithRetry(endpoint, method, body, timeout = this.statusTimeout, maxAttempts = 4) {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await this.request(endpoint, method, body, timeout);
+            }
+            catch (err) {
+                const e = err;
+                const httpStatus = e.response?.status;
+                const isTimeout = e.code === "ECONNABORTED" || (e.message?.includes("timeout") ?? false);
+                const isNetworkError = e.code === "ECONNRESET" ||
+                    e.code === "ECONNREFUSED" ||
+                    e.code === "ENOTFOUND" ||
+                    e.code === "ERR_NETWORK";
+                const isRateLimit = httpStatus === 429;
+                const isRetryable = isTimeout || isNetworkError || isRateLimit;
+                if (!isRetryable || attempt === maxAttempts) {
+                    logger_1.logger.error("Tavus request failed (non-retryable or max attempts)", {
+                        endpoint,
+                        attempt,
+                        maxAttempts,
+                        httpStatus,
+                        errorCode: e.code,
+                        errorMessage: e.message,
+                    });
+                    throw err;
+                }
+                const backoffMs = isRateLimit ? 10000 : 1000;
+                logger_1.logger.warn("Tavus request failed — retrying", {
+                    endpoint,
+                    attempt,
+                    maxAttempts,
+                    httpStatus,
+                    backoffMs,
+                });
+                await new Promise((r) => setTimeout(r, backoffMs));
+            }
+        }
+        throw new Error("Unreachable");
+    }
+}
+exports.TavusAvatarProvider = TavusAvatarProvider;
+/** Static so callers can branch on capability without constructing (which
+ *  would require TAVUS_API_KEY just to read the input mode). */
+TavusAvatarProvider.CAPABILITIES = {
+    inputMode: "hosted",
+    nativeTts: true,
+    multiSceneSplit: false,
+};

package/lib/services/demo/demoAuthor.d.ts

@@ -0,0 +1,45 @@
+import { LlmCaller } from "../agent/llmCaller";
+import { ModelChoice, ModelRouter } from "../agent/modelRouter";
+import { DemoAuthorInput } from "./demoAuthorPrompt";
+import { NormalizeResult } from "./demoAuthorNormalize";
+export interface DemoAuthorDeps {
+    /** LLM caller. Defaults to the host-wired dispatcher. */
+    llm?: LlmCaller;
+    /** Model router. Defaults to DEFAULT_MODEL_ROUTING. */
+    router?: ModelRouter;
+    /** Route the planner to the premium tier (Opus) for higher-fidelity authoring. */
+    premium?: boolean;
+    /** Sampling temperature. Creative-but-structured default. */
+    temperature?: number;
+    /** Max output tokens — a full DemoSpec with rich scenes can be large. */
+    maxTokens?: number;
+    /**
+     * Allow the planner to propose Layer-B `custom` scenes (with an `intent`
+     * brief). Threaded from the worker's `DEMO_CODEGEN_ENABLED` gate; default
+     * false, so the author never emits a `custom` scene the pipeline can't fill.
+     */
+    allowCustomScenes?: boolean;
+    /**
+     * Allow the planner to commission AI-generated media (`generatedAssets` +
+     * `gen://` refs). Default true; the worker passes false only under the
+     * DEMO_GEN_ASSETS_DISABLED kill-switch.
+     */
+    allowGeneratedAssets?: boolean;
+}
+export interface DemoAuthorResult extends NormalizeResult {
+    /** Model that produced the spec (primary or fallback). */
+    modelUsed: ModelChoice;
+    usedFallback?: boolean;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+}
+/**
+ * Author a render-ready DemoSpec from inputs. Pure orchestration: build the
+ * prompt, attach screenshots as vision, call `.structured(DemoSpec)`, then
+ * normalize. Throws if the caller is unconfigured or the model returns an
+ * unparseable / scene-less spec (the normalize pass is the last guard).
+ */
+export declare function authorDemoSpec(input: DemoAuthorInput, deps?: DemoAuthorDeps): Promise<DemoAuthorResult>;
+//# sourceMappingURL=demoAuthor.d.ts.map

package/lib/services/demo/demoAuthor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoAuthor.d.ts","sourceRoot":"","sources":["../../../src/services/demo/demoAuthor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EACL,eAAe,EAGhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAqB,MAAM,uBAAuB,CAAC;AAqB3E,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,uDAAuD;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,0DAA0D;IAC1D,SAAS,EAAE,WAAW,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAgD3B"}