@apifuse/provider-sdk 2.2.0-beta.62 → 2.2.0-beta.64

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

@@ -0,0 +1,77 @@
+import type { SttContext } from "../types.js";
+import { type ClosedEnum, type SpanIndex, type TelemetryContributor } from "./request-telemetry.js";
+export type SttTelemetryBackend = "cloudflare-workers-ai" | "custom" | "unavailable";
+export type SttTelemetryEngine = "workers-ai" | "custom";
+export type SttTelemetryErrorCode = "STT_UNAVAILABLE" | "UNSUPPORTED_STT_BACKEND" | "STT_UPSTREAM_FAILED" | "STT_AUDIO_TOO_LARGE" | "UNSUPPORTED_STT_OPTION" | "INVALID_STT_AUDIO" | "INVALID_STT_VERIFICATION_CODE_OPTIONS" | "NO_CODE_FOUND" | "AMBIGUOUS_CODE" | "transport_network_error" | "transport_timeout" | "other";
+export type SttTelemetryModel = "whisper-large-v3-turbo";
+export type SttTelemetryEvent = {
+    backend: SttTelemetryBackend;
+    engine: SttTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    audioBytes?: number;
+    durationMs?: number;
+    usage?: number;
+    warnings?: number;
+    errorCode?: SttTelemetryErrorCode;
+    diagnostics?: string;
+};
+export interface SttTelemetrySink {
+    record(event: SttTelemetryEvent): void;
+    markTelemetryFailed?(): void;
+}
+export type SttTelemetryLogPayload = {
+    telemetryFailed?: true;
+    diagnostics?: string[];
+    backend: SttTelemetryBackend;
+    engine: SttTelemetryEngine;
+    model?: string;
+    ms: number;
+    status?: number;
+    audioBytes: number;
+    durationMs: number;
+    usage: number;
+    warnings: number;
+    lastErrorCode?: SttTelemetryErrorCode;
+    samples?: Array<Omit<SttTelemetryEvent, "backend" | "engine" | "model" | "diagnostics">>;
+    samplesDropped?: number;
+};
+export type SttTelemetryHeaderPayload = {
+    backend: ClosedEnum<SttTelemetryBackend>;
+    engine: ClosedEnum<SttTelemetryEngine>;
+    model?: ClosedEnum<SttTelemetryModel>;
+    ms: number;
+    status?: number;
+    audioBytes: number;
+    durationMs: number;
+    usage: number;
+    warnings: number;
+    lastErrorCode?: ClosedEnum<SttTelemetryErrorCode>;
+    samples?: Array<{
+        ms: number;
+        status?: number;
+        audioBytes?: number;
+        durationMs?: number;
+        usage?: number;
+        warnings?: number;
+        errorCode?: ClosedEnum<SttTelemetryErrorCode>;
+    }>;
+    samplesDropped?: number;
+};
+export declare class SttTelemetryCollector implements SttTelemetrySink, TelemetryContributor<SttTelemetryLogPayload, SttTelemetryHeaderPayload> {
+    #private;
+    readonly key: "stt";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    markTelemetryFailed(): void;
+    record(event: SttTelemetryEvent): void;
+    toLogPayload(_spans: SpanIndex): SttTelemetryLogPayload | undefined;
+    toHeaderPayload(log: SttTelemetryLogPayload): SttTelemetryHeaderPayload;
+}
+export declare function bindSttTelemetry(context: SttContext, sink: SttTelemetrySink, options?: {
+    backend?: SttTelemetryBackend;
+    engine?: SttTelemetryEngine;
+    model?: string;
+}): SttContext;

package/dist/runtime/stt-telemetry.js

@@ -0,0 +1,176 @@
+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([
+    "STT_UNAVAILABLE",
+    "UNSUPPORTED_STT_BACKEND",
+    "STT_UPSTREAM_FAILED",
+    "STT_AUDIO_TOO_LARGE",
+    "UNSUPPORTED_STT_OPTION",
+    "INVALID_STT_AUDIO",
+    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+    "NO_CODE_FOUND",
+    "AMBIGUOUS_CODE",
+    "transport_network_error",
+    "transport_timeout",
+    "other",
+]);
+const MODELS = new Map([
+    ["@cf/openai/whisper-large-v3-turbo", "whisper-large-v3-turbo"],
+]);
+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";
+}
+export class SttTelemetryCollector {
+    key = "stt";
+    #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,
+            audioBytes: 0,
+            durationMs: 0,
+            usage: 0,
+            warnings: 0,
+        };
+    }
+    record(event) {
+        const sample = {
+            ms: integer(event.ms),
+            ...(event.status === undefined ? {} : { status: integer(event.status) }),
+            ...(event.audioBytes === undefined ? {} : { audioBytes: integer(event.audioBytes) }),
+            ...(event.durationMs === undefined ? {} : { durationMs: integer(event.durationMs) }),
+            ...(event.usage === undefined ? {} : { usage: integer(event.usage) }),
+            ...(event.warnings === undefined ? {} : { warnings: integer(event.warnings) }),
+            ...(event.errorCode ? { errorCode: event.errorCode } : {}),
+            ...(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 }),
+            audioBytes: add(prior?.audioBytes ?? 0, sample.audioBytes ?? 0),
+            durationMs: add(prior?.durationMs ?? 0, sample.durationMs ?? 0),
+            usage: add(prior?.usage ?? 0, sample.usage ?? 0),
+            warnings: add(prior?.warnings ?? 0, sample.warnings ?? 0),
+            ...(event.errorCode ? { lastErrorCode: event.errorCode } : {}),
+        };
+        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 }),
+            audioBytes: log.audioBytes,
+            durationMs: log.durationMs,
+            usage: log.usage,
+            warnings: log.warnings,
+            ...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+            ...(log.samples
+                ? {
+                    samples: log.samples.map((s) => ({
+                        ms: s.ms,
+                        ...(s.status === undefined ? {} : { status: s.status }),
+                        ...(s.audioBytes === undefined ? {} : { audioBytes: s.audioBytes }),
+                        ...(s.durationMs === undefined ? {} : { durationMs: s.durationMs }),
+                        ...(s.usage === undefined ? {} : { usage: s.usage }),
+                        ...(s.warnings === undefined ? {} : { warnings: s.warnings }),
+                        ...(s.errorCode ? { errorCode: closedEnum(s.errorCode) } : {}),
+                    })),
+                }
+                : {}),
+            ...(log.samplesDropped ? { samplesDropped: log.samplesDropped } : {}),
+        };
+    }
+}
+export function bindSttTelemetry(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,
+                    audioBytes: inputBytes(input),
+                    errorCode: errorCode(error),
+                    diagnostics: `${capabilityErrorText(error)} ${facts.diagnostics ?? ""}`,
+                });
+            });
+            throw error;
+        }
+        observeCapability(sink, () => sink.record({
+            backend,
+            engine,
+            model: model,
+            ms: performance.now() - started,
+            status: facts.status,
+            audioBytes: result.usage?.audioBytes ?? inputBytes(input),
+            durationMs: result.durationMs,
+            usage: result.usage?.audioDurationMs,
+            warnings: result.warnings?.length ?? 0,
+        }));
+        return result;
+    }
+    return {
+        ...context,
+        transcribe: (request) => run(request.audio, () => context.transcribe(request)),
+        extractVerificationCode: (text, opts) => context.extractVerificationCode(text, opts),
+    };
+}

package/dist/runtime/stt.js

@@ -1,5 +1,7 @@
-import { readDiagnosticEnv } from "./diagnostic-env.js";
 import { ProviderError, TransportError, ValidationError } from "../errors.js";
+import { readCapabilityErrorBody } from "./capability-response.js";
+import { captureCapability, registerCapabilityInput, tagCapability, } from "./capability-telemetry.js";
+import { readDiagnosticEnv, registerDiagnosticValue } from "./diagnostic-env.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";
@@ -15,7 +17,7 @@ function providerError(message, options) {
     return new ProviderError(message, options);
 }
 function createErrorSttClient(options) {
-    return {
+    return tagCapability({
         async transcribe() {
             throw providerError(options.message, {
                 code: options.code,
@@ -23,7 +25,7 @@ function createErrorSttClient(options) {
             });
         },
         extractVerificationCode,
-    };
+    }, { backend: "unavailable", engine: "custom" });
 }
 export function createUnsupportedSttClient(reason) {
     return createErrorSttClient({
@@ -209,8 +211,11 @@ function toSttTranscript(payload, audioBytes) {
 export function createCloudflareWorkersAiSttClient(options) {
     const model = options.model ?? DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL;
     const runFetch = options.fetch ?? fetch;
-    return {
+    return tagCapability({
         async transcribe(request) {
+            registerCapabilityInput(request.audio);
+            registerDiagnosticValue(options.apiToken);
+            registerDiagnosticValue(`Bearer ${options.apiToken}`);
             const warnings = [];
             if (request.initialPrompt && effectivePromptPolicy(request) !== "custom-hint") {
                 const warning = warnOrThrowUnsupportedOption(request, "initialPrompt is honored only when promptPolicy is custom-hint");
@@ -235,16 +240,20 @@ export function createCloudflareWorkersAiSttClient(options) {
                 catch (error) {
                     throw toSttTransportError(error);
                 }
-                const payload = await response.json().catch(() => undefined);
+                captureCapability({ status: response.status });
                 if (!response.ok) {
+                    const echoed = await readCapabilityErrorBody(response, timeout.controller.signal);
+                    captureCapability({ diagnostics: echoed });
                     throw new TransportError("STT upstream request failed", {
                         code: "STT_UPSTREAM_FAILED",
                         status: response.status,
                         upstreamStatus: response.status,
                     });
                 }
+                const payload = await response.json().catch(() => undefined);
                 const envelope = unknownRecord(payload);
                 if (envelope?.success === false) {
+                    captureCapability({ diagnostics: JSON.stringify(payload) });
                     throw new TransportError("STT upstream returned an error", {
                         code: "STT_UPSTREAM_FAILED",
                         status: 502,
@@ -270,7 +279,7 @@ export function createCloudflareWorkersAiSttClient(options) {
             }
         },
         extractVerificationCode,
-    };
+    }, { backend: "cloudflare-workers-ai", engine: "workers-ai", model });
 }
 const EN_DIGITS = {
     zero: "0",

package/dist/runtime-boundary-lint.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime boundary lint: provider runtime source must reach the outside world
+ * through the SDK context (`ctx.http`, `ctx.stealth`, `ctx.env`,
+ * `ctx.credential`, `ctx.browser`), not through ambient Node/Bun globals.
+ *
+ * Three rules, all reported at `warn` level in this first release so the
+ * fleet can migrate before the level is raised:
+ *
+ * - `process-env-direct-read`: `process.env.X`, `process.env["X"]`, a bare
+ *   `process.env` object use, and the `Bun.env` equivalents. Runtime bootstrap
+ *   keys (`APIFUSE__RUNTIME__*`) are exempt everywhere because `serve()`
+ *   callers read the port and pod identity before a context exists.
+ * - `node-runtime-module-import`: value imports of `fs`, `fs/promises`, `net`,
+ *   `tls`, `dgram`, `http`, `https`, `http2`, `child_process` (with or without
+ *   the `node:` prefix) via import/export declarations, `require()`, or dynamic
+ *   `import()`, plus the Bun equivalents `Bun.spawn`, `Bun.spawnSync`, `Bun.$`,
+ *   `Bun.file`, `Bun.write`. Type-only imports are not runtime reach and are
+ *   ignored.
+ * - `direct-fetch-call`: a call to the global `fetch` (bare identifier, or
+ *   `globalThis`/`window`/`self`/`global` member). A bare `fetch` call whose
+ *   enclosing scope declares a `fetch` binding (parameter, variable, import,
+ *   function, catch clause) is calling that binding, not the global, and is
+ *   left alone; the check is lexical, so a wrapper that takes `fetch` as a
+ *   parameter does not hide a global `fetch()` elsewhere in the same file.
+ *   `ctx.stealth.fetch()` is a member call and never matches.
+ *
+ * Files are parsed with the script kind their extension implies (`.ts` as
+ * TypeScript, `.tsx` as TSX, …). Parsing everything as TSX would make a
+ * generic arrow (`<T>(value: T) => value`) or an angle-bracket assertion in an
+ * ordinary `.ts` file read as JSX, and everything after it would silently drop
+ * out of the AST.
+ *
+ * Scope is the provider *runtime* source: JavaScript/TypeScript files under
+ * `providerSourceFiles` minus tests, recorded fixtures, the root bootstrap
+ * entrypoints (`dev.ts`, `start.ts`, `deploy.ts`) and the operator tooling
+ * directories (`scripts/`, `tools/`, `bin/`). Tooling legitimately reads the
+ * ambient environment and the filesystem when a human runs it; the rule is
+ * about code the pod executes on behalf of a request.
+ *
+ * A deliberate exception is acknowledged with the same escape hatch the submit
+ * check uses: `// @apifuse-allow <rule>: <reason>` on the finding line or the
+ * line directly above it. Acknowledged findings are reported as information so
+ * `apifuse check` still lists them.
+ */
+import type { LintDiagnostic, ProviderLintInformation, ProviderLintResult } from "./lint.js";
+import { type TypeScriptCompilerModuleLike, type TypeScriptModule } from "./typescript-module.js";
+export declare const PROCESS_ENV_DIRECT_READ_RULE = "process-env-direct-read";
+export declare const NODE_RUNTIME_MODULE_IMPORT_RULE = "node-runtime-module-import";
+export declare const DIRECT_FETCH_CALL_RULE = "direct-fetch-call";
+export declare const RUNTIME_BOUNDARY_RULES: readonly ["process-env-direct-read", "node-runtime-module-import", "direct-fetch-call"];
+export type RuntimeBoundaryRule = (typeof RUNTIME_BOUNDARY_RULES)[number];
+/**
+ * Environment names a provider may read from `process.env` directly. These
+ * are consumed before `serve()` builds a context (port, pod identity), so
+ * `ctx.env` cannot carry them. The whole `APIFUSE__RUNTIME__` family is the
+ * bootstrap contract; nothing else is exempt.
+ */
+export declare const BOOTSTRAP_ENV_NAME_PREFIX = "APIFUSE__RUNTIME__";
+export declare function isBootstrapEnvName(name: string): boolean;
+type RuntimeBoundaryFinding = {
+    rule: RuntimeBoundaryRule;
+    /** 1-based line. */
+    line: number;
+    /** What was reached: the env name, module specifier, or call text. */
+    subject: string;
+};
+type RuntimeBoundaryFileReport = {
+    findings: RuntimeBoundaryFinding[];
+    acknowledged: Array<RuntimeBoundaryFinding & {
+        reason: string;
+    }>;
+};
+/** True for the files the runtime boundary rules look at. */
+export declare function isRuntimeBoundarySourceFile(relativePath: string): boolean;
+/**
+ * Script kind for a provider source file, from its extension. `.tsx`/`.jsx`
+ * enable JSX; everything else (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`,
+ * and the synthetic names used for in-memory sources) does not, so a generic
+ * arrow or `<T>value` assertion in a `.ts` file parses as TypeScript instead
+ * of swallowing the rest of the file as unterminated JSX.
+ */
+export declare function scriptKindForSourceFile(ts: TypeScriptModule, fileName: string): import("typescript").ScriptKind;
+export declare function analyzeRuntimeBoundary(ts: TypeScriptModule, fileName: string, source: string): RuntimeBoundaryFileReport;
+export type RuntimeBoundaryLintInput = {
+    authFlowSource?: string;
+    providerSourceFiles?: Record<string, string>;
+    operations?: Record<string, {
+        handler?: unknown;
+        source?: string;
+    }>;
+};
+/**
+ * Lint the provider runtime boundary. Returns warn-level diagnostics (one per
+ * file and rule, listing every line) and information entries for findings
+ * acknowledged with `@apifuse-allow`.
+ */
+export declare function lintRuntimeBoundary(ts: TypeScriptModule, provider: RuntimeBoundaryLintInput, readOperationSource: (operation: {
+    handler?: unknown;
+    source?: string;
+}) => string): {
+    diagnostics: LintDiagnostic[];
+    information: ProviderLintInformation[];
+};
+export type LintRuntimeBoundarySourcesOptions = {
+    /**
+     * A loaded TypeScript compiler API module to parse with (`typescript` 6.x
+     * or `@typescript/typescript6`). When omitted the SDK resolves one from its
+     * own install location, trying `typescript` first and falling back to
+     * `@typescript/typescript6` when `typescript` is the 7.x native shell
+     * without `createSourceFile`. A caller whose dependency tree pins its own
+     * compiler module (the APIFuse monorepo contract check) passes it here so
+     * the parse does not depend on what hoists next to the SDK.
+     */
+    typescript?: TypeScriptCompilerModuleLike;
+};
+/**
+ * Lint provider runtime source files for the runtime boundary rules without a
+ * provider definition: `files` maps provider-root-relative paths to source
+ * text (the same shape `apifuse check` collects as `providerSourceFiles`).
+ * Out-of-scope paths (tests, recorded fixtures, `.d.ts`, the root
+ * `dev.ts`/`start.ts`/`deploy.ts`, `scripts/`, `tools/`, `bin/`) are skipped
+ * with `isRuntimeBoundarySourceFile`. Diagnostics carry
+ * `field: "sourceFiles.<path>"`; `@apifuse-allow` acknowledgements come back
+ * as `information`.
+ *
+ * Parses with `options.typescript` when given, otherwise with the compiler
+ * module resolved from the installed SDK (see `getTypeScript`). This is the
+ * entry point the platform contract check uses to apply the rules with the
+ * monorepo's SDK pin instead of each provider's own pin.
+ */
+export declare function lintRuntimeBoundarySources(files: Record<string, string>, options?: LintRuntimeBoundarySourcesOptions): ProviderLintResult;
+export {};