@gravito/flare 2.0.0 → 3.0.1

package/dist/index.cjs

@@ -369,7 +369,7 @@ var OrbitFlare = class _OrbitFlare {
   async install(core) {
     const manager = new NotificationManager(core);
     if (this.options.enableMail) {
-      const mail = core.services.get("mail");
+      const mail = core.container.make("mail");
       if (mail) {
         manager.channel("mail", new MailChannel(mail));
       } else {
@@ -377,7 +377,7 @@ var OrbitFlare = class _OrbitFlare {
       }
     }
     if (this.options.enableDatabase) {
-      const db = core.services.get("db");
+      const db = core.container.make("db");
       if (db) {
         manager.channel("database", new DatabaseChannel(db));
       } else {
@@ -385,7 +385,7 @@ var OrbitFlare = class _OrbitFlare {
       }
     }
     if (this.options.enableBroadcast) {
-      const broadcast = core.services.get("broadcast");
+      const broadcast = core.container.make("broadcast");
       if (broadcast) {
         manager.channel("broadcast", new BroadcastChannel(broadcast));
       } else {
@@ -408,8 +408,8 @@ var OrbitFlare = class _OrbitFlare {
         core.logger.warn("[OrbitFlare] SMS configuration not found, sms channel disabled");
       }
     }
-    core.services.set("notifications", manager);
-    const queue = core.services.get("queue");
+    core.container.instance("notifications", manager);
+    const queue = core.container.make("queue");
     if (queue) {
       manager.setQueueManager({
         push: async (job, queueName, connection, delay) => {

package/dist/index.d.cts

@@ -6,69 +6,95 @@ import { PlanetCore, GravitoOrbit } from '@gravito/core';
 
 /**
  * Notification channel interface.
+ * @public
  */
 interface NotificationChannel {
     /**
-     * Send a notification.
-     * @param notification - Notification instance
-     * @param notifiable - Recipient
+     * Send a notification through the specified channel.
+     *
+     * @param notification - The notification instance containing data.
+     * @param notifiable - The recipient of the notification.
      */
     send(notification: Notification, notifiable: Notifiable): Promise<void>;
 }
 /**
- * Notifiable (notification recipient) interface.
+ * Interface for recipients that can receive notifications.
+ * @public
  */
 interface Notifiable {
     /**
-     * Recipient identifier (usually an ID).
+     * Unique identifier for the recipient (e.g., User ID).
      */
     getNotifiableId(): string | number;
     /**
-     * Recipient type (optional, for polymorphic relations).
+     * Optional recipient type (useful for polymorphic notifications).
      */
     getNotifiableType?(): string;
     /**
-     * Preferred channels (optional).
+     * Optional list of preferred channels for this specific recipient.
      */
     preferredNotificationChannels?(): string[];
 }
 /**
- * Mail message payload.
+ * Payload for email notifications.
+ * @public
  */
 interface MailMessage {
+    /** Email subject line */
     subject: string;
+    /** View template path */
     view?: string;
+    /** Data to pass to the view template */
     data?: Record<string, unknown>;
+    /** Inline HTML content */
     html?: string;
+    /** Plain text content */
     text?: string;
+    /** Sender address */
     from?: string;
+    /** Target recipient(s) */
     to?: string | string[];
+    /** Carbon copy recipient(s) */
     cc?: string | string[];
+    /** Blind carbon copy recipient(s) */
     bcc?: string | string[];
 }
 /**
- * Database notification payload.
+ * Payload for database-stored notifications.
+ * @public
  */
 interface DatabaseNotification {
+    /** Type identifier for the notification */
     type: string;
+    /** JSON-serializable data payload */
     data: Record<string, unknown>;
+    /** Timestamp when the notification was marked as read */
     readAt?: Date | null;
 }
 /**
- * Broadcast notification payload.
+ * Payload for real-time broadcast notifications.
+ * @public
  */
 interface BroadcastNotification {
+    /** Event/Type identifier for the broadcast */
     type: string;
+    /** Data to be broadcasted to subscribers */
     data: Record<string, unknown>;
 }
 /**
- * Slack message payload.
+ * Payload for Slack channel notifications.
+ * @public
  */
 interface SlackMessage {
+    /** Main message text */
     text: string;
+    /** Target Slack channel */
     channel?: string;
+    /** Custom bot username */
     username?: string;
+    /** Icon emoji for the bot */
     iconEmoji?: string;
+    /** Array of Slack attachments for rich formatting */
     attachments?: Array<{
         color?: string;
         title?: string;
@@ -81,56 +107,42 @@ interface SlackMessage {
     }>;
 }
 /**
- * SMS message payload.
+ * Payload for SMS notifications.
+ * @public
  */
 interface SmsMessage {
+    /** Recipient phone number */
     to: string;
+    /** Message content */
     message: string;
+    /** Sender ID or phone number */
     from?: string;
 }
 
 /**
  * Marker interface for notifications that should be queued.
+ *
+ * Implementing this interface will cause the notification to be dispatched
+ * to a background queue automatically by the `NotificationManager`.
+ *
+ * @public
+ * @since 3.0.0
  */
 interface ShouldQueue {
-    /**
-     * Queue name (optional).
-     */
+    /** The name of the queue to push this notification to. */
     queue?: string | undefined;
+    /** The connection name (e.g., 'redis', 'database') to use for queuing. */
     connection?: string | undefined;
+    /** Delay in seconds before the notification is delivered. */
     delay?: number | undefined;
 }
 /**
  * Base Notification class.
  *
- * All notifications should extend this class.
- * Notifications can be delivered via multiple channels (mail, database, broadcast, Slack, SMS, etc.).
+ * All application notifications should extend this class.
  *
- * @example
- * ```typescript
- * class InvoicePaid extends Notification {
- *   constructor(private invoice: Invoice) {
- *     super()
- *   }
- *
- *   via(user: User): string[] {
- *     return ['mail', 'database']
- *   }
- *
- *   toMail(user: User): MailMessage {
- *     return new MailMessage()
- *       .subject('Invoice Paid')
- *       .view('emails.invoice-paid', { invoice: this.invoice })
- *   }
- *
- *   toDatabase(user: User): DatabaseNotification {
- *     return {
- *       type: 'invoice-paid',
- *       data: { invoice_id: this.invoice.id }
- *     }
- *   }
- * }
- * ```
+ * @public
+ * @since 3.0.0
  */
 declare abstract class Notification {
     /**
@@ -331,36 +343,41 @@ declare class NotificationManager {
 /**
  * OrbitFlare options.
  */
+/**
+ * Options for configuring OrbitFlare.
+ * @public
+ */
 interface OrbitFlareOptions {
-    /**
-     * Enable mail channel.
-     */
+    /** Enable or disable the email notification channel. */
     enableMail?: boolean;
-    /**
-     * Enable database channel.
-     */
+    /** Enable or disable the database storage notification channel. */
     enableDatabase?: boolean;
-    /**
-     * Enable broadcast channel.
-     */
+    /** Enable or disable the real-time broadcast notification channel. */
     enableBroadcast?: boolean;
-    /**
-     * Enable Slack channel.
-     */
+    /** Enable or disable the Slack notification channel. */
     enableSlack?: boolean;
-    /**
-     * Enable SMS channel.
-     */
+    /** Enable or disable the SMS notification channel. */
     enableSms?: boolean;
-    /**
-     * Custom channel configuration.
-     */
+    /** Custom channel configuration records for flexible extension. */
     channels?: Record<string, unknown>;
 }
 /**
- * Notifications Orbit
+ * OrbitFlare is the official notification orbit for Gravito.
+ * It provides a unified API for sending notifications across multiple channels
+ * (Mail, Database, Broadcast, Slack, SMS) and supports background queuing.
+ *
+ * @example
+ * ```typescript
+ * const flare = new OrbitFlare({
+ *   enableSlack: true,
+ *   channels: { slack: { webhookUrl: '...' } }
+ * });
+ * core.addOrbit(flare);
  *
- * Provides notifications with multiple channels (mail, database, broadcast, Slack, SMS).
+ * // Usage in controller
+ * await ctx.get('notifications').send(user, new WelcomeNotification());
+ * ```
+ * @public
  */
 declare class OrbitFlare implements GravitoOrbit {
     private options;
@@ -379,5 +396,11 @@ declare class OrbitFlare implements GravitoOrbit {
      */
     install(core: PlanetCore): Promise<void>;
 }
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Notification manager for multi-channel notifications */
+        notifications?: NotificationManager;
+    }
+}
 
 export { BroadcastChannel, type BroadcastNotification, DatabaseChannel, type DatabaseNotification, MailChannel, type MailMessage, type Notifiable, Notification, type NotificationChannel, NotificationManager, OrbitFlare, type OrbitFlareOptions, type ShouldQueue, SlackChannel, type SlackChannelConfig, type SlackMessage, SmsChannel, type SmsChannelConfig, type SmsMessage };

package/dist/index.d.ts

@@ -6,69 +6,95 @@ import { PlanetCore, GravitoOrbit } from '@gravito/core';
 
 /**
  * Notification channel interface.
+ * @public
  */
 interface NotificationChannel {
     /**
-     * Send a notification.
-     * @param notification - Notification instance
-     * @param notifiable - Recipient
+     * Send a notification through the specified channel.
+     *
+     * @param notification - The notification instance containing data.
+     * @param notifiable - The recipient of the notification.
      */
     send(notification: Notification, notifiable: Notifiable): Promise<void>;
 }
 /**
- * Notifiable (notification recipient) interface.
+ * Interface for recipients that can receive notifications.
+ * @public
  */
 interface Notifiable {
     /**
-     * Recipient identifier (usually an ID).
+     * Unique identifier for the recipient (e.g., User ID).
      */
     getNotifiableId(): string | number;
     /**
-     * Recipient type (optional, for polymorphic relations).
+     * Optional recipient type (useful for polymorphic notifications).
      */
     getNotifiableType?(): string;
     /**
-     * Preferred channels (optional).
+     * Optional list of preferred channels for this specific recipient.
      */
     preferredNotificationChannels?(): string[];
 }
 /**
- * Mail message payload.
+ * Payload for email notifications.
+ * @public
  */
 interface MailMessage {
+    /** Email subject line */
     subject: string;
+    /** View template path */
     view?: string;
+    /** Data to pass to the view template */
     data?: Record<string, unknown>;
+    /** Inline HTML content */
     html?: string;
+    /** Plain text content */
     text?: string;
+    /** Sender address */
     from?: string;
+    /** Target recipient(s) */
     to?: string | string[];
+    /** Carbon copy recipient(s) */
     cc?: string | string[];
+    /** Blind carbon copy recipient(s) */
     bcc?: string | string[];
 }
 /**
- * Database notification payload.
+ * Payload for database-stored notifications.
+ * @public
  */
 interface DatabaseNotification {
+    /** Type identifier for the notification */
     type: string;
+    /** JSON-serializable data payload */
     data: Record<string, unknown>;
+    /** Timestamp when the notification was marked as read */
     readAt?: Date | null;
 }
 /**
- * Broadcast notification payload.
+ * Payload for real-time broadcast notifications.
+ * @public
  */
 interface BroadcastNotification {
+    /** Event/Type identifier for the broadcast */
     type: string;
+    /** Data to be broadcasted to subscribers */
     data: Record<string, unknown>;
 }
 /**
- * Slack message payload.
+ * Payload for Slack channel notifications.
+ * @public
  */
 interface SlackMessage {
+    /** Main message text */
     text: string;
+    /** Target Slack channel */
     channel?: string;
+    /** Custom bot username */
     username?: string;
+    /** Icon emoji for the bot */
     iconEmoji?: string;
+    /** Array of Slack attachments for rich formatting */
     attachments?: Array<{
         color?: string;
         title?: string;
@@ -81,56 +107,42 @@ interface SlackMessage {
     }>;
 }
 /**
- * SMS message payload.
+ * Payload for SMS notifications.
+ * @public
  */
 interface SmsMessage {
+    /** Recipient phone number */
     to: string;
+    /** Message content */
     message: string;
+    /** Sender ID or phone number */
     from?: string;
 }
 
 /**
  * Marker interface for notifications that should be queued.
+ *
+ * Implementing this interface will cause the notification to be dispatched
+ * to a background queue automatically by the `NotificationManager`.
+ *
+ * @public
+ * @since 3.0.0
  */
 interface ShouldQueue {
-    /**
-     * Queue name (optional).
-     */
+    /** The name of the queue to push this notification to. */
     queue?: string | undefined;
+    /** The connection name (e.g., 'redis', 'database') to use for queuing. */
     connection?: string | undefined;
+    /** Delay in seconds before the notification is delivered. */
     delay?: number | undefined;
 }
 /**
  * Base Notification class.
  *
- * All notifications should extend this class.
- * Notifications can be delivered via multiple channels (mail, database, broadcast, Slack, SMS, etc.).
+ * All application notifications should extend this class.
  *
- * @example
- * ```typescript
- * class InvoicePaid extends Notification {
- *   constructor(private invoice: Invoice) {
- *     super()
- *   }
- *
- *   via(user: User): string[] {
- *     return ['mail', 'database']
- *   }
- *
- *   toMail(user: User): MailMessage {
- *     return new MailMessage()
- *       .subject('Invoice Paid')
- *       .view('emails.invoice-paid', { invoice: this.invoice })
- *   }
- *
- *   toDatabase(user: User): DatabaseNotification {
- *     return {
- *       type: 'invoice-paid',
- *       data: { invoice_id: this.invoice.id }
- *     }
- *   }
- * }
- * ```
+ * @public
+ * @since 3.0.0
  */
 declare abstract class Notification {
     /**
@@ -331,36 +343,41 @@ declare class NotificationManager {
 /**
  * OrbitFlare options.
  */
+/**
+ * Options for configuring OrbitFlare.
+ * @public
+ */
 interface OrbitFlareOptions {
-    /**
-     * Enable mail channel.
-     */
+    /** Enable or disable the email notification channel. */
     enableMail?: boolean;
-    /**
-     * Enable database channel.
-     */
+    /** Enable or disable the database storage notification channel. */
     enableDatabase?: boolean;
-    /**
-     * Enable broadcast channel.
-     */
+    /** Enable or disable the real-time broadcast notification channel. */
     enableBroadcast?: boolean;
-    /**
-     * Enable Slack channel.
-     */
+    /** Enable or disable the Slack notification channel. */
     enableSlack?: boolean;
-    /**
-     * Enable SMS channel.
-     */
+    /** Enable or disable the SMS notification channel. */
     enableSms?: boolean;
-    /**
-     * Custom channel configuration.
-     */
+    /** Custom channel configuration records for flexible extension. */
     channels?: Record<string, unknown>;
 }
 /**
- * Notifications Orbit
+ * OrbitFlare is the official notification orbit for Gravito.
+ * It provides a unified API for sending notifications across multiple channels
+ * (Mail, Database, Broadcast, Slack, SMS) and supports background queuing.
+ *
+ * @example
+ * ```typescript
+ * const flare = new OrbitFlare({
+ *   enableSlack: true,
+ *   channels: { slack: { webhookUrl: '...' } }
+ * });
+ * core.addOrbit(flare);
  *
- * Provides notifications with multiple channels (mail, database, broadcast, Slack, SMS).
+ * // Usage in controller
+ * await ctx.get('notifications').send(user, new WelcomeNotification());
+ * ```
+ * @public
  */
 declare class OrbitFlare implements GravitoOrbit {
     private options;
@@ -379,5 +396,11 @@ declare class OrbitFlare implements GravitoOrbit {
      */
     install(core: PlanetCore): Promise<void>;
 }
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Notification manager for multi-channel notifications */
+        notifications?: NotificationManager;
+    }
+}
 
 export { BroadcastChannel, type BroadcastNotification, DatabaseChannel, type DatabaseNotification, MailChannel, type MailMessage, type Notifiable, Notification, type NotificationChannel, NotificationManager, OrbitFlare, type OrbitFlareOptions, type ShouldQueue, SlackChannel, type SlackChannelConfig, type SlackMessage, SmsChannel, type SmsChannelConfig, type SmsMessage };

package/dist/index.js

@@ -336,7 +336,7 @@ var OrbitFlare = class _OrbitFlare {
   async install(core) {
     const manager = new NotificationManager(core);
     if (this.options.enableMail) {
-      const mail = core.services.get("mail");
+      const mail = core.container.make("mail");
       if (mail) {
         manager.channel("mail", new MailChannel(mail));
       } else {
@@ -344,7 +344,7 @@ var OrbitFlare = class _OrbitFlare {
       }
     }
     if (this.options.enableDatabase) {
-      const db = core.services.get("db");
+      const db = core.container.make("db");
       if (db) {
         manager.channel("database", new DatabaseChannel(db));
       } else {
@@ -352,7 +352,7 @@ var OrbitFlare = class _OrbitFlare {
       }
     }
     if (this.options.enableBroadcast) {
-      const broadcast = core.services.get("broadcast");
+      const broadcast = core.container.make("broadcast");
       if (broadcast) {
         manager.channel("broadcast", new BroadcastChannel(broadcast));
       } else {
@@ -375,8 +375,8 @@ var OrbitFlare = class _OrbitFlare {
         core.logger.warn("[OrbitFlare] SMS configuration not found, sms channel disabled");
       }
     }
-    core.services.set("notifications", manager);
-    const queue = core.services.get("queue");
+    core.container.instance("notifications", manager);
+    const queue = core.container.make("queue");
     if (queue) {
       manager.setQueueManager({
         push: async (job, queueName, connection, delay) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/flare",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "publishConfig": {
     "access": "public"
   },