@gravito/flare 🌌

輕量化、高效能的 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，支援零配置整合。

📦 安裝

bun add @gravito/flare

🚀 快速上手

1. 定義您的通知

建立一個繼承自 Notification 的類別。實作 via 方法來指定發送通路，以及實作 to[Channel] 方法來定義發送內容。

import { Notification } from '@gravito/flare'
import type { MailMessage, DatabaseNotification, Notifiable } from '@gravito/flare'

class OrderShipped extends Notification {
  constructor(private order: any) {
    super()
  }

  // 指定發送通路
  via(user: Notifiable): string[] {
    return ['mail', 'database']
  }

  // 郵件內容
  toMail(user: Notifiable): MailMessage {
    return {
      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。

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 管理器。

// 在業務邏輯或控制器中
const notifications = core.container.make('notifications')

await notifications.send(user, new OrderShipped(order))

⏳ 非同步隊列

若要將通知放入背景發送，只需在通知類別中實作 ShouldQueue 介面。

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)：註冊自定義的發送通路。

🤝 參與貢獻

我們歡迎任何形式的貢獻！詳細資訊請參閱 貢獻指南。

📄 開源授權

MIT © Carl Lee