@rapidmx/crm-plugin 0.1.0

package/dist/lib/sending/Audience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Audience.js","sourceRoot":"","sources":["../../../src/sending/Audience.ts"],"names":[],"mappings":"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"}

package/dist/lib/sending/CampaignRenderer.js

@@ -0,0 +1,123 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ModelUtils } from "@rapidrest/service-core";
+import { CrmObjectType, } from "../models/types.js";
+import { buildMergeContext } from "../templates/MergeContext.js";
+import { compileDesign, renderEmail } from "../templates/Render.js";
+import { composeMessage } from "../util/Mailer.js";
+import { readValues } from "../util/PropertyValues.js";
+import { signToken } from "../util/Tokens.js";
+import { addOpenPixel, clickPath, trackLinks, verpAddress } from "./Tracking.js";
+/** Why a message can't be rendered: its campaign's template or sender is gone. Not worth retrying. */
+export class UnrenderableError extends Error {
+}
+/**
+ * Renders campaign messages, one per recipient: the variant's template filled in for the contact, with its unsubscribe and
+ * preferences links (signed tokens), tracked links and the open image when the campaign tracks them, and the headers bulk mail
+ * needs - `List-Unsubscribe` with RFC 8058 one-click, `List-Id`, `Precedence: bulk` and a `Feedback-ID`. Templates, senders and
+ * workspaces are read once per renderer (one per dispatch run).
+ */
+export class CampaignRenderer {
+    constructor(repos, settings) {
+        this.repos = repos;
+        this.settings = settings;
+        this.templates = new Map();
+        this.records = new Map();
+        this.definitions = new Map();
+    }
+    async render(send, campaign, contact) {
+        const variant = campaign.abTest?.variants.find((entry) => entry.id === send.variantId);
+        const templateUid = variant?.templateUid ?? campaign.templateUid;
+        const compiled = templateUid ? await this.template(templateUid) : undefined;
+        const sender = campaign.senderUid ? await this.record("workspaceSender", campaign.senderUid) : undefined;
+        const workspace = await this.record("workspace", campaign.workspaceUid);
+        if (!compiled || !sender || !workspace) {
+            throw new UnrenderableError("The campaign's template or sender no longer exists.");
+        }
+        const { secret, publicUrl } = this.settings;
+        const unsubscribeToken = signToken({ p: "unsub", w: workspace.uid, c: contact.uid, l: campaign.listUids, s: send.uid }, secret);
+        const links = {
+            unsubscribe: `${publicUrl}/subscriptions/unsubscribe/${unsubscribeToken}`,
+            preferences: `${publicUrl}/subscriptions/${signToken({ p: "prefs", w: workspace.uid, c: contact.uid }, secret)}`,
+        };
+        const company = contact.companyUid ? await this.record("company", contact.companyUid) : undefined;
+        const values = await readValues(await this.repos.get("propertyValue"), company ? [contact.uid, company.uid] : [contact.uid]);
+        const definitions = await this.workspaceDefinitions(workspace.uid);
+        const firstList = campaign.listUids[0] ? await this.record("mailingList", campaign.listUids[0]) : undefined;
+        const context = buildMergeContext({
+            workspace,
+            contact,
+            contactValues: values.get(contact.uid),
+            contactDefinitions: definitions.filter((definition) => definition.objectType === CrmObjectType.CONTACT),
+            company,
+            companyValues: company ? values.get(company.uid) : undefined,
+            companyDefinitions: definitions.filter((definition) => definition.objectType === CrmObjectType.COMPANY),
+            sender,
+            list: firstList ? { name: firstList.publicName } : undefined,
+            links,
+        });
+        const email = await renderEmail(compiled.compiled, send.subject ?? variant?.subject ?? compiled.template.subject, context);
+        let html = email.html;
+        if (campaign.trackClicks) {
+            html = trackLinks(html, (url, index) => `${publicUrl}/api/mail/crm${clickPath(secret, send.token, index, url)}`, new Set([links.unsubscribe, links.preferences])).html;
+        }
+        if (campaign.trackOpens) {
+            html = addOpenPixel(html, `${publicUrl}/api/mail/crm/t/o/${send.token}`);
+        }
+        const domain = sender.fromAddress.slice(sender.fromAddress.lastIndexOf("@") + 1);
+        const messageId = `${send.token}@${domain}`;
+        const raw = await composeMessage({
+            sender,
+            to: contact.email,
+            subject: email.subject,
+            text: email.text,
+            html,
+            messageId: `<${messageId}>`,
+            headers: {
+                "List-Unsubscribe": `<${publicUrl}/api/mail/crm/public/unsubscribe/${unsubscribeToken}>`,
+                "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+                "List-Id": `${listIdName(firstList?.publicName ?? workspace.name)} <${campaign.listUids[0] ?? campaign.uid}.${workspace.uid}.crm.${domain}>`,
+                Precedence: "bulk",
+                "Feedback-ID": `${campaign.uid}:${workspace.uid}:crm:rapidmx`,
+            },
+        });
+        return { raw, envelopeFrom: this.settings.verp ? verpAddress(sender.fromAddress, send.token) : sender.fromAddress, messageId, subject: email.subject };
+    }
+    template(uid) {
+        let cached = this.templates.get(uid);
+        if (!cached) {
+            cached = (async () => {
+                const template = await this.record("template", uid);
+                return template ? { template, compiled: await compileDesign(template.design, template.preheader ?? undefined) } : undefined;
+            })();
+            this.templates.set(uid, cached);
+        }
+        return cached;
+    }
+    record(name, uid) {
+        const key = `${name}:${uid}`;
+        let cached = this.records.get(key);
+        if (!cached) {
+            cached = this.repos.get(name).then((repo) => repo.findOne(uid, { ignoreACL: true, skipCache: true }));
+            this.records.set(key, cached);
+        }
+        return cached;
+    }
+    workspaceDefinitions(workspaceUid) {
+        let cached = this.definitions.get(workspaceUid);
+        if (!cached) {
+            cached = this.repos
+                .get("propertyDefinition")
+                .then((repo) => repo.find({ workspaceUid: ModelUtils.literal(workspaceUid) }, { ignoreACL: true, limit: 1000, skipCache: true }));
+            this.definitions.set(workspaceUid, cached);
+        }
+        return cached;
+    }
+}
+/** A `List-Id` phrase: the name quoted, with the characters a quoted string can't hold removed. */
+function listIdName(name) {
+    return `"${name.replace(/["\\\r\n]/g, "").slice(0, 100)}"`;
+}
+//# sourceMappingURL=CampaignRenderer.js.map

package/dist/lib/sending/CampaignRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CampaignRenderer.js","sourceRoot":"","sources":["../../../src/sending/CampaignRenderer.ts"],"names":[],"mappings":"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"}

package/dist/lib/sending/Engagement.js

@@ -0,0 +1,216 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ModelUtils } from "@rapidrest/service-core";
+import { CrmEventType, recordCrmEvent } from "../automation/Events.js";
+import { CrmObjectType, EmailStatus, EngagementType, SendSource, SuppressionReason, TimelineKind, } from "../models/types.js";
+/** How often a send's update is retried when another write to it got there first. */
+const UPDATE_ATTEMPTS = 5;
+/**
+ * Records what happened to an outbound message: an `EngagementEvent`, the message's own counters and first-times (what campaign
+ * statistics count), and what follows for the contact:
+ * - An open, click or reply makes the contact engaged (`lastEngagedAt`) - an automatic open doesn't.
+ * - The first open, the first click, a reply, a bounce and a complaint go on the contact's timeline.
+ * - A hard bounce or a complaint suppresses the address and marks the contact `bounced` or `complained`, so nothing more is sent to it.
+ *
+ * Replies, complaints and unsubscribes count once per message; a hard bounce once (a soft one may be followed by a hard one).
+ */
+export class EngagementRecorder {
+    constructor(repos, classes, logger) {
+        this.repos = repos;
+        this.classes = classes;
+        this.logger = logger;
+    }
+    /** Records `type` for `send` (as of `at`) - see the class comment. Returns the send as updated, or `undefined` for an ignored repeat. */
+    async record(send, type, data = {}, at = new Date()) {
+        const updated = await this.updateSend(send, type, data, at);
+        if (!updated) {
+            return undefined;
+        }
+        await (await this.repos.get("engagementEvent")).create(new this.classes.engagementEvent({
+            workspaceUid: send.workspaceUid,
+            sendUid: send.uid,
+            sourceType: send.sourceType,
+            sourceUid: send.sourceUid,
+            contactUid: send.contactUid,
+            variantId: send.variantId,
+            type,
+            occurredAt: at,
+            data,
+        }), { ignoreACL: true, skipPush: true });
+        await this.followUp(send, updated, type, data, at);
+        await this.recordEvent(send, updated, type, data);
+        return updated;
+    }
+    /**
+     * Applies `type` to the send's fields, retrying on version conflicts from a fresh read. `undefined` when it's a repeat that doesn't
+     * count (a second reply, complaint, unsubscribe or hard bounce).
+     */
+    async updateSend(send, type, data, at) {
+        const repo = await this.repos.get("outboundSend");
+        let current = send;
+        for (let attempt = 1;; attempt++) {
+            const changes = this.changesFor(current, type, data, at);
+            if (!changes) {
+                return undefined;
+            }
+            if (Object.keys(changes).length === 0) {
+                return current;
+            }
+            try {
+                return await repo.update({ ...changes, uid: current.uid, version: current.version }, current, { ignoreACL: true, skipPush: true });
+            }
+            catch (err) {
+                if (attempt >= UPDATE_ATTEMPTS || !/version/i.test(err?.message ?? "")) {
+                    throw err;
+                }
+                current = (await repo.findOne(send.uid, { ignoreACL: true, skipCache: true }));
+            }
+        }
+    }
+    /** What `type` changes on `send`: `{}` for nothing, `undefined` for a repeat to ignore. */
+    changesFor(send, type, data, at) {
+        switch (type) {
+            case EngagementType.OPENED: {
+                const first = !send.firstOpenedAt;
+                return {
+                    openCount: send.openCount + 1,
+                    lastOpenedAt: at,
+                    ...(first ? { firstOpenedAt: at, machineOpen: !!data.machine } : { machineOpen: send.machineOpen && !!data.machine }),
+                };
+            }
+            case EngagementType.CLICKED:
+                // A click proves the message was opened, whatever the image said.
+                return {
+                    clickCount: send.clickCount + 1,
+                    ...(send.firstClickedAt ? {} : { firstClickedAt: at }),
+                    ...(send.firstOpenedAt ? {} : { firstOpenedAt: at, lastOpenedAt: at }),
+                    ...(data.machine ? {} : { machineOpen: false }),
+                };
+            case EngagementType.BOUNCED:
+                if (send.bounceType === "hard") {
+                    return undefined;
+                }
+                return { bouncedAt: send.bouncedAt ?? at, bounceType: data.bounceType ?? "hard" };
+            case EngagementType.REPLIED:
+                return send.repliedAt ? undefined : { repliedAt: at };
+            case EngagementType.COMPLAINED:
+                return send.complainedAt ? undefined : { complainedAt: at };
+            case EngagementType.UNSUBSCRIBED:
+                return send.unsubscribedAt ? undefined : { unsubscribedAt: at };
+            default:
+                // SENT and FAILED: the dispatch job has already set the send's status.
+                return {};
+        }
+    }
+    /** The contact-side consequences of an event - see the class comment. Failures are logged, not thrown: the event is recorded. */
+    async followUp(before, after, type, data, at) {
+        try {
+            const engaged = (type === EngagementType.OPENED && !data.machine) || (type === EngagementType.CLICKED && !data.machine) || type === EngagementType.REPLIED;
+            const hard = type === EngagementType.BOUNCED && after.bounceType === "hard";
+            if (engaged || hard || type === EngagementType.COMPLAINED) {
+                await this.updateContact(after, {
+                    ...(engaged ? { lastEngagedAt: at } : {}),
+                    ...(hard ? { emailStatus: EmailStatus.BOUNCED } : {}),
+                    ...(type === EngagementType.COMPLAINED ? { emailStatus: EmailStatus.COMPLAINED } : {}),
+                });
+            }
+            if (hard || type === EngagementType.COMPLAINED) {
+                await this.suppress(after, hard ? SuppressionReason.HARD_BOUNCE : SuppressionReason.COMPLAINT);
+            }
+            const timeline = await this.timelineEntry(before, after, type, data);
+            if (timeline) {
+                await (await this.repos.get("timelineEvent")).create(new this.classes.timelineEvent({
+                    workspaceUid: after.workspaceUid,
+                    subjectType: CrmObjectType.CONTACT,
+                    subjectUid: after.contactUid,
+                    kind: timeline.kind,
+                    summary: timeline.summary,
+                    occurredAt: at,
+                    data: { sendUid: after.uid, sourceType: after.sourceType, sourceUid: after.sourceUid, ...(data.url ? { url: data.url } : {}) },
+                    refUid: after.sourceUid,
+                }), { ignoreACL: true, skipPush: true });
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`EngagementRecorder: could not update the contact of send ${after.uid}: ${err?.message ?? err}`);
+        }
+    }
+    async updateContact(send, changes) {
+        const repo = await this.repos.get("contact");
+        const contact = await repo.findOne(send.contactUid, { ignoreACL: true, skipCache: true });
+        if (!contact) {
+            return;
+        }
+        // A bounce or complaint outranks an unsubscribe, but never undoes the other.
+        if (changes.emailStatus && contact.emailStatus !== EmailStatus.ACTIVE && contact.emailStatus !== EmailStatus.UNSUBSCRIBED) {
+            delete changes.emailStatus;
+        }
+        if (Object.keys(changes).length > 0) {
+            await repo.update({ ...changes, uid: contact.uid, version: contact.version }, contact, { ignoreACL: true, skipPush: true });
+        }
+    }
+    async suppress(send, reason) {
+        const repo = await this.repos.get("suppression");
+        const existing = await repo.find({ workspaceUid: ModelUtils.literal(send.workspaceUid), email: ModelUtils.literal(send.email) }, { ignoreACL: true, limit: 1, skipCache: true });
+        if (existing.length === 0) {
+            await repo.create(new this.classes.suppression({ workspaceUid: send.workspaceUid, email: send.email, reason, note: `Send ${send.uid}` }), {
+                ignoreACL: true,
+                skipPush: true,
+            });
+        }
+    }
+    /** The timeline entry an event makes, if any: the first open, the first click, a reply, a bounce, a complaint. */
+    async timelineEntry(before, after, type, data) {
+        const name = await this.sourceName(after);
+        switch (type) {
+            case EngagementType.SENT:
+                return { kind: TimelineKind.EMAIL_SENT, summary: `Sent ${name}` };
+            case EngagementType.OPENED:
+                // The first open that looked like a person's.
+                return !data.machine && (!before.firstOpenedAt || before.machineOpen) ? { kind: TimelineKind.EMAIL_OPENED, summary: `Opened ${name}` } : undefined;
+            case EngagementType.CLICKED:
+                return !before.firstClickedAt ? { kind: TimelineKind.EMAIL_CLICKED, summary: `Clicked a link in ${name}` } : undefined;
+            case EngagementType.REPLIED:
+                return { kind: TimelineKind.EMAIL_REPLIED, summary: `Replied to ${name}` };
+            case EngagementType.BOUNCED:
+                return { kind: TimelineKind.EMAIL_BOUNCED, summary: `${name} bounced (${after.bounceType})` };
+            case EngagementType.COMPLAINED:
+                return { kind: TimelineKind.EMAIL_COMPLAINED, summary: `Reported ${name} as spam` };
+            default:
+                return undefined;
+        }
+    }
+    /** How the timeline names what was sent: the campaign's name in quotes, or "an email". */
+    async sourceName(send) {
+        const source = await (await this.repos.get(send.sourceType === SendSource.CAMPAIGN ? "campaign" : "automation")).findOne(send.sourceUid, { ignoreACL: true });
+        return source ? `"${source.name}"` : "an email";
+    }
+    /**
+     * Records the automation event of an engagement: every one but a failure, an automatic open or click, and a repeat open (only the
+     * first open a person makes is an event).
+     */
+    async recordEvent(before, after, type, data) {
+        const types = {
+            [EngagementType.SENT]: CrmEventType.EMAIL_SENT,
+            [EngagementType.OPENED]: CrmEventType.EMAIL_OPENED,
+            [EngagementType.CLICKED]: CrmEventType.EMAIL_CLICKED,
+            [EngagementType.REPLIED]: CrmEventType.EMAIL_REPLIED,
+            [EngagementType.BOUNCED]: CrmEventType.EMAIL_BOUNCED,
+            [EngagementType.UNSUBSCRIBED]: CrmEventType.EMAIL_UNSUBSCRIBED,
+        };
+        const event = types[type];
+        const repeatOpen = type === EngagementType.OPENED && !!before.firstOpenedAt && !before.machineOpen;
+        if (!event || data.machine || repeatOpen) {
+            return;
+        }
+        await recordCrmEvent(this.repos, this.classes, {
+            workspaceUid: after.workspaceUid,
+            type: event,
+            contactUid: after.contactUid,
+            data: { sendUid: after.uid, sourceType: after.sourceType, sourceUid: after.sourceUid, nodeId: after.nodeId, ...(data.url ? { url: data.url } : {}) },
+        }, this.logger);
+    }
+}
+//# sourceMappingURL=Engagement.js.map

package/dist/lib/sending/Engagement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Engagement.js","sourceRoot":"","sources":["../../../src/sending/Engagement.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,EAEH,aAAa,EACb,WAAW,EACX,cAAc,EAEd,UAAU,EAEV,iBAAiB,EACjB,YAAY,GACf,MAAM,oBAAoB,CAAC;AAE5B,qFAAqF;AACrF,MAAM,eAAe,GAAG,CAAC,CAAC;AAc1B;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAkB;IAC3B,YACqB,KAAe,EACf,OAAwB,EACxB,MAAY;QAFZ,UAAK,GAAL,KAAK,CAAU;QACf,YAAO,GAAP,OAAO,CAAiB;QACxB,WAAM,GAAN,MAAM,CAAM;IAC9B,CAAC;IAEJ,yIAAyI;IAClI,KAAK,CAAC,MAAM,CAAC,IAAkB,EAAE,IAAoB,EAAE,OAAuB,EAAE,EAAE,KAAW,IAAI,IAAI,EAAE;QAC1G,MAAM,OAAO,GAA6B,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAClD,IAAI,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,OAAO,EAAE,IAAI,CAAC,GAAG;YACjB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,IAAI;YACJ,UAAU,EAAE,EAAE;YACd,IAAI;SACP,CAAC,EACF,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CACtC,CAAC;QACF,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QACnD,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAClD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,UAAU,CAAC,IAAkB,EAAE,IAAoB,EAAE,IAAoB,EAAE,EAAQ;QAC7F,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,cAAc,CAAC,CAAC;QAChE,IAAI,OAAO,GAAiB,IAAI,CAAC;QACjC,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAChC,MAAM,OAAO,GAAsC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;YAC5F,IAAI,CAAC,OAAO,EAAE,CAAC;gBACX,OAAO,SAAS,CAAC;YACrB,CAAC;YACD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpC,OAAO,OAAO,CAAC;YACnB,CAAC;YACD,IAAI,CAAC;gBACD,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAS,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9I,CAAC;YAAC,OAAO,GAAQ,EAAE,CAAC;gBAChB,IAAI,OAAO,IAAI,eAAe,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;oBACrE,MAAM,GAAG,CAAC;gBACd,CAAC;gBACD,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAE,CAAC;YACpF,CAAC;QACL,CAAC;IACL,CAAC;IAED,2FAA2F;IACnF,UAAU,CAAC,IAAkB,EAAE,IAAoB,EAAE,IAAoB,EAAE,EAAQ;QACvF,QAAQ,IAAI,EAAE,CAAC;YACX,KAAK,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;gBACzB,MAAM,KAAK,GAAY,CAAC,IAAI,CAAC,aAAa,CAAC;gBAC3C,OAAO;oBACH,SAAS,EAAE,IAAI,CAAC,SAAS,GAAG,CAAC;oBAC7B,YAAY,EAAE,EAAE;oBAChB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;iBACxH,CAAC;YACN,CAAC;YACD,KAAK,cAAc,CAAC,OAAO;gBACvB,kEAAkE;gBAClE,OAAO;oBACH,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,CAAC;oBAC/B,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;oBACtD,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;oBACtE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;iBAClD,CAAC;YACN,KAAK,cAAc,CAAC,OAAO;gBACvB,IAAI,IAAI,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;oBAC7B,OAAO,SAAS,CAAC;gBACrB,CAAC;gBACD,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,MAAM,EAAE,CAAC;YACtF,KAAK,cAAc,CAAC,OAAO;gBACvB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;YAC1D,KAAK,cAAc,CAAC,UAAU;gBAC1B,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;YAChE,KAAK,cAAc,CAAC,YAAY;gBAC5B,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;YACpE;gBACI,uEAAuE;gBACvE,OAAO,EAAE,CAAC;QAClB,CAAC;IACL,CAAC;IAED,iIAAiI;IACzH,KAAK,CAAC,QAAQ,CAAC,MAAoB,EAAE,KAAmB,EAAE,IAAoB,EAAE,IAAoB,EAAE,EAAQ;QAClH,IAAI,CAAC;YACD,MAAM,OAAO,GACT,CAAC,IAAI,KAAK,cAAc,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,KAAK,cAAc,CAAC,OAAO,CAAC;YAC/I,MAAM,IAAI,GAAY,IAAI,KAAK,cAAc,CAAC,OAAO,IAAI,KAAK,CAAC,UAAU,KAAK,MAAM,CAAC;YACrF,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI,KAAK,cAAc,CAAC,UAAU,EAAE,CAAC;gBACxD,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE;oBAC5B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACzC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACrD,GAAG,CAAC,IAAI,KAAK,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACzF,CAAC,CAAC;YACP,CAAC;YACD,IAAI,IAAI,IAAI,IAAI,KAAK,cAAc,CAAC,UAAU,EAAE,CAAC;gBAC7C,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACnG,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACrE,IAAI,QAAQ,EAAE,CAAC;gBACX,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAChD,IAAI,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC;oBAC3B,YAAY,EAAE,KAAK,CAAC,YAAY;oBAChC,WAAW,EAAE,aAAa,CAAC,OAAO;oBAClC,UAAU,EAAE,KAAK,CAAC,UAAU;oBAC5B,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,UAAU,EAAE,EAAE;oBACd,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;oBAC9H,MAAM,EAAE,KAAK,CAAC,SAAS;iBAC1B,CAAC,EACF,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CACtC,CAAC;YACN,CAAC;QACL,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,4DAA4D,KAAK,CAAC,GAAG,KAAK,GAAG,EAAE,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC;QACvH,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,IAAkB,EAAE,OAA4B;QACxE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAa,SAAS,CAAC,CAAC;QACzD,MAAM,OAAO,GAA2B,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClH,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO;QACX,CAAC;QACD,6EAA6E;QAC7E,IAAI,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,KAAK,WAAW,CAAC,MAAM,IAAI,OAAO,CAAC,WAAW,KAAK,WAAW,CAAC,YAAY,EAAE,CAAC;YACxH,OAAO,OAAO,CAAC,WAAW,CAAC;QAC/B,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAS,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACvI,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,QAAQ,CAAC,IAAkB,EAAE,MAAyB;QAChE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAc,aAAa,CAAC,CAAC;QAC9D,MAAM,QAAQ,GAAkB,MAAM,IAAI,CAAC,IAAI,CAC3C,EAAE,YAAY,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAC9F,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CACjD,CAAC;QACF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE;gBACtI,SAAS,EAAE,IAAI;gBACf,QAAQ,EAAE,IAAI;aACjB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,kHAAkH;IAC1G,KAAK,CAAC,aAAa,CACvB,MAAoB,EACpB,KAAmB,EACnB,IAAoB,EACpB,IAAoB;QAEpB,MAAM,IAAI,GAAW,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAClD,QAAQ,IAAI,EAAE,CAAC;YACX,KAAK,cAAc,CAAC,IAAI;gBACpB,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;YACtE,KAAK,cAAc,CAAC,MAAM;gBACtB,8CAA8C;gBAC9C,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,YAAY,EAAE,OAAO,EAAE,UAAU,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YACvJ,KAAK,cAAc,CAAC,OAAO;gBACvB,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,aAAa,EAAE,OAAO,EAAE,qBAAqB,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YAC3H,KAAK,cAAc,CAAC,OAAO;gBACvB,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,aAAa,EAAE,OAAO,EAAE,cAAc,IAAI,EAAE,EAAE,CAAC;YAC/E,KAAK,cAAc,CAAC,OAAO;gBACvB,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,aAAa,EAAE,OAAO,EAAE,GAAG,IAAI,aAAa,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC;YAClG,KAAK,cAAc,CAAC,UAAU;gBAC1B,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,gBAAgB,EAAE,OAAO,EAAE,YAAY,IAAI,UAAU,EAAE,CAAC;YACxF;gBACI,OAAO,SAAS,CAAC;QACzB,CAAC;IACL,CAAC;IAED,0FAA0F;IAClF,KAAK,CAAC,UAAU,CAAC,IAAkB;QACvC,MAAM,MAAM,GAAiC,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAClJ,IAAI,CAAC,SAAS,EACd,EAAE,SAAS,EAAE,IAAI,EAAE,CACtB,CAAC;QACF,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;IACpD,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,WAAW,CAAC,MAAoB,EAAE,KAAmB,EAAE,IAAoB,EAAE,IAAoB;QAC3G,MAAM,KAAK,GAAkD;YACzD,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC,UAAU;YAC9C,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,YAAY;YAClD,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,aAAa;YACpD,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,aAAa;YACpD,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,aAAa;YACpD,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC,kBAAkB;SACjE,CAAC;QACF,MAAM,KAAK,GAA6B,KAAK,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,UAAU,GAAY,IAAI,KAAK,cAAc,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QAC5G,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,UAAU,EAAE,CAAC;YACvC,OAAO;QACX,CAAC;QACD,MAAM,cAAc,CAChB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,OAAO,EACZ;YACI,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,IAAI,EAAE,KAAK;YACX,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;SACvJ,EACD,IAAI,CAAC,MAAM,CACd,CAAC;IACN,CAAC;CACJ"}

package/dist/lib/sending/Stats.js

@@ -0,0 +1,70 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { ModelUtils } from "@rapidrest/service-core";
+import { EngagementType, SendStatus } from "../models/types.js";
+/** Counts with every number zero. */
+export function emptyCounts() {
+    return { recipients: 0, sent: 0, failed: 0, suppressed: 0, bounced: 0, opened: 0, clicked: 0, replied: 0, unsubscribed: 0, complained: 0 };
+}
+const NOT_NULL = () => ModelUtils.literal(null, "ne");
+/** The conditions of each count, on a source's sends. `opened` leaves out messages only machines opened. */
+const COUNTS = [
+    ["recipients", () => ({})],
+    ["sent", () => ({ status: ModelUtils.literal(SendStatus.SENT) })],
+    ["failed", () => ({ status: ModelUtils.literal(SendStatus.FAILED) })],
+    ["suppressed", () => ({ status: ModelUtils.literal(SendStatus.SUPPRESSED) })],
+    ["bounced", () => ({ bouncedAt: NOT_NULL() })],
+    ["opened", () => ({ firstOpenedAt: NOT_NULL(), machineOpen: ModelUtils.literal(false) })],
+    ["clicked", () => ({ firstClickedAt: NOT_NULL() })],
+    ["replied", () => ({ repliedAt: NOT_NULL() })],
+    ["unsubscribed", () => ({ unsubscribedAt: NOT_NULL() })],
+    ["complained", () => ({ complainedAt: NOT_NULL() })],
+];
+/** The counts of the sends of `sourceUid` (one variant's, when given). Cancelled sends aren't recipients. */
+export async function countSends(repo, sourceUid, variantId) {
+    const counts = emptyCounts();
+    const base = {
+        sourceUid: ModelUtils.literal(sourceUid),
+        ...(variantId !== undefined ? { variantId: ModelUtils.literal(variantId) } : {}),
+    };
+    for (const [key, condition] of COUNTS) {
+        const extra = condition();
+        counts[key] = await repo.count({ ...base, ...(key === "recipients" ? { status: ModelUtils.literal([SendStatus.CANCELLED, SendStatus.HELD], "nin") } : {}), ...extra }, { ignoreACL: true, skipCache: true });
+    }
+    return counts;
+}
+/** A campaign's stats: the counts overall and, for an A/B test, per variant. */
+export async function campaignStats(repo, campaignUid, variantIds) {
+    const stats = await countSends(repo, campaignUid);
+    if (variantIds && variantIds.length > 0) {
+        stats.variants = {};
+        for (const variantId of variantIds) {
+            stats.variants[variantId] = await countSends(repo, campaignUid, variantId);
+        }
+    }
+    return stats;
+}
+/** A campaign's links by clicks, most first - from at most `maxEvents` click events. */
+export async function linkClicks(repo, sourceUid, maxEvents = 50000) {
+    const byUrl = new Map();
+    const pageSize = 1000;
+    for (let page = 0; page * pageSize < maxEvents; page++) {
+        const events = await repo.find({ sourceUid: ModelUtils.literal(sourceUid), type: ModelUtils.literal(EngagementType.CLICKED), sort: { occurredAt: "ASC" } }, { ignoreACL: true, limit: pageSize, page, skipCache: true });
+        for (const event of events) {
+            const url = String(event.data?.url ?? "");
+            const entry = byUrl.get(url) ?? { clicks: 0, senders: new Set() };
+            entry.clicks++;
+            entry.senders.add(event.sendUid);
+            byUrl.set(url, entry);
+        }
+        if (events.length < pageSize) {
+            break;
+        }
+    }
+    return [...byUrl.entries()]
+        .map(([url, entry]) => ({ url, clicks: entry.clicks, uniqueClicks: entry.senders.size }))
+        .sort((a, b) => b.clicks - a.clicks || a.url.localeCompare(b.url));
+}
+//# sourceMappingURL=Stats.js.map

package/dist/lib/sending/Stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Stats.js","sourceRoot":"","sources":["../../../src/sending/Stats.ts"],"names":[],"mappings":"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"}

package/dist/lib/sending/Tracking.js

@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import * as crypto from "crypto";
+/** A new outbound message token: 16 random bytes, base64url (22 characters). */
+export function newSendToken() {
+    return crypto.randomBytes(16).toString("base64url");
+}
+/** What a send token looks like, for refusing anything else before a database lookup. */
+export const SEND_TOKEN = /^[A-Za-z0-9_-]{22}$/;
+function clickMac(secret, token, index, url) {
+    return crypto.createHmac("sha256", secret).update(`click|${token}|${index}|${url}`).digest("base64url");
+}
+/**
+ * The path of a tracked link: `/t/c/<token>/<index>?u=<url>&s=<signature>`. The destination travels in the link (merge tags can make
+ * every recipient's different), signed so the redirect only ever goes where the email said - never an open redirect.
+ */
+export function clickPath(secret, token, index, url) {
+    return `/t/c/${token}/${index}?u=${encodeURIComponent(url)}&s=${clickMac(secret, token, index, url)}`;
+}
+/** Whether `signature` is `clickPath()`'s for this link. Compared in constant time. */
+export function verifyClick(secret, token, index, url, signature) {
+    if (typeof signature !== "string") {
+        return false;
+    }
+    const expected = Buffer.from(clickMac(secret, token, index, url));
+    const given = Buffer.from(signature);
+    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
+}
+/** A transparent 1x1 GIF, the open-tracking image. */
+export const TRACKING_PIXEL = Buffer.from("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7", "base64");
+/** User agents of mail servers, security scanners and link previewers that fetch images and links nobody looked at. */
+const MACHINE_AGENTS = /bot|crawler|spider|preview|scanner|barracuda|mimecast|proofpoint|symantec|trendmicro|forcepoint|messagelabs|python|curl|wget|go-http|java\//i;
+/** How soon after sending an open or click is taken as automatic (a server fetching everything on arrival). */
+export const MACHINE_WINDOW_MS = 2000;
+/**
+ * Whether an open or click looks automatic rather than a person's: a known scanner or previewer, no user agent, or within
+ * `MACHINE_WINDOW_MS` of sending. Apple Mail Privacy Protection and Gmail's image proxy fetch images for their users, so their opens
+ * count - but are never proof of reading.
+ */
+export function isMachine(userAgent, sentAt, now = new Date()) {
+    if (!userAgent || MACHINE_AGENTS.test(userAgent)) {
+        return true;
+    }
+    return sentAt !== undefined && now.getTime() - new Date(sentAt).getTime() < MACHINE_WINDOW_MS;
+}
+/** `&amp;` and the other entities an `href` attribute holds, decoded - the URL a mail client follows. */
+function decodeAttribute(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;|&#x27;|&apos;/g, "'")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+function encodeAttribute(value) {
+    return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+/**
+ * `html` with the `href` of each `http(s)` link replaced by `rewrite(url, index)` - `index` counting the rewritten links from 0 in
+ * order. Links in `keep` (the unsubscribe and preference links, which must work however tracking goes), `mailto:`/`tel:` links and
+ * anything else stay as they are. Returns the HTML and the URLs, in index order.
+ */
+export function trackLinks(html, rewrite, keep) {
+    const urls = [];
+    const rewritten = html.replace(/(<a\b[^>]*?\shref=)(["'])(.*?)\2/gi, (whole, prefix, quote, raw) => {
+        const url = decodeAttribute(raw.trim());
+        if (!/^https?:\/\//i.test(url) || keep.has(url)) {
+            return whole;
+        }
+        urls.push(url);
+        return `${prefix}${quote}${encodeAttribute(rewrite(url, urls.length - 1))}${quote}`;
+    });
+    return { html: rewritten, urls };
+}
+/** `html` with the open-tracking image `src` added at the end of its body. */
+export function addOpenPixel(html, src) {
+    const pixel = `<img src="${encodeAttribute(src)}" width="1" height="1" alt="" style="display:block;width:1px;height:1px;border:0;overflow:hidden" />`;
+    const close = html.toLowerCase().lastIndexOf("</body>");
+    return close >= 0 ? `${html.slice(0, close)}${pixel}${html.slice(close)}` : `${html}${pixel}`;
+}
+/** The longest local part an address may have (RFC 5321). */
+const MAX_LOCAL_PART = 64;
+/**
+ * The bounce address (VERP) of one message: `<local>+b-<token>@<domain>` of the sender's address, so a bounce comes back to the
+ * sender's mailbox (by plus-addressing) naming the message it is about. The plain address when that would be too long.
+ */
+export function verpAddress(fromAddress, token) {
+    const at = fromAddress.lastIndexOf("@");
+    const local = `${fromAddress.slice(0, at)}+b-${token}`;
+    return local.length > MAX_LOCAL_PART ? fromAddress : `${local}${fromAddress.slice(at)}`;
+}
+/** The send token of a bounce address `verpAddress()` made, if `address` is one. */
+export function tokenFromVerp(address) {
+    return /\+b-([A-Za-z0-9_-]{22})@/.exec(address)?.[1];
+}
+//# sourceMappingURL=Tracking.js.map

package/dist/lib/sending/Tracking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tracking.js","sourceRoot":"","sources":["../../../src/sending/Tracking.ts"],"names":[],"mappings":"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"}