@gravito/signal 3.0.3 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @gravito/signal
 
+## 3.0.4
+
+### Patch Changes
+
+- Convert all workspace:\* dependencies to version numbers for npm publishing
+
+  - Fixed 144 workspace:\* dependencies across 58 packages
+  - Ensures all packages work properly when installed from npm
+  - Resolves issues with bunx and npm installation of CLI tools
+  - All internal dependencies now use explicit version constraints
+
+- Updated dependencies
+  - @gravito/core@1.6.1
+  - @gravito/prism@3.1.1
+  - @gravito/stream@2.0.2
+
 ## 3.0.3
 
 ### Patch Changes

package/README.md

@@ -1,42 +1,69 @@
+# @gravito/signal 🛰️
 
-# Orbit Mail
+`@gravito/signal` is the powerful, multi-driver email framework for the Gravito ecosystem. It provides a clean, fluent API for building and sending emails with support for multiple rendering engines and transport drivers.
 
-A powerful, multi-driver email framework for Gravito applications. Supports HTML, Template, React, and Vue renderers, with built-in development tools.
+## ✨ Features
 
-## Features
+- 🚀 **Fluent API**: Expressive `Mailable` classes for building complex email messages with zero friction.
+- 🌌 **Galaxy-Ready**: A native Gravito Orbit that integrates seamlessly into the IoC container and context.
+- 🔌 **Multi-Driver Transport**: Support for SMTP, AWS SES, SendGrid, Log, and Memory drivers.
+- 🎨 **Modern Rendering**: Design emails using **React**, **Vue**, **MJML**, or **Prism** templates.
+- 📬 **Dev Mailbox UI**: Built-in visual interface at `/__mail` for local email inspection and debugging.
+- ⚙️ **Distributed Queueing**: Automatic offloading to `@gravito/stream` for background delivery.
+- 🛡️ **Webhook Processing**: Handle inbound delivery events (bounces, clicks) with ease.
 
-- **Multi-Driver Transport**: SMTP, AWS SES, Log, Memory.
-- **Content Renderers**:
-  - Raw HTML
-  - OrbitPrism Templates
-  - React Components (lazy-loaded)
-  - Vue Components (lazy-loaded)
-- **Development Mode**: Intercept emails and view them in a built-in UI (`/__mail`).
-- **Flexible API**: Fluent interface for building emails.
-- **Queue Support**: Built-in `Queueable` interface for async sending.
+## 🌌 Role in Galaxy Architecture
 
-## Installation
+In the **Gravito Galaxy Architecture**, Signal serves as the **Communication Nervous System**.
+
+- **Outbound Signal**: Satellites (domain plugins) trigger `Signal` to communicate with the outside world (users, other systems).
+- **Inbound Feedback**: Signal processes Webhooks from providers to update the state of the Galaxy (e.g., marking an email as invalid in the `Membership` Satellite).
+- **Event-Driven**: Leverages `@gravito/core`'s lifecycle to ensure emails are sent only after transactions are committed.
+
+```mermaid
+graph LR
+    S[Satellite] -->|Trigger| Signal[Signal Orbit]
+    Signal -->|Render| MW[MJML/React/Vue]
+    MW -->|Send| Provider[SES/SMTP]
+    Provider -.->|Webhook| Signal
+    Signal -.->|Event| S
+```
+
+## 📦 Installation
 
 ```bash
 bun add @gravito/signal
 ```
 
-For AWS SES support:
+### Optional Dependencies
+
+Depending on your transport or renderer choice, you may need additional packages:
+
 ```bash
+# For AWS SES
 bun add @aws-sdk/client-ses
+
+# For React components
+bun add react react-dom
+
+# For Vue components
+bun add vue @vue/server-renderer
 ```
 
-## Basic Usage
+## 🚀 Quick Start
 
-### Configuration
+### 1. Configure the Orbit
 
-Configure OrbitSignal in your generic startup or creation logic:
+Register `OrbitSignal` in your Gravito application:
 
 ```typescript
+import { PlanetCore } from '@gravito/core';
 import { OrbitSignal, SmtpTransport } from '@gravito/signal';
 
-const mail = OrbitSignal.configure({
-  from: { name: 'My App', address: 'noreply@myapp.com' },
+const core = new PlanetCore();
+
+const mail = new OrbitSignal({
+  from: { name: 'Gravito Support', address: 'support@example.com' },
   transport: new SmtpTransport({
     host: 'smtp.mailtrap.io',
     port: 2525,
@@ -45,19 +72,18 @@ const mail = OrbitSignal.configure({
   devMode: process.env.NODE_ENV === 'development',
 });
 
-// Install into PlanetCore
 mail.install(core);
 ```
 
-### Creating Mailables
+### 2. Create a Mailable
 
-Extend the `Mailable` class to create email definitions.
+Extend the `Mailable` class to define your email:
 
 ```typescript
 import { Mailable } from '@gravito/signal';
 
 export class WelcomeEmail extends Mailable {
-  constructor(private user: User) {
+  constructor(private user: { name: string; email: string }) {
     super();
   }
 
@@ -70,60 +96,74 @@ export class WelcomeEmail extends Mailable {
 }
 ```
 
-### Sending Email
+### 3. Send the Email
 
-```typescript
-import { WelcomeEmail } from './mail/WelcomeEmail';
+Access the mail service via the Gravito context:
 
-// In a controller/handler
-await new WelcomeEmail(user).renderContent(); // Validate content
-await context.get('mail').send(new WelcomeEmail(user));
+```typescript
+// In your route handler
+const mail = c.get('mail');
+await mail.send(new WelcomeEmail(user));
 ```
 
-### Queueing Email
+## 🛠️ Advanced Usage
 
-OrbitSignal supports queuing mail for background processing.
+### React & Vue Rendering
+
+You can use modern frontend frameworks to design your emails:
 
 ```typescript
-const email = new WelcomeEmail(user)
-  .onQueue('high-priority')
-  .delay(60);
+// React example
+export class MonthlyReport extends Mailable {
+  build() {
+    return this
+      .subject('Your Monthly Report')
+      .react(ReportComponent, { data: this.data });
+  }
+}
 
-// Queue the email
-await email.queue();
+// Vue example
+export class InvoiceEmail extends Mailable {
+  build() {
+    return this
+      .subject('Invoice #12345')
+      .vue(InvoiceTemplate, { total: 100 });
+  }
+}
 ```
 
-## Transports
-
-### SMTP
-Standard SMTP transport using `nodemailer`.
+### Queueing Emails
 
-### AWS SES
-Send via Amazon SES API.
+For better performance, send emails asynchronously:
 
 ```typescript
-import { SesTransport } from '@gravito/signal';
+const email = new WelcomeEmail(user)
+  .onQueue('notifications')
+  .delay(60); // Send after 60 seconds
 
-const transport = new SesTransport({
-  region: 'us-east-1',
-  accessKeyId: '...', // Optional if using environment variables
-  secretAccessKey: '...'
-});
+await email.queue();
 ```
 
-### Log
-Logs email content to the console (useful for debugging).
+### Development Mailbox
+
+When `devMode` is enabled, `OrbitSignal` intercepts all outgoing emails and stores them in memory. You can view them by navigating to `/__mail` (or your configured `devUiPrefix`) in your browser. This UI provides:
+- A list of all intercepted emails.
+- Preview of HTML and Plain Text content.
+- Metadata view (Subject, To, From, etc.).
 
-### Memory
-Stores emails in memory (used by Dev Mode).
+## 🔧 Configuration Options
 
-## Renderers
+The `MailConfig` object supports the following options:
 
-- **html(string)**: Raw HTML string.
-- **view(template, data)**: Uses generic template engine.
-- **react(Component, props)**: Renders a React component to HTML.
-- **vue(Component, props)**: Renders a Vue component to HTML.
+| Option | Type | Description |
+|---|---|---|
+| `from` | `Address` | Default sender address. |
+| `transport` | `Transport` | The transport driver to use. |
+| `devMode` | `boolean` | Enable/disable email interception. |
+| `viewsDir` | `string` | Path to template directory. |
+| `devUiPrefix`| `string` | URL prefix for Dev UI (default: `/__mail`). |
+| `translator` | `Function` | I18n translation function. |
 
-## License
+## 📄 License
 
-MIT
+MIT © Carl Lee

package/README.zh-TW.md

@@ -1,27 +1,158 @@
-# Orbit Mail
+# @gravito/signal 🛰️
 
-> Gravito 的郵件模組，支援多種傳輸與 HTML/模板/React/Vue 渲染。
+`@gravito/signal` 是 Gravito 生態系統中功能強大且支援多種驅動程式的電子郵件框架。它提供了一個簡潔、流暢的 API 來構建和發送電子郵件，並支援多種渲染引擎和傳輸驅動程式。
 
-## 安裝
+## 🌟 特性
+
+- **流暢的 API**：使用具表現力的 `Mailable` 類別來構建電子郵件內容。
+- **多驅動傳輸**：支援 SMTP (Nodemailer)、AWS SES、Log (控制台日誌) 和 Memory (記憶體)。
+- **靈活的渲染引擎**：支援使用以下方式渲染郵件內容：
+  - 原生 HTML 字串
+  - **Prism** (Edge 優化的模板引擎)
+  - **React** 組件 (透過 `react-dom/server`)
+  - **Vue** 組件 (透過 `@vue/server-renderer`)
+- **開發體驗優化**：
+  - **開發模式 (Dev Mode)**：在本地開發時攔截電子郵件，而不實際發送。
+  - **信箱 UI (Mailbox UI)**：在開發期間透過 `/__mail` 存取攔截到的郵件預覽界面。
+- **隊列整合**：內建支援透過 `@gravito/stream` 進行異步郵件發送。
+- **國際化 (I18n)**：整合多語系支援，輕鬆發送在地化郵件。
+- **類型安全**：完全使用 TypeScript 編寫，提供完善的配置與使用類型定義。
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/signal
 ```
 
-## 快速開始
+### 選用依賴
+
+根據您選擇的傳輸方式或渲染引擎，您可能需要安裝額外的套件：
+
+```bash
+# 若使用 AWS SES
+bun add @aws-sdk/client-ses
+
+# 若使用 React 組件
+bun add react react-dom
+
+# 若使用 Vue 組件
+bun add vue @vue/server-renderer
+```
+
+## 🚀 快速上手
+
+### 1. 配置 Orbit
+
+在您的 Gravito 應用程式中註冊 `OrbitSignal`：
 
 ```typescript
-import { OrbitSignal, SmtpTransport } from '@gravito/signal'
+import { PlanetCore } from '@gravito/core';
+import { OrbitSignal, SmtpTransport } from '@gravito/signal';
 
-const mail = OrbitSignal.configure({
-  from: { name: 'My App', address: 'noreply@myapp.com' },
+const core = new PlanetCore();
+
+const mail = new OrbitSignal({
+  from: { name: 'Gravito 支援團隊', address: 'support@example.com' },
   transport: new SmtpTransport({
     host: 'smtp.mailtrap.io',
     port: 2525,
     auth: { user: '...', pass: '...' }
   }),
   devMode: process.env.NODE_ENV === 'development',
-})
+});
+
+mail.install(core);
+```
+
+### 2. 建立 Mailable
+
+繼承 `Mailable` 類別來定義您的郵件內容：
+
+```typescript
+import { Mailable } from '@gravito/signal';
+
+export class WelcomeEmail extends Mailable {
+  constructor(private user: { name: string; email: string }) {
+    super();
+  }
+
+  build() {
+    return this
+      .to(this.user.email)
+      .subject('歡迎來到 Gravito！')
+      .view('emails/welcome', { name: this.user.name });
+  }
+}
+```
+
+### 3. 發送郵件
 
-mail.install(core)
+透過 Gravito Context 存取郵件服務：
+
+```typescript
+// 在路由處理器中
+const mail = c.get('mail');
+await mail.send(new WelcomeEmail(user));
+```
+
+## 🛠️ 進階用法
+
+### 使用 React 或 Vue 渲染
+
+您可以使用現代前端框架來設計您的郵件：
+
+```typescript
+// React 範例
+export class MonthlyReport extends Mailable {
+  build() {
+    return this
+      .subject('您的每月報表')
+      .react(ReportComponent, { data: this.data });
+  }
+}
+
+// Vue 範例
+export class InvoiceEmail extends Mailable {
+  build() {
+    return this
+      .subject('發票單號 #12345')
+      .vue(InvoiceTemplate, { total: 100 });
+  }
+}
+```
+
+### 隊列發送 (Queueing)
+
+為了提升應用程式效能，建議使用異步隊列發送郵件：
+
+```typescript
+const email = new WelcomeEmail(user)
+  .onQueue('notifications')
+  .delay(60); // 60 秒後發送
+
+await email.queue();
 ```
+
+### 開發者信箱 (Dev Mailbox)
+
+當啟用 `devMode` 時，`OrbitSignal` 會攔截所有外發郵件並將其存儲在記憶體中。您可以透過瀏覽器訪問 `/__mail` (或您配置的 `devUiPrefix`) 來查看。此界面提供：
+- 所有已攔截郵件的列表。
+- HTML 與純文字內容預覽。
+- 中繼資料查看 (主旨、收件者、寄件者等)。
+
+## 🔧 配置選項
+
+`MailConfig` 物件支援以下選項：
+
+| 選項 | 類型 | 描述 |
+|---|---|---|
+| `from` | `Address` | 預設寄件者地址。 |
+| `transport` | `Transport` | 使用的傳輸驅動程式。 |
+| `devMode` | `boolean` | 是否啟用郵件攔截開發模式。 |
+| `viewsDir` | `string` | 模板檔案存放目錄。 |
+| `devUiPrefix`| `string` | 開發界面 URL 前綴 (預設: `/__mail`)。 |
+| `translator` | `Function` | I18n 翻譯函數。 |
+
+## 📄 授權
+
+MIT © Carl Lee

package/build.ts

@@ -0,0 +1,133 @@
+import { cp, type Dirent, mkdir, readdir, rm } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { build } from 'bun'
+
+const isDtsOnly = process.argv.includes('--dts-only')
+const pkgName = basename(import.meta.dirname) // "signal"
+
+console.log(
+  isDtsOnly ? 'Building @gravito/signal DTS...' : 'Building @gravito/signal in parallel...'
+)
+
+// Clean dist
+await rm('dist', { recursive: true, force: true })
+
+// External dependencies（peer deps + framework 包）
+const externalDeps = [
+  '@gravito/core',
+  '@gravito/stream',
+  '@gravito/prism',
+  'react',
+  'react-dom',
+  'vue',
+  '@vue/server-renderer',
+  'nodemailer',
+  '@aws-sdk/client-ses',
+]
+
+async function buildInParallel() {
+  const tasks: Promise<number>[] = []
+  const tempDir = isDtsOnly ? 'dist' : '.tsc-temp'
+
+  if (!isDtsOnly) {
+    await rm(tempDir, { recursive: true, force: true })
+
+    // Task 1: bun build ESM
+    const esmPromise = (async () => {
+      const buildResult = await build({
+        entrypoints: ['src/index.ts'],
+        outdir: 'dist',
+        format: 'esm',
+        target: 'node',
+        splitting: false,
+        sourcemap: 'external',
+        external: externalDeps,
+        naming: '[dir]/[name].mjs',
+      })
+
+      if (!buildResult.success) {
+        console.error('❌ ESM build failed:', buildResult.logs)
+        return 1
+      }
+      return 0
+    })()
+    tasks.push(esmPromise)
+
+    // Task 2: bun build CJS
+    const cjsPromise = (async () => {
+      const cjsResult = await build({
+        entrypoints: ['src/index.ts'],
+        outdir: 'dist',
+        format: 'cjs',
+        target: 'node',
+        splitting: false,
+        sourcemap: 'external',
+        naming: '[dir]/[name].cjs',
+        external: externalDeps,
+      })
+
+      if (!cjsResult.success) {
+        console.error('❌ CJS build failed:', cjsResult.logs)
+        return 1
+      }
+      return 0
+    })()
+    tasks.push(cjsPromise)
+  }
+
+  // Task 3: tsc 生成型別宣告（使用 tsconfig.build.json + noCheck）
+  const tscPromise = (async () => {
+    const tsc = Bun.spawn(['bunx', 'tsc', '-p', 'tsconfig.build.json', '--outDir', tempDir], {
+      stdout: 'inherit',
+      stderr: 'inherit',
+      cwd: import.meta.dirname,
+    })
+    return await tsc.exited
+  })()
+  tasks.push(tscPromise)
+
+  const results = await Promise.all(tasks)
+  for (const result of results) {
+    if (result !== 0) {
+      process.exit(1)
+    }
+  }
+}
+
+// 遞迴複製 .d.ts 檔案
+async function copyDtsFiles(src: string, dest: string) {
+  let entries: Dirent[]
+  try {
+    entries = await readdir(src, { withFileTypes: true })
+  } catch (_e) {
+    return
+  }
+
+  for (const entry of entries) {
+    const srcPath = `${src}/${entry.name}`
+    const destPath = `${dest}/${entry.name}`
+
+    if (entry.isDirectory()) {
+      await mkdir(destPath, { recursive: true }).catch(() => {})
+      await copyDtsFiles(srcPath, destPath)
+    } else if (entry.isFile() && entry.name.endsWith('.d.ts')) {
+      await cp(srcPath, destPath)
+    }
+  }
+}
+
+await buildInParallel()
+
+// 後處理：tsc 輸出到 .tsc-temp/{pkgName}/src/，需要移到 dist/
+const tempDir = isDtsOnly ? 'dist' : '.tsc-temp'
+if (!isDtsOnly) {
+  try {
+    const dtsSourceDir = `${tempDir}/${pkgName}/src`
+    await copyDtsFiles(dtsSourceDir, 'dist')
+    await rm(tempDir, { recursive: true, force: true })
+  } catch (e) {
+    console.warn('⚠️  Warning: Failed to copy type declarations:', e)
+  }
+}
+
+console.log('✅ @gravito/signal build completed')