@gravito/flare 1.0.0-alpha.5 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,383 @@
+import { PlanetCore, GravitoOrbit } from 'gravito-core';
+
+/**
+ * Notification system type definitions.
+ */
+
+/**
+ * Notification channel interface.
+ */
+interface NotificationChannel {
+    /**
+     * Send a notification.
+     * @param notification - Notification instance
+     * @param notifiable - Recipient
+     */
+    send(notification: Notification, notifiable: Notifiable): Promise<void>;
+}
+/**
+ * Notifiable (notification recipient) interface.
+ */
+interface Notifiable {
+    /**
+     * Recipient identifier (usually an ID).
+     */
+    getNotifiableId(): string | number;
+    /**
+     * Recipient type (optional, for polymorphic relations).
+     */
+    getNotifiableType?(): string;
+    /**
+     * Preferred channels (optional).
+     */
+    preferredNotificationChannels?(): string[];
+}
+/**
+ * Mail message payload.
+ */
+interface MailMessage {
+    subject: string;
+    view?: string;
+    data?: Record<string, unknown>;
+    html?: string;
+    text?: string;
+    from?: string;
+    to?: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+}
+/**
+ * Database notification payload.
+ */
+interface DatabaseNotification {
+    type: string;
+    data: Record<string, unknown>;
+    readAt?: Date | null;
+}
+/**
+ * Broadcast notification payload.
+ */
+interface BroadcastNotification {
+    type: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Slack message payload.
+ */
+interface SlackMessage {
+    text: string;
+    channel?: string;
+    username?: string;
+    iconEmoji?: string;
+    attachments?: Array<{
+        color?: string;
+        title?: string;
+        text?: string;
+        fields?: Array<{
+            title: string;
+            value: string;
+            short?: boolean;
+        }>;
+    }>;
+}
+/**
+ * SMS message payload.
+ */
+interface SmsMessage {
+    to: string;
+    message: string;
+    from?: string;
+}
+
+/**
+ * Marker interface for notifications that should be queued.
+ */
+interface ShouldQueue {
+    /**
+     * Queue name (optional).
+     */
+    queue?: string | undefined;
+    connection?: string | undefined;
+    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.).
+ *
+ * @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 }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Notification {
+    /**
+     * Specify which channels should be used for delivery.
+     * @param notifiable - Recipient
+     * @returns Channel names
+     */
+    abstract via(notifiable: Notifiable): string[];
+    /**
+     * Get mail message (optional).
+     * Implement this if the notification will be sent via the mail channel.
+     */
+    toMail?(_notifiable: Notifiable): MailMessage;
+    /**
+     * Get database notification (optional).
+     * Implement this if the notification will be stored via the database channel.
+     */
+    toDatabase?(_notifiable: Notifiable): DatabaseNotification;
+    /**
+     * Get broadcast notification (optional).
+     * Implement this if the notification will be sent via the broadcast channel.
+     */
+    toBroadcast?(_notifiable: Notifiable): BroadcastNotification;
+    /**
+     * Get Slack message (optional).
+     * Implement this if the notification will be sent via the Slack channel.
+     */
+    toSlack?(_notifiable: Notifiable): SlackMessage;
+    /**
+     * Get SMS message (optional).
+     * Implement this if the notification will be sent via the SMS channel.
+     */
+    toSms?(_notifiable: Notifiable): SmsMessage;
+    /**
+     * Check whether this notification should be queued.
+     */
+    shouldQueue(): boolean;
+    /**
+     * Get queue configuration.
+     */
+    getQueueConfig(): {
+        queue?: string | undefined;
+        connection?: string | undefined;
+        delay?: number | undefined;
+    };
+}
+
+/**
+ * Broadcast channel.
+ *
+ * Sends notifications via a broadcast service.
+ */
+declare class BroadcastChannel implements NotificationChannel {
+    private broadcastService;
+    constructor(broadcastService: {
+        broadcast(channel: string, event: string, data: Record<string, unknown>): Promise<void>;
+    });
+    send(notification: Notification, notifiable: Notifiable): Promise<void>;
+}
+
+/**
+ * Database channel.
+ *
+ * Persists notifications to a database.
+ */
+declare class DatabaseChannel implements NotificationChannel {
+    private dbService;
+    constructor(dbService: {
+        insertNotification(data: {
+            notifiableId: string | number;
+            notifiableType: string;
+            type: string;
+            data: Record<string, unknown>;
+        }): Promise<void>;
+    });
+    send(notification: Notification, notifiable: Notifiable): Promise<void>;
+}
+
+/**
+ * Mail channel.
+ *
+ * Sends notifications via the mail service.
+ */
+declare class MailChannel implements NotificationChannel {
+    private mailService;
+    constructor(mailService: {
+        send(message: MailMessage): Promise<void>;
+    });
+    send(notification: Notification, notifiable: Notifiable): Promise<void>;
+}
+
+/**
+ * Slack channel configuration.
+ */
+interface SlackChannelConfig {
+    webhookUrl: string;
+    defaultChannel?: string;
+}
+/**
+ * Slack channel.
+ *
+ * Sends notifications via a Slack webhook.
+ */
+declare class SlackChannel implements NotificationChannel {
+    private config;
+    constructor(config: SlackChannelConfig);
+    send(notification: Notification, notifiable: Notifiable): Promise<void>;
+}
+
+/**
+ * SMS channel configuration.
+ */
+interface SmsChannelConfig {
+    provider: string;
+    apiKey?: string;
+    apiSecret?: string;
+    from?: string;
+}
+/**
+ * SMS channel.
+ *
+ * Sends notifications via an SMS provider.
+ * Only a basic interface is provided; real implementations should be extended per provider.
+ */
+declare class SmsChannel implements NotificationChannel {
+    private config;
+    constructor(config: SmsChannelConfig);
+    send(notification: Notification, notifiable: Notifiable): Promise<void>;
+    /**
+     * Send SMS via Twilio.
+     */
+    private sendViaTwilio;
+    /**
+     * Send SMS via AWS SNS.
+     */
+    private sendViaAwsSns;
+}
+
+/**
+ * Notification manager.
+ *
+ * Responsible for managing notification channels and delivering notifications.
+ */
+declare class NotificationManager {
+    private core;
+    /**
+     * Channel registry.
+     */
+    private channels;
+    /**
+     * Queue manager (optional, injected by `orbit-queue`).
+     */
+    private queueManager?;
+    constructor(core: PlanetCore);
+    /**
+     * Register a notification channel.
+     *
+     * @param name - The name of the channel.
+     * @param channel - The channel instance.
+     */
+    channel(name: string, channel: NotificationChannel): void;
+    /**
+     * Register the queue manager (called by `orbit-queue`).
+     *
+     * @param manager - The queue manager implementation.
+     */
+    setQueueManager(manager: NotificationManager['queueManager']): void;
+    /**
+     * Send a notification.
+     *
+     * @param notifiable - The recipient of the notification.
+     * @param notification - The notification instance.
+     * @returns A promise that resolves when the notification is sent or queued.
+     *
+     * @example
+     * ```typescript
+     * await notificationManager.send(user, new InvoicePaid(invoice))
+     * ```
+     */
+    send(notifiable: Notifiable, notification: Notification): Promise<void>;
+    /**
+     * Send immediately (without queue).
+     *
+     * @param notifiable - The recipient.
+     * @param notification - The notification.
+     * @param channels - The list of channels to send via.
+     */
+    private sendNow;
+    /**
+     * Serialize notification (for queuing).
+     *
+     * @param notification - The notification to serialize.
+     * @returns A plain object representation of the notification.
+     */
+    private serializeNotification;
+}
+
+/**
+ * OrbitFlare options.
+ */
+interface OrbitFlareOptions {
+    /**
+     * Enable mail channel.
+     */
+    enableMail?: boolean;
+    /**
+     * Enable database channel.
+     */
+    enableDatabase?: boolean;
+    /**
+     * Enable broadcast channel.
+     */
+    enableBroadcast?: boolean;
+    /**
+     * Enable Slack channel.
+     */
+    enableSlack?: boolean;
+    /**
+     * Enable SMS channel.
+     */
+    enableSms?: boolean;
+    /**
+     * Custom channel configuration.
+     */
+    channels?: Record<string, unknown>;
+}
+/**
+ * Notifications Orbit
+ *
+ * Provides notifications with multiple channels (mail, database, broadcast, Slack, SMS).
+ */
+declare class OrbitFlare implements GravitoOrbit {
+    private options;
+    constructor(options?: OrbitFlareOptions);
+    /**
+     * Configure OrbitFlare.
+     *
+     * @param options - The OrbitFlare configuration options.
+     * @returns A new OrbitFlare instance.
+     */
+    static configure(options?: OrbitFlareOptions): OrbitFlare;
+    /**
+     * Install OrbitFlare into PlanetCore.
+     *
+     * @param core - The PlanetCore instance.
+     */
+    install(core: PlanetCore): Promise<void>;
+}
+
+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.mjs → index.js}

@@ -1,6 +1,5 @@
 // src/channels/BroadcastChannel.ts
-class BroadcastChannel {
-  broadcastService;
+var BroadcastChannel = class {
   constructor(broadcastService) {
     this.broadcastService = broadcastService;
   }
@@ -12,12 +11,16 @@ class BroadcastChannel {
     const notifiableId = notifiable.getNotifiableId();
     const notifiableType = notifiable.getNotifiableType?.() || "user";
     const channel = `private-${notifiableType}.${notifiableId}`;
-    await this.broadcastService.broadcast(channel, broadcastNotification.type, broadcastNotification.data);
+    await this.broadcastService.broadcast(
+      channel,
+      broadcastNotification.type,
+      broadcastNotification.data
+    );
   }
-}
+};
+
 // src/channels/DatabaseChannel.ts
-class DatabaseChannel {
-  dbService;
+var DatabaseChannel = class {
   constructor(dbService) {
     this.dbService = dbService;
   }
@@ -33,10 +36,10 @@ class DatabaseChannel {
       data: dbNotification.data
     });
   }
-}
+};
+
 // src/channels/MailChannel.ts
-class MailChannel {
-  mailService;
+var MailChannel = class {
   constructor(mailService) {
     this.mailService = mailService;
   }
@@ -47,10 +50,10 @@ class MailChannel {
     const message = notification.toMail(notifiable);
     await this.mailService.send(message);
   }
-}
+};
+
 // src/channels/SlackChannel.ts
-class SlackChannel {
-  config;
+var SlackChannel = class {
   constructor(config) {
     this.config = config;
   }
@@ -76,10 +79,10 @@ class SlackChannel {
       throw new Error(`Failed to send Slack notification: ${response.statusText}`);
     }
   }
-}
+};
+
 // src/channels/SmsChannel.ts
-class SmsChannel {
-  config;
+var SmsChannel = class {
   constructor(config) {
     this.config = config;
   }
@@ -99,53 +102,89 @@ class SmsChannel {
         throw new Error(`Unsupported SMS provider: ${this.config.provider}`);
     }
   }
+  /**
+   * Send SMS via Twilio.
+   */
   async sendViaTwilio(message) {
     if (!this.config.apiKey || !this.config.apiSecret) {
       throw new Error("Twilio API key and secret are required");
     }
     const accountSid = this.config.apiKey;
     const authToken = this.config.apiSecret;
-    const response = await fetch(`https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`, {
-      method: "POST",
-      headers: {
-        Authorization: `Basic ${btoa(`${accountSid}:${authToken}`)}`,
-        "Content-Type": "application/x-www-form-urlencoded"
-      },
-      body: new URLSearchParams({
-        From: this.config.from || "",
-        To: message.to,
-        Body: message.message
-      })
-    });
+    const response = await fetch(
+      `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${btoa(`${accountSid}:${authToken}`)}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: new URLSearchParams({
+          From: this.config.from || "",
+          To: message.to,
+          Body: message.message
+        })
+      }
+    );
     if (!response.ok) {
       const error = await response.text();
       throw new Error(`Failed to send SMS via Twilio: ${error}`);
     }
   }
+  /**
+   * Send SMS via AWS SNS.
+   */
   async sendViaAwsSns(_message) {
     throw new Error("AWS SNS SMS provider not yet implemented. Please install @aws-sdk/client-sns");
   }
-}
+};
+
 // src/Notification.ts
-class Notification {
+var Notification = class {
+  /**
+   * Get mail message (optional).
+   * Implement this if the notification will be sent via the mail channel.
+   */
   toMail(_notifiable) {
     throw new Error("toMail method not implemented");
   }
+  /**
+   * Get database notification (optional).
+   * Implement this if the notification will be stored via the database channel.
+   */
   toDatabase(_notifiable) {
     throw new Error("toDatabase method not implemented");
   }
+  /**
+   * Get broadcast notification (optional).
+   * Implement this if the notification will be sent via the broadcast channel.
+   */
   toBroadcast(_notifiable) {
     throw new Error("toBroadcast method not implemented");
   }
+  /**
+   * Get Slack message (optional).
+   * Implement this if the notification will be sent via the Slack channel.
+   */
   toSlack(_notifiable) {
     throw new Error("toSlack method not implemented");
   }
+  /**
+   * Get SMS message (optional).
+   * Implement this if the notification will be sent via the SMS channel.
+   */
   toSms(_notifiable) {
     throw new Error("toSms method not implemented");
   }
+  /**
+   * Check whether this notification should be queued.
+   */
   shouldQueue() {
     return "queue" in this || "connection" in this || "delay" in this;
   }
+  /**
+   * Get queue configuration.
+   */
   getQueueConfig() {
     if (this.shouldQueue()) {
       const queueable = this;
@@ -157,21 +196,50 @@ class Notification {
     }
     return {};
   }
-}
+};
+
 // src/NotificationManager.ts
-class NotificationManager {
-  core;
-  channels = new Map;
-  queueManager;
+var NotificationManager = class {
   constructor(core) {
     this.core = core;
   }
+  /**
+   * Channel registry.
+   */
+  channels = /* @__PURE__ */ new Map();
+  /**
+   * Queue manager (optional, injected by `orbit-queue`).
+   */
+  queueManager;
+  /**
+   * Register a notification channel.
+   *
+   * @param name - The name of the channel.
+   * @param channel - The channel instance.
+   */
   channel(name, channel) {
     this.channels.set(name, channel);
   }
+  /**
+   * Register the queue manager (called by `orbit-queue`).
+   *
+   * @param manager - The queue manager implementation.
+   */
   setQueueManager(manager) {
     this.queueManager = manager;
   }
+  /**
+   * Send a notification.
+   *
+   * @param notifiable - The recipient of the notification.
+   * @param notification - The notification instance.
+   * @returns A promise that resolves when the notification is sent or queued.
+   *
+   * @example
+   * ```typescript
+   * await notificationManager.send(user, new InvoicePaid(invoice))
+   * ```
+   */
   async send(notifiable, notification) {
     const channels = notification.via(notifiable);
     if (notification.shouldQueue() && this.queueManager) {
@@ -187,11 +255,23 @@ class NotificationManager {
           await this.sendNow(notifiable, notification, channels);
         }
       };
-      await this.queueManager.push(queueJob, queueConfig.queue, queueConfig.connection, queueConfig.delay);
+      await this.queueManager.push(
+        queueJob,
+        queueConfig.queue,
+        queueConfig.connection,
+        queueConfig.delay
+      );
       return;
     }
     await this.sendNow(notifiable, notification, channels);
   }
+  /**
+   * Send immediately (without queue).
+   *
+   * @param notifiable - The recipient.
+   * @param notification - The notification.
+   * @param channels - The list of channels to send via.
+   */
   async sendNow(notifiable, notification, channels) {
     for (const channelName of channels) {
       const channel = this.channels.get(channelName);
@@ -202,10 +282,19 @@ class NotificationManager {
       try {
         await channel.send(notification, notifiable);
       } catch (error) {
-        this.core.logger.error(`[NotificationManager] Failed to send notification via '${channelName}':`, error);
+        this.core.logger.error(
+          `[NotificationManager] Failed to send notification via '${channelName}':`,
+          error
+        );
       }
     }
   }
+  /**
+   * Serialize notification (for queuing).
+   *
+   * @param notification - The notification to serialize.
+   * @returns A plain object representation of the notification.
+   */
   serializeNotification(notification) {
     const data = {};
     for (const [key, value] of Object.entries(notification)) {
@@ -215,9 +304,10 @@ class NotificationManager {
     }
     return data;
   }
-}
+};
+
 // src/OrbitFlare.ts
-class OrbitFlare {
+var OrbitFlare = class _OrbitFlare {
   options;
   constructor(options = {}) {
     this.options = {
@@ -229,9 +319,20 @@ class OrbitFlare {
       ...options
     };
   }
+  /**
+   * Configure OrbitFlare.
+   *
+   * @param options - The OrbitFlare configuration options.
+   * @returns A new OrbitFlare instance.
+   */
   static configure(options = {}) {
-    return new OrbitFlare(options);
+    return new _OrbitFlare(options);
   }
+  /**
+   * Install OrbitFlare into PlanetCore.
+   *
+   * @param core - The PlanetCore instance.
+   */
   async install(core) {
     const manager = new NotificationManager(core);
     if (this.options.enableMail) {
@@ -285,14 +386,14 @@ class OrbitFlare {
     }
     core.logger.info("[OrbitFlare] Installed");
   }
-}
+};
 export {
-  SmsChannel,
-  SlackChannel,
-  OrbitFlare,
-  NotificationManager,
-  Notification,
-  MailChannel,
+  BroadcastChannel,
   DatabaseChannel,
-  BroadcastChannel
+  MailChannel,
+  Notification,
+  NotificationManager,
+  OrbitFlare,
+  SlackChannel,
+  SmsChannel
 };