@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/runtime/native-telemetry.d.ts

@@ -0,0 +1,142 @@
+import type { ProviderProxyProvider } from "../types.js";
+import type { NativeNetworkErrorCode } from "./native-network-errors.js";
+import { type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
+export type NativeTelemetryErrorCode = NativeNetworkErrorCode | "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED" | "other";
+export type NativeTelemetryKind = "tcp" | "tls";
+export type NativeTelemetryOutcome = "ok" | "error";
+export type NativeTelemetryVendorSkipReason = "credentials_absent" | "protocol_unsupported" | "allocation_failed" | "credential_lookup_failed" | "adapter_unavailable";
+export type NativeTelemetryLifecycleKind = "drain" | "drain_acknowledged" | "drain_error" | "drain_missing_handler" | "idle" | "expiry";
+/** Operator-only text is redacted before it is detached and bounded to 300 code units. */
+export type NativeTelemetryDiagnostics = {
+    host?: string;
+    serverName?: string;
+    protocol?: string;
+    sessionId?: string;
+    expiresAt?: string;
+    errorName?: string;
+    errorMessage?: string;
+    causeName?: string;
+    causeMessage?: string;
+    systemCode?: string;
+    missingFields?: readonly string[];
+    port?: number;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    status?: number;
+    socksReplyCode?: number;
+    sticky?: boolean;
+};
+export type NativeConnectTelemetryEvent = {
+    kind: NativeTelemetryKind;
+    outcome: NativeTelemetryOutcome;
+    /** Entire establishment, including lease resolution, tunnel and TLS handshake. */
+    ms: number;
+    /** Tunnel establishment only; included in ms, never added to it. */
+    tunnelMs: number;
+    proxyUsed: boolean;
+    /** Selected vendor for this connection; operator log only. */
+    vendor?: ProviderProxyProvider;
+    errorCode?: NativeTelemetryErrorCode;
+    diagnostics?: NativeTelemetryDiagnostics;
+};
+export type NativeVendorSkipTelemetryEvent = {
+    vendor: ProviderProxyProvider;
+    reason: NativeTelemetryVendorSkipReason;
+    diagnostics?: NativeTelemetryDiagnostics;
+};
+export type NativeLifecycleTelemetryEvent = {
+    kind: NativeTelemetryLifecycleKind;
+    errorCode?: NativeTelemetryErrorCode;
+    diagnostics?: NativeTelemetryDiagnostics;
+};
+export interface NativeTelemetrySink {
+    recordConnect(event: NativeConnectTelemetryEvent): void;
+    recordVendorSkip(event: NativeVendorSkipTelemetryEvent): void;
+    recordLifecycle(event: NativeLifecycleTelemetryEvent): void;
+    /** Application bytes returned by read or accepted by a successful write. Excludes tunnel/TLS framing. */
+    recordBytes(event: {
+        direction: "in" | "out";
+        bytes: number;
+    }): void;
+    recordError(event: {
+        errorCode: NativeTelemetryErrorCode;
+        diagnostics?: NativeTelemetryDiagnostics;
+    }): void;
+}
+export type NativeAttemptSample = NativeConnectTelemetryEvent & {
+    n: number;
+};
+export type NativeTelemetryLogPayload = {
+    attempts: number;
+    connectMs: number;
+    tunnelMs: number;
+    vendorSkips: number;
+    vendorSkipReasons: {
+        reason: NativeTelemetryVendorSkipReason;
+        count: number;
+    }[];
+    drain: number;
+    drainAcknowledged: number;
+    drainErrors: number;
+    drainMissingHandler: number;
+    idle: number;
+    expiry: number;
+    bytesIn: number;
+    bytesOut: number;
+    lastErrorCode?: NativeTelemetryErrorCode;
+    lastErrorDiagnostics?: NativeTelemetryDiagnostics;
+    attemptSamples?: NativeAttemptSample[];
+    attemptSamplesDropped?: number;
+    vendorSkipSamples?: NativeVendorSkipTelemetryEvent[];
+    vendorSkipSamplesDropped?: number;
+};
+export type NativeTelemetryHeaderPayload = {
+    attempts: number;
+    connectMs: number;
+    tunnelMs: number;
+    vendorSkips: number;
+    vendorSkipReasons: {
+        reason: ClosedEnum<NativeTelemetryVendorSkipReason>;
+        count: number;
+    }[];
+    drain: number;
+    drainAcknowledged: number;
+    drainErrors: number;
+    drainMissingHandler: number;
+    idle: number;
+    expiry: number;
+    bytesIn: number;
+    bytesOut: number;
+    lastErrorCode?: ClosedEnum<NativeTelemetryErrorCode>;
+    attemptSamples?: {
+        n: number;
+        kind: ClosedEnum<NativeTelemetryKind>;
+        outcome: ClosedEnum<NativeTelemetryOutcome>;
+        ms: number;
+        tunnelMs: number;
+        proxyUsed: boolean;
+        errorCode?: ClosedEnum<NativeTelemetryErrorCode>;
+    }[];
+    attemptSamplesDropped?: number;
+    vendorSkipSamplesDropped?: number;
+};
+export declare class NativeTelemetryCollector implements NativeTelemetrySink, TelemetryContributor<NativeTelemetryLogPayload, NativeTelemetryHeaderPayload> {
+    #private;
+    readonly key: "native";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    recordConnect(event: NativeConnectTelemetryEvent): void;
+    recordVendorSkip(event: NativeVendorSkipTelemetryEvent): void;
+    recordLifecycle(event: NativeLifecycleTelemetryEvent): void;
+    recordBytes(event: {
+        direction: "in" | "out";
+        bytes: number;
+    }): void;
+    recordError(event: {
+        errorCode: NativeTelemetryErrorCode;
+        diagnostics?: NativeTelemetryDiagnostics;
+    }): void;
+    toLogPayload(): NativeTelemetryLogPayload | undefined;
+    toHeaderPayload(log: NativeTelemetryLogPayload): NativeTelemetryHeaderPayload;
+}

package/dist/runtime/native-telemetry.js

@@ -0,0 +1,231 @@
+import { Buffer } from "node:buffer";
+import { closedEnum } from "./request-telemetry.js";
+const MAX_SAMPLES = 24;
+function integer(value) {
+    return Math.max(0, Math.floor(Number.isFinite(value) ? value : 0));
+}
+function saturatingAdd(a, b) {
+    if (!Number.isFinite(a) || !Number.isFinite(b))
+        return Number.MAX_SAFE_INTEGER;
+    return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+function boundedText(value, redact) {
+    let result;
+    try {
+        result = redact ? redact(value) : value;
+        if (typeof result !== "string")
+            return "[REDACTION_FAILED]";
+    }
+    catch {
+        return "[REDACTION_FAILED]";
+    }
+    // Do not slice caller text: a substring may retain the entire vendor response.
+    const length = Math.min(result.length, 300);
+    const units = Buffer.alloc(length * 2);
+    for (let index = 0; index < length; index++)
+        units.writeUInt16LE(result.charCodeAt(index), index * 2);
+    return units.toString("utf16le");
+}
+function diagnostics(value, redact) {
+    const result = {};
+    for (const key of [
+        "host",
+        "serverName",
+        "protocol",
+        "sessionId",
+        "expiresAt",
+        "errorName",
+        "errorMessage",
+        "causeName",
+        "causeMessage",
+        "systemCode",
+    ]) {
+        if (value[key] !== undefined)
+            result[key] = boundedText(value[key], redact);
+    }
+    for (const key of ["port", "timeoutMs", "idleTimeoutMs", "status", "socksReplyCode"]) {
+        if (value[key] !== undefined)
+            result[key] = integer(value[key]);
+    }
+    if (value.sticky !== undefined)
+        result.sticky = value.sticky;
+    if (value.missingFields)
+        result.missingFields = value.missingFields
+            .slice(0, MAX_SAMPLES)
+            .map((field) => boundedText(field, redact));
+    return result;
+}
+function copyDiagnostics(value) {
+    return { ...value, ...(value.missingFields ? { missingFields: [...value.missingFields] } : {}) };
+}
+export class NativeTelemetryCollector {
+    key = "native";
+    #redact;
+    #recorded = false;
+    #attempts = 0;
+    #connectMs = 0;
+    #tunnelMs = 0;
+    #vendorSkips = 0;
+    #vendorSkipReasons = new Map();
+    #lifecycle = {
+        drain: 0,
+        drain_acknowledged: 0,
+        drain_error: 0,
+        drain_missing_handler: 0,
+        idle: 0,
+        expiry: 0,
+    };
+    #bytesIn = 0;
+    #bytesOut = 0;
+    #lastErrorCode;
+    #lastErrorDiagnostics;
+    #attemptSamples = [];
+    #attemptSamplesDropped = 0;
+    #vendorSkipSamples = [];
+    #vendorSkipSamplesDropped = 0;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    recordConnect(event) {
+        this.#recorded = true;
+        const ms = saturatingAdd(0, event.ms);
+        const tunnelMs = saturatingAdd(0, event.tunnelMs);
+        this.#attempts = saturatingAdd(this.#attempts, 1);
+        this.#connectMs = saturatingAdd(this.#connectMs, ms);
+        this.#tunnelMs = saturatingAdd(this.#tunnelMs, tunnelMs);
+        if (event.errorCode)
+            this.recordError({ errorCode: event.errorCode, diagnostics: event.diagnostics });
+        if (this.#attemptSamples.length < MAX_SAMPLES) {
+            this.#attemptSamples.push({
+                n: this.#attempts,
+                kind: event.kind,
+                outcome: event.outcome,
+                ms,
+                tunnelMs,
+                proxyUsed: event.proxyUsed,
+                ...(event.vendor ? { vendor: event.vendor } : {}),
+                ...(event.errorCode ? { errorCode: event.errorCode } : {}),
+                ...(event.diagnostics ? { diagnostics: diagnostics(event.diagnostics, this.#redact) } : {}),
+            });
+        }
+        else
+            this.#attemptSamplesDropped = saturatingAdd(this.#attemptSamplesDropped, 1);
+    }
+    recordVendorSkip(event) {
+        this.#recorded = true;
+        this.#vendorSkips = saturatingAdd(this.#vendorSkips, 1);
+        this.#vendorSkipReasons.set(event.reason, saturatingAdd(this.#vendorSkipReasons.get(event.reason) ?? 0, 1));
+        if (this.#vendorSkipSamples.length < MAX_SAMPLES) {
+            this.#vendorSkipSamples.push({
+                vendor: event.vendor,
+                reason: event.reason,
+                ...(event.diagnostics ? { diagnostics: diagnostics(event.diagnostics, this.#redact) } : {}),
+            });
+        }
+        else
+            this.#vendorSkipSamplesDropped = saturatingAdd(this.#vendorSkipSamplesDropped, 1);
+    }
+    recordLifecycle(event) {
+        this.#recorded = true;
+        this.#lifecycle[event.kind] = saturatingAdd(this.#lifecycle[event.kind], 1);
+        if (event.errorCode)
+            this.recordError({ errorCode: event.errorCode, diagnostics: event.diagnostics });
+    }
+    recordBytes(event) {
+        this.#recorded = true;
+        if (event.direction === "in")
+            this.#bytesIn = saturatingAdd(this.#bytesIn, event.bytes);
+        else
+            this.#bytesOut = saturatingAdd(this.#bytesOut, event.bytes);
+    }
+    recordError(event) {
+        this.#recorded = true;
+        this.#lastErrorCode = event.errorCode;
+        this.#lastErrorDiagnostics = event.diagnostics
+            ? diagnostics(event.diagnostics, this.#redact)
+            : undefined;
+    }
+    toLogPayload() {
+        if (!this.#recorded)
+            return undefined;
+        return {
+            attempts: this.#attempts,
+            connectMs: this.#connectMs,
+            tunnelMs: this.#tunnelMs,
+            vendorSkips: this.#vendorSkips,
+            vendorSkipReasons: [...this.#vendorSkipReasons].map(([reason, count]) => ({ reason, count })),
+            drain: this.#lifecycle.drain,
+            drainAcknowledged: this.#lifecycle.drain_acknowledged,
+            drainErrors: this.#lifecycle.drain_error,
+            drainMissingHandler: this.#lifecycle.drain_missing_handler,
+            idle: this.#lifecycle.idle,
+            expiry: this.#lifecycle.expiry,
+            bytesIn: this.#bytesIn,
+            bytesOut: this.#bytesOut,
+            ...(this.#lastErrorCode ? { lastErrorCode: this.#lastErrorCode } : {}),
+            ...(this.#lastErrorDiagnostics
+                ? { lastErrorDiagnostics: copyDiagnostics(this.#lastErrorDiagnostics) }
+                : {}),
+            ...(this.#attemptSamples.length
+                ? {
+                    attemptSamples: this.#attemptSamples.map((sample) => ({
+                        ...sample,
+                        ...(sample.diagnostics ? { diagnostics: copyDiagnostics(sample.diagnostics) } : {}),
+                    })),
+                }
+                : {}),
+            ...(this.#attemptSamplesDropped
+                ? { attemptSamplesDropped: this.#attemptSamplesDropped }
+                : {}),
+            ...(this.#vendorSkipSamples.length
+                ? {
+                    vendorSkipSamples: this.#vendorSkipSamples.map((sample) => ({
+                        ...sample,
+                        ...(sample.diagnostics ? { diagnostics: copyDiagnostics(sample.diagnostics) } : {}),
+                    })),
+                }
+                : {}),
+            ...(this.#vendorSkipSamplesDropped
+                ? { vendorSkipSamplesDropped: this.#vendorSkipSamplesDropped }
+                : {}),
+        };
+    }
+    toHeaderPayload(log) {
+        return {
+            attempts: log.attempts,
+            connectMs: log.connectMs,
+            tunnelMs: log.tunnelMs,
+            vendorSkips: log.vendorSkips,
+            vendorSkipReasons: log.vendorSkipReasons.map(({ reason, count }) => ({
+                reason: closedEnum(reason),
+                count,
+            })),
+            drain: log.drain,
+            drainAcknowledged: log.drainAcknowledged,
+            drainErrors: log.drainErrors,
+            drainMissingHandler: log.drainMissingHandler,
+            idle: log.idle,
+            expiry: log.expiry,
+            bytesIn: log.bytesIn,
+            bytesOut: log.bytesOut,
+            ...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+            ...(log.attemptSamples
+                ? {
+                    attemptSamples: log.attemptSamples.map((sample) => ({
+                        n: sample.n,
+                        kind: closedEnum(sample.kind),
+                        outcome: closedEnum(sample.outcome),
+                        ms: sample.ms,
+                        tunnelMs: sample.tunnelMs,
+                        proxyUsed: sample.proxyUsed,
+                        ...(sample.errorCode ? { errorCode: closedEnum(sample.errorCode) } : {}),
+                    })),
+                }
+                : {}),
+            ...(log.attemptSamplesDropped ? { attemptSamplesDropped: log.attemptSamplesDropped } : {}),
+            ...(log.vendorSkipSamplesDropped
+                ? { vendorSkipSamplesDropped: log.vendorSkipSamplesDropped }
+                : {}),
+        };
+    }
+}

package/dist/runtime/ocr-telemetry.d.ts

@@ -0,0 +1,82 @@
+import type { OcrContext } from "../types.js";
+import { type ClosedEnum, type SpanIndex, type TelemetryContributor } from "./request-telemetry.js";
+export type OcrTelemetryBackend = "cloudflare-workers-ai" | "openai-compatible" | "custom" | "unavailable";
+export type OcrTelemetryEngine = "workers-ai" | "openai-compatible" | "custom";
+export type OcrTelemetryErrorCode = "OCR_UNAVAILABLE" | "UNSUPPORTED_OCR_BACKEND" | "OCR_UPSTREAM_FAILED" | "OCR_INCOMPLETE_RESPONSE" | "transport_network_error" | "transport_timeout" | "other";
+export type OcrTelemetryModel = "gemma-4-26b-a4b-it" | "glm-ocr" | "moondream3.1-9B-A2B" | "kimi-k2.7-code";
+export type OcrTelemetryFinishReason = "stop" | "length" | "content_filter" | "tool_calls" | "function_call" | "error" | "unknown";
+export type OcrTelemetryEvent = {
+    backend: OcrTelemetryBackend;
+    engine: OcrTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    bytesIn?: number;
+    bytesOut?: number;
+    candidates?: number;
+    warnings?: number;
+    errorCode?: OcrTelemetryErrorCode;
+    diagnostics?: string;
+    finishReason?: OcrTelemetryFinishReason;
+};
+export interface OcrTelemetrySink {
+    record(event: OcrTelemetryEvent): void;
+    markTelemetryFailed?(): void;
+}
+export type OcrTelemetryLogPayload = {
+    telemetryFailed?: true;
+    diagnostics?: string[];
+    backend: OcrTelemetryBackend;
+    engine: OcrTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    bytesIn: number;
+    bytesOut: number;
+    candidates: number;
+    warnings: number;
+    lastErrorCode?: OcrTelemetryErrorCode;
+    finishReason?: OcrTelemetryFinishReason;
+    samples?: Array<Omit<OcrTelemetryEvent, "backend" | "engine" | "model" | "diagnostics">>;
+    samplesDropped?: number;
+};
+export type OcrTelemetryHeaderPayload = {
+    backend: ClosedEnum<OcrTelemetryBackend>;
+    engine: ClosedEnum<OcrTelemetryEngine>;
+    model?: ClosedEnum<OcrTelemetryModel>;
+    ms: number;
+    status?: number;
+    bytesIn: number;
+    bytesOut: number;
+    candidates: number;
+    warnings: number;
+    lastErrorCode?: ClosedEnum<OcrTelemetryErrorCode>;
+    finishReason?: ClosedEnum<OcrTelemetryFinishReason>;
+    samples?: Array<{
+        ms: number;
+        status?: number;
+        bytesIn?: number;
+        bytesOut?: number;
+        candidates?: number;
+        warnings?: number;
+        errorCode?: ClosedEnum<OcrTelemetryErrorCode>;
+        finishReason?: ClosedEnum<OcrTelemetryFinishReason>;
+    }>;
+    samplesDropped?: number;
+};
+export declare class OcrTelemetryCollector implements OcrTelemetrySink, TelemetryContributor<OcrTelemetryLogPayload, OcrTelemetryHeaderPayload> {
+    #private;
+    readonly key: "ocr";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    markTelemetryFailed(): void;
+    record(event: OcrTelemetryEvent): void;
+    toLogPayload(_spans: SpanIndex): OcrTelemetryLogPayload | undefined;
+    toHeaderPayload(log: OcrTelemetryLogPayload): OcrTelemetryHeaderPayload;
+}
+export declare function bindOcrTelemetry(context: OcrContext, sink: OcrTelemetrySink, options?: {
+    backend?: OcrTelemetryBackend;
+    engine?: OcrTelemetryEngine;
+    model?: string;
+}): OcrContext;

package/dist/runtime/ocr-telemetry.js

@@ -0,0 +1,192 @@
+import { add, capabilityErrorText, capabilityFacts, capabilityMetadata, capabilityText, inputBytes, integer, observeCapability, registerCapabilityInput, } from "./capability-telemetry.js";
+import { closedEnum, } from "./request-telemetry.js";
+const ERROR_CODES = new Set([
+    "OCR_UNAVAILABLE",
+    "UNSUPPORTED_OCR_BACKEND",
+    "OCR_UPSTREAM_FAILED",
+    "OCR_INCOMPLETE_RESPONSE",
+    "transport_network_error",
+    "transport_timeout",
+    "other",
+]);
+const MODELS = new Map([
+    ["@cf/google/gemma-4-26b-a4b-it", "gemma-4-26b-a4b-it"],
+    ["zai-org/GLM-OCR", "glm-ocr"],
+    ["@cf/moondream/moondream3.1-9B-A2B", "moondream3.1-9B-A2B"],
+    ["@cf/moonshotai/kimi-k2.7-code", "kimi-k2.7-code"],
+]);
+function errorCode(error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+    return typeof code === "string" && ERROR_CODES.has(code)
+        ? code
+        : "other";
+}
+function finishReason(value, failed) {
+    switch (value) {
+        case "stop":
+        case "length":
+        case "content_filter":
+        case "tool_calls":
+        case "function_call":
+            return value;
+        default:
+            return value === undefined ? (failed ? "error" : "stop") : "unknown";
+    }
+}
+export class OcrTelemetryCollector {
+    key = "ocr";
+    #redact;
+    #samples = [];
+    #summary;
+    #diagnostics = [];
+    #dropped = 0;
+    #failed = false;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    markTelemetryFailed() {
+        this.#failed = true;
+        this.#summary ??= {
+            backend: "custom",
+            engine: "custom",
+            ms: 0,
+            bytesIn: 0,
+            bytesOut: 0,
+            candidates: 0,
+            warnings: 0,
+        };
+    }
+    record(event) {
+        const sample = {
+            ms: integer(event.ms),
+            ...(event.status === undefined ? {} : { status: integer(event.status) }),
+            ...(event.bytesIn === undefined ? {} : { bytesIn: integer(event.bytesIn) }),
+            ...(event.bytesOut === undefined ? {} : { bytesOut: integer(event.bytesOut) }),
+            ...(event.candidates === undefined ? {} : { candidates: integer(event.candidates) }),
+            ...(event.warnings === undefined ? {} : { warnings: integer(event.warnings) }),
+            ...(event.errorCode ? { errorCode: event.errorCode } : {}),
+            ...(event.finishReason ? { finishReason: event.finishReason } : {}),
+            ...(event.diagnostics === undefined
+                ? {}
+                : { diagnostics: capabilityText(event.diagnostics, this.#redact, true) }),
+        };
+        const prior = this.#summary;
+        this.#summary = {
+            backend: event.backend,
+            engine: event.engine,
+            ...(event.model === undefined ? {} : { model: capabilityText(event.model, this.#redact) }),
+            ms: add(prior?.ms ?? 0, sample.ms),
+            ...(sample.status === undefined ? {} : { status: sample.status }),
+            bytesIn: add(prior?.bytesIn ?? 0, sample.bytesIn ?? 0),
+            bytesOut: add(prior?.bytesOut ?? 0, sample.bytesOut ?? 0),
+            candidates: add(prior?.candidates ?? 0, sample.candidates ?? 0),
+            warnings: add(prior?.warnings ?? 0, sample.warnings ?? 0),
+            ...(event.errorCode ? { lastErrorCode: event.errorCode } : {}),
+            ...(event.finishReason ? { finishReason: event.finishReason } : {}),
+        };
+        if (this.#samples.length < 24) {
+            const { diagnostics, ...closedSample } = sample;
+            this.#samples.push(closedSample);
+            if (diagnostics !== undefined)
+                this.#diagnostics.push(diagnostics);
+        }
+        else
+            this.#dropped = add(this.#dropped, 1);
+    }
+    toLogPayload(_spans) {
+        if (!this.#summary)
+            return undefined;
+        return {
+            ...this.#summary,
+            ...(this.#diagnostics.length ? { diagnostics: [...this.#diagnostics] } : {}),
+            ...(this.#failed ? { telemetryFailed: true } : {}),
+            samples: this.#samples.map((s) => ({ ...s })),
+            ...(this.#dropped ? { samplesDropped: this.#dropped } : {}),
+        };
+    }
+    toHeaderPayload(log) {
+        return {
+            backend: closedEnum(log.backend),
+            engine: closedEnum(log.engine),
+            ...(log.model && MODELS.has(log.model) ? { model: closedEnum(MODELS.get(log.model)) } : {}),
+            ms: log.ms,
+            ...(log.status === undefined ? {} : { status: log.status }),
+            bytesIn: log.bytesIn,
+            bytesOut: log.bytesOut,
+            candidates: log.candidates,
+            warnings: log.warnings,
+            ...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+            ...(log.finishReason ? { finishReason: closedEnum(log.finishReason) } : {}),
+            ...(log.samples
+                ? {
+                    samples: log.samples.map((s) => ({
+                        ms: s.ms,
+                        ...(s.status === undefined ? {} : { status: s.status }),
+                        ...(s.bytesIn === undefined ? {} : { bytesIn: s.bytesIn }),
+                        ...(s.bytesOut === undefined ? {} : { bytesOut: s.bytesOut }),
+                        ...(s.candidates === undefined ? {} : { candidates: s.candidates }),
+                        ...(s.warnings === undefined ? {} : { warnings: s.warnings }),
+                        ...(s.errorCode ? { errorCode: closedEnum(s.errorCode) } : {}),
+                        ...(s.finishReason ? { finishReason: closedEnum(s.finishReason) } : {}),
+                    })),
+                }
+                : {}),
+            ...(log.samplesDropped ? { samplesDropped: log.samplesDropped } : {}),
+        };
+    }
+}
+export function bindOcrTelemetry(context, sink, options = {}) {
+    const metadata = capabilityMetadata(context);
+    const backend = options.backend ?? metadata?.backend ?? "custom";
+    const engine = options.engine ?? metadata?.engine ?? "custom";
+    const model = options.model ?? metadata?.model;
+    async function run(input, operation) {
+        const started = performance.now();
+        const facts = {};
+        observeCapability(sink, () => registerCapabilityInput(input));
+        let result;
+        try {
+            result = await capabilityFacts.run(facts, operation);
+        }
+        catch (error) {
+            observeCapability(sink, () => {
+                const status = error &&
+                    typeof error === "object" &&
+                    "status" in error &&
+                    typeof error.status === "number"
+                    ? error.status
+                    : undefined;
+                return sink.record({
+                    backend,
+                    engine,
+                    model,
+                    ms: performance.now() - started,
+                    status: facts.status ?? status,
+                    bytesIn: inputBytes(input),
+                    errorCode: errorCode(error),
+                    finishReason: finishReason(facts.finishReason, true),
+                    diagnostics: `${capabilityErrorText(error)} ${facts.diagnostics ?? ""}`,
+                });
+            });
+            throw error;
+        }
+        observeCapability(sink, () => sink.record({
+            backend,
+            engine,
+            model: result.model,
+            ms: performance.now() - started,
+            status: facts.status,
+            bytesIn: inputBytes(input),
+            bytesOut: Buffer.byteLength(result.text),
+            candidates: result.candidates?.length ?? 0,
+            finishReason: finishReason(facts.finishReason, false),
+            warnings: result.warnings?.length ?? 0,
+        }));
+        return result;
+    }
+    return {
+        ...context,
+        recognize: (request) => run(request.image, () => context.recognize(request)),
+        extractCaptchaText: (image, opts) => run(image, () => context.extractCaptchaText(image, opts)),
+    };
+}

package/dist/runtime/ocr.d.ts

@@ -0,0 +1,29 @@
+import type { OcrCaptchaCandidate, OcrCaptchaOptions, OcrContext, ProviderOcrConfig } from "../types.js";
+export { CLOUDFLARE_ACCOUNT_ID_ENV } from "./stt.js";
+export declare const APIFUSE__OCR__BACKEND_ENV = "APIFUSE__OCR__BACKEND";
+export declare const APIFUSE__OCR__MODEL_ENV = "APIFUSE__OCR__MODEL";
+export declare const APIFUSE__OCR__CLOUDFLARE_API_TOKEN_ENV = "APIFUSE__OCR__CLOUDFLARE_API_TOKEN";
+export declare const APIFUSE__OCR__BASE_URL_ENV = "APIFUSE__OCR__BASE_URL";
+export declare const APIFUSE__OCR__API_KEY_ENV = "APIFUSE__OCR__API_KEY";
+export declare const CLOUDFLARE_WORKERS_AI_OCR_BACKEND = "cloudflare-workers-ai";
+export declare const OPENAI_COMPATIBLE_OCR_BACKEND = "openai-compatible";
+export declare const DEFAULT_CLOUDFLARE_WORKERS_AI_OCR_MODEL = "@cf/google/gemma-4-26b-a4b-it";
+export declare const DEFAULT_OCR_TIMEOUT_MS = 30000;
+type EnvLike = Record<string, string | undefined>;
+type CloudflareWorkersAiOcrClientOptions = {
+    accountId: string;
+    apiToken: string;
+    model?: string;
+    fetch?: typeof fetch;
+};
+type OpenAiCompatibleOcrClientOptions = {
+    baseUrl: string;
+    apiKey?: string;
+    model: string;
+    fetch?: typeof fetch;
+};
+export declare function createUnsupportedOcrClient(reason?: string): OcrContext;
+export declare function createOcrClientFromEnv(config: ProviderOcrConfig | undefined, env?: EnvLike): OcrContext;
+export declare function createCloudflareWorkersAiOcrClient(options: CloudflareWorkersAiOcrClientOptions): OcrContext;
+export declare function createOpenAiCompatibleOcrClient(options: OpenAiCompatibleOcrClientOptions): OcrContext;
+export declare function extractCaptchaCandidates(modelText: string, options?: OcrCaptchaOptions): readonly OcrCaptchaCandidate[];