@juspay/neurolink 9.64.0 → 9.65.0

package/dist/avatar/providers/HeyGenAvatar.js

@@ -0,0 +1,337 @@
+/**
+ * HeyGen Avatar Handler
+ *
+ * Async talking-head generation. Submits a video.generate request, polls
+ * the video status, downloads the result MP4.
+ *
+ * @module avatar/providers/HeyGenAvatar
+ * @see https://docs.heygen.com/reference/avatar-video
+ */
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { AVATAR_ERROR_CODES, AvatarError, } from "../../utils/avatarProcessor.js";
+import { logger } from "../../utils/logger.js";
+import { sanitizeForLog } from "../../utils/logSanitize.js";
+import { safeDownload } from "../../utils/safeFetch.js";
+import { MAX_VIDEO_BYTES } from "../../utils/sizeGuard.js";
+const DEFAULT_BASE_URL = "https://api.heygen.com/v2";
+const REQUEST_TIMEOUT_MS = 30_000;
+const POLL_INTERVAL_MS = 5_000;
+const TOTAL_TIMEOUT_MS = 5 * 60_000;
+/**
+ * HeyGen Avatar Handler.
+ *
+ * Auth: `X-API-Key: ${HEYGEN_API_KEY}`. The HeyGen API expects an
+ * `avatar_id` (HeyGen's own avatar catalog) — pass it via `options.voice`
+ * for legacy callers, or `options.avatarId` for explicit users.
+ */
+export class HeyGenAvatar {
+    maxAudioDurationSeconds = 300; // 5 minutes
+    supportedFormats = ["mp4"];
+    apiKey;
+    baseUrl;
+    constructor(apiKey) {
+        const resolved = (apiKey ?? process.env.HEYGEN_API_KEY ?? "").trim();
+        this.apiKey = resolved.length > 0 ? resolved : null;
+        this.baseUrl = (process.env.HEYGEN_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    }
+    isConfigured() {
+        return this.apiKey !== null;
+    }
+    async generate(options) {
+        if (!this.apiKey) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: "HEYGEN_API_KEY not configured",
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        if (!options.text && !options.audio) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.AUDIO_REQUIRED,
+                message: "HeyGen requires either `text` or `audio` to drive the avatar",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+            });
+        }
+        const startTime = Date.now();
+        const abortSignal = options.abortSignal;
+        const videoId = await this.submitVideo(options);
+        const videoUrl = await this.pollUntilComplete(videoId, abortSignal);
+        const buffer = await this.download(videoUrl);
+        const latency = Date.now() - startTime;
+        logger.info(`[HeyGenAvatar] Generated ${buffer.length} bytes in ${latency}ms — video ${videoId}`);
+        return {
+            buffer,
+            format: "mp4",
+            size: buffer.length,
+            provider: "heygen",
+            metadata: {
+                latency,
+                provider: "heygen",
+                jobId: videoId,
+            },
+        };
+    }
+    async submitVideo(options) {
+        const heyOpts = options;
+        const avatarId = heyOpts.avatarId ??
+            (typeof options.image === "string" &&
+                /^[a-zA-Z0-9_-]{20,}$/.test(options.image)
+                ? options.image // use image string as avatar_id when it looks like one
+                : undefined);
+        if (!avatarId) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                message: "HeyGen requires `avatarId` (HeyGen avatar catalog id). Pass via options.avatarId or as options.image with a valid HeyGen id.",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+            });
+        }
+        if (options.audio !== undefined) {
+            if (Buffer.isBuffer(options.audio)) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                    message: "HeyGen requires a publicly accessible audio URL; got a binary Buffer. Upload the audio to a hosted location and pass the HTTPS URL instead.",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                });
+            }
+            if (typeof options.audio !== "string" ||
+                !/^https?:\/\//i.test(options.audio)) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                    message: "HeyGen requires a publicly accessible HTTPS audio URL; got an unsupported audio input type. Upload the audio to a hosted location and pass the HTTPS URL instead.",
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                });
+            }
+        }
+        const voiceConfig = options.audio
+            ? {
+                type: "audio",
+                audio_url: options.audio,
+            }
+            : {
+                type: "text",
+                input_text: options.text,
+                voice_id: options.voice ?? "1bd001e7e50f421d891986aad5158bc8",
+            };
+        const body = {
+            video_inputs: [
+                {
+                    character: {
+                        type: "avatar",
+                        avatar_id: avatarId,
+                        avatar_style: "normal",
+                    },
+                    voice: voiceConfig,
+                    background: {
+                        type: "color",
+                        value: heyOpts.backgroundColor ?? "#FFFFFF",
+                    },
+                },
+            ],
+            dimension: {
+                width: heyOpts.width ?? 1280,
+                height: heyOpts.height ?? 720,
+            },
+        };
+        const response = await this.fetchWithTimeout(`${this.baseUrl}/video/generate`, {
+            method: "POST",
+            headers: {
+                "X-API-Key": this.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const raw = await response.text();
+            const retriable = response.status === 408 ||
+                response.status === 429 ||
+                response.status >= 500;
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                message: `HeyGen submit failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
+                category: retriable ? ErrorCategory.NETWORK : ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable,
+                context: { status: response.status },
+            });
+        }
+        const json = (await response.json());
+        const videoId = json.data?.video_id;
+        if (!videoId) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                message: "HeyGen submit response missing video_id",
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { response: json },
+            });
+        }
+        return videoId;
+    }
+    async pollUntilComplete(videoId, abortSignal) {
+        const startTime = Date.now();
+        // HeyGen status endpoint is on v1, not v2.
+        const statusBaseUrl = this.baseUrl.replace(/\/v2$/, "/v1");
+        while (Date.now() - startTime < TOTAL_TIMEOUT_MS) {
+            if (abortSignal?.aborted) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                    message: `HeyGen poll for video ${videoId} aborted by caller`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: false,
+                    context: { videoId },
+                });
+            }
+            const response = await this.fetchWithTimeout(`${statusBaseUrl}/video_status.get?video_id=${videoId}`, {
+                method: "GET",
+                headers: { "X-API-Key": this.apiKey },
+            }, abortSignal);
+            if (!response.ok) {
+                const raw = await response.text();
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                    message: `HeyGen poll failed: ${response.status} — ${sanitizeForLog(raw, 500)}`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: response.status >= 500,
+                    context: { status: response.status, videoId },
+                });
+            }
+            const data = (await response.json());
+            if (data.data?.status === "completed") {
+                const videoUrl = data.data.video_url;
+                if (!videoUrl) {
+                    throw new AvatarError({
+                        code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                        message: `HeyGen video ${videoId} completed but no URL returned`,
+                        category: ErrorCategory.EXECUTION,
+                        severity: ErrorSeverity.HIGH,
+                        retriable: false,
+                        context: { videoId, data },
+                    });
+                }
+                return videoUrl;
+            }
+            if (data.data?.status === "failed") {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                    message: `HeyGen video ${videoId} failed: ${data.data?.error?.message ?? "unknown"}`,
+                    category: ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                    context: { videoId, data },
+                });
+            }
+            // Abortable sleep.
+            await new Promise((resolve, reject) => {
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    reject(new AvatarError({
+                        code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                        message: `HeyGen poll for video ${videoId} aborted by caller`,
+                        category: ErrorCategory.NETWORK,
+                        severity: ErrorSeverity.MEDIUM,
+                        retriable: false,
+                        context: { videoId },
+                    }));
+                };
+                const timer = setTimeout(() => {
+                    abortSignal?.removeEventListener("abort", onAbort);
+                    resolve();
+                }, POLL_INTERVAL_MS);
+                abortSignal?.addEventListener("abort", onAbort, { once: true });
+            });
+        }
+        throw new AvatarError({
+            code: AVATAR_ERROR_CODES.POLL_TIMEOUT,
+            message: `HeyGen video ${videoId} did not complete within ${TOTAL_TIMEOUT_MS / 1000}s`,
+            category: ErrorCategory.TIMEOUT,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: true,
+            context: { videoId },
+        });
+    }
+    async download(url) {
+        try {
+            return await safeDownload(url, {
+                maxBytes: MAX_VIDEO_BYTES,
+                label: "HeyGen video",
+                timeoutMs: REQUEST_TIMEOUT_MS,
+            });
+        }
+        catch (err) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                message: `HeyGen video download rejected: ${err instanceof Error ? err.message : String(err)}`,
+                category: ErrorCategory.NETWORK,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { url },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+    }
+    async fetchWithTimeout(url, init, callerAbortSignal) {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, REQUEST_TIMEOUT_MS);
+        const onCallerAbort = () => controller.abort();
+        callerAbortSignal?.addEventListener("abort", onCallerAbort, { once: true });
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                // Check caller abort first — a cancelled request is not a timeout.
+                if (callerAbortSignal?.aborted) {
+                    throw new AvatarError({
+                        code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                        message: `HeyGen request to ${url} was aborted by the caller`,
+                        category: ErrorCategory.NETWORK,
+                        severity: ErrorSeverity.MEDIUM,
+                        retriable: false,
+                        originalError: err,
+                    });
+                }
+                if (timedOut) {
+                    throw new AvatarError({
+                        code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                        message: `HeyGen request to ${url} timed out after ${REQUEST_TIMEOUT_MS / 1000}s`,
+                        category: ErrorCategory.NETWORK,
+                        severity: ErrorSeverity.HIGH,
+                        retriable: true,
+                        originalError: err,
+                    });
+                }
+                // Generic abort (shouldn't happen, but surface it).
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                    message: `HeyGen request to ${url} was aborted`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: true,
+                    originalError: err,
+                });
+            }
+            throw err;
+        }
+        finally {
+            callerAbortSignal?.removeEventListener("abort", onCallerAbort);
+            clearTimeout(timeoutId);
+        }
+    }
+}

package/dist/avatar/providers/ReplicateAvatar.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Replicate Avatar Handler (MuseTalk default)
+ *
+ * Routes avatar / lip-sync generation through Replicate's universal
+ * prediction lifecycle. Default model is MuseTalk; other lip-sync models
+ * (SadTalker, Wav2Lip, etc.) can be selected via `options.model`.
+ *
+ * @module avatar/providers/ReplicateAvatar
+ * @see https://replicate.com/douwantech/musetalk
+ */
+import type { AvatarHandler, AvatarOptions, AvatarResult, AvatarVideoFormat } from "../../types/index.js";
+/**
+ * Replicate Avatar Handler.
+ *
+ * MuseTalk requires both `image` and `audio` inputs — `text`-only is not
+ * supported here (use D-ID for that, or chain TTS + this handler).
+ */
+export declare class ReplicateAvatar implements AvatarHandler {
+    readonly maxAudioDurationSeconds = 60;
+    readonly supportedFormats: readonly AvatarVideoFormat[];
+    isConfigured(): boolean;
+    generate(options: AvatarOptions): Promise<AvatarResult>;
+    private resolveBuffer;
+    /**
+     * Detect audio MIME subtype from magic bytes.
+     *
+     * - WAV : "RIFF" header (52 49 46 46)
+     * - MP3 : ID3 tag (49 44 33) or sync word 0xFF 0xFB/0xF3/0xF2
+     * - OGG : "OggS" capture pattern (4F 67 67 53)
+     * - M4A : "ftyp" box at offset 4 (common isom/M4A variant)
+     *
+     * Falls back to "mp3" when detection is inconclusive.
+     */
+    private detectAudioType;
+    private detectImageType;
+}

package/dist/avatar/providers/ReplicateAvatar.js

@@ -0,0 +1,267 @@
+/**
+ * Replicate Avatar Handler (MuseTalk default)
+ *
+ * Routes avatar / lip-sync generation through Replicate's universal
+ * prediction lifecycle. Default model is MuseTalk; other lip-sync models
+ * (SadTalker, Wav2Lip, etc.) can be selected via `options.model`.
+ *
+ * @module avatar/providers/ReplicateAvatar
+ * @see https://replicate.com/douwantech/musetalk
+ */
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { AVATAR_ERROR_CODES, AvatarError, } from "../../utils/avatarProcessor.js";
+import { logger } from "../../utils/logger.js";
+import { getReplicateAuth } from "../../adapters/replicate/auth.js";
+import { downloadPredictionOutput, predict, } from "../../adapters/replicate/predictionLifecycle.js";
+import { MAX_AUDIO_BYTES, MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, readBoundedBuffer, } from "../../utils/sizeGuard.js";
+import { assertSafeUrl } from "../../utils/ssrfGuard.js";
+const DEFAULT_MODEL = "douwantech/musetalk:5501004e78525e4bbd9fa20d1e75ad51fddce5a274bec07b9b16d685e34eeaf8";
+/**
+ * Replicate Avatar Handler.
+ *
+ * MuseTalk requires both `image` and `audio` inputs — `text`-only is not
+ * supported here (use D-ID for that, or chain TTS + this handler).
+ */
+export class ReplicateAvatar {
+    maxAudioDurationSeconds = 60;
+    supportedFormats = ["mp4"];
+    isConfigured() {
+        return getReplicateAuth() !== null;
+    }
+    async generate(options) {
+        const auth = getReplicateAuth();
+        if (!auth) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+                message: "REPLICATE_API_TOKEN not configured",
+                category: ErrorCategory.CONFIGURATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        if (!options.audio) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.AUDIO_REQUIRED,
+                message: "Replicate avatar handler (MuseTalk) requires `audio` (Buffer or path); text-only is not supported. Use D-ID for text-driven talks or chain TTS + Replicate.",
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+            });
+        }
+        const startTime = Date.now();
+        const model = options.model ?? DEFAULT_MODEL;
+        const imageBuffer = await this.resolveBuffer(options.image, MAX_IMAGE_BYTES, "Replicate avatar reference image");
+        const audioBuffer = await this.resolveBuffer(options.audio, MAX_AUDIO_BYTES, "Replicate avatar reference audio");
+        const imageDataUri = `data:image/${this.detectImageType(imageBuffer)};base64,${imageBuffer.toString("base64")}`;
+        const audioDataUri = `data:audio/${this.detectAudioType(audioBuffer)};base64,${audioBuffer.toString("base64")}`;
+        let prediction;
+        try {
+            prediction = await predict(auth, {
+                model,
+                input: {
+                    image: imageDataUri,
+                    audio: audioDataUri,
+                    bbox_shift: 0,
+                    fps: 25,
+                },
+            });
+        }
+        catch (err) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                message: `Replicate avatar generation failed: ${err instanceof Error ? err.message : String(err)}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.HIGH,
+                retriable: true,
+                context: { model },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+        let videoBuffer;
+        try {
+            videoBuffer = await downloadPredictionOutput(prediction, MAX_VIDEO_BYTES);
+        }
+        catch (err) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.GENERATION_FAILED,
+                message: `Replicate avatar download failed: ${err instanceof Error ? err.message : String(err)}`,
+                category: ErrorCategory.NETWORK,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: true,
+                context: { predictionId: prediction.id },
+                originalError: err instanceof Error ? err : undefined,
+            });
+        }
+        const latency = Date.now() - startTime;
+        logger.info(`[ReplicateAvatar] Generated ${videoBuffer.length} bytes in ${latency}ms — model ${model}`);
+        return {
+            buffer: videoBuffer,
+            format: "mp4",
+            size: videoBuffer.length,
+            provider: "replicate",
+            metadata: {
+                latency,
+                provider: "replicate",
+                model,
+                jobId: prediction.id,
+            },
+        };
+    }
+    async resolveBuffer(input, maxBytes = MAX_IMAGE_BYTES, label = "Replicate avatar input") {
+        if (Buffer.isBuffer(input)) {
+            if (input.length > maxBytes) {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                    message: `${label} too large: ${input.length} bytes exceeds ${maxBytes}`,
+                    category: ErrorCategory.VALIDATION,
+                    severity: ErrorSeverity.HIGH,
+                    retriable: false,
+                });
+            }
+            return input;
+        }
+        // Reject local file paths — only Buffer or HTTPS URLs are accepted.
+        if (!/^https:\/\//.test(input)) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                message: `Invalid input: expected Buffer or HTTPS URL, got string "${input}". Local file reads are not supported.`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+            });
+        }
+        try {
+            await assertSafeUrl(input);
+        }
+        catch (err) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                message: `Unsafe URL rejected: ${err instanceof Error ? err.message : String(err)}`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { url: input },
+            });
+        }
+        const FETCH_TIMEOUT_MS = 60_000;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        let r;
+        try {
+            r = await fetch(input, { signal: controller.signal });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new AvatarError({
+                    code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                    message: `Replicate avatar input fetch timed out after ${FETCH_TIMEOUT_MS / 1000}s: ${input}`,
+                    category: ErrorCategory.NETWORK,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: true,
+                });
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!r.ok) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                message: `Failed to fetch ${input}: ${r.status}`,
+                category: ErrorCategory.NETWORK,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: r.status >= 500,
+            });
+        }
+        try {
+            return await readBoundedBuffer(r, maxBytes, label);
+        }
+        catch (err) {
+            throw new AvatarError({
+                code: AVATAR_ERROR_CODES.INVALID_INPUT,
+                message: `${label} too large: ${err instanceof Error ? err.message : String(err)}`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: { url: input },
+            });
+        }
+    }
+    /**
+     * Detect audio MIME subtype from magic bytes.
+     *
+     * - WAV : "RIFF" header (52 49 46 46)
+     * - MP3 : ID3 tag (49 44 33) or sync word 0xFF 0xFB/0xF3/0xF2
+     * - OGG : "OggS" capture pattern (4F 67 67 53)
+     * - M4A : "ftyp" box at offset 4 (common isom/M4A variant)
+     *
+     * Falls back to "mp3" when detection is inconclusive.
+     */
+    detectAudioType(buffer) {
+        if (buffer.length < 4) {
+            return "mp3";
+        }
+        // WAV: starts with RIFF
+        if (buffer[0] === 0x52 &&
+            buffer[1] === 0x49 &&
+            buffer[2] === 0x46 &&
+            buffer[3] === 0x46) {
+            return "wav";
+        }
+        // OGG: starts with OggS
+        if (buffer[0] === 0x4f &&
+            buffer[1] === 0x67 &&
+            buffer[2] === 0x67 &&
+            buffer[3] === 0x53) {
+            return "ogg";
+        }
+        // MP3: ID3 header
+        if (buffer[0] === 0x49 && buffer[1] === 0x44 && buffer[2] === 0x33) {
+            return "mp3";
+        }
+        // MP3: MPEG sync word (0xFF 0xE0–0xFF)
+        if (buffer[0] === 0xff && (buffer[1] & 0xe0) === 0xe0) {
+            return "mpeg";
+        }
+        // M4A / AAC: "ftyp" box at offset 4
+        if (buffer.length >= 8 &&
+            buffer[4] === 0x66 &&
+            buffer[5] === 0x74 &&
+            buffer[6] === 0x79 &&
+            buffer[7] === 0x70) {
+            return "mp4";
+        }
+        return "mp3";
+    }
+    detectImageType(buffer) {
+        if (buffer.length < 4) {
+            return "jpeg";
+        }
+        if (buffer[0] === 0x89 && buffer[1] === 0x50) {
+            return "png";
+        }
+        if (buffer[0] === 0xff && buffer[1] === 0xd8) {
+            return "jpeg";
+        }
+        // RIFF container: disambiguate WebP (WEBP at offset 8) from WAV (WAVE at
+        // offset 8) so audio data passed as image is not silently misidentified.
+        if (buffer.length >= 12 &&
+            buffer[0] === 0x52 &&
+            buffer[1] === 0x49 &&
+            buffer[2] === 0x46 &&
+            buffer[3] === 0x46) {
+            // "WEBP" → image/webp
+            if (buffer[8] === 0x57 &&
+                buffer[9] === 0x45 &&
+                buffer[10] === 0x42 &&
+                buffer[11] === 0x50) {
+                return "webp";
+            }
+            // Any other RIFF type (e.g. WAVE) is not a valid image → fall through to
+            // the default so the caller's validation can flag the wrong content type.
+            return "jpeg";
+        }
+        return "jpeg";
+    }
+}