@apifuse/provider-sdk 2.2.0-beta.58 → 2.2.0-beta.60

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;

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

@@ -111,7 +111,6 @@ async function runBoundedCleanup(cleanup, timeoutMs, challengeKind, operation, t
         onError(error) {
             return {
                 error_message: error instanceof Error ? error.message : String(error),
-                ...(error instanceof Error && error.stack ? { error_stack: error.stack } : {}),
             };
         },
     })

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

@@ -1,6 +1,6 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
-import { type ResolverIdentity, type ResolverVendorAdapter } from "./types.js";
+import { type ResolverIdentity, type ResolverPaidUsageContext, type ResolverVendorAdapter, type ResolverVendorTransport } from "./types.js";
 type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
 export interface CapsolverResolverVendorOptions {
     readonly apiKey?: string;
@@ -16,7 +16,7 @@ export interface CapsolverResolverVendorOptions {
 }
 export interface CapsolverResolverVendorAdapter extends ResolverVendorAdapter {
     readonly id: "capsolver";
-    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport, usage?: ResolverPaidUsageContext): Promise<ChallengeSolution>;
 }
 export declare function createCapsolverResolverVendorAdapter(options: CapsolverResolverVendorOptions): CapsolverResolverVendorAdapter;
 export {};

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

@@ -1,8 +1,9 @@
 import { getStealthProfile } from "../../stealth/profiles.js";
 import { redactSensitiveText } from "../request-options.js";
 import { DEFAULT_STEALTH_PROFILE } from "../stealth.js";
+import { recordPaidResolverCreate } from "../resolver-usage.js";
 import { assertResolverHostAllowed } from "./hosts.js";
-import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, resolverVendorSupports, } from "./types.js";
+import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, resolverVendorSupports, } from "./types.js";
 const CAPSOLVER_VENDOR_ID = "capsolver";
 const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
@@ -304,7 +305,7 @@ export function createCapsolverResolverVendorAdapter(options) {
         supports(kind) {
             return resolverVendorSupports(CAPSOLVER_VENDOR_ID, kind);
         },
-        async solve(challenge, identity, callerSignal, traceRecorder) {
+        async solve(challenge, identity, callerSignal, traceRecorder, _transport, usage) {
             const apiKey = options.apiKey?.trim();
             if (!apiKey) {
                 throw new ResolverVendorUnavailableError(CAPSOLVER_VENDOR_ID, "missing_credentials", {
@@ -416,12 +417,22 @@ export function createCapsolverResolverVendorAdapter(options) {
                                             : (() => {
                                                 throw new TypeError(`Capsolver resolver does not support ${challenge.kind}`);
                                             })();
-                    const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, solveController.signal, phase, sensitiveValues, parseCreateTaskResponse);
-                    const taskId = createResult.payload.taskId;
-                    if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
-                        throw unavailableForPayload(createResult.payload, phase, sensitiveValues);
-                    }
-                    return taskId;
+                    return await recordPaidResolverCreate({
+                        traceRecorder,
+                        vendor: CAPSOLVER_VENDOR_ID,
+                        kind: challenge.kind,
+                        endpoint: "capsolver:create_task",
+                        signal: solveController.signal,
+                        usage,
+                        create: async () => {
+                            const createResult = await postJson(fetchImpl, endpoint(baseUrl, "createTask"), { clientKey: apiKey, task }, solveController.signal, phase, sensitiveValues, parseCreateTaskResponse);
+                            const taskId = createResult.payload.taskId;
+                            if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+                                throw unavailableForPayload(createResult.payload, phase, sensitiveValues);
+                            }
+                            return taskId;
+                        },
+                    });
                 };
                 const taskId = traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
@@ -443,6 +454,7 @@ export function createCapsolverResolverVendorAdapter(options) {
                         callerSignal.throwIfAborted();
                         if (now() - startedAt >= timeoutMs)
                             throw new CapsolverSolveTimeoutError();
+                        recordResolverVendorPoll(traceRecorder);
                         const result = await postJson(fetchImpl, endpoint(baseUrl, "getTaskResult"), { clientKey: apiKey, taskId }, solveController.signal, phase, sensitiveValues, parsePollResultResponse);
                         if (!result.ok || result.payload.errorId !== 0) {
                             throw unavailableForPayload(result.payload, phase, sensitiveValues);
@@ -460,7 +472,7 @@ export function createCapsolverResolverVendorAdapter(options) {
                         }
                         const solutionValue = challenge.kind === "aws_waf"
                             ? result.payload.solution?.cookie
-                            : result.payload.solution?.token ?? result.payload.solution?.gRecaptchaResponse;
+                            : (result.payload.solution?.token ?? result.payload.solution?.gRecaptchaResponse);
                         if (challenge.kind === "cloudflare_interstitial") {
                             const cookies = result.payload.solution?.cookies;
                             const clearance = cookies?.cf_clearance ?? solutionValue;

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

@@ -0,0 +1,27 @@
+import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+import { type ResolverIdentity, type ResolverPaidUsageContext, type ResolverVendorAdapter, type ResolverVendorTransport } from "./types.js";
+/**
+ * Only the observed-IP reflector rides the bound transport: Hyper must see the
+ * egress address the upstream will see. The payload-generation POST carries no
+ * identity and goes direct, as in the measured zozotown source.
+ */
+declare const HYPER_TRANSPORT_HOSTS: readonly ["ip.hypersolutions.co"];
+export interface HypersolutionsResolverVendorOptions {
+    readonly apiKey?: string;
+    readonly timeoutMs?: number;
+    readonly allowedHosts: readonly string[];
+    /** Direct egress used only for the Hyper payload-generation POST. */
+    readonly fetchImpl?: typeof fetch;
+}
+export type AkamaiSbsdChallengeSolution = Extract<ChallengeSolution, {
+    readonly form: "cookie_state";
+}>;
+export interface HypersolutionsResolverVendorAdapter extends ResolverVendorAdapter {
+    readonly id: "hypersolutions";
+    readonly requiresTransport: true;
+    readonly transportAllowedHosts: typeof HYPER_TRANSPORT_HOSTS;
+    solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport, usage?: ResolverPaidUsageContext): Promise<AkamaiSbsdChallengeSolution>;
+}
+export declare function createHypersolutionsResolverVendorAdapter(options: HypersolutionsResolverVendorOptions): HypersolutionsResolverVendorAdapter;
+export {};