@brightchain/brightchain-lib 0.13.0 → 0.14.0

package/src/lib/interfaces/messaging/emailAddress.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * RFC 5322 Email Address Interfaces and Utilities
+ *
+ * Provides interfaces for representing email addresses per RFC 5322 Section 3.4,
+ * including individual mailboxes (addr-spec and name-addr formats) and group
+ * addresses. Also provides utility functions for creating, formatting, and
+ * type-guarding address objects.
+ *
+ * @see RFC 5322 Section 3.4 - Address Specification
+ * @see RFC 5321 - Address length limits
+ * @see RFC 6532 - Internationalized Email Headers (UTF-8)
+ *
+ * @remarks
+ * Requirements: 2.1, 2.2, 2.3, 2.4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMailbox = createMailbox;
+exports.createAddressGroup = createAddressGroup;
+exports.isMailbox = isMailbox;
+exports.isAddressGroup = isAddressGroup;
+exports.formatMailbox = formatMailbox;
+exports.formatAddressGroup = formatAddressGroup;
+exports.formatAddress = formatAddress;
+exports.formatAddressList = formatAddressList;
+// ─── Utility Functions ──────────────────────────────────────────────────────
+/**
+ * Creates an IMailbox object with a computed `address` property.
+ *
+ * @param localPart - The local part of the email address (before @)
+ * @param domain - The domain of the email address (after @)
+ * @param displayName - Optional display name
+ * @returns A fully constructed IMailbox with computed address getter
+ *
+ * @example
+ * ```typescript
+ * const mailbox = createMailbox('john', 'example.com', 'John Doe');
+ * console.log(mailbox.address); // "john@example.com"
+ * console.log(mailbox.displayName); // "John Doe"
+ * ```
+ */
+function createMailbox(localPart, domain, displayName) {
+    return {
+        localPart,
+        domain,
+        displayName,
+        get address() {
+            return `${this.localPart}@${this.domain}`;
+        },
+    };
+}
+/**
+ * Creates an IAddressGroup object.
+ *
+ * @param displayName - The group display name
+ * @param mailboxes - Array of mailboxes in the group (defaults to empty)
+ * @returns A fully constructed IAddressGroup
+ *
+ * @example
+ * ```typescript
+ * const group = createAddressGroup('Team', [
+ *   createMailbox('alice', 'example.com'),
+ *   createMailbox('bob', 'example.com'),
+ * ]);
+ * ```
+ */
+function createAddressGroup(displayName, mailboxes = []) {
+    return {
+        displayName,
+        mailboxes,
+    };
+}
+/**
+ * Type guard to check if an IAddress is an IMailbox.
+ *
+ * Distinguishes mailboxes from groups by checking for the presence of
+ * `localPart` and `domain` properties (which are unique to IMailbox).
+ *
+ * @param address - The address to check
+ * @returns true if the address is an IMailbox
+ *
+ * @example
+ * ```typescript
+ * const addr: IAddress = createMailbox('user', 'example.com');
+ * if (isMailbox(addr)) {
+ *   console.log(addr.address); // "user@example.com"
+ * }
+ * ```
+ */
+function isMailbox(address) {
+    return ('localPart' in address &&
+        'domain' in address &&
+        typeof address.localPart === 'string' &&
+        typeof address.domain === 'string');
+}
+/**
+ * Type guard to check if an IAddress is an IAddressGroup.
+ *
+ * Distinguishes groups from mailboxes by checking for the presence of
+ * the `mailboxes` array property (which is unique to IAddressGroup).
+ *
+ * @param address - The address to check
+ * @returns true if the address is an IAddressGroup
+ *
+ * @example
+ * ```typescript
+ * const addr: IAddress = createAddressGroup('Team', []);
+ * if (isAddressGroup(addr)) {
+ *   console.log(addr.displayName); // "Team"
+ * }
+ * ```
+ */
+function isAddressGroup(address) {
+    return ('mailboxes' in address &&
+        Array.isArray(address.mailboxes) &&
+        !('localPart' in address));
+}
+/**
+ * Formats an IMailbox as an RFC 5322 compliant string.
+ *
+ * If a display name is present, formats as name-addr: `"Display Name" <local@domain>`
+ * Otherwise, formats as addr-spec: `local@domain`
+ *
+ * @param mailbox - The mailbox to format
+ * @returns RFC 5322 formatted mailbox string
+ *
+ * @see RFC 5322 Section 3.4
+ * @see Requirement 2.1
+ *
+ * @example
+ * ```typescript
+ * formatMailbox(createMailbox('john', 'example.com', 'John Doe'));
+ * // => '"John Doe" <john@example.com>'
+ *
+ * formatMailbox(createMailbox('john', 'example.com'));
+ * // => 'john@example.com'
+ * ```
+ */
+function formatMailbox(mailbox) {
+    if (mailbox.displayName) {
+        // Use quoted-string for display name to handle special characters
+        return `"${mailbox.displayName}" <${mailbox.address}>`;
+    }
+    return mailbox.address;
+}
+/**
+ * Formats an IAddressGroup as an RFC 5322 compliant string.
+ *
+ * Formats as: `display-name: mailbox-list;`
+ * For empty groups: `display-name:;`
+ *
+ * @param group - The address group to format
+ * @returns RFC 5322 formatted group address string
+ *
+ * @see RFC 5322 Section 3.4
+ * @see Requirement 2.4
+ *
+ * @example
+ * ```typescript
+ * formatAddressGroup(createAddressGroup('Team', [
+ *   createMailbox('alice', 'example.com'),
+ *   createMailbox('bob', 'example.com'),
+ * ]));
+ * // => 'Team: alice@example.com, bob@example.com;'
+ * ```
+ */
+function formatAddressGroup(group) {
+    if (group.mailboxes.length === 0) {
+        return `${group.displayName}:;`;
+    }
+    const mailboxList = group.mailboxes.map(formatMailbox).join(', ');
+    return `${group.displayName}: ${mailboxList};`;
+}
+/**
+ * Formats an IAddress (either mailbox or group) as an RFC 5322 compliant string.
+ *
+ * @param address - The address to format
+ * @returns RFC 5322 formatted address string
+ *
+ * @example
+ * ```typescript
+ * formatAddress(createMailbox('user', 'example.com'));
+ * // => 'user@example.com'
+ *
+ * formatAddress(createAddressGroup('Team', []));
+ * // => 'Team:;'
+ * ```
+ */
+function formatAddress(address) {
+    if (isMailbox(address)) {
+        return formatMailbox(address);
+    }
+    return formatAddressGroup(address);
+}
+/**
+ * Formats an array of IAddress objects as a comma-separated RFC 5322 address list.
+ *
+ * @param addresses - Array of addresses to format
+ * @returns Comma-separated RFC 5322 formatted address list string
+ *
+ * @example
+ * ```typescript
+ * formatAddressList([
+ *   createMailbox('alice', 'example.com', 'Alice'),
+ *   createMailbox('bob', 'example.com'),
+ * ]);
+ * // => '"Alice" <alice@example.com>, bob@example.com'
+ * ```
+ */
+function formatAddressList(addresses) {
+    return addresses.map(formatAddress).join(', ');
+}
+//# sourceMappingURL=emailAddress.js.map

package/src/lib/interfaces/messaging/emailAddress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailAddress.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/messaging/emailAddress.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AA4EH,sCAaC;AAiBD,gDAQC;AAmBD,8BAOC;AAmBD,wCAMC;AAuBD,sCAMC;AAuBD,gDAMC;AAiBD,sCAKC;AAiBD,8CAEC;AA7MD,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,SAAgB,aAAa,CAC3B,SAAiB,EACjB,MAAc,EACd,WAAoB;IAEpB,OAAO;QACL,SAAS;QACT,MAAM;QACN,WAAW;QACX,IAAI,OAAO;YACT,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,kBAAkB,CAChC,WAAmB,EACnB,YAAwB,EAAE;IAE1B,OAAO;QACL,WAAW;QACX,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,SAAS,CAAC,OAAiB;IACzC,OAAO,CACL,WAAW,IAAI,OAAO;QACtB,QAAQ,IAAI,OAAO;QACnB,OAAQ,OAAoB,CAAC,SAAS,KAAK,QAAQ;QACnD,OAAQ,OAAoB,CAAC,MAAM,KAAK,QAAQ,CACjD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,cAAc,CAAC,OAAiB;IAC9C,OAAO,CACL,WAAW,IAAI,OAAO;QACtB,KAAK,CAAC,OAAO,CAAE,OAAyB,CAAC,SAAS,CAAC;QACnD,CAAC,CAAC,WAAW,IAAI,OAAO,CAAC,CAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,aAAa,CAAC,OAAiB;IAC7C,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,kEAAkE;QAClE,OAAO,IAAI,OAAO,CAAC,WAAW,MAAM,OAAO,CAAC,OAAO,GAAG,CAAC;IACzD,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,kBAAkB,CAAC,KAAoB;IACrD,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,GAAG,KAAK,CAAC,WAAW,IAAI,CAAC;IAClC,CAAC;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClE,OAAO,GAAG,KAAK,CAAC,WAAW,KAAK,WAAW,GAAG,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,aAAa,CAAC,OAAiB;IAC7C,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QACvB,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,kBAAkB,CAAC,OAAwB,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,iBAAiB,CAAC,SAAqB;IACrD,OAAO,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC"}

package/src/lib/interfaces/messaging/emailDelivery.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Email delivery status tracking types.
+ *
+ * Defines the IDeliveryReceipt interface for tracking email delivery lifecycle
+ * across BrightChain nodes. The IDeliveryReceipt now uses the unified
+ * DeliveryStatus enum instead of the deprecated EmailDeliveryStatus.
+ *
+ * @see Requirements 12.1, 12.2, 12.3, 2.4, 2.5
+ * @module emailDelivery
+ */
+import { DeliveryStatus } from '../../enumerations/messaging/deliveryStatus';
+/**
+ * Delivery status states for tracking email delivery lifecycle.
+ *
+ * @deprecated Use {@link DeliveryStatus} from `../../enumerations/messaging/deliveryStatus` instead.
+ * This enum is replaced by the unified DeliveryStatus enum as part of the
+ * unified gossip delivery migration (Requirement 2.4, 2.5).
+ *
+ * Migration mapping:
+ * - Pending → DeliveryStatus.Pending
+ * - Queued → DeliveryStatus.Pending (no separate Queued state)
+ * - InTransit → DeliveryStatus.Announced
+ * - Delivered → DeliveryStatus.Delivered
+ * - Failed → DeliveryStatus.Failed
+ * - Bounced → DeliveryStatus.Bounced
+ * - Read → DeliveryStatus.Read
+ *
+ * @see Requirement 12.1
+ * @see DeliveryStatus
+ */
+export declare enum EmailDeliveryStatus {
+    /** Initial state when email is created but not yet queued for delivery */
+    Pending = "pending",
+    /** Email has been queued for delivery processing */
+    Queued = "queued",
+    /** Email blocks are being replicated to the recipient's node */
+    InTransit = "in_transit",
+    /** Email blocks have been successfully replicated to the recipient's node */
+    Delivered = "delivered",
+    /** Delivery failed after exhausting retry attempts */
+    Failed = "failed",
+    /** Email was rejected/bounced by the recipient's node */
+    Bounced = "bounced",
+    /** Recipient has read the email (read receipt received) */
+    Read = "read"
+}
+/**
+ * Delivery receipt for tracking email delivery status per recipient.
+ *
+ * Each recipient of an email has their own delivery receipt that tracks
+ * the full delivery lifecycle including timestamps and failure information.
+ *
+ * @see Requirement 12.2 - Delivery receipts with timestamps
+ * @see Requirement 12.3 - Delivery timestamps per recipient
+ */
+export interface IDeliveryReceipt {
+    /** Recipient identifier (e.g., user ID or address) */
+    recipientId: string;
+    /** Recipient's home node identifier */
+    recipientNode: string;
+    /** Current delivery status */
+    status: DeliveryStatus;
+    /** Timestamp when the email was queued for delivery */
+    queuedAt?: Date;
+    /** Timestamp when the email blocks were sent/replication initiated */
+    sentAt?: Date;
+    /** Timestamp when delivery was confirmed at the recipient's node */
+    deliveredAt?: Date;
+    /** Timestamp when the recipient read the email */
+    readAt?: Date;
+    /** Timestamp when delivery failed */
+    failedAt?: Date;
+    /** Human-readable reason for delivery failure */
+    failureReason?: string;
+    /** Machine-readable error code for delivery failure */
+    failureCode?: string;
+    /** Number of delivery retry attempts made */
+    retryCount: number;
+}
+//# sourceMappingURL=emailDelivery.d.ts.map

package/src/lib/interfaces/messaging/emailDelivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailDelivery.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/messaging/emailDelivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAE7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,oBAAY,mBAAmB;IAC7B,0EAA0E;IAC1E,OAAO,YAAY;IAEnB,oDAAoD;IACpD,MAAM,WAAW;IAEjB,gEAAgE;IAChE,SAAS,eAAe;IAExB,6EAA6E;IAC7E,SAAS,cAAc;IAEvB,sDAAsD;IACtD,MAAM,WAAW;IAEjB,yDAAyD;IACzD,OAAO,YAAY;IAEnB,2DAA2D;IAC3D,IAAI,SAAS;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IAEtB,8BAA8B;IAC9B,MAAM,EAAE,cAAc,CAAC;IAIvB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,IAAI,CAAC;IAEhB,sEAAsE;IACtE,MAAM,CAAC,EAAE,IAAI,CAAC;IAEd,oEAAoE;IACpE,WAAW,CAAC,EAAE,IAAI,CAAC;IAEnB,kDAAkD;IAClD,MAAM,CAAC,EAAE,IAAI,CAAC;IAEd,qCAAqC;IACrC,QAAQ,CAAC,EAAE,IAAI,CAAC;IAIhB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/src/lib/interfaces/messaging/emailDelivery.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Email delivery status tracking types.
+ *
+ * Defines the IDeliveryReceipt interface for tracking email delivery lifecycle
+ * across BrightChain nodes. The IDeliveryReceipt now uses the unified
+ * DeliveryStatus enum instead of the deprecated EmailDeliveryStatus.
+ *
+ * @see Requirements 12.1, 12.2, 12.3, 2.4, 2.5
+ * @module emailDelivery
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailDeliveryStatus = void 0;
+/**
+ * Delivery status states for tracking email delivery lifecycle.
+ *
+ * @deprecated Use {@link DeliveryStatus} from `../../enumerations/messaging/deliveryStatus` instead.
+ * This enum is replaced by the unified DeliveryStatus enum as part of the
+ * unified gossip delivery migration (Requirement 2.4, 2.5).
+ *
+ * Migration mapping:
+ * - Pending → DeliveryStatus.Pending
+ * - Queued → DeliveryStatus.Pending (no separate Queued state)
+ * - InTransit → DeliveryStatus.Announced
+ * - Delivered → DeliveryStatus.Delivered
+ * - Failed → DeliveryStatus.Failed
+ * - Bounced → DeliveryStatus.Bounced
+ * - Read → DeliveryStatus.Read
+ *
+ * @see Requirement 12.1
+ * @see DeliveryStatus
+ */
+var EmailDeliveryStatus;
+(function (EmailDeliveryStatus) {
+    /** Initial state when email is created but not yet queued for delivery */
+    EmailDeliveryStatus["Pending"] = "pending";
+    /** Email has been queued for delivery processing */
+    EmailDeliveryStatus["Queued"] = "queued";
+    /** Email blocks are being replicated to the recipient's node */
+    EmailDeliveryStatus["InTransit"] = "in_transit";
+    /** Email blocks have been successfully replicated to the recipient's node */
+    EmailDeliveryStatus["Delivered"] = "delivered";
+    /** Delivery failed after exhausting retry attempts */
+    EmailDeliveryStatus["Failed"] = "failed";
+    /** Email was rejected/bounced by the recipient's node */
+    EmailDeliveryStatus["Bounced"] = "bounced";
+    /** Recipient has read the email (read receipt received) */
+    EmailDeliveryStatus["Read"] = "read";
+})(EmailDeliveryStatus || (exports.EmailDeliveryStatus = EmailDeliveryStatus = {}));
+//# sourceMappingURL=emailDelivery.js.map

package/src/lib/interfaces/messaging/emailDelivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailDelivery.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/messaging/emailDelivery.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAIH;;;;;;;;;;;;;;;;;;GAkBG;AACH,IAAY,mBAqBX;AArBD,WAAY,mBAAmB;IAC7B,0EAA0E;IAC1E,0CAAmB,CAAA;IAEnB,oDAAoD;IACpD,wCAAiB,CAAA;IAEjB,gEAAgE;IAChE,+CAAwB,CAAA;IAExB,6EAA6E;IAC7E,8CAAuB,CAAA;IAEvB,sDAAsD;IACtD,wCAAiB,CAAA;IAEjB,yDAAyD;IACzD,0CAAmB,CAAA;IAEnB,2DAA2D;IAC3D,oCAAa,CAAA;AACf,CAAC,EArBW,mBAAmB,mCAAnB,mBAAmB,QAqB9B"}

package/src/lib/interfaces/messaging/emailMetadata.d.ts

@@ -0,0 +1,269 @@
+import { IMailbox } from './emailAddress';
+import { IMessageMetadata } from './messageMetadata';
+import { ContentTransferEncoding, type IContentType, type IMimePart } from './mimePart';
+export type { IMailbox } from './emailAddress';
+export { ContentTransferEncoding, createContentType } from './mimePart';
+export type { IContentDisposition, IContentType, IMimePart } from './mimePart';
+export type { IAttachmentMetadata } from './attachmentMetadata';
+import type { IAttachmentMetadata } from './attachmentMetadata';
+export { EmailDeliveryStatus } from './emailDelivery';
+export type { IDeliveryReceipt } from './emailDelivery';
+export { DeliveryStatus } from '../../enumerations/messaging/deliveryStatus';
+import type { IDeliveryReceipt } from './emailDelivery';
+/**
+ * Resent header block for forwarded emails per RFC 5322 Section 3.6.6.
+ *
+ * @remarks
+ * When an email is forwarded, a new block of Resent-* headers is prepended.
+ * Multiple forwards result in multiple blocks, most recent first.
+ */
+export interface IResentHeaderBlock {
+    /** Resent-From: the forwarder's mailbox */
+    resentFrom: IMailbox;
+    /** Resent-To: forwarding recipients */
+    resentTo: IMailbox[];
+    /** Resent-Cc: optional carbon copy recipients for the forward */
+    resentCc?: IMailbox[];
+    /** Resent-Bcc: optional blind carbon copy recipients for the forward */
+    resentBcc?: IMailbox[];
+    /** Resent-Date: date of the forward */
+    resentDate: Date;
+    /** Resent-Message-ID: unique identifier for this forward action */
+    resentMessageId: string;
+    /** Resent-Sender: optional actual sender if different from Resent-From */
+    resentSender?: IMailbox;
+}
+/**
+ * Email-specific metadata extending the base message metadata.
+ * Provides RFC 5322 compliant email header fields and MIME support.
+ *
+ * @remarks
+ * This interface extends {@link IMessageMetadata} with all fields necessary
+ * to represent a complete RFC 5322 Internet Message Format email, including:
+ * - Originator fields (From, Sender, Reply-To) per Section 3.6.2
+ * - Destination fields (To, Cc, Bcc) per Section 3.6.3
+ * - Identification fields (Message-ID, In-Reply-To, References) per Section 3.6.4
+ * - Informational fields (Subject, Comments, Keywords) per Section 3.6.5
+ * - Date field per Section 3.6.1
+ * - MIME headers per RFC 2045
+ * - Resent headers for forwarding per Section 3.6.6
+ * - Delivery tracking extensions for BrightChain cross-node delivery
+ *
+ * @see Requirements 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
+ */
+export interface IEmailMetadata extends IMessageMetadata {
+    /**
+     * Required: sender mailbox.
+     * Per RFC 5322, the "From:" field specifies the author(s) of the message.
+     *
+     * @see Requirement 1.1
+     */
+    from: IMailbox;
+    /**
+     * Optional: actual sender if different from From.
+     * Per RFC 5322, the "Sender:" field is used when the actual sender
+     * differs from the author specified in "From:".
+     *
+     * @see Requirement 1.1
+     */
+    sender?: IMailbox;
+    /**
+     * Optional: reply addresses.
+     * Per RFC 5322, the "Reply-To:" field indicates the address(es)
+     * to which the author suggests replies be sent.
+     *
+     * @see Requirement 1.1
+     */
+    replyTo?: IMailbox[];
+    /**
+     * Primary recipients.
+     * Per RFC 5322, the "To:" field contains the address(es) of the
+     * primary recipient(s) of the message.
+     *
+     * @see Requirement 1.2
+     */
+    to: IMailbox[];
+    /**
+     * Carbon copy recipients.
+     * Per RFC 5322, the "Cc:" field contains the addresses of others
+     * who are to receive the message, though the content is not directed at them.
+     *
+     * @see Requirement 1.2
+     */
+    cc?: IMailbox[];
+    /**
+     * Blind carbon copy recipients.
+     * Per RFC 5322, the "Bcc:" field contains addresses of recipients
+     * who should receive the message but whose addresses should not be
+     * revealed to other recipients. Stored separately for privacy.
+     *
+     * @see Requirement 1.2
+     */
+    bcc?: IMailbox[];
+    /**
+     * Unique message identifier in the format `<id-left@id-right>`.
+     * Per RFC 5322, the "Message-ID:" field provides a unique identifier
+     * for the message. Auto-generated if not provided.
+     *
+     * @see Requirement 1.3
+     */
+    messageId: string;
+    /**
+     * Parent message ID for threading.
+     * Per RFC 5322, the "In-Reply-To:" field identifies the message(s)
+     * to which this message is a reply.
+     *
+     * @see Requirement 1.3
+     */
+    inReplyTo?: string;
+    /**
+     * Thread reference chain.
+     * Per RFC 5322, the "References:" field identifies other correspondence
+     * that this message references, used for threading.
+     *
+     * @see Requirement 1.3
+     */
+    references?: string[];
+    /**
+     * Email subject line (UTF-8 encoded).
+     * Per RFC 5322, the "Subject:" field is a short string identifying
+     * the topic of the message.
+     *
+     * @see Requirement 1.4
+     */
+    subject?: string;
+    /**
+     * Optional comments.
+     * Per RFC 5322, the "Comments:" field provides additional comments
+     * on the text of the body. May appear multiple times.
+     *
+     * @see Requirement 1.4
+     */
+    comments?: string[];
+    /**
+     * Optional keywords.
+     * Per RFC 5322, the "Keywords:" field contains a comma-separated
+     * list of important words and phrases. May appear multiple times.
+     *
+     * @see Requirement 1.4
+     */
+    keywords?: string[];
+    /**
+     * Origination date.
+     * Per RFC 5322, the "Date:" field specifies the date and time at which
+     * the creator of the message indicated that the message was complete
+     * and ready to enter the mail delivery system. Auto-generated if not provided.
+     *
+     * @see Requirement 1.5
+     */
+    date: Date;
+    /**
+     * MIME version, always "1.0".
+     * Per RFC 2045, the "MIME-Version:" header field indicates that the
+     * message is MIME compliant.
+     *
+     * @see Requirement 1.8
+     */
+    mimeVersion: string;
+    /**
+     * Content-Type header with type/subtype and optional parameters.
+     * Per RFC 2045, the "Content-Type:" header field describes the data
+     * contained in the body.
+     *
+     * @see Requirement 5.1
+     */
+    contentType: IContentType;
+    /**
+     * Content-Transfer-Encoding for the top-level message.
+     * Per RFC 2045, specifies the encoding used for the message body.
+     */
+    contentTransferEncoding?: ContentTransferEncoding;
+    /**
+     * Custom and extension headers (X-* and other non-standard headers).
+     * Per RFC 5322, user-defined header fields may be added to messages.
+     * Keys are header field names, values are arrays to support multiple
+     * occurrences of the same header.
+     *
+     * @see Requirement 1.6
+     */
+    customHeaders: Map<string, string[]>;
+    /**
+     * MIME parts for multipart messages.
+     * Contains the individual parts of a multipart message, each with
+     * its own Content-Type, encoding, and body.
+     *
+     * @see Requirement 6.1
+     */
+    parts?: IMimePart[];
+    /**
+     * Attachment references with CBL storage metadata.
+     * Each attachment is stored as separate blocks with filename,
+     * MIME type, and integrity information.
+     *
+     * @see Requirement 8.1
+     */
+    attachments?: IAttachmentMetadata[];
+    /**
+     * Delivery receipts per recipient.
+     * Maps recipient identifier to their delivery receipt,
+     * tracking the full delivery lifecycle.
+     *
+     * @see Requirement 12.1
+     */
+    deliveryReceipts: Map<string, IDeliveryReceipt>;
+    /**
+     * Read receipts per recipient.
+     * Maps recipient identifier to the timestamp when they read the message.
+     *
+     * @see Requirement 12.3
+     */
+    readReceipts: Map<string, Date>;
+    /**
+     * Resent header blocks for forwarded emails.
+     * Each forward operation prepends a new block of Resent-* headers.
+     * Most recent forward is first in the array.
+     *
+     * @see Requirement 17.1
+     */
+    resentHeaders?: IResentHeaderBlock[];
+    /**
+     * Per-recipient encrypted symmetric keys.
+     * Maps recipient address to their ECIES-encrypted copy of the symmetric key
+     * used to encrypt the email content. Only present when encryptionScheme
+     * is RECIPIENT_KEYS.
+     *
+     * @see Requirement 16.4 - Separate encrypted copies for each recipient
+     * @see Requirement 16.7 - Store encryption metadata in Email_Metadata
+     */
+    encryptedKeys?: Map<string, Uint8Array>;
+    /**
+     * Initialization vector used for AES-256-GCM content encryption.
+     * Present when the email content is encrypted (RECIPIENT_KEYS or SHARED_KEY).
+     */
+    encryptionIv?: Uint8Array;
+    /**
+     * Authentication tag from AES-256-GCM content encryption.
+     * Present when the email content is encrypted.
+     */
+    encryptionAuthTag?: Uint8Array;
+    /**
+     * Whether the email content has been digitally signed.
+     *
+     * @see Requirement 16.5 - S/MIME signatures for sender authentication
+     */
+    isSigned?: boolean;
+    /**
+     * Digital signature bytes for the email content.
+     * Present when isSigned is true.
+     *
+     * @see Requirement 16.5
+     */
+    contentSignature?: Uint8Array;
+    /**
+     * Public key of the signer, stored for signature verification.
+     *
+     * @see Requirement 16.8 - Verify sender's signature on decryption
+     */
+    signerPublicKey?: Uint8Array;
+}
+//# sourceMappingURL=emailMetadata.d.ts.map

package/src/lib/interfaces/messaging/emailMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailMetadata.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/messaging/emailMetadata.ts"],"names":[],"mappings":"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"}

package/src/lib/interfaces/messaging/emailMetadata.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeliveryStatus = exports.EmailDeliveryStatus = exports.createContentType = exports.ContentTransferEncoding = void 0;
+// Re-export MIME types from their canonical location (mimePart.ts)
+// so existing consumers of emailMetadata.ts still work
+var mimePart_1 = require("./mimePart");
+Object.defineProperty(exports, "ContentTransferEncoding", { enumerable: true, get: function () { return mimePart_1.ContentTransferEncoding; } });
+Object.defineProperty(exports, "createContentType", { enumerable: true, get: function () { return mimePart_1.createContentType; } });
+// Re-export delivery types from their canonical location (emailDelivery.ts)
+// so existing consumers of emailMetadata.ts still work
+var emailDelivery_1 = require("./emailDelivery");
+Object.defineProperty(exports, "EmailDeliveryStatus", { enumerable: true, get: function () { return emailDelivery_1.EmailDeliveryStatus; } });
+// Re-export unified DeliveryStatus
+var deliveryStatus_1 = require("../../enumerations/messaging/deliveryStatus");
+Object.defineProperty(exports, "DeliveryStatus", { enumerable: true, get: function () { return deliveryStatus_1.DeliveryStatus; } });
+//# sourceMappingURL=emailMetadata.js.map

package/src/lib/interfaces/messaging/emailMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailMetadata.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/messaging/emailMetadata.ts"],"names":[],"mappings":";;;AAWA,mEAAmE;AACnE,uDAAuD;AACvD,uCAAwE;AAA/D,mHAAA,uBAAuB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AASnD,4EAA4E;AAC5E,uDAAuD;AACvD,iDAAsD;AAA7C,oHAAA,mBAAmB,OAAA;AAG5B,mCAAmC;AACnC,8EAA6E;AAApE,gHAAA,cAAc,OAAA"}

package/src/lib/interfaces/messaging/index.d.ts

@@ -1,5 +1,9 @@
+export * from './attachmentMetadata';
+export * from './emailAddress';
+export * from './emailDelivery';
+export * from './emailMetadata';
 export * from './messageMetadata';
 export * from './messageMetadataStore';
-export * from './messageRouter';
 export * from './messageSystemConfig';
+export * from './mimePart';
 //# sourceMappingURL=index.d.ts.map

package/src/lib/interfaces/messaging/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/messaging/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/interfaces/messaging/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,YAAY,CAAC"}