@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.9

package/dist/define.js

@@ -8,7 +8,7 @@ const VALID_RUNTIMES = ["standard", "shared", "browser"];
 const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"];
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"];
-const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "decodo", "custom"];
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"];
 const VALID_PROVIDER_PROXY_AFFINITIES = [
     "request",
     "operation",
@@ -17,6 +17,20 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ];
 const VALID_PROVIDER_STT_MODES = ["optional", "required"];
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
+const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+// Per-vendor provider-declared credential secrets. A required-mode chain must
+// declare every secret of every credentialed vendor it names, so a missing
+// credential fails at build/validation time rather than during a live outage: a
+// declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
+// exactly the failure class the multi-vendor chain exists to remove. Vendors
+// absent from this map (e.g. `custom`/`decodo`, whose credentials come from the
+// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) impose
+// no declaration requirement.
+const VENDOR_REQUIRED_SECRETS = {
+    smartproxy: [SMARTPROXY_APP_KEY_SECRET],
+    nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
+};
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"];
@@ -137,11 +151,21 @@ function validateProviderProxy(config) {
             fix: `Use proxy: { mode: "required", provider: "smartproxy", geo: { country: "KR" }, session: { affinity: "connection", lifetimeMinutes: 30 } }`,
         });
     }
-    rejectUnknownFields(proxy, new Set(["mode", "provider", "geo", "session"]), "proxy");
+    rejectUnknownFields(proxy, new Set(["mode", "provider", "providers", "geo", "session"]), "proxy");
     assertLiteralField(proxy.mode, "proxy.mode", VALID_PROVIDER_PROXY_MODES, config.id);
     if (proxy.provider !== undefined) {
         assertLiteralField(proxy.provider, "proxy.provider", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
     }
+    if (proxy.providers !== undefined) {
+        if (!Array.isArray(proxy.providers) || proxy.providers.length === 0) {
+            throw new ValidationError(`Provider "${config.id}" has invalid proxy.providers: must be a non-empty array of proxy vendors.`, {
+                fix: `Use proxy.providers: ["smartproxy", "nodemaven"] to declare an ordered fallback chain.`,
+            });
+        }
+        for (const vendor of proxy.providers) {
+            assertLiteralField(vendor, "proxy.providers[]", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
+        }
+    }
     if (proxy.geo !== undefined) {
         if (!proxy.geo || typeof proxy.geo !== "object" || Array.isArray(proxy.geo)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.geo: must be an object.`, {
@@ -178,14 +202,45 @@ function validateProviderProxy(config) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session.poolSize: must be a positive integer.`);
         }
     }
-    if (proxy.mode === "required" && proxy.provider === "smartproxy") {
-        const hasSmartproxySecret = config.secrets?.some((secret) => secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false);
-        if (!hasSmartproxySecret) {
-            throw new ValidationError(`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`, {
-                fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
-            });
+    // Every credentialed vendor in a required-mode chain must declare its
+    // provider secret(s) so a missing credential fails at build/validation time,
+    // not during a live outage. This covers the fallback legs too (not just the
+    // first vendor): a declared-but-uncredentialed nodemaven fallback would leave
+    // the chain silently down to a single vendor, reintroducing the SPOF the chain
+    // removes.
+    const vendorChain = proxy.providers && proxy.providers.length > 0
+        ? proxy.providers
+        : proxy.provider
+            ? [proxy.provider]
+            : [];
+    if (proxy.mode === "required") {
+        for (const vendor of vendorChain) {
+            const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
+            if (!requiredSecrets)
+                continue;
+            for (const secretName of requiredSecrets) {
+                // Match the canonical runtime gate (assertRequiredSecretsPresent /
+                // listMissingRequiredSecrets), which enforces only `required === true`
+                // declarations. A declaration that omits `required` (defaulting to
+                // optional) is skipped at runtime, so accepting it here would pass
+                // validation while leaving the credential unenforced until proxy
+                // resolution during a live request — the fail-open gap this check exists
+                // to close.
+                const declared = config.secrets?.some((secret) => secret.name === secretName && secret.required === true);
+                if (!declared) {
+                    throw new ValidationError(`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`, {
+                        fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
+                    });
+                }
+            }
         }
     }
+    // `decodo`/`custom` are deprecated vendor values (string-union members, so the
+    // @deprecated symbol gate can't catch them — warn at validation time instead).
+    const deprecatedVendors = vendorChain.filter((vendor) => vendor === "decodo" || vendor === "custom");
+    if (deprecatedVendors.length > 0) {
+        console.warn(`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven", or the APIFUSE__PROXY__URL bring-your-own escape hatch.`);
+    }
 }
 function validateProviderStt(config) {
     const stt = config.stt;

package/dist/runtime/choice.js

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
 import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token.js";
-import { ProviderError } from "../errors.js";
+import { isProviderError, ProviderError } from "../errors.js";
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
 const PRIMARY_CHOICE_TOKEN_KID = "v1";
 const MANAGED_CHOICE_TOKEN_VERSION = 1;
@@ -209,7 +209,25 @@ async function parseServerStoredChoice(options) {
         storage,
         contextState: options.contextState,
     });
-    const record = await namespace.get(optionsStateKey(options.handle.state_id));
+    // Reading a server-stored choice back deserializes a persisted value. A
+    // corrupt/undecodable value would otherwise surface as a raw JSON.parse
+    // SyntaxError (or another unexpected throwable) that escapes the choice error
+    // taxonomy, gets masked as internal_error 500, and is treated as retryable by
+    // the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+    // Convert any non-branded throwable into a branded invalid_payload so it maps
+    // to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+    // ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+    // their category/retryable semantics are preserved.
+    let record;
+    try {
+        record = await namespace.get(optionsStateKey(options.handle.state_id));
+    }
+    catch (error) {
+        if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+            throw error;
+        }
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload could not be decoded.");
+    }
     if (!record) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload is missing.");
     }

package/dist/runtime/http.js

@@ -1,4 +1,4 @@
-import { resolveProxyConfigAsync } from "../config/loader.js";
+import { policyRotatesTransportVendorChain, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, } from "../config/loader.js";
 import { ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
@@ -7,6 +7,9 @@ const DEFAULT_HTTP_BASE_URL = "http://localhost";
 function isHttpStatusOutcome(outcome) {
     return "kind" in outcome && outcome.kind === "http-status";
 }
+function isDedupeSkipOutcome(outcome) {
+    return "kind" in outcome && outcome.kind === "dedupe-skip";
+}
 async function sleep(ms) {
     if (ms <= 0)
         return;
@@ -175,6 +178,9 @@ async function resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffs
             baseProxyAttempt: clientOptions.proxyAttempt,
             retryAttemptOffset: proxyAttemptOffset,
         }),
+        // Bun's native fetch proxy option tunnels HTTP CONNECT only; SOCKS5 is not
+        // supported here, so a socks5 policy fails loudly rather than downgrading.
+        transportProtocols: ["http"],
         telemetry: clientOptions.telemetry,
     });
     if (resolvedProxy.shouldWarn) {
@@ -196,7 +202,7 @@ function normalizeNativeFetchBody(body) {
     copied.set(normalized);
     return copied.buffer;
 }
-async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0) {
+async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe) {
     const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
     const controller = options.timeout ? new AbortController() : undefined;
     const timeoutHandle = options.timeout
@@ -204,7 +210,20 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
         : undefined;
     let proxy;
     try {
+        // Resolve inside the try (and after the timeout is armed) so allocator
+        // failures are branded as TransportErrors and count against the request
+        // deadline, exactly as an inline resolve would.
         proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
+        // For a registry allocator chain, skip an endpoint a prior attempt already
+        // tried rather than re-issuing the same request. Returning the sentinel
+        // (instead of breaking) lets the loop keep advancing the flat offset until
+        // it crosses into the fallback vendor's pool span.
+        if (dedupe && proxy) {
+            if (dedupe.attempted.has(proxy)) {
+                return { kind: "dedupe-skip" };
+            }
+            dedupe.attempted.add(proxy);
+        }
         const requestInit = {
             headers: options.headers,
             method,
@@ -325,22 +344,99 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         const attemptOptions = statusRetryEnabled
             ? { ...headersOptions, throwOnHttpError: false }
             : headersOptions;
-        const executeOnce = (proxyAttemptOffset = 0) => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset);
+        // Span the whole vendor chain on transport failures. Like ctx.stealth, a
+        // policy-managed proxy resolves a *different* endpoint/vendor per attempt
+        // (the flat proxyAttemptOffset rotates across the concatenated vendor pool
+        // spans), so a transport failure should advance to the next endpoint —
+        // potentially crossing into the fallback vendor — rather than stopping at
+        // the per-endpoint retry budget and stranding the request on the primary
+        // vendor. resolvePolicyTransportAttemptCap widens the cap to the chain span
+        // only for implicit, safe-method allocator requests; explicit retry
+        // policies (their documented `attempts` ceiling), unsafe methods, and
+        // static/non-registry vendors keep the retry budget. Status-code retries
+        // stay bounded by the retry budget regardless; only transport rotation gets
+        // the full span.
+        const policyProxy = (() => {
+            const policy = clientOptions.proxyPolicy ?? clientOptions.upstream?.proxy;
+            return policy && typeof policy === "object" ? policy : undefined;
+        })();
+        const usesPolicyAllocator = Boolean(policyProxy) && !options.proxy && !clientOptions.proxy;
+        const transportAttemptCap = retryOptions
+            ? resolvePolicyTransportAttemptCap({
+                policy: policyProxy,
+                usesPolicyAllocator,
+                retryAttempts: retryOptions.attempts,
+                explicitRetry,
+                method: methodName,
+            })
+            : 1;
+        // Track resolved endpoints across a policy-allocator chain. Successive
+        // attempts rotate the flat offset across the concatenated vendor pool
+        // spans, but an under-filled allocation (fewer live endpoints than the
+        // configured pool size) makes the modulo mapping repeat endpoints before
+        // the offset reaches the next vendor. Rather than re-hammering an
+        // already-tried endpoint under backoff, fetchNativeHttp returns a skip
+        // sentinel for a duplicate; the loop then advances the flat offset without
+        // issuing the request, so it keeps walking toward — and into — the fallback
+        // vendor's pool span instead of stalling on the primary vendor.
+        // De-duplication is gated on the SAME predicate that widens the attempt cap
+        // (implicit, safe-method, registry-chain rotation). It must NOT engage for
+        // an explicit retry policy: there the caller's `attempts` count is the
+        // contract and each attempt must issue against whatever endpoint it resolves
+        // — even a repeat — instead of being silently skipped (which would collapse
+        // a `poolSize: 1` + `attempts: 3` request to a single fetch).
+        const dedupeAllocatorEndpoints = policyRotatesTransportVendorChain({
+            policy: policyProxy,
+            usesPolicyAllocator,
+            explicitRetry,
+            method: methodName,
+        });
+        const dedupeContext = dedupeAllocatorEndpoints
+            ? { attempted: new Set() }
+            : undefined;
+        const executeOnce = (proxyAttemptOffset = 0) => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset, dedupeContext);
         if (!retryEnabled || !retryOptions) {
             const outcome = await executeOnce();
+            if (isDedupeSkipOutcome(outcome)) {
+                // Single-shot path never de-duplicates (dedupeContext is undefined),
+                // but keep the union total.
+                throw new TransportError("HTTP request produced no terminal result", {
+                    code: "retry_exhausted",
+                });
+            }
             if (isHttpStatusOutcome(outcome)) {
                 throw toUpstreamHttpError(outcome.status);
             }
             return outcome;
         }
+        let lastError;
         let lastErrorCode;
         let lastStatus;
-        for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
+        // `attempt` walks the flat proxy offset across the full chain span; `issued`
+        // counts requests that were actually sent (skipped duplicate offsets do not
+        // increment it). Retry summaries and the status-retry budget must reflect
+        // issued requests, not the raw offset, so they stay accurate when partial
+        // allocations skip offsets.
+        let issued = 0;
+        for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+            // Whether this offset actually issued a request (vs. a skipped duplicate),
+            // so the catch counts a thrown *transport* failure once without
+            // double-counting a status outcome that already incremented before it
+            // re-threw as an upstream HTTP error.
+            let issuedThisAttempt = false;
             try {
                 const outcome = await executeOnce(attempt - 1);
+                if (isDedupeSkipOutcome(outcome)) {
+                    // Duplicate endpoint from a partial allocation: advance the flat
+                    // offset without issuing the request (no backoff, not a failure) so
+                    // the loop keeps rotating toward the fallback vendor.
+                    continue;
+                }
+                issued += 1;
+                issuedThisAttempt = true;
                 if (isHttpStatusOutcome(outcome)) {
                     lastStatus = outcome.status;
-                    if (outcome.retryable && attempt < retryOptions.attempts) {
+                    if (outcome.retryable && issued < retryOptions.attempts) {
                         await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
                         continue;
                     }
@@ -350,10 +446,10 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
                     throw toUpstreamHttpError(response.status);
                 }
-                if (attempt > 1) {
+                if (issued > 1) {
                     const summary = {
-                        attempts: attempt,
-                        retries: attempt - 1,
+                        attempts: issued,
+                        retries: issued - 1,
                         ...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
                         transport: "native",
                         ...(lastErrorCode ? { lastErrorCode } : {}),
@@ -364,10 +460,13 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 return response;
             }
             catch (error) {
+                if (!issuedThisAttempt)
+                    issued += 1;
+                lastError = error;
                 lastErrorCode = proxyTransportRetryErrorCode(error);
                 lastStatus = proxyTransportRetryErrorStatus(error);
                 const proxyUsed = Boolean(error.proxyUsed);
-                if (attempt < retryOptions.attempts &&
+                if (attempt < transportAttemptCap &&
                     shouldRetryProxyTransportAttempt({
                         error,
                         explicitRetry,
@@ -381,6 +480,13 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 throw error;
             }
         }
+        // Reached when the attempt cap is consumed without a terminal outcome —
+        // e.g. the final offsets of a partial allocation all resolved to
+        // already-tried endpoints and were skipped. Surface the last real transport
+        // failure rather than a synthetic exhaustion error.
+        if (lastError !== undefined) {
+            throw lastError;
+        }
         throw new TransportError("HTTP retry exhausted without a terminal result", {
             code: "retry_exhausted",
         });

package/dist/runtime/proxy-errors.js

@@ -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);
 }

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

@@ -0,0 +1,35 @@
+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";
+/** 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 type NodemavenSynthesisInput = {
+    policy: ProviderProxyPolicy;
+    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;
+};
+export type NodemavenSynthesis = {
+    url: string;
+    protocol: ProxyProtocol;
+    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;

package/dist/runtime/proxy-nodemaven.js

@@ -0,0 +1,128 @@
+import { createHash, randomBytes } from "node:crypto";
+export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+export const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+/**
+ * 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 const NODEMAVEN_DEFAULT_PROTOCOL = "http";
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS = {
+    http: { min: 8080, max: 9080 },
+    socks5: { min: 1080, max: 2080 },
+};
+const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
+const DEFAULT_NODEMAVEN_FILTER = "medium";
+const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
+/** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
+const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
+const SID_LENGTH = 10;
+export function hasNodemavenCredentials() {
+    return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+function readNodemavenUsername() {
+    return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+function readNodemavenPassword() {
+    return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+function resolveNodemavenFilter() {
+    const raw = process.env[NODEMAVEN_FILTER_ENV]?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_NODEMAVEN_FILTER;
+    if (!NODEMAVEN_FILTERS.has(raw)) {
+        throw new Error(`${NODEMAVEN_FILTER_ENV} must be "medium" or "high"`);
+    }
+    return raw;
+}
+export function nodemavenPoolSize(policy) {
+    return Math.min(NODEMAVEN_MAX_POOL_SIZE, Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)));
+}
+function nodemavenLifetimeMinutes(policy) {
+    const configured = policy.session?.lifetimeMinutes;
+    if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+        return NODEMAVEN_MAX_LIFETIME_MINUTES;
+    }
+    return Math.min(NODEMAVEN_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configured)));
+}
+/** NodeMaven username tokens accept `[a-z0-9]`; slugify geo values to that set. */
+function slugifyGeo(value) {
+    if (!value)
+        return undefined;
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "");
+    return slug || undefined;
+}
+function isStickyAffinity(policy) {
+    return (policy.session?.affinity ?? "request") !== "request";
+}
+/**
+ * A sticky sid is deterministic from the affinity key so every process serving
+ * the same connection derives the same egress IP without shared storage. A
+ * rotating sid is random per call (a fresh egress IP per request).
+ */
+function deriveSid(policy, affinityKey, poolIndex, refreshEpoch) {
+    if (!isStickyAffinity(policy) || !affinityKey) {
+        return randomBytes(SID_LENGTH).toString("hex").slice(0, SID_LENGTH);
+    }
+    const digest = createHash("sha256")
+        .update(`${affinityKey}:${refreshEpoch}:${poolIndex}`)
+        .digest("hex");
+    // hex digits are a subset of the allowed [a-z0-9] sid charset.
+    return digest.slice(0, SID_LENGTH);
+}
+function selectPort(protocol, sid, poolIndex) {
+    const { min, max } = NODEMAVEN_PORTS[protocol];
+    const span = max - min + 1;
+    const hashInt = Number.parseInt(createHash("sha256").update(`${sid}:${poolIndex}`).digest("hex").slice(0, 8), 16);
+    return min + (hashInt % span);
+}
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export function synthesizeNodemavenProxy(input) {
+    const username = readNodemavenUsername();
+    const password = readNodemavenPassword();
+    if (!username || !password) {
+        throw new Error(`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`);
+    }
+    const filter = resolveNodemavenFilter();
+    const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
+    const port = selectPort(input.protocol, sid, input.poolIndex);
+    const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);
+    const country = slugifyGeo(input.country ?? input.policy.geo?.country);
+    const region = slugifyGeo(input.policy.geo?.subdivision);
+    const city = slugifyGeo(input.policy.geo?.city);
+    const tokens = [username];
+    if (country)
+        tokens.push("country", country);
+    if (region)
+        tokens.push("region", region);
+    if (city)
+        tokens.push("city", city);
+    tokens.push("sid", sid);
+    tokens.push("filter", filter);
+    tokens.push("ipv4", "true");
+    const proxyUsername = tokens.join("-");
+    // Username tokens are [a-z0-9-] only, which survive URL encoding unchanged.
+    const url = `${input.protocol}://${proxyUsername}:${encodeURIComponent(password)}@${NODEMAVEN_GATEWAY_HOST}:${port}`;
+    return {
+        url,
+        protocol: input.protocol,
+        diagnostics: {
+            vendor: "nodemaven",
+            protocol: input.protocol,
+            sticky: isStickyAffinity(input.policy),
+            filter,
+            lifetimeMinutes,
+            ...(country ? { country } : {}),
+        },
+    };
+}

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

@@ -1,8 +1,9 @@
-import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink } from "../config/loader.js";
+import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyVendorFailoverTelemetryEvent } from "../config/loader.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
     #private;
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
+    recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void;
     recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void;
     toHeaderValue(): string | undefined;
 }

package/dist/runtime/proxy-telemetry.js

@@ -1,6 +1,7 @@
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const MAX_PROXY_FAILOVER_SAMPLES = 12;
 const CACHE_STATUS_SEVERITY = {
     disabled: 0,
     memory_hit: 1,
@@ -28,9 +29,11 @@ function encodeBase64Url(value) {
 export class ProxyTelemetryCollector {
     #events = [];
     #attempts = [];
+    #failovers = [];
     recordProxyResolution(event) {
         this.#events.push({
-            provider: "smartproxy",
+            provider: event.provider,
+            ...(event.protocol ? { protocol: event.protocol } : {}),
             cacheStatus: event.cacheStatus,
             cacheHit: event.cacheHit,
             resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
@@ -53,11 +56,22 @@ export class ProxyTelemetryCollector {
             refreshes: event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
         });
     }
+    recordProxyVendorFailover(event) {
+        if (this.#failovers.length >= MAX_PROXY_FAILOVER_SAMPLES)
+            return;
+        this.#failovers.push({
+            vendor: event.vendor,
+            ...(event.nextVendor ? { nextVendor: event.nextVendor } : {}),
+            phase: event.phase,
+            reason: event.reason,
+            ...(event.attempt === undefined ? {} : { attempt: Math.max(0, Math.floor(event.attempt)) }),
+        });
+    }
     recordProxyAttempt(event) {
         if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES)
             return;
         this.#attempts.push({
-            provider: "smartproxy",
+            provider: event.provider,
             attempt: Math.max(1, Math.floor(event.attempt || 1)),
             ...(event.poolIndex === undefined
                 ? {}
@@ -75,8 +89,16 @@ export class ProxyTelemetryCollector {
         const [first, ...rest] = this.#events;
         if (!first)
             return undefined;
+        // The serving vendor/protocol is the last recorded resolution (a failed
+        // vendor records first, the vendor that served records last).
+        const serving = this.#events[this.#events.length - 1] ?? first;
+        const vendors = [];
+        for (const event of this.#events) {
+            if (!vendors.includes(event.provider))
+                vendors.push(event.provider);
+        }
         const aggregate = rest.reduce((acc, event) => ({
-            provider: "smartproxy",
+            provider: event.provider,
             cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
             cacheHit: acc.cacheHit && event.cacheHit,
             resolutionMs: acc.resolutionMs + event.resolutionMs,
@@ -95,7 +117,8 @@ export class ProxyTelemetryCollector {
         const payload = {
             v: 1,
             proxy: {
-                provider: "smartproxy",
+                provider: serving.provider,
+                ...(serving.protocol ? { protocol: serving.protocol } : {}),
                 cacheStatus: aggregate.cacheStatus,
                 cacheHit: aggregate.cacheHit,
                 resolutionMs: aggregate.resolutionMs,
@@ -132,6 +155,18 @@ export class ProxyTelemetryCollector {
                         })),
                     }
                     : {}),
+                ...(vendors.length > 1 ? { vendors } : {}),
+                ...(this.#failovers.length > 0
+                    ? {
+                        failovers: this.#failovers.map((failover) => ({
+                            v: failover.vendor,
+                            ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+                            p: failover.phase,
+                            r: failover.reason,
+                            ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
+                        })),
+                    }
+                    : {}),
             },
         };
         const encoded = encodeBase64Url(JSON.stringify(payload));

package/dist/runtime/state.js

@@ -69,7 +69,18 @@ function resolveExpiresAt(ttl) {
 function envelopeFromJson(key, raw) {
     if (!raw)
         return null;
-    const parsed = JSON.parse(raw);
+    // A corrupt/undecodable persisted envelope must be treated as absent rather
+    // than throwing a raw JSON.parse SyntaxError: an uncaught SyntaxError escapes
+    // the provider error taxonomy, is masked as internal_error 500, and is then
+    // retried by the hub (2026-07-22 catchtable reserve RCA, candidate A). Returning
+    // null also keeps list() from aborting the whole scan on a single bad entry.
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
         return null;
     }