index.d.ts

// This is adapted from DefinitelyTyped/DefinitelyTyped/types/mailparser
// pending merging of my pull request (https://github.com/DefinitelyTyped/DefinitelyTyped/pull/42290)
// to fix an optional string type.

declare module "mailparser" {
  // Type definitions for mailparser 2.7
  // Project: https://github.com/nodemailer/mailparser
  // Definitions by: Peter Snider <https://github.com/psnider>
  //                 Andrey Volynkin <https://github.com/Avol-V>
  // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

  /// <reference types="node" />

  import StreamModule = require("stream");
  import Stream = StreamModule.Stream;

  /**
   * Structured object for headers with arguments.
   *
   * `content-type: text/plain; CHARSET="UTF-8"` =>
   * ```
   * {
   *     "value": "text/plain",
   *     "params": {
   *         "charset": "UTF-8"
   *     }
   * }
   * ```
   */
  interface StructuredHeader {
    /**
     * The main value.
     */
    value: string;
    /**
     * Additional arguments.
     */
    params: { [key: string]: string };
  }

  /**
   * Possible types of a header value.
   */
  export type HeaderValue =
    | string
    | string[]
    | AddressObject
    | Date
    | StructuredHeader;

  /**
   * A Map object with lowercase header keys.
   */
  export type Headers = Map<string, HeaderValue>;
  /**
   * An array of raw header lines
   */
  export type HeaderLines = ReadonlyArray<{
    key: string;
    line: string;
  }>;
  /**
   * Address details.
   */
  interface EmailAddress {
    /**
     * The email address.
     */
    address: string;
    /**
     * The name part of the email/group.
     */
    name: string;
    /**
     * An array of grouped addresses.
     */
    group?: EmailAddress[];
  }

  /**
   * Address object.
   */
  interface AddressObject {
    /**
     * An array with address details.
     */
    value: EmailAddress[];
    /**
     * A formatted address string for HTML context.
     */
    html: string;
    /**
     * A formatted address string for plaintext context.
     */
    text: string;
  }

  /**
   * COmmon part of the Attachment object.
   */
  interface AttachmentCommon {
    /**
     * Message type.
     */
    type: "attachment";
    /**
     * Attachment contents.
     */
    content: any;
    /**
     * MIME type of the message.
     */
    contentType: string;
    /**
     * Content disposition type for the attachment,
     * most probably `'attachment'`.
     */
    contentDisposition: string;
    /**
     * File name of the attachment.
     */
    filename?: string;
    /**
     * A Map value that holds MIME headers for the attachment node.
     */
    headers: Headers;
    /**
     * An array of raw header lines for the attachment node.
     */
    headerLines: HeaderLines;
    /**
     * A MD5 hash of the message content.
     */
    checksum: string;
    /**
     * Message size in bytes.
     */
    size: number;
    /**
     * The header value from `Content-ID`.
     */
    contentId?: string;
    /**
     * `contentId` without `<` and `>`.
     */
    cid?: string; // e.g. '5.1321281380971@localhost'
    /**
     * If true then this attachment should not be offered for download
     * (at least not in the main attachments list).
     */
    related?: boolean;
  }

  /**
   * Attachment object.
   */
  interface Attachment extends AttachmentCommon {
    /**
     * A Buffer that contains the attachment contents.
     */
    content: Buffer;
    /**
     * If true then this attachment should not be offered for download
     * (at least not in the main attachments list).
     */
    related: boolean;
  }

  /**
   * MailParser Attachment object.
   */
  interface AttachmentStream extends AttachmentCommon {
    /**
     * A Buffer that contains the attachment contents.
     */
    content: Stream;
    /**
     * Method must be called once you have processed the attachment.
     */
    release(): void;
  }

  /**
   * Parsed mail object.
   */
  interface ParsedMail {
    /**
     * An array of attachments.
     */
    attachments?: Attachment[];
    /**
     * A Map object with lowercase header keys.
     *
     * - All address headers are converted into address objects.
     * - `references` is a string if only a single reference-id exists or an
     *    array if multiple ids exist.
     * - `date` value is a Date object.
     */
    headers: Headers;
    /**
     * An array of raw header lines
     */
    headerLines: HeaderLines;
    /**
     * The HTML body of the message.
     *
     * Sets to `false` when there is no HTML body.
     *
     * If the message included embedded images as cid: urls then these are all
     * replaced with base64 formatted data: URIs.
     */
    html: string | boolean;
    /**
     * The plaintext body of the message.
     */
    text: string;
    /**
     * The plaintext body of the message formatted as HTML.
     */
    textAsHtml: string;
    /**
     * The subject line.
     */
    subject?: string;
    /**
     * An array of referenced Message-ID values.
     *
     * Not set if no reference values present.
     */
    references?: string[];
    /**
     * A Date object for the `Date:` header.
     */
    date?: Date;
    /**
     * An address object for the `To:` header.
     */
    to: AddressObject;
    /**
     * An address object for the `From:` header.
     */
    from: AddressObject;
    /**
     * An address object for the `Cc:` header.
     */
    cc?: AddressObject;
    /**
     * An address object for the `Bcc:` header (usually not present).
     */
    bcc?: AddressObject;
    /**
     * An address object for the `Reply-To:` header.
     */
    replyTo?: AddressObject;
    /**
     * The Message-ID value string.
     */
    messageId?: string;
    /**
     * The In-Reply-To value string.
     */
    inReplyTo?: string;
    /**
     * Priority of the e-mail.
     */
    priority?: "normal" | "low" | "high";
  }

  /**
   * Text message content.
   */
  interface MessageText {
    /**
     * Message type.
     */
    type: "text";
    /**
     * Includes the HTML version of the message.
     *
     * Is set if the message has at least one `text/html` node.
     */
    html?: string | boolean;
    /**
     * Includes the plaintext version of the message.
     *
     * Is set if the message has at least one `text/plain` node.
     */
    text?: string;
    /**
     * Includes the plaintext version of the message in HTML format.
     *
     * Is set if the message has at least one `text/plain` node.
     */
    textAsHtml?: string;
  }

  /**
   * A lower-level email parsing class.
   *
   * It is a transform stream that takes email source as bytestream for the input
   * and emits data objects for attachments and text contents.
   */
  export class MailParser extends StreamModule.Transform {
    constructor(options?: StreamModule.TransformOptions);
    on(event: string, callback: (any: any) => void): this;
    on(event: "headers", callback: (headers: Headers) => void): this;
    on(
      event: "data",
      callback: (data: AttachmentStream | MessageText) => void
    ): this;
    on(
      event: "readable",
      callback: (data: AttachmentStream | MessageText) => void
    ): this;
  }

  /**
   * A message source.
   */
  export type Source = Buffer | Stream | string;

  /**
   * Options object for simpleParser.
   */
  export interface SimpleParserOptions extends StreamModule.TransformOptions {
    keepCidLinks?: boolean;
  }

  /**
   * Parse email message to structure object.
   *
   * @param source A message source.
   * @param callback Function to get a structured email object.
   */
  export function simpleParser(
    source: Source,
    callback: (err: any, mail: ParsedMail) => void
  ): void;

  /**
   * Parse email message to structure object.
   *
   * @param source A message source.
   * @param options Transform options passed to MailParser's constructor
   * @param callback Function to get a structured email object.
   */
  export function simpleParser(
    source: Source,
    options: SimpleParserOptions,
    callback: (err: any, mail: ParsedMail) => void
  ): void;

  /**
   * Parse email message to structure object.
   *
   * @param source A message source.
   * @param options Transform options passed to MailParser's constructor
   */
  export function simpleParser(
    source: Source,
    options?: SimpleParserOptions
  ): Promise<ParsedMail>;
}