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

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, ResolverContext, 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";
@@ -61,6 +61,7 @@ export type ProviderServerOperationExecutorInput = {
 };
 export type ProviderServerOperationExecutor = (input: ProviderServerOperationExecutorInput) => Promise<unknown>;
 export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
+export declare function resolveProviderResolverIdentityScope(provider: ProviderDefinition, affinityKey: string, contextId: string): string;
 type ProviderRequestCost = {
     durationMs: number;
     cpuUserMicros: number;
@@ -133,6 +134,10 @@ 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 resolver override for tests or custom hosts; local/prod normally resolves from env. */
+    resolver?: ResolverContext;
     /** 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,8 +18,10 @@ 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 { bindResolverSignal, createResolverClientFromEnv } from "../runtime/resolver.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
 import { createStealthClient } from "../runtime/stealth.js";
@@ -148,6 +150,13 @@ export function resolveProviderProxyAffinityKey(provider, request, operationId)
     }
     return connectionKey ?? provider.id;
 }
+export function resolveProviderResolverIdentityScope(provider, affinityKey, contextId) {
+    return JSON.stringify({
+        proxy: provider.proxy ?? null,
+        affinityKey,
+        contextId,
+    });
+}
 function resolveOperationConnectionId(request) {
     return request.connection?.id ?? request.connectionId;
 }
@@ -160,7 +169,7 @@ function resolveNativeProxyPolicy(provider) {
         return { mode: "disabled" };
     return undefined;
 }
-function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
+function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -169,6 +178,7 @@ function createProviderContext(provider, request, operationId, options = {}, sta
         affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
         telemetry: proxyTelemetry,
     };
+    const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     let wrappedContext;
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
@@ -189,6 +199,8 @@ function createProviderContext(provider, request, operationId, options = {}, sta
         connectionId: resolveOperationConnectionId(request),
         headers: request.headers ?? {},
     };
+    const requestState = state.forConnection(requestContext.connectionId);
+    const cache = createProviderCache({ providerId: provider.id });
     const context = wrapWithInstrumentation({
         env,
         credential,
@@ -201,8 +213,8 @@ function createProviderContext(provider, request, operationId, options = {}, sta
                 retryResponseMeta.set(wrappedContext, summary);
             },
         }),
-        cache: createProviderCache({ providerId: provider.id }),
-        state,
+        cache,
+        state: requestState,
         stealth: stealthBaseUrl
             ? stealthProfile
                 ? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
@@ -232,13 +244,20 @@ function createProviderContext(provider, request, operationId, options = {}, sta
             : {}),
         trace: createTraceContext(),
         auth: createAuthStub(),
+        ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),
+        resolver: bindResolverSignal(options.resolver ??
+            createResolverClientFromEnv(provider.resolver, undefined, {
+                allowedHosts: provider.allowedHosts,
+                cache,
+                identityScope: resolverIdentityScope,
+            }), signal),
         choice: createProviderChoiceContext({
             providerId: provider.id,
             env,
             request: requestContext,
             credential,
-            state,
+            state: requestState,
         }),
     });
     wrappedContext = context;
@@ -282,6 +301,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
             request.providerId ??
             provider.id,
     };
+    const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
@@ -294,6 +314,7 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
             values: request.connection.secrets,
         })
         : undefined;
+    const cache = createProviderCache({ providerId: provider.id });
     return {
         context: {
             flowId: request.flowId,
@@ -327,7 +348,14 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
             ]),
             credential,
             context: flowContextStore.context,
+            ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
             stt: options.stt ?? createSttClientFromEnv(provider.stt),
+            resolver: bindResolverSignal(options.resolver ??
+                createResolverClientFromEnv(provider.resolver, undefined, {
+                    allowedHosts: provider.allowedHosts,
+                    cache,
+                    identityScope: resolverIdentityScope,
+                }), signal),
             auth: createAuthFlowHelpers({ signal }),
         },
         getPatch: flowContextStore.getPatch,
@@ -1045,8 +1073,8 @@ function withAuthRequestHeaders(request, headers) {
         },
     };
 }
-async function handleOperation(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
-    const ctx = createProviderContext(provider, request, operationId, options, state, proxyTelemetry);
+async function handleOperation(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry, signal) {
+    const ctx = createProviderContext(provider, request, operationId, options, state, proxyTelemetry, signal);
     const operation = provider.operations[operationId];
     const streaming = operation?.transport?.kind && operation.transport.kind !== "json";
     let cleanupCalled = false;
@@ -1074,6 +1102,7 @@ async function handleOperation(provider, request, operationId, options = {}, sta
                 operationId,
                 ctx,
                 request,
+                signal,
             })
             : await executeOperation(provider, operationId, ctx, request.input);
         if (streaming && operation) {
@@ -1393,7 +1422,7 @@ export function createServerApp(provider, options = {}) {
             }
             const request = operationRequestFromForwardingEnvelope(envelope);
             operationId = envelope.operationId;
-            const ctx = createProviderContext(provider, request, operationId, options, state);
+            const ctx = createProviderContext(provider, request, operationId, options, state, undefined, signal);
             if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
                 throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt);
             }
@@ -1432,7 +1461,7 @@ export function createServerApp(provider, options = {}) {
             const body = OperationRequestSchema.parse(rawBody);
             const requestHeaders = Object.fromEntries(c.req.raw.headers.entries());
             body.headers = { ...requestHeaders, ...body.headers };
-            const response = await handleOperation(provider, body, operation, options, state, proxyTelemetry);
+            const response = await handleOperation(provider, body, operation, options, state, proxyTelemetry, c.req.raw.signal);
             if (response instanceof Response) {
                 logProviderSuccess(logger, provider, "operation", operation, body.requestId, response.status, finishRequestCost(requestCost));
                 return responseWithProviderTelemetry(response, proxyTelemetry);
@@ -1608,7 +1637,9 @@ 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,
+        resolver: options.resolver,
         state: options.state,
         allowMemoryStateFallback: options.allowMemoryStateFallback,
         operationExecutor: options.operationExecutor,

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";
@@ -247,6 +248,7 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
                 },
             }),
             close: async () => { },
+            cookies: async () => (await browserAction("cookies")).data,
             fill: async (selector, textValue) => {
                 await browserAction("fill", { selector, text: textValue });
             },
@@ -397,7 +399,11 @@ 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"),
+        resolver: {
+            solve: async () => unsupported("ctx.resolver.solve"),
+        },
         choice: createTestProviderChoiceContext({
             providerId: `standard-test-${operationName}`,
             request,
@@ -503,7 +509,11 @@ 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"),
+        resolver: {
+            solve: async () => unsupported("ctx.resolver.solve"),
+        },
         choice: createTestProviderChoiceContext({
             providerId: "standard-test",
             request,

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";
@@ -203,6 +251,79 @@ export type ProviderSttMode = "optional" | "required";
 export interface ProviderSttConfig {
     mode: ProviderSttMode;
 }
+/**
+ * `browser` is the in-house CDP pool (`apps/cdp-pool`, reached through
+ * `createBrowserClient`) and is a first-class vendor rather than an escape hatch:
+ * for fingerprint-family kinds, it was measured faster than a paid vendor
+ * (4.5 s vs 17.5 s) at zero marginal cost.
+ *
+ * `2captcha` is the vendor already carrying production traffic in
+ * `apifuse-provider-tabelog`.
+ *
+ * Union order is documentation only; the effective fallback order is whatever
+ * `ProviderResolverConfig.vendors` declares.
+ */
+export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "custom";
+/**
+ * Token-family kinds resolve to `{ form: "token" }`. Cookie-family kinds resolve
+ * to `{ form: "cookies" }`; network-identity binding is defined per kind. `aws_waf`
+ * was measured portable across residential leases on buyee, while `cf_clearance`
+ * remains unmeasured here and is treated as identity-scoped because it is widely
+ * described as IP-bound.
+ */
+export type ProviderChallenge = {
+    readonly kind: "turnstile";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+    readonly action?: string;
+    readonly cdata?: string;
+} | {
+    readonly kind: "recaptcha_v2";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+} | {
+    readonly kind: "recaptcha_v3";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+    readonly action: string;
+    readonly minScore?: number;
+} | {
+    readonly kind: "hcaptcha";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+} | {
+    readonly kind: "cloudflare_interstitial";
+    readonly pageUrl: string;
+    readonly blockedHtml?: string;
+} | {
+    readonly kind: "aws_waf";
+    readonly pageUrl: string;
+    readonly captchaScript?: string;
+    readonly context?: string;
+    readonly iv?: string;
+};
+export type ProviderChallengeKind = ProviderChallenge["kind"];
+/**
+ * Token solutions carry no network-identity binding. Cookie-solution binding is
+ * per challenge kind: `aws_waf` was measured portable across residential leases
+ * on buyee, while `cf_clearance` is unmeasured here and treated as scoped to the
+ * identity that produced it. The provider attaches the returned cookies to its
+ * own requests.
+ */
+export type ChallengeSolution = {
+    readonly form: "token";
+    readonly token: string;
+} | {
+    readonly form: "cookies";
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly userAgent: string;
+};
+export interface ProviderResolverConfig {
+    /** Ordered vendor fallback chain, tried first to last. */
+    readonly vendors: readonly ProviderResolverVendor[];
+    /** Challenge kinds this provider is permitted to request. */
+    readonly kinds: readonly ProviderChallengeKind[];
+}
 export type SttAudioInput = {
     kind: "base64";
     data: string;
@@ -267,6 +388,9 @@ export interface SttContext {
     transcribe(request: SttTranscribeRequest): Promise<SttTranscript>;
     extractVerificationCode(text: string, options?: SttVerificationCodeOptions): VerificationCodeExtractionResult;
 }
+export interface ResolverContext {
+    solve(challenge: ProviderChallenge, signal?: AbortSignal): Promise<ChallengeSolution>;
+}
 export interface HealthJourneySchedule {
     kind: "interval";
     /** ISO 8601 duration, for example PT8H. */
@@ -668,10 +792,12 @@ export type ProviderProxyMode = "disabled" | "optional" | "required";
  * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
  *	 (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
  *	 username params. A different company from `smartproxy` above.
- *	 **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
- *	 or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
- * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
- *	 `APIFUSE__PROXY__URL` env still works without declaring this value.
+ *	 **@deprecated** — unused; no managed adapter. Declare a
+ *	 `ProviderProxyPolicy` using `smartproxy` or `nodemaven` instead; the
+ *	 `smartproxy` allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `custom` — **@deprecated** static proxy marker with no managed adapter.
+ *	 Use `ProviderProxyPolicy` with `smartproxy`/`nodemaven`; the `smartproxy`
+ *	 allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
  */
 export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 export type ProviderProxySessionAffinity = "request" | "operation" | "auth-flow" | "connection";
@@ -1281,6 +1407,17 @@ export interface BrowserFrame {
     evaluate<T>(fn: string | (() => T)): Promise<T>;
     locator(selector: string): BrowserLocator;
 }
+export interface BrowserCookie {
+    readonly name: string;
+    readonly value: string;
+    readonly domain: string;
+    readonly path: string;
+    /** Unix seconds. Absent for a session cookie. */
+    readonly expires?: number;
+    readonly httpOnly: boolean;
+    readonly secure: boolean;
+    readonly sameSite?: "Strict" | "Lax" | "None";
+}
 export type BrowserResourceMethod = "GET" | "HEAD";
 export type BrowserResourceRequest = {
     readonly url: string;
@@ -1309,6 +1446,11 @@ export type BrowserResourcePolicy = {
 };
 export interface BrowserPage extends BrowserFrame {
     close(): Promise<void>;
+    /**
+     * Reads the browser context's cookie jar, including httpOnly cookies.
+     * Cookie expiry values are Unix seconds and are absent for session cookies.
+     */
+    cookies(): Promise<readonly BrowserCookie[]>;
     fill(selector: string, text: string): Promise<void>;
     goto(url: string): Promise<void>;
     pageId?: string;
@@ -1543,7 +1685,9 @@ export interface FlowContext {
     env: EnvContext;
     credential?: CredentialContext;
     context: ContextScratchpad;
+    ocr: OcrContext;
     stt: SttContext;
+    resolver: ResolverContext;
     auth: AuthFlowTerminalContext;
 }
 export interface AuthTurn {
@@ -1575,7 +1719,13 @@ export interface AuthFlowDefinition {
     refresh?: AuthFlowInputHandler;
 }
 export type ProviderStateDurationString = `${number}${"ms" | "s" | "m" | "h" | "d"}` | `PT${string}`;
+export type StateNamespaceScope = "connection" | "provider";
 export interface StateNamespaceOptions {
+    /**
+     * State isolation boundary. Connection scope is the default; provider scope
+     * must be selected explicitly for provider-wide coordination state.
+     */
+    scope?: StateNamespaceScope;
     /** Default TTL used when a write omits ttl. Required to avoid unbounded state. */
     defaultTtl: ProviderStateDurationString;
     /** Maximum allowed TTL; writes are rejected when they exceed this policy. */
@@ -1617,6 +1767,11 @@ export interface ProviderStateNamespace {
     increment(key: string, field: string, delta?: number, options?: StateWriteOptions): Promise<StateValue<Record<string, unknown>>>;
 }
 export interface ProviderRuntimeState {
+    /**
+     * Returns an immutable view bound to one request connection. An unresolved
+     * connection uses an isolated reserved sentinel, never the provider-global scope.
+     */
+    forConnection(connectionId: string | undefined): ProviderRuntimeState;
     namespace(name: string, options: StateNamespaceOptions): ProviderStateNamespace;
 }
 export interface ProviderContext {
@@ -1634,7 +1789,9 @@ export interface ProviderContext {
     browser: BrowserClient;
     trace: TraceContext;
     auth: AuthContext;
+    ocr: OcrContext;
     stt: SttContext;
+    resolver: ResolverContext;
     choice: ProviderChoiceContext;
 }
 export interface ProxiedOAuthConfig {
@@ -1785,7 +1942,9 @@ export interface ProviderDefinition {
         platform: StealthPlatform;
     };
     proxy?: ProviderProxyConfig;
+    ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
+    resolver?: ProviderResolverConfig;
     browser?: {
         engine: BrowserEngine;
     };

package/package.json

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