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

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,4 +1,8 @@
 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";
 export const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";
@@ -13,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,
@@ -21,7 +25,7 @@ function createErrorSttClient(options) {
             });
         },
         extractVerificationCode,
-    };
+    }, { backend: "unavailable", engine: "custom" });
 }
 export function createUnsupportedSttClient(reason) {
     return createErrorSttClient({
@@ -31,7 +35,7 @@ export function createUnsupportedSttClient(reason) {
     });
 }
 function normalizedEnvValue(env, key) {
-    const value = env[key]?.trim();
+    const value = readDiagnosticEnv(key, env)?.trim();
     return value ? value : undefined;
 }
 export function createSttClientFromEnv(config, env = process.env) {
@@ -52,7 +56,7 @@ export function createSttClientFromEnv(config, env = process.env) {
         });
     }
     const accountId = env.APIFUSE__CLOUDFLARE__ACCOUNT_ID?.trim();
-    const apiToken = env.APIFUSE__STT__CLOUDFLARE_API_TOKEN?.trim();
+    const apiToken = readDiagnosticEnv(APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, env)?.trim();
     if (!accountId || !apiToken) {
         return createUnsupportedSttClient(`STT backend ${backend} requires ${CLOUDFLARE_ACCOUNT_ID_ENV} and ${APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV}`);
     }
@@ -112,12 +116,6 @@ function warnOrThrowUnsupportedOption(request, message) {
 function normalizeCloudflareLanguage(language) {
     return language?.split("-")[0]?.toLowerCase();
 }
-function isTimeoutLikeError(error) {
-    return (error instanceof Error &&
-        (error.name === "AbortError" ||
-            error.name === "TimeoutError" ||
-            /\b(timed out|timeout|deadline exceeded)\b/i.test(error.message)));
-}
 function toSttTransportError(error) {
     if (error instanceof TransportError)
         return error;
@@ -134,12 +132,6 @@ function toSttTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-function createTimeoutController(signalTimeoutMs) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
-    timeout.unref?.();
-    return { controller, clear: () => clearTimeout(timeout) };
-}
 function toCloudflareInput(request) {
     const prompt = resolveSttPrompt(request);
     const input = {
@@ -219,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");
@@ -245,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,
@@ -280,7 +279,7 @@ export function createCloudflareWorkersAiSttClient(options) {
             }
         },
         extractVerificationCode,
-    };
+    }, { backend: "cloudflare-workers-ai", engine: "workers-ai", model });
 }
 const EN_DIGITS = {
     zero: "0",

package/dist/runtime/timeout.d.ts

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

package/dist/runtime/timeout.js

@@ -0,0 +1,12 @@
+export function isTimeoutLikeError(error) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" ||
+            error.name === "TimeoutError" ||
+            /\b(timed out|timeout|deadline exceeded)\b/i.test(error.message)));
+}
+export function createTimeoutController(signalTimeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
+    timeout.unref?.();
+    return { controller, clear: () => clearTimeout(timeout) };
+}

package/dist/runtime/trace-config.d.ts

@@ -0,0 +1,12 @@
+import type { TraceConfig } from "../types.js";
+/** SDK-owned environment variable names for server trace output. */
+export declare const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export declare const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+type EnvLike = Record<string, string | undefined>;
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export declare function resolveTraceConfigFromEnv(env?: EnvLike): TraceConfig | undefined;
+export {};

package/dist/runtime/trace-config.js

@@ -0,0 +1,62 @@
+/** SDK-owned environment variable names for server trace output. */
+export const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+const TRACE_EXPORTER_LOOKUP = {
+    console: true,
+    json: true,
+    otlp: true,
+    none: true,
+};
+const TRACE_EXPORTERS = new Set(Object.keys(TRACE_EXPORTER_LOOKUP));
+const emittedWarnings = new Set();
+function warnOnce(key, message) {
+    if (emittedWarnings.has(key))
+        return;
+    emittedWarnings.add(key);
+    console.warn(message);
+}
+function parseEnabled(raw) {
+    if (raw === undefined)
+        return undefined;
+    switch (raw.trim().toLowerCase()) {
+        case "1":
+        case "true":
+        case "yes":
+        case "on":
+            return true;
+        case "0":
+        case "false":
+        case "no":
+        case "off":
+            return false;
+        default:
+            warnOnce(APIFUSE__TRACE__ENABLED, "[apifuse] Invalid APIFUSE__TRACE__ENABLED; falling back to disabled tracing.");
+            return false;
+    }
+}
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export function resolveTraceConfigFromEnv(env = process.env) {
+    const enabledRaw = env[APIFUSE__TRACE__ENABLED];
+    const exporterRaw = env[APIFUSE__TRACE__EXPORTER];
+    if (enabledRaw === undefined && exporterRaw === undefined) {
+        return undefined;
+    }
+    const enabled = parseEnabled(enabledRaw);
+    const normalizedExporter = exporterRaw?.trim().toLowerCase();
+    const exporter = TRACE_EXPORTERS.has(normalizedExporter)
+        ? normalizedExporter
+        : exporterRaw === undefined
+            ? undefined
+            : "none";
+    if (exporterRaw !== undefined && exporter === "none" && normalizedExporter !== "none") {
+        warnOnce(APIFUSE__TRACE__EXPORTER, `[apifuse] Invalid APIFUSE__TRACE__EXPORTER value "${normalizedExporter ?? exporterRaw}"; supported exporters are "console", "json", "otlp", and "none"; falling back to exporter "none".`);
+    }
+    return {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(exporter !== undefined ? { exporter } : {}),
+    };
+}

package/dist/runtime/trace.d.ts

@@ -1,4 +1,5 @@
 import type { TraceContext as BaseTraceContext, TraceAttributeValue, TraceConfig, TraceSpan } from "../types.js";
+import { type DiagnosticRedactor } from "./diagnostic-redactor.js";
 import { type OTLPExportOptions } from "./otlp.js";
 export type SpanAttributeValue = TraceAttributeValue;
 export type Span = TraceSpan;
@@ -8,8 +9,17 @@ export interface TraceContext extends BaseTraceContext {
 export interface CreateTraceContextOptions {
     maxSpans?: number;
     onSpan?: (span: Span) => void;
+    /** Redacts diagnostic attribute values and errors before recording or calling onSpan. */
+    redact?: DiagnosticRedactor;
     exportOptions?: OTLPExportOptions;
     resourceAttributes?: Record<string, string>;
+    /** W3C-compatible 32-character lowercase hexadecimal trace id used for export. */
+    traceId?: string;
+    /**
+     * Applied to a detached copy of each span immediately before OTLP export; never touches
+     * getSpans() or onSpan. Returning nothing (or throwing) drops that export batch.
+     */
+    sanitizeSpanForExport?: (span: Span) => Span | undefined;
 }
 type SpanHookOptions<T> = {
     attributes?: Record<string, unknown>;
@@ -20,7 +30,14 @@ export interface TraceRecorder {
     runSpan<T>(name: string, fn: () => Promise<T> | T, options?: SpanHookOptions<T>): Promise<T>;
 }
 export declare const TRACE_RECORDER: unique symbol;
+/** Updates request metadata before its pending root span completes and exports. */
+export declare function updateTraceContextExportMetadata(trace: BaseTraceContext, input: {
+    traceId?: string;
+    resourceAttributes?: Record<string, string>;
+}): void;
 export declare function resolveTraceContextOptions(config?: TraceConfig): CreateTraceContextOptions;
 export declare function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null;
+/** Internal, read-only process counters; no reset can re-arm a warning. */
+export declare function getDroppedOTLPSpanCount(reason: string): number;
 export declare function createTraceContext(options?: CreateTraceContextOptions): TraceContext;
 export {};