mikser-io-post-email 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Almero Digital Marketing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# mikser-io-post-email
+
+Email postprocessor for [mikser-io](https://github.com/almero-digital-marketing/mikser-io). Reads rendered HTML from a postprocess chain, composes a MIME message, delivers it via SMTP (or any [nodemailer](https://nodemailer.com/) transport), and writes the `.eml` audit file to the output folder. Idempotency falls out of mikser's render manifest — unchanged inputs don't resend.
+
+Sits *after* `post-mjml` in the canonical chain, so the same source content ships as a web page *and* a responsive email built from one MJML layout:
+
+```
+layouts/welcome.html-mjml-email.hbs    # renderer → MJML → post-mjml → HTML → post-email → EML
+```
+
+## Install
+
+```bash
+npm install mikser-io-post-email
+```
+
+## Minimal usage
+
+```js
+// mikser.config.js
+import { documents, layouts, renderHbs, frontMatter } from 'mikser-io'
+import { postMjml } from 'mikser-io-post-mjml'
+import { postEmail } from 'mikser-io-post-email'
+
+export default {
+    plugins: [
+        documents(),
+        frontMatter(),
+        layouts(),
+        renderHbs(),
+        postMjml(),
+        postEmail({
+            from: 'hello@me.com',
+            transport: {
+                host: 'smtp.example.com',
+                port: 587,
+                auth: { user: '...', pass: '...' },
+            },
+        }),
+    ],
+}
+```
+
+```yaml
+---
+to: alice@acme.com
+subject: Welcome, Alice
+layout: welcome.html-mjml-email
+---
+```
+
+That's the transactional case: one entity, one recipient. The `.eml` lands at `out/welcome.eml` and the message ships immediately. On the next build, mikser's render manifest sees unchanged inputs and skips the whole chain — no resend.
+
+## Recipient lists — `@listname` references
+
+For broadcast, define named lists in plugin options and reference them from `to`/`cc`/`bcc` with an `@` prefix.
+
+```js
+postEmail({
+    from: 'newsletter@me.com',
+    lists: {
+        subscribers: async ({ entity }) =>
+            (await queryEntities({ type: 'subscriber', meta: { lang: entity.meta.lang } }))
+                .map(s => s.meta.email),
+        clients:     ['ceo@acme.com', 'cto@acme.com'],
+        team:        ['ops@me.com'],
+        archive:     ['audit@me.com'],
+    },
+    bcc: ['@archive'],     // global audit copy on every send
+})
+```
+
+```yaml
+# newsletter
+---
+to: '@subscribers'
+subject: This week
+---
+
+# client update + one-off CC
+---
+to: '@clients'
+cc: ['investor@vc.com']
+---
+```
+
+### Resolution rule
+
+| Field | Where it comes from | Combine semantics |
+|---|---|---|
+| `to`  | entity `meta.to` only | exclusive — no plugin-options fallback |
+| `cc`  | entity `meta.cc` + plugin `cc` | additive, deduped (case-insensitive) |
+| `bcc` | entity `meta.bcc` + plugin `bcc` | additive, deduped |
+| `from`| entity `meta.from` ?? plugin `from` | entity wins; missing entirely → error |
+
+A `@listname` in any of these fields resolves through `options.lists`. Spec values can be a literal string, an array, or `(ctx) => Promise<string | string[]>` where `ctx = { entity, runtime, config, lists, logger }`.
+
+**Errors:**
+- `to` missing → hard error (no silent send-to-nobody).
+- `@unknown` → hard error naming the missing list.
+- `to: []` (empty after resolution) → writes an empty `.eml` marker, logs debug, no delivery. Valid "no subscribers for this language" case.
+
+## Scheduling — `sendAt`
+
+```yaml
+---
+to: '@subscribers'
+subject: Friday digest
+sendAt: 2026-06-20T09:00:00Z   # ISO 8601, or missing/'now' for immediate
+---
+```
+
+Resolution against `maxDelay` (default `'1h'`):
+
+| `sendAt` | What happens |
+|---|---|
+| missing / `'now'` | Deliver immediately during the chain |
+| future | Write `.eml`, queue a row, deliver on drain when due |
+| recent past (≤ `maxDelay`) | Catch-up: deliver immediately, warn nothing |
+| ancient past (> `maxDelay`) | Write `.eml`, mark `expired_at`, log warning, no delivery |
+
+`maxDelay` is overridable per-entity:
+
+```yaml
+---
+sendAt: 2026-06-20T09:00:00Z
+maxDelay: 4h                    # tolerate up to 4h of downtime
+---
+```
+
+### How the queue works
+
+A persistent table (`mikser_post_email_queue` in `runtime/mikser.sqlite`) holds future sends.
+
+```sql
+mikser_post_email_queue (
+    id          PRIMARY KEY → mikser_entities(id) ON DELETE CASCADE,
+    eml_path,
+    send_at, sent_at, expired_at,
+    attempts, last_error
+)
+```
+
+- **PK on entity id + UPSERT** — re-editing `sendAt` reschedules in place; can't double-queue.
+- **FK CASCADE** — delete the source doc, queue row vanishes. Schedule follows the file.
+- **Drain triggers**: on startup, after every cycle (`onFinalized`), and every 60s in `--watch` mode.
+- **Failures stay queued**: `attempts` and `last_error` track retries; the next drain re-attempts.
+- **Retention**: delivered + expired rows are kept for `retention` (default `'90d'`) then pruned.
+
+## Transport
+
+Anything [nodemailer.createTransport](https://nodemailer.com/transports/) accepts:
+
+```js
+postEmail({
+    transport: {
+        host: 'smtp.example.com', port: 587, secure: false,
+        auth: { user: '...', pass: '...' },
+    },
+})
+```
+
+With no `transport` provided, the plugin builds a JSON transport — useful for dev/testing: messages serialize to the `.eml` on disk but never leave the box.
+
+## Dry-run
+
+```js
+postEmail({ dryRun: process.env.NODE_ENV !== 'production' })
+```
+
+`dryRun: true` writes every `.eml` (so authors can review them in the output folder) but skips `transport.sendMail()`. The queue still records deliveries (with `sent_at`) for observability.
+
+## Options reference
+
+| Option | Type | Default | |
+|---|---|---|---|
+| `name` | string | `'email'` | Chain identifier (used in layout filenames as `-email`) |
+| `from` | string | required (or per-entity `from`) | Default sender |
+| `lists` | `Record<string, string \| string[] \| function>` | `{}` | Named recipient lists for `@listname` references |
+| `cc` | spec | none | Global CC, deduped with entity `cc` |
+| `bcc` | spec | none | Global BCC, deduped with entity `bcc` |
+| `transport` | nodemailer config | JSON transport | Delivery target |
+| `maxDelay` | duration string | `'1h'` | How late past `sendAt` is still acceptable |
+| `retention` | duration string | `'90d'` | How long delivered/expired rows stay in the queue |
+| `dryRun` | boolean | `false` | Write `.eml`, skip transport |
+
+## What it does NOT do (v1)
+
+- **No transport-native scheduling.** Setting `send_at` on SendGrid/Mailchimp/etc. is not exposed — when an entity is rescheduled (frontmatter edited), the transport would hold both the old and new send. The internal queue dedupes via PK; transport-native scheduling can't.
+- **No rename-preserving queue.** A file rename = old entity DELETE + new entity INSERT; the old queue row cascades out, the new one's queue row inherits the renamed file's `sendAt`. Acceptable for v1.
+- **No throttling.** If 10k pending sends drain at once after long downtime, that's transport-side load to manage via SMTP-pool config.
+- **No retry policy beyond "next drain tries again".** `attempts` is recorded for visibility; there's no exponential backoff or dead-lettering.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,273 @@
+import path from 'node:path'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import nodemailer from 'nodemailer'
+import {
+    runtime,
+    registerSchema,
+    useDatabase,
+    useLogger,
+    onLoaded,
+    onFinalized,
+} from 'mikser-io'
+import {
+    parseDuration,
+    humanizeMs,
+    resolveAddresses,
+    decideTiming,
+} from './lib/pure.js'
+
+// Re-export pure helpers so callers (and tests) can import them
+// from the package root if they want.
+export {
+    parseDuration,
+    humanizeMs,
+    resolveAddresses,
+    decideTiming,
+} from './lib/pure.js'
+
+// Postprocessor name — used in chain syntax (`welcome.html-mjml-email.hbs`)
+// and as the `post-email` plugin identifier the dispatcher resolves.
+export const output = 'eml'
+
+// Table prefix follows the cross-repo plugin-table convention:
+// strip `mikser-io-` from the package name, replace `-` with `_`,
+// prepend `mikser_`. `mikser-io-post-email` → `mikser_post_email_*`.
+registerSchema('post_email', `
+    CREATE TABLE IF NOT EXISTS mikser_post_email_queue (
+        id          TEXT PRIMARY KEY REFERENCES mikser_entities(id) ON DELETE CASCADE,
+        eml_path    TEXT NOT NULL,
+        send_at     INTEGER NOT NULL,
+        sent_at     INTEGER,
+        expired_at  INTEGER,
+        attempts    INTEGER NOT NULL DEFAULT 0,
+        last_error  TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_mikser_post_email_queue_due
+        ON mikser_post_email_queue (send_at)
+        WHERE sent_at IS NULL AND expired_at IS NULL;
+`)
+
+const DEFAULT_MAX_DELAY_MS = 60 * 60 * 1000                 // 1h
+const DEFAULT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000       // 90d
+const DRAIN_INTERVAL_MS    = 60 * 1000                      // 60s in watch mode
+
+// Per-config closures populate this on onLoaded. Module-level so the
+// postprocess() call (which is per-entity, may run on workers in
+// theory but in practice INLINE for this plugin) and the drain timer
+// share the same transport handle.
+let transport = null
+let drainTimer = null
+
+// ---------- EML composition + delivery -------------------------------
+
+// Build the .eml bytes nodemailer would have handed SMTP. Used both
+// for the on-disk audit file and (re-read) for queued deliveries.
+async function composeEml({ from, to, cc, bcc, subject, html }) {
+    const json = nodemailer.createTransport({ jsonTransport: true })
+    const built = await json.sendMail({ from, to, cc, bcc, subject, html })
+    return built.message
+}
+
+// ---------- queue ops ------------------------------------------------
+
+function upsertQueueRow({ id, emlPath, sendAt }) {
+    useDatabase().handle.prepare(`
+        INSERT INTO mikser_post_email_queue (id, eml_path, send_at)
+        VALUES (?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+            send_at    = excluded.send_at,
+            eml_path   = excluded.eml_path,
+            sent_at    = NULL,
+            expired_at = NULL,
+            attempts   = 0,
+            last_error = NULL
+    `).run(id, emlPath, sendAt)
+}
+
+function recordExpiredInBand({ id, emlPath, sendAt, reason }) {
+    // Expired during the in-band path → no future delivery, but record
+    // for observability. INSERT-or-UPDATE in case the entity was
+    // already queued and reschedule arrived too late.
+    useDatabase().handle.prepare(`
+        INSERT INTO mikser_post_email_queue (id, eml_path, send_at, expired_at, last_error)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+            send_at    = excluded.send_at,
+            expired_at = excluded.expired_at,
+            last_error = excluded.last_error
+    `).run(id, emlPath, sendAt, Date.now(), reason)
+}
+
+function markSent(id)        { useDatabase().handle.prepare(`UPDATE mikser_post_email_queue SET sent_at = ? WHERE id = ?`).run(Date.now(), id) }
+function markExpired(id, r)  { useDatabase().handle.prepare(`UPDATE mikser_post_email_queue SET expired_at = ?, last_error = ? WHERE id = ?`).run(Date.now(), r, id) }
+function markFailed(id, err) { useDatabase().handle.prepare(`UPDATE mikser_post_email_queue SET attempts = attempts + 1, last_error = ? WHERE id = ?`).run(err.message || String(err), id) }
+
+// Drain the queue: deliver due rows that are still within maxDelay,
+// expire the overdue ones. Failed deliveries stay queued for retry.
+async function drain({ config, logger }) {
+    const db = useDatabase()
+    if (!db?.isOpen) return
+
+    const maxDelayMs  = parseDuration(config.maxDelay,  DEFAULT_MAX_DELAY_MS)
+    const retentionMs = parseDuration(config.retention, DEFAULT_RETENTION_MS)
+    const now = Date.now()
+
+    // Retention prune (best-effort, runs every drain).
+    db.handle.prepare(`
+        DELETE FROM mikser_post_email_queue
+        WHERE (sent_at    IS NOT NULL AND sent_at    < ?)
+           OR (expired_at IS NOT NULL AND expired_at < ?)
+    `).run(now - retentionMs, now - retentionMs)
+
+    const due = db.handle.prepare(`
+        SELECT id, eml_path, send_at FROM mikser_post_email_queue
+        WHERE sent_at IS NULL AND expired_at IS NULL AND send_at <= ?
+        ORDER BY send_at
+    `).all(now)
+
+    for (const row of due) {
+        // Cascade-race guard: catalog delete may have fired between
+        // SELECT and now. Re-check before sending.
+        const stillThere = db.handle.prepare(`SELECT 1 FROM mikser_post_email_queue WHERE id = ?`).get(row.id)
+        if (!stillThere) continue
+
+        const overdueMs = now - row.send_at
+        if (overdueMs > maxDelayMs) {
+            const reason = `overdue by ${humanizeMs(overdueMs)}, past maxDelay ${humanizeMs(maxDelayMs)}`
+            markExpired(row.id, reason)
+            logger.warn('postEmail: %s expired — %s', row.id, reason)
+            continue
+        }
+
+        try {
+            const emlAbs = path.isAbsolute(row.eml_path)
+                ? row.eml_path
+                : path.join(runtime.options.outputFolder, row.eml_path)
+            const raw = await readFile(emlAbs)
+            if (config.dryRun) {
+                logger.info('postEmail: [dryRun] would deliver %s', row.id)
+            } else {
+                await transport.sendMail({ raw })
+            }
+            markSent(row.id)
+            logger.info('postEmail: delivered %s', row.id)
+        } catch (err) {
+            markFailed(row.id, err)
+            logger.error('postEmail: delivery failed for %s — %s', row.id, err.message || err)
+        }
+    }
+}
+
+// ---------- postprocess entrypoint -----------------------------------
+
+// `options` here is the ENGINE options bag (outputFolder, watch, etc).
+// `config`  here is the PLUGIN options the factory was called with
+// (lists, from, transport, maxDelay, dryRun, ...).
+export async function postprocess({ entity, options, config, logger }) {
+    const sourcePath = path.join(options.outputFolder, entity.origin)
+    const outputPath = path.join(options.outputFolder, entity.destination)
+    const html = await readFile(sourcePath, 'utf8')
+
+    if (!entity.meta?.to) {
+        throw new Error(`postEmail: ${entity.id} has no "to" — set entity frontmatter`)
+    }
+
+    const ctx = { entity, runtime, config, lists: config.lists ?? {}, logger }
+    const { from, to, cc, bcc, subject } = await resolveAddresses({ entity, config, ctx })
+
+    await mkdir(path.dirname(outputPath), { recursive: true })
+
+    if (!to.length) {
+        // Empty resolved list — write a marker EML and skip delivery.
+        // Valid case: language-filtered list returns no subscribers.
+        logger.debug('postEmail: %s resolved to no recipients, skipping delivery', entity.id)
+        await writeFile(outputPath, '')
+        return { success: true, result: entity.destination }
+    }
+
+    const eml = await composeEml({ from, to, cc, bcc, subject, html })
+    await writeFile(outputPath, eml)
+
+    const maxDelayMs = parseDuration(entity.meta?.maxDelay ?? config.maxDelay, DEFAULT_MAX_DELAY_MS)
+    const timing = decideTiming({ meta: entity.meta ?? {}, maxDelayMs })
+
+    if (timing.mode === 'queue') {
+        upsertQueueRow({ id: entity.id, emlPath: entity.destination, sendAt: timing.sendAt })
+        logger.info('postEmail: queued %s for %s', entity.id, new Date(timing.sendAt).toISOString())
+    } else if (timing.mode === 'expired') {
+        const reason = `overdue by ${humanizeMs(timing.overdueMs)}, past maxDelay ${humanizeMs(maxDelayMs)}`
+        recordExpiredInBand({ id: entity.id, emlPath: entity.destination, sendAt: timing.sendAt, reason })
+        logger.warn('postEmail: %s expired in-band — %s', entity.id, reason)
+    } else {
+        // mode === 'now' — deliver synchronously.
+        try {
+            if (config.dryRun) {
+                logger.info('postEmail: [dryRun] would deliver %s', entity.id)
+            } else {
+                await transport.sendMail({ from, to, cc, bcc, subject, html })
+            }
+            logger.info('postEmail: delivered %s', entity.id)
+        } catch (err) {
+            logger.error('postEmail: delivery failed for %s — %s', entity.id, err.message || err)
+            throw err
+        }
+    }
+
+    return { success: true, result: entity.destination }
+}
+
+// ---------- v9 factory + lifecycle wiring -----------------------------
+
+export function postEmail(config = {}) {
+    // Lifecycle wiring is a side-effect of the factory call. The
+    // returned descriptor is the postprocessor itself.
+    onLoaded(async () => {
+        const logger = useLogger()
+        transport = nodemailer.createTransport(config.transport ?? { jsonTransport: true })
+
+        onFinalized(async () => {
+            try {
+                await drain({ config, logger })
+            } catch (err) {
+                logger.error('postEmail: drain failed (onFinalized) — %s', err.message || err)
+            }
+        })
+
+        if (runtime.options.watch && !drainTimer) {
+            drainTimer = setInterval(() => {
+                drain({ config, logger }).catch(err => {
+                    logger.error('postEmail: drain failed (timer) — %s', err.message || err)
+                })
+            }, DRAIN_INTERVAL_MS)
+            drainTimer.unref?.()
+        }
+
+        // Run one drain at startup to catch anything that came due
+        // while mikser was off. Wrapped so a startup-time delivery
+        // failure doesn't crash the boot.
+        try {
+            await drain({ config, logger })
+        } catch (err) {
+            logger.error('postEmail: startup drain failed — %s', err.message || err)
+        }
+    })
+
+    return {
+        name: config.name ?? 'email',
+        output,
+        options: config,
+        postprocess,
+        teardown,
+    }
+}
+
+export async function teardown() {
+    if (drainTimer) {
+        clearInterval(drainTimer)
+        drainTimer = null
+    }
+    if (transport?.close) {
+        try { transport.close() } catch { /* not all transports expose close */ }
+    }
+    transport = null
+}

package/lib/pure.js

@@ -0,0 +1,91 @@
+// Pure helpers — no mikser-io, no nodemailer, no sqlite imports.
+// Kept separate so unit tests don't have to load the engine.
+
+export function parseDuration(value, fallback) {
+    if (value == null) return fallback
+    if (typeof value === 'number') return value
+    const m = /^\s*(\d+)\s*(ms|s|m|h|d)\s*$/i.exec(String(value))
+    if (!m) throw new Error(`Invalid duration: ${value} (expected e.g. "1h", "30m", "90d")`)
+    const n = Number(m[1])
+    const u = m[2].toLowerCase()
+    return n * ({ ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[u])
+}
+
+export function humanizeMs(ms) {
+    if (ms < 0) ms = -ms
+    if (ms < 1000) return `${ms}ms`
+    const s = Math.round(ms / 1000)
+    if (s < 60) return `${s}s`
+    const m = Math.round(s / 60)
+    if (m < 60) return `${m}m`
+    const h = Math.round(m / 60)
+    if (h < 48) return `${h}h`
+    return `${Math.round(h / 24)}d`
+}
+
+export async function resolveSpec(spec, ctx) {
+    if (spec == null) return []
+    if (typeof spec === 'function') spec = await spec(ctx)
+    const list = Array.isArray(spec) ? spec : [spec]
+    const out = []
+    for (const raw of list) {
+        if (raw == null || raw === '') continue
+        if (typeof raw !== 'string') {
+            throw new Error(`Recipient must be a string, got ${typeof raw}: ${JSON.stringify(raw)}`)
+        }
+        if (raw.startsWith('@')) {
+            const name = raw.slice(1)
+            const listSpec = ctx.lists?.[name]
+            if (listSpec === undefined) {
+                throw new Error(`Unknown recipient list "@${name}". Define it in postEmail({ lists: { ${name}: ... } }).`)
+            }
+            out.push(...await resolveSpec(listSpec, ctx))
+        } else {
+            out.push(raw)
+        }
+    }
+    return out
+}
+
+export function dedupe(addresses) {
+    const seen = new Set()
+    const out = []
+    for (const a of addresses) {
+        const k = a.toLowerCase().trim()
+        if (!k || seen.has(k)) continue
+        seen.add(k)
+        out.push(a)
+    }
+    return out
+}
+
+export async function resolveAddresses({ entity, config, ctx }) {
+    const meta = entity.meta ?? {}
+    const to  = dedupe(await resolveSpec(meta.to, ctx))
+    const cc  = dedupe([
+        ...await resolveSpec(meta.cc,  ctx),
+        ...await resolveSpec(config.cc, ctx),
+    ])
+    const bcc = dedupe([
+        ...await resolveSpec(meta.bcc, ctx),
+        ...await resolveSpec(config.bcc, ctx),
+    ])
+    const from = meta.from ?? config.from
+    if (!from) {
+        throw new Error(`postEmail: no "from" address — set it in postEmail({from:...}) or entity frontmatter`)
+    }
+    return { from, to, cc, bcc, subject: meta.subject }
+}
+
+export function decideTiming({ meta, maxDelayMs, now = Date.now() }) {
+    const raw = meta.sendAt
+    if (raw == null || raw === 'now') return { mode: 'now', sendAt: now }
+
+    const ts = typeof raw === 'number' ? raw : Date.parse(raw)
+    if (Number.isNaN(ts)) {
+        throw new Error(`postEmail: invalid sendAt "${raw}" (expected ISO 8601 or 'now')`)
+    }
+    if (ts > now)               return { mode: 'queue',   sendAt: ts }
+    if (now - ts <= maxDelayMs) return { mode: 'now',     sendAt: ts }
+    return                        { mode: 'expired', sendAt: ts, overdueMs: now - ts }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "mikser-io-post-email",
+  "version": "1.0.0",
+  "description": "Email postprocessor for mikser-io — sends rendered output via SMTP and writes .eml audit files. Composes after post-mjml in a chain.",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "node --no-warnings --test --test-reporter=spec 'test/**/*.test.js'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almero-digital-marketing/mikser-io-post-email.git"
+  },
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/almero-digital-marketing/mikser-io-post-email/issues"
+  },
+  "homepage": "https://github.com/almero-digital-marketing/mikser-io-post-email#readme",
+  "peerDependencies": {
+    "mikser-io": "^9.0.0"
+  },
+  "dependencies": {
+    "nodemailer": "^6.9.0"
+  }
+}

package/test/unit.test.js

@@ -0,0 +1,175 @@
+// Pure-logic tests for postEmail. No engine, no nodemailer transport,
+// no sqlite — just the resolution + decision-tree functions.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+    parseDuration, humanizeMs,
+    resolveSpec, dedupe, resolveAddresses,
+    decideTiming,
+} from '../lib/pure.js'
+
+describe('parseDuration', () => {
+    it('returns fallback on null', () => {
+        assert.equal(parseDuration(null, 42), 42)
+    })
+    it('passes through numbers', () => {
+        assert.equal(parseDuration(1234), 1234)
+    })
+    it('parses suffixed strings', () => {
+        assert.equal(parseDuration('500ms'), 500)
+        assert.equal(parseDuration('10s'),   10_000)
+        assert.equal(parseDuration('30m'),   1_800_000)
+        assert.equal(parseDuration('1h'),    3_600_000)
+        assert.equal(parseDuration('2d'),    172_800_000)
+    })
+    it('throws on garbage', () => {
+        assert.throws(() => parseDuration('soon'))
+        assert.throws(() => parseDuration('1week'))
+    })
+})
+
+describe('humanizeMs', () => {
+    it('chooses appropriate units', () => {
+        assert.equal(humanizeMs(500), '500ms')
+        assert.equal(humanizeMs(2_500), '3s')
+        assert.equal(humanizeMs(120_000), '2m')
+        assert.equal(humanizeMs(3_600_000), '1h')
+        assert.equal(humanizeMs(48 * 3_600_000), '2d')
+    })
+})
+
+describe('resolveSpec', () => {
+    const ctx = (lists = {}) => ({ entity: {}, runtime: {}, config: {}, lists, logger: { debug() {} } })
+
+    it('returns [] for null', async () => {
+        assert.deepEqual(await resolveSpec(null, ctx()), [])
+    })
+    it('passes literal address through', async () => {
+        assert.deepEqual(await resolveSpec('a@x.com', ctx()), ['a@x.com'])
+    })
+    it('expands array of literals', async () => {
+        assert.deepEqual(await resolveSpec(['a@x.com', 'b@y.com'], ctx()), ['a@x.com', 'b@y.com'])
+    })
+    it('expands @listname against options.lists', async () => {
+        const r = await resolveSpec('@team', ctx({ team: ['a@x.com', 'b@y.com'] }))
+        assert.deepEqual(r, ['a@x.com', 'b@y.com'])
+    })
+    it('expands listname when value is a function', async () => {
+        const r = await resolveSpec('@subs', ctx({ subs: async () => ['c@z.com'] }))
+        assert.deepEqual(r, ['c@z.com'])
+    })
+    it('mixes literals and @lists', async () => {
+        const r = await resolveSpec(['@team', 'extra@me.com'], ctx({ team: ['a@x.com'] }))
+        assert.deepEqual(r, ['a@x.com', 'extra@me.com'])
+    })
+    it('recurses into nested @-references', async () => {
+        const r = await resolveSpec('@outer', ctx({
+            outer: ['@inner', 'top@x.com'],
+            inner: ['a@x.com', 'b@x.com'],
+        }))
+        assert.deepEqual(r, ['a@x.com', 'b@x.com', 'top@x.com'])
+    })
+    it('throws on unknown @listname', async () => {
+        await assert.rejects(
+            () => resolveSpec('@nope', ctx()),
+            /Unknown recipient list "@nope"/,
+        )
+    })
+})
+
+describe('dedupe', () => {
+    it('removes case-insensitive duplicates', () => {
+        assert.deepEqual(
+            dedupe(['A@X.com', 'a@x.com', 'b@y.com']),
+            ['A@X.com', 'b@y.com'],
+        )
+    })
+    it('drops empty and whitespace', () => {
+        assert.deepEqual(dedupe(['', '  ', 'a@x.com']), ['a@x.com'])
+    })
+})
+
+describe('resolveAddresses', () => {
+    const entity = (meta) => ({ id: '/x', meta })
+    const ctx = (lists) => ({ runtime: {}, lists, logger: { debug() {} } })
+
+    it('to is exclusive to the entity (no options fallback)', async () => {
+        const r = await resolveAddresses({
+            entity: entity({ to: 'alice@acme.com' }),
+            config: { from: 'me@x.com', cc: ['audit@x.com'] },
+            ctx: { ...ctx(), config: {} },
+        })
+        assert.deepEqual(r.to, ['alice@acme.com'])
+        assert.deepEqual(r.cc, ['audit@x.com'])
+        assert.equal(r.from, 'me@x.com')
+    })
+    it('cc/bcc are additive between entity and options', async () => {
+        const r = await resolveAddresses({
+            entity: entity({ to: 'a@x.com', cc: ['per@entity.com'], bcc: ['x@y.com'] }),
+            config: { from: 'me@x.com', cc: ['from@options.com'], bcc: ['x@y.com', 'z@y.com'] },
+            ctx: { ...ctx(), config: {} },
+        })
+        assert.deepEqual(r.cc, ['per@entity.com', 'from@options.com'])
+        assert.deepEqual(r.bcc, ['x@y.com', 'z@y.com'])   // deduped across both
+    })
+    it('expands @listname references in any field', async () => {
+        const r = await resolveAddresses({
+            entity: entity({ to: '@subs' }),
+            config: { from: 'me@x.com', bcc: ['@audit'] },
+            ctx: { ...ctx({ subs: ['a@x.com', 'b@x.com'], audit: ['log@x.com'] }), config: {} },
+        })
+        assert.deepEqual(r.to,  ['a@x.com', 'b@x.com'])
+        assert.deepEqual(r.bcc, ['log@x.com'])
+    })
+    it('frontmatter from beats options from', async () => {
+        const r = await resolveAddresses({
+            entity: entity({ to: 'a@x.com', from: 'override@x.com' }),
+            config: { from: 'default@x.com' },
+            ctx: { ...ctx(), config: {} },
+        })
+        assert.equal(r.from, 'override@x.com')
+    })
+    it('throws when from is missing entirely', async () => {
+        await assert.rejects(
+            () => resolveAddresses({
+                entity: entity({ to: 'a@x.com' }),
+                config: {},
+                ctx: { ...ctx(), config: {} },
+            }),
+            /no "from" address/,
+        )
+    })
+})
+
+describe('decideTiming', () => {
+    const now = 1_700_000_000_000   // fixed ts to avoid Date.now-based flake
+    const oneHour = 3_600_000
+
+    it('missing sendAt → now', () => {
+        const r = decideTiming({ meta: {}, maxDelayMs: oneHour, now })
+        assert.equal(r.mode, 'now')
+        assert.equal(r.sendAt, now)
+    })
+    it('"now" literal → now', () => {
+        const r = decideTiming({ meta: { sendAt: 'now' }, maxDelayMs: oneHour, now })
+        assert.equal(r.mode, 'now')
+    })
+    it('future ISO → queue', () => {
+        const r = decideTiming({ meta: { sendAt: new Date(now + 86_400_000).toISOString() }, maxDelayMs: oneHour, now })
+        assert.equal(r.mode, 'queue')
+        assert.equal(r.sendAt, now + 86_400_000)
+    })
+    it('past within maxDelay → now (catch-up)', () => {
+        const r = decideTiming({ meta: { sendAt: new Date(now - 30 * 60_000).toISOString() }, maxDelayMs: oneHour, now })
+        assert.equal(r.mode, 'now')
+    })
+    it('past beyond maxDelay → expired', () => {
+        const r = decideTiming({ meta: { sendAt: new Date(now - 2 * oneHour).toISOString() }, maxDelayMs: oneHour, now })
+        assert.equal(r.mode, 'expired')
+        assert.ok(r.overdueMs > oneHour)
+    })
+    it('garbage sendAt throws', () => {
+        assert.throws(() => decideTiming({ meta: { sendAt: 'soon' }, maxDelayMs: oneHour, now }))
+    })
+})