@buenojs/bueno 0.8.5 → 0.8.7

package/dist/notification/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Notification System Type Definitions
+ *
+ * Flexible multi-channel notification system with support for email, SMS,
+ * WhatsApp, push notifications, and custom channels. Uses registry pattern
+ * for dynamic channel registration.
+ */
+/**
+ * Supported notification channels
+ */
+export type NotificationChannel = "email" | "sms" | "whatsapp" | "push" | string;
+/**
+ * Base notification message interface
+ * All notification types must extend this
+ */
+export interface NotificationMessage {
+    /** Channel identifier */
+    channel: NotificationChannel;
+    /** Recipient identifier (email, phone, device ID, etc) */
+    recipient: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Reference to a template file with rendering data.
+ * Used in message fields that support template rendering.
+ * The NotificationService will resolve this to a rendered string before sending.
+ */
+export interface TemplateRef {
+    /** Template identifier (path without extension, e.g. "emails/welcome") */
+    templateId: string;
+    /** Data to pass to the template renderer */
+    data: Record<string, unknown>;
+    /** Optional variant override (e.g. "email", "sms"). Auto-detected from channel if omitted. */
+    variant?: string;
+    /** Output format: "html" or "text". Defaults based on field context. */
+    outputFormat?: "html" | "text";
+}
+/**
+ * Type guard for TemplateRef
+ */
+export declare function isTemplateRef(value: unknown): value is TemplateRef;
+export interface EmailRecipient {
+    name?: string;
+    email: string;
+}
+export type EmailRecipients = string | EmailRecipient | (string | EmailRecipient)[];
+export interface EmailAttachment {
+    filename: string;
+    content: string | Buffer;
+    contentType?: string;
+    encoding?: string;
+    contentDisposition?: "attachment" | "inline";
+    cid?: string;
+}
+export interface EmailMessage extends NotificationMessage {
+    channel: "email";
+    recipient: string;
+    subject: string;
+    html?: string | TemplateRef;
+    text?: string | TemplateRef;
+    cc?: EmailRecipients;
+    bcc?: EmailRecipients;
+    replyTo?: string;
+    from?: string;
+    attachments?: EmailAttachment[];
+    headers?: Record<string, string>;
+    messageId?: string;
+    references?: string[];
+    inReplyTo?: string;
+    tags?: string[];
+    priority?: "high" | "normal" | "low";
+    scheduledAt?: Date;
+}
+export interface SMSMessage extends NotificationMessage {
+    channel: "sms";
+    recipient: string;
+    message: string | TemplateRef;
+    senderId?: string;
+    scheduledAt?: Date;
+}
+export interface WhatsAppMessage extends NotificationMessage {
+    channel: "whatsapp";
+    recipient: string;
+    templateId: string;
+    parameters?: Record<string, string>;
+    mediaUrl?: string;
+}
+export interface PushNotificationMessage extends NotificationMessage {
+    channel: "push";
+    recipient: string;
+    title: string | TemplateRef;
+    body: string | TemplateRef;
+    actionUrl?: string;
+    imageUrl?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Union of all built-in notification types
+ */
+export type BuiltInNotification = EmailMessage | SMSMessage | WhatsAppMessage | PushNotificationMessage;
+/**
+ * Interface for composable notification messages
+ * Implement this interface to create reusable notification templates
+ */
+export interface Notifiable {
+    /**
+     * Build notification message(s)
+     * Can return single message or array of messages for multi-channel
+     * @returns NotificationMessage or Promise<NotificationMessage>
+     */
+    build(channel?: NotificationChannel): NotificationMessage | Promise<NotificationMessage>;
+    /**
+     * Optional: Build multiple channel notifications at once
+     */
+    buildAll?(): Record<NotificationChannel, NotificationMessage | Promise<NotificationMessage>>;
+}
+/**
+ * Health status for channel services
+ */
+export interface ChannelHealth {
+    status: "healthy" | "degraded" | "unhealthy";
+    message: string;
+    checkedAt: Date;
+    error?: string;
+}
+/**
+ * Base interface for all channel services
+ */
+export interface ChannelService<T extends NotificationMessage = NotificationMessage> {
+    /** Channel name/identifier */
+    readonly name: NotificationChannel;
+    /** Configuration schema validator (optional) */
+    readonly configSchema?: StandardSchema;
+    /**
+     * Validate message structure at runtime
+     * Should throw if message is invalid
+     */
+    validate(message: unknown): asserts message is T;
+    /**
+     * Send a notification message
+     * @returns Message ID or undefined if not trackable
+     */
+    send(message: T): Promise<string | undefined>;
+    /**
+     * Get channel health status
+     */
+    getHealth?(): Promise<ChannelHealth>;
+    /**
+     * Get channel metrics (optional)
+     */
+    getMetrics?(): Promise<ChannelMetrics>;
+}
+export interface BaseChannelConfig {
+    /** Enable this channel */
+    enabled?: boolean;
+    /** Dry-run mode (log instead of sending) */
+    dryRun?: boolean;
+    /** Enable metrics collection */
+    enableMetrics?: boolean;
+}
+export interface EmailChannelConfig extends BaseChannelConfig {
+    driver: "smtp" | "sendgrid" | "brevo" | "resend";
+    from: string;
+    fromName?: string;
+    smtp?: {
+        host: string;
+        port: number;
+        secure?: boolean;
+        username?: string;
+        password?: string;
+    };
+    apiKey?: string;
+}
+export interface SMSChannelConfig extends BaseChannelConfig {
+    driver: "twilio" | "aws-sns" | "custom";
+    accountSid?: string;
+    authToken?: string;
+    fromNumber?: string;
+    apiKey?: string;
+}
+export interface WhatsAppChannelConfig extends BaseChannelConfig {
+    driver: "twilio" | "custom";
+    accountSid?: string;
+    authToken?: string;
+    businessPhoneNumber?: string;
+    apiKey?: string;
+}
+export interface PushChannelConfig extends BaseChannelConfig {
+    driver: "firebase" | "apns" | "custom";
+    serverKey?: string;
+    certificatePath?: string;
+    apiKey?: string;
+}
+export type ChannelConfig = EmailChannelConfig | SMSChannelConfig | WhatsAppChannelConfig | PushChannelConfig | Record<string, unknown>;
+export interface NotificationServiceConfig {
+    /** Channels configuration */
+    channels?: Record<NotificationChannel, ChannelConfig>;
+    /** Default channel for sending */
+    defaultChannel?: NotificationChannel;
+    /** Queue system for async sending */
+    queue?: boolean;
+    /** Enable metrics collection */
+    enableMetrics?: boolean;
+    /** Optional template engine for rendering TemplateRef fields */
+    templateEngine?: import("../templates/engine").TemplateEngine;
+}
+export interface ChannelMetrics {
+    /** Total messages sent */
+    sent: number;
+    /** Total messages failed */
+    failed: number;
+    /** Successful send rate (0-1) */
+    successRate: number;
+    /** Average send time in ms */
+    avgSendTime: number;
+    /** Total time spent sending */
+    totalSendTime: number;
+    /** Last updated timestamp */
+    updatedAt: Date;
+}
+export type NotificationEventType = "notification.sent" | "notification.failed" | "notification.queued" | "notification.bounced" | "notification.delivered";
+export interface NotificationEvent {
+    type: NotificationEventType;
+    channel: NotificationChannel;
+    messageId?: string;
+    recipient?: string;
+    timestamp: Date;
+    data?: Record<string, unknown>;
+}
+export interface NotificationValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface StandardSchema<T = unknown> {
+    "~standard": {
+        version: number;
+        types?: {
+            input: unknown;
+            output: T;
+        };
+        validate: (value: unknown) => Promise<{
+            issues?: Array<{
+                message: string;
+                path?: Array<PropertyKey | {
+                    key: PropertyKey;
+                }>;
+            }>;
+        }>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/notification/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/notification/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC5B,OAAO,GACP,KAAK,GACL,UAAU,GACV,MAAM,GACN,MAAM,CAAC;AAEV;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,yBAAyB;IACzB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAID,MAAM,WAAW,cAAc;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GACxB,MAAM,GACN,cAAc,GACd,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,CAAC;AAE/B,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kBAAkB,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAC;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAa,SAAQ,mBAAmB;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,EAAE,CAAC,EAAE,eAAe,CAAC;IACrB,GAAG,CAAC,EAAE,eAAe,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACrC,WAAW,CAAC,EAAE,IAAI,CAAC;CACnB;AAID,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACtD,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,IAAI,CAAC;CACnB;AAID,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC3D,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAID;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAC5B,YAAY,GACZ,UAAU,GACV,eAAe,GACf,uBAAuB,CAAC;AAI3B;;;GAGG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;OAIG;IACH,KAAK,CACJ,OAAO,CAAC,EAAE,mBAAmB,GAC3B,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,IAAI,MAAM,CAClB,mBAAmB,EACnB,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAClD,CAAC;CACF;AAID;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC9B,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAEnD,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAEnC,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IAEjD;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAE9C;;OAEG;IACH,SAAS,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAErC;;OAEG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;CACvC;AAID,MAAM,WAAW,iBAAiB;IACjC,0BAA0B;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gCAAgC;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC5D,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IAC1D,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC/D,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC3D,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,aAAa,GACtB,kBAAkB,GAClB,gBAAgB,GAChB,qBAAqB,GACrB,iBAAiB,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAI3B,MAAM,WAAW,yBAAyB;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,mBAAmB,EAAE,aAAa,CAAC,CAAC;IACtD,kCAAkC;IAClC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gCAAgC;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,qBAAqB,EAAE,cAAc,CAAC;CAC9D;AAID,MAAM,WAAW,cAAc;IAC9B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CAChB;AAID,MAAM,MAAM,qBAAqB,GAC9B,mBAAmB,GACnB,qBAAqB,GACrB,qBAAqB,GACrB,sBAAsB,GACtB,wBAAwB,CAAC;AAE5B,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAID,MAAM,WAAW,4BAA4B;IAC5C,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAID,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IAC1C,WAAW,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE;YACP,KAAK,EAAE,OAAO,CAAC;YACf,MAAM,EAAE,CAAC,CAAC;SACV,CAAC;QACF,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;YACrC,MAAM,CAAC,EAAE,KAAK,CAAC;gBACd,OAAO,EAAE,MAAM,CAAC;gBAChB,IAAI,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG;oBAAE,GAAG,EAAE,WAAW,CAAA;iBAAE,CAAC,CAAC;aACjD,CAAC,CAAC;SACH,CAAC,CAAC;KACH,CAAC;CACF"}

package/dist/observability/__tests__/observability.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=observability.test.d.ts.map

package/dist/observability/__tests__/observability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.test.d.ts","sourceRoot":"","sources":["../../../src/observability/__tests__/observability.test.ts"],"names":[],"mappings":""}

package/dist/observability/breadcrumbs.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Breadcrumb Collector
+ *
+ * Ring-buffer implementation for tracking recent events leading up to an error.
+ * When the buffer is full, the oldest entry is evicted to make room for new ones.
+ */
+import type { BreadcrumbEntry } from "./types";
+/**
+ * Fixed-size ring buffer for breadcrumb entries.
+ * Thread-safe for single-threaded Bun environments.
+ */
+export declare class BreadcrumbCollector {
+    private readonly _buffer;
+    private readonly _maxSize;
+    private _head;
+    private _size;
+    constructor(maxSize?: number);
+    /**
+     * Add a breadcrumb to the ring buffer.
+     * If the buffer is full, the oldest entry is evicted.
+     */
+    add(entry: BreadcrumbEntry): void;
+    /**
+     * Return all breadcrumbs in chronological order (oldest first).
+     */
+    getAll(): BreadcrumbEntry[];
+    /**
+     * Clear all breadcrumbs.
+     */
+    clear(): void;
+    /**
+     * Current number of stored breadcrumbs.
+     */
+    get size(): number;
+    /**
+     * Maximum capacity of this collector.
+     */
+    get maxSize(): number;
+}
+/**
+ * Convenience helper to build a breadcrumb entry from HTTP request info.
+ */
+export declare function httpBreadcrumb(method: string, path: string, statusCode?: number, durationMs?: number): BreadcrumbEntry;
+/**
+ * Convenience helper to build a log breadcrumb.
+ */
+export declare function logBreadcrumb(level: BreadcrumbEntry["level"], message: string, data?: Record<string, unknown>): BreadcrumbEntry;
+//# sourceMappingURL=breadcrumbs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/observability/breadcrumbs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;GAGG;AACH,qBAAa,mBAAmB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAK;gBAEN,OAAO,SAAK;IAMxB;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAYjC;;OAEG;IACH,MAAM,IAAI,eAAe,EAAE;IAQ3B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;CACD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GACjB,eAAe,CAajB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,eAAe,CAQjB"}

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/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/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/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"}