@stainlessdev/xray-emitter 0.2.0 → 0.3.0

package/dist/types-BrKvhHbn.d.cts

@@ -0,0 +1,446 @@
+import * as _opentelemetry_sdk_trace_base from '@opentelemetry/sdk-trace-base';
+
+/**
+ * Exporter settings used by the OTLP trace exporter.
+ */
+interface ExporterConfig {
+    /**
+     * OTLP trace endpoint URL. `/v1/traces` is appended if missing.
+     */
+    endpointUrl: string;
+    /**
+     * Additional OTLP exporter headers (for example `Authorization`).
+     */
+    headers?: Record<string, string>;
+    /**
+     * Export timeout in milliseconds.
+     */
+    timeoutMs: number;
+    /**
+     * Span processor mode.
+     *
+     * Use `batch` (default) for lower overhead in long-lived services.
+     * Use `simple` to export each span immediately (useful for tests and
+     * short-lived runtimes).
+     */
+    spanProcessor: 'simple' | 'batch';
+}
+/**
+ * Request/response capture settings.
+ */
+interface CaptureConfig {
+    /**
+     * Include sanitized request headers in logs/spans.
+     */
+    requestHeaders: boolean;
+    /**
+     * Include sanitized response headers in logs/spans.
+     */
+    responseHeaders: boolean;
+    /**
+     * Request body capture mode.
+     *
+     * `none` disables capture, `text` records UTF-8 text, and `base64` preserves
+     * binary payloads safely.
+     */
+    requestBody: 'none' | 'text' | 'base64';
+    /**
+     * Response body capture mode.
+     *
+     * `none` disables capture, `text` records UTF-8 text, and `base64` preserves
+     * binary payloads safely.
+     */
+    responseBody: 'none' | 'text' | 'base64';
+    /**
+     * Maximum captured bytes per request/response body before truncation.
+     */
+    maxBodyBytes: number;
+}
+/**
+ * Redaction settings for logs and captured payloads.
+ */
+interface RedactionConfig {
+    /**
+     * Header names to redact (case-insensitive).
+     */
+    headers: string[];
+    /**
+     * Query parameter names to redact (case-insensitive).
+     */
+    queryParams: string[];
+    /**
+     * JSON paths to redact in captured JSON bodies.
+     */
+    bodyJsonPaths: string[];
+    /**
+     * Replacement value used for redacted data.
+     */
+    replacement: string;
+}
+/**
+ * Request ID extraction and propagation settings.
+ */
+interface RequestIdConfig {
+    /**
+     * Response header name to read request IDs from. This is normalized to
+     * lowercase during configuration.
+     */
+    header: string;
+}
+/**
+ * Route normalization settings.
+ */
+interface RouteConfig {
+    /**
+     * When true, normalize route patterns before emitting logs.
+     */
+    normalize: boolean;
+    /**
+     * Optional custom normalizer. Defaults to X-ray's built-in normalizer.
+     */
+    normalizer?: (path: string) => string;
+}
+/**
+ * Core emitter configuration.
+ */
+interface XrayConfig {
+    /**
+     * Logical service name for all emitted request logs.
+     */
+    serviceName: string;
+    /**
+     * Optional deployment environment label.
+     */
+    environment?: string;
+    /**
+     * Optional service version label.
+     */
+    version?: string;
+    /**
+     * Logger for internal X-ray diagnostics.
+     */
+    logger?: Logger;
+    /**
+     * Minimum log level for internal diagnostics.
+     */
+    logLevel?: LogLevel;
+    /**
+     * OTLP endpoint URL. Falls back to `STAINLESS_XRAY_ENDPOINT_URL`.
+     */
+    endpointUrl?: string;
+    /**
+     * Exporter overrides.
+     */
+    exporter?: Partial<ExporterConfig>;
+    /**
+     * Capture overrides.
+     */
+    capture?: Partial<CaptureConfig>;
+    /**
+     * Redaction overrides.
+     */
+    redaction?: Partial<RedactionConfig>;
+    /**
+     * Request ID resolution settings. The header is read from response headers at
+     * the end of the request.
+     */
+    requestId?: Partial<RequestIdConfig>;
+    /**
+     * Route normalization overrides.
+     */
+    route?: Partial<RouteConfig>;
+}
+/**
+ * Runtime config accepted by framework/node/fetch entrypoints.
+ */
+type XrayRuntimeConfig = Omit<XrayConfig, 'exporter'> & {
+    exporter?: Partial<ExporterConfig> & {
+        /**
+         * Custom exporter instance. When provided, endpoint/header options are ignored.
+         */
+        instance?: _opentelemetry_sdk_trace_base.SpanExporter;
+    };
+};
+/**
+ * Fully-resolved configuration returned by `normalizeConfig`.
+ */
+interface ResolvedXrayConfig {
+    serviceName: string;
+    environment?: string;
+    version?: string;
+    logger: Logger;
+    logLevel: LogLevel;
+    exporter: ExporterConfig;
+    capture: CaptureConfig;
+    redaction: RedactionConfig;
+    requestId: RequestIdConfig;
+    route: RouteConfig;
+}
+declare class XrayConfigError extends Error {
+    code: 'INVALID_CONFIG' | 'INVALID_REDACTION';
+    constructor(code: XrayConfigError['code'], message: string);
+}
+/**
+ * Normalize and validate user configuration.
+ *
+ * Applies defaults, validates required fields, and resolves environment
+ * fallbacks such as `STAINLESS_XRAY_ENDPOINT_URL`.
+ */
+declare function normalizeConfig(config: XrayConfig): ResolvedXrayConfig;
+
+/**
+ * Attribute value types accepted by OpenTelemetry span attributes.
+ */
+type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+/**
+ * Logging levels used by the internal X-ray logger.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Logger contract used by X-ray for internal diagnostics.
+ */
+interface Logger {
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * Captured request/response body payload details.
+ */
+interface CapturedBody {
+    /**
+     * Total body size before truncation.
+     */
+    bytes: number;
+    /**
+     * Encoding used for `value`.
+     */
+    encoding: 'utf8' | 'base64';
+    /**
+     * True when `value` was truncated due to `capture.maxBodyBytes`.
+     */
+    truncated: boolean;
+    /**
+     * Captured body payload. Omitted when there is no body.
+     */
+    value?: string;
+}
+/**
+ * Final emitted request log record.
+ */
+interface RequestLog {
+    /**
+     * Request identifier for this request.
+     *
+     * Written to span attributes and, where supported by the runtime/framework
+     * adapter, propagated to response headers.
+     */
+    requestId: string;
+    /**
+     * OpenTelemetry trace ID for this request span.
+     */
+    traceId?: string;
+    /**
+     * OpenTelemetry span ID for this request span.
+     */
+    spanId?: string;
+    /**
+     * Service name from configuration.
+     */
+    serviceName: string;
+    /**
+     * HTTP method recorded at request start (for example `GET` or `POST`).
+     */
+    method: string;
+    /**
+     * Full URL after redaction.
+     */
+    url: string;
+    /**
+     * Normalized route pattern when available (for example `/users/{id}`).
+     */
+    route?: string;
+    /**
+     * Final HTTP response status code, when known.
+     */
+    statusCode?: number;
+    /**
+     * Request duration in milliseconds.
+     */
+    durationMs: number;
+    /**
+     * Sanitized and optionally redacted request headers.
+     */
+    requestHeaders?: Record<string, string | string[]>;
+    /**
+     * Sanitized and optionally redacted response headers.
+     */
+    responseHeaders?: Record<string, string | string[]>;
+    /**
+     * Captured request body when enabled by capture settings.
+     */
+    requestBody?: CapturedBody;
+    /**
+     * Captured response body when enabled by capture settings.
+     */
+    responseBody?: CapturedBody;
+    /**
+     * Tenant identifier recorded via `setActor`.
+     */
+    tenantId?: string;
+    /**
+     * User identifier recorded via `setActor` or legacy `setUserId`.
+     */
+    userId?: string;
+    /**
+     * Session identifier recorded via `setSessionId`.
+     */
+    sessionId?: string;
+    /**
+     * Captured error details when the request fails.
+     */
+    error?: {
+        message: string;
+        type?: string;
+        stack?: string;
+    };
+    /**
+     * Custom attributes added via `setAttribute`.
+     */
+    attributes?: Record<string, AttributeValue>;
+    /**
+     * ISO timestamp for when request processing completed.
+     */
+    timestamp: string;
+}
+/**
+ * Per-request context bound to framework request objects.
+ */
+interface XrayContext {
+    /**
+     * Final request ID. May be empty until request completion.
+     */
+    requestId: string;
+    /**
+     * OpenTelemetry trace ID, when tracing is active.
+     */
+    traceId?: string;
+    /**
+     * OpenTelemetry span ID, when tracing is active.
+     */
+    spanId?: string;
+    /**
+     * Set actor identity for the request.
+     *
+     * `tenantId` is always recorded.
+     * `userId` is recorded only when non-empty.
+     */
+    setActor(tenantId: string, userId: string): void;
+    /**
+     * @deprecated Use `setActor(tenantId, userId)` to record tenant and user IDs together.
+     */
+    setUserId(id: string): void;
+    /**
+     * Set a session identifier on the request log.
+     */
+    setSessionId(id: string): void;
+    /**
+     * Add or overwrite a custom attribute on the request span/log.
+     */
+    setAttribute(key: string, value: AttributeValue): void;
+    /**
+     * Add a span event for the current request.
+     */
+    addEvent(name: string, attributes?: Record<string, AttributeValue>): void;
+    /**
+     * Mark the request as failed with error details.
+     */
+    setError(err: unknown): void;
+}
+/**
+ * Runtime-agnostic request input passed into `startRequest`.
+ */
+interface NormalizedRequest {
+    /**
+     * HTTP method used for span naming and emitted log metadata.
+     */
+    method: string;
+    /**
+     * Full request URL before redaction.
+     */
+    url: string;
+    /**
+     * Route pattern (if known at request start).
+     */
+    route?: string;
+    /**
+     * Request headers as normalized string/string[] values.
+     */
+    headers: Record<string, string | string[]>;
+    /**
+     * Optional pre-captured body.
+     */
+    body?: CapturedBody;
+    /**
+     * Optional explicit request ID. If omitted, X-ray reads from response headers
+     * when the span is closed (and generates a UUIDv7 if none is present).
+     */
+    requestId?: string;
+    /**
+     * Client remote address, used for client address attributes.
+     */
+    remoteAddress?: string;
+    /**
+     * Request start timestamp (milliseconds since epoch).
+     */
+    startTimeMs: number;
+}
+/**
+ * Runtime-agnostic response input passed into `endRequest`.
+ */
+interface NormalizedResponse {
+    /**
+     * HTTP response status code, if a response was produced.
+     */
+    statusCode?: number;
+    /**
+     * Response headers available at request completion.
+     */
+    headers?: Record<string, string | string[]>;
+    /**
+     * Optional captured response body.
+     */
+    body?: CapturedBody;
+    /**
+     * Response completion timestamp (milliseconds since epoch).
+     */
+    endTimeMs: number;
+}
+/**
+ * Runtime-agnostic emitter API used by adapters/framework wrappers.
+ */
+interface XrayEmitter {
+    /**
+     * Fully-resolved runtime configuration.
+     */
+    config: ResolvedXrayConfig;
+    /**
+     * Start request tracking and return a mutable per-request context.
+     */
+    startRequest(req: NormalizedRequest): XrayContext;
+    /**
+     * Finish request tracking and return the emitted request log payload.
+     */
+    endRequest(ctx: XrayContext, res: NormalizedResponse, err?: unknown): RequestLog;
+    /**
+     * Flush pending spans to the configured exporter.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the emitter and release exporter resources.
+     */
+    shutdown(): Promise<void>;
+}
+
+export { type AttributeValue as A, type CapturedBody as C, type ExporterConfig as E, type LogLevel as L, type NormalizedRequest as N, type RequestLog as R, type XrayConfig as X, type XrayEmitter as a, type Logger as b, type NormalizedResponse as c, type XrayContext as d, type CaptureConfig as e, type RedactionConfig as f, type RequestIdConfig as g, type ResolvedXrayConfig as h, type RouteConfig as i, type XrayRuntimeConfig as j, XrayConfigError as k, normalizeConfig as n };