@orkestrel/msg 0.0.1

package/dist/src/core/index.d.ts

@@ -0,0 +1,1350 @@
+/**
+ * CFB-compliant directory name comparator.
+ * Compares by UTF-16 length first, then by uppercased code points.
+ *
+ * @param a - First name
+ * @param b - Second name
+ * @returns Negative, zero, or positive
+ */
+export declare function compareCFBName(a: string, b: string): number;
+
+/**
+ * Create a new email file parser for .eml and .msg input.
+ *
+ * @param options - Optional parser configuration
+ * @returns A working {@link EmailParserInterface}
+ *
+ * @example
+ * ```ts
+ * import { createEmailParser, isSuccess } from '@src/core'
+ *
+ * const parser = createEmailParser()
+ * const result = parser.parse({ bytes, name: 'message.eml' })
+ * if (isSuccess(result)) {
+ * 	console.log(result.value.messages[0].subject)
+ * }
+ * ```
+ */
+export declare function createEmailParser(options?: EmailParserOptions): EmailParserInterface;
+
+/**
+ * Create a new CFB binary writer for reconstituting .msg files.
+ *
+ * @returns A working {@link MSGBurnerInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMSGBurner } from '@src/core'
+ *
+ * const burner = createMSGBurner()
+ * const binary = burner.burn(entries)
+ * ```
+ */
+export declare function createMSGBurner(): MSGBurnerInterface;
+
+/**
+ * Create a new .msg file reader.
+ *
+ * @param buffer - Raw .msg file bytes
+ * @param options - Optional reader configuration
+ * @returns A working {@link MSGReaderInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMSGReader } from '@src/core'
+ *
+ * const reader = createMSGReader(buffer)
+ * const data = reader.parse()
+ * console.log(data.kind)
+ * ```
+ */
+export declare function createMSGReader(buffer: ArrayBuffer | Uint8Array, options?: MSGReaderOptions): MSGReaderInterface;
+
+/**
+ * Decode a Base64 string into raw bytes without relying on `atob`.
+ * Ignores ASCII whitespace and tolerates missing padding.
+ *
+ * @param text - Base64-encoded string
+ * @returns Decoded byte array
+ * @throws {@link MSGError} with code `MALFORMED` when the string contains
+     * a character outside the Base64 alphabet
+     *
+     * @example
+     * ```ts
+     * decodeBase64('SGVsbG8=') // Uint8Array [72, 101, 108, 108, 111]
+     * ```
+     */
+ export declare function decodeBase64(text: string): Uint8Array;
+
+ /**
+  * Decode Latin-1 (ISO-8859-1) bytes into a string, byte-for-code-point.
+  *
+  * @param bytes - Latin-1 byte array
+  * @returns Decoded string
+  *
+  * @example
+  * ```ts
+  * decodeLatin1(new Uint8Array([0xe9])) // 'é'
+  * ```
+  */
+ export declare function decodeLatin1(bytes: Uint8Array): string;
+
+ /**
+  * Decode a MIME-encoded body string into a raw byte array.
+  *
+  * @param body - Raw encoded string
+  * @param encoding - Encoding type (e.g., 'base64', 'quoted-printable')
+  * @returns Decoded byte array
+  * @throws {@link MSGError} with code `MALFORMED` when `encoding` is `'base64'`
+      * and `body` contains an invalid Base64 character
+      */
+  export declare function decodeMIMEEncoding(body: string, encoding: string): Uint8Array;
+
+  /**
+   * Decode a MIME-encoded body into a text string based on an arbitrary
+   * charset label, resolved via {@link resolveEncoding}.
+   *
+   * @param body - Raw encoded string
+   * @param encoding - Transfer encoding type
+   * @param charset - Character set label (e.g., 'utf-8')
+   * @returns Decoded string
+   */
+  export declare function decodeMIMEText(body: string, encoding: string, charset: string): string;
+
+  /**
+   * Decode RFC 2047 encoded words in header values.
+   * Handles both Base64 (B) and Quoted-Printable (Q) forms.
+   *
+   * @param text - Header value string potentially containing encoded words
+   * @returns Decoded string
+   *
+   * @example
+   * ```ts
+   * decodeMIMEWords('=?UTF-8?B?SGVsbG8=?=') // 'Hello'
+   * ```
+   */
+  export declare function decodeMIMEWords(text: string): string;
+
+  /**
+   * Decode UTF-8 bytes into a string, WHATWG-style: an invalid byte
+   * sequence decodes as U+FFFD rather than throwing. Rejects overlong
+   * encodings, surrogate code points (0xD800-0xDFFF), and code points
+   * beyond 0x10FFFF — each invalid sequence yields exactly one U+FFFD
+   * and decoding resumes at the next lead byte.
+   *
+   * @param bytes - UTF-8 byte array
+   * @returns Decoded string
+   *
+   * @example
+   * ```ts
+   * decodeUTF8(new Uint8Array([65])) // 'A'
+   * decodeUTF8(new Uint8Array([0xff])) // '�'
+   * ```
+   */
+  export declare function decodeUTF8(bytes: Uint8Array): string;
+
+  /**
+   * Decode Windows-1252 bytes into a string. Identical to {@link decodeLatin1}
+   * except for the 0x80-0x9F range, which maps through {@link WINDOWS_1252_HIGH}.
+   *
+   * @param bytes - Windows-1252 byte array
+   * @returns Decoded string
+   *
+   * @example
+   * ```ts
+   * decodeWindows1252(new Uint8Array([0x93])) // '“'
+   * ```
+   */
+  export declare function decodeWindows1252(bytes: Uint8Array): string;
+
+  /**
+   * Derive the EmailFormat from a file name and/or MIME type.
+   * Returns undefined when the format cannot be determined.
+   *
+   * @param name - File name to inspect
+   * @param mime - MIME type to inspect
+   * @returns Detected format or undefined
+   *
+   * @example
+   * ```ts
+   * detectFormat('message.eml', undefined) // 'eml'
+   * detectFormat(undefined, 'application/vnd.ms-outlook') // 'msg'
+   * ```
+   */
+  export declare function detectFormat(name: string | undefined, mime: string | undefined): EmailFormat | undefined;
+
+  /**
+   * Extracted attachment from an email message.
+   *
+   * @remarks
+   * - `name` — attachment file name
+   * - `mimeType` — MIME content type
+   * - `size` — byte length
+   * - `bytes` — raw binary content
+   */
+  export declare interface EmailAttachment {
+      readonly name: string;
+      readonly mimeType: string;
+      readonly size: number;
+      readonly bytes: Uint8Array;
+  }
+
+  /**
+   * Parsed email chain from a single file.
+   *
+   * @remarks
+   * - `format` — detected file format ('eml' or 'msg')
+   * - `messages` — extracted messages (always length 1 for single-file formats)
+   */
+  export declare interface EmailChain {
+      readonly format: EmailFormat;
+      readonly messages: readonly EmailMessage[];
+  }
+
+  /**
+   * Supported email file format.
+   */
+  export declare type EmailFormat = 'eml' | 'msg';
+
+  /**
+   * Raw email input handed to an EmailParser.
+   *
+   * @remarks
+   * - `bytes` — raw file content
+   * - `name` — optional file name, used to infer format when `mime` is absent
+   * - `mime` — optional MIME type, used to infer format
+   */
+  export declare interface EmailInput {
+      readonly bytes: Uint8Array;
+      readonly name?: string;
+      readonly mime?: string;
+  }
+
+  /**
+   * Structured email message extracted from a parsed file.
+   *
+   * @remarks
+   * - `from` — sender address string
+   * - `to` — recipient addresses
+   * - `cc` — carbon copy addresses
+   * - `subject` — decoded subject line
+   * - `date` — delivery date or undefined when absent/malformed
+   * - `text` — plain-text body (includes quoted reply chain)
+   * - `html` — HTML body (includes quoted reply chain)
+   * - `attachments` — decoded file attachments
+   */
+  export declare interface EmailMessage {
+      readonly from: string;
+      readonly to: readonly string[];
+      readonly cc: readonly string[];
+      readonly subject: string;
+      readonly date: Date | undefined;
+      readonly text: string;
+      readonly html: string;
+      readonly attachments: readonly EmailAttachment[];
+  }
+
+  /**
+   * Parses raw .eml or .msg file bytes into a structured {@link EmailChain}.
+   * Synchronous and dependency-free: format detection falls back to sniffing
+   * the CFB magic header when neither `name` nor `mime` resolves it, and every
+   * parse failure is contained into a `Result` rather than thrown.
+   *
+   * @example
+   * ```ts
+   * import { createEmailParser, isSuccess } from '@src/core'
+   *
+   * const parser = createEmailParser()
+   * const result = parser.parse({ bytes, name: 'message.eml' })
+   * if (isSuccess(result)) {
+   * 	const { messages } = result.value
+   * 	console.log(messages[0].text)
+   * 	console.log(messages[0].attachments)
+   * }
+   * ```
+   */
+  export declare class EmailParser implements EmailParserInterface {
+      #private;
+      constructor(options?: EmailParserOptions);
+      /**
+       * Parse raw email bytes into a structured chain.
+       *
+       * @param input - Raw bytes plus optional name/MIME hints
+       * @returns A {@link Success} wrapping the parsed {@link EmailChain}, or a
+       * {@link Failure} wrapping an {@link MSGError} (code `UNSUPPORTED` when
+       * the format cannot be determined, `MALFORMED` when parsing fails)
+       *
+       * @example
+       * ```ts
+       * const result = parser.parse({ bytes, name: 'message.msg' })
+       * ```
+       */
+      parse(input: EmailInput): Result<EmailChain, MSGError>;
+      /**
+       * Current parser configuration.
+       *
+       * @returns A copy of the configured {@link EmailParserOptions} — the
+       * internal reference is never leaked
+       */
+      get options(): EmailParserOptions;
+  }
+
+  /**
+   * Public interface for parsing email files into structured chains.
+   *
+   * @remarks
+   * - `parse` — parse an EmailInput into an EmailChain result
+   * - `options` — current parser configuration
+   */
+  export declare interface EmailParserInterface {
+      /**
+       * Parse raw email bytes into a structured chain.
+       *
+       * @param input - Raw bytes plus optional name/MIME hints
+       * @returns A {@link Success} wrapping the parsed {@link EmailChain}, or a
+       * {@link Failure} wrapping an {@link MSGError} (code `UNSUPPORTED` when
+       * the format cannot be determined, `MALFORMED` when parsing fails)
+       */
+      parse(input: EmailInput): Result<EmailChain, MSGError>;
+      readonly options: EmailParserOptions;
+  }
+
+  /**
+   * Configuration for creating an EmailParser.
+   *
+   * @remarks
+   * - `encoding` — encoding for decoding MIME part bodies (default `'utf-8'`)
+   */
+  export declare interface EmailParserOptions {
+      readonly encoding?: MSGEncoding;
+  }
+
+  /**
+   * File extensions recognized as RFC 2822 / MIME email files.
+   */
+  export declare const EML_EXTENSIONS: readonly string[];
+
+  /**
+   * MIME types recognized as RFC 2822 / MIME email files.
+   */
+  export declare const EML_MIME_TYPES: readonly string[];
+
+  /**
+   * Encode a string into UTF-8 bytes, handling surrogate pairs.
+   * A lone (unpaired) surrogate encodes as U+FFFD.
+   *
+   * @param text - String to encode
+   * @returns UTF-8 byte array
+   *
+   * @example
+   * ```ts
+   * encodeUTF8('A') // Uint8Array [65]
+   * ```
+   */
+  export declare function encodeUTF8(text: string): Uint8Array;
+
+  /**
+   * Extract a single EmailMessage from a top-level MIMEPart.
+   * Walks the full MIME tree to collect text, HTML, and attachments.
+   *
+   * @param part - Root MIMEPart from parseMIMEPart
+   * @returns Structured EmailMessage
+   */
+  export declare function extractMessage(part: MIMEPart): EmailMessage;
+
+  /**
+   * Extract a single EmailMessage from a parsed MSGReader.
+   * Reads field data and attachments from the reader interface.
+   *
+   * Each attachment is read independently: a corrupt attachment throws
+   * from `reader.attachment(i)` is caught and that attachment is skipped
+   * so the rest of the message still parses. This containment keeps one
+   * damaged attachment stream from failing the entire message extraction.
+   *
+   * @param reader - A parsed MSGReaderInterface instance
+   * @returns Structured EmailMessage
+   */
+  export declare function extractMessageFromMSG(reader: MSGReaderInterface): EmailMessage;
+
+  /**
+   * Failed operation result.
+   */
+  export declare interface Failure<E> {
+      readonly success: false;
+      readonly error: E;
+  }
+
+  /**
+   * Construct a {@link Failure} wrapping an error.
+   *
+   * @param error - The error to wrap
+   * @returns A `Failure<E>` result
+   *
+   * @example
+   * ```ts
+   * const result = failure(new MSGError('MALFORMED', 'bad input'))
+   * ```
+   */
+  export declare function failure<E>(error: E): Failure<E>;
+
+  /**
+   * Default file name for attachments without an explicit name.
+   */
+  export declare const FALLBACK_ATTACHMENT_NAME = "attachment";
+
+  /**
+   * Default charset for decoding MIME part bodies.
+   */
+  export declare const FALLBACK_CHARSET = "utf-8";
+
+  /**
+   * Convert a Windows FILETIME (100-ns intervals since 1601-01-01) to a UTC date string.
+   * Combines the low/high 32-bit halves with `BigInt` so the 64-bit interval
+   * count never loses precision to float64 rounding.
+   *
+   * @param low - Low 32 bits of FILETIME
+   * @param high - High 32 bits of FILETIME
+   * @returns UTC date string
+   */
+  export declare function fileTimeToUTCString(low: number, high: number): string;
+
+  /**
+   * Format a name and email into a standard composite address.
+   *
+   * @param name - Display name
+   * @param email - Email address
+   * @returns Formatted address string
+   */
+  export declare function formatEmailAddress(name: string | undefined, email: string | undefined): string;
+
+  /**
+   * Infers the file extension for an attachment based on its filename or MIME type.
+   * Returns the extension including the dot (e.g., '.jpg').
+   *
+   * @param mimeType - MIME type to infer from
+   * @param fileName - File name to infer from
+   * @returns Inferred extension, or `.bin` when neither hint resolves
+   */
+  export declare function inferExtension(mimeType?: string, fileName?: string): string;
+
+  /**
+   * Narrow an unknown value to a valid EmailFormat.
+   *
+   * @param value - Value to check
+   * @returns True when value is 'eml' or 'msg'
+   */
+  export declare function isEmailFormat(value: unknown): value is EmailFormat;
+
+  /**
+   * Narrow a Result to Failure.
+   *
+   * @param result - Result to check
+   * @returns True when result is Failure
+   */
+  export declare function isFailure<T, E>(result: Result<T, E>): result is Failure<E>;
+
+  /**
+   * Narrow an unknown caught (or `Failure.error`) value to an {@link MSGError}.
+   *
+   * @param value - The value to test (typically a `catch` binding or a `Result.error`)
+   * @returns `true` when `value` is an {@link MSGError}
+   *
+   * @example
+   * ```ts
+   * import { isMSGError } from '@src/core'
+   *
+   * try {
+   * 	reader.parse()
+   * } catch (error) {
+   * 	if (isMSGError(error) && error.code === 'MALFORMED') return
+   * }
+   * ```
+   */
+  export declare function isMSGError(value: unknown): value is MSGError;
+
+  /**
+   * Validate that a DataView starts with the CFB magic header.
+   *
+   * @param view - DataView to check
+   * @returns True when the first 8 bytes match the CFB signature
+   */
+  export declare function isMSGFile(view: DataView): boolean;
+
+  /**
+   * Narrow an unknown value to a plain record.
+   *
+   * @param value - Value to check
+   * @returns True when value is a non-null, non-array object
+   */
+  export declare function isRecord(value: unknown): value is Record<string, unknown>;
+
+  /**
+   * Narrow a Result to Success.
+   *
+   * @param result - Result to check
+   * @returns True when result is Success
+   */
+  export declare function isSuccess<T, E>(result: Result<T, E>): result is Success<T>;
+
+  /**
+   * Common MIME types to file extensions mapping.
+   * Used for inferring the correct extension during file extraction.
+   */
+  export declare const MIME_EXTENSIONS: ReadonlyMap<string, string>;
+
+  /**
+   * Maximum multipart nesting depth accepted by `parseMIMEPart`.
+   * Guards against pathological or hostile MIME trees causing
+   * unbounded recursion.
+   */
+  export declare const MIME_MAX_DEPTH = 50;
+
+  /**
+   * Parsed MIME header with value and parameter map.
+   *
+   * @remarks
+   * - `value` — primary header value (before first semicolon)
+   * - `params` — key-value parameter map (e.g. charset, boundary)
+   */
+  export declare interface MIMEHeader {
+      readonly value: string;
+      readonly params: ReadonlyMap<string, string>;
+  }
+
+  /**
+   * Recursive MIME part tree node.
+   *
+   * @remarks
+   * - `headers` — parsed header map keyed by lowercase name
+   * - `body` — raw body text (empty for multipart containers)
+   * - `parts` — child parts for multipart types
+   */
+  export declare interface MIMEPart {
+      readonly headers: ReadonlyMap<string, MIMEHeader>;
+      readonly body: string;
+      readonly parts: readonly MIMEPart[];
+  }
+
+  /**
+   * Stringify a mixed-endian Microsoft UUID from a byte array.
+   *
+   * @param data - Byte array containing the UUID
+   * @param offset - Byte offset to start reading
+   * @returns UUID string in lowercase
+   */
+  export declare function msftUUIDStringify(data: Uint8Array, offset: number): string;
+
+  /**
+   * Threshold below which data is stored in the mini-stream.
+   */
+  export declare const MSG_BIG_BLOCK_MIN_DOC_SIZE = 4096;
+
+  /**
+   * Maximum DIFAT entries stored in the CFB header (109).
+   */
+  export declare const MSG_BURNER_DIFAT_HEADER_SLOTS = 109;
+
+  /**
+   * DIFAT sector marker: this sector holds DIFAT data (-4).
+   */
+  export declare const MSG_BURNER_DIFAT_SECTOR_MARKER = -4;
+
+  /**
+   * CFB directory entry size in bytes (128).
+   */
+  export declare const MSG_BURNER_DIR_ENTRY_SIZE = 128;
+
+  /**
+   * FAT sector marker: this sector holds FAT data (-3).
+   */
+  export declare const MSG_BURNER_FAT_SECTOR_MARKER = -3;
+
+  /**
+   * Number of 32-bit integers per standard sector (128).
+   */
+  export declare const MSG_BURNER_INTS_PER_SECTOR: number;
+
+  /**
+   * CFB mini-stream sector size in bytes (64).
+   */
+  export declare const MSG_BURNER_MINI_SECTOR_SIZE = 64;
+
+  /**
+   * Threshold below which streams are stored in the mini-stream (4096).
+   */
+  export declare const MSG_BURNER_MINI_STREAM_CUTOFF = 4096;
+
+  /**
+   * Maximum UTF-16 code units allowed in a CFB directory entry name (31).
+   * The fixed 64-byte name field holds 32 UTF-16 units including the
+   * NUL terminator, so the name itself is capped at 31 units.
+   */
+  export declare const MSG_BURNER_NAME_MAX = 31;
+
+  /**
+   * Root entry CLSID for MSG compound files.
+   */
+  export declare const MSG_BURNER_ROOT_CLSID: Uint8Array<ArrayBuffer>;
+
+  /**
+   * Standard CFB sector size in bytes (512).
+   */
+  export declare const MSG_BURNER_SECTOR_SIZE = 512;
+
+  /**
+   * Sentinel for end-of-chain in the FAT.
+   */
+  export declare const MSG_END_OF_CHAIN = -2;
+
+  /**
+   * File extensions recognized as Outlook binary email files.
+   */
+  export declare const MSG_EXTENSIONS: readonly string[];
+
+  /**
+   * Attachment data class identifier.
+   */
+  export declare const MSG_FIELD_CLASS_ATTACHMENT_DATA = "3701";
+
+  /**
+   * Directory field type indicating an embedded MSG.
+   */
+  export declare const MSG_FIELD_DIR_TYPE_INNER_MSG = "000d";
+
+  /**
+   * Full 8-char property tag to field name mapping (for compound tags).
+   */
+  export declare const MSG_FIELD_FULL_NAME_MAPPING: Readonly<Record<string, string>>;
+
+  /**
+   * MAPI property tag to field name mapping.
+   */
+  export declare const MSG_FIELD_NAME_MAPPING: Readonly<Record<string, string>>;
+
+  /**
+   * MAPI property type tag to decode type mapping.
+   */
+  export declare const MSG_FIELD_TYPE_MAPPING: Readonly<Record<string, string>>;
+
+  /**
+   * CFB magic header bytes (0xD0CF11E0A1B11AE1).
+   */
+  export declare const MSG_FILE_HEADER: Uint8Array<ArrayBuffer>;
+
+  /**
+   * Header offset: BAT sector count.
+   */
+  export declare const MSG_HEADER_BAT_COUNT_OFFSET = 44;
+
+  /**
+   * Header offset: BAT sector array start.
+   */
+  export declare const MSG_HEADER_BAT_START_OFFSET = 76;
+
+  /**
+   * Header offset: property (directory) start sector.
+   */
+  export declare const MSG_HEADER_PROPERTY_START_OFFSET = 48;
+
+  /**
+   * Header offset: SBAT sector count.
+   */
+  export declare const MSG_HEADER_SBAT_COUNT_OFFSET = 64;
+
+  /**
+   * Header offset: SBAT start sector.
+   */
+  export declare const MSG_HEADER_SBAT_START_OFFSET = 60;
+
+  /**
+   * Header offset: XBAT (DIFAT) sector count.
+   */
+  export declare const MSG_HEADER_XBAT_COUNT_OFFSET = 72;
+
+  /**
+   * Header offset: XBAT (DIFAT) start sector.
+   */
+  export declare const MSG_HEADER_XBAT_START_OFFSET = 68;
+
+  /**
+   * Large sector size mark in the header (byte at offset 30).
+   */
+  export declare const MSG_L_BIG_BLOCK_MARK = 12;
+
+  /**
+   * Large sector size (4096 bytes).
+   */
+  export declare const MSG_L_BIG_BLOCK_SIZE = 4096;
+
+  /**
+   * MAPI recipient type: BCC.
+   */
+  export declare const MSG_MAPI_RECIPIENT_BCC = 3;
+
+  /**
+   * MAPI recipient type: CC.
+   */
+  export declare const MSG_MAPI_RECIPIENT_CC = 2;
+
+  /**
+   * MAPI recipient type: TO.
+   */
+  export declare const MSG_MAPI_RECIPIENT_TO = 1;
+
+  /**
+   * Maximum recursion depth accepted by the directory hierarchy builder
+   * (`MSGReader#buildHierarchy`). Defense-in-depth against a pathological
+   * or hostile directory tree — the sibling-chain and visited-set guards
+   * already bound each level, this caps the recursion depth itself.
+   */
+  export declare const MSG_MAX_HIERARCHY_DEPTH = 64;
+
+  /**
+   * MIME types recognized as Outlook binary email files.
+   */
+  export declare const MSG_MIME_TYPES: readonly string[];
+
+  /**
+   * PidLid property set GUID to LID-to-field-name mapping.
+   * Maps well-known MAPI named property sets to their property
+   * long IDs and corresponding field names on MSGFieldData.
+   */
+  export declare const MSG_PIDLID_MAPPING: Readonly<Record<string, Readonly<Record<number, string>>>>;
+
+  /**
+   * Name prefix for attachment storage entries.
+   */
+  export declare const MSG_PREFIX_ATTACHMENT = "__attach_version1.0";
+
+  /**
+   * Name prefix for document (substg) stream entries.
+   */
+  export declare const MSG_PREFIX_DOCUMENT = "__substg1.";
+
+  /**
+   * Name prefix for named property mapping storage.
+   */
+  export declare const MSG_PREFIX_NAMEID = "__nameid_version1.0";
+
+  /**
+   * Name prefix for recipient storage entries.
+   */
+  export declare const MSG_PREFIX_RECIPIENT = "__recip_version1.0";
+
+  /**
+   * Offset within a directory entry: child index.
+   */
+  export declare const MSG_PROP_CHILD_PROPERTY_OFFSET = 76;
+
+  /**
+   * Offset within a directory entry: name byte length.
+   */
+  export declare const MSG_PROP_NAME_SIZE_OFFSET = 64;
+
+  /**
+   * Offset within a directory entry: right sibling index.
+   */
+  export declare const MSG_PROP_NEXT_PROPERTY_OFFSET = 72;
+
+  /**
+   * No child/sibling index sentinel.
+   */
+  export declare const MSG_PROP_NO_INDEX = -1;
+
+  /**
+   * Offset within a directory entry: left sibling index.
+   */
+  export declare const MSG_PROP_PREVIOUS_PROPERTY_OFFSET = 68;
+
+  /**
+   * Offset within a directory entry: stream byte length.
+   */
+  export declare const MSG_PROP_SIZE_OFFSET = 120;
+
+  /**
+   * Offset within a directory entry: start sector of stream data.
+   */
+  export declare const MSG_PROP_START_BLOCK_OFFSET = 116;
+
+  /**
+   * Offset within a directory entry: object type byte.
+   */
+  export declare const MSG_PROP_TYPE_OFFSET = 66;
+
+  /**
+   * Directory entry size in bytes.
+   */
+  export declare const MSG_PROPERTY_SIZE = 128;
+
+  /**
+   * Small sector size mark in the header (byte at offset 30).
+   */
+  export declare const MSG_S_BIG_BLOCK_MARK = 9;
+
+  /**
+   * Small sector size (512 bytes).
+   */
+  export declare const MSG_S_BIG_BLOCK_SIZE = 512;
+
+  /**
+   * Mini-stream sector size (64 bytes).
+   */
+  export declare const MSG_SMALL_BLOCK_SIZE = 64;
+
+  /**
+   * Directory entry type: storage (folder).
+   */
+  export declare const MSG_TYPE_DIRECTORY = 1;
+
+  /**
+   * Directory entry type: stream (document).
+   */
+  export declare const MSG_TYPE_DOCUMENT = 2;
+
+  /**
+   * Directory entry type: root storage.
+   */
+  export declare const MSG_TYPE_ROOT = 5;
+
+  /**
+   * Directory entry type: unallocated.
+   */
+  export declare const MSG_TYPE_UNALLOCATED = 0;
+
+  /**
+   * Sentinel for unused blocks in the FAT.
+   */
+  export declare const MSG_UNUSED_BLOCK = -1;
+
+  /**
+   * Extracted attachment content from an MSG file.
+   *
+   * @remarks
+   * - `fileName` — the attachment file name
+   * - `content` — the raw binary content
+   */
+  export declare interface MSGAttachment {
+      readonly fileName: string;
+      readonly content: Uint8Array;
+  }
+
+  /**
+   * Reconstitutes a valid CFB (Compound Binary File) from a flat list of
+   * {@link MSGBurnerEntry} descriptors — root storage at index 0, its
+   * children reachable through `children` indices.
+   *
+   * @remarks
+   * Builds a red-black directory tree, allocates FAT/mini-FAT/DIFAT
+   * sectors, then writes the header, directory entries, and stream data
+   * into a single binary. Used to extract embedded `.msg` attachments as
+   * standalone CFB files.
+   */
+  export declare class MSGBurner implements MSGBurnerInterface {
+      #private;
+      /**
+       * Burn a flat list of CFB entries into a valid compound binary file.
+       *
+       * @param entries - Flat entry list starting with Root Entry at index 0
+       * @returns Complete CFB binary as Uint8Array
+       * @throws {@link MSGError} with code `BURN` when an entry name exceeds
+           * the {@link MSG_BURNER_NAME_MAX} UTF-16 code unit limit the CFB directory entry format allows
+           */
+       burn(entries: readonly MSGBurnerEntry[]): Uint8Array;
+      }
+
+      /**
+       * CFB entry descriptor for the MSG burner (CFB binary writer).
+       * Entries form a flat list starting with the root storage at index 0.
+       */
+      export declare interface MSGBurnerEntry {
+          readonly name: string;
+          readonly type: number;
+          readonly length: number;
+          readonly binaryProvider?: () => Uint8Array;
+          children?: number[];
+      }
+
+      /**
+       * Public interface for the CFB binary writer.
+       * Reconstitutes a flat list of entry descriptors into a valid
+       * Compound Binary File (CFB) byte stream.
+       *
+       * @remarks
+       * - `burn` — write the entries to a CFB binary
+       */
+      export declare interface MSGBurnerInterface {
+          /**
+           * Write the entries to a CFB binary.
+           *
+           * @param entries - Flat CFB entry descriptor list, root storage at index 0
+           * @returns Complete CFB byte stream
+           * @throws {@link MSGError} with code `BURN` when the entry list cannot be
+               * reconstituted into a valid CFB structure
+               */
+           burn(entries: readonly MSGBurnerEntry[]): Uint8Array;
+          }
+
+          /**
+           * Internal lite entry with tree metadata used during CFB burn.
+           * Tracks red-black coloring and sector allocation alongside
+           * the source MSGBurnerEntry.
+           */
+          export declare interface MSGBurnerLiteEntry {
+              readonly entry: MSGBurnerEntry;
+              left: number;
+              right: number;
+              child: number;
+              firstSector: number;
+              readonly mini: boolean;
+              red: boolean;
+          }
+
+          /**
+           * CFB directory entry describing a storage or stream in the compound file.
+           */
+          export declare interface MSGDirectoryEntry {
+              readonly type: number;
+              readonly name: string;
+              readonly previousProperty: number;
+              readonly nextProperty: number;
+              readonly childProperty: number;
+              readonly startBlock: number;
+              readonly sizeBlock: number;
+              children?: number[];
+          }
+
+          /**
+           * Lifecycle type of a directory entry in a CFB compound file.
+           */
+          export declare type MSGDirectoryEntryType = 'root' | 'directory' | 'document' | 'unallocated';
+
+          /**
+           * Supported text encoding for decoding non-Unicode MSG strings and
+           * MIME part bodies.
+           */
+          export declare type MSGEncoding = 'utf-8' | 'utf-16le' | 'windows-1252' | 'latin1';
+
+          /**
+           * An error thrown or returned by the MSG/EML parsing and burning surfaces.
+           *
+           * @remarks
+           * Carries a machine-readable {@link MSGErrorCode} so a `catch` (or a
+           * `Failure.error` branch) can dispatch on `error.code` instead of parsing
+           * the message text. `context` carries whatever structured detail the
+           * throwing site has on hand (e.g. `{ offset, expected }`).
+           */
+          export declare class MSGError extends Error {
+              readonly code: MSGErrorCode;
+              readonly context?: Readonly<Record<string, unknown>>;
+              constructor(code: MSGErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+          }
+
+          /**
+           * Machine-readable classification for an {@link MSGError}.
+           *
+           * @remarks
+           * - `UNSUPPORTED` — the input is not a recognized MSG/EML format
+           * - `MALFORMED` — the input claims a recognized format but is structurally invalid
+           * - `CYCLE` — a directory or MIME structure references itself, forming a cycle
+           * - `RANGE` — a computed offset, length, or index falls outside the valid bounds
+           * - `BURN` — the CFB binary writer could not reconstitute the entry list
+           */
+          export declare type MSGErrorCode = 'UNSUPPORTED' | 'MALFORMED' | 'CYCLE' | 'RANGE' | 'BURN';
+
+          /**
+           * Parsed field data extracted from an MSG file.
+           * Represents the root message, an attachment, or a recipient.
+           *
+           * @remarks
+           * - `kind` — discriminator: 'msg', 'attachment', or 'recipient'
+           * - `subject` — message subject
+           * - `senderName` — display name of the sender
+           * - `senderEmail` — email address of the sender
+           * - `body` — plain text body
+           * - `headers` — transport message headers
+           * - `bodyHTML` — HTML body (string)
+           * - `html` — HTML body (binary)
+           * - `compressedRTF` — compressed RTF body (binary)
+           * - `attachments` — child attachment field data
+           * - `recipients` — child recipient field data
+           * - `innerMSGContent` — true if the attachment is an embedded .msg
+           * - `innerMSGContentFields` — parsed fields of the embedded .msg
+           * - `dataId` — internal CFBF entry index (for attachment binary access)
+           * - `contentLength` — attachment binary length
+           * - `folderId` — internal CFBF storage index (for embedded msg)
+           * - `recipientRole` — recipient type: 'to', 'cc', or 'bcc'
+           */
+          export declare interface MSGFieldData {
+              readonly kind: 'msg' | 'attachment' | 'recipient';
+              readonly subject?: string;
+              readonly senderName?: string;
+              readonly senderEmail?: string;
+              readonly senderAddressType?: string;
+              readonly senderSMTPAddress?: string;
+              readonly sentRepresentingSMTPAddress?: string;
+              readonly body?: string;
+              readonly headers?: string;
+              readonly bodyHTML?: string;
+              readonly html?: Uint8Array;
+              readonly compressedRTF?: Uint8Array;
+              readonly messageClass?: string;
+              readonly messageFlags?: number;
+              readonly messageId?: string;
+              readonly internetCodepage?: number;
+              readonly messageCodepage?: number;
+              readonly messageLocaleId?: number;
+              readonly clientSubmitTime?: string;
+              readonly messageDeliveryTime?: string;
+              readonly creationTime?: string;
+              readonly lastModificationTime?: string;
+              readonly lastModifierName?: string;
+              readonly creatorSMTPAddress?: string;
+              readonly lastModifierSMTPAddress?: string;
+              readonly preview?: string;
+              readonly conversationTopic?: string;
+              readonly normalizedSubject?: string;
+              readonly name?: string;
+              readonly email?: string;
+              readonly addressType?: string;
+              readonly smtpAddress?: string;
+              readonly recipientRole?: MSGRecipientRole;
+              readonly extension?: string;
+              readonly fileNameShort?: string;
+              readonly fileName?: string;
+              readonly contentId?: string;
+              readonly attachmentHidden?: boolean;
+              readonly mimeType?: string;
+              readonly contentLength?: number;
+              readonly dataId?: number;
+              readonly folderId?: number;
+              readonly innerMSGContent?: true;
+              readonly innerMSGContentFields?: MSGFieldData;
+              readonly attachments?: readonly MSGFieldData[];
+              readonly recipients?: readonly MSGFieldData[];
+              readonly departmentName?: string;
+              readonly middleName?: string;
+              readonly generation?: string;
+              readonly surname?: string;
+              readonly givenName?: string;
+              readonly companyName?: string;
+              readonly jobTitle?: string;
+              readonly location?: string;
+              readonly postalAddress?: string;
+              readonly streetAddress?: string;
+              readonly postalCode?: string;
+              readonly country?: string;
+              readonly stateOrProvince?: string;
+              readonly homePhone?: string;
+              readonly mobilePhone?: string;
+              readonly businessPhone?: string;
+              readonly businessFax?: string;
+              readonly businessHomePage?: string;
+              readonly namePrefix?: string;
+              readonly homeAddressCity?: string;
+              readonly appointmentStart?: string;
+              readonly appointmentEnd?: string;
+              readonly clipStart?: string;
+              readonly clipEnd?: string;
+              readonly timeZoneDescription?: string;
+              readonly appointmentLocation?: string;
+              readonly appointmentOldLocation?: string;
+              readonly globalAppointmentId?: string;
+              readonly votingResponse?: string;
+              readonly internetAccountName?: string;
+              readonly yomiFirstName?: string;
+              readonly yomiLastName?: string;
+              readonly yomiCompanyName?: string;
+              readonly primaryEmailAddress?: string;
+              readonly primaryEmailDisplayName?: string;
+              readonly primaryEmailOriginalDisplayName?: string;
+              readonly fileUnder?: string;
+              readonly workAddressCity?: string;
+              readonly workAddressStreet?: string;
+              readonly workAddressState?: string;
+              readonly workAddressPostalCode?: string;
+              readonly workAddressCountry?: string;
+              readonly workAddressCountryCode?: string;
+              readonly addressCountryCode?: string;
+              readonly contactWebPage?: string;
+              readonly workAddress?: string;
+              readonly instantMessagingAddress?: string;
+              readonly fax1AddressType?: string;
+              readonly fax1EmailAddress?: string;
+              readonly fax1OriginalDisplayName?: string;
+              readonly fax2AddressType?: string;
+              readonly fax2EmailAddress?: string;
+              readonly fax2OriginalDisplayName?: string;
+              readonly fax3AddressType?: string;
+              readonly fax3EmailAddress?: string;
+              readonly fax3OriginalDisplayName?: string;
+          }
+
+          /**
+           * MAPI property data type tag.
+           */
+          export declare type MSGFieldType = 'string' | 'unicode' | 'binary' | 'time' | 'integer' | 'boolean';
+
+          /**
+           * Internal mutable accumulator used during MSG field extraction.
+           * Properties are assigned dynamically via index signature and
+           * narrowed to the readonly {@link MSGFieldData} at the public boundary.
+           */
+          export declare interface MSGMutableFieldData {
+              kind: 'msg' | 'attachment' | 'recipient';
+              attachments?: MSGMutableFieldData[];
+              recipients?: MSGMutableFieldData[];
+              innerMSGContent?: true;
+              innerMSGContentFields?: MSGMutableFieldData;
+              dataId?: number;
+              contentLength?: number;
+              folderId?: number;
+              [key: string]: unknown;
+          }
+
+          /**
+           * Resolved named property entry from the __nameid_version1.0 storage.
+           */
+          export declare interface MSGNameIdEntry {
+              readonly useName: boolean;
+              readonly name?: string;
+              readonly propertySet?: string;
+              readonly propertyLid?: number;
+          }
+
+          /**
+           * Parses Microsoft Outlook .msg files (CFB/OLE2 compound binary format).
+           * Every parsing step treats the input as untrusted: sector and property
+           * chains are cycle-guarded and length-capped, every raw byte range is
+           * bounds-checked before a view is constructed over it, and every failure
+           * surfaces as a typed {@link MSGError} rather than a raw `RangeError` or
+           * `TypeError`.
+           */
+          export declare class MSGReader implements MSGReaderInterface {
+              #private;
+              /**
+               * Create a reader over a raw MSG file buffer.
+               *
+               * @param input - Raw MSG file bytes, as an `ArrayBuffer` or a `Uint8Array` view
+               * @param options - Reader configuration
+               */
+              constructor(input: ArrayBuffer | Uint8Array, options?: MSGReaderOptions);
+              /**
+               * Parse the MSG file and return extracted field data.
+               *
+               * @returns Root message field data with nested attachments and recipients
+               * @throws {@link MSGError} with code `UNSUPPORTED`, `MALFORMED`, `CYCLE`,
+                   * or `RANGE` when the compound file cannot be parsed
+                   */
+               parse(): MSGFieldData;
+               /**
+                * Read attachment binary content by index.
+                *
+                * @param index - Zero-based index into the parsed attachment list
+                * @returns File name and raw binary content
+                * @throws {@link MSGError} with code `RANGE` when the index is out of bounds
+                    */
+                attachment(index: number): MSGAttachment;
+                /**
+                 * Rebuild the parsed MSG as a standalone CFB/.msg binary.
+                 *
+                 * @returns Complete CFB byte stream
+                 * @throws {@link MSGError} with code `BURN` when the parsed structure
+                     * cannot be reconstituted
+                     */
+                 burn(): Uint8Array;
+                }
+
+                /**
+                 * Public interface for parsing Microsoft Outlook .msg files.
+                 *
+                 * @remarks
+                 * - `parse` — parse the MSG file and return extracted field data
+                 * - `attachment` — read attachment binary content by index
+                 * - `burn` — rebuild the parsed MSG as a standalone CFB/.msg binary
+                 */
+                export declare interface MSGReaderInterface {
+                    /**
+                     * Parse the MSG file and return extracted field data.
+                     *
+                     * @returns Root message field data with nested attachments and recipients
+                     * @throws {@link MSGError} with code `UNSUPPORTED`, `MALFORMED`, `CYCLE`,
+                         * or `RANGE` when the compound file cannot be parsed
+                         */
+                     parse(): MSGFieldData;
+                     /**
+                      * Read attachment binary content by index.
+                      *
+                      * @param index - Zero-based index into the parsed attachment list
+                      * @returns File name and raw binary content
+                      * @throws {@link MSGError} with code `RANGE` when the index is out of bounds
+                          */
+                      attachment(index: number): MSGAttachment;
+                      /**
+                       * Rebuild the parsed MSG as a standalone CFB/.msg binary.
+                       *
+                       * @returns Complete CFB byte stream
+                       * @throws {@link MSGError} with code `BURN` when the parsed structure
+                           * cannot be reconstituted
+                           */
+                       burn(): Uint8Array;
+                      }
+
+                      /**
+                       * Configuration for creating an MSGReader.
+                       *
+                       * @remarks
+                       * - `encoding` — encoding for non-Unicode (PT_STRING8) strings (default `'windows-1252'`)
+                       */
+                      export declare interface MSGReaderOptions {
+                          readonly encoding?: MSGEncoding;
+                      }
+
+                      /**
+                       * Recipient role in a message.
+                       */
+                      export declare type MSGRecipientRole = 'to' | 'cc' | 'bcc';
+
+                      /**
+                       * Parse headers from a raw RFC 2822 / MIME header text block.
+                       *
+                       * @param text - Raw header text
+                       * @returns Map of parsed header objects
+                       */
+                      export declare function parseMIMEHeaders(text: string): ReadonlyMap<string, MIMEHeader>;
+
+                      /**
+                       * Parse a raw RFC 2822 / MIME text string into a MIMEPart tree.
+                       * Line endings are normalised to \n before processing. Recursion is
+                       * capped at {@link MIME_MAX_DEPTH} to guard against a hostile or
+                       * pathological multipart nesting cycle.
+                       *
+                       * @param raw - Raw MIME text
+                       * @param depth - Current recursion depth (internal; callers omit this)
+                       * @returns Parsed MIMEPart tree
+                       * @throws {@link MSGError} with code `CYCLE` when nesting exceeds {@link MIME_MAX_DEPTH}
+                           */
+                       export declare function parseMIMEPart(raw: string, depth?: number): MIMEPart;
+
+                       /**
+                        * Read a non-Unicode (PT_STRING8) string from a byte array using a
+                        * pure-ES decoder — no `TextDecoder` dependency, so this stays usable
+                        * in the core's DOM/Node-free environment.
+                        *
+                        * @param data - Binary data
+                        * @param encoding - Encoding to decode with (default `'windows-1252'`)
+                        * @returns Decoded string
+                        *
+                        * @example
+                        * ```ts
+                        * readANSIString(new Uint8Array([0x93, 0x41, 0x94])) // '“A”'
+                        * ```
+                        */
+                       export declare function readANSIString(data: Uint8Array, encoding?: MSGEncoding): string;
+
+                       /**
+                        * Read a UTF-16LE string from a DataView.
+                        *
+                        * @param view - DataView to read from
+                        * @param offset - Byte offset to start reading
+                        * @param charCount - Number of UTF-16 code units to read
+                        * @returns Decoded string
+                        * @throws {@link MSGError} with code `MALFORMED` when the requested range
+                            * exceeds the view's bounds
+                            */
+                        export declare function readUTF16String(view: DataView, offset: number, charCount: number): string;
+
+                        /**
+                         * Remove trailing null characters from a string.
+                         *
+                         * @param text - Input string
+                         * @returns String with trailing nulls removed
+                         */
+                        export declare function removeTrailingNull(text: string): string;
+
+                        /**
+                         * Resolve a free-form charset label (as seen in a MIME `charset` parameter)
+                         * to a supported {@link MSGEncoding}. Unknown or absent labels fall back
+                         * to `'utf-8'`.
+                         *
+                         * @param label - Charset label to resolve (case-insensitive)
+                         * @returns Resolved encoding
+                         *
+                         * @example
+                         * ```ts
+                         * resolveEncoding('ISO-8859-1') // 'latin1'
+                         * resolveEncoding(undefined) // 'utf-8'
+                         * ```
+                         */
+                        export declare function resolveEncoding(label: string | undefined): MSGEncoding;
+
+                        /**
+                         * Discriminated union for operations that can succeed or fail safely.
+                         */
+                        export declare type Result<T, E = Error> = Success<T> | Failure<E>;
+
+                        /**
+                         * Round a value up to the nearest multiple of a boundary.
+                         *
+                         * @param value - Number to round
+                         * @param boundary - Must be a power of 2
+                         * @returns Rounded value
+                         */
+                        export declare function roundUpToMultiple(value: number, boundary: number): number;
+
+                        /**
+                         * Compute how many sectors are needed to hold a given byte count.
+                         *
+                         * @param bytes - Total byte count
+                         * @param sectorSize - Sector size in bytes
+                         * @returns Number of sectors (0 when bytes ≤ 0)
+                         */
+                        export declare function sectorsNeeded(bytes: number, sectorSize: number): number;
+
+                        /**
+                         * Successful operation result.
+                         */
+                        export declare interface Success<T> {
+                            readonly success: true;
+                            readonly value: T;
+                        }
+
+                        /**
+                         * Construct a {@link Success} wrapping a value.
+                         *
+                         * @param value - The value to wrap
+                         * @returns A `Success<T>` result
+                         *
+                         * @example
+                         * ```ts
+                         * const result = success(42) // { success: true, value: 42 }
+                         * ```
+                         */
+                        export declare function success<T>(value: T): Success<T>;
+
+                        /**
+                         * Convert a number to a lowercase hex string with specified padding.
+                         *
+                         * @param value - Number to convert
+                         * @param length - Minimum hex string length (zero-padded)
+                         * @returns Lowercase hex string
+                         */
+                        export declare function toHexLower(value: number, length: number): string;
+
+                        /**
+                         * Minimum valid code point for each UTF-8 sequence length, keyed by the
+                         * number of continuation bytes (1, 2, or 3). Enforces the WHATWG
+                         * requirement that a sequence encode the shortest possible form — an
+                         * overlong encoding (a code point below its sequence's minimum) is
+                         * rejected rather than accepted by `decodeUTF8`.
+                         */
+                        export declare const UTF8_SEQUENCE_MINIMUM: Readonly<Record<number, number>>;
+
+                        /**
+                         * Windows-1252 high-byte (0x80-0x9F) to Unicode code point lookup.
+                         * Index `n` maps byte `0x80 + n` to its Unicode code point; entries
+                         * that Windows-1252 leaves undefined map to the byte's own value
+                         * (C1 control code passthrough) per the WHATWG encoding standard.
+                         */
+                        export declare const WINDOWS_1252_HIGH: readonly number[];
+
+                        export { }