@gravito/flare 4.0.1 → 5.0.0

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

@@ -200,6 +200,8 @@ __export(index_exports, {
   AbortError: () => AbortError,
   BroadcastChannel: () => BroadcastChannel,
   DatabaseChannel: () => DatabaseChannel,
+  FlareError: () => FlareError,
+  FlareErrorCodes: () => FlareErrorCodes,
   LazyNotification: () => LazyNotification,
   MailChannel: () => MailChannel,
   MemoryStore: () => MemoryStore,
@@ -225,6 +227,37 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors/FlareError.ts
+var import_core = require("@gravito/core");
+var FlareError = class extends import_core.InfrastructureException {
+  /**
+   * Creates a new FlareError instance.
+   *
+   * @param code - The error code.
+   * @param message - The error message.
+   * @param options - Optional infrastructure exception options.
+   */
+  constructor(code, message, options = {}) {
+    const status = options.retryable ? 503 : 500;
+    super(status, code, { message, ...options });
+    this.name = "FlareError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/codes.ts
+var FlareErrorCodes = {
+  RATE_LIMIT_EXCEEDED: "flare.rate_limit_exceeded",
+  SERIALIZATION_FAILED: "flare.serialization_failed",
+  TEMPLATE_NOT_DEFINED: "flare.template_not_defined",
+  NOTIFIABLE_MISSING_EMAIL: "flare.notifiable_missing_email",
+  INVALID_CONFIG: "flare.invalid_config",
+  NOTIFICATION_METHOD_NOT_IMPLEMENTED: "flare.notification_method_not_implemented",
+  UNSUPPORTED_PROVIDER: "flare.unsupported_provider",
+  CREDENTIALS_MISSING: "flare.credentials_missing",
+  SEND_FAILED: "flare.send_failed"
+};
+
 // src/channels/TimeoutChannel.ts
 var TimeoutError = class extends Error {
   constructor(message) {
@@ -262,16 +295,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 +332,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);
+      }
+    }
   }
 };
 
@@ -305,7 +355,10 @@ var BroadcastChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, _options) => {
         if (!notification.toBroadcast) {
-          throw new Error("Notification does not implement toBroadcast method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toBroadcast method"
+          );
         }
         const broadcastNotification = notification.toBroadcast(notifiable);
         const notifiableId = notifiable.getNotifiableId();
@@ -339,7 +392,10 @@ var DatabaseChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, _options) => {
         if (!notification.toDatabase) {
-          throw new Error("Notification does not implement toDatabase method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toDatabase method"
+          );
         }
         const dbNotification = notification.toDatabase(notifiable);
         await this.dbService.insertNotification({
@@ -371,7 +427,10 @@ var MailChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, _options) => {
         if (!notification.toMail) {
-          throw new Error("Notification does not implement toMail method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toMail method"
+          );
         }
         const message = notification.toMail(notifiable);
         await this.mailService.send(message);
@@ -397,7 +456,10 @@ var SlackChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, options) => {
         if (!notification.toSlack) {
-          throw new Error("Notification does not implement toSlack method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toSlack method"
+          );
         }
         const slackMessage = notification.toSlack(notifiable);
         const response = await fetch(this.config.webhookUrl, {
@@ -416,7 +478,10 @@ var SlackChannel = class {
           // Pass AbortSignal to fetch
         });
         if (!response.ok) {
-          throw new Error(`Failed to send Slack notification: ${response.statusText}`);
+          throw new FlareError(
+            FlareErrorCodes.SEND_FAILED,
+            `Failed to send Slack notification: ${response.statusText}`
+          );
         }
       }
     };
@@ -440,7 +505,10 @@ var SmsChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, options) => {
         if (!notification.toSms) {
-          throw new Error("Notification does not implement toSms method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toSms method"
+          );
         }
         const smsMessage = notification.toSms(notifiable);
         switch (this.config.provider) {
@@ -451,7 +519,10 @@ var SmsChannel = class {
             await this.sendViaAwsSns(smsMessage, options?.signal);
             break;
           default:
-            throw new Error(`Unsupported SMS provider: ${this.config.provider}`);
+            throw new FlareError(
+              FlareErrorCodes.UNSUPPORTED_PROVIDER,
+              `Unsupported SMS provider: ${this.config.provider}`
+            );
         }
       }
     };
@@ -470,7 +541,10 @@ var SmsChannel = class {
    */
   async sendViaTwilio(message, signal) {
     if (!this.config.apiKey || !this.config.apiSecret) {
-      throw new Error("Twilio API key and secret are required");
+      throw new FlareError(
+        FlareErrorCodes.CREDENTIALS_MISSING,
+        "Twilio API key and secret are required"
+      );
     }
     const accountSid = this.config.apiKey;
     const authToken = this.config.apiSecret;
@@ -493,7 +567,7 @@ var SmsChannel = class {
     );
     if (!response.ok) {
       const error = await response.text();
-      throw new Error(`Failed to send SMS via Twilio: ${error}`);
+      throw new FlareError(FlareErrorCodes.SEND_FAILED, `Failed to send SMS via Twilio: ${error}`);
     }
   }
   /**
@@ -507,7 +581,8 @@ var SmsChannel = class {
       SNSClient = awsSns.SNSClient;
       PublishCommand = awsSns.PublishCommand;
     } catch {
-      throw new Error(
+      throw new FlareError(
+        FlareErrorCodes.UNSUPPORTED_PROVIDER,
         "AWS SNS SMS requires @aws-sdk/client-sns. Install it with: bun add @aws-sdk/client-sns"
       );
     }
@@ -538,7 +613,10 @@ var SmsChannel = class {
       await client.send(command, { abortSignal: signal });
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
-      throw new Error(`Failed to send SMS via AWS SNS: ${err.message}`);
+      throw new FlareError(
+        FlareErrorCodes.SEND_FAILED,
+        `Failed to send SMS via AWS SNS: ${err.message}`
+      );
     }
   }
 };
@@ -797,7 +875,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 +892,7 @@ var RateLimitMiddleware = class {
    */
   constructor(config, store) {
     this.config = config;
-    this.store = store ?? new MemoryStore();
+    this.store = store || new MemoryStore();
     this.initializeBuckets();
   }
   /**
@@ -833,7 +911,6 @@ var RateLimitMiddleware = class {
   buckets = /* @__PURE__ */ new Map();
   /**
    * Cache store for distributed rate limiting.
-   * 分散式限流使用的快取儲存
    */
   store;
   /**
@@ -891,7 +968,8 @@ var RateLimitMiddleware = class {
       if (bucket) {
         const allowed = bucket.tryConsume();
         if (!allowed) {
-          throw new Error(
+          throw new FlareError(
+            FlareErrorCodes.RATE_LIMIT_EXCEEDED,
             `Rate limit exceeded for channel '${channel}' (${window}ly limit). Please try again later.`
           );
         }
@@ -1194,7 +1272,8 @@ function checkSerializable(obj, path = "") {
 function assertSerializable(obj) {
   const result = checkSerializable(obj);
   if (!result.serializable) {
-    throw new Error(
+    throw new FlareError(
+      FlareErrorCodes.SERIALIZATION_FAILED,
       `\u7269\u4EF6\u5305\u542B\u4E0D\u53EF\u5E8F\u5217\u5316\u7684\u5C6C\u6027:
 \u554F\u984C\u8DEF\u5F91: ${result.problematicPaths.join(", ")}
 \u8A73\u7D30\u8CC7\u8A0A:
@@ -1713,24 +1792,30 @@ var OrbitFlare = class _OrbitFlare {
     if (options.enableSlack) {
       const slack = options.channels?.slack;
       if (!slack?.webhookUrl) {
-        throw new Error(
+        throw new FlareError(
+          FlareErrorCodes.INVALID_CONFIG,
           "[OrbitFlare] Slack channel enabled but webhookUrl not provided. Configure channels.slack.webhookUrl or set enableSlack to false."
         );
       }
       if (!this.isValidUrl(slack.webhookUrl)) {
-        throw new Error(`[OrbitFlare] Invalid Slack webhook URL: ${slack.webhookUrl}`);
+        throw new FlareError(
+          FlareErrorCodes.INVALID_CONFIG,
+          `[OrbitFlare] Invalid Slack webhook URL: ${slack.webhookUrl}`
+        );
       }
     }
     if (options.enableSms) {
       const sms = options.channels?.sms;
       if (!sms?.provider) {
-        throw new Error(
+        throw new FlareError(
+          FlareErrorCodes.INVALID_CONFIG,
           "[OrbitFlare] SMS channel enabled but provider not specified. Configure channels.sms.provider or set enableSms to false."
         );
       }
       const supportedProviders = ["twilio", "aws-sns"];
       if (!supportedProviders.includes(sms.provider)) {
-        throw new Error(
+        throw new FlareError(
+          FlareErrorCodes.UNSUPPORTED_PROVIDER,
           `[OrbitFlare] Unsupported SMS provider: ${sms.provider}. Supported providers: ${supportedProviders.join(", ")}`
         );
       }
@@ -1853,6 +1938,7 @@ var OrbitFlare = class _OrbitFlare {
 };
 
 // src/templates/NotificationTemplate.ts
+var import_core2 = require("@gravito/core");
 var TemplatedNotification = class extends Notification {
   data = {};
   with(data) {
@@ -1872,7 +1958,7 @@ var TemplatedNotification = class extends Notification {
   // Auto-implement toSlack
   toSlack(_notifiable) {
     if (!this.slackTemplate) {
-      throw new Error("slackTemplate not defined");
+      throw new FlareError(FlareErrorCodes.TEMPLATE_NOT_DEFINED, "slackTemplate not defined");
     }
     const template = this.slackTemplate();
     return {
@@ -1881,6 +1967,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_core2.getMarkdownAdapter)();
+    const sanitizeCallbacks = (0, import_core2.createHtmlRenderCallbacks)({
+      html: (rawHtml) => sanitizeHtml(rawHtml)
+    });
+    return md.render(interpolated, sanitizeCallbacks);
+  }
   interpolate(text) {
     return text.replace(/\{\{(\w+)\}\}/g, (_, key) => String(this.data[key] ?? `{{${key}}}`));
   }
@@ -1888,9 +2001,23 @@ var TemplatedNotification = class extends Notification {
     if ("email" in notifiable && typeof notifiable.email === "string") {
       return notifiable.email;
     }
-    throw new Error("Notifiable does not have an email property");
+    throw new FlareError(
+      FlareErrorCodes.NOTIFIABLE_MISSING_EMAIL,
+      "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();
@@ -1949,6 +2076,8 @@ var LazyNotification = class extends Notification {
   AbortError,
   BroadcastChannel,
   DatabaseChannel,
+  FlareError,
+  FlareErrorCodes,
   LazyNotification,
   MailChannel,
   MemoryStore,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PlanetCore, GravitoOrbit } from '@gravito/core';
+import { InfrastructureException, InfrastructureExceptionOptions, PlanetCore, GravitoOrbit } from '@gravito/core';
 
 /**
  * Notification system type definitions.
@@ -404,6 +404,59 @@ declare class BroadcastChannel implements NotificationChannel {
     send(notification: Notification, notifiable: Notifiable, options?: AbortableSendOptions): Promise<void>;
 }
 
+/**
+ * @fileoverview Flare error codes
+ *
+ * Namespaced error codes for the Flare notification module.
+ *
+ * @module @gravito/flare/errors
+ */
+/**
+ * Error codes for Flare module operations.
+ * Follows dot-separated namespace convention.
+ */
+declare const FlareErrorCodes: {
+    readonly RATE_LIMIT_EXCEEDED: "flare.rate_limit_exceeded";
+    readonly SERIALIZATION_FAILED: "flare.serialization_failed";
+    readonly TEMPLATE_NOT_DEFINED: "flare.template_not_defined";
+    readonly NOTIFIABLE_MISSING_EMAIL: "flare.notifiable_missing_email";
+    readonly INVALID_CONFIG: "flare.invalid_config";
+    readonly NOTIFICATION_METHOD_NOT_IMPLEMENTED: "flare.notification_method_not_implemented";
+    readonly UNSUPPORTED_PROVIDER: "flare.unsupported_provider";
+    readonly CREDENTIALS_MISSING: "flare.credentials_missing";
+    readonly SEND_FAILED: "flare.send_failed";
+};
+type FlareErrorCode = (typeof FlareErrorCodes)[keyof typeof FlareErrorCodes];
+
+/**
+ * @fileoverview Flare error types
+ *
+ * @module @gravito/flare/errors
+ */
+
+/**
+ * Base error class for Flare module.
+ *
+ * Provides structured error handling with error codes and messages.
+ * Extends InfrastructureException for unified error handling across Gravito.
+ *
+ * @example
+ * ```typescript
+ * throw new FlareError('flare.send_failed', 'Failed to send notification')
+ * ```
+ * @public
+ */
+declare class FlareError extends InfrastructureException {
+    /**
+     * Creates a new FlareError instance.
+     *
+     * @param code - The error code.
+     * @param message - The error message.
+     * @param options - Optional infrastructure exception options.
+     */
+    constructor(code: FlareErrorCode, message: string, options?: InfrastructureExceptionOptions);
+}
+
 /**
  * Database channel 配置選項。
  */
@@ -1039,14 +1092,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 +1431,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;
 }
 
@@ -1866,4 +1935,4 @@ declare class TokenBucket {
     private refill;
 }
 
-export { AbortError, type BatchResult, BroadcastChannel, type BroadcastNotification, type CacheStore, type ChannelFailurePayload, type ChannelHookPayload, type ChannelMiddleware, type ChannelRateLimitConfig, type ChannelSuccessPayload, DatabaseChannel, type DatabaseNotification, type FlareHookEvent, type FlareHookPayloads, type FlareHooks, type HookEmitter, LazyNotification, MailChannel, type MailChannelConfig, type MailMessage, type MailTemplate, MemoryStore, type MetricsSummary, MiddlewarePriority, type MiddlewarePriorityValue, type Notifiable, Notification, type NotificationBatchCompletePayload, type NotificationBatchStartPayload, type NotificationChannel, type NotificationCompletePayload, type NotificationHookPayload, NotificationManager, type NotificationMetric, NotificationMetricsCollector, type NotificationPreference, type NotificationResult, OrbitFlare, type OrbitFlareOptions, PreferenceMiddleware, type RateLimitConfig, RateLimitMiddleware, type RetryConfig, type SendOptions, type SendResult, type SerializationCheckResult, type ShouldQueue, type ShouldRetry, SlackChannel, type SlackChannelConfig, type SlackMessage, type SlackTemplate, SmsChannel, type SmsChannelConfig, type SmsMessage, type TemplateData, TemplatedNotification, TimeoutChannel, type TimeoutConfig, TimeoutError, TokenBucket, assertSerializable, checkSerializable, createHookEmitter, deepDeserialize, deepSerialize, toPrometheusFormat };
+export { AbortError, type BatchResult, BroadcastChannel, type BroadcastNotification, type CacheStore, type ChannelFailurePayload, type ChannelHookPayload, type ChannelMiddleware, type ChannelRateLimitConfig, type ChannelSuccessPayload, DatabaseChannel, type DatabaseNotification, FlareError, type FlareErrorCode, FlareErrorCodes, type FlareHookEvent, type FlareHookPayloads, type FlareHooks, type HookEmitter, LazyNotification, MailChannel, type MailChannelConfig, type MailMessage, type MailTemplate, MemoryStore, type MetricsSummary, MiddlewarePriority, type MiddlewarePriorityValue, type Notifiable, Notification, type NotificationBatchCompletePayload, type NotificationBatchStartPayload, type NotificationChannel, type NotificationCompletePayload, type NotificationHookPayload, NotificationManager, type NotificationMetric, NotificationMetricsCollector, type NotificationPreference, type NotificationResult, OrbitFlare, type OrbitFlareOptions, PreferenceMiddleware, type RateLimitConfig, RateLimitMiddleware, type RetryConfig, type SendOptions, type SendResult, type SerializationCheckResult, type ShouldQueue, type ShouldRetry, SlackChannel, type SlackChannelConfig, type SlackMessage, type SlackTemplate, SmsChannel, type SmsChannelConfig, type SmsMessage, type TemplateData, TemplatedNotification, TimeoutChannel, type TimeoutConfig, TimeoutError, TokenBucket, assertSerializable, checkSerializable, createHookEmitter, deepDeserialize, deepSerialize, toPrometheusFormat };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PlanetCore, GravitoOrbit } from '@gravito/core';
+import { InfrastructureException, InfrastructureExceptionOptions, PlanetCore, GravitoOrbit } from '@gravito/core';
 
 /**
  * Notification system type definitions.
@@ -404,6 +404,59 @@ declare class BroadcastChannel implements NotificationChannel {
     send(notification: Notification, notifiable: Notifiable, options?: AbortableSendOptions): Promise<void>;
 }
 
+/**
+ * @fileoverview Flare error codes
+ *
+ * Namespaced error codes for the Flare notification module.
+ *
+ * @module @gravito/flare/errors
+ */
+/**
+ * Error codes for Flare module operations.
+ * Follows dot-separated namespace convention.
+ */
+declare const FlareErrorCodes: {
+    readonly RATE_LIMIT_EXCEEDED: "flare.rate_limit_exceeded";
+    readonly SERIALIZATION_FAILED: "flare.serialization_failed";
+    readonly TEMPLATE_NOT_DEFINED: "flare.template_not_defined";
+    readonly NOTIFIABLE_MISSING_EMAIL: "flare.notifiable_missing_email";
+    readonly INVALID_CONFIG: "flare.invalid_config";
+    readonly NOTIFICATION_METHOD_NOT_IMPLEMENTED: "flare.notification_method_not_implemented";
+    readonly UNSUPPORTED_PROVIDER: "flare.unsupported_provider";
+    readonly CREDENTIALS_MISSING: "flare.credentials_missing";
+    readonly SEND_FAILED: "flare.send_failed";
+};
+type FlareErrorCode = (typeof FlareErrorCodes)[keyof typeof FlareErrorCodes];
+
+/**
+ * @fileoverview Flare error types
+ *
+ * @module @gravito/flare/errors
+ */
+
+/**
+ * Base error class for Flare module.
+ *
+ * Provides structured error handling with error codes and messages.
+ * Extends InfrastructureException for unified error handling across Gravito.
+ *
+ * @example
+ * ```typescript
+ * throw new FlareError('flare.send_failed', 'Failed to send notification')
+ * ```
+ * @public
+ */
+declare class FlareError extends InfrastructureException {
+    /**
+     * Creates a new FlareError instance.
+     *
+     * @param code - The error code.
+     * @param message - The error message.
+     * @param options - Optional infrastructure exception options.
+     */
+    constructor(code: FlareErrorCode, message: string, options?: InfrastructureExceptionOptions);
+}
+
 /**
  * Database channel 配置選項。
  */
@@ -1039,14 +1092,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 +1431,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;
 }
 
@@ -1866,4 +1935,4 @@ declare class TokenBucket {
     private refill;
 }
 
-export { AbortError, type BatchResult, BroadcastChannel, type BroadcastNotification, type CacheStore, type ChannelFailurePayload, type ChannelHookPayload, type ChannelMiddleware, type ChannelRateLimitConfig, type ChannelSuccessPayload, DatabaseChannel, type DatabaseNotification, type FlareHookEvent, type FlareHookPayloads, type FlareHooks, type HookEmitter, LazyNotification, MailChannel, type MailChannelConfig, type MailMessage, type MailTemplate, MemoryStore, type MetricsSummary, MiddlewarePriority, type MiddlewarePriorityValue, type Notifiable, Notification, type NotificationBatchCompletePayload, type NotificationBatchStartPayload, type NotificationChannel, type NotificationCompletePayload, type NotificationHookPayload, NotificationManager, type NotificationMetric, NotificationMetricsCollector, type NotificationPreference, type NotificationResult, OrbitFlare, type OrbitFlareOptions, PreferenceMiddleware, type RateLimitConfig, RateLimitMiddleware, type RetryConfig, type SendOptions, type SendResult, type SerializationCheckResult, type ShouldQueue, type ShouldRetry, SlackChannel, type SlackChannelConfig, type SlackMessage, type SlackTemplate, SmsChannel, type SmsChannelConfig, type SmsMessage, type TemplateData, TemplatedNotification, TimeoutChannel, type TimeoutConfig, TimeoutError, TokenBucket, assertSerializable, checkSerializable, createHookEmitter, deepDeserialize, deepSerialize, toPrometheusFormat };
+export { AbortError, type BatchResult, BroadcastChannel, type BroadcastNotification, type CacheStore, type ChannelFailurePayload, type ChannelHookPayload, type ChannelMiddleware, type ChannelRateLimitConfig, type ChannelSuccessPayload, DatabaseChannel, type DatabaseNotification, FlareError, type FlareErrorCode, FlareErrorCodes, type FlareHookEvent, type FlareHookPayloads, type FlareHooks, type HookEmitter, LazyNotification, MailChannel, type MailChannelConfig, type MailMessage, type MailTemplate, MemoryStore, type MetricsSummary, MiddlewarePriority, type MiddlewarePriorityValue, type Notifiable, Notification, type NotificationBatchCompletePayload, type NotificationBatchStartPayload, type NotificationChannel, type NotificationCompletePayload, type NotificationHookPayload, NotificationManager, type NotificationMetric, NotificationMetricsCollector, type NotificationPreference, type NotificationResult, OrbitFlare, type OrbitFlareOptions, PreferenceMiddleware, type RateLimitConfig, RateLimitMiddleware, type RetryConfig, type SendOptions, type SendResult, type SerializationCheckResult, type ShouldQueue, type ShouldRetry, SlackChannel, type SlackChannelConfig, type SlackMessage, type SlackTemplate, SmsChannel, type SmsChannelConfig, type SmsMessage, type TemplateData, TemplatedNotification, TimeoutChannel, type TimeoutConfig, TimeoutError, TokenBucket, assertSerializable, checkSerializable, createHookEmitter, deepDeserialize, deepSerialize, toPrometheusFormat };

package/dist/index.js

@@ -183,6 +183,37 @@ var init_PreferenceMiddleware = __esm({
   }
 });
 
+// src/errors/FlareError.ts
+import { InfrastructureException } from "@gravito/core";
+var FlareError = class extends InfrastructureException {
+  /**
+   * Creates a new FlareError instance.
+   *
+   * @param code - The error code.
+   * @param message - The error message.
+   * @param options - Optional infrastructure exception options.
+   */
+  constructor(code, message, options = {}) {
+    const status = options.retryable ? 503 : 500;
+    super(status, code, { message, ...options });
+    this.name = "FlareError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/codes.ts
+var FlareErrorCodes = {
+  RATE_LIMIT_EXCEEDED: "flare.rate_limit_exceeded",
+  SERIALIZATION_FAILED: "flare.serialization_failed",
+  TEMPLATE_NOT_DEFINED: "flare.template_not_defined",
+  NOTIFIABLE_MISSING_EMAIL: "flare.notifiable_missing_email",
+  INVALID_CONFIG: "flare.invalid_config",
+  NOTIFICATION_METHOD_NOT_IMPLEMENTED: "flare.notification_method_not_implemented",
+  UNSUPPORTED_PROVIDER: "flare.unsupported_provider",
+  CREDENTIALS_MISSING: "flare.credentials_missing",
+  SEND_FAILED: "flare.send_failed"
+};
+
 // src/channels/TimeoutChannel.ts
 var TimeoutError = class extends Error {
   constructor(message) {
@@ -220,16 +251,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 +288,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);
+      }
+    }
   }
 };
 
@@ -263,7 +311,10 @@ var BroadcastChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, _options) => {
         if (!notification.toBroadcast) {
-          throw new Error("Notification does not implement toBroadcast method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toBroadcast method"
+          );
         }
         const broadcastNotification = notification.toBroadcast(notifiable);
         const notifiableId = notifiable.getNotifiableId();
@@ -297,7 +348,10 @@ var DatabaseChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, _options) => {
         if (!notification.toDatabase) {
-          throw new Error("Notification does not implement toDatabase method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toDatabase method"
+          );
         }
         const dbNotification = notification.toDatabase(notifiable);
         await this.dbService.insertNotification({
@@ -329,7 +383,10 @@ var MailChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, _options) => {
         if (!notification.toMail) {
-          throw new Error("Notification does not implement toMail method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toMail method"
+          );
         }
         const message = notification.toMail(notifiable);
         await this.mailService.send(message);
@@ -355,7 +412,10 @@ var SlackChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, options) => {
         if (!notification.toSlack) {
-          throw new Error("Notification does not implement toSlack method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toSlack method"
+          );
         }
         const slackMessage = notification.toSlack(notifiable);
         const response = await fetch(this.config.webhookUrl, {
@@ -374,7 +434,10 @@ var SlackChannel = class {
           // Pass AbortSignal to fetch
         });
         if (!response.ok) {
-          throw new Error(`Failed to send Slack notification: ${response.statusText}`);
+          throw new FlareError(
+            FlareErrorCodes.SEND_FAILED,
+            `Failed to send Slack notification: ${response.statusText}`
+          );
         }
       }
     };
@@ -398,7 +461,10 @@ var SmsChannel = class {
     const innerChannel = {
       send: async (notification, notifiable, options) => {
         if (!notification.toSms) {
-          throw new Error("Notification does not implement toSms method");
+          throw new FlareError(
+            FlareErrorCodes.NOTIFICATION_METHOD_NOT_IMPLEMENTED,
+            "Notification does not implement toSms method"
+          );
         }
         const smsMessage = notification.toSms(notifiable);
         switch (this.config.provider) {
@@ -409,7 +475,10 @@ var SmsChannel = class {
             await this.sendViaAwsSns(smsMessage, options?.signal);
             break;
           default:
-            throw new Error(`Unsupported SMS provider: ${this.config.provider}`);
+            throw new FlareError(
+              FlareErrorCodes.UNSUPPORTED_PROVIDER,
+              `Unsupported SMS provider: ${this.config.provider}`
+            );
         }
       }
     };
@@ -428,7 +497,10 @@ var SmsChannel = class {
    */
   async sendViaTwilio(message, signal) {
     if (!this.config.apiKey || !this.config.apiSecret) {
-      throw new Error("Twilio API key and secret are required");
+      throw new FlareError(
+        FlareErrorCodes.CREDENTIALS_MISSING,
+        "Twilio API key and secret are required"
+      );
     }
     const accountSid = this.config.apiKey;
     const authToken = this.config.apiSecret;
@@ -451,7 +523,7 @@ var SmsChannel = class {
     );
     if (!response.ok) {
       const error = await response.text();
-      throw new Error(`Failed to send SMS via Twilio: ${error}`);
+      throw new FlareError(FlareErrorCodes.SEND_FAILED, `Failed to send SMS via Twilio: ${error}`);
     }
   }
   /**
@@ -465,7 +537,8 @@ var SmsChannel = class {
       SNSClient = awsSns.SNSClient;
       PublishCommand = awsSns.PublishCommand;
     } catch {
-      throw new Error(
+      throw new FlareError(
+        FlareErrorCodes.UNSUPPORTED_PROVIDER,
         "AWS SNS SMS requires @aws-sdk/client-sns. Install it with: bun add @aws-sdk/client-sns"
       );
     }
@@ -496,7 +569,10 @@ var SmsChannel = class {
       await client.send(command, { abortSignal: signal });
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
-      throw new Error(`Failed to send SMS via AWS SNS: ${err.message}`);
+      throw new FlareError(
+        FlareErrorCodes.SEND_FAILED,
+        `Failed to send SMS via AWS SNS: ${err.message}`
+      );
     }
   }
 };
@@ -755,7 +831,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 +848,7 @@ var RateLimitMiddleware = class {
    */
   constructor(config, store) {
     this.config = config;
-    this.store = store ?? new MemoryStore();
+    this.store = store || new MemoryStore();
     this.initializeBuckets();
   }
   /**
@@ -791,7 +867,6 @@ var RateLimitMiddleware = class {
   buckets = /* @__PURE__ */ new Map();
   /**
    * Cache store for distributed rate limiting.
-   * 分散式限流使用的快取儲存
    */
   store;
   /**
@@ -849,7 +924,8 @@ var RateLimitMiddleware = class {
       if (bucket) {
         const allowed = bucket.tryConsume();
         if (!allowed) {
-          throw new Error(
+          throw new FlareError(
+            FlareErrorCodes.RATE_LIMIT_EXCEEDED,
             `Rate limit exceeded for channel '${channel}' (${window}ly limit). Please try again later.`
           );
         }
@@ -1152,7 +1228,8 @@ function checkSerializable(obj, path = "") {
 function assertSerializable(obj) {
   const result = checkSerializable(obj);
   if (!result.serializable) {
-    throw new Error(
+    throw new FlareError(
+      FlareErrorCodes.SERIALIZATION_FAILED,
       `\u7269\u4EF6\u5305\u542B\u4E0D\u53EF\u5E8F\u5217\u5316\u7684\u5C6C\u6027:
 \u554F\u984C\u8DEF\u5F91: ${result.problematicPaths.join(", ")}
 \u8A73\u7D30\u8CC7\u8A0A:
@@ -1671,24 +1748,30 @@ var OrbitFlare = class _OrbitFlare {
     if (options.enableSlack) {
       const slack = options.channels?.slack;
       if (!slack?.webhookUrl) {
-        throw new Error(
+        throw new FlareError(
+          FlareErrorCodes.INVALID_CONFIG,
           "[OrbitFlare] Slack channel enabled but webhookUrl not provided. Configure channels.slack.webhookUrl or set enableSlack to false."
         );
       }
       if (!this.isValidUrl(slack.webhookUrl)) {
-        throw new Error(`[OrbitFlare] Invalid Slack webhook URL: ${slack.webhookUrl}`);
+        throw new FlareError(
+          FlareErrorCodes.INVALID_CONFIG,
+          `[OrbitFlare] Invalid Slack webhook URL: ${slack.webhookUrl}`
+        );
       }
     }
     if (options.enableSms) {
       const sms = options.channels?.sms;
       if (!sms?.provider) {
-        throw new Error(
+        throw new FlareError(
+          FlareErrorCodes.INVALID_CONFIG,
           "[OrbitFlare] SMS channel enabled but provider not specified. Configure channels.sms.provider or set enableSms to false."
         );
       }
       const supportedProviders = ["twilio", "aws-sns"];
       if (!supportedProviders.includes(sms.provider)) {
-        throw new Error(
+        throw new FlareError(
+          FlareErrorCodes.UNSUPPORTED_PROVIDER,
           `[OrbitFlare] Unsupported SMS provider: ${sms.provider}. Supported providers: ${supportedProviders.join(", ")}`
         );
       }
@@ -1811,6 +1894,7 @@ var OrbitFlare = class _OrbitFlare {
 };
 
 // src/templates/NotificationTemplate.ts
+import { createHtmlRenderCallbacks, getMarkdownAdapter } from "@gravito/core";
 var TemplatedNotification = class extends Notification {
   data = {};
   with(data) {
@@ -1830,7 +1914,7 @@ var TemplatedNotification = class extends Notification {
   // Auto-implement toSlack
   toSlack(_notifiable) {
     if (!this.slackTemplate) {
-      throw new Error("slackTemplate not defined");
+      throw new FlareError(FlareErrorCodes.TEMPLATE_NOT_DEFINED, "slackTemplate not defined");
     }
     const template = this.slackTemplate();
     return {
@@ -1839,6 +1923,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}}}`));
   }
@@ -1846,9 +1957,23 @@ var TemplatedNotification = class extends Notification {
     if ("email" in notifiable && typeof notifiable.email === "string") {
       return notifiable.email;
     }
-    throw new Error("Notifiable does not have an email property");
+    throw new FlareError(
+      FlareErrorCodes.NOTIFIABLE_MISSING_EMAIL,
+      "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();
@@ -1906,6 +2031,8 @@ export {
   AbortError,
   BroadcastChannel,
   DatabaseChannel,
+  FlareError,
+  FlareErrorCodes,
   LazyNotification,
   MailChannel,
   MemoryStore,

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/flare",
-  "version": "4.0.1",
+  "sideEffects": false,
+  "version": "5.0.0",
   "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,13 +44,13 @@
   "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/radiance": "^1.0.4"
+    "@gravito/stream": "^3.0.0",
+    "@gravito/signal": "^4.0.0",
+    "@gravito/radiance": "^2.0.0"
   },
   "devDependencies": {
     "bun-types": "latest",