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

package/src/define.ts

@@ -78,7 +78,7 @@ const VALID_RUNTIMES = ["standard", "shared", "browser"] as const;
 const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"] as const;
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"] as const;
-const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "decodo", "custom"] as const;
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"] as const;
 const VALID_PROVIDER_PROXY_AFFINITIES = [
 	"request",
 	"operation",
@@ -371,11 +371,24 @@ function validateProviderProxy(config: {
 			},
 		);
 	}
-	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(
@@ -433,7 +446,16 @@ function validateProviderProxy(config: {
 			);
 		}
 	}
-	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,
 		);
@@ -446,6 +468,16 @@ 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: { id: string; stt?: ProviderSttConfig }): void {

package/src/runtime/http.ts

@@ -256,6 +256,9 @@ async function resolveNativeProxy(
 			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/src/runtime/proxy-errors.ts

@@ -19,10 +19,18 @@ 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: string): boolean {
 	return PROXY_AUTH_IP_DENIED_PATTERN.test(message);

package/src/runtime/proxy-nodemaven.ts

@@ -0,0 +1,178 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import type { ProviderProxyPolicy } from "../types.js";
+
+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";
+
+/** 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 const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol = "http";
+
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS: Record<ProxyProtocol, { min: number; max: number }> = {
+	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;
+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(): boolean {
+	return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+
+function readNodemavenUsername(): string | undefined {
+	return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+
+function readNodemavenPassword(): string | undefined {
+	return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+
+function resolveNodemavenFilter(): string {
+	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: ProviderProxyPolicy): number {
+	return Math.min(
+		NODEMAVEN_MAX_POOL_SIZE,
+		Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)),
+	);
+}
+
+function nodemavenLifetimeMinutes(policy: ProviderProxyPolicy): number {
+	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: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const slug = value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "");
+	return slug || undefined;
+}
+
+function isStickyAffinity(policy: ProviderProxyPolicy): boolean {
+	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: ProviderProxyPolicy,
+	affinityKey: string | undefined,
+	poolIndex: number,
+	refreshEpoch: number,
+): string {
+	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: ProxyProtocol, sid: string, poolIndex: number): number {
+	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);
+}
+
+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 function synthesizeNodemavenProxy(input: NodemavenSynthesisInput): NodemavenSynthesis {
+	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/src/runtime/proxy-telemetry.ts

@@ -1,8 +1,11 @@
 import type {
 	ProxyAttemptTelemetryEvent,
 	ProxyCacheStatus,
+	ProxyProtocol,
 	ProxyResolutionTelemetryEvent,
 	ProxyTelemetrySink,
+	ProxyVendorFailoverTelemetryEvent,
+	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
 } from "../config/loader.js";
 
@@ -11,7 +14,8 @@ export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 type ProviderTelemetryHeader = {
 	v: 1;
 	proxy?: {
-		provider: "smartproxy";
+		provider: ProxyVendorName;
+		protocol?: ProxyProtocol;
 		cacheStatus: ProxyCacheStatus;
 		cacheHit: boolean;
 		resolutionMs: number;
@@ -27,6 +31,10 @@ type ProviderTelemetryHeader = {
 		attempts: number;
 		refreshes?: number;
 		attemptSamples?: CompactProxyAttemptSample[];
+		/** Distinct vendors attempted across the resolution chain, in order seen. */
+		vendors?: ProxyVendorName[];
+		/** Cross-vendor failover events (bounded). */
+		failovers?: CompactVendorFailoverSample[];
 	};
 };
 
@@ -41,8 +49,17 @@ type CompactProxyAttemptSample = {
 	d?: number;
 };
 
+type CompactVendorFailoverSample = {
+	v: ProxyVendorName;
+	nx?: ProxyVendorName;
+	p: "resolution" | "transport";
+	r: ProxyVendorFailoverTelemetryEvent["reason"];
+	a?: number;
+};
+
 const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const MAX_PROXY_FAILOVER_SAMPLES = 12;
 
 const CACHE_STATUS_SEVERITY: Record<ProxyCacheStatus, number> = {
 	disabled: 0,
@@ -76,10 +93,12 @@ function encodeBase64Url(value: string): string {
 export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 	#events: ProxyResolutionTelemetryEvent[] = [];
 	#attempts: ProxyAttemptTelemetryEvent[] = [];
+	#failovers: ProxyVendorFailoverTelemetryEvent[] = [];
 
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
 		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)),
@@ -112,10 +131,21 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		});
 	}
 
+	recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void {
+		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: ProxyAttemptTelemetryEvent): void {
 		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
 				? {}
@@ -134,9 +164,17 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		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: ProxyVendorName[] = [];
+		for (const event of this.#events) {
+			if (!vendors.includes(event.provider)) vendors.push(event.provider);
+		}
+
 		const aggregate = rest.reduce<ProxyResolutionTelemetryEvent>(
 			(acc, event) => ({
-				provider: "smartproxy",
+				provider: event.provider,
 				cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
 				cacheHit: acc.cacheHit && event.cacheHit,
 				resolutionMs: acc.resolutionMs + event.resolutionMs,
@@ -157,7 +195,8 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		const payload: ProviderTelemetryHeader = {
 			v: 1,
 			proxy: {
-				provider: "smartproxy",
+				provider: serving.provider,
+				...(serving.protocol ? { protocol: serving.protocol } : {}),
 				cacheStatus: aggregate.cacheStatus,
 				cacheHit: aggregate.cacheHit,
 				resolutionMs: aggregate.resolutionMs,
@@ -194,6 +233,18 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 							})),
 						}
 					: {}),
+				...(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 }),
+							})),
+						}
+					: {}),
 			},
 		};
 

package/src/runtime/stealth.ts

@@ -2,13 +2,15 @@ import { createHash } from "node:crypto";
 import type { Browser, ImpitOptions, ImpitResponse, RequestInit } from "impit";
 import { Impit } from "impit";
 
-import type { ProxyResolutionOptions } from "../config/loader.js";
+import type { ProxyResolutionOptions, ProxyVendorName } from "../config/loader.js";
 import {
 	DEFAULT_SMARTPROXY_POOL_SIZE,
 	invalidateProxyResolutionCacheAsync,
 	ProxyResolutionError,
+	resolvePolicyProxyPoolSpan,
 	resolveProxyConfigAsync,
 	SMARTPROXY_MAX_POOL_SIZE,
+	vendorFromResolvedSource,
 } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
@@ -51,7 +53,11 @@ const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING =
 	"[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
 
-const MAX_POLICY_PROXY_RETRY_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE;
+/**
+ * Upper bound on attempts across a multi-vendor chain, so a two-vendor chain can
+ * exhaust each vendor's pool before failing over and finally throwing.
+ */
+const MAX_POLICY_PROXY_TOTAL_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE * 2;
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
 const PROXY_CONNECT_FAILURE_BODY_PATTERN =
@@ -426,6 +432,7 @@ type ResolvedAttemptProxy = {
 	url?: string;
 	poolIndex?: number;
 	proxyHash?: string;
+	vendor?: ProxyVendorName;
 };
 
 function proxyPoolIndexFromDiagnostics(
@@ -615,6 +622,7 @@ function createSessionFetcher(
 	async function resolveRequestProxy(
 		options?: StealthFetchOptions,
 		proxyAttempt?: number,
+		refreshEpoch?: number,
 	): Promise<ResolvedAttemptProxy> {
 		const resolvedProxy = await resolveProxyConfigAsync({
 			proxy: options?.proxy ?? clientOptions.proxy,
@@ -626,6 +634,10 @@ function createSessionFetcher(
 				proxyAttemptOffset: options?.proxyAttemptOffset,
 				retryAttemptOffset: proxyAttempt,
 			}),
+			// The impit stealth transport tunnels both HTTP CONNECT and SOCKS5,
+			// preserving the client TLS fingerprint end-to-end.
+			transportProtocols: ["http", "socks5"],
+			...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
 			telemetry: clientOptions.telemetry,
 		});
 
@@ -638,6 +650,7 @@ function createSessionFetcher(
 			url: resolvedProxy.url,
 			poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
 			proxyHash: proxyEndpointHash(resolvedProxy.url),
+			vendor: vendorFromResolvedSource(resolvedProxy.source),
 		};
 	}
 
@@ -662,15 +675,18 @@ function createSessionFetcher(
 			const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
 			const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
 			const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
+			// Span the whole vendor chain: successive attempts rotate one vendor's
+			// pool, then fail over to the next vendor via the flat attempt index.
+			const policyProxy =
+				clientOptions.proxyPolicy ??
+				(typeof clientOptions.upstream?.proxy === "object"
+					? clientOptions.upstream.proxy
+					: undefined);
 			const policyProxyAttemptCap = Math.max(
 				1,
 				Math.min(
-					MAX_POLICY_PROXY_RETRY_ATTEMPTS,
-					clientOptions.proxyPolicy?.session?.poolSize ??
-						(typeof clientOptions.upstream?.proxy === "object"
-							? clientOptions.upstream.proxy.session?.poolSize
-							: undefined) ??
-						DEFAULT_SMARTPROXY_POOL_SIZE,
+					MAX_POLICY_PROXY_TOTAL_ATTEMPTS,
+					policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE,
 				),
 			);
 			const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
@@ -698,7 +714,7 @@ function createSessionFetcher(
 						if (attemptRecorded || !proxy) return;
 						attemptRecorded = true;
 						clientOptions.telemetry?.recordProxyAttempt?.({
-							provider: "smartproxy",
+							provider: attemptProxy?.vendor ?? "smartproxy",
 							attempt: attempt + 1,
 							...(attemptProxy?.poolIndex === undefined
 								? {}
@@ -712,7 +728,7 @@ function createSessionFetcher(
 					};
 					try {
 						assertNoUnsupportedFingerprintOverrides(options);
-						attemptProxy = await resolveRequestProxy(options, attempt);
+						attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
 						proxy = attemptProxy.url;
 						if (proxy && usesPolicyAllocator) {
 							if (attemptedProxies.has(proxy)) {

package/src/types.ts

@@ -769,7 +769,25 @@ export type ProviderAccessVisibility = "public" | "early_access";
 
 export type ProviderProxyMode = "disabled" | "optional" | "required";
 
-export type ProviderProxyProvider = "smartproxy" | "decodo" | "custom";
+/**
+ * Proxy egress vendors. These are FOUR DISTINCT services — do not conflate them
+ * (a common mistake because the names collide with a well-known rebrand):
+ *
+ * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
+ *   *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *   endpoints). This is our own vendor. It is NOT the company formerly named
+ *   "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
+ *   credentials; geo/session encoded in the username, no allocation API.
+ * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
+ *   (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *   username params. A different company from `smartproxy` above.
+ *   **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
+ *   or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
+ *   `APIFUSE__PROXY__URL` env still works without declaring this value.
+ */
+export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 
 export type ProviderProxySessionAffinity =
 	| "request"
@@ -783,7 +801,18 @@ export interface ProviderProxyPolicy {
 	 * certificate verification, and vendor allocator endpoints are SDK-owned.
 	 */
 	mode: ProviderProxyMode;
+	/**
+	 * @deprecated Use `providers: [...]` to declare an ordered vendor fallback
+	 * chain. A single-element `providers` list is equivalent to this field.
+	 */
 	provider?: ProviderProxyProvider;
+	/**
+	 * Ordered proxy-vendor fallback chain. The SDK tries each vendor in order and
+	 * fails over to the next when a vendor lacks credentials or its allocation /
+	 * transport is exhausted. When omitted, `provider` (or the platform default)
+	 * is used as a single-vendor chain.
+	 */
+	providers?: ProviderProxyProvider[];
 	geo?: {
 		/** ISO 3166-1 alpha-2 country code, for example KR or US. */
 		country?: Iso3166Alpha2CountryCode;