@apifuse/provider-sdk 2.2.0-beta.67 → 2.2.0-beta.69

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

@@ -4,6 +4,14 @@ 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";
+/**
+ * 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.
+ */
+export type ResolverPaidUsageBilling = "metered" | "unconfirmed";
 /**
  * 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

package/dist/runtime/resolver-usage.js

@@ -1,11 +1,5 @@
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 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" },
@@ -42,7 +36,7 @@ export async function recordPaidResolverCreate(options) {
         }
         return options.create();
     }
-    const baseAttributes = {
+    const baseAttributes = resolverSpanAttributes({
         vendor: options.vendor,
         challenge_kind: options.kind,
         endpoint: options.endpoint,
@@ -51,10 +45,10 @@ export async function recordPaidResolverCreate(options) {
         ...(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) }),
+        onSuccess: () => resolverSpanAttributes({ outcome: "success" }),
+        onError: (error) => resolverSpanAttributes({ outcome: errorOutcome(error, options.signal) }),
     });
 }

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

@@ -1,5 +1,6 @@
 import { isProviderError } from "../../errors.js";
 import { createBrowserClient } from "../browser.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
 import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
 import { ResolverVendorUnavailableError, } from "./types.js";
@@ -141,15 +142,15 @@ async function runBoundedCleanup(cleanup, timeoutMs, challengeKind, operation, t
     }
     await traceRecorder
         .runSpan("resolver.vendor.cleanup", boundedCleanup, {
-        attributes: {
+        attributes: resolverSpanAttributes({
             vendor: BROWSER_VENDOR_ID,
             challenge_kind: challengeKind,
             operation,
-        },
+        }),
         onError(error) {
-            return {
+            return resolverSpanAttributes({
                 error_message: error instanceof Error ? error.message : String(error),
-            };
+            });
         },
     })
         .catch(() => undefined);

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

@@ -2,6 +2,7 @@ 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 { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, resolverVendorSupports, } from "./types.js";
 const CAPSOLVER_VENDOR_ID = "capsolver";
@@ -263,7 +264,7 @@ function endpoint(baseUrl, path) {
 }
 function spanErrorAttributes(error, phase) {
     if (error instanceof ResolverVendorUnavailableError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: error.reason,
             transport_phase: error.phase,
             ...(error instanceof CapsolverUnavailableError
@@ -275,21 +276,21 @@ function spanErrorAttributes(error, phase) {
                     response_length: error.responseLength,
                 }
                 : {}),
-        };
+        });
     }
     if (error instanceof CapsolverVerdictError) {
-        return {
+        return resolverSpanAttributes({
             verdict_reason: error.reason,
             transport_phase: error.phase,
             vendor_error_code: error.errorCode,
             vendor_error_description: error.errorDescription,
-        };
+        });
     }
     if (error instanceof CapsolverSolveTimeoutError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: "timeout",
             transport_phase: phase,
-        };
+        });
     }
     return undefined;
 }
@@ -436,10 +437,10 @@ export function createCapsolverResolverVendorAdapter(options) {
                 };
                 const taskId = traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: CAPSOLVER_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "create_task"),
                     })
                     : await createTask();
@@ -506,10 +507,10 @@ export function createCapsolverResolverVendorAdapter(options) {
                 };
                 return traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: CAPSOLVER_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "poll_result"),
                     })
                     : await pollResult();

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

@@ -1,4 +1,5 @@
 import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import { ResolverChallengeVerdictError, ResolverVendorUnavailableError, recordResolverVendorPoll, resolverVendorSupports, } from "./types.js";
 const TWOCAPTCHA_VENDOR_ID = "2captcha";
@@ -198,19 +199,19 @@ function endpoint(baseUrl, path) {
 }
 function spanErrorAttributes(error, phase) {
     if (error instanceof ResolverVendorUnavailableError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: error.reason,
             transport_phase: error.phase,
-        };
+        });
     }
     // The solve budget raises TwoCaptchaSolveTimeoutError inside the spanned closure and
     // the outer catch converts it only after the span has been finalized, so the span has
     // to recognize it here or slow solves lose exactly the attribution these spans add.
     if (error instanceof TwoCaptchaSolveTimeoutError) {
-        return {
+        return resolverSpanAttributes({
             unavailability_reason: "timeout",
             transport_phase: phase,
-        };
+        });
     }
     return undefined;
 }
@@ -345,10 +346,10 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                 };
                 const taskId = traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: TWOCAPTCHA_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "create_task"),
                     })
                     : await createTask();
@@ -387,10 +388,10 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                 };
                 return traceRecorder
                     ? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
-                        attributes: {
+                        attributes: resolverSpanAttributes({
                             vendor: TWOCAPTCHA_VENDOR_ID,
                             challenge_kind: challenge.kind,
-                        },
+                        }),
                         onError: (error) => spanErrorAttributes(error, "poll_result"),
                     })
                     : await pollResult();

package/dist/runtime/resolver.js

@@ -13,6 +13,7 @@ import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocap
 import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, attachResolverVendorPollObserver, resolveProviderResolverVendors, resolverVendorSupports, } from "./resolver-vendors/types.js";
 import { createUnsupportedResolverClient, inheritResolverTelemetryBinding, registerResolverTelemetryBinding, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 import { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, kindRequiresClientProfile, } from "./resolver-config.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
@@ -356,7 +357,7 @@ function unavailableAttempt(error, forTelemetry = false) {
 }
 function unavailableSpanAttributes(error) {
     const attempt = unavailableAttempt(error);
-    return {
+    return resolverSpanAttributes({
         unavailability_reason: error.reason,
         missing_fields: error.missingFields,
         cause_name: attempt.cause?.name,
@@ -364,7 +365,7 @@ function unavailableSpanAttributes(error) {
         upstream_host: attempt.upstreamHost,
         transport_phase: attempt.phase,
         transport_round: attempt.round,
-    };
+    });
 }
 function resolverTelemetryPhase(value) {
     return value === "create_task" ||
@@ -657,8 +658,8 @@ async function invalidateResolverSolutionWithOutcome(resolver, challenge, soluti
         return await invalidate();
     }
     return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
-        attributes: { challenge_kind: challenge.kind },
-        onSuccess: (outcome) => ({ outcome }),
+        attributes: resolverSpanAttributes({ challenge_kind: challenge.kind }),
+        onSuccess: (outcome) => resolverSpanAttributes({ outcome }),
     });
 }
 /** Remove the cached entry for the exact solution object returned by this resolver. */
@@ -864,12 +865,12 @@ function createResolverChainClient(options) {
                         };
                         solution = traceRecorder
                             ? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
-                                attributes: {
+                                attributes: resolverSpanAttributes({
                                     vendor: adapter.id,
                                     challenge_kind: challenge.kind,
                                     client_profile: options.clientProfile,
                                     resolver_identity_source: identityResolution.userAgentSource,
-                                },
+                                }),
                                 onError(error) {
                                     return error instanceof ResolverVendorUnavailableError
                                         ? unavailableSpanAttributes(error)

package/dist/runtime/stealth-owned-headers.d.ts

@@ -3,18 +3,24 @@
  *
  * `ctx.stealth` composes these from the Chrome emulation and the request class,
  * so a caller value is rejected at request time with `SDKError` code
- * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` (`assertCallerHeadersSupported` in
- * stealth.ts). The `browser-version-literal` lint reports a subset of these
- * names — the `sec-fetch-*` and `sec-ch-ua*` families — in files that use
- * `ctx.stealth` (`isReportedOwnedHeaderName` in lint.ts). Both read this
- * module, so the lint cannot claim a rejection the runtime does not perform;
- * it reports deliberately less than the runtime rejects (host, connection,
+ * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` ({@link assertCallerHeadersSupported}).
+ * The offline test harness (`runStandardTests`) calls the same function on
+ * every `ctx.stealth` request it serves, so a provider test fails exactly where
+ * production would, whichever file or variable the header came from. That is
+ * the cross-file enforcement.
+ *
+ * The `browser-version-literal` lint reports a subset of these names — the
+ * `sec-fetch-*` and `sec-ch-ua*` families — in files that use `ctx.stealth`
+ * (`isReportedOwnedHeaderName` in lint.ts). Both read this module, so the lint
+ * cannot claim a rejection the runtime does not perform; it reports
+ * deliberately less than the runtime rejects (host, connection,
  * accept-encoding and a non-literal user-agent stay silent — see that
  * predicate for why), so a green `apifuse check` is not proof that no owned
  * header is set.
  *
- * Leaf module by design: no imports, so the lazily loaded CLI lint path does
- * not pull the stealth runtime in.
+ * Kept off the stealth runtime: the only import is `errors.js`, whose own
+ * imports are type-only, so the lazily loaded CLI lint path does not pull the
+ * stealth runtime in.
  */
 export declare const SDK_OWNED_EXACT_CHROME_HEADERS: ReadonlySet<string>;
 export declare const SDK_OWNED_CHROME_HEADER_PREFIX = "sec-fetch-";
@@ -24,3 +30,10 @@ export declare const SDK_OWNED_CHROME_HEADER_PREFIX = "sec-fetch-";
  * `sec-fetch-*` name.
  */
 export declare function isStealthOwnedHeaderName(name: string): boolean;
+/**
+ * Throws `SDKError` `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` for the first caller
+ * header `ctx.stealth` owns. An `undefined` value is skipped, as the transport
+ * drops it before sending. The stealth runtime and the offline test harness
+ * both call this, so the two cannot disagree about what is rejected.
+ */
+export declare function assertCallerHeadersSupported(headers: Readonly<Record<string, string | readonly string[] | undefined>>): void;

package/dist/runtime/stealth-owned-headers.js

@@ -1,20 +1,27 @@
+import { SDKError } from "../errors.js";
 /**
  * Header names the stealth transport owns.
  *
  * `ctx.stealth` composes these from the Chrome emulation and the request class,
  * so a caller value is rejected at request time with `SDKError` code
- * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` (`assertCallerHeadersSupported` in
- * stealth.ts). The `browser-version-literal` lint reports a subset of these
- * names — the `sec-fetch-*` and `sec-ch-ua*` families — in files that use
- * `ctx.stealth` (`isReportedOwnedHeaderName` in lint.ts). Both read this
- * module, so the lint cannot claim a rejection the runtime does not perform;
- * it reports deliberately less than the runtime rejects (host, connection,
+ * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` ({@link assertCallerHeadersSupported}).
+ * The offline test harness (`runStandardTests`) calls the same function on
+ * every `ctx.stealth` request it serves, so a provider test fails exactly where
+ * production would, whichever file or variable the header came from. That is
+ * the cross-file enforcement.
+ *
+ * The `browser-version-literal` lint reports a subset of these names — the
+ * `sec-fetch-*` and `sec-ch-ua*` families — in files that use `ctx.stealth`
+ * (`isReportedOwnedHeaderName` in lint.ts). Both read this module, so the lint
+ * cannot claim a rejection the runtime does not perform; it reports
+ * deliberately less than the runtime rejects (host, connection,
  * accept-encoding and a non-literal user-agent stay silent — see that
  * predicate for why), so a green `apifuse check` is not proof that no owned
  * header is set.
  *
- * Leaf module by design: no imports, so the lazily loaded CLI lint path does
- * not pull the stealth runtime in.
+ * Kept off the stealth runtime: the only import is `errors.js`, whose own
+ * imports are type-only, so the lazily loaded CLI lint path does not pull the
+ * stealth runtime in.
  */
 export const SDK_OWNED_EXACT_CHROME_HEADERS = new Set([
     "host",
@@ -35,3 +42,16 @@ export function isStealthOwnedHeaderName(name) {
     const lower = name.toLowerCase();
     return (SDK_OWNED_EXACT_CHROME_HEADERS.has(lower) || lower.startsWith(SDK_OWNED_CHROME_HEADER_PREFIX));
 }
+/**
+ * Throws `SDKError` `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` for the first caller
+ * header `ctx.stealth` owns. An `undefined` value is skipped, as the transport
+ * drops it before sending. The stealth runtime and the offline test harness
+ * both call this, so the two cannot disagree about what is rejected.
+ */
+export function assertCallerHeadersSupported(headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined || !isStealthOwnedHeaderName(name))
+            continue;
+        throw new SDKError(`Stealth transport owns the "${name.toLowerCase()}" header; remove it from headers.`, { code: "STEALTH_HEADER_OVERRIDE_UNSUPPORTED" });
+    }
+}

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

@@ -1,7 +1,7 @@
 import type { StealthBrowser, StealthChallengeClassification, StealthOS, StealthProfileDescriptor } from "../types.js";
 import { type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
 export type StealthTelemetryErrorCode = "transport_network_error" | "transport_timeout" | "transport_cancelled" | "upstream_http_error" | "response_too_large" | "proxy_connect_failed" | "PROXY_POOL_STALE" | "PROXY_EDGE_AUTH_REJECTED" | "PROXY_AUTH_IP_DENIED" | "PROXY_EDGE_TLS_REJECTED" | "PROXY_REQUIRED" | "other";
-export type StealthTelemetryRequestClass = "navigation" | "script_navigation" | "xhr" | "post";
+export type StealthTelemetryRequestClass = "navigation" | "script_navigation" | "form_post" | "xhr" | "post";
 export type StealthTelemetryAttemptKind = "request" | "resolver" | "proxy_diagnostic";
 export type StealthTelemetrySbsdOutcome = StealthChallengeClassification["outcome"] | "detected" | "refetch_clear";
 export type StealthTelemetryDiagnostics = {