mailfile 0.1.0

package/types/mapi/bag.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A read-only view of one object's MAPI properties.
+ *
+ * Variable-length properties live in `__substg1.0_*` streams; fixed-length
+ * ones live in `__properties_version1.0`.
+ */
+export class PropertyBag {
+    /**
+     * @param {import('../cfb/read.js').CfbFile} cfb
+     * @param {object} storage Directory entry of the storage to read.
+     * @param {number} headerSize One of `HeaderSize.*`.
+     */
+    constructor(cfb: import("../cfb/read.js").CfbFile, storage: object, headerSize: number);
+    /** @type {Record<string, Uint8Array>} keyed by 8-hex-digit tag */
+    vars: Record<string, Uint8Array>;
+    /** @type {Record<number, {type:number, lo:number, hi:number, i32:number}>} */
+    fixed: Record<number, {
+        type: number;
+        lo: number;
+        hi: number;
+        i32: number;
+    }>;
+    /** @type {object[]} Nested storages (recipients, attachments, embedded messages). */
+    subStorages: object[];
+    cfb: import("../cfb/read.js").CfbFile;
+    childMap: Record<string, import("../cfb/read.js").DirEntry>;
+    /** Encoding used for 8-bit string properties in this object. */
+    charset: any;
+    /**
+     * String property, preferring the Unicode variant.
+     * @param {number} id @returns {string}
+     */
+    str(id: number): string;
+    /** @param {number} id @returns {Uint8Array|null} */
+    bin(id: number): Uint8Array | null;
+    /** @param {number} id @returns {number|null} */
+    int(id: number): number | null;
+    /** @param {number} id @returns {boolean|null} */
+    bool(id: number): boolean | null;
+    /** @param {number} id @returns {Date|null} */
+    date(id: number): Date | null;
+    /** @param {number} id @returns {boolean} */
+    has(id: number): boolean;
+    /** Every property id present on this object. @returns {number[]} */
+    ids(): number[];
+    /** Nested storages whose names match a prefix, in directory order. */
+    storagesMatching(re: any): any[];
+}
+/**
+ * Accumulates properties and emits the streams for one object.
+ */
+export class PropertyWriter {
+    /**
+     * @param {import('../cfb/write.js').CfbNode} node Storage to write into.
+     * @param {number} headerSize One of `HeaderSize.*`.
+     */
+    constructor(node: import("../cfb/write.js").CfbNode, headerSize: number);
+    node: import("../cfb/write.js").CfbNode;
+    headerSize: number;
+    entries: any[];
+    _entry(id: any, type: any, size: any, lo: any, hi: any): void;
+    /** @param {number} id @param {string} value */
+    str(id: number, value: string): this;
+    /** @param {number} id @param {Uint8Array} bytes */
+    bin(id: number, bytes: Uint8Array): this;
+    /** @param {number} id @param {number} v */
+    int32(id: number, v: number): this;
+    /** @param {number} id @param {boolean} v */
+    bool(id: number, v: boolean): this;
+    /** @param {number} id @param {Date} date */
+    time(id: number, date: Date): this;
+    /**
+     * Write `__properties_version1.0`.
+     * @param {(dv: DataView) => void} [headerFill] Fills the stream header.
+     */
+    finish(headerFill?: (dv: DataView) => void): void;
+}

package/types/mapi/index.d.ts

@@ -0,0 +1,2 @@
+export { PropertyBag, PropertyWriter } from "./bag.js";
+export { PropId, PropType, RecipientType, AttachMethod, HeaderSize, MSG_CLSID, CODEPAGES, hex4, hex8, tagName, filetimeToDate, dateToFiletime } from "./tags.js";

package/types/mapi/tags.d.ts

@@ -0,0 +1,137 @@
+/** @param {number} n @returns {string} */
+export function hex4(n: number): string;
+/** @param {number} n @returns {string} */
+export function hex8(n: number): string;
+/**
+ * Stream name for a variable-length property, e.g. `__substg1.0_0037001F`.
+ * @param {number} id
+ * @param {number} type
+ * @returns {string}
+ */
+export function tagName(id: number, type: number): string;
+/**
+ * FILETIME (100ns ticks since 1601-01-01) -> Date.
+ * @param {number} lo @param {number} hi @returns {Date|null}
+ */
+export function filetimeToDate(lo: number, hi: number): Date | null;
+/**
+ * Date -> FILETIME halves.
+ * @param {Date} date @returns {{lo: number, hi: number}}
+ */
+export function dateToFiletime(date: Date): {
+    lo: number;
+    hi: number;
+};
+export namespace PropId {
+    let SUBJECT: number;
+    let NORMALIZED_SUBJECT: number;
+    let BODY: number;
+    let RTF_COMPRESSED: number;
+    let HTML: number;
+    let MESSAGE_CLASS: number;
+    let TRANSPORT_HEADERS: number;
+    let CLIENT_SUBMIT_TIME: number;
+    let DELIVERY_TIME: number;
+    let LAST_MODIFICATION_TIME: number;
+    let CREATION_TIME: number;
+    let INTERNET_MESSAGE_ID: number;
+    let IN_REPLY_TO_ID: number;
+    let INTERNET_REFERENCES: number;
+    let DISPLAY_TO: number;
+    let DISPLAY_CC: number;
+    let DISPLAY_BCC: number;
+    let SENDER_NAME: number;
+    let SENDER_EMAIL: number;
+    let SENDER_ADDRTYPE: number;
+    let SENDER_SMTP: number;
+    let SENT_REP_NAME: number;
+    let SENT_REP_EMAIL: number;
+    let SENT_REP_ADDRTYPE: number;
+    let SENT_REP_SMTP: number;
+    let MESSAGE_FLAGS: number;
+    let HASATTACH: number;
+    let STORE_SUPPORT_MASK: number;
+    let INTERNET_CPID: number;
+    let MESSAGE_CODEPAGE: number;
+    let PRIORITY: number;
+    let IMPORTANCE: number;
+    let OBJECT_TYPE: number;
+    let DISPLAY_TYPE: number;
+    let ROWID: number;
+    let RECIPIENT_TYPE: number;
+    let DISPLAY_NAME: number;
+    let EMAIL_ADDRESS: number;
+    let ADDRTYPE: number;
+    let SMTP_ADDRESS: number;
+    let ATTACH_METHOD: number;
+    let ATTACH_DATA_BIN: number;
+    let ATTACH_LONG_FILENAME: number;
+    let ATTACH_FILENAME: number;
+    let ATTACH_EXTENSION: number;
+    let ATTACH_MIME_TAG: number;
+    let ATTACH_CONTENT_ID: number;
+    let ATTACH_SIZE: number;
+    let ATTACH_NUM: number;
+    let ATTACH_FLAGS: number;
+    let ATTACHMENT_HIDDEN: number;
+    let RENDERING_POSITION: number;
+}
+export namespace PropType {
+    let SHORT: number;
+    let LONG: number;
+    let FLOAT: number;
+    let DOUBLE: number;
+    let BOOLEAN: number;
+    let I8: number;
+    let STRING8: number;
+    let UNICODE: number;
+    let SYSTIME: number;
+    let BINARY: number;
+    let OBJECT: number;
+}
+export namespace RecipientType {
+    let TO: number;
+    let CC: number;
+    let BCC: number;
+}
+export namespace AttachMethod {
+    let NONE: number;
+    let BY_VALUE: number;
+    let BY_REFERENCE: number;
+    let EMBEDDED_MSG: number;
+}
+export namespace HeaderSize {
+    let TOP_LEVEL: number;
+    let EMBEDDED: number;
+    let RECIPIENT: number;
+    let ATTACHMENT: number;
+}
+/** CLSID written to the root entry of a .msg file. */
+export const MSG_CLSID: Uint8Array<ArrayBuffer>;
+/** Windows code page number -> WHATWG encoding label. */
+export const CODEPAGES: {
+    20127: string;
+    28591: string;
+    28592: string;
+    28595: string;
+    28597: string;
+    28598: string;
+    28599: string;
+    28605: string;
+    65000: string;
+    65001: string;
+    1250: string;
+    1251: string;
+    1252: string;
+    1253: string;
+    1254: string;
+    1255: string;
+    1256: string;
+    1257: string;
+    1258: string;
+    932: string;
+    936: string;
+    949: string;
+    950: string;
+    874: string;
+};

package/types/message.d.ts

@@ -0,0 +1,94 @@
+/**
+ * A single email message, independent of its on-disk format.
+ *
+ * Fields are plain and mutable: read one in, change what you need, write the
+ * other out.
+ */
+export class Message {
+    /**
+     * Parse an Outlook `.msg` file.
+     * @param {Uint8Array} bytes
+     * @param {{lazy?: boolean}} [opts] `lazy` defers attachment byte extraction
+     *   until `.data` is read — useful when you only want headers.
+     * @returns {Message}
+     */
+    static fromMsg(bytes: Uint8Array, opts?: {
+        lazy?: boolean;
+    }): Message;
+    /**
+     * Parse an RFC 5322 `.eml` file.
+     * @param {Uint8Array} bytes
+     * @returns {Message}
+     */
+    static fromEml(bytes: Uint8Array): Message;
+    /** @param {Partial<Message>} [data] */
+    constructor(data?: Partial<Message>);
+    /** @type {string} */
+    subject: string;
+    /** @type {Address} */
+    from: Address;
+    /** @type {Address[]} */
+    to: Address[];
+    /** @type {Address[]} */
+    cc: Address[];
+    /** @type {Address[]} */
+    bcc: Address[];
+    /** @type {Date|null} */
+    date: Date | null;
+    /** @type {string} */
+    messageId: string;
+    /** @type {string} */
+    inReplyTo: string;
+    /** @type {string} */
+    references: string;
+    /** @type {number|null} 0 low, 1 normal, 2 high. */
+    importance: number | null;
+    /** @type {string} MAPI message class, e.g. `IPM.Note`. */
+    messageClass: string;
+    /** @type {string} Plain-text body. */
+    text: string;
+    /** @type {string} HTML body. */
+    html: string;
+    /** @type {Attachment[]} */
+    attachments: Attachment[];
+    /** @type {Headers} Original internet headers, when the source had them. */
+    headers: Headers;
+    /**
+     * Raw MAPI property access — present only for messages read from `.msg`.
+     * Use it to reach properties this model does not surface (appointments,
+     * contacts, custom properties).
+     * @type {import('./mapi/bag.js').PropertyBag|null}
+     */
+    props: import("./mapi/bag.js").PropertyBag | null;
+    /**
+     * Serialise to an RFC 5322 `.eml` document.
+     *
+     * Headers carried in from the source are preserved verbatim — minus the
+     * content headers, which are regenerated to match the body actually written.
+     * @returns {Uint8Array}
+     */
+    toEml(): Uint8Array;
+    /**
+     * Serialise to an Outlook `.msg` file.
+     * @returns {Uint8Array}
+     */
+    toMsg(): Uint8Array;
+}
+export type Address = {
+    name: string;
+    email: string;
+};
+export type Attachment = {
+    filename: string;
+    mime: string;
+    data: Uint8Array;
+    /**
+     * Content-ID, without angle brackets.
+     */
+    cid?: string;
+    /**
+     * True when referenced from the HTML body by cid.
+     */
+    inline?: boolean;
+};
+import { Headers } from './mime/headers.js';

package/types/mime/build.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Build an `.eml` document.
+ *
+ * Structure is chosen from what is present: `multipart/alternative` for a
+ * text+html pair, wrapped in `multipart/related` when there are inline
+ * (cid-referenced) parts, wrapped again in `multipart/mixed` for ordinary
+ * attachments.
+ *
+ * @param {object} msg
+ * @param {Array<[string,string]>} [msg.headers] Emitted before the MIME headers.
+ * @param {string} [msg.text]
+ * @param {string} [msg.html]
+ * @param {Array<{filename: string, mime: string, data: Uint8Array, cid?: string, inline?: boolean}>} [msg.attachments]
+ * @returns {Uint8Array}
+ */
+export function buildEml(msg: {
+    headers?: Array<[string, string]>;
+    text?: string;
+    html?: string;
+    attachments?: Array<{
+        filename: string;
+        mime: string;
+        data: Uint8Array;
+        cid?: string;
+        inline?: boolean;
+    }>;
+}): Uint8Array;

package/types/mime/encodings.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Tolerant base64 decoder: ignores whitespace and any non-alphabet bytes.
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+export function base64ToBytes(str: string): Uint8Array;
+/**
+ * @param {string} str
+ * @param {number} width
+ * @returns {string}
+ */
+export function wrap(str: string, width: number): string;
+/**
+ * @param {string} s
+ * @returns {Uint8Array}
+ */
+export function utf8Encode(s: string): Uint8Array;
+/**
+ * Decode bytes using a named charset, falling back to windows-1252 for
+ * labels the runtime does not know. Real-world mail mislabels constantly,
+ * so this never throws.
+ * @param {Uint8Array} bytes
+ * @param {string} [charset]
+ * @returns {string}
+ */
+export function decodeBytes(bytes: Uint8Array, charset?: string): string;
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function utf16Decode(bytes: Uint8Array): string;
+/**
+ * @param {string} str
+ * @returns {Uint8Array}
+ */
+export function utf16Encode(str: string): Uint8Array;
+/**
+ * @param {string} str
+ * @param {boolean} [isHeaderWord] Treat `_` as space (RFC 2047 Q encoding).
+ * @returns {Uint8Array}
+ */
+export function decodeQP(str: string, isHeaderWord?: boolean): Uint8Array;
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+export function encodeQP(bytes: Uint8Array): string;

package/types/mime/headers.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @typedef {object} Address
+ * @property {string} name Display name, already decoded.
+ * @property {string} email
+ */
+/**
+ * Decode RFC 2047 encoded words (`=?UTF-8?B?...?=`) anywhere in a string.
+ * @param {string} str
+ * @returns {string}
+ */
+export function decodeWords(str: string): string;
+/**
+ * @param {string} s
+ * @returns {boolean}
+ */
+export function needsEncoding(s: string): boolean;
+/**
+ * Encode a string as one or more RFC 2047 words, if it needs it.
+ * @param {string} s
+ * @returns {string}
+ */
+export function encodeWord(s: string): string;
+/**
+ * Fold a long header onto continuation lines.
+ * @param {string} name
+ * @param {string} value
+ * @returns {string}
+ */
+export function foldHeader(name: string, value: string): string;
+/**
+ * @param {string} name
+ * @param {string} email
+ * @returns {string}
+ */
+export function formatAddress(name: string, email: string): string;
+/**
+ * @param {string} str
+ * @returns {Address}
+ */
+export function parseAddress(str: string): Address;
+/**
+ * @param {string} str
+ * @returns {Address[]}
+ */
+export function parseAddressList(str: string): Address[];
+/**
+ * Parse a structured header into its value and parameters, reassembling
+ * RFC 2231 continuations and percent-encoding (`filename*0*=`, `filename*=`).
+ * @param {string} raw
+ * @returns {{value: string, params: Record<string, string>}}
+ */
+export function parseHeaderValue(raw: string): {
+    value: string;
+    params: Record<string, string>;
+};
+/**
+ * Emit a parameter, using RFC 2231 with an ASCII fallback when non-ASCII.
+ * @param {string} name
+ * @param {string} val
+ * @returns {string}
+ */
+export function encodeParamValue(name: string, val: string): string;
+/**
+ * Format a Date as an RFC 5322 date-time in local time.
+ * @param {Date} d
+ * @returns {string}
+ */
+export function formatDate(d: Date): string;
+/**
+ * Parse an RFC 5322 date, tolerating a trailing `(GMT)`-style comment.
+ * @param {string} str
+ * @returns {Date|null}
+ */
+export function parseDate(str: string): Date | null;
+/**
+ * An ordered, case-insensitive, repeat-preserving header collection.
+ */
+export class Headers {
+    /**
+     * Parse a raw header block. Continuation lines are unfolded.
+     * @param {string} text
+     * @returns {Headers}
+     */
+    static parse(text: string): Headers;
+    /** @param {Array<[string, string]>} [entries] */
+    constructor(entries?: Array<[string, string]>);
+    /** @type {Array<[string, string]>} */
+    entries: Array<[string, string]>;
+    /** @param {string} name @returns {string|null} First matching value. */
+    get(name: string): string | null;
+    /** @param {string} name @returns {string[]} Every matching value, in order. */
+    getAll(name: string): string[];
+    /** @param {string} name @returns {boolean} */
+    has(name: string): boolean;
+    /** Replace all occurrences with a single value. @param {string} name @param {string} value */
+    set(name: string, value: string): this;
+    /** Append without removing existing occurrences. @param {string} name @param {string} value */
+    add(name: string, value: string): this;
+    /** @param {string} name */
+    delete(name: string): this;
+    /** Header block as text, with folding applied. @returns {string} */
+    get raw(): string;
+    [Symbol.iterator](): ArrayIterator<[string, string]>;
+}
+export type Address = {
+    /**
+     * Display name, already decoded.
+     */
+    name: string;
+    email: string;
+};

package/types/mime/index.d.ts

@@ -0,0 +1,4 @@
+export { buildEml } from "./build.js";
+export { parseEml, parseNode } from "./parse.js";
+export { Headers, decodeWords, encodeWord, foldHeader, formatAddress, formatDate, parseAddress, parseAddressList, parseDate, parseHeaderValue, encodeParamValue, needsEncoding } from "./headers.js";
+export { base64ToBytes, bytesToBase64, decodeBytes, decodeQP, encodeQP, utf8Encode, utf16Decode, utf16Encode, wrap } from "./encodings.js";

package/types/mime/parse.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Parse a MIME entity and its children.
+ * @param {Uint8Array} bytes
+ * @param {number} [depth]
+ * @returns {MimeNode}
+ */
+export function parseNode(bytes: Uint8Array, depth?: number): MimeNode;
+/**
+ * Parse a complete `.eml` document.
+ * @param {Uint8Array} bytes
+ * @returns {ParsedEml}
+ */
+export function parseEml(bytes: Uint8Array): ParsedEml;
+export type MimeNode = {
+    headers: Headers;
+    /**
+     * Lower-cased, without parameters.
+     */
+    contentType: string;
+    params: Record<string, string>;
+    children: MimeNode[];
+    /**
+     * Decoded body, for leaf nodes only.
+     */
+    content?: Uint8Array;
+};
+export type ParsedEml = {
+    /**
+     * Top-level headers.
+     */
+    headers: Headers;
+    text: string;
+    html: string;
+    attachments: Array<{
+        filename: string;
+        mime: string;
+        data: Uint8Array;
+        cid: string;
+        inline: boolean;
+    }>;
+    root: MimeNode;
+};
+import { Headers } from './headers.js';

package/types/msg/read.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Read a `.msg` file into plain message data.
+ * @param {Uint8Array} bytes
+ * @param {{lazy?: boolean}} [opts]
+ */
+export function readMsg(bytes: Uint8Array, opts?: {
+    lazy?: boolean;
+}): {
+    messageClass: string;
+    subject: string;
+    messageId: string;
+    inReplyTo: string;
+    references: string;
+    date: Date;
+    importance: number;
+    text: string;
+    html: string;
+    to: any[];
+    cc: any[];
+    bcc: any[];
+    attachments: any[];
+    headers: Headers;
+    props: PropertyBag;
+};
+import { Headers } from '../mime/headers.js';
+import { PropertyBag } from '../mapi/bag.js';

package/types/msg/write.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Build a `.msg` file from message data.
+ * @param {object} msg
+ * @returns {Uint8Array}
+ */
+export function writeMsg(msg: object): Uint8Array;

package/types/rtf/deencapsulate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {string} rtf
+ * @returns {boolean} True if this RTF carries encapsulated HTML or text.
+ */
+export function isEncapsulated(rtf: string): boolean;
+/**
+ * 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: string, decode: (bytes: Uint8Array) => string): string;
+/**
+ * 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: Uint8Array, decode: (bytes: Uint8Array) => string): string | null;

package/types/rtf/index.d.ts

@@ -0,0 +1,2 @@
+export { decompress } from "./lzfu.js";
+export { rtfToHtml, deencapsulate, isEncapsulated } from "./deencapsulate.js";

package/types/rtf/lzfu.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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: Uint8Array): Uint8Array | null;

package/types/util.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Guess a content type from a filename extension.
+ * @param {string} name
+ * @returns {string}
+ */
+export function guessMime(name: string): string;
+/**
+ * Strip path separators and characters that are illegal in filenames.
+ * @param {string} s
+ * @returns {string}
+ */
+export function safeName(s: string): string;
+/**
+ * An 8.3-style short name for PR_ATTACH_FILENAME.
+ * @param {string} name
+ * @returns {string}
+ */
+export function shortName(name: string): string;
+/**
+ * Replace the extension on a filename.
+ * @param {string} name
+ * @param {string} ext Including the dot.
+ * @returns {string}
+ */
+export function replaceExt(name: string, ext: string): string;