@apifuse/provider-sdk 2.2.0-beta.15 → 2.2.0-beta.17

package/AUTHORING.md

@@ -411,12 +411,14 @@ Provider-server failures use a stable public envelope:
 
 `retryable` is always present on responses emitted by the current SDK. Set
 `retryable` in the `ProviderError` options when the provider knows the answer;
-an explicit `true` or `false` wins over SDK derivation. When it is omitted, the
-SDK derives the value for its known error classes and otherwise defaults to
-`false`. During stateful rolling upgrades, the forwarding client also accepts
-an older owner response that omits `retryable` and treats it as `false` without
-loosening the emitted response contract. Existing optional `fix` guidance is
-also preserved when a `ProviderError` supplies it.
+an explicit `true` or `false` wins over the matching operation declaration and
+SDK derivation. When it is omitted, `operations.<id>.docs.errorCodes[].retryable`
+is used for a matching provider-owned code, followed by SDK derivation (which
+defaults ordinary `ProviderError` values to `false`). During stateful rolling
+upgrades, the forwarding client also accepts an older owner response that omits
+`retryable` and treats it as `false` without loosening the emitted response
+contract. Existing optional `fix` guidance is also preserved when a
+`ProviderError` supplies it.
 
 `details` belongs exclusively to the provider. The server passes
 `ProviderError.options.details` through verbatim, including strings and arrays,
@@ -435,8 +437,41 @@ Treat this header as telemetry, not as provider-controlled public error detail.
 Its category, taxonomy version, retryability, and optional upstream status match
 the structured `provider_request_failed` log event.
 
-Registered error-code mappings take precedence for every `ProviderError`,
-including `ValidationError`:
+Declare provider-owned operation failures next to their documentation. The
+server builds a lookup once at startup and applies it to failures from that
+operation:
+
+```ts
+docs: {
+  errorCodes: [{
+    code: "UPSTREAM_SCHEMA_ERROR",
+    status: 502,
+    retryable: true,
+    description: "The upstream response no longer matches its schema.",
+  }],
+},
+handler: async () => {
+  throw new ProviderError("Upstream schema changed", {
+    code: "UPSTREAM_SCHEMA_ERROR",
+  });
+},
+```
+
+`defineProvider` accepts only statuses the server can emit: 400, 401, 404, 429,
+500, 502, 503, and 504. Invalid declared statuses fail provider definition,
+not a live request. Status selection uses this order:
+
+1. SDK-owned errors retain SDK status semantics. Operation declarations cannot
+   override SDK-owned codes, stateful-forwarding failures, Zod/deadline errors,
+   or `TransportError` values.
+2. A matching operation `errorCodes` entry with `status` supplies the status.
+   This slot applies to `ValidationError` as well as ordinary `ProviderError`.
+3. The registered mappings below apply.
+4. Existing fallbacks apply: `TransportError` 502/504, unregistered input
+   `ValidationError` 400 (output validation 500), and other unregistered
+   `ProviderError` values 500.
+
+The registered mappings are:
 
 | Error code or fallback | HTTP status |
 | --- | ---: |
@@ -451,11 +486,15 @@ including `ValidationError`:
 
 An unregistered non-validation `ProviderError` code returns HTTP 500 and emits
 the greppable `unregistered_provider_error_code` signal with the code in the
-structured failure log. Before publishing a new code, register its status in
-the SDK mapping and add it to the mapping tests; declaring it only in operation
-documentation does not change runtime status selection. The HTTP 400
-`ValidationError` behavior is only the fallback for unregistered input
-validation codes; a registered code such as `NOT_FOUND` retains its mapped 404.
+structured failure log. A matching operation declaration, including one that
+omits `status`, makes the code registered for this signal and may independently
+supply `retryable`. The HTTP 400 `ValidationError` behavior is only the fallback
+when neither an operation status nor a registered mapping applies.
+
+Throw the domain `ProviderError` directly. Subclassing or wrapping it as a
+`TransportError` solely to preserve a 5xx response is obsolete; declare the
+domain code's `status` instead. Genuine `TransportError` values remain
+SDK-owned and keep their 502/504 mapping.
 
 ### Declared secrets are SDK-enforced
 
@@ -703,6 +742,46 @@ const credentialsAuth = defineCredentialsAuth({
   `bunx playwright install chromium`, or set
   `APIFUSE__CDP_POOL__URL` for remote browser debugging.
 
+### Native gateway adapter migration
+
+Native proxy resolution supports both HTTP CONNECT and SOCKS5 without
+terminating origin TLS. The built-in vendor order follows `proxy.providers`
+exactly: `smartproxy` means the `api.smartproxy.org` allocation vendor (raw
+`ip:port` endpoints), while `nodemaven` is the credentialed gateway. It is not
+the company formerly called Smartproxy; that separate company is represented
+by the deprecated `decodo` name.
+
+Custom `gatewaySynthesizers` must now accept the selected `protocol` and the
+injected `credentials` resolver on `NativeGatewayProxySynthesisInput`.
+Synthesizers may be async because allocation vendors perform network I/O. They
+may return a proxy, `undefined` when they do not implement the offered vendor,
+or `{ kind: "skipped", reason }` so an exhausted required chain can explain an
+absent credential, unsupported protocol, or allocation failure. Accordingly,
+`resolveNativeGatewayProxy(...)` must now be awaited.
+
+Callers that do not supply custom synthesizers or credentials keep env-backed
+behavior. Hosts that already have an allowlisted `EnvContext` can inject it
+explicitly, and vault-backed or per-tenant hosts can supply their own resolver:
+
+```ts
+import {
+  createEnvVendorCredentialResolver,
+  createNativeNetworkClient,
+} from "@apifuse/provider-sdk";
+
+const network = createNativeNetworkClient({
+  proxyPolicy: { mode: "required", providers: ["smartproxy", "nodemaven"] },
+  credentials: createEnvVendorCredentialResolver(ctx.env),
+  // Optional advanced override; omit for each vendor's default.
+  proxyProtocol: "socks5",
+});
+```
+
+Never include credential values in adapter skip messages or thrown errors. The
+SDK redacts built-in proxy URL userinfo, CONNECT authentication, and allocator
+causes, but a custom adapter remains responsible for not publishing secrets in
+its own diagnostics.
+
 ### Limiting stealth response bodies
 
 Set `maxBodyBytes` on `ctx.stealth.fetch()` or `session.redirects.run()` when an

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.17
+
+- Release candidate for main commit 5a0f9127a5861992d5c144b07ad379a085756544.
+
+## 2.2.0-beta.16
+
+- Release candidate for main commit c5deb2bc31a4a4a236d27a2ce3d214b533ed358f.
+
 ## 2.2.0-beta.15
 
 - Release candidate for main commit b5ebd25e48f6502e4ddb775d4e0a25f5c8276712.
@@ -90,6 +98,8 @@
 
 ## Unreleased
 
+- **Breaking for custom native gateway adapters:** `NativeGatewayProxySynthesisInput` now includes an injected `credentials` resolver and selected `protocol`; synthesizers may return promises and structured skip reasons, and `resolveNativeGatewayProxy` is async. Default callers retain env-backed behavior. Native transport now supports both HTTP CONNECT and SOCKS5, defaults per vendor with an explicit runtime override, registers smartproxy allocation ahead of nodemaven when declared in that order, and reports every exhausted vendor reason without exposing proxy credentials.
+- Honor operation `docs.errorCodes` at runtime: declared provider-owned statuses and retryability now drive the HTTP envelope, observability header, and structured log; invalid statuses fail `defineProvider`, declared codes no longer emit the unregistered-code signal, and `TransportError` status-preservation workarounds are obsolete.
 - Add an opt-in same-origin redirect hop policy to `ctx.http`, with bounded manual following and typed failures before a refused target is requested.
 - Enforce provider-declared native TCP/TLS egress before proxy or socket setup, with revocable and expiring dynamic grants plus typed authorization failures; providers without a native egress declaration retain legacy behavior.
 - **Breaking:** Provider error `details` is now passed through verbatim; SDK observability fields (`category`, `taxonomyVersion`, `upstreamStatus`, and derived `retryable`) are no longer merged into the public body. Emitted error envelopes now require top-level `retryable`, while inbound stateful forwarding tolerates an older owner response that omits it and defaults it to `false`. The removed observability metadata is available in the new `X-ApiFuse-Error-Observability` response header.

package/dist/config/loader.d.ts

@@ -150,12 +150,31 @@ export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions
  * Vendor allocation and failover remain owned by the SDK.
  */
 export declare function resolveProxy(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * 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 declare const VENDOR_DEFAULT_PROTOCOL: Readonly<Record<ProxyVendorName, ProxyProtocol>>;
 /**
  * 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 declare function assertTunnelingScheme(url: string): void;
+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 declare function resolveWithVendor(vendor: ProxyVendorName, policy: ProviderProxyPolicy, options: ProxyResolutionOptions, context: ProxyVendorResolutionContext): Promise<ResolvedProxyConfig>;
 /**
  * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
  * takes precedence over the legacy singular `provider`; the platform default

package/dist/config/loader.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { Redis } from "ioredis";
-import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_MAX_POOL_SIZE, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
+import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_FILTER_ENV, NODEMAVEN_MAX_POOL_SIZE, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
 // "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
@@ -415,7 +415,7 @@ export async function resolveProxy(options = {}) {
  * for smartproxy, and is the only protocol ctx.http (Bun native fetch) supports.
  * Override per call via ProxyResolutionOptions.protocol (harness/tests).
  */
-const VENDOR_DEFAULT_PROTOCOL = {
+export const VENDOR_DEFAULT_PROTOCOL = {
     smartproxy: "http",
     nodemaven: NODEMAVEN_DEFAULT_PROTOCOL,
 };
@@ -436,16 +436,33 @@ export function assertTunnelingScheme(url) {
         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.`);
     }
 }
-async function resolveWithVendor(vendor, policy, options, context) {
+export async function resolveWithVendor(vendor, policy, options, context) {
     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),
+            country: resolveSmartproxyCountry(policy, context.ambientDefaults !== false),
         });
         options.telemetry?.recordProxyResolution({
             provider: "nodemaven",
@@ -468,13 +485,15 @@ async function resolveWithVendor(vendor, policy, options, context) {
         };
     }
     // smartproxy allocation-style vendor.
-    const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+    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);
-    const allocated = await allocateSmartproxy(policy, appKey, lifetimeMinutes, options.affinityKey, context.protocol);
+    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];
@@ -665,11 +684,15 @@ export function mapFlatAttempt(flat, sizes) {
     }
     return { vendorIndex: 0, poolIndex: 0 };
 }
-function resolveSmartproxyCountry(policy) {
-    return (policy.geo?.country ?? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() ?? undefined);
+function resolveSmartproxyCountry(policy, ambientDefaults = true) {
+    return (policy.geo?.country ??
+        (ambientDefaults
+            ? process.env[DEFAULT_PROXY_COUNTRY_ENV]?.trim().toUpperCase() || undefined
+            : undefined));
 }
-function resolveSmartproxyLifetime(policy) {
-    const configuredLifetime = policy.session?.lifetimeMinutes ?? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30);
+function resolveSmartproxyLifetime(policy, ambientDefaults = true) {
+    const configuredLifetime = policy.session?.lifetimeMinutes ??
+        (ambientDefaults ? readPositiveNumberEnv(DEFAULT_PROXY_LIFETIME_ENV, 30) : 30);
     return Math.min(SMARTPROXY_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configuredLifetime)));
 }
 function readPositiveNumberEnv(name, fallback) {
@@ -692,20 +715,24 @@ function selectProxyPoolIndex(poolSize, attempt = 0) {
     const normalizedAttempt = Number.isFinite(attempt) ? Math.max(0, Math.floor(attempt)) : 0;
     return normalizedAttempt % poolSize;
 }
-function buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol) {
+function buildSmartproxyCacheKey(policy, appKey, affinityKey, lifetimeMinutes, protocol, ambientDefaults = true) {
     const poolSize = resolveSmartproxyPoolSize(policy);
     return JSON.stringify({
         provider: "smartproxy",
+        credentialHash: createHash("sha256")
+            .update("apifuse-smartproxy-credential:v1\0")
+            .update(appKey)
+            .digest("hex"),
         protocol,
-        country: resolveSmartproxyCountry(policy),
+        country: resolveSmartproxyCountry(policy, ambientDefaults),
         affinity: policy.session?.affinity ?? "request",
         affinityKey: (policy.session?.affinity ?? "request") === "request" ? undefined : affinityKey,
         lifetimeMinutes,
         poolSize,
     });
 }
-async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey, protocol) {
-    const cacheKey = buildSmartproxyCacheKey(policy, affinityKey, lifetimeMinutes, protocol);
+async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey, protocol, ambientDefaults = true, sharedCache = true) {
+    const cacheKey = buildSmartproxyCacheKey(policy, appKey, affinityKey, lifetimeMinutes, protocol, ambientDefaults);
     const startedAt = Date.now();
     const now = startedAt;
     const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
@@ -713,7 +740,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
     const cached = proxyCache.get(cacheKey);
     if (!skipCached && cached && isFresh(cached, now)) {
         if (shouldSoftRefresh(cached, now)) {
-            void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol);
+            void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol, ambientDefaults, sharedCache);
             return {
                 pool: cached,
                 telemetry: telemetryForPool(cached, "soft_stale_refresh", startedAt, {
@@ -726,7 +753,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
             telemetry: telemetryForPool(cached, "memory_hit", startedAt),
         };
     }
-    if (!skipCached) {
+    if (!skipCached && sharedCache) {
         const redisResult = await readSmartproxyRedisPool(cacheKey, startedAt);
         if (redisResult)
             return redisResult;
@@ -741,7 +768,7 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
             }),
         };
     }
-    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol).finally(() => {
+    const promise = allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, ambientDefaults, sharedCache).finally(() => {
         proxyInflight.delete(cacheKey);
     });
     proxyInflight.set(cacheKey, promise);
@@ -772,9 +799,9 @@ async function readSmartproxyRedisPool(cacheKey, startedAt) {
         telemetry: telemetryForPool(pool, "redis_hit", startedAt, { redisReadMs }),
     };
 }
-async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol) {
+async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol, ambientDefaults, sharedCache) {
     try {
-        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), protocol, {
+        await allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, Date.now(), protocol, ambientDefaults, sharedCache, {
             background: true,
         });
     }
@@ -782,10 +809,10 @@ async function refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes,
         // Soft refresh is opportunistic; current fresh pool remains usable.
     }
 }
-async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, options = {}) {
-    const redis = getProxyRedis();
+async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinutes, startedAt, protocol, ambientDefaults, sharedCache, options = {}) {
+    const redis = sharedCache ? getProxyRedis() : undefined;
     if (!redis || !(await ensureRedisReady(redis))) {
-        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator", protocol });
+        return await allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, { cacheStatus: "allocator", protocol, ambientDefaults });
     }
     const poolKey = smartproxyRedisPoolKey(cacheKey);
     const lockKey = smartproxyRedisLockKey(cacheKey);
@@ -800,6 +827,7 @@ async function allocateSmartproxyShared(cacheKey, policy, appKey, lifetimeMinute
                     redis,
                     poolKey,
                     protocol,
+                    ambientDefaults,
                 });
             }
             finally {
@@ -912,7 +940,7 @@ async function readSmartproxyAllocatorBodyWithDeadline(response, signal) {
 }
 async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, startedAt, options) {
     const poolSize = resolveSmartproxyPoolSize(policy);
-    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, options.protocol);
+    const allocatorUrl = buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, options.protocol, options.ambientDefaults);
     const allocatorStartedAt = Date.now();
     const allocatorDeadlineAt = allocatorStartedAt + smartproxyAllocatorDeadlineMs();
     let allocation;
@@ -970,7 +998,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
         expiresAt: allocatedAt + ttlMs,
         diagnostics: {
             provider: "smartproxy",
-            country: resolveSmartproxyCountry(policy) ?? "default",
+            country: resolveSmartproxyCountry(policy, options.ambientDefaults) ?? "default",
             lifetimeMinutes,
             affinity: policy.session?.affinity ?? "request",
             rawConnect: true,
@@ -1090,7 +1118,7 @@ const SMARTPROXY_PROTOCOL_PARAM = {
     http: "1",
     socks5: "2",
 };
-function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, protocol) {
+function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize, protocol, ambientDefaults = true) {
     const params = new URLSearchParams({
         app_key: appKey,
         pt: "9",
@@ -1100,7 +1128,7 @@ function buildSmartproxyAllocatorUrl(policy, appKey, lifetimeMinutes, poolSize,
         format: "txt",
         lb: "\\n",
     });
-    const country = resolveSmartproxyCountry(policy);
+    const country = resolveSmartproxyCountry(policy, ambientDefaults);
     if (country) {
         params.set("cc", country);
     }
@@ -1172,7 +1200,10 @@ function markSmartproxyCacheInvalidated(options = {}) {
         return undefined;
     }
     const lifetimeMinutes = resolveSmartproxyLifetime(policy);
-    const cacheKey = buildSmartproxyCacheKey(policy, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);
+    const appKey = process.env[SMARTPROXY_APP_KEY_ENV]?.trim();
+    if (!appKey)
+        return undefined;
+    const cacheKey = buildSmartproxyCacheKey(policy, appKey, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);
     invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
     proxyCache.delete(cacheKey);
     proxyInflight.delete(cacheKey);

package/dist/define.js

@@ -1,9 +1,10 @@
 import ms from "ms";
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
 import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
 import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
-import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
+import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, VALID_OPERATION_ERROR_STATUSES, } from "./types.js";
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"];
@@ -410,6 +411,23 @@ function validateOperationObservability(providerId, operations) {
         }
     }
 }
+function validateOperationErrorCodes(providerId, operations) {
+    for (const [operationName, operation] of Object.entries(operations)) {
+        for (const [index, errorCode] of (operation.docs?.errorCodes ?? []).entries()) {
+            if (errorCode.status !== undefined &&
+                !VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)) {
+                const field = `operations.${operationName}.docs.errorCodes[${index}].status`;
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}: ${String(errorCode.status)} is not an emittable provider error status.`, {
+                    fix: `Set ${field} to one of ${VALID_OPERATION_ERROR_STATUSES.join(", ")}, or omit it.`,
+                });
+            }
+            if (errorCode.status !== undefined &&
+                SDK_RUNTIME_OWNED_ERROR_CODES.has(errorCode.code)) {
+                console.warn(`[provider-sdk] Provider "${providerId}" operation "${operationName}" declares status ${errorCode.status} for SDK-owned error code "${errorCode.code}"; the declared status is documentation-only and will be ignored at runtime.`);
+            }
+        }
+    }
+}
 const JSON_TRANSPORT_FIELDS = new Set(["kind"]);
 const SSE_TRANSPORT_FIELDS = new Set([
     "kind",
@@ -1396,6 +1414,7 @@ export function defineProvider(config) {
     validateOperationIds(config.id, config.operations);
     validateOperationAnnotations(config.id, config.operations);
     validateOperationObservability(config.id, config.operations);
+    validateOperationErrorCodes(config.id, config.operations);
     validateOperationTransports(config.id, config.operations);
     validateOperationContracts(config.id, config.operations);
     validateToolRouterMetadata(config.id, config.operations);

package/dist/error-resolution.d.ts

@@ -0,0 +1,2 @@
+export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
+export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;

package/dist/error-resolution.js

@@ -0,0 +1,90 @@
+// This set suppresses the unregistered-provider-error-code signal for codes
+// intentionally emitted by SDK paths. It is not the complete authority for
+// runtime error resolution: branded errors and additional canonical SDK codes
+// must also remain immune to provider-declared status/retryability overrides.
+export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+    "MISSING_SECRET",
+    "AUTH_PROMPT_UNAVAILABLE",
+    "BROWSER_CDP_POOL_REQUIRED",
+    "BROWSER_RUNTIME_UNSUPPORTED",
+    "STEALTH_RUNTIME_UNSUPPORTED",
+    "SSE_EVENT_UNDECLARED",
+    "STREAM_EVENT_TOO_LARGE",
+    "STREAM_CHUNK_TOO_LARGE",
+    "SSE_RESULT_UNSUPPORTED",
+    "STREAM_RESULT_UNSUPPORTED",
+    "AUTH_FLOW_NOT_CONFIGURED",
+    "refresh_not_supported",
+    "RUNTIME_UNSUPPORTED",
+    "PROVIDER_STATE_UNSUPPORTED",
+    "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+    "CHOICE_STATE_PAYLOAD_TOO_LARGE",
+    "CHOICE_STATE_UNAVAILABLE",
+    "CHOICE_CONTEXT_REQUIRED",
+    "unsupported_stealth_cookie_store_version",
+    "provider_secret_error",
+    "credential_key_error",
+    "credential_mode_error",
+    "flow_expired",
+    "turn_validation_error",
+    "context_access_error",
+    "UNSUPPORTED_STT_OPTION",
+    "INVALID_STT_AUDIO",
+    "STT_AUDIO_TOO_LARGE",
+    "STT_UPSTREAM_FAILED",
+    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+    "NO_CODE_FOUND",
+    "AMBIGUOUS_CODE",
+    "retry_invalid_policy",
+    "retry_unsafe_method",
+    "stealth_cookie_store_serialize_failed",
+    "response_too_large",
+    "transport_stream_unavailable",
+    "transport_invalid_method",
+    "http_transport_override_unsupported",
+    "http_redirect_policy_invalid",
+    "http_redirect_stopped",
+    "http_redirect_max_hops",
+    "http_redirect_missing_location",
+    "http_redirect_loop",
+    "transport_invalid_url",
+    "retry_exhausted",
+    "auth_abort_unsafe_data",
+    "credentials_auth_missing_credential_keys",
+    "credentials_auth_missing_credential",
+    "credentials_auth_invalid_login_result",
+    "credentials_auth_unknown_challenge",
+    "credentials_auth_unknown_pending_challenge",
+    "STATEFUL_FORWARDING_NOT_CONFIGURED",
+    "STATEFUL_FORWARDING_SIGNATURE_MISSING",
+    "STATEFUL_FORWARDING_NONCE_INVALID",
+    "STATEFUL_FORWARDING_TIMESTAMP_INVALID",
+    "STATEFUL_FORWARDING_SIGNATURE_INVALID",
+    "STATEFUL_FORWARDING_REPLAY_DETECTED",
+    "STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+    "STATEFUL_FORWARDING_ENVELOPE_INVALID",
+    "STATEFUL_FORWARDING_PROVIDER_MISMATCH",
+    "STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+    "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+    "STATEFUL_FORWARDING_REQUEST_FAILED",
+    "STATEFUL_FORWARDING_CONTEXT_MISSING",
+    "STATEFUL_FORWARDING_BAD_RESPONSE",
+    "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+    "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+    "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+    "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+    "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+    "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+]);
+// Complete code authority for provider-declared runtime resolution. Keep this
+// separate from signal suppression: declarations may document these codes, but
+// their status and retryability can never override the SDK's canonical result.
+export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
+    ...SDK_OWNED_PROVIDER_ERROR_CODES,
+    "reauth_required",
+    "STT_UNAVAILABLE",
+    "UNSUPPORTED_STT_BACKEND",
+    "OUTPUT_VALIDATION_FAILED",
+    "NOT_FOUND",
+    "not_found",
+]);

package/dist/index.d.ts

@@ -22,7 +22,7 @@ export { type CreateCredentialContextOptions, createCredentialContext, } from ".
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, createEnvVendorCredentialResolver, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, type NativeGatewayProxy, type NativeGatewayProxyResolutionInput, type NativeGatewayProxySkipReason, type NativeGatewayProxySynthesizer, type NativeGatewayProxySynthesisResult, type NativeGatewayProxySynthesisInput, type NativeNetworkClientOptions, type NativeNetworkErrorCode, type VendorCredentialLookup, type VendorCredentialResolver, } from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
 export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
@@ -37,7 +37,7 @@ export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SEN
 export { createServerApp, ERROR_OBSERVABILITY_HEADER, type ServeOptions, serve, } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";

package/dist/index.js

@@ -20,7 +20,7 @@ export { createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
-export { createNativeNetworkClient, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
+export { createNativeNetworkClient, createEnvVendorCredentialResolver, deriveNativeCredentialAffinityKey, NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, resolveNativeGatewayProxy, } from "./runtime/native-network.js";
 export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { prevalidate } from "./runtime/prevalidate.js";

package/dist/native-egress-policy.d.ts

@@ -10,6 +10,7 @@ export type DynamicEgressRuleSnapshot = {
     readonly sourcePorts: readonly number[];
     readonly sourcePortRanges: readonly NativeTcpPortRange[];
     readonly targetHostSuffixes: readonly string[];
+    readonly targetIpv4Cidrs: readonly string[];
     readonly targetPorts: readonly number[];
     readonly targetPortRanges: readonly NativeTcpPortRange[];
     readonly tls: NativeTcpTlsMode;