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

package/dist/runtime/ocr.js

@@ -0,0 +1,440 @@
+import { ProviderError, TransportError } from "../errors.js";
+import { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
+import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
+export { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
+export const APIFUSE__OCR__BACKEND_ENV = "APIFUSE__OCR__BACKEND";
+export const APIFUSE__OCR__MODEL_ENV = "APIFUSE__OCR__MODEL";
+export const APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV = "APIFUSE__OCR__CLOUDFLARE_API_TOKEN";
+export const APIFUSE__OCR__BASE_URL_ENV = "APIFUSE__OCR__BASE_URL";
+export const APIFUSE__OCR__API_KEY_ENV = "APIFUSE__OCR__API_KEY";
+export const CLOUDFLARE_WORKERS_AI_OCR_BACKEND = "cloudflare-workers-ai";
+export const OPENAI_COMPATIBLE_OCR_BACKEND = "openai-compatible";
+export const DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL = "@cf/google/gemma-4-26b-a4b-it";
+export const DEFAULT_OCR_TIMEOUT_MS = 30_000;
+const DEFAULT_CAPTCHA_MAX_TOKENS = 64;
+const DEFAULT_DOCUMENT_MAX_TOKENS = 4_096;
+const KIMI_MIN_MAX_TOKENS = 3_000;
+const DEFAULT_MAX_CAPTCHA_CANDIDATES = 3;
+const MAX_HOMOGLYPH_SEARCH_NODES = 512;
+const HOMOGLYPH_CLASSES = [
+    ["I", "l", "1", "i"],
+    ["O", "0", "o"],
+    ["S", "5", "s"],
+    ["Z", "2", "z"],
+    ["B", "8"],
+];
+const HINT_PROMPTS = {
+    captcha: "Read the CAPTCHA image. Return only the characters, with no explanation. Preserve character case.",
+    document: "Transcribe all visible text in the document image.",
+    generic: "Read and return the visible text in this image.",
+};
+function providerError(message, options) {
+    return new ProviderError(message, options);
+}
+function createErrorOcrClient(options) {
+    const unavailable = () => {
+        throw providerError(options.message, {
+            code: options.code,
+            fix: options.fix,
+        });
+    };
+    return {
+        async recognize() {
+            return unavailable();
+        },
+        async extractCaptchaText() {
+            return unavailable();
+        },
+    };
+}
+export function createUnsupportedOcrClient(reason) {
+    return createErrorOcrClient({
+        code: "OCR_UNAVAILABLE",
+        message: reason ?? "OCR runtime is not configured",
+        fix: `Configure ${APIFUSE__OCR__BACKEND_ENV} and ${APIFUSE__OCR__MODEL_ENV}; Cloudflare uses ${CLOUDFLARE_ACCOUNT_ID_ENV} and ${APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV}, while openai-compatible uses ${APIFUSE__OCR__BASE_URL_ENV} and optional ${APIFUSE__OCR__API_KEY_ENV}. Alternatively, provide a test OcrContext override.`,
+    });
+}
+function normalizedEnvValue(env, key) {
+    const value = env[key]?.trim();
+    return value ? value : undefined;
+}
+export function createOcrClientFromEnv(config, env = process.env) {
+    if (!config) {
+        return createUnsupportedOcrClient("Provider does not declare OCR capability");
+    }
+    const backend = normalizedEnvValue(env, APIFUSE__OCR__BACKEND_ENV) ?? CLOUDFLARE_WORKERS_AI_OCR_BACKEND;
+    const configuredModel = normalizedEnvValue(env, APIFUSE__OCR__MODEL_ENV);
+    if (backend === CLOUDFLARE_WORKERS_AI_OCR_BACKEND) {
+        const model = configuredModel ?? DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL;
+        const accountId = normalizedEnvValue(env, CLOUDFLARE_ACCOUNT_ID_ENV);
+        const apiToken = normalizedEnvValue(env, APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV);
+        if (!accountId || !apiToken) {
+            return createUnsupportedOcrClient(`OCR backend ${backend} requires ${CLOUDFLARE_ACCOUNT_ID_ENV} and ${APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV}`);
+        }
+        return createCloudflareWorkersAiOcrClient({ accountId, apiToken, model });
+    }
+    if (backend === OPENAI_COMPATIBLE_OCR_BACKEND) {
+        const baseUrl = normalizedEnvValue(env, APIFUSE__OCR__BASE_URL_ENV);
+        if (!baseUrl) {
+            return createUnsupportedOcrClient(`OCR backend ${backend} requires ${APIFUSE__OCR__BASE_URL_ENV}`);
+        }
+        if (!configuredModel) {
+            return createErrorOcrClient({
+                code: "OCR_UNAVAILABLE",
+                message: `OCR backend ${backend} requires ${APIFUSE__OCR__MODEL_ENV}`,
+                fix: `Set ${APIFUSE__OCR__MODEL_ENV} to the exact model ID served by your self-hosted endpoint, for example ${APIFUSE__OCR__MODEL_ENV}=zai-org/GLM-OCR.`,
+            });
+        }
+        return createOpenAiCompatibleOcrClient({
+            baseUrl,
+            apiKey: normalizedEnvValue(env, APIFUSE__OCR__API_KEY_ENV),
+            model: configuredModel,
+        });
+    }
+    return createErrorOcrClient({
+        code: "UNSUPPORTED_OCR_BACKEND",
+        message: `Unsupported OCR backend "${backend}"`,
+        fix: `Use ${APIFUSE__OCR__BACKEND_ENV}=${CLOUDFLARE_WORKERS_AI_OCR_BACKEND} or ${APIFUSE__OCR__BACKEND_ENV}=${OPENAI_COMPATIBLE_OCR_BACKEND}, or provide a custom OcrContext override.`,
+    });
+}
+function unknownRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    return Object.fromEntries(Object.entries(value));
+}
+function imageUrl(image) {
+    if (image.kind === "url")
+        return image.url.trim();
+    return `data:${image.mediaType?.trim() || "image/png"};base64,${image.data.trim()}`;
+}
+function resolvePrompt(request) {
+    return request.prompt ?? HINT_PROMPTS[request.hint ?? "generic"];
+}
+function isGemmaModel(model) {
+    return model.toLowerCase().includes("gemma");
+}
+function isKimiModel(model) {
+    return model.toLowerCase().includes("kimi");
+}
+function isMoondreamModel(model) {
+    return model.toLowerCase().includes("moondream");
+}
+function defaultMaxTokens(request) {
+    return request.hint === "captcha" ? DEFAULT_CAPTCHA_MAX_TOKENS : DEFAULT_DOCUMENT_MAX_TOKENS;
+}
+function resolvedMaxTokens(request, model = "") {
+    const requestedMaxTokens = request.maxTokens ?? defaultMaxTokens(request);
+    return isKimiModel(model)
+        ? Math.max(requestedMaxTokens, KIMI_MIN_MAX_TOKENS)
+        : requestedMaxTokens;
+}
+function messagesPayload(request, model) {
+    const payload = {
+        ...(model ? { model } : {}),
+        messages: [
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: resolvePrompt(request) },
+                    { type: "image_url", image_url: { url: imageUrl(request.image) } },
+                ],
+            },
+        ],
+        max_tokens: resolvedMaxTokens(request, model),
+        temperature: 0,
+    };
+    if (isGemmaModel(model ?? "")) {
+        payload.chat_template_kwargs = { enable_thinking: false };
+    }
+    return payload;
+}
+function cloudflareMessagesPayload(request, model) {
+    const payload = messagesPayload(request, model);
+    delete payload.model;
+    return payload;
+}
+function moondreamPayload(request) {
+    return {
+        task: "query",
+        image: imageUrl(request.image),
+        question: resolvePrompt(request),
+        stream: true,
+        reasoning: false,
+        temperature: 0,
+        max_tokens: resolvedMaxTokens(request),
+    };
+}
+function incompleteResponseError(model, finishReason) {
+    return new TransportError(`OCR model "${model}" did not complete normally (finish_reason: ${finishReason})`, {
+        code: "OCR_INCOMPLETE_RESPONSE",
+        status: 502,
+        details: { finishReason },
+    });
+}
+function responseContent(payload, cloudflare, model) {
+    const envelope = unknownRecord(payload);
+    const root = cloudflare ? unknownRecord(envelope?.result) : envelope;
+    const choices = root?.choices;
+    if (!Array.isArray(choices))
+        return undefined;
+    const choice = unknownRecord(choices[0]);
+    if (typeof choice?.finish_reason === "string" && choice.finish_reason !== "stop") {
+        throw incompleteResponseError(model, choice.finish_reason);
+    }
+    const message = unknownRecord(choice?.message);
+    return typeof message?.content === "string" ? message.content.trim() || undefined : undefined;
+}
+function malformedResponseError(model, cause) {
+    return new TransportError(`OCR model "${model}" returned a malformed response`, {
+        code: "OCR_UPSTREAM_FAILED",
+        status: 502,
+        cause,
+    });
+}
+async function responseJson(response, model) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        if (isTimeoutLikeError(error))
+            throw toOcrTransportError(error);
+        throw malformedResponseError(model, error instanceof Error ? error : new Error("Failed to decode OCR response JSON"));
+    }
+}
+function moondreamSseContent(body, model) {
+    let finalAnswer;
+    let firstDecodingFailure;
+    let terminalFinishReason;
+    for (const line of body.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("data:"))
+            continue;
+        const data = trimmed.slice("data:".length).trim();
+        if (!data || data === "[DONE]")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch (error) {
+            firstDecodingFailure ??=
+                error instanceof Error ? error : new Error("Failed to decode OCR SSE event");
+            continue;
+        }
+        const event = unknownRecord(parsed);
+        const chunk = unknownRecord(event?.chunk) ?? unknownRecord(event?.result) ?? event;
+        if (chunk?.finish_reason === "stop" &&
+            typeof chunk.answer === "string" &&
+            chunk.answer.trim()) {
+            finalAnswer = chunk.answer.trim();
+        }
+        else if (typeof chunk?.finish_reason === "string") {
+            terminalFinishReason = chunk.finish_reason;
+        }
+    }
+    if (finalAnswer)
+        return finalAnswer;
+    if (terminalFinishReason)
+        throw incompleteResponseError(model, terminalFinishReason);
+    if (firstDecodingFailure)
+        throw malformedResponseError(model, firstDecodingFailure);
+    return finalAnswer;
+}
+function emptyResponseError(model) {
+    return new TransportError(`OCR model "${model}" returned no usable text`, {
+        code: "OCR_UPSTREAM_FAILED",
+        status: 502,
+        fix: `Verify ${APIFUSE__OCR__MODEL_ENV}="${model}" supports image input and the runtime calling convention for that model.`,
+    });
+}
+function toOcrTransportError(error) {
+    if (error instanceof TransportError)
+        return error;
+    if (isTimeoutLikeError(error)) {
+        return new TransportError("OCR upstream request timed out", {
+            code: "transport_timeout",
+            status: 0,
+            cause: error,
+        });
+    }
+    return new TransportError("OCR upstream network request failed", {
+        code: "transport_network_error",
+        status: 0,
+        cause: error instanceof Error ? error : undefined,
+    });
+}
+function createOcrClient(model, recognize) {
+    return {
+        recognize,
+        async extractCaptchaText(image, options = {}) {
+            const result = await recognize({ image, hint: "captcha" });
+            const candidates = extractCaptchaCandidates(result.text, options);
+            const primary = candidates[0];
+            if (!primary?.text)
+                throw emptyResponseError(model);
+            return {
+                text: primary.text,
+                candidates,
+                satisfiesConstraints: primary.satisfiesConstraints,
+                model: result.model,
+            };
+        },
+    };
+}
+export function createCloudflareWorkersAiOcrClient(options) {
+    const model = options.model ?? DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL;
+    const runFetch = options.fetch ?? fetch;
+    return createOcrClient(model, async (request) => {
+        const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
+        try {
+            let response;
+            try {
+                response = await runFetch(`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(options.accountId)}/ai/run/${model}`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${options.apiToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify(isMoondreamModel(model)
+                        ? moondreamPayload(request)
+                        : cloudflareMessagesPayload(request, model)),
+                    signal: timeout.controller.signal,
+                });
+            }
+            catch (error) {
+                throw toOcrTransportError(error);
+            }
+            if (!response.ok) {
+                throw new TransportError("OCR upstream request failed", {
+                    code: "OCR_UPSTREAM_FAILED",
+                    status: response.status,
+                    upstreamStatus: response.status,
+                });
+            }
+            const text = isMoondreamModel(model)
+                ? moondreamSseContent(await response.text(), model)
+                : responseContent(await responseJson(response, model), true, model);
+            if (!text)
+                throw emptyResponseError(model);
+            return { text, model };
+        }
+        catch (error) {
+            throw toOcrTransportError(error);
+        }
+        finally {
+            timeout.clear();
+        }
+    });
+}
+export function createOpenAiCompatibleOcrClient(options) {
+    const model = options.model;
+    const runFetch = options.fetch ?? fetch;
+    return createOcrClient(model, async (request) => {
+        const headers = { "Content-Type": "application/json" };
+        if (options.apiKey)
+            headers.Authorization = `Bearer ${options.apiKey}`;
+        const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_OCR_TIMEOUT_MS);
+        try {
+            let response;
+            try {
+                response = await runFetch(`${options.baseUrl.replace(/\/+$/u, "")}/chat/completions`, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(messagesPayload(request, model)),
+                    signal: timeout.controller.signal,
+                });
+            }
+            catch (error) {
+                throw toOcrTransportError(error);
+            }
+            if (!response.ok) {
+                throw new TransportError("OCR upstream request failed", {
+                    code: "OCR_UPSTREAM_FAILED",
+                    status: response.status,
+                    upstreamStatus: response.status,
+                });
+            }
+            const text = responseContent(await responseJson(response, model), false, model);
+            if (!text)
+                throw emptyResponseError(model);
+            return { text, model };
+        }
+        catch (error) {
+            throw toOcrTransportError(error);
+        }
+        finally {
+            timeout.clear();
+        }
+    });
+}
+function cleanCaptchaText(text) {
+    const afterColon = text.slice(text.lastIndexOf(":") + 1).trim();
+    return afterColon.replace(/^[\s\p{P}\p{S}]+|[\s\p{P}\p{S}]+$/gu, "");
+}
+function caseFold(value, caseSensitive) {
+    return caseSensitive ? value : value.toLocaleLowerCase();
+}
+function matchesCharset(text, charset, caseSensitive) {
+    if (charset === undefined)
+        return true;
+    if (typeof charset === "string") {
+        const allowed = new Set([...caseFold(charset, caseSensitive)]);
+        return [...caseFold(text, caseSensitive)].every((character) => allowed.has(character));
+    }
+    const flags = caseSensitive || charset.flags.includes("i") ? charset.flags : `${charset.flags}i`;
+    const matcher = new RegExp(charset.source, flags);
+    return [...text].every((character) => {
+        matcher.lastIndex = 0;
+        return matcher.test(character);
+    });
+}
+function satisfiesCaptchaConstraints(text, options) {
+    const lengthMatches = options.length === undefined || [...text].length === options.length;
+    return lengthMatches && matchesCharset(text, options.charset, options.caseSensitive !== false);
+}
+function homoglyphAlternatives(character) {
+    const group = HOMOGLYPH_CLASSES.find((characters) => characters.includes(character));
+    return group?.filter((alternative) => alternative !== character) ?? [];
+}
+export function extractCaptchaCandidates(modelText, options = {}) {
+    const primaryText = cleanCaptchaText(modelText);
+    const primary = {
+        text: primaryText,
+        satisfiesConstraints: satisfiesCaptchaConstraints(primaryText, options),
+    };
+    const requestedMaxCandidates = options.maxCandidates ?? DEFAULT_MAX_CAPTCHA_CANDIDATES;
+    const maxCandidates = Number.isFinite(requestedMaxCandidates)
+        ? Math.max(1, Math.floor(requestedMaxCandidates))
+        : DEFAULT_MAX_CAPTCHA_CANDIDATES;
+    if (primary.satisfiesConstraints || maxCandidates === 1)
+        return [primary];
+    if (options.length !== undefined && [...primaryText].length !== options.length)
+        return [primary];
+    const candidates = [primary];
+    const queue = [primaryText];
+    const visited = new Set(queue);
+    for (let index = 0; index < queue.length && candidates.length < maxCandidates; index += 1) {
+        const current = queue[index] ?? "";
+        const characters = [...current];
+        for (let position = 0; position < characters.length; position += 1) {
+            const character = characters[position] ?? "";
+            for (const alternative of homoglyphAlternatives(character)) {
+                const nextCharacters = [...characters];
+                nextCharacters[position] = alternative;
+                const next = nextCharacters.join("");
+                if (visited.has(next))
+                    continue;
+                visited.add(next);
+                queue.push(next);
+                if (satisfiesCaptchaConstraints(next, options)) {
+                    candidates.push({ text: next, satisfiesConstraints: true });
+                    if (candidates.length >= maxCandidates)
+                        return candidates;
+                }
+                if (visited.size >= MAX_HOMOGLYPH_SEARCH_NODES)
+                    return candidates;
+            }
+        }
+    }
+    return candidates;
+}

package/dist/runtime/stt.js

@@ -1,4 +1,5 @@
 import { ProviderError, TransportError, ValidationError } from "../errors.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";
 export const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";
@@ -112,12 +113,6 @@ function warnOrThrowUnsupportedOption(request, message) {
 function normalizeCloudflareLanguage(language) {
     return language?.split("-")[0]?.toLowerCase();
 }
-function isTimeoutLikeError(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) {
     if (error instanceof TransportError)
         return error;
@@ -134,12 +129,6 @@ function toSttTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-function createTimeoutController(signalTimeoutMs) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
-    timeout.unref?.();
-    return { controller, clear: () => clearTimeout(timeout) };
-}
 function toCloudflareInput(request) {
     const prompt = resolveSttPrompt(request);
     const input = {

package/dist/runtime/timeout.d.ts

@@ -0,0 +1,5 @@
+export declare function isTimeoutLikeError(error: unknown): error is Error;
+export declare function createTimeoutController(signalTimeoutMs: number): {
+    controller: AbortController;
+    clear: () => void;
+};

package/dist/runtime/timeout.js

@@ -0,0 +1,12 @@
+export function isTimeoutLikeError(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) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
+    timeout.unref?.();
+    return { controller, clear: () => clearTimeout(timeout) };
+}

package/dist/server/serve.d.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { z } from "zod";
 import { type ProviderErrorCategory } from "../observability.js";
-import type { ProviderContext, ProviderDefinition, ProviderRuntimeState, SttContext } from "../types.js";
+import type { OcrContext, ProviderContext, ProviderDefinition, ProviderRuntimeState, SttContext } from "../types.js";
 import { type OperationRequest } from "./types.js";
 /** Compact SDK-owned error classification emitted separately from the public response body. */
 export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
@@ -133,6 +133,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. */

package/dist/server/serve.js

@@ -18,6 +18,7 @@ import { createHttpClient } from "../runtime/http.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import { createEnvVendorCredentialResolver, 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, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
@@ -232,6 +233,7 @@ function createProviderContext(provider, request, operationId, options = {}, sta
             : {}),
         trace: createTraceContext(),
         auth: createAuthStub(),
+        ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),
         choice: createProviderChoiceContext({
             providerId: provider.id,
@@ -327,6 +329,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
             ]),
             credential,
             context: flowContextStore.context,
+            ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
             stt: options.stt ?? createSttClientFromEnv(provider.stt),
             auth: createAuthFlowHelpers({ signal }),
         },
@@ -1608,6 +1611,7 @@ export async function serve(provider, options = {}) {
     const configuredSignals = resolveShutdownSignals(options.shutdown?.signals ?? true);
     const app = createServerApp(provider, {
         logger: options.logger,
+        ocr: options.ocr,
         stt: options.stt,
         state: options.state,
         allowMemoryStateFallback: options.allowMemoryStateFallback,

package/dist/testing/run.js

@@ -2,6 +2,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, NativeNetworkError, snapshotNativeConnectInput, snapshotNativeGrantInput, } from "../runtime/native-network.js";
 import { safeParseSchemaSync } from "../schema.js";
@@ -397,6 +398,7 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
             : {}),
         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"),
         choice: createTestProviderChoiceContext({
             providerId: `standard-test-${operationName}`,
@@ -503,6 +505,7 @@ export function createSnapshotContext(rawFixture) {
         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"),
         choice: createTestProviderChoiceContext({
             providerId: "standard-test",

package/dist/types.d.ts

@@ -196,6 +196,54 @@ export interface SmsOtpMatcherDefinition {
     /** Runtime/fixture helper. Not serialized into generated registry artifacts. */
     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";
@@ -1543,6 +1591,7 @@ export interface FlowContext {
     env: EnvContext;
     credential?: CredentialContext;
     context: ContextScratchpad;
+    ocr: OcrContext;
     stt: SttContext;
     auth: AuthFlowTerminalContext;
 }
@@ -1634,6 +1683,7 @@ export interface ProviderContext {
     browser: BrowserClient;
     trace: TraceContext;
     auth: AuthContext;
+    ocr: OcrContext;
     stt: SttContext;
     choice: ProviderChoiceContext;
 }
@@ -1785,6 +1835,7 @@ export interface ProviderDefinition {
         platform: StealthPlatform;
     };
     proxy?: ProviderProxyConfig;
+    ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
     browser?: {
         engine: BrowserEngine;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.22",
+	"version": "2.2.0-beta.23",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

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 }),