mikser-io-post-email 1.1.0 → 2.0.0

package/README.md

@@ -168,7 +168,59 @@ With no `transport` provided, the plugin builds a JSON transport — useful for
 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.
+`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. No send-once marker is written, so a dry run never suppresses a later real delivery.
+
+## Send-once — durable delivery markers
+
+An email is delivered **once**, even across rebuilds. After a successful send
+the plugin writes a marker file into `sentFolder` (default `emails/` in the
+working folder); on every later build the marker suppresses re-delivery.
+
+This can't live in the queue table: mikser wipes its cache whenever
+`mikser.config.js` changes, and the queue rows cascade off `mikser_entities`.
+Both drop the sent state, so before markers existed a rebuild re-rendered every
+email document and re-sent the lot — a whole backlog of form submissions at
+once. The marker is on disk for the same reason the assets plugin keeps `.md5`
+sidecars there: it has to outlive the cache.
+
+```js
+postEmail({
+    from: 'Site <info@example.com>',
+    sentFolder: 'emails',   // default; relative to the working folder, or absolute
+    revision: 1,            // bump to invalidate every marker and allow a resend
+})
+```
+
+**Keep `sentFolder` out of source control and out of any deploy that deletes
+what it doesn't ship.** It is runtime delivery state, not build cache — unlike
+`assets/`, "who we already emailed" must never be committed, and if a deploy's
+`rsync --delete` removes it the backlog re-sends. Treat it like `runtime/`:
+add it to `.gitignore` and to the deploy's exclude list.
+
+### What counts as "the same email"
+
+The delivery identity is a hash of `from`, `to`, `cc`, `bcc`, `subject`, the
+rendered body, and `sendAt` — not the composed `.eml` bytes, which carry a
+fresh `Message-ID` and `Date` on every compose and would never match.
+
+`sendAt` is part of it on purpose: a recurring email keeps its id and its body
+and only moves its send time, so without it every occurrence after the first
+would look already-delivered and be silently dropped.
+
+**Volatile bodies.** If a template renders something that changes every build —
+a timestamp, a random token, a cache-buster — its hash changes too and the
+guard never matches. Name a stable identity in the entity's frontmatter
+instead, and the body stops being part of it:
+
+```yaml
+to: client@example.com
+subject: Your receipt
+deliveryKey: receipt-42
+```
+
+### Forcing a resend
+
+Delete the entity's marker file, or bump `revision` to invalidate all of them.
 
 ## Options reference
 
@@ -182,7 +234,9 @@ postEmail({ dryRun: process.env.NODE_ENV !== 'production' })
 | `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 |
+| `sentFolder` | string | `'emails'` | Where send-once markers live; keep it gitignored and out of the deploy's delete set |
+| `revision` | number | `1` | Bump to invalidate every marker (forces a resend) |
+| `dryRun` | boolean | `false` | Write `.eml`, skip transport (and write no marker) |
 
 ## What it does NOT do (v1)
 

package/index.js

@@ -117,6 +117,24 @@ async function recordSent(config, id, hash) {
     await writeFile(file, formatMarker(config.revision ?? 1, hash))
 }
 
+// Record the marker AFTER the mail is already out, where a failure must
+// never look like a delivery failure: the message has been handed to the
+// transport and cannot be unsent. Losing the marker only risks a future
+// duplicate (and only after a cache-wipe); treating it as a send failure
+// would guarantee one — the queue path would keep the row due and
+// re-deliver every drain, and the inline path would report a render
+// failure for mail that was actually delivered. So: warn, don't throw.
+async function recordSentSafely(config, id, hash, logger) {
+    try {
+        await recordSent(config, id, hash)
+    } catch (err) {
+        logger.warn(
+            'postEmail: %s delivered but its send-once marker could not be written in %s — %s. ' +
+            'A later rebuild may re-send it; check the folder exists and is writable.',
+            id, sentFolder(config), err.message || err)
+    }
+}
+
 // ---------- queue ops ------------------------------------------------
 
 function upsertQueueRow({ id, emlPath, emlHash, sendAt }) {
@@ -198,6 +216,15 @@ async function drain({ config, logger }) {
             continue
         }
 
+        // Rows queued by < 1.1.0 predate eml_hash, so they carry no
+        // delivery identity and cannot be marked. They still send, but
+        // say so: this one row may re-send once after the upgrade.
+        if (!row.eml_hash) {
+            logger.warn(
+                'postEmail: %s was queued before send-once tracking existed — delivering without a marker, ' +
+                'so a rebuild may re-send it once.', row.id)
+        }
+
         try {
             const emlAbs = path.isAbsolute(row.eml_path)
                 ? row.eml_path
@@ -205,11 +232,17 @@ async function drain({ config, logger }) {
             const raw = await readFile(emlAbs)
             if (config.dryRun) {
                 logger.info('postEmail: [dryRun] would deliver %s', row.id)
+                markSent(row.id)
             } else {
                 await transport.sendMail({ raw })
-                if (row.eml_hash) await recordSent(config, row.id, row.eml_hash)
+                // Order matters: the mail is out, so retire the row FIRST.
+                // If the marker write were inside this try and threw, the
+                // catch below would markFailed() and leave the row due —
+                // re-delivering the same message every drain (~every 60s
+                // in watch mode) until it expires.
+                markSent(row.id)
+                if (row.eml_hash) await recordSentSafely(config, row.id, row.eml_hash, logger)
             }
-            markSent(row.id)
             logger.info('postEmail: delivered %s', row.id)
         } catch (err) {
             markFailed(row.id, err)
@@ -250,7 +283,13 @@ export async function postprocess({ entity, options, config, logger }) {
 
     // Send-once identity for this delivery (semantic fields, not the .eml
     // bytes — those carry a fresh Message-ID/Date every compose).
-    const hash = deliveryHash({ from, to, cc, bcc, subject, html })
+    // sendAt is part of it, so a rescheduled occurrence of a recurring
+    // email is a NEW delivery rather than a suppressed duplicate.
+    const hash = deliveryHash({
+        from, to, cc, bcc, subject, html,
+        sendAt: entity.meta?.sendAt,
+        deliveryKey: entity.meta?.deliveryKey,
+    })
 
     // Already delivered this exact content? Skip delivery — whatever the
     // timing. The .eml audit file above is still refreshed; only the send
@@ -278,7 +317,8 @@ export async function postprocess({ entity, options, config, logger }) {
                 logger.info('postEmail: [dryRun] would deliver %s', entity.id)
             } else {
                 await transport.sendMail({ from, to, cc, bcc, subject, html })
-                await recordSent(config, entity.id, hash)
+                // Outside the throw path on purpose — see recordSentSafely.
+                await recordSentSafely(config, entity.id, hash, logger)
             }
             logger.info('postEmail: delivered %s', entity.id)
         } catch (err) {
@@ -301,10 +341,20 @@ export function postEmail(config = {}) {
 
         // Migrate pre-1.1 installs: the queue table predates eml_hash, and
         // CREATE TABLE IF NOT EXISTS won't add a column to an existing one.
+        //
+        // Only "already there" is expected and silent. Anything else — a
+        // locked or read-only database — must be said out loud: swallowing
+        // it leaves the table without the column, and the failure resurfaces
+        // later as an opaque "no column named eml_hash" from an INSERT
+        // inside postprocess, far from its cause.
         try {
             const db = useDatabase()
             if (db?.isOpen) db.handle.exec(`ALTER TABLE mikser_post_email_queue ADD COLUMN eml_hash TEXT`)
-        } catch { /* column already present */ }
+        } catch (err) {
+            if (!/duplicate column/i.test(err.message || '')) {
+                logger.error('postEmail: could not add the eml_hash column — %s', err.message || err)
+            }
+        }
 
         onFinalized(async () => {
             try {

package/lib/pure.js

@@ -100,24 +100,60 @@ export function decideTiming({ meta, maxDelayMs, now = Date.now() }) {
 // rebuild re-renders every email document and re-fires it. These are the
 // pure pieces; the fs lives in index.js (see sentFolder handling).
 
+// `sendAt` is part of the delivery identity, but 'now' and "absent" mean
+// the same thing, so they must normalize to the same value.
+export function normalizeSendAt(value) {
+    return (value == null || value === 'now') ? null : String(value)
+}
+
 // Stable content hash identifying a delivery. Deliberately NOT the
 // composed .eml bytes: nodemailer stamps a fresh Message-ID and Date on
 // every compose, so hashing the .eml would change on every build and
 // defeat the guard. Hash the semantic fields — same submission ⇒ same
 // hash, a genuinely edited one ⇒ new hash ⇒ resend.
-export function deliveryHash({ from, to, cc, bcc, subject, html }) {
+//
+// `sendAt` IS included: a recurring/rescheduled email keeps its id and
+// its body and only moves its send time, and without it every occurrence
+// after the first would hash identically and be suppressed — a silently
+// lost email, which is worse than the duplicate this guard prevents.
+//
+// `deliveryKey` (entity frontmatter) pins the identity explicitly for
+// templates whose rendered body is volatile — a timestamp, a random
+// token, a cache-buster. Such a body hashes differently on every build,
+// which would make the guard inert; naming a key opts out of hashing the
+// body at all.
+export function deliveryHash({ from, to, cc, bcc, subject, html, sendAt, deliveryKey }) {
     const norm = v => Array.isArray(v) ? v.join(',') : (v ?? '')
+    const keyed = deliveryKey != null
     const payload = JSON.stringify({
         from: norm(from), to: norm(to), cc: norm(cc), bcc: norm(bcc),
-        subject: subject ?? '', html: html ?? '',
+        subject: subject ?? '',
+        key: keyed ? String(deliveryKey) : null,
+        html: keyed ? '' : (html ?? ''),
+        sendAt: normalizeSendAt(sendAt),
     })
     return createHash('sha256').update(payload).digest('hex')
 }
 
-// One marker file per delivery identity. Ids carry slashes and other
-// path-hostile characters, so collapse anything non-portable to '_'.
+// One marker file per delivery identity.
+//
+// The sanitized id is for humans reading the folder; the appended digest
+// is what makes the name UNIQUE. Sanitizing alone collides: every
+// character outside the safe set becomes '_', so a fully non-ASCII id
+// (Cyrillic document paths are normal here) collapses to a name that
+// encodes only its length — '/бг/оферта' and '/бг/заявка' both became
+// '__________.sent'. Colliding entities then overwrite each other's
+// marker and BOTH re-send on every rebuild, defeating the guard, or —
+// if their content matches — one is silently never sent.
+//
+// Also bounded: ids can be long and most filesystems cap a name at 255
+// bytes. The digest is taken from the raw id, so truncation cannot
+// merge two distinct ids.
 export function markerName(id) {
-    return `${String(id).replace(/[^A-Za-z0-9._-]/g, '_')}.sent`
+    const raw = String(id)
+    const safe = raw.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120)
+    const digest = createHash('sha256').update(raw).digest('hex').slice(0, 12)
+    return `${safe}-${digest}.sent`
 }
 
 // Marker body: "<revision>:<hash>". Bumping config.revision invalidates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-post-email",
-  "version": "1.1.0",
+  "version": "2.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",
@@ -18,7 +18,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-post-email#readme",
   "peerDependencies": {
-    "mikser-io": "^9.0.0"
+    "mikser-io": "^10.0.0"
   },
   "dependencies": {
     "nodemailer": "^6.9.0"

package/test/unit.test.js

@@ -7,7 +7,7 @@ import {
     parseDuration, humanizeMs,
     resolveSpec, dedupe, resolveAddresses,
     decideTiming,
-    deliveryHash, markerName, formatMarker, isDelivered,
+    deliveryHash, markerName, formatMarker, isDelivered, normalizeSendAt,
 } from '../lib/pure.js'
 
 describe('parseDuration', () => {
@@ -195,12 +195,86 @@ describe('deliveryHash', () => {
     })
 })
 
+describe('normalizeSendAt', () => {
+    it('treats absent and "now" as the same immediate send', () => {
+        assert.equal(normalizeSendAt(undefined), null)
+        assert.equal(normalizeSendAt(null), null)
+        assert.equal(normalizeSendAt('now'), null)
+    })
+    it('keeps a real timestamp', () => {
+        assert.equal(normalizeSendAt('2026-09-01T10:00:00Z'), '2026-09-01T10:00:00Z')
+        assert.equal(normalizeSendAt(1_700_000_000_000), '1700000000000')
+    })
+})
+
+describe('deliveryHash — sendAt is part of the identity', () => {
+    const base = { from: 'me@x.com', to: 'a@x.com', subject: 'Weekly digest', html: '<p>same</p>' }
+
+    // Regression: a recurring email keeps its id, recipients and body and
+    // only moves sendAt. Hashing without sendAt made every occurrence after
+    // the first look already-delivered, so it was silently never sent.
+    it('a rescheduled occurrence of identical content is a NEW delivery', () => {
+        const week1 = deliveryHash({ ...base, sendAt: '2026-09-01T08:00:00Z' })
+        const week2 = deliveryHash({ ...base, sendAt: '2026-09-08T08:00:00Z' })
+        assert.notEqual(week1, week2)
+    })
+    it('the same occurrence still hashes stably (rebuild ⇒ no resend)', () => {
+        const a = deliveryHash({ ...base, sendAt: '2026-09-01T08:00:00Z' })
+        const b = deliveryHash({ ...base, sendAt: '2026-09-01T08:00:00Z' })
+        assert.equal(a, b)
+    })
+    it('absent and "now" sendAt are equivalent', () => {
+        assert.equal(deliveryHash(base), deliveryHash({ ...base, sendAt: 'now' }))
+    })
+})
+
+describe('deliveryHash — deliveryKey pins volatile bodies', () => {
+    const base = { from: 'me@x.com', to: 'a@x.com', subject: 'Receipt' }
+
+    it('a changing body does not change the hash when a key is set', () => {
+        const a = deliveryHash({ ...base, html: '<p>generated 10:00:01</p>', deliveryKey: 'receipt-42' })
+        const b = deliveryHash({ ...base, html: '<p>generated 23:59:59</p>', deliveryKey: 'receipt-42' })
+        assert.equal(a, b)
+    })
+    it('a different key is a different delivery', () => {
+        const a = deliveryHash({ ...base, html: '<p>x</p>', deliveryKey: 'receipt-42' })
+        const b = deliveryHash({ ...base, html: '<p>x</p>', deliveryKey: 'receipt-43' })
+        assert.notEqual(a, b)
+    })
+    it('without a key the body still counts', () => {
+        assert.notEqual(
+            deliveryHash({ ...base, html: '<p>a</p>' }),
+            deliveryHash({ ...base, html: '<p>b</p>' }),
+        )
+    })
+})
+
 describe('markerName', () => {
-    it('collapses path-hostile characters to _', () => {
-        assert.equal(markerName('/franchise/123-request'), '_franchise_123-request.sent')
+    it('keeps a readable prefix and appends a disambiguating digest', () => {
+        assert.match(markerName('/franchise/123-request'), /^_franchise_123-request-[0-9a-f]{12}\.sent$/)
     })
-    it('keeps portable characters', () => {
-        assert.equal(markerName('a.B_9-x'), 'a.B_9-x.sent')
+
+    // Regression: sanitizing alone mapped every unsafe char to '_', so ids
+    // that differ only in unsafe characters — including any two same-length
+    // Cyrillic paths — produced ONE marker file. Colliding entities then
+    // overwrote each other and both re-sent on every rebuild.
+    it('does not collide for same-length non-ASCII ids', () => {
+        assert.notEqual(markerName('/бг/оферта'), markerName('/бг/заявка'))
+    })
+    it('does not collide for ids differing only in unsafe characters', () => {
+        assert.notEqual(markerName('/mail/a:b'), markerName('/mail/a/b'))
+    })
+    it('is stable for the same id', () => {
+        assert.equal(markerName('/mail/x'), markerName('/mail/x'))
+    })
+    it('bounds the filename for very long ids', () => {
+        const name = markerName('/' + 'x'.repeat(500))
+        assert.ok(name.length <= 140, `too long: ${name.length}`)
+    })
+    it('still separates long ids that share a truncated prefix', () => {
+        const a = markerName('/' + 'x'.repeat(300) + 'a')
+        const b = markerName('/' + 'x'.repeat(300) + 'b')
+        assert.notEqual(a, b)
     })
 })