@buenojs/bueno 0.8.10 → 0.8.11

package/dist/observability/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Observability Module
+ *
+ * Provides structured error tracking and observability integration for Bueno.
+ * Implement ErrorReporter to send events to Sentry, Bugsnag, Datadog, or any
+ * custom backend — zero SDK dependencies shipped by the framework.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createApp } from '@buenojs/bueno';
+ * import { ObservabilityModule } from '@buenojs/bueno/observability';
+ *
+ * const app = createApp(AppModule);
+ *
+ * // Wire everything with a single call
+ * const obs = ObservabilityModule.setup(app, {
+ *   reporter: new MyReporter(),
+ *   breadcrumbsSize: 20,
+ *   ignoreStatusCodes: [404, 401],
+ *   tags: { environment: 'production' },
+ * });
+ *
+ * await app.listen(3000);
+ * ```
+ *
+ * ## Writing a reporter (Sentry example)
+ *
+ * ```typescript
+ * import * as Sentry from '@sentry/node';
+ * import type { ErrorReporter, ErrorEvent } from '@buenojs/bueno/observability';
+ *
+ * class SentryReporter implements ErrorReporter {
+ *   constructor(dsn: string) { Sentry.init({ dsn }); }
+ *
+ *   captureError(event: ErrorEvent) {
+ *     Sentry.withScope(scope => {
+ *       if (event.user)    scope.setUser(event.user);
+ *       if (event.traceId) scope.setTag('traceId', event.traceId);
+ *       event.breadcrumbs.forEach(b => scope.addBreadcrumb(b));
+ *       Sentry.captureException(event.error);
+ *     });
+ *   }
+ *
+ *   async flush() { await Sentry.flush(2000); }
+ * }
+ *
+ * ObservabilityModule.setup(app, {
+ *   reporter: new SentryReporter(process.env.SENTRY_DSN),
+ * });
+ * ```
+ */
+import type { Application } from "../modules";
+import { ObservabilityService } from "./service";
+import type { ObservabilityOptions } from "./types";
+/**
+ * Static module class for configuring observability.
+ * Use `ObservabilityModule.setup(app, options)` for the simplest setup.
+ */
+export declare class ObservabilityModule {
+    /**
+     * One-call setup: creates the ObservabilityService, registers the global
+     * interceptor for trace ID injection and breadcrumb tracking, and wires
+     * process-level shutdown flush.
+     *
+     * Call this before `app.listen()`.
+     *
+     * @param app - The Bueno Application instance (from `createApp()`)
+     * @param options - Observability configuration including the reporter
+     * @returns The ObservabilityService — use for manual captureError / addBreadcrumb
+     *
+     * @example
+     * ```typescript
+     * const obs = ObservabilityModule.setup(app, {
+     *   reporter: new SentryReporter(process.env.SENTRY_DSN),
+     *   ignoreStatusCodes: [404, 401],
+     *   tags: { environment: 'production', version: '1.2.3' },
+     * });
+     *
+     * // Later, in a background job:
+     * obs.captureError(new Error('Job failed'));
+     *
+     * // Add a manual breadcrumb:
+     * obs.addBreadcrumb({ type: 'custom', level: 'info', message: 'Checkout started' });
+     * ```
+     */
+    static setup(app: Application, options: ObservabilityOptions): ObservabilityService;
+}
+export type { BreadcrumbEntry, ErrorEvent, ErrorRequestContext, ErrorUserContext, MessageEvent, ErrorReporter, ObservabilityOptions, ObservabilityConfig, } from "./types";
+export { ObservabilityService } from "./service";
+export { extractTraceContext } from "./service";
+export { ObservabilityInterceptor } from "./interceptor";
+export { BreadcrumbCollector, httpBreadcrumb, logBreadcrumb, } from "./breadcrumbs";
+export { generateTraceId, generateSpanId, buildTraceparent } from "./trace";
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;GAGG;AACH,qBAAa,mBAAmB;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,KAAK,CACX,GAAG,EAAE,WAAW,EAChB,OAAO,EAAE,oBAAoB,GAC3B,oBAAoB;CAYvB;AAKD,YAAY,EACX,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAGzD,OAAO,EACN,mBAAmB,EACnB,cAAc,EACd,aAAa,GACb,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAGzD;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,KAAK,CACX,GAAgB,EAChB,OAA6B;QAE7B,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAClD,MAAM,WAAW,GAAG,IAAI,wBAAwB,CAAC,OAAO,CAAC,CAAC;QAE1D,mFAAmF;QACnF,GAAG,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC;QAEvC,iCAAiC;QACjC,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAE3B,OAAO,OAAO,CAAC;IAChB,CAAC;CACD;AAgBD,oBAAoB;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,cAAc;AACd,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD,uBAAuB;AACvB,OAAO,EACN,mBAAmB,EACnB,cAAc,EACd,aAAa,GACb,MAAM,eAAe,CAAC;AAEvB,gBAAgB;AAChB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/observability/interceptor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ObservabilityInterceptor
+ *
+ * Global interceptor that enriches every request with:
+ * 1. Trace/span IDs — extracted from W3C `traceparent` header or generated fresh
+ * 2. Breadcrumbs — records request entry and exit (with status + duration)
+ * 3. Error capture — calls ObservabilityService when a route handler throws
+ *
+ * Register via ObservabilityModule.setup() (done automatically).
+ */
+import type { Context } from "../context";
+import type { CallHandler, NestInterceptor } from "../modules";
+import type { ObservabilityService } from "./service";
+export declare class ObservabilityInterceptor implements NestInterceptor {
+    private readonly service;
+    constructor(service: ObservabilityService);
+    intercept(context: Context, next: CallHandler): Promise<unknown>;
+}
+//# sourceMappingURL=interceptor.d.ts.map

package/dist/observability/interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../../src/observability/interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAkBtD,qBAAa,wBAAyB,YAAW,eAAe;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,oBAAoB;IAEpD,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CAgDtE"}

package/dist/observability/interceptor.js

@@ -0,0 +1,67 @@
+/**
+ * ObservabilityInterceptor
+ *
+ * Global interceptor that enriches every request with:
+ * 1. Trace/span IDs — extracted from W3C `traceparent` header or generated fresh
+ * 2. Breadcrumbs — records request entry and exit (with status + duration)
+ * 3. Error capture — calls ObservabilityService when a route handler throws
+ *
+ * Register via ObservabilityModule.setup() (done automatically).
+ */
+import { generateSpanId, generateTraceId } from "./trace";
+import { httpBreadcrumb } from "./breadcrumbs";
+import { extractTraceContext } from "./service";
+/**
+ * Resolves trace context from the incoming request.
+ * Uses the W3C `traceparent` header if present, otherwise generates new IDs.
+ */
+function resolveTraceIds(context) {
+    const existing = extractTraceContext(context);
+    if (existing.traceId && existing.spanId) {
+        return { traceId: existing.traceId, spanId: existing.spanId };
+    }
+    return { traceId: generateTraceId(), spanId: generateSpanId() };
+}
+export class ObservabilityInterceptor {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    async intercept(context, next) {
+        const startMs = Date.now();
+        // 1. Inject trace IDs into context for downstream use
+        const { traceId, spanId } = resolveTraceIds(context);
+        context.set("traceId", traceId);
+        context.set("spanId", spanId);
+        // 2. Record request entry breadcrumb
+        this.service.addBreadcrumb({
+            type: "navigation",
+            level: "info",
+            message: `${context.method} ${context.path}`,
+            data: { traceId, spanId },
+        });
+        try {
+            const result = await next.handle();
+            // 3a. Record successful request exit
+            const durationMs = Date.now() - startMs;
+            const response = result;
+            const statusCode = response instanceof Response ? response.status : undefined;
+            this.service
+                .getBreadcrumbCollector()
+                .add(httpBreadcrumb(context.method, context.path, statusCode, durationMs));
+            return result;
+        }
+        catch (error) {
+            // 3b. Capture the error with full request context (non-blocking)
+            this.service.captureFromContext(context, error);
+            // 4. Record failed request breadcrumb
+            const durationMs = Date.now() - startMs;
+            this.service
+                .getBreadcrumbCollector()
+                .add(httpBreadcrumb(context.method, context.path, undefined, durationMs));
+            // 5. Rethrow so the framework's exception filters still fire
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=interceptor.js.map

package/dist/observability/interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.js","sourceRoot":"","sources":["../../src/observability/interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD;;;GAGG;AACH,SAAS,eAAe,CAAC,OAAgB;IAIxC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC/D,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,OAAO,wBAAwB;IACP;IAA7B,YAA6B,OAA6B;QAA7B,YAAO,GAAP,OAAO,CAAsB;IAAG,CAAC;IAE9D,KAAK,CAAC,SAAS,CAAC,OAAgB,EAAE,IAAiB;QAClD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE3B,sDAAsD;QACtD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAE9B,qCAAqC;QACrC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC;YAC1B,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,MAAM;YACb,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,EAAE;YAC5C,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;SACzB,CAAC,CAAC;QAEH,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YAEnC,qCAAqC;YACrC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;YACxC,MAAM,QAAQ,GAAG,MAAyB,CAAC;YAC3C,MAAM,UAAU,GACf,QAAQ,YAAY,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YAE5D,IAAI,CAAC,OAAO;iBACV,sBAAsB,EAAE;iBACxB,GAAG,CACH,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,CACpE,CAAC;YAEH,OAAO,MAAM,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,iEAAiE;YACjE,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,OAAO,EAAE,KAAc,CAAC,CAAC;YAEzD,sCAAsC;YACtC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC;YACxC,IAAI,CAAC,OAAO;iBACV,sBAAsB,EAAE;iBACxB,GAAG,CACH,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,CAAC,CACnE,CAAC;YAEH,6DAA6D;YAC7D,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;CACD"}

package/dist/observability/service.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ObservabilityService
+ *
+ * Central service that assembles ErrorEvents and dispatches them to the
+ * configured ErrorReporter. Error capture happens through the
+ * ObservabilityInterceptor which calls captureFromContext() directly.
+ *
+ * Exposes addBreadcrumb() and captureError() for manual instrumentation
+ * throughout the application.
+ */
+import type { Context } from "../context";
+import { BreadcrumbCollector } from "./breadcrumbs";
+import type { BreadcrumbEntry, ErrorEvent, MessageEvent, ObservabilityOptions } from "./types";
+/**
+ * ObservabilityService manages error reporting and breadcrumb tracking.
+ *
+ * Use ObservabilityModule.setup(app, options) to wire it to the application,
+ * or instantiate directly for contexts where the full module isn't needed.
+ *
+ * @example
+ * ```typescript
+ * // Via ObservabilityModule (recommended):
+ * const obs = ObservabilityModule.setup(app, {
+ *   reporter: new SentryReporter(),
+ * });
+ *
+ * // Manual breadcrumb:
+ * obs.addBreadcrumb({
+ *   type: 'custom',
+ *   level: 'info',
+ *   message: 'User completed checkout',
+ *   data: { orderId: '123' }
+ * });
+ * ```
+ */
+export declare class ObservabilityService {
+    private readonly reporter;
+    private readonly breadcrumbs;
+    private readonly options;
+    constructor(options: ObservabilityOptions);
+    /**
+     * Called by ObservabilityInterceptor when an HTTP route throws.
+     * Assembles a full ErrorEvent with request context and dispatches it.
+     * Non-blocking — never delays the HTTP response.
+     */
+    captureFromContext(context: Context, error: Error): void;
+    /**
+     * Register flush on process shutdown.
+     * Called automatically by ObservabilityModule.setup().
+     */
+    registerShutdown(): void;
+    /**
+     * Manually capture an error outside the HTTP pipeline.
+     * Useful inside background jobs, event listeners, scheduled tasks.
+     *
+     * @example
+     * obs.captureError(new Error('Payment failed'), 'error');
+     */
+    captureError(error: Error, level?: ErrorEvent["level"]): void;
+    /**
+     * Manually capture a non-error message.
+     *
+     * @example
+     * obs.captureMessage('Deployment completed', 'info', { version: '2.0.0' });
+     */
+    captureMessage(message: string, level?: MessageEvent["level"], extra?: Record<string, unknown>): void;
+    /**
+     * Add a breadcrumb to the ring buffer.
+     * Breadcrumbs recorded here are included in the next error event.
+     *
+     * @example
+     * obs.addBreadcrumb({
+     *   type: 'custom',
+     *   level: 'info',
+     *   message: 'Fetched user from database',
+     *   data: { userId: 42 }
+     * });
+     */
+    addBreadcrumb(entry: Omit<BreadcrumbEntry, "timestamp"> & {
+        timestamp?: Date;
+    }): void;
+    /**
+     * Access the underlying BreadcrumbCollector.
+     * Used internally by ObservabilityInterceptor.
+     */
+    getBreadcrumbCollector(): BreadcrumbCollector;
+    private assembleEvent;
+    private shouldIgnore;
+    private dispatchAsync;
+    private dispatchMessageAsync;
+    private setupUnhandledCapture;
+}
+/**
+ * Extract traceId and spanId from the W3C traceparent header.
+ * Format: 00-<traceId>-<spanId>-<flags>
+ */
+export declare function extractTraceContext(context: Context): {
+    traceId?: string;
+    spanId?: string;
+};
+//# sourceMappingURL=service.d.ts.map

package/dist/observability/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/observability/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAkB,MAAM,eAAe,CAAC;AACpE,OAAO,KAAK,EACX,eAAe,EACf,UAAU,EAGV,YAAY,EACZ,oBAAoB,EACpB,MAAM,SAAS,CAAC;AAoCjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAMtB;gBAEU,OAAO,EAAE,oBAAoB;IAkBzC;;;;OAIG;IACH,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAYxD;;;OAGG;IACH,gBAAgB,IAAI,IAAI;IAkBxB;;;;;;OAMG;IACH,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,GAAE,UAAU,CAAC,OAAO,CAAW,GAAG,IAAI;IAMtE;;;;;OAKG;IACH,cAAc,CACb,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,YAAY,CAAC,OAAO,CAAU,EACrC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI;IAYP;;;;;;;;;;;OAWG;IACH,aAAa,CACZ,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAAG;QAAE,SAAS,CAAC,EAAE,IAAI,CAAA;KAAE,GAC9D,IAAI;IAOP;;;OAGG;IACH,sBAAsB,IAAI,mBAAmB;IAM7C,OAAO,CAAC,aAAa;IA+BrB,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,qBAAqB;CAa7B;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,OAAO,GACd;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAMvC"}

package/dist/observability/service.js

@@ -0,0 +1,249 @@
+/**
+ * ObservabilityService
+ *
+ * Central service that assembles ErrorEvents and dispatches them to the
+ * configured ErrorReporter. Error capture happens through the
+ * ObservabilityInterceptor which calls captureFromContext() directly.
+ *
+ * Exposes addBreadcrumb() and captureError() for manual instrumentation
+ * throughout the application.
+ */
+import { BreadcrumbCollector, httpBreadcrumb } from "./breadcrumbs";
+// ============= Helpers =============
+function generateId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+function extractSafeHeaders(req) {
+    const safe = {};
+    const sensitiveHeaders = new Set([
+        "authorization",
+        "cookie",
+        "x-api-key",
+        "x-auth-token",
+        "proxy-authorization",
+    ]);
+    req.headers.forEach((value, key) => {
+        if (!sensitiveHeaders.has(key.toLowerCase())) {
+            safe[key] = value;
+        }
+    });
+    return safe;
+}
+function getStatusCode(error) {
+    const e = error;
+    return e.statusCode ?? e.status;
+}
+// ============= Service =============
+/**
+ * ObservabilityService manages error reporting and breadcrumb tracking.
+ *
+ * Use ObservabilityModule.setup(app, options) to wire it to the application,
+ * or instantiate directly for contexts where the full module isn't needed.
+ *
+ * @example
+ * ```typescript
+ * // Via ObservabilityModule (recommended):
+ * const obs = ObservabilityModule.setup(app, {
+ *   reporter: new SentryReporter(),
+ * });
+ *
+ * // Manual breadcrumb:
+ * obs.addBreadcrumb({
+ *   type: 'custom',
+ *   level: 'info',
+ *   message: 'User completed checkout',
+ *   data: { orderId: '123' }
+ * });
+ * ```
+ */
+export class ObservabilityService {
+    reporter;
+    breadcrumbs;
+    options;
+    constructor(options) {
+        this.reporter = options.reporter;
+        this.options = {
+            breadcrumbsSize: options.breadcrumbsSize ?? 20,
+            ignoreErrors: options.ignoreErrors ?? [],
+            ignoreStatusCodes: options.ignoreStatusCodes ?? [],
+            tags: options.tags ?? {},
+            captureUnhandled: options.captureUnhandled ?? false,
+        };
+        this.breadcrumbs = new BreadcrumbCollector(this.options.breadcrumbsSize);
+        if (this.options.captureUnhandled) {
+            this.setupUnhandledCapture();
+        }
+    }
+    // ============= Framework Integration =============
+    /**
+     * Called by ObservabilityInterceptor when an HTTP route throws.
+     * Assembles a full ErrorEvent with request context and dispatches it.
+     * Non-blocking — never delays the HTTP response.
+     */
+    captureFromContext(context, error) {
+        if (this.shouldIgnore(error))
+            return;
+        // Add a breadcrumb for the failed request entry
+        this.breadcrumbs.add(httpBreadcrumb(context.method, context.path, undefined));
+        const event = this.assembleEvent(error, "error", context);
+        this.dispatchAsync(event);
+    }
+    /**
+     * Register flush on process shutdown.
+     * Called automatically by ObservabilityModule.setup().
+     */
+    registerShutdown() {
+        const flush = async () => {
+            if (this.reporter.flush) {
+                try {
+                    await this.reporter.flush();
+                }
+                catch (err) {
+                    console.error("[ObservabilityService] Reporter flush failed:", err);
+                }
+            }
+        };
+        process.once("beforeExit", () => {
+            flush().catch(console.error);
+        });
+    }
+    // ============= Public API =============
+    /**
+     * Manually capture an error outside the HTTP pipeline.
+     * Useful inside background jobs, event listeners, scheduled tasks.
+     *
+     * @example
+     * obs.captureError(new Error('Payment failed'), 'error');
+     */
+    captureError(error, level = "error") {
+        if (this.shouldIgnore(error))
+            return;
+        const event = this.assembleEvent(error, level);
+        this.dispatchAsync(event);
+    }
+    /**
+     * Manually capture a non-error message.
+     *
+     * @example
+     * obs.captureMessage('Deployment completed', 'info', { version: '2.0.0' });
+     */
+    captureMessage(message, level = "info", extra) {
+        if (!this.reporter.captureMessage)
+            return;
+        const event = {
+            id: generateId(),
+            timestamp: new Date(),
+            message,
+            level,
+            extra,
+        };
+        this.dispatchMessageAsync(event);
+    }
+    /**
+     * Add a breadcrumb to the ring buffer.
+     * Breadcrumbs recorded here are included in the next error event.
+     *
+     * @example
+     * obs.addBreadcrumb({
+     *   type: 'custom',
+     *   level: 'info',
+     *   message: 'Fetched user from database',
+     *   data: { userId: 42 }
+     * });
+     */
+    addBreadcrumb(entry) {
+        this.breadcrumbs.add({
+            ...entry,
+            timestamp: entry.timestamp ?? new Date(),
+        });
+    }
+    /**
+     * Access the underlying BreadcrumbCollector.
+     * Used internally by ObservabilityInterceptor.
+     */
+    getBreadcrumbCollector() {
+        return this.breadcrumbs;
+    }
+    // ============= Private =============
+    assembleEvent(error, level, context) {
+        const user = context?.get("user");
+        const traceId = context?.get("traceId") ?? undefined;
+        const spanId = context?.get("spanId") ?? undefined;
+        return {
+            id: generateId(),
+            timestamp: new Date(),
+            error,
+            level,
+            request: context
+                ? {
+                    method: context.method,
+                    path: context.path,
+                    headers: extractSafeHeaders(context.req),
+                    ip: context.ip ?? "",
+                    userAgent: context.getHeader("user-agent"),
+                }
+                : undefined,
+            traceId,
+            spanId,
+            user: user ?? undefined,
+            breadcrumbs: this.breadcrumbs.getAll(),
+            tags: { ...this.options.tags },
+        };
+    }
+    shouldIgnore(error) {
+        for (const ErrorClass of this.options.ignoreErrors) {
+            if (error instanceof ErrorClass)
+                return true;
+        }
+        if (this.options.ignoreStatusCodes.length > 0) {
+            const code = getStatusCode(error);
+            if (code !== undefined && this.options.ignoreStatusCodes.includes(code)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    dispatchAsync(event) {
+        // Fire-and-forget — never blocks the HTTP response
+        Promise.resolve(this.reporter.captureError(event)).catch((err) => {
+            console.error("[ObservabilityService] Reporter.captureError failed:", err);
+        });
+    }
+    dispatchMessageAsync(event) {
+        if (!this.reporter.captureMessage)
+            return;
+        Promise.resolve(this.reporter.captureMessage(event)).catch((err) => {
+            console.error("[ObservabilityService] Reporter.captureMessage failed:", err);
+        });
+    }
+    setupUnhandledCapture() {
+        process.on("unhandledRejection", (reason) => {
+            const error = reason instanceof Error
+                ? reason
+                : new Error(String(reason ?? "Unhandled rejection"));
+            this.captureError(error, "error");
+        });
+        process.on("uncaughtException", (error) => {
+            this.captureError(error, "fatal");
+        });
+    }
+}
+// ============= Trace Context Extraction =============
+/**
+ * Extract traceId and spanId from the W3C traceparent header.
+ * Format: 00-<traceId>-<spanId>-<flags>
+ */
+export function extractTraceContext(context) {
+    const traceparent = context.getHeader("traceparent");
+    if (!traceparent)
+        return {};
+    const parts = traceparent.split("-");
+    if (parts.length < 4)
+        return {};
+    return { traceId: parts[1], spanId: parts[2] };
+}
+//# sourceMappingURL=service.js.map

package/dist/observability/service.js.map

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

package/dist/observability/trace.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Trace ID generation helpers
+ *
+ * Generates W3C TraceContext-compatible IDs using the Web Crypto API.
+ * These are intentionally kept separate from src/telemetry to avoid
+ * coupling the observability module to the OTLP tracing module.
+ */
+/**
+ * Generate a W3C-compatible trace ID (32 hex characters / 16 bytes)
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a W3C-compatible span ID (16 hex characters / 8 bytes)
+ */
+export declare function generateSpanId(): string;
+/**
+ * Build a W3C `traceparent` header value from traceId + spanId.
+ * Format: 00-<traceId>-<spanId>-01
+ */
+export declare function buildTraceparent(traceId: string, spanId: string): string;
+//# sourceMappingURL=trace.d.ts.map

package/dist/observability/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/observability/trace.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAMxC;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAMvC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/observability/trace.js

@@ -0,0 +1,35 @@
+/**
+ * Trace ID generation helpers
+ *
+ * Generates W3C TraceContext-compatible IDs using the Web Crypto API.
+ * These are intentionally kept separate from src/telemetry to avoid
+ * coupling the observability module to the OTLP tracing module.
+ */
+/**
+ * Generate a W3C-compatible trace ID (32 hex characters / 16 bytes)
+ */
+export function generateTraceId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Generate a W3C-compatible span ID (16 hex characters / 8 bytes)
+ */
+export function generateSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/**
+ * Build a W3C `traceparent` header value from traceId + spanId.
+ * Format: 00-<traceId>-<spanId>-01
+ */
+export function buildTraceparent(traceId, spanId) {
+    return `00-${traceId}-${spanId}-01`;
+}
+//# sourceMappingURL=trace.js.map

package/dist/observability/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/observability/trace.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,UAAU,eAAe;IAC9B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACtB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAC7B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SACtB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,MAAc;IAC/D,OAAO,MAAM,OAAO,IAAI,MAAM,KAAK,CAAC;AACrC,CAAC"}