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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.23
+
+- Release candidate for main commit 36b3bedc9c14913c4152c4631cc87de71062f21f.
+
+## 2.2.0-beta.22
+
+- Release candidate for main commit b8bf920b5ca053d1bf43018167fd4eedff01700d.
+
+## Unreleased
+
+- Added the `thrown-error-code-undeclared` authoring lint (warning level): `apifuse check` now statically flags literal `ProviderError`/`ValidationError` codes that are neither SDK-registered nor declared in any operation's `docs.errorCodes`, surfacing the runtime `unregistered_provider_error_code` signal at check time. The canonical SDK code→status mapping moved to `SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES` in `error-resolution.ts`, shared by the runtime status resolver and the lint.
+
 ## 2.2.0-beta.21
 
 - Release candidate for main commit 00f61024fb18db39711dc5076c4621508baa49f5.

package/bin/apifuse-dev.ts

@@ -8,6 +8,7 @@ import {
 	createCredentialContext,
 	createEnvContext,
 	createHttpClient,
+	createOcrClientFromEnv,
 	createProviderCache,
 	createProviderChoiceContext,
 	createStealthClient,
@@ -96,6 +97,7 @@ export function createProviderContext(provider: ProviderDefinition): {
 		state,
 		trace: createTraceContext(),
 		stealth: createStealthClient("http://localhost"),
+		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,

package/bin/apifuse-record.ts

@@ -8,6 +8,7 @@ import { pathToFileURL } from "node:url";
 import {
 	createBypassProviderCache,
 	createHttpClient,
+	createOcrClientFromEnv,
 	createProviderChoiceContext,
 	createStealthClient,
 	createSttClientFromEnv,
@@ -536,6 +537,7 @@ function createCaptureContext(provider: ProviderRuntime, baseUrl: string, saniti
 				throw new Error("Auth prompts are not available in apifuse record.");
 			},
 		},
+		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,

package/dist/contract-types.d.ts

@@ -11,6 +11,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/dist/contract.js

@@ -7,6 +7,7 @@ export function extractProviderContract(provider) {
     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);
@@ -30,6 +31,7 @@ export function extractProviderContract(provider) {
         ...(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/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, NativeProviderConfig, ProviderAccessConfig, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, NativeProviderConfig, ProviderOcrConfig, ProviderAccessConfig, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -55,6 +55,7 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
         platform: StealthPlatform;
     };
     proxy?: ProviderProxyConfig;
+    ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
     browser?: {
         engine: BrowserEngine;

package/dist/define.js

@@ -47,6 +47,7 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
     "auth-flow",
     "connection",
 ];
+const VALID_PROVIDER_OCR_MODES = ["optional", "required"];
 const VALID_PROVIDER_STT_MODES = ["optional", "required"];
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
@@ -377,6 +378,18 @@ function validateProviderStt(config) {
     rejectUnknownFields(stt, new Set(["mode"]), "stt");
     assertLiteralField(stt.mode, "stt.mode", VALID_PROVIDER_STT_MODES, config.id);
 }
+function validateProviderOcr(config) {
+    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, operations) {
     for (const operationName of Object.keys(operations)) {
         if (!OPERATION_ID_REGEX.test(operationName))
@@ -1538,6 +1551,7 @@ export function defineProvider(config) {
         throw error;
     }
     validateProviderProxy(config);
+    validateProviderOcr(config);
     validateProviderStt(config);
     if (config.runtime === "browser" && !config.browser)
         throw new ProviderError(`Provider "${config.id}" must define browser.engine when runtime is "browser"`, {
@@ -1556,6 +1570,7 @@ export function defineProvider(config) {
         native: config.native,
         stealth: config.stealth,
         proxy: config.proxy,
+        ocr: config.ocr,
         stt: config.stt,
         browser: config.browser,
         auth: config.auth,

package/dist/error-resolution.d.ts

@@ -1,2 +1,4 @@
+import type { ProviderErrorStatus } from "./types.js";
 export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
 export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;
+export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;

package/dist/error-resolution.js

@@ -28,6 +28,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",
@@ -82,9 +83,40 @@ 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",
     "NOT_FOUND",
     "not_found",
 ]);
+// Canonical SDK status mapping for recognized provider-thrown error codes.
+// serve.ts toStatusCode consults this map (after operation-declared overrides
+// for non-SDK-owned codes), and the authoring lint treats these codes as
+// SDK-registered. Add new codes here instead of duplicating literals in
+// either consumer.
+export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES = new Map([
+    ["AUTH_REQUIRED", 401],
+    ["reauth_required", 401],
+    // Unprovisioned declared secret: a deployment/config defect, never an
+    // upstream failure — explicit 400.
+    ["MISSING_SECRET", 400],
+    ["NOT_FOUND", 404],
+    ["not_found", 404],
+    ["NO_DATA", 404],
+    ["RATE_LIMITED", 429],
+    ["UPSTREAM_RATE_LIMIT", 429],
+    ["LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR", 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.
+    ["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/dist/index.d.ts

@@ -32,13 +32,14 @@ export { getProviderBaseUrl } from "./runtime/provider.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, 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, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
 export { createServerApp, ERROR_OBSERVABILITY_HEADER, type ServeOptions, serve, } from "./server/index.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";

package/dist/index.js

@@ -29,6 +29,7 @@ export { getProviderBaseUrl } from "./runtime/provider.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";
 export { createUnsupportedProviderRuntimeState, 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, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
 export { createTraceContext, } from "./runtime/trace.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, sensitive, z, } from "./schema.js";

package/dist/lint.d.ts

@@ -65,6 +65,11 @@ export declare function lintProvider(provider: {
         derivations?: Record<string, string>;
         handler?: unknown;
         source?: string;
+        docs?: {
+            errorCodes?: ReadonlyArray<{
+                code: string;
+            }>;
+        };
     }>;
     meta?: {
         contract?: ProviderContractMetaLike;

package/dist/lint.js

@@ -1,3 +1,4 @@
+import { SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 const AUTH_OPERATION_ID_PATTERN = /^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
@@ -587,6 +588,281 @@ function lintSelfHostedBrowserPatterns(provider, options) {
     }
     return diagnostics;
 }
+const THROWN_ERROR_CONSTRUCTION_PATTERN = /new\s+(?:ProviderError|ValidationError)\s*\(/g;
+const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/**
+ * Skips a string literal starting at `startIndex` (which must point at the
+ * opening quote). Returns the index of the closing quote, or -1 when the
+ * literal is unterminated. Template literals handle nested `${...}`
+ * expressions, including strings inside them.
+ */
+function skipStringLiteral(source, startIndex) {
+    const quote = source[startIndex];
+    for (let index = startIndex + 1; index < source.length; index++) {
+        const char = source[index];
+        if (char === "\\") {
+            index++;
+            continue;
+        }
+        if (quote === "`" && char === "$" && source[index + 1] === "{") {
+            index = skipTemplateExpression(source, index + 2);
+            if (index < 0) {
+                return -1;
+            }
+            continue;
+        }
+        if (char === quote) {
+            return index;
+        }
+        if (quote !== "`" && char === "\n") {
+            return -1;
+        }
+    }
+    return -1;
+}
+function skipTemplateExpression(source, startIndex) {
+    let depth = 1;
+    for (let index = startIndex; index < source.length; index++) {
+        const char = source[index];
+        if (char === '"' || char === "'" || char === "`") {
+            index = skipStringLiteral(source, index);
+            if (index < 0) {
+                return -1;
+            }
+            continue;
+        }
+        if (char === "{") {
+            depth++;
+        }
+        else if (char === "}") {
+            depth--;
+            if (depth === 0) {
+                return index;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extracts the argument text of a call whose opening paren has already been
+ * consumed (`startIndex` points just past it). Returns undefined when the
+ * call never closes in this source, which the caller treats as "skip
+ * silently" — this scanner is conservative by design.
+ */
+function extractBalancedCallArguments(source, startIndex) {
+    let depth = 1;
+    for (let index = startIndex; index < source.length; index++) {
+        const char = source[index];
+        if (char === '"' || char === "'" || char === "`") {
+            index = skipStringLiteral(source, index);
+            if (index < 0) {
+                return undefined;
+            }
+            continue;
+        }
+        if (char === "/" && source[index + 1] === "/") {
+            const newline = source.indexOf("\n", index);
+            if (newline === -1) {
+                return undefined;
+            }
+            index = newline;
+            continue;
+        }
+        if (char === "/" && source[index + 1] === "*") {
+            const end = source.indexOf("*/", index + 2);
+            if (end === -1) {
+                return undefined;
+            }
+            index = end + 1;
+            continue;
+        }
+        if (char === "(") {
+            depth++;
+        }
+        else if (char === ")") {
+            depth--;
+            if (depth === 0) {
+                return source.slice(startIndex, index);
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Collects literal string values of top-level `code:` properties inside a
+ * ProviderError/ValidationError options object. Only plain `"..."` / `'...'`
+ * literals at options-object depth count; computed codes (identifiers,
+ * ternaries, template substitutions, concatenations, escapes) are skipped
+ * silently so the rule never guesses.
+ */
+function collectLiteralErrorCodeValues(args) {
+    const codes = [];
+    let braceDepth = 0;
+    let parenDepth = 0;
+    let bracketDepth = 0;
+    let previousSignificantChar = "";
+    for (let index = 0; index < args.length; index++) {
+        const char = args[index] ?? "";
+        if (char === '"' || char === "'" || char === "`") {
+            const end = skipStringLiteral(args, index);
+            if (end < 0) {
+                return codes;
+            }
+            index = end;
+            previousSignificantChar = char;
+            continue;
+        }
+        if (char === "/" && args[index + 1] === "/") {
+            const newline = args.indexOf("\n", index);
+            if (newline === -1) {
+                return codes;
+            }
+            index = newline;
+            continue;
+        }
+        if (char === "/" && args[index + 1] === "*") {
+            const end = args.indexOf("*/", index + 2);
+            if (end === -1) {
+                return codes;
+            }
+            index = end + 1;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            continue;
+        }
+        if (char === "{") {
+            braceDepth++;
+        }
+        else if (char === "}") {
+            braceDepth--;
+        }
+        else if (char === "(") {
+            parenDepth++;
+        }
+        else if (char === ")") {
+            parenDepth--;
+        }
+        else if (char === "[") {
+            bracketDepth++;
+        }
+        else if (char === "]") {
+            bracketDepth--;
+        }
+        else if (braceDepth === 1 &&
+            parenDepth === 0 &&
+            bracketDepth === 0 &&
+            (previousSignificantChar === "{" || previousSignificantChar === ",") &&
+            args.startsWith("code", index)) {
+            let cursor = index + "code".length;
+            while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+                cursor++;
+            }
+            if (args[cursor] === ":") {
+                cursor++;
+                while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+                    cursor++;
+                }
+                const quote = args[cursor];
+                if (quote === '"' || quote === "'") {
+                    const end = skipStringLiteral(args, cursor);
+                    if (end > cursor) {
+                        const value = args.slice(cursor + 1, end);
+                        let after = end + 1;
+                        while (after < args.length && /\s/.test(args[after] ?? "")) {
+                            after++;
+                        }
+                        const nextChar = after < args.length ? (args[after] ?? "") : "";
+                        if (!value.includes("\\") && (nextChar === "," || nextChar === "}" || nextChar === "")) {
+                            codes.push(value);
+                        }
+                        index = end;
+                        previousSignificantChar = quote;
+                        continue;
+                    }
+                    return codes;
+                }
+            }
+        }
+        previousSignificantChar = char;
+    }
+    return codes;
+}
+function collectLiteralThrownErrorCodes(source) {
+    const codes = [];
+    THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = 0;
+    for (let match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source); match; match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source)) {
+        const argsStart = match.index + match[0].length;
+        const args = extractBalancedCallArguments(source, argsStart);
+        if (args !== undefined) {
+            codes.push(...collectLiteralErrorCodeValues(args));
+        }
+        THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = argsStart;
+    }
+    return codes;
+}
+/**
+ * Static counterpart of the runtime `unregistered_provider_error_code`
+ * signal (honest-provider-error-contract Phase 3.5.5): flags
+ * `new ProviderError(...)` / `new ValidationError(...)` constructions whose
+ * literal `code` is neither SDK-registered (SDK_RUNTIME_OWNED_ERROR_CODES
+ * plus the canonical status-mapped codes shared with serve.ts toStatusCode)
+ * nor declared in any operation's docs.errorCodes. At runtime such a code
+ * serves HTTP 500 and emits the signal; this rule surfaces it at check time.
+ *
+ * A throw site cannot be attributed to a specific operation statically —
+ * providers routinely throw from helpers shared across operations — so this
+ * rule matches against the provider-level union of declared codes. That is
+ * the honest scope: it will not catch a code declared only on the "wrong"
+ * operation, and it never claims per-operation attribution it cannot prove.
+ * Only literal string codes are checked; computed/dynamic codes and test
+ * sources are skipped silently. Warning level: the long tail of existing
+ * providers converges gradually, so this must not fail `apifuse check`.
+ */
+function lintUndeclaredThrownErrorCodes(provider) {
+    const knownCodes = new Set([
+        ...SDK_RUNTIME_OWNED_ERROR_CODES,
+        ...SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.keys(),
+    ]);
+    for (const operation of Object.values(provider.operations ?? {})) {
+        for (const entry of operation.docs?.errorCodes ?? []) {
+            if (typeof entry?.code === "string") {
+                knownCodes.add(entry.code);
+            }
+        }
+    }
+    const sources = [];
+    const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(([filePath]) => !TEST_SOURCE_FILE_PATTERN.test(filePath));
+    if (sourceFiles.length > 0) {
+        for (const [filePath, source] of sourceFiles) {
+            sources.push({ field: `sourceFiles.${filePath}`, source });
+        }
+    }
+    else {
+        if (provider.authFlowSource) {
+            sources.push({ field: "auth.flow", source: provider.authFlowSource });
+        }
+        for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+            const source = getOperationSource(operation);
+            if (source) {
+                sources.push({ field: `operations.${operationKey}.handler`, source });
+            }
+        }
+    }
+    const diagnostics = [];
+    for (const { field, source } of sources) {
+        const undeclaredCodes = new Set(collectLiteralThrownErrorCodes(source).filter((code) => !knownCodes.has(code)));
+        for (const code of undeclaredCodes) {
+            diagnostics.push({
+                rule: "thrown-error-code-undeclared",
+                level: "warn",
+                field,
+                message: `Thrown error code "${code}" (${field}) is neither SDK-registered nor declared in any operation's docs.errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's docs.errorCodes with status and retryable.`,
+            });
+        }
+    }
+    return diagnostics;
+}
 export function lintOperation(op) {
     const diagnostics = [];
     const description = op.description ?? "";
@@ -677,6 +953,7 @@ export function lintProvider(provider, options = {}) {
         ...lintCredentialWriteUsage(provider),
         ...lintPlaywrightDirectImports(provider),
         ...lintSelfHostedBrowserPatterns(provider, options),
+        ...lintUndeclaredThrownErrorCodes(provider),
     ];
     if (provider.operations) {
         const authMode = provider.auth?.mode;

package/dist/runtime/auth-flow.d.ts

@@ -1,4 +1,4 @@
-import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, StealthClient, SttContext } from "../types.js";
+import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, OcrContext, StealthClient, SttContext } from "../types.js";
 export declare function createScratchpad(allowedKeys: string[], initial?: Record<string, unknown>): ContextScratchpad;
 export declare function createFlowContext(options: {
     flowId?: string;
@@ -11,5 +11,6 @@ export declare function createFlowContext(options: {
     externalRef?: string;
     allowedKeys: string[];
     initialContext?: Record<string, unknown>;
+    ocr?: OcrContext;
     stt?: SttContext;
 }): FlowContext;

package/dist/runtime/auth-flow.js

@@ -1,5 +1,6 @@
 import { ContextAccessError } from "../errors.js";
 import { createAuthFlowHelpers } from "../auth.js";
+import { createUnsupportedOcrClient } from "./ocr.js";
 import { createUnsupportedSttClient } from "./stt.js";
 function normalizeAllowedKeys(allowedKeys) {
     return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -41,6 +42,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/dist/runtime/browser.js

@@ -457,7 +457,7 @@ function normalizeWebSocketEndpoint(endpoint) {
     }
     throw new Error(`Unsupported WebSocket endpoint protocol: ${url.protocol}`);
 }
-class JsonRpcWebSocketClient {
+class WebSocketCommandClient {
     nextId = 1;
     endpoint;
     listeners = new Map();
@@ -483,12 +483,7 @@ class JsonRpcWebSocketClient {
         const id = this.nextId++;
         return await new Promise((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)));
         });
     }
     async close() {
@@ -526,7 +521,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;
                     }
                     pending.resolve(payload.result ?? {});
@@ -554,6 +553,26 @@ class JsonRpcWebSocketClient {
         return this.socketPromise;
     }
 }
+class CdpWebSocketClient extends WebSocketCommandClient {
+    sessionId;
+    constructor(endpoint, sessionId) {
+        super(endpoint);
+        this.sessionId = sessionId;
+    }
+    createCommandFrame(id, method, params) {
+        return {
+            id,
+            method,
+            params,
+            ...(this.sessionId === undefined ? {} : { sessionId: this.sessionId }),
+        };
+    }
+}
+class JsonRpcWebSocketClient extends WebSocketCommandClient {
+    createCommandFrame(id, method, params) {
+        return { id, jsonrpc: "2.0", method, params };
+    }
+}
 function flattenCdpFrameTree(node, out = []) {
     if (!node) {
         return out;
@@ -996,7 +1015,7 @@ class CdpPoolBrowserClient {
             ...(this.allowedHosts.length > 0 ? { allowedHosts: this.allowedHosts } : {}),
             ...(options?.isolatedContext ? { isolationMode: "browserContext" } : {}),
         }));
-        const pageClient = new JsonRpcWebSocketClient(acquireResult.wsEndpoint);
+        const pageClient = new CdpWebSocketClient(acquireResult.wsEndpoint);
         const page = new CdpPoolBrowserPage(acquireResult.pageId, acquireResult.browserContextId, pageClient, async (request) => {
             await this.poolClient.send("release", request);
         });