@vynelix/vynemit-core 1.0.0 → 1.0.1

package/README.md

@@ -4,14 +4,14 @@
 
 ## Features
 
-✨ **Unified Notification Model** - Single interface for in-app, push, email, SMS, and webhooks  
+**Unified Notification Model** - Single interface for in-app, push, email, SMS, and webhooks  
 **Event-Based Dispatch** - Reactive system with real-time subscriptions  
-📊 **Read/Unread Tracking** - Built-in state management  
-🎛️ **Channel Filters** - User preferences for notification channels  
-⚡ **Queue Support** - Redis, BullMQ, or in-memory queues  
-🔌 **Pluggable Architecture** - Swap storage and transport adapters  
-🎨 **Template System** - Reusable notification templates  
-🔄 **Middleware Support** - Rate limiting, deduplication, analytics  
+**Read/Unread Tracking** - Built-in state management  
+**Channel Filters** - User preferences for notification channels  
+**Queue Support** - Redis, BullMQ, or in-memory queues  
+**Pluggable Architecture** - Swap storage and transport adapters  
+**Template System** - Reusable notification templates  
+**Middleware Support** - Rate limiting, deduplication, analytics  
 **Zero Dependencies** - Lightweight core with optional adapters  
 
 ## Installation
@@ -394,7 +394,7 @@ Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
 
 ## Support
 
-- 📧 Email: support@synq.dev
-- 💬 Discord: [Join our community](https://discord.gg/synq)
-- 📖 Docs: [docs.synq.dev](https://docs.synq.dev)
-- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/synq-notifications/issues)
+- Email: [EMAIL ADDRESS](mailto:admin@vynelix.com)
+- Discord: [Join our community](https://discord.gg/synq)
+- Docs: [docs](https://vynelix.com/docs)
+- Issues: [GitHub Issues](https://github.com/IsaiahTek/vynemit/issues)

package/dist/index.d.mts

@@ -227,52 +227,260 @@ interface NotificationStats {
     byPriority: Record<NotificationPriority, number>;
 }
 
+/**
+ * The core NotificationCenter class responsible for dispatching, routing, storing,
+ * and managing the lifecycle of notifications across multiple transports.
+ */
 declare class NotificationCenter {
+    /** The configuration object for the NotificationCenter. */
     private config;
+    /** The storage adapter used for persisting notifications and preferences. */
     private storage;
+    /** A map of available transport adapters, indexed by channel type. */
     private transports;
+    /** The queue adapter used for asynchronous delivery and scheduling (optional). */
     private queue?;
+    /** A map of registered notification templates. */
     private templates;
+    /** A list of middleware functions applied to notifications during their lifecycle. */
     private middleware;
+    /** Subscribers listening for raw incoming notifications by user ID. */
     private subscribers;
+    /** Subscribers listening for notification lifecycle events (e.g., read, sent) by user ID. */
     private eventSubscribers;
+    /** Subscribers listening to unread count changes by user ID. */
     private unreadSubscribers;
+    /** Indicates whether the NotificationCenter background processes are currently running. */
     private isRunning;
+    /** The interval handle for the queue worker. */
     private workerInterval?;
+    /**
+     * Initializes a new NotificationCenter with the provided configuration.
+     * @param config - The configuration options including adapters and transports.
+     */
     constructor(config: NotificationConfig);
+    /**
+     * Dispatches a single notification based on the provided input.
+     * If a queue is configured, the delivery takes place asynchronously.
+     *
+     * @param input - The notification payload and routing instructions.
+     * @returns A promise that resolves to the processed Notification object.
+     */
     send(input: NotificationInput): Promise<Notification>;
+    /**
+     * Dispatches an array of notifications sequentially or concurrently.
+     *
+     * @param inputs - An array of notification inputs.
+     * @returns A promise resolving to an array of generated Notification objects.
+     */
     sendBatch(inputs: NotificationInput[]): Promise<Notification[]>;
+    /**
+     * Sends an identical notification to a list of users (multicast).
+     * Automatically optimizes push/sms transport delivery if transport supports bulk send.
+     *
+     * @param input - Multicast payload including the target `userIds`.
+     * @returns A promise resolving to the dispatched notifications.
+     */
     sendMulticast(input: NotificationMulticastInput): Promise<Notification[]>;
+    /**
+     * Schedules a notification to be sent at a specific future date/time.
+     * Automatically enqueues it if the queue adapter supports delayed jobs.
+     *
+     * @param input - The notification input.
+     * @param when - The Date at which the notification should be delivered.
+     * @returns A promise resolving to the generated Notification ID.
+     */
     schedule(input: NotificationInput, when: Date): Promise<string>;
+    /**
+     * Retrieves notifications intended for a specific user ID.
+     *
+     * @param userId - The target user's ID.
+     * @param filters - Optional filters like status, type, limit, offset.
+     * @returns A promise resolving to the list of matched notifications.
+     */
     getForUser(userId: string, filters?: NotificationFilters): Promise<Notification[]>;
+    /**
+     * Retrieves the current number of unread notifications for a specified user.
+     *
+     * @param userId - The target user's ID.
+     * @returns The count of unread notifications.
+     */
     getUnreadCount(userId: string): Promise<number>;
+    /**
+     * Retrieves a specific notification by its unique ID.
+     *
+     * @param id - The Notification ID.
+     * @returns The notification object if found, otherwise null.
+     */
     getById(id: string): Promise<Notification | null>;
+    /**
+     * Aggregates notification statistics for a specified user (e.g., total, unread, counts by channel).
+     *
+     * @param userId - The user's ID to fetch stats for.
+     * @returns An object containing grouped statistics.
+     */
     getStats(userId: string): Promise<NotificationStats>;
+    /**
+     * Marks a specific notification as "read" and triggers real-time updates for listeners.
+     *
+     * @param notificationId - The unique ID of the notification.
+     */
     markAsRead(notificationId: string): Promise<void>;
+    /**
+     * Marks all notifications belonging to a user as "read".
+     *
+     * @param userId - The user's ID.
+     */
     markAllAsRead(userId: string): Promise<void>;
+    /**
+     * Reverts a notification status back to "unread".
+     *
+     * @param notificationId - The unique ID of the notification.
+     */
     markAsUnread(notificationId: string): Promise<void>;
+    /**
+     * Marks all notifications belonging to a user as "unread".
+     *
+     * @param userId - The target user's ID.
+     */
     markAllAsUnread(userId: string): Promise<void>;
+    /**
+     * Deletes a specific notification from storage.
+     *
+     * @param notificationId - The Notification ID to delete.
+     */
     delete(notificationId: string): Promise<void>;
+    /**
+     * Deletes all notifications for a specific user.
+     *
+     * @param userId - The user's ID.
+     */
     deleteAll(userId: string): Promise<void>;
+    /**
+     * Retrieves the notification opt-in/opt-out routing preferences for a given user.
+     *
+     * @param userId - The user's ID.
+     * @returns A promise resolving to the user's NotificationPreferences.
+     */
     getPreferences(userId: string): Promise<NotificationPreferences>;
+    /**
+     * Updates the notification routing and delivery preferences for an user.
+     *
+     * @param userId - The user's ID.
+     * @param prefs - A partial object containing the updated preferences.
+     */
     updatePreferences(userId: string, prefs: Partial<NotificationPreferences>): Promise<void>;
+    /**
+     * Registers a notification template, mapping a named key to dynamic defaults/formatting.
+     *
+     * @param template - The NotificationTemplate definitions.
+     */
     registerTemplate(template: NotificationTemplate): void;
+    /**
+     * Looks up a registered template by its ID.
+     *
+     * @param id - The ID of the template.
+     * @returns The template object, or undefined if not found.
+     */
     getTemplate(id: string): NotificationTemplate | undefined;
+    /**
+     * Unregisters a template from the NotificationCenter.
+     *
+     * @param id - The template ID to remove.
+     */
     unregisterTemplate(id: string): void;
+    /**
+     * Enables batch notification "digests" for a specific user to prevent notification fatigue.
+     *
+     * @param userId - The user's ID.
+     * @param config - The timeframe and configuration for the user's digest.
+     */
     enableDigest(userId: string, config: DigestConfig): Promise<void>;
+    /**
+     * Disables the digest feature for a user, reverting to immediate delivery.
+     *
+     * @param userId - The target user's ID.
+     */
     disableDigest(userId: string): Promise<void>;
+    /**
+     * Fetches the current digest rules configured for a user.
+     *
+     * @param userId - The user's ID.
+     * @returns The digest configuration, or null if disabled.
+     */
     getDigestConfig(userId: string): Promise<DigestConfig | null>;
+    /**
+     * Retrieves all delivery receipts generated from transports for a specific notification.
+     * Useful to see which channels succeeded and which failed.
+     *
+     * @param notificationId - The notification's ID.
+     * @returns An array of delivery receipts.
+     */
     getDeliveryStatus(notificationId: string): Promise<DeliveryReceipt[]>;
+    /**
+     * Attempts to resend a notification for any channels that previously marked it as "failed".
+     *
+     * @param notificationId - The target notification ID.
+     * @param channel - Optional channel scope. If provided, retries only on this specific transport.
+     */
     retryFailed(notificationId: string, channel?: ChannelType): Promise<void>;
+    /**
+     * Registers a callback to be invoked whenever a notification is sent to a specific user.
+     *
+     * @param userId - The target user's ID.
+     * @param callback - Function to handle the raw notification map.
+     * @returns A cleanup function to unsubscribe from this event.
+     */
     subscribe(userId: string, callback: (notification: Notification) => void): Unsubscribe;
+    /**
+     * Registers a callback for state changes (e.g. read/unread status updates) for a user's notifications.
+     *
+     * @param userId - The target user's ID.
+     * @param callback - Lifecycle event listener.
+     * @returns A cleanup function to unsubscribe.
+     */
     subscribeToEvents(userId: string, callback: (event: NotificationEvent) => void): Unsubscribe;
+    /**
+     * Registers a listener to react to changes in the unread notification count for a user.
+     *
+     * @param userId - The user's ID.
+     * @param callback - Handlers receiving the current unread count.
+     * @returns Unsubscribe function.
+     */
     onUnreadCountChange(userId: string, callback: (count: number, userId: string) => void): Unsubscribe;
+    /**
+     * Injects a middleware interceptor to apply custom logic before or after notifications are sent.
+     *
+     * @param middleware - The middleware object conforming to `NotificationMiddleware`.
+     */
     use(middleware: NotificationMiddleware): void;
+    /**
+     * Removes a previously configured middleware globally.
+     *
+     * @param name - The name identifier of the middleware to remove.
+     */
     removeMiddleware(name: string): void;
+    /**
+     * Boots up the NotificationCenter, initializing storage, queues, and worker loops if enabled.
+     */
     start(): Promise<void>;
+    /**
+     * Gracefully shuts down the NotificationCenter, terminating background queues and workers.
+     */
     stop(): Promise<void>;
+    /**
+     * Pings all registered transports to report on their current health and active status.
+     *
+     * @returns A map representing the readiness boolean state of each registered transport.
+     */
     healthCheck(): Promise<Record<string, boolean>>;
+    /**
+     * Applies metadata, templates, and defaults to construct the internal Notification shape.
+     */
     private buildNotification;
+    /**
+     * Internal mechanism sending payload out across desired transports without queue delay.
+     */
     private sendNow;
     private castNotification;
     private startWorker;

package/dist/index.d.ts

@@ -227,52 +227,260 @@ interface NotificationStats {
     byPriority: Record<NotificationPriority, number>;
 }
 
+/**
+ * The core NotificationCenter class responsible for dispatching, routing, storing,
+ * and managing the lifecycle of notifications across multiple transports.
+ */
 declare class NotificationCenter {
+    /** The configuration object for the NotificationCenter. */
     private config;
+    /** The storage adapter used for persisting notifications and preferences. */
     private storage;
+    /** A map of available transport adapters, indexed by channel type. */
     private transports;
+    /** The queue adapter used for asynchronous delivery and scheduling (optional). */
     private queue?;
+    /** A map of registered notification templates. */
     private templates;
+    /** A list of middleware functions applied to notifications during their lifecycle. */
     private middleware;
+    /** Subscribers listening for raw incoming notifications by user ID. */
     private subscribers;
+    /** Subscribers listening for notification lifecycle events (e.g., read, sent) by user ID. */
     private eventSubscribers;
+    /** Subscribers listening to unread count changes by user ID. */
     private unreadSubscribers;
+    /** Indicates whether the NotificationCenter background processes are currently running. */
     private isRunning;
+    /** The interval handle for the queue worker. */
     private workerInterval?;
+    /**
+     * Initializes a new NotificationCenter with the provided configuration.
+     * @param config - The configuration options including adapters and transports.
+     */
     constructor(config: NotificationConfig);
+    /**
+     * Dispatches a single notification based on the provided input.
+     * If a queue is configured, the delivery takes place asynchronously.
+     *
+     * @param input - The notification payload and routing instructions.
+     * @returns A promise that resolves to the processed Notification object.
+     */
     send(input: NotificationInput): Promise<Notification>;
+    /**
+     * Dispatches an array of notifications sequentially or concurrently.
+     *
+     * @param inputs - An array of notification inputs.
+     * @returns A promise resolving to an array of generated Notification objects.
+     */
     sendBatch(inputs: NotificationInput[]): Promise<Notification[]>;
+    /**
+     * Sends an identical notification to a list of users (multicast).
+     * Automatically optimizes push/sms transport delivery if transport supports bulk send.
+     *
+     * @param input - Multicast payload including the target `userIds`.
+     * @returns A promise resolving to the dispatched notifications.
+     */
     sendMulticast(input: NotificationMulticastInput): Promise<Notification[]>;
+    /**
+     * Schedules a notification to be sent at a specific future date/time.
+     * Automatically enqueues it if the queue adapter supports delayed jobs.
+     *
+     * @param input - The notification input.
+     * @param when - The Date at which the notification should be delivered.
+     * @returns A promise resolving to the generated Notification ID.
+     */
     schedule(input: NotificationInput, when: Date): Promise<string>;
+    /**
+     * Retrieves notifications intended for a specific user ID.
+     *
+     * @param userId - The target user's ID.
+     * @param filters - Optional filters like status, type, limit, offset.
+     * @returns A promise resolving to the list of matched notifications.
+     */
     getForUser(userId: string, filters?: NotificationFilters): Promise<Notification[]>;
+    /**
+     * Retrieves the current number of unread notifications for a specified user.
+     *
+     * @param userId - The target user's ID.
+     * @returns The count of unread notifications.
+     */
     getUnreadCount(userId: string): Promise<number>;
+    /**
+     * Retrieves a specific notification by its unique ID.
+     *
+     * @param id - The Notification ID.
+     * @returns The notification object if found, otherwise null.
+     */
     getById(id: string): Promise<Notification | null>;
+    /**
+     * Aggregates notification statistics for a specified user (e.g., total, unread, counts by channel).
+     *
+     * @param userId - The user's ID to fetch stats for.
+     * @returns An object containing grouped statistics.
+     */
     getStats(userId: string): Promise<NotificationStats>;
+    /**
+     * Marks a specific notification as "read" and triggers real-time updates for listeners.
+     *
+     * @param notificationId - The unique ID of the notification.
+     */
     markAsRead(notificationId: string): Promise<void>;
+    /**
+     * Marks all notifications belonging to a user as "read".
+     *
+     * @param userId - The user's ID.
+     */
     markAllAsRead(userId: string): Promise<void>;
+    /**
+     * Reverts a notification status back to "unread".
+     *
+     * @param notificationId - The unique ID of the notification.
+     */
     markAsUnread(notificationId: string): Promise<void>;
+    /**
+     * Marks all notifications belonging to a user as "unread".
+     *
+     * @param userId - The target user's ID.
+     */
     markAllAsUnread(userId: string): Promise<void>;
+    /**
+     * Deletes a specific notification from storage.
+     *
+     * @param notificationId - The Notification ID to delete.
+     */
     delete(notificationId: string): Promise<void>;
+    /**
+     * Deletes all notifications for a specific user.
+     *
+     * @param userId - The user's ID.
+     */
     deleteAll(userId: string): Promise<void>;
+    /**
+     * Retrieves the notification opt-in/opt-out routing preferences for a given user.
+     *
+     * @param userId - The user's ID.
+     * @returns A promise resolving to the user's NotificationPreferences.
+     */
     getPreferences(userId: string): Promise<NotificationPreferences>;
+    /**
+     * Updates the notification routing and delivery preferences for an user.
+     *
+     * @param userId - The user's ID.
+     * @param prefs - A partial object containing the updated preferences.
+     */
     updatePreferences(userId: string, prefs: Partial<NotificationPreferences>): Promise<void>;
+    /**
+     * Registers a notification template, mapping a named key to dynamic defaults/formatting.
+     *
+     * @param template - The NotificationTemplate definitions.
+     */
     registerTemplate(template: NotificationTemplate): void;
+    /**
+     * Looks up a registered template by its ID.
+     *
+     * @param id - The ID of the template.
+     * @returns The template object, or undefined if not found.
+     */
     getTemplate(id: string): NotificationTemplate | undefined;
+    /**
+     * Unregisters a template from the NotificationCenter.
+     *
+     * @param id - The template ID to remove.
+     */
     unregisterTemplate(id: string): void;
+    /**
+     * Enables batch notification "digests" for a specific user to prevent notification fatigue.
+     *
+     * @param userId - The user's ID.
+     * @param config - The timeframe and configuration for the user's digest.
+     */
     enableDigest(userId: string, config: DigestConfig): Promise<void>;
+    /**
+     * Disables the digest feature for a user, reverting to immediate delivery.
+     *
+     * @param userId - The target user's ID.
+     */
     disableDigest(userId: string): Promise<void>;
+    /**
+     * Fetches the current digest rules configured for a user.
+     *
+     * @param userId - The user's ID.
+     * @returns The digest configuration, or null if disabled.
+     */
     getDigestConfig(userId: string): Promise<DigestConfig | null>;
+    /**
+     * Retrieves all delivery receipts generated from transports for a specific notification.
+     * Useful to see which channels succeeded and which failed.
+     *
+     * @param notificationId - The notification's ID.
+     * @returns An array of delivery receipts.
+     */
     getDeliveryStatus(notificationId: string): Promise<DeliveryReceipt[]>;
+    /**
+     * Attempts to resend a notification for any channels that previously marked it as "failed".
+     *
+     * @param notificationId - The target notification ID.
+     * @param channel - Optional channel scope. If provided, retries only on this specific transport.
+     */
     retryFailed(notificationId: string, channel?: ChannelType): Promise<void>;
+    /**
+     * Registers a callback to be invoked whenever a notification is sent to a specific user.
+     *
+     * @param userId - The target user's ID.
+     * @param callback - Function to handle the raw notification map.
+     * @returns A cleanup function to unsubscribe from this event.
+     */
     subscribe(userId: string, callback: (notification: Notification) => void): Unsubscribe;
+    /**
+     * Registers a callback for state changes (e.g. read/unread status updates) for a user's notifications.
+     *
+     * @param userId - The target user's ID.
+     * @param callback - Lifecycle event listener.
+     * @returns A cleanup function to unsubscribe.
+     */
     subscribeToEvents(userId: string, callback: (event: NotificationEvent) => void): Unsubscribe;
+    /**
+     * Registers a listener to react to changes in the unread notification count for a user.
+     *
+     * @param userId - The user's ID.
+     * @param callback - Handlers receiving the current unread count.
+     * @returns Unsubscribe function.
+     */
     onUnreadCountChange(userId: string, callback: (count: number, userId: string) => void): Unsubscribe;
+    /**
+     * Injects a middleware interceptor to apply custom logic before or after notifications are sent.
+     *
+     * @param middleware - The middleware object conforming to `NotificationMiddleware`.
+     */
     use(middleware: NotificationMiddleware): void;
+    /**
+     * Removes a previously configured middleware globally.
+     *
+     * @param name - The name identifier of the middleware to remove.
+     */
     removeMiddleware(name: string): void;
+    /**
+     * Boots up the NotificationCenter, initializing storage, queues, and worker loops if enabled.
+     */
     start(): Promise<void>;
+    /**
+     * Gracefully shuts down the NotificationCenter, terminating background queues and workers.
+     */
     stop(): Promise<void>;
+    /**
+     * Pings all registered transports to report on their current health and active status.
+     *
+     * @returns A map representing the readiness boolean state of each registered transport.
+     */
     healthCheck(): Promise<Record<string, boolean>>;
+    /**
+     * Applies metadata, templates, and defaults to construct the internal Notification shape.
+     */
     private buildNotification;
+    /**
+     * Internal mechanism sending payload out across desired transports without queue delay.
+     */
     private sendNow;
     private castNotification;
     private startWorker;