@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.30

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,16 @@ function encodeBase64Url(value) {
 export class ProxyTelemetryCollector {
     #events = [];
     #attempts = [];
+    #failovers = [];
     recordProxyResolution(event) {
         this.#events.push({
-            provider: "smartproxy",
+            provider: event.provider,
+            ...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
+            ...(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 +46,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 +80,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 +90,17 @@ 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,
+            userAgentSource: event.userAgentSource ?? acc.userAgentSource,
             cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
             cacheHit: acc.cacheHit && event.cacheHit,
             resolutionMs: acc.resolutionMs + event.resolutionMs,
@@ -111,13 +119,13 @@ export class ProxyTelemetryCollector {
         const payload = {
             v: 1,
             proxy: {
-                provider: "smartproxy",
+                provider: serving.provider,
+                ...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
+                ...(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 +135,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 type { Redis } from "ioredis";
 export type ProviderRedisClient = Redis;
 export type ProviderRedisClientOptions = {
     readonly redisUrl: string;

package/dist/runtime/redis.js

@@ -1,6 +1,8 @@
-import Redis from "ioredis";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
 export function createProviderRedisClient(options) {
-    const redis = new Redis(options.redisUrl, {
+    const { Redis: RedisClient } = require("ioredis");
+    const redis = new RedisClient(options.redisUrl, {
         connectTimeout: options.timeoutMs,
         enableOfflineQueue: false,
         lazyConnect: true,
@@ -23,9 +25,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 {

package/dist/runtime/request-options.d.ts

@@ -1,3 +1,70 @@
-import type { RequestParams } from "../types";
+import type { HttpClient, RequestOptions, RequestParams } from "../types.js";
+export declare const REDACTED_QUERY_VALUE = "[REDACTED]";
+/** Internal heuristic shared by diagnostic and fixture structural redaction. */
+export declare function isSensitiveKey(key: string): boolean;
+declare const HTTP_REQUEST_METHOD_CONFIG: {
+    readonly request: {
+        readonly optionsIndex: 1;
+    };
+    readonly get: {
+        readonly optionsIndex: 1;
+    };
+    readonly post: {
+        readonly optionsIndex: 2;
+    };
+    readonly put: {
+        readonly optionsIndex: 2;
+    };
+    readonly delete: {
+        readonly optionsIndex: 1;
+    };
+    readonly stream: {
+        readonly optionsIndex: 1;
+    };
+    readonly sse: {
+        readonly optionsIndex: 1;
+    };
+};
+export type HttpRequestMethod = keyof typeof HTTP_REQUEST_METHOD_CONFIG;
+export type HttpRequestInvocation = {
+    [M in HttpRequestMethod]: {
+        method: M;
+        args: Parameters<HttpClient[M]>;
+    };
+}[HttpRequestMethod];
+export declare const HTTP_REQUEST_METHOD_NAMES: HttpRequestMethod[];
+export declare function isHttpRequestMethod(method: PropertyKey): method is HttpRequestMethod;
+export type SerializedRequestUrl = {
+    requestUrl: string;
+    redactedUrl: string;
+    sensitiveValues: readonly string[];
+};
+export declare function normalizeSensitiveParams(sensitiveParams?: Record<string, string>): Record<string, string> | undefined;
 export declare function appendQueryParams(url: string, params?: RequestParams): string;
+/** Redacts matching query keys without reserializing any other URL bytes. */
+export declare function redactUrlQueryParams(url: string, sensitiveParamNames: readonly string[]): {
+    redactedUrl: string;
+    sensitiveValues: readonly string[];
+};
+/**
+ * Serializes public and secret query parameters together while constructing a
+ * separate, structurally redacted URL for diagnostics and observability.
+ */
+export declare function serializeRequestUrl(url: string, params?: RequestParams, sensitiveParams?: Record<string, string>): SerializedRequestUrl;
+/** Scrubs raw and URL-encoded secret values from diagnostic text. */
+export declare function redactSensitiveText(text: string, sensitiveValues: readonly string[], requestUrl?: string, redactedUrl?: string): string;
+/**
+ * Redacts error text and recursively serializable diagnostic metadata.
+ * Mutable errors retain identity; readonly/frozen errors may be replaced, so
+ * callers must use the returned value.
+ */
+export declare function redactSensitiveError<T>(error: T, sensitiveValues: readonly string[], requestUrl?: string, redactedUrl?: string): T;
+/** Redacts failures that occur before a request URL can be fully serialized. */
+export declare function redactSensitiveRequestError<T>(error: T, url: string, sensitiveParams?: Record<string, string>): T;
+/** Validates an untyped proxy invocation before narrowing it to the HttpClient contract. */
+export declare function parseHttpRequestInvocation(method: PropertyKey, args: unknown[]): HttpRequestInvocation | undefined;
+/** Internal typed registry for the request-options position of HttpClient calls. */
+export declare function requestOptionsFromHttpInvocation(invocation: HttpRequestInvocation): RequestOptions | undefined;
+export declare function replaceRequestOptionsInHttpInvocation(invocation: HttpRequestInvocation, options: RequestOptions): void;
 export declare function normalizeHttpRequestBody(body: unknown): string | Buffer | undefined;
+export {};