@sigx/lynx-observability 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @sigx/lynx-observability
+
+Opt-in **production error capture** and **provider-agnostic log/error sinks** for sigx-lynx. Builds on the logger in [`@sigx/lynx-core`](https://github.com/signalxjs/lynx/tree/main/packages/lynx-core#logging): uncaught errors are funneled in as `error`-level records, and a "sink" is just a `LogTransport`. No hard dependency on any vendor SDK.
+
+> Logging itself ships in the framework (`import { createLogger } from '@sigx/lynx'`). This package adds the *production* pieces — catching crashes and shipping records off-device — and is installed only when you want them.
+
+## Install
+
+```sh
+pnpm add @sigx/lynx-observability
+```
+
+## Quick start — declarative (recommended)
+
+Declare it in `signalx.config.ts` and it auto-wires in **release** builds — no code in your app entry:
+
+```ts
+// signalx.config.ts
+export default defineLynxConfig({
+    name: 'my-app',
+    logging: {
+        level: 'warn',                     // logger level (also dev: 'debug' / release: 'warn' default)
+        namespaces: { disabled: ['http'] },// silence namespaces at startup
+        production: {
+            sink: { url: 'https://logs.example.com/ingest', headers: { 'x-api-key': KEY }, sampleRate: 0.25 },
+            captureErrors: true,           // default
+        },
+    },
+});
+```
+
+Just install the package (`pnpm add @sigx/lynx-observability`) — `@sigx/lynx-plugin` prepends the init for you in release builds. (Dev uses the console streamer; observability auto-wiring is release-only.)
+
+## Quick start — manual
+
+Or wire it yourself, `Sentry.init()`-style (call once in your app entry):
+
+```ts
+import { initObservability } from '@sigx/lynx-observability';
+
+initObservability({
+    level: 'warn',                    // optional: override the default level
+    captureErrors: true,              // default — catch uncaught errors / rejections
+    sink: {                           // optional remote sink
+        url: 'https://logs.example.com/ingest',
+        headers: { 'x-api-key': API_KEY },
+        sampleRate: 0.25,             // keep 25% of non-error records; errors always kept
+    },
+});
+```
+
+That's it: uncaught errors now flow to your logs (and the `sigx dev` terminal in development), and records at/above the level are batched and POSTed to your endpoint.
+
+## Pieces (compose them yourself)
+
+- **`installErrorCapture(opts?)`** — registers Lynx's `lynx.onError` (background thread) plus `globalThis` `error`/`unhandledrejection` handlers, normalizes whatever was thrown into an `Error`, and logs it at `error` level under the `uncaught` namespace. The `Error` rides in the record's `fields`, so transports can treat it as an exception (with a stack). Idempotent; returns an uninstall function.
+- **`createHttpSink(opts)`** — a batching `LogTransport` that POSTs `{ records: [...] }` as JSON to `opts.url`. Options: `batchSize`, `flushIntervalMs`, `sampleRate`, `minLevel`, `headers`, `excludeNamespaces`. `Error` fields are serialized to `{ name, message, stack }`. It excludes the `http` namespace by default (its own POSTs log there) and swallows its own send failures, so it can't feed back into itself. Has a `.flush()` for graceful shutdown.
+- **`toError(value)`** — the normalization helper, exported for reuse.
+
+```ts
+import { addTransport } from '@sigx/lynx';
+import { createHttpSink, installErrorCapture } from '@sigx/lynx-observability';
+
+addTransport(createHttpSink({ url, minLevel: 'info' }));
+const uninstall = installErrorCapture({ onError: (e) => myAnalytics.track('crash', e.message) });
+```
+
+## Wire format
+
+The sink POSTs:
+
+```json
+{ "records": [ { "level": "error", "namespace": "uncaught", "msg": "[lynx] …", "fields": [ { "name": "TypeError", "message": "…", "stack": "…" } ], "ts": 1733740000000 } ] }
+```
+
+## Provider adapters
+
+There's no built-in vendor coupling — any provider is a `LogTransport`. Errors arrive as `error`-level records with the `Error` in `fields[0]`, so an adapter can split exceptions from breadcrumbs. Example **Sentry** adapter (Sentry is an optional peer in *your* app, not a dependency of this package):
+
+```ts
+import * as Sentry from '@sentry/browser'; // your app's dep
+import { addTransport, installErrorCapture, type LogRecord } from '@sigx/lynx';
+
+Sentry.init({ dsn: SENTRY_DSN });
+
+addTransport((r: LogRecord) => {
+    const err = r.fields.find((f) => f instanceof Error) as Error | undefined;
+    if (r.level.name === 'error' && err) {
+        Sentry.captureException(err);
+    } else {
+        Sentry.addBreadcrumb({ category: r.namespace, message: r.msg, level: r.level.name });
+    }
+});
+installErrorCapture();
+```
+
+The same shape works for Datadog, a custom backend, etc.
+
+## Notes
+
+- `lynx.onError` is **background-thread only** upstream; main-thread error capture may need a separate path in the future.
+- For readable stack traces in release builds, upload your source maps to your provider (out of scope here).
+- Declarative `signalx.config.ts` `logging.production` config auto-wires this package in release builds (see Quick start above); `initObservability()` remains for manual/dev setup.

package/dist/error-capture.d.ts

@@ -0,0 +1,13 @@
+export interface ErrorCaptureOptions {
+    /** Extra callback invoked with the normalized Error for each captured error. */
+    onError?: (error: Error) => void;
+}
+/** Normalize anything thrown (Error, ErrorEvent, PromiseRejection, string, …) into an Error. */
+export declare function toError(input: unknown): Error;
+/**
+ * Install global error capture. Returns an uninstall function. Idempotent —
+ * calling it again while already installed is a no-op and returns a no-op
+ * uninstall.
+ */
+export declare function installErrorCapture(opts?: ErrorCaptureOptions): () => void;
+//# sourceMappingURL=error-capture.d.ts.map

package/dist/error-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-capture.d.ts","sourceRoot":"","sources":["../src/error-capture.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,mBAAmB;IAChC,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpC;AAUD,gGAAgG;AAChG,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAa7C;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,mBAAwB,GAAG,MAAM,IAAI,CAmE9E"}

package/dist/error-capture.js

@@ -0,0 +1,117 @@
+/**
+ * Production error capture. Registers Lynx's background-thread error hook
+ * (`lynx.onError`) plus the `globalThis` `error` / `unhandledrejection`
+ * handlers where present, normalizes whatever was thrown into an `Error`, and
+ * funnels it into the core logger as an `error`-level record under the
+ * `uncaught` namespace.
+ *
+ * Because it goes through the core logger, captured errors show up in the
+ * `sigx dev` terminal AND reach every registered transport (e.g. a remote
+ * sink from {@link createHttpSink}). The original `Error` rides in the record
+ * `fields`, so transports can treat it as an exception (with a stack) rather
+ * than a plain log line.
+ */
+import { createLogger } from '@sigx/lynx-core';
+const log = createLogger('uncaught');
+function lynxObj() {
+    return typeof lynx !== 'undefined' ? lynx : undefined;
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Normalize anything thrown (Error, ErrorEvent, PromiseRejection, string, …) into an Error. */
+export function toError(input) {
+    if (input instanceof Error)
+        return input;
+    if (input && typeof input === 'object') {
+        const o = input;
+        // ErrorEvent.error / PromiseRejectionEvent.reason may hold the real Error.
+        const inner = o['error'] ?? o['reason'];
+        if (inner instanceof Error)
+            return inner;
+        const msg = o['message'] ?? o['reason'] ?? o['error'];
+        const err = new Error(typeof msg === 'string' && msg ? msg : safeStringify(input));
+        if (typeof o['stack'] === 'string')
+            err.stack = o['stack'];
+        return err;
+    }
+    return new Error(typeof input === 'string' ? input : safeStringify(input));
+}
+// Idempotent across module re-evaluation (HMR) / multiple bundle copies.
+const G = globalThis;
+const INSTALLED = '__sigxObservabilityErrorCaptureInstalled';
+/**
+ * Install global error capture. Returns an uninstall function. Idempotent —
+ * calling it again while already installed is a no-op and returns a no-op
+ * uninstall.
+ */
+export function installErrorCapture(opts = {}) {
+    if (G[INSTALLED])
+        return () => { };
+    G[INSTALLED] = true;
+    const report = (input, source) => {
+        const err = toError(input);
+        // Error object in fields → transports can treat it as an exception.
+        log.error(`[${source}] ${err.message}`, err);
+        try {
+            opts.onError?.(err);
+        }
+        catch {
+            /* never let a user hook break capture */
+        }
+    };
+    const undo = [];
+    // 1. Lynx background-thread hook (no documented removal — nothing to undo).
+    const lx = lynxObj();
+    if (typeof lx?.onError === 'function') {
+        lx.onError((e) => report(e, 'lynx'));
+    }
+    // 2. globalThis handlers (web/dev and any host exposing them).
+    const g = globalThis;
+    if (typeof g.addEventListener === 'function') {
+        const onErr = (e) => report(e?.error ?? e, 'error');
+        const onRej = (e) => report(e?.reason ?? e, 'unhandledrejection');
+        g.addEventListener('error', onErr);
+        g.addEventListener('unhandledrejection', onRej);
+        undo.push(() => {
+            g.removeEventListener?.('error', onErr);
+            g.removeEventListener?.('unhandledrejection', onRej);
+        });
+    }
+    else {
+        const prevErr = g.onerror;
+        const prevRej = g.onunhandledrejection;
+        g.onerror = (...args) => {
+            // (message, source, lineno, colno, error)
+            report(args[4] ?? args[0], 'error');
+            // Chain to any pre-existing handler so we don't clobber host/app
+            // error reporting; preserve its return value (truthy = handled).
+            if (typeof prevErr === 'function') {
+                return prevErr(...args);
+            }
+            return false;
+        };
+        g.onunhandledrejection = (e) => {
+            report(e?.reason ?? e, 'unhandledrejection');
+            if (typeof prevRej === 'function')
+                prevRej(e);
+        };
+        undo.push(() => {
+            g.onerror = prevErr;
+            g.onunhandledrejection = prevRej;
+        });
+    }
+    return () => {
+        if (!G[INSTALLED])
+            return;
+        G[INSTALLED] = false;
+        for (const u of undo)
+            u();
+    };
+}
+//# sourceMappingURL=error-capture.js.map

package/dist/error-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-capture.js","sourceRoot":"","sources":["../src/error-capture.ts"],"names":[],"mappings":"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"}

package/dist/http-sink.d.ts

@@ -0,0 +1,23 @@
+import type { LogLevelName, LogTransport } from '@sigx/lynx-core';
+export interface HttpSinkOptions {
+    /** Endpoint that receives `POST` `{ records: WireRecord[] }`. */
+    url: string;
+    /** Extra headers (e.g. auth). `content-type: application/json` is set for you. */
+    headers?: Record<string, string>;
+    /** Flush once the buffer reaches this many records. Default 20. */
+    batchSize?: number;
+    /** Flush at most this often (ms) while records trickle in. Default 5000. */
+    flushIntervalMs?: number;
+    /** Keep this fraction (0–1) of non-error records; errors are always kept. Default 1. */
+    sampleRate?: number;
+    /** Only send records at or above this level. Default `'info'`. */
+    minLevel?: LogLevelName;
+    /** Namespaces to drop. Default `['http']` (prevents the sink's own POSTs feeding back). */
+    excludeNamespaces?: string[];
+}
+/** A LogTransport with an extra `flush()` for tests / graceful shutdown. */
+export type HttpSink = LogTransport & {
+    flush(): void;
+};
+export declare function createHttpSink(opts: HttpSinkOptions): HttpSink;
+//# sourceMappingURL=http-sink.d.ts.map

package/dist/http-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-sink.d.ts","sourceRoot":"","sources":["../src/http-sink.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAa,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAM7E,MAAM,WAAW,eAAe;IAC5B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,2FAA2F;IAC3F,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAUD,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE,CAAC;AAOxD,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,QAAQ,CAoD9D"}

package/dist/http-sink.js

@@ -0,0 +1,75 @@
+/**
+ * Provider-agnostic batching HTTP sink — a {@link LogTransport} that buffers
+ * log records and POSTs them as JSON to any endpoint (your own backend, an
+ * OTLP-style collector, a serverless function, …). Register it with the core
+ * logger's `addTransport`.
+ *
+ * Loop safety: the sink's own POST goes through `@sigx/lynx-http`, which logs
+ * under the `http` namespace — so that namespace is excluded by default to
+ * stop the sink from feeding its own traffic back into itself. The sink also
+ * swallows its own send failures (it never logs them).
+ */
+import { fetch } from '@sigx/lynx-http';
+const SEVERITY = {
+    trace: 10, debug: 20, info: 30, warn: 40, error: 50, silent: 100,
+};
+function serializeField(f) {
+    if (f instanceof Error)
+        return { name: f.name, message: f.message, stack: f.stack };
+    return f;
+}
+export function createHttpSink(opts) {
+    const batchSize = opts.batchSize ?? 20;
+    const flushIntervalMs = opts.flushIntervalMs ?? 5000;
+    const sampleRate = opts.sampleRate ?? 1;
+    const minSeverity = SEVERITY[opts.minLevel ?? 'info'];
+    const exclude = new Set(opts.excludeNamespaces ?? ['http']);
+    let buffer = [];
+    let timer = null;
+    const flush = () => {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (buffer.length === 0)
+            return;
+        const batch = buffer;
+        buffer = [];
+        // Fire-and-forget; swallow failures so the sink never feeds its own
+        // errors back into the logger (which would loop into this transport).
+        void fetch(opts.url, {
+            method: 'POST',
+            // content-type is set for us — caller headers can't override it.
+            headers: { ...opts.headers, 'content-type': 'application/json' },
+            body: JSON.stringify({ records: batch }),
+        }).catch(() => { });
+    };
+    const schedule = () => {
+        if (timer === null)
+            timer = setTimeout(flush, flushIntervalMs);
+    };
+    const sink = ((record) => {
+        if (record.level.severity < minSeverity)
+            return;
+        if (exclude.has(record.namespace))
+            return;
+        // Sample non-error records; always keep errors.
+        if (sampleRate < 1 && record.level.severity < SEVERITY.error && Math.random() >= sampleRate) {
+            return;
+        }
+        buffer.push({
+            level: record.level.name,
+            namespace: record.namespace,
+            msg: record.msg,
+            fields: record.fields.map(serializeField),
+            ts: record.ts,
+        });
+        if (buffer.length >= batchSize)
+            flush();
+        else
+            schedule();
+    });
+    sink.flush = flush;
+    return sink;
+}
+//# sourceMappingURL=http-sink.js.map

package/dist/http-sink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-sink.js","sourceRoot":"","sources":["../src/http-sink.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @sigx/lynx-observability — opt-in production error capture + provider-agnostic
+ * log/error sinks for sigx-lynx.
+ *
+ * Builds on the `@sigx/lynx-core` logger: uncaught errors are funneled in as
+ * `error`-level records, and sinks are just `LogTransport`s. Call
+ * {@link initObservability} once in your app entry, or compose the pieces
+ * ({@link installErrorCapture}, {@link createHttpSink}) yourself.
+ *
+ * @packageDocumentation
+ */
+export { initObservability } from './init.js';
+export type { ObservabilityOptions } from './init.js';
+export { installErrorCapture, toError } from './error-capture.js';
+export type { ErrorCaptureOptions } from './error-capture.js';
+export { createHttpSink } from './http-sink.js';
+export type { HttpSink, HttpSinkOptions } from './http-sink.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * @sigx/lynx-observability — opt-in production error capture + provider-agnostic
+ * log/error sinks for sigx-lynx.
+ *
+ * Builds on the `@sigx/lynx-core` logger: uncaught errors are funneled in as
+ * `error`-level records, and sinks are just `LogTransport`s. Call
+ * {@link initObservability} once in your app entry, or compose the pieces
+ * ({@link installErrorCapture}, {@link createHttpSink}) yourself.
+ *
+ * @packageDocumentation
+ */
+export { initObservability } from './init.js';
+export { installErrorCapture, toError } from './error-capture.js';
+export { createHttpSink } from './http-sink.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One-call setup, à la `Sentry.init()`. Call once in your app entry.
+ *
+ * @example
+ * ```ts
+ * import { initObservability } from '@sigx/lynx-observability';
+ *
+ * initObservability({
+ *     level: 'warn',                              // optional: override the default level
+ *     captureErrors: true,                        // default: capture uncaught errors
+ *     sink: { url: 'https://logs.example.com/ingest', headers: { 'x-api-key': KEY } },
+ * });
+ * ```
+ */
+import { type LogLevelName } from '@sigx/lynx-core';
+import { type HttpSinkOptions } from './http-sink.js';
+import { type ErrorCaptureOptions } from './error-capture.js';
+export interface ObservabilityOptions {
+    /** Override the global log level (e.g. `'warn'` in production). */
+    level?: LogLevelName;
+    /** Remote sink to forward records to. Omit for error-capture only. */
+    sink?: HttpSinkOptions;
+    /** Capture uncaught errors / unhandled rejections. Default `true`. */
+    captureErrors?: boolean;
+    /** Options for {@link installErrorCapture} (e.g. an extra `onError` hook). */
+    errorCapture?: ErrorCaptureOptions;
+}
+/** Wire up logging level, an optional remote sink, and error capture in one call. */
+export declare function initObservability(opts?: ObservabilityOptions): void;
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,oBAAoB;IACjC,mEAAmE;IACnE,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,sEAAsE;IACtE,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,sEAAsE;IACtE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,oBAAyB,GAAG,IAAI,CAIvE"}

package/dist/init.js

@@ -0,0 +1,27 @@
+/**
+ * One-call setup, à la `Sentry.init()`. Call once in your app entry.
+ *
+ * @example
+ * ```ts
+ * import { initObservability } from '@sigx/lynx-observability';
+ *
+ * initObservability({
+ *     level: 'warn',                              // optional: override the default level
+ *     captureErrors: true,                        // default: capture uncaught errors
+ *     sink: { url: 'https://logs.example.com/ingest', headers: { 'x-api-key': KEY } },
+ * });
+ * ```
+ */
+import { addTransport, setLogLevel } from '@sigx/lynx-core';
+import { createHttpSink } from './http-sink.js';
+import { installErrorCapture } from './error-capture.js';
+/** Wire up logging level, an optional remote sink, and error capture in one call. */
+export function initObservability(opts = {}) {
+    if (opts.level)
+        setLogLevel(opts.level);
+    if (opts.sink)
+        addTransport(createHttpSink(opts.sink));
+    if (opts.captureErrors !== false)
+        installErrorCapture(opts.errorCapture);
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAqB,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAwB,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAA4B,MAAM,oBAAoB,CAAC;AAanF,qFAAqF;AACrF,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAAyB,EAAE;IAC7D,IAAI,IAAI,CAAC,KAAK;QAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,IAAI,IAAI,CAAC,IAAI;QAAE,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,IAAI,IAAI,CAAC,aAAa,KAAK,KAAK;QAAE,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AAC7E,CAAC"}

package/dist/install.d.ts

@@ -0,0 +1,13 @@
+import type { HttpSinkOptions } from './http-sink.js';
+/** Config injected into {@link install} (the `logging.production` shape). */
+export interface InjectedObservabilityConfig {
+    sink?: HttpSinkOptions;
+    captureErrors?: boolean;
+}
+/**
+ * Apply the injected config: no-op when `null`/`undefined`, otherwise wire up
+ * observability. Never throws — observability must not crash the host app.
+ * Exported (not just the side effect) so it's unit-testable.
+ */
+export declare function install(cfg: InjectedObservabilityConfig | null | undefined): void;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IACxC,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,2BAA2B,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAMjF"}

package/dist/install.js

@@ -0,0 +1,25 @@
+/**
+ * Auto-installed by `@sigx/lynx-plugin` in **release** builds when the app's
+ * `signalx.config.ts` declares `logging.production`. Prepended to the BG entry
+ * so error capture + the remote sink are wired before app code runs.
+ *
+ * Never import this directly from app code — it has unconditional side effects.
+ * To set up observability manually instead, call `initObservability(...)`.
+ */
+import { initObservability } from './init.js';
+/**
+ * Apply the injected config: no-op when `null`/`undefined`, otherwise wire up
+ * observability. Never throws — observability must not crash the host app.
+ * Exported (not just the side effect) so it's unit-testable.
+ */
+export function install(cfg) {
+    try {
+        if (cfg)
+            initObservability({ sink: cfg.sink, captureErrors: cfg.captureErrors });
+    }
+    catch {
+        /* never let observability wiring crash the host app */
+    }
+}
+install(typeof __SIGX_OBSERVABILITY_CONFIG__ !== 'undefined' ? __SIGX_OBSERVABILITY_CONFIG__ : null);
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAS9C;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,GAAmD;IACvE,IAAI,CAAC;QACD,IAAI,GAAG;YAAE,iBAAiB,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACL,uDAAuD;IAC3D,CAAC;AACL,CAAC;AAMD,OAAO,CAAC,OAAO,6BAA6B,KAAK,WAAW,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@sigx/lynx-observability",
+  "version": "0.5.2",
+  "description": "Opt-in production error capture + provider-agnostic log/error sinks for sigx-lynx",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./install": {
+      "import": "./dist/install.js",
+      "types": "./dist/install.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "sigx",
+    "lynx",
+    "logging",
+    "observability",
+    "error-reporting"
+  ],
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-observability"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-observability",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "dependencies": {
+    "@sigx/lynx-core": "^0.5.2",
+    "@sigx/lynx-http": "^0.5.2"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean.mjs dist && tsgo",
+    "dev": "tsgo --watch",
+    "clean": "node ../../scripts/clean.mjs dist .turbo"
+  }
+}