mailfile 0.1.0

package/src/msg/write.js

@@ -0,0 +1,124 @@
+/** Message data -> compound file + MAPI properties. */
+import { addStorage, addStream, newRoot, write as writeCfb } from '../cfb/write.js';
+import { PropertyWriter } from '../mapi/bag.js';
+import { HeaderSize, MSG_CLSID, PropId, RecipientType, hex8 } from '../mapi/tags.js';
+import { utf8Encode } from '../mime/encodings.js';
+import { guessMime, shortName } from '../util.js';
+
+const MSGFLAG_READ = 0x01;
+const STORE_UNICODE_OK = 0x00040000;
+const CP_UTF8 = 65001;
+const ATT_MHTML_REF = 0x04;
+
+const displayName = (a) => a.name || a.email;
+
+/**
+ * Build a `.msg` file from message data.
+ * @param {object} msg
+ * @returns {Uint8Array}
+ */
+export function writeMsg(msg) {
+  const root = newRoot(MSG_CLSID);
+
+  // Required by the format even when no named properties are used.
+  const nameid = addStorage(root, '__nameid_version1.0');
+  addStream(nameid, '__substg1.0_00020102', new Uint8Array(0));
+  addStream(nameid, '__substg1.0_00030102', new Uint8Array(0));
+  addStream(nameid, '__substg1.0_00040102', new Uint8Array(0));
+
+  const to = msg.to || [];
+  const cc = msg.cc || [];
+  const bcc = msg.bcc || [];
+  const attachments = msg.attachments || [];
+  const from = msg.from || { name: '', email: '' };
+
+  const p = new PropertyWriter(root, HeaderSize.TOP_LEVEL);
+  p.str(PropId.MESSAGE_CLASS, msg.messageClass || 'IPM.Note');
+  p.str(PropId.SUBJECT, msg.subject || '');
+  p.str(PropId.NORMALIZED_SUBJECT, (msg.subject || '').replace(/^\s*(re|fw|fwd)\s*:\s*/i, ''));
+  p.str(PropId.BODY, msg.text || '');
+  if (msg.html) p.bin(PropId.HTML, utf8Encode(msg.html));
+  if (msg.headersRaw) p.str(PropId.TRANSPORT_HEADERS, msg.headersRaw);
+  p.str(PropId.INTERNET_MESSAGE_ID, msg.messageId || '');
+  p.str(PropId.IN_REPLY_TO_ID, msg.inReplyTo || '');
+  p.str(PropId.INTERNET_REFERENCES, msg.references || '');
+
+  const addrType = from.email ? 'SMTP' : '';
+  p.str(PropId.SENDER_NAME, from.name || from.email || '');
+  p.str(PropId.SENDER_EMAIL, from.email || '');
+  p.str(PropId.SENDER_ADDRTYPE, addrType);
+  p.str(PropId.SENDER_SMTP, from.email || '');
+  p.str(PropId.SENT_REP_NAME, from.name || from.email || '');
+  p.str(PropId.SENT_REP_EMAIL, from.email || '');
+  p.str(PropId.SENT_REP_ADDRTYPE, addrType);
+  p.str(PropId.SENT_REP_SMTP, from.email || '');
+
+  p.str(PropId.DISPLAY_TO, to.map(displayName).join('; '));
+  p.str(PropId.DISPLAY_CC, cc.map(displayName).join('; '));
+  p.str(PropId.DISPLAY_BCC, bcc.map(displayName).join('; '));
+
+  p.time(PropId.CLIENT_SUBMIT_TIME, msg.date);
+  p.time(PropId.DELIVERY_TIME, msg.date);
+  p.time(PropId.CREATION_TIME, msg.date || new Date());
+  p.time(PropId.LAST_MODIFICATION_TIME, new Date());
+
+  p.int32(PropId.MESSAGE_FLAGS, MSGFLAG_READ);
+  p.int32(PropId.STORE_SUPPORT_MASK, STORE_UNICODE_OK);
+  p.int32(PropId.INTERNET_CPID, CP_UTF8);
+  p.int32(PropId.MESSAGE_CODEPAGE, CP_UTF8);
+  if (msg.importance != null) p.int32(PropId.IMPORTANCE, msg.importance);
+  p.bool(PropId.HASATTACH, attachments.length > 0);
+
+  const recipients = [
+    ...to.map((a) => ({ a, t: RecipientType.TO })),
+    ...cc.map((a) => ({ a, t: RecipientType.CC })),
+    ...bcc.map((a) => ({ a, t: RecipientType.BCC }))
+  ];
+
+  recipients.forEach((r, i) => {
+    const node = addStorage(root, '__recip_version1.0_#' + hex8(i));
+    const rp = new PropertyWriter(node, HeaderSize.RECIPIENT);
+    rp.int32(PropId.ROWID, i);
+    rp.int32(PropId.RECIPIENT_TYPE, r.t);
+    rp.int32(PropId.OBJECT_TYPE, 6);  // MAPI_MAILUSER
+    rp.int32(PropId.DISPLAY_TYPE, 0); // DT_MAILUSER
+    rp.str(PropId.DISPLAY_NAME, r.a.name || r.a.email);
+    rp.str(PropId.EMAIL_ADDRESS, r.a.email);
+    rp.str(PropId.SMTP_ADDRESS, r.a.email);
+    rp.str(PropId.ADDRTYPE, 'SMTP');
+    rp.finish();
+  });
+
+  attachments.forEach((att, i) => {
+    const node = addStorage(root, '__attach_version1.0_#' + hex8(i));
+    const ap = new PropertyWriter(node, HeaderSize.ATTACHMENT);
+    ap.int32(PropId.ATTACH_NUM, i);
+    ap.int32(PropId.ATTACH_METHOD, 1); // ATTACH_BY_VALUE
+    ap.int32(PropId.OBJECT_TYPE, 7);   // MAPI_ATTACH
+    ap.int32(PropId.ATTACH_SIZE, att.data.length);
+    ap.int32(PropId.RENDERING_POSITION, -1);
+    ap.bin(PropId.ATTACH_DATA_BIN, att.data);
+    ap.str(PropId.ATTACH_LONG_FILENAME, att.filename);
+    ap.str(PropId.ATTACH_FILENAME, shortName(att.filename));
+    const ext = /\.[A-Za-z0-9]+$/.exec(att.filename);
+    if (ext) ap.str(PropId.ATTACH_EXTENSION, ext[0]);
+    ap.str(PropId.ATTACH_MIME_TAG, att.mime || guessMime(att.filename));
+    if (att.cid) {
+      ap.str(PropId.ATTACH_CONTENT_ID, att.cid);
+      if (att.inline) {
+        ap.int32(PropId.ATTACH_FLAGS, ATT_MHTML_REF);
+        ap.bool(PropId.ATTACHMENT_HIDDEN, true);
+      }
+    }
+    ap.finish();
+  });
+
+  p.finish((dv) => {
+    dv.setUint32(8, recipients.length, true);   // next recipient id
+    dv.setUint32(12, attachments.length, true); // next attachment id
+    dv.setUint32(16, recipients.length, true);  // recipient count
+    dv.setUint32(20, attachments.length, true); // attachment count
+  });
+
+  return writeCfb(root);
+}

package/src/rtf/deencapsulate.js

@@ -0,0 +1,155 @@
+/** Recover HTML from RTF that encapsulates it (\fromhtml1) — MS-OXRTFEX. */
+
+const ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
+const esc = (s) => s.replace(/[&<>]/g, (c) => ENTITIES[c]);
+
+const SIMPLE = {
+  lquote: '&lsquo;', rquote: '&rsquo;', ldblquote: '&ldquo;', rdblquote: '&rdquo;',
+  emdash: '&mdash;', endash: '&ndash;', bullet: '&bull;', nbsp: '&nbsp;'
+};
+
+const SKIP_DESTINATIONS = new Set([
+  'fonttbl', 'colortbl', 'stylesheet', 'info', 'pntext', 'generator'
+]);
+
+/**
+ * @param {string} rtf
+ * @returns {boolean} True if this RTF carries encapsulated HTML or text.
+ */
+export function isEncapsulated(rtf) {
+  return /\\from(html|text)1?/.test(rtf.slice(0, 4096));
+}
+
+/**
+ * Walk the RTF and emit the original HTML.
+ *
+ * `\*\htmltag` destinations hold the real markup; `\htmlrtf`/`\htmlrtf0`
+ * brackets the RTF-only rendering text that must be dropped.
+ *
+ * @param {string} rtf RTF as raw bytes widened to chars (one char per byte).
+ * @param {(bytes: Uint8Array) => string} decode Code-page decoder.
+ * @returns {string}
+ */
+export function deencapsulate(rtf, decode) {
+  const out = [];
+  const suppressStack = [];
+  let i = 0;
+  const len = rtf.length;
+  let suppress = false;   // inside \htmlrtf ... \htmlrtf0
+  let inHtmlTag = 0;      // group depth of the active \*\htmltag destination
+  let depth = 0;
+  let skipDest = 0;       // group depth of a destination to drop entirely
+  let pendingSkipWord = false;
+  let textBytes = [];     // buffered so multi-byte code pages decode correctly
+  const fromText = /\\fromtext/.test(rtf.slice(0, 4096));
+
+  function emit(s) {
+    if (skipDest || (suppress && !inHtmlTag)) return;
+    out.push(s);
+  }
+  function flushBytes() {
+    if (!textBytes.length) return;
+    const s = decode(new Uint8Array(textBytes));
+    textBytes = [];
+    emit(inHtmlTag ? s : esc(s));
+  }
+
+  while (i < len) {
+    const c = rtf[i];
+
+    if (c === '\\') {
+      const next = rtf[i + 1];
+      if (next === '\\' || next === '{' || next === '}') {
+        textBytes.push(next.charCodeAt(0));
+        i += 2;
+        continue;
+      }
+      if (next === "'") {
+        textBytes.push(parseInt(rtf.substr(i + 2, 2), 16) || 0);
+        i += 4;
+        continue;
+      }
+      if (next === '*') { i += 2; pendingSkipWord = true; continue; }
+
+      const m = /^\\([a-zA-Z]+)(-?\d+)? ?/.exec(rtf.slice(i));
+      if (!m) { i += 2; continue; }
+      const word = m[1];
+      const param = m[2] === undefined ? null : parseInt(m[2], 10);
+      i += m[0].length;
+      flushBytes();
+
+      if (word === 'htmltag') { pendingSkipWord = false; inHtmlTag = depth; continue; }
+      if (word === 'htmlrtf') { suppress = param !== 0; continue; }
+      if (word === 'mhtmltag') { skipDest = depth; pendingSkipWord = false; continue; }
+      if (pendingSkipWord) {
+        // An unrecognised \* destination: drop the whole group.
+        skipDest = depth;
+        pendingSkipWord = false;
+        continue;
+      }
+      if (word === 'u' && param !== null) {
+        if (!suppress || inHtmlTag) {
+          const cp = param < 0 ? param + 65536 : param;
+          emit(inHtmlTag ? String.fromCharCode(cp) : esc(String.fromCharCode(cp)));
+        }
+        if (rtf[i] === '?') i++; // skip the ANSI fallback character
+        continue;
+      }
+      if (word === 'par' || word === 'line') { if (fromText) emit('\n'); continue; }
+      if (word === 'tab') { emit('\t'); continue; }
+      if (SIMPLE[word]) { emit(SIMPLE[word]); continue; }
+      if (SKIP_DESTINATIONS.has(word)) { skipDest = depth; continue; }
+      continue;
+    }
+
+    if (c === '{') {
+      flushBytes();
+      depth++;
+      suppressStack.push({ suppress, inHtmlTag });
+      i++;
+      continue;
+    }
+    if (c === '}') {
+      flushBytes();
+      if (skipDest && depth === skipDest) skipDest = 0;
+      if (inHtmlTag && depth === inHtmlTag) inHtmlTag = 0;
+      depth--;
+      const st = suppressStack.pop();
+      if (st) suppress = st.suppress;
+      pendingSkipWord = false;
+      i++;
+      continue;
+    }
+    if (c === '\r' || c === '\n') { i++; continue; }
+
+    textBytes.push(rtf.charCodeAt(i) & 0xFF);
+    i++;
+  }
+  flushBytes();
+
+  const html = out.join('');
+  if (fromText) {
+    return '<html><body><pre style="font-family:inherit;white-space:pre-wrap">' +
+      html + '</pre></body></html>';
+  }
+  return html;
+}
+
+/**
+ * Convenience wrapper: decompressed RTF bytes in, HTML out.
+ * @param {Uint8Array} rtfBytes
+ * @param {(bytes: Uint8Array) => string} decode
+ * @returns {string|null} null when the RTF does not encapsulate HTML.
+ */
+export function rtfToHtml(rtfBytes, decode) {
+  if (!rtfBytes || !rtfBytes.length) return null;
+  let rtf = '';
+  for (let i = 0; i < rtfBytes.length; i++) rtf += String.fromCharCode(rtfBytes[i]);
+  if (!isEncapsulated(rtf)) return null;
+  try {
+    const html = deencapsulate(rtf, decode);
+    return html && html.trim() ? html : null;
+  } catch {
+    return null;
+  }
+}

package/src/rtf/index.js

@@ -0,0 +1,3 @@
+/** Compressed-RTF handling: LZFu plus HTML de-encapsulation. */
+export { decompress } from './lzfu.js';
+export { rtfToHtml, deencapsulate, isEncapsulated } from './deencapsulate.js';

package/src/rtf/lzfu.js

@@ -0,0 +1,67 @@
+/** LZFu decompression for PR_RTF_COMPRESSED — MS-OXRTFCP. */
+
+// The 207-byte preload dictionary defined by the specification.
+const INIT_DICT =
+  '{\\rtf1\\ansi\\mac\\deff0\\deftab720{\\fonttbl;}' +
+  '{\\f0\\fnil \\froman \\fswiss \\fmodern \\fscript \\fdecor MS Sans SerifSymbolArial' +
+  'Times New RomanCourier{\\colortbl\\red0\\green0\\blue0\r\n' +
+  '\\par \\pard\\plain\\f0\\fs20\\b\\i\\u\\tab\\tx';
+
+const COMPRESSED = 0x75465a4c;   // "LZFu"
+const UNCOMPRESSED = 0x414c454d; // "MELA"
+
+/**
+ * Decompress a PR_RTF_COMPRESSED stream.
+ * Handles both the compressed ("LZFu") and stored ("MELA") containers.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {Uint8Array|null} RTF bytes, or null if this is not an RTF container.
+ */
+export function decompress(bytes) {
+  if (!bytes || bytes.length < 16) return null;
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const compSize = dv.getUint32(0, true);
+  const rawSize = dv.getUint32(4, true);
+  const magic = dv.getUint32(8, true);
+
+  if (magic === UNCOMPRESSED) {
+    return bytes.subarray(16, Math.min(bytes.length, 16 + rawSize));
+  }
+  if (magic !== COMPRESSED) return null;
+
+  const dict = new Uint8Array(4096);
+  for (let i = 0; i < INIT_DICT.length; i++) dict[i] = INIT_DICT.charCodeAt(i) & 0xFF;
+  let writeAt = INIT_DICT.length;
+
+  const out = new Uint8Array(rawSize);
+  let outPos = 0;
+  let pos = 16;
+  const end = Math.min(bytes.length, compSize + 4);
+
+  while (pos < end && outPos < rawSize) {
+    const control = bytes[pos++];
+    for (let bit = 0; bit < 8 && pos < end && outPos < rawSize; bit++) {
+      if (control & (1 << bit)) {
+        if (pos + 1 >= end) return out.subarray(0, outPos);
+        const b1 = bytes[pos++];
+        const b2 = bytes[pos++];
+        const offset = (b1 << 4) | (b2 >> 4);
+        const length = (b2 & 0x0F) + 2;
+        // A reference to the current write position marks the end of the stream.
+        if (offset === (writeAt % 4096)) return out.subarray(0, outPos);
+        for (let n = 0; n < length && outPos < rawSize; n++) {
+          const byte = dict[(offset + n) % 4096];
+          out[outPos++] = byte;
+          dict[writeAt % 4096] = byte;
+          writeAt++;
+        }
+      } else {
+        const lit = bytes[pos++];
+        out[outPos++] = lit;
+        dict[writeAt % 4096] = lit;
+        writeAt++;
+      }
+    }
+  }
+  return out.subarray(0, outPos);
+}

package/src/util.js

@@ -0,0 +1,59 @@
+/** Small shared helpers. */
+
+const MIME_BY_EXT = {
+  pdf: 'application/pdf', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg',
+  gif: 'image/gif', bmp: 'image/bmp', webp: 'image/webp', svg: 'image/svg+xml',
+  txt: 'text/plain', csv: 'text/csv', html: 'text/html', htm: 'text/html',
+  xml: 'application/xml', json: 'application/json', zip: 'application/zip',
+  doc: 'application/msword', dot: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  eml: 'message/rfc822', msg: 'application/vnd.ms-outlook', ics: 'text/calendar',
+  rtf: 'application/rtf', mp3: 'audio/mpeg', mp4: 'video/mp4'
+};
+
+/**
+ * Guess a content type from a filename extension.
+ * @param {string} name
+ * @returns {string}
+ */
+export function guessMime(name) {
+  const m = /\.([A-Za-z0-9]+)$/.exec(name || '');
+  return (m && MIME_BY_EXT[m[1].toLowerCase()]) || 'application/octet-stream';
+}
+
+/**
+ * Strip path separators and characters that are illegal in filenames.
+ * @param {string} s
+ * @returns {string}
+ */
+export function safeName(s) {
+  return String(s || 'file')
+    .replace(/[\\/:*?"<>|\r\n\t]+/g, '_')
+    .replace(/^\.+/, '')
+    .slice(0, 120) || 'file';
+}
+
+/**
+ * An 8.3-style short name for PR_ATTACH_FILENAME.
+ * @param {string} name
+ * @returns {string}
+ */
+export function shortName(name) {
+  const m = /^(.*?)(\.[A-Za-z0-9]{1,3})?$/.exec(name || 'file');
+  const base = (m[1] || 'file').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 8) || 'file';
+  return base + (m[2] || '');
+}
+
+/**
+ * Replace the extension on a filename.
+ * @param {string} name
+ * @param {string} ext Including the dot.
+ * @returns {string}
+ */
+export function replaceExt(name, ext) {
+  return (String(name).replace(/\.[^.\\/]+$/, '') || 'message') + ext;
+}

package/types/cfb/index.d.ts

@@ -0,0 +1,2 @@
+export { read } from "./read.js";
+export { write, newRoot, addStorage, addStream } from "./write.js";

package/types/cfb/read.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @typedef {object} DirEntry
+ * @property {number} id
+ * @property {string} name
+ * @property {number} type 1 = storage, 2 = stream, 5 = root
+ * @property {number} start First sector of the stream.
+ * @property {number} size Stream length in bytes.
+ * @property {number} left Left sibling id in the storage's red-black tree.
+ * @property {number} right Right sibling id.
+ * @property {number} child First child id, for storages.
+ * @property {{list: DirEntry[], map: Record<string, DirEntry>}|null} children
+ *   Memoised child index, filled in by `childrenOf`.
+ */
+/**
+ * @typedef {object} CfbFile
+ * @property {DirEntry} root
+ * @property {DirEntry[]} entries
+ * @property {(entry: DirEntry) => Uint8Array} readStream
+ * @property {(entry: DirEntry) => {list: DirEntry[], map: Record<string, DirEntry>}} childrenOf
+ */
+/**
+ * Parse a compound file.
+ * @param {Uint8Array} bytes
+ * @returns {CfbFile}
+ */
+export function read(bytes: Uint8Array): CfbFile;
+export type DirEntry = {
+    id: number;
+    name: string;
+    /**
+     * 1 = storage, 2 = stream, 5 = root
+     */
+    type: number;
+    /**
+     * First sector of the stream.
+     */
+    start: number;
+    /**
+     * Stream length in bytes.
+     */
+    size: number;
+    /**
+     * Left sibling id in the storage's red-black tree.
+     */
+    left: number;
+    /**
+     * Right sibling id.
+     */
+    right: number;
+    /**
+     * First child id, for storages.
+     */
+    child: number;
+    /**
+     *   Memoised child index, filled in by `childrenOf`.
+     */
+    children: {
+        list: DirEntry[];
+        map: Record<string, DirEntry>;
+    } | null;
+};
+export type CfbFile = {
+    root: DirEntry;
+    entries: DirEntry[];
+    readStream: (entry: DirEntry) => Uint8Array;
+    childrenOf: (entry: DirEntry) => {
+        list: DirEntry[];
+        map: Record<string, DirEntry>;
+    };
+};

package/types/cfb/write.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A node in the storage tree being built.
+ *
+ * The `id`/`leftId`/`rightId`/`childId`/`startSector`/`streamSize` fields are
+ * assigned by {@link write} while laying the file out; callers never set them.
+ *
+ * @typedef {object} CfbNode
+ * @property {string} name
+ * @property {number} type 1 = storage, 2 = stream, 5 = root
+ * @property {Uint8Array|null} [clsid]
+ * @property {CfbNode[]} [children]
+ * @property {Uint8Array} [data]
+ * @property {number} [id]
+ * @property {number} [leftId]
+ * @property {number} [rightId]
+ * @property {number} [childId]
+ * @property {number} [startSector]
+ * @property {number} [streamSize]
+ */
+/**
+ * Create an empty root storage.
+ * @param {Uint8Array|null} [clsid] 16-byte class id written to the root entry.
+ * @returns {CfbNode}
+ */
+export function newRoot(clsid?: Uint8Array | null): CfbNode;
+/**
+ * @param {CfbNode} parent
+ * @param {string} name
+ * @param {Uint8Array|null} [clsid]
+ * @returns {CfbNode}
+ */
+export function addStorage(parent: CfbNode, name: string, clsid?: Uint8Array | null): CfbNode;
+/**
+ * @param {CfbNode} parent
+ * @param {string} name
+ * @param {Uint8Array} [data]
+ * @returns {CfbNode}
+ */
+export function addStream(parent: CfbNode, name: string, data?: Uint8Array): CfbNode;
+/**
+ * Serialise a storage tree to compound file bytes.
+ * @param {CfbNode} root
+ * @returns {Uint8Array}
+ */
+export function write(root: CfbNode): Uint8Array;
+/**
+ * A node in the storage tree being built.
+ *
+ * The `id`/`leftId`/`rightId`/`childId`/`startSector`/`streamSize` fields are
+ * assigned by {@link write} while laying the file out; callers never set them.
+ */
+export type CfbNode = {
+    name: string;
+    /**
+     * 1 = storage, 2 = stream, 5 = root
+     */
+    type: number;
+    clsid?: Uint8Array | null;
+    children?: CfbNode[];
+    data?: Uint8Array;
+    id?: number;
+    leftId?: number;
+    rightId?: number;
+    childId?: number;
+    startSector?: number;
+    streamSize?: number;
+};

package/types/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @param {string} code
+ * @param {string} message
+ * @returns {never}
+ */
+export function fail(code: string, message: string): never;
+/**
+ * Error codes thrown by mailfile. Callers should branch on `error.code`
+ * rather than on message text.
+ */
+export type ErrorCode = string;
+export namespace ErrorCode {
+    let NOT_COMPOUND_FILE: string;
+    let CORRUPT_CFB: string;
+    let TRUNCATED_STREAM: string;
+    let NOT_A_MESSAGE: string;
+    let EMPTY_INPUT: string;
+    let UNSUPPORTED: string;
+    let MALFORMED: string;
+}
+/**
+ * All errors raised by mailfile.
+ */
+export class MailfileError extends Error {
+    /**
+     * @param {string} code One of {@link ErrorCode}.
+     * @param {string} message Human-readable description.
+     * @param {{cause?: unknown}} [options]
+     */
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+    /** @type {string} */
+    code: string;
+    cause: unknown;
+}

package/types/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Identify a message file from its content, falling back to the extension.
+ *
+ * Compound-file magic bytes are authoritative, so a `.msg` renamed to `.eml`
+ * is still detected correctly.
+ *
+ * @param {Uint8Array} bytes
+ * @param {string} [filename]
+ * @returns {'msg'|'eml'}
+ */
+export function detect(bytes: Uint8Array, filename?: string): "msg" | "eml";
+/**
+ * @typedef {object} ConvertResult
+ * @property {Uint8Array} data Converted bytes.
+ * @property {'msg'|'eml'} format Format of `data`.
+ * @property {'msg'|'eml'} sourceFormat Format that was detected on input.
+ * @property {string} mime Content type for `data`.
+ * @property {string} [filename] Suggested output name, when one was given.
+ * @property {Message} message The parsed message.
+ */
+/**
+ * Convert a message to the other format, detecting the input automatically.
+ *
+ * @example
+ * const { data, format } = convert(bytes, { filename: 'note.msg' })
+ * // data is .eml bytes, format === 'eml'
+ *
+ * @param {Uint8Array} bytes
+ * @param {object} [opts]
+ * @param {string} [opts.filename] Used for detection and for naming the output.
+ * @param {'msg'|'eml'} [opts.to] Force the target format instead of flipping.
+ * @param {'msg'|'eml'} [opts.from] Skip detection and assume this input format.
+ * @param {boolean} [opts.lazy] Defer attachment extraction (`.msg` input only).
+ * @returns {ConvertResult}
+ */
+export function convert(bytes: Uint8Array, opts?: {
+    filename?: string;
+    to?: "msg" | "eml";
+    from?: "msg" | "eml";
+    lazy?: boolean;
+}): ConvertResult;
+export { Message } from "./message.js";
+export { Headers } from "./mime/headers.js";
+/** @type {string} */
+export const version: string;
+export type ConvertResult = {
+    /**
+     * Converted bytes.
+     */
+    data: Uint8Array;
+    /**
+     * Format of `data`.
+     */
+    format: "msg" | "eml";
+    /**
+     * Format that was detected on input.
+     */
+    sourceFormat: "msg" | "eml";
+    /**
+     * Content type for `data`.
+     */
+    mime: string;
+    /**
+     * Suggested output name, when one was given.
+     */
+    filename?: string;
+    /**
+     * The parsed message.
+     */
+    message: Message;
+};
+import { Message } from './message.js';
+export { MailfileError, ErrorCode } from "./errors.js";