@gravito/signal 3.1.2 → 4.0.0

package/dist/OrbitSignal.d.ts

@@ -200,6 +200,12 @@ export declare class OrbitSignal implements GravitoOrbit {
      * ```
      */
     install(core: PlanetCore): void;
+    /**
+     * Gracefully release transport and dev resources.
+     *
+     * Called during shutdown. Detects closeable transports via type narrowing (no `as any`).
+     */
+    private cleanup;
     /**
      * Internal: Handle processed webhook.
      */

package/dist/errors/codes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Structured error codes for @gravito/signal mail operations.
+ * Follows fortify's dot-separated namespace convention.
+ *
+ * NOTE: This replaces MailErrorCode enum for new code.
+ * The existing enum in ../errors.ts remains until Phase 18-19 migration.
+ *
+ * @public
+ */
+export declare const MailErrorCodes: {
+    readonly CONNECTION_FAILED: "mail.connection_failed";
+    readonly AUTH_FAILED: "mail.auth_failed";
+    readonly RECIPIENT_REJECTED: "mail.recipient_rejected";
+    readonly MESSAGE_REJECTED: "mail.message_rejected";
+    readonly RATE_LIMIT: "mail.rate_limit";
+    readonly SEND_FAILED: "mail.send_failed";
+    readonly UNKNOWN: "mail.unknown";
+};
+export type MailErrorCode = (typeof MailErrorCodes)[keyof typeof MailErrorCodes];

package/dist/errors.d.ts

@@ -1,9 +1,10 @@
+import { InfrastructureException } from '@gravito/core';
+import { type MailErrorCode as MailErrorCodeType } from './errors/codes';
 /**
- * Mail transport error codes.
- *
- * Categorizes common failure modes in the mail delivery process to allow
- * for programmatic handling (e.g., retries on rate limits).
+ * Mail transport error codes (legacy enum — kept for backward compat).
+ * New code should use MailErrorCodes from './errors/codes' instead.
  *
+ * @deprecated Use MailErrorCodes from './errors/codes'
  * @public
  * @since 3.1.0
  */
@@ -24,8 +25,9 @@ export declare enum MailErrorCode {
 /**
  * Error class for mail transport failures.
  *
- * Provides structured error information for mail sending failures,
- * including error codes and original cause tracking for debugging.
+ * Extends InfrastructureException for unified error handling across Gravito.
+ * Carries a `retryable` flag indicating whether the operation can be retried,
+ * and preserves backward compat with the legacy MailErrorCode enum via `.legacyCode`.
  *
  * @example
  * ```typescript
@@ -39,14 +41,19 @@ export declare enum MailErrorCode {
  * @public
  * @since 3.1.0
  */
-export declare class MailTransportError extends Error {
-    readonly code: MailErrorCode;
-    readonly cause?: Error;
+export declare class MailTransportError extends InfrastructureException {
+    /**
+     * Legacy enum code — preserved for backward compat with callers that switch on MailErrorCode.
+     * @deprecated Prefer checking `.code` (mail.* namespaced string) instead.
+     */
+    readonly legacyCode: MailErrorCode;
     /**
      * Create a new mail transport error.
      *
+     * Accepts both the legacy MailErrorCode enum and new mail.* namespaced string codes.
+     *
      * @param message - Human-readable error message
-     * @param code - Categorized error code
+     * @param code - Categorized error code (legacy enum or new mail.* string)
      * @param cause - Original error that caused this failure
      *
      * @example
@@ -54,5 +61,5 @@ export declare class MailTransportError extends Error {
      * const error = new MailTransportError('Auth failed', MailErrorCode.AUTH_FAILED);
      * ```
      */
-    constructor(message: string, code: MailErrorCode, cause?: Error);
+    constructor(message: string, code?: MailErrorCode | MailErrorCodeType, cause?: Error);
 }

package/dist/index.cjs

@@ -59693,6 +59693,7 @@ __export(index_exports, {
   HtmlRenderer: () => HtmlRenderer,
   LogTransport: () => LogTransport,
   MailErrorCode: () => MailErrorCode,
+  MailErrorCodes: () => MailErrorCodes,
   MailTransportError: () => MailTransportError,
   Mailable: () => Mailable,
   MemoryTransport: () => MemoryTransport,
@@ -59838,6 +59839,20 @@ var DevMailbox = class {
   }
 };
 
+// src/errors.ts
+var import_core = require("@gravito/core");
+
+// src/errors/codes.ts
+var MailErrorCodes = {
+  CONNECTION_FAILED: "mail.connection_failed",
+  AUTH_FAILED: "mail.auth_failed",
+  RECIPIENT_REJECTED: "mail.recipient_rejected",
+  MESSAGE_REJECTED: "mail.message_rejected",
+  RATE_LIMIT: "mail.rate_limit",
+  SEND_FAILED: "mail.send_failed",
+  UNKNOWN: "mail.unknown"
+};
+
 // src/errors.ts
 var MailErrorCode = /* @__PURE__ */ ((MailErrorCode2) => {
   MailErrorCode2["CONNECTION_FAILED"] = "CONNECTION_FAILED";
@@ -59848,12 +59863,31 @@ var MailErrorCode = /* @__PURE__ */ ((MailErrorCode2) => {
   MailErrorCode2["UNKNOWN"] = "UNKNOWN";
   return MailErrorCode2;
 })(MailErrorCode || {});
-var MailTransportError = class _MailTransportError extends Error {
+var legacyToNewCode = {
+  ["CONNECTION_FAILED" /* CONNECTION_FAILED */]: MailErrorCodes.CONNECTION_FAILED,
+  ["AUTH_FAILED" /* AUTH_FAILED */]: MailErrorCodes.AUTH_FAILED,
+  ["RECIPIENT_REJECTED" /* RECIPIENT_REJECTED */]: MailErrorCodes.RECIPIENT_REJECTED,
+  ["MESSAGE_REJECTED" /* MESSAGE_REJECTED */]: MailErrorCodes.MESSAGE_REJECTED,
+  ["RATE_LIMIT" /* RATE_LIMIT */]: MailErrorCodes.RATE_LIMIT,
+  ["UNKNOWN" /* UNKNOWN */]: MailErrorCodes.UNKNOWN
+};
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  MailErrorCodes.CONNECTION_FAILED,
+  MailErrorCodes.RATE_LIMIT
+]);
+var MailTransportError = class _MailTransportError extends import_core.InfrastructureException {
+  /**
+   * Legacy enum code — preserved for backward compat with callers that switch on MailErrorCode.
+   * @deprecated Prefer checking `.code` (mail.* namespaced string) instead.
+   */
+  legacyCode;
   /**
    * Create a new mail transport error.
    *
+   * Accepts both the legacy MailErrorCode enum and new mail.* namespaced string codes.
+   *
    * @param message - Human-readable error message
-   * @param code - Categorized error code
+   * @param code - Categorized error code (legacy enum or new mail.* string)
    * @param cause - Original error that caused this failure
    *
    * @example
@@ -59861,11 +59895,16 @@ var MailTransportError = class _MailTransportError extends Error {
    * const error = new MailTransportError('Auth failed', MailErrorCode.AUTH_FAILED);
    * ```
    */
-  constructor(message, code, cause) {
-    super(message);
-    this.code = code;
-    this.cause = cause;
+  constructor(message, code = "UNKNOWN" /* UNKNOWN */, cause) {
+    const newCode = typeof code === "string" && code.startsWith("mail.") ? code : legacyToNewCode[code] ?? MailErrorCodes.UNKNOWN;
+    super(502, newCode, {
+      message,
+      cause,
+      retryable: RETRYABLE_CODES.has(newCode)
+    });
     this.name = "MailTransportError";
+    this.legacyCode = typeof code === "string" && code.startsWith("mail.") ? Object.entries(legacyToNewCode).find(([, v]) => v === code)?.[0] ?? "UNKNOWN" /* UNKNOWN */ : code;
+    Object.setPrototypeOf(this, new.target.prototype);
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _MailTransportError);
     }
@@ -60851,6 +60890,9 @@ var MemoryTransport = class {
 };
 
 // src/OrbitSignal.ts
+function isCloseable(obj) {
+  return typeof obj === "object" && obj !== null && "close" in obj && typeof obj.close === "function";
+}
 var OrbitSignal = class {
   config;
   devMailbox;
@@ -60916,6 +60958,34 @@ var OrbitSignal = class {
         }
       });
     }
+    core.hooks.doAction("core:shutdown", async () => {
+      const DEADLINE_MS = 5e3;
+      const deadline = new Promise(
+        (_, reject) => setTimeout(
+          () => reject(new Error("[OrbitSignal] Shutdown deadline exceeded (5s)")),
+          DEADLINE_MS
+        )
+      );
+      try {
+        await Promise.race([this.cleanup(), deadline]);
+      } catch (err) {
+        core.logger.warn("[OrbitSignal] Forced shutdown:", err);
+      }
+    });
+  }
+  /**
+   * Gracefully release transport and dev resources.
+   *
+   * Called during shutdown. Detects closeable transports via type narrowing (no `as any`).
+   */
+  async cleanup() {
+    if (this.devMailbox) {
+      this.devMailbox = void 0;
+    }
+    const transport = this.config.transport;
+    if (isCloseable(transport)) {
+      await transport.close();
+    }
   }
   /**
    * Internal: Handle processed webhook.
@@ -61111,6 +61181,7 @@ init_ReactMjmlRenderer();
 init_VueMjmlRenderer();
 
 // src/transports/BaseTransport.ts
+var import_resilience = require("@gravito/resilience");
 var BaseTransport = class {
   options;
   /**
@@ -61126,14 +61197,14 @@ var BaseTransport = class {
     };
   }
   /**
-   * Orchestrates the message delivery with retry logic.
+   * Orchestrates the message delivery with automatic retry via @gravito/resilience.
    *
-   * This method wraps the concrete `doSend` implementation in a retry loop.
-   * It tracks the last error encountered to provide context if all retries fail.
+   * Delegates to `doSend()` and retries on retryable InfrastructureException errors
+   * (CONNECTION_FAILED, RATE_LIMIT). Non-retryable errors surface immediately.
    *
    * @param message - The message to be delivered.
    * @returns A promise that resolves when the message is successfully sent.
-   * @throws {MailTransportError} If the message cannot be sent after the maximum number of retries.
+   * @throws {MailTransportError} If the message cannot be sent after the maximum number of attempts.
    *
    * @example
    * ```typescript
@@ -61146,33 +61217,22 @@ var BaseTransport = class {
    * ```
    */
   async send(message) {
-    let lastError;
-    let delay = this.options.retryDelay;
-    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
-      try {
-        return await this.doSend(message);
-      } catch (error) {
-        lastError = error;
-        if (attempt < this.options.maxRetries) {
-          await this.sleep(delay);
-          delay *= this.options.backoffMultiplier;
-        }
+    try {
+      await (0, import_resilience.withRetry)(() => this.doSend(message), {
+        idempotent: true,
+        maxAttempts: this.options.maxRetries,
+        baseDelayMs: this.options.retryDelay
+      });
+    } catch (error) {
+      if (error instanceof MailTransportError) {
+        throw error;
       }
+      throw new MailTransportError(
+        `Mail sending failed after ${this.options.maxRetries} retries`,
+        "UNKNOWN" /* UNKNOWN */,
+        error
+      );
     }
-    throw new MailTransportError(
-      `Mail sending failed after ${this.options.maxRetries} retries`,
-      "UNKNOWN" /* UNKNOWN */,
-      lastError
-    );
-  }
-  /**
-   * Utility method to pause execution for a given duration.
-   *
-   * @param ms - Milliseconds to sleep.
-   * @returns A promise that resolves after the delay.
-   */
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
   }
 };
 
@@ -61452,6 +61512,7 @@ var SesWebhookDriver = class {
   HtmlRenderer,
   LogTransport,
   MailErrorCode,
+  MailErrorCodes,
   MailTransportError,
   Mailable,
   MemoryTransport,

package/dist/index.d.ts

@@ -54,6 +54,7 @@ export { DevMailbox, type MailboxEntry } from './dev/DevMailbox';
  * @public
  */
 export { MailErrorCode, MailTransportError } from './errors';
+export { MailErrorCodes } from './errors/codes';
 /**
  * Mail lifecycle event types and handlers.
  *

package/dist/index.js

@@ -59693,6 +59693,7 @@ __export(index_exports, {
   HtmlRenderer: () => HtmlRenderer,
   LogTransport: () => LogTransport,
   MailErrorCode: () => MailErrorCode,
+  MailErrorCodes: () => MailErrorCodes,
   MailTransportError: () => MailTransportError,
   Mailable: () => Mailable,
   MemoryTransport: () => MemoryTransport,
@@ -59838,6 +59839,20 @@ var DevMailbox = class {
   }
 };
 
+// src/errors.ts
+var import_core = require("@gravito/core");
+
+// src/errors/codes.ts
+var MailErrorCodes = {
+  CONNECTION_FAILED: "mail.connection_failed",
+  AUTH_FAILED: "mail.auth_failed",
+  RECIPIENT_REJECTED: "mail.recipient_rejected",
+  MESSAGE_REJECTED: "mail.message_rejected",
+  RATE_LIMIT: "mail.rate_limit",
+  SEND_FAILED: "mail.send_failed",
+  UNKNOWN: "mail.unknown"
+};
+
 // src/errors.ts
 var MailErrorCode = /* @__PURE__ */ ((MailErrorCode2) => {
   MailErrorCode2["CONNECTION_FAILED"] = "CONNECTION_FAILED";
@@ -59848,12 +59863,31 @@ var MailErrorCode = /* @__PURE__ */ ((MailErrorCode2) => {
   MailErrorCode2["UNKNOWN"] = "UNKNOWN";
   return MailErrorCode2;
 })(MailErrorCode || {});
-var MailTransportError = class _MailTransportError extends Error {
+var legacyToNewCode = {
+  ["CONNECTION_FAILED" /* CONNECTION_FAILED */]: MailErrorCodes.CONNECTION_FAILED,
+  ["AUTH_FAILED" /* AUTH_FAILED */]: MailErrorCodes.AUTH_FAILED,
+  ["RECIPIENT_REJECTED" /* RECIPIENT_REJECTED */]: MailErrorCodes.RECIPIENT_REJECTED,
+  ["MESSAGE_REJECTED" /* MESSAGE_REJECTED */]: MailErrorCodes.MESSAGE_REJECTED,
+  ["RATE_LIMIT" /* RATE_LIMIT */]: MailErrorCodes.RATE_LIMIT,
+  ["UNKNOWN" /* UNKNOWN */]: MailErrorCodes.UNKNOWN
+};
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  MailErrorCodes.CONNECTION_FAILED,
+  MailErrorCodes.RATE_LIMIT
+]);
+var MailTransportError = class _MailTransportError extends import_core.InfrastructureException {
+  /**
+   * Legacy enum code — preserved for backward compat with callers that switch on MailErrorCode.
+   * @deprecated Prefer checking `.code` (mail.* namespaced string) instead.
+   */
+  legacyCode;
   /**
    * Create a new mail transport error.
    *
+   * Accepts both the legacy MailErrorCode enum and new mail.* namespaced string codes.
+   *
    * @param message - Human-readable error message
-   * @param code - Categorized error code
+   * @param code - Categorized error code (legacy enum or new mail.* string)
    * @param cause - Original error that caused this failure
    *
    * @example
@@ -59861,11 +59895,16 @@ var MailTransportError = class _MailTransportError extends Error {
    * const error = new MailTransportError('Auth failed', MailErrorCode.AUTH_FAILED);
    * ```
    */
-  constructor(message, code, cause) {
-    super(message);
-    this.code = code;
-    this.cause = cause;
+  constructor(message, code = "UNKNOWN" /* UNKNOWN */, cause) {
+    const newCode = typeof code === "string" && code.startsWith("mail.") ? code : legacyToNewCode[code] ?? MailErrorCodes.UNKNOWN;
+    super(502, newCode, {
+      message,
+      cause,
+      retryable: RETRYABLE_CODES.has(newCode)
+    });
     this.name = "MailTransportError";
+    this.legacyCode = typeof code === "string" && code.startsWith("mail.") ? Object.entries(legacyToNewCode).find(([, v]) => v === code)?.[0] ?? "UNKNOWN" /* UNKNOWN */ : code;
+    Object.setPrototypeOf(this, new.target.prototype);
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _MailTransportError);
     }
@@ -60851,6 +60890,9 @@ var MemoryTransport = class {
 };
 
 // src/OrbitSignal.ts
+function isCloseable(obj) {
+  return typeof obj === "object" && obj !== null && "close" in obj && typeof obj.close === "function";
+}
 var OrbitSignal = class {
   config;
   devMailbox;
@@ -60916,6 +60958,34 @@ var OrbitSignal = class {
         }
       });
     }
+    core.hooks.doAction("core:shutdown", async () => {
+      const DEADLINE_MS = 5e3;
+      const deadline = new Promise(
+        (_, reject) => setTimeout(
+          () => reject(new Error("[OrbitSignal] Shutdown deadline exceeded (5s)")),
+          DEADLINE_MS
+        )
+      );
+      try {
+        await Promise.race([this.cleanup(), deadline]);
+      } catch (err) {
+        core.logger.warn("[OrbitSignal] Forced shutdown:", err);
+      }
+    });
+  }
+  /**
+   * Gracefully release transport and dev resources.
+   *
+   * Called during shutdown. Detects closeable transports via type narrowing (no `as any`).
+   */
+  async cleanup() {
+    if (this.devMailbox) {
+      this.devMailbox = void 0;
+    }
+    const transport = this.config.transport;
+    if (isCloseable(transport)) {
+      await transport.close();
+    }
   }
   /**
    * Internal: Handle processed webhook.
@@ -61111,6 +61181,7 @@ init_ReactMjmlRenderer();
 init_VueMjmlRenderer();
 
 // src/transports/BaseTransport.ts
+var import_resilience = require("@gravito/resilience");
 var BaseTransport = class {
   options;
   /**
@@ -61126,14 +61197,14 @@ var BaseTransport = class {
     };
   }
   /**
-   * Orchestrates the message delivery with retry logic.
+   * Orchestrates the message delivery with automatic retry via @gravito/resilience.
    *
-   * This method wraps the concrete `doSend` implementation in a retry loop.
-   * It tracks the last error encountered to provide context if all retries fail.
+   * Delegates to `doSend()` and retries on retryable InfrastructureException errors
+   * (CONNECTION_FAILED, RATE_LIMIT). Non-retryable errors surface immediately.
    *
    * @param message - The message to be delivered.
    * @returns A promise that resolves when the message is successfully sent.
-   * @throws {MailTransportError} If the message cannot be sent after the maximum number of retries.
+   * @throws {MailTransportError} If the message cannot be sent after the maximum number of attempts.
    *
    * @example
    * ```typescript
@@ -61146,33 +61217,22 @@ var BaseTransport = class {
    * ```
    */
   async send(message) {
-    let lastError;
-    let delay = this.options.retryDelay;
-    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
-      try {
-        return await this.doSend(message);
-      } catch (error) {
-        lastError = error;
-        if (attempt < this.options.maxRetries) {
-          await this.sleep(delay);
-          delay *= this.options.backoffMultiplier;
-        }
+    try {
+      await (0, import_resilience.withRetry)(() => this.doSend(message), {
+        idempotent: true,
+        maxAttempts: this.options.maxRetries,
+        baseDelayMs: this.options.retryDelay
+      });
+    } catch (error) {
+      if (error instanceof MailTransportError) {
+        throw error;
       }
+      throw new MailTransportError(
+        `Mail sending failed after ${this.options.maxRetries} retries`,
+        "UNKNOWN" /* UNKNOWN */,
+        error
+      );
     }
-    throw new MailTransportError(
-      `Mail sending failed after ${this.options.maxRetries} retries`,
-      "UNKNOWN" /* UNKNOWN */,
-      lastError
-    );
-  }
-  /**
-   * Utility method to pause execution for a given duration.
-   *
-   * @param ms - Milliseconds to sleep.
-   * @returns A promise that resolves after the delay.
-   */
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
   }
 };
 
@@ -61452,6 +61512,7 @@ var SesWebhookDriver = class {
   HtmlRenderer,
   LogTransport,
   MailErrorCode,
+  MailErrorCodes,
   MailTransportError,
   Mailable,
   MemoryTransport,

package/dist/index.mjs

@@ -59817,6 +59817,20 @@ var DevMailbox = class {
   }
 };
 
+// src/errors.ts
+import { InfrastructureException } from "@gravito/core";
+
+// src/errors/codes.ts
+var MailErrorCodes = {
+  CONNECTION_FAILED: "mail.connection_failed",
+  AUTH_FAILED: "mail.auth_failed",
+  RECIPIENT_REJECTED: "mail.recipient_rejected",
+  MESSAGE_REJECTED: "mail.message_rejected",
+  RATE_LIMIT: "mail.rate_limit",
+  SEND_FAILED: "mail.send_failed",
+  UNKNOWN: "mail.unknown"
+};
+
 // src/errors.ts
 var MailErrorCode = /* @__PURE__ */ ((MailErrorCode2) => {
   MailErrorCode2["CONNECTION_FAILED"] = "CONNECTION_FAILED";
@@ -59827,12 +59841,31 @@ var MailErrorCode = /* @__PURE__ */ ((MailErrorCode2) => {
   MailErrorCode2["UNKNOWN"] = "UNKNOWN";
   return MailErrorCode2;
 })(MailErrorCode || {});
-var MailTransportError = class _MailTransportError extends Error {
+var legacyToNewCode = {
+  ["CONNECTION_FAILED" /* CONNECTION_FAILED */]: MailErrorCodes.CONNECTION_FAILED,
+  ["AUTH_FAILED" /* AUTH_FAILED */]: MailErrorCodes.AUTH_FAILED,
+  ["RECIPIENT_REJECTED" /* RECIPIENT_REJECTED */]: MailErrorCodes.RECIPIENT_REJECTED,
+  ["MESSAGE_REJECTED" /* MESSAGE_REJECTED */]: MailErrorCodes.MESSAGE_REJECTED,
+  ["RATE_LIMIT" /* RATE_LIMIT */]: MailErrorCodes.RATE_LIMIT,
+  ["UNKNOWN" /* UNKNOWN */]: MailErrorCodes.UNKNOWN
+};
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  MailErrorCodes.CONNECTION_FAILED,
+  MailErrorCodes.RATE_LIMIT
+]);
+var MailTransportError = class _MailTransportError extends InfrastructureException {
+  /**
+   * Legacy enum code — preserved for backward compat with callers that switch on MailErrorCode.
+   * @deprecated Prefer checking `.code` (mail.* namespaced string) instead.
+   */
+  legacyCode;
   /**
    * Create a new mail transport error.
    *
+   * Accepts both the legacy MailErrorCode enum and new mail.* namespaced string codes.
+   *
    * @param message - Human-readable error message
-   * @param code - Categorized error code
+   * @param code - Categorized error code (legacy enum or new mail.* string)
    * @param cause - Original error that caused this failure
    *
    * @example
@@ -59840,11 +59873,16 @@ var MailTransportError = class _MailTransportError extends Error {
    * const error = new MailTransportError('Auth failed', MailErrorCode.AUTH_FAILED);
    * ```
    */
-  constructor(message, code, cause) {
-    super(message);
-    this.code = code;
-    this.cause = cause;
+  constructor(message, code = "UNKNOWN" /* UNKNOWN */, cause) {
+    const newCode = typeof code === "string" && code.startsWith("mail.") ? code : legacyToNewCode[code] ?? MailErrorCodes.UNKNOWN;
+    super(502, newCode, {
+      message,
+      cause,
+      retryable: RETRYABLE_CODES.has(newCode)
+    });
     this.name = "MailTransportError";
+    this.legacyCode = typeof code === "string" && code.startsWith("mail.") ? Object.entries(legacyToNewCode).find(([, v]) => v === code)?.[0] ?? "UNKNOWN" /* UNKNOWN */ : code;
+    Object.setPrototypeOf(this, new.target.prototype);
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _MailTransportError);
     }
@@ -60830,6 +60868,9 @@ var MemoryTransport = class {
 };
 
 // src/OrbitSignal.ts
+function isCloseable(obj) {
+  return typeof obj === "object" && obj !== null && "close" in obj && typeof obj.close === "function";
+}
 var OrbitSignal = class {
   config;
   devMailbox;
@@ -60895,6 +60936,34 @@ var OrbitSignal = class {
         }
       });
     }
+    core.hooks.doAction("core:shutdown", async () => {
+      const DEADLINE_MS = 5e3;
+      const deadline = new Promise(
+        (_, reject) => setTimeout(
+          () => reject(new Error("[OrbitSignal] Shutdown deadline exceeded (5s)")),
+          DEADLINE_MS
+        )
+      );
+      try {
+        await Promise.race([this.cleanup(), deadline]);
+      } catch (err) {
+        core.logger.warn("[OrbitSignal] Forced shutdown:", err);
+      }
+    });
+  }
+  /**
+   * Gracefully release transport and dev resources.
+   *
+   * Called during shutdown. Detects closeable transports via type narrowing (no `as any`).
+   */
+  async cleanup() {
+    if (this.devMailbox) {
+      this.devMailbox = void 0;
+    }
+    const transport = this.config.transport;
+    if (isCloseable(transport)) {
+      await transport.close();
+    }
   }
   /**
    * Internal: Handle processed webhook.
@@ -61090,6 +61159,7 @@ init_ReactMjmlRenderer();
 init_VueMjmlRenderer();
 
 // src/transports/BaseTransport.ts
+import { withRetry } from "@gravito/resilience";
 var BaseTransport = class {
   options;
   /**
@@ -61105,14 +61175,14 @@ var BaseTransport = class {
     };
   }
   /**
-   * Orchestrates the message delivery with retry logic.
+   * Orchestrates the message delivery with automatic retry via @gravito/resilience.
    *
-   * This method wraps the concrete `doSend` implementation in a retry loop.
-   * It tracks the last error encountered to provide context if all retries fail.
+   * Delegates to `doSend()` and retries on retryable InfrastructureException errors
+   * (CONNECTION_FAILED, RATE_LIMIT). Non-retryable errors surface immediately.
    *
    * @param message - The message to be delivered.
    * @returns A promise that resolves when the message is successfully sent.
-   * @throws {MailTransportError} If the message cannot be sent after the maximum number of retries.
+   * @throws {MailTransportError} If the message cannot be sent after the maximum number of attempts.
    *
    * @example
    * ```typescript
@@ -61125,33 +61195,22 @@ var BaseTransport = class {
    * ```
    */
   async send(message) {
-    let lastError;
-    let delay = this.options.retryDelay;
-    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
-      try {
-        return await this.doSend(message);
-      } catch (error) {
-        lastError = error;
-        if (attempt < this.options.maxRetries) {
-          await this.sleep(delay);
-          delay *= this.options.backoffMultiplier;
-        }
+    try {
+      await withRetry(() => this.doSend(message), {
+        idempotent: true,
+        maxAttempts: this.options.maxRetries,
+        baseDelayMs: this.options.retryDelay
+      });
+    } catch (error) {
+      if (error instanceof MailTransportError) {
+        throw error;
       }
+      throw new MailTransportError(
+        `Mail sending failed after ${this.options.maxRetries} retries`,
+        "UNKNOWN" /* UNKNOWN */,
+        error
+      );
     }
-    throw new MailTransportError(
-      `Mail sending failed after ${this.options.maxRetries} retries`,
-      "UNKNOWN" /* UNKNOWN */,
-      lastError
-    );
-  }
-  /**
-   * Utility method to pause execution for a given duration.
-   *
-   * @param ms - Milliseconds to sleep.
-   * @returns A promise that resolves after the delay.
-   */
-  sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
   }
 };
 
@@ -61430,6 +61489,7 @@ export {
   HtmlRenderer,
   LogTransport,
   MailErrorCode,
+  MailErrorCodes,
   MailTransportError,
   Mailable,
   MemoryTransport,

package/dist/transports/BaseTransport.d.ts

@@ -5,6 +5,9 @@ import type { Message, Transport } from '../types';
  * Defines the behavior of the automatic retry mechanism, including the number of attempts
  * and the timing between them using exponential backoff.
  *
+ * @deprecated Configuration now handled internally by @gravito/resilience RetryOptions.
+ * Kept for backward compat of existing subclass constructors.
+ *
  * @example
  * ```typescript
  * const options: TransportOptions = {
@@ -29,21 +32,17 @@ export interface TransportOptions {
     /**
      * Multiplier applied to the delay after each failed attempt.
      * Used to implement exponential backoff to avoid overwhelming the service.
+     * @deprecated Backoff is now managed by @gravito/resilience (ExponentialBackoff).
      */
     backoffMultiplier?: number;
 }
 /**
- * Base transport class with automatic retry mechanism.
+ * Base transport class with automatic retry via @gravito/resilience.
  *
  * This abstract class provides a robust foundation for all transport implementations by
- * handling transient failures through an exponential backoff retry strategy. It ensures
- * that temporary network issues or service rate limits do not immediately fail the email delivery.
- *
- * The retry mechanism works as follows:
- * 1. Attempt to send the message via `doSend()`.
- * 2. If it fails, wait for `retryDelay` milliseconds.
- * 3. Increment the delay by `backoffMultiplier` for the next attempt.
- * 4. Repeat until success or `maxRetries` is reached.
+ * handling transient failures through the unified @gravito/resilience withRetry primitive.
+ * Only errors whose `retryable` flag is true (e.g., CONNECTION_FAILED, RATE_LIMIT) are
+ * retried automatically.
  *
  * @example
  * ```typescript
@@ -54,7 +53,7 @@ export interface TransportOptions {
  *
  *   protected async doSend(message: Message): Promise<void> {
  *     // Actual implementation of the sending logic
- *     // If this throws, BaseTransport will catch and retry
+ *     // If this throws, BaseTransport will retry via withRetry
  *   }
  * }
  * ```
@@ -70,14 +69,14 @@ export declare abstract class BaseTransport implements Transport {
      */
     constructor(options?: TransportOptions);
     /**
-     * Orchestrates the message delivery with retry logic.
+     * Orchestrates the message delivery with automatic retry via @gravito/resilience.
      *
-     * This method wraps the concrete `doSend` implementation in a retry loop.
-     * It tracks the last error encountered to provide context if all retries fail.
+     * Delegates to `doSend()` and retries on retryable InfrastructureException errors
+     * (CONNECTION_FAILED, RATE_LIMIT). Non-retryable errors surface immediately.
      *
      * @param message - The message to be delivered.
      * @returns A promise that resolves when the message is successfully sent.
-     * @throws {MailTransportError} If the message cannot be sent after the maximum number of retries.
+     * @throws {MailTransportError} If the message cannot be sent after the maximum number of attempts.
      *
      * @example
      * ```typescript
@@ -94,18 +93,11 @@ export declare abstract class BaseTransport implements Transport {
      * Actual transport implementation to be provided by subclasses.
      *
      * This method should contain the protocol-specific logic for delivering the message.
-     * It will be automatically retried by the `send` method if it throws an error.
+     * It will be automatically retried by `send()` if it throws a retryable error.
      *
      * @param message - The message to send.
      * @returns A promise that resolves when the delivery is successful.
-     * @throws {Error} Any error encountered during delivery, which will trigger a retry.
+     * @throws {Error} Any error encountered during delivery, which may trigger a retry.
      */
     protected abstract doSend(message: Message): Promise<void>;
-    /**
-     * Utility method to pause execution for a given duration.
-     *
-     * @param ms - Milliseconds to sleep.
-     * @returns A promise that resolves after the delay.
-     */
-    private sleep;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gravito/signal",
   "sideEffects": false,
-  "version": "3.1.2",
+  "version": "4.0.0",
   "description": "Powerful email framework for Gravito applications with Dev UI and multi-renderer support.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -39,12 +39,13 @@
   "license": "MIT",
   "dependencies": {
     "@aws-sdk/client-ses": "^3.953.0",
+    "@gravito/resilience": "workspace:*",
     "nodemailer": "^7.0.11"
   },
   "peerDependencies": {
-    "@gravito/core": "^2.0.0",
-    "@gravito/stream": "^2.1.0",
-    "@gravito/prism": "^3.1.1",
+    "@gravito/core": "^3.0.0",
+    "@gravito/stream": "^3.0.0",
+    "@gravito/prism": "^4.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "vue": "^3.0.0"