@awesome-lang-auth/node 1.10.1

package/dist/tools/auth-tools.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthTools = void 0;
+const crypto_1 = require("crypto");
+const sse_manager_1 = require("./sse-manager");
+const webhook_sender_1 = require("./webhook-sender");
+const sse_notify_decorator_1 = require("./sse-notify.decorator");
+const notification_service_1 = require("../services/notification.service");
+/**
+ * The main tools module.
+ *
+ * Provides a unified API for telemetry tracking, real-time SSE notifications,
+ * and outgoing webhooks.  All capabilities are optional and have zero overhead
+ * when disabled.
+ *
+ * ```ts
+ * import { AuthTools, AuthEventBus } from '@awesome-lang-auth/node';
+ *
+ * const bus = new AuthEventBus();
+ * const tools = new AuthTools(bus, {
+ *   telemetryStore: myStore,
+ *   webhookStore: myWebhookStore,
+ *   sse: true,
+ * });
+ *
+ * // Track an event programmatically
+ * await tools.track('identity.auth.login.success', { user }, { userId: user.id });
+ *
+ * // Notify a topic over SSE
+ * await tools.notify('user:123', { message: 'Welcome!' });
+ * ```
+ */
+class AuthTools {
+    constructor(eventBus, options = {}) {
+        this.eventBus = eventBus;
+        this.telemetryStore = options.telemetryStore;
+        this.webhookStore = options.webhookStore;
+        this.webhookSender = new webhook_sender_1.WebhookSender();
+        this.webhookVersion = options.webhookVersion ?? '1';
+        this.sseManager = options.sse ? new sse_manager_1.SseManager(options.sseOptions) : null;
+        this.sseDistributor = options.sseDistributor;
+        this.userStore = options.userStore;
+        if (options.sse && options.sseDistributor) {
+            process.stderr.write('[awesome-node-auth] WARN: AuthTools received both sse=true and sseDistributor; notify() will use the custom distributor.\n');
+        }
+        if (options.emailConfig || options.smsConfig) {
+            this.notificationService = new notification_service_1.NotificationService({
+                email: options.emailConfig,
+                sms: options.smsConfig,
+            });
+        }
+        if (this.sseManager) {
+            sse_notify_decorator_1.SseNotifyRegistry.setManager(this.sseManager);
+        }
+    }
+    /**
+     * Track an event: persist it (optional), emit it on the event bus, broadcast
+     * it to SSE subscribers and fire matching outgoing webhooks.
+     *
+     * @param eventName  Standardised event name (see `AuthEventNames`).
+     * @param data       Arbitrary event data.
+     * @param options    Metadata (userId, tenantId, …).
+     */
+    async track(eventName, data, options = {}) {
+        const id = (0, crypto_1.randomUUID)();
+        const timestamp = new Date().toISOString();
+        const telemetryEvent = {
+            id,
+            event: eventName,
+            timestamp,
+            data,
+            userId: options.userId,
+            tenantId: options.tenantId,
+            sessionId: options.sessionId,
+            correlationId: options.correlationId,
+            ip: options.ip,
+            userAgent: options.userAgent,
+        };
+        // 1. Persist
+        if (this.telemetryStore) {
+            await this.telemetryStore.save(telemetryEvent).catch(() => { });
+        }
+        // 2. Emit on the event bus
+        const busPayload = {
+            data,
+            userId: options.userId,
+            tenantId: options.tenantId,
+            sessionId: options.sessionId,
+            correlationId: options.correlationId,
+            ip: options.ip,
+            userAgent: options.userAgent,
+        };
+        this.eventBus.publish(eventName, busPayload);
+        // 3. SSE broadcast (topic per tenant or global)
+        if (this.sseManager) {
+            const topics = this.resolveTopics(eventName, options);
+            const streamEvent = {
+                id,
+                timestamp,
+                type: eventName,
+                data: telemetryEvent,
+                userId: options.userId,
+                tenantId: options.tenantId,
+            };
+            for (const topic of topics) {
+                this.sseManager.broadcast(topic, streamEvent);
+            }
+        }
+        // 4. Outgoing webhooks
+        if (this.webhookStore) {
+            const configs = await this.webhookStore.findByEvent(eventName, options.tenantId).catch(() => []);
+            const webhookEvent = {
+                event: eventName,
+                version: this.webhookVersion,
+                timestamp,
+                data: data ?? null,
+                metadata: {
+                    userId: options.userId,
+                    tenantId: options.tenantId,
+                    sessionId: options.sessionId,
+                    correlationId: options.correlationId,
+                },
+            };
+            for (const config of configs) {
+                // Fire-and-forget; don't let webhook failures block the caller
+                this.webhookSender.send(config, webhookEvent).catch(() => { });
+            }
+        }
+    }
+    /**
+     * Send a notification to one or more delivery channels.
+     *
+     * By default (or when `channels` is `['sse']`) the behaviour is identical to
+     * the original synchronous broadcast.  Pass additional channels to also
+     * deliver the notification via email and/or SMS.
+     *
+     * When `'email'` or `'sms'` is included the method becomes asynchronous and
+     * requires:
+     *   - `userStore` — to look up the user's contact details by `options.userId`.
+     *   - `emailConfig` / `smsConfig` — transport configuration in
+     *     {@link AuthToolsOptions}.
+     *
+     * Channel failures are best-effort and do not reject the returned Promise.
+     *
+     * @param target   Target SSE topic (e.g. `'user:123'`, `'tenant:acme'`).
+     * @param data     Payload to deliver.
+     * @param options  Channels, type, tenantId, userId, metadata, etc.
+     *
+     * @since 1.8.0 (async + multi-channel)
+     */
+    async notify(target, data, options = {}) {
+        const channels = options.channels ?? ['sse'];
+        // ── 1. SSE ──────────────────────────────────────────────────────────────
+        if (channels.includes('sse')) {
+            const streamEvent = {
+                type: options.type ?? 'notification',
+                data,
+                tenantId: options.tenantId,
+                userId: options.userId,
+                metadata: options.metadata,
+            };
+            if (this.sseDistributor) {
+                // Publish a complete StreamEvent, as SseManager.broadcast() does:
+                // receivers (SseManager included) deduplicate on `id`.
+                const fullEvent = {
+                    id: (0, crypto_1.randomUUID)(),
+                    timestamp: new Date().toISOString(),
+                    topic: target,
+                    ...streamEvent,
+                };
+                this.sseDistributor.publish(target, fullEvent).catch(() => { });
+            }
+            else if (this.sseManager) {
+                this.sseManager.broadcast(target, streamEvent);
+            }
+        }
+        // ── 2. Email / SMS (only when userId is provided and userStore is set) ───
+        if ((channels.includes('email') || channels.includes('sms')) && options.userId && this.userStore) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            let user = null;
+            try {
+                user = await this.userStore.findById(options.userId);
+            }
+            catch {
+                user = null;
+            }
+            if (user) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const u = user;
+                // ── 2a. Email ─────────────────────────────────────────────────────
+                if (channels.includes('email') && u.email && this.notificationService?.hasEmail) {
+                    const subject = options.emailSubject ?? (options.type ? String(options.type) : 'Notification');
+                    const body = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+                    this.notificationService.sendEmail({
+                        to: u.email,
+                        subject,
+                        html: `<p>${body.replace(/\n/g, '<br>')}</p>`,
+                        text: body,
+                    }).catch(() => { });
+                }
+                // ── 2b. SMS ───────────────────────────────────────────────────────
+                if (channels.includes('sms') && u.phoneNumber && this.notificationService?.hasSms) {
+                    const message = options.smsMessage ?? (typeof data === 'string' ? data : JSON.stringify(data));
+                    this.notificationService.sendSms({
+                        to: u.phoneNumber,
+                        message,
+                    }).catch(() => { });
+                }
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Resolve the SSE topics an event should be broadcast to.
+     * Always includes `'global'`; additionally adds tenant and user topics when
+     * the corresponding IDs are present.
+     */
+    resolveTopics(eventName, options) {
+        const topics = ['global'];
+        if (options.tenantId)
+            topics.push(`tenant:${options.tenantId}`);
+        if (options.userId)
+            topics.push(`user:${options.userId}`);
+        if (options.sessionId)
+            topics.push(`session:${options.sessionId}`);
+        return topics;
+    }
+}
+exports.AuthTools = AuthTools;
+//# sourceMappingURL=auth-tools.js.map

package/dist/tools/auth-tools.js.map

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

package/dist/tools/sse-manager.d.ts

@@ -0,0 +1,118 @@
+import { Response } from 'express';
+import { ISseDistributor } from '../interfaces/sse-distributor.interface';
+/**
+ * A single real-time SSE event delivered to subscribers.
+ */
+export interface StreamEvent<T = unknown> {
+    /** Unique event identifier (auto-generated if not provided). */
+    id: string;
+    /** Event type / name. */
+    type: string;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Topic / channel this event was published to. */
+    topic: string;
+    /** Arbitrary event data. */
+    data: T;
+    /** User ID (optional). */
+    userId?: string;
+    /** Tenant ID (optional). */
+    tenantId?: string;
+    /** Optional extra metadata. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for the {@link SseManager}.
+ */
+export interface SseManagerOptions {
+    /**
+     * Interval in milliseconds between heartbeat comments (`:heartbeat`).
+     * Set to `0` to disable heartbeats.
+     * @default 30000
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Optional distributor for cross-instance event synchronization.
+     * Required for horizontal scaling.
+     */
+    distributor?: ISseDistributor;
+    /**
+     * When `true` (default), events with the same ID are deduplicated per connection.
+     * This prevents clients from receiving the same event multiple times when
+     * subscribed to multiple matching topics.
+     * @default true
+     */
+    deduplicate?: boolean;
+}
+/**
+ * Manages Server-Sent Events connections.
+ *
+ * Tracks open HTTP streams and broadcasts `StreamEvent` objects to all
+ * subscribers matching a given topic.  Topics follow the hierarchical
+ * channel scheme:
+ *
+ * ```
+ * global
+ * tenant:{tenantId}
+ * tenant:{tenantId}:role:{role}
+ * tenant:{tenantId}:group:{groupId}
+ * user:{userId}
+ * session:{sessionId}
+ * custom:{namespace}
+ * ```
+ *
+ * The server controls which topics a connection is allowed to subscribe to —
+ * clients cannot self-declare channels.
+ */
+export declare class SseManager {
+    private connections;
+    private readonly distributor?;
+    /**
+     * Interval in milliseconds between heartbeat comments (`:heartbeat`).
+     * Set to `0` to disable heartbeats.
+     * @default 30000
+     */
+    readonly heartbeatIntervalMs: number;
+    /**
+     * Whether to deduplicate events by ID per connection.
+     */
+    readonly deduplicate: boolean;
+    constructor(options?: SseManagerOptions);
+    /**
+     * Attach an SSE response to a new connection and register its authorised
+     * topics.
+     *
+     * @param res     The HTTP response to write events to.
+     * @param topics  Topics this connection may receive (enforced server-side).
+     * @param meta    Optional user / tenant context.
+     * @returns The generated connection ID.
+     */
+    connect(res: Response, topics: string[], meta?: {
+        userId?: string;
+        tenantId?: string;
+    }): string;
+    /**
+     * Broadcast a `StreamEvent` to all connections subscribed to `topic`.
+     * If a distributor is configured, the event is published to it for
+     * cross-instance delivery.
+     */
+    broadcast<T = unknown>(topic: string, event: Omit<StreamEvent<T>, 'id' | 'timestamp' | 'topic'> & {
+        id?: string;
+        timestamp?: string;
+    }): void;
+    /**
+     * Broadcast an event to ONLY the local connections.
+     * This is typically called by the distributor's subscription callback.
+     */
+    private broadcastLocal;
+    /**
+     * Close and remove a connection by its ID.
+     */
+    disconnect(connectionId: string): void;
+    /**
+     * Number of currently open connections.
+     */
+    get connectionCount(): number;
+    private write;
+}
+//# sourceMappingURL=sse-manager.d.ts.map

package/dist/tools/sse-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-manager.d.ts","sourceRoot":"","sources":["../../src/tools/sse-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,IAAI,EAAE,CAAC,CAAC;IACR,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAiBD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;IAE9B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAkB;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAElB,OAAO,CAAC,EAAE,iBAAiB;IAYvC;;;;;;;;OAQG;IACH,OAAO,CACL,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,MAAM,EAAE,EAChB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,MAAM;IA6CT;;;;OAIG;IACH,SAAS,CAAC,CAAC,GAAG,OAAO,EACnB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,GAAG,WAAW,GAAG,OAAO,CAAC,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9F,IAAI;IAkBP;;;OAGG;IACH,OAAO,CAAC,cAAc;IAmBtB;;OAEG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAYtC;;OAEG;IACH,IAAI,eAAe,IAAI,MAAM,CAE5B;IAMD,OAAO,CAAC,KAAK;CAKd"}

package/dist/tools/sse-manager.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseManager = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Manages Server-Sent Events connections.
+ *
+ * Tracks open HTTP streams and broadcasts `StreamEvent` objects to all
+ * subscribers matching a given topic.  Topics follow the hierarchical
+ * channel scheme:
+ *
+ * ```
+ * global
+ * tenant:{tenantId}
+ * tenant:{tenantId}:role:{role}
+ * tenant:{tenantId}:group:{groupId}
+ * user:{userId}
+ * session:{sessionId}
+ * custom:{namespace}
+ * ```
+ *
+ * The server controls which topics a connection is allowed to subscribe to —
+ * clients cannot self-declare channels.
+ */
+class SseManager {
+    constructor(options) {
+        this.connections = new Map();
+        this.heartbeatIntervalMs = options?.heartbeatIntervalMs ?? 30000;
+        this.deduplicate = options?.deduplicate !== false;
+        this.distributor = options?.distributor;
+        if (this.distributor) {
+            this.distributor.subscribe((topic, event) => {
+                this.broadcastLocal(topic, event);
+            });
+        }
+    }
+    /**
+     * Attach an SSE response to a new connection and register its authorised
+     * topics.
+     *
+     * @param res     The HTTP response to write events to.
+     * @param topics  Topics this connection may receive (enforced server-side).
+     * @param meta    Optional user / tenant context.
+     * @returns The generated connection ID.
+     */
+    connect(res, topics, meta) {
+        const id = (0, crypto_1.randomUUID)();
+        // SSE headers
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no');
+        res.flushHeaders?.();
+        // Send initial connection event
+        this.write(res, {
+            id: (0, crypto_1.randomUUID)(),
+            type: 'connected',
+            timestamp: new Date().toISOString(),
+            topic: 'meta',
+            data: { connectionId: id, topics },
+        });
+        const conn = {
+            id,
+            res,
+            topics: new Set(topics),
+            userId: meta?.userId,
+            tenantId: meta?.tenantId,
+        };
+        if (this.heartbeatIntervalMs > 0) {
+            conn.heartbeatTimer = setInterval(() => {
+                try {
+                    res.write(': heartbeat\n\n');
+                }
+                catch {
+                    this.disconnect(id);
+                }
+            }, this.heartbeatIntervalMs);
+        }
+        this.connections.set(id, conn);
+        // Clean up when the client disconnects
+        res.on('close', () => this.disconnect(id));
+        return id;
+    }
+    /**
+     * Broadcast a `StreamEvent` to all connections subscribed to `topic`.
+     * If a distributor is configured, the event is published to it for
+     * cross-instance delivery.
+     */
+    broadcast(topic, event) {
+        const full = {
+            id: event.id ?? (0, crypto_1.randomUUID)(),
+            timestamp: event.timestamp ?? new Date().toISOString(),
+            topic,
+            ...event,
+        };
+        if (this.distributor) {
+            this.distributor.publish(topic, full).catch(() => {
+                // Fallback to local broadcast if distribution fails
+                this.broadcastLocal(topic, full);
+            });
+        }
+        else {
+            this.broadcastLocal(topic, full);
+        }
+    }
+    /**
+     * Broadcast an event to ONLY the local connections.
+     * This is typically called by the distributor's subscription callback.
+     */
+    broadcastLocal(topic, event) {
+        for (const conn of this.connections.values()) {
+            if (!conn.topics.has(topic))
+                continue;
+            // Tenant isolation: if the event has a tenantId the connection must
+            // belong to the same tenant (unless it is a global connection with no
+            // tenantId set).
+            if (event.tenantId && conn.tenantId && conn.tenantId !== event.tenantId)
+                continue;
+            try {
+                if (this.deduplicate && event.id === conn.lastEventId)
+                    continue;
+                conn.lastEventId = event.id;
+                this.write(conn.res, event);
+            }
+            catch {
+                this.disconnect(conn.id);
+            }
+        }
+    }
+    /**
+     * Close and remove a connection by its ID.
+     */
+    disconnect(connectionId) {
+        const conn = this.connections.get(connectionId);
+        if (!conn)
+            return;
+        if (conn.heartbeatTimer)
+            clearInterval(conn.heartbeatTimer);
+        this.connections.delete(connectionId);
+        try {
+            conn.res.end();
+        }
+        catch {
+            // already closed
+        }
+    }
+    /**
+     * Number of currently open connections.
+     */
+    get connectionCount() {
+        return this.connections.size;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    write(res, event) {
+        res.write(`id: ${event.id}\n`);
+        res.write(`event: ${event.type}\n`);
+        res.write(`data: ${JSON.stringify({ ...event, data: undefined, rawData: event.data })}\n\n`);
+    }
+}
+exports.SseManager = SseManager;
+//# sourceMappingURL=sse-manager.js.map

package/dist/tools/sse-manager.js.map

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

package/dist/tools/sse-notify.decorator.d.ts

@@ -0,0 +1,74 @@
+import { SseManager } from './sse-manager';
+/**
+ * Options for the `@sseNotify` decorator.
+ */
+export interface SseNotifyOptions {
+    /**
+     * The SSE topic to broadcast to.  Can be a static string or a function
+     * that resolves the topic based on method arguments and execution result.
+     */
+    topic: string | ((args: any[], result: any) => string);
+    /**
+     * The event type name.  Defaults to `'notification'`.
+     */
+    event?: string;
+    /**
+     * Optional payload transformer.  By default, the method's return value is sent.
+     */
+    payload?: (result: any, args: any[]) => any;
+    /**
+     * Optional tenant ID resolver.
+     */
+    tenantId?: (result: any, args: any[]) => string | undefined;
+    /**
+     * Optional user ID resolver.
+     */
+    userId?: (result: any, args: any[]) => string | undefined;
+}
+/**
+ * Global registry and dispatcher for decorated SSE notifications.
+ */
+export declare class SseNotifyRegistry {
+    private static manager;
+    /**
+     * Set the active SSE manager used for broadcasts.  Should be called
+     * during application initialization.
+     */
+    static setManager(manager: SseManager | null): void;
+    /**
+     * Perform a broadcast if a manager is registered.
+     */
+    static notify(topic: string, event: {
+        type: string;
+        data: any;
+        tenantId?: string;
+        userId?: string;
+    }): void;
+    /**
+     * Internal helper to execute notification logic.
+     * Can be called manually to bypass decorators.
+     */
+    static executeNotify(options: SseNotifyOptions, args: any[], result: any): Promise<void>;
+}
+/**
+ * Method decorator that automatically triggers an SSE broadcast after
+ * successful execution.
+ *
+ * Uses the **TC39 Stage 3** decorator syntax (TypeScript 5.x+).
+ * For legacy environments, use manual notification via `SseNotifyRegistry.notify()`.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   @sseNotify({
+ *     topic: (_args, user) => `user:${user.id}`,
+ *     event: 'user.updated',
+ *   })
+ *   async updateProfile(userId: string, data: any) {
+ *     return await db.users.update(userId, data);
+ *   }
+ * }
+ * ```
+ */
+export declare function sseNotify(options: SseNotifyOptions): <This, Args extends unknown[], Return>(target: (this: This, ...args: Args) => Promise<Return> | Return, _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Promise<Return> | Return>) => (this: This, ...args: Args) => Promise<Return>;
+//# sourceMappingURL=sse-notify.decorator.d.ts.map

package/dist/tools/sse-notify.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-notify.decorator.d.ts","sourceRoot":"","sources":["../../src/tools/sse-notify.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;IAEvD;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;IAE5D;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;CAC7D;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,MAAM,CAAC,OAAO,CAA2B;IAEjD;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI;IAInD;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,GAAG,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAK1G;;;OAGG;WACU,aAAa,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;CAkBjG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,IAC9B,IAAI,EAAE,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACjD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EAC/D,UAAU,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,MAE7E,MAAM,IAAI,EAAE,GAAG,MAAM,IAAI,KAAG,OAAO,CAAC,MAAM,CAAC,CAMzE"}