@bernierllc/email-headers 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,7 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Error codes for programmatic error handling in email header operations.
+ */
+export declare const HeaderErrorCode: {
+    readonly INVALID_HEADER: "INVALID_HEADER";
+    readonly INVALID_MESSAGE_ID: "INVALID_MESSAGE_ID";
+    readonly INVALID_EMAIL: "INVALID_EMAIL";
+    readonly PARSE_ERROR: "PARSE_ERROR";
+};
+export type HeaderErrorCodeType = typeof HeaderErrorCode[keyof typeof HeaderErrorCode];
+/**
+ * Options for creating a HeaderError.
+ */
+export interface HeaderErrorOptions {
+    /** The underlying error that caused this error */
+    cause?: Error;
+    /** Machine-readable error code for programmatic handling */
+    code?: HeaderErrorCodeType;
+    /** Additional context about the error */
+    context?: Record<string, unknown>;
+}
+/**
+ * Error class for email header operations.
+ *
+ * Supports ES2022 Error.cause for error chaining.
+ *
+ * @example
+ * ```typescript
+ * throw new HeaderError('Invalid message ID format', {
+ *   code: HeaderErrorCode.INVALID_MESSAGE_ID,
+ *   context: { messageId: 'bad-id' }
+ * });
+ * ```
+ */
+export declare class HeaderError extends Error {
+    readonly code: HeaderErrorCodeType;
+    readonly context: Record<string, unknown> | undefined;
+    constructor(message: string, options?: HeaderErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;CAKlB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAE1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB;CAc1D"}

package/dist/errors.js

@@ -0,0 +1,48 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeaderError = exports.HeaderErrorCode = void 0;
+/**
+ * Error codes for programmatic error handling in email header operations.
+ */
+exports.HeaderErrorCode = {
+    INVALID_HEADER: 'INVALID_HEADER',
+    INVALID_MESSAGE_ID: 'INVALID_MESSAGE_ID',
+    INVALID_EMAIL: 'INVALID_EMAIL',
+    PARSE_ERROR: 'PARSE_ERROR',
+};
+/**
+ * Error class for email header operations.
+ *
+ * Supports ES2022 Error.cause for error chaining.
+ *
+ * @example
+ * ```typescript
+ * throw new HeaderError('Invalid message ID format', {
+ *   code: HeaderErrorCode.INVALID_MESSAGE_ID,
+ *   context: { messageId: 'bad-id' }
+ * });
+ * ```
+ */
+class HeaderError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'HeaderError';
+        this.code = options?.code ?? exports.HeaderErrorCode.INVALID_HEADER;
+        this.context = options?.context;
+        // Set cause using ES2022 pattern (works at runtime in Node 16.9+)
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+        // Maintains proper stack trace in V8 engines
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+exports.HeaderError = HeaderError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AAEF;;GAEG;AACU,QAAA,eAAe,GAAG;IAC7B,cAAc,EAAE,gBAAgB;IAChC,kBAAkB,EAAE,oBAAoB;IACxC,aAAa,EAAE,eAAe;IAC9B,WAAW,EAAE,aAAa;CAClB,CAAC;AAgBX;;;;;;;;;;;;GAYG;AACH,MAAa,WAAY,SAAQ,KAAK;IAIpC,YAAY,OAAe,EAAE,OAA4B;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,uBAAe,CAAC,cAAc,CAAC;QAC5D,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;QAEhC,kEAAkE;QAClE,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YAClB,IAAoC,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC9D,CAAC;QAED,6CAA6C;QAC7C,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACpD,CAAC;CACF;AAlBD,kCAkBC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './errors';
+export * from './threading';
+export * from './unsubscribe';
+export * from './mdn';
+export * from './merge';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./threading"), exports);
+__exportStar(require("./unsubscribe"), exports);
+__exportStar(require("./mdn"), exports);
+__exportStar(require("./merge"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;;;;;;;;;;;;;;AAEF,0CAAwB;AACxB,2CAAyB;AACzB,8CAA4B;AAC5B,gDAA8B;AAC9B,wCAAsB;AACtB,0CAAwB"}

package/dist/mdn.d.ts

@@ -0,0 +1,41 @@
+import type { MdnDisposition } from './types';
+/**
+ * Create a Disposition-Notification-To header for requesting read receipts.
+ *
+ * @param notifyEmail - Email address to send the MDN notification to
+ * @returns Record with Disposition-Notification-To header
+ *
+ * @throws {HeaderError} If the email format is invalid
+ *
+ * @example
+ * ```typescript
+ * const headers = createMdnRequestHeader('sender@example.com');
+ * // { 'Disposition-Notification-To': 'sender@example.com' }
+ * ```
+ */
+export declare function createMdnRequestHeader(notifyEmail: string): Record<string, string>;
+/**
+ * Parse an MDN (Message Disposition Notification) response body per RFC 3798.
+ *
+ * MDN bodies contain fields like:
+ * - Original-Message-ID: <message-id>
+ * - Final-Recipient: rfc822; user@example.com
+ * - Disposition: automatic-action/MDN-sent-automatically; displayed
+ *
+ * @param mdnContent - The MDN body content to parse
+ * @returns Parsed MDN disposition information
+ *
+ * @throws {HeaderError} If required fields are missing or disposition is invalid
+ *
+ * @example
+ * ```typescript
+ * const mdn = parseMdnResponse(
+ *   'Original-Message-ID: <abc@example.com>\r\n' +
+ *   'Final-Recipient: rfc822; user@example.com\r\n' +
+ *   'Disposition: manual-action/MDN-sent-manually; displayed\r\n'
+ * );
+ * // { originalMessageId: '<abc@example.com>', recipient: 'user@example.com', disposition: 'displayed' }
+ * ```
+ */
+export declare function parseMdnResponse(mdnContent: string): MdnDisposition;
+//# sourceMappingURL=mdn.d.ts.map

package/dist/mdn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdn.d.ts","sourceRoot":"","sources":["../src/mdn.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAsB9C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBxB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAkFnE"}

package/dist/mdn.js

@@ -0,0 +1,160 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMdnRequestHeader = createMdnRequestHeader;
+exports.parseMdnResponse = parseMdnResponse;
+const errors_1 = require("./errors");
+/**
+ * Basic email format validation.
+ */
+function isValidEmail(email) {
+    // Simple but reasonable email regex
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+/**
+ * Valid MDN disposition types per RFC 3798.
+ */
+const VALID_DISPOSITIONS = new Set([
+    'displayed',
+    'deleted',
+    'dispatched',
+    'processed',
+    'denied',
+    'failed',
+]);
+/**
+ * Create a Disposition-Notification-To header for requesting read receipts.
+ *
+ * @param notifyEmail - Email address to send the MDN notification to
+ * @returns Record with Disposition-Notification-To header
+ *
+ * @throws {HeaderError} If the email format is invalid
+ *
+ * @example
+ * ```typescript
+ * const headers = createMdnRequestHeader('sender@example.com');
+ * // { 'Disposition-Notification-To': 'sender@example.com' }
+ * ```
+ */
+function createMdnRequestHeader(notifyEmail) {
+    if (!notifyEmail || notifyEmail.trim().length === 0) {
+        throw new errors_1.HeaderError('Notification email is required', {
+            code: errors_1.HeaderErrorCode.INVALID_EMAIL,
+            context: { notifyEmail },
+        });
+    }
+    const trimmed = notifyEmail.trim();
+    if (!isValidEmail(trimmed)) {
+        throw new errors_1.HeaderError('Invalid email format for MDN notification', {
+            code: errors_1.HeaderErrorCode.INVALID_EMAIL,
+            context: { notifyEmail: trimmed },
+        });
+    }
+    return {
+        'Disposition-Notification-To': trimmed,
+    };
+}
+/**
+ * Parse an MDN (Message Disposition Notification) response body per RFC 3798.
+ *
+ * MDN bodies contain fields like:
+ * - Original-Message-ID: <message-id>
+ * - Final-Recipient: rfc822; user@example.com
+ * - Disposition: automatic-action/MDN-sent-automatically; displayed
+ *
+ * @param mdnContent - The MDN body content to parse
+ * @returns Parsed MDN disposition information
+ *
+ * @throws {HeaderError} If required fields are missing or disposition is invalid
+ *
+ * @example
+ * ```typescript
+ * const mdn = parseMdnResponse(
+ *   'Original-Message-ID: <abc@example.com>\r\n' +
+ *   'Final-Recipient: rfc822; user@example.com\r\n' +
+ *   'Disposition: manual-action/MDN-sent-manually; displayed\r\n'
+ * );
+ * // { originalMessageId: '<abc@example.com>', recipient: 'user@example.com', disposition: 'displayed' }
+ * ```
+ */
+function parseMdnResponse(mdnContent) {
+    if (!mdnContent || mdnContent.trim().length === 0) {
+        throw new errors_1.HeaderError('MDN content is required', {
+            code: errors_1.HeaderErrorCode.PARSE_ERROR,
+            context: { mdnContent },
+        });
+    }
+    // Parse fields from MDN body (case-insensitive)
+    const lines = mdnContent.split(/\r?\n/);
+    const fields = {};
+    for (const line of lines) {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex > 0) {
+            const key = line.substring(0, colonIndex).trim().toLowerCase();
+            const value = line.substring(colonIndex + 1).trim();
+            fields[key] = value;
+        }
+    }
+    // Extract Original-Message-ID
+    const originalMessageId = fields['original-message-id'];
+    if (originalMessageId === undefined || originalMessageId.length === 0) {
+        throw new errors_1.HeaderError('Missing Original-Message-ID in MDN response', {
+            code: errors_1.HeaderErrorCode.PARSE_ERROR,
+            context: { fields },
+        });
+    }
+    // Extract Final-Recipient (format: rfc822; user@example.com)
+    const finalRecipientRaw = fields['final-recipient'];
+    if (finalRecipientRaw === undefined || finalRecipientRaw.length === 0) {
+        throw new errors_1.HeaderError('Missing Final-Recipient in MDN response', {
+            code: errors_1.HeaderErrorCode.PARSE_ERROR,
+            context: { fields },
+        });
+    }
+    let recipient = finalRecipientRaw;
+    // Strip "rfc822;" or "rfc822; " prefix if present
+    const semicolonIndex = finalRecipientRaw.indexOf(';');
+    if (semicolonIndex >= 0) {
+        recipient = finalRecipientRaw.substring(semicolonIndex + 1).trim();
+    }
+    // Extract Disposition (format: action-mode/sending-mode; disposition-type)
+    const dispositionRaw = fields['disposition'];
+    if (dispositionRaw === undefined || dispositionRaw.length === 0) {
+        throw new errors_1.HeaderError('Missing Disposition in MDN response', {
+            code: errors_1.HeaderErrorCode.PARSE_ERROR,
+            context: { fields },
+        });
+    }
+    // Parse disposition type from the value after the last semicolon
+    const dispositionSemicolonIndex = dispositionRaw.lastIndexOf(';');
+    let dispositionType;
+    if (dispositionSemicolonIndex >= 0) {
+        dispositionType = dispositionRaw.substring(dispositionSemicolonIndex + 1).trim().toLowerCase();
+    }
+    else {
+        dispositionType = dispositionRaw.trim().toLowerCase();
+    }
+    // Handle composite disposition types like "displayed/error" - take the first part
+    const slashIndex = dispositionType.indexOf('/');
+    if (slashIndex >= 0) {
+        dispositionType = dispositionType.substring(0, slashIndex).trim();
+    }
+    if (!VALID_DISPOSITIONS.has(dispositionType)) {
+        throw new errors_1.HeaderError(`Invalid disposition type: ${dispositionType}`, {
+            code: errors_1.HeaderErrorCode.PARSE_ERROR,
+            context: { dispositionType, raw: dispositionRaw },
+        });
+    }
+    return {
+        originalMessageId,
+        recipient,
+        disposition: dispositionType,
+    };
+}
+//# sourceMappingURL=mdn.js.map

package/dist/mdn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdn.js","sourceRoot":"","sources":["../src/mdn.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;AAuCF,wDAqBC;AAyBD,4CAkFC;AArKD,qCAAwD;AAGxD;;GAEG;AACH,SAAS,YAAY,CAAC,KAAa;IACjC,oCAAoC;IACpC,OAAO,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,WAAW;IACX,SAAS;IACT,YAAY;IACZ,WAAW;IACX,QAAQ;IACR,QAAQ;CACT,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,SAAgB,sBAAsB,CACpC,WAAmB;IAEnB,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,oBAAW,CAAC,gCAAgC,EAAE;YACtD,IAAI,EAAE,wBAAe,CAAC,aAAa;YACnC,OAAO,EAAE,EAAE,WAAW,EAAE;SACzB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,oBAAW,CAAC,2CAA2C,EAAE;YACjE,IAAI,EAAE,wBAAe,CAAC,aAAa;YACnC,OAAO,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE;SAClC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,6BAA6B,EAAE,OAAO;KACvC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,gBAAgB,CAAC,UAAkB;IACjD,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,oBAAW,CAAC,yBAAyB,EAAE;YAC/C,IAAI,EAAE,wBAAe,CAAC,WAAW;YACjC,OAAO,EAAE,EAAE,UAAU,EAAE;SACxB,CAAC,CAAC;IACL,CAAC;IAED,gDAAgD;IAChD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACpD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,MAAM,iBAAiB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;IACxD,IAAI,iBAAiB,KAAK,SAAS,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,oBAAW,CAAC,6CAA6C,EAAE;YACnE,IAAI,EAAE,wBAAe,CAAC,WAAW;YACjC,OAAO,EAAE,EAAE,MAAM,EAAE;SACpB,CAAC,CAAC;IACL,CAAC;IAED,6DAA6D;IAC7D,MAAM,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;IACpD,IAAI,iBAAiB,KAAK,SAAS,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,oBAAW,CAAC,yCAAyC,EAAE;YAC/D,IAAI,EAAE,wBAAe,CAAC,WAAW;YACjC,OAAO,EAAE,EAAE,MAAM,EAAE;SACpB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,SAAS,GAAG,iBAAiB,CAAC;IAClC,kDAAkD;IAClD,MAAM,cAAc,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtD,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACxB,SAAS,GAAG,iBAAiB,CAAC,SAAS,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrE,CAAC;IAED,2EAA2E;IAC3E,MAAM,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;IAC7C,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,oBAAW,CAAC,qCAAqC,EAAE;YAC3D,IAAI,EAAE,wBAAe,CAAC,WAAW;YACjC,OAAO,EAAE,EAAE,MAAM,EAAE;SACpB,CAAC,CAAC;IACL,CAAC;IAED,iEAAiE;IACjE,MAAM,yBAAyB,GAAG,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClE,IAAI,eAAuB,CAAC;IAC5B,IAAI,yBAAyB,IAAI,CAAC,EAAE,CAAC;QACnC,eAAe,GAAG,cAAc,CAAC,SAAS,CAAC,yBAAyB,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjG,CAAC;SAAM,CAAC;QACN,eAAe,GAAG,cAAc,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxD,CAAC;IAED,kFAAkF;IAClF,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACpB,eAAe,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IACpE,CAAC;IAED,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,oBAAW,CAAC,6BAA6B,eAAe,EAAE,EAAE;YACpE,IAAI,EAAE,wBAAe,CAAC,WAAW;YACjC,OAAO,EAAE,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,EAAE;SAClD,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,iBAAiB;QACjB,SAAS;QACT,WAAW,EAAE,eAAgD;KAC9D,CAAC;AACJ,CAAC"}

package/dist/merge.d.ts

@@ -0,0 +1,21 @@
+import type { EmailHeaders } from './types';
+/**
+ * Merge multiple email header objects into one.
+ *
+ * Later values override earlier ones for the same key.
+ *
+ * @param base - The base headers to start with
+ * @param additional - Additional header sets to merge in order
+ * @returns Merged headers
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeHeaders(
+ *   { 'From': 'a@example.com', 'Subject': 'Hello' },
+ *   { 'Subject': 'Updated', 'X-Custom': 'value' }
+ * );
+ * // { 'From': 'a@example.com', 'Subject': 'Updated', 'X-Custom': 'value' }
+ * ```
+ */
+export declare function mergeHeaders(base: EmailHeaders, ...additional: EmailHeaders[]): EmailHeaders;
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,YAAY,EAClB,GAAG,UAAU,EAAE,YAAY,EAAE,GAC5B,YAAY,CAad"}

package/dist/merge.js

@@ -0,0 +1,41 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeHeaders = mergeHeaders;
+/**
+ * Merge multiple email header objects into one.
+ *
+ * Later values override earlier ones for the same key.
+ *
+ * @param base - The base headers to start with
+ * @param additional - Additional header sets to merge in order
+ * @returns Merged headers
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeHeaders(
+ *   { 'From': 'a@example.com', 'Subject': 'Hello' },
+ *   { 'Subject': 'Updated', 'X-Custom': 'value' }
+ * );
+ * // { 'From': 'a@example.com', 'Subject': 'Updated', 'X-Custom': 'value' }
+ * ```
+ */
+function mergeHeaders(base, ...additional) {
+    const result = { ...base };
+    for (const headers of additional) {
+        for (const key of Object.keys(headers)) {
+            const value = headers[key];
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=merge.js.map

package/dist/merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../src/merge.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;AAsBF,oCAgBC;AAlCD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,YAAY,CAC1B,IAAkB,EAClB,GAAG,UAA0B;IAE7B,MAAM,MAAM,GAAiB,EAAE,GAAG,IAAI,EAAE,CAAC;IAEzC,KAAK,MAAM,OAAO,IAAI,UAAU,EAAE,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/threading.d.ts

@@ -0,0 +1,34 @@
+import type { ParsedThreadingInfo } from './types';
+/**
+ * Create threading headers (In-Reply-To and References) for email replies.
+ *
+ * @param inReplyTo - The message ID being replied to
+ * @param references - Optional array of previous message IDs in the thread
+ * @returns Record with 'In-Reply-To' and 'References' headers
+ *
+ * @example
+ * ```typescript
+ * const headers = createThreadingHeaders('abc@example.com', ['root@example.com']);
+ * // { 'In-Reply-To': '<abc@example.com>', 'References': '<root@example.com> <abc@example.com>' }
+ * ```
+ */
+export declare function createThreadingHeaders(inReplyTo: string, references?: string[]): Record<string, string>;
+/**
+ * Parse threading headers from an email message.
+ *
+ * Performs case-insensitive header lookup to handle different email systems.
+ *
+ * @param headers - Raw email headers as key-value pairs
+ * @returns Parsed threading information
+ *
+ * @example
+ * ```typescript
+ * const info = parseThreadingHeaders({
+ *   'In-Reply-To': '<reply@example.com>',
+ *   'References': '<root@example.com> <reply@example.com>'
+ * });
+ * // { inReplyTo: '<reply@example.com>', references: ['<root@example.com>', '<reply@example.com>'], threadId: '<root@example.com>' }
+ * ```
+ */
+export declare function parseThreadingHeaders(headers: Record<string, string>): ParsedThreadingInfo;
+//# sourceMappingURL=threading.d.ts.map

package/dist/threading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threading.d.ts","sourceRoot":"","sources":["../src/threading.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AA6BnD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8BxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,mBAAmB,CAqCrB"}

package/dist/threading.js

@@ -0,0 +1,128 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createThreadingHeaders = createThreadingHeaders;
+exports.parseThreadingHeaders = parseThreadingHeaders;
+const errors_1 = require("./errors");
+/**
+ * Wrap a message ID in angle brackets if not already wrapped.
+ */
+function ensureAngleBrackets(messageId) {
+    const trimmed = messageId.trim();
+    if (trimmed.startsWith('<') && trimmed.endsWith('>')) {
+        return trimmed;
+    }
+    return `<${trimmed}>`;
+}
+/**
+ * Extract message IDs from a header value (space or comma separated, angle-bracketed).
+ */
+function extractMessageIds(headerValue) {
+    const matches = headerValue.match(/<[^>]+>/g);
+    if (!matches) {
+        // Try treating the whole value as a single message ID
+        const trimmed = headerValue.trim();
+        if (trimmed.length > 0) {
+            return [trimmed];
+        }
+        return [];
+    }
+    return matches;
+}
+/**
+ * Create threading headers (In-Reply-To and References) for email replies.
+ *
+ * @param inReplyTo - The message ID being replied to
+ * @param references - Optional array of previous message IDs in the thread
+ * @returns Record with 'In-Reply-To' and 'References' headers
+ *
+ * @example
+ * ```typescript
+ * const headers = createThreadingHeaders('abc@example.com', ['root@example.com']);
+ * // { 'In-Reply-To': '<abc@example.com>', 'References': '<root@example.com> <abc@example.com>' }
+ * ```
+ */
+function createThreadingHeaders(inReplyTo, references) {
+    if (!inReplyTo || inReplyTo.trim().length === 0) {
+        throw new errors_1.HeaderError('inReplyTo message ID is required', {
+            code: errors_1.HeaderErrorCode.INVALID_MESSAGE_ID,
+            context: { inReplyTo },
+        });
+    }
+    const wrappedInReplyTo = ensureAngleBrackets(inReplyTo);
+    // Build references: existing refs + the inReplyTo at the end
+    const refIds = [];
+    if (references && references.length > 0) {
+        for (const ref of references) {
+            const wrapped = ensureAngleBrackets(ref);
+            if (!refIds.includes(wrapped)) {
+                refIds.push(wrapped);
+            }
+        }
+    }
+    // Add inReplyTo at the end if not already present
+    if (!refIds.includes(wrappedInReplyTo)) {
+        refIds.push(wrappedInReplyTo);
+    }
+    return {
+        'In-Reply-To': wrappedInReplyTo,
+        'References': refIds.join(' '),
+    };
+}
+/**
+ * Parse threading headers from an email message.
+ *
+ * Performs case-insensitive header lookup to handle different email systems.
+ *
+ * @param headers - Raw email headers as key-value pairs
+ * @returns Parsed threading information
+ *
+ * @example
+ * ```typescript
+ * const info = parseThreadingHeaders({
+ *   'In-Reply-To': '<reply@example.com>',
+ *   'References': '<root@example.com> <reply@example.com>'
+ * });
+ * // { inReplyTo: '<reply@example.com>', references: ['<root@example.com>', '<reply@example.com>'], threadId: '<root@example.com>' }
+ * ```
+ */
+function parseThreadingHeaders(headers) {
+    // Case-insensitive header lookup
+    const normalizedHeaders = {};
+    for (const key of Object.keys(headers)) {
+        normalizedHeaders[key.toLowerCase()] = headers[key];
+    }
+    const inReplyToValue = normalizedHeaders['in-reply-to'];
+    const referencesValue = normalizedHeaders['references'];
+    // Parse In-Reply-To
+    let inReplyTo = null;
+    if (inReplyToValue !== undefined && inReplyToValue.trim().length > 0) {
+        const ids = extractMessageIds(inReplyToValue);
+        // In-Reply-To typically contains a single message ID
+        inReplyTo = ids[0] ?? null;
+    }
+    // Parse References
+    const references = [];
+    if (referencesValue !== undefined && referencesValue.trim().length > 0) {
+        const ids = extractMessageIds(referencesValue);
+        for (const id of ids) {
+            if (!references.includes(id)) {
+                references.push(id);
+            }
+        }
+    }
+    // Thread ID is the first message in the references chain
+    const threadId = references.length > 0 ? references[0] : null;
+    return {
+        inReplyTo,
+        references,
+        threadId,
+    };
+}
+//# sourceMappingURL=threading.js.map

package/dist/threading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threading.js","sourceRoot":"","sources":["../src/threading.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generic email headers as key-value pairs.
+ * Values can be a single string or an array of strings for multi-value headers.
+ */
+export type EmailHeaders = Record<string, string | string[]>;
+/**
+ * Headers for email threading (In-Reply-To and References).
+ */
+export interface ThreadingHeaders {
+    readonly inReplyTo: string;
+    readonly references?: readonly string[];
+}
+/**
+ * Headers for list unsubscribe functionality (RFC 8058).
+ */
+export interface ListUnsubscribeHeaders {
+    readonly listUnsubscribe: string;
+    readonly listUnsubscribePost?: string;
+}
+/**
+ * Parsed MDN (Message Disposition Notification) disposition.
+ */
+export interface MdnDisposition {
+    readonly originalMessageId: string;
+    readonly recipient: string;
+    readonly disposition: 'displayed' | 'deleted' | 'dispatched' | 'processed' | 'denied' | 'failed';
+}
+/**
+ * Options for requesting an MDN read receipt.
+ */
+export interface MdnRequestOptions {
+    readonly notifyEmail: string;
+}
+/**
+ * Parsed threading information from email headers.
+ */
+export interface ParsedThreadingInfo {
+    readonly inReplyTo: string | null;
+    readonly references: readonly string[];
+    readonly threadId: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;CAClG;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC"}

package/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;EAME"}

package/dist/unsubscribe.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Create List-Unsubscribe headers per RFC 2369 and optionally RFC 8058 (one-click).
+ *
+ * @param url - The HTTPS unsubscribe URL (must be HTTPS)
+ * @param mailto - Optional mailto address for unsubscribe
+ * @param oneClick - If true, adds List-Unsubscribe-Post header for RFC 8058 one-click unsubscribe
+ * @returns Record with List-Unsubscribe and optionally List-Unsubscribe-Post headers
+ *
+ * @throws {HeaderError} If the URL is not HTTPS
+ *
+ * @example
+ * ```typescript
+ * const headers = createListUnsubscribeHeaders(
+ *   'https://example.com/unsubscribe?token=abc',
+ *   'unsubscribe@example.com',
+ *   true
+ * );
+ * // {
+ * //   'List-Unsubscribe': '<https://example.com/unsubscribe?token=abc>, <mailto:unsubscribe@example.com>',
+ * //   'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
+ * // }
+ * ```
+ */
+export declare function createListUnsubscribeHeaders(url: string, mailto?: string, oneClick?: boolean): Record<string, string>;
+//# sourceMappingURL=unsubscribe.d.ts.map

package/dist/unsubscribe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe.d.ts","sourceRoot":"","sources":["../src/unsubscribe.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,OAAO,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsCxB"}

package/dist/unsubscribe.js

@@ -0,0 +1,69 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createListUnsubscribeHeaders = createListUnsubscribeHeaders;
+const errors_1 = require("./errors");
+/**
+ * Create List-Unsubscribe headers per RFC 2369 and optionally RFC 8058 (one-click).
+ *
+ * @param url - The HTTPS unsubscribe URL (must be HTTPS)
+ * @param mailto - Optional mailto address for unsubscribe
+ * @param oneClick - If true, adds List-Unsubscribe-Post header for RFC 8058 one-click unsubscribe
+ * @returns Record with List-Unsubscribe and optionally List-Unsubscribe-Post headers
+ *
+ * @throws {HeaderError} If the URL is not HTTPS
+ *
+ * @example
+ * ```typescript
+ * const headers = createListUnsubscribeHeaders(
+ *   'https://example.com/unsubscribe?token=abc',
+ *   'unsubscribe@example.com',
+ *   true
+ * );
+ * // {
+ * //   'List-Unsubscribe': '<https://example.com/unsubscribe?token=abc>, <mailto:unsubscribe@example.com>',
+ * //   'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
+ * // }
+ * ```
+ */
+function createListUnsubscribeHeaders(url, mailto, oneClick) {
+    if (!url || url.trim().length === 0) {
+        throw new errors_1.HeaderError('Unsubscribe URL is required', {
+            code: errors_1.HeaderErrorCode.INVALID_HEADER,
+            context: { url },
+        });
+    }
+    // Validate HTTPS
+    const trimmedUrl = url.trim();
+    if (!trimmedUrl.toLowerCase().startsWith('https://')) {
+        throw new errors_1.HeaderError('Unsubscribe URL must use HTTPS', {
+            code: errors_1.HeaderErrorCode.INVALID_HEADER,
+            context: { url: trimmedUrl },
+        });
+    }
+    // Build List-Unsubscribe value
+    const parts = [`<${trimmedUrl}>`];
+    if (mailto !== undefined && mailto.trim().length > 0) {
+        const trimmedMailto = mailto.trim();
+        // Add mailto: prefix if not already present
+        const mailtoUri = trimmedMailto.startsWith('mailto:')
+            ? trimmedMailto
+            : `mailto:${trimmedMailto}`;
+        parts.push(`<${mailtoUri}>`);
+    }
+    const result = {
+        'List-Unsubscribe': parts.join(', '),
+    };
+    // RFC 8058 one-click unsubscribe
+    if (oneClick === true) {
+        result['List-Unsubscribe-Post'] = 'List-Unsubscribe=One-Click';
+    }
+    return result;
+}
+//# sourceMappingURL=unsubscribe.js.map

package/dist/unsubscribe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsubscribe.js","sourceRoot":"","sources":["../src/unsubscribe.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;AA2BF,oEA0CC;AAnED,qCAAwD;AAExD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,4BAA4B,CAC1C,GAAW,EACX,MAAe,EACf,QAAkB;IAElB,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,oBAAW,CAAC,6BAA6B,EAAE;YACnD,IAAI,EAAE,wBAAe,CAAC,cAAc;YACpC,OAAO,EAAE,EAAE,GAAG,EAAE;SACjB,CAAC,CAAC;IACL,CAAC;IAED,iBAAiB;IACjB,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,oBAAW,CAAC,gCAAgC,EAAE;YACtD,IAAI,EAAE,wBAAe,CAAC,cAAc;YACpC,OAAO,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,+BAA+B;IAC/B,MAAM,KAAK,GAAa,CAAC,IAAI,UAAU,GAAG,CAAC,CAAC;IAC5C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrD,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QACpC,4CAA4C;QAC5C,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,CAAC,SAAS,CAAC;YACnD,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,UAAU,aAAa,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,MAAM,GAA2B;QACrC,kBAAkB,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;KACrC,CAAC;IAEF,iCAAiC;IACjC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,CAAC,uBAAuB,CAAC,GAAG,4BAA4B,CAAC;IACjE,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,10 +1,53 @@
 {
   "name": "@bernierllc/email-headers",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @bernierllc/email-headers",
+  "version": "0.2.0",
+  "description": "Email header construction and parsing utilities for threading, unsubscribe, and read receipts with zero external dependencies",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "email",
+    "headers",
+    "threading",
+    "unsubscribe",
+    "mdn",
+    "read-receipt",
+    "rfc-8058",
+    "rfc-3798",
+    "typescript"
+  ],
+  "author": "Bernier LLC",
+  "license": "PROPRIETARY",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bernier-llc/tools"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:run": "jest --watchAll=false --forceExit",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean"
+  }
+}

package/README.md

@@ -1,45 +0,0 @@
-# @bernierllc/email-headers
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@bernierllc/email-headers`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**