vidspotai-shared 1.0.94 → 1.0.96

package/lib/services/avatarGen/IAvatarVideoProvider.d.ts

@@ -0,0 +1,136 @@
+import { EVideoSceneStatus, TVideoJobTask } from "../../globals/types";
+import { EVideoMode } from "../aiGen/types";
+/**
+ * Avatar video generation — a first-class provider abstraction, deliberately
+ * SEPARATE from the generic `BaseAiGenProviderService` (text/image → video).
+ *
+ * Why its own seam (SOLID):
+ *  - SRP: animating a presenter/script into a talking video is a different
+ *    responsibility from text/image→video generation. Each gets its own contract.
+ *  - ISP: avatar engines have different capabilities (hosted avatar catalogs,
+ *    trained replicas, dubbing). Those are NARROW optional interfaces below, so
+ *    no engine has to no-op methods it doesn't support.
+ *  - DIP: the worker's `AvatarJobProcessor` and the agent's avatar tool depend on
+ *    THIS interface, not on any concrete engine (Kling/HeyGen/Tavus).
+ *  - OCP: adding an engine = add a class + register it in the avatar factory,
+ *    with zero edits to the processor.
+ *
+ * Today `kling-avatar` is the only implementation (it adapts the shared Kling
+ * transport via `KlingAvatarProvider`). HeyGen/Tavus/Synthesia plug in here next.
+ */
+export declare enum EAvatarEngine {
+    KLING = "kling",
+    HEYGEN = "heygen",
+    TAVUS = "tavus",
+    SYNTHESIA = "synthesia"
+}
+/**
+ * Declares HOW an engine produces a talking video, so the orchestrator
+ * (AvatarJobProcessor) knows what to do around the call:
+ *  - inputMode "byo-media": caller supplies a face image; the AUDIO is produced
+ *    by us (TTS stays its own concern) and passed in. (Kling)
+ *  - inputMode "hosted": caller supplies a provider-hosted avatar + voice + a
+ *    script; the engine does its own TTS/lip-sync. (HeyGen/Tavus)
+ *  - nativeTts: false => the processor must run TTS first and pass `audioUrl`.
+ *  - multiSceneSplit: true => long audio is split into scenes + stitched (Kling);
+ *    false => the engine renders the whole script in one shot (HeyGen/Tavus).
+ */
+export interface AvatarCapabilities {
+    inputMode: "byo-media" | "hosted";
+    nativeTts: boolean;
+    multiSceneSplit: boolean;
+}
+/**
+ * Discriminated request. A provider accepts exactly one `mode` (the one its
+ * `capabilities.inputMode` declares); passing the other is a programmer error
+ * and providers throw.
+ */
+export type AvatarGenerateRequest = {
+    mode: "byo-media";
+    /** Presenter face still — the engine animates this image to lipsync the audio. */
+    faceImageUrl: string;
+    /** Public audio URL (we generated it via TTS, or the caller supplied it). */
+    audioUrl: string;
+    /** Optional motion/emotion hint passed through to the engine. */
+    prompt?: string;
+    /** std / pro etc. — maps to the engine's render quality mode. */
+    renderMode?: EVideoMode;
+} | {
+    mode: "hosted";
+    /** Provider-hosted avatar id (or trained replica id). */
+    hostedAvatarId: string;
+    /** Provider-hosted voice id. */
+    hostedVoiceId: string;
+    /** Script the engine will synthesize + lipsync natively. */
+    script: string;
+    /** BCP-47 locale for native TTS / dubbing. */
+    locale?: string;
+    renderMode?: EVideoMode;
+};
+export interface AvatarSubmitResult {
+    /** Provider-internal task id, polled via `checkStatus`. */
+    providerTaskId: TVideoJobTask;
+}
+export interface AvatarStatusQuery {
+    providerTaskId: TVideoJobTask;
+    /** Filename (no extension) used when stashing the finished video to storage. */
+    outputFilename: string;
+    /** Storage sub-path; defaults to the avatar bucket folder. */
+    outputFilePath?: string;
+}
+export interface AvatarStatusResult {
+    status: EVideoSceneStatus;
+    /** Present when status is COMPLETED. */
+    videoUrl?: string;
+    /** Present when status is FAILED. */
+    errorMessage?: string;
+}
+/**
+ * Core contract every avatar engine implements. Submit + poll only — TTS,
+ * scene-splitting, stitching, credits and retries live in the orchestrator.
+ */
+export interface IAvatarVideoProvider {
+    readonly engine: EAvatarEngine;
+    readonly capabilities: AvatarCapabilities;
+    generate(req: AvatarGenerateRequest): Promise<AvatarSubmitResult>;
+    checkStatus(query: AvatarStatusQuery): Promise<AvatarStatusResult>;
+}
+export interface AvatarOption {
+    id: string;
+    name: string;
+    previewUrl?: string;
+}
+export interface VoiceOption {
+    id: string;
+    name: string;
+    gender?: "male" | "female" | "neutral";
+    accent?: string;
+    previewUrl?: string;
+}
+export interface ConsentRecord {
+    /** Who consented (user id). */
+    userId: string;
+    /** Free-text or signed consent reference for likeness training. */
+    statement: string;
+    /** ISO timestamp the consent was captured. */
+    capturedAt: string;
+}
+/** Engine exposes a catalog of hosted avatars/voices (HeyGen, Tavus, Synthesia). */
+export interface ISupportsHostedCatalog {
+    listAvatars(): Promise<AvatarOption[]>;
+    listVoices(): Promise<VoiceOption[]>;
+}
+/** Engine can train a likeness replica from user media (HeyGen instant avatar, Tavus replica). */
+export interface ISupportsReplica {
+    createReplica(trainingMediaUrl: string, consent: ConsentRecord): Promise<{
+        replicaId: string;
+    }>;
+}
+/** Engine can dub an existing video into another language (Tavus — our multilingual wedge). */
+export interface ISupportsDubbing {
+    dub(videoUrl: string, targetLocale: string): Promise<AvatarSubmitResult>;
+}
+export declare function supportsHostedCatalog(p: IAvatarVideoProvider): p is IAvatarVideoProvider & ISupportsHostedCatalog;
+export declare function supportsReplica(p: IAvatarVideoProvider): p is IAvatarVideoProvider & ISupportsReplica;
+export declare function supportsDubbing(p: IAvatarVideoProvider): p is IAvatarVideoProvider & ISupportsDubbing;
+//# sourceMappingURL=IAvatarVideoProvider.d.ts.map

package/lib/services/avatarGen/IAvatarVideoProvider.d.ts.map

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

package/lib/services/avatarGen/IAvatarVideoProvider.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EAvatarEngine = void 0;
+exports.supportsHostedCatalog = supportsHostedCatalog;
+exports.supportsReplica = supportsReplica;
+exports.supportsDubbing = supportsDubbing;
+/**
+ * Avatar video generation — a first-class provider abstraction, deliberately
+ * SEPARATE from the generic `BaseAiGenProviderService` (text/image → video).
+ *
+ * Why its own seam (SOLID):
+ *  - SRP: animating a presenter/script into a talking video is a different
+ *    responsibility from text/image→video generation. Each gets its own contract.
+ *  - ISP: avatar engines have different capabilities (hosted avatar catalogs,
+ *    trained replicas, dubbing). Those are NARROW optional interfaces below, so
+ *    no engine has to no-op methods it doesn't support.
+ *  - DIP: the worker's `AvatarJobProcessor` and the agent's avatar tool depend on
+ *    THIS interface, not on any concrete engine (Kling/HeyGen/Tavus).
+ *  - OCP: adding an engine = add a class + register it in the avatar factory,
+ *    with zero edits to the processor.
+ *
+ * Today `kling-avatar` is the only implementation (it adapts the shared Kling
+ * transport via `KlingAvatarProvider`). HeyGen/Tavus/Synthesia plug in here next.
+ */
+var EAvatarEngine;
+(function (EAvatarEngine) {
+    EAvatarEngine["KLING"] = "kling";
+    EAvatarEngine["HEYGEN"] = "heygen";
+    EAvatarEngine["TAVUS"] = "tavus";
+    EAvatarEngine["SYNTHESIA"] = "synthesia";
+})(EAvatarEngine || (exports.EAvatarEngine = EAvatarEngine = {}));
+// ─── Type guards ─────────────────────────────────────────────────────────────
+function supportsHostedCatalog(p) {
+    return (typeof p.listAvatars === "function" &&
+        typeof p.listVoices === "function");
+}
+function supportsReplica(p) {
+    return typeof p.createReplica === "function";
+}
+function supportsDubbing(p) {
+    return typeof p.dub === "function";
+}

package/lib/services/avatarGen/avatarProviderFactory.d.ts

@@ -0,0 +1,18 @@
+import { EVideoGenModels } from "../../globals/aiModels";
+import { AvatarCapabilities, IAvatarVideoProvider } from "./IAvatarVideoProvider";
+/** True if `modelKey` is an avatar model handled by a dedicated avatar provider. */
+export declare function isAvatarModel(modelKey: EVideoGenModels): boolean;
+/** Capabilities for an avatar model, or undefined if it isn't an avatar model. */
+export declare function getAvatarCapabilities(modelKey: EVideoGenModels): AvatarCapabilities | undefined;
+/**
+ * True for "hosted" avatar engines (HeyGen/Tavus) — the engine owns TTS + lipsync
+ * from a script, so the orchestrator skips the byo-media (face image + audio)
+ * path. False for byo-media engines (Kling) and non-avatar models.
+ */
+export declare function isHostedAvatarModel(modelKey: EVideoGenModels): boolean;
+/**
+ * Resolve the avatar provider for a model key. Throws if the model isn't an
+ * avatar model (callers should gate on `isAvatarModel` or know the model type).
+ */
+export declare function getAvatarVideoProvider(modelKey: EVideoGenModels): IAvatarVideoProvider;
+//# sourceMappingURL=avatarProviderFactory.d.ts.map

package/lib/services/avatarGen/avatarProviderFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatarProviderFactory.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/avatarProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AA4ClF,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEhE;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,eAAe,GACxB,kBAAkB,GAAG,SAAS,CAEhC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,GACxB,oBAAoB,CAMtB"}

package/lib/services/avatarGen/avatarProviderFactory.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAvatarModel = isAvatarModel;
+exports.getAvatarCapabilities = getAvatarCapabilities;
+exports.isHostedAvatarModel = isHostedAvatarModel;
+exports.getAvatarVideoProvider = getAvatarVideoProvider;
+const aiModels_1 = require("../../globals/aiModels");
+const heygenAvatarProvider_1 = require("./providers/heygenAvatarProvider");
+const klingAvatarProvider_1 = require("./providers/klingAvatarProvider");
+const tavusAvatarProvider_1 = require("./providers/tavusAvatarProvider");
+const avatarProviderMap = {
+    [aiModels_1.EVideoGenModels.KLING_AVATAR]: (modelKey) => new klingAvatarProvider_1.KlingAvatarProvider(modelKey),
+    [aiModels_1.EVideoGenModels.HEYGEN_AVATAR]: (modelKey) => new heygenAvatarProvider_1.HeyGenAvatarProvider(modelKey),
+    [aiModels_1.EVideoGenModels.TAVUS_AVATAR]: (modelKey) => new tavusAvatarProvider_1.TavusAvatarProvider(modelKey),
+};
+/**
+ * Static capability lookup, keyed off each provider's `CAPABILITIES` constant —
+ * so orchestrators (the worker, controllers) can branch on input mode WITHOUT
+ * constructing a provider (construction needs the engine's API key, which would
+ * make a simple "is this hosted?" check fail when keys are absent). Single
+ * source of truth: each entry references the provider class's own static.
+ */
+const avatarCapabilityMap = {
+    [aiModels_1.EVideoGenModels.KLING_AVATAR]: klingAvatarProvider_1.KlingAvatarProvider.CAPABILITIES,
+    [aiModels_1.EVideoGenModels.HEYGEN_AVATAR]: heygenAvatarProvider_1.HeyGenAvatarProvider.CAPABILITIES,
+    [aiModels_1.EVideoGenModels.TAVUS_AVATAR]: tavusAvatarProvider_1.TavusAvatarProvider.CAPABILITIES,
+};
+/** True if `modelKey` is an avatar model handled by a dedicated avatar provider. */
+function isAvatarModel(modelKey) {
+    return modelKey in avatarProviderMap;
+}
+/** Capabilities for an avatar model, or undefined if it isn't an avatar model. */
+function getAvatarCapabilities(modelKey) {
+    return avatarCapabilityMap[modelKey];
+}
+/**
+ * True for "hosted" avatar engines (HeyGen/Tavus) — the engine owns TTS + lipsync
+ * from a script, so the orchestrator skips the byo-media (face image + audio)
+ * path. False for byo-media engines (Kling) and non-avatar models.
+ */
+function isHostedAvatarModel(modelKey) {
+    return avatarCapabilityMap[modelKey]?.inputMode === "hosted";
+}
+/**
+ * Resolve the avatar provider for a model key. Throws if the model isn't an
+ * avatar model (callers should gate on `isAvatarModel` or know the model type).
+ */
+function getAvatarVideoProvider(modelKey) {
+    const factory = avatarProviderMap[modelKey];
+    if (!factory) {
+        throw new Error(`No avatar provider registered for model: ${modelKey}`);
+    }
+    return factory(modelKey);
+}

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

@@ -0,0 +1,6 @@
+export * from "./IAvatarVideoProvider";
+export * from "./avatarProviderFactory";
+export * from "./providers/klingAvatarProvider";
+export * from "./providers/heygenAvatarProvider";
+export * from "./providers/tavusAvatarProvider";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/avatarGen/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC"}

package/lib/services/avatarGen/index.js

@@ -0,0 +1,21 @@
+"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("./IAvatarVideoProvider"), exports);
+__exportStar(require("./avatarProviderFactory"), exports);
+__exportStar(require("./providers/klingAvatarProvider"), exports);
+__exportStar(require("./providers/heygenAvatarProvider"), exports);
+__exportStar(require("./providers/tavusAvatarProvider"), exports);

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

@@ -0,0 +1,45 @@
+import { EVideoGenModels } from "../../../globals/aiModels";
+import { AvatarCapabilities, AvatarGenerateRequest, AvatarOption, AvatarStatusQuery, AvatarStatusResult, AvatarSubmitResult, EAvatarEngine, IAvatarVideoProvider, ISupportsHostedCatalog, VoiceOption } from "../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.
+ */
+export declare class HeyGenAvatarProvider implements IAvatarVideoProvider, ISupportsHostedCatalog {
+    private readonly modelKey;
+    /** Static so callers can branch on capability without constructing (which
+     *  would require HEYGEN_API_KEY just to read the input mode). */
+    static readonly CAPABILITIES: AvatarCapabilities;
+    readonly engine = EAvatarEngine.HEYGEN;
+    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>;
+    listAvatars(): Promise<AvatarOption[]>;
+    listVoices(): Promise<VoiceOption[]>;
+    private normalizeGender;
+    private request;
+    /** Retries transient network/timeout/429 failures with a small backoff. */
+    private requestWithRetry;
+}
+//# sourceMappingURL=heygenAvatarProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heygenAvatarProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/avatarGen/providers/heygenAvatarProvider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAI5D,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACZ,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,oBACX,YAAW,oBAAoB,EAAE,sBAAsB;IAmBrD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjB3B;qEACiE;IACjE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAI9C;IAEF,QAAQ,CAAC,MAAM,wBAAwB;IACvC,QAAQ,CAAC,YAAY,qBAAqC;IAE1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAW;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;gBAGrB,QAAQ,GAAE,eAA+C;IAQtE,QAAQ,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA6CjE,WAAW,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgClE,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAYtC,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAwB1C,OAAO,CAAC,eAAe;YAOT,OAAO;IA0BrB,2EAA2E;YAC7D,gBAAgB;CAmD/B"}

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,
+};