@beignet/core 0.0.1 → 0.0.3

package/src/mail/index.ts

@@ -4,27 +4,71 @@
  * Shared mail port and test adapters for Beignet applications.
  */
 
+/**
+ * Value or promise of that value.
+ */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Email address accepted by Beignet mail helpers.
+ */
 export type MailAddress =
   | string
   | {
+      /**
+       * Email address.
+       */
       email: string;
+      /**
+       * Optional display name.
+       */
       name?: string;
     };
 
+/**
+ * Single address or address list.
+ */
 export type MailAddressList = MailAddress | readonly MailAddress[];
 
+/**
+ * Common mail message fields shared by all send options.
+ */
 export interface MailBaseMessage {
+  /**
+   * Required recipients.
+   */
   to: MailAddressList;
+  /**
+   * Message subject.
+   */
   subject: string;
+  /**
+   * Sender address. Providers or adapters may supply a default.
+   */
   from?: MailAddress;
+  /**
+   * Carbon-copy recipients.
+   */
   cc?: MailAddressList;
+  /**
+   * Blind-carbon-copy recipients.
+   */
   bcc?: MailAddressList;
+  /**
+   * Reply-to recipients.
+   */
   replyTo?: MailAddressList;
+  /**
+   * Provider-specific message headers.
+   */
   headers?: Record<string, string>;
 }
 
+/**
+ * Mail send options.
+ *
+ * A message must include at least one body format: `text` or `html`.
+ */
 export type SendMailOptions = MailBaseMessage &
   (
     | {
@@ -37,45 +81,129 @@ export type SendMailOptions = MailBaseMessage &
       }
   );
 
+/**
+ * Normalized mail message with address fields converted to arrays.
+ */
 export interface NormalizedMailMessage extends MailBaseMessage {
+  /**
+   * Normalized recipients.
+   */
   to: readonly MailAddress[];
+  /**
+   * Sender address after applying any default.
+   */
   from?: MailAddress;
+  /**
+   * Normalized carbon-copy recipients.
+   */
   cc?: readonly MailAddress[];
+  /**
+   * Normalized blind-carbon-copy recipients.
+   */
   bcc?: readonly MailAddress[];
+  /**
+   * Normalized reply-to recipients.
+   */
   replyTo?: readonly MailAddress[];
+  /**
+   * Plain text body.
+   */
   text?: string;
+  /**
+   * HTML body.
+   */
   html?: string;
 }
 
+/**
+ * Result returned by a mail provider.
+ */
 export interface SendMailResult {
+  /**
+   * Provider message ID when available.
+   */
   id?: string;
+  /**
+   * Provider name.
+   */
   provider?: string;
 }
 
+/**
+ * App-facing mailer port.
+ */
 export interface MailerPort {
+  /**
+   * Send one mail message.
+   */
   send(message: SendMailOptions): Promise<SendMailResult>;
 }
 
+/**
+ * Delivery captured by the memory mailer.
+ */
 export interface MemoryMailDelivery {
+  /**
+   * Generated delivery ID.
+   */
   id: string;
+  /**
+   * Normalized message that would have been sent.
+   */
   message: NormalizedMailMessage;
+  /**
+   * Timestamp assigned by the memory mailer.
+   */
   sentAt: Date;
 }
 
+/**
+ * In-memory mailer port for tests and local examples.
+ */
 export interface MemoryMailerPort extends MailerPort {
+  /**
+   * Captured deliveries.
+   */
   readonly deliveries: readonly MemoryMailDelivery[];
+  /**
+   * Clear captured deliveries.
+   */
   clear(): void;
 }
 
+/**
+ * Options for `createMemoryMailer(...)`.
+ */
 export interface CreateMemoryMailerOptions {
+  /**
+   * Sender used when a message does not specify `from`.
+   */
   defaultFrom?: MailAddress;
+  /**
+   * Clock used for captured deliveries.
+   */
   now?: () => Date;
+  /**
+   * ID factory used for captured deliveries.
+   */
   id?: () => string;
+  /**
+   * Observer called after a delivery is captured.
+   */
   onSend?: (delivery: MemoryMailDelivery) => MaybePromise<void>;
 }
 
+/**
+ * Error thrown by mail helpers and provider adapters.
+ */
 export class MailDeliveryError extends Error {
+  /**
+   * Provider name when known.
+   */
   readonly provider?: string;
+  /**
+   * Original provider error when available.
+   */
   readonly cause?: unknown;
 
   constructor(args: { provider?: string; message: string; cause?: unknown }) {
@@ -86,6 +214,11 @@ export class MailDeliveryError extends Error {
   }
 }
 
+/**
+ * Normalize a single address or address list into an array.
+ *
+ * This helper does not validate email syntax.
+ */
 export function normalizeMailAddressList(
   addresses: MailAddressList | undefined,
 ): readonly MailAddress[] | undefined {
@@ -100,6 +233,9 @@ function normalizeOptionalMailAddressList(
   return normalized && normalized.length > 0 ? normalized : undefined;
 }
 
+/**
+ * Format one address for providers that accept RFC-like address strings.
+ */
 export function formatMailAddress(address: MailAddress): string {
   if (typeof address === "string") return address;
   if (!address.name) return address.email;
@@ -108,6 +244,9 @@ export function formatMailAddress(address: MailAddress): string {
   return `"${escapedName}" <${address.email}>`;
 }
 
+/**
+ * Format one or more addresses for providers that accept string address fields.
+ */
 export function formatMailAddressList(
   addresses: MailAddressList,
 ): string | string[] {
@@ -116,6 +255,11 @@ export function formatMailAddressList(
   return formatted.length === 1 ? formatted[0] : formatted;
 }
 
+/**
+ * Normalize a mail message and apply a default sender.
+ *
+ * Throws when the message has no recipients.
+ */
 export function normalizeMailMessage(
   message: SendMailOptions,
   options: { defaultFrom?: MailAddress } = {},
@@ -140,6 +284,11 @@ export function normalizeMailMessage(
   };
 }
 
+/**
+ * Create an in-memory mailer for tests, local development, and examples.
+ *
+ * The memory mailer does not send real email or validate address syntax.
+ */
 export function createMemoryMailer(
   options: CreateMemoryMailerOptions = {},
 ): MemoryMailerPort {