@sudobility/shapeshyft_engine 1.0.0

package/dist/lib/media-constants.js

@@ -0,0 +1,166 @@
+/**
+ * Media constants for multimodal support.
+ * Single source of truth for MIME types, size limits, and validation.
+ */
+// =============================================================================
+// MIME Type Allowlists
+// =============================================================================
+/** Allowed MIME types per media type (directly supported by LLMs) */
+export const ALLOWED_MIME_TYPES = {
+    image: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+    audio: [
+        "audio/mp3",
+        "audio/mpeg",
+        "audio/wav",
+        "audio/ogg",
+        "audio/flac",
+        "audio/m4a",
+    ],
+    video: ["video/mp4", "video/webm", "video/quicktime"],
+};
+/** MIME types that can be converted to supported formats */
+export const CONVERTIBLE_MIME_TYPES = {
+    image: [
+        "image/svg+xml",
+        "image/tiff",
+        "image/bmp",
+        "image/heic",
+        "image/heif",
+        "image/avif",
+    ],
+    audio: [],
+    video: [],
+};
+/** All accepted MIME types (allowed + convertible) */
+export const ACCEPTED_MIME_TYPES = {
+    image: [...ALLOWED_MIME_TYPES.image, ...CONVERTIBLE_MIME_TYPES.image],
+    audio: [...ALLOWED_MIME_TYPES.audio, ...CONVERTIBLE_MIME_TYPES.audio],
+    video: [...ALLOWED_MIME_TYPES.video, ...CONVERTIBLE_MIME_TYPES.video],
+};
+// =============================================================================
+// Provider-Specific Audio Formats (Single Source of Truth)
+// =============================================================================
+/** OpenAI only supports mp3/wav for audio input */
+export const OPENAI_AUDIO_INPUT_MIMES = [
+    "audio/mp3",
+    "audio/mpeg",
+    "audio/wav",
+];
+/** Gemini supports more audio formats */
+export const GEMINI_AUDIO_INPUT_MIMES = [
+    "audio/mp3",
+    "audio/mpeg",
+    "audio/wav",
+    "audio/ogg",
+    "audio/flac",
+];
+/** Map MIME types to OpenAI format strings */
+export const OPENAI_MIME_TO_FORMAT = {
+    "audio/mp3": "mp3",
+    "audio/mpeg": "mp3", // mpeg is mp3
+    "audio/wav": "wav",
+};
+/**
+ * Get provider-specific supported audio formats
+ */
+export function getProviderAudioFormats(provider) {
+    switch (provider) {
+        case "openai":
+            return OPENAI_AUDIO_INPUT_MIMES;
+        case "gemini":
+            return GEMINI_AUDIO_INPUT_MIMES;
+        default:
+            // Other providers: allow all formats in global allowlist
+            return ALLOWED_MIME_TYPES.audio;
+    }
+}
+/**
+ * Convert MIME type to OpenAI format string.
+ * Throws if the format is not supported by OpenAI.
+ */
+export function getOpenAIAudioFormat(mimeType) {
+    const format = OPENAI_MIME_TO_FORMAT[mimeType];
+    if (!format) {
+        throw new Error(`OpenAI does not support audio format: ${mimeType}. ` +
+            `Supported: ${OPENAI_AUDIO_INPUT_MIMES.join(", ")}`);
+    }
+    return format;
+}
+// =============================================================================
+// Size Limits
+// =============================================================================
+/** Size limits in bytes per media type */
+export const SIZE_LIMITS = {
+    image: 20 * 1024 * 1024, // 20 MB
+    audio: 25 * 1024 * 1024, // 25 MB
+    video: 10 * 1024 * 1024, // 10 MB (base64 only, URLs handled by provider)
+};
+// =============================================================================
+// Regex Patterns
+// =============================================================================
+/**
+ * Data URL pattern for base64-encoded media.
+ * Captures: [1] full MIME type, [2] media category, [3] base64 data
+ */
+export const DATA_URL_REGEX = /^data:((image|audio|video)\/[\w+-]+);base64,(.+)$/;
+/**
+ * Provider-native URL pattern (gs:// for Gemini).
+ * SECURITY: Only allow gs:// URLs to prevent SSRF.
+ */
+export const PROVIDER_URL_REGEX = /^gs:\/\/[\w-]+\/.+$/;
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+/**
+ * Check if a MIME type is allowed for a given media type
+ */
+export function isAllowedMimeType(type, mimeType) {
+    return ALLOWED_MIME_TYPES[type]?.includes(mimeType) ?? false;
+}
+/**
+ * Get the size limit for a media type
+ */
+export function getSizeLimit(type) {
+    return SIZE_LIMITS[type] ?? 0;
+}
+/**
+ * Infer media type from MIME type string
+ */
+export function inferMediaTypeFromMime(mimeType) {
+    if (mimeType.startsWith("image/"))
+        return "image";
+    if (mimeType.startsWith("audio/"))
+        return "audio";
+    if (mimeType.startsWith("video/"))
+        return "video";
+    return undefined;
+}
+/**
+ * Infer MIME type from file extension in URL
+ */
+export function inferMimeFromUrl(url) {
+    const extensionMatch = url.match(/\.(\w+)(?:\?|$)/);
+    if (!extensionMatch)
+        return undefined;
+    const ext = extensionMatch[1].toLowerCase();
+    const mimeMap = {
+        // Images
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        png: "image/png",
+        gif: "image/gif",
+        webp: "image/webp",
+        // Audio
+        mp3: "audio/mp3",
+        wav: "audio/wav",
+        ogg: "audio/ogg",
+        flac: "audio/flac",
+        m4a: "audio/m4a",
+        // Video
+        mp4: "video/mp4",
+        webm: "video/webm",
+        mov: "video/quicktime",
+    };
+    return mimeMap[ext];
+}
+//# sourceMappingURL=media-constants.js.map

package/dist/lib/media-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-constants.js","sourceRoot":"","sources":["../../src/lib/media-constants.ts"],"names":[],"mappings":"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"}

package/dist/lib/media-conversion.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Media conversion utilities for converting unsupported image formats to supported ones.
+ * Used to convert SVG and other formats to PNG before sending to LLM.
+ */
+import type { MediaContent } from "../types/index.js";
+/**
+ * Check if a MIME type needs conversion
+ */
+export declare function needsConversion(mimeType: string): boolean;
+/**
+ * Check if a MIME type is convertible (but not currently supported)
+ */
+export declare function isConvertibleMimeType(mimeType: string): boolean;
+/**
+ * Convert an image buffer to PNG using sharp
+ */
+export declare function convertToPng(inputBuffer: Buffer, mimeType: string): Promise<Buffer>;
+/**
+ * Convert a base64-encoded image to PNG
+ * Returns the new base64 data and MIME type
+ */
+export declare function convertBase64ToPng(base64Data: string, mimeType: string): Promise<{
+    data: string;
+    mimeType: string;
+}>;
+/**
+ * Convert media content if needed.
+ * Returns the original or converted media.
+ */
+export declare function convertMediaIfNeeded(media: MediaContent): Promise<MediaContent>;
+/**
+ * Convert all media in an array if needed.
+ * Returns a new array with converted media.
+ */
+export declare function convertAllMediaIfNeeded(mediaArray: MediaContent[]): Promise<MediaContent[]>;
+//# sourceMappingURL=media-conversion.d.ts.map

package/dist/lib/media-conversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-conversion.d.ts","sourceRoot":"","sources":["../../src/lib/media-conversion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAO7C;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,YAAY,CAAC,CAmCvB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,YAAY,EAAE,GACzB,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB"}

package/dist/lib/media-conversion.js

@@ -0,0 +1,87 @@
+/**
+ * Media conversion utilities for converting unsupported image formats to supported ones.
+ * Used to convert SVG and other formats to PNG before sending to LLM.
+ */
+import sharp from "sharp";
+import { ALLOWED_MIME_TYPES, CONVERTIBLE_MIME_TYPES } from "./media-constants.js";
+/**
+ * Check if a MIME type needs conversion
+ */
+export function needsConversion(mimeType) {
+    // If already supported, no conversion needed
+    if (ALLOWED_MIME_TYPES.image.includes(mimeType)) {
+        return false;
+    }
+    // Check if it's a convertible format
+    return CONVERTIBLE_MIME_TYPES.image.includes(mimeType);
+}
+/**
+ * Check if a MIME type is convertible (but not currently supported)
+ */
+export function isConvertibleMimeType(mimeType) {
+    return CONVERTIBLE_MIME_TYPES.image.includes(mimeType);
+}
+/**
+ * Convert an image buffer to PNG using sharp
+ */
+export async function convertToPng(inputBuffer, mimeType) {
+    let sharpInstance = sharp(inputBuffer);
+    // For SVG, we need to handle it specially with density for better quality
+    if (mimeType === "image/svg+xml") {
+        // Re-create sharp instance with density option for SVG
+        sharpInstance = sharp(inputBuffer, { density: 300 });
+    }
+    // Convert to PNG
+    return sharpInstance.png().toBuffer();
+}
+/**
+ * Convert a base64-encoded image to PNG
+ * Returns the new base64 data and MIME type
+ */
+export async function convertBase64ToPng(base64Data, mimeType) {
+    const inputBuffer = Buffer.from(base64Data, "base64");
+    const outputBuffer = await convertToPng(inputBuffer, mimeType);
+    return {
+        data: outputBuffer.toString("base64"),
+        mimeType: "image/png",
+    };
+}
+/**
+ * Convert media content if needed.
+ * Returns the original or converted media.
+ */
+export async function convertMediaIfNeeded(media) {
+    // Only convert images
+    if (media.type !== "image") {
+        return media;
+    }
+    // Only convert if format is base64 (can't convert URLs)
+    if (media.format !== "base64") {
+        return media;
+    }
+    // Check if conversion is needed
+    if (!needsConversion(media.mimeType)) {
+        return media;
+    }
+    try {
+        const { data, mimeType } = await convertBase64ToPng(media.data, media.mimeType);
+        return {
+            ...media,
+            data,
+            mimeType,
+        };
+    }
+    catch (error) {
+        // If conversion fails, throw with helpful message
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        throw new Error(`Failed to convert ${media.mimeType} to PNG: ${errorMessage}`);
+    }
+}
+/**
+ * Convert all media in an array if needed.
+ * Returns a new array with converted media.
+ */
+export async function convertAllMediaIfNeeded(mediaArray) {
+    return Promise.all(mediaArray.map(convertMediaIfNeeded));
+}
+//# sourceMappingURL=media-conversion.js.map

package/dist/lib/media-conversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-conversion.js","sourceRoot":"","sources":["../../src/lib/media-conversion.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAElF;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,6CAA6C;IAC7C,IAAI,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,qCAAqC;IACrC,OAAO,sBAAsB,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,sBAAsB,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,WAAmB,EACnB,QAAgB;IAEhB,IAAI,aAAa,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;IAEvC,0EAA0E;IAC1E,IAAI,QAAQ,KAAK,eAAe,EAAE,CAAC;QACjC,uDAAuD;QACvD,aAAa,GAAG,KAAK,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,iBAAiB;IACjB,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAkB,EAClB,QAAgB;IAEhB,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,MAAM,YAAY,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC/D,OAAO;QACL,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACrC,QAAQ,EAAE,WAAW;KACtB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAmB;IAEnB,sBAAsB;IACtB,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,wDAAwD;IACxD,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gCAAgC;IAChC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM,kBAAkB,CACjD,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,QAAQ,CACf,CAAC;QAEF,OAAO;YACL,GAAG,KAAK;YACR,IAAI;YACJ,QAAQ;SACT,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kDAAkD;QAClD,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,qBAAqB,KAAK,CAAC,QAAQ,YAAY,YAAY,EAAE,CAC9D,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,UAA0B;IAE1B,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/lib/media-utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Media utilities for extracting and parsing media from input data.
+ */
+import type { MediaContent } from "../types/index.js";
+export interface ExtractedMedia {
+    /** Input data with media fields replaced by placeholders */
+    cleanedInput: Record<string, unknown>;
+    /** Extracted media content */
+    media: MediaContent[];
+}
+export interface ExtractionResult {
+    result?: ExtractedMedia;
+    error?: string;
+}
+interface ParseResult {
+    media?: MediaContent;
+    error?: string;
+}
+/**
+ * Parse a data URL into MediaContent.
+ * Returns error if invalid or unsupported.
+ */
+export declare function parseDataUrl(value: string, fieldName?: string): ParseResult;
+/**
+ * Parse a provider URL (gs:// for Gemini).
+ * Returns error if URL is not allowed (SSRF prevention).
+ */
+export declare function parseProviderUrl(value: string, mimeType?: string, fieldName?: string): ParseResult;
+/**
+ * Extract media from input data.
+ * Returns cleaned input (with placeholders) and extracted media array.
+ */
+export declare function extractMediaFromInput(input: Record<string, unknown>): ExtractionResult;
+export {};
+//# sourceMappingURL=media-utils.d.ts.map

package/dist/lib/media-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-utils.d.ts","sourceRoot":"","sources":["../../src/lib/media-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,mBAAmB,CAAC;AAcjE,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,8BAA8B;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAiC3E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,WAAW,CAoCb;AAiGD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,gBAAgB,CAgBlB"}

package/dist/lib/media-utils.js

@@ -0,0 +1,173 @@
+/**
+ * Media utilities for extracting and parsing media from input data.
+ */
+import { DATA_URL_REGEX, PROVIDER_URL_REGEX, ACCEPTED_MIME_TYPES, SIZE_LIMITS, inferMimeFromUrl, inferMediaTypeFromMime, } from "./media-constants.js";
+// =============================================================================
+// Data URL Parsing
+// =============================================================================
+/**
+ * Parse a data URL into MediaContent.
+ * Returns error if invalid or unsupported.
+ */
+export function parseDataUrl(value, fieldName) {
+    const match = value.match(DATA_URL_REGEX);
+    if (!match) {
+        return {}; // Not a data URL
+    }
+    const mimeType = match[1];
+    const mediaCategory = match[2];
+    const data = match[3];
+    // Validate MIME type is in allowlist (includes convertible types)
+    if (!ACCEPTED_MIME_TYPES[mediaCategory]?.includes(mimeType)) {
+        return { error: `Unsupported MIME type: ${mimeType}` };
+    }
+    // Validate size (base64 is ~33% larger than binary)
+    const estimatedSize = (data.length * 3) / 4;
+    const limit = SIZE_LIMITS[mediaCategory];
+    if (estimatedSize > limit) {
+        return {
+            error: `${mediaCategory} exceeds ${limit / 1024 / 1024}MB limit`,
+        };
+    }
+    return {
+        media: {
+            type: mediaCategory,
+            format: "base64",
+            mimeType,
+            data,
+            fieldName,
+        },
+    };
+}
+/**
+ * Parse a provider URL (gs:// for Gemini).
+ * Returns error if URL is not allowed (SSRF prevention).
+ */
+export function parseProviderUrl(value, mimeType, fieldName) {
+    // SECURITY: Reject http/https URLs to prevent SSRF
+    if (value.startsWith("http://") || value.startsWith("https://")) {
+        return {
+            error: "HTTP/HTTPS URLs not allowed. Use base64 or gs:// (Gemini only)",
+        };
+    }
+    // Only allow gs:// URLs for Gemini
+    if (!PROVIDER_URL_REGEX.test(value)) {
+        return {}; // Not a URL we handle
+    }
+    // Infer MIME type from URL if not provided
+    const inferredMime = mimeType ?? inferMimeFromUrl(value);
+    if (!inferredMime) {
+        return {
+            error: "Cannot infer MIME type from URL, please specify contentMediaType in schema",
+        };
+    }
+    const mediaType = inferMediaTypeFromMime(inferredMime);
+    if (!mediaType) {
+        return { error: `Unknown media type for MIME: ${inferredMime}` };
+    }
+    return {
+        media: {
+            type: mediaType,
+            format: "url",
+            mimeType: inferredMime,
+            data: value,
+            fieldName,
+        },
+    };
+}
+// =============================================================================
+// Media Extraction
+// =============================================================================
+/**
+ * Check if a value looks like media (data URL or provider URL).
+ */
+function isMediaValue(value) {
+    if (typeof value !== "string")
+        return false;
+    return DATA_URL_REGEX.test(value) || PROVIDER_URL_REGEX.test(value);
+}
+/**
+ * Recursively extract media from input data.
+ * Replaces media fields with placeholders like "[Image: fieldName]".
+ */
+function extractFromObject(data, media, errors, path = "") {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const fieldPath = path ? `${path}.${key}` : key;
+        if (isMediaValue(value)) {
+            // Try to parse as data URL first
+            let parseResult = parseDataUrl(value, fieldPath);
+            // If not a data URL, try provider URL
+            if (!parseResult.media && !parseResult.error) {
+                parseResult = parseProviderUrl(value, undefined, fieldPath);
+            }
+            if (parseResult.error) {
+                errors.push(`${fieldPath}: ${parseResult.error}`);
+                result[key] = value; // Keep original on error
+            }
+            else if (parseResult.media) {
+                media.push(parseResult.media);
+                // Replace with placeholder
+                const typeLabel = parseResult.media.type.charAt(0).toUpperCase() +
+                    parseResult.media.type.slice(1);
+                result[key] = `[${typeLabel}: ${key}]`;
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        else if (Array.isArray(value)) {
+            // Recursively handle arrays
+            result[key] = value.map((item, index) => {
+                if (typeof item === "object" && item !== null) {
+                    return extractFromObject(item, media, errors, `${fieldPath}[${index}]`);
+                }
+                if (isMediaValue(item)) {
+                    const itemPath = `${fieldPath}[${index}]`;
+                    let parseResult = parseDataUrl(item, itemPath);
+                    if (!parseResult.media && !parseResult.error) {
+                        parseResult = parseProviderUrl(item, undefined, itemPath);
+                    }
+                    if (parseResult.error) {
+                        errors.push(`${itemPath}: ${parseResult.error}`);
+                        return item;
+                    }
+                    else if (parseResult.media) {
+                        media.push(parseResult.media);
+                        const typeLabel = parseResult.media.type.charAt(0).toUpperCase() +
+                            parseResult.media.type.slice(1);
+                        return `[${typeLabel}: ${itemPath}]`;
+                    }
+                }
+                return item;
+            });
+        }
+        else if (typeof value === "object" && value !== null) {
+            // Recursively handle nested objects
+            result[key] = extractFromObject(value, media, errors, fieldPath);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Extract media from input data.
+ * Returns cleaned input (with placeholders) and extracted media array.
+ */
+export function extractMediaFromInput(input) {
+    const media = [];
+    const errors = [];
+    const cleanedInput = extractFromObject(input, media, errors);
+    if (errors.length > 0) {
+        return { error: errors.join("; ") };
+    }
+    return {
+        result: {
+            cleanedInput,
+            media,
+        },
+    };
+}
+//# sourceMappingURL=media-utils.js.map

package/dist/lib/media-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-utils.js","sourceRoot":"","sources":["../../src/lib/media-utils.ts"],"names":[],"mappings":"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"}

package/dist/lib/output-limit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Per-invocation output ceiling resolution
+ * @description Combines an endpoint's configured `max_output_tokens` with an
+ * optional per-call override into the single ceiling handed to the provider.
+ *
+ * Its own module, free of Hono and the database, so the clamping rule -- the
+ * part with security consequences -- is testable in isolation.
+ */
+/** Result of resolving a ceiling: a usable value, or a caller-facing error. */
+export type ResolvedMaxOutputTokens = {
+    ok: true;
+    value: number | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the output ceiling for one invocation.
+ *
+ * The per-call value is a **ceiling, not a raise**: it is clamped to the
+ * endpoint's own ceiling, so a caller can only ever ask for fewer tokens. That
+ * keeps it from becoming a way around an operator's limit.
+ *
+ * An endpoint ceiling of `null` means no protection at all. A per-call value is
+ * still honoured in that case -- asking for less than unlimited is safe, and it
+ * is the only protection available on endpoints that predate this field.
+ *
+ * A malformed per-call value is an error rather than a silent fallback: a caller
+ * who typos their ceiling should learn immediately, not discover later that the
+ * protection they thought they had was never applied.
+ *
+ * @param endpointCeiling - The endpoint's configured ceiling, or null for none
+ * @param requested - The caller's `max_output_tokens`, if any. `null` and
+ *   `undefined` both mean "not specified" and leave the endpoint ceiling intact.
+ * @returns The ceiling to send to the provider, or a validation error
+ */
+export declare function resolveMaxOutputTokens(endpointCeiling: number | null, requested: unknown): ResolvedMaxOutputTokens;
+//# sourceMappingURL=output-limit.d.ts.map

package/dist/lib/output-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-limit.d.ts","sourceRoot":"","sources":["../../src/lib/output-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,SAAS,EAAE,OAAO,GACjB,uBAAuB,CA+BzB"}

package/dist/lib/output-limit.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Per-invocation output ceiling resolution
+ * @description Combines an endpoint's configured `max_output_tokens` with an
+ * optional per-call override into the single ceiling handed to the provider.
+ *
+ * Its own module, free of Hono and the database, so the clamping rule -- the
+ * part with security consequences -- is testable in isolation.
+ */
+/**
+ * Resolve the output ceiling for one invocation.
+ *
+ * The per-call value is a **ceiling, not a raise**: it is clamped to the
+ * endpoint's own ceiling, so a caller can only ever ask for fewer tokens. That
+ * keeps it from becoming a way around an operator's limit.
+ *
+ * An endpoint ceiling of `null` means no protection at all. A per-call value is
+ * still honoured in that case -- asking for less than unlimited is safe, and it
+ * is the only protection available on endpoints that predate this field.
+ *
+ * A malformed per-call value is an error rather than a silent fallback: a caller
+ * who typos their ceiling should learn immediately, not discover later that the
+ * protection they thought they had was never applied.
+ *
+ * @param endpointCeiling - The endpoint's configured ceiling, or null for none
+ * @param requested - The caller's `max_output_tokens`, if any. `null` and
+ *   `undefined` both mean "not specified" and leave the endpoint ceiling intact.
+ * @returns The ceiling to send to the provider, or a validation error
+ */
+export function resolveMaxOutputTokens(endpointCeiling, requested) {
+    if (requested === undefined || requested === null) {
+        return { ok: true, value: endpointCeiling };
+    }
+    // GET invocations parse their input from the query string, so a perfectly
+    // valid ceiling arrives as the string "2000". Accept that spelling, but only
+    // when it denotes a whole number exactly -- "12.5" and "2000abc" are errors.
+    const candidate = typeof requested === "string" && /^\d+$/.test(requested.trim())
+        ? Number(requested.trim())
+        : requested;
+    if (typeof candidate !== "number" ||
+        !Number.isInteger(candidate) ||
+        candidate <= 0) {
+        return {
+            ok: false,
+            error: "max_output_tokens must be a positive integer, or omitted to use the endpoint's own limit",
+        };
+    }
+    // Clamp rather than reject: a caller asking for more than the operator allows
+    // gets the operator's limit, not a failed request.
+    if (endpointCeiling === null) {
+        return { ok: true, value: candidate };
+    }
+    return { ok: true, value: Math.min(candidate, endpointCeiling) };
+}
+//# sourceMappingURL=output-limit.js.map

package/dist/lib/output-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-limit.js","sourceRoot":"","sources":["../../src/lib/output-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,sBAAsB,CACpC,eAA8B,EAC9B,SAAkB;IAElB,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IAC9C,CAAC;IAED,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,MAAM,SAAS,GACb,OAAO,SAAS,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAC7D,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC,CAAC,SAAS,CAAC;IAEhB,IACE,OAAO,SAAS,KAAK,QAAQ;QAC7B,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC;QAC5B,SAAS,IAAI,CAAC,EACd,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EACH,0FAA0F;SAC7F,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,mDAAmD;IACnD,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,eAAe,CAAC,EAAE,CAAC;AACnE,CAAC"}