@stabgan/openrouter-mcp-multimodal 2.0.0 → 3.1.0

package/dist/model-cache.d.ts

@@ -3,6 +3,7 @@ export interface OpenRouterModelRecord {
     name?: string;
     architecture?: {
         input_modalities?: string[];
+        output_modalities?: string[];
     };
     context_length?: number;
     [key: string]: unknown;
@@ -11,9 +12,16 @@ export declare class ModelCache {
     private static instance;
     private models;
     private fetchedAt;
+    private inflight;
     static getInstance(): ModelCache;
     isValid(): boolean;
     setModels(models: OpenRouterModelRecord[]): void;
+    /**
+     * Populate the cache using `fetcher` if stale, coalescing concurrent callers
+     * so only one request hits the upstream API per stale window. Callers that
+     * arrive while a populate is in flight await the same promise.
+     */
+    ensureFresh(fetcher: () => Promise<OpenRouterModelRecord[]>): Promise<void>;
     getAll(): OpenRouterModelRecord[];
     get(id: string): OpenRouterModelRecord | null;
     has(id: string): boolean;
@@ -22,6 +30,8 @@ export declare class ModelCache {
         provider?: string;
         capabilities?: {
             vision?: boolean;
+            audio?: boolean;
+            video?: boolean;
         };
         limit?: number;
     }): OpenRouterModelRecord[];

package/dist/model-cache.js

@@ -5,10 +5,12 @@ function getCacheTtlMs() {
     const n = parseInt(raw, 10);
     return Number.isFinite(n) && n > 0 ? n : 3600000;
 }
+const MAX_SEARCH_LIMIT = 50;
 export class ModelCache {
     static instance;
     models = {};
     fetchedAt = 0;
+    inflight = null;
     static getInstance() {
         return (ModelCache.instance ??= new ModelCache());
     }
@@ -19,6 +21,27 @@ export class ModelCache {
         this.models = Object.fromEntries(models.map((m) => [m.id, m]));
         this.fetchedAt = Date.now();
     }
+    /**
+     * Populate the cache using `fetcher` if stale, coalescing concurrent callers
+     * so only one request hits the upstream API per stale window. Callers that
+     * arrive while a populate is in flight await the same promise.
+     */
+    async ensureFresh(fetcher) {
+        if (this.isValid())
+            return;
+        if (this.inflight) {
+            await this.inflight;
+            return;
+        }
+        this.inflight = (async () => fetcher())();
+        try {
+            const models = await this.inflight;
+            this.setModels(models);
+        }
+        finally {
+            this.inflight = null;
+        }
+    }
     getAll() {
         return Object.values(this.models);
     }
@@ -41,6 +64,13 @@ export class ModelCache {
         if (params.capabilities?.vision) {
             results = results.filter((m) => m.architecture?.input_modalities?.includes('image'));
         }
-        return results.slice(0, params.limit ?? 10);
+        if (params.capabilities?.audio) {
+            results = results.filter((m) => m.architecture?.input_modalities?.includes('audio'));
+        }
+        if (params.capabilities?.video) {
+            results = results.filter((m) => m.architecture?.input_modalities?.includes('video'));
+        }
+        const limit = Math.min(Math.max(1, params.limit ?? 10), MAX_SEARCH_LIMIT);
+        return results.slice(0, limit);
     }
 }

package/dist/openrouter-api.d.ts

@@ -1,6 +1,60 @@
 import type { OpenRouterModelRecord } from './model-cache.js';
+declare function parseRetryAfter(headerValue: string | null): number | null;
+declare function backoffWithJitter(attempt: number, retryAfterMs: number | null): number;
+/**
+ * fetch() wrapper with retries on 429 / 5xx / network error.
+ *
+ * A fresh `AbortSignal.timeout(timeoutMs)` is created per attempt so retries
+ * each get a full timeout budget. Backoff honors `Retry-After` (seconds or
+ * HTTP-date) and applies jitter to avoid thundering-herd synchronization.
+ */
+declare function fetchWithRetry(url: string, init: Omit<RequestInit, 'signal'>, { retries, timeoutMs }?: {
+    retries?: number;
+    timeoutMs?: number;
+}): Promise<Response>;
 export declare class OpenRouterAPIClient {
     private apiKey;
     constructor(apiKey: string);
+    private authHeaders;
     getModels(): Promise<OpenRouterModelRecord[]>;
+    /** Submit a video-generation job. Returns the `{ id, polling_url, status }` envelope. */
+    submitVideoJob(body: Record<string, unknown>): Promise<VideoJobEnvelope>;
+    /** Poll a submitted video-generation job by id. */
+    pollVideoJob(id: string): Promise<VideoJobStatus>;
+    /**
+     * Download the generated video binary. Returns `{ buffer, contentType }`.
+     * This intentionally does NOT go through our SSRF-guarded `fetchHttpResource`
+     * because the URL is always OpenRouter itself (trusted origin) — and it can
+     * return arbitrarily large bodies that the caller bounds via
+     * `OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES`.
+     */
+    downloadVideoContent(id: string, index?: number, maxBytes?: number): Promise<{
+        buffer: Buffer;
+        contentType: string | null;
+    }>;
 }
+export interface VideoJobEnvelope {
+    id: string;
+    status?: VideoJobStatusName;
+    polling_url?: string;
+    [key: string]: unknown;
+}
+export type VideoJobStatusName = 'pending' | 'queued' | 'processing' | 'completed' | 'failed';
+export interface VideoJobStatus {
+    id: string;
+    status: VideoJobStatusName | string;
+    unsigned_urls?: string[];
+    error?: {
+        message?: string;
+        code?: string;
+    } | string;
+    usage?: Record<string, unknown>;
+    progress?: number;
+    [key: string]: unknown;
+}
+export declare const _internals: {
+    parseRetryAfter: typeof parseRetryAfter;
+    backoffWithJitter: typeof backoffWithJitter;
+    fetchWithRetry: typeof fetchWithRetry;
+};
+export {};

package/dist/openrouter-api.js

@@ -1,25 +1,63 @@
 const BASE_URL = 'https://openrouter.ai/api/v1';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const VIDEO_TIMEOUT_MS = 60_000;
+const MAX_BACKOFF_MS = 10_000;
 async function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
-async function fetchWithRetry(url, init, retries = 2) {
+function parseRetryAfter(headerValue) {
+    if (!headerValue)
+        return null;
+    const asInt = parseInt(headerValue, 10);
+    if (Number.isFinite(asInt) && asInt >= 0)
+        return asInt * 1000;
+    const asDate = Date.parse(headerValue);
+    if (Number.isFinite(asDate)) {
+        const delta = asDate - Date.now();
+        return delta > 0 ? delta : 0;
+    }
+    return null;
+}
+function backoffWithJitter(attempt, retryAfterMs) {
+    const base = 400 * (attempt + 1);
+    const target = Math.min(Math.max(base, retryAfterMs ?? 0), MAX_BACKOFF_MS);
+    const jitter = 0.5 + Math.random(); // 0.5x .. 1.5x
+    return Math.round(target * jitter);
+}
+/**
+ * fetch() wrapper with retries on 429 / 5xx / network error.
+ *
+ * A fresh `AbortSignal.timeout(timeoutMs)` is created per attempt so retries
+ * each get a full timeout budget. Backoff honors `Retry-After` (seconds or
+ * HTTP-date) and applies jitter to avoid thundering-herd synchronization.
+ */
+async function fetchWithRetry(url, init, { retries = 2, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
     let lastErr;
     for (let attempt = 0; attempt <= retries; attempt++) {
         try {
-            const res = await fetch(url, init);
+            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
             if (res.status === 429 || res.status >= 500) {
-                if (attempt < retries)
-                    await sleep(400 * (attempt + 1));
-                else
-                    return res;
-                continue;
+                if (attempt < retries) {
+                    const retryAfter = parseRetryAfter(res.headers.get('retry-after'));
+                    // Release the connection before retrying so undici/pool doesn't
+                    // keep it open while we sleep.
+                    try {
+                        await res.body?.cancel();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                    await sleep(backoffWithJitter(attempt, retryAfter));
+                    continue;
+                }
+                return res;
             }
             return res;
         }
         catch (e) {
             lastErr = e;
             if (attempt < retries)
-                await sleep(400 * (attempt + 1));
+                await sleep(backoffWithJitter(attempt, null));
         }
     }
     throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
@@ -29,14 +67,100 @@ export class OpenRouterAPIClient {
     constructor(apiKey) {
         this.apiKey = apiKey;
     }
+    authHeaders(extra) {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            'HTTP-Referer': 'https://github.com/stabgan/openrouter-mcp-multimodal',
+            'X-Title': 'openrouter-mcp-multimodal',
+            ...extra,
+        };
+    }
     async getModels() {
-        const res = await fetchWithRetry(`${BASE_URL}/models`, {
-            headers: { Authorization: `Bearer ${this.apiKey}` },
-            signal: AbortSignal.timeout(30000),
-        }, 2);
+        const res = await fetchWithRetry(`${BASE_URL}/models`, { headers: this.authHeaders() }, { retries: 2, timeoutMs: DEFAULT_TIMEOUT_MS });
         if (!res.ok)
             throw new Error(`Failed to fetch models: HTTP ${res.status}`);
         const data = (await res.json());
         return data.data ?? [];
     }
+    /** Submit a video-generation job. Returns the `{ id, polling_url, status }` envelope. */
+    async submitVideoJob(body) {
+        const res = await fetchWithRetry(`${BASE_URL}/videos`, {
+            method: 'POST',
+            headers: this.authHeaders({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body),
+        }, { retries: 2, timeoutMs: VIDEO_TIMEOUT_MS });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`POST /videos failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
+    /** Poll a submitted video-generation job by id. */
+    async pollVideoJob(id) {
+        const res = await fetchWithRetry(`${BASE_URL}/videos/${encodeURIComponent(id)}`, { headers: this.authHeaders() }, { retries: 2, timeoutMs: DEFAULT_TIMEOUT_MS });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`GET /videos/${id} failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
+    /**
+     * Download the generated video binary. Returns `{ buffer, contentType }`.
+     * This intentionally does NOT go through our SSRF-guarded `fetchHttpResource`
+     * because the URL is always OpenRouter itself (trusted origin) — and it can
+     * return arbitrarily large bodies that the caller bounds via
+     * `OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES`.
+     */
+    async downloadVideoContent(id, index = 0, maxBytes = 256 * 1024 * 1024) {
+        const url = `${BASE_URL}/videos/${encodeURIComponent(id)}/content?index=${index}`;
+        const res = await fetchWithRetry(url, { headers: this.authHeaders() }, { retries: 1, timeoutMs: VIDEO_TIMEOUT_MS * 2 });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`GET /videos/${id}/content failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        const declared = res.headers.get('content-length');
+        if (declared) {
+            const n = parseInt(declared, 10);
+            if (Number.isFinite(n) && n > maxBytes) {
+                throw new Error(`Generated video too large: ${n} bytes > ${maxBytes}`);
+            }
+        }
+        const reader = res.body?.getReader();
+        if (!reader) {
+            const buf = Buffer.from(await res.arrayBuffer());
+            if (buf.length > maxBytes)
+                throw new Error('Generated video too large');
+            return { buffer: buf, contentType: res.headers.get('content-type') };
+        }
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    /* ignore */
+                }
+                throw new Error('Generated video too large');
+            }
+            chunks.push(Buffer.from(value));
+        }
+        return { buffer: Buffer.concat(chunks), contentType: res.headers.get('content-type') };
+    }
+}
+async function safeReadText(res) {
+    try {
+        const t = await res.text();
+        return t.length > 500 ? t.slice(0, 500) + '…' : t;
+    }
+    catch {
+        return '';
+    }
 }
+// Exported for tests.
+export const _internals = { parseRetryAfter, backoffWithJitter, fetchWithRetry };

package/dist/tool-handlers/analyze-audio.d.ts

@@ -8,16 +8,12 @@ export declare function handleAnalyzeAudio(request: {
     params: {
         arguments: AnalyzeAudioToolRequest;
     };
-}, openai: OpenAI, defaultModel?: string): Promise<{
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
 }>;

package/dist/tool-handlers/analyze-audio.js

@@ -1,13 +1,32 @@
 import { prepareAudioData } from './audio-utils.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash';
 export async function handleAnalyzeAudio(request, openai, defaultModel) {
-    const { audio_path, question, model } = request.params.arguments;
+    const { audio_path, question, model } = request.params.arguments ?? { audio_path: '' };
     if (!audio_path) {
-        return { content: [{ type: 'text', text: 'audio_path is required.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'audio_path is required.');
     }
+    let audioData;
     try {
-        const audioData = await prepareAudioData(audio_path);
-        const completion = await openai.chat.completions.create({
+        audioData = await prepareAudioData(audio_path);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host'))
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        if (msg.toLowerCase().includes('too large')) {
+            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+        }
+        if (msg.toLowerCase().includes('unsupported')) {
+            return toolErrorFrom(ErrorCode.UNSUPPORTED_FORMAT, err);
+        }
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    let completion;
+    try {
+        completion = await openai.chat.completions.create({
             model: model || defaultModel || DEFAULT_MODEL,
             messages: [
                 {
@@ -25,10 +44,24 @@ export async function handleAnalyzeAudio(request, openai, defaultModel) {
                 },
             ],
         });
-        return { content: [{ type: 'text', text: completion.choices[0].message.content || '' }] };
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    catch (err) {
+        return classifyUpstreamError(err);
+    }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Audio model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
     }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
 }

package/dist/tool-handlers/analyze-image.d.ts

@@ -8,16 +8,12 @@ export declare function handleAnalyzeImage(request: {
     params: {
         arguments: AnalyzeImageToolRequest;
     };
-}, openai: OpenAI, defaultModel?: string): Promise<{
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: string;
+        type: "text";
         text: string;
     }[];
-    isError: boolean;
-} | {
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError?: undefined;
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
 }>;

package/dist/tool-handlers/analyze-image.js

@@ -1,13 +1,29 @@
 import { prepareImageUrl } from './image-utils.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
 export async function handleAnalyzeImage(request, openai, defaultModel) {
-    const { image_path, question, model } = request.params.arguments;
+    const { image_path, question, model } = request.params.arguments ?? { image_path: '' };
     if (!image_path) {
-        return { content: [{ type: 'text', text: 'image_path is required.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'image_path is required.');
     }
+    let imageUrl;
     try {
-        const imageUrl = await prepareImageUrl(image_path);
-        const completion = await openai.chat.completions.create({
+        imageUrl = await prepareImageUrl(image_path);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host'))
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        if (msg.toLowerCase().includes('too large')) {
+            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+        }
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    let completion;
+    try {
+        completion = await openai.chat.completions.create({
             model: model || defaultModel || DEFAULT_MODEL,
             messages: [
                 {
@@ -19,10 +35,24 @@ export async function handleAnalyzeImage(request, openai, defaultModel) {
                 },
             ],
         });
-        return { content: [{ type: 'text', text: completion.choices[0].message.content || '' }] };
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    catch (err) {
+        return classifyUpstreamError(err);
+    }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Vision model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
     }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
 }

package/dist/tool-handlers/analyze-video.d.ts

@@ -0,0 +1,19 @@
+import OpenAI from 'openai';
+export interface AnalyzeVideoToolRequest {
+    video_path: string;
+    question?: string;
+    model?: string;
+}
+export declare function handleAnalyzeVideo(request: {
+    params: {
+        arguments: AnalyzeVideoToolRequest;
+    };
+}, openai: OpenAI, defaultModel?: string): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: {
+        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
+    };
+}>;

package/dist/tool-handlers/analyze-video.js

@@ -0,0 +1,93 @@
+import { prepareVideoData } from './video-utils.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { logger } from '../logger.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
+/**
+ * Default model — `google/gemini-2.5-flash` has the widest video-input
+ * support on OpenRouter at time of writing. Override via env
+ * `OPENROUTER_DEFAULT_VIDEO_MODEL` or per-call `model`.
+ */
+const FALLBACK_DEFAULT_MODEL = 'google/gemini-2.5-flash';
+export async function handleAnalyzeVideo(request, openai, defaultModel) {
+    const { video_path, question, model } = request.params.arguments ?? {
+        video_path: '',
+    };
+    if (!video_path) {
+        return toolError(ErrorCode.INVALID_INPUT, 'video_path is required.');
+    }
+    const pickedModel = model ||
+        process.env.OPENROUTER_DEFAULT_VIDEO_MODEL ||
+        defaultModel ||
+        FALLBACK_DEFAULT_MODEL;
+    let videoData;
+    try {
+        videoData = await prepareVideoData(video_path);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host')) {
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        }
+        if (msg.includes('too large')) {
+            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+        }
+        if (msg.includes('Unsupported') || msg.includes('not a video')) {
+            return toolErrorFrom(ErrorCode.UNSUPPORTED_FORMAT, err);
+        }
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    let completion;
+    try {
+        logger.debug('analyze_video.submit', {
+            model: pickedModel,
+            format: videoData.format,
+            size_bytes: videoData.sizeBytes,
+        });
+        completion = await openai.chat.completions.create({
+            model: pickedModel,
+            messages: [
+                {
+                    role: 'user',
+                    content: [
+                        {
+                            type: 'text',
+                            text: question || 'Describe what happens in this video, step by step.',
+                        },
+                        {
+                            // The `video_url` content type is an OpenRouter extension; the
+                            // OpenAI SDK's typings don't know about it yet. See:
+                            // https://openrouter.ai/docs/guides/overview/multimodal/videos
+                            type: 'video_url',
+                            video_url: {
+                                url: `data:${videoData.mediaType};base64,${videoData.data}`,
+                            },
+                        },
+                    ],
+                },
+            ],
+        });
+    }
+    catch (err) {
+        logger.warn('analyze_video.error', {
+            err: err instanceof Error ? err.message : String(err),
+        });
+        return classifyUpstreamError(err);
+    }
+    const extracted = extractCompletionText(completion);
+    const cutoff = detectReasoningCutoff(extracted);
+    if (cutoff)
+        return cutoff;
+    if (!extracted.text) {
+        return toolError(ErrorCode.INTERNAL, 'Video model returned no textual content.', {
+            finish_reason: extracted.finishReason,
+        });
+    }
+    return {
+        content: [{ type: 'text', text: extracted.text }],
+        _meta: {
+            finish_reason: extracted.finishReason,
+            ...(toUsageMeta(extracted.usage) ?? {}),
+        },
+    };
+}

package/dist/tool-handlers/audio-utils.js

@@ -4,7 +4,7 @@
  */
 import path from 'path';
 import { promises as fs } from 'fs';
-import { readEnvInt, fetchHttpResource } from './fetch-utils.js';
+import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
 // Re-export for tests
 export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
@@ -89,19 +89,17 @@ function formatFromContentType(ct) {
 export async function prepareAudioData(source) {
     // --- data URL ---
     if (source.startsWith('data:')) {
-        const match = source.match(/^data:([^;]+);base64,(.+)$/);
-        if (!match)
+        const parsed = parseBase64DataUrl(source);
+        if (!parsed)
             throw new Error('Invalid data URL format');
-        const mime = match[1];
-        const b64 = match[2];
-        const format = mimeSubtypeToFormat(mime.split('/')[1] ?? '');
+        const format = mimeSubtypeToFormat(parsed.mediaType.split('/')[1] ?? '');
         if (!format) {
-            throw new Error(`Unsupported audio format from MIME: ${mime}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
+            throw new Error(`Unsupported audio format from MIME: ${parsed.mediaType}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
         }
-        const approxBytes = Math.ceil((b64.length * 3) / 4);
+        const approxBytes = Math.ceil((parsed.base64.length * 3) / 4);
         if (approxBytes > getMaxDataUrlBytes())
             throw new Error('Data URL too large');
-        return { data: b64, format };
+        return { data: parsed.base64, format };
     }
     // --- HTTP(S) URL ---
     if (source.startsWith('http://') || source.startsWith('https://')) {