@autter/runtime-node 1.4.0 → 1.6.0

package/dist/index.d.cts

@@ -1,4 +1,6 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
+import { b as RedactOptions, c as Redactor$1, d as RuntimeLogLevel, e as RuntimeOperationKind, f as RuntimeSink, F as FileSinkOptions, g as RuntimeLogContext, a as RuntimeOutcome, h as RuntimeCarrier, B as BreadcrumbInput } from './sinks-CPGDyfU8.cjs';
+export { i as Breadcrumb, j as BreadcrumbLevel, k as BreadcrumbType, l as CODE_PATTERN, n as ClientErrorBody, o as ConsoleSinkOptions, O as OtlpSinkOptions, p as RuntimeError, q as RuntimeErrorCatalog, r as RuntimeErrorDefinition, s as RuntimeErrorExtras, t as RuntimeErrorFactory, u as RuntimeErrorLike, v as RuntimeErrorOptions, R as RuntimeEvent, w as RuntimeLogContextValue, x as RuntimeSinkContext, y as consoleSink, z as defineRuntimeErrors, A as errorAttributes, D as fileSink, E as isRuntimeErrorLike, G as otlpSink, H as redactAttributes, I as redactText, J as toClientError } from './sinks-CPGDyfU8.cjs';
 import { Attributes } from '@opentelemetry/api';
 
 /**
@@ -23,8 +25,25 @@ interface RelayOptions {
     perIpRateLimit?: number | false;
     /** Called when the async forward fails (default: console.warn). */
     onError?: (err: unknown) => void;
+    /**
+     * Scrub secrets/PII from browser events (message, stack, name, nested
+     * context) before they leave your server — the same patterns as
+     * `initAutterServer({ redactAttributes })`. Catches old browser SDK
+     * versions and anything the browser's lean redactor misses. Pass a
+     * RedactOptions object to add your own patterns; `false` disables.
+     * Default true.
+     */
+    redact?: boolean | RedactOptions;
+    /**
+     * Warn once (server-side) when browser features in the forwarded events
+     * — CSP violations, network/timing capture — need a newer ingester than
+     * the one answering. Reads the ingester's version header from the forward
+     * response; never blocks the 202. Also disabled by AUTTER_COMPAT_CHECK=0.
+     * Default true.
+     */
+    compatCheck?: boolean;
 }
-declare function sanitizeBrowserPayload(raw: unknown): object | null;
+declare function sanitizeBrowserPayload(raw: unknown, redactor?: Redactor$1): object | null;
 /**
  * Fetch-style handler (Next.js App Router route, Remix, Hono, Bun, Deno):
  *
@@ -43,42 +62,55 @@ declare function createBrowserRelayHandler(opts: RelayOptions): (req: IncomingMe
     body?: unknown;
 }, res: ServerResponse) => void;
 
-interface RedactOptions {
+/** Mutable view of a record handed to enrichers before redaction/bounding. */
+interface RuntimeEnrichEvent {
+    level: RuntimeLogLevel;
+    message: string;
+    attributes: Record<string, unknown>;
+}
+interface RuntimeEnrichContext {
+    /** The inbound request of a request summary (Node IncomingMessage or fetch Request). */
+    req?: unknown;
+    /** The response object, when the framework exposes one. */
+    res?: unknown;
+    operation: {
+        id: string;
+        name: string;
+        kind: RuntimeOperationKind;
+    };
+}
+/** Adds attributes to operation/request summaries. Must be cheap; errors are ignored. */
+type RuntimeEnricher = (event: RuntimeEnrichEvent, context: RuntimeEnrichContext) => void;
+interface RuntimeLoggingOptions {
+    /** Print records to the console (default sinks only). Default true. */
+    console?: boolean;
+    /** Drop plain log records below this level. Summaries are always kept. */
+    minLevel?: RuntimeLogLevel;
     /**
-     * Extra patterns matched against lower-cased attribute KEYS; a match
-     * masks the whole value. Strings become case-insensitive substring
-     * patterns. Extends the built-in list.
+     * Fold debug/info messages logged inside an operation into its summary
+     * (`autter.operation.logs`, max 50) instead of emitting separate records;
+     * warn/error are folded AND emitted. Default true.
      */
-    additionalKeyPatterns?: (RegExp | string)[];
+    inline?: boolean;
+    /** Run on every operation/request summary before redaction. */
+    enrich?: RuntimeEnricher[];
     /**
-     * Extra patterns scrubbed inside string VALUES (same semantics as the
-     * built-in email/token patterns). Extends the built-in list.
+     * Replace the default sinks (`[otlpSink(), consoleSink()]`, plus
+     * `fileSink()` when NODE_ENV=development).
      */
-    additionalValuePatterns?: (RegExp | string)[];
-    /** Replacement token. Default "[redacted]". */
-    mask?: string;
+    sinks?: RuntimeSink[];
     /**
-     * Scrub email-shaped substrings from ALL string values, not just
-     * sensitive keys. Default true.
+     * Local NDJSON files (`.autter/runtime/YYYY-MM-DD.jsonl`). Default: on only
+     * when NODE_ENV === "development". Ignored when `sinks` is set.
      */
-    scrubEmailValues?: boolean;
-}
-/**
- * Return a copy of `attributes` with PII/secrets masked. Never mutates the
- * input; non-string primitives pass through untouched; `undefined` values
- * are dropped (OpenTelemetry rejects them).
- */
-declare function redactAttributes(attributes?: Attributes | null, options?: RedactOptions): Attributes;
-
-type RuntimeLogContextValue = string | number | boolean | null | undefined | RuntimeLogContextValue[] | {
-    [key: string]: RuntimeLogContextValue;
-};
-type RuntimeLogContext = Record<string, RuntimeLogContextValue>;
-type RuntimeLogLevel = "debug" | "info" | "warning" | "error";
-type RuntimeOutcome = "succeeded" | "failed" | "degraded" | "cancelled" | "pending";
-interface RuntimeLoggingOptions {
-    console?: boolean;
-    minLevel?: RuntimeLogLevel;
+    file?: boolean | FileSinkOptions;
+    /**
+     * EXPERIMENTAL zero-code request summaries for plain `node:http` servers
+     * via the HTTP instrumentation hook (initAutterServer only). Uses
+     * AsyncLocalStorage.enterWith, which can leak context across keep-alive /
+     * pipelined requests on one socket — prefer `autterRequests()`. Default false.
+     */
+    requests?: boolean;
 }
 interface RuntimeOperation {
     readonly id: string;
@@ -86,6 +118,12 @@ interface RuntimeOperation {
     outcome(status: RuntimeOutcome, message?: string): void;
     step<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
 }
+interface RuntimeOperationOptions {
+    /** Carrier from `runtimeContext.carrier()` (object or JSON string): links parent op, request id and trace. */
+    from?: RuntimeCarrier | string | null;
+    /** Receives the log flush promise once the operation completes (serverless `waitUntil`). */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
 declare function runtimeLogStats(): {
     buffered: number;
     dropped: number;
@@ -103,8 +141,45 @@ declare const runtimeLogger: {
     warn: (message: string, extra?: RuntimeLogContext) => void;
     error: (error: unknown, extra?: RuntimeLogContext) => void;
 };
-/** Context stays local to this operation; queues/processes require explicit propagation. */
-declare function withRuntimeOperation<T>(name: string, fn: (operation: RuntimeOperation) => T | Promise<T>, attributes?: RuntimeLogContext): Promise<T>;
+/**
+ * Run `fn` as a named operation: one summary record (outcome, duration,
+ * steps, context, inline messages) when it ends. Nested operations link via
+ * `autter.operation.parent_id`; pass `{ from: carrier }` to continue work
+ * handed over through a queue or another process.
+ */
+declare function withRuntimeOperation<T>(name: string, fn: (operation: RuntimeOperation) => T | Promise<T>, attributes?: RuntimeLogContext, options?: RuntimeOperationOptions): Promise<T>;
+/**
+ * Like `runtimeContext.fork` but not awaited: errors are recorded on the
+ * child operation (and its span) and never become unhandled rejections.
+ */
+declare function runInBackground<T>(name: string, fn: (operation: RuntimeOperation) => T | Promise<T>): Promise<T | undefined>;
+/**
+ * The current request/operation, from anywhere in its async call tree.
+ * Every method is a safe no-op (or plain log) outside an operation.
+ */
+declare const runtimeContext: {
+    /** Merge attributes into the current summary's context. */
+    set(attributes: RuntimeLogContext): void;
+    /** Set the outcome explicitly (wins over status/thrown-error rules). */
+    outcome(status: RuntimeOutcome, message?: string): void;
+    debug(message: string, attributes?: RuntimeLogContext): void;
+    info(message: string, attributes?: RuntimeLogContext): void;
+    warn(message: string, attributes?: RuntimeLogContext): void;
+    /** Log an error and attach it (code/why/fix) to the current summary. */
+    error(error: unknown, attributes?: RuntimeLogContext): void;
+    /** Current operation id. */
+    readonly id: string | undefined;
+    /** Current request id (inherited by child operations and forks). */
+    readonly requestId: string | undefined;
+    /**
+     * Run `fn` as a child operation whose parent link is captured NOW, so it
+     * still links after the parent has finished (background work).
+     */
+    fork<T>(name: string, fn: (operation: RuntimeOperation) => T | Promise<T>): Promise<T>;
+    /** Serialisable link for queue payloads: `{ v: 1, op, req?, traceparent? }`. */
+    carrier(): RuntimeCarrier | undefined;
+};
+type RuntimeContextHandle = typeof runtimeContext;
 
 /**
  * Curated OpenTelemetry setup for Autter Runtime — deliberately NOT the
@@ -125,10 +200,16 @@ declare function withRuntimeOperation<T>(name: string, fn: (operation: RuntimeOp
  *   request metrics              : aggregated every 60 s, keyed by route
  *                                  template (Express routes detected
  *                                  out of the box — see captureExpressRoute)
- *   logs                         : not collected
+ *   operation / request summaries: 100%  (withRuntimeOperation,
+ *                                         autterRequests, … — one wide
+ *                                         record per unit of work, never
+ *                                         sampled)
+ *   logs                         : runtimeLogger / runtimeContext records
+ *                                  (debug/info folded into the current
+ *                                  operation's summary; minLevel applies)
  *
  * Exports OTLP/HTTP JSON to the Autter ingester (`/v1/traces`,
- * `/v1/metrics`) with the ingest key as a bearer header.
+ * `/v1/metrics`, `/v1/logs`) with the ingest key as a bearer header.
  */
 interface AutterServerOptions {
     /** Structured logs and completed operation summaries. */
@@ -161,8 +242,23 @@ interface AutterServerOptions {
     metricIntervalMs?: number;
     /** Collect RSS, heap, limit, and GC signals per process instance. Default true. */
     memoryMetrics?: boolean;
-    /** Capture crashing exceptions via process.uncaughtExceptionMonitor (default true). */
+    /**
+     * Capture crashing exceptions via process.uncaughtExceptionMonitor, and
+     * unhandled promise rejections (see `captureUnhandledRejections`).
+     * Default true; false turns both off.
+     */
     captureGlobalErrors?: boolean;
+    /**
+     * Record unhandled promise rejections as errors (severity "error",
+     * `autter.unhandled_rejection: true`). Never changes whether the process
+     * crashes: when Node would have crashed (the default
+     * `--unhandled-rejections=throw` mode and no other `unhandledRejection`
+     * listener), the rejection is rethrown on the next tick, so the process
+     * still exits with code 1 and the crash is recorded as fatal like any
+     * other. False restores 1.5.0 behaviour: a rejection is only seen when it
+     * crashes the process. Default true.
+     */
+    captureUnhandledRejections?: boolean;
     /**
      * Flush all exporters when the process exits (`beforeExit`, SIGINT,
      * SIGTERM) so a forgotten `shutdown()` doesn't silently drop buffered
@@ -171,12 +267,17 @@ interface AutterServerOptions {
      */
     autoFlush?: boolean;
     /**
-     * Mask PII/secrets in custom attributes before they leave the process:
-     * emails, tokens (JWT, sk-, gh_, AWS, Slack), bearer headers,
-     * `scheme://user:pass@` URLs, and anything whose attribute KEY looks
-     * sensitive (password/token/secret/cookie/…). Mirrors the browser
-     * relay's whitelist sanitiser. `true`/undefined = defaults; pass a
-     * RedactOptions object to extend the patterns; `false` disables.
+     * Mask secrets/PII before anything leaves the process — custom
+     * attributes, exception messages and stack traces, span status
+     * messages, URLs/query strings and attributes set by any
+     * instrumentation (scrubbed again at export), and structured logs:
+     * JWTs, bearer/basic credentials, Cookie/Authorization header text,
+     * `scheme://user:pass@` connection strings, vendor API keys (sk-, sk_live_,
+     * ghp_, xox*-, AIza, AKIA, …), PEM private keys, `password=`/`?token=`
+     * assignments, emails, card numbers, and anything whose attribute KEY
+     * looks sensitive (password/token/secret/cookie/authorization/session/…).
+     * `true`/undefined = defaults; pass a RedactOptions object to add your
+     * own key/value patterns; `false` disables (not recommended).
      * Default true.
      */
     redactAttributes?: boolean | RedactOptions;
@@ -194,6 +295,22 @@ interface AutterServerOptions {
     llmTracing?: boolean;
     /** Extra instrumentations (e.g. `new ExpressInstrumentation()`). */
     instrumentations?: unknown[];
+    /**
+     * Check once, in the background, that the ingester supports the features
+     * in use (operation logging, memory metrics, …) and print one warning per
+     * mismatch naming both versions and the fix. Never throws or delays
+     * startup. Also disabled by AUTTER_COMPAT_CHECK=0. Default true.
+     * Run `npx @autter/runtime-node doctor` for a full report.
+     */
+    compatCheck?: boolean;
+    /**
+     * @internal Wrapper packages (`@autter/runtime-next`) report their own
+     * name/version as the OTLP `telemetry.distro.*` resource attributes.
+     */
+    distro?: {
+        name: string;
+        version: string;
+    };
 }
 type AutterSeverity = "fatal" | "error" | "warning" | "info";
 /** Token usage (and optionally exact cost) of one LLM call. */
@@ -205,6 +322,8 @@ interface LlmUsage {
      * built-in per-model price estimate.
      */
     costUsd?: number;
+    /** Prompt tokens served from the provider cache (rolled into `autter.operation.ai`). */
+    cacheReadTokens?: number;
 }
 interface LlmCallInfo {
     /** Provider system: "openai", "anthropic", "google", "mistral_ai", … */
@@ -240,7 +359,12 @@ interface TrackedLlmCall extends LlmCallInfo, LlmUsage {
     error?: unknown;
 }
 interface AutterServer {
-    /** Report a handled exception. Always recorded (never sampled out). */
+    /**
+     * Report a handled exception. Always recorded (never sampled out).
+     * `attributes.fingerprint` (a string or up to 10 strings) groups every
+     * error that carries it into one issue (ingester 1.6.0+); it is sent as
+     * `autter.fingerprint` on the exception event, not as a span attribute.
+     */
     captureException(error: unknown, attributes?: Attributes): void;
     /**
      * Report a warning (or info) without an exception — deprecated code
@@ -433,4 +557,399 @@ declare function startCaughtExceptionSampler(options?: {
     stop(): void;
 };
 
-export { type AutoFlushHandle, type AutoFlushOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, type FlushTarget, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, type RedactOptions, type RelayOptions, type RuntimeLogContext, type RuntimeLogContextValue, type RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, type RuntimeOutcome, type SafeCapture, type TrackedLlmCall, captureException, captureMessage, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, flushRuntimeLogs, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, redactAttributes, reportOutcome, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, withLlmCall, withProcessSpan, withRuntimeOperation };
+interface AutterRequestsOptions {
+    /** Path globs never summarised: `*` = one segment, `**` = any depth. */
+    ignore?: string[];
+    /** Request id header to honour and echo. Default "x-request-id". */
+    requestIdHeader?: string;
+    /** Honour an inbound request id that matches `^[\w.-]{8,128}$`. Default true. */
+    trustRequestId?: boolean;
+}
+interface AutterErrorResponseOptions {
+    /**
+     * Report the error as an exception. Default: errors with status ≥ 500,
+     * RuntimeErrors and any error with a valid code (expected ones included —
+     * they are recorded but never open incidents).
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+    /** Header the request id is read from when no request summary is active. */
+    requestIdHeader?: string;
+}
+interface RuntimeRequestOptions {
+    /** Summary name suffix (default: the route). Name = `METHOD name`. */
+    name?: string;
+    /** Route template for `http.route` (default: pathname with ids → `:id`). */
+    route?: string;
+    requestIdHeader?: string;
+    trustRequestId?: boolean;
+    ignore?: string[];
+    /** Receives the log flush promise after the response (serverless `waitUntil`). */
+    waitUntil?: (promise: Promise<unknown>) => void;
+}
+/**
+ * Report an error that reached a request boundary — a framework error hook,
+ * an exception filter, Next.js `onRequestError`. Unlike `captureException`
+ * it reports each error once (an error a handler or another hook already
+ * captured is skipped), and it records the exception, with its stack, on the
+ * request's HTTP server span even when a child span is active, so the failed
+ * request and its exception stay one issue. When the error was already
+ * captured (e.g. by `withRuntimeRequest`), `attributes` still go on the
+ * request span, without a second exception.
+ */
+declare function captureRequestError(error: unknown, attributes?: Attributes): void;
+/**
+ * Express / Connect middleware. Mount it early (before routers; after body
+ * parsers is fine too):
+ *
+ *   app.use(autterRequests({ ignore: ["/healthz", "/metrics"] }));
+ *
+ * Echoes the request id in the response (`x-request-id`), stamps it on the
+ * server span and every record, and emits the summary on finish/close.
+ */
+declare function autterRequests(options?: AutterRequestsOptions): (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;
+/**
+ * Express error middleware: records the error on the request summary,
+ * reports it (see `capture`), and answers with
+ * `{ error: { message, code?, why?, fix?, link?, requestId? } }` and the
+ * error's status (default 500). Never includes `internal`, stacks or causes;
+ * unstructured 5xx messages are replaced with a generic one.
+ *
+ *   app.use(autterErrorResponse());   // after your routes
+ */
+declare function autterErrorResponse(options?: AutterErrorResponseOptions): (error: unknown, req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;
+interface FastifyLikeInstance {
+    addHook(name: string, hook: (...args: never[]) => unknown): unknown;
+}
+/**
+ * Fastify plugin (Fastify 4/5, no dependency on fastify itself):
+ *
+ *   app.register(autterFastify, { ignore: ["/healthz"] });
+ *
+ * Skips plugin encapsulation, so its hooks cover every route.
+ */
+declare function autterFastify(fastify: FastifyLikeInstance, options: AutterRequestsOptions | undefined, done: (error?: Error) => void): void;
+/**
+ * Wrap a fetch-style handler `(request, ...rest) => Response` in a request
+ * summary. Thrown errors are recorded and reported, then rethrown.
+ *
+ *   export const POST = withRuntimeRequest(handler, { name: "checkout" });
+ */
+declare function withRuntimeRequest<A extends unknown[]>(handler: (request: Request, ...rest: A) => Response | Promise<Response>, options?: RuntimeRequestOptions): (request: Request, ...rest: A) => Promise<Response>;
+
+/**
+ * Server error hooks for Express, Fastify and Koa. Each records the error,
+ * with its stack, on the request's span through `captureException`, then
+ * lets the framework carry on exactly as before (same error, same response).
+ * Without them a thrown error only reaches Autter as the 500 the framework
+ * answers with: a stackless `HttpServerError` grouped by route.
+ *
+ * No framework is a dependency: the request/reply shapes are structural.
+ */
+interface AutterErrorHandlerOptions {
+    /**
+     * Which errors to report. Default: errors with status ≥ 500 (or no
+     * status), RuntimeErrors and any error with a valid code — so 4xx errors
+     * such as `ctx.throw(404)` or validation failures stay out of your issues.
+     * `true` reports every error; a predicate decides per error.
+     */
+    capture?: boolean | ((error: unknown) => boolean);
+}
+/**
+ * Express (4/5) / Connect error middleware that reports the error and calls
+ * `next(err)` unchanged. Mount it after your routes and before your own
+ * error handlers:
+ *
+ *   app.use(autterErrorHandler());
+ *   app.use((err, req, res, next) => res.status(500).send("…"));   // yours
+ *
+ * (`autterErrorResponse()` reports too, and also answers the request.)
+ */
+declare function autterErrorHandler(options?: AutterErrorHandlerOptions): (error: unknown, req: IncomingMessage, _res: ServerResponse, next: (error?: unknown) => void) => void;
+interface FastifyHookInstance {
+    addHook(name: string, hook: (...args: never[]) => unknown): unknown;
+}
+/**
+ * Fastify (4/5) `onError` hook that reports the error; Fastify's error
+ * handler still builds the response. Register it as a plugin, or call it on
+ * the instance directly:
+ *
+ *   app.register(autterFastifyErrors);            // or: autterFastifyErrors(app)
+ *   app.register(autterFastifyErrors, { capture: true });
+ *
+ * It skips plugin encapsulation, so it covers every route. `autterFastify`
+ * (request summaries) already includes the same hook; you don't need both.
+ */
+declare function autterFastifyErrors(fastify: FastifyHookInstance, options?: AutterErrorHandlerOptions, done?: (error?: Error) => void): void;
+interface KoaContextLike {
+    req?: IncomingMessage;
+}
+/**
+ * Koa (2/3) middleware that reports errors thrown downstream and rethrows
+ * them, so Koa's own error handling (and `app.on("error")`) is unchanged.
+ * Mount it first:
+ *
+ *   app.use(autterKoa());
+ */
+declare function autterKoa(options?: AutterErrorHandlerOptions): (ctx: KoaContextLike, next: () => Promise<unknown>) => Promise<void>;
+
+/**
+ * Unhandled promise rejections, recorded without changing whether the
+ * process crashes.
+ *
+ * Node's `--unhandled-rejections` mode decides what an unhandled rejection
+ * does, and most modes behave differently once ANY `unhandledRejection`
+ * listener exists:
+ *
+ *   mode                   no listener                      with a listener
+ *   throw (default)        crash (uncaught exception)        listener only — no crash
+ *   strict                 crash, then the listener          same
+ *   warn                   warning                           listener + warning
+ *   warn-with-error-code   warning + exit code 1             listener only
+ *   none                   nothing                           listener only
+ *
+ * Adding our listener would therefore silently stop the default crash. So
+ * when ours is the only listener we do what Node would have done:
+ *
+ *   - throw: rethrow the reason (or Node's `UnhandledPromiseRejection`
+ *     wrapper for a non-error reason) on the next tick. The process crashes
+ *     with exit code 1 as before, and `uncaughtExceptionMonitor` records it
+ *     as a crash (fatal), exactly as it did without this listener. The one
+ *     visible difference: `uncaughtException` listeners and the monitor
+ *     receive origin `"uncaughtException"` instead of `"unhandledRejection"`.
+ *   - warn-with-error-code: print Node's warning and set `process.exitCode = 1`.
+ *   - strict: no listener at all — Node raises the rejection as an uncaught
+ *     exception first, which the crash monitor already records.
+ *
+ * Everything else — the app has its own listener (it decides what happens),
+ * or the mode never crashes — is recorded as an error (severity "error", not
+ * fatal) with `autter.unhandled_rejection: true`.
+ */
+type UnhandledRejectionsMode = "throw" | "strict" | "warn" | "warn-with-error-code" | "none";
+/**
+ * Node's effective `--unhandled-rejections` mode: `NODE_OPTIONS` first, then
+ * the command line (which wins), last occurrence wins. Default `"throw"`.
+ */
+declare function unhandledRejectionsMode(execArgv?: readonly string[], nodeOptions?: string | undefined): UnhandledRejectionsMode;
+
+/**
+ * Logger-only mode: requests, operations, coded errors, sinks and enrichers
+ * WITHOUT starting the OpenTelemetry NodeSDK. For apps that already run
+ * their own OTel (a second NodeSDK would fight it) or want logs only.
+ *
+ *   initAutterLogging({ apiKey: process.env.AUTTER_RUNTIME_KEY, service: "api" });
+ *
+ * Exceptions are recorded on the app's active span when there is one
+ * (`exceptions: "auto"`); otherwise — or always with `exceptions: "log"` —
+ * they become error log records with `exception.*` and
+ * `autter.capture.mode = "log"`, which the ingester (1.5.0+) promotes to
+ * occurrences. Without an apiKey records go to the console/file sinks only.
+ */
+interface AutterLoggingOptions {
+    /** Private ingest key (autter_rt_…). Omit to log locally only. */
+    apiKey?: string;
+    /** Ingester base URL. Default: https://otlp.autter.dev */
+    endpoint?: string;
+    service: string;
+    environment?: string;
+    release?: string;
+    logging?: RuntimeLoggingOptions;
+    /** Same semantics as initAutterServer. Default true. */
+    redactAttributes?: boolean | RedactOptions;
+    /** Capture crashes via process.uncaughtExceptionMonitor, and unhandled
+     * rejections (`captureUnhandledRejections`). Default true. */
+    captureGlobalErrors?: boolean;
+    /** Same semantics as initAutterServer: record unhandled rejections as
+     * errors without changing whether the process crashes. Default true. */
+    captureUnhandledRejections?: boolean;
+    /** Flush records on beforeExit/SIGINT/SIGTERM. Default true. */
+    autoFlush?: boolean;
+    debug?: boolean;
+    /**
+     * "auto" (default): record on the app's active recording span if any,
+     * else emit a promoted log record. "log": always emit the log record
+     * (use when the app's own spans are not exported to Autter).
+     */
+    exceptions?: "auto" | "log";
+}
+interface AutterLogging {
+    captureException(error: unknown, attributes?: Attributes): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+declare function initAutterLogging(options: AutterLoggingOptions): AutterLogging;
+
+/** `user_agent.browser` ("Chrome 120"), `user_agent.os`, `user_agent.device`, `user_agent.bot`. */
+declare function enrichUserAgent(): RuntimeEnricher;
+/** `http.request.body.size` / `http.response.body.size` from Content-Length. */
+declare function enrichRequestSize(): RuntimeEnricher;
+/** `geo.country.iso_code` from CDN/edge headers (Cloudflare, Vercel, CloudFront, Fastly). Country only. */
+declare function enrichEdgeGeo(): RuntimeEnricher;
+/** `deployment.region` and `deployment.commit` from common platform environment variables. */
+declare function enrichDeployment(env?: Record<string, string | undefined>): RuntimeEnricher;
+
+/**
+ * Version compatibility between Autter Runtime SDKs, this ingester and its
+ * ClickHouse schema — the single source of truth.
+ *
+ * `compat-manifest.json` lists every feature that needs a minimum ingester
+ * version, a ClickHouse migration, a dedicated ingest route, or a minimum SDK
+ * version. Everything else derives from it:
+ *
+ * - the ingester serves it (evaluated against its own version and applied
+ *   migrations) at `GET /v1/compat`;
+ * - `@autter/runtime-node` / `@autter/runtime-next` bundle this file at build
+ *   time to warn once when an enabled feature needs a newer ingester, and to
+ *   power `npx @autter/runtime-node doctor`;
+ * - the Python adapter (`adapters/python/compat.py`) embeds a copy that a
+ *   parity test keeps identical.
+ *
+ * This module is dependency-free and side-effect-free on purpose: it is
+ * bundled into the Node SDK. Keep it that way.
+ *
+ * Adding a feature: append an entry to compat-manifest.json with the first
+ * ingester release that handles it, the migrations it writes to, its route
+ * (if it has its own), and the first SDK release that emits it. The
+ * consistency test in compat.test.ts checks ids, migrations and routes, and
+ * that no version is ahead of its package's package.json: a feature for the
+ * next release bumps the packages it names in the same change.
+ */
+interface CompatFeature {
+    id: string;
+    title: string;
+    /** First ingester release that stores this feature correctly. */
+    ingester: string;
+    /** ClickHouse migrations (migrations.ts ids) the feature writes to. */
+    migrations: string[];
+    /** Dedicated ingest route, when the feature has one. */
+    route?: string;
+    /** First release of each SDK package that emits the feature. */
+    sdks: Record<string, string>;
+    /** Browser payload event types that belong to this feature. */
+    browserEvents?: string[];
+}
+interface CompatManifest {
+    manifestVersion: number;
+    docs: string;
+    upgrade: {
+        ingester: string;
+        sdk: string;
+    };
+    features: CompatFeature[];
+}
+declare const COMPAT_MANIFEST: CompatManifest;
+/** Response header carrying the ingester version on every ingest response. */
+declare const INGESTER_VERSION_HEADER = "x-autter-ingester-version";
+type SchemaStatus = "ready" | "pending" | "failed" | "unconfigured";
+/** What is known about the ingester an SDK talks to. */
+interface IngesterCompatInfo {
+    /** Exact version, or null when the ingester predates /v1/compat. */
+    version: string | null;
+    /** True when /v1/compat returned 404 (ingester 1.4.0 or older). */
+    legacy?: boolean;
+    schema?: {
+        status: SchemaStatus;
+        applied: string[];
+    };
+    /** Legacy ingesters: route → exists, learned by probing. */
+    routes?: Record<string, boolean>;
+}
+type CompatIssueKind = "ingester_too_old" | "schema_not_applied" | "sdk_too_old";
+interface CompatIssue {
+    feature: string;
+    title: string;
+    kind: CompatIssueKind;
+    /** Package that must change: the ingester or an SDK package name. */
+    component: string;
+    required: string;
+    /** What was found ("1.3.4", "1.4.0 or older", …). */
+    actual: string;
+    /** One line: what is wrong, versions, and the fix. */
+    message: string;
+    fix: string;
+}
+interface SdkIdentity {
+    name: string;
+    version: string;
+}
+/**
+ * Every incompatibility for the features in use. Unknown is never an issue:
+ * when the ingester version can't be determined (and a legacy route probe
+ * didn't prove a route missing) nothing is reported, so the check has no
+ * false positives.
+ */
+declare function evaluateCompat(input: {
+    features: Iterable<string>;
+    ingester: IngesterCompatInfo | null;
+    sdk?: SdkIdentity | null;
+    manifest?: CompatManifest;
+}): CompatIssue[];
+
+/**
+ * One-time, fire-and-forget version compatibility check.
+ *
+ * When a feature that needs a newer ingester is in use (operation logging,
+ * memory metrics, …), ask the ingester once — `GET /v1/compat`, or the
+ * `x-autter-ingester-version` header on responses the SDK already receives —
+ * and print ONE clear warning per incompatible feature naming both versions
+ * and the fix. Never throws, never blocks or delays startup or exit (the
+ * socket is unref'd), and is silent when versions match or can't be
+ * determined. Disable with `compatCheck: false` or AUTTER_COMPAT_CHECK=0.
+ */
+declare const SDK_IDENTITY: SdkIdentity;
+/**
+ * What the ingester at `endpoint` supports. `null` = unknown (unreachable,
+ * auth proxy, 5xx). A 404 on /v1/compat means a pre-compat ingester (1.4.0 or
+ * older); `probeRoutes` then learns which feature routes exist (an
+ * unauthenticated POST answers 401/503/… when the route exists, 404 when not).
+ */
+declare function fetchIngesterCompat(endpoint: string, options?: {
+    probeRoutes?: string[];
+    unref?: boolean;
+    timeoutMs?: number;
+}): Promise<{
+    info: IngesterCompatInfo | null;
+    report: unknown;
+    error?: string;
+}>;
+
+/**
+ * `npx @autter/runtime-node doctor` — one-shot version compatibility report:
+ * installed Autter SDK versions, the ingester's version and ClickHouse schema
+ * level, the ingest key (optional), and every feature the installed SDKs can
+ * use that the ingester can't store. Exit codes: 0 compatible, 1 a mismatch
+ * or rejected key, 2 the ingester could not be reached or identified.
+ */
+interface DoctorOptions {
+    endpoint?: string;
+    key?: string;
+    features?: string[];
+    json?: boolean;
+    cwd?: string;
+    timeoutMs?: number;
+}
+interface DoctorReport {
+    endpoint: string;
+    sdks: SdkIdentity[];
+    ingester: IngesterCompatInfo | null;
+    ingesterError?: string;
+    key?: "accepted" | "rejected" | "client_key" | "storage_unavailable" | "unknown";
+    features: Array<{
+        id: string;
+        title: string;
+        status: "ok" | "incompatible" | "unknown";
+    }>;
+    issues: CompatIssue[];
+    exitCode: 0 | 1 | 2;
+}
+declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;
+
+/**
+ * Record a step (type "custom" unless you say otherwise) on the current
+ * request. The next exception captured in it carries the last 30. Message
+ * and data are scrubbed with your `redact` settings. Never throws.
+ *
+ *   addBreadcrumb({ message: "Loaded cart", data: { items: 3 } });
+ */
+declare function addBreadcrumb(input: BreadcrumbInput): void;
+
+export { type AutoFlushHandle, type AutoFlushOptions, type AutterErrorHandlerOptions, type AutterErrorResponseOptions, type AutterLogging, type AutterLoggingOptions, type AutterRequestsOptions, type AutterServer, type AutterServerOptions, type AutterSeverity, BreadcrumbInput, COMPAT_MANIFEST, type CompatIssue, type DoctorOptions, type DoctorReport, FileSinkOptions, type FlushTarget, INGESTER_VERSION_HEADER, type IngesterCompatInfo, type InstrumentLlmOptions, type LlmCallHandle, type LlmCallInfo, type LlmUsage, RedactOptions, type RelayOptions, RuntimeCarrier, type RuntimeContextHandle, type RuntimeEnrichContext, type RuntimeEnrichEvent, type RuntimeEnricher, RuntimeLogContext, RuntimeLogLevel, type RuntimeLoggingOptions, type RuntimeOperation, RuntimeOperationKind, type RuntimeOperationOptions, RuntimeOutcome, type RuntimeRequestOptions, RuntimeSink, SDK_IDENTITY, type SafeCapture, type SdkIdentity, type TrackedLlmCall, type UnhandledRejectionsMode, addBreadcrumb, autterErrorHandler, autterErrorResponse, autterFastify, autterFastifyErrors, autterKoa, autterRequests, captureException, captureMessage, captureRequestError, createBrowserRelayFetchHandler, createBrowserRelayHandler, createRuntimeLogger, emitLlmSelftestTrace, enrichDeployment, enrichEdgeGeo, enrichRequestSize, enrichUserAgent, evaluateCompat, fetchIngesterCompat, flushRuntimeLogs, initAutterLogging, initAutterServer, installAutterAutoFlush, instrumentLlmClient, makeSafeCapture, reportOutcome, runDoctor, runInBackground, runtimeContext, runtimeLogStats, runtimeLogger, sanitizeBrowserPayload, startCaughtExceptionSampler, trackLlmCall, unhandledRejectionsMode, withLlmCall, withProcessSpan, withRuntimeOperation, withRuntimeRequest };