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

package/src/config/loader.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "../runtime/diagnostic-env.js";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -6,6 +7,7 @@ import path from "node:path";
 import type { Redis } from "ioredis";
 
 import type { ProviderProxyPolicy, ProviderProxyProvider, TraceConfig } from "../types.js";
+import { BoundedExpiringMap } from "../runtime/bounded-expiring-map.js";
 import {
 	NODEMAVEN_DEFAULT_PROTOCOL,
 	NODEMAVEN_FILTER_ENV,
@@ -223,7 +225,13 @@ type ProxyRedisClient = Pick<
 	"connect" | "del" | "eval" | "get" | "on" | "pttl" | "set" | "status"
 >;
 
-const proxyCache = new Map<string, CachedProxyPool>();
+// Keyed per (policy, affinity). Connection affinities are minted by callers, so
+// without a cap a long-lived process accumulates one pool per affinity it ever
+// saw. Evicting a still-fresh pool forces a fresh allocation (a different
+// egress endpoint) for that affinity, so the cap is generous and every
+// capacity eviction is reported as `diagnostics.poolCacheEvictions`.
+const SMARTPROXY_POOL_CACHE_MAX_ENTRIES = 10_000;
+let proxyCache = createSmartproxyPoolCache(SMARTPROXY_POOL_CACHE_MAX_ENTRIES);
 const require = createRequire(import.meta.url);
 const proxyInflight = new Map<string, Promise<SmartproxyAllocationResult>>();
 const invalidatedProxyKeys = new Map<string, number>();
@@ -249,8 +257,8 @@ const SMARTPROXY_EXTRACTION_SOFT_REFRESH_MS = 10_000;
 
 function redisUrlFromEnv(): string | undefined {
 	return (
-		process.env.APIFUSE__PROVIDER__CACHE_REDIS_URL?.trim() ||
-		process.env[REDIS_URL_ENV]?.trim() ||
+		readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
 		undefined
 	);
 }
@@ -261,9 +269,9 @@ export function providerCacheRedisUrlFromEnv(): string | undefined {
 
 export function providerStateRedisUrlFromEnv(): string | undefined {
 	return (
-		process.env[PROVIDER_STATE_REDIS_URL_ENV]?.trim() ||
-		process.env[PROVIDER_CACHE_REDIS_URL_ENV]?.trim() ||
-		process.env[REDIS_URL_ENV]?.trim() ||
+		readDiagnosticEnv(PROVIDER_STATE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
 		undefined
 	);
 }
@@ -277,6 +285,22 @@ export function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number |
 	smartproxyAllocatorDeadlineMsForTests = deadlineMs;
 }
 
+/** @internal Test-only hook for exercising the pool-cache capacity bound at a small size. */
+export function __setSmartproxyPoolCacheMaxEntriesForTests(maxEntries: number | undefined): void {
+	proxyCache = createSmartproxyPoolCache(maxEntries ?? SMARTPROXY_POOL_CACHE_MAX_ENTRIES);
+}
+
+/** @internal Test-only view of the in-memory Smartproxy cache sizes. */
+export function __getSmartproxyCacheSizesForTests(): { pools: number; tombstones: number } {
+	return { pools: proxyCache.size, tombstones: invalidatedProxyKeys.size };
+}
+
+function createSmartproxyPoolCache(
+	maxEntries: number,
+): BoundedExpiringMap<string, CachedProxyPool> {
+	return new BoundedExpiringMap(maxEntries, (pool) => pool.expiresAt);
+}
+
 function getProxyRedis(): ProxyRedisClient | undefined {
 	if (proxyRedisForTests) return proxyRedisForTests;
 	const redisUrl = redisUrlFromEnv();
@@ -670,12 +694,12 @@ export async function resolveWithVendor(
 		const startedAt = Date.now();
 		const username = (
 			context.credentials === undefined
-				? process.env[NODEMAVEN_USERNAME_ENV]
+				? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
 				: context.credentials[NODEMAVEN_USERNAME_ENV]
 		)?.trim();
 		const password = (
 			context.credentials === undefined
-				? process.env[NODEMAVEN_PASSWORD_ENV]
+				? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
 				: context.credentials[NODEMAVEN_PASSWORD_ENV]
 		)?.trim();
 		const filter =
@@ -726,7 +750,7 @@ export async function resolveWithVendor(
 	// smartproxy allocation-style vendor.
 	const appKey = (
 		context.credentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: context.credentials[SMARTPROXY_APP_KEY_ENV]
 	)?.trim();
 	if (!appKey) {
@@ -760,6 +784,7 @@ export async function resolveWithVendor(
 			...allocated.pool.diagnostics,
 			poolSize: allocated.pool.urls.length,
 			poolIndex,
+			poolCacheEvictions: proxyCache.capacityEvictions,
 		},
 	};
 }
@@ -814,18 +839,18 @@ function vendorHasCredentials(
 	if (vendor === "nodemaven") {
 		return Boolean(
 			(credentials === undefined
-				? process.env[NODEMAVEN_USERNAME_ENV]
+				? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
 				: credentials[NODEMAVEN_USERNAME_ENV]
 			)?.trim() &&
 				(credentials === undefined
-					? process.env[NODEMAVEN_PASSWORD_ENV]
+					? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
 					: credentials[NODEMAVEN_PASSWORD_ENV]
 				)?.trim(),
 		);
 	}
 	return Boolean(
 		(credentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: credentials[SMARTPROXY_APP_KEY_ENV]
 		)?.trim(),
 	);
@@ -1082,8 +1107,8 @@ async function allocateSmartproxy(
 	const now = startedAt;
 	const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
 	const skipCached = invalidatedUntil > now;
-	const cached = proxyCache.get(cacheKey);
-	if (!skipCached && cached && isFresh(cached, now)) {
+	const cached = skipCached ? undefined : proxyCache.get(cacheKey, now);
+	if (cached) {
 		if (shouldSoftRefresh(cached, now)) {
 			void refreshSmartproxyPool(
 				cacheKey,
@@ -1158,7 +1183,7 @@ async function readSmartproxyRedisPool(
 	}
 	const now = Date.now();
 	if (!isFresh(pool, now)) return null;
-	proxyCache.set(cacheKey, pool);
+	proxyCache.set(cacheKey, pool, now);
 	return {
 		pool,
 		telemetry: telemetryForPool(pool, "redis_hit", startedAt, { redisReadMs }),
@@ -1482,7 +1507,7 @@ async function allocateAndStoreSmartproxyPool(
 			rawConnect: true,
 		},
 	};
-	proxyCache.set(cacheKey, result);
+	proxyCache.set(cacheKey, result, allocatedAt);
 	if (options.redis && options.poolKey) {
 		const redis = options.redis;
 		const poolKey = options.poolKey;
@@ -1733,7 +1758,7 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
 	const appKey = (
 		options.engineCredentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: options.engineCredentials[SMARTPROXY_APP_KEY_ENV]
 	)?.trim();
 	if (!appKey) return undefined;
@@ -1744,7 +1769,11 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 		lifetimeMinutes,
 		options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy,
 	);
-	invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
+	const now = Date.now();
+	for (const [key, invalidatedUntil] of invalidatedProxyKeys) {
+		if (invalidatedUntil <= now) invalidatedProxyKeys.delete(key);
+	}
+	invalidatedProxyKeys.set(cacheKey, now + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
 	proxyCache.delete(cacheKey);
 	proxyInflight.delete(cacheKey);
 	return cacheKey;

package/src/declaration-validation.ts

@@ -1,6 +1,8 @@
 import { describeSchema } from "./contract-serialization.js";
 import { ProviderError } from "./errors.js";
 import { HealthScenarioSchema } from "./health-scenario.js";
+import { kindRequiresClientProfile } from "./runtime/resolver-config.js";
+import { resolverClientProfileFamily, resolveStealthProfileSelection } from "./stealth/profiles.js";
 import type {
 	HealthJourneyDefinition,
 	ProviderDefinition,
@@ -22,6 +24,7 @@ export const DECLARATION_RULE_IDS = {
 	proxySmartproxyGeo: "proxy-smartproxy-country-only",
 	operationUpstreamProxy: "operation-upstream-proxy-unsupported",
 	pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid",
+	resolverClientProfileFamily: "resolver-client-profile-family",
 } as const;
 
 export type DeclarationRuleId =
@@ -57,11 +60,15 @@ export function validateFailClosedDeclaration(provider: ProviderDefinition): voi
 	validatePinnedWireFieldPaths(provider, violations);
 	validateSchemaDeclaration(provider, violations);
 	validateProxyDeclaration(provider, violations);
+	validateResolverClientProfileDeclaration(provider, violations);
 	validateOperationDeclaration(provider, violations);
 	if (violations.length > 0) throw declarationInvalidError(violations);
 }
 
-type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "meta" | "proxy">;
+type ProviderDeclarationRulesInput = Pick<
+	ProviderDefinition,
+	"healthJourneys" | "meta" | "proxy" | "resolver" | "stealth"
+>;
 type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
 
 /** Enforces fail-closed rules that only depend on the provider declaration. */
@@ -89,6 +96,7 @@ function collectProviderDeclarationViolations(
 	validateHealthDeclaration(provider, violations);
 	validatePinnedWireFieldPaths(provider, violations);
 	validateProxyDeclaration(provider, violations);
+	validateResolverClientProfileDeclaration(provider, violations);
 }
 
 function validatePinnedWireFieldPaths(
@@ -307,6 +315,44 @@ function validateProxyDeclaration(
 	}
 }
 
+/**
+ * An akamai_sbsd solve runs on the provider's own stealth session, so the declared
+ * resolver.clientProfile must name the browser family that session emulates. The
+ * stealth runtime re-checks per request (a fetch may override the browser); this
+ * rule fails the declaration instead of the first challenged request.
+ */
+function validateResolverClientProfileDeclaration(
+	provider: ProviderDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	const resolver = provider.resolver;
+	if (
+		!resolver ||
+		!Array.isArray(resolver.kinds) ||
+		!resolver.kinds.some(kindRequiresClientProfile) ||
+		typeof resolver.clientProfile !== "string"
+	) {
+		return;
+	}
+	let sessionBrowser: string;
+	try {
+		sessionBrowser = resolveStealthProfileSelection(provider.stealth).browser;
+	} catch {
+		// An unsupported stealth selection is reported by the stealth runtime itself.
+		return;
+	}
+	const family = resolverClientProfileFamily(resolver.clientProfile);
+	if (family === sessionBrowser) return;
+	violations.push({
+		ruleId: DECLARATION_RULE_IDS.resolverClientProfileFamily,
+		path: "resolver.clientProfile",
+		message: family
+			? `"${resolver.clientProfile}" names ${family}, but the stealth session browser is ${sessionBrowser}.`
+			: `"${resolver.clientProfile}" does not name a supported browser family (chrome, firefox, safari).`,
+		fix: `Declare stealth.browser as the family resolver.clientProfile names, or set resolver.clientProfile to the ${sessionBrowser} profile the SBSD session runs on.`,
+	});
+}
+
 function declaredProxyVendors(policy: ProviderProxyPolicy): ProviderProxyProvider[] {
 	const vendors = [...(policy.providers ?? [])];
 	if (policy.provider !== undefined) vendors.push(policy.provider);

package/src/define.ts

@@ -6,8 +6,15 @@ import {
 } from "./declaration-validation.js";
 import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
-import { isEngineOwnedProxyCredentialName, isEngineOwnedTelemetryEnvName } from "./engine.js";
+import {
+	engineOwnedResolverCredentialTarget,
+	isEngineOwnedEnvName,
+	isEngineOwnedProxyCredentialName,
+	isEngineOwnedRuntimeEnvName,
+	isEngineOwnedTelemetryEnvName,
+} from "./engine.js";
 import { HealthScenarioSchema } from "./health-scenario.js";
+import { kindRequiresClientProfile } from "./runtime/resolver-config.js";
 import {
 	NativeEgressPolicyValidationError,
 	validateNativeProviderConfig,
@@ -49,9 +56,9 @@ import type {
 	ProviderSecretDeclaration,
 	ProviderStreamEvent,
 	ProviderSttConfig,
+	ProviderStealthConfig,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
-	StealthProfileSelection,
 } from "./types.js";
 import {
 	HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
@@ -151,6 +158,7 @@ export const VALID_PROVIDER_RESOLVER_VENDORS = exhaustiveLiteralArray<ProviderRe
 	"capsolver",
 	"capmonster",
 	"2captcha",
+	"hypersolutions",
 	"custom",
 ] as const);
 export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderChallengeKind>()([
@@ -162,6 +170,7 @@ export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderCha
 	"aws_waf",
 	"akamai_sec_cpt",
 	"akamai_sensor",
+	"akamai_sbsd",
 ] as const);
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"] as const;
@@ -584,7 +593,7 @@ export interface ProviderDeclaration {
 	/** Declares upstream host policy; this does not add a `ctx.allowedHosts` member. */
 	allowedHosts?: string[];
 	native?: NativeProviderConfig;
-	stealth?: StealthProfileSelection;
+	stealth?: ProviderStealthConfig;
 	/** Declares proxy policy; this is provider intent and does not add a `ctx.proxy` member. */
 	proxy?: ProviderProxyConfig;
 	ocr?: ProviderOcrConfig;
@@ -939,6 +948,15 @@ function validateProviderProxy(config: {
 	secrets?: ProviderSecretDeclaration[];
 }): void {
 	for (const secret of config.secrets ?? []) {
+		const engineName = engineOwnedResolverCredentialTarget(secret.name);
+		if (engineName !== undefined) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned resolver credential "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; configure the solver key only on the provider engine as ${engineName}.`,
+				},
+			);
+		}
 		if (isEngineOwnedTelemetryEnvName(secret.name)) {
 			throw new ValidationError(
 				`Provider "${config.id}" cannot declare engine-owned telemetry variable "${secret.name}"`,
@@ -947,6 +965,22 @@ function validateProviderProxy(config: {
 				},
 			);
 		}
+		if (isEngineOwnedRuntimeEnvName(secret.name)) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned runtime variable "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; the provider engine reads it from its own environment.`,
+				},
+			);
+		}
+		if (isEngineOwnedEnvName(secret.name) && !isEngineOwnedProxyCredentialName(secret.name)) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned control variable "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; configure it only on the provider engine.`,
+				},
+			);
+		}
 		if (!isEngineOwnedProxyCredentialName(secret.name)) continue;
 		throw new ValidationError(
 			`Provider "${config.id}" cannot declare engine-owned proxy credential "${secret.name}"`,
@@ -1163,6 +1197,14 @@ function validateProviderResolver(config: { id: string; resolver?: ProviderResol
 			},
 		);
 	}
+	if (resolver.kinds.some(kindRequiresClientProfile) && resolver.clientProfile === undefined) {
+		throw new ValidationError(
+			`Provider "${config.id}" must declare resolver.clientProfile for akamai_sbsd.`,
+			{
+				fix: `Set resolver.clientProfile for provider "${config.id}" to the transport-owned profile used by its Akamai session.`,
+			},
+		);
+	}
 }
 
 function validateResolverLiteralArray<TValue extends string>(

package/src/engine.ts

@@ -1,4 +1,11 @@
+import { readDiagnosticEnv } from "./runtime/diagnostic-env.js";
 import { ProviderError } from "./errors.js";
+import {
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
+} from "./runtime/resolver-config.js";
 import {
 	OTEL_EXPORTER_OTLP_ENDPOINT,
 	OTEL_EXPORTER_OTLP_HEADERS,
@@ -55,6 +62,36 @@ export function isEngineOwnedProxyCredentialName(name: string): boolean {
 	return ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAME_SET.has(canonicalEnvName(name));
 }
 
+/** Hosted resolver credentials owned by the engine and never projected to providers. */
+export const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES = [
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY,
+] as const;
+
+const ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET = new Set<string>(
+	ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES,
+);
+
+/**
+ * Engine variable a provider-declared secret name resolves to, or `undefined` when the
+ * name is not an engine-owned resolver credential. Provider-scoped Hyper aliases
+ * (`APIFUSE__PROVIDER__<ID>__HYPER_API_KEY`, measured on zozotown) map to the shared key.
+ */
+export function engineOwnedResolverCredentialTarget(name: string): string | undefined {
+	const canonical = canonicalEnvName(name);
+	if (ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAME_SET.has(canonical)) return canonical;
+	if (/^APIFUSE__PROVIDER__.+__HYPER_API_KEY$/u.test(canonical)) {
+		return APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY;
+	}
+	return undefined;
+}
+
+export function isEngineOwnedResolverCredentialName(name: string): boolean {
+	return engineOwnedResolverCredentialTarget(name) !== undefined;
+}
+
 /**
  * Trace-export configuration owned by the engine and forbidden in provider
  * declarations. The header variables carry collector credentials; the rest are
@@ -75,9 +112,47 @@ export function isEngineOwnedTelemetryEnvName(name: string): boolean {
 	return ENGINE_OWNED_TELEMETRY_ENV_NAME_SET.has(canonicalEnvName(name));
 }
 
+/** Engine control-plane configuration is never declarable or visible to provider code. */
+function isEngineOwnedEngineEnvName(name: string): boolean {
+	return canonicalEnvName(name).startsWith("APIFUSE__ENGINE__");
+}
+
+/**
+ * Hosted runtime settings the engine reads for OCR, STT, cache keying, choice
+ * tokens, and the CDP pool. Providers never own them: declarations are rejected
+ * and projections drop them, like the vendor credentials above.
+ */
+export const ENGINE_OWNED_RUNTIME_ENV_NAMES = [
+	"APIFUSE__STT__CLOUDFLARE_API_TOKEN",
+	"APIFUSE__OCR__CLOUDFLARE_API_TOKEN",
+	"APIFUSE__OCR__API_KEY",
+	"APIFUSE__CLOUDFLARE__ACCOUNT_ID",
+	"APIFUSE__CACHE__KEY_PEPPER",
+	"APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET",
+] as const;
+
+const ENGINE_OWNED_RUNTIME_ENV_NAME_SET = new Set<string>(ENGINE_OWNED_RUNTIME_ENV_NAMES);
+
+/** CDP pool settings form a prefix family (`APIFUSE__CDP_POOL__URL` today); the whole prefix is engine-owned. */
+const ENGINE_OWNED_CDP_POOL_ENV_PREFIX = "APIFUSE__CDP_POOL__";
+
+export function isEngineOwnedRuntimeEnvName(name: string): boolean {
+	const canonical = canonicalEnvName(name);
+	return (
+		ENGINE_OWNED_RUNTIME_ENV_NAME_SET.has(canonical) ||
+		canonical.startsWith(ENGINE_OWNED_CDP_POOL_ENV_PREFIX)
+	);
+}
+
 /** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
 export function isEngineOwnedEnvName(name: string): boolean {
-	return isEngineOwnedProxyCredentialName(name) || isEngineOwnedTelemetryEnvName(name);
+	return (
+		isEngineOwnedEngineEnvName(name) ||
+		isEngineOwnedProxyCredentialName(name) ||
+		isEngineOwnedResolverCredentialName(name) ||
+		isEngineOwnedRuntimeEnvName(name) ||
+		isEngineOwnedTelemetryEnvName(name)
+	);
 }
 
 /** Capture credentials in the engine host before constructing provider bindings. */
@@ -86,7 +161,7 @@ export function readEngineProxyCredentials(
 ): Readonly<Record<string, string>> {
 	return Object.fromEntries(
 		ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES.flatMap((name) => {
-			const value = environment[name]?.trim();
+			const value = readDiagnosticEnv(name, environment)?.trim();
 			return value ? [[name, value] as const] : [];
 		}),
 	);
@@ -100,7 +175,7 @@ export function createProviderEnvironment(
 	return Object.fromEntries(
 		declaredNames.flatMap((name) => {
 			if (isEngineOwnedEnvName(name)) return [];
-			const value = environment[name];
+			const value = readDiagnosticEnv(name, environment);
 			return value === undefined ? [] : [[name, value] as const];
 		}),
 	);

package/src/error-resolution.ts

@@ -10,6 +10,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"BROWSER_CDP_POOL_REQUIRED",
 	"BROWSER_RUNTIME_UNSUPPORTED",
 	"STEALTH_RUNTIME_UNSUPPORTED",
+	"STEALTH_HEADER_OVERRIDE_UNSUPPORTED",
 	"SSE_EVENT_UNDECLARED",
 	"STREAM_EVENT_TOO_LARGE",
 	"STREAM_CHUNK_TOO_LARGE",
@@ -51,6 +52,13 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"http_redirect_missing_location",
 	"http_redirect_loop",
 	"transport_invalid_url",
+	"EGRESS_LEASE_INVALID",
+	"EGRESS_LEASE_BINDING_INVALID",
+	"EGRESS_LEASE_KEY_MISSING",
+	"EGRESS_LEASE_KEY_WEAK",
+	"STEALTH_BODY_UNSUPPORTED",
+	"REPLAY_SESSION_MISMATCH",
+	"REPLAY_ALREADY_ATTEMPTED",
 	"retry_exhausted",
 	"auth_abort_unsafe_data",
 	"credentials_auth_missing_credential_keys",
@@ -117,6 +125,11 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		// contract): the upstream evaluated the request and said no under its
 		// own rules — a conflict with upstream state, never a 5xx.
 		["UPSTREAM_REJECTED", 409],
+		// Only an unverifiable or foreign handle is the caller's: key and binding
+		// faults stay unmapped (500) because the engine host, not the caller, owns them.
+		["EGRESS_LEASE_INVALID", 409],
+		["REPLAY_SESSION_MISMATCH", 409],
+		["REPLAY_ALREADY_ATTEMPTED", 409],
 		["UPSTREAM_ERROR", 502],
 		["BLOCKED", 502],
 		["OCR_UNAVAILABLE", 503],

package/src/index.ts

@@ -198,17 +198,43 @@ export {
 	type TelemetryKey,
 	type TenantNeutral,
 } from "./runtime/request-telemetry.js";
+export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
+export {
+	ResolverTelemetryCollector,
+	type ResolverCacheReadTelemetryEvent,
+	type ResolverCacheWriteTelemetryEvent,
+	type ResolverFailoverTelemetryEvent,
+	type ResolverIdentityTelemetryEvent,
+	type ResolverOutcomeTelemetryEvent,
+	type ResolverTelemetryAttemptOutcome,
+	type ResolverAttemptSample,
+	type ResolverTelemetryCacheStatus,
+	type ResolverTelemetryCacheWriteReason,
+	type ResolverTelemetryErrorClass,
+	type ResolverTelemetryHeaderPayload,
+	type ResolverTelemetryIdentitySource,
+	type ResolverTelemetryLogPayload,
+	type ResolverTelemetryOutcome,
+	type ResolverTelemetryPhase,
+	type ResolverTelemetrySink,
+	type ResolverVendorAttemptTelemetryEvent,
+} from "./runtime/resolver-telemetry.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 "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
-export type { ResolverVendorTransport } from "./runtime/resolver-vendors/types.js";
+export type {
+	ResolverPaidUsageContext,
+	ResolverVendorTransport,
+	ResolverVendorUnavailableReason,
+} from "./runtime/resolver-vendors/types.js";
 export {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -249,7 +275,10 @@ export {
 	type Span,
 	type TraceContext,
 } from "./runtime/trace.js";
+export type { DiagnosticRedactor } from "./runtime/diagnostic-redactor.js";
 export {
+	APIFUSE_CONTENT_PROVENANCE_META_KEY,
+	APIFUSE_CONTENT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
@@ -259,11 +288,13 @@ export {
 	field,
 	fields,
 	isSensitiveSchema,
+	publicField,
 	redactPayload,
 	type SensitiveFieldKind,
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
+	untrustedContent,
 	z,
 } from "./schema.js";
 export {
@@ -432,6 +463,7 @@ export type {
 	ProviderRuntimeTarget,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
+	ProviderStealthConfig,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderStreamEvent,
@@ -455,6 +487,7 @@ export type {
 	StateWriteOptions,
 	StealthClient,
 	StealthBrowser,
+	StealthChallengeClassification,
 	StealthCookieStore,
 	StealthCookieStoreV1,
 	StealthFetchOptions,