@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.8

package/dist/runtime/proxy-nodemaven.js

@@ -0,0 +1,128 @@
+import { createHash, randomBytes } from "node:crypto";
+export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+export const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+/**
+ * NodeMaven's fastest protocol: HTTP CONNECT. Benchmarks (KR, cold + warm)
+ * showed socks5 through the gateway adds ~500ms per request over http, so
+ * NodeMaven never defaults to socks5.
+ */
+export const NODEMAVEN_DEFAULT_PROTOCOL = "http";
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS = {
+    http: { min: 8080, max: 9080 },
+    socks5: { min: 1080, max: 2080 },
+};
+const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
+const DEFAULT_NODEMAVEN_FILTER = "medium";
+const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
+const NODEMAVEN_MAX_POOL_SIZE = 50;
+/** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
+const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
+const SID_LENGTH = 10;
+export function hasNodemavenCredentials() {
+    return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+function readNodemavenUsername() {
+    return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+function readNodemavenPassword() {
+    return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+function resolveNodemavenFilter() {
+    const raw = process.env[NODEMAVEN_FILTER_ENV]?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_NODEMAVEN_FILTER;
+    if (!NODEMAVEN_FILTERS.has(raw)) {
+        throw new Error(`${NODEMAVEN_FILTER_ENV} must be "medium" or "high"`);
+    }
+    return raw;
+}
+export function nodemavenPoolSize(policy) {
+    return Math.min(NODEMAVEN_MAX_POOL_SIZE, Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)));
+}
+function nodemavenLifetimeMinutes(policy) {
+    const configured = policy.session?.lifetimeMinutes;
+    if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+        return NODEMAVEN_MAX_LIFETIME_MINUTES;
+    }
+    return Math.min(NODEMAVEN_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configured)));
+}
+/** NodeMaven username tokens accept `[a-z0-9]`; slugify geo values to that set. */
+function slugifyGeo(value) {
+    if (!value)
+        return undefined;
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "");
+    return slug || undefined;
+}
+function isStickyAffinity(policy) {
+    return (policy.session?.affinity ?? "request") !== "request";
+}
+/**
+ * A sticky sid is deterministic from the affinity key so every process serving
+ * the same connection derives the same egress IP without shared storage. A
+ * rotating sid is random per call (a fresh egress IP per request).
+ */
+function deriveSid(policy, affinityKey, poolIndex, refreshEpoch) {
+    if (!isStickyAffinity(policy) || !affinityKey) {
+        return randomBytes(SID_LENGTH).toString("hex").slice(0, SID_LENGTH);
+    }
+    const digest = createHash("sha256")
+        .update(`${affinityKey}:${refreshEpoch}:${poolIndex}`)
+        .digest("hex");
+    // hex digits are a subset of the allowed [a-z0-9] sid charset.
+    return digest.slice(0, SID_LENGTH);
+}
+function selectPort(protocol, sid, poolIndex) {
+    const { min, max } = NODEMAVEN_PORTS[protocol];
+    const span = max - min + 1;
+    const hashInt = Number.parseInt(createHash("sha256").update(`${sid}:${poolIndex}`).digest("hex").slice(0, 8), 16);
+    return min + (hashInt % span);
+}
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export function synthesizeNodemavenProxy(input) {
+    const username = readNodemavenUsername();
+    const password = readNodemavenPassword();
+    if (!username || !password) {
+        throw new Error(`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`);
+    }
+    const filter = resolveNodemavenFilter();
+    const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
+    const port = selectPort(input.protocol, sid, input.poolIndex);
+    const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);
+    const country = slugifyGeo(input.country ?? input.policy.geo?.country);
+    const region = slugifyGeo(input.policy.geo?.subdivision);
+    const city = slugifyGeo(input.policy.geo?.city);
+    const tokens = [username];
+    if (country)
+        tokens.push("country", country);
+    if (region)
+        tokens.push("region", region);
+    if (city)
+        tokens.push("city", city);
+    tokens.push("sid", sid);
+    tokens.push("filter", filter);
+    tokens.push("ipv4", "true");
+    const proxyUsername = tokens.join("-");
+    // Username tokens are [a-z0-9-] only, which survive URL encoding unchanged.
+    const url = `${input.protocol}://${proxyUsername}:${encodeURIComponent(password)}@${NODEMAVEN_GATEWAY_HOST}:${port}`;
+    return {
+        url,
+        protocol: input.protocol,
+        diagnostics: {
+            vendor: "nodemaven",
+            protocol: input.protocol,
+            sticky: isStickyAffinity(input.policy),
+            filter,
+            lifetimeMinutes,
+            ...(country ? { country } : {}),
+        },
+    };
+}

package/dist/runtime/proxy-telemetry.d.ts

@@ -1,8 +1,9 @@
-import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink } from "../config/loader.js";
+import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyVendorFailoverTelemetryEvent } from "../config/loader.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
     #private;
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
+    recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void;
     recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void;
     toHeaderValue(): string | undefined;
 }

package/dist/runtime/proxy-telemetry.js

@@ -1,6 +1,7 @@
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const MAX_PROXY_FAILOVER_SAMPLES = 12;
 const CACHE_STATUS_SEVERITY = {
     disabled: 0,
     memory_hit: 1,
@@ -28,9 +29,11 @@ function encodeBase64Url(value) {
 export class ProxyTelemetryCollector {
     #events = [];
     #attempts = [];
+    #failovers = [];
     recordProxyResolution(event) {
         this.#events.push({
-            provider: "smartproxy",
+            provider: event.provider,
+            ...(event.protocol ? { protocol: event.protocol } : {}),
             cacheStatus: event.cacheStatus,
             cacheHit: event.cacheHit,
             resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
@@ -53,11 +56,22 @@ export class ProxyTelemetryCollector {
             refreshes: event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
         });
     }
+    recordProxyVendorFailover(event) {
+        if (this.#failovers.length >= MAX_PROXY_FAILOVER_SAMPLES)
+            return;
+        this.#failovers.push({
+            vendor: event.vendor,
+            ...(event.nextVendor ? { nextVendor: event.nextVendor } : {}),
+            phase: event.phase,
+            reason: event.reason,
+            ...(event.attempt === undefined ? {} : { attempt: Math.max(0, Math.floor(event.attempt)) }),
+        });
+    }
     recordProxyAttempt(event) {
         if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES)
             return;
         this.#attempts.push({
-            provider: "smartproxy",
+            provider: event.provider,
             attempt: Math.max(1, Math.floor(event.attempt || 1)),
             ...(event.poolIndex === undefined
                 ? {}
@@ -75,8 +89,16 @@ export class ProxyTelemetryCollector {
         const [first, ...rest] = this.#events;
         if (!first)
             return undefined;
+        // The serving vendor/protocol is the last recorded resolution (a failed
+        // vendor records first, the vendor that served records last).
+        const serving = this.#events[this.#events.length - 1] ?? first;
+        const vendors = [];
+        for (const event of this.#events) {
+            if (!vendors.includes(event.provider))
+                vendors.push(event.provider);
+        }
         const aggregate = rest.reduce((acc, event) => ({
-            provider: "smartproxy",
+            provider: event.provider,
             cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
             cacheHit: acc.cacheHit && event.cacheHit,
             resolutionMs: acc.resolutionMs + event.resolutionMs,
@@ -95,7 +117,8 @@ export class ProxyTelemetryCollector {
         const payload = {
             v: 1,
             proxy: {
-                provider: "smartproxy",
+                provider: serving.provider,
+                ...(serving.protocol ? { protocol: serving.protocol } : {}),
                 cacheStatus: aggregate.cacheStatus,
                 cacheHit: aggregate.cacheHit,
                 resolutionMs: aggregate.resolutionMs,
@@ -132,6 +155,18 @@ export class ProxyTelemetryCollector {
                         })),
                     }
                     : {}),
+                ...(vendors.length > 1 ? { vendors } : {}),
+                ...(this.#failovers.length > 0
+                    ? {
+                        failovers: this.#failovers.map((failover) => ({
+                            v: failover.vendor,
+                            ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+                            p: failover.phase,
+                            r: failover.reason,
+                            ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
+                        })),
+                    }
+                    : {}),
             },
         };
         const encoded = encodeBase64Url(JSON.stringify(payload));

package/dist/runtime/secrets.d.ts

@@ -0,0 +1,27 @@
+import type { EnvContext, ProviderDefinition } from "../types.js";
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export declare const MISSING_SECRET_CODE = "MISSING_SECRET";
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export declare function listMissingRequiredSecrets(provider: ProviderDefinition, env: EnvContext): string[];
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export declare function assertRequiredSecretsPresent(provider: ProviderDefinition, env: EnvContext): void;

package/dist/runtime/secrets.js

@@ -0,0 +1,51 @@
+import { ProviderSecretError } from "../errors.js";
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export const MISSING_SECRET_CODE = "MISSING_SECRET";
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export function listMissingRequiredSecrets(provider, env) {
+    const missing = [];
+    for (const secret of provider.secrets ?? []) {
+        if (secret.required !== true) {
+            continue;
+        }
+        const value = env.get(secret.name);
+        if (value === undefined || value.trim() === "") {
+            missing.push(secret.name);
+        }
+    }
+    return missing;
+}
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export function assertRequiredSecretsPresent(provider, env) {
+    const missing = listMissingRequiredSecrets(provider, env);
+    if (missing.length === 0) {
+        return;
+    }
+    const names = missing.join(", ");
+    throw new ProviderSecretError(`Missing required provider secret${missing.length > 1 ? "s" : ""}: ${names}`, {
+        code: MISSING_SECRET_CODE,
+        category: "credential_unavailable",
+        retryable: false,
+        fix: `Provision ${names} in the provider environment (e.g. Doppler). Declared in defineProvider({ secrets: [...] }).`,
+    });
+}

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, ProxyResolutionError, resolvePolicyProxyPoolSpan, resolveProxyConfigAsync, SMARTPROXY_MAX_POOL_SIZE, 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,11 @@ 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;
+/**
+ * Upper bound on attempts across a multi-vendor chain, so a two-vendor chain can
+ * exhaust each vendor's pool before failing over and finally throwing.
+ */
+const MAX_POLICY_PROXY_TOTAL_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE * 2;
 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 +467,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 +478,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 +492,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             url: resolvedProxy.url,
             poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
             proxyHash: proxyEndpointHash(resolvedProxy.url),
+            vendor: vendorFromResolvedSource(resolvedProxy.source),
         };
     }
     const session = {
@@ -506,11 +515,13 @@ 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));
+                    ? clientOptions.upstream.proxy
+                    : undefined);
+            const policyProxyAttemptCap = Math.max(1, Math.min(MAX_POLICY_PROXY_TOTAL_ATTEMPTS, policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE));
             const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
             let lastError;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
@@ -527,7 +538,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,7 +552,7 @@ 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 (attemptedProxies.has(proxy)) {

package/dist/server/serve.d.ts

@@ -35,6 +35,11 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
         message: string;
     }>;
 }) | {
+    level: "warn";
+    event: "provider_secrets_missing";
+    providerId: string;
+    missingSecrets: string[];
+} | {
     level: "warn";
     event: "provider_cleanup_failed";
     providerId: string;

package/dist/server/serve.js

@@ -18,6 +18,7 @@ import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import { getProviderBaseUrl } from "../runtime/provider.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 { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
 import { createStealthClient } from "../runtime/stealth.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
@@ -357,6 +358,18 @@ function providerObservabilityDetails(error) {
             retryable: error.options?.retryable ?? false,
         };
     }
+    // Missing-secret errors carry the canonical credential_unavailable category
+    // so Gateway/observability can attribute the failure to provisioning, not
+    // the upstream. Matched by code (not constructor) so both the SDK-owned
+    // runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
+    // serialize identically, including across duplicate SDK module instances.
+    if (isProviderError(error) && error.code === MISSING_SECRET_CODE) {
+        return {
+            category: error.options?.category ?? "credential_unavailable",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: error.options?.retryable ?? false,
+        };
+    }
     if (!isTransportError(error)) {
         return undefined;
     }
@@ -422,6 +435,10 @@ function toStatusCode(error) {
             case "AUTH_REQUIRED":
             case "reauth_required":
                 return 401;
+            // Unprovisioned declared secret: a deployment/config defect, never an
+            // upstream failure — explicit 400 (was only reached via fallthrough).
+            case MISSING_SECRET_CODE:
+                return 400;
             case "NOT_FOUND":
             case "not_found":
             case "NO_DATA":
@@ -885,8 +902,16 @@ async function handleAuthFlow(provider, request, route, options = {}, signal) {
             code: "AUTH_FLOW_NOT_CONFIGURED",
         });
     }
+    // Same SDK-owned gate as executeOperation: OAuth/credentials ceremonies
+    // depend on declared secrets (client ids/secrets), so fail structured before
+    // any flow code runs instead of at whatever point the ceremony first reads
+    // the env. `abort` stays exempt: a user must always be able to cancel a
+    // stranded flow even when provisioning is broken.
     const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
     try {
+        if (route !== "abort") {
+            assertRequiredSecretsPresent(provider, context.env);
+        }
         const result = route === "start"
             ? await flow.start(context)
             : route === "continue"
@@ -933,6 +958,20 @@ export function createServerApp(provider, options = {}) {
             providerId: provider.id,
             allowMemoryFallback: options.allowMemoryStateFallback === true,
         });
+    // Boot-time visibility for unprovisioned declared secrets: emit a structured
+    // warn so deploy tooling/alerting sees the gap the moment the pod boots,
+    // instead of discovering it request-by-request. Deliberately log-only — a
+    // boot crash would trade a structured MISSING_SECRET signal for
+    // CrashLoopBackOff. Requests still fail closed via the executeOperation gate.
+    const missingSecretsAtBoot = listMissingRequiredSecrets(provider, createEnvContext(provider.secrets?.map((secret) => secret.name)));
+    if (missingSecretsAtBoot.length > 0) {
+        logger({
+            level: "warn",
+            event: "provider_secrets_missing",
+            providerId: provider.id,
+            missingSecrets: missingSecretsAtBoot,
+        });
+    }
     app.notFound((c) => c.json({
         error: {
             code: "not_found",

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.5",
+	"version": "2.2.0-beta.8",
 	"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",

package/src/cli/commands.ts

@@ -2,6 +2,7 @@ export type ApifuseCommandName =
 	| "create"
 	| "dev"
 	| "check"
+	| "sync-assets"
 	| "submit-check"
 	| "bounty-check"
 	| "record"
@@ -46,6 +47,14 @@ export const COMMAND_MANIFEST: Record<
 		examples: ["apifuse check .", "apifuse check providers/korea-air-quality"],
 		modulePath: "./apifuse-check",
 	},
+	"sync-assets": {
+		name: "sync-assets",
+		summary:
+			"Regenerate SDK-managed agent prompt assets (AGENTS.md, .agents/skills, symlinks, manifest) for the installed SDK version.",
+		usage: "apifuse sync-assets [path] [--check]",
+		examples: ["apifuse sync-assets .", "apifuse sync-assets . --check"],
+		modulePath: "./apifuse-sync-assets",
+	},
 	"submit-check": {
 		name: "submit-check",
 		summary:
@@ -103,6 +112,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"create",
 	"dev",
 	"check",
+	"sync-assets",
 	"submit-check",
 	"record",
 	"test",