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

package/src/runtime/resolver-usage.ts

@@ -4,6 +4,7 @@ import type {
 	ResolverVendorUnavailableError,
 } from "./resolver-vendors/types.js";
 import type { TraceRecorder } from "./trace.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 
 export const RESOLVER_PAID_USAGE_SPAN = "resolver.usage";
 
@@ -22,9 +23,11 @@ export type ResolverPaidUsageEndpoint =
  * 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";
+
 const ENDPOINT_BILLING: Record<
 	ResolverPaidUsageEndpoint,
-	{ readonly billable_units: 0 | 1; readonly billing: "metered" | "unconfirmed" }
+	{ readonly billable_units: 0 | 1; readonly billing: ResolverPaidUsageBilling }
 > = {
 	"capsolver:create_task": { billable_units: 1, billing: "metered" },
 	"twocaptcha:create_task": { billable_units: 1, billing: "metered" },
@@ -78,7 +81,7 @@ export async function recordPaidResolverCreate<T>(options: {
 		}
 		return options.create();
 	}
-	const baseAttributes = {
+	const baseAttributes = resolverSpanAttributes({
 		vendor: options.vendor,
 		challenge_kind: options.kind,
 		endpoint: options.endpoint,
@@ -87,10 +90,10 @@ export async function recordPaidResolverCreate<T>(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/src/runtime/resolver-vendors/browser.ts

@@ -8,6 +8,7 @@ import type {
 } from "../../types.js";
 import { type BrowserClientOptions, createBrowserClient } from "../browser.js";
 import type { TraceRecorder } from "../trace.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import type { BrowserTelemetrySink } from "../browser-telemetry.js";
 import { resolverChallengeIssuingIdentity } from "./bindings.js";
 import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.js";
@@ -218,15 +219,15 @@ async function runBoundedCleanup(
 
 	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/src/runtime/resolver-vendors/capsolver.ts

@@ -3,6 +3,7 @@ import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind } from
 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 type { TraceRecorder } from "../trace.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import {
@@ -413,7 +414,7 @@ function spanErrorAttributes(
 	phase: CapsolverOperationPhase,
 ): Record<string, unknown> | undefined {
 	if (error instanceof ResolverVendorUnavailableError) {
-		return {
+		return resolverSpanAttributes({
 			unavailability_reason: error.reason,
 			transport_phase: error.phase,
 			...(error instanceof CapsolverUnavailableError
@@ -425,21 +426,21 @@ function spanErrorAttributes(
 						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;
 }
@@ -606,10 +607,10 @@ export function createCapsolverResolverVendorAdapter(
 				};
 				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();
@@ -689,10 +690,10 @@ export function createCapsolverResolverVendorAdapter(
 				};
 				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/src/runtime/resolver-vendors/twocaptcha.ts

@@ -1,6 +1,7 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
 import { recordPaidResolverCreate } from "../resolver-usage.js";
+import { resolverSpanAttributes } from "../resolver-span-attributes.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import {
 	type ResolverIdentity,
@@ -300,19 +301,19 @@ function spanErrorAttributes(
 	phase: TwoCaptchaOperationPhase,
 ): Record<string, unknown> | undefined {
 	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;
 }
@@ -468,10 +469,10 @@ export function createTwoCaptchaResolverVendorAdapter(
 				};
 				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();
@@ -517,10 +518,10 @@ export function createTwoCaptchaResolverVendorAdapter(
 				};
 				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/src/runtime/resolver.ts

@@ -64,6 +64,7 @@ import {
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 	kindRequiresClientProfile,
 } from "./resolver-config.js";
+import { resolverSpanAttributes } from "./resolver-span-attributes.js";
 import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 import type { TraceRecorder } from "./trace.js";
 import type { BrowserTelemetrySink } from "./browser-telemetry.js";
@@ -595,7 +596,7 @@ function unavailableAttempt(
 
 function unavailableSpanAttributes(error: ResolverVendorUnavailableError): Record<string, unknown> {
 	const attempt = unavailableAttempt(error);
-	return {
+	return resolverSpanAttributes({
 		unavailability_reason: error.reason,
 		missing_fields: error.missingFields,
 		cause_name: attempt.cause?.name,
@@ -603,7 +604,7 @@ function unavailableSpanAttributes(error: ResolverVendorUnavailableError): Recor
 		upstream_host: attempt.upstreamHost,
 		transport_phase: attempt.phase,
 		transport_round: attempt.round,
-	};
+	});
 }
 
 type ResolverAttemptDiagnostics = {
@@ -994,8 +995,8 @@ async function invalidateResolverSolutionWithOutcome(
 		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 }),
 	});
 }
 
@@ -1257,12 +1258,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/src/runtime/stealth-owned-headers.ts

@@ -1,20 +1,28 @@
+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: ReadonlySet<string> = new Set([
 	"host",
@@ -39,3 +47,21 @@ export function isStealthOwnedHeaderName(name: string): boolean {
 		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: Readonly<Record<string, string | readonly string[] | undefined>>,
+): void {
+	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/src/runtime/stealth-telemetry.ts

@@ -22,7 +22,12 @@ export type StealthTelemetryErrorCode =
 	| "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";