@bobfrankston/mailx 1.0.1

package/packages/mailx-send/README.md

@@ -0,0 +1,217 @@
+# @bobfrankston/mailx-send
+
+Queue-based mail sender with SMTP and OAuth2 support. Messages are queued as RFC 822 `.ltr` files and sent via SMTP with automatic retry.
+
+Part of the [mailx](../../README.md) email client, but usable standalone by any application.
+
+## Install
+
+```bash
+npm install @bobfrankston/mailx-send
+# or globally for CLI tools:
+npm install -g @bobfrankston/mailx-send
+```
+
+## Two CLI Commands
+
+This package provides two commands:
+
+- **`mailsend`** — create and queue a new message for sending
+- **`mailq`** — manage the outgoing mail queue (process, retry, status)
+
+## Directory Structure
+
+Each account has its own queue:
+
+```
+{baseDir}/
+  {accountId}/
+    queue/        pending .ltr files
+    sent/         sent messages (YYYY/MM/DD/) — optional log
+    fail/         failed messages awaiting retry
+```
+
+## Library API
+
+```typescript
+import { initMailSend, queueMessage } from "@bobfrankston/mailx-send";
+
+// Initialize once at startup
+initMailSend({
+    baseDir: "./mailqueue",
+    defaultAccount: "iecc",
+    logSent: true,
+    retryIntervalMs: 300000,  // 5 min
+    accounts: {
+        iecc: {
+            host: "smtp.iecc.com",
+            port: 587,
+            auth: "password",
+            user: "bob",
+            password: "secret",
+            from: "Bob Frankston <bob@iecc.com>",
+        },
+        gmail: {
+            host: "smtp.gmail.com",
+            port: 587,
+            auth: "oauth2",
+            user: "bob@gmail.com",
+            from: "Bob Frankston <bob@gmail.com>",
+            tokenProvider: async () => getOAuthToken(),
+        },
+    },
+});
+
+// Queue a message — returns filename, sends in background
+queueMessage({
+    from: "Bob Frankston <bob@iecc.com>",
+    to: ["alice@example.com"],
+    subject: "Hello",
+    html: "<p>Rich <b>HTML</b> body</p>",
+    accountId: "iecc",
+});
+```
+
+### MailMessage interface
+
+```typescript
+interface MailMessage {
+    from: string;           // "Name <address>"
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    html?: string;          // HTML body (preferred for rich email)
+    text?: string;          // Plain text body
+    inReplyTo?: string;     // Message-ID for threading
+    references?: string;    // References header for threading
+    accountId?: string;     // Queue/account to send from
+}
+```
+
+### Other API functions
+
+```typescript
+import { initMailSend, queueMessage, getMailSender } from "@bobfrankston/mailx-send";
+
+const sender = initMailSend(config);
+
+sender.processQueue("iecc");      // Process one account's queue
+sender.processAllQueues();         // Process all accounts
+sender.getStatus();                // { iecc: { pending: 2, failed: 0 }, gmail: { ... } }
+sender.startWorker();              // Start background retry timer (auto-started by initMailSend)
+sender.stopWorker();               // Stop background processing
+```
+
+## CLI: mailsend
+
+Create and queue a new message:
+
+```bash
+# From CLI arguments
+mailsend --to alice@example.com --subject "Hello" --body "Message text"
+mailsend -q gmail --from "Bob <bob@gmail.com>" --to alice@example.com --subject "Test"
+
+# From a JSON file
+mailsend --json message.json
+mailsend --json message.json -q gmail
+
+# From stdin
+echo '{"to":["alice@example.com"],"subject":"Test","text":"Hello"}' | mailsend --json -
+
+# Custom config file
+mailsend --config /path/to/mailsend.json --to ...
+```
+
+### JSON message format
+
+```json
+{
+    "to": ["alice@example.com"],
+    "cc": ["bob@example.com"],
+    "from": "Bob Frankston <bob@iecc.com>",
+    "subject": "Hello",
+    "html": "<p>Rich body</p>",
+    "text": "Plain text fallback",
+    "accountId": "iecc"
+}
+```
+
+## CLI: mailq
+
+Manage the outgoing mail queue:
+
+```bash
+mailq                     # Show queue status (all accounts)
+mailq --process           # Process all queues (send pending, retry failed)
+mailq --process -q gmail  # Process only the gmail queue
+```
+
+## Configuration
+
+Create `mailsend.json`:
+
+```json
+{
+    "baseDir": "./mailqueue",
+    "defaultAccount": "iecc",
+    "logSent": true,
+    "retryIntervalMs": 300000,
+    "accounts": {
+        "iecc": {
+            "host": "smtp.iecc.com",
+            "port": 587,
+            "auth": "password",
+            "user": "bob",
+            "password": "secret",
+            "from": "Bob Frankston <bob@iecc.com>"
+        }
+    }
+}
+```
+
+## Queue Format
+
+Messages are stored as `.ltr` files — standard RFC 822 format with an `X-MailSend-Account` header for routing. Filenames: `YYYYMMDD_HHMMSS-NNNN.ltr`
+
+## Building MIME Messages
+
+mailx-send currently builds simple single-part RFC 822 messages (text or HTML). For complex MIME messages (multipart, attachments, inline images), use one of these packages to build the raw message, then pass it to the queue:
+
+- **[nodemailer](https://www.npmjs.com/package/nodemailer)** — `MailComposer` class builds full MIME from parts (already a dependency)
+- **[emailjs-mime-builder](https://www.npmjs.com/package/emailjs-mime-builder)** — lightweight MIME builder
+- **[mimetext](https://www.npmjs.com/package/mimetext)** — simple API for building MIME messages: `createMimeMessage()`, add text/html/attachments
+- **[mailcomposer](https://www.npmjs.com/package/mailcomposer)** — standalone MIME composer (from nodemailer's author)
+
+Example with nodemailer's MailComposer:
+
+```typescript
+import MailComposer from "nodemailer/lib/mail-composer";
+
+const mail = new MailComposer({
+    from: "Bob <bob@iecc.com>",
+    to: "alice@example.com",
+    subject: "With attachment",
+    html: "<p>See attached</p>",
+    attachments: [{ filename: "doc.pdf", path: "/path/to/doc.pdf" }],
+});
+
+const raw = await mail.compile().build();
+// Write raw to the queue directory as a .ltr file
+```
+
+## Retry
+
+Failed messages move to `{accountId}/fail/YYYY/MM/DD/`. The background worker retries at the configured interval (default 5 min) by moving them back to the queue.
+
+## OAuth2 (Gmail)
+
+Set `auth: "oauth2"` and provide a `tokenProvider` function returning a current access token. Integrates with `@bobfrankston/oauthsupport` or any OAuth2 flow.
+
+## Sent Log
+
+When `logSent: true`, sent messages are preserved in `{accountId}/sent/YYYY/MM/DD/` for debugging.
+
+## License
+
+MIT

package/packages/mailx-send/cli-queue.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * mailq — manage the outgoing mail queue.
+ *
+ * Usage:
+ *   mailq                    Show queue status (all accounts)
+ *   mailq --process          Process all queues now (send pending, retry failed)
+ *   mailq --process -q gmail Process only the gmail queue
+ */
+export {};
+//# sourceMappingURL=cli-queue.d.ts.map

package/packages/mailx-send/cli-queue.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * mailq — manage the outgoing mail queue.
+ *
+ * Usage:
+ *   mailq                    Show queue status (all accounts)
+ *   mailq --process          Process all queues now (send pending, retry failed)
+ *   mailq --process -q gmail Process only the gmail queue
+ */
+import * as fs from "node:fs";
+import { initMailSend } from "./index.js";
+const args = process.argv.slice(2);
+function getArg(name) {
+    const shorts = { q: "queue" };
+    const longIdx = args.indexOf(`--${name}`);
+    const shortKey = Object.entries(shorts).find(([, v]) => v === name)?.[0];
+    const shortIdx = shortKey ? args.indexOf(`-${shortKey}`) : -1;
+    const i = Math.max(longIdx, shortIdx);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    return args[i + 1];
+}
+function hasFlag(name) {
+    return args.includes(`--${name}`);
+}
+const configPath = getArg("config") || "mailsend.json";
+if (!fs.existsSync(configPath)) {
+    console.error(`Config file not found: ${configPath}`);
+    process.exit(1);
+}
+const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+const sender = initMailSend(config);
+if (hasFlag("process")) {
+    const accountId = getArg("queue");
+    if (accountId) {
+        await sender.processQueue(accountId);
+    }
+    else {
+        await sender.processAllQueues();
+    }
+    // Show status after processing
+    const status = sender.getStatus();
+    for (const [id, s] of Object.entries(status)) {
+        console.log(`  ${id}: ${s.pending} pending, ${s.failed} failed`);
+    }
+}
+else {
+    // Default: show status
+    const status = sender.getStatus();
+    let total = 0;
+    for (const [id, s] of Object.entries(status)) {
+        console.log(`  ${id}: ${s.pending} pending, ${s.failed} failed`);
+        total += s.pending + s.failed;
+    }
+    if (total === 0)
+        console.log("  All queues empty");
+}
+process.exit(0);
+//# sourceMappingURL=cli-queue.js.map

package/packages/mailx-send/cli-send.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * mailsend — create and send an email message.
+ *
+ * Usage:
+ *   mailsend --to addr --subject "text" --body "text"
+ *   mailsend -q gmail --from "Bob <bob@gmail.com>" --to addr --subject "text"
+ *   mailsend --json message.json       Read message from JSON file
+ *   echo '{"to":["a@b.com"],...}' | mailsend --json -    Read from stdin
+ *
+ * JSON format:
+ *   { "to": ["addr"], "cc": ["addr"], "from": "Name <addr>",
+ *     "subject": "text", "text": "body", "html": "<p>body</p>",
+ *     "accountId": "iecc" }
+ */
+export {};
+//# sourceMappingURL=cli-send.d.ts.map

package/packages/mailx-send/cli-send.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * mailsend — create and send an email message.
+ *
+ * Usage:
+ *   mailsend --to addr --subject "text" --body "text"
+ *   mailsend -q gmail --from "Bob <bob@gmail.com>" --to addr --subject "text"
+ *   mailsend --json message.json       Read message from JSON file
+ *   echo '{"to":["a@b.com"],...}' | mailsend --json -    Read from stdin
+ *
+ * JSON format:
+ *   { "to": ["addr"], "cc": ["addr"], "from": "Name <addr>",
+ *     "subject": "text", "text": "body", "html": "<p>body</p>",
+ *     "accountId": "iecc" }
+ */
+import * as fs from "node:fs";
+import { initMailSend, queueMessage } from "./index.js";
+const args = process.argv.slice(2);
+function getArg(name) {
+    const shorts = { q: "queue" };
+    const longIdx = args.indexOf(`--${name}`);
+    const shortKey = Object.entries(shorts).find(([, v]) => v === name)?.[0];
+    const shortIdx = shortKey ? args.indexOf(`-${shortKey}`) : -1;
+    const i = Math.max(longIdx, shortIdx);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    return args[i + 1];
+}
+const configPath = getArg("config") || "mailsend.json";
+if (!fs.existsSync(configPath)) {
+    console.error(`Config file not found: ${configPath}`);
+    process.exit(1);
+}
+const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+const sender = initMailSend(config);
+const accountId = getArg("queue") || config.defaultAccount || "";
+let msg = {};
+const jsonArg = getArg("json");
+if (jsonArg) {
+    const raw = jsonArg === "-"
+        ? fs.readFileSync(0, "utf-8")
+        : fs.readFileSync(jsonArg, "utf-8");
+    msg = JSON.parse(raw);
+}
+else {
+    const to = getArg("to");
+    if (!to) {
+        console.error("Usage: mailsend --to addr --subject text [--body text] [--from addr] [-q account]");
+        console.error("       mailsend --json message.json [-q account]");
+        process.exit(1);
+    }
+    msg = {
+        to: to.split(",").map(s => s.trim()),
+        subject: getArg("subject") || "(no subject)",
+        text: getArg("body") || "",
+        html: getArg("html"),
+    };
+}
+const acctId = msg.accountId || accountId;
+const acct = config.accounts[acctId];
+if (!acct) {
+    console.error(`Unknown account: ${acctId}`);
+    console.error(`Available: ${Object.keys(config.accounts).join(", ")}`);
+    process.exit(1);
+}
+msg.from = msg.from || getArg("from") || acct.from || acct.user;
+msg.accountId = acctId;
+if (!msg.to?.length) {
+    console.error("Message must have at least one recipient (to)");
+    process.exit(1);
+}
+const filename = queueMessage(msg);
+console.log(`Queued: ${filename}`);
+setTimeout(() => process.exit(0), 2000);
+//# sourceMappingURL=cli-send.js.map

package/packages/mailx-send/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * mailx-send CLI — queue and send email.
+ *
+ * Queue management (process queued .ltr files):
+ *   mailx-send --process              Process all account queues now
+ *   mailx-send --process -q gmail     Process only the gmail queue
+ *   mailx-send --status               Show queue status
+ *
+ * Create and queue a new message:
+ *   mailx-send --new --to addr --subject "text" --body "text"
+ *   mailx-send --new -q gmail --from "Bob <bob@gmail.com>" --to addr --subject "text"
+ *   mailx-send --new --json message.json       Read message from JSON file
+ *   echo '{"to":["a@b.com"],...}' | mailx-send --new --json -    Read from stdin
+ *
+ * JSON message format:
+ *   { "to": ["addr"], "cc": ["addr"], "from": "Name <addr>",
+ *     "subject": "text", "text": "body", "html": "<p>body</p>",
+ *     "accountId": "iecc" }
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/packages/mailx-send/cli.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * mailx-send CLI — queue and send email.
+ *
+ * Queue management (process queued .ltr files):
+ *   mailx-send --process              Process all account queues now
+ *   mailx-send --process -q gmail     Process only the gmail queue
+ *   mailx-send --status               Show queue status
+ *
+ * Create and queue a new message:
+ *   mailx-send --new --to addr --subject "text" --body "text"
+ *   mailx-send --new -q gmail --from "Bob <bob@gmail.com>" --to addr --subject "text"
+ *   mailx-send --new --json message.json       Read message from JSON file
+ *   echo '{"to":["a@b.com"],...}' | mailx-send --new --json -    Read from stdin
+ *
+ * JSON message format:
+ *   { "to": ["addr"], "cc": ["addr"], "from": "Name <addr>",
+ *     "subject": "text", "text": "body", "html": "<p>body</p>",
+ *     "accountId": "iecc" }
+ */
+import * as fs from "node:fs";
+import { initMailSend, queueMessage } from "./index.js";
+const args = process.argv.slice(2);
+function getArg(name) {
+    const shorts = { q: "queue" };
+    const longIdx = args.indexOf(`--${name}`);
+    const shortKey = Object.entries(shorts).find(([, v]) => v === name)?.[0];
+    const shortIdx = shortKey ? args.indexOf(`-${shortKey}`) : -1;
+    const i = Math.max(longIdx, shortIdx);
+    if (i === -1 || i + 1 >= args.length)
+        return undefined;
+    return args[i + 1];
+}
+function hasFlag(name) {
+    return args.includes(`--${name}`);
+}
+// Load config
+const configPath = getArg("config") || "mailsend.json";
+if (!fs.existsSync(configPath)) {
+    console.error(`Config file not found: ${configPath}`);
+    console.error(`Create a mailsend.json with baseDir, accounts, etc.`);
+    process.exit(1);
+}
+const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+const sender = initMailSend(config);
+const accountId = getArg("queue") || config.defaultAccount || "";
+// ── Queue management ──
+if (hasFlag("status")) {
+    const status = sender.getStatus();
+    for (const [id, s] of Object.entries(status)) {
+        console.log(`  ${id}: ${s.pending} pending, ${s.failed} failed`);
+    }
+    process.exit(0);
+}
+if (hasFlag("process") && !hasFlag("new")) {
+    if (accountId && accountId !== config.defaultAccount) {
+        await sender.processQueue(accountId);
+    }
+    else {
+        await sender.processAllQueues();
+    }
+    process.exit(0);
+}
+// ── Create new message ──
+if (hasFlag("new")) {
+    let msg = {};
+    const jsonArg = getArg("json");
+    if (jsonArg) {
+        // Load from JSON file or stdin
+        const raw = jsonArg === "-"
+            ? fs.readFileSync(0, "utf-8") // stdin
+            : fs.readFileSync(jsonArg, "utf-8");
+        msg = JSON.parse(raw);
+    }
+    else {
+        // Build from CLI args
+        const to = getArg("to");
+        if (!to) {
+            console.error("--new requires --to or --json");
+            process.exit(1);
+        }
+        msg = {
+            to: to.split(",").map(s => s.trim()),
+            subject: getArg("subject") || "(no subject)",
+            text: getArg("body") || "",
+            html: getArg("html"),
+        };
+    }
+    // Set from/account
+    const acctId = msg.accountId || accountId;
+    const acct = config.accounts[acctId];
+    if (!acct) {
+        console.error(`Unknown account: ${acctId}`);
+        console.error(`Available: ${Object.keys(config.accounts).join(", ")}`);
+        process.exit(1);
+    }
+    msg.from = msg.from || getArg("from") || acct.from || acct.user;
+    msg.accountId = acctId;
+    if (!msg.to?.length) {
+        console.error("Message must have at least one recipient (to)");
+        process.exit(1);
+    }
+    const filename = queueMessage(msg);
+    console.log(`Queued: ${filename}`);
+    setTimeout(() => process.exit(0), 2000);
+}
+else if (!hasFlag("status") && !hasFlag("process")) {
+    console.error("Usage:");
+    console.error("  mailx-send --new --to addr --subject text [--body text] [-q account]");
+    console.error("  mailx-send --new --json message.json [-q account]");
+    console.error("  mailx-send --process [-q account]");
+    console.error("  mailx-send --status");
+    process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/packages/mailx-send/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @bobfrankston/mailsend
+ * Queue-based mail sender. Each account has its own queue directory.
+ * Messages queued as .ltr (RFC 822) files, sent via SMTP with retry.
+ * Supports password and OAuth2 (Gmail) authentication.
+ *
+ * Directory structure:
+ *   {baseDir}/{accountId}/queue/    — pending .ltr files
+ *   {baseDir}/{accountId}/sent/     — sent messages (optional, YYYY/MM/DD)
+ *   {baseDir}/{accountId}/fail/     — failed messages for retry
+ */
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth: "password" | "oauth2";
+    user: string;
+    password?: string;
+    /** Default From address, e.g. "Bob Frankston <bob@iecc.com>" */
+    from?: string;
+    tokenProvider?: () => Promise<string>;
+}
+export interface MailMessage {
+    from: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    inReplyTo?: string;
+    references?: string;
+    accountId?: string;
+}
+export interface MailSendConfig {
+    /** Base directory for all queues */
+    baseDir: string;
+    /** SMTP configs keyed by account ID */
+    accounts: Record<string, SmtpConfig>;
+    /** Log sent messages to sent/ subdirectory */
+    logSent?: boolean;
+    /** Retry interval in ms (default: 5 minutes) */
+    retryIntervalMs?: number;
+    /** Default account ID */
+    defaultAccount?: string;
+}
+export declare function buildRfc822(msg: MailMessage): string;
+export declare class MailSender {
+    private config;
+    private processing;
+    private retryTimer;
+    constructor(config: MailSendConfig);
+    private accountDir;
+    private queueDir;
+    private sentDir;
+    private failDir;
+    /** Queue a message. Returns the filename. */
+    queueMessage(msg: MailMessage): string;
+    /** Process pending messages for one account */
+    processQueue(accountId: string): Promise<void>;
+    /** Process all account queues */
+    processAllQueues(): Promise<void>;
+    private sendFile;
+    /** Start background worker — retries failed, processes queues */
+    startWorker(): void;
+    private retryFailed;
+    stopWorker(): void;
+    /** Get queue status per account */
+    getStatus(): Record<string, {
+        pending: number;
+        failed: number;
+    }>;
+}
+export declare function initMailSend(config: MailSendConfig): MailSender;
+export declare function getMailSender(): MailSender | null;
+export declare function queueMessage(msg: MailMessage): string;
+//# sourceMappingURL=index.d.ts.map