@yozz.app/smtp 0.1.1 → 0.1.3

package/README.md

@@ -8,12 +8,13 @@ pnpm add @yozz.app/smtp
 
 ## The seam
 
-`@yozz.app/smtp` speaks SMTP over any `ByteDuplex` from `@yozz.app/tls`. It knows replies, EHLO
+`@yozz.app/smtp` speaks SMTP over any `ByteDuplex` (`{ read, write }`, a type it declares itself; a
+`@yozz.app/tls` connection satisfies it). No runtime dependencies. It knows replies, EHLO
 keywords, AUTH PLAIN / LOGIN, the MAIL / RCPT / DATA sequence and dot-stuffing. It **never knows**
 TLS, certificates or the vault. STARTTLS is not spoken: the transport is already TLS (465).
 
 `buildMessage` turns composer fields into 7-bit bytes: RFC 2047 headers, 7bit or quoted-printable bodies,
-`multipart/alternative` when an HTML rendering is given, `In-Reply-To` + `References` for replies.
+`multipart/alternative` when an HTML rendering is given, `In-Reply-To` + the folded `References` chain for replies.
 
 ## Tests
 

package/dist/index.d.mts

@@ -1,5 +1,14 @@
-import { ByteDuplex } from "@yozz.app/tls";
-
+//#region src/transport.d.ts
+/**
+ * What this client needs from a transport: bytes in, bytes out. Declared here rather than
+ * imported from `@yozz.app/tls` so the package has no runtime dependency at all; it is the same
+ * two-method shape, so a `TlsConnection` satisfies it structurally.
+ */
+type ByteDuplex = {
+  readonly read: () => Promise<Uint8Array | null>;
+  readonly write: (bytes: Uint8Array) => Promise<void>;
+};
+//#endregion
 //#region src/reply.d.ts
 type SmtpReply = {
   readonly code: number; /** One entry per line, the `NNN-` / `NNN ` prefix removed. */
@@ -68,8 +77,25 @@ type MessageInput = {
   readonly messageId: string;
   readonly text: string; /** When present the message is `multipart/alternative`, text first. */
   readonly html?: string;
-  readonly inReplyTo?: string; /** When present the whole message becomes `multipart/mixed`: the body first, then each file. */
+  readonly inReplyTo?: string;
+  /**
+   * The parent's `References` followed by its Message-ID, oldest first — the chain RFC 5322 §3.6.4
+   * asks a reply to carry. Without it a client that threads on References alone (and the base
+   * subject is a guess, not a rule) sees a reply to a reply as a new conversation. Defaults to
+   * `[inReplyTo]`, which is what a first reply's chain is anyway.
+   */
+  readonly references?: readonly string[]; /** When present the whole message becomes `multipart/mixed`: the body first, then each file. */
   readonly attachments?: readonly MessageAttachment[];
+  /**
+   * Headers this client owns, appended after the standard block.
+   *
+   * YOZZ no longer uses this. It stamped `X-Yozz-Draft` here to find its own copies again without
+   * trusting a Message-ID a provider may rewrite, and that failed on a more basic point: a server
+   * need only index the headers IMAP names, so `SEARCH HEADER` on a private one can answer the
+   * empty list for a message that carries it (docs/knowledge/forwardemail-api.md). The field stays
+   * because a message builder should be able to set a header; do not build a LOOKUP on one.
+   */
+  readonly extraHeaders?: readonly (readonly [string, string])[];
 };
 type MessageAttachment = {
   readonly filename: string;
@@ -86,4 +112,4 @@ declare const formatMailbox: ({
 declare const formatDate: (date: Date) => string;
 declare const buildMessage: (input: MessageInput) => Uint8Array;
 //#endregion
-export { type MessageAttachment, type MessageInput, type SmtpCapabilities, type SmtpClient, type SmtpEnvelope, type SmtpFailure, type SmtpReply, type SmtpResult, buildMessage, createSmtpClient, dotStuff, encodeHeaderText, formatDate, formatMailbox };
+export { type ByteDuplex, type MessageAttachment, type MessageInput, type SmtpCapabilities, type SmtpClient, type SmtpEnvelope, type SmtpFailure, type SmtpReply, type SmtpResult, buildMessage, createSmtpClient, dotStuff, encodeHeaderText, formatDate, formatMailbox };

package/dist/index.mjs

@@ -94,6 +94,11 @@ const readReply = async (reader) => {
 };
 //#endregion
 //#region src/client.ts
+/**
+* SMTP client over a `ByteDuplex` (RFC 5321 + AUTH, RFC 4954). Implicit TLS is the transport's
+* business; this never sees a certificate or a password store. One command in flight at a time,
+* which is all SMTP allows without PIPELINING.
+*/
 const encoder$1 = new TextEncoder();
 const base64$1 = (bytes) => {
 	let binary = "";
@@ -430,7 +435,16 @@ const buildMessage = (input) => {
 	const cc = input.cc ?? [];
 	if (cc.length > 0) headers.push(["Cc", cc.join(", ")]);
 	headers.push(["Subject", encodeHeaderText(input.subject)], ["Date", formatDate(input.date)], ["Message-ID", input.messageId], ["MIME-Version", "1.0"]);
-	if (input.inReplyTo !== void 0) headers.push(["In-Reply-To", input.inReplyTo], ["References", input.inReplyTo]);
+	if (input.inReplyTo !== void 0) headers.push(["In-Reply-To", input.inReplyTo]);
+	const references = input.references ?? (input.inReplyTo === void 0 ? [] : [input.inReplyTo]);
+	if (references.length > 0) {
+		for (const id of references) assertNoLineBreak("References", id);
+		headers.push(["References", references.join("\r\n ")]);
+	}
+	for (const [name, value] of input.extraHeaders ?? []) {
+		assertNoLineBreak(name, value);
+		headers.push([name, value]);
+	}
 	for (const { filename, mimeType } of input.attachments ?? []) {
 		assertNoLineBreak("filename", filename);
 		assertNoLineBreak("Content-Type", mimeType);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yozz.app/smtp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Transport-agnostic SMTP client core plus an RFC 5322 message builder.",
   "license": "MIT",
   "homepage": "https://github.com/fishballapp/yozz",
@@ -28,13 +28,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@yozz.app/tls": "0.1.1"
-  },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsdown": "^0.22.3",
-    "@yozz.app/x509": "0.1.1"
+    "@yozz.app/tls": "0.1.3",
+    "@yozz.app/x509": "0.1.3"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm --dts",