@gravito/flare 4.0.1 → 4.0.2

package/README.md

@@ -4,18 +4,32 @@
 
 **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 (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
+## ✨ Key Features
+
+- 🪐 **Galaxy-Ready Notifications**: Native integration with PlanetCore for universal user notification across all Satellites.
+- 📡 **Multi-Channel Delivery**: Seamlessly broadcast via **Mail**, **SMS**, **Slack**, **Discord**, and **Push Notifications**.
+- 🛠️ **Distributed Preference Management**: User-level notification settings that persist across the entire Galaxy.
+- 🛡️ **Reliability Stack**: Built-in exponential backoff, timeout protection, and automatic retries.
+- 🚀 **High Performance**: Parallel channel execution and batch sending optimized for Bun.
+- ⚙️ **Queue Integration**: Offload notification delivery to `@gravito/stream` with zero configuration.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Flare acts as the **Communication Flux (Nervous System Extension)**.
+
+- **Outbound Feedback**: Provides the primary mechanism for Satellites to communicate directly with users (e.g., "Your order has shipped" from the `Shop` Satellite).
+- **Preference Guard**: Ensures that user privacy and communication preferences are respected globally, regardless of which Satellite initiates the notification.
+- **Micro-Infrastructure Bridge**: Connects internal domain events to external communication providers (Twilio, AWS, SendGrid) without bloating Satellite logic.
+
+```mermaid
+graph LR
+    S[Satellite: Order] -- "Notify" --> Flare{Flare Orbit}
+    Flare -->|Check| Pref[User Preferences]
+    Flare -->|Route| C1[Mail: SES]
+    Flare -->|Route| C2[SMS: Twilio]
+    Flare -->|Route| C3[Social: Slack]
+    Flare -.->|Queue| Stream[Stream Orbit]
+```
 
 ## Installation
 
@@ -276,6 +290,14 @@ OrbitFlare.configure({
 })
 ```
 
+## 📚 Documentation
+
+Detailed guides and references for the Galaxy Architecture:
+
+- [🏗️ **Architecture Overview**](./README.md) — Multi-channel notification core.
+- [📡 **Notification Strategies**](./doc/NOTIFICATION_STRATEGIES.md) — **NEW**: Multi-channel routing, preferences, and queuing.
+- [⚙️ **Queue Support**](#-queue-support) — Asynchronous delivery with `@gravito/stream`.
+
 ## API Reference
 
 ### NotificationManager

package/dist/index.cjs

@@ -262,16 +262,23 @@ var TimeoutChannel = class {
     }
     const controller = new AbortController();
     const { signal } = controller;
+    let timeoutId;
+    let settled = false;
+    let handleExternalAbort;
     if (options?.signal) {
       if (options.signal.aborted) {
         throw new AbortError("Request was aborted before sending");
       }
-      options.signal.addEventListener("abort", () => {
+      handleExternalAbort = () => {
         controller.abort();
-      });
+      };
+      options.signal.addEventListener("abort", handleExternalAbort, { once: true });
     }
     const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => {
+      timeoutId = setTimeout(() => {
+        if (settled) {
+          return;
+        }
         if (this.config.onTimeout) {
           this.config.onTimeout(this.inner.constructor.name, notification);
         }
@@ -292,7 +299,17 @@ var TimeoutChannel = class {
       }
       throw error;
     });
-    return Promise.race([sendPromise, timeoutPromise]);
+    try {
+      return await Promise.race([sendPromise, timeoutPromise]);
+    } finally {
+      settled = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (options?.signal && handleExternalAbort) {
+        options.signal.removeEventListener("abort", handleExternalAbort);
+      }
+    }
   }
 };
 
@@ -797,7 +814,7 @@ var RateLimitMiddleware = class {
    * Create a new RateLimitMiddleware instance.
    *
    * @param config - Rate limit configuration for each channel
-   * @param store - Optional cache store for distributed rate limiting
+   * @param store - Optional cache store for distributed rate limiting (future use)
    *
    * @example
    * ```typescript
@@ -814,7 +831,7 @@ var RateLimitMiddleware = class {
    */
   constructor(config, store) {
     this.config = config;
-    this.store = store ?? new MemoryStore();
+    this.store = store || new MemoryStore();
     this.initializeBuckets();
   }
   /**
@@ -833,7 +850,6 @@ var RateLimitMiddleware = class {
   buckets = /* @__PURE__ */ new Map();
   /**
    * Cache store for distributed rate limiting.
-   * 分散式限流使用的快取儲存
    */
   store;
   /**
@@ -1853,6 +1869,7 @@ var OrbitFlare = class _OrbitFlare {
 };
 
 // src/templates/NotificationTemplate.ts
+var import_core = require("@gravito/core");
 var TemplatedNotification = class extends Notification {
   data = {};
   with(data) {
@@ -1881,6 +1898,33 @@ var TemplatedNotification = class extends Notification {
       attachments: template.attachments
     };
   }
+  /**
+   * 將 Markdown 模板渲染為 HTML。
+   * 先執行變數插值（`{{var}}`），再將 Markdown 轉為 HTML。
+   * 內建 XSS 防護：過濾 script、iframe、event handler 等危險 HTML。
+   *
+   * 適用於郵件、Slack 等富文本通知頻道。
+   *
+   * @param template - Markdown 格式的模板字串
+   * @returns 安全的 HTML 字串
+   *
+   * @example
+   * ```typescript
+   * const html = this.renderMarkdown('# Hello {{name}}')
+   * await sendEmail({ htmlBody: html })
+   * ```
+   */
+  renderMarkdown(template) {
+    if (!template) {
+      return "";
+    }
+    const interpolated = this.interpolate(template);
+    const md = (0, import_core.getMarkdownAdapter)();
+    const sanitizeCallbacks = (0, import_core.createHtmlRenderCallbacks)({
+      html: (rawHtml) => sanitizeHtml(rawHtml)
+    });
+    return md.render(interpolated, sanitizeCallbacks);
+  }
   interpolate(text) {
     return text.replace(/\{\{(\w+)\}\}/g, (_, key) => String(this.data[key] ?? `{{${key}}}`));
   }
@@ -1891,6 +1935,17 @@ var TemplatedNotification = class extends Notification {
     throw new Error("Notifiable does not have an email property");
   }
 };
+var DANGEROUS_TAGS = /^<\/?(?:script|iframe|object|embed|form|input|textarea|button|select|style|link|meta|base)\b[^>]*>$/i;
+var EVENT_HANDLER_ATTRS = /\s+on\w+\s*=/i;
+function sanitizeHtml(rawHtml) {
+  if (DANGEROUS_TAGS.test(rawHtml.trim())) {
+    return "";
+  }
+  if (EVENT_HANDLER_ATTRS.test(rawHtml)) {
+    return "";
+  }
+  return rawHtml;
+}
 
 // src/index.ts
 init_middleware();

package/dist/index.d.cts

@@ -1039,14 +1039,13 @@ declare class RateLimitMiddleware implements ChannelMiddleware {
     private buckets;
     /**
      * Cache store for distributed rate limiting.
-     * 分散式限流使用的快取儲存
      */
-    private store;
+    store: CacheStore;
     /**
      * Create a new RateLimitMiddleware instance.
      *
      * @param config - Rate limit configuration for each channel
-     * @param store - Optional cache store for distributed rate limiting
+     * @param store - Optional cache store for distributed rate limiting (future use)
      *
      * @example
      * ```typescript
@@ -1379,7 +1378,24 @@ declare abstract class TemplatedNotification extends Notification {
     protected slackTemplate?(): SlackTemplate;
     toMail(notifiable: Notifiable): MailMessage;
     toSlack(_notifiable: Notifiable): SlackMessage;
-    private interpolate;
+    /**
+     * 將 Markdown 模板渲染為 HTML。
+     * 先執行變數插值（`{{var}}`），再將 Markdown 轉為 HTML。
+     * 內建 XSS 防護：過濾 script、iframe、event handler 等危險 HTML。
+     *
+     * 適用於郵件、Slack 等富文本通知頻道。
+     *
+     * @param template - Markdown 格式的模板字串
+     * @returns 安全的 HTML 字串
+     *
+     * @example
+     * ```typescript
+     * const html = this.renderMarkdown('# Hello {{name}}')
+     * await sendEmail({ htmlBody: html })
+     * ```
+     */
+    protected renderMarkdown(template: string): string;
+    protected interpolate(text: string): string;
     private getRecipientEmail;
 }
 

package/dist/index.d.ts

@@ -1039,14 +1039,13 @@ declare class RateLimitMiddleware implements ChannelMiddleware {
     private buckets;
     /**
      * Cache store for distributed rate limiting.
-     * 分散式限流使用的快取儲存
      */
-    private store;
+    store: CacheStore;
     /**
      * Create a new RateLimitMiddleware instance.
      *
      * @param config - Rate limit configuration for each channel
-     * @param store - Optional cache store for distributed rate limiting
+     * @param store - Optional cache store for distributed rate limiting (future use)
      *
      * @example
      * ```typescript
@@ -1379,7 +1378,24 @@ declare abstract class TemplatedNotification extends Notification {
     protected slackTemplate?(): SlackTemplate;
     toMail(notifiable: Notifiable): MailMessage;
     toSlack(_notifiable: Notifiable): SlackMessage;
-    private interpolate;
+    /**
+     * 將 Markdown 模板渲染為 HTML。
+     * 先執行變數插值（`{{var}}`），再將 Markdown 轉為 HTML。
+     * 內建 XSS 防護：過濾 script、iframe、event handler 等危險 HTML。
+     *
+     * 適用於郵件、Slack 等富文本通知頻道。
+     *
+     * @param template - Markdown 格式的模板字串
+     * @returns 安全的 HTML 字串
+     *
+     * @example
+     * ```typescript
+     * const html = this.renderMarkdown('# Hello {{name}}')
+     * await sendEmail({ htmlBody: html })
+     * ```
+     */
+    protected renderMarkdown(template: string): string;
+    protected interpolate(text: string): string;
     private getRecipientEmail;
 }
 

package/dist/index.js

@@ -220,16 +220,23 @@ var TimeoutChannel = class {
     }
     const controller = new AbortController();
     const { signal } = controller;
+    let timeoutId;
+    let settled = false;
+    let handleExternalAbort;
     if (options?.signal) {
       if (options.signal.aborted) {
         throw new AbortError("Request was aborted before sending");
       }
-      options.signal.addEventListener("abort", () => {
+      handleExternalAbort = () => {
         controller.abort();
-      });
+      };
+      options.signal.addEventListener("abort", handleExternalAbort, { once: true });
     }
     const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => {
+      timeoutId = setTimeout(() => {
+        if (settled) {
+          return;
+        }
         if (this.config.onTimeout) {
           this.config.onTimeout(this.inner.constructor.name, notification);
         }
@@ -250,7 +257,17 @@ var TimeoutChannel = class {
       }
       throw error;
     });
-    return Promise.race([sendPromise, timeoutPromise]);
+    try {
+      return await Promise.race([sendPromise, timeoutPromise]);
+    } finally {
+      settled = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (options?.signal && handleExternalAbort) {
+        options.signal.removeEventListener("abort", handleExternalAbort);
+      }
+    }
   }
 };
 
@@ -755,7 +772,7 @@ var RateLimitMiddleware = class {
    * Create a new RateLimitMiddleware instance.
    *
    * @param config - Rate limit configuration for each channel
-   * @param store - Optional cache store for distributed rate limiting
+   * @param store - Optional cache store for distributed rate limiting (future use)
    *
    * @example
    * ```typescript
@@ -772,7 +789,7 @@ var RateLimitMiddleware = class {
    */
   constructor(config, store) {
     this.config = config;
-    this.store = store ?? new MemoryStore();
+    this.store = store || new MemoryStore();
     this.initializeBuckets();
   }
   /**
@@ -791,7 +808,6 @@ var RateLimitMiddleware = class {
   buckets = /* @__PURE__ */ new Map();
   /**
    * Cache store for distributed rate limiting.
-   * 分散式限流使用的快取儲存
    */
   store;
   /**
@@ -1811,6 +1827,7 @@ var OrbitFlare = class _OrbitFlare {
 };
 
 // src/templates/NotificationTemplate.ts
+import { createHtmlRenderCallbacks, getMarkdownAdapter } from "@gravito/core";
 var TemplatedNotification = class extends Notification {
   data = {};
   with(data) {
@@ -1839,6 +1856,33 @@ var TemplatedNotification = class extends Notification {
       attachments: template.attachments
     };
   }
+  /**
+   * 將 Markdown 模板渲染為 HTML。
+   * 先執行變數插值（`{{var}}`），再將 Markdown 轉為 HTML。
+   * 內建 XSS 防護：過濾 script、iframe、event handler 等危險 HTML。
+   *
+   * 適用於郵件、Slack 等富文本通知頻道。
+   *
+   * @param template - Markdown 格式的模板字串
+   * @returns 安全的 HTML 字串
+   *
+   * @example
+   * ```typescript
+   * const html = this.renderMarkdown('# Hello {{name}}')
+   * await sendEmail({ htmlBody: html })
+   * ```
+   */
+  renderMarkdown(template) {
+    if (!template) {
+      return "";
+    }
+    const interpolated = this.interpolate(template);
+    const md = getMarkdownAdapter();
+    const sanitizeCallbacks = createHtmlRenderCallbacks({
+      html: (rawHtml) => sanitizeHtml(rawHtml)
+    });
+    return md.render(interpolated, sanitizeCallbacks);
+  }
   interpolate(text) {
     return text.replace(/\{\{(\w+)\}\}/g, (_, key) => String(this.data[key] ?? `{{${key}}}`));
   }
@@ -1849,6 +1893,17 @@ var TemplatedNotification = class extends Notification {
     throw new Error("Notifiable does not have an email property");
   }
 };
+var DANGEROUS_TAGS = /^<\/?(?:script|iframe|object|embed|form|input|textarea|button|select|style|link|meta|base)\b[^>]*>$/i;
+var EVENT_HANDLER_ATTRS = /\s+on\w+\s*=/i;
+function sanitizeHtml(rawHtml) {
+  if (DANGEROUS_TAGS.test(rawHtml.trim())) {
+    return "";
+  }
+  if (EVENT_HANDLER_ATTRS.test(rawHtml)) {
+    return "";
+  }
+  return rawHtml;
+}
 
 // src/index.ts
 init_middleware();

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/flare",
-  "version": "4.0.1",
+  "sideEffects": false,
+  "version": "4.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -23,6 +24,7 @@
   ],
   "scripts": {
     "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
     "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
@@ -42,12 +44,12 @@
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
   "dependencies": {
-    "@gravito/core": "^1.6.1",
+    "@gravito/core": "^2.0.6",
     "@aws-sdk/client-sns": "^3.734.0"
   },
   "peerDependencies": {
-    "@gravito/stream": "^2.0.2",
-    "@gravito/signal": "^3.0.4",
+    "@gravito/stream": "^2.1.0",
+    "@gravito/signal": "^3.1.0",
     "@gravito/radiance": "^1.0.4"
   },
   "devDependencies": {