@crewhaus/tool-notify 0.7.0

package/dist/lib/mime.d.ts

@@ -0,0 +1,125 @@
+export declare const CRLF = "\r\n";
+/**
+ * An address the message may carry. `name` is optional; when present it is
+ * encoded or quoted as the address form requires.
+ */
+export type Mailbox = {
+    readonly address: string;
+    readonly name?: string;
+};
+export type Attachment = {
+    readonly filename: string;
+    readonly contentType: string;
+    readonly content: Uint8Array;
+    /** `inline` for something referenced by the HTML part; `attachment` else. */
+    readonly disposition?: "attachment" | "inline";
+    /** `cid:` reference for an inline part. */
+    readonly contentId?: string;
+};
+export type ComposeInput = {
+    readonly from: Mailbox;
+    readonly to: readonly Mailbox[];
+    readonly cc?: readonly Mailbox[];
+    /**
+     * Blind recipients. They are envelope-only: an address here reaches the
+     * RCPT TO list and NEVER a header, because a `Bcc:` header in a delivered
+     * message is how blind copies stop being blind.
+     */
+    readonly bcc?: readonly Mailbox[];
+    readonly replyTo?: readonly Mailbox[];
+    readonly subject: string;
+    readonly text: string;
+    readonly html?: string;
+    readonly attachments?: readonly Attachment[];
+    /** The instant the message claims to have been written. Never the clock. */
+    readonly date: Date;
+    /**
+     * The left-hand side of `Message-ID`. Omitted ⇒ derived from a hash of the
+     * message, so the same message always carries the same id and a duplicate
+     * is recognisable as one.
+     */
+    readonly messageIdLocal?: string;
+    /** Domain for `Message-ID`. Omitted ⇒ the sender address's domain. */
+    readonly messageIdDomain?: string;
+    readonly inReplyTo?: string;
+    readonly references?: readonly string[];
+    /** Extra headers. Names are validated; values are encoded like any other. */
+    readonly headers?: Readonly<Record<string, string>>;
+};
+export type ComposeResult = {
+    readonly ok: true;
+    /** The full message: headers, blank line, body. CRLF line endings. */
+    readonly message: string;
+    readonly messageId: string;
+    readonly bytes: number;
+    /** Envelope recipients, deduplicated and in a stable order. */
+    readonly envelopeTo: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export declare function isValidAddress(address: string): boolean;
+/** The domain half of an address, lowercased. `null` when there is none. */
+export declare function addressDomain(address: string): string | null;
+/**
+ * RFC 2047 encoded words, base64, UTF-8.
+ *
+ * An encoded word may be at most 75 characters. `=?UTF-8?B?` + `?=` costs
+ * 12, so the base64 payload is capped at 60 characters — 45 source bytes —
+ * and the split is made on whole code points, because half of a UTF-8
+ * sequence in one word and half in the next decodes to a replacement
+ * character on every client.
+ */
+export declare function encodeWords(text: string): string;
+/** A header value safe to emit: encoded when it has to be, raw when it can be. */
+export declare function encodeHeaderValue(text: string): string;
+/** `Name <addr>`, with the display name quoted or encoded as needed. */
+export declare function formatMailbox(mailbox: Mailbox): string;
+/** RFC 5322 date in UTC. Locale-free by construction — no `toLocaleString`. */
+export declare function formatDate(date: Date): string;
+/**
+ * The two header questions asked in more than one place.
+ *
+ * `EmailSendPreflight` reports every bad header name at once, while
+ * `composeMessage` refuses at the first. Both have to be asking the SAME
+ * question: a preflight that says "ready" against its own copy of the rule,
+ * and a compose that then refuses, is a preflight nobody can act on. So the
+ * predicate is exported and the composer below is one of its callers rather
+ * than a second implementation.
+ */
+export declare function isValidHeaderName(name: string): boolean;
+export declare function isReservedHeaderName(name: string): boolean;
+/** True for exactly one bracketed message id, per the grammar above. */
+export declare function isMessageId(value: string): boolean;
+/**
+ * Quoted-printable, per RFC 2045 §6.7.
+ *
+ * The parts people get wrong, handled explicitly: trailing whitespace before
+ * a hard break is encoded (a relay that strips it would otherwise change the
+ * message), a soft break is never inserted inside an `=XX` triplet, hard
+ * breaks stay CRLF rather than being encoded, and a line-leading `.` is
+ * encoded so no amount of SMTP dot handling can eat it.
+ */
+export declare function encodeQuotedPrintable(text: string): string;
+/** Base64, wrapped at 76 columns. */
+export declare function encodeBase64Lines(bytes: Uint8Array): string;
+/**
+ * A MIME boundary derived from the content it separates.
+ *
+ * Random boundaries make the same message compose to different bytes every
+ * time, which costs the caller the ability to compare two composes or to use
+ * the message as its own idempotency key. Hashing the parts keeps the
+ * boundary unique-in-practice while staying reproducible; the `=_` prefix
+ * uses characters that cannot appear in base64 or quoted-printable output,
+ * so a boundary can never collide with the content it delimits.
+ */
+export declare function boundaryFor(kind: string, material: string): string;
+/** Build the complete message. Pure: same input, same bytes, every time. */
+export declare function composeMessage(input: ComposeInput): ComposeResult;
+/**
+ * Dot-stuff a message for SMTP DATA, per RFC 5321 §4.5.2, and terminate it.
+ *
+ * A line that begins with `.` would otherwise end the DATA phase early and
+ * leave the remainder of the message being parsed as commands.
+ */
+export declare function dotStuff(message: string): string;