@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.10

package/dist/runtime/instrumentation.js

@@ -1,11 +1,10 @@
-import { createTraceContext, getTraceRecorder, } from "./trace";
-const BROWSER_PAGE_METHODS = new Set([
-    "goto",
-    "fill",
-    "click",
-    "type",
-    "waitForSelector",
-]);
+import { createTraceContext, getTraceRecorder, } from "./trace.js";
+const BROWSER_PAGE_METHODS = new Set(["goto", "fill", "click", "type", "waitForSelector"]);
+function isThenable(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof value.then === "function");
+}
 function getErrorStatus(error) {
     if (typeof error === "object" &&
         error !== null &&
@@ -69,9 +68,7 @@ function buildSpanAttributes(namespace, methodName, args, result, error) {
     const attributes = {};
     const url = getUrl(namespace, args, result);
     const method = getMethod(namespace, methodName, args);
-    const status = error
-        ? getErrorStatus(error)
-        : getResponseStatus(namespace, result);
+    const status = error ? getErrorStatus(error) : getResponseStatus(namespace, result);
     const duration = error ? undefined : getResponseDuration(result);
     if (url) {
         attributes.url = url;
@@ -79,8 +76,7 @@ function buildSpanAttributes(namespace, methodName, args, result, error) {
     if (method) {
         attributes.method = method;
     }
-    if (status !== undefined &&
-        (namespace === "http" || namespace === "stealth")) {
+    if (status !== undefined && (namespace === "http" || namespace === "stealth")) {
         attributes.status = status;
     }
     if (duration !== undefined) {
@@ -192,8 +188,7 @@ function wrapNamespace(namespace, target, trace) {
                             if (namespaceTarget &&
                                 typeof namespaceTarget === "object" &&
                                 "engine" in namespaceTarget &&
-                                typeof namespaceTarget.engine ===
-                                    "string") {
+                                typeof namespaceTarget.engine === "string") {
                                 attributes.engine = namespaceTarget.engine;
                             }
                             return attributes;
@@ -224,10 +219,52 @@ function wrapNamespace(namespace, target, trace) {
                 wrappedMethods.set(property, wrapped);
                 return wrapped;
             }
-            const wrapped = (...args) => recorder.runSpan(`${namespace}.${methodName}`, () => Reflect.apply(value, namespaceTarget, args), {
-                onSuccess: (result) => buildSpanAttributes(namespace, methodName, args, result),
-                onError: (error) => buildSpanAttributes(namespace, methodName, args, undefined, error),
-            });
+            const wrapped = (...args) => {
+                // Invoke first and decide by the RETURN VALUE. `runSpan` always
+                // returns a Promise, so unconditionally span-wrapping every member
+                // silently rewrote synchronous contracts: `ctx.state.namespace()`
+                // (a sync factory) came back as a Promise, and every method call on
+                // it threw a raw TypeError — surfaced in production as catchtable's
+                // deterministic CONFIRM_STATE_UNAVAILABLE on 2026-07-27 (and the
+                // 2026-07-22 reserve internal_error loop before it). Sync members
+                // keep their sync contract; only genuinely async operations are
+                // recorded as spans.
+                let result;
+                try {
+                    result = Reflect.apply(value, namespaceTarget, args);
+                }
+                catch (error) {
+                    // A promise-returning implementation may still throw
+                    // SYNCHRONOUSLY during pre-flight validation. Preserve the
+                    // synchronous throw contract, but keep recording the failure
+                    // span (the pre-fidelity wrapper captured these).
+                    recorder
+                        .runSpan(`${namespace}.${methodName}`, () => {
+                        throw error;
+                    }, {
+                        onError: (spanError) => buildSpanAttributes(namespace, methodName, args, undefined, spanError),
+                    })
+                        .catch(() => undefined);
+                    throw error;
+                }
+                if (!isThenable(result)) {
+                    // The state namespace factory returns the object whose METHODS
+                    // are the operations worth tracing — instrument that object so
+                    // `state.get`/`state.compareAndSet`/… spans exist (they never
+                    // could before: the factory's return value was destroyed).
+                    if (namespace === "state" &&
+                        methodName === "namespace" &&
+                        typeof result === "object" &&
+                        result !== null) {
+                        return wrapNamespace(namespace, result, trace);
+                    }
+                    return result;
+                }
+                return recorder.runSpan(`${namespace}.${methodName}`, () => result, {
+                    onSuccess: (spanResult) => buildSpanAttributes(namespace, methodName, args, spanResult),
+                    onError: (error) => buildSpanAttributes(namespace, methodName, args, undefined, error),
+                });
+            };
             wrappedMethods.set(property, wrapped);
             return wrapped;
         },

package/dist/runtime/keyring.js

@@ -1,4 +1,4 @@
-import { ConfigurationError, decodeMasterKey } from "./key-derivation";
+import { ConfigurationError, decodeMasterKey } from "./key-derivation.js";
 const DEFAULT_KEY_PREFIX = "APIFUSE__KEYRING__MASTER_KEY_V";
 const DEFAULT_ACCEPT_LIST_VAR = "APIFUSE__KEYRING__MASTER_KEY_ACCEPT_LIST";
 const DEFAULT_WRITER_VERSION_VAR = "APIFUSE__KEYRING__MASTER_KEY_WRITER_VERSION";

package/dist/runtime/namespace.js

@@ -1,5 +1,5 @@
 import { createHmac } from "node:crypto";
-import { deriveSubkey } from "./key-derivation";
+import { deriveSubkey } from "./key-derivation.js";
 const HMAC_HEX_LENGTH = 16;
 /**
  * @internal Trusted loaders only; not re-exported to provider-importable paths.

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,35 @@
+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";
+/** 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 type NodemavenSynthesisInput = {
+    policy: ProviderProxyPolicy;
+    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;
+};
+export type NodemavenSynthesis = {
+    url: string;
+    protocol: ProxyProtocol;
+    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,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;
+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() {
+    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-retry-policy.d.ts

@@ -0,0 +1,40 @@
+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[];
+    statusCodes: readonly number[];
+    errorCodes: readonly string[];
+};
+export declare const DEFAULT_PROXY_TRANSPORT_RETRY_METHODS: readonly ["GET", "HEAD", "OPTIONS"];
+export declare const DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES: readonly ["transport_network_error", "transport_timeout"];
+export declare const MAX_PROXY_TRANSPORT_RETRY_ATTEMPTS = 8;
+type RetryPolicyLabel = "HTTP" | "Stealth" | "Proxy transport";
+export declare function proxyTransportRetryErrorCode(error: unknown): string | undefined;
+export declare function proxyTransportRetryErrorStatus(error: unknown): number | undefined;
+export declare function createDefaultProxyTransportRetryOptions(options?: {
+    extraErrorCodes?: readonly string[];
+    label?: RetryPolicyLabel;
+}): NormalizedProxyTransportRetryOptions;
+export declare function normalizeProxyTransportRetryOptions(retry: RequestOptions["retry"], options?: {
+    extraErrorCodes?: readonly string[];
+    label?: RetryPolicyLabel;
+}): NormalizedProxyTransportRetryOptions | undefined;
+export declare function validateUnsafeProxyTransportRetryMethods(options: NormalizedProxyTransportRetryOptions, label?: RetryPolicyLabel): void;
+export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions): boolean;
+export declare function shouldRetryProxyTransportError(error: unknown, options: NormalizedProxyTransportRetryOptions): boolean;
+export declare function shouldRetryProxyTransportAttempt(input: {
+    error: unknown;
+    explicitRetry: boolean;
+    method: HttpMethod | string;
+    options: NormalizedProxyTransportRetryOptions | undefined;
+    proxyUsed: boolean;
+}): boolean;
+export declare function computeProxyTransportRetryDelayMs(options: NormalizedProxyTransportRetryOptions, attemptIndex: number, headers?: Record<string, string>): number;
+export declare function normalizeProxyAttemptIndex(value: number | undefined): number;
+export declare function computeProxyAttemptIndex(options: {
+    baseProxyAttempt?: number;
+    proxyAttemptOffset?: number;
+    retryAttemptOffset?: number;
+}): number;
+export {};