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

package/src/define.ts

@@ -27,6 +27,7 @@ import type {
 	OperationTransport,
 	OperationWebSocketTransport,
 	NativeProviderConfig,
+	ProviderOcrConfig,
 	ProviderAccessConfig,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
@@ -123,6 +124,7 @@ 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;
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
@@ -248,6 +250,7 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 		platform: StealthPlatform;
 	};
 	proxy?: ProviderProxyConfig;
+	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
@@ -697,6 +700,18 @@ 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 validateOperationIds(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
@@ -2386,6 +2401,7 @@ export function defineProvider<
 		throw error;
 	}
 	validateProviderProxy(config);
+	validateProviderOcr(config);
 	validateProviderStt(config);
 	if (config.runtime === "browser" && !config.browser)
 		throw new ProviderError(
@@ -2410,6 +2426,7 @@ export function defineProvider<
 		native: config.native,
 		stealth: config.stealth,
 		proxy: config.proxy,
+		ocr: config.ocr,
 		stt: config.stt,
 		browser: config.browser,
 		auth: config.auth,

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

@@ -111,6 +111,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,
@@ -229,6 +245,14 @@ export type {
 	NativeTcpPortRange,
 	NativeTcpTlsMode,
 	NativeTlsConnectOptions,
+	OcrCaptchaCandidate,
+	OcrCaptchaOptions,
+	OcrCaptchaResult,
+	OcrContext,
+	OcrImageInput,
+	OcrRecognizeRequest,
+	OcrResult,
+	OcrWarning,
 	OperationAnnotations,
 	OperationApprovalPolicy,
 	OperationContractMetadata,
@@ -274,6 +298,7 @@ export type {
 	ProviderLogoProfile,
 	ProviderLogoSource,
 	ProviderMeta,
+	ProviderOcrConfig,
 	ProviderProxyConfig,
 	ProviderProxyMode,
 	ProviderProxyPolicy,

package/src/runtime/auth-flow.ts

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

package/src/runtime/browser.ts

@@ -42,19 +42,35 @@ type PoolReleaseRequest = {
 	pageId: string;
 };
 
-type JsonRpcId = number;
+type WebSocketCommandId = number;
 
-type JsonRpcError = {
+type WebSocketCommandError = {
 	code?: number;
 	message?: string;
 };
 
-type JsonRpcMessage = {
-	error?: JsonRpcError;
-	id?: JsonRpcId;
+type WebSocketCommandMessage = {
+	error?: WebSocketCommandError;
+	id?: WebSocketCommandId;
+	jsonrpc?: "2.0";
 	method?: string;
 	params?: Record<string, unknown>;
 	result?: Record<string, unknown>;
+	sessionId?: string;
+};
+
+type CdpCommandFrame = {
+	id: WebSocketCommandId;
+	method: string;
+	params: Record<string, unknown>;
+	sessionId?: string;
+};
+
+type JsonRpcCommandFrame = {
+	id: WebSocketCommandId;
+	jsonrpc: "2.0";
+	method: string;
+	params: Record<string, unknown>;
 };
 
 type CdpFrameTreeNode = {
@@ -641,12 +657,12 @@ function normalizeWebSocketEndpoint(endpoint: string): string {
 	throw new Error(`Unsupported WebSocket endpoint protocol: ${url.protocol}`);
 }
 
-class JsonRpcWebSocketClient {
+abstract class WebSocketCommandClient {
 	private nextId = 1;
 	private readonly endpoint: string;
 	private readonly listeners = new Map<string, Set<(params: unknown) => void>>();
 	private readonly pending = new Map<
-		JsonRpcId,
+		WebSocketCommandId,
 		{
 			reject: (reason?: unknown) => void;
 			resolve: (value: Record<string, unknown>) => void;
@@ -682,14 +698,7 @@ class JsonRpcWebSocketClient {
 		return await new Promise<Record<string, unknown>>((resolve, reject) => {
 			this.pending.set(id, { resolve, reject });
 
-			socket.send(
-				JSON.stringify({
-					id,
-					jsonrpc: "2.0",
-					method,
-					params,
-				}),
-			);
+			socket.send(JSON.stringify(this.createCommandFrame(id, method, params)));
 		});
 	}
 
@@ -705,6 +714,12 @@ class JsonRpcWebSocketClient {
 		this.socketPromise = undefined;
 	}
 
+	protected abstract createCommandFrame(
+		id: WebSocketCommandId,
+		method: string,
+		params: Record<string, unknown>,
+	): CdpCommandFrame | JsonRpcCommandFrame;
+
 	private async getSocket(): Promise<WebSocket> {
 		if (this.socket?.readyState === WebSocket.OPEN) {
 			return this.socket;
@@ -727,7 +742,7 @@ class JsonRpcWebSocketClient {
 					typeof event.data === "string"
 						? event.data
 						: Buffer.from(event.data as ArrayBufferLike).toString("utf8");
-				const payload = JSON.parse(rawData) as JsonRpcMessage;
+				const payload = JSON.parse(rawData) as WebSocketCommandMessage;
 
 				if (typeof payload.id === "number") {
 					const pending = this.pending.get(payload.id);
@@ -738,7 +753,11 @@ class JsonRpcWebSocketClient {
 					this.pending.delete(payload.id);
 
 					if (payload.error) {
-						pending.reject(new Error(payload.error.message ?? "JSON-RPC command failed"));
+						const error = new Error(payload.error.message ?? "JSON-RPC command failed");
+						if (typeof payload.error.code === "number") {
+							Object.assign(error, { code: payload.error.code });
+						}
+						pending.reject(error);
 						return;
 					}
 
@@ -774,6 +793,38 @@ class JsonRpcWebSocketClient {
 	}
 }
 
+class CdpWebSocketClient extends WebSocketCommandClient {
+	constructor(
+		endpoint: string,
+		private readonly sessionId?: string,
+	) {
+		super(endpoint);
+	}
+
+	protected createCommandFrame(
+		id: WebSocketCommandId,
+		method: string,
+		params: Record<string, unknown>,
+	): CdpCommandFrame {
+		return {
+			id,
+			method,
+			params,
+			...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
+		};
+	}
+}
+
+class JsonRpcWebSocketClient extends WebSocketCommandClient {
+	protected createCommandFrame(
+		id: WebSocketCommandId,
+		method: string,
+		params: Record<string, unknown>,
+	): JsonRpcCommandFrame {
+		return { id, jsonrpc: "2.0", method, params };
+	}
+}
+
 function flattenCdpFrameTree(
 	node: CdpFrameTreeNode | undefined,
 	out: CdpFrameTreeNode["frame"][] = [],
@@ -974,7 +1025,7 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 	constructor(
 		readonly pageId: string,
 		private readonly browserContextId: string | undefined,
-		private readonly pageClient: JsonRpcWebSocketClient,
+		private readonly pageClient: CdpWebSocketClient,
 		private readonly release: (request: PoolReleaseRequest) => Promise<void>,
 	) {}
 
@@ -1335,7 +1386,7 @@ class CdpPoolBrowserClient implements SupportedBrowserClient {
 				...(options?.isolatedContext ? { isolationMode: "browserContext" } : {}),
 			}),
 		);
-		const pageClient = new JsonRpcWebSocketClient(acquireResult.wsEndpoint);
+		const pageClient = new CdpWebSocketClient(acquireResult.wsEndpoint);
 		const page = new CdpPoolBrowserPage(
 			acquireResult.pageId,
 			acquireResult.browserContextId,