@gravito/flare 3.0.3 → 4.0.0

package/README.md

@@ -2,15 +2,20 @@
 
 > Lightweight, high-performance notifications for Gravito with multi-channel delivery (mail, database, broadcast, Slack, SMS).
 
-**Status**: v0.1.0 - core features complete with multiple channel support.
+**Status**: v3.4.0 - Production ready with advanced features (Retries, Metrics, Batching, Timeout, Rate Limiting, Preference Driver).
 
 ## Features
 
 - **Zero runtime overhead**: Pure type wrappers that delegate to channel drivers
-- **Multi-channel delivery**: Mail, database, broadcast, Slack, SMS
-- **Modular by design**: Install only the channels you need
-- **Queue support**: Works with `@gravito/stream` for async delivery
-- **AI-friendly**: Strong typing, clear JSDoc, and predictable APIs
+- **Multi-channel delivery**: Mail, database, broadcast, Slack, SMS (Twilio & AWS SNS)
+- **High Performance**: Parallel channel execution and batch sending capabilities
+- **Reliability**: Built-in retry mechanism with exponential backoff and timeout protection
+- **Observability**: Comprehensive metrics with Prometheus support
+- **Developer Experience**: Strong typing, lifecycle hooks, and template system
+- **Queue support**: Works with `@gravito/stream` for async delivery with Lazy Loading
+- **Rate Limiting**: Channel-level rate limiting with Token Bucket algorithm
+- **Preference Driver**: User notification preferences with automatic channel filtering
+- **Middleware System**: Extensible middleware chain for custom notification processing
 
 ## Installation
 
@@ -20,208 +25,274 @@ bun add @gravito/flare
 
 ## Quick Start
 
-### 1. Create a notification
-
-```typescript
-import { Notification } from '@gravito/flare'
-import type { MailMessage, DatabaseNotification, Notifiable } from '@gravito/flare'
-
-class InvoicePaid extends Notification {
-  constructor(private invoice: Invoice) {
-    super()
-  }
-
-  via(user: Notifiable): string[] {
-    return ['mail', 'database']
-  }
-
-  toMail(user: Notifiable): MailMessage {
-    return {
-      subject: 'Invoice Paid',
-      view: 'emails.invoice-paid',
-      data: { invoice: this.invoice },
-      to: user.email,
-    }
-  }
-
-  toDatabase(user: Notifiable): DatabaseNotification {
-    return {
-      type: 'invoice-paid',
-      data: {
-        invoice_id: this.invoice.id,
-        amount: this.invoice.amount,
-      },
-    }
-  }
-}
-```
-
-### 2. Configure OrbitFlare
+### 1. Configure OrbitFlare
 
 ```typescript
 import { PlanetCore } from '@gravito/core'
 import { OrbitFlare } from '@gravito/flare'
-import { OrbitSignal } from '@gravito/signal'
-import { OrbitStream } from '@gravito/stream'
 
 const core = await PlanetCore.boot({
   orbits: [
-    OrbitSignal.configure({ /* ... */ }),
-    OrbitStream.configure({ /* ... */ }),
     OrbitFlare.configure({
       enableMail: true,
       enableDatabase: true,
-      enableBroadcast: true,
       channels: {
-        slack: {
-          webhookUrl: 'https://hooks.slack.com/services/...',
-        },
+        slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL },
+        sms: {
+          provider: 'aws-sns', // or 'twilio'
+          region: 'us-east-1'
+        }
       },
+      // Optional: Global retry policy
+      retry: {
+        maxAttempts: 3,
+        backoff: 'exponential',
+        baseDelay: 1000
+      }
     }),
   ],
 })
 ```
 
-### 3. Send a notification
-
-```typescript
-// In a controller
-const notifications = c.get('notifications') as NotificationManager
-
-await notifications.send(user, new InvoicePaid(invoice))
-```
-
-## Queueing Notifications
+### 2. Create a notification
 
 ```typescript
-import { Notification, ShouldQueue } from '@gravito/flare'
+import { Notification } from '@gravito/flare'
+import type { MailMessage, Notifiable } from '@gravito/flare'
 
-class SendEmailNotification extends Notification implements ShouldQueue {
-  queue = 'notifications'
-  delay = 60 // delay by 60 seconds
+class WelcomeNotification extends Notification {
+  constructor(private name: string) {
+    super()
+  }
 
   via(user: Notifiable): string[] {
-    return ['mail']
+    return ['mail', 'database']
   }
 
   toMail(user: Notifiable): MailMessage {
     return {
       subject: 'Welcome!',
-      to: user.email,
       view: 'emails.welcome',
+      data: { name: this.name },
+      to: user.email,
     }
   }
-}
 
-await notifications.send(user, new SendEmailNotification())
+  // Define per-notification retry logic
+  retry = {
+    maxAttempts: 5,
+    backoff: 'linear' as const
+  }
+}
 ```
 
-## Channels
+### 3. Send a notification
 
-### Mail
+```typescript
+const notifications = c.get('notifications') as NotificationManager
 
-Requires `@gravito/signal`:
+// Simple send
+const result = await notifications.send(user, new WelcomeNotification('Alice'))
 
-```typescript
-via(user: Notifiable): string[] {
-  return ['mail']
+if (result.failed.length > 0) {
+  console.error('Some channels failed:', result.failed)
 }
 
-toMail(user: Notifiable): MailMessage {
-  return {
-    subject: 'Subject',
-    view: 'emails.template',
-    data: { /* ... */ },
-    to: user.email,
+// Batch send (high performance)
+await notifications.sendBatch(users, new SystemUpdateNotification())
+```
+
+## Advanced Features
+
+### Retries
+Configure retries globally or per-notification:
+
+```typescript
+// Per-notification
+class CriticalAlert extends Notification {
+  shouldRetry(attempt: number, error: Error): boolean {
+    return attempt < 5 && isRetryable(error)
   }
 }
 ```
 
-### Database
+### Metrics
+Enable metrics to track success rates and latency:
+
+```typescript
+const metrics = new NotificationMetricsCollector()
+notifications.setMetricsCollector(metrics)
+
+// Export to Prometheus
+const promData = toPrometheusFormat(metrics.getSummary())
+```
 
-Requires database support:
+### Hooks
+Listen to lifecycle events:
 
 ```typescript
-via(user: Notifiable): string[] {
-  return ['database']
-}
+notifications.on('notification:failed', ({ notification, error }) => {
+  logger.error('Notification failed completely', error)
+})
+```
 
-toDatabase(user: Notifiable): DatabaseNotification {
-  return {
-    type: 'notification-type',
-    data: { /* ... */ },
+### Templates
+Use `TemplatedNotification` for consistent messaging:
+
+```typescript
+class OrderShipped extends TemplatedNotification {
+  constructor(order: Order) {
+    super('order-shipped', { orderId: order.id })
   }
 }
 ```
 
-### Broadcast
-
-Requires `@gravito/radiance`:
+### Timeout Protection (v3.4.0)
+All channels support timeout configuration to prevent slow responses from blocking notifications:
 
 ```typescript
-via(user: Notifiable): string[] {
-  return ['broadcast']
-}
+OrbitFlare.configure({
+  channels: {
+    slack: {
+      webhookUrl: process.env.SLACK_WEBHOOK_URL,
+      timeout: 5000, // 5 秒超時
+      onTimeout: (channel, notification) => {
+        console.error(`Timeout: ${channel}`)
+      }
+    }
+  }
+})
+```
+
+### Rate Limiting (v3.4.0)
+Protect downstream services with channel-level rate limiting:
 
-toBroadcast(user: Notifiable): BroadcastNotification {
-  return {
-    type: 'notification-type',
-    data: { /* ... */ },
+```typescript
+import { RateLimitMiddleware } from '@gravito/flare'
+
+const rateLimiter = new RateLimitMiddleware({
+  email: {
+    maxPerSecond: 10,
+    maxPerMinute: 100,
+    maxPerHour: 1000
+  },
+  sms: {
+    maxPerSecond: 5
   }
-}
+})
+
+notifications.use(rateLimiter)
+
+// 檢查狀態
+const status = rateLimiter.getStatus('email')
+console.log(`剩餘: ${status.second}/10`)
 ```
 
-### Slack
+### Lazy Loading for Queue (v3.4.0)
+Optimize queue serialization with Lazy Loading pattern:
 
 ```typescript
-via(user: Notifiable): string[] {
-  return ['slack']
-}
+import { LazyNotification } from '@gravito/flare'
 
-toSlack(user: Notifiable): SlackMessage {
-  return {
-    text: 'Notification message',
-    channel: '#notifications',
+class OrderConfirmation extends LazyNotification<Order> {
+  constructor(private orderId: string) {
+    super()
+  }
+
+  protected async loadData(notifiable: Notifiable): Promise<Order> {
+    return await db.orders.find(this.orderId)
+  }
+
+  via(user: Notifiable): string[] {
+    return ['mail', 'database']
+  }
+
+  async toMail(user: Notifiable): Promise<MailMessage> {
+    const order = await this.ensureLoaded(user)
+    return {
+      subject: `訂單確認 #${order.id}`,
+      view: 'emails.order-confirmation',
+      data: { order },
+      to: user.email,
+    }
   }
 }
 ```
 
-### SMS
+### User Preferences (v3.4.0)
+Respect user notification preferences automatically:
 
 ```typescript
-via(user: Notifiable): string[] {
-  return ['sms']
-}
+import { PreferenceMiddleware } from '@gravito/flare'
 
-toSms(user: Notifiable): SmsMessage {
-  return {
-    to: user.phone,
-    message: 'Notification message',
+// 方式 1: 在 OrbitFlare 配置中啟用
+OrbitFlare.configure({
+  enablePreference: true
+})
+
+// 方式 2: 使用自定義偏好提供者
+const preferenceMiddleware = new PreferenceMiddleware({
+  async getUserPreferences(notifiable) {
+    const prefs = await db.userPreferences.find(notifiable.id)
+    return {
+      enabledChannels: prefs.enabledChannels,
+      disabledChannels: prefs.disabledChannels,
+      disabledNotifications: prefs.disabledNotifications
+    }
+  }
+})
+
+notifications.use(preferenceMiddleware)
+
+// 方式 3: 在 Notifiable 物件中實作
+class User implements Notifiable {
+  async getNotificationPreferences() {
+    return {
+      enabledChannels: ['email', 'slack'],
+      disabledChannels: ['sms']
+    }
   }
 }
 ```
 
-## API Reference
+### Middleware Chain (v3.4.0)
+Combine multiple middleware for powerful notification processing:
 
-### Notification
+```typescript
+import { RateLimitMiddleware, PreferenceMiddleware } from '@gravito/flare'
 
-Every notification should extend `Notification`.
+// 建立中介層
+const rateLimiter = new RateLimitMiddleware({ /* ... */ })
+const preferenceFilter = new PreferenceMiddleware({ /* ... */ })
 
-#### Methods
+// 註冊中介層（執行順序：由內而外）
+notifications
+  .use(rateLimiter)      // 先限流
+  .use(preferenceFilter) // 後過濾
 
-- `via(notifiable: Notifiable): string[]` - Choose delivery channels (required)
-- `toMail(notifiable: Notifiable): MailMessage` - Mail payload (optional)
-- `toDatabase(notifiable: Notifiable): DatabaseNotification` - Database payload (optional)
-- `toBroadcast(notifiable: Notifiable): BroadcastNotification` - Broadcast payload (optional)
-- `toSlack(notifiable: Notifiable): SlackMessage` - Slack payload (optional)
-- `toSms(notifiable: Notifiable): SmsMessage` - SMS payload (optional)
+// 或在 OrbitFlare 配置中一次註冊
+OrbitFlare.configure({
+  middleware: [rateLimiter, preferenceFilter]
+})
+```
+
+## API Reference
 
 ### NotificationManager
 
 #### Methods
 
-- `send(notifiable: Notifiable, notification: Notification): Promise<void>` - Send notification
-- `channel(name: string, channel: NotificationChannel): void` - Register a custom channel
+- `send(notifiable: Notifiable, notification: Notification, options?: SendOptions): Promise<NotificationResult>`
+- `sendBatch(notifiables: Notifiable[], notification: Notification): Promise<BatchResult>`
+- `sendBatchStream(iterator: AsyncIterator<Notifiable>, notification: Notification): Promise<BatchResult>`
+
+### Notification
+
+#### Methods
+
+- `via(notifiable: Notifiable): string[]` - Choose delivery channels
+- `toMail`, `toDatabase`, `toBroadcast`, `toSlack`, `toSms` - Channel payloads
+- `shouldRetry(attempt: number, error: Error): boolean` - Custom retry logic
 
 ## License
 

package/README.zh-TW.md

@@ -1,35 +1,150 @@
-# @gravito/flare
+# @gravito/flare 🌌
 
-> Gravito 的通知模組，支援郵件、資料庫、廣播、Slack、SMS 等多種通道。
+> 輕量化、高效能的 Gravito 通知引擎，支援多通路發送（郵件、資料庫、廣播、Slack、SMS）。
 
-## 安裝
+`@gravito/flare` 是 Gravito 框架官方提供的通知引擎。它提供了一套簡潔且具表現力的 API，讓開發者能夠輕鬆地透過多種通路發送通知，並原生支援背景隊列處理。
+
+**狀態**: v1.0.0 - 生產環境可用。
+
+## 🌟 核心特性
+
+- **零執行負擔 (Zero Runtime Overhead)**：純 TypeScript 實作，直接委派給高效的通路驅動程式。
+- **多通路支援**：單一通知可同時透過多個通路（Mail, DB, Slack 等）發送。
+- **背景隊列支援**：與 `@gravito/stream` (OrbitStream) 無縫整合，處理高流量通知發送而不阻塞請求。
+- **類型安全 (Type-Safe)**：為每個通路提供嚴格的訊息結構定義，確保資料完整性。
+- **易於擴充**：可輕鬆註冊自定義的通知通路。
+- **Galaxy 架構相容**：設計為標準的 Gravito Orbit，支援零配置整合。
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/flare
 ```
 
-## 快速開始
+## 🚀 快速上手
+
+### 1. 定義您的通知
+
+建立一個繼承自 `Notification` 的類別。實作 `via` 方法來指定發送通路，以及實作 `to[Channel]` 方法來定義發送內容。
 
 ```typescript
 import { Notification } from '@gravito/flare'
-import type { MailMessage, Notifiable } from '@gravito/flare'
+import type { MailMessage, DatabaseNotification, Notifiable } from '@gravito/flare'
 
-class WelcomeUser extends Notification {
+class OrderShipped extends Notification {
+  constructor(private order: any) {
+    super()
+  }
+
+  // 指定發送通路
   via(user: Notifiable): string[] {
-    return ['mail']
+    return ['mail', 'database']
   }
 
+  // 郵件內容
   toMail(user: Notifiable): MailMessage {
     return {
-      subject: 'Welcome!',
-      view: 'emails.welcome',
+      subject: `訂單 #${this.order.id} 已出貨！`,
+      view: 'emails.order-shipped',
+      data: { order: this.order },
       to: user.email,
     }
   }
+
+  // 資料庫通知內容
+  toDatabase(user: Notifiable): DatabaseNotification {
+    return {
+      type: 'order_shipped',
+      data: {
+        order_id: this.order.id,
+        tracking_number: this.order.tracking,
+      },
+    }
+  }
 }
 ```
 
+### 2. 配置 OrbitFlare
+
+在 `PlanetCore` 啟動程序中註冊 `OrbitFlare`。
+
+```typescript
+import { PlanetCore } from '@gravito/core'
+import { OrbitFlare } from '@gravito/flare'
+
+const core = await PlanetCore.boot({
+  orbits: [
+    OrbitFlare.configure({
+      enableMail: true,
+      enableDatabase: true,
+      channels: {
+        slack: {
+          webhookUrl: process.env.SLACK_WEBHOOK_URL,
+        },
+      },
+    }),
+  ],
+})
+```
+
+### 3. 發送通知
+
+透過核心容器或上下文變數取得 `notifications` 管理器。
+
+```typescript
+// 在業務邏輯或控制器中
+const notifications = core.container.make('notifications')
+
+await notifications.send(user, new OrderShipped(order))
+```
+
+## ⏳ 非同步隊列
+
+若要將通知放入背景發送，只需在通知類別中實作 `ShouldQueue` 介面。
+
 ```typescript
-const notifications = c.get('notifications')
-await notifications.send(user, new WelcomeUser())
+import { Notification, ShouldQueue } from '@gravito/flare'
+
+class WeeklyReport extends Notification implements ShouldQueue {
+  queue = 'notifications' // 可選：指定隊列名稱
+  delay = 3600            // 可選：延遲秒數
+
+  via(user: Notifiable): string[] {
+    return ['mail']
+  }
+  
+  // ... toMail 實作
+}
 ```
+
+## 🛠️ 支援的通路
+
+| 通路 | 依賴模組 | 描述 |
+|---|---|---|
+| **Mail** | `@gravito/signal` | 透過配置的郵件驅動發送電子郵件。 |
+| **Database** | `@gravito/atlas` | 將通知儲存至 `notifications` 資料表。 |
+| **Broadcast**| `@gravito/radiance`| 透過 WebSockets 推送即時更新。 |
+| **Slack** | 無 | 透過 Webhooks 發送訊息至 Slack。 |
+| **SMS** | 供應商配置 | 透過配置的簡訊供應商發送簡訊。 |
+
+## 🧩 API 參考
+
+### `Notification` 基礎類別
+- `via(notifiable)`：回傳通路名稱陣列。
+- `toMail(notifiable)`：回傳 `MailMessage`。
+- `toDatabase(notifiable)`：回傳 `DatabaseNotification`。
+- `toBroadcast(notifiable)`：回傳 `BroadcastNotification`。
+- `toSlack(notifiable)`：回傳 `SlackMessage`。
+- `toSms(notifiable)`：回傳 `SmsMessage`。
+
+### `NotificationManager`
+- `send(notifiable, notification)`：將通知發送至所有指定的通路。
+- `channel(name, implementation)`：註冊自定義的發送通路。
+
+## 🤝 參與貢獻
+
+我們歡迎任何形式的貢獻！詳細資訊請參閱 [貢獻指南](../../CONTRIBUTING.md)。
+
+## 📄 開源授權
+
+MIT © Carl Lee