@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/request-telemetry.js

@@ -0,0 +1,229 @@
+import { PROVIDER_OBSERVABILITY_TAXONOMY_VERSION } from "../observability.js";
+export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+/** Brands a value from an SDK-declared closed string union without changing it. */
+export function closedEnum(value) {
+    return value;
+}
+/** Names the deliberate tenant cache-key exemption without changing its wire value. */
+export function tenantOpaqueKeys(value) {
+    return value;
+}
+const MAX_HEADER_BYTES = 4_096;
+const MAX_INGESTIBLE_ARRAY_LENGTH = 64;
+const MAX_INGESTIBLE_OBJECT_KEYS = 32;
+const MAX_INGESTIBLE_DEPTH = 4;
+const INGESTIBLE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+/** @internal */
+export const HEADER_PRIORITY = [
+    "proxy",
+    "resolver",
+    "native",
+    "http",
+    "stealth",
+    "browser",
+    "ocr",
+    "stt",
+    "cache",
+    "state",
+];
+const warnedInvalidKeys = new Set();
+function createSpanIndex(trace) {
+    const spans = trace.getSpans().slice();
+    const mutableByName = new Map();
+    for (const span of spans) {
+        const named = mutableByName.get(span.name);
+        if (named)
+            named.push(span);
+        else
+            mutableByName.set(span.name, [span]);
+    }
+    const byName = new Map(mutableByName);
+    return {
+        spans,
+        byName,
+        count(name) {
+            return byName.get(name)?.length ?? 0;
+        },
+        durationMs(name) {
+            return (byName.get(name) ?? []).reduce((total, span) => total + span.duration_ms, 0);
+        },
+    };
+}
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * 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,
+ * while this check only enforces safe token shapes and collection bounds.
+ */
+export function isGatewayIngestible(value) {
+    const ancestors = new Set();
+    const visit = (candidate, depth) => {
+        if (typeof candidate === "number")
+            return Number.isFinite(candidate);
+        if (typeof candidate === "boolean")
+            return true;
+        if (typeof candidate === "string")
+            return INGESTIBLE_TOKEN.test(candidate);
+        if (candidate === null || typeof candidate !== "object")
+            return false;
+        if (depth >= MAX_INGESTIBLE_DEPTH || ancestors.has(candidate))
+            return false;
+        if (Array.isArray(candidate)) {
+            if (candidate.length > MAX_INGESTIBLE_ARRAY_LENGTH)
+                return false;
+            ancestors.add(candidate);
+            const valid = candidate.every((item, index) => Object.hasOwn(candidate, index) && visit(item, depth + 1));
+            ancestors.delete(candidate);
+            return valid;
+        }
+        if (!isPlainRecord(candidate))
+            return false;
+        const keys = Object.keys(candidate);
+        if (keys.length > MAX_INGESTIBLE_OBJECT_KEYS)
+            return false;
+        ancestors.add(candidate);
+        const valid = keys.every((key) => visit(candidate[key], depth + 1));
+        ancestors.delete(candidate);
+        return valid;
+    };
+    try {
+        return visit(value, 0);
+    }
+    catch {
+        return false;
+    }
+}
+function encodeEnvelope(envelope) {
+    return Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url");
+}
+function warnInvalidSibling(key) {
+    if (warnedInvalidKeys.has(key))
+        return;
+    warnedInvalidKeys.add(key);
+    try {
+        console.warn(`[provider-sdk] Dropped invalid telemetry sibling "${key}"; contributors must return serializable log objects and bounded gateway-safe header values.`);
+    }
+    catch {
+        // A host-provided console must not let telemetry fail the request path.
+    }
+}
+function isProxySink(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    try {
+        return typeof Reflect.get(value, "recordProxyResolution") === "function";
+    }
+    catch {
+        return false;
+    }
+}
+/** One finalisation owner for every request-scoped telemetry contributor. */
+export class RequestTelemetry {
+    trace;
+    contributors;
+    #registered = {};
+    #exposed = {};
+    #proxy;
+    constructor(trace) {
+        this.trace = trace;
+        this.contributors = this.#exposed;
+    }
+    register(contributor) {
+        if (this.#registered[contributor.key]) {
+            throw new TypeError(`Telemetry contributor "${contributor.key}" is already registered.`);
+        }
+        const registered = {
+            key: contributor.key,
+            toLogPayload: (spans) => contributor.toLogPayload(spans),
+            toHeaderPayload: (log) => contributor.toHeaderPayload(log),
+        };
+        this.#registered[contributor.key] = registered;
+        this.#exposed[contributor.key] = contributor;
+        if (contributor.key === "proxy" && isProxySink(contributor))
+            this.#proxy = contributor;
+    }
+    get proxy() {
+        return this.#proxy;
+    }
+    toLogPayload() {
+        const spans = createSpanIndex(this.trace);
+        const payload = {};
+        for (const key of Object.keys(this.#registered)) {
+            const contributor = this.#registered[key];
+            if (!contributor)
+                continue;
+            try {
+                const sibling = contributor.toLogPayload(spans);
+                if (sibling === undefined)
+                    continue;
+                JSON.stringify(sibling);
+                payload[key] = sibling;
+            }
+            catch {
+                warnInvalidSibling(key);
+            }
+        }
+        return Object.keys(payload).length > 0 ? payload : undefined;
+    }
+    toHeaderValue() {
+        const spans = createSpanIndex(this.trace);
+        const siblings = {};
+        for (const key of HEADER_PRIORITY) {
+            const contributor = this.#registered[key];
+            if (!contributor)
+                continue;
+            try {
+                const log = contributor.toLogPayload(spans);
+                if (log === undefined)
+                    continue;
+                const projected = contributor.toHeaderPayload(log);
+                if (projected === undefined)
+                    continue;
+                if (!isGatewayIngestible(projected)) {
+                    warnInvalidSibling(key);
+                    continue;
+                }
+                const serialized = JSON.stringify(projected);
+                const decoded = JSON.parse(serialized);
+                if (!isGatewayIngestible(decoded) || !isPlainRecord(decoded)) {
+                    warnInvalidSibling(key);
+                    continue;
+                }
+                siblings[key] = decoded;
+            }
+            catch {
+                warnInvalidSibling(key);
+            }
+        }
+        if (Object.keys(siblings).length === 0)
+            return undefined;
+        // Gateway uses permissive json.Unmarshal (unknown keys are ignored) but
+        // requires v === 1. The observability taxonomy is additive and independent.
+        const envelope = {
+            v: 1,
+            taxonomy: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            ...siblings,
+        };
+        let encoded = encodeEnvelope(envelope);
+        if (encoded.length <= MAX_HEADER_BYTES)
+            return encoded;
+        for (let index = HEADER_PRIORITY.length - 1; index >= 0; index -= 1) {
+            const key = HEADER_PRIORITY[index];
+            if (!key || !(key in envelope))
+                continue;
+            delete envelope[key];
+            if (!HEADER_PRIORITY.some((candidate) => candidate in envelope))
+                return undefined;
+            envelope.truncated = true;
+            encoded = encodeEnvelope(envelope);
+            if (encoded.length <= MAX_HEADER_BYTES)
+                return encoded;
+        }
+        return undefined;
+    }
+}

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

@@ -0,0 +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

@@ -0,0 +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

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1 @@
+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-runtime-options.d.ts

@@ -0,0 +1,14 @@
+import type { ProviderCache, ProviderDefinition, ProviderProxyPolicy } from "../types.js";
+import type { ResolverRuntimeOptions } from "./resolver.js";
+import type { ResolverTelemetrySink } from "./resolver-telemetry.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
+/** Normalize the `proxy` declaration shorthand (`true`/`false`) into the policy object the resolver chain consumes. */
+export declare function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | undefined;
+/**
+ * One option set for every SDK-built resolver chain — the server's ctx.resolver and automatic
+ * SBSD solve, and the CLI helper contexts — so they share allowed hosts, cache, identity scope,
+ * proxy intent, and the telemetry sink. `identityScope` is server-owned; CLI contexts pass none.
+ */
+export declare function createResolverRuntimeOptions(provider: ProviderDefinition, cache: ProviderCache, identityScope: string | undefined, proxyPolicy: ProviderProxyPolicy | undefined, proxyClientOptions: Omit<NonNullable<ResolverRuntimeOptions["proxyIntent"]>, "mode" | "userAgent">, stealthProfile: {
+    readonly userAgent: string;
+} | undefined, telemetry: ResolverTelemetrySink, browserTelemetry?: BrowserTelemetrySink): ResolverRuntimeOptions;

package/dist/runtime/resolver-runtime-options.js

@@ -0,0 +1,33 @@
+/** Normalize the `proxy` declaration shorthand (`true`/`false`) into the policy object the resolver chain consumes. */
+export function resolveNativeProxyPolicy(provider) {
+    if (typeof provider.proxy === "object")
+        return provider.proxy;
+    if (provider.proxy === true)
+        return { mode: "optional" };
+    if (provider.proxy === false)
+        return { mode: "disabled" };
+    return undefined;
+}
+/**
+ * One option set for every SDK-built resolver chain — the server's ctx.resolver and automatic
+ * SBSD solve, and the CLI helper contexts — so they share allowed hosts, cache, identity scope,
+ * proxy intent, and the telemetry sink. `identityScope` is server-owned; CLI contexts pass none.
+ */
+export function createResolverRuntimeOptions(provider, cache, identityScope, proxyPolicy, proxyClientOptions, stealthProfile, telemetry, browserTelemetry) {
+    return {
+        allowedHosts: provider.allowedHosts,
+        cache,
+        telemetry,
+        browserTelemetry,
+        ...(identityScope === undefined ? {} : { identityScope }),
+        ...(proxyPolicy
+            ? {
+                proxyIntent: {
+                    mode: proxyPolicy.mode,
+                    ...proxyClientOptions,
+                    ...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
+                },
+            }
+            : {}),
+    };
+}

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

@@ -0,0 +1,24 @@
+import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
+import type { TraceRecorder } from "./trace.js";
+import type { ResolverTelemetrySink } from "./resolver-telemetry.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
+type ResolverTelemetryBinding = (sink: ResolverTelemetrySink, browserSink?: BrowserTelemetrySink) => 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, browserSink?: BrowserTelemetrySink): ResolverContext;
+export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
+/**
+ * Internal solve surface. The instrumentation layer threads its recorder as a
+ * third argument so vendor-level spans (`resolver.vendor.*`) attach to the
+ * active trace. Every wrapper that re-exposes `solve` must forward the extra
+ * arguments; a wrapper typed against the public two-argument `ResolverContext`
+ * silently drops the recorder and vendor spans vanish.
+ */
+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

@@ -0,0 +1,69 @@
+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, browserSink) {
+    if (!sink)
+        return resolver;
+    const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
+    if (metadata)
+        return bindResolverTelemetry(metadata.target, sink, browserSink);
+    const bind = telemetryBindings.get(resolver);
+    if (bind)
+        return bind(sink, browserSink);
+    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, browserSink) => bindResolverTelemetry(resolver, sink, browserSink);
+}
+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-span-attributes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Closed-enum span attributes emitted by the resolver, by attribute key. A value listed here is an
+ * SDK-declared literal, so fail-closed diagnostic redaction keeps it the way it keeps a typed
+ * number; any other value under the same key is still free text. Registered credentials are
+ * matched either way.
+ */
+export declare const RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES: {
+    readonly vendor: readonly ["browser", "capsolver", "capmonster", "2captcha", "hypersolutions", "custom"];
+    readonly challenge_kind: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor", "akamai_sbsd"];
+    readonly endpoint: readonly ["capsolver:create_task", "twocaptcha:create_task", "hyper:ip", "hyper:sbsd_create"];
+    readonly billing: readonly ["metered", "unconfirmed"];
+    readonly outcome: readonly ["success", "vendor_error", "timeout", "abandoned", "cache_disabled", "entry_deleted", "index_entry_deleted", "not_cookie_solution", "solution_not_cached"];
+    readonly unavailability_reason: readonly ["missing_credentials", "missing_proxy_identity", "missing_client_profile", "missing_challenge_input", "missing_transport", "allocation_exhausted", "transport_failure", "timeout", "not_implemented"];
+    readonly verdict_reason: readonly ["human_puzzle", "solve_failed"];
+    readonly transport_phase: readonly ["create_task", "poll_result", "cleanup", "measure_ip", "fetch_script", "generate_payload", "post_payload"];
+    readonly resolver_identity_source: readonly ["declared", "defaulted"];
+    readonly operation: readonly ["client.close", "context.close"];
+};
+type ResolverClosedEnumSpanAttributes = typeof RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES;
+type Present<T> = Exclude<T, undefined>;
+/** Properties typed as a finite union of string literals, never plain `string`. */
+type FiniteStringKeys<T> = {
+    [K in keyof T]-?: [Present<T[K]>] extends [never] ? never : [Present<T[K]>] extends [string] ? string extends Present<T[K]> ? never : K : never;
+}[keyof T];
+type DeclaredClosedEnumAttributes<T> = {
+    [K in keyof T]: K extends FiniteStringKeys<T> ? K extends keyof ResolverClosedEnumSpanAttributes ? [Present<T[K]>] extends [ResolverClosedEnumSpanAttributes[K][number]] ? T[K] : never : never : T[K];
+};
+/**
+ * Resolver span attributes. Every property typed as a finite string union must be declared in
+ * `RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES` with all of its members, so a new closed-enum attribute
+ * cannot silently become free text that fail-closed redaction suppresses.
+ */
+export declare function resolverSpanAttributes<const T extends Record<string, unknown>>(attributes: T & DeclaredClosedEnumAttributes<T>): T;
+export {};

package/dist/runtime/resolver-span-attributes.js

@@ -0,0 +1,93 @@
+// Type-only imports: the diagnostic redactor reads this table, so it must not pull the resolver
+// runtime (or anything that imports the redactor) into module evaluation.
+/** Every member of a closed string union, as runtime values; a missing or extra member fails tsc. */
+function closedEnumValues() {
+    return (values, ..._missing) => values;
+}
+const RESOLVER_PAID_USAGE_OUTCOMES = closedEnumValues()([
+    "success",
+    "vendor_error",
+    "timeout",
+    "abandoned",
+]);
+// `resolver.cache.invalidate` outcomes. The union stays private to resolver.ts; its producer's
+// `resolverSpanAttributes` call fails to compile if it can emit an outcome missing here.
+const RESOLVER_CACHE_INVALIDATION_OUTCOMES = [
+    "cache_disabled",
+    "entry_deleted",
+    "index_entry_deleted",
+    "not_cookie_solution",
+    "solution_not_cached",
+];
+/**
+ * Closed-enum span attributes emitted by the resolver, by attribute key. A value listed here is an
+ * SDK-declared literal, so fail-closed diagnostic redaction keeps it the way it keeps a typed
+ * number; any other value under the same key is still free text. Registered credentials are
+ * matched either way.
+ */
+export const RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES = {
+    vendor: closedEnumValues()([
+        "browser",
+        "capsolver",
+        "capmonster",
+        "2captcha",
+        "hypersolutions",
+        "custom",
+    ]),
+    challenge_kind: closedEnumValues()([
+        "turnstile",
+        "recaptcha_v2",
+        "recaptcha_v3",
+        "hcaptcha",
+        "cloudflare_interstitial",
+        "aws_waf",
+        "akamai_sec_cpt",
+        "akamai_sensor",
+        "akamai_sbsd",
+    ]),
+    endpoint: closedEnumValues()([
+        "capsolver:create_task",
+        "twocaptcha:create_task",
+        "hyper:ip",
+        "hyper:sbsd_create",
+    ]),
+    billing: closedEnumValues()(["metered", "unconfirmed"]),
+    outcome: [...RESOLVER_PAID_USAGE_OUTCOMES, ...RESOLVER_CACHE_INVALIDATION_OUTCOMES],
+    unavailability_reason: closedEnumValues()([
+        "missing_credentials",
+        "missing_proxy_identity",
+        "missing_client_profile",
+        "missing_challenge_input",
+        "missing_transport",
+        "allocation_exhausted",
+        "transport_failure",
+        "timeout",
+        "not_implemented",
+    ]),
+    verdict_reason: closedEnumValues()([
+        "human_puzzle",
+        "solve_failed",
+    ]),
+    transport_phase: closedEnumValues()([
+        "create_task",
+        "poll_result",
+        "cleanup",
+        "measure_ip",
+        "fetch_script",
+        "generate_payload",
+        "post_payload",
+    ]),
+    resolver_identity_source: closedEnumValues()(["declared", "defaulted"]),
+    operation: closedEnumValues()([
+        "client.close",
+        "context.close",
+    ]),
+};
+/**
+ * Resolver span attributes. Every property typed as a finite string union must be declared in
+ * `RESOLVER_CLOSED_ENUM_SPAN_ATTRIBUTES` with all of its members, so a new closed-enum attribute
+ * cannot silently become free text that fail-closed redaction suppresses.
+ */
+export function resolverSpanAttributes(attributes) {
+    return attributes;
+}