@apifuse/provider-sdk 2.2.0-beta.27 → 2.2.0-beta.28

package/dist/runtime/instrumentation.js

@@ -1,7 +1,7 @@
 import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { parseHttpRequestInvocation, isSensitiveKey, redactSensitiveError, redactSensitiveText, redactUrlQueryParams, requestOptionsFromHttpInvocation, serializeRequestUrl, } from "./request-options.js";
 import { createTraceContext, getTraceRecorder, } from "./trace.js";
-import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver.js";
+import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
 const BROWSER_PAGE_METHODS = new Set(["goto", "fill", "click", "type", "waitForSelector"]);
 const DIAGNOSTIC_BASE_URL = "http://apifuse-instrumentation.invalid";
 function isThenable(value) {

package/dist/runtime/native-network-errors.d.ts

@@ -0,0 +1,33 @@
+import { TransportError } from "../errors.js";
+export type NativeNetworkErrorCode = "native_connection_aborted" | "native_connection_closed" | "native_connection_failed" | "native_connection_idle_timeout" | "native_connection_timeout" | "native_egress_authorization_failed" | "native_egress_grant_expired" | "native_egress_grant_invalid" | "native_egress_grant_limit_exceeded" | "native_egress_input_invalid" | "native_egress_not_declared" | "native_egress_policy_invalid" | "native_dynamic_egress_unsupported" | "native_proxy_expired" | "native_proxy_invalid";
+export declare class NativeNetworkError extends TransportError {
+    constructor(message: string, code: NativeNetworkErrorCode, cause?: Error);
+    get code(): NativeNetworkErrorCode;
+}
+export declare function safeDiagnosticEgressHost(value: unknown): string;
+export declare class NativeProxyExpiredError extends NativeNetworkError {
+    readonly expiresAt: string;
+    constructor(expiresAt: string);
+}
+/** Raised before transport setup when a native destination is not authorized. */
+export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
+    readonly port: number;
+    readonly tls: "required" | "disabled";
+    readonly host: string;
+    constructor(host: string, port: number, tls: "required" | "disabled");
+}
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export declare class NativeEgressGrantExpiredError extends NativeNetworkError {
+    readonly port: number;
+    readonly tls: "required" | "disabled";
+    readonly expiresAt: string;
+    readonly host: string;
+    constructor(host: string, port: number, tls: "required" | "disabled", expiresAt: string);
+}
+/** Raised when an established connection exceeds its opt-in read-idle window. */
+export declare class NativeIdleTimeoutError extends NativeNetworkError {
+    constructor();
+}

package/dist/runtime/native-network-errors.js

@@ -0,0 +1,69 @@
+import { TransportError } from "../errors.js";
+import { canonicalizeEgressHost } from "../native-address.js";
+export class NativeNetworkError extends TransportError {
+    constructor(message, code, cause) {
+        const isEgressPolicyFailure = code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
+        super(message, {
+            code,
+            status: 0,
+            ...(cause ? { cause } : {}),
+            ...(isEgressPolicyFailure ? { category: "provider_error", retryable: false } : {}),
+        });
+        this.name = "NativeNetworkError";
+    }
+    get code() {
+        return super.code;
+    }
+}
+export function safeDiagnosticEgressHost(value) {
+    const canonical = canonicalizeEgressHost(value);
+    return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
+export class NativeProxyExpiredError extends NativeNetworkError {
+    expiresAt;
+    constructor(expiresAt) {
+        super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
+        this.expiresAt = expiresAt;
+        this.name = "NativeProxyExpiredError";
+    }
+}
+/** Raised before transport setup when a native destination is not authorized. */
+export class NativeEgressNotDeclaredError extends NativeNetworkError {
+    port;
+    tls;
+    host;
+    constructor(host, port, tls) {
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`, "native_egress_not_declared");
+        this.port = port;
+        this.tls = tls;
+        this.host = diagnosticHost;
+        this.name = "NativeEgressNotDeclaredError";
+    }
+}
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export class NativeEgressGrantExpiredError extends NativeNetworkError {
+    port;
+    tls;
+    expiresAt;
+    host;
+    constructor(host, port, tls, expiresAt) {
+        const diagnosticHost = safeDiagnosticEgressHost(host);
+        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`, "native_egress_grant_expired");
+        this.port = port;
+        this.tls = tls;
+        this.expiresAt = expiresAt;
+        this.host = diagnosticHost;
+        this.name = "NativeEgressGrantExpiredError";
+    }
+}
+/** Raised when an established connection exceeds its opt-in read-idle window. */
+export class NativeIdleTimeoutError extends NativeNetworkError {
+    constructor() {
+        super("Native network socket timed out while reading.", "native_connection_idle_timeout");
+        this.name = "NativeIdleTimeoutError";
+    }
+}

package/dist/runtime/native-network.d.ts

@@ -1,40 +1,10 @@
 import { Socket } from "node:net";
 import { type TLSSocket } from "node:tls";
 import { type ProxyProtocol } from "../config/loader.js";
-import { TransportError } from "../errors.js";
 import { type DynamicEgressRuleSnapshot } from "../native-egress-policy.js";
 import type { NativeNetworkClient, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider, EnvContext } from "../types.js";
-export type NativeNetworkErrorCode = "native_connection_aborted" | "native_connection_closed" | "native_connection_failed" | "native_connection_idle_timeout" | "native_connection_timeout" | "native_egress_authorization_failed" | "native_egress_grant_expired" | "native_egress_grant_invalid" | "native_egress_grant_limit_exceeded" | "native_egress_input_invalid" | "native_egress_not_declared" | "native_egress_policy_invalid" | "native_dynamic_egress_unsupported" | "native_proxy_expired" | "native_proxy_invalid";
-export declare class NativeNetworkError extends TransportError {
-    constructor(message: string, code: NativeNetworkErrorCode, cause?: Error);
-    get code(): NativeNetworkErrorCode;
-}
-export declare class NativeProxyExpiredError extends NativeNetworkError {
-    readonly expiresAt: string;
-    constructor(expiresAt: string);
-}
-/** Raised before transport setup when a native destination is not authorized. */
-export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
-    readonly port: number;
-    readonly tls: "required" | "disabled";
-    readonly host: string;
-    constructor(host: string, port: number, tls: "required" | "disabled");
-}
-/**
- * Raised when the destination was authorized by a grant whose TTL elapsed and
- * its expiry remains in the client's bounded recent-expiry evidence window.
- */
-export declare class NativeEgressGrantExpiredError extends NativeNetworkError {
-    readonly port: number;
-    readonly tls: "required" | "disabled";
-    readonly expiresAt: string;
-    readonly host: string;
-    constructor(host: string, port: number, tls: "required" | "disabled", expiresAt: string);
-}
-/** Raised when an established connection exceeds its opt-in read-idle window. */
-export declare class NativeIdleTimeoutError extends NativeNetworkError {
-    constructor();
-}
+export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./native-network-errors.js";
+export type { NativeNetworkErrorCode } from "./native-network-errors.js";
 export type NativeGatewayProxy = NativeProxyEgressInfo & {
     readonly url: string;
 };
@@ -124,4 +94,3 @@ export declare function createNativeEgressAuthorization(options: NativeNetworkCl
 };
 /** Create the SDK byte-stream runtime with provider-declared egress enforcement. */
 export declare function createNativeNetworkClient(options?: NativeNetworkClientOptions): NativeNetworkClient;
-export {};

package/dist/runtime/native-network.js

@@ -3,79 +3,13 @@ import { Socket } from "node:net";
 import { connect as connectTlsSocket } from "node:tls";
 import { SocksClient } from "socks";
 import { assertTunnelingScheme, ProxyResolutionError, SMARTPROXY_APP_KEY_ENV, VENDOR_DEFAULT_PROTOCOL, resolveWithVendor, } from "../config/loader.js";
-import { TransportError } from "../errors.js";
 import { NativeEgressPolicyValidationError, parseNativeEgressPolicy, } from "../native-egress-policy.js";
 import { canonicalizeEgressHost, classifyEgressHost, embeddedIpv4FromIpv6, ipv4InCidr, ipv6InCidr, parseIpv6, parseStrictIpv4, } from "../native-address.js";
 import { createEnvContext } from "./env.js";
+import { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, safeDiagnosticEgressHost, } from "./native-network-errors.js";
 import { NODEMAVEN_FILTER_ENV, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, nodemavenSessionWindow, synthesizeNodemavenProxy, } from "./proxy-nodemaven.js";
 import { redactSensitiveError } from "./request-options.js";
-export class NativeNetworkError extends TransportError {
-    constructor(message, code, cause) {
-        const isEgressPolicyFailure = code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
-        super(message, {
-            code,
-            status: 0,
-            ...(cause ? { cause } : {}),
-            ...(isEgressPolicyFailure ? { category: "provider_error", retryable: false } : {}),
-        });
-        this.name = "NativeNetworkError";
-    }
-    get code() {
-        return super.code;
-    }
-}
-function safeDiagnosticEgressHost(value) {
-    const canonical = canonicalizeEgressHost(value);
-    return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
-}
-export class NativeProxyExpiredError extends NativeNetworkError {
-    expiresAt;
-    constructor(expiresAt) {
-        super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
-        this.expiresAt = expiresAt;
-        this.name = "NativeProxyExpiredError";
-    }
-}
-/** Raised before transport setup when a native destination is not authorized. */
-export class NativeEgressNotDeclaredError extends NativeNetworkError {
-    port;
-    tls;
-    host;
-    constructor(host, port, tls) {
-        const diagnosticHost = safeDiagnosticEgressHost(host);
-        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`, "native_egress_not_declared");
-        this.port = port;
-        this.tls = tls;
-        this.host = diagnosticHost;
-        this.name = "NativeEgressNotDeclaredError";
-    }
-}
-/**
- * Raised when the destination was authorized by a grant whose TTL elapsed and
- * its expiry remains in the client's bounded recent-expiry evidence window.
- */
-export class NativeEgressGrantExpiredError extends NativeNetworkError {
-    port;
-    tls;
-    expiresAt;
-    host;
-    constructor(host, port, tls, expiresAt) {
-        const diagnosticHost = safeDiagnosticEgressHost(host);
-        super(`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`, "native_egress_grant_expired");
-        this.port = port;
-        this.tls = tls;
-        this.expiresAt = expiresAt;
-        this.host = diagnosticHost;
-        this.name = "NativeEgressGrantExpiredError";
-    }
-}
-/** Raised when an established connection exceeds its opt-in read-idle window. */
-export class NativeIdleTimeoutError extends NativeNetworkError {
-    constructor() {
-        super("Native network socket timed out while reading.", "native_connection_idle_timeout");
-        this.name = "NativeIdleTimeoutError";
-    }
-}
+export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./native-network-errors.js";
 const VENDOR_CREDENTIAL_NAMES = {
     smartproxy: [SMARTPROXY_APP_KEY_ENV],
     nodemaven: [NODEMAVEN_USERNAME_ENV, NODEMAVEN_PASSWORD_ENV],

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,

package/dist/runtime/resolver-config.d.ts

@@ -0,0 +1,6 @@
+export declare const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
+export declare const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
+export declare const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
+export declare const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
+export declare const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
+export declare const DEFAULT_RESOLVER_TIMEOUT_MS = 180000;

package/dist/runtime/resolver-config.js

@@ -0,0 +1,6 @@
+export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
+export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
+export const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
+export const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
+export const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
+export const DEFAULT_RESOLVER_TIMEOUT_MS = 180_000;

package/dist/runtime/resolver-shared.d.ts

@@ -0,0 +1,3 @@
+import type { ResolverContext } from "../types.js";
+export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
+export declare function createUnsupportedResolverClient(reason?: string): ResolverContext;

package/dist/runtime/resolver-shared.js

@@ -0,0 +1,12 @@
+import { ProviderError } from "../errors.js";
+export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata");
+export function createUnsupportedResolverClient(reason) {
+    return {
+        async solve() {
+            throw new ProviderError(reason ?? "Resolver runtime is not configured", {
+                code: "RESOLVER_UNAVAILABLE",
+                fix: "Declare resolver on the provider definition and configure vendor credentials.",
+            });
+        },
+    };
+}

package/dist/runtime/resolver-vendors/twocaptcha.d.ts

@@ -1,4 +1,5 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
 import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
 type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
 export interface TwoCaptchaResolverVendorOptions {
@@ -15,7 +16,7 @@ export interface TwoCaptchaResolverVendorOptions {
 }
 export interface TwoCaptchaResolverVendorAdapter extends ResolverVendorAdapter {
     readonly id: "2captcha";
-    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal): Promise<Extract<ChallengeSolution, {
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<Extract<ChallengeSolution, {
         readonly form: "token";
     }>>;
 }

package/dist/runtime/resolver-vendors/twocaptcha.js

@@ -147,6 +147,24 @@ function tokenFrom(payload) {
 function endpoint(baseUrl, path) {
     return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
 }
+function spanErrorAttributes(error, phase) {
+    if (error instanceof ResolverVendorUnavailableError) {
+        return {
+            unavailability_reason: error.reason,
+            transport_phase: error.phase,
+        };
+    }
+    // The solve budget raises TwoCaptchaSolveTimeoutError inside the spanned closure and
+    // the outer catch converts it only after the span has been finalized, so the span has
+    // to recognize it here or slow solves lose exactly the attribution these spans add.
+    if (error instanceof TwoCaptchaSolveTimeoutError) {
+        return {
+            unavailability_reason: "timeout",
+            transport_phase: phase,
+        };
+    }
+    return undefined;
+}
 export function createTwoCaptchaResolverVendorAdapter(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     const baseUrl = options.baseUrl ?? DEFAULT_TWOCAPTCHA_BASE_URL;
@@ -159,7 +177,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
         supports(kind) {
             return resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, kind);
         },
-        async solve(challenge, identity, callerSignal) {
+        async solve(challenge, identity, callerSignal, traceRecorder) {
             const apiKey = options.apiKey?.trim();
             if (!apiKey) {
                 throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_credentials", {
@@ -192,50 +210,69 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
             const startedAt = now();
             let phase = "create_task";
             try {
-                const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), {
-                    clientKey: apiKey,
-                    task: {
-                        type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
-                        websiteURL: challenge.pageUrl,
-                        websiteKey: challenge.siteKey,
-                        isInvisible: false,
-                        ...(identity ? { userAgent: identity.userAgent } : {}),
-                        ...(proxy ?? {}),
-                    },
-                }, solveController.signal, phase);
-                const taskId = taskIdFrom(createResult.payload);
-                if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
-                    throw unavailableForPayload(createResult.payload, phase);
-                }
-                phase = "poll_result";
-                while (true) {
-                    callerSignal.throwIfAborted();
-                    const remainingMs = timeoutMs - (now() - startedAt);
-                    if (remainingMs <= 0)
-                        throw new TwoCaptchaSolveTimeoutError();
-                    await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
-                    callerSignal.throwIfAborted();
-                    if (now() - startedAt >= timeoutMs)
-                        throw new TwoCaptchaSolveTimeoutError();
-                    const pollResult = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase);
-                    if (!pollResult.ok || pollResult.payload.errorId !== 0) {
-                        throw unavailableForPayload(pollResult.payload, phase);
+                const createTask = async () => {
+                    const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), {
+                        clientKey: apiKey,
+                        task: {
+                            type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+                            websiteURL: challenge.pageUrl,
+                            websiteKey: challenge.siteKey,
+                            isInvisible: false,
+                            ...(identity ? { userAgent: identity.userAgent } : {}),
+                            ...(proxy ?? {}),
+                        },
+                    }, solveController.signal, phase);
+                    const taskId = taskIdFrom(createResult.payload);
+                    if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+                        throw unavailableForPayload(createResult.payload, phase);
                     }
-                    if (pollResult.payload.status === "processing")
-                        continue;
-                    if (pollResult.payload.status !== "ready") {
-                        throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-                            phase,
-                        });
-                    }
-                    const token = tokenFrom(pollResult.payload);
-                    if (!token?.trim()) {
-                        throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-                            phase,
-                        });
+                    return taskId;
+                };
+                const taskId = traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
+                        attributes: {
+                            vendor: TWOCAPTCHA_VENDOR_ID,
+                            challenge_kind: challenge.kind,
+                        },
+                        onError: (error) => spanErrorAttributes(error, "create_task"),
+                    })
+                    : await createTask();
+                phase = "poll_result";
+                const pollResult = async () => {
+                    while (true) {
+                        callerSignal.throwIfAborted();
+                        const remainingMs = timeoutMs - (now() - startedAt);
+                        if (remainingMs <= 0)
+                            throw new TwoCaptchaSolveTimeoutError();
+                        await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
+                        callerSignal.throwIfAborted();
+                        if (now() - startedAt >= timeoutMs)
+                            throw new TwoCaptchaSolveTimeoutError();
+                        const pollResult = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase);
+                        if (!pollResult.ok || pollResult.payload.errorId !== 0) {
+                            throw unavailableForPayload(pollResult.payload, phase);
+                        }
+                        if (pollResult.payload.status === "processing")
+                            continue;
+                        if (pollResult.payload.status !== "ready") {
+                            throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
+                        }
+                        const token = tokenFrom(pollResult.payload);
+                        if (!token?.trim()) {
+                            throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
+                        }
+                        return { form: "token", token };
                     }
-                    return { form: "token", token };
-                }
+                };
+                return traceRecorder
+                    ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+                        attributes: {
+                            vendor: TWOCAPTCHA_VENDOR_ID,
+                            challenge_kind: challenge.kind,
+                        },
+                        onError: (error) => spanErrorAttributes(error, "poll_result"),
+                    })
+                    : await pollResult();
             }
             catch (error) {
                 if (callerSignal.aborted)

package/dist/runtime/resolver-vendors/types.d.ts

@@ -55,7 +55,7 @@ export interface ResolverVendorAdapter {
     getIssuingIdentity?(solution: ChallengeSolution, requestedIdentity: ResolverIdentity | undefined, challenge: ProviderChallenge): ResolverIssuingIdentity | undefined;
     solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport): Promise<ChallengeSolution>;
 }
-export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
+export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
 export type ResolverChallengeVerdictReason = "human_puzzle";
 type ResolverErrorOptions = {
     /** Raw cause; adapters must not place bodies, cookies, headers, credentials, or proxy URLs here. */

package/dist/runtime/resolver.d.ts

@@ -1,12 +1,8 @@
-import type { ChallengeSolution, ProviderCache, ProviderChallenge, ProviderChallengeKind, ProviderResolverConfig, ProviderResolverVendor, ResolverContext } from "../types.js";
+import type { ChallengeSolution, ProviderCache, ProviderChallenge, ProviderChallengeKind, ProviderProxyMode, ProviderResolverConfig, ProviderResolverVendor, ResolverContext } from "../types.js";
 import { type ResolverIdentity, type ResolverVendorAdapter, type ResolverVendorTransport } from "./resolver-vendors/types.js";
 import type { TraceRecorder } from "./trace.js";
-export declare const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
-export declare const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
-export declare const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
-export declare const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
-export declare const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
-export declare const DEFAULT_RESOLVER_TIMEOUT_MS = 180000;
+export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
 type EnvLike = Record<string, string | undefined>;
 type ResolverChainClient = ResolverContext & {
     solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
@@ -14,6 +10,8 @@ type ResolverChainClient = ResolverContext & {
 export interface ResolverRuntimeOptions {
     readonly allowedHosts?: readonly string[];
     readonly cache?: ProviderCache;
+    /** Provider-declared proxy intent. The SDK never accepts a caller-built identity. */
+    readonly proxyMode?: ProviderProxyMode;
     /** Server-owned context/proxy scope used only for identity-bound cache entries. */
     readonly identityScope?: string;
     /** SDK-owned transport already bound to the resolved proxy lease and client profile. */
@@ -25,7 +23,6 @@ export interface ResolverRuntimeOptions {
         readonly identityScope?: string;
     }) => ResolverVendorTransport;
 }
-export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
 export type ResolverInstrumentationMetadata = {
     readonly target: ResolverContext;
     readonly traceRecorder: TraceRecorder;
@@ -41,14 +38,13 @@ export declare function createResolverClient(options: {
     readonly unavailableReason?: string;
     readonly cache?: ProviderCache;
     readonly identity?: ResolverIdentity;
+    readonly proxyMode?: ProviderProxyMode;
     readonly transport?: ResolverVendorTransport;
     readonly createTransport?: ResolverRuntimeOptions["createTransport"];
     readonly clientProfile?: string;
     readonly allowedHosts?: readonly string[];
 }): ResolverChainClient;
-export declare function createUnsupportedResolverClient(reason?: string): ResolverContext;
 export declare function bindResolverSignal(resolver: ResolverContext, defaultSignal: AbortSignal | undefined): ResolverContext;
 export declare function createResolverClientFromEnv(config: ProviderResolverConfig | undefined, env?: EnvLike, options?: ResolverRuntimeOptions): ResolverContext;
 /** Internal test seam; deliberately not re-exported from the package root. */
 export declare function createResolverClientFromEnvForTests(config: ProviderResolverConfig | undefined, env: EnvLike, options: ResolverRuntimeOptions, adapterFactories: Partial<Readonly<Record<ProviderResolverVendor, ResolverAdapterFactory>>>): ResolverContext;
-export {};

package/dist/runtime/resolver.js

@@ -5,12 +5,10 @@ import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.j
 import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
 import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolverVendorSupports, } from "./resolver-vendors/types.js";
-export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
-export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
-export const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
-export const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
-export const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
-export const DEFAULT_RESOLVER_TIMEOUT_MS = 180_000;
+import { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
+import { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
+export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
 const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
 const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
@@ -52,7 +50,6 @@ const SAFE_CAUSE_MESSAGE_WORDS = new Set([
     "while",
     "writing",
 ]);
-export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata");
 const resolverAdapterRegistry = {
     "2captcha"(configuration, timeoutMs, allowedHosts) {
         return createTwoCaptchaResolverVendorAdapter({
@@ -193,7 +190,9 @@ function sanitizeCauseMessage(message) {
         if (token === "[REDACTED]" || /^[a-z][a-z\d+.-]*:\/\/[^\s]+$/i.test(token))
             return token;
         const word = token.replace(/^[^a-z\d]+|[^a-z\d]+$/gi, "");
-        return word.length > 0 && word.length <= 32 && SAFE_CAUSE_MESSAGE_WORDS.has(word.toLowerCase())
+        return word.length > 0 &&
+            word.length <= 32 &&
+            SAFE_CAUSE_MESSAGE_WORDS.has(word.toLowerCase())
             ? token
             : "[REDACTED]";
     });
@@ -465,6 +464,16 @@ function createResolverChainClient(options) {
             if (supportingEntries.length === 0)
                 throwUnsupportedKind(challenge.kind);
             signal.throwIfAborted();
+            // A required proxy policy is checked before the cache. Solutions minted under a
+            // previous release are shared and long-lived, so consulting the cache first would
+            // keep reporting success without a proxy identity until every old entry expired.
+            const requiredProxyIdentityMissing = options.proxyMode === "required" && options.identity === undefined;
+            if (requiredProxyIdentityMissing) {
+                throwExhausted(supportingEntries.map((entry) => ({
+                    vendor: entry.id,
+                    reason: "missing_proxy_identity",
+                })));
+            }
             if (options.cache && resolverChallengeIsCacheable(challenge)) {
                 const cached = await findCachedSolution(options.cache, challenge, options.identity, options.identityScope);
                 if (cached)
@@ -544,6 +553,7 @@ export function createResolverClient(options) {
         unavailableReason: options.unavailableReason,
         cache: options.cache,
         identity: options.identity,
+        proxyMode: options.proxyMode,
         transport: options.transport,
         createTransport: options.createTransport,
         clientProfile: options.clientProfile,
@@ -570,16 +580,6 @@ function resolveVendorAvailability(vendor, env) {
         ? { vendor, available: true, configuration }
         : { vendor, available: false, reason: "missing_credentials" };
 }
-export function createUnsupportedResolverClient(reason) {
-    return {
-        async solve() {
-            throw new ProviderError(reason ?? "Resolver runtime is not configured", {
-                code: "RESOLVER_UNAVAILABLE",
-                fix: "Declare resolver on the provider definition and configure vendor credentials.",
-            });
-        },
-    };
-}
 export function bindResolverSignal(resolver, defaultSignal) {
     if (!defaultSignal)
         return resolver;
@@ -620,6 +620,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
             };
         }),
         cache: options.cache,
+        proxyMode: options.proxyMode,
         identityScope: options.identityScope,
         transport: options.transport,
         createTransport: options.createTransport,