@gravito/signal 3.0.1 → 3.0.4

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @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
+
+- Updated dependencies [6234dab]
+  - @gravito/prism@3.0.2
+
+## 3.0.2
+
+### Patch Changes
+
+- Updated dependencies [905588f]
+  - @gravito/stream@2.0.1
+
 ## 3.0.1
 
 ### Patch Changes

package/README.md

@@ -1,42 +1,58 @@
+# @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
-
-- **Multi-Driver Transport**: SMTP, AWS SES, Log, Memory.
-- **Content Renderers**:
+- **Fluent API**: Expressive `Mailable` classes for building email messages.
+- **Multi-Driver Transport**: Support for SMTP (Nodemailer), AWS SES, Log (console), and Memory.
+- **Flexible Rendering**: Render email content using:
   - 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.
-
-## Installation
+  - **Prism** (Edge-optimized view engine)
+  - **React** Components (via `react-dom/server`)
+  - **Vue** Components (via `@vue/server-renderer`)
+- **Development Experience**:
+  - **Dev Mode**: Intercept emails locally and view them in a built-in UI.
+  - **Mailbox UI**: Access intercepted emails at `/__mail` during development.
+- **Queue Integration**: Built-in support for asynchronous email sending via `@gravito/stream`.
+- **Internationalization**: Integrated I18n support for localized email content.
+- **Type-Safe**: Written in TypeScript with full type safety for configuration and usage.
+
+## 📦 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 +61,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 +85,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
+
+### React & Vue Rendering
 
-OrbitSignal supports queuing mail for background processing.
+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/dist/MjmlRenderer-IUH663FT.mjs

@@ -0,0 +1,8 @@
+import {
+  MjmlRenderer
+} from "./chunk-W6LXIJKK.mjs";
+import "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
+export {
+  MjmlRenderer
+};

package/dist/ReactMjmlRenderer-C3P5YO5L.mjs

@@ -0,0 +1,8 @@
+import {
+  ReactMjmlRenderer
+} from "./chunk-DBFIVHHG.mjs";
+import "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
+export {
+  ReactMjmlRenderer
+};

package/dist/ReactRenderer-2JFLRVST.mjs

@@ -0,0 +1,45 @@
+import {
+  stripHtml
+} from "./chunk-XBIVBJS2.mjs";
+import "./chunk-EBO3CZXG.mjs";
+
+// src/renderers/ReactRenderer.ts
+var ReactRenderer = class {
+  /**
+   * Creates an instance of ReactRenderer.
+   *
+   * @param component - The React component to render.
+   * @param props - Initial props for the component.
+   * @param deps - Optional dependency injection for testing.
+   */
+  constructor(component, props, deps = {}) {
+    this.component = component;
+    this.props = props;
+    this.deps = deps;
+  }
+  /**
+   * Renders the React component to a static HTML string.
+   *
+   * This method performs dynamic imports of `react` and `react-dom/server`
+   * to ensure they are only loaded if this renderer is actually used.
+   *
+   * @param data - Runtime data to be merged with initial props.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If React dependencies cannot be loaded or rendering fails.
+   */
+  async render(data) {
+    const createElement = this.deps.createElement ?? (await import("react")).createElement;
+    const renderToStaticMarkup = this.deps.renderToStaticMarkup ?? (await import("react-dom/server")).renderToStaticMarkup;
+    const mergedProps = { ...this.props, ...data };
+    const element = createElement(this.component, mergedProps);
+    const html = renderToStaticMarkup(element);
+    const fullHtml = html.startsWith("<!DOCTYPE") ? html : `<!DOCTYPE html>${html}`;
+    return {
+      html: fullHtml,
+      text: stripHtml(html)
+    };
+  }
+};
+export {
+  ReactRenderer
+};

package/dist/{ReactRenderer-L5INVYKT.mjs → ReactRenderer-LYEOSYFS.mjs}

@@ -1,26 +1,27 @@
-import "./chunk-6DZX6EAA.mjs";
+import {
+  stripHtml
+} from "./chunk-XBIVBJS2.mjs";
+import "./chunk-EBO3CZXG.mjs";
 
 // src/renderers/ReactRenderer.ts
-import { createElement } from "react";
-import { renderToStaticMarkup } from "react-dom/server";
 var ReactRenderer = class {
-  constructor(component, props) {
+  constructor(component, props, deps = {}) {
     this.component = component;
     this.props = props;
+    this.deps = deps;
   }
   async render(data) {
+    const createElement = this.deps.createElement ?? (await import("react")).createElement;
+    const renderToStaticMarkup = this.deps.renderToStaticMarkup ?? (await import("react-dom/server")).renderToStaticMarkup;
     const mergedProps = { ...this.props, ...data };
     const element = createElement(this.component, mergedProps);
     const html = renderToStaticMarkup(element);
     const fullHtml = html.startsWith("<!DOCTYPE") ? html : `<!DOCTYPE html>${html}`;
     return {
       html: fullHtml,
-      text: this.stripHtml(html)
+      text: stripHtml(html)
     };
   }
-  stripHtml(html) {
-    return html.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "").replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "").replace(/<[^>]+>/g, "").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
-  }
 };
 export {
   ReactRenderer

package/dist/ReactRenderer-V54CUUEI.mjs

@@ -0,0 +1,45 @@
+import {
+  stripHtml
+} from "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
+
+// src/renderers/ReactRenderer.ts
+var ReactRenderer = class {
+  /**
+   * Creates an instance of ReactRenderer.
+   *
+   * @param component - The React component to render.
+   * @param props - Initial props for the component.
+   * @param deps - Optional dependency injection for testing.
+   */
+  constructor(component, props, deps = {}) {
+    this.component = component;
+    this.props = props;
+    this.deps = deps;
+  }
+  /**
+   * Renders the React component to a static HTML string.
+   *
+   * This method performs dynamic imports of `react` and `react-dom/server`
+   * to ensure they are only loaded if this renderer is actually used.
+   *
+   * @param data - Runtime data to be merged with initial props.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If React dependencies cannot be loaded or rendering fails.
+   */
+  async render(data) {
+    const createElement = this.deps.createElement ?? (await import("react")).createElement;
+    const renderToStaticMarkup = this.deps.renderToStaticMarkup ?? (await import("react-dom/server")).renderToStaticMarkup;
+    const mergedProps = { ...this.props, ...data };
+    const element = createElement(this.component, mergedProps);
+    const html = renderToStaticMarkup(element);
+    const fullHtml = html.startsWith("<!DOCTYPE") ? html : `<!DOCTYPE html>${html}`;
+    return {
+      html: fullHtml,
+      text: stripHtml(html)
+    };
+  }
+};
+export {
+  ReactRenderer
+};

package/dist/VueMjmlRenderer-4F4CXHDB.mjs

@@ -0,0 +1,8 @@
+import {
+  VueMjmlRenderer
+} from "./chunk-KB7IDDBT.mjs";
+import "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
+export {
+  VueMjmlRenderer
+};

package/dist/VueMjmlRenderer-5WZR4CQG.mjs

@@ -0,0 +1,8 @@
+import {
+  VueMjmlRenderer
+} from "./chunk-3WOR3XSL.mjs";
+import "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
+export {
+  VueMjmlRenderer
+};

package/dist/VueMjmlRenderer-U5YMWI44.mjs

@@ -0,0 +1,8 @@
+import {
+  VueMjmlRenderer
+} from "./chunk-LZL5UUPC.mjs";
+import "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
+export {
+  VueMjmlRenderer
+};

package/dist/VueRenderer-3YBRQXME.mjs

@@ -0,0 +1,48 @@
+import {
+  stripHtml
+} from "./chunk-XBIVBJS2.mjs";
+import "./chunk-HEBXNMVQ.mjs";
+
+// src/renderers/VueRenderer.ts
+var VueRenderer = class {
+  /**
+   * Creates an instance of VueRenderer.
+   *
+   * @param component - The Vue component to render.
+   * @param props - Initial props for the component.
+   * @param deps - Optional dependency injection for testing.
+   */
+  constructor(component, props, deps = {}) {
+    this.component = component;
+    this.props = props;
+    this.deps = deps;
+  }
+  /**
+   * Renders the Vue component to a static HTML string.
+   *
+   * This method performs dynamic imports of `vue` and `@vue/server-renderer`
+   * to ensure they are only loaded if this renderer is actually used.
+   *
+   * @param data - Runtime data to be merged with initial props.
+   * @returns A promise resolving to the rendered content.
+   * @throws {Error} If Vue dependencies cannot be loaded or rendering fails.
+   */
+  async render(data) {
+    const createSSRApp = this.deps.createSSRApp ?? (await import("vue")).createSSRApp;
+    const h = this.deps.h ?? (await import("vue")).h;
+    const renderToString = this.deps.renderToString ?? (await import("./server-renderer-7KWFSTPV.mjs")).renderToString;
+    const mergedProps = { ...this.props, ...data };
+    const app = createSSRApp({
+      render: () => h(this.component, mergedProps)
+    });
+    const html = await renderToString(app);
+    const fullHtml = html.startsWith("<!DOCTYPE") ? html : `<!DOCTYPE html>${html}`;
+    return {
+      html: fullHtml,
+      text: stripHtml(html)
+    };
+  }
+};
+export {
+  VueRenderer
+};