@apifuse/provider-sdk 2.2.0-beta.22 → 2.2.0-beta.24

package/src/config/loader.ts

@@ -19,7 +19,7 @@ import {
 
 export type { ProxyProtocol } from "../runtime/proxy-nodemaven.js";
 
-/** Proxy vendors the SDK resolves natively (as opposed to the static env path). */
+/** Proxy vendors with SDK-managed resolution. */
 export type ProxyVendorName = "smartproxy" | "nodemaven";
 
 // "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
@@ -37,15 +37,6 @@ export const PROVIDER_CACHE_REDIS_URL_ENV = "APIFUSE__PROVIDER__CACHE_REDIS_URL"
 export const PROVIDER_STATE_REDIS_URL_ENV = "APIFUSE__PROVIDER__STATE_REDIS_URL";
 export const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
 
-export type ProxyOptions = {
-	url: string;
-};
-
-export type ProxyConfig = Partial<ProxyOptions> & {
-	provider?: string;
-	apiKey?: string;
-};
-
 export type BrowserConfig = {
 	executablePath?: string;
 	headless?: boolean;
@@ -57,7 +48,6 @@ export type SessionConfig = {
 };
 
 export type ApiFuseConfig = {
-	proxy?: ProxyConfig;
 	browser?: BrowserConfig;
 	session?: SessionConfig;
 	trace?: TraceConfig;
@@ -67,7 +57,6 @@ export type ApiFuseConfig = {
 export type ProxyResolutionOptions = {
 	proxy?: string;
 	upstream?: { proxy?: boolean | ProviderProxyPolicy };
-	apifuseConfig?: Pick<ApiFuseConfig, "proxy">;
 	proxyPolicy?: ProviderProxyPolicy;
 	affinityKey?: string;
 	/** Zero-based proxy-pool attempt index used by SDK transports for failover. */
@@ -444,75 +433,7 @@ function serializeSmartproxyPool(pool: CachedProxyPool): string {
 
 function normalizeProxyUrl(url?: string): string | undefined {
 	const normalized = url?.trim();
-	return normalized ? applyStickyProxySession(normalized) : undefined;
-}
-
-function readPositiveIntegerEnv(name: string): string | undefined {
-	const raw = process.env[name]?.trim();
-	if (!raw) return undefined;
-	if (!/^[1-9]\d*$/.test(raw)) {
-		throw new Error(`${name} must be a positive integer`);
-	}
-	return raw;
-}
-
-function applyStickyProxySession(proxyUrl: string): string {
-	let parsed: URL;
-	try {
-		parsed = new URL(proxyUrl);
-	} catch {
-		return proxyUrl;
-	}
-
-	if (!parsed.hostname || !parsed.username || !parsed.password) {
-		return proxyUrl;
-	}
-
-	// This rewrites sticky-session usernames for a bring-your-own *gateway* URL
-	// (APIFUSE__PROXY__URL). The `smartproxy` host here means a smartproxy.com /
-	// Decodo-family gateway that authenticates by username — NOT the
-	// api.smartproxy.org allocation vendor, whose endpoints are raw ip:port with
-	// no credentials and therefore return early above.
-	const host = parsed.hostname.toLowerCase();
-	if (!host.includes("smartproxy") && !host.includes("decodo")) {
-		return proxyUrl;
-	}
-
-	const username = decodeURIComponent(parsed.username);
-	const sessionId = process.env.APIFUSE__PROXY__SESSION_ID?.trim() || "apifuse-shared";
-	const sessionDuration = readPositiveIntegerEnv("APIFUSE__PROXY__SESSION_DURATION");
-	const stickyUsername = host.includes("smartproxy")
-		? buildSmartproxyUsername(username, sessionId, sessionDuration)
-		: buildDecodoUsername(username, sessionId, sessionDuration ?? "60");
-
-	parsed.username = stickyUsername;
-	return parsed.toString();
-}
-
-function buildSmartproxyUsername(
-	username: string,
-	sessionId: string,
-	sessionDuration?: string,
-): string {
-	const parts = username.split("_");
-	const configuredLife = parts.find((part) => part.startsWith("life-"))?.slice("life-".length);
-	const baseUsername = parts
-		.filter((part) => !part.startsWith("session-") && !part.startsWith("life-"))
-		.join("_");
-	return `${baseUsername}_session-${sessionId}_life-${sessionDuration ?? configuredLife ?? "60"}`;
-}
-
-function buildDecodoUsername(username: string, sessionId: string, sessionDuration: string): string {
-	const withoutSticky = username.replace(/-session-.+-sessionduration-\d+$/, "");
-	const baseUsername = withoutSticky.startsWith("user-") ? withoutSticky : `user-${withoutSticky}`;
-	return `${baseUsername}-session-${sessionId}-sessionduration-${sessionDuration}`;
-}
-
-function syncProxyEnv(config: ApiFuseConfig): void {
-	const configProxyUrl = normalizeProxyUrl(config.proxy?.url);
-	if (!process.env.APIFUSE__PROXY__URL && configProxyUrl) {
-		process.env.APIFUSE__PROXY__URL = configProxyUrl;
-	}
+	return normalized || undefined;
 }
 
 export function resolveProxyConfig(options: ProxyResolutionOptions = {}): ResolvedProxyConfig {
@@ -532,16 +453,6 @@ export function resolveProxyConfig(options: ProxyResolutionOptions = {}): Resolv
 		return { shouldWarn: false };
 	}
 
-	const envProxyUrl = normalizeProxyUrl(process.env.APIFUSE__PROXY__URL);
-	if (envProxyUrl) {
-		return { shouldWarn: false, url: envProxyUrl };
-	}
-
-	const configuredProxyUrl = normalizeProxyUrl(options.apifuseConfig?.proxy?.url);
-	if (configuredProxyUrl) {
-		return { shouldWarn: false, url: configuredProxyUrl };
-	}
-
 	return { shouldWarn: true };
 }
 
@@ -563,7 +474,22 @@ export async function resolveProxyConfigAsync(
 
 	const chain = resolveVendorChain(policy);
 	if (chain.length === 0) {
-		// decodo/custom/env-static providers keep the legacy static-URL path.
+		const declared = declaredVendorChain(policy);
+		const deprecated = declared.filter((vendor) => vendor === "decodo" || vendor === "custom");
+		if (policy.mode === "required") {
+			const providerIds =
+				declared.length > 0 ? declared.map((vendor) => `"${vendor}"`).join(", ") : "none";
+			const deprecatedDetail =
+				deprecated.length > 0
+					? ` Deprecated vendor(s): ${deprecated.map((vendor) => `"${vendor}"`).join(", ")}.`
+					: "";
+			throw new ProxyResolutionError(
+				"PROXY_REQUIRED",
+				`Required proxy policy has no SDK-managed adapter for provider id(s): ${providerIds}.${deprecatedDetail} Use "smartproxy" or "nodemaven".`,
+			);
+		}
+		// Deprecated decodo/custom providers have no SDK-managed adapter. Optional
+		// policies preserve the warning-only behavior and may continue directly.
 		return resolveProxyConfig({
 			...options,
 			upstream: { proxy: true },
@@ -842,18 +768,22 @@ function isRegistryVendor(name: string | undefined): name is ProxyVendorName {
 	return name === "smartproxy" || name === "nodemaven";
 }
 
+function declaredVendorChain(policy: ProviderProxyPolicy): ProviderProxyProvider[] {
+	const declared = policy.providers?.length
+		? policy.providers
+		: [policy.provider ?? envDefaultProvider()];
+	return declared.filter((vendor): vendor is ProviderProxyProvider => vendor !== undefined);
+}
+
 /**
  * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
  * takes precedence over the legacy singular `provider`; the platform default
  * env is the final fallback. Non-registry names (decodo/custom) are dropped so
- * an all-static chain falls through to the legacy env-URL path unchanged.
+ * an all-deprecated chain has no managed adapter.
  */
 export function resolveVendorChain(policy: ProviderProxyPolicy): ProxyVendorName[] {
-	const declared: (ProviderProxyProvider | undefined)[] = policy.providers?.length
-		? policy.providers
-		: [policy.provider ?? envDefaultProvider()];
 	const chain: ProxyVendorName[] = [];
-	for (const name of declared) {
+	for (const name of declaredVendorChain(policy)) {
 		if (isRegistryVendor(name) && !chain.includes(name)) {
 			chain.push(name);
 		}
@@ -924,9 +854,8 @@ const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"
  *  - the method is safe/idempotent — an unsafe request must never be duplicated
  *    across the pool even if some framework default would allow it;
  *  - the policy resolves a non-empty *registry* vendor chain (smartproxy /
- *    nodemaven). Static vendors (custom / decodo) and credential-less policies
- *    resolve no allocator pool, so every attempt would hit the same endpoint
- *    with no possible crossover — they keep the retry budget.
+ *    nodemaven). Deprecated vendors (custom / decodo) resolve no managed pool,
+ *    so there is no possible endpoint crossover — they keep the retry budget.
  *
  * The widened cap is bounded by the chain's true maximum span (sum of each
  * vendor's max pool size), so a large NodeMaven pool (≤50) stays reachable and
@@ -945,8 +874,8 @@ const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"
  *    endpoint each attempt resolves (even a repeated one), so no de-duplication;
  *  - the method is safe/idempotent — an unsafe request is never duplicated;
  *  - the policy resolves a non-empty registry vendor chain (smartproxy /
- *    nodemaven). Static vendors (custom / decodo) resolve the same URL every
- *    attempt, so there is nothing to rotate or de-duplicate.
+ *    nodemaven). Deprecated vendors (custom / decodo) resolve no managed
+ *    endpoint, so there is nothing to rotate or de-duplicate.
  */
 export function policyRotatesTransportVendorChain(input: {
 	policy: ProviderProxyPolicy | undefined;
@@ -989,9 +918,8 @@ export function resolvePolicyTransportAttemptCap(input: {
  * A registry vendor chain (smartproxy/nodemaven) resolves a potentially
  * *different* endpoint per flat attempt index, so a transport retry should
  * advance across endpoints and de-duplicate once the chain stops yielding new
- * ones. Static/custom/decodo policies (empty registry chain) resolve the *same*
- * URL every attempt by design — retrying that same endpoint is intended, so the
- * transport loop must not de-duplicate them.
+ * ones. Deprecated custom/decodo policies have an empty registry chain and no
+ * managed endpoint, so the transport loop has nothing to rotate or de-duplicate.
  */
 export function policyResolvesRegistryVendorChain(
 	policy: ProviderProxyPolicy | undefined,
@@ -1828,17 +1756,13 @@ export async function loadApiFuseConfig(dir: string = process.cwd()): Promise<Ap
 	const tsPath = path.resolve(dir, "apifuse.config.ts");
 	if (existsSync(tsPath)) {
 		const config = await importConfig(tsPath);
-		const resolvedConfig = config ?? {};
-		syncProxyEnv(resolvedConfig);
-		return resolvedConfig;
+		return config ?? {};
 	}
 
 	const jsPath = path.resolve(dir, "apifuse.config.js");
 	if (existsSync(jsPath)) {
 		const config = await importConfig(jsPath);
-		const resolvedConfig = config ?? {};
-		syncProxyEnv(resolvedConfig);
-		return resolvedConfig;
+		return config ?? {};
 	}
 
 	return {};

package/src/contract-types.ts

@@ -13,6 +13,7 @@ export interface ProviderContractSnapshot {
 	readonly allowedHosts?: readonly string[];
 	readonly stealth?: JsonValue;
 	readonly proxy?: JsonValue;
+	readonly ocr?: JsonValue;
 	readonly stt?: JsonValue;
 	readonly browser?: JsonValue;
 	readonly auth?: JsonValue;

package/src/contract.ts

@@ -35,6 +35,7 @@ export function extractProviderContract(provider: ProviderDefinition): ProviderC
 	const auth = extractAuth(provider.auth);
 	const stealth = toJsonValue(provider.stealth);
 	const proxy = toJsonValue(provider.proxy);
+	const ocr = toJsonValue(provider.ocr);
 	const stt = toJsonValue(provider.stt);
 	const browser = toJsonValue(provider.browser);
 	const reviewed = toJsonValue(provider.reviewed);
@@ -59,6 +60,7 @@ export function extractProviderContract(provider: ProviderDefinition): ProviderC
 		...(provider.allowedHosts ? { allowedHosts: [...provider.allowedHosts].sort() } : {}),
 		...(stealth === undefined ? {} : { stealth }),
 		...(proxy === undefined ? {} : { proxy }),
+		...(ocr === undefined ? {} : { ocr }),
 		...(stt === undefined ? {} : { stt }),
 		...(browser === undefined ? {} : { browser }),
 		...(auth === undefined ? {} : { auth }),

package/src/define.ts

@@ -20,20 +20,24 @@ import type {
 	HealthJourneySchedule,
 	HealthScheduleRandomization,
 	InferSchemaOutput,
+	NativeProviderConfig,
 	OperationDefinition,
 	OperationHandlerResult,
 	OperationHttpStreamTransport,
 	OperationSseTransport,
 	OperationTransport,
 	OperationWebSocketTransport,
-	NativeProviderConfig,
 	ProviderAccessConfig,
+	ProviderChallengeKind,
 	ProviderDefinition,
+	ProviderOcrConfig,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
 	ProviderProxyConfig,
 	ProviderProxyProvider,
 	ProviderPublicProfile,
+	ProviderResolverConfig,
+	ProviderResolverVendor,
 	ProviderReviewed,
 	ProviderSecretDeclaration,
 	ProviderStreamEvent,
@@ -123,7 +127,32 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 	"auth-flow",
 	"connection",
 ] as const;
+const VALID_PROVIDER_OCR_MODES = ["optional", "required"] as const;
 const VALID_PROVIDER_STT_MODES = ["optional", "required"] as const;
+function exhaustiveLiteralArray<TUnion extends string>() {
+	return <const TValues extends readonly TUnion[]>(
+		values: TValues,
+		..._missing: Exclude<TUnion, TValues[number]> extends never
+			? []
+			: ["Missing runtime values", Exclude<TUnion, TValues[number]>]
+	): TValues => values;
+}
+
+export const VALID_PROVIDER_RESOLVER_VENDORS = exhaustiveLiteralArray<ProviderResolverVendor>()([
+	"browser",
+	"capsolver",
+	"capmonster",
+	"2captcha",
+	"custom",
+] as const);
+export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderChallengeKind>()([
+	"turnstile",
+	"recaptcha_v2",
+	"recaptcha_v3",
+	"hcaptcha",
+	"cloudflare_interstitial",
+	"aws_waf",
+] as const);
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
 const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
@@ -132,9 +161,8 @@ const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
 // credential fails at build/validation time rather than during a live outage: a
 // declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
 // exactly the failure class the multi-vendor chain exists to remove. Vendors
-// absent from this map (e.g. `custom`/`decodo`, whose credentials come from the
-// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) impose
-// no declaration requirement.
+// absent from this map (the deprecated `custom`/`decodo` values have no managed
+// adapter) impose no declaration requirement.
 const VENDOR_REQUIRED_SECRETS: Partial<Record<ProviderProxyProvider, readonly string[]>> = {
 	smartproxy: [SMARTPROXY_APP_KEY_SECRET],
 	nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
@@ -248,7 +276,9 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 		platform: StealthPlatform;
 	};
 	proxy?: ProviderProxyConfig;
+	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
+	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
 	reviewed?: ProviderReviewed;
@@ -678,9 +708,21 @@ function validateProviderProxy(config: {
 	const deprecatedVendors = vendorChain.filter(
 		(vendor) => vendor === "decodo" || vendor === "custom",
 	);
+	if (
+		proxy.mode === "required" &&
+		vendorChain.length > 0 &&
+		deprecatedVendors.length === vendorChain.length
+	) {
+		throw new ValidationError(
+			`Provider "${config.id}" requires proxy egress but declares only deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}.`,
+			{
+				fix: `Use proxy.provider or proxy.providers with "smartproxy" and/or "nodemaven".`,
+			},
+		);
+	}
 	if (deprecatedVendors.length > 0) {
 		console.warn(
-			`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven", or the APIFUSE__PROXY__URL bring-your-own escape hatch.`,
+			`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven".`,
 		);
 	}
 }
@@ -697,6 +739,65 @@ function validateProviderStt(config: { id: string; stt?: ProviderSttConfig }): v
 	assertLiteralField(stt.mode, "stt.mode", VALID_PROVIDER_STT_MODES, config.id);
 }
 
+function validateProviderOcr(config: { id: string; ocr?: ProviderOcrConfig }): void {
+	const ocr = config.ocr;
+	if (ocr === undefined) return;
+	if (!ocr || typeof ocr !== "object" || Array.isArray(ocr)) {
+		throw new ValidationError(`Provider "${config.id}" has invalid ocr: must be an object.`, {
+			fix: `Use ocr: { mode: "required" } or ocr: { mode: "optional" }.`,
+		});
+	}
+	rejectUnknownFields(ocr, new Set(["mode"]), "ocr");
+	assertLiteralField(ocr.mode, "ocr.mode", VALID_PROVIDER_OCR_MODES, config.id);
+}
+
+function validateProviderResolver(config: { id: string; resolver?: ProviderResolverConfig }): void {
+	const resolver = config.resolver;
+	if (resolver === undefined) return;
+	if (!resolver || typeof resolver !== "object" || Array.isArray(resolver)) {
+		throw new ValidationError(`Provider "${config.id}" has invalid resolver: must be an object.`, {
+			fix: `Set resolver for provider "${config.id}" to { vendors: ["2captcha"], kinds: ["turnstile"] }.`,
+		});
+	}
+	rejectUnknownFields(resolver, new Set(["vendors", "kinds"]), "resolver", config.id);
+	validateResolverLiteralArray(
+		resolver.vendors,
+		"resolver.vendors",
+		VALID_PROVIDER_RESOLVER_VENDORS,
+		config.id,
+	);
+	validateResolverLiteralArray(
+		resolver.kinds,
+		"resolver.kinds",
+		VALID_PROVIDER_CHALLENGE_KINDS,
+		config.id,
+	);
+}
+
+function validateResolverLiteralArray<TValue extends string>(
+	value: readonly TValue[],
+	field: string,
+	validValues: readonly TValue[],
+	providerId: string,
+): void {
+	if (!Array.isArray(value)) {
+		throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an array.`, {
+			fix: `Set ${field} for provider "${providerId}" to an array containing only: ${validValues.join(", ")}.`,
+		});
+	}
+	for (const [index, item] of value.entries()) {
+		if (typeof item === "string" && validValues.some((validValue) => validValue === item)) {
+			continue;
+		}
+		throw new ValidationError(
+			`Provider "${providerId}" has invalid ${field}[${index}]: ${JSON.stringify(item)}. Expected one of: ${validValues.join(", ")}`,
+			{
+				fix: `Set ${field}[${index}] for provider "${providerId}" to one of ${validValues.map((validValue) => `"${validValue}"`).join(", ")}.`,
+			},
+		);
+	}
+}
+
 function validateOperationIds(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
@@ -1294,7 +1395,12 @@ function suggestField(unknown: string, candidates: ReadonlySet<string>): string
 	return best;
 }
 
-function rejectUnknownFields(value: object, allowed: ReadonlySet<string>, fieldPath: string): void {
+function rejectUnknownFields(
+	value: object,
+	allowed: ReadonlySet<string>,
+	fieldPath: string,
+	providerId?: string,
+): void {
 	for (const key of Object.keys(value)) {
 		if (allowed.has(key)) continue;
 		const hint = suggestField(key, allowed);
@@ -1302,7 +1408,11 @@ function rejectUnknownFields(value: object, allowed: ReadonlySet<string>, fieldP
 			hint
 				? `Unknown field "${key}" on ${fieldPath}. Did you mean "${hint}"?`
 				: `Unknown field "${key}" on ${fieldPath}.`,
-			{ fix: `Remove ${fieldPath}.${key} or rename it.` },
+			{
+				fix: providerId
+					? `Remove ${fieldPath}.${key} from provider "${providerId}" or rename it.`
+					: `Remove ${fieldPath}.${key} or rename it.`,
+			},
 		);
 	}
 }
@@ -2386,7 +2496,9 @@ export function defineProvider<
 		throw error;
 	}
 	validateProviderProxy(config);
+	validateProviderOcr(config);
 	validateProviderStt(config);
+	validateProviderResolver(config);
 	if (config.runtime === "browser" && !config.browser)
 		throw new ProviderError(
 			`Provider "${config.id}" must define browser.engine when runtime is "browser"`,
@@ -2410,7 +2522,9 @@ export function defineProvider<
 		native: config.native,
 		stealth: config.stealth,
 		proxy: config.proxy,
+		ocr: config.ocr,
 		stt: config.stt,
+		resolver: config.resolver,
 		browser: config.browser,
 		auth: config.auth,
 		reviewed: config.reviewed,

package/src/error-resolution.ts

@@ -30,6 +30,7 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"flow_expired",
 	"turn_validation_error",
 	"context_access_error",
+	"OCR_UPSTREAM_FAILED",
 	"UNSUPPORTED_STT_OPTION",
 	"INVALID_STT_AUDIO",
 	"STT_AUDIO_TOO_LARGE",
@@ -85,6 +86,8 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
 	...SDK_OWNED_PROVIDER_ERROR_CODES,
 	"reauth_required",
+	"OCR_UNAVAILABLE",
+	"UNSUPPORTED_OCR_BACKEND",
 	"STT_UNAVAILABLE",
 	"UNSUPPORTED_STT_BACKEND",
 	"OUTPUT_VALIDATION_FAILED",
@@ -116,6 +119,8 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		["UPSTREAM_REJECTED", 409],
 		["UPSTREAM_ERROR", 502],
 		["BLOCKED", 502],
+		["OCR_UNAVAILABLE", 503],
+		["UNSUPPORTED_OCR_BACKEND", 503],
 		["STT_UNAVAILABLE", 503],
 		["UNSUPPORTED_STT_BACKEND", 503],
 		["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],

package/src/index.ts

@@ -6,7 +6,6 @@ export * from "./choice-token.js";
 export type {
 	ApiFuseConfig,
 	BrowserConfig,
-	ProxyConfig,
 	ProxyProtocol,
 	ProxyResolutionOptions,
 	ProxyResolutionSource,
@@ -101,6 +100,18 @@ export {
 } from "./runtime/instrumentation.js";
 export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export {
+	APIFUSE__CDP_POOL__URL,
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__TIMEOUT_MS,
+	createResolverClientFromEnv,
+	createUnsupportedResolverClient,
+	DEFAULT_RESOLVER_TIMEOUT_MS,
+	invalidateResolverSolution,
+	type ResolverRuntimeOptions,
+} from "./runtime/resolver.js";
 export {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -111,6 +122,22 @@ export {
 	UnsupportedProviderStateError,
 } from "./runtime/state.js";
 export { createStealthClient } from "./runtime/stealth.js";
+export {
+	APIFUSE__OCR__API_KEY_ENV,
+	APIFUSE__OCR__BACKEND_ENV,
+	APIFUSE__OCR__BASE_URL_ENV,
+	APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV,
+	APIFUSE__OCR__MODEL_ENV,
+	CLOUDFLARE_ACCOUNT_ID_ENV,
+	CLOUDFLARE_WORKERS_AI_OCR_BACKEND,
+	createCloudflareWorkersAiOcrClient,
+	createOcrClientFromEnv,
+	createOpenAiCompatibleOcrClient,
+	createUnsupportedOcrClient,
+	DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL,
+	extractCaptchaCandidates,
+	OPENAI_COMPATIBLE_OCR_BACKEND,
+} from "./runtime/ocr.js";
 export {
 	APIFUSE__STT__BACKEND_ENV,
 	APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV,
@@ -161,6 +188,7 @@ export type {
 	AuthMode,
 	AuthTurn,
 	Bcp47Locale,
+	BrowserCookie,
 	BrowserEngine,
 	BrowserOptions,
 	BrowserResourceBody,
@@ -169,6 +197,7 @@ export type {
 	BrowserResourcePolicy,
 	BrowserResourceRequest,
 	BrowserResourceRoute,
+	ChallengeSolution,
 	ConnectionMode,
 	ContextDeclaration,
 	CookieJar,
@@ -229,6 +258,14 @@ export type {
 	NativeTcpPortRange,
 	NativeTcpTlsMode,
 	NativeTlsConnectOptions,
+	OcrCaptchaCandidate,
+	OcrCaptchaOptions,
+	OcrCaptchaResult,
+	OcrContext,
+	OcrImageInput,
+	OcrRecognizeRequest,
+	OcrResult,
+	OcrWarning,
 	OperationAnnotations,
 	OperationApprovalPolicy,
 	OperationContractMetadata,
@@ -261,6 +298,8 @@ export type {
 	ProviderChoiceContext,
 	ProviderChoiceIssueOptions,
 	ProviderChoiceParseOptions,
+	ProviderChallenge,
+	ProviderChallengeKind,
 	ProviderContext,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
@@ -274,6 +313,7 @@ export type {
 	ProviderLogoProfile,
 	ProviderLogoSource,
 	ProviderMeta,
+	ProviderOcrConfig,
 	ProviderProxyConfig,
 	ProviderProxyMode,
 	ProviderProxyPolicy,
@@ -284,6 +324,8 @@ export type {
 	ProviderPublicProfile,
 	ProviderReviewed,
 	ProviderResolvedFile,
+	ProviderResolverConfig,
+	ProviderResolverVendor,
 	ProviderRuntimeState,
 	ProviderSecretDeclaration,
 	ProviderStateDurationString,
@@ -294,6 +336,7 @@ export type {
 	ProviderSupportLevel,
 	RequestOptions,
 	RedirectRunReason,
+	ResolverContext,
 	Rfc3339Instant,
 	SchemaLike,
 	SmsOrigin,
@@ -303,6 +346,7 @@ export type {
 	StandardSchemaV1,
 	StateCasResult,
 	StateNamespaceOptions,
+	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
 	StealthClient,

package/src/provider.ts

@@ -162,6 +162,7 @@ export type {
 	StandardSchemaV1,
 	StateCasResult,
 	StateNamespaceOptions,
+	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
 } from "./types.js";

package/src/runtime/auth-flow.ts

@@ -5,9 +5,12 @@ import type {
 	EnvContext,
 	FlowContext,
 	HttpClient,
+	OcrContext,
 	StealthClient,
 	SttContext,
 } from "../types.js";
+import { createUnsupportedOcrClient } from "./ocr.js";
+import { createUnsupportedResolverClient } from "./resolver.js";
 import { createUnsupportedSttClient } from "./stt.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
@@ -58,6 +61,7 @@ export function createFlowContext(options: {
 	externalRef?: string;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
+	ocr?: OcrContext;
 	stt?: SttContext;
 }): FlowContext {
 	return {
@@ -70,7 +74,9 @@ export function createFlowContext(options: {
 		stealth: options.stealth,
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),
+		ocr: options.ocr ?? createUnsupportedOcrClient(),
 		stt: options.stt ?? createUnsupportedSttClient(),
+		resolver: createUnsupportedResolverClient("Resolver is not available in auth flow context"),
 		auth: createAuthFlowHelpers(),
 	};
 }