@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/src/config/loader.ts

@@ -2,22 +2,39 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
 
-import Redis from "ioredis";
-
-import type { ProviderProxyPolicy, TraceConfig } from "../types";
-
+import { 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 the SDK resolves natively (as opposed to the static env path). */
+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;
 export const SMARTPROXY_MAX_POOL_SIZE = 20;
 export const DEFAULT_PROXY_PROVIDER_ENV = "APIFUSE__PROXY__PROVIDER";
 export const DEFAULT_PROXY_COUNTRY_ENV = "APIFUSE__PROXY__DEFAULT_COUNTRY";
-export const DEFAULT_PROXY_LIFETIME_ENV =
-	"APIFUSE__PROXY__DEFAULT_LIFETIME_MINUTES";
-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 DEFAULT_PROXY_LIFETIME_ENV = "APIFUSE__PROXY__DEFAULT_LIFETIME_MINUTES";
+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 = {
@@ -55,6 +72,26 @@ export type ProxyResolutionOptions = {
 	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;
 };
 
@@ -77,7 +114,8 @@ export type SmartproxyAllocatorBodyClass =
 	| "usable_proxy_endpoints";
 
 export type ProxyResolutionTelemetryEvent = {
-	provider: "smartproxy";
+	provider: ProxyVendorName;
+	protocol?: ProxyProtocol;
 	cacheStatus: ProxyCacheStatus;
 	cacheHit: boolean;
 	resolutionMs: number;
@@ -95,7 +133,7 @@ export type ProxyResolutionTelemetryEvent = {
 };
 
 export type ProxyAttemptTelemetryEvent = {
-	provider: "smartproxy";
+	provider: ProxyVendorName;
 	attempt: number;
 	poolIndex?: number;
 	proxyHash?: string;
@@ -105,31 +143,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;
 	}
 }
 
@@ -165,8 +241,7 @@ const SMARTPROXY_LOCK_POLL_MAX_MS = 9_000;
 const SMARTPROXY_DEADLINE_MARGIN_MS = 1_000;
 const SMARTPROXY_INVALIDATION_SKIP_REDIS_MS = 30_000;
 const SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS = 3;
-const SMARTPROXY_ALLOCATOR_DEADLINE_MS =
-	SMARTPROXY_LOCK_TTL_MS - SMARTPROXY_DEADLINE_MARGIN_MS;
+const SMARTPROXY_ALLOCATOR_DEADLINE_MS = SMARTPROXY_LOCK_TTL_MS - SMARTPROXY_DEADLINE_MARGIN_MS;
 const SMARTPROXY_ALLOCATOR_RETRY_BASE_MS = 25;
 // Smartproxy API extraction returns fresh IP:port candidates; the `life`
 // parameter controls session duration intent, not a hard endpoint lease. Keep
@@ -197,15 +272,11 @@ export function providerStateRedisUrlFromEnv(): string | undefined {
 }
 
 /** @internal Test-only hook for exercising shared proxy-cache behavior. */
-export function __setProxyRedisForTests(
-	redis: ProxyRedisClient | undefined,
-): void {
+export function __setProxyRedisForTests(redis: ProxyRedisClient | undefined): void {
 	proxyRedisForTests = redis;
 }
 
-export function __setSmartproxyAllocatorDeadlineMsForTests(
-	deadlineMs: number | undefined,
-): void {
+export function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number | undefined): void {
 	smartproxyAllocatorDeadlineMsForTests = deadlineMs;
 }
 
@@ -230,9 +301,7 @@ function getProxyRedis(): ProxyRedisClient | undefined {
 	return redis;
 }
 
-async function withRedisTimeout<T>(
-	operation: () => Promise<T>,
-): Promise<T | undefined> {
+async function withRedisTimeout<T>(operation: () => Promise<T>): Promise<T | undefined> {
 	let timeoutId: ReturnType<typeof setTimeout> | undefined;
 	try {
 		const timeout = new Promise<undefined>((resolve) => {
@@ -318,17 +387,11 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
-function toProxyDiagnostics(
-	value: unknown,
-): Record<string, string | number | boolean> | undefined {
+function toProxyDiagnostics(value: unknown): Record<string, string | number | boolean> | undefined {
 	if (!isRecord(value)) return undefined;
 	const diagnostics: Record<string, string | number | boolean> = {};
 	for (const [key, item] of Object.entries(value)) {
-		if (
-			typeof item === "string" ||
-			typeof item === "number" ||
-			typeof item === "boolean"
-		) {
+		if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
 			diagnostics[key] = item;
 		}
 	}
@@ -405,17 +468,19 @@ function applyStickyProxySession(proxyUrl: string): string {
 		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;
 	}
 
 	const username = decodeURIComponent(parsed.username);
-	const sessionId =
-		process.env.APIFUSE__PROXY__SESSION_ID?.trim() || "apifuse-shared";
-	const sessionDuration = readPositiveIntegerEnv(
-		"APIFUSE__PROXY__SESSION_DURATION",
-	);
+	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");
@@ -430,27 +495,16 @@ function buildSmartproxyUsername(
 	sessionDuration?: string,
 ): string {
 	const parts = username.split("_");
-	const configuredLife = parts
-		.find((part) => part.startsWith("life-"))
-		?.slice("life-".length);
+	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}`;
+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}`;
 }
 
@@ -461,9 +515,7 @@ function syncProxyEnv(config: ApiFuseConfig): void {
 	}
 }
 
-export function resolveProxyConfig(
-	options: ProxyResolutionOptions = {},
-): ResolvedProxyConfig {
+export function resolveProxyConfig(options: ProxyResolutionOptions = {}): ResolvedProxyConfig {
 	const explicitProxyUrl = normalizeProxyUrl(options.proxy);
 	if (explicitProxyUrl) {
 		return { shouldWarn: false, url: explicitProxyUrl };
@@ -485,9 +537,7 @@ export function resolveProxyConfig(
 		return { shouldWarn: false, url: envProxyUrl };
 	}
 
-	const configuredProxyUrl = normalizeProxyUrl(
-		options.apifuseConfig?.proxy?.url,
-	);
+	const configuredProxyUrl = normalizeProxyUrl(options.apifuseConfig?.proxy?.url);
 	if (configuredProxyUrl) {
 		return { shouldWarn: false, url: configuredProxyUrl };
 	}
@@ -511,68 +561,273 @@ export async function resolveProxyConfigAsync(
 		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") {
+	// 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,
-		);
-		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.`,
 		);
+	}
+}
+
+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 {
+function resolvePolicy(options: ProxyResolutionOptions): ProviderProxyPolicy | undefined {
 	if (options.proxyPolicy) {
 		return options.proxyPolicy;
 	}
@@ -583,32 +838,217 @@ function resolvePolicy(
 	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";
+}
+
+/**
+ * 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: ProviderProxyPolicy): ProxyVendorName[] {
+	const declared: (ProviderProxyProvider | undefined)[] = policy.providers?.length
+		? policy.providers
+		: [policy.provider ?? envDefaultProvider()];
+	const chain: ProxyVendorName[] = [];
+	for (const name of declared) {
+		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). Static vendors (custom / decodo) and credential-less policies
+ *    resolve no allocator pool, so every attempt would hit the same endpoint
+ *    with no possible 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). Static vendors (custom / decodo) resolve the same URL every
+ *    attempt, 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. Static/custom/decodo policies (empty registry chain) resolve the *same*
+ * URL every attempt by design — retrying that same endpoint is intended, so the
+ * transport loop must not de-duplicate them.
+ */
+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,
+	ambientDefaults = true,
 ): string | undefined {
 	return (
 		policy.geo?.country ??
-		process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ??
-		undefined
+		(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);
-	return Math.min(
-		SMARTPROXY_MAX_LIFETIME_MINUTES,
-		Math.max(1, Math.floor(configuredLifetime)),
-	);
+		(ambientDefaults ? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30) : 30);
+	return Math.min(SMARTPROXY_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configuredLifetime)));
 }
 
 function readPositiveNumberEnv(name: string, fallback: number): number {
@@ -624,10 +1064,7 @@ function readPositiveNumberEnv(name: string, fallback: number): number {
 function resolveSmartproxyPoolSize(policy: ProviderProxyPolicy): number {
 	return Math.min(
 		SMARTPROXY_MAX_POOL_SIZE,
-		Math.max(
-			1,
-			Math.floor(policy.session?.poolSize ?? DEFAULT_SMARTPROXY_POOL_SIZE),
-		),
+		Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_SMARTPROXY_POOL_SIZE)),
 	);
 }
 
@@ -635,26 +1072,29 @@ function selectProxyPoolIndex(poolSize: number, attempt = 0): number {
 	if (poolSize <= 1) {
 		return 0;
 	}
-	const normalizedAttempt = Number.isFinite(attempt)
-		? Math.max(0, Math.floor(attempt))
-		: 0;
+	const normalizedAttempt = Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
 	return normalizedAttempt % poolSize;
 }
 
 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,
+		affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
 		lifetimeMinutes,
 		poolSize,
 	});
@@ -665,11 +1105,17 @@ async function allocateSmartproxy(
 	appKey: string,
 	lifetimeMinutes: number,
 	affinityKey: string | undefined,
+	protocol: ProxyProtocol,
+	ambientDefaults = true,
+	sharedCache = true,
 ): Promise<SmartproxyAllocationResult> {
 	const cacheKey = buildSmartproxyCacheKey(
 		policy,
+		appKey,
 		affinityKey,
 		lifetimeMinutes,
+		protocol,
+		ambientDefaults,
 	);
 	const startedAt = Date.now();
 	const now = startedAt;
@@ -678,7 +1124,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, {
@@ -692,7 +1146,7 @@ async function allocateSmartproxy(
 		};
 	}
 
-	if (!skipCached) {
+	if (!skipCached && sharedCache) {
 		const redisResult = await readSmartproxyRedisPool(cacheKey, startedAt);
 		if (redisResult) return redisResult;
 	}
@@ -714,6 +1168,9 @@ async function allocateSmartproxy(
 		appKey,
 		lifetimeMinutes,
 		startedAt,
+		protocol,
+		ambientDefaults,
+		sharedCache,
 	).finally(() => {
 		proxyInflight.delete(cacheKey);
 	});
@@ -730,9 +1187,7 @@ async function readSmartproxyRedisPool(
 	const redis = getProxyRedis();
 	if (!redis || !(await ensureRedisReady(redis))) return null;
 	const redisStartedAt = Date.now();
-	const raw = await withRedisTimeout(() =>
-		redis.get(smartproxyRedisPoolKey(cacheKey)),
-	);
+	const raw = await withRedisTimeout(() => redis.get(smartproxyRedisPoolKey(cacheKey)));
 	const redisReadMs = Math.max(0, Date.now() - redisStartedAt);
 	if (typeof raw !== "string") return null;
 	const pool = safeParseSmartproxyPool(raw);
@@ -754,6 +1209,9 @@ async function refreshSmartproxyPool(
 	policy: ProviderProxyPolicy,
 	appKey: string,
 	lifetimeMinutes: number,
+	protocol: ProxyProtocol,
+	ambientDefaults: boolean,
+	sharedCache: boolean,
 ): Promise<void> {
 	try {
 		await allocateSmartproxyShared(
@@ -762,6 +1220,9 @@ async function refreshSmartproxyPool(
 			appKey,
 			lifetimeMinutes,
 			Date.now(),
+			protocol,
+			ambientDefaults,
+			sharedCache,
 			{
 				background: true,
 			},
@@ -777,9 +1238,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,
@@ -787,7 +1251,7 @@ async function allocateSmartproxyShared(
 			appKey,
 			lifetimeMinutes,
 			startedAt,
-			{ cacheStatus: "allocator" },
+			{ cacheStatus: "allocator", protocol, ambientDefaults },
 		);
 	}
 
@@ -809,11 +1273,11 @@ async function allocateSmartproxyShared(
 					lifetimeMinutes,
 					startedAt,
 					{
-						cacheStatus: options.background
-							? "soft_stale_refresh"
-							: "allocator",
+						cacheStatus: options.background ? "soft_stale_refresh" : "allocator",
 						redis,
 						poolKey,
+						protocol,
+						ambientDefaults,
 					},
 				);
 			} finally {
@@ -838,15 +1302,10 @@ async function allocateSmartproxyShared(
 		if (typeof pttl === "number" && pttl <= 0) {
 			continue;
 		}
-		if (
-			Date.now() - startedAt >
-			SMARTPROXY_LOCK_POLL_MAX_MS - SMARTPROXY_DEADLINE_MARGIN_MS
-		) {
+		if (Date.now() - startedAt > SMARTPROXY_LOCK_POLL_MAX_MS - SMARTPROXY_DEADLINE_MARGIN_MS) {
 			break;
 		}
-		await sleep(
-			Math.min(500, Math.max(50, typeof pttl === "number" ? pttl : 100)),
-		);
+		await sleep(Math.min(500, Math.max(50, typeof pttl === "number" ? pttl : 100)));
 	}
 
 	throw new ProxyResolutionError(
@@ -893,9 +1352,7 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
 }
 
 function smartproxyAllocatorDeadlineMs(): number {
-	return (
-		smartproxyAllocatorDeadlineMsForTests ?? SMARTPROXY_ALLOCATOR_DEADLINE_MS
-	);
+	return smartproxyAllocatorDeadlineMsForTests ?? SMARTPROXY_ALLOCATOR_DEADLINE_MS;
 }
 
 function createDeadlineAbortController(deadlineAt: number): {
@@ -917,9 +1374,7 @@ function createDeadlineAbortController(deadlineAt: number): {
 	};
 }
 
-function smartproxyAllocatorDeadlineFailure(
-	attempt: number,
-): SmartproxyAllocatorFailure {
+function smartproxyAllocatorDeadlineFailure(attempt: number): SmartproxyAllocatorFailure {
 	return {
 		ok: false,
 		attempt,
@@ -978,6 +1433,8 @@ async function allocateAndStoreSmartproxyPool(
 		cacheStatus: ProxyCacheStatus;
 		redis?: ProxyRedisClient;
 		poolKey?: string;
+		protocol: ProxyProtocol;
+		ambientDefaults: boolean;
 	},
 ): Promise<SmartproxyAllocationResult> {
 	const poolSize = resolveSmartproxyPoolSize(policy);
@@ -986,17 +1443,14 @@ async function allocateAndStoreSmartproxyPool(
 		appKey,
 		lifetimeMinutes,
 		poolSize,
+		options.protocol,
+		options.ambientDefaults,
 	);
 	const allocatorStartedAt = Date.now();
-	const allocatorDeadlineAt =
-		allocatorStartedAt + smartproxyAllocatorDeadlineMs();
+	const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
 	let allocation: SmartproxyAllocatorSuccess | undefined;
 	let lastFailure: SmartproxyAllocatorFailure | undefined;
-	for (
-		let attempt = 1;
-		attempt <= SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS;
-		attempt += 1
-	) {
+	for (let attempt = 1; attempt <= SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS; attempt += 1) {
 		if (Date.now() >= allocatorDeadlineAt) {
 			lastFailure = smartproxyAllocatorDeadlineFailure(attempt);
 			break;
@@ -1005,6 +1459,7 @@ async function allocateAndStoreSmartproxyPool(
 			allocatorUrl,
 			attempt,
 			allocatorDeadlineAt,
+			options.protocol,
 		);
 		if (attemptResult.ok) {
 			allocation = attemptResult;
@@ -1013,8 +1468,7 @@ async function allocateAndStoreSmartproxyPool(
 		lastFailure = attemptResult;
 		if (attempt < SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS) {
 			if (Date.now() >= allocatorDeadlineAt) break;
-			const { controller, dispose } =
-				createDeadlineAbortController(allocatorDeadlineAt);
+			const { controller, dispose } = createDeadlineAbortController(allocatorDeadlineAt);
 			try {
 				await sleep(smartproxyAllocatorBackoffMs(attempt), controller.signal);
 			} catch {
@@ -1027,9 +1481,7 @@ async function allocateAndStoreSmartproxyPool(
 
 	const allocatorMs = Math.max(0, Date.now() - allocatorStartedAt);
 	const allocatorAttempts =
-		allocation?.attempt ??
-		lastFailure?.attempt ??
-		SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS;
+		allocation?.attempt ?? lastFailure?.attempt ?? SMARTPROXY_ALLOCATOR_MAX_ATTEMPTS;
 	const allocatorBodyClass =
 		lastFailure?.bodyClass ?? allocation?.bodyClass ?? "usable_proxy_endpoints";
 	const allocatorStatus = lastFailure ? lastFailure.status : allocation?.status;
@@ -1063,7 +1515,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,
@@ -1106,9 +1558,7 @@ async function allocateAndStoreSmartproxyPool(
 	};
 }
 
-type SmartproxyAllocatorAttemptResult =
-	| SmartproxyAllocatorSuccess
-	| SmartproxyAllocatorFailure;
+type SmartproxyAllocatorAttemptResult = SmartproxyAllocatorSuccess | SmartproxyAllocatorFailure;
 
 type SmartproxyAllocatorSuccess = {
 	ok: true;
@@ -1130,6 +1580,7 @@ async function fetchSmartproxyAllocatorAttempt(
 	allocatorUrl: string,
 	attempt: number,
 	deadlineAt: number,
+	protocol: ProxyProtocol,
 ): Promise<SmartproxyAllocatorAttemptResult> {
 	const { controller, dispose } = createDeadlineAbortController(deadlineAt);
 	let response: Response;
@@ -1150,10 +1601,7 @@ async function fetchSmartproxyAllocatorAttempt(
 
 	let body: string;
 	try {
-		body = await readSmartproxyAllocatorBodyWithDeadline(
-			response,
-			controller.signal,
-		);
+		body = await readSmartproxyAllocatorBodyWithDeadline(response, controller.signal);
 	} catch (error) {
 		dispose();
 		return {
@@ -1176,7 +1624,7 @@ async function fetchSmartproxyAllocatorAttempt(
 		};
 	}
 
-	const urls = parseSmartproxyAllocatorProxies(body);
+	const urls = parseSmartproxyAllocatorProxies(body, protocol);
 	const bodyClass = classifySmartproxyAllocatorBody(body, urls);
 	if (urls.length === 0) {
 		return {
@@ -1196,8 +1644,7 @@ async function fetchSmartproxyAllocatorAttempt(
 }
 
 function smartproxyAllocatorBackoffMs(attempt: number): number {
-	const base =
-		SMARTPROXY_ALLOCATOR_RETRY_BASE_MS * 2 ** Math.max(0, attempt - 1);
+	const base = SMARTPROXY_ALLOCATOR_RETRY_BASE_MS * 2 ** Math.max(0, attempt - 1);
 	const jitter = Math.floor(Math.random() * SMARTPROXY_ALLOCATOR_RETRY_BASE_MS);
 	return base + jitter;
 }
@@ -1217,29 +1664,42 @@ 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);
 	}
-	return `https://www.smartproxy.org/web_v1/ip/get-ip-v3?${params.toString()}`;
+	// www.smartproxy.org stopped serving the extraction API on 2026-07-21 (the
+	// 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: string): string[] {
+function parseSmartproxyAllocatorProxies(body: string, protocol: ProxyProtocol): string[] {
+	const scheme = protocol === "socks5" ? "socks5" : "http";
 	const trimmed = body.trim();
 	if (!trimmed) {
 		return [];
@@ -1247,14 +1707,8 @@ function parseSmartproxyAllocatorProxies(body: string): string[] {
 
 	try {
 		const parsed: unknown = JSON.parse(trimmed);
-		const data =
-			parsed && typeof parsed === "object" && "data" in parsed
-				? parsed.data
-				: undefined;
-		const list =
-			data && typeof data === "object" && "list" in data
-				? data.list
-				: undefined;
+		const data = parsed && typeof parsed === "object" && "data" in parsed ? parsed.data : undefined;
+		const list = data && typeof data === "object" && "list" in data ? data.list : undefined;
 		if (Array.isArray(list)) {
 			return list
 				.map((item) => {
@@ -1263,11 +1717,10 @@ function parseSmartproxyAllocatorProxies(body: string): string[] {
 					}
 					const ip = "ip" in item && typeof item.ip === "string" ? item.ip : "";
 					const port =
-						"port" in item &&
-						(typeof item.port === "string" || typeof item.port === "number")
+						"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);
 		}
@@ -1279,7 +1732,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(
@@ -1307,35 +1760,32 @@ export function clearProxyResolutionCache(): void {
 	invalidatedProxyKeys.clear();
 }
 
-function markSmartproxyCacheInvalidated(
-	options: ProxyResolutionOptions = {},
-): string | undefined {
+function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): string | undefined {
 	const policy = resolvePolicy(options);
 	if (!policy || policy.mode === "disabled") {
 		return undefined;
 	}
-	if (resolveProxyProvider(policy) !== "smartproxy") {
+	if (!resolveVendorChain(policy).includes("smartproxy")) {
 		return undefined;
 	}
 
 	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
+	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,
-	);
+	invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
 	proxyCache.delete(cacheKey);
 	proxyInflight.delete(cacheKey);
 	return cacheKey;
 }
 
-export function invalidateProxyResolutionCache(
-	options: ProxyResolutionOptions = {},
-): boolean {
+export function invalidateProxyResolutionCache(options: ProxyResolutionOptions = {}): boolean {
 	return markSmartproxyCacheInvalidated(options) !== undefined;
 }
 
@@ -1374,9 +1824,7 @@ async function importConfig(filePath: string): Promise<ApiFuseConfig | null> {
 	}
 }
 
-export async function loadApiFuseConfig(
-	dir: string = process.cwd(),
-): Promise<ApiFuseConfig> {
+export async function loadApiFuseConfig(dir: string = process.cwd()): Promise<ApiFuseConfig> {
 	const tsPath = path.resolve(dir, "apifuse.config.ts");
 	if (existsSync(tsPath)) {
 		const config = await importConfig(tsPath);