@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/dist/runtime/ocr.d.ts

@@ -0,0 +1,29 @@
+import type { OcrCaptchaCandidate, OcrCaptchaOptions, OcrContext, ProviderOcrConfig } from "../types.js";
+export { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
+export declare const APIFUSE__OCR__BACKEND_ENV = "APIFUSE__OCR__BACKEND";
+export declare const APIFUSE__OCR__MODEL_ENV = "APIFUSE__OCR__MODEL";
+export declare const APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV = "APIFUSE__OCR__CLOUDFLARE_API_TOKEN";
+export declare const APIFUSE__OCR__BASE_URL_ENV = "APIFUSE__OCR__BASE_URL";
+export declare const APIFUSE__OCR__API_KEY_ENV = "APIFUSE__OCR__API_KEY";
+export declare const CLOUDFLARE_WORKERS_AI_OCR_BACKEND = "cloudflare-workers-ai";
+export declare const OPENAI_COMPATIBLE_OCR_BACKEND = "openai-compatible";
+export declare const DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL = "@cf/google/gemma-4-26b-a4b-it";
+export declare const DEFAULT_OCR_TIMEOUT_MS = 30000;
+type EnvLike = Record<string, string | undefined>;
+type CloudflareWorkersAiOcrClientOptions = {
+    accountId: string;
+    apiToken: string;
+    model?: string;
+    fetch?: typeof fetch;
+};
+type OpenAiCompatibleOcrClientOptions = {
+    baseUrl: string;
+    apiKey?: string;
+    model: string;
+    fetch?: typeof fetch;
+};
+export declare function createUnsupportedOcrClient(reason?: string): OcrContext;
+export declare function createOcrClientFromEnv(config: ProviderOcrConfig | undefined, env?: EnvLike): OcrContext;
+export declare function createCloudflareWorkersAiOcrClient(options: CloudflareWorkersAiOcrClientOptions): OcrContext;
+export declare function createOpenAiCompatibleOcrClient(options: OpenAiCompatibleOcrClientOptions): OcrContext;
+export declare function extractCaptchaCandidates(modelText: string, options?: OcrCaptchaOptions): readonly OcrCaptchaCandidate[];

package/dist/runtime/ocr.js

@@ -0,0 +1,440 @@
+import { ProviderError, TransportError } from "../errors.js";
+import { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
+import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
+export { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
+export const APIFUSE__OCR__BACKEND_ENV = "APIFUSE__OCR__BACKEND";
+export const APIFUSE__OCR__MODEL_ENV = "APIFUSE__OCR__MODEL";
+export const APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV = "APIFUSE__OCR__CLOUDFLARE_API_TOKEN";
+export const APIFUSE__OCR__BASE_URL_ENV = "APIFUSE__OCR__BASE_URL";
+export const APIFUSE__OCR__API_KEY_ENV = "APIFUSE__OCR__API_KEY";
+export const CLOUDFLARE_WORKERS_AI_OCR_BACKEND = "cloudflare-workers-ai";
+export const OPENAI_COMPATIBLE_OCR_BACKEND = "openai-compatible";
+export const DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL = "@cf/google/gemma-4-26b-a4b-it";
+export const DEFAULT_OCR_TIMEOUT_MS = 30_000;
+const DEFAULT_CAPTCHA_MAX_TOKENS = 64;
+const DEFAULT_DOCUMENT_MAX_TOKENS = 4_096;
+const KIMI_MIN_MAX_TOKENS = 3_000;
+const DEFAULT_MAX_CAPTCHA_CANDIDATES = 3;
+const MAX_HOMOGLYPH_SEARCH_NODES = 512;
+const HOMOGLYPH_CLASSES = [
+    ["I", "l", "1", "i"],
+    ["O", "0", "o"],
+    ["S", "5", "s"],
+    ["Z", "2", "z"],
+    ["B", "8"],
+];
+const HINT_PROMPTS = {
+    captcha: "Read the CAPTCHA image. Return only the characters, with no explanation. Preserve character case.",
+    document: "Transcribe all visible text in the document image.",
+    generic: "Read and return the visible text in this image.",
+};
+function providerError(message, options) {
+    return new ProviderError(message, options);
+}
+function createErrorOcrClient(options) {
+    const unavailable = () => {
+        throw providerError(options.message, {
+            code: options.code,
+            fix: options.fix,
+        });
+    };
+    return {
+        async recognize() {
+            return unavailable();
+        },
+        async extractCaptchaText() {
+            return unavailable();
+        },
+    };
+}
+export function createUnsupportedOcrClient(reason) {
+    return createErrorOcrClient({
+        code: "OCR_UNAVAILABLE",
+        message: reason ?? "OCR runtime is not configured",
+        fix: `Configure ${APIFUSE__OCR__BACKEND_ENV} and ${APIFUSE__OCR__MODEL_ENV}; Cloudflare uses ${CLOUDFLARE_ACCOUNT_ID_ENV} and ${APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV}, while openai-compatible uses ${APIFUSE__OCR__BASE_URL_ENV} and optional ${APIFUSE__OCR__API_KEY_ENV}. Alternatively, provide a test OcrContext override.`,
+    });
+}
+function normalizedEnvValue(env, key) {
+    const value = env[key]?.trim();
+    return value ? value : undefined;
+}
+export function createOcrClientFromEnv(config, env = process.env) {
+    if (!config) {
+        return createUnsupportedOcrClient("Provider does not declare OCR capability");
+    }
+    const backend = normalizedEnvValue(env, APIFUSE__OCR__BACKEND_ENV) ?? CLOUDFLARE_WORKERS_AI_OCR_BACKEND;
+    const configuredModel = normalizedEnvValue(env, APIFUSE__OCR__MODEL_ENV);
+    if (backend === CLOUDFLARE_WORKERS_AI_OCR_BACKEND) {
+        const model = configuredModel ?? DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL;
+        const accountId = normalizedEnvValue(env, CLOUDFLARE_ACCOUNT_ID_ENV);
+        const apiToken = normalizedEnvValue(env, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV);
+        if (!accountId || !apiToken) {
+            return createUnsupportedOcrClient(`OCR backend ${backend} requires ${CLOUDFLARE_ACCOUNT_ID_ENV} and ${APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV}`);
+        }
+        return createCloudflareWorkersAiOcrClient({ accountId, apiToken, model });
+    }
+    if (backend === OPENAI_COMPATIBLE_OCR_BACKEND) {
+        const baseUrl = normalizedEnvValue(env, APIFUSE__OCR__BASE_URL_ENV);
+        if (!baseUrl) {
+            return createUnsupportedOcrClient(`OCR backend ${backend} requires ${APIFUSE__OCR__BASE_URL_ENV}`);
+        }
+        if (!configuredModel) {
+            return createErrorOcrClient({
+                code: "OCR_UNAVAILABLE",
+                message: `OCR backend ${backend} requires ${APIFUSE__OCR__MODEL_ENV}`,
+                fix: `Set ${APIFUSE__OCR__MODEL_ENV} to the exact model ID served by your self-hosted endpoint, for example ${APIFUSE__OCR__MODEL_ENV}=zai-org/GLM-OCR.`,
+            });
+        }
+        return createOpenAiCompatibleOcrClient({
+            baseUrl,
+            apiKey: normalizedEnvValue(env, APIFUSE__OCR__API_KEY_ENV),
+            model: configuredModel,
+        });
+    }
+    return createErrorOcrClient({
+        code: "UNSUPPORTED_OCR_BACKEND",
+        message: `Unsupported OCR backend "${backend}"`,
+        fix: `Use ${APIFUSE__OCR__BACKEND_ENV}=${CLOUDFLARE_WORKERS_AI_OCR_BACKEND} or ${APIFUSE__OCR__BACKEND_ENV}=${OPENAI_COMPATIBLE_OCR_BACKEND}, or provide a custom OcrContext override.`,
+    });
+}
+function unknownRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return Object.fromEntries(Object.entries(value));
+}
+function imageUrl(image) {
+    if (image.kind === "url")
+        return image.url.trim();
+    return `data:${image.mediaType?.trim() || "image/png"};base64,${image.data.trim()}`;
+}
+function resolvePrompt(request) {
+    return request.prompt ?? HINT_PROMPTS[request.hint ?? "generic"];
+}
+function isGemmaModel(model) {
+    return model.toLowerCase().includes("gemma");
+}
+function isKimiModel(model) {
+    return model.toLowerCase().includes("kimi");
+}
+function isMoondreamModel(model) {
+    return model.toLowerCase().includes("moondream");
+}
+function defaultMaxTokens(request) {
+    return request.hint === "captcha" ? DEFAULT_CAPTCHA_MAX_TOKENS : DEFAULT_DOCUMENT_MAX_TOKENS;
+}
+function resolvedMaxTokens(request, model = "") {
+    const requestedMaxTokens = request.maxTokens ?? defaultMaxTokens(request);
+    return isKimiModel(model)
+        ? Math.max(requestedMaxTokens, KIMI_MIN_MAX_TOKENS)
+        : requestedMaxTokens;
+}
+function messagesPayload(request, model) {
+    const payload = {
+        ...(model ? { model } : {}),
+        messages: [
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: resolvePrompt(request) },
+                    { type: "image_url", image_url: { url: imageUrl(request.image) } },
+                ],
+            },
+        ],
+        max_tokens: resolvedMaxTokens(request, model),
+        temperature: 0,
+    };
+    if (isGemmaModel(model ?? "")) {
+        payload.chat_template_kwargs = { enable_thinking: false };
+    }
+    return payload;
+}
+function cloudflareMessagesPayload(request, model) {
+    const payload = messagesPayload(request, model);
+    delete payload.model;
+    return payload;
+}
+function moondreamPayload(request) {
+    return {
+        task: "query",
+        image: imageUrl(request.image),
+        question: resolvePrompt(request),
+        stream: true,
+        reasoning: false,
+        temperature: 0,
+        max_tokens: resolvedMaxTokens(request),
+    };
+}
+function incompleteResponseError(model, finishReason) {
+    return new TransportError(`OCR model "${model}" did not complete normally (finish_reason: ${finishReason})`, {
+        code: "OCR_INCOMPLETE_RESPONSE",
+        status: 502,
+        details: { finishReason },
+    });
+}
+function responseContent(payload, cloudflare, model) {
+    const envelope = unknownRecord(payload);
+    const root = cloudflare ? unknownRecord(envelope?.result) : envelope;
+    const choices = root?.choices;
+    if (!Array.isArray(choices))
+        return undefined;
+    const choice = unknownRecord(choices[0]);
+    if (typeof choice?.finish_reason === "string" && choice.finish_reason !== "stop") {
+        throw incompleteResponseError(model, choice.finish_reason);
+    }
+    const message = unknownRecord(choice?.message);
+    return typeof message?.content === "string" ? message.content.trim() || undefined : undefined;
+}
+function malformedResponseError(model, cause) {
+    return new TransportError(`OCR model "${model}" returned a malformed response`, {
+        code: "OCR_UPSTREAM_FAILED",
+        status: 502,
+        cause,
+    });
+}
+async function responseJson(response, model) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        if (isTimeoutLikeError(error))
+            throw toOcrTransportError(error);
+        throw malformedResponseError(model, error instanceof Error ? error : new Error("Failed to decode OCR response JSON"));
+    }
+}
+function moondreamSseContent(body, model) {
+    let finalAnswer;
+    let firstDecodingFailure;
+    let terminalFinishReason;
+    for (const line of body.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("data:"))
+            continue;
+        const data = trimmed.slice("data:".length).trim();
+        if (!data || data === "[DONE]")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch (error) {
+            firstDecodingFailure ??=
+                error instanceof Error ? error : new Error("Failed to decode OCR SSE event");
+            continue;
+        }
+        const event = unknownRecord(parsed);
+        const chunk = unknownRecord(event?.chunk) ?? unknownRecord(event?.result) ?? event;
+        if (chunk?.finish_reason === "stop" &&
+            typeof chunk.answer === "string" &&
+            chunk.answer.trim()) {
+            finalAnswer = chunk.answer.trim();
+        }
+        else if (typeof chunk?.finish_reason === "string") {
+            terminalFinishReason = chunk.finish_reason;
+        }
+    }
+    if (finalAnswer)
+        return finalAnswer;
+    if (terminalFinishReason)
+        throw incompleteResponseError(model, terminalFinishReason);
+    if (firstDecodingFailure)
+        throw malformedResponseError(model, firstDecodingFailure);
+    return finalAnswer;
+}
+function emptyResponseError(model) {
+    return new TransportError(`OCR model "${model}" returned no usable text`, {
+        code: "OCR_UPSTREAM_FAILED",
+        status: 502,
+        fix: `Verify ${APIFUSE__OCR__MODEL_ENV}="${model}" supports image input and the runtime calling convention for that model.`,
+    });
+}
+function toOcrTransportError(error) {
+    if (error instanceof TransportError)
+        return error;
+    if (isTimeoutLikeError(error)) {
+        return new TransportError("OCR upstream request timed out", {
+            code: "transport_timeout",
+            status: 0,
+            cause: error,
+        });
+    }
+    return new TransportError("OCR upstream network request failed", {
+        code: "transport_network_error",
+        status: 0,
+        cause: error instanceof Error ? error : undefined,
+    });
+}
+function createOcrClient(model, recognize) {
+    return {
+        recognize,
+        async extractCaptchaText(image, options = {}) {
+            const result = await recognize({ image, hint: "captcha" });
+            const candidates = extractCaptchaCandidates(result.text, options);
+            const primary = candidates[0];
+            if (!primary?.text)
+                throw emptyResponseError(model);
+            return {
+                text: primary.text,
+                candidates,
+                satisfiesConstraints: primary.satisfiesConstraints,
+                model: result.model,
+            };
+        },
+    };
+}
+export function createCloudflareWorkersAiOcrClient(options) {
+    const model = options.model ?? DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL;
+    const runFetch = options.fetch ?? fetch;
+    return createOcrClient(model, async (request) => {
+        const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
+        try {
+            let response;
+            try {
+                response = await runFetch(`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(options.accountId)}/ai/run/${model}`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${options.apiToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify(isMoondreamModel(model)
+                        ? moondreamPayload(request)
+                        : cloudflareMessagesPayload(request, model)),
+                    signal: timeout.controller.signal,
+                });
+            }
+            catch (error) {
+                throw toOcrTransportError(error);
+            }
+            if (!response.ok) {
+                throw new TransportError("OCR upstream request failed", {
+                    code: "OCR_UPSTREAM_FAILED",
+                    status: response.status,
+                    upstreamStatus: response.status,
+                });
+            }
+            const text = isMoondreamModel(model)
+                ? moondreamSseContent(await response.text(), model)
+                : responseContent(await responseJson(response, model), true, model);
+            if (!text)
+                throw emptyResponseError(model);
+            return { text, model };
+        }
+        catch (error) {
+            throw toOcrTransportError(error);
+        }
+        finally {
+            timeout.clear();
+        }
+    });
+}
+export function createOpenAiCompatibleOcrClient(options) {
+    const model = options.model;
+    const runFetch = options.fetch ?? fetch;
+    return createOcrClient(model, async (request) => {
+        const headers = { "Content-Type": "application/json" };
+        if (options.apiKey)
+            headers.Authorization = `Bearer ${options.apiKey}`;
+        const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
+        try {
+            let response;
+            try {
+                response = await runFetch(`${options.baseUrl.replace(/\/+$/u, "")}/chat/completions`, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(messagesPayload(request, model)),
+                    signal: timeout.controller.signal,
+                });
+            }
+            catch (error) {
+                throw toOcrTransportError(error);
+            }
+            if (!response.ok) {
+                throw new TransportError("OCR upstream request failed", {
+                    code: "OCR_UPSTREAM_FAILED",
+                    status: response.status,
+                    upstreamStatus: response.status,
+                });
+            }
+            const text = responseContent(await responseJson(response, model), false, model);
+            if (!text)
+                throw emptyResponseError(model);
+            return { text, model };
+        }
+        catch (error) {
+            throw toOcrTransportError(error);
+        }
+        finally {
+            timeout.clear();
+        }
+    });
+}
+function cleanCaptchaText(text) {
+    const afterColon = text.slice(text.lastIndexOf(":") + 1).trim();
+    return afterColon.replace(/^[\s\p{P}\p{S}]+|[\s\p{P}\p{S}]+$/gu, "");
+}
+function caseFold(value, caseSensitive) {
+    return caseSensitive ? value : value.toLocaleLowerCase();
+}
+function matchesCharset(text, charset, caseSensitive) {
+    if (charset === undefined)
+        return true;
+    if (typeof charset === "string") {
+        const allowed = new Set([...caseFold(charset, caseSensitive)]);
+        return [...caseFold(text, caseSensitive)].every((character) => allowed.has(character));
+    }
+    const flags = caseSensitive || charset.flags.includes("i") ? charset.flags : `${charset.flags}i`;
+    const matcher = new RegExp(charset.source, flags);
+    return [...text].every((character) => {
+        matcher.lastIndex = 0;
+        return matcher.test(character);
+    });
+}
+function satisfiesCaptchaConstraints(text, options) {
+    const lengthMatches = options.length === undefined || [...text].length === options.length;
+    return lengthMatches && matchesCharset(text, options.charset, options.caseSensitive !== false);
+}
+function homoglyphAlternatives(character) {
+    const group = HOMOGLYPH_CLASSES.find((characters) => characters.includes(character));
+    return group?.filter((alternative) => alternative !== character) ?? [];
+}
+export function extractCaptchaCandidates(modelText, options = {}) {
+    const primaryText = cleanCaptchaText(modelText);
+    const primary = {
+        text: primaryText,
+        satisfiesConstraints: satisfiesCaptchaConstraints(primaryText, options),
+    };
+    const requestedMaxCandidates = options.maxCandidates ?? DEFAULT_MAX_CAPTCHA_CANDIDATES;
+    const maxCandidates = Number.isFinite(requestedMaxCandidates)
+        ? Math.max(1, Math.floor(requestedMaxCandidates))
+        : DEFAULT_MAX_CAPTCHA_CANDIDATES;
+    if (primary.satisfiesConstraints || maxCandidates === 1)
+        return [primary];
+    if (options.length !== undefined && [...primaryText].length !== options.length)
+        return [primary];
+    const candidates = [primary];
+    const queue = [primaryText];
+    const visited = new Set(queue);
+    for (let index = 0; index < queue.length && candidates.length < maxCandidates; index += 1) {
+        const current = queue[index] ?? "";
+        const characters = [...current];
+        for (let position = 0; position < characters.length; position += 1) {
+            const character = characters[position] ?? "";
+            for (const alternative of homoglyphAlternatives(character)) {
+                const nextCharacters = [...characters];
+                nextCharacters[position] = alternative;
+                const next = nextCharacters.join("");
+                if (visited.has(next))
+                    continue;
+                visited.add(next);
+                queue.push(next);
+                if (satisfiesCaptchaConstraints(next, options)) {
+                    candidates.push({ text: next, satisfiesConstraints: true });
+                    if (candidates.length >= maxCandidates)
+                        return candidates;
+                }
+                if (visited.size >= MAX_HOMOGLYPH_SEARCH_NODES)
+                    return candidates;
+            }
+        }
+    }
+    return candidates;
+}

package/dist/runtime/otlp.d.ts

@@ -1,4 +1,4 @@
-import type { TraceSpan } from "../types";
+import type { TraceSpan } from "../types.js";
 export interface OTLPExportOptions {
     endpoint: string;
     headers?: Record<string, string>;

package/dist/runtime/perf.d.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 export type PerfStats = {
     p50: number;
     p95: number;

package/dist/runtime/provider.d.ts

@@ -1,2 +1,2 @@
-import type { ProviderDefinition } from "../types";
+import type { ProviderDefinition } from "../types.js";
 export declare function getProviderBaseUrl(provider: ProviderDefinition): string | undefined;

package/dist/runtime/provider.js

@@ -1,8 +1,7 @@
 export function getProviderBaseUrl(provider) {
     const operations = Object.values(provider.operations);
     for (const operation of operations) {
-        const baseUrl = operation.upstream
-            ?.baseUrl;
+        const baseUrl = operation.upstream?.baseUrl;
         if (typeof baseUrl === "string" && baseUrl.length > 0) {
             return baseUrl;
         }

package/dist/runtime/proxy-errors.d.ts

@@ -1,4 +1,4 @@
-import { TransportError } from "../errors";
+import { TransportError } from "../errors.js";
 export declare const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
 export declare const PROXY_AUTH_IP_DENIED_MESSAGE = "Proxy source IP is not authorized. Add the runtime egress IP to the proxy provider allowlist.";
 export declare const PROXY_EDGE_AUTH_REJECTED_CODE = "PROXY_EDGE_AUTH_REJECTED";

package/dist/runtime/proxy-errors.js

@@ -1,4 +1,4 @@
-import { TransportError } from "../errors";
+import { TransportError } from "../errors.js";
 export const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
 export const PROXY_AUTH_IP_DENIED_MESSAGE = "Proxy source IP is not authorized. Add the runtime egress IP to the proxy provider allowlist.";
 export const PROXY_EDGE_AUTH_REJECTED_CODE = "PROXY_EDGE_AUTH_REJECTED";
@@ -11,8 +11,12 @@ const PROXY_POOL_STALE_STATUS_CODES = new Set([509, 512]);
 const PROXY_EDGE_TLS_REJECTED_STATUS_CODES = new Set([495]);
 const PROXY_AUTH_IP_DENIED_PATTERN = /\b(?:source|egress|client)\s+ip\b.{0,120}\b(?:deny|denied|unauthori[sz]ed|not\s+authori[sz]ed|white\s*list|allow\s*list)\b|\b(?:white\s*list|allow\s*list)\b.{0,120}\b(?:source|egress|client)\s+ip\b/i;
 const PROXY_EDGE_AUTH_REJECTED_PATTERN = /\bauth\s+ip\s+err\b|\bproxy\b.{0,120}\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b|\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b.{0,120}\bproxy\b/i;
-const PROXY_POOL_STALE_MESSAGE_PATTERN = /\bproxy\b.{0,120}\b(?:pool|lease|expired|unavailable|exhausted|non[\s-]?200\s+code:\s*(?:509|512))\b|\bnon[\s-]?200\s+code:\s*(?:509|512)\b.{0,120}\bproxy\b|\bsmartproxy\b.{0,120}\b(?:509|512)\b/i;
-const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = /\b(?:smartproxy|proxy)\b.{0,160}\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b|\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b.{0,160}\b(?:smartproxy|proxy)\b/i;
+// Vendor host tokens that can appear in upstream error strings. Adding a proxy
+// vendor updates every classifier below in one place. `proxy` is the generic
+// fallback so vendor-agnostic messages still classify.
+const PROXY_VENDOR_ALTERNATION = "smartproxy|nodemaven|proxy";
+const PROXY_POOL_STALE_MESSAGE_PATTERN = new RegExp(`\\bproxy\\b.{0,120}\\b(?:pool|lease|expired|unavailable|exhausted|non[\\s-]?200\\s+code:\\s*(?:509|512))\\b|\\bnon[\\s-]?200\\s+code:\\s*(?:509|512)\\b.{0,120}\\bproxy\\b|\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,120}\\b(?:509|512)\\b`, "i");
+const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = new RegExp(`\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,160}\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b|\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b.{0,160}\\b(?:${PROXY_VENDOR_ALTERNATION})\\b`, "i");
 export function isProxyAuthIpDeniedMessage(message) {
     return PROXY_AUTH_IP_DENIED_PATTERN.test(message);
 }
@@ -42,8 +46,7 @@ export function isProxyPoolStaleMessage(message) {
     return PROXY_POOL_STALE_MESSAGE_PATTERN.test(message);
 }
 export function isProxyPoolRefreshableError(error) {
-    if (error instanceof TransportError &&
-        error.code === PROXY_AUTH_IP_DENIED_CODE) {
+    if (error instanceof TransportError && error.code === PROXY_AUTH_IP_DENIED_CODE) {
         return false;
     }
     if (error instanceof TransportError &&
@@ -57,8 +60,7 @@ export function isProxyPoolRefreshableError(error) {
         error instanceof Error ? error.message : String(error),
         cause instanceof Error ? cause.message : "",
     ].join(" ");
-    return (PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) ||
-        PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message));
+    return (PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) || PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message));
 }
 export const isProxyPoolStaleError = isProxyPoolRefreshableError;
 export function createProxyPoolStaleError(status, cause) {

package/dist/runtime/proxy-nodemaven.d.ts

@@ -0,0 +1,56 @@
+import type { ProviderProxyPolicy } from "../types.js";
+export declare const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export declare const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export declare const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+export declare const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+export type NodemavenCredentials = {
+    readonly username: string;
+    readonly password: string;
+    readonly filter?: string;
+};
+/** Both schemes tunnel bytes end-to-end, preserving the client TLS handshake. */
+export type ProxyProtocol = "http" | "socks5";
+/**
+ * NodeMaven's fastest protocol: HTTP CONNECT. Benchmarks (KR, cold + warm)
+ * showed socks5 through the gateway adds ~500ms per request over http, so
+ * NodeMaven never defaults to socks5.
+ */
+export declare const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol;
+export declare const NODEMAVEN_MAX_POOL_SIZE = 50;
+export declare function hasNodemavenCredentials(): boolean;
+export declare function nodemavenPoolSize(policy: ProviderProxyPolicy): number;
+export declare function nodemavenLifetimeMinutes(policy: ProviderProxyPolicy): number;
+export type NodemavenSessionWindow = {
+    refreshEpoch: number;
+    expiresAt: string;
+};
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export declare function nodemavenSessionWindow(policy: ProviderProxyPolicy, now?: number): NodemavenSessionWindow;
+export type NodemavenSynthesisInput = {
+    policy: ProviderProxyPolicy;
+    /** Explicit credentials; synthesis never reads process-global state. */
+    credentials: NodemavenCredentials;
+    affinityKey: string | undefined;
+    protocol: ProxyProtocol;
+    poolIndex: number;
+    refreshEpoch: number;
+    /** ISO 3166-1 alpha-2, already resolved by the caller (falls back to env). */
+    country?: string;
+    /** Clock injection used by native sticky-expiry lifecycle tests. */
+    now?: number;
+    /** Stable caller-owned hard expiry when the refresh epoch is wall-clock-derived. */
+    expiresAt?: string;
+};
+export type NodemavenSynthesis = {
+    url: string;
+    protocol: ProxyProtocol;
+    sticky: boolean;
+    sessionId: string;
+    expiresAt?: string;
+    diagnostics: Record<string, string | number | boolean>;
+};
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export declare function synthesizeNodemavenProxy(input: NodemavenSynthesisInput): NodemavenSynthesis;