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

package/src/runtime/stt.ts

@@ -14,6 +14,7 @@ import type {
 	VerificationCodeCandidateSource,
 	VerificationCodeExtractionResult,
 } from "../types.js";
+import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
 
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
@@ -169,15 +170,6 @@ function normalizeCloudflareLanguage(language: Bcp47Locale | undefined): string
 	return language?.split("-")[0]?.toLowerCase();
 }
 
-function isTimeoutLikeError(error: unknown): error is Error {
-	return (
-		error instanceof Error &&
-		(error.name === "AbortError" ||
-			error.name === "TimeoutError" ||
-			/\b(timed out|timeout|deadline exceeded)\b/i.test(error.message))
-	);
-}
-
 function toSttTransportError(error: unknown): TransportError {
 	if (error instanceof TransportError) return error;
 	if (isTimeoutLikeError(error)) {
@@ -194,16 +186,6 @@ function toSttTransportError(error: unknown): TransportError {
 	});
 }
 
-function createTimeoutController(signalTimeoutMs: number): {
-	controller: AbortController;
-	clear: () => void;
-} {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
-	timeout.unref?.();
-	return { controller, clear: () => clearTimeout(timeout) };
-}
-
 function toCloudflareInput(request: SttTranscribeRequest): Record<string, unknown> {
 	const prompt = resolveSttPrompt(request);
 	const input: Record<string, unknown> = {

package/src/runtime/timeout.ts

@@ -0,0 +1,18 @@
+export function isTimeoutLikeError(error: unknown): error is Error {
+	return (
+		error instanceof Error &&
+		(error.name === "AbortError" ||
+			error.name === "TimeoutError" ||
+			/\b(timed out|timeout|deadline exceeded)\b/i.test(error.message))
+	);
+}
+
+export function createTimeoutController(signalTimeoutMs: number): {
+	controller: AbortController;
+	clear: () => void;
+} {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
+	timeout.unref?.();
+	return { controller, clear: () => clearTimeout(timeout) };
+}

package/src/server/serve.ts

@@ -7,6 +7,7 @@ import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import {
 	SDK_OWNED_PROVIDER_ERROR_CODES,
 	SDK_RUNTIME_OWNED_ERROR_CODES,
+	SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES,
 } from "../error-resolution.js";
 import {
 	AuthError,
@@ -47,6 +48,7 @@ import {
 	createNativeNetworkClient,
 } from "../runtime/native-network.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
+import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import {
 	PROXY_AUTH_IP_DENIED_CODE,
 	PROXY_EDGE_AUTH_REJECTED_CODE,
@@ -91,6 +93,7 @@ import type {
 	OperationErrorCode,
 	OperationHttpStreamTransport,
 	OperationSseTransport,
+	OcrContext,
 	ProviderErrorStatus,
 	ProviderContext,
 	ProviderDefinition,
@@ -388,6 +391,7 @@ function createProviderContext(
 			: {}),
 		trace: createTraceContext(),
 		auth: createAuthStub(),
+		ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
 		stt: options.stt ?? createSttClientFromEnv(provider.stt),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,
@@ -511,6 +515,7 @@ function createAuthFlowContext(
 			]),
 			credential,
 			context: flowContextStore.context,
+			ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
 			stt: options.stt ?? createSttClientFromEnv(provider.stt),
 			auth: createAuthFlowHelpers({ signal }),
 		},
@@ -595,6 +600,8 @@ export type ProviderServerOptions = {
 	};
 	/** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
 	stt?: SttContext;
+	/** Optional OCR override for tests or custom hosts; local/prod normally resolves from env. */
+	ocr?: OcrContext;
 	/** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
 	state?: ProviderRuntimeState;
 	/** Allow process-local runtime state only for local development and tests. */
@@ -948,34 +955,13 @@ function toStatusCode(error: unknown, declaredErrorCode?: OperationErrorCode): P
 		) {
 			return declaredErrorCode.status;
 		}
-		switch (error.code) {
-			case "AUTH_REQUIRED":
-			case "reauth_required":
-				return 401;
-			// Unprovisioned declared secret: a deployment/config defect, never an
-			// upstream failure — explicit 400 (was only reached via fallthrough).
-			case MISSING_SECRET_CODE:
-				return 400;
-			case "NOT_FOUND":
-			case "not_found":
-			case "NO_DATA":
-				return 404;
-			case "RATE_LIMITED":
-			case "UPSTREAM_RATE_LIMIT":
-			case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
-				return 429;
-			// Deterministic upstream business refusal (honest-provider-error-
-			// contract): the upstream evaluated the request and said no under
-			// its own rules — a conflict with upstream state, never a 5xx.
-			case "UPSTREAM_REJECTED":
-				return 409;
-			case "UPSTREAM_ERROR":
-			case "BLOCKED":
-				return 502;
-			case "STT_UNAVAILABLE":
-			case "UNSUPPORTED_STT_BACKEND":
-			case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
-				return 503;
+		// Canonical SDK code → status mapping lives in error-resolution.ts so
+		// the authoring lint and this runtime path share one source of truth.
+		if (typeof error.code === "string") {
+			const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(error.code);
+			if (mappedStatus !== undefined) {
+				return mappedStatus;
+			}
 		}
 		if (isTransportError(error)) {
 			return error.code === "transport_timeout" ? 504 : 502;
@@ -2401,6 +2387,7 @@ export async function serve(
 
 	const app = createServerApp(provider, {
 		logger: options.logger,
+		ocr: options.ocr,
 		stt: options.stt,
 		state: options.state,
 		allowMemoryStateFallback: options.allowMemoryStateFallback,

package/src/testing/run.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "bun:test";
 import { createProviderCache } from "../runtime/cache.js";
 import { createTestProviderChoiceContext } from "../runtime/choice.js";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
+import { createUnsupportedOcrClient } from "../runtime/ocr.js";
 import { createUnsupportedSttClient } from "../runtime/stt.js";
 import {
 	createNativeEgressAuthorization,
@@ -559,6 +560,9 @@ function createUpstreamContext(
 			: {}),
 		trace: { span: async (_name, fn) => fn() },
 		auth: { requestField: async (name) => unsupported(`ctx.auth.requestField(${name})`) },
+		ocr: createUnsupportedOcrClient(
+			"Standard test upstream context does not support ctx.ocr.recognize",
+		),
 		stt: createUnsupportedSttClient(
 			"Standard test upstream context does not support ctx.stt.transcribe",
 		),
@@ -684,6 +688,9 @@ export function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		auth: {
 			requestField: async (name) => unsupported(`ctx.auth.requestField(${name})`),
 		},
+		ocr: createUnsupportedOcrClient(
+			"Standard test snapshot context does not support ctx.ocr.recognize",
+		),
 		stt: createUnsupportedSttClient(
 			"Standard test snapshot context does not support ctx.stt.transcribe",
 		),

package/src/types.ts

@@ -243,6 +243,61 @@ export interface SmsOtpMatcherDefinition {
 	extractOtp(body: string): string | null;
 }
 
+export interface ProviderOcrConfig {
+	readonly mode: "required" | "optional";
+}
+
+export type OcrImageInput =
+	| { readonly kind: "base64"; readonly data: string; readonly mediaType?: string }
+	| { readonly kind: "url"; readonly url: string };
+
+export interface OcrRecognizeRequest {
+	readonly image: OcrImageInput;
+	readonly hint?: "captcha" | "document" | "generic";
+	readonly prompt?: string;
+	readonly maxTokens?: number;
+	readonly timeoutMs?: number;
+}
+
+export interface OcrWarning {
+	readonly code: string;
+	readonly message: string;
+}
+
+export interface OcrResult {
+	readonly text: string;
+	readonly model: string;
+	readonly warnings?: readonly OcrWarning[];
+}
+
+export interface OcrCaptchaOptions {
+	readonly length?: number;
+	/** Allowed characters. A RegExp is applied to each character, not to the whole text. */
+	readonly charset?: string | RegExp;
+	readonly caseSensitive?: boolean;
+	readonly maxCandidates?: number;
+}
+
+export interface OcrCaptchaCandidate {
+	readonly text: string;
+	readonly satisfiesConstraints: boolean;
+}
+
+export interface OcrCaptchaResult {
+	readonly text: string;
+	readonly candidates: readonly OcrCaptchaCandidate[];
+	readonly satisfiesConstraints: boolean;
+	readonly model: string;
+}
+
+export interface OcrContext {
+	recognize(request: OcrRecognizeRequest): Promise<OcrResult>;
+	extractCaptchaText(
+		image: OcrImageInput,
+		options?: OcrCaptchaOptions,
+	): Promise<OcrCaptchaResult>;
+}
+
 export type SttTranscribeMode = "general" | "otp";
 export type SttPromptPolicy = "none" | "default-hint" | "custom-hint";
 export type SttUnsupportedOptionPolicy = "warn" | "error";
@@ -1889,6 +1944,7 @@ export interface FlowContext {
 	env: EnvContext;
 	credential?: CredentialContext;
 	context: ContextScratchpad;
+	ocr: OcrContext;
 	stt: SttContext;
 	auth: AuthFlowTerminalContext;
 }
@@ -2014,6 +2070,7 @@ export interface ProviderContext {
 	browser: BrowserClient;
 	trace: TraceContext;
 	auth: AuthContext;
+	ocr: OcrContext;
 	stt: SttContext;
 	choice: ProviderChoiceContext;
 }
@@ -2187,6 +2244,7 @@ export interface ProviderDefinition {
 		platform: StealthPlatform;
 	};
 	proxy?: ProviderProxyConfig;
+	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
 	browser?: {
 		engine: BrowserEngine;