@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/src/config/loader.ts

@@ -1,11 +1,32 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import path from "node:path";
 
-import { Redis } from "ioredis";
-
-import type { ProviderProxyPolicy, TraceConfig } from "../types.js";
-
+import type { Redis } from "ioredis";
+
+import type { ProviderProxyPolicy, ProviderProxyProvider, TraceConfig } from "../types.js";
+import {
+	NODEMAVEN_DEFAULT_PROTOCOL,
+	NODEMAVEN_FILTER_ENV,
+	NODEMAVEN_MAX_POOL_SIZE,
+	NODEMAVEN_PASSWORD_ENV,
+	NODEMAVEN_USERNAME_ENV,
+	type ProxyProtocol,
+	hasNodemavenCredentials,
+	nodemavenPoolSize,
+	synthesizeNodemavenProxy,
+} from "../runtime/proxy-nodemaven.js";
+
+export type { ProxyProtocol } from "../runtime/proxy-nodemaven.js";
+
+/** Proxy vendors with SDK-managed resolution. */
+export type ProxyVendorName = "smartproxy" | "nodemaven";
+
+// "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;
@@ -17,15 +38,6 @@ export const PROVIDER_CACHE_REDIS_URL_ENV = "APIFUSE__PROVIDER__CACHE_REDIS_URL"
 export const PROVIDER_STATE_REDIS_URL_ENV = "APIFUSE__PROVIDER__STATE_REDIS_URL";
 export const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
 
-export type ProxyOptions = {
-	url: string;
-};
-
-export type ProxyConfig = Partial<ProxyOptions> & {
-	provider?: string;
-	apiKey?: string;
-};
-
 export type BrowserConfig = {
 	executablePath?: string;
 	headless?: boolean;
@@ -37,7 +49,6 @@ export type SessionConfig = {
 };
 
 export type ApiFuseConfig = {
-	proxy?: ProxyConfig;
 	browser?: BrowserConfig;
 	session?: SessionConfig;
 	trace?: TraceConfig;
@@ -47,11 +58,30 @@ export type ApiFuseConfig = {
 export type ProxyResolutionOptions = {
 	proxy?: string;
 	upstream?: { proxy?: boolean | ProviderProxyPolicy };
-	apifuseConfig?: Pick<ApiFuseConfig, "proxy">;
 	proxyPolicy?: ProviderProxyPolicy;
 	affinityKey?: string;
 	/** Zero-based proxy-pool attempt index used by SDK transports for failover. */
 	proxyAttempt?: number;
+	/**
+	 * Tunnelling protocols the calling transport can use. When a resolved
+	 * protocol is not in this set the resolver fails with
+	 * `PROXY_PROTOCOL_UNSUPPORTED` instead of silently downgrading. Unset means
+	 * permissive (both protocols allowed).
+	 */
+	transportProtocols?: readonly ProxyProtocol[];
+	/**
+	 * Explicit protocol override. Internal — for the verification harness and
+	 * tests, or an advanced caller. Normal callers omit it and each vendor uses
+	 * its own benchmarked default protocol (see VENDOR_DEFAULT_PROTOCOL). Not an
+	 * env var and not a provider-policy field.
+	 */
+	protocol?: ProxyProtocol;
+	/**
+	 * Gateway pool "refresh" generation. Bumped by transports on pool refresh to
+	 * derive a fresh gateway session set (ignored by allocation-style vendors,
+	 * whose refresh is driven by cache invalidation).
+	 */
+	proxyRefreshEpoch?: number;
 	telemetry?: ProxyTelemetrySink;
 };
 
@@ -73,8 +103,14 @@ export type SmartproxyAllocatorBodyClass =
 	| "text_without_proxies"
 	| "usable_proxy_endpoints";
 
+export type ProxyUserAgentSource = "declared" | "defaulted";
+
 export type ProxyResolutionTelemetryEvent = {
-	provider: "smartproxy";
+	provider: ProxyVendorName;
+	/** Defaults to `"ok"` when omitted. */
+	outcome?: "ok" | "error";
+	userAgentSource?: ProxyUserAgentSource;
+	protocol?: ProxyProtocol;
 	cacheStatus: ProxyCacheStatus;
 	cacheHit: boolean;
 	resolutionMs: number;
@@ -92,7 +128,7 @@ export type ProxyResolutionTelemetryEvent = {
 };
 
 export type ProxyAttemptTelemetryEvent = {
-	provider: "smartproxy";
+	provider: ProxyVendorName;
 	attempt: number;
 	poolIndex?: number;
 	proxyHash?: string;
@@ -102,31 +138,69 @@ export type ProxyAttemptTelemetryEvent = {
 	durationMs?: number;
 };
 
+export type ProxyVendorFailoverTelemetryEvent = {
+	/** Vendor that failed or was skipped. */
+	vendor: ProxyVendorName;
+	/** Vendor tried next, or undefined when the chain is exhausted. */
+	nextVendor?: ProxyVendorName;
+	phase: "resolution" | "transport";
+	reason: "no_credentials" | "allocation_failed" | "pool_exhausted" | "protocol_unsupported";
+	attempt?: number;
+};
+
 export type ProxyTelemetrySink = {
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
 	recordProxyAttempt?(event: ProxyAttemptTelemetryEvent): void;
+	recordProxyVendorFailover?(event: ProxyVendorFailoverTelemetryEvent): void;
 };
 
+export type ProxyResolutionSource =
+	| "explicit"
+	| "env"
+	| "config"
+	| "smartproxy-allocator"
+	| "nodemaven-gateway";
+
 export type ResolvedProxyConfig = {
 	shouldWarn: boolean;
 	url?: string;
-	source?: "explicit" | "env" | "config" | "smartproxy-allocator";
+	/** SDK-native vendor that supplied the URL, when applicable. */
+	vendor?: ProxyVendorName;
+	source?: ProxyResolutionSource;
+	protocol?: ProxyProtocol;
 	diagnostics?: Record<string, string | number | boolean>;
 };
 
+export type ProxyResolutionErrorCode =
+	| "PROXY_REQUIRED"
+	| "PROXY_ALLOCATION_FAILED"
+	| "PROXY_PROTOCOL_UNSUPPORTED";
+
 export class ProxyResolutionError extends Error {
-	readonly code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED";
+	readonly code: ProxyResolutionErrorCode;
 	readonly telemetry?: ProxyResolutionTelemetryEvent;
+	readonly vendor?: ProxyVendorName;
+	readonly vendorChain?: ProxyVendorName[];
+	readonly protocol?: ProxyProtocol;
 
 	constructor(
-		code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED",
+		code: ProxyResolutionErrorCode,
 		message: string,
-		options?: { cause?: unknown; telemetry?: ProxyResolutionTelemetryEvent },
+		options?: {
+			cause?: unknown;
+			telemetry?: ProxyResolutionTelemetryEvent;
+			vendor?: ProxyVendorName;
+			vendorChain?: ProxyVendorName[];
+			protocol?: ProxyProtocol;
+		},
 	) {
 		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;
 	}
 }
 
@@ -149,6 +223,7 @@ type ProxyRedisClient = Pick<
 >;
 
 const proxyCache = new Map<string, CachedProxyPool>();
+const require = createRequire(import.meta.url);
 const proxyInflight = new Map<string, Promise<SmartproxyAllocationResult>>();
 const invalidatedProxyKeys = new Map<string, number>();
 const redisClients = new Map<string, ProxyRedisClient>();
@@ -208,7 +283,8 @@ function getProxyRedis(): ProxyRedisClient | undefined {
 	const existing = redisClients.get(redisUrl);
 	if (existing) return existing;
 
-	const redis = new Redis(redisUrl, {
+	const { Redis: RedisClient } = require("ioredis") as typeof import("ioredis");
+	const redis = new RedisClient(redisUrl, {
 		connectTimeout: REDIS_TIMEOUT_MS,
 		enableOfflineQueue: false,
 		lazyConnect: true,
@@ -296,6 +372,7 @@ function telemetryForFailure(
 ): ProxyResolutionTelemetryEvent {
 	return {
 		provider: "smartproxy",
+		outcome: "error",
 		cacheStatus,
 		cacheHit: false,
 		resolutionMs: Math.max(0, Date.now() - startedAt),
@@ -365,70 +442,7 @@ function serializeSmartproxyPool(pool: CachedProxyPool): string {
 
 function normalizeProxyUrl(url?: string): string | undefined {
 	const normalized = url?.trim();
-	return normalized ? applyStickyProxySession(normalized) : undefined;
-}
-
-function readPositiveIntegerEnv(name: string): string | undefined {
-	const raw = process.env[name]?.trim();
-	if (!raw) return undefined;
-	if (!/^[1-9]\d*$/.test(raw)) {
-		throw new Error(`${name} must be a positive integer`);
-	}
-	return raw;
-}
-
-function applyStickyProxySession(proxyUrl: string): string {
-	let parsed: URL;
-	try {
-		parsed = new URL(proxyUrl);
-	} catch {
-		return proxyUrl;
-	}
-
-	if (!parsed.hostname || !parsed.username || !parsed.password) {
-		return proxyUrl;
-	}
-
-	const host = parsed.hostname.toLowerCase();
-	if (!host.includes("smartproxy") && !host.includes("decodo")) {
-		return proxyUrl;
-	}
-
-	const username = decodeURIComponent(parsed.username);
-	const sessionId = process.env.APIFUSE__PROXY__SESSION_ID?.trim() || "apifuse-shared";
-	const sessionDuration = readPositiveIntegerEnv("APIFUSE__PROXY__SESSION_DURATION");
-	const stickyUsername = host.includes("smartproxy")
-		? buildSmartproxyUsername(username, sessionId, sessionDuration)
-		: buildDecodoUsername(username, sessionId, sessionDuration ?? "60");
-
-	parsed.username = stickyUsername;
-	return parsed.toString();
-}
-
-function buildSmartproxyUsername(
-	username: string,
-	sessionId: string,
-	sessionDuration?: string,
-): string {
-	const parts = username.split("_");
-	const configuredLife = parts.find((part) => part.startsWith("life-"))?.slice("life-".length);
-	const baseUsername = parts
-		.filter((part) => !part.startsWith("session-") && !part.startsWith("life-"))
-		.join("_");
-	return `${baseUsername}_session-${sessionId}_life-${sessionDuration ?? configuredLife ?? "60"}`;
-}
-
-function buildDecodoUsername(username: string, sessionId: string, sessionDuration: string): string {
-	const withoutSticky = username.replace(/-session-.+-sessionduration-\d+$/, "");
-	const baseUsername = withoutSticky.startsWith("user-") ? withoutSticky : `user-${withoutSticky}`;
-	return `${baseUsername}-session-${sessionId}-sessionduration-${sessionDuration}`;
-}
-
-function syncProxyEnv(config: ApiFuseConfig): void {
-	const configProxyUrl = normalizeProxyUrl(config.proxy?.url);
-	if (!process.env.APIFUSE__PROXY__URL && configProxyUrl) {
-		process.env.APIFUSE__PROXY__URL = configProxyUrl;
-	}
+	return normalized || undefined;
 }
 
 export function resolveProxyConfig(options: ProxyResolutionOptions = {}): ResolvedProxyConfig {
@@ -448,16 +462,6 @@ export function resolveProxyConfig(options: ProxyResolutionOptions = {}): Resolv
 		return { shouldWarn: false };
 	}
 
-	const envProxyUrl = normalizeProxyUrl(process.env.APIFUSE__PROXY__URL);
-	if (envProxyUrl) {
-		return { shouldWarn: false, url: envProxyUrl };
-	}
-
-	const configuredProxyUrl = normalizeProxyUrl(options.apifuseConfig?.proxy?.url);
-	if (configuredProxyUrl) {
-		return { shouldWarn: false, url: configuredProxyUrl };
-	}
-
 	return { shouldWarn: true };
 }
 
@@ -477,60 +481,285 @@ export async function resolveProxyConfigAsync(
 		return { shouldWarn: false };
 	}
 
-	const provider = resolveProxyProvider(policy);
-	if (provider !== "smartproxy") {
+	const chain = resolveVendorChain(policy);
+	if (chain.length === 0) {
+		const declared = declaredVendorChain(policy);
+		const deprecated = declared.filter((vendor) => vendor === "decodo" || vendor === "custom");
+		if (policy.mode === "required") {
+			const providerIds =
+				declared.length > 0 ? declared.map((vendor) => `"${vendor}"`).join(", ") : "none";
+			const deprecatedDetail =
+				deprecated.length > 0
+					? ` Deprecated vendor(s): ${deprecated.map((vendor) => `"${vendor}"`).join(", ")}.`
+					: "";
+			throw new ProxyResolutionError(
+				"PROXY_REQUIRED",
+				`Required proxy policy has no SDK-managed adapter for provider id(s): ${providerIds}.${deprecatedDetail} Use "smartproxy" or "nodemaven".`,
+			);
+		}
+		// Deprecated decodo/custom providers have no SDK-managed adapter. Optional
+		// policies preserve the warning-only behavior and may continue directly.
 		return resolveProxyConfig({
 			...options,
 			upstream: { proxy: true },
 		});
 	}
 
-	const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
-	if (!appKey) {
-		if (policy.mode === "required") {
+	// 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"] as const);
+
+	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: unknown;
+	let blockedProtocol: ProxyProtocol | undefined;
+	for (let vendorIndex = startVendorIndex; vendorIndex < chain.length; vendorIndex++) {
+		const vendor = chain[vendorIndex] as ProxyVendorName;
+		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",
+			});
+		}
+	}
+
+	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_REQUIRED",
-				`Smartproxy egress is required but ${SMARTPROXY_APP_KEY_ENV} is not configured.`,
+				"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 },
 			);
 		}
-		return { shouldWarn: true };
+		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 },
+		);
 	}
-	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+	return { shouldWarn: true };
+}
 
+/**
+ * Resolve the proxy URL for a provider-owned consumer such as a CAPTCHA solver.
+ * Vendor allocation and failover remain owned by the SDK.
+ */
+export async function resolveProxy(
+	options: ProxyResolutionOptions = {},
+): Promise<ResolvedProxyConfig> {
+	const resolved = await resolveProxyConfigAsync(options);
+	const vendor = vendorFromResolvedSource(resolved.source);
+	return vendor ? { ...resolved, vendor } : resolved;
+}
+
+/**
+ * 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).
+ */
+export const VENDOR_DEFAULT_PROTOCOL: Readonly<Record<ProxyVendorName, ProxyProtocol>> = {
+	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: string): void {
+	let scheme: string;
 	try {
-		const allocated = await allocateSmartproxy(
-			policy,
-			appKey,
-			lifetimeMinutes,
-			options.affinityKey,
+		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.`,
 		);
-		options.telemetry?.recordProxyResolution(allocated.telemetry);
-		const poolIndex = selectProxyPoolIndex(allocated.pool.urls.length, options.proxyAttempt);
+	}
+}
+
+export type ProxyVendorResolutionContext = {
+	readonly protocol: ProxyProtocol;
+	readonly poolIndex: number;
+	readonly refreshEpoch: number;
+	/** Explicit vendor credentials. Omit only on the legacy ambient-env path. */
+	readonly credentials?: Readonly<Record<string, string>>;
+	/** Disable non-policy env defaults for deterministic injected adapters. */
+	readonly ambientDefaults?: boolean;
+	/** Disable env-discovered Redis sharing for deterministic injected adapters. */
+	readonly sharedCache?: boolean;
+};
+
+export async function resolveWithVendor(
+	vendor: ProxyVendorName,
+	policy: ProviderProxyPolicy,
+	options: ProxyResolutionOptions,
+	context: ProxyVendorResolutionContext,
+): Promise<ResolvedProxyConfig> {
+	if (vendor === "nodemaven") {
+		const startedAt = Date.now();
+		const username = (
+			context.credentials === undefined
+				? process.env[NODEMAVEN_USERNAME_ENV]
+				: context.credentials[NODEMAVEN_USERNAME_ENV]
+		)?.trim();
+		const password = (
+			context.credentials === undefined
+				? process.env[NODEMAVEN_PASSWORD_ENV]
+				: context.credentials[NODEMAVEN_PASSWORD_ENV]
+		)?.trim();
+		const filter =
+			context.credentials === undefined
+				? process.env[NODEMAVEN_FILTER_ENV]
+				: context.credentials[NODEMAVEN_FILTER_ENV];
+		if (!username || !password) {
+			throw new ProxyResolutionError(
+				"PROXY_ALLOCATION_FAILED",
+				`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`,
+				{ vendor: "nodemaven" },
+			);
+		}
+		const synthesized = synthesizeNodemavenProxy({
+			policy,
+			credentials: {
+				username,
+				password,
+				...(filter ? { filter } : {}),
+			},
+			affinityKey: options.affinityKey,
+			protocol: context.protocol,
+			poolIndex: context.poolIndex,
+			refreshEpoch: context.refreshEpoch,
+			country: resolveSmartproxyCountry(policy, context.ambientDefaults !== false),
+		});
+		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 = (
+		context.credentials === undefined
+			? process.env[SMARTPROXY_APP_KEY_ENV]
+			: context.credentials[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, context.ambientDefaults !== false);
+	const allocated = await allocateSmartproxy(
+		policy,
+		appKey,
+		lifetimeMinutes,
+		options.affinityKey,
+		context.protocol,
+		context.ambientDefaults !== false,
+		context.sharedCache !== false,
+	);
+	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: ProxyResolutionOptions): ProviderProxyPolicy | undefined {
@@ -544,21 +773,221 @@ function resolvePolicy(options: ProxyResolutionOptions): ProviderProxyPolicy | u
 	return undefined;
 }
 
-function resolveProxyProvider(policy: ProviderProxyPolicy): string {
-	return (
-		policy.provider ?? process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase() ?? "custom"
+function isRegistryVendor(name: string | undefined): name is ProxyVendorName {
+	return name === "smartproxy" || name === "nodemaven";
+}
+
+function declaredVendorChain(policy: ProviderProxyPolicy): ProviderProxyProvider[] {
+	const declared = policy.providers?.length
+		? policy.providers
+		: [policy.provider ?? envDefaultProvider()];
+	return declared.filter((vendor): vendor is ProviderProxyProvider => vendor !== undefined);
+}
+
+/**
+ * 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-deprecated chain has no managed adapter.
+ */
+export function resolveVendorChain(policy: ProviderProxyPolicy): ProxyVendorName[] {
+	const chain: ProxyVendorName[] = [];
+	for (const name of declaredVendorChain(policy)) {
+		if (isRegistryVendor(name) && !chain.includes(name)) {
+			chain.push(name);
+		}
+	}
+	return chain;
+}
+
+function envDefaultProvider(): ProviderProxyProvider | undefined {
+	const raw = process.env[DEFAULT_PROXY_PROVIDER_ENV]?.trim().toLowerCase();
+	return (raw as ProviderProxyProvider | undefined) ?? undefined;
+}
+
+function vendorHasCredentials(vendor: ProxyVendorName): boolean {
+	if (vendor === "nodemaven") return hasNodemavenCredentials();
+	return Boolean(process.env[SMARTPROXY_APP_KEY_ENV]?.trim());
+}
+
+function missingCredentialEnv(vendor: ProxyVendorName): string {
+	return vendor === "nodemaven" ? "APIFUSE__PROXY__NODEMAVEN_USERNAME" : SMARTPROXY_APP_KEY_ENV;
+}
+
+function vendorPoolSize(vendor: ProxyVendorName, policy: ProviderProxyPolicy): number {
+	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: ProviderProxyPolicy): number {
+	const chain = resolveVendorChain(policy);
+	if (chain.length === 0) return resolveSmartproxyPoolSize(policy);
+	return chain.reduce((sum, vendor) => sum + vendorPoolSize(vendor, policy), 0);
+}
+
+function vendorMaxPoolSize(vendor: ProxyVendorName): number {
+	return vendor === "nodemaven" ? NODEMAVEN_MAX_POOL_SIZE : SMARTPROXY_MAX_POOL_SIZE;
+}
+
+/**
+ * Absolute upper bound on a chain's attempt span — the sum of each vendor's
+ * *maximum* pool size. Unlike `resolvePolicyProxyPoolSpan` (the configured
+ * span), this backstop is independent of `session.poolSize`, so it never
+ * truncates a legitimately large pool below the point where the flat attempt
+ * index would cross into the next vendor (e.g. a 50-slot NodeMaven pool).
+ */
+export function maxPolicyProxyPoolSpan(policy: ProviderProxyPolicy): number {
+	const chain = resolveVendorChain(policy);
+	if (chain.length === 0) return SMARTPROXY_MAX_POOL_SIZE;
+	return chain.reduce((sum, vendor) => sum + vendorMaxPoolSize(vendor), 0);
+}
+
+const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE", "TRACE"]);
+
+/**
+ * Transport-retry attempt cap for a policy-managed request. A transport failure
+ * rotates the flat attempt index onto the *next* endpoint (and, once the index
+ * passes the primary vendor's pool span, the *next vendor*), so the cap must be
+ * the chain's full pool span for failover to reach the fallback vendor — the
+ * per-endpoint retry budget (default 3) never gets there.
+ *
+ * The span only widens beyond the caller's retry budget when ALL hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — `HttpRetryOptions.attempts`
+ *    is the documented total-attempt ceiling and must be honoured verbatim;
+ *  - the method is safe/idempotent — an unsafe request must never be duplicated
+ *    across the pool even if some framework default would allow it;
+ *  - the policy resolves a non-empty *registry* vendor chain (smartproxy /
+ *    nodemaven). Deprecated vendors (custom / decodo) resolve no managed pool,
+ *    so there is no possible endpoint crossover — they keep the retry budget.
+ *
+ * The widened cap is bounded by the chain's true maximum span (sum of each
+ * vendor's max pool size), so a large NodeMaven pool (≤50) stays reachable and
+ * a pathological chain can never spin unbounded.
+ */
+/**
+ * True when a policy request is in *implicit chain-rotation* mode: successive
+ * transport attempts rotate the flat index across the concatenated vendor pool
+ * spans (and, past the primary vendor's span, into the fallback vendor). This is
+ * the ONLY mode in which the transport loop widens its attempt cap AND
+ * de-duplicates repeated endpoints — the two behaviours must share one predicate
+ * so they never diverge. It holds when ALL of the widening conditions hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — its `attempts` ceiling is
+ *    the documented contract and must be honoured verbatim against whatever
+ *    endpoint each attempt resolves (even a repeated one), so no de-duplication;
+ *  - the method is safe/idempotent — an unsafe request is never duplicated;
+ *  - the policy resolves a non-empty registry vendor chain (smartproxy /
+ *    nodemaven). Deprecated vendors (custom / decodo) resolve no managed
+ *    endpoint, so there is nothing to rotate or de-duplicate.
+ */
+export function policyRotatesTransportVendorChain(input: {
+	policy: ProviderProxyPolicy | undefined;
+	usesPolicyAllocator: boolean;
+	explicitRetry: boolean;
+	method: string;
+}): boolean {
+	if (!input.usesPolicyAllocator || !input.policy || input.explicitRetry) {
+		return false;
+	}
+	if (UNSAFE_TRANSPORT_RETRY_METHODS.has(input.method.toUpperCase())) {
+		return false;
+	}
+	return resolveVendorChain(input.policy).length > 0;
+}
+
+export function resolvePolicyTransportAttemptCap(input: {
+	policy: ProviderProxyPolicy | undefined;
+	usesPolicyAllocator: boolean;
+	retryAttempts: number;
+	explicitRetry: boolean;
+	method: string;
+}): number {
+	const budget = Math.max(1, Math.floor(input.retryAttempts));
+	if (
+		!policyRotatesTransportVendorChain({
+			policy: input.policy,
+			usesPolicyAllocator: input.usesPolicyAllocator,
+			explicitRetry: input.explicitRetry,
+			method: input.method,
+		})
+	) {
+		return budget;
+	}
+	const span = Math.min(
+		maxPolicyProxyPoolSpan(input.policy as ProviderProxyPolicy),
+		resolvePolicyProxyPoolSpan(input.policy as ProviderProxyPolicy),
 	);
+	return Math.max(budget, span);
+}
+
+/**
+ * A registry vendor chain (smartproxy/nodemaven) resolves a potentially
+ * *different* endpoint per flat attempt index, so a transport retry should
+ * advance across endpoints and de-duplicate once the chain stops yielding new
+ * ones. Deprecated custom/decodo policies have an empty registry chain and no
+ * managed endpoint, so the transport loop has nothing to rotate or de-duplicate.
+ */
+export function policyResolvesRegistryVendorChain(
+	policy: ProviderProxyPolicy | undefined,
+): boolean {
+	return Boolean(policy) && resolveVendorChain(policy as ProviderProxyPolicy).length > 0;
+}
+
+/** Map a resolved proxy source label to the vendor that served it. */
+export function vendorFromResolvedSource(
+	source: ResolvedProxyConfig["source"],
+): ProxyVendorName | undefined {
+	if (source === "nodemaven-gateway") return "nodemaven";
+	if (source === "smartproxy-allocator") return "smartproxy";
+	return undefined;
+}
+
+function normalizeAttemptIndex(attempt: number | undefined): number {
+	return Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt as number)) : 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: number,
+	sizes: readonly number[],
+): { vendorIndex: number; poolIndex: number } {
+	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: ProviderProxyPolicy): string | undefined {
+function resolveSmartproxyCountry(
+	policy: ProviderProxyPolicy,
+	ambientDefaults = true,
+): string | undefined {
 	return (
-		policy.geo?.country ?? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ?? undefined
+		policy.geo?.country ??
+		(ambientDefaults
+			? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() || undefined
+			: undefined)
 	);
 }
 
-function resolveSmartproxyLifetime(policy: ProviderProxyPolicy): number {
+function resolveSmartproxyLifetime(policy: ProviderProxyPolicy, ambientDefaults = true): number {
 	const configuredLifetime =
-		policy.session?.lifetimeMinutes ?? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30);
+		policy.session?.lifetimeMinutes ??
+		(ambientDefaults ? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30) : 30);
 	return Math.min(SMARTPROXY_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configuredLifetime)));
 }
 
@@ -589,13 +1018,21 @@ function selectProxyPoolIndex(poolSize: number, attempt = 0): number {
 
 function buildSmartproxyCacheKey(
 	policy: ProviderProxyPolicy,
+	appKey: string,
 	affinityKey: string | undefined,
 	lifetimeMinutes: number,
+	protocol: ProxyProtocol,
+	ambientDefaults = true,
 ): string {
 	const poolSize = resolveSmartproxyPoolSize(policy);
 	return JSON.stringify({
 		provider: "smartproxy",
-		country: resolveSmartproxyCountry(policy),
+		credentialHash: createHash("sha256")
+			.update("apifuse-smartproxy-credential:v1\0")
+			.update(appKey)
+			.digest("hex"),
+		protocol,
+		country: resolveSmartproxyCountry(policy, ambientDefaults),
 		affinity: policy.session?.affinity ?? "request",
 		affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
 		lifetimeMinutes,
@@ -608,8 +1045,18 @@ async function allocateSmartproxy(
 	appKey: string,
 	lifetimeMinutes: number,
 	affinityKey: string | undefined,
+	protocol: ProxyProtocol,
+	ambientDefaults = true,
+	sharedCache = true,
 ): Promise<SmartproxyAllocationResult> {
-	const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes);
+	const cacheKey = buildSmartproxyCacheKey(
+		policy,
+		appKey,
+		affinityKey,
+		lifetimeMinutes,
+		protocol,
+		ambientDefaults,
+	);
 	const startedAt = Date.now();
 	const now = startedAt;
 	const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
@@ -617,7 +1064,15 @@ async function allocateSmartproxy(
 	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,
+				ambientDefaults,
+				sharedCache,
+			);
 			return {
 				pool: cached,
 				telemetry: telemetryForPool(cached, "soft_stale_refresh", startedAt, {
@@ -631,7 +1086,7 @@ async function allocateSmartproxy(
 		};
 	}
 
-	if (!skipCached) {
+	if (!skipCached && sharedCache) {
 		const redisResult = await readSmartproxyRedisPool(cacheKey, startedAt);
 		if (redisResult) return redisResult;
 	}
@@ -653,6 +1108,9 @@ async function allocateSmartproxy(
 		appKey,
 		lifetimeMinutes,
 		startedAt,
+		protocol,
+		ambientDefaults,
+		sharedCache,
 	).finally(() => {
 		proxyInflight.delete(cacheKey);
 	});
@@ -691,11 +1149,24 @@ async function refreshSmartproxyPool(
 	policy: ProviderProxyPolicy,
 	appKey: string,
 	lifetimeMinutes: number,
+	protocol: ProxyProtocol,
+	ambientDefaults: boolean,
+	sharedCache: boolean,
 ): Promise<void> {
 	try {
-		await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), {
-			background: true,
-		});
+		await allocateSmartproxyShared(
+			cacheKey,
+			policy,
+			appKey,
+			lifetimeMinutes,
+			Date.now(),
+			protocol,
+			ambientDefaults,
+			sharedCache,
+			{
+				background: true,
+			},
+		);
 	} catch {
 		// Soft refresh is opportunistic; current fresh pool remains usable.
 	}
@@ -707,9 +1178,12 @@ async function allocateSmartproxyShared(
 	appKey: string,
 	lifetimeMinutes: number,
 	startedAt: number,
+	protocol: ProxyProtocol,
+	ambientDefaults: boolean,
+	sharedCache: boolean,
 	options: { background?: boolean } = {},
 ): Promise<SmartproxyAllocationResult> {
-	const redis = getProxyRedis();
+	const redis = sharedCache ? getProxyRedis() : undefined;
 	if (!redis || !(await ensureRedisReady(redis))) {
 		return await allocateAndStoreSmartproxyPool(
 			cacheKey,
@@ -717,7 +1191,7 @@ async function allocateSmartproxyShared(
 			appKey,
 			lifetimeMinutes,
 			startedAt,
-			{ cacheStatus: "allocator" },
+			{ cacheStatus: "allocator", protocol, ambientDefaults },
 		);
 	}
 
@@ -742,6 +1216,8 @@ async function allocateSmartproxyShared(
 						cacheStatus: options.background ? "soft_stale_refresh" : "allocator",
 						redis,
 						poolKey,
+						protocol,
+						ambientDefaults,
 					},
 				);
 			} finally {
@@ -897,10 +1373,19 @@ async function allocateAndStoreSmartproxyPool(
 		cacheStatus: ProxyCacheStatus;
 		redis?: ProxyRedisClient;
 		poolKey?: string;
+		protocol: ProxyProtocol;
+		ambientDefaults: boolean;
 	},
 ): Promise<SmartproxyAllocationResult> {
 	const poolSize = resolveSmartproxyPoolSize(policy);
-	const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize);
+	const allocatorUrl = buildSmartproxyAllocatorUrl(
+		policy,
+		appKey,
+		lifetimeMinutes,
+		poolSize,
+		options.protocol,
+		options.ambientDefaults,
+	);
 	const allocatorStartedAt = Date.now();
 	const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
 	let allocation: SmartproxyAllocatorSuccess | undefined;
@@ -914,6 +1399,7 @@ async function allocateAndStoreSmartproxyPool(
 			allocatorUrl,
 			attempt,
 			allocatorDeadlineAt,
+			options.protocol,
 		);
 		if (attemptResult.ok) {
 			allocation = attemptResult;
@@ -969,7 +1455,7 @@ async function allocateAndStoreSmartproxyPool(
 		expiresAt: allocatedAt + ttlMs,
 		diagnostics: {
 			provider: "smartproxy",
-			country: resolveSmartproxyCountry(policy) ?? "default",
+			country: resolveSmartproxyCountry(policy, options.ambientDefaults) ?? "default",
 			lifetimeMinutes,
 			affinity: policy.session?.affinity ?? "request",
 			rawConnect: true,
@@ -1034,6 +1520,7 @@ async function fetchSmartproxyAllocatorAttempt(
 	allocatorUrl: string,
 	attempt: number,
 	deadlineAt: number,
+	protocol: ProxyProtocol,
 ): Promise<SmartproxyAllocatorAttemptResult> {
 	const { controller, dispose } = createDeadlineAbortController(deadlineAt);
 	let response: Response;
@@ -1077,7 +1564,7 @@ async function fetchSmartproxyAllocatorAttempt(
 		};
 	}
 
-	const urls = parseSmartproxyAllocatorProxies(body);
+	const urls = parseSmartproxyAllocatorProxies(body, protocol);
 	const bodyClass = classifySmartproxyAllocatorBody(body, urls);
 	if (urls.length === 0) {
 		return {
@@ -1117,22 +1604,32 @@ function smartproxyAllocatorFailureMessage(
 	return "Smartproxy allocator response did not contain a usable proxy endpoint.";
 }
 
+// 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: Record<ProxyProtocol, string> = {
+	http: "1",
+	socks5: "2",
+};
+
 function buildSmartproxyAllocatorUrl(
 	policy: ProviderProxyPolicy,
 	appKey: string,
 	lifetimeMinutes: number,
 	poolSize: number,
+	protocol: ProxyProtocol,
+	ambientDefaults = true,
 ): string {
 	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",
 	});
-	const country = resolveSmartproxyCountry(policy);
+	const country = resolveSmartproxyCountry(policy, ambientDefaults);
 	if (country) {
 		params.set("cc", country);
 	}
@@ -1141,7 +1638,8 @@ function buildSmartproxyAllocatorUrl(
 	return `https://api.smartproxy.org/web_v1/ip/get-ip-v3?${params.toString()}`;
 }
 
-function parseSmartproxyAllocatorProxies(body: string): string[] {
+function parseSmartproxyAllocatorProxies(body: string, protocol: ProxyProtocol): string[] {
+	const scheme = protocol === "socks5" ? "socks5" : "http";
 	const trimmed = body.trim();
 	if (!trimmed) {
 		return [];
@@ -1162,7 +1660,7 @@ function parseSmartproxyAllocatorProxies(body: string): string[] {
 						"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 is string => url !== null);
 		}
@@ -1174,7 +1672,7 @@ function parseSmartproxyAllocatorProxies(body: string): string[] {
 		.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(
@@ -1207,12 +1705,20 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 	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 appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+	if (!appKey) return undefined;
+	const cacheKey = buildSmartproxyCacheKey(
+		policy,
+		appKey,
+		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);
@@ -1262,17 +1768,13 @@ export async function loadApiFuseConfig(dir: string = process.cwd()): Promise<Ap
 	const tsPath = path.resolve(dir, "apifuse.config.ts");
 	if (existsSync(tsPath)) {
 		const config = await importConfig(tsPath);
-		const resolvedConfig = config ?? {};
-		syncProxyEnv(resolvedConfig);
-		return resolvedConfig;
+		return config ?? {};
 	}
 
 	const jsPath = path.resolve(dir, "apifuse.config.js");
 	if (existsSync(jsPath)) {
 		const config = await importConfig(jsPath);
-		const resolvedConfig = config ?? {};
-		syncProxyEnv(resolvedConfig);
-		return resolvedConfig;
+		return config ?? {};
 	}
 
 	return {};