@apifuse/provider-sdk 2.2.0-beta.23 → 2.2.0-beta.25

package/dist/server/serve.js

@@ -21,6 +21,7 @@ import { getProviderBaseUrl } from "../runtime/provider.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
+import { bindResolverSignal, createResolverClientFromEnv } from "../runtime/resolver.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
 import { createStealthClient } from "../runtime/stealth.js";
@@ -149,6 +150,13 @@ export function resolveProviderProxyAffinityKey(provider, request, operationId)
     }
     return connectionKey ?? provider.id;
 }
+export function resolveProviderResolverIdentityScope(provider, affinityKey, contextId) {
+    return JSON.stringify({
+        proxy: provider.proxy ?? null,
+        affinityKey,
+        contextId,
+    });
+}
 function resolveOperationConnectionId(request) {
     return request.connection?.id ?? request.connectionId;
 }
@@ -161,7 +169,7 @@ function resolveNativeProxyPolicy(provider) {
         return { mode: "disabled" };
     return undefined;
 }
-function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
+function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -170,6 +178,7 @@ function createProviderContext(provider, request, operationId, options = {}, sta
         affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
         telemetry: proxyTelemetry,
     };
+    const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     let wrappedContext;
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
@@ -190,6 +199,8 @@ function createProviderContext(provider, request, operationId, options = {}, sta
         connectionId: resolveOperationConnectionId(request),
         headers: request.headers ?? {},
     };
+    const requestState = state.forConnection(requestContext.connectionId);
+    const cache = createProviderCache({ providerId: provider.id });
     const context = wrapWithInstrumentation({
         env,
         credential,
@@ -202,8 +213,8 @@ function createProviderContext(provider, request, operationId, options = {}, sta
                 retryResponseMeta.set(wrappedContext, summary);
             },
         }),
-        cache: createProviderCache({ providerId: provider.id }),
-        state,
+        cache,
+        state: requestState,
         stealth: stealthBaseUrl
             ? stealthProfile
                 ? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
@@ -235,12 +246,18 @@ function createProviderContext(provider, request, operationId, options = {}, sta
         auth: createAuthStub(),
         ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),
+        resolver: bindResolverSignal(options.resolver ??
+            createResolverClientFromEnv(provider.resolver, undefined, {
+                allowedHosts: provider.allowedHosts,
+                cache,
+                identityScope: resolverIdentityScope,
+            }), signal),
         choice: createProviderChoiceContext({
             providerId: provider.id,
             env,
             request: requestContext,
             credential,
-            state,
+            state: requestState,
         }),
     });
     wrappedContext = context;
@@ -284,6 +301,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
             request.providerId ??
             provider.id,
     };
+    const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
@@ -296,6 +314,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
             values: request.connection.secrets,
         })
         : undefined;
+    const cache = createProviderCache({ providerId: provider.id });
     return {
         context: {
             flowId: request.flowId,
@@ -331,6 +350,12 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
             context: flowContextStore.context,
             ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
             stt: options.stt ?? createSttClientFromEnv(provider.stt),
+            resolver: bindResolverSignal(options.resolver ??
+                createResolverClientFromEnv(provider.resolver, undefined, {
+                    allowedHosts: provider.allowedHosts,
+                    cache,
+                    identityScope: resolverIdentityScope,
+                }), signal),
             auth: createAuthFlowHelpers({ signal }),
         },
         getPatch: flowContextStore.getPatch,
@@ -1048,8 +1073,8 @@ function withAuthRequestHeaders(request, headers) {
         },
     };
 }
-async function handleOperation(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
-    const ctx = createProviderContext(provider, request, operationId, options, state, proxyTelemetry);
+async function handleOperation(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry, signal) {
+    const ctx = createProviderContext(provider, request, operationId, options, state, proxyTelemetry, signal);
     const operation = provider.operations[operationId];
     const streaming = operation?.transport?.kind && operation.transport.kind !== "json";
     let cleanupCalled = false;
@@ -1077,6 +1102,7 @@ async function handleOperation(provider, request, operationId, options = {}, sta
                 operationId,
                 ctx,
                 request,
+                signal,
             })
             : await executeOperation(provider, operationId, ctx, request.input);
         if (streaming && operation) {
@@ -1396,7 +1422,7 @@ export function createServerApp(provider, options = {}) {
             }
             const request = operationRequestFromForwardingEnvelope(envelope);
             operationId = envelope.operationId;
-            const ctx = createProviderContext(provider, request, operationId, options, state);
+            const ctx = createProviderContext(provider, request, operationId, options, state, undefined, signal);
             if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
                 throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt);
             }
@@ -1435,7 +1461,7 @@ export function createServerApp(provider, options = {}) {
             const body = OperationRequestSchema.parse(rawBody);
             const requestHeaders = Object.fromEntries(c.req.raw.headers.entries());
             body.headers = { ...requestHeaders, ...body.headers };
-            const response = await handleOperation(provider, body, operation, options, state, proxyTelemetry);
+            const response = await handleOperation(provider, body, operation, options, state, proxyTelemetry, c.req.raw.signal);
             if (response instanceof Response) {
                 logProviderSuccess(logger, provider, "operation", operation, body.requestId, response.status, finishRequestCost(requestCost));
                 return responseWithProviderTelemetry(response, proxyTelemetry);
@@ -1613,6 +1639,7 @@ export async function serve(provider, options = {}) {
         logger: options.logger,
         ocr: options.ocr,
         stt: options.stt,
+        resolver: options.resolver,
         state: options.state,
         allowMemoryStateFallback: options.allowMemoryStateFallback,
         operationExecutor: options.operationExecutor,

package/dist/testing/run.js

@@ -248,6 +248,7 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
                 },
             }),
             close: async () => { },
+            cookies: async () => (await browserAction("cookies")).data,
             fill: async (selector, textValue) => {
                 await browserAction("fill", { selector, text: textValue });
             },
@@ -400,6 +401,9 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
         auth: { requestField: async (name) => unsupported(`ctx.auth.requestField(${name})`) },
         ocr: createUnsupportedOcrClient("Standard test upstream context does not support ctx.ocr.recognize"),
         stt: createUnsupportedSttClient("Standard test upstream context does not support ctx.stt.transcribe"),
+        resolver: {
+            solve: async () => unsupported("ctx.resolver.solve"),
+        },
         choice: createTestProviderChoiceContext({
             providerId: `standard-test-${operationName}`,
             request,
@@ -507,6 +511,9 @@ export function createSnapshotContext(rawFixture) {
         },
         ocr: createUnsupportedOcrClient("Standard test snapshot context does not support ctx.ocr.recognize"),
         stt: createUnsupportedSttClient("Standard test snapshot context does not support ctx.stt.transcribe"),
+        resolver: {
+            solve: async () => unsupported("ctx.resolver.solve"),
+        },
         choice: createTestProviderChoiceContext({
             providerId: "standard-test",
             request,

package/dist/types.d.ts

@@ -251,6 +251,79 @@ export type ProviderSttMode = "optional" | "required";
 export interface ProviderSttConfig {
     mode: ProviderSttMode;
 }
+/**
+ * `browser` is the in-house CDP pool (`apps/cdp-pool`, reached through
+ * `createBrowserClient`) and is a first-class vendor rather than an escape hatch:
+ * for fingerprint-family kinds, it was measured faster than a paid vendor
+ * (4.5 s vs 17.5 s) at zero marginal cost.
+ *
+ * `2captcha` is the vendor already carrying production traffic in
+ * `apifuse-provider-tabelog`.
+ *
+ * Union order is documentation only; the effective fallback order is whatever
+ * `ProviderResolverConfig.vendors` declares.
+ */
+export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "custom";
+/**
+ * Token-family kinds resolve to `{ form: "token" }`. Cookie-family kinds resolve
+ * to `{ form: "cookies" }`; network-identity binding is defined per kind. `aws_waf`
+ * was measured portable across residential leases on buyee, while `cf_clearance`
+ * remains unmeasured here and is treated as identity-scoped because it is widely
+ * described as IP-bound.
+ */
+export type ProviderChallenge = {
+    readonly kind: "turnstile";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+    readonly action?: string;
+    readonly cdata?: string;
+} | {
+    readonly kind: "recaptcha_v2";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+} | {
+    readonly kind: "recaptcha_v3";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+    readonly action: string;
+    readonly minScore?: number;
+} | {
+    readonly kind: "hcaptcha";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+} | {
+    readonly kind: "cloudflare_interstitial";
+    readonly pageUrl: string;
+    readonly blockedHtml?: string;
+} | {
+    readonly kind: "aws_waf";
+    readonly pageUrl: string;
+    readonly captchaScript?: string;
+    readonly context?: string;
+    readonly iv?: string;
+};
+export type ProviderChallengeKind = ProviderChallenge["kind"];
+/**
+ * Token solutions carry no network-identity binding. Cookie-solution binding is
+ * per challenge kind: `aws_waf` was measured portable across residential leases
+ * on buyee, while `cf_clearance` is unmeasured here and treated as scoped to the
+ * identity that produced it. The provider attaches the returned cookies to its
+ * own requests.
+ */
+export type ChallengeSolution = {
+    readonly form: "token";
+    readonly token: string;
+} | {
+    readonly form: "cookies";
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly userAgent: string;
+};
+export interface ProviderResolverConfig {
+    /** Ordered vendor fallback chain, tried first to last. */
+    readonly vendors: readonly ProviderResolverVendor[];
+    /** Challenge kinds this provider is permitted to request. */
+    readonly kinds: readonly ProviderChallengeKind[];
+}
 export type SttAudioInput = {
     kind: "base64";
     data: string;
@@ -315,6 +388,9 @@ export interface SttContext {
     transcribe(request: SttTranscribeRequest): Promise<SttTranscript>;
     extractVerificationCode(text: string, options?: SttVerificationCodeOptions): VerificationCodeExtractionResult;
 }
+export interface ResolverContext {
+    solve(challenge: ProviderChallenge, signal?: AbortSignal): Promise<ChallengeSolution>;
+}
 export interface HealthJourneySchedule {
     kind: "interval";
     /** ISO 8601 duration, for example PT8H. */
@@ -716,10 +792,12 @@ export type ProviderProxyMode = "disabled" | "optional" | "required";
  * - `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.
+ *	 **@deprecated** — unused; no managed adapter. Declare a
+ *	 `ProviderProxyPolicy` using `smartproxy` or `nodemaven` instead; the
+ *	 `smartproxy` allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `custom` — **@deprecated** static proxy marker with no managed adapter.
+ *	 Use `ProviderProxyPolicy` with `smartproxy`/`nodemaven`; the `smartproxy`
+ *	 allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
  */
 export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 export type ProviderProxySessionAffinity = "request" | "operation" | "auth-flow" | "connection";
@@ -1254,9 +1332,9 @@ export interface NativeProviderConfig {
 }
 export interface ProviderCacheKeyOptions {
     /**
-     * Additional field names to omit from stable key material. The SDK always
-     * omits known secret-bearing names such as serviceKey, authorization,
-     * cookie, token, password, and secret.
+     * Additional field names whose values are hashed in stable key material. The
+     * SDK always hashes values under known secret-bearing names such as serviceKey,
+     * authorization, cookie, token, password, and secret.
      */
     redactFields?: string[];
 }
@@ -1329,6 +1407,17 @@ export interface BrowserFrame {
     evaluate<T>(fn: string | (() => T)): Promise<T>;
     locator(selector: string): BrowserLocator;
 }
+export interface BrowserCookie {
+    readonly name: string;
+    readonly value: string;
+    readonly domain: string;
+    readonly path: string;
+    /** Unix seconds. Absent for a session cookie. */
+    readonly expires?: number;
+    readonly httpOnly: boolean;
+    readonly secure: boolean;
+    readonly sameSite?: "Strict" | "Lax" | "None";
+}
 export type BrowserResourceMethod = "GET" | "HEAD";
 export type BrowserResourceRequest = {
     readonly url: string;
@@ -1357,6 +1446,11 @@ export type BrowserResourcePolicy = {
 };
 export interface BrowserPage extends BrowserFrame {
     close(): Promise<void>;
+    /**
+     * Reads the browser context's cookie jar, including httpOnly cookies.
+     * Cookie expiry values are Unix seconds and are absent for session cookies.
+     */
+    cookies(): Promise<readonly BrowserCookie[]>;
     fill(selector: string, text: string): Promise<void>;
     goto(url: string): Promise<void>;
     pageId?: string;
@@ -1593,6 +1687,7 @@ export interface FlowContext {
     context: ContextScratchpad;
     ocr: OcrContext;
     stt: SttContext;
+    resolver: ResolverContext;
     auth: AuthFlowTerminalContext;
 }
 export interface AuthTurn {
@@ -1624,7 +1719,13 @@ export interface AuthFlowDefinition {
     refresh?: AuthFlowInputHandler;
 }
 export type ProviderStateDurationString = `${number}${"ms" | "s" | "m" | "h" | "d"}` | `PT${string}`;
+export type StateNamespaceScope = "connection" | "provider";
 export interface StateNamespaceOptions {
+    /**
+     * State isolation boundary. Connection scope is the default; provider scope
+     * must be selected explicitly for provider-wide coordination state.
+     */
+    scope?: StateNamespaceScope;
     /** Default TTL used when a write omits ttl. Required to avoid unbounded state. */
     defaultTtl: ProviderStateDurationString;
     /** Maximum allowed TTL; writes are rejected when they exceed this policy. */
@@ -1666,6 +1767,11 @@ export interface ProviderStateNamespace {
     increment(key: string, field: string, delta?: number, options?: StateWriteOptions): Promise<StateValue<Record<string, unknown>>>;
 }
 export interface ProviderRuntimeState {
+    /**
+     * Returns an immutable view bound to one request connection. An unresolved
+     * connection uses an isolated reserved sentinel, never the provider-global scope.
+     */
+    forConnection(connectionId: string | undefined): ProviderRuntimeState;
     namespace(name: string, options: StateNamespaceOptions): ProviderStateNamespace;
 }
 export interface ProviderContext {
@@ -1685,6 +1791,7 @@ export interface ProviderContext {
     auth: AuthContext;
     ocr: OcrContext;
     stt: SttContext;
+    resolver: ResolverContext;
     choice: ProviderChoiceContext;
 }
 export interface ProxiedOAuthConfig {
@@ -1837,6 +1944,7 @@ export interface ProviderDefinition {
     proxy?: ProviderProxyConfig;
     ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
+    resolver?: ProviderResolverConfig;
     browser?: {
         engine: BrowserEngine;
     };

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.23",
+	"version": "2.2.0-beta.25",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/config/loader.ts

@@ -19,7 +19,7 @@ import {
 
 export type { ProxyProtocol } from "../runtime/proxy-nodemaven.js";
 
-/** Proxy vendors the SDK resolves natively (as opposed to the static env path). */
+/** Proxy vendors with SDK-managed resolution. */
 export type ProxyVendorName = "smartproxy" | "nodemaven";
 
 // "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
@@ -37,15 +37,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;
@@ -57,7 +48,6 @@ export type SessionConfig = {
 };
 
 export type ApiFuseConfig = {
-	proxy?: ProxyConfig;
 	browser?: BrowserConfig;
 	session?: SessionConfig;
 	trace?: TraceConfig;
@@ -67,7 +57,6 @@ 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. */
@@ -444,75 +433,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;
-	}
-
-	// 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 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 {
@@ -532,16 +453,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 };
 }
 
@@ -563,7 +474,22 @@ export async function resolveProxyConfigAsync(
 
 	const chain = resolveVendorChain(policy);
 	if (chain.length === 0) {
-		// decodo/custom/env-static providers keep the legacy static-URL path.
+		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 },
@@ -842,18 +768,22 @@ 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-static chain falls through to the legacy env-URL path unchanged.
+ * an all-deprecated chain has no managed adapter.
  */
 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) {
+	for (const name of declaredVendorChain(policy)) {
 		if (isRegistryVendor(name) && !chain.includes(name)) {
 			chain.push(name);
 		}
@@ -924,9 +854,8 @@ const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"
  *  - 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.
+ *    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
@@ -945,8 +874,8 @@ const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"
  *    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.
+ *    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;
@@ -989,9 +918,8 @@ export function resolvePolicyTransportAttemptCap(input: {
  * 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.
+ * 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,
@@ -1828,17 +1756,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 {};