@apifuse/provider-sdk 2.2.0-beta.57 → 2.2.0-beta.59

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

@@ -1,5 +1,6 @@
 import { ProviderError, TransportError } from "../errors.js";
 import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types.js";
+import { isSensitiveKey } from "./request-options.js";
 export const DEFAULT_PROXY_TRANSPORT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
 export const DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES = [
     "transport_network_error",
@@ -250,10 +251,18 @@ export function validateUnsafeProxyTransportRetryMethods(options, label = "Proxy
         return;
     throw new ProviderError(`${label} retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
 }
-export function isProxyTransportRetryMethod(method, options) {
-    return options.methods
+export function isProxyTransportRetryMethod(method, options, request) {
+    const methodAllowed = options.methods
         .map((allowedMethod) => allowedMethod.toUpperCase())
         .includes(method.toUpperCase());
+    if (!methodAllowed || request === undefined)
+        return methodAllowed;
+    if (request.body !== undefined)
+        return false;
+    return !Object.keys(request.headers ?? {}).some((name) => {
+        const normalized = name.toLowerCase();
+        return normalized === "cookie" || normalized === "proxy-authorization" || isSensitiveKey(name);
+    });
 }
 export function shouldRetryProxyTransportError(error, options) {
     const code = retryErrorCode(error);

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

@@ -1,5 +1,6 @@
 import type { ProxyTelemetrySink } from "../config/loader.js";
 import type { ProxyTelemetryLogPayload } from "./proxy-telemetry.js";
+import type { ResolverTelemetryLogPayload } from "./resolver-telemetry.js";
 import type { Span, TraceContext } from "./trace.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 export type TelemetryKey = "proxy" | "resolver" | "http" | "stealth" | "native" | "browser" | "ocr" | "stt" | "cache" | "state" | "events";
@@ -21,17 +22,13 @@ export declare function tenantOpaqueKeys(value: string[]): TenantOpaqueKeys;
  * URLs, hostnames, free text, unknown values, and escape-hatch properties reduce to `never`.
  */
 export type GatewayIngestible<T> = 0 extends 1 & T ? never : T extends object ? keyof T extends never ? never : {
-    [K in keyof T]: 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [readonly (infer U)[]] ? 0 extends 1 & U ? never : unknown extends U ? never : [U] extends [
-        number | boolean | ClosedEnum<string> | GatewayIngestible<U>
-    ] ? T[K] : never : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [GatewayIngestible<NonNullable<T[K]>>] ? T[K] : never : never;
+    [K in keyof T]: 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [readonly (infer U)[]] ? 0 extends 1 & U ? never : unknown extends U ? never : [U] extends [number | boolean | ClosedEnum<string> | GatewayIngestible<U>] ? T[K] : never : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [GatewayIngestible<NonNullable<T[K]>>] ? T[K] : never : never;
 } : never;
 /** Compile-time projection for tenant-visible, identity-neutral metadata. */
 export type TenantNeutral<T> = 0 extends 1 & T ? never : T extends object ? {
-    [K in keyof T]: K extends `vendor${string}` | "provider" | "engine" | "model" | `${string}Host` ? never : 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [
-        string[] & {
-            readonly __tenantOpaqueCacheKeys: true;
-        }
-    ] ? K extends "keys" ? T[K] : never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [TenantNeutral<NonNullable<T[K]>>] ? T[K] : never : never;
+    [K in keyof T]: K extends `vendor${string}` | "provider" | "engine" | "model" | `${string}Host` ? never : 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [string[] & {
+        readonly __tenantOpaqueCacheKeys: true;
+    }] ? K extends "keys" ? T[K] : never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [TenantNeutral<NonNullable<T[K]>>] ? T[K] : never : never;
 } : never;
 export interface SpanIndex {
     readonly spans: readonly Span[];
@@ -46,7 +43,8 @@ export interface TelemetryContributor<Log extends object, Header extends object>
 }
 export type RequestTelemetryLogPayload = {
     proxy?: ProxyTelemetryLogPayload;
-} & Partial<Record<Exclude<TelemetryKey, "proxy">, object>>;
+    resolver?: ResolverTelemetryLogPayload;
+} & Partial<Record<Exclude<TelemetryKey, "proxy" | "resolver">, object>>;
 /**
  * Bounded structural defence in depth against casts and accidental free text.
  * Closed-enum brands are erased at runtime; the type-level guard is the contract,

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

@@ -1,6 +1,13 @@
+import type { ProviderChallengeKind } from "../types.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__HYPERSOLUTIONS__API_KEY = "APIFUSE__RESOLVER__HYPERSOLUTIONS__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;
+/**
+ * SBSD is solved on the provider's own admitted session, so the transport profile must be
+ * declared up front. Other kinds, including `akamai_sensor`, keep the profile optional.
+ */
+export declare function kindRequiresClientProfile(kind: ProviderChallengeKind): boolean;

package/dist/runtime/resolver-config.js

@@ -1,6 +1,14 @@
 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__HYPERSOLUTIONS__API_KEY = "APIFUSE__RESOLVER__HYPERSOLUTIONS__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;
+/**
+ * SBSD is solved on the provider's own admitted session, so the transport profile must be
+ * declared up front. Other kinds, including `akamai_sensor`, keep the profile optional.
+ */
+export function kindRequiresClientProfile(kind) {
+    return kind === "akamai_sbsd";
+}

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

@@ -1 +1,3 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, type ResolverSolutionSource, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, type ResolverSolutionSource, } from "./resolver.js";
+export { type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryIdentitySource, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "./resolver-telemetry.js";
+export type { ResolverPaidUsageContext, ResolverVendorUnavailableReason, } from "./resolver-vendors/types.js";

package/dist/runtime/resolver-public.js

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";

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

@@ -1,5 +1,13 @@
 import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
 import type { TraceRecorder } from "./trace.js";
+import type { ResolverTelemetrySink } from "./resolver-telemetry.js";
+type ResolverTelemetryBinding = (sink: ResolverTelemetrySink) => ResolverContext;
+/** Internal contract: reconstruct a chain with a new request sink, without mutating the host chain. */
+export declare function registerResolverTelemetryBinding(resolver: ResolverContext, bind: ResolverTelemetryBinding): void;
+/** Preserve reconstruction across SDK wrappers without capturing their current request sink. */
+export declare function inheritResolverTelemetryBinding(resolver: ResolverContext, wrapper: ResolverContext): void;
+/** SDK chains expose each vendor invocation; opaque host resolvers expose one custom invocation. */
+export declare function bindResolverTelemetry(resolver: ResolverContext, sink: ResolverTelemetrySink | undefined): ResolverContext;
 export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
 /**
  * Internal solve surface. The instrumentation layer threads its recorder as a
@@ -12,3 +20,4 @@ export type ResolverSolveWithRecorder = {
     solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
 };
 export declare function createUnsupportedResolverClient(reason?: string): ResolverContext;
+export {};

package/dist/runtime/resolver-shared.js

@@ -1,4 +1,61 @@
 import { ProviderError } from "../errors.js";
+const telemetryBindings = new WeakMap();
+/** Internal contract: reconstruct a chain with a new request sink, without mutating the host chain. */
+export function registerResolverTelemetryBinding(resolver, bind) {
+    telemetryBindings.set(resolver, bind);
+}
+/** Preserve reconstruction across SDK wrappers without capturing their current request sink. */
+export function inheritResolverTelemetryBinding(resolver, wrapper) {
+    const bind = telemetryBindings.get(resolver);
+    if (bind)
+        telemetryBindings.set(wrapper, bind);
+}
+/** SDK chains expose each vendor invocation; opaque host resolvers expose one custom invocation. */
+export function bindResolverTelemetry(resolver, sink) {
+    if (!sink)
+        return resolver;
+    const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
+    if (metadata)
+        return bindResolverTelemetry(metadata.target, sink);
+    const bind = telemetryBindings.get(resolver);
+    if (bind)
+        return bind(sink);
+    const wrapper = {
+        async solve(challenge, signal, recorder) {
+            const startedAt = Date.now();
+            let outcome = "error";
+            try {
+                const solution = await resolver.solve(challenge, signal, recorder);
+                outcome = "solved";
+                return solution;
+            }
+            catch (error) {
+                outcome = signal?.aborted
+                    ? "aborted"
+                    : error instanceof ProviderError && error.code === "RESOLVER_CHAIN_EXHAUSTED"
+                        ? "exhausted"
+                        : "error";
+                throw error;
+            }
+            finally {
+                const ms = Date.now() - startedAt;
+                sink.recordVendorAttempt({
+                    vendor: "custom",
+                    phase: outcome === "solved" ? "poll_result" : "create_task",
+                    outcome: outcome === "solved" ? "ok" : "error",
+                    ms,
+                });
+                sink.recordOutcome({ outcome, solveMs: ms, challengeKind: challenge.kind });
+            }
+        },
+    };
+    // Rebinding this wrapper returns to the original host, never to its previous sink.
+    registerResolverTelemetryBinding(wrapper, createOpaqueResolverTelemetryBinding(resolver));
+    return wrapper;
+}
+function createOpaqueResolverTelemetryBinding(resolver) {
+    return (sink) => bindResolverTelemetry(resolver, sink);
+}
 export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for("@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata");
 export function createUnsupportedResolverClient(reason) {
     return {

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

@@ -0,0 +1,134 @@
+import type { ProviderChallengeKind, ProviderResolverVendor } from "../types.js";
+import { type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
+import type { ResolverVendorUnavailableReason } from "./resolver-vendors/types.js";
+/**
+ * Result of the resolver call. `solved` means the adapter returned a solution;
+ * for SBSD this means payload acceptance, even when `verified` is false.
+ * It does not assert that a later protected request succeeded. Stealth reports
+ * that verification separately through the refetch status and challenge outcome.
+ */
+export type ResolverTelemetryOutcome = "solved" | "cached" | "exhausted" | "aborted" | "error";
+export type ResolverTelemetryCacheStatus = "hit" | "miss" | "disabled" | "not_cacheable";
+export type ResolverTelemetryIdentitySource = "declared" | "defaulted" | "none";
+export type ResolverTelemetryPhase = "create_task" | "poll_result" | "cleanup" | "measure_ip" | "fetch_script" | "generate_payload" | "post_payload";
+export type ResolverTelemetryAttemptOutcome = "ok" | "error";
+export type ResolverTelemetryErrorClass = ResolverVendorUnavailableReason | "aborted" | "unexpected";
+export type ResolverTelemetryCacheWriteReason = "no_expires" | "not_cacheable" | "error";
+export type ResolverIdentityTelemetryEvent = {
+    readonly source: ResolverTelemetryIdentitySource;
+    readonly failure?: ResolverVendorUnavailableReason;
+};
+export type ResolverCacheReadTelemetryEvent = {
+    readonly status: ResolverTelemetryCacheStatus;
+    readonly challengeKind: ProviderChallengeKind;
+};
+export type ResolverCacheWriteTelemetryEvent = {
+    readonly written: boolean;
+    readonly reason?: ResolverTelemetryCacheWriteReason;
+};
+export type ResolverVendorAttemptTelemetryEvent = {
+    readonly vendor: ProviderResolverVendor;
+    readonly phase: ResolverTelemetryPhase;
+    readonly outcome: ResolverTelemetryAttemptOutcome;
+    readonly ms: number;
+    readonly pollCount?: number;
+    readonly errorClass?: ResolverTelemetryErrorClass;
+    readonly vendorErrorCode?: string;
+    readonly vendorErrorDescription?: string;
+    /** Operator-only diagnostics; free text is redacted, detached and bounded by the collector. */
+    readonly diagnostics?: {
+        readonly cause?: {
+            readonly name: string;
+            readonly message: string;
+        };
+        readonly upstreamHost?: string;
+        readonly missingFields?: readonly string[];
+        readonly round?: number;
+        /** One-based position in the supporting vendor chain. */
+        readonly attemptIndex?: number;
+        /** Actual adapter phase, including phases outside the header's closed enum. */
+        readonly phase?: string;
+    };
+};
+export type ResolverFailoverTelemetryEvent = {
+    readonly from: ProviderResolverVendor;
+    readonly to: ProviderResolverVendor;
+    readonly reason: ResolverVendorUnavailableReason;
+};
+export type ResolverOutcomeTelemetryEvent = {
+    readonly outcome: ResolverTelemetryOutcome;
+    readonly solveMs: number;
+    readonly challengeKind: ProviderChallengeKind;
+};
+export interface ResolverTelemetrySink {
+    recordIdentity(event: ResolverIdentityTelemetryEvent): void;
+    recordCacheRead(event: ResolverCacheReadTelemetryEvent): void;
+    recordCacheWrite(event: ResolverCacheWriteTelemetryEvent): void;
+    recordVendorAttempt(event: ResolverVendorAttemptTelemetryEvent): void;
+    recordFailover(event: ResolverFailoverTelemetryEvent): void;
+    recordOutcome(event: ResolverOutcomeTelemetryEvent): void;
+}
+export type ResolverAttemptSample = {
+    v: ProviderResolverVendor;
+    p: ResolverTelemetryPhase;
+    o: ResolverTelemetryAttemptOutcome;
+    ms: number;
+    c?: string;
+    e?: ResolverTelemetryErrorClass;
+    diagnostics?: ResolverVendorAttemptTelemetryEvent["diagnostics"];
+};
+export type ResolverTelemetryLogPayload = {
+    /** Adapter result; `solved` includes unverified payload acceptance. Read the protected refetch status/challenge outcome for verification. */
+    outcome?: ResolverTelemetryOutcome;
+    challengeKind?: ProviderChallengeKind;
+    cacheStatus?: ResolverTelemetryCacheStatus;
+    cacheWrite?: {
+        written: boolean;
+        reason?: ResolverTelemetryCacheWriteReason;
+    };
+    identitySource?: ResolverTelemetryIdentitySource;
+    identityFailure?: ResolverVendorUnavailableReason;
+    solveMs?: number;
+    attempts: number;
+    failovers: number;
+    vendorChain: ProviderResolverVendor[];
+    vendorUsed?: ProviderResolverVendor;
+    pollCount: number;
+    attemptSamples?: ResolverAttemptSample[];
+    attemptSamplesDropped?: number;
+    lastVendorErrorDescription?: string;
+};
+export type ResolverTelemetryHeaderPayload = {
+    /** Same adapter-result semantics as the log outcome; `solved` does not imply protected-refetch success. */
+    outcome?: ClosedEnum<ResolverTelemetryOutcome>;
+    cacheStatus?: ClosedEnum<ResolverTelemetryCacheStatus>;
+    solveMs?: number;
+    attempts: number;
+    failovers: number;
+    vendorUsed?: ClosedEnum<ProviderResolverVendor>;
+    vendorChain: ClosedEnum<ProviderResolverVendor>[];
+    pollCount: number;
+    identitySource?: ClosedEnum<ResolverTelemetryIdentitySource>;
+    attemptSamples?: {
+        v: ClosedEnum<ProviderResolverVendor>;
+        p: ClosedEnum<ResolverTelemetryPhase>;
+        o: ClosedEnum<ResolverTelemetryAttemptOutcome>;
+        ms: number;
+        c?: ClosedEnum<string>;
+    }[];
+};
+export declare class ResolverTelemetryCollector implements ResolverTelemetrySink, TelemetryContributor<ResolverTelemetryLogPayload, ResolverTelemetryHeaderPayload> {
+    #private;
+    readonly key: "resolver";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    recordIdentity(event: ResolverIdentityTelemetryEvent): void;
+    recordCacheRead(event: ResolverCacheReadTelemetryEvent): void;
+    recordCacheWrite(event: ResolverCacheWriteTelemetryEvent): void;
+    recordVendorAttempt(event: ResolverVendorAttemptTelemetryEvent): void;
+    recordFailover(_event: ResolverFailoverTelemetryEvent): void;
+    recordOutcome(event: ResolverOutcomeTelemetryEvent): void;
+    toLogPayload(): ResolverTelemetryLogPayload | undefined;
+    toHeaderPayload(log: ResolverTelemetryLogPayload): ResolverTelemetryHeaderPayload;
+}

package/dist/runtime/resolver-telemetry.js

@@ -0,0 +1,204 @@
+import { Buffer } from "node:buffer";
+import { closedEnum } from "./request-telemetry.js";
+const MAX_RESOLVER_ATTEMPT_SAMPLES = 24;
+const MAX_RESOLVER_VENDOR_CHAIN = 64;
+const MAX_DIAGNOSTIC_TEXT = 300;
+const MAX_MISSING_FIELDS = 24;
+const HEADER_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+function boundedInteger(value) {
+    return Math.max(0, Math.floor(Number.isFinite(value) ? value : 0));
+}
+function boundedText(value, redact) {
+    let result = value;
+    try {
+        result = redact?.(value) ?? value;
+    }
+    catch {
+        return "[REDACTION_FAILED]";
+    }
+    // Copy code units through an independent UTF-16 buffer. A sliced string can
+    // otherwise keep a multi-megabyte vendor response alive in both JSC and V8.
+    // Preserve lone surrogates deliberately, including a pair split at the limit.
+    const length = Math.min(result.length, MAX_DIAGNOSTIC_TEXT);
+    const units = Buffer.alloc(length * 2);
+    for (let index = 0; index < length; index += 1) {
+        units.writeUInt16LE(result.charCodeAt(index), index * 2);
+    }
+    return units.toString("utf16le");
+}
+function boundedDiagnostics(diagnostics, redact) {
+    return {
+        ...(diagnostics.cause
+            ? {
+                cause: {
+                    name: boundedText(diagnostics.cause.name, redact),
+                    message: boundedText(diagnostics.cause.message, redact),
+                },
+            }
+            : {}),
+        ...(diagnostics.upstreamHost
+            ? { upstreamHost: boundedText(diagnostics.upstreamHost, redact) }
+            : {}),
+        ...(diagnostics.missingFields
+            ? {
+                missingFields: diagnostics.missingFields
+                    .slice(0, MAX_MISSING_FIELDS)
+                    .map((field) => boundedText(field, redact)),
+            }
+            : {}),
+        ...(diagnostics.round === undefined ? {} : { round: boundedInteger(diagnostics.round) }),
+        ...(diagnostics.attemptIndex === undefined
+            ? {}
+            : { attemptIndex: boundedInteger(diagnostics.attemptIndex) }),
+        ...(diagnostics.phase ? { phase: boundedText(diagnostics.phase, redact) } : {}),
+    };
+}
+export class ResolverTelemetryCollector {
+    key = "resolver";
+    #redact;
+    #identity;
+    #cacheRead;
+    #cacheWrite;
+    #outcome;
+    #attempts = 0;
+    #failovers = 0;
+    #pollCount = 0;
+    #vendorChain = [];
+    #vendorUsed;
+    #attemptSamples = [];
+    #attemptSamplesDropped = 0;
+    #lastVendorErrorDescription;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    recordIdentity(event) {
+        this.#identity = { ...event };
+    }
+    recordCacheRead(event) {
+        this.#cacheRead = { ...event };
+    }
+    recordCacheWrite(event) {
+        this.#cacheWrite = { ...event };
+    }
+    recordVendorAttempt(event) {
+        const ms = boundedInteger(event.ms);
+        const pollCount = event.pollCount === undefined ? 0 : boundedInteger(event.pollCount);
+        this.#pollCount += pollCount;
+        if (event.phase !== "cleanup") {
+            this.#attempts += 1;
+            if (this.#vendorChain.length < MAX_RESOLVER_VENDOR_CHAIN &&
+                this.#vendorChain.at(-1) !== event.vendor) {
+                this.#vendorChain.push(event.vendor);
+            }
+            if (event.outcome === "ok")
+                this.#vendorUsed = event.vendor;
+        }
+        if (this.#attemptSamples.length < MAX_RESOLVER_ATTEMPT_SAMPLES) {
+            this.#attemptSamples.push({
+                v: event.vendor,
+                p: event.phase,
+                o: event.outcome,
+                ms,
+                ...(event.vendorErrorCode ? { c: boundedText(event.vendorErrorCode, this.#redact) } : {}),
+                ...(event.errorClass ? { e: event.errorClass } : {}),
+                ...(event.diagnostics
+                    ? { diagnostics: boundedDiagnostics(event.diagnostics, this.#redact) }
+                    : {}),
+            });
+        }
+        else {
+            this.#attemptSamplesDropped += 1;
+        }
+        if (event.vendorErrorDescription) {
+            this.#lastVendorErrorDescription = boundedText(event.vendorErrorDescription, this.#redact);
+        }
+    }
+    recordFailover(_event) {
+        this.#failovers += 1;
+    }
+    recordOutcome(event) {
+        this.#outcome = { ...event, solveMs: boundedInteger(event.solveMs) };
+    }
+    toLogPayload() {
+        if (!this.#identity &&
+            !this.#cacheRead &&
+            !this.#cacheWrite &&
+            !this.#outcome &&
+            this.#attempts === 0 &&
+            this.#attemptSamples.length === 0 &&
+            this.#failovers === 0) {
+            return undefined;
+        }
+        return {
+            ...(this.#outcome
+                ? {
+                    outcome: this.#outcome.outcome,
+                    challengeKind: this.#outcome.challengeKind,
+                    solveMs: this.#outcome.solveMs,
+                }
+                : this.#cacheRead
+                    ? { challengeKind: this.#cacheRead.challengeKind }
+                    : {}),
+            ...(this.#cacheRead ? { cacheStatus: this.#cacheRead.status } : {}),
+            ...(this.#cacheWrite ? { cacheWrite: { ...this.#cacheWrite } } : {}),
+            ...(this.#identity
+                ? {
+                    identitySource: this.#identity.source,
+                    ...(this.#identity.failure ? { identityFailure: this.#identity.failure } : {}),
+                }
+                : {}),
+            attempts: this.#attempts,
+            failovers: this.#failovers,
+            vendorChain: [...this.#vendorChain],
+            ...(this.#vendorUsed ? { vendorUsed: this.#vendorUsed } : {}),
+            pollCount: this.#pollCount,
+            ...(this.#attemptSamples.length > 0
+                ? {
+                    attemptSamples: this.#attemptSamples.map((sample) => ({
+                        ...sample,
+                        ...(sample.diagnostics
+                            ? {
+                                diagnostics: {
+                                    ...sample.diagnostics,
+                                    ...(sample.diagnostics.cause
+                                        ? { cause: { ...sample.diagnostics.cause } }
+                                        : {}),
+                                    ...(sample.diagnostics.missingFields
+                                        ? { missingFields: [...sample.diagnostics.missingFields] }
+                                        : {}),
+                                },
+                            }
+                            : {}),
+                    })),
+                }
+                : {}),
+            ...(this.#attemptSamplesDropped > 0
+                ? { attemptSamplesDropped: this.#attemptSamplesDropped }
+                : {}),
+            ...(this.#lastVendorErrorDescription
+                ? { lastVendorErrorDescription: this.#lastVendorErrorDescription }
+                : {}),
+        };
+    }
+    toHeaderPayload(log) {
+        const attemptSamples = log.attemptSamples?.map((sample) => ({
+            v: closedEnum(sample.v),
+            p: closedEnum(sample.p),
+            o: closedEnum(sample.o),
+            ms: sample.ms,
+            ...(sample.c && HEADER_TOKEN.test(sample.c) ? { c: closedEnum(sample.c) } : {}),
+        }));
+        return {
+            ...(log.outcome ? { outcome: closedEnum(log.outcome) } : {}),
+            ...(log.cacheStatus ? { cacheStatus: closedEnum(log.cacheStatus) } : {}),
+            ...(log.solveMs === undefined ? {} : { solveMs: log.solveMs }),
+            attempts: log.attempts,
+            failovers: log.failovers,
+            ...(log.vendorUsed ? { vendorUsed: closedEnum(log.vendorUsed) } : {}),
+            vendorChain: log.vendorChain.map((vendor) => closedEnum(vendor)),
+            pollCount: log.pollCount,
+            ...(log.identitySource ? { identitySource: closedEnum(log.identitySource) } : {}),
+            ...(attemptSamples && attemptSamples.length > 0 ? { attemptSamples } : {}),
+        };
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { ProviderChallengeKind, ProviderResolverVendor } from "../types.js";
+import type { ResolverPaidUsageContext } from "./resolver-vendors/types.js";
+import type { TraceRecorder } from "./trace.js";
+export declare const RESOLVER_PAID_USAGE_SPAN = "resolver.usage";
+export type ResolverPaidUsageOutcome = "success" | "vendor_error" | "timeout" | "abandoned";
+export type ResolverPaidUsageEndpoint = "capsolver:create_task" | "twocaptcha:create_task" | "hyper:ip" | "hyper:sbsd_create";
+/**
+ * Records one `resolver.usage` span around a paid vendor call. Callers validate credentials
+ * and transport first, so a span means a potentially billable request was attempted (a
+ * failed create the vendor may still bill is a span too). Without a trace recorder the call
+ * still runs; the lost billing record is warned once per warn sink.
+ */
+export declare function recordPaidResolverCreate<T>(options: {
+    readonly traceRecorder?: TraceRecorder;
+    readonly vendor: ProviderResolverVendor;
+    readonly kind: ProviderChallengeKind;
+    readonly endpoint: ResolverPaidUsageEndpoint;
+    /** 1-based round for endpoints called more than once per solve (Hyper payload rounds). */
+    readonly round?: number;
+    readonly signal: AbortSignal;
+    readonly usage?: ResolverPaidUsageContext;
+    readonly warn?: (message: string) => void;
+    readonly create: () => Promise<T>;
+}): Promise<T>;

package/dist/runtime/resolver-usage.js

@@ -0,0 +1,60 @@
+export const RESOLVER_PAID_USAGE_SPAN = "resolver.usage";
+/**
+ * How one call to the endpoint is counted. `metered` endpoints are the vendors' task or
+ * payload creation calls: the SDK counts one unit per call (the vendor ledger stays
+ * authoritative for refunds of failed tasks). Hyper's `/ip` reflector is authenticated
+ * but has no published price, so it is recorded with 0 units and `billing: "unconfirmed"`
+ * rather than invented as a paid unit; the span still proves the call was made.
+ */
+const ENDPOINT_BILLING = {
+    "capsolver:create_task": { billable_units: 1, billing: "metered" },
+    "twocaptcha:create_task": { billable_units: 1, billing: "metered" },
+    "hyper:ip": { billable_units: 0, billing: "unconfirmed" },
+    "hyper:sbsd_create": { billable_units: 1, billing: "metered" },
+};
+function errorOutcome(error, signal) {
+    const signalReason = signal.reason;
+    const errorName = error instanceof Error ? error.name : "";
+    const reasonName = signalReason instanceof Error ? signalReason.name : "";
+    const unavailableReason = error?.reason;
+    if (unavailableReason === "timeout" ||
+        /timeout/iu.test(errorName) ||
+        /timeout/iu.test(reasonName)) {
+        return "timeout";
+    }
+    if (signal.aborted)
+        return "abandoned";
+    return "vendor_error";
+}
+const warnedSinks = new WeakSet();
+/**
+ * Records one `resolver.usage` span around a paid vendor call. Callers validate credentials
+ * and transport first, so a span means a potentially billable request was attempted (a
+ * failed create the vendor may still bill is a span too). Without a trace recorder the call
+ * still runs; the lost billing record is warned once per warn sink.
+ */
+export async function recordPaidResolverCreate(options) {
+    if (!options.traceRecorder) {
+        const warn = options.warn ?? console.warn;
+        if (!warnedSinks.has(warn)) {
+            warnedSinks.add(warn);
+            warn(`[provider-sdk] Paid resolver call ${options.endpoint} ran without a trace recorder; its resolver.usage record is lost (reported once).`);
+        }
+        return options.create();
+    }
+    const baseAttributes = {
+        vendor: options.vendor,
+        challenge_kind: options.kind,
+        endpoint: options.endpoint,
+        ...ENDPOINT_BILLING[options.endpoint],
+        // Only the resolver chain knows the vendor's position; a direct adapter call has none.
+        ...(options.usage ? { vendor_index: options.usage.vendorIndex } : {}),
+        ...(options.round === undefined ? {} : { round: options.round }),
+        resolver_identity_scope: options.usage?.resolverIdentityScope,
+    };
+    return options.traceRecorder.runSpan(RESOLVER_PAID_USAGE_SPAN, options.create, {
+        attributes: baseAttributes,
+        onSuccess: () => ({ outcome: "success" }),
+        onError: (error) => ({ outcome: errorOutcome(error, options.signal) }),
+    });
+}

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

@@ -41,6 +41,11 @@ export declare const RESOLVER_CHALLENGE_BINDINGS: {
         readonly identityBinding: "identity_scoped";
         readonly directCacheable: false;
     };
+    readonly akamai_sbsd: {
+        readonly cacheable: false;
+        readonly identityBinding: "identity_scoped";
+        readonly directCacheable: false;
+    };
 };
 export declare function resolverChallengeIsCacheable(challenge: ProviderChallenge): boolean;
 export declare function resolverChallengeAllowsDirectCache(challenge: ProviderChallenge): boolean;

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

@@ -22,6 +22,11 @@ export const RESOLVER_CHALLENGE_BINDINGS = {
         identityBinding: "identity_scoped",
         directCacheable: false,
     },
+    akamai_sbsd: {
+        cacheable: false,
+        identityBinding: "identity_scoped",
+        directCacheable: false,
+    },
 };
 export function resolverChallengeIsCacheable(challenge) {
     return RESOLVER_CHALLENGE_BINDINGS[challenge.kind].cacheable;