vidspotai-shared 1.0.95 → 1.0.97

package/lib/services/aiGen/providers/kling/klingStatus.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkTurboVideoStatus = checkTurboVideoStatus;
 exports.checkRegularVideoStatus = checkRegularVideoStatus;
 exports.checkAvatarVideoStatus = checkAvatarVideoStatus;
 const axios_1 = __importDefault(require("axios"));
@@ -11,6 +12,116 @@ const https_1 = __importDefault(require("https"));
 const types_1 = require("../../../../globals/types");
 const firebase_1 = require("../../../../libs/firebase");
 const logger_1 = require("../../../../utils/logger");
+/**
+ * Download a finished Kling video and re-host it in GCS, returning a signed
+ * URL. Bounded retry + IPv4 pinning: Kling's CDN hostnames frequently resolve
+ * to an IPv6 PoP that is dead or geo-blocked for us, which surfaces as
+ * AggregateError(ETIMEDOUT) with both happy-eyeballs sockets failing.
+ *
+ * Extracted from checkAvatarVideoStatus, which had the hardened version. The
+ * regular (v1) poller still has its own unretried copy inline — left alone
+ * deliberately so this change doesn't touch a working prod path; it can adopt
+ * this helper in a separate commit.
+ */
+async function stashVideoToGcs(videoUrl, outputFilePath, outputFilename, timeout, logContext) {
+    const file = (0, firebase_1.getBucket)().file(`${outputFilePath}/${outputFilename}.mp4`);
+    const maxAttempts = 3;
+    let lastErr;
+    let downloadHost = "unknown";
+    try {
+        downloadHost = new URL(videoUrl).host;
+    }
+    catch {
+        /* leave as unknown */
+    }
+    const v4Http = new http_1.default.Agent({ family: 4, keepAlive: true });
+    const v4Https = new https_1.default.Agent({ family: 4, keepAlive: true });
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const videoResp = await axios_1.default.get(videoUrl, {
+                responseType: "arraybuffer",
+                timeout,
+                httpAgent: v4Http,
+                httpsAgent: v4Https,
+            });
+            await file.save(Buffer.from(videoResp.data), { contentType: "video/mp4" });
+            const [signedUrl] = await file.getSignedUrl({
+                action: "read",
+                expires: "03-09-2491",
+            });
+            return signedUrl;
+        }
+        catch (err) {
+            lastErr = err;
+            const isErr = err instanceof Error;
+            logger_1.logger.warn("Kling post-success stash failed", {
+                ...logContext,
+                attempt,
+                maxAttempts,
+                downloadHost,
+                errName: isErr ? err.name : typeof err,
+                errCode: isErr ? err.code : undefined,
+                httpStatus: isErr ? err.response?.status : undefined,
+                msg: isErr ? err.message : String(err),
+            });
+            if (attempt < maxAttempts) {
+                await new Promise((r) => setTimeout(r, 2000 * 2 ** (attempt - 1)));
+            }
+        }
+    }
+    // Throw rather than returning FAILED: the generation SUCCEEDED and was
+    // billed; only our re-hosting failed. The outer TaskPoller retries the whole
+    // checkVideoStatus call with its own budget, so a transient GCS/CDN blip
+    // doesn't cost the user a video they already paid for.
+    throw lastErr instanceof Error
+        ? lastErr
+        : new Error(`Kling stash failed after ${maxAttempts} attempts`);
+}
+/**
+ * kling-3.0-turbo polling (Kling API 2.0). Separate from the v1 poller for
+ * three reasons, any one of which would break if the v1 path were reused:
+ *   • the endpoint is GET /tasks?task_ids=<id>, not /v1/videos/<kind>/<id>
+ *   • `data` is an ARRAY of tasks, not a single object
+ *   • success is spelled "succeeded" here and "succeed" on v1
+ * It also means turbo needs no endpoint probing — one call, no 404 fan-out.
+ */
+async function checkTurboVideoStatus(deps, { task, outputFilename, outputFilePath = "videos" }) {
+    const startTime = Date.now();
+    const result = await deps.request(`/tasks?task_ids=${encodeURIComponent(task)}`, "GET", undefined, undefined, undefined, "apiKey");
+    const taskData = result?.data?.[0];
+    logger_1.logger.info("Kling checkTurboVideoStatus polled", {
+        task,
+        durationMs: Date.now() - startTime,
+        status: taskData?.status,
+        statusMsg: taskData?.message || undefined,
+    });
+    if (!taskData) {
+        return {
+            status: types_1.EVideoSceneStatus.FAILED,
+            errorMessage: `Turbo task ${task} not found`,
+        };
+    }
+    if (taskData.status === "succeeded") {
+        const videoUrl = taskData.outputs?.find((o) => o.type === "video")?.url;
+        if (!videoUrl) {
+            return {
+                status: types_1.EVideoSceneStatus.FAILED,
+                errorMessage: "No video output in Kling turbo response",
+            };
+        }
+        const signedUrl = await stashVideoToGcs(videoUrl, outputFilePath, outputFilename, deps.generateTimeout, { task, surface: "turbo" });
+        return { videoUrl: signedUrl, status: types_1.EVideoSceneStatus.COMPLETED };
+    }
+    if (taskData.status === "failed") {
+        return {
+            status: types_1.EVideoSceneStatus.FAILED,
+            errorMessage: taskData.message ||
+                result.message ||
+                "Kling turbo task failed (no reason provided)",
+        };
+    }
+    return { status: types_1.EVideoSceneStatus.PENDING };
+}
 async function checkRegularVideoStatus(deps, { task, outputFilename, outputFilePath = "videos" }) {
     const startTime = Date.now();
     // Try each Kling status endpoint in order until one returns non-404.

package/lib/services/aiGen/providers/kling/types.d.ts

@@ -188,4 +188,75 @@ export interface KlingAvatarGenerateRequest {
     callback_url?: string;
     external_task_id?: string;
 }
+export type KlingTurboResolution = "720p" | "1080p";
+/** contents[] entry — API 2.0 folds prompt and image into one typed array. */
+export interface KlingTurboContent {
+    type: "prompt" | "first_frame";
+    /** Set when type === "prompt". Max 2500 chars. */
+    text?: string;
+    /** Set when type === "first_frame". */
+    url?: string;
+}
+export interface KlingTurboSettings {
+    resolution?: KlingTurboResolution;
+    aspect_ratio?: KlingAspectRatio;
+    /** 3–15s inclusive. */
+    duration?: number;
+}
+export interface KlingTurboOptions {
+    callback_url?: string;
+    external_task_id?: string;
+    watermark_info?: {
+        enabled: boolean;
+    };
+}
+/** T2V body — prompt is a top-level string on this endpoint. */
+export interface KlingTurboTextToVideoRequest {
+    prompt: string;
+    settings?: KlingTurboSettings;
+    options?: KlingTurboOptions;
+}
+/** I2V body — prompt AND image both travel inside contents[]. */
+export interface KlingTurboImageToVideoRequest {
+    contents: KlingTurboContent[];
+    settings?: KlingTurboSettings;
+    options?: KlingTurboOptions;
+}
+/**
+ * API 2.0 task status. Note "succeeded" — the v1 surface spells the same state
+ * "succeed". Reusing the v1 comparison here would never match, and the scene
+ * would poll until it timed out.
+ */
+export type KlingTurboTaskStatus = "submitted" | "processing" | "succeeded" | "failed";
+export interface KlingTurboOutput {
+    type: "video" | "image" | "audio" | "element" | "voice";
+    id?: string;
+    url?: string;
+    watermark_url?: string;
+    duration?: string;
+}
+export interface KlingTurboTask {
+    id: string;
+    status: KlingTurboTaskStatus;
+    /** Failure reason when status === "failed" (e.g. risk-control rejection). */
+    message?: string;
+    create_time?: number;
+    update_time?: number;
+    external_id?: string;
+    outputs?: KlingTurboOutput[];
+}
+/** Submit response — a single task object under `data`. */
+export interface KlingTurboSubmitResponse {
+    code: number;
+    message: string;
+    request_id: string;
+    data: KlingTurboTask;
+}
+/** GET /tasks response — `data` is an ARRAY (batch query is supported). */
+export interface KlingTurboTasksResponse {
+    code: number;
+    message: string;
+    request_id: string;
+    data: KlingTurboTask[];
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/services/aiGen/providers/kling/types.d.ts.map

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

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"}