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

package/dist/runtime/otlp.d.ts

@@ -1,4 +1,4 @@
-import type { TraceSpan } from "../types";
+import type { TraceSpan } from "../types.js";
 export interface OTLPExportOptions {
     endpoint: string;
     headers?: Record<string, string>;

package/dist/runtime/perf.d.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 export type PerfStats = {
     p50: number;
     p95: number;

package/dist/runtime/provider.d.ts

@@ -1,2 +1,2 @@
-import type { ProviderDefinition } from "../types";
+import type { ProviderDefinition } from "../types.js";
 export declare function getProviderBaseUrl(provider: ProviderDefinition): string | undefined;

package/dist/runtime/provider.js

@@ -1,8 +1,7 @@
 export function getProviderBaseUrl(provider) {
     const operations = Object.values(provider.operations);
     for (const operation of operations) {
-        const baseUrl = operation.upstream
-            ?.baseUrl;
+        const baseUrl = operation.upstream?.baseUrl;
         if (typeof baseUrl === "string" && baseUrl.length > 0) {
             return baseUrl;
         }

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

@@ -1,4 +1,4 @@
-import { TransportError } from "../errors";
+import { TransportError } from "../errors.js";
 export declare const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
 export declare const PROXY_AUTH_IP_DENIED_MESSAGE = "Proxy source IP is not authorized. Add the runtime egress IP to the proxy provider allowlist.";
 export declare const PROXY_EDGE_AUTH_REJECTED_CODE = "PROXY_EDGE_AUTH_REJECTED";

package/dist/runtime/proxy-errors.js

@@ -1,4 +1,4 @@
-import { TransportError } from "../errors";
+import { TransportError } from "../errors.js";
 export const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
 export const PROXY_AUTH_IP_DENIED_MESSAGE = "Proxy source IP is not authorized. Add the runtime egress IP to the proxy provider allowlist.";
 export const PROXY_EDGE_AUTH_REJECTED_CODE = "PROXY_EDGE_AUTH_REJECTED";
@@ -11,8 +11,12 @@ const PROXY_POOL_STALE_STATUS_CODES = new Set([509, 512]);
 const PROXY_EDGE_TLS_REJECTED_STATUS_CODES = new Set([495]);
 const PROXY_AUTH_IP_DENIED_PATTERN = /\b(?:source|egress|client)\s+ip\b.{0,120}\b(?:deny|denied|unauthori[sz]ed|not\s+authori[sz]ed|white\s*list|allow\s*list)\b|\b(?:white\s*list|allow\s*list)\b.{0,120}\b(?:source|egress|client)\s+ip\b/i;
 const PROXY_EDGE_AUTH_REJECTED_PATTERN = /\bauth\s+ip\s+err\b|\bproxy\b.{0,120}\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b|\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b.{0,120}\bproxy\b/i;
-const PROXY_POOL_STALE_MESSAGE_PATTERN = /\bproxy\b.{0,120}\b(?:pool|lease|expired|unavailable|exhausted|non[\s-]?200\s+code:\s*(?:509|512))\b|\bnon[\s-]?200\s+code:\s*(?:509|512)\b.{0,120}\bproxy\b|\bsmartproxy\b.{0,120}\b(?:509|512)\b/i;
-const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = /\b(?:smartproxy|proxy)\b.{0,160}\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b|\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b.{0,160}\b(?:smartproxy|proxy)\b/i;
+// Vendor host tokens that can appear in upstream error strings. Adding a proxy
+// vendor updates every classifier below in one place. `proxy` is the generic
+// fallback so vendor-agnostic messages still classify.
+const PROXY_VENDOR_ALTERNATION = "smartproxy|nodemaven|proxy";
+const PROXY_POOL_STALE_MESSAGE_PATTERN = new RegExp(`\\bproxy\\b.{0,120}\\b(?:pool|lease|expired|unavailable|exhausted|non[\\s-]?200\\s+code:\\s*(?:509|512))\\b|\\bnon[\\s-]?200\\s+code:\\s*(?:509|512)\\b.{0,120}\\bproxy\\b|\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,120}\\b(?:509|512)\\b`, "i");
+const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = new RegExp(`\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,160}\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b|\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b.{0,160}\\b(?:${PROXY_VENDOR_ALTERNATION})\\b`, "i");
 export function isProxyAuthIpDeniedMessage(message) {
     return PROXY_AUTH_IP_DENIED_PATTERN.test(message);
 }
@@ -42,8 +46,7 @@ export function isProxyPoolStaleMessage(message) {
     return PROXY_POOL_STALE_MESSAGE_PATTERN.test(message);
 }
 export function isProxyPoolRefreshableError(error) {
-    if (error instanceof TransportError &&
-        error.code === PROXY_AUTH_IP_DENIED_CODE) {
+    if (error instanceof TransportError && error.code === PROXY_AUTH_IP_DENIED_CODE) {
         return false;
     }
     if (error instanceof TransportError &&
@@ -57,8 +60,7 @@ export function isProxyPoolRefreshableError(error) {
         error instanceof Error ? error.message : String(error),
         cause instanceof Error ? cause.message : "",
     ].join(" ");
-    return (PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) ||
-        PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message));
+    return (PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) || PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message));
 }
 export const isProxyPoolStaleError = isProxyPoolRefreshableError;
 export function createProxyPoolStaleError(status, cause) {

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

@@ -0,0 +1,56 @@
+import type { ProviderProxyPolicy } from "../types.js";
+export declare const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export declare const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export declare const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+export declare const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+export type NodemavenCredentials = {
+    readonly username: string;
+    readonly password: string;
+    readonly filter?: string;
+};
+/** Both schemes tunnel bytes end-to-end, preserving the client TLS handshake. */
+export type ProxyProtocol = "http" | "socks5";
+/**
+ * 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 declare const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol;
+export declare const NODEMAVEN_MAX_POOL_SIZE = 50;
+export declare function hasNodemavenCredentials(): boolean;
+export declare function nodemavenPoolSize(policy: ProviderProxyPolicy): number;
+export declare function nodemavenLifetimeMinutes(policy: ProviderProxyPolicy): number;
+export type NodemavenSessionWindow = {
+    refreshEpoch: number;
+    expiresAt: string;
+};
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export declare function nodemavenSessionWindow(policy: ProviderProxyPolicy, now?: number): NodemavenSessionWindow;
+export type NodemavenSynthesisInput = {
+    policy: ProviderProxyPolicy;
+    /** Explicit credentials; synthesis never reads process-global state. */
+    credentials: NodemavenCredentials;
+    affinityKey: string | undefined;
+    protocol: ProxyProtocol;
+    poolIndex: number;
+    refreshEpoch: number;
+    /** ISO 3166-1 alpha-2, already resolved by the caller (falls back to env). */
+    country?: string;
+    /** Clock injection used by native sticky-expiry lifecycle tests. */
+    now?: number;
+    /** Stable caller-owned hard expiry when the refresh epoch is wall-clock-derived. */
+    expiresAt?: string;
+};
+export type NodemavenSynthesis = {
+    url: string;
+    protocol: ProxyProtocol;
+    sticky: boolean;
+    sessionId: string;
+    expiresAt?: string;
+    diagnostics: Record<string, string | number | boolean>;
+};
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export declare function synthesizeNodemavenProxy(input: NodemavenSynthesisInput): NodemavenSynthesis;

package/dist/runtime/proxy-nodemaven.js

@@ -0,0 +1,146 @@
+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;
+export 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(value) {
+    const raw = value?.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)));
+}
+export 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)));
+}
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export function nodemavenSessionWindow(policy, now = Date.now()) {
+    const lifetimeMs = nodemavenLifetimeMinutes(policy) * 60_000;
+    const refreshEpoch = Math.floor(now / lifetimeMs);
+    return {
+        refreshEpoch,
+        expiresAt: new Date((refreshEpoch + 1) * lifetimeMs).toISOString(),
+    };
+}
+/** 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 = input.credentials.username.trim();
+    const password = input.credentials.password.trim();
+    if (!username || !password) {
+        throw new Error(`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`);
+    }
+    const filter = resolveNodemavenFilter(input.credentials.filter);
+    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 sticky = isStickyAffinity(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,
+        sticky,
+        sessionId: sid,
+        ...(sticky
+            ? {
+                expiresAt: input.expiresAt ??
+                    new Date((input.now ?? Date.now()) + lifetimeMinutes * 60_000).toISOString(),
+            }
+            : {}),
+        diagnostics: {
+            vendor: "nodemaven",
+            protocol: input.protocol,
+            sticky,
+            filter,
+            lifetimeMinutes,
+            ...(country ? { country } : {}),
+        },
+    };
+}

package/dist/runtime/proxy-retry-policy.d.ts

@@ -1,5 +1,5 @@
-import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types";
-import { HttpRetryPreset } from "../types";
+import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types.js";
+import { HttpRetryPreset } from "../types.js";
 export type NormalizedProxyTransportRetryOptions = Required<Pick<HttpRetryOptions, "attempts" | "delayStrategy" | "baseDelayMs" | "maxDelayMs" | "jitter" | "retryAfter" | "unsafeMethodPolicy">> & {
     preset?: HttpRetryPreset;
     methods: readonly string[];

package/dist/runtime/proxy-retry-policy.js

@@ -1,5 +1,5 @@
-import { ProviderError, TransportError } from "../errors";
-import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types";
+import { ProviderError, TransportError } from "../errors.js";
+import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types.js";
 export const DEFAULT_PROXY_TRANSPORT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
 export const DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES = [
     "transport_network_error",

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

@@ -1,8 +1,9 @@
-import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink } from "../config/loader";
+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,
@@ -20,9 +21,7 @@ function maxOptional(left, right) {
     return values.length > 0 ? Math.max(...values) : undefined;
 }
 function worseStatus(left, right) {
-    return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left]
-        ? right
-        : left;
+    return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left] ? right : left;
 }
 function encodeBase64Url(value) {
     return Buffer.from(value, "utf8").toString("base64url");
@@ -30,15 +29,15 @@ 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)),
-            allocatorMs: event.allocatorMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.allocatorMs)),
+            allocatorMs: event.allocatorMs === undefined ? undefined : Math.max(0, Math.floor(event.allocatorMs)),
             allocatorStatus: event.allocatorStatus === undefined
                 ? undefined
                 : Math.max(0, Math.floor(event.allocatorStatus)),
@@ -46,32 +45,33 @@ export class ProxyTelemetryCollector {
             allocatorAttempts: event.allocatorAttempts === undefined
                 ? undefined
                 : Math.max(1, Math.floor(event.allocatorAttempts)),
-            lockWaitMs: event.lockWaitMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.lockWaitMs)),
-            redisReadMs: event.redisReadMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.redisReadMs)),
-            redisWriteMs: event.redisWriteMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.redisWriteMs)),
-            poolAgeMs: event.poolAgeMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.poolAgeMs)),
+            lockWaitMs: event.lockWaitMs === undefined ? undefined : Math.max(0, Math.floor(event.lockWaitMs)),
+            redisReadMs: event.redisReadMs === undefined ? undefined : Math.max(0, Math.floor(event.redisReadMs)),
+            redisWriteMs: event.redisWriteMs === undefined ? undefined : Math.max(0, Math.floor(event.redisWriteMs)),
+            poolAgeMs: event.poolAgeMs === undefined ? undefined : Math.max(0, Math.floor(event.poolAgeMs)),
             poolExpiresInMs: event.poolExpiresInMs === undefined
                 ? undefined
                 : Math.max(0, Math.floor(event.poolExpiresInMs)),
             attempts: Math.max(1, Math.floor(event.attempts || 1)),
-            refreshes: event.refreshes === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.refreshes)),
+            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
                 ? {}
@@ -79,9 +79,7 @@ export class ProxyTelemetryCollector {
             ...(event.proxyHash ? { proxyHash: event.proxyHash.slice(0, 16) } : {}),
             outcome: event.outcome === "ok" ? "ok" : "error",
             ...(event.errorCode ? { errorCode: event.errorCode.slice(0, 80) } : {}),
-            ...(event.status === undefined
-                ? {}
-                : { status: Math.max(0, Math.floor(event.status)) }),
+            ...(event.status === undefined ? {} : { status: Math.max(0, Math.floor(event.status)) }),
             ...(event.durationMs === undefined
                 ? {}
                 : { durationMs: Math.max(0, Math.floor(event.durationMs)) }),
@@ -91,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,
@@ -111,13 +117,12 @@ 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,
-                ...(aggregate.allocatorMs !== undefined
-                    ? { allocatorMs: aggregate.allocatorMs }
-                    : {}),
+                ...(aggregate.allocatorMs !== undefined ? { allocatorMs: aggregate.allocatorMs } : {}),
                 ...(aggregate.allocatorStatus !== undefined
                     ? { allocatorStatus: aggregate.allocatorStatus }
                     : {}),
@@ -127,40 +132,38 @@ export class ProxyTelemetryCollector {
                 ...(aggregate.allocatorAttempts !== undefined
                     ? { allocatorAttempts: aggregate.allocatorAttempts }
                     : {}),
-                ...(aggregate.lockWaitMs !== undefined
-                    ? { lockWaitMs: aggregate.lockWaitMs }
-                    : {}),
-                ...(aggregate.redisReadMs !== undefined
-                    ? { redisReadMs: aggregate.redisReadMs }
-                    : {}),
-                ...(aggregate.redisWriteMs !== undefined
-                    ? { redisWriteMs: aggregate.redisWriteMs }
-                    : {}),
-                ...(aggregate.poolAgeMs !== undefined
-                    ? { poolAgeMs: aggregate.poolAgeMs }
-                    : {}),
+                ...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
+                ...(aggregate.redisReadMs !== undefined ? { redisReadMs: aggregate.redisReadMs } : {}),
+                ...(aggregate.redisWriteMs !== undefined ? { redisWriteMs: aggregate.redisWriteMs } : {}),
+                ...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
                 ...(aggregate.poolExpiresInMs !== undefined
                     ? { poolExpiresInMs: aggregate.poolExpiresInMs }
                     : {}),
                 attempts: aggregate.attempts,
-                ...(aggregate.refreshes !== undefined
-                    ? { refreshes: aggregate.refreshes }
-                    : {}),
+                ...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
                 ...(this.#attempts.length > 0
                     ? {
                         attemptSamples: this.#attempts.map((attempt, index) => ({
                             n: index + 1,
                             a: attempt.attempt,
-                            ...(attempt.poolIndex === undefined
-                                ? {}
-                                : { i: attempt.poolIndex }),
+                            ...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
                             ...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
                             o: attempt.outcome,
                             ...(attempt.errorCode ? { c: attempt.errorCode } : {}),
                             ...(attempt.status === undefined ? {} : { s: attempt.status }),
-                            ...(attempt.durationMs === undefined
-                                ? {}
-                                : { d: attempt.durationMs }),
+                            ...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
+                        })),
+                    }
+                    : {}),
+                ...(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 }),
                         })),
                     }
                     : {}),

package/dist/runtime/redirects.d.ts

@@ -0,0 +1,29 @@
+import type { HttpRedirectFailureReason } from "../types.js";
+export type RedirectHopDecision<TMethod extends string> = {
+    kind: "follow";
+    nextMethod: TMethod | "GET";
+    nextUrl: string;
+} | {
+    kind: "stop";
+    reason: HttpRedirectFailureReason;
+    nextUrl?: string;
+};
+export declare function isRedirectStatus(status: number): boolean;
+/** Shared fetch-compatible redirect method rewriting for stealth and ctx.http. */
+export declare function nextRedirectMethod<TMethod extends string>(status: number, method: TMethod): TMethod | "GET";
+/** Resolves a Location value against the response URL without issuing a request. */
+export declare function resolveRedirectUrl(location: string | undefined, responseUrl: string): string | undefined;
+/**
+ * Shared post-response decision ordering for both redirect walkers. The
+ * caller-owned stop hook is checked first, matching stealth's pre-follow
+ * contract, then structural termination and loop checks run before follow.
+ */
+export declare function evaluateRedirectHop<TMethod extends string>(input: {
+    status: number;
+    method: TMethod;
+    nextUrl: string | undefined;
+    shouldStop: boolean;
+    redirectCount: number;
+    maxHops: number;
+    visitedRequests: ReadonlySet<string>;
+}): RedirectHopDecision<TMethod>;

package/dist/runtime/redirects.js

@@ -0,0 +1,36 @@
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+export function isRedirectStatus(status) {
+    return REDIRECT_STATUSES.has(status);
+}
+/** Shared fetch-compatible redirect method rewriting for stealth and ctx.http. */
+export function nextRedirectMethod(status, method) {
+    if (status === 303 && method !== "HEAD")
+        return "GET";
+    if ((status === 301 || status === 302) && method === "POST")
+        return "GET";
+    return method;
+}
+/** Resolves a Location value against the response URL without issuing a request. */
+export function resolveRedirectUrl(location, responseUrl) {
+    return location ? new URL(location, responseUrl).toString() : undefined;
+}
+/**
+ * Shared post-response decision ordering for both redirect walkers. The
+ * caller-owned stop hook is checked first, matching stealth's pre-follow
+ * contract, then structural termination and loop checks run before follow.
+ */
+export function evaluateRedirectHop(input) {
+    if (input.shouldStop) {
+        return { kind: "stop", reason: "stopped", ...(input.nextUrl ? { nextUrl: input.nextUrl } : {}) };
+    }
+    if (!input.nextUrl)
+        return { kind: "stop", reason: "missing_location" };
+    if (input.redirectCount > input.maxHops) {
+        return { kind: "stop", reason: "max_hops", nextUrl: input.nextUrl };
+    }
+    const nextMethod = nextRedirectMethod(input.status, input.method);
+    if (input.visitedRequests.has(`${nextMethod} ${input.nextUrl}`)) {
+        return { kind: "stop", reason: "loop", nextUrl: input.nextUrl };
+    }
+    return { kind: "follow", nextMethod, nextUrl: input.nextUrl };
+}

package/dist/runtime/redis.d.ts

@@ -1,4 +1,4 @@
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 export type ProviderRedisClient = Redis;
 export type ProviderRedisClientOptions = {
     readonly redisUrl: string;

package/dist/runtime/redis.js

@@ -1,4 +1,4 @@
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 export function createProviderRedisClient(options) {
     const redis = new Redis(options.redisUrl, {
         connectTimeout: options.timeoutMs,
@@ -23,9 +23,7 @@ export async function withRedisTimeout(operation, options) {
                 }
             }, options.timeoutMs);
         });
-        const operationResult = options.onError
-            ? operation().catch(options.onError)
-            : operation();
+        const operationResult = options.onError ? operation().catch(options.onError) : operation();
         return await Promise.race([operationResult, timeout]);
     }
     finally {