@apifuse/provider-sdk 2.1.0-beta.0 → 2.1.0-beta.10

package/dist/runtime/stt.d.ts

@@ -0,0 +1,22 @@
+import type { ProviderSttConfig, SttContext, SttTranscribeRequest, SttVerificationCodeOptions, VerificationCodeExtractionResult } from "../types";
+export declare const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
+export declare const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
+export declare const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";
+export declare const APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV = "APIFUSE__STT__CLOUDFLARE_API_TOKEN";
+export declare const CLOUDFLARE_WORKERS_AI_STT_BACKEND = "cloudflare-workers-ai";
+export declare const DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL = "@cf/openai/whisper-large-v3-turbo";
+export declare const DEFAULT_STT_MAX_AUDIO_BYTES: number;
+export declare const DEFAULT_STT_TIMEOUT_MS = 30000;
+type EnvLike = Record<string, string | undefined>;
+type CloudflareWorkersAiSttClientOptions = {
+    accountId: string;
+    apiToken: string;
+    model?: string;
+    fetch?: typeof fetch;
+};
+export declare function createUnsupportedSttClient(reason?: string): SttContext;
+export declare function createSttClientFromEnv(config: ProviderSttConfig | undefined, env?: EnvLike): SttContext;
+export declare function resolveSttPrompt(request: SttTranscribeRequest): string | undefined;
+export declare function createCloudflareWorkersAiSttClient(options: CloudflareWorkersAiSttClientOptions): SttContext;
+export declare function extractVerificationCode(text: string, options?: SttVerificationCodeOptions): VerificationCodeExtractionResult;
+export {};

package/dist/runtime/stt.js

@@ -0,0 +1,480 @@
+import { ProviderError, TransportError, ValidationError } from "../errors";
+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";
+export const APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV = "APIFUSE__STT__CLOUDFLARE_API_TOKEN";
+export const CLOUDFLARE_WORKERS_AI_STT_BACKEND = "cloudflare-workers-ai";
+export const DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL = "@cf/openai/whisper-large-v3-turbo";
+export const DEFAULT_STT_MAX_AUDIO_BYTES = 10 * 1024 * 1024;
+export const DEFAULT_STT_TIMEOUT_MS = 30_000;
+const BASE64_AUDIO_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+const DEFAULT_OTP_HINT = "Transcribe verification codes using Arabic numerals only. Preserve leading zeros and spacing.";
+function providerError(message, options) {
+    return new ProviderError(message, options);
+}
+function createErrorSttClient(options) {
+    return {
+        async transcribe() {
+            throw providerError(options.message, {
+                code: options.code,
+                fix: options.fix,
+            });
+        },
+        extractVerificationCode,
+    };
+}
+export function createUnsupportedSttClient(reason) {
+    return createErrorSttClient({
+        code: "STT_UNAVAILABLE",
+        message: reason ?? "STT runtime is not configured",
+        fix: `Configure ${APIFUSE__STT__BACKEND_ENV} and the matching backend credentials, or provide a test SttContext override.`,
+    });
+}
+function normalizedEnvValue(env, key) {
+    const value = env[key]?.trim();
+    return value ? value : undefined;
+}
+export function createSttClientFromEnv(config, env = process.env) {
+    if (!config) {
+        return createUnsupportedSttClient("Provider does not declare STT capability");
+    }
+    const backend = normalizedEnvValue(env, APIFUSE__STT__BACKEND_ENV);
+    if (!backend) {
+        return createUnsupportedSttClient(config.mode === "required"
+            ? `STT is required by this provider but ${APIFUSE__STT__BACKEND_ENV} is not configured`
+            : undefined);
+    }
+    if (backend !== CLOUDFLARE_WORKERS_AI_STT_BACKEND) {
+        return createErrorSttClient({
+            code: "UNSUPPORTED_STT_BACKEND",
+            message: `Unsupported STT backend "${backend}"`,
+            fix: `Use ${APIFUSE__STT__BACKEND_ENV}=${CLOUDFLARE_WORKERS_AI_STT_BACKEND} or provide a custom SttContext override.`,
+        });
+    }
+    const accountId = env.APIFUSE__CLOUDFLARE__ACCOUNT_ID?.trim();
+    const apiToken = env.APIFUSE__STT__CLOUDFLARE_API_TOKEN?.trim();
+    if (!accountId || !apiToken) {
+        return createUnsupportedSttClient(`STT backend ${backend} requires ${CLOUDFLARE_ACCOUNT_ID_ENV} and ${APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV}`);
+    }
+    return createCloudflareWorkersAiSttClient({
+        accountId,
+        apiToken,
+        model: normalizedEnvValue(env, APIFUSE__STT__MODEL_ENV) ??
+            DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL,
+    });
+}
+function base64ByteLength(data) {
+    const normalized = data.trim();
+    const padding = normalized.endsWith("==")
+        ? 2
+        : normalized.endsWith("=")
+            ? 1
+            : 0;
+    return Math.floor((normalized.length * 3) / 4) - padding;
+}
+function assertBase64Audio(audio, maxAudioBytes) {
+    if (audio.kind !== "base64") {
+        throw new ValidationError("Unsupported STT audio input kind", {
+            code: "UNSUPPORTED_STT_OPTION",
+            fix: 'Use audio: { kind: "base64", data, mediaType } for STT v1.',
+        });
+    }
+    const data = audio.data.trim();
+    if (data.length === 0 ||
+        data.length % 4 !== 0 ||
+        !BASE64_AUDIO_PATTERN.test(data)) {
+        throw new ValidationError("STT audio.data must be a base64-encoded string", {
+            code: "INVALID_STT_AUDIO",
+        });
+    }
+    const bytes = base64ByteLength(data);
+    const maxBytes = maxAudioBytes ?? DEFAULT_STT_MAX_AUDIO_BYTES;
+    if (bytes > maxBytes) {
+        throw new ValidationError(`STT audio exceeds maxAudioBytes (${bytes} > ${maxBytes})`, { code: "STT_AUDIO_TOO_LARGE" });
+    }
+    return bytes;
+}
+export function resolveSttPrompt(request) {
+    const policy = effectivePromptPolicy(request);
+    if (policy === "none")
+        return undefined;
+    if (policy === "default-hint")
+        return DEFAULT_OTP_HINT;
+    return request.initialPrompt;
+}
+function effectivePromptPolicy(request) {
+    if (request.promptPolicy)
+        return request.promptPolicy;
+    return request.mode === "otp" ? "default-hint" : "none";
+}
+function warnOrThrowUnsupportedOption(request, message) {
+    const policy = request.unsupportedOptionPolicy ?? "warn";
+    if (policy === "error") {
+        throw new ProviderError(message, { code: "UNSUPPORTED_STT_OPTION" });
+    }
+    return { code: "UNSUPPORTED_STT_OPTION", 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;
+    if (isTimeoutLikeError(error)) {
+        return new TransportError("STT upstream request timed out", {
+            code: "transport_timeout",
+            status: 0,
+            cause: error,
+        });
+    }
+    return new TransportError("STT upstream network request failed", {
+        code: "transport_network_error",
+        status: 0,
+        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 = {
+        audio: request.audio.data.trim(),
+        task: "transcribe",
+    };
+    const language = normalizeCloudflareLanguage(request.language);
+    if (language)
+        input.language = language;
+    if (prompt)
+        input.initial_prompt = prompt;
+    return input;
+}
+function unknownRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(value));
+}
+function parseSegments(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const segments = [];
+    for (const item of value) {
+        const segment = unknownRecord(item);
+        if (!segment || typeof segment.text !== "string")
+            continue;
+        segments.push({
+            text: segment.text,
+            startMs: typeof segment.start === "number"
+                ? Math.round(segment.start * 1000)
+                : typeof segment.startMs === "number"
+                    ? segment.startMs
+                    : undefined,
+            endMs: typeof segment.end === "number"
+                ? Math.round(segment.end * 1000)
+                : typeof segment.endMs === "number"
+                    ? segment.endMs
+                    : undefined,
+            confidence: typeof segment.confidence === "number" ? segment.confidence : undefined,
+        });
+    }
+    return segments.length > 0 ? segments : undefined;
+}
+function toSttTranscript(payload, audioBytes) {
+    const envelope = unknownRecord(payload);
+    const result = unknownRecord(envelope?.result) ?? envelope;
+    const info = unknownRecord(result?.transcription_info);
+    const text = (typeof result?.text === "string" ? result.text : undefined) ??
+        (typeof info?.text === "string" ? info.text : undefined);
+    if (!text) {
+        throw new TransportError("STT upstream response did not include transcript text", {
+            code: "STT_UPSTREAM_FAILED",
+            status: 502,
+        });
+    }
+    const durationMs = typeof result?.durationMs === "number"
+        ? result.durationMs
+        : typeof info?.duration === "number"
+            ? Math.round(info.duration * 1000)
+            : undefined;
+    return {
+        text,
+        language: typeof result?.language === "string"
+            ? result.language
+            : typeof info?.language === "string"
+                ? info.language
+                : undefined,
+        durationMs,
+        segments: parseSegments(result?.segments),
+        usage: {
+            audioBytes,
+            ...(durationMs ? { audioDurationMs: durationMs } : {}),
+        },
+    };
+}
+export function createCloudflareWorkersAiSttClient(options) {
+    const model = options.model ?? DEFAULT_CLOUDFLARE_WORKERS_AI_STT_MODEL;
+    const runFetch = options.fetch ?? fetch;
+    return {
+        async transcribe(request) {
+            const warnings = [];
+            if (request.initialPrompt &&
+                effectivePromptPolicy(request) !== "custom-hint") {
+                const warning = warnOrThrowUnsupportedOption(request, "initialPrompt is honored only when promptPolicy is custom-hint");
+                if (warning)
+                    warnings.push(warning);
+            }
+            const audioBytes = assertBase64Audio(request.audio, request.maxAudioBytes);
+            const timeout = createTimeoutController(request.timeoutMs ?? DEFAULT_STT_TIMEOUT_MS);
+            try {
+                let response;
+                try {
+                    response = await runFetch(`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(options.accountId)}/ai/run/${model}`, {
+                        method: "POST",
+                        headers: {
+                            Authorization: `Bearer ${options.apiToken}`,
+                            "Content-Type": "application/json",
+                        },
+                        body: JSON.stringify(toCloudflareInput(request)),
+                        signal: timeout.controller.signal,
+                    });
+                }
+                catch (error) {
+                    throw toSttTransportError(error);
+                }
+                const payload = await response.json().catch(() => undefined);
+                if (!response.ok) {
+                    throw new TransportError("STT upstream request failed", {
+                        code: "STT_UPSTREAM_FAILED",
+                        status: response.status,
+                        upstreamStatus: response.status,
+                    });
+                }
+                const envelope = unknownRecord(payload);
+                if (envelope?.success === false) {
+                    throw new TransportError("STT upstream returned an error", {
+                        code: "STT_UPSTREAM_FAILED",
+                        status: 502,
+                    });
+                }
+                const transcript = toSttTranscript(payload, audioBytes);
+                const withWarnings = warnings.length > 0
+                    ? {
+                        ...transcript,
+                        warnings: [...(transcript.warnings ?? []), ...warnings],
+                    }
+                    : transcript;
+                if (request.mode === "otp" || request.verificationCode) {
+                    return {
+                        ...withWarnings,
+                        verificationCode: extractVerificationCode(withWarnings.text, request.verificationCode),
+                    };
+                }
+                return withWarnings;
+            }
+            finally {
+                timeout.clear();
+            }
+        },
+        extractVerificationCode,
+    };
+}
+const EN_DIGITS = {
+    zero: "0",
+    oh: "0",
+    o: "0",
+    one: "1",
+    two: "2",
+    three: "3",
+    four: "4",
+    five: "5",
+    six: "6",
+    seven: "7",
+    eight: "8",
+    nine: "9",
+};
+const KO_DIGITS = {
+    공: "0",
+    영: "0",
+    일: "1",
+    이: "2",
+    삼: "3",
+    사: "4",
+    오: "5",
+    육: "6",
+    륙: "6",
+    칠: "7",
+    팔: "8",
+    구: "9",
+};
+function lengthSet(codeLengths) {
+    if (codeLengths === undefined)
+        return new Set([4, 5, 6, 7, 8]);
+    if (typeof codeLengths === "number")
+        return new Set([validCodeLength(codeLengths)]);
+    if (Array.isArray(codeLengths)) {
+        const values = codeLengths.map((length) => validCodeLength(length));
+        return new Set(values);
+    }
+    if (!("min" in codeLengths) || !("max" in codeLengths)) {
+        throw new ValidationError("STT verification code range is malformed", {
+            code: "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+        });
+    }
+    const min = validCodeLength(codeLengths.min);
+    const max = validCodeLength(codeLengths.max);
+    if (min > max) {
+        throw new ValidationError("STT verification code range min exceeds max", {
+            code: "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+        });
+    }
+    if (max - min > 16) {
+        throw new ValidationError("STT verification code range is too large", {
+            code: "INVALID_STT_VERIFICATION_CODE_OPTIONS",
+        });
+    }
+    const values = new Set();
+    for (let length = min; length <= max; length += 1) {
+        values.add(length);
+    }
+    return values;
+}
+function validCodeLength(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 32) {
+        throw new ValidationError("STT verification code length must be an integer between 1 and 32", { code: "INVALID_STT_VERIFICATION_CODE_OPTIONS" });
+    }
+    return value;
+}
+function sourceForGroup(tokens) {
+    const sources = new Set(tokens.map((token) => token.source));
+    return sources.size === 1 ? (tokens[0]?.source ?? "digits") : "mixed";
+}
+function emitWordToken(token, startIndex) {
+    const lower = token.toLowerCase();
+    const english = EN_DIGITS[lower];
+    if (english) {
+        return [
+            {
+                text: token,
+                digits: english,
+                source: "spoken_words",
+                startIndex,
+                endIndex: startIndex + token.length,
+            },
+        ];
+    }
+    const korean = KO_DIGITS[token];
+    if (korean) {
+        return [
+            {
+                text: token,
+                digits: korean,
+                source: "spoken_words",
+                startIndex,
+                endIndex: startIndex + token.length,
+            },
+        ];
+    }
+    const chars = [...token];
+    if (chars.length > 1 && chars.every((char) => KO_DIGITS[char])) {
+        let offset = startIndex;
+        return chars.map((char) => {
+            const item = {
+                text: char,
+                digits: KO_DIGITS[char] ?? "",
+                source: "spoken_words",
+                startIndex: offset,
+                endIndex: offset + char.length,
+            };
+            offset += char.length;
+            return item;
+        });
+    }
+    return [];
+}
+function tokenizeDigits(text) {
+    const tokens = [];
+    for (const match of text.matchAll(/[0-9]+|[A-Za-z]+|[가-힣]+/gu)) {
+        const value = match[0];
+        const index = match.index ?? 0;
+        if (/^[0-9]+$/.test(value)) {
+            tokens.push({
+                text: value,
+                digits: value,
+                source: "digits",
+                startIndex: index,
+                endIndex: index + value.length,
+            });
+            continue;
+        }
+        tokens.push(...emitWordToken(value, index));
+    }
+    return tokens.sort((a, b) => a.startIndex - b.startIndex);
+}
+function isAdjacent(left, right, text) {
+    const between = text.slice(left.endIndex, right.startIndex);
+    return /^[\s,.:;\-_/]*$/u.test(between);
+}
+function candidatesFromTokens(text, allowedLengths) {
+    const tokens = tokenizeDigits(text);
+    const candidates = [];
+    let group = [];
+    const flush = () => {
+        if (group.length === 0)
+            return;
+        const code = group.map((token) => token.digits).join("");
+        if (allowedLengths.has(code.length)) {
+            candidates.push({
+                code,
+                source: sourceForGroup(group),
+                startIndex: group[0]?.startIndex,
+                endIndex: group[group.length - 1]?.endIndex,
+            });
+        }
+        group = [];
+    };
+    for (const token of tokens) {
+        const previous = group[group.length - 1];
+        if (previous && !isAdjacent(previous, token, text)) {
+            flush();
+        }
+        group.push(token);
+    }
+    flush();
+    return candidates;
+}
+export function extractVerificationCode(text, options = {}) {
+    const allowedLengths = lengthSet(options.codeLengths);
+    const candidatesByCode = new Map();
+    for (const candidate of candidatesFromTokens(text, allowedLengths)) {
+        if (!candidatesByCode.has(candidate.code)) {
+            candidatesByCode.set(candidate.code, candidate);
+        }
+    }
+    const candidates = [...candidatesByCode.values()];
+    if (candidates.length === 0) {
+        throw new ProviderError("No verification code candidate found in transcript", {
+            code: "NO_CODE_FOUND",
+        });
+    }
+    if (candidates.length > 1) {
+        throw new ProviderError("Multiple verification code candidates found", {
+            code: "AMBIGUOUS_CODE",
+        });
+    }
+    const [candidate] = candidates;
+    return {
+        code: candidate.code,
+        candidates,
+        normalizedText: text.normalize("NFKC"),
+    };
+}

package/dist/runtime/trace.d.ts

@@ -0,0 +1,26 @@
+import type { TraceContext as BaseTraceContext, TraceAttributeValue, TraceConfig, TraceSpan } from "../types";
+import { type OTLPExportOptions } from "./otlp";
+export type SpanAttributeValue = TraceAttributeValue;
+export type Span = TraceSpan;
+export interface TraceContext extends BaseTraceContext {
+    getSpans(): Span[];
+}
+export interface CreateTraceContextOptions {
+    maxSpans?: number;
+    onSpan?: (span: Span) => void;
+    exportOptions?: OTLPExportOptions;
+    resourceAttributes?: Record<string, string>;
+}
+type SpanHookOptions<T> = {
+    attributes?: Record<string, unknown>;
+    onSuccess?: (value: T) => Record<string, unknown> | undefined;
+    onError?: (error: unknown) => Record<string, unknown> | undefined;
+};
+export interface TraceRecorder {
+    runSpan<T>(name: string, fn: () => Promise<T> | T, options?: SpanHookOptions<T>): Promise<T>;
+}
+export declare const TRACE_RECORDER: unique symbol;
+export declare function resolveTraceContextOptions(config?: TraceConfig): CreateTraceContextOptions;
+export declare function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null;
+export declare function createTraceContext(options?: CreateTraceContextOptions): TraceContext;
+export {};

package/dist/runtime/trace.js

@@ -0,0 +1,142 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { exportSpansOTLP } from "./otlp";
+export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-recorder");
+function buildOTLPExportOptions(config) {
+    if (config?.exporter !== "otlp") {
+        return undefined;
+    }
+    const endpoint = config.otlp?.endpoint ?? config.endpoint;
+    if (!endpoint) {
+        return undefined;
+    }
+    return {
+        endpoint,
+        headers: config.otlp?.headers,
+        timeout: config.otlp?.timeout,
+    };
+}
+export function resolveTraceContextOptions(config) {
+    return {
+        maxSpans: config?.maxSpans,
+        onSpan: config?.onSpan,
+        exportOptions: buildOTLPExportOptions(config),
+    };
+}
+function normalizeAttributeValue(value) {
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    return String(value);
+}
+function normalizeAttributes(attributes) {
+    if (!attributes) {
+        return {};
+    }
+    const normalizedEntries = Object.entries(attributes)
+        .map(([key, value]) => [key, normalizeAttributeValue(value)])
+        .filter((entry) => entry[1] !== undefined);
+    return Object.fromEntries(normalizedEntries);
+}
+function insertCompletedSpan(completed, entry, maxSpans) {
+    const insertAt = completed.findIndex((existingEntry) => existingEntry.sequence > entry.sequence);
+    if (insertAt === -1) {
+        completed.push(entry);
+    }
+    else {
+        completed.splice(insertAt, 0, entry);
+    }
+    if (completed.length > maxSpans) {
+        completed.splice(0, completed.length - maxSpans);
+    }
+}
+export function getTraceRecorder(trace) {
+    return trace[TRACE_RECORDER] ?? null;
+}
+export function createTraceContext(options = {}) {
+    const maxSpans = options.maxSpans ?? 1000;
+    const completed = [];
+    const activeSpanStorage = new AsyncLocalStorage();
+    let sequence = 0;
+    let traceContext;
+    const scheduleExport = () => {
+        if (!traceContext._exportOptions) {
+            return;
+        }
+        const spans = completed.map((entry) => ({ ...entry.span }));
+        setImmediate(() => {
+            void exportSpansOTLP(spans, traceContext._exportOptions, traceContext._resourceAttributes);
+        });
+    };
+    const recorder = {
+        async runSpan(name, fn, spanOptions = {}) {
+            const pendingSpan = {
+                id: crypto.randomUUID(),
+                name,
+                startedAt: Date.now(),
+                parentId: activeSpanStorage.getStore()?.id,
+                sequence: sequence++,
+                attributes: normalizeAttributes(spanOptions.attributes),
+            };
+            const finalize = (status, extraAttributes, error) => {
+                const endedAt = Date.now();
+                const duration = endedAt - pendingSpan.startedAt;
+                const attributes = {
+                    ...pendingSpan.attributes,
+                    ...normalizeAttributes(extraAttributes),
+                };
+                if (attributes.duration_ms === undefined) {
+                    attributes.duration_ms = duration;
+                }
+                const span = {
+                    id: pendingSpan.id,
+                    name: pendingSpan.name,
+                    startedAt: pendingSpan.startedAt,
+                    endedAt,
+                    duration_ms: duration,
+                    status,
+                    attributes,
+                    ...(error ? { error } : {}),
+                    ...(pendingSpan.parentId ? { parentId: pendingSpan.parentId } : {}),
+                };
+                insertCompletedSpan(completed, { sequence: pendingSpan.sequence, span }, maxSpans);
+                options.onSpan?.(span);
+                if (!pendingSpan.parentId) {
+                    scheduleExport();
+                }
+            };
+            return activeSpanStorage.run(pendingSpan, async () => {
+                try {
+                    const value = await fn();
+                    const successAttributes = spanOptions.onSuccess?.(value);
+                    finalize("ok", successAttributes ?? undefined);
+                    return value;
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    const errorAttributes = spanOptions.onError?.(error);
+                    finalize("error", errorAttributes ?? undefined, errorMessage);
+                    throw error;
+                }
+            });
+        },
+    };
+    traceContext = {
+        span(name, fn) {
+            return recorder.runSpan(name, fn);
+        },
+        getSpans() {
+            return completed.map((entry) => ({ ...entry.span }));
+        },
+        ...(options.exportOptions ? { _exportOptions: options.exportOptions } : {}),
+        ...(options.resourceAttributes
+            ? { _resourceAttributes: { ...options.resourceAttributes } }
+            : {}),
+        [TRACE_RECORDER]: recorder,
+    };
+    return traceContext;
+}

package/dist/runtime/waterfall.d.ts

@@ -0,0 +1,12 @@
+import type { Span } from "./trace";
+export type WaterfallRequest = {
+    method: string;
+    path: string;
+    status: number;
+    totalMs: number;
+};
+export type WaterfallOptions = {
+    slowThresholdMs?: number;
+    maxBarWidth?: number;
+};
+export declare function renderWaterfall(spans: Span[], request: WaterfallRequest, options?: WaterfallOptions): string;