@juspay/neurolink 9.64.0 → 9.65.1

package/dist/utils/pricing.js

@@ -285,6 +285,177 @@ const PRICING = {
     llamacpp: {
         _default: { input: 0, output: 0 },
     },
+    xai: {
+        _default: { input: 3.0 / 1_000_000, output: 15.0 / 1_000_000 },
+        "grok-3": { input: 3.0 / 1_000_000, output: 15.0 / 1_000_000 },
+        "grok-3-mini": { input: 0.3 / 1_000_000, output: 0.5 / 1_000_000 },
+        "grok-2-latest": { input: 2.0 / 1_000_000, output: 10.0 / 1_000_000 },
+        "grok-2-vision-latest": {
+            input: 2.0 / 1_000_000,
+            output: 10.0 / 1_000_000,
+        },
+        "grok-beta": { input: 5.0 / 1_000_000, output: 15.0 / 1_000_000 },
+    },
+    groq: {
+        _default: { input: 0.59 / 1_000_000, output: 0.79 / 1_000_000 },
+        "llama-3.3-70b-versatile": {
+            input: 0.59 / 1_000_000,
+            output: 0.79 / 1_000_000,
+        },
+        "llama-3.1-8b-instant": {
+            input: 0.05 / 1_000_000,
+            output: 0.08 / 1_000_000,
+        },
+        "llama-3.2-90b-vision-preview": {
+            input: 0.9 / 1_000_000,
+            output: 0.9 / 1_000_000,
+        },
+        "llama-3.2-11b-vision-preview": {
+            input: 0.18 / 1_000_000,
+            output: 0.18 / 1_000_000,
+        },
+        "gemma2-9b-it": { input: 0.2 / 1_000_000, output: 0.2 / 1_000_000 },
+        "mixtral-8x7b-32768": {
+            input: 0.24 / 1_000_000,
+            output: 0.24 / 1_000_000,
+        },
+    },
+    cohere: {
+        _default: { input: 2.5 / 1_000_000, output: 10.0 / 1_000_000 },
+        "command-r-plus": { input: 2.5 / 1_000_000, output: 10.0 / 1_000_000 },
+        "command-r": { input: 0.15 / 1_000_000, output: 0.6 / 1_000_000 },
+        "command-r7b-12-2024": {
+            input: 0.0375 / 1_000_000,
+            output: 0.15 / 1_000_000,
+        },
+    },
+    "together-ai": {
+        _default: { input: 0.88 / 1_000_000, output: 0.88 / 1_000_000 },
+        "meta-llama/Llama-3.3-70B-Instruct-Turbo": {
+            input: 0.88 / 1_000_000,
+            output: 0.88 / 1_000_000,
+        },
+        "meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo": {
+            input: 3.5 / 1_000_000,
+            output: 3.5 / 1_000_000,
+        },
+        "meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo": {
+            input: 0.88 / 1_000_000,
+            output: 0.88 / 1_000_000,
+        },
+        "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo": {
+            input: 0.18 / 1_000_000,
+            output: 0.18 / 1_000_000,
+        },
+        "mistralai/Mixtral-8x22B-Instruct-v0.1": {
+            input: 1.2 / 1_000_000,
+            output: 1.2 / 1_000_000,
+        },
+        "mistralai/Mixtral-8x7B-Instruct-v0.1": {
+            input: 0.6 / 1_000_000,
+            output: 0.6 / 1_000_000,
+        },
+        "Qwen/Qwen2.5-72B-Instruct-Turbo": {
+            input: 1.2 / 1_000_000,
+            output: 1.2 / 1_000_000,
+        },
+        "deepseek-ai/DeepSeek-R1": {
+            input: 7.0 / 1_000_000,
+            output: 7.0 / 1_000_000,
+        },
+        "deepseek-ai/DeepSeek-V3": {
+            input: 1.25 / 1_000_000,
+            output: 1.25 / 1_000_000,
+        },
+    },
+    fireworks: {
+        _default: { input: 0.9 / 1_000_000, output: 0.9 / 1_000_000 },
+        "accounts/fireworks/models/llama-v3p1-70b-instruct": {
+            input: 0.9 / 1_000_000,
+            output: 0.9 / 1_000_000,
+        },
+        "accounts/fireworks/models/llama-v3p1-405b-instruct": {
+            input: 3.0 / 1_000_000,
+            output: 3.0 / 1_000_000,
+        },
+        "accounts/fireworks/models/llama-v3p1-8b-instruct": {
+            input: 0.2 / 1_000_000,
+            output: 0.2 / 1_000_000,
+        },
+        "accounts/fireworks/models/llama-v3p3-70b-instruct": {
+            input: 0.9 / 1_000_000,
+            output: 0.9 / 1_000_000,
+        },
+        "accounts/fireworks/models/mixtral-8x22b-instruct": {
+            input: 1.2 / 1_000_000,
+            output: 1.2 / 1_000_000,
+        },
+        "accounts/fireworks/models/qwen2p5-72b-instruct": {
+            input: 0.9 / 1_000_000,
+            output: 0.9 / 1_000_000,
+        },
+        "accounts/fireworks/models/qwen2p5-coder-32b-instruct": {
+            input: 0.9 / 1_000_000,
+            output: 0.9 / 1_000_000,
+        },
+        "accounts/fireworks/models/deepseek-v3": {
+            input: 0.75 / 1_000_000,
+            output: 3.0 / 1_000_000,
+        },
+    },
+    perplexity: {
+        _default: { input: 1.0 / 1_000_000, output: 1.0 / 1_000_000 },
+        sonar: { input: 1.0 / 1_000_000, output: 1.0 / 1_000_000 },
+        "sonar-pro": { input: 3.0 / 1_000_000, output: 15.0 / 1_000_000 },
+        "sonar-reasoning": { input: 1.0 / 1_000_000, output: 5.0 / 1_000_000 },
+        "sonar-reasoning-pro": {
+            input: 2.0 / 1_000_000,
+            output: 8.0 / 1_000_000,
+        },
+        "sonar-deep-research": {
+            input: 2.0 / 1_000_000,
+            output: 8.0 / 1_000_000,
+        },
+    },
+    cloudflare: {
+        // Cloudflare bills per "neuron"; symbolic per-token rate so cost
+        // attribution dashboards have non-zero values.
+        _default: { input: 0.011 / 1_000_000, output: 0.011 / 1_000_000 },
+    },
+    replicate: {
+        // Replicate bills per compute-second, not per-token. Symbolic rate.
+        _default: { input: 0.5 / 1_000_000, output: 1.5 / 1_000_000 },
+    },
+    voyage: {
+        // Voyage bills per million input tokens — output dimension is the
+        // embedding vector, not generated tokens. We charge to input only.
+        _default: { input: 0.18 / 1_000_000, output: 0 },
+        "voyage-3.5": { input: 0.06 / 1_000_000, output: 0 },
+        "voyage-3.5-lite": { input: 0.02 / 1_000_000, output: 0 },
+        "voyage-3-large": { input: 0.18 / 1_000_000, output: 0 },
+        "voyage-code-3": { input: 0.18 / 1_000_000, output: 0 },
+        "voyage-finance-2": { input: 0.12 / 1_000_000, output: 0 },
+        "voyage-law-2": { input: 0.12 / 1_000_000, output: 0 },
+        "voyage-multilingual-2": { input: 0.12 / 1_000_000, output: 0 },
+    },
+    jina: {
+        _default: { input: 0.02 / 1_000_000, output: 0 },
+        "jina-embeddings-v3": { input: 0.02 / 1_000_000, output: 0 },
+        "jina-reranker-v2-base-multilingual": {
+            input: 0.05 / 1_000_000,
+            output: 0,
+        },
+    },
+    stability: {
+        // Stability AI bills per image; symbolic per-token rate.
+        _default: { input: 0, output: 0.04 / 1_000 },
+    },
+    ideogram: {
+        _default: { input: 0, output: 0.08 / 1_000 },
+    },
+    recraft: {
+        _default: { input: 0, output: 0.04 / 1_000 },
+    },
 };
 /**
  * Map of normalized provider aliases to canonical PRICING keys.
@@ -313,6 +484,28 @@ const PROVIDER_ALIASES = {
     nvidia: "nvidia-nim",
     lmstudio: "lm-studio",
     llamacpp: "llamacpp",
+    xai: "xai",
+    grok: "xai",
+    groq: "groq",
+    cohere: "cohere",
+    togetherai: "together-ai",
+    together: "together-ai",
+    fireworks: "fireworks",
+    perplexity: "perplexity",
+    pplx: "perplexity",
+    cloudflare: "cloudflare",
+    workersai: "cloudflare",
+    cfai: "cloudflare",
+    replicate: "replicate",
+    voyage: "voyage",
+    voyageai: "voyage",
+    jina: "jina",
+    jinaai: "jina",
+    stability: "stability",
+    stabilityai: "stability",
+    sd: "stability",
+    ideogram: "ideogram",
+    recraft: "recraft",
 };
 /**
  * Look up per-token rates for a provider/model combination.

package/dist/utils/providerConfig.d.ts

@@ -123,6 +123,61 @@ export declare function createLmStudioConfig(): ProviderConfigOptions;
  * Creates llama.cpp provider configuration (local server)
  */
 export declare function createLlamaCppConfig(): ProviderConfigOptions;
+/**
+ * Creates xAI Grok provider configuration.
+ */
+export declare function createXaiConfig(): ProviderConfigOptions;
+/**
+ * Creates Groq provider configuration.
+ */
+export declare function createGroqConfig(): ProviderConfigOptions;
+/**
+ * Creates Cohere provider configuration.
+ */
+export declare function createCohereConfig(): ProviderConfigOptions;
+/**
+ * Creates Replicate provider configuration.
+ */
+export declare function createReplicateConfig(): ProviderConfigOptions;
+/**
+ * Creates Together AI provider configuration.
+ */
+export declare function createTogetherAIConfig(): ProviderConfigOptions;
+/**
+ * Creates Fireworks AI provider configuration.
+ */
+export declare function createFireworksConfig(): ProviderConfigOptions;
+/**
+ * Creates Perplexity provider configuration.
+ */
+export declare function createPerplexityConfig(): ProviderConfigOptions;
+/**
+ * Creates Voyage AI provider configuration (embedding-only).
+ */
+export declare function createVoyageConfig(): ProviderConfigOptions;
+/**
+ * Creates Jina AI provider configuration (embeddings + reranking).
+ */
+export declare function createJinaConfig(): ProviderConfigOptions;
+/**
+ * Creates Stability AI provider configuration (image generation).
+ */
+export declare function createStabilityConfig(): ProviderConfigOptions;
+/**
+ * Creates Ideogram provider configuration (image generation).
+ */
+export declare function createIdeogramConfig(): ProviderConfigOptions;
+/**
+ * Creates Recraft provider configuration (image generation, vector focus).
+ */
+export declare function createRecraftConfig(): ProviderConfigOptions;
+/**
+ * Creates Cloudflare Workers AI provider configuration.
+ *
+ * Cloudflare requires both `CLOUDFLARE_API_KEY` (workers-AI-scoped token)
+ * AND `CLOUDFLARE_ACCOUNT_ID` since the endpoint is per-account.
+ */
+export declare function createCloudflareConfig(): ProviderConfigOptions;
 /**
  * Creates Google Vertex Project ID configuration
  */

package/dist/utils/providerConfig.js

@@ -448,6 +448,230 @@ export function createLlamaCppConfig() {
         optional: true,
     };
 }
+/**
+ * Creates xAI Grok provider configuration.
+ */
+export function createXaiConfig() {
+    return {
+        providerName: "xAI",
+        envVarName: "XAI_API_KEY",
+        setupUrl: "https://console.x.ai/",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://console.x.ai/",
+            "2. Sign in with your xAI account",
+            "3. Create an API key",
+            "4. Set XAI_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Groq provider configuration.
+ */
+export function createGroqConfig() {
+    return {
+        providerName: "Groq",
+        envVarName: "GROQ_API_KEY",
+        setupUrl: "https://console.groq.com/keys",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://console.groq.com/keys",
+            "2. Sign in to your Groq account",
+            "3. Create a new API key",
+            "4. Set GROQ_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Cohere provider configuration.
+ */
+export function createCohereConfig() {
+    return {
+        providerName: "Cohere",
+        envVarName: "COHERE_API_KEY",
+        setupUrl: "https://dashboard.cohere.com/api-keys",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://dashboard.cohere.com/api-keys",
+            "2. Sign in to your Cohere account",
+            "3. Create a new API key",
+            "4. Set COHERE_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Replicate provider configuration.
+ */
+export function createReplicateConfig() {
+    return {
+        providerName: "Replicate",
+        envVarName: "REPLICATE_API_TOKEN",
+        setupUrl: "https://replicate.com/account/api-tokens",
+        description: "API token",
+        instructions: [
+            "1. Visit: https://replicate.com/account/api-tokens",
+            "2. Sign in to your Replicate account",
+            "3. Create a new API token",
+            "4. Set REPLICATE_API_TOKEN in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Together AI provider configuration.
+ */
+export function createTogetherAIConfig() {
+    return {
+        providerName: "Together AI",
+        envVarName: "TOGETHER_API_KEY",
+        setupUrl: "https://api.together.xyz/settings/api-keys",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://api.together.xyz/settings/api-keys",
+            "2. Sign in to your Together AI account",
+            "3. Create a new API key",
+            "4. Set TOGETHER_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Fireworks AI provider configuration.
+ */
+export function createFireworksConfig() {
+    return {
+        providerName: "Fireworks AI",
+        envVarName: "FIREWORKS_API_KEY",
+        setupUrl: "https://fireworks.ai/account/api-keys",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://fireworks.ai/account/api-keys",
+            "2. Sign in to your Fireworks AI account",
+            "3. Create a new API key",
+            "4. Set FIREWORKS_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Perplexity provider configuration.
+ */
+export function createPerplexityConfig() {
+    return {
+        providerName: "Perplexity",
+        envVarName: "PERPLEXITY_API_KEY",
+        setupUrl: "https://www.perplexity.ai/settings/api",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://www.perplexity.ai/settings/api",
+            "2. Sign in to your Perplexity account",
+            "3. Create a new API key (Sonar tier)",
+            "4. Set PERPLEXITY_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Voyage AI provider configuration (embedding-only).
+ */
+export function createVoyageConfig() {
+    return {
+        providerName: "Voyage AI",
+        envVarName: "VOYAGE_API_KEY",
+        setupUrl: "https://dash.voyageai.com/api-keys",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://dash.voyageai.com/api-keys",
+            "2. Sign in to your Voyage AI account",
+            "3. Create a new API key",
+            "4. Set VOYAGE_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Jina AI provider configuration (embeddings + reranking).
+ */
+export function createJinaConfig() {
+    return {
+        providerName: "Jina AI",
+        envVarName: "JINA_API_KEY",
+        setupUrl: "https://jina.ai/?sui=apikey",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://jina.ai/?sui=apikey",
+            "2. Sign in / create account",
+            "3. Copy your API key",
+            "4. Set JINA_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Stability AI provider configuration (image generation).
+ */
+export function createStabilityConfig() {
+    return {
+        providerName: "Stability AI",
+        envVarName: "STABILITY_API_KEY",
+        setupUrl: "https://platform.stability.ai/account/keys",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://platform.stability.ai/account/keys",
+            "2. Sign in to your Stability AI account",
+            "3. Create a new API key",
+            "4. Set STABILITY_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Ideogram provider configuration (image generation).
+ */
+export function createIdeogramConfig() {
+    return {
+        providerName: "Ideogram",
+        envVarName: "IDEOGRAM_API_KEY",
+        setupUrl: "https://developer.ideogram.ai/",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://developer.ideogram.ai/",
+            "2. Sign in / create account",
+            "3. Generate a new API key",
+            "4. Set IDEOGRAM_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Recraft provider configuration (image generation, vector focus).
+ */
+export function createRecraftConfig() {
+    return {
+        providerName: "Recraft",
+        envVarName: "RECRAFT_API_KEY",
+        setupUrl: "https://www.recraft.ai/api",
+        description: "API token",
+        instructions: [
+            "1. Visit: https://www.recraft.ai/api",
+            "2. Sign in / create account",
+            "3. Create an API token",
+            "4. Set RECRAFT_API_KEY in your .env file",
+        ],
+    };
+}
+/**
+ * Creates Cloudflare Workers AI provider configuration.
+ *
+ * Cloudflare requires both `CLOUDFLARE_API_KEY` (workers-AI-scoped token)
+ * AND `CLOUDFLARE_ACCOUNT_ID` since the endpoint is per-account.
+ */
+export function createCloudflareConfig() {
+    return {
+        providerName: "Cloudflare Workers AI",
+        envVarName: "CLOUDFLARE_API_KEY",
+        setupUrl: "https://dash.cloudflare.com/profile/api-tokens",
+        description: "API token (Workers AI Read+Write scope)",
+        instructions: [
+            "1. Visit: https://dash.cloudflare.com/profile/api-tokens",
+            "2. Create a token with 'Workers AI: Read + Write' scope",
+            "3. Set CLOUDFLARE_API_KEY in your .env file",
+            "4. Also set CLOUDFLARE_ACCOUNT_ID (find it in the dashboard URL or under 'Account ID')",
+        ],
+    };
+}
 /**
  * Creates Google Vertex Project ID configuration
  */

package/dist/utils/safeFetch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Safe Fetch — SSRF-hardened binary download helper.
+ *
+ * Combines:
+ *   - `assertSafeUrl` (validates and rejects blocked IPs)
+ *   - undici `Agent` with custom `connect.lookup` so the actual connection
+ *     uses the IP we validated (closes the DNS-rebinding window where the
+ *     resolver returns a public IP for the guard but a private IP for the
+ *     real request).
+ *   - `readBoundedBuffer` for size cap.
+ *   - `redirect: "manual"` so a 3xx → private-IP redirect can't bypass
+ *     the guard.
+ *
+ * Use this for **every** download of an external (caller-supplied or
+ * third-party-returned) URL. Direct `fetch(url)` of such URLs is unsafe.
+ *
+ * @module utils/safeFetch
+ */
+import type { SafeDownloadOptions } from "../types/index.js";
+/**
+ * Safely download a binary asset from an external URL.
+ *
+ * @throws {Error} if the URL is unsafe, the response is too large, a redirect
+ *   is encountered, or the HTTP status indicates failure.
+ */
+export declare function safeDownload(url: string, options: SafeDownloadOptions): Promise<Buffer>;

package/dist/utils/safeFetch.js

@@ -0,0 +1,82 @@
+/**
+ * Safe Fetch — SSRF-hardened binary download helper.
+ *
+ * Combines:
+ *   - `assertSafeUrl` (validates and rejects blocked IPs)
+ *   - undici `Agent` with custom `connect.lookup` so the actual connection
+ *     uses the IP we validated (closes the DNS-rebinding window where the
+ *     resolver returns a public IP for the guard but a private IP for the
+ *     real request).
+ *   - `readBoundedBuffer` for size cap.
+ *   - `redirect: "manual"` so a 3xx → private-IP redirect can't bypass
+ *     the guard.
+ *
+ * Use this for **every** download of an external (caller-supplied or
+ * third-party-returned) URL. Direct `fetch(url)` of such URLs is unsafe.
+ *
+ * @module utils/safeFetch
+ */
+import { Agent, fetch as undiciFetch } from "undici";
+import { readBoundedBuffer } from "./sizeGuard.js";
+import { validateAndResolveUrl } from "./ssrfGuard.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Build a once-off undici Agent whose connect lookup resolves `hostname` to a
+ * fixed IP. This pins the actual TCP connection to the IP we validated,
+ * removing the DNS-rebinding window.
+ */
+function buildPinnedAgent(hostname, ip, family) {
+    return new Agent({
+        connect: {
+            lookup: (host, _options, callback) => {
+                if (host.toLowerCase() !== hostname.toLowerCase()) {
+                    // The host the connect layer asks for differs from the URL host —
+                    // this happens for absolute Host headers etc. Reject defensively.
+                    callback(new Error(`safeFetch: refusing to resolve "${host}" — expected "${hostname}"`), "", 0);
+                    return;
+                }
+                callback(null, ip, family);
+            },
+        },
+    });
+}
+/**
+ * Safely download a binary asset from an external URL.
+ *
+ * @throws {Error} if the URL is unsafe, the response is too large, a redirect
+ *   is encountered, or the HTTP status indicates failure.
+ */
+export async function safeDownload(url, options) {
+    const { url: validatedUrl, ip, family } = await validateAndResolveUrl(url);
+    const parsed = new URL(validatedUrl);
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, "");
+    const agent = buildPinnedAgent(hostname, ip, family);
+    const timeoutCtrl = new AbortController();
+    const timeoutId = setTimeout(() => timeoutCtrl.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const composedSignal = options.signal
+        ? AbortSignal.any([options.signal, timeoutCtrl.signal])
+        : timeoutCtrl.signal;
+    let response;
+    try {
+        response = await undiciFetch(validatedUrl, {
+            method: "GET",
+            signal: composedSignal,
+            redirect: "manual", // a 3xx → private-IP redirect would bypass the guard
+            dispatcher: agent,
+        });
+    }
+    finally {
+        clearTimeout(timeoutId);
+        // Close the per-request agent so the pinned connection isn't pooled.
+        agent.close().catch(() => undefined);
+    }
+    if (response.status >= 300 && response.status < 400) {
+        throw new Error(`safeDownload(${options.label}): refused to follow redirect ${response.status} → ${response.headers.get("location") ?? "<no-location>"} (for ${url})`);
+    }
+    if (!response.ok) {
+        throw new Error(`safeDownload(${options.label}) failed: HTTP ${response.status} for ${url}`);
+    }
+    // readBoundedBuffer expects a Response that exposes Content-Length and
+    // arrayBuffer(). undici Response satisfies both.
+    return readBoundedBuffer(response, options.maxBytes, options.label);
+}

package/dist/utils/sizeGuard.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Size Guard Utility
+ *
+ * Provides bounded binary downloads to prevent OOM when fetching generated
+ * media from external providers. Applies a Content-Length pre-check and a
+ * post-buffer guard so multi-GB responses are rejected before they fully
+ * materialise in process memory.
+ *
+ * @module utils/sizeGuard
+ */
+/** 256 MiB — suitable for video output (MP4). */
+export declare const MAX_VIDEO_BYTES: number;
+/** 50 MiB — suitable for audio output (MP3/WAV). */
+export declare const MAX_AUDIO_BYTES: number;
+/** 25 MiB — suitable for image output (PNG/JPEG/WebP). */
+export declare const MAX_IMAGE_BYTES: number;
+/**
+ * Download the body of a {@link Response} into a {@link Buffer}, enforcing an
+ * upper-bound on the number of bytes consumed.
+ *
+ * Two checks are performed:
+ * 1. If the response includes a `Content-Length` header that exceeds
+ *    `maxBytes`, the download is rejected immediately (no data is read).
+ * 2. After buffering, the actual buffer size is verified against `maxBytes`.
+ *    This catches chunked transfers where no `Content-Length` was provided.
+ *
+ * @param response  The fetch {@link Response} to drain.
+ * @param maxBytes  Maximum number of bytes allowed.
+ * @param label     Human-readable identifier used in error messages
+ *                  (e.g. "Kling video", "D-ID result").
+ * @returns         The response body as a {@link Buffer}.
+ * @throws          {@link Error} when either size check fails.
+ */
+export declare function readBoundedBuffer(response: Response, maxBytes: number, label: string): Promise<Buffer>;

package/dist/utils/sizeGuard.js

@@ -0,0 +1,44 @@
+/**
+ * Size Guard Utility
+ *
+ * Provides bounded binary downloads to prevent OOM when fetching generated
+ * media from external providers. Applies a Content-Length pre-check and a
+ * post-buffer guard so multi-GB responses are rejected before they fully
+ * materialise in process memory.
+ *
+ * @module utils/sizeGuard
+ */
+/** 256 MiB — suitable for video output (MP4). */
+export const MAX_VIDEO_BYTES = 256 * 1024 * 1024;
+/** 50 MiB — suitable for audio output (MP3/WAV). */
+export const MAX_AUDIO_BYTES = 50 * 1024 * 1024;
+/** 25 MiB — suitable for image output (PNG/JPEG/WebP). */
+export const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+/**
+ * Download the body of a {@link Response} into a {@link Buffer}, enforcing an
+ * upper-bound on the number of bytes consumed.
+ *
+ * Two checks are performed:
+ * 1. If the response includes a `Content-Length` header that exceeds
+ *    `maxBytes`, the download is rejected immediately (no data is read).
+ * 2. After buffering, the actual buffer size is verified against `maxBytes`.
+ *    This catches chunked transfers where no `Content-Length` was provided.
+ *
+ * @param response  The fetch {@link Response} to drain.
+ * @param maxBytes  Maximum number of bytes allowed.
+ * @param label     Human-readable identifier used in error messages
+ *                  (e.g. "Kling video", "D-ID result").
+ * @returns         The response body as a {@link Buffer}.
+ * @throws          {@link Error} when either size check fails.
+ */
+export async function readBoundedBuffer(response, maxBytes, label) {
+    const contentLength = parseInt(response.headers.get("content-length") ?? "0", 10);
+    if (contentLength > 0 && contentLength > maxBytes) {
+        throw new Error(`${label} download too large: ${contentLength} bytes (max ${maxBytes})`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (buffer.length > maxBytes) {
+        throw new Error(`${label} download exceeded size cap after fetch: ${buffer.length} bytes (max ${maxBytes})`);
+    }
+    return buffer;
+}