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

package/dist/runtime/stealth.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { Impit } from "impit";
-import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, resolveProxyConfigAsync, SMARTPROXY_MAX_POOL_SIZE, } from "../config/loader.js";
+import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, policyResolvesRegistryVendorChain, ProxyResolutionError, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
@@ -8,7 +8,6 @@ import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefa
 import { appendQueryParams } from "./request-options.js";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
-const MAX_POLICY_PROXY_RETRY_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE;
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
 const PROXY_CONNECT_FAILURE_BODY_PATTERN = /\bproxy\b.*\b(non[\s-]?200|connect|tunnel)|\bconnect\b.*\bproxy\b|\btunnel\b/i;
@@ -463,7 +462,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         }
         return client;
     }
-    async function resolveRequestProxy(options, proxyAttempt) {
+    async function resolveRequestProxy(options, proxyAttempt, refreshEpoch) {
         const resolvedProxy = await resolveProxyConfigAsync({
             proxy: options?.proxy ?? clientOptions.proxy,
             upstream: clientOptions.upstream,
@@ -474,6 +473,10 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 proxyAttemptOffset: options?.proxyAttemptOffset,
                 retryAttemptOffset: proxyAttempt,
             }),
+            // The impit stealth transport tunnels both HTTP CONNECT and SOCKS5,
+            // preserving the client TLS fingerprint end-to-end.
+            transportProtocols: ["http", "socks5"],
+            ...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
             telemetry: clientOptions.telemetry,
         });
         if (resolvedProxy.shouldWarn && !hasWarnedMissingProxy) {
@@ -484,6 +487,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             url: resolvedProxy.url,
             poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
             proxyHash: proxyEndpointHash(resolvedProxy.url),
+            vendor: vendorFromResolvedSource(resolvedProxy.source),
         };
     }
     const session = {
@@ -506,12 +510,28 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
             const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
             const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
-            const policyProxyAttemptCap = Math.max(1, Math.min(MAX_POLICY_PROXY_RETRY_ATTEMPTS, clientOptions.proxyPolicy?.session?.poolSize ??
+            // Span the whole vendor chain: successive attempts rotate one vendor's
+            // pool, then fail over to the next vendor via the flat attempt index.
+            const policyProxy = clientOptions.proxyPolicy ??
                 (typeof clientOptions.upstream?.proxy === "object"
-                    ? clientOptions.upstream.proxy.session?.poolSize
-                    : undefined) ??
-                DEFAULT_SMARTPROXY_POOL_SIZE));
-            const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
+                    ? clientOptions.upstream.proxy
+                    : undefined);
+            // The pool span is already bounded by each vendor's max pool size
+            // (smartproxy ≤20, nodemaven ≤50), so the configured span never exceeds
+            // the chain's true maximum — a large NodeMaven pool stays fully
+            // reachable rather than being truncated at an arbitrary ceiling.
+            const policyProxyAttemptCap = Math.max(1, policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE);
+            // A registry vendor chain (smartproxy/nodemaven) is the only policy whose
+            // successive attempts resolve a *different* endpoint, so it is the only one
+            // that may widen the attempt cap to the pool span, de-duplicate endpoints,
+            // and drive allocator stale-pool refresh. A static custom/decodo policy
+            // resolves the same URL every attempt: widening/refreshing it would resend
+            // the request dozens of times (up to maxAttempts × refreshes) and bypass
+            // retry:false and unsafe-method controls. Static policies therefore follow
+            // the ordinary transport-retry budget instead.
+            const rotatesRegistryChain = usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
+            const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+            const dedupeAllocatorEndpoints = rotatesRegistryChain;
             let lastError;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
                 let stalePoolError;
@@ -527,7 +547,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             return;
                         attemptRecorded = true;
                         clientOptions.telemetry?.recordProxyAttempt?.({
-                            provider: "smartproxy",
+                            provider: attemptProxy?.vendor ?? "smartproxy",
                             attempt: attempt + 1,
                             ...(attemptProxy?.poolIndex === undefined
                                 ? {}
@@ -541,11 +561,16 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     };
                     try {
                         assertNoUnsupportedFingerprintOverrides(options);
-                        attemptProxy = await resolveRequestProxy(options, attempt);
+                        attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
                         proxy = attemptProxy.url;
-                        if (proxy && usesPolicyAllocator) {
+                        if (proxy && dedupeAllocatorEndpoints) {
+                            // An under-filled allocation repeats endpoints (via the modulo
+                            // pool mapping) before the flat offset crosses into the next
+                            // vendor. Skip an already-tried endpoint and advance the offset
+                            // rather than breaking — breaking here would strand the request on
+                            // the primary vendor and never reach the fallback leg.
                             if (attemptedProxies.has(proxy)) {
-                                break;
+                                continue;
                             }
                             attemptedProxies.add(proxy);
                         }
@@ -605,7 +630,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const normalizedError = normalizeStealthTransportError(error);
                         recordProxyAttempt("error", proxyAttemptErrorCode(normalizedError), proxyAttemptStatus(normalizedError));
                         lastError = normalizedError;
-                        if (proxy && usesPolicyAllocator && isProxyPoolRefreshableError(normalizedError)) {
+                        if (proxy && rotatesRegistryChain && isProxyPoolRefreshableError(normalizedError)) {
                             stalePoolError = normalizedError;
                             if (shouldRunProxyAuthDiagnostic(normalizedError)) {
                                 stalePoolDiagnosticProxy = proxy;
@@ -615,10 +640,27 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             }
                             break;
                         }
-                        if (attempt + 1 <
-                            (stealthRetryOptions
-                                ? Math.min(maxAttempts, stealthRetryOptions.attempts)
-                                : maxAttempts) &&
+                        // Cap the number of transport retries. For a policy-allocator chain,
+                        // every attempt resolves a *different* endpoint/vendor (poolIndex
+                        // rotates across the concatenated vendor pool spans), so a transport
+                        // failure is a signal to advance to the next endpoint — potentially
+                        // crossing into the fallback vendor — not to retry the same endpoint.
+                        // Truncating that rotation at the per-endpoint retry budget would
+                        // strand the request on the primary vendor and never reach the
+                        // fallback, since the crossover only happens once the flat attempt
+                        // index exceeds the primary vendor's pool size (~10-20).
+                        // resolvePolicyTransportAttemptCap widens to the full chain span only
+                        // for implicit, safe-method allocator requests; explicit retry
+                        // policies (their documented `attempts` ceiling), unsafe methods, and
+                        // static/non-registry vendors keep the per-endpoint retry budget.
+                        const transportRetryCap = resolvePolicyTransportAttemptCap({
+                            policy: policyProxy,
+                            usesPolicyAllocator,
+                            retryAttempts: stealthRetryOptions?.attempts ?? 1,
+                            explicitRetry: hasExplicitRetryPolicy,
+                            method,
+                        });
+                        if (attempt + 1 < transportRetryCap &&
                             shouldRetryProxyTransportAttempt({
                                 error: normalizedError,
                                 explicitRetry: hasExplicitRetryPolicy,
@@ -634,7 +676,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         throw normalizedError;
                     }
                 }
-                if (usesPolicyAllocator &&
+                if (rotatesRegistryChain &&
                     stalePoolError &&
                     refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES) {
                     await invalidateProxyResolutionCacheAsync({

package/dist/server/serve.js

@@ -312,11 +312,22 @@ function toErrorResponse(error, requestId) {
             },
         };
     }
+    // A masked internal error MUST NOT be advertised as retryable: without an
+    // explicit retryable:false the hub (bori provider-backed engine) defaults 5xx
+    // to retryable:true, which turns a deterministic pre-upstream crash into an
+    // infinite START->CONTINUE->restart loop (2026-07-22 catchtable reserve RCA).
+    // We still refuse to leak message/stack — only the error class name (or the
+    // primitive type for non-Error throwables) is surfaced for ops triage.
     return {
         error: {
             code: "internal_error",
             message: "Internal error",
             ...(requestId ? { requestId } : {}),
+            details: {
+                retryable: false,
+                category: "internal_error",
+                errorClass: error instanceof Error ? error.name : typeof error,
+            },
         },
     };
 }

package/dist/server/types.d.ts

@@ -1,15 +1,15 @@
 import { z } from "zod";
 export declare const ConnectionModeSchema: z.ZodEnum<{
-    credentials: "credentials";
     none: "none";
+    credentials: "credentials";
     oauth2: "oauth2";
     "platform-managed": "platform-managed";
 }>;
 export declare const OperationConnectionSchema: z.ZodObject<{
     id: z.ZodString;
     mode: z.ZodEnum<{
-        credentials: "credentials";
         none: "none";
+        credentials: "credentials";
         oauth2: "oauth2";
         "platform-managed": "platform-managed";
     }>;
@@ -25,8 +25,8 @@ export declare const OperationRequestSchema: z.ZodObject<{
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            credentials: "credentials";
             none: "none";
+            credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
         }>;
@@ -55,21 +55,21 @@ export declare const OperationSuccessResponseSchema: z.ZodObject<{
             stale: z.ZodBoolean;
             keys: z.ZodArray<z.ZodString>;
             source: z.ZodOptional<z.ZodEnum<{
-                loader: "loader";
-                memory: "memory";
                 mixed: "mixed";
                 redis: "redis";
+                memory: "memory";
+                loader: "loader";
             }>>;
         }, z.core.$strip>>;
         retry: z.ZodOptional<z.ZodObject<{
             attempts: z.ZodNumber;
             retries: z.ZodNumber;
             preset: z.ZodOptional<z.ZodEnum<{
-                aggressive_read: "aggressive_read";
                 off: "off";
-                rate_limit_aware: "rate_limit_aware";
-                safe_read: "safe_read";
                 transport_transient: "transport_transient";
+                safe_read: "safe_read";
+                aggressive_read: "aggressive_read";
+                rate_limit_aware: "rate_limit_aware";
             }>>;
             transport: z.ZodEnum<{
                 native: "native";
@@ -101,8 +101,8 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            credentials: "credentials";
             none: "none";
+            credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
         }>;

package/dist/types.d.ts

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

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.7",
+	"version": "2.2.0-beta.9",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -75,10 +75,11 @@
 	"scripts": {
 		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
+		"lint:deprecated": "bun run scripts/lint-deprecated-usage.ts",
 		"format": "biome format --write",
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check && bun run build",
+		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run build",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
 		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",
@@ -91,7 +92,7 @@
 		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"typescript": "7.0.2"
+		"typescript": "6.0.3"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",