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

package/dist/index.d.cts

@@ -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 };