@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.8

package/dist/config/loader.js

@@ -2,6 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { Redis } from "ioredis";
+import { NODEMAVEN_DEFAULT_PROTOCOL, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
+// "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
+// extraction API (app_key → raw ip:port pool). It is NOT the company formerly
+// named Smartproxy (smartproxy.com), which rebranded to Decodo in 2025 and is
+// modelled separately as the `decodo` gateway vendor. Do not conflate them.
 export const SMARTPROXY_APP_KEY_ENV = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 export const SMARTPROXY_MAX_LIFETIME_MINUTES = 2000;
 export const DEFAULT_SMARTPROXY_POOL_SIZE = 20;
@@ -15,11 +20,17 @@ export const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
 export class ProxyResolutionError extends Error {
     code;
     telemetry;
+    vendor;
+    vendorChain;
+    protocol;
     constructor(code, message, options) {
         super(message, options);
         this.name = "ProxyResolutionError";
         this.code = code;
         this.telemetry = options?.telemetry;
+        this.vendor = options?.vendor;
+        this.vendorChain = options?.vendorChain;
+        this.protocol = options?.protocol;
     }
 }
 const proxyCache = new Map();
@@ -232,6 +243,11 @@ function applyStickyProxySession(proxyUrl) {
     if (!parsed.hostname || !parsed.username || !parsed.password) {
         return proxyUrl;
     }
+    // This rewrites sticky-session usernames for a bring-your-own *gateway* URL
+    // (APIFUSE__PROXY__URL). The `smartproxy` host here means a smartproxy.com /
+    // Decodo-family gateway that authenticates by username — NOT the
+    // api.smartproxy.org allocation vendor, whose endpoints are raw ip:port with
+    // no credentials and therefore return early above.
     const host = parsed.hostname.toLowerCase();
     if (!host.includes("smartproxy") && !host.includes("decodo")) {
         return proxyUrl;
@@ -299,47 +315,173 @@ export async function resolveProxyConfigAsync(options = {}) {
     if (policy.mode === "disabled") {
         return { shouldWarn: false };
     }
-    const provider = resolveProxyProvider(policy);
-    if (provider !== "smartproxy") {
+    const chain = resolveVendorChain(policy);
+    if (chain.length === 0) {
+        // decodo/custom/env-static providers keep the legacy static-URL path.
         return resolveProxyConfig({
             ...options,
             upstream: { proxy: true },
         });
     }
-    const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
-    if (!appKey) {
-        if (policy.mode === "required") {
-            throw new ProxyResolutionError("PROXY_REQUIRED", `Smartproxy egress is required but ${SMARTPROXY_APP_KEY_ENV} is not configured.`);
+    // Protocol is chosen per vendor (each vendor's benchmarked-best), with an
+    // optional explicit override for the harness/tests. Both are tunnelling
+    // schemes. transportProtocols is what the calling transport can actually use.
+    const transportProtocols = options.transportProtocols ?? ["http", "socks5"];
+    const sizes = chain.map((vendor) => vendorPoolSize(vendor, policy));
+    const total = sizes.reduce((sum, size) => sum + size, 0);
+    const normalizedAttempt = normalizeAttemptIndex(options.proxyAttempt);
+    const { vendorIndex: startVendorIndex, poolIndex: startPoolIndex } = mapFlatAttempt(total > 0 ? normalizedAttempt % total : 0, sizes);
+    const refreshEpoch = normalizeAttemptIndex(options.proxyRefreshEpoch);
+    let lastError;
+    let blockedProtocol;
+    for (let vendorIndex = startVendorIndex; vendorIndex < chain.length; vendorIndex++) {
+        const vendor = chain[vendorIndex];
+        const nextVendor = chain[vendorIndex + 1];
+        const poolIndex = vendorIndex === startVendorIndex ? startPoolIndex : 0;
+        const protocol = options.protocol ?? VENDOR_DEFAULT_PROTOCOL[vendor];
+        if (!vendorHasCredentials(vendor)) {
+            options.telemetry?.recordProxyVendorFailover?.({
+                vendor,
+                nextVendor,
+                phase: "resolution",
+                reason: "no_credentials",
+            });
+            continue;
+        }
+        // The calling transport must be able to use this vendor's protocol; if not,
+        // fail over to the next vendor rather than silently downgrading.
+        if (!transportProtocols.includes(protocol)) {
+            blockedProtocol = protocol;
+            options.telemetry?.recordProxyVendorFailover?.({
+                vendor,
+                nextVendor,
+                phase: "resolution",
+                reason: "protocol_unsupported",
+            });
+            continue;
+        }
+        try {
+            return await resolveWithVendor(vendor, policy, options, {
+                protocol,
+                poolIndex,
+                refreshEpoch,
+            });
+        }
+        catch (error) {
+            // Config/programming errors (invalid filter, etc.) are not vendor
+            // outages — propagate them rather than failing over.
+            if (!(error instanceof ProxyResolutionError)) {
+                throw error;
+            }
+            if (error.telemetry) {
+                options.telemetry?.recordProxyResolution(error.telemetry);
+            }
+            lastError = error;
+            options.telemetry?.recordProxyVendorFailover?.({
+                vendor,
+                nextVendor,
+                phase: "resolution",
+                reason: "allocation_failed",
+            });
         }
-        return { shouldWarn: true };
     }
-    const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+    if (policy.mode === "required") {
+        if (lastError) {
+            throw lastError instanceof ProxyResolutionError
+                ? lastError
+                : new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `All proxy vendors [${chain.join(", ")}] failed for required proxy egress.`, { cause: lastError, vendorChain: chain });
+        }
+        if (blockedProtocol) {
+            throw new ProxyResolutionError("PROXY_PROTOCOL_UNSUPPORTED", `No proxy vendor in [${chain.join(", ")}] could serve a protocol supported by this transport (supports: ${transportProtocols.join(", ")}; vendor wanted "${blockedProtocol}"). Route this provider through the stealth transport.`, { protocol: blockedProtocol, vendorChain: chain });
+        }
+        throw new ProxyResolutionError("PROXY_REQUIRED", `Proxy egress is required but no vendor credentials are configured. Missing: ${chain
+            .map((vendor) => `${missingCredentialEnv(vendor)} (${vendor})`)
+            .join(", ")}.`, { vendorChain: chain });
+    }
+    return { shouldWarn: true };
+}
+/**
+ * Each vendor's default egress protocol, chosen from live KR benchmarks. HTTP
+ * CONNECT wins for nodemaven (socks5 adds ~500ms through the gateway) and ties
+ * for smartproxy, and is the only protocol ctx.http (Bun native fetch) supports.
+ * Override per call via ProxyResolutionOptions.protocol (harness/tests).
+ */
+const VENDOR_DEFAULT_PROTOCOL = {
+    smartproxy: "http",
+    nodemaven: NODEMAVEN_DEFAULT_PROTOCOL,
+};
+/**
+ * Guard the No-MITM invariant: a resolved proxy URL must use a tunnelling scheme
+ * (http CONNECT or socks5) so the client TLS handshake reaches the origin
+ * end-to-end. Anything else would intercept TLS and break fingerprinting.
+ */
+export function assertTunnelingScheme(url) {
+    let scheme;
     try {
-        const allocated = await allocateSmartproxy(policy, appKey, lifetimeMinutes, options.affinityKey);
-        options.telemetry?.recordProxyResolution(allocated.telemetry);
-        const poolIndex = selectProxyPoolIndex(allocated.pool.urls.length, options.proxyAttempt);
+        scheme = new URL(url).protocol.replace(/:$/, "").toLowerCase();
+    }
+    catch {
+        throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `Malformed proxy URL: ${url}`);
+    }
+    if (scheme !== "http" && scheme !== "socks5") {
+        throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `Resolved proxy scheme "${scheme}" is not a tunnelling scheme (expected http or socks5). Refusing to route TLS through a non-tunnelling proxy.`);
+    }
+}
+async function resolveWithVendor(vendor, policy, options, context) {
+    if (vendor === "nodemaven") {
+        const startedAt = Date.now();
+        const synthesized = synthesizeNodemavenProxy({
+            policy,
+            affinityKey: options.affinityKey,
+            protocol: context.protocol,
+            poolIndex: context.poolIndex,
+            refreshEpoch: context.refreshEpoch,
+            country: resolveSmartproxyCountry(policy),
+        });
+        options.telemetry?.recordProxyResolution({
+            provider: "nodemaven",
+            protocol: synthesized.protocol,
+            cacheStatus: "disabled",
+            cacheHit: false,
+            resolutionMs: Math.max(0, Date.now() - startedAt),
+            attempts: 1,
+        });
+        assertTunnelingScheme(synthesized.url);
         return {
             shouldWarn: false,
-            url: allocated.pool.urls[poolIndex],
-            source: "smartproxy-allocator",
+            url: synthesized.url,
+            source: "nodemaven-gateway",
+            protocol: synthesized.protocol,
             diagnostics: {
-                ...allocated.pool.diagnostics,
-                poolSize: allocated.pool.urls.length,
-                poolIndex,
+                ...synthesized.diagnostics,
+                poolIndex: context.poolIndex,
             },
         };
     }
-    catch (error) {
-        if (error instanceof ProxyResolutionError && error.telemetry) {
-            options.telemetry?.recordProxyResolution(error.telemetry);
-        }
-        if (policy.mode === "required") {
-            throw error instanceof ProxyResolutionError
-                ? error
-                : new ProxyResolutionError("PROXY_ALLOCATION_FAILED", "Smartproxy allocator failed for required proxy egress.", { cause: error });
-        }
-        return { shouldWarn: true };
+    // smartproxy allocation-style vendor.
+    const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+    if (!appKey) {
+        // Guarded by vendorHasCredentials; treated as a vendor-internal failure.
+        throw new ProxyResolutionError("PROXY_ALLOCATION_FAILED", `${SMARTPROXY_APP_KEY_ENV} is not configured.`, { vendor: "smartproxy" });
     }
+    const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+    const allocated = await allocateSmartproxy(policy, appKey, lifetimeMinutes, options.affinityKey, context.protocol);
+    options.telemetry?.recordProxyResolution({ ...allocated.telemetry, protocol: context.protocol });
+    const poolIndex = selectProxyPoolIndex(allocated.pool.urls.length, context.poolIndex);
+    const url = allocated.pool.urls[poolIndex];
+    if (url)
+        assertTunnelingScheme(url);
+    return {
+        shouldWarn: false,
+        url,
+        source: "smartproxy-allocator",
+        protocol: context.protocol,
+        diagnostics: {
+            ...allocated.pool.diagnostics,
+            poolSize: allocated.pool.urls.length,
+            poolIndex,
+        },
+    };
 }
 function resolvePolicy(options) {
     if (options.proxyPolicy) {
@@ -351,8 +493,80 @@ function resolvePolicy(options) {
     }
     return undefined;
 }
-function resolveProxyProvider(policy) {
-    return (policy.provider ?? process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase() ?? "custom");
+function isRegistryVendor(name) {
+    return name === "smartproxy" || name === "nodemaven";
+}
+/**
+ * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
+ * takes precedence over the legacy singular `provider`; the platform default
+ * env is the final fallback. Non-registry names (decodo/custom) are dropped so
+ * an all-static chain falls through to the legacy env-URL path unchanged.
+ */
+export function resolveVendorChain(policy) {
+    const declared = policy.providers?.length
+        ? policy.providers
+        : [policy.provider ?? envDefaultProvider()];
+    const chain = [];
+    for (const name of declared) {
+        if (isRegistryVendor(name) && !chain.includes(name)) {
+            chain.push(name);
+        }
+    }
+    return chain;
+}
+function envDefaultProvider() {
+    const raw = process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase();
+    return raw ?? undefined;
+}
+function vendorHasCredentials(vendor) {
+    if (vendor === "nodemaven")
+        return hasNodemavenCredentials();
+    return Boolean(process.env[SMARTPROXY_APP_KEY_ENV]?.trim());
+}
+function missingCredentialEnv(vendor) {
+    return vendor === "nodemaven" ? "APIFUSE__PROXY__NODEMAVEN_USERNAME" : SMARTPROXY_APP_KEY_ENV;
+}
+function vendorPoolSize(vendor, policy) {
+    return vendor === "nodemaven" ? nodemavenPoolSize(policy) : resolveSmartproxyPoolSize(policy);
+}
+/**
+ * Total attempt span across a policy's vendor chain — the sum of each vendor's
+ * pool size. Transports use this so successive attempts rotate a vendor's pool
+ * and then fail over to the next vendor via the flat attempt index. With one
+ * vendor this equals that vendor's pool size (today's behaviour).
+ */
+export function resolvePolicyProxyPoolSpan(policy) {
+    const chain = resolveVendorChain(policy);
+    if (chain.length === 0)
+        return resolveSmartproxyPoolSize(policy);
+    return chain.reduce((sum, vendor) => sum + vendorPoolSize(vendor, policy), 0);
+}
+/** Map a resolved proxy source label to the vendor that served it. */
+export function vendorFromResolvedSource(source) {
+    if (source === "nodemaven-gateway")
+        return "nodemaven";
+    if (source === "smartproxy-allocator")
+        return "smartproxy";
+    return undefined;
+}
+function normalizeAttemptIndex(attempt) {
+    return Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
+}
+/**
+ * Map a flat attempt index into (vendorIndex, poolIndex) by concatenating each
+ * vendor's pool space in chain order. With a single vendor this reduces to
+ * `attempt % poolSize`, preserving today's behaviour exactly.
+ */
+export function mapFlatAttempt(flat, sizes) {
+    let cursor = flat;
+    for (let vendorIndex = 0; vendorIndex < sizes.length; vendorIndex++) {
+        const size = Math.max(1, sizes[vendorIndex] ?? 1);
+        if (cursor < size) {
+            return { vendorIndex, poolIndex: cursor };
+        }
+        cursor -= size;
+    }
+    return { vendorIndex: 0, poolIndex: 0 };
 }
 function resolveSmartproxyCountry(policy) {
     return (policy.geo?.country ?? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ?? undefined);
@@ -381,10 +595,11 @@ function selectProxyPoolIndex(poolSize, attempt = 0) {
     const normalizedAttempt = Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
     return normalizedAttempt % poolSize;
 }
-function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes) {
+function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol) {
     const poolSize = resolveSmartproxyPoolSize(policy);
     return JSON.stringify({
         provider: "smartproxy",
+        protocol,
         country: resolveSmartproxyCountry(policy),
         affinity: policy.session?.affinity ?? "request",
         affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
@@ -392,8 +607,8 @@ function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes) {
         poolSize,
     });
 }
-async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey) {
-    const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes);
+async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey, protocol) {
+    const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol);
     const startedAt = Date.now();
     const now = startedAt;
     const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
@@ -401,7 +616,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey)
     const cached = proxyCache.get(cacheKey);
     if (!skipCached && cached && isFresh(cached, now)) {
         if (shouldSoftRefresh(cached, now)) {
-            void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes);
+            void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol);
             return {
                 pool: cached,
                 telemetry: telemetryForPool(cached, "soft_stale_refresh", startedAt, {
@@ -429,7 +644,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey)
             }),
         };
     }
-    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt).finally(() => {
+    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol).finally(() => {
         proxyInflight.delete(cacheKey);
     });
     proxyInflight.set(cacheKey, promise);
@@ -460,9 +675,9 @@ async function readSmartproxyRedisPool(cacheKey, startedAt) {
         telemetry: telemetryForPool(pool, "redis_hit", startedAt, { redisReadMs }),
     };
 }
-async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes) {
+async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol) {
     try {
-        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), {
+        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), protocol, {
             background: true,
         });
     }
@@ -470,10 +685,10 @@ async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes)
         // Soft refresh is opportunistic; current fresh pool remains usable.
     }
 }
-async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, options = {}) {
+async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, options = {}) {
     const redis = getProxyRedis();
     if (!redis || !(await ensureRedisReady(redis))) {
-        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator" });
+        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator", protocol });
     }
     const poolKey = smartproxyRedisPoolKey(cacheKey);
     const lockKey = smartproxyRedisLockKey(cacheKey);
@@ -487,6 +702,7 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
                     cacheStatus: options.background ? "soft_stale_refresh" : "allocator",
                     redis,
                     poolKey,
+                    protocol,
                 });
             }
             finally {
@@ -599,7 +815,7 @@ async function readSmartproxyAllocatorBodyWithDeadline(response, signal) {
 }
 async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, options) {
     const poolSize = resolveSmartproxyPoolSize(policy);
-    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize);
+    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, options.protocol);
     const allocatorStartedAt = Date.now();
     const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
     let allocation;
@@ -609,7 +825,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
             lastFailure = smartproxyAllocatorDeadlineFailure(attempt);
             break;
         }
-        const attemptResult = await fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, allocatorDeadlineAt);
+        const attemptResult = await fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, allocatorDeadlineAt, options.protocol);
         if (attemptResult.ok) {
             allocation = attemptResult;
             break;
@@ -692,7 +908,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
         }),
     };
 }
-async function fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, deadlineAt) {
+async function fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, deadlineAt, protocol) {
     const { controller, dispose } = createDeadlineAbortController(deadlineAt);
     let response;
     try {
@@ -735,7 +951,7 @@ async function fetchSmartproxyAllocatorAttempt(allocatorUrl, attempt, deadlineAt
             bodyClass: "http_error",
         };
     }
-    const urls = parseSmartproxyAllocatorProxies(body);
+    const urls = parseSmartproxyAllocatorProxies(body, protocol);
     const bodyClass = classifySmartproxyAllocatorBody(body, urls);
     if (urls.length === 0) {
         return {
@@ -770,13 +986,20 @@ function smartproxyAllocatorFailureMessage(failure) {
     }
     return "Smartproxy allocator response did not contain a usable proxy endpoint.";
 }
-function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize) {
+// Smartproxy get-ip-v3 `protocol` param: 1 = HTTP. The SOCKS5 value ("2") is a
+// best-effort mapping pending live vendor confirmation; http is the default and
+// the only value exercised in production today.
+const SMARTPROXY_PROTOCOL_PARAM = {
+    http: "1",
+    socks5: "2",
+};
+function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, protocol) {
     const params = new URLSearchParams({
         app_key: appKey,
         pt: "9",
         num: String(poolSize),
         life: String(lifetimeMinutes),
-        protocol: "1",
+        protocol: SMARTPROXY_PROTOCOL_PARAM[protocol],
         format: "txt",
         lb: "\\n",
     });
@@ -788,7 +1011,8 @@ function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize)
     // old path 404s into the marketing site); the API lives on the api host.
     return `https://api.smartproxy.org/web_v1/ip/get-ip-v3?${params.toString()}`;
 }
-function parseSmartproxyAllocatorProxies(body) {
+function parseSmartproxyAllocatorProxies(body, protocol) {
+    const scheme = protocol === "socks5" ? "socks5" : "http";
     const trimmed = body.trim();
     if (!trimmed) {
         return [];
@@ -807,7 +1031,7 @@ function parseSmartproxyAllocatorProxies(body) {
                 const port = "port" in item && (typeof item.port === "string" || typeof item.port === "number")
                     ? item.port
                     : "";
-                return ip && port ? `http://${ip}:${port}` : null;
+                return ip && port ? `${scheme}://${ip}:${port}` : null;
             })
                 .filter((url) => url !== null);
         }
@@ -819,7 +1043,7 @@ function parseSmartproxyAllocatorProxies(body) {
         .split(/\r?\n/)
         .map((item) => item.trim())
         .filter((item) => /^\d{1,3}(?:\.\d{1,3}){3}:\d{2,5}$/.test(item))
-        .map((line) => `http://${line}`);
+        .map((line) => `${scheme}://${line}`);
 }
 function classifySmartproxyAllocatorBody(body, urls) {
     if (urls.length > 0) {
@@ -847,11 +1071,11 @@ function markSmartproxyCacheInvalidated(options = {}) {
     if (!policy || policy.mode === "disabled") {
         return undefined;
     }
-    if (resolveProxyProvider(policy) !== "smartproxy") {
+    if (!resolveVendorChain(policy).includes("smartproxy")) {
         return undefined;
     }
     const lifetimeMinutes = resolveSmartproxyLifetime(policy);
-    const cacheKey = buildSmartproxyCacheKey(policy, options.affinityKey, lifetimeMinutes);
+    const cacheKey = buildSmartproxyCacheKey(policy, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);
     invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
     proxyCache.delete(cacheKey);
     proxyInflight.delete(cacheKey);

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",
@@ -137,11 +137,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,7 +188,15 @@ 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") {
+    // Smartproxy uses a provider-declared secret; when it is a required-mode
+    // vendor (singular or in the chain) the app key must be declared so a missing
+    // credential fails at build/validation time, not during a live outage.
+    const vendorChain = proxy.providers && proxy.providers.length > 0
+        ? proxy.providers
+        : proxy.provider
+            ? [proxy.provider]
+            : [];
+    if (proxy.mode === "required" && vendorChain.includes("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}.`, {
@@ -186,6 +204,12 @@ function validateProviderProxy(config) {
             });
         }
     }
+    // `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/index.d.ts

@@ -27,6 +27,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";

package/dist/index.js

@@ -24,6 +24,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
 export { createStealthClient } from "./runtime/stealth.js";
 export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";

package/dist/runtime/executor.js

@@ -1,5 +1,6 @@
 import { isSessionExpiredError, ProviderError, SessionExpiredError } from "../errors.js";
 import { parseSchema } from "../schema.js";
+import { assertRequiredSecretsPresent } from "./secrets.js";
 export function isStreamingOperation(provider, operationId) {
     const kind = provider.operations[operationId]?.transport?.kind ?? "json";
     return kind !== "json";
@@ -23,6 +24,12 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }
+    // SDK-owned secret presence gate (single source of truth): declared
+    // `required: true` secrets are validated here, before input parsing and the
+    // handler, so every invocation path (serve /v1, self-test probes, perf,
+    // record) fails with the same structured MISSING_SECRET error instead of a
+    // handler-specific crash. Providers must not re-check presence locally.
+    assertRequiredSecretsPresent(provider, ctx.env);
     const validatedInput = await parseSchema(operation.input, input, `operations.${operationId}.input`);
     const execute = () => ctx.trace.span(`handler:${operationId}`, () => Promise.resolve(operation.handler(ctx, validatedInput)));
     let result;

package/dist/runtime/http.js

@@ -175,6 +175,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) {

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,34 @@
+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 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;