@gravito/flare 3.0.1 → 3.3.0

package/dist/index.d.cts

@@ -118,6 +118,111 @@ interface SmsMessage {
     /** Sender ID or phone number */
     from?: string;
 }
+/**
+ * Result of a single channel delivery attempt.
+ * @public
+ */
+interface SendResult {
+    success: boolean;
+    channel: string;
+    error?: Error;
+    duration?: number;
+}
+/**
+ * Aggregated result of a notification delivery.
+ * @public
+ */
+interface NotificationResult {
+    notification: string;
+    notifiable: string | number;
+    results: SendResult[];
+    allSuccess: boolean;
+    timestamp: Date;
+}
+/**
+ * Options for sending notifications.
+ * @public
+ */
+interface SendOptions {
+    /** If true, throws an AggregateError when any channel fails */
+    throwOnError?: boolean;
+    /** Whether to send to channels in parallel (default: true) */
+    parallel?: boolean;
+    /** Maximum number of concurrent channel sends (default: unlimited) */
+    concurrency?: number;
+    /** Retry configuration */
+    retry?: Partial<RetryConfig> | boolean;
+}
+/**
+ * Retry configuration options.
+ * @public
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts: number;
+    /** Base delay in milliseconds (default: 1000) */
+    baseDelay: number;
+    /** Backoff strategy: 'fixed' | 'linear' | 'exponential' (default: 'exponential') */
+    backoff: 'fixed' | 'linear' | 'exponential';
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelay: number;
+    /** Function to determine if an error is retryable */
+    retryableErrors?: (error: Error) => boolean;
+}
+/**
+ * Interface for notifications that should retry on failure.
+ * @public
+ */
+interface ShouldRetry {
+    /** Retry configuration for this notification */
+    retry?: Partial<RetryConfig>;
+}
+/**
+ * Result of a batch notification delivery.
+ * @public
+ */
+interface BatchResult {
+    total: number;
+    success: number;
+    failed: number;
+    results: NotificationResult[];
+    duration: number;
+}
+interface NotificationHookPayload {
+    notification: Notification;
+    notifiable: Notifiable;
+    channels: string[];
+}
+interface ChannelHookPayload {
+    notification: Notification;
+    notifiable: Notifiable;
+    channel: string;
+}
+interface ChannelSuccessPayload extends ChannelHookPayload {
+    duration: number;
+}
+interface ChannelFailurePayload extends ChannelHookPayload {
+    error: Error;
+    duration: number;
+}
+interface NotificationCompletePayload {
+    notification: Notification;
+    notifiable: Notifiable;
+    results: SendResult[];
+    allSuccess: boolean;
+    totalDuration: number;
+}
+interface NotificationBatchStartPayload {
+    notification: Notification;
+    count: number;
+}
+interface NotificationBatchCompletePayload {
+    notification: Notification;
+    total: number;
+    success: number;
+    failed: number;
+    duration: number;
+}
 
 /**
  * Marker interface for notifications that should be queued.
@@ -155,27 +260,27 @@ declare abstract class Notification {
      * Get mail message (optional).
      * Implement this if the notification will be sent via the mail channel.
      */
-    toMail?(_notifiable: Notifiable): MailMessage;
+    toMail?(notifiable: Notifiable): MailMessage;
     /**
      * Get database notification (optional).
      * Implement this if the notification will be stored via the database channel.
      */
-    toDatabase?(_notifiable: Notifiable): DatabaseNotification;
+    toDatabase?(notifiable: Notifiable): DatabaseNotification;
     /**
      * Get broadcast notification (optional).
      * Implement this if the notification will be sent via the broadcast channel.
      */
-    toBroadcast?(_notifiable: Notifiable): BroadcastNotification;
+    toBroadcast?(notifiable: Notifiable): BroadcastNotification;
     /**
      * Get Slack message (optional).
      * Implement this if the notification will be sent via the Slack channel.
      */
-    toSlack?(_notifiable: Notifiable): SlackMessage;
+    toSlack?(notifiable: Notifiable): SlackMessage;
     /**
      * Get SMS message (optional).
      * Implement this if the notification will be sent via the SMS channel.
      */
-    toSms?(_notifiable: Notifiable): SmsMessage;
+    toSms?(notifiable: Notifiable): SmsMessage;
     /**
      * Check whether this notification should be queued.
      */
@@ -260,12 +365,14 @@ interface SmsChannelConfig {
     apiKey?: string;
     apiSecret?: string;
     from?: string;
+    region?: string;
+    accessKeyId?: string;
+    secretAccessKey?: 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;
@@ -281,6 +388,46 @@ declare class SmsChannel implements NotificationChannel {
     private sendViaAwsSns;
 }
 
+interface NotificationMetric {
+    notification: string;
+    channel: string;
+    success: boolean;
+    duration: number;
+    timestamp: Date;
+    error?: string;
+    retryCount?: number;
+}
+interface MetricsSummary {
+    totalSent: number;
+    totalSuccess: number;
+    totalFailed: number;
+    avgDuration: number;
+    byChannel: Record<string, {
+        sent: number;
+        success: number;
+        failed: number;
+        avgDuration: number;
+    }>;
+    byNotification: Record<string, {
+        sent: number;
+        success: number;
+        failed: number;
+        avgDuration: number;
+    }>;
+}
+declare class NotificationMetricsCollector {
+    private metrics;
+    private readonly maxHistory;
+    constructor(maxHistory?: number);
+    record(metric: NotificationMetric): void;
+    getSummary(since?: Date): MetricsSummary;
+    getRecentFailures(limit?: number): NotificationMetric[];
+    getSlowNotifications(threshold: number, limit?: number): NotificationMetric[];
+    clear(): void;
+}
+
+declare function toPrometheusFormat(summary: MetricsSummary): string;
+
 /**
  * Notification manager.
  *
@@ -297,6 +444,19 @@ declare class NotificationManager {
      */
     private queueManager?;
     constructor(core: PlanetCore);
+    private metrics?;
+    /**
+     * Enable metrics collection.
+     */
+    enableMetrics(maxHistory?: number): void;
+    /**
+     * Get metrics summary.
+     */
+    getMetrics(since?: Date): MetricsSummary | undefined;
+    /**
+     * Get recent failures.
+     */
+    getRecentFailures(limit?: number): NotificationMetric[];
     /**
      * Register a notification channel.
      *
@@ -315,22 +475,50 @@ declare class NotificationManager {
      *
      * @param notifiable - The recipient of the notification.
      * @param notification - The notification instance.
-     * @returns A promise that resolves when the notification is sent or queued.
+     * @param options - Options for sending.
+     * @returns A promise that resolves to the notification result.
      *
      * @example
      * ```typescript
-     * await notificationManager.send(user, new InvoicePaid(invoice))
+     * const result = await notificationManager.send(user, new InvoicePaid(invoice))
+     * if (!result.allSuccess) { ... }
      * ```
      */
-    send(notifiable: Notifiable, notification: Notification): Promise<void>;
+    send(notifiable: Notifiable, notification: Notification, options?: SendOptions): Promise<NotificationResult>;
     /**
-     * Send immediately (without queue).
+     * Batch send notification to multiple recipients.
+     *
+     * @param notifiables - List of recipients.
+     * @param notification - The notification instance.
+     * @param options - Options for sending.
+     * @returns A promise that resolves to the batch result.
+     */
+    sendBatch(notifiables: Notifiable[], notification: Notification, options?: SendOptions & {
+        /** Batch concurrency (default: 10) */
+        batchConcurrency?: number;
+    }): Promise<BatchResult>;
+    /**
+     * Batch send notification to multiple recipients (streaming).
      *
-     * @param notifiable - The recipient.
-     * @param notification - The notification.
-     * @param channels - The list of channels to send via.
+     * @param notifiables - AsyncIterable or Iterable of recipients.
+     * @param notification - The notification instance.
+     * @param options - Options for sending.
+     * @yields Notification results as they are processed.
+     */
+    sendBatchStream(notifiables: AsyncIterable<Notifiable> | Iterable<Notifiable>, notification: Notification, options?: SendOptions & {
+        batchSize?: number;
+    }): AsyncGenerator<NotificationResult>;
+    /**
+     * Send immediately (without queue).
      */
     private sendNow;
+    private sendSequential;
+    private sendParallel;
+    private sendWithConcurrencyLimit;
+    private processWithConcurrency;
+    private sendToChannel;
+    private executeChannelSend;
+    private getRetryConfig;
     /**
      * Serialize notification (for queuing).
      *
@@ -340,9 +528,6 @@ declare class NotificationManager {
     private serializeNotification;
 }
 
-/**
- * OrbitFlare options.
- */
 /**
  * Options for configuring OrbitFlare.
  * @public
@@ -389,12 +574,24 @@ declare class OrbitFlare implements GravitoOrbit {
      * @returns A new OrbitFlare instance.
      */
     static configure(options?: OrbitFlareOptions): OrbitFlare;
+    private validateOptions;
+    private isValidUrl;
     /**
      * Install OrbitFlare into PlanetCore.
      *
      * @param core - The PlanetCore instance.
      */
     install(core: PlanetCore): Promise<void>;
+    private setupMailChannel;
+    private setupDatabaseChannel;
+    private setupBroadcastChannel;
+    private setupSlackChannel;
+    private setupSmsChannel;
+    private setupQueueIntegration;
+    private isMailService;
+    private isDatabaseService;
+    private isBroadcastService;
+    private isQueueService;
 }
 declare module '@gravito/core' {
     interface GravitoVariables {
@@ -403,4 +600,32 @@ declare module '@gravito/core' {
     }
 }
 
-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 };
+interface TemplateData {
+    [key: string]: unknown;
+}
+interface MailTemplate {
+    subject: string;
+    view?: string;
+    data?: TemplateData;
+}
+interface SlackTemplate {
+    text: string;
+    channel?: string;
+    attachments?: Array<{
+        color?: string;
+        title?: string;
+        text?: string;
+    }>;
+}
+declare abstract class TemplatedNotification extends Notification {
+    protected data: TemplateData;
+    with(data: TemplateData): this;
+    protected abstract mailTemplate(): MailTemplate;
+    protected slackTemplate?(): SlackTemplate;
+    toMail(notifiable: Notifiable): MailMessage;
+    toSlack(_notifiable: Notifiable): SlackMessage;
+    private interpolate;
+    private getRecipientEmail;
+}
+
+export { type BatchResult, BroadcastChannel, type BroadcastNotification, type ChannelFailurePayload, type ChannelHookPayload, type ChannelSuccessPayload, DatabaseChannel, type DatabaseNotification, MailChannel, type MailMessage, type MailTemplate, type MetricsSummary, type Notifiable, Notification, type NotificationBatchCompletePayload, type NotificationBatchStartPayload, type NotificationChannel, type NotificationCompletePayload, type NotificationHookPayload, NotificationManager, type NotificationMetric, NotificationMetricsCollector, type NotificationResult, OrbitFlare, type OrbitFlareOptions, type RetryConfig, type SendOptions, type SendResult, type ShouldQueue, type ShouldRetry, SlackChannel, type SlackChannelConfig, type SlackMessage, type SlackTemplate, SmsChannel, type SmsChannelConfig, type SmsMessage, type TemplateData, TemplatedNotification, toPrometheusFormat };

package/dist/index.d.ts

@@ -118,6 +118,111 @@ interface SmsMessage {
     /** Sender ID or phone number */
     from?: string;
 }
+/**
+ * Result of a single channel delivery attempt.
+ * @public
+ */
+interface SendResult {
+    success: boolean;
+    channel: string;
+    error?: Error;
+    duration?: number;
+}
+/**
+ * Aggregated result of a notification delivery.
+ * @public
+ */
+interface NotificationResult {
+    notification: string;
+    notifiable: string | number;
+    results: SendResult[];
+    allSuccess: boolean;
+    timestamp: Date;
+}
+/**
+ * Options for sending notifications.
+ * @public
+ */
+interface SendOptions {
+    /** If true, throws an AggregateError when any channel fails */
+    throwOnError?: boolean;
+    /** Whether to send to channels in parallel (default: true) */
+    parallel?: boolean;
+    /** Maximum number of concurrent channel sends (default: unlimited) */
+    concurrency?: number;
+    /** Retry configuration */
+    retry?: Partial<RetryConfig> | boolean;
+}
+/**
+ * Retry configuration options.
+ * @public
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts: number;
+    /** Base delay in milliseconds (default: 1000) */
+    baseDelay: number;
+    /** Backoff strategy: 'fixed' | 'linear' | 'exponential' (default: 'exponential') */
+    backoff: 'fixed' | 'linear' | 'exponential';
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelay: number;
+    /** Function to determine if an error is retryable */
+    retryableErrors?: (error: Error) => boolean;
+}
+/**
+ * Interface for notifications that should retry on failure.
+ * @public
+ */
+interface ShouldRetry {
+    /** Retry configuration for this notification */
+    retry?: Partial<RetryConfig>;
+}
+/**
+ * Result of a batch notification delivery.
+ * @public
+ */
+interface BatchResult {
+    total: number;
+    success: number;
+    failed: number;
+    results: NotificationResult[];
+    duration: number;
+}
+interface NotificationHookPayload {
+    notification: Notification;
+    notifiable: Notifiable;
+    channels: string[];
+}
+interface ChannelHookPayload {
+    notification: Notification;
+    notifiable: Notifiable;
+    channel: string;
+}
+interface ChannelSuccessPayload extends ChannelHookPayload {
+    duration: number;
+}
+interface ChannelFailurePayload extends ChannelHookPayload {
+    error: Error;
+    duration: number;
+}
+interface NotificationCompletePayload {
+    notification: Notification;
+    notifiable: Notifiable;
+    results: SendResult[];
+    allSuccess: boolean;
+    totalDuration: number;
+}
+interface NotificationBatchStartPayload {
+    notification: Notification;
+    count: number;
+}
+interface NotificationBatchCompletePayload {
+    notification: Notification;
+    total: number;
+    success: number;
+    failed: number;
+    duration: number;
+}
 
 /**
  * Marker interface for notifications that should be queued.
@@ -155,27 +260,27 @@ declare abstract class Notification {
      * Get mail message (optional).
      * Implement this if the notification will be sent via the mail channel.
      */
-    toMail?(_notifiable: Notifiable): MailMessage;
+    toMail?(notifiable: Notifiable): MailMessage;
     /**
      * Get database notification (optional).
      * Implement this if the notification will be stored via the database channel.
      */
-    toDatabase?(_notifiable: Notifiable): DatabaseNotification;
+    toDatabase?(notifiable: Notifiable): DatabaseNotification;
     /**
      * Get broadcast notification (optional).
      * Implement this if the notification will be sent via the broadcast channel.
      */
-    toBroadcast?(_notifiable: Notifiable): BroadcastNotification;
+    toBroadcast?(notifiable: Notifiable): BroadcastNotification;
     /**
      * Get Slack message (optional).
      * Implement this if the notification will be sent via the Slack channel.
      */
-    toSlack?(_notifiable: Notifiable): SlackMessage;
+    toSlack?(notifiable: Notifiable): SlackMessage;
     /**
      * Get SMS message (optional).
      * Implement this if the notification will be sent via the SMS channel.
      */
-    toSms?(_notifiable: Notifiable): SmsMessage;
+    toSms?(notifiable: Notifiable): SmsMessage;
     /**
      * Check whether this notification should be queued.
      */
@@ -260,12 +365,14 @@ interface SmsChannelConfig {
     apiKey?: string;
     apiSecret?: string;
     from?: string;
+    region?: string;
+    accessKeyId?: string;
+    secretAccessKey?: 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;
@@ -281,6 +388,46 @@ declare class SmsChannel implements NotificationChannel {
     private sendViaAwsSns;
 }
 
+interface NotificationMetric {
+    notification: string;
+    channel: string;
+    success: boolean;
+    duration: number;
+    timestamp: Date;
+    error?: string;
+    retryCount?: number;
+}
+interface MetricsSummary {
+    totalSent: number;
+    totalSuccess: number;
+    totalFailed: number;
+    avgDuration: number;
+    byChannel: Record<string, {
+        sent: number;
+        success: number;
+        failed: number;
+        avgDuration: number;
+    }>;
+    byNotification: Record<string, {
+        sent: number;
+        success: number;
+        failed: number;
+        avgDuration: number;
+    }>;
+}
+declare class NotificationMetricsCollector {
+    private metrics;
+    private readonly maxHistory;
+    constructor(maxHistory?: number);
+    record(metric: NotificationMetric): void;
+    getSummary(since?: Date): MetricsSummary;
+    getRecentFailures(limit?: number): NotificationMetric[];
+    getSlowNotifications(threshold: number, limit?: number): NotificationMetric[];
+    clear(): void;
+}
+
+declare function toPrometheusFormat(summary: MetricsSummary): string;
+
 /**
  * Notification manager.
  *
@@ -297,6 +444,19 @@ declare class NotificationManager {
      */
     private queueManager?;
     constructor(core: PlanetCore);
+    private metrics?;
+    /**
+     * Enable metrics collection.
+     */
+    enableMetrics(maxHistory?: number): void;
+    /**
+     * Get metrics summary.
+     */
+    getMetrics(since?: Date): MetricsSummary | undefined;
+    /**
+     * Get recent failures.
+     */
+    getRecentFailures(limit?: number): NotificationMetric[];
     /**
      * Register a notification channel.
      *
@@ -315,22 +475,50 @@ declare class NotificationManager {
      *
      * @param notifiable - The recipient of the notification.
      * @param notification - The notification instance.
-     * @returns A promise that resolves when the notification is sent or queued.
+     * @param options - Options for sending.
+     * @returns A promise that resolves to the notification result.
      *
      * @example
      * ```typescript
-     * await notificationManager.send(user, new InvoicePaid(invoice))
+     * const result = await notificationManager.send(user, new InvoicePaid(invoice))
+     * if (!result.allSuccess) { ... }
      * ```
      */
-    send(notifiable: Notifiable, notification: Notification): Promise<void>;
+    send(notifiable: Notifiable, notification: Notification, options?: SendOptions): Promise<NotificationResult>;
     /**
-     * Send immediately (without queue).
+     * Batch send notification to multiple recipients.
+     *
+     * @param notifiables - List of recipients.
+     * @param notification - The notification instance.
+     * @param options - Options for sending.
+     * @returns A promise that resolves to the batch result.
+     */
+    sendBatch(notifiables: Notifiable[], notification: Notification, options?: SendOptions & {
+        /** Batch concurrency (default: 10) */
+        batchConcurrency?: number;
+    }): Promise<BatchResult>;
+    /**
+     * Batch send notification to multiple recipients (streaming).
      *
-     * @param notifiable - The recipient.
-     * @param notification - The notification.
-     * @param channels - The list of channels to send via.
+     * @param notifiables - AsyncIterable or Iterable of recipients.
+     * @param notification - The notification instance.
+     * @param options - Options for sending.
+     * @yields Notification results as they are processed.
+     */
+    sendBatchStream(notifiables: AsyncIterable<Notifiable> | Iterable<Notifiable>, notification: Notification, options?: SendOptions & {
+        batchSize?: number;
+    }): AsyncGenerator<NotificationResult>;
+    /**
+     * Send immediately (without queue).
      */
     private sendNow;
+    private sendSequential;
+    private sendParallel;
+    private sendWithConcurrencyLimit;
+    private processWithConcurrency;
+    private sendToChannel;
+    private executeChannelSend;
+    private getRetryConfig;
     /**
      * Serialize notification (for queuing).
      *
@@ -340,9 +528,6 @@ declare class NotificationManager {
     private serializeNotification;
 }
 
-/**
- * OrbitFlare options.
- */
 /**
  * Options for configuring OrbitFlare.
  * @public
@@ -389,12 +574,24 @@ declare class OrbitFlare implements GravitoOrbit {
      * @returns A new OrbitFlare instance.
      */
     static configure(options?: OrbitFlareOptions): OrbitFlare;
+    private validateOptions;
+    private isValidUrl;
     /**
      * Install OrbitFlare into PlanetCore.
      *
      * @param core - The PlanetCore instance.
      */
     install(core: PlanetCore): Promise<void>;
+    private setupMailChannel;
+    private setupDatabaseChannel;
+    private setupBroadcastChannel;
+    private setupSlackChannel;
+    private setupSmsChannel;
+    private setupQueueIntegration;
+    private isMailService;
+    private isDatabaseService;
+    private isBroadcastService;
+    private isQueueService;
 }
 declare module '@gravito/core' {
     interface GravitoVariables {
@@ -403,4 +600,32 @@ declare module '@gravito/core' {
     }
 }
 
-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 };
+interface TemplateData {
+    [key: string]: unknown;
+}
+interface MailTemplate {
+    subject: string;
+    view?: string;
+    data?: TemplateData;
+}
+interface SlackTemplate {
+    text: string;
+    channel?: string;
+    attachments?: Array<{
+        color?: string;
+        title?: string;
+        text?: string;
+    }>;
+}
+declare abstract class TemplatedNotification extends Notification {
+    protected data: TemplateData;
+    with(data: TemplateData): this;
+    protected abstract mailTemplate(): MailTemplate;
+    protected slackTemplate?(): SlackTemplate;
+    toMail(notifiable: Notifiable): MailMessage;
+    toSlack(_notifiable: Notifiable): SlackMessage;
+    private interpolate;
+    private getRecipientEmail;
+}
+
+export { type BatchResult, BroadcastChannel, type BroadcastNotification, type ChannelFailurePayload, type ChannelHookPayload, type ChannelSuccessPayload, DatabaseChannel, type DatabaseNotification, MailChannel, type MailMessage, type MailTemplate, type MetricsSummary, type Notifiable, Notification, type NotificationBatchCompletePayload, type NotificationBatchStartPayload, type NotificationChannel, type NotificationCompletePayload, type NotificationHookPayload, NotificationManager, type NotificationMetric, NotificationMetricsCollector, type NotificationResult, OrbitFlare, type OrbitFlareOptions, type RetryConfig, type SendOptions, type SendResult, type ShouldQueue, type ShouldRetry, SlackChannel, type SlackChannelConfig, type SlackMessage, type SlackTemplate, SmsChannel, type SmsChannelConfig, type SmsMessage, type TemplateData, TemplatedNotification, toPrometheusFormat };