@aglyn/plugins-marketing 1.0.0-beta.221 → 1.0.0-beta.222

package/src/lib/server/conversion-creditor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { PluginConversionCreditor } from '@aglyn/aglyn/plugin-manager/plugin-conversion-credit';
+export declare const marketingConversionCreditor: PluginConversionCreditor;

package/src/lib/server/conversion-creditor.js

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { CAMPAIGN_CONVERSION_KINDS } from "../model/campaign-conversions.js";
+import { attributeCampaignConversion, creditCampaignSequenceOutcome, eraseCampaignAttributionsForPersonKey, resolveCampaignTouch } from "./campaign-conversion-attribution.js";
+import { eraseEmailCampaignTouches, recordEmailCampaignTouch } from "./email-campaign-touch.js";
+import { attributeOrderToEmail, reverseEmailAttributedRevenue } from "./email-revenue-attribution.js";
+/**
+ * The Marketing plugin's conversion creditor: the platform's
+ * `plugin-conversion-credit` contract, answered by the campaign joins this
+ * plugin keeps.
+ *
+ *  - a door's identify moment (a form, a lead, a contact, a booking) by the
+ *    last-touch join (`campaign-conversion-attribution.ts`);
+ *  - an order's money and its refund by the revenue join
+ *    (`email-revenue-attribution.ts`);
+ *  - a click on mail another plugin sent by the touch map
+ *    (`email-campaign-touch.ts`), which a sequence's mail stamps with its
+ *    sequence and enrollment;
+ *  - what a sequence produced, counted under the campaigns it is filed in;
+ *  - and the person's erasure, which takes the touches and every credit
+ *    drawn from them.
+ *
+ * A touch leaves here as the join resolved it and comes back from the door
+ * unread, so a value is checked for the shape the join writes before it is
+ * credited: a door that handed something else hands nobody's credit.
+ *
+ * Loaded with the first credit, never at boot; every writer it reaches
+ * already never throws.
+ */ const CHANNELS = [
+    'email',
+    'web',
+    'sequence'
+];
+/** A touch as this plugin resolved it, or `null` for anything else. */ function asResolvedTouch(value) {
+    if (!value || typeof value !== 'object') return null;
+    const channel = value['channel'];
+    const touchedAtMs = value['touchedAtMs'];
+    if (!CHANNELS.includes(channel)) return null;
+    if (typeof touchedAtMs !== 'number' || !Number.isFinite(touchedAtMs)) return null;
+    return value;
+}
+/** The touch a click on this or another plugin's mail is credited as. */ function touchOfClick(click) {
+    var _click_via, _click_via1;
+    const sequenceId = (_click_via = click.via) == null ? void 0 : _click_via['sequenceId'];
+    const enrollmentId = (_click_via1 = click.via) == null ? void 0 : _click_via1['enrollmentId'];
+    const viaSequence = Boolean(sequenceId && enrollmentId);
+    return _extends({
+        channel: viaSequence ? 'sequence' : 'email',
+        campaignId: click.creditTo
+    }, viaSequence ? {
+        sequenceId,
+        enrollmentId
+    } : {}, {
+        touchedAtMs: click.atMs
+    });
+}
+const isConversionKind = (kind)=>CAMPAIGN_CONVERSION_KINDS.includes(kind);
+export const marketingConversionCreditor = {
+    async resolveTouch (request) {
+        const touch = await resolveCampaignTouch(request);
+        return touch ? _extends({}, touch) : null;
+    },
+    async creditConversion (request) {
+        if (!isConversionKind(request.kind)) return false;
+        const touch = request.click ? touchOfClick(request.click) : asResolvedTouch(request.touch);
+        if (!touch) return false;
+        const record = await attributeCampaignConversion(_extends({
+            hostId: request.hostId,
+            kind: request.kind,
+            refId: request.refId,
+            touch
+        }, request.convertedAtMs !== undefined ? {
+            convertedAtMs: request.convertedAtMs
+        } : {}));
+        return record !== null;
+    },
+    async creditOrder (request) {
+        return await attributeOrderToEmail(request) !== null;
+    },
+    async reverseOrder (request) {
+        return reverseEmailAttributedRevenue(request);
+    },
+    async recordClick (click) {
+        var _click_email;
+        var _click_via, _click_via1;
+        const sequenceId = (_click_via = click.via) == null ? void 0 : _click_via['sequenceId'];
+        const enrollmentId = (_click_via1 = click.via) == null ? void 0 : _click_via1['enrollmentId'];
+        return recordEmailCampaignTouch(_extends({
+            email: typeof click.email === 'string' ? click.email : String((_click_email = click.email) != null ? _click_email : ''),
+            hostId: click.hostId,
+            campaignId: click.creditTo,
+            atMs: click.atMs
+        }, sequenceId && enrollmentId ? {
+            sequenceId,
+            enrollmentId
+        } : {}));
+    },
+    async creditOutcome (request) {
+        return creditCampaignSequenceOutcome(_extends({
+            hostId: request.hostId
+        }, request.orgId ? {
+            orgId: request.orgId
+        } : {}, {
+            campaignIds: request.containerIds,
+            outcome: request.outcome
+        }, request.atMs !== undefined ? {
+            atMs: request.atMs
+        } : {}));
+    },
+    async erasePerson (key) {
+        const touches = await eraseEmailCampaignTouches(key);
+        const credits = await eraseCampaignAttributionsForPersonKey(key);
+        return credits + (touches ? 1 : 0);
+    }
+};
+
+//# sourceMappingURL=conversion-creditor.js.map

package/src/lib/server/conversion-creditor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/server/conversion-creditor.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  PluginConversionClick,\n  PluginConversionCreditor,\n  PluginConversionTouch,\n} from '@aglyn/aglyn/plugin-manager/plugin-conversion-credit'\nimport { CAMPAIGN_CONVERSION_KINDS, type CampaignConversionKind } from '../model/campaign-conversions'\nimport {\n  attributeCampaignConversion,\n  creditCampaignSequenceOutcome,\n  eraseCampaignAttributionsForPersonKey,\n  resolveCampaignTouch,\n  type CampaignSequenceOutcome,\n  type CampaignTouchChannel,\n  type ResolvedCampaignTouch,\n} from './campaign-conversion-attribution'\nimport { eraseEmailCampaignTouches, recordEmailCampaignTouch } from './email-campaign-touch'\nimport { attributeOrderToEmail, reverseEmailAttributedRevenue } from './email-revenue-attribution'\n\n/**\n * The Marketing plugin's conversion creditor: the platform's\n * `plugin-conversion-credit` contract, answered by the campaign joins this\n * plugin keeps.\n *\n *  - a door's identify moment (a form, a lead, a contact, a booking) by the\n *    last-touch join (`campaign-conversion-attribution.ts`);\n *  - an order's money and its refund by the revenue join\n *    (`email-revenue-attribution.ts`);\n *  - a click on mail another plugin sent by the touch map\n *    (`email-campaign-touch.ts`), which a sequence's mail stamps with its\n *    sequence and enrollment;\n *  - what a sequence produced, counted under the campaigns it is filed in;\n *  - and the person's erasure, which takes the touches and every credit\n *    drawn from them.\n *\n * A touch leaves here as the join resolved it and comes back from the door\n * unread, so a value is checked for the shape the join writes before it is\n * credited: a door that handed something else hands nobody's credit.\n *\n * Loaded with the first credit, never at boot; every writer it reaches\n * already never throws.\n */\n\nconst CHANNELS: readonly CampaignTouchChannel[] = ['email', 'web', 'sequence']\n\n/** A touch as this plugin resolved it, or `null` for anything else. */\nfunction asResolvedTouch(value: PluginConversionTouch | null | undefined): ResolvedCampaignTouch | null {\n  if (!value || typeof value !== 'object') return null\n  const channel = value['channel']\n  const touchedAtMs = value['touchedAtMs']\n  if (!CHANNELS.includes(channel as CampaignTouchChannel)) return null\n  if (typeof touchedAtMs !== 'number' || !Number.isFinite(touchedAtMs)) return null\n  return value as unknown as ResolvedCampaignTouch\n}\n\n/** The touch a click on this or another plugin's mail is credited as. */\nfunction touchOfClick(click: PluginConversionClick): ResolvedCampaignTouch {\n  const sequenceId = click.via?.['sequenceId']\n  const enrollmentId = click.via?.['enrollmentId']\n  const viaSequence = Boolean(sequenceId && enrollmentId)\n  return {\n    channel: viaSequence ? 'sequence' : 'email',\n    campaignId: click.creditTo,\n    ...(viaSequence ? { sequenceId, enrollmentId } : {}),\n    touchedAtMs: click.atMs,\n  }\n}\n\nconst isConversionKind = (kind: string): kind is CampaignConversionKind =>\n  (CAMPAIGN_CONVERSION_KINDS as readonly string[]).includes(kind)\n\nexport const marketingConversionCreditor: PluginConversionCreditor = {\n  async resolveTouch(request) {\n    const touch = await resolveCampaignTouch(request)\n    return touch ? ({ ...touch } as PluginConversionTouch) : null\n  },\n\n  async creditConversion(request) {\n    if (!isConversionKind(request.kind)) return false\n    const touch = request.click ? touchOfClick(request.click) : asResolvedTouch(request.touch)\n    if (!touch) return false\n    const record = await attributeCampaignConversion({\n      hostId: request.hostId,\n      kind: request.kind,\n      refId: request.refId,\n      touch,\n      ...(request.convertedAtMs !== undefined ? { convertedAtMs: request.convertedAtMs } : {}),\n    })\n    return record !== null\n  },\n\n  async creditOrder(request) {\n    return (await attributeOrderToEmail(request)) !== null\n  },\n\n  async reverseOrder(request) {\n    return reverseEmailAttributedRevenue(request)\n  },\n\n  async recordClick(click) {\n    const sequenceId = click.via?.['sequenceId']\n    const enrollmentId = click.via?.['enrollmentId']\n    return recordEmailCampaignTouch({\n      email: typeof click.email === 'string' ? click.email : String(click.email ?? ''),\n      hostId: click.hostId,\n      campaignId: click.creditTo,\n      atMs: click.atMs,\n      ...(sequenceId && enrollmentId ? { sequenceId, enrollmentId } : {}),\n    })\n  },\n\n  async creditOutcome(request) {\n    return creditCampaignSequenceOutcome({\n      hostId: request.hostId,\n      ...(request.orgId ? { orgId: request.orgId } : {}),\n      campaignIds: request.containerIds,\n      outcome: request.outcome as CampaignSequenceOutcome,\n      ...(request.atMs !== undefined ? { atMs: request.atMs } : {}),\n    })\n  },\n\n  async erasePerson(key) {\n    const touches = await eraseEmailCampaignTouches(key)\n    const credits = await eraseCampaignAttributionsForPersonKey(key)\n    return credits + (touches ? 1 : 0)\n  },\n}\n"],"names":["CAMPAIGN_CONVERSION_KINDS","attributeCampaignConversion","creditCampaignSequenceOutcome","eraseCampaignAttributionsForPersonKey","resolveCampaignTouch","eraseEmailCampaignTouches","recordEmailCampaignTouch","attributeOrderToEmail","reverseEmailAttributedRevenue","CHANNELS","asResolvedTouch","value","channel","touchedAtMs","includes","Number","isFinite","touchOfClick","click","sequenceId","via","enrollmentId","viaSequence","Boolean","campaignId","creditTo","atMs","isConversionKind","kind","marketingConversionCreditor","resolveTouch","request","touch","creditConversion","record","hostId","refId","convertedAtMs","undefined","creditOrder","reverseOrder","recordClick","email","String","creditOutcome","orgId","campaignIds","containerIds","outcome","erasePerson","key","touches","credits"],"mappings":"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"}

package/src/lib/server/email-campaign-touch.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** The field on `emailDeliveries/{key}` holding the per-host touches. */
+export declare const EMAIL_TOUCH_FIELD = "campaignTouches";
+/**
+ * How many sites' touches one person's document keeps.
+ *
+ * A cap, not a page size: the map lives in a document with a 1 MiB ceiling
+ * and nothing else bounds how many sites may mail one address.
+ */
+export declare const EMAIL_TOUCH_MAX_HOSTS = 10;
+/**
+ * The last campaign one person clicked on one site.
+ *
+ * A click on a SEQUENCE email (AGL-3254) is the same touch with two more
+ * facts: the sequence and the enrollment the email went out under. The
+ * campaign is then the container the sequence is in, and the identify
+ * moments this touch is credited to read as the sequence's rather than as
+ * a campaign send's.
+ */
+export interface EmailCampaignTouch {
+    hostId: string;
+    campaignId: string;
+    /** When the click happened, epoch ms — the provider's instant. */
+    clickedAtMs: number;
+    sequenceId?: string;
+    enrollmentId?: string;
+}
+/**
+ * Records that this person clicked this campaign's mail. Never throws.
+ *
+ * Forward-only, in a transaction, for the reason the delivery log's
+ * `recordPersonEngagement` is: provider delivery is at-least-once and unordered, so a replayed click
+ * from last month must not displace this week's. That same property is what
+ * makes this idempotent — a redelivered event finds its own instant already
+ * stored and writes nothing.
+ *
+ * @returns whether the touch moved forward.
+ */
+export declare function recordEmailCampaignTouch(touch: {
+    email: string | null | undefined;
+    hostId: string;
+    campaignId: string;
+    atMs: number;
+    /** Both or neither: a sequence click names the enrollment it came through. */
+    sequenceId?: string;
+    enrollmentId?: string;
+}, firestore?: any): Promise<boolean>;
+/**
+ * The last campaign this person clicked on this site, or `null`.
+ *
+ * One keyed document read — no query, no index, and nothing that can be
+ * truncated. `null` for an address we hold no touch for AND for a read that
+ * failed, which are the same answer on purpose: both mean "we cannot say
+ * which campaign preceded this order", and the only safe thing to do with
+ * that is credit nobody.
+ */
+export declare function readEmailCampaignTouch(email: string | null | undefined, hostId: string, firestore?: any): Promise<EmailCampaignTouch | null>;
+/**
+ * Forgets every site's touch for one person, by `emailSuppressionKey` — the
+ * erasure's half of this module. Never throws; answers whether the field
+ * was on the document to delete.
+ *
+ * `update()` rather than a merge-set: a person the log never held has no
+ * document, and an erasure must not leave one behind holding a deletion.
+ */
+export declare function eraseEmailCampaignTouches(key: string | null | undefined, firestore?: any): Promise<boolean>;

package/src/lib/server/email-campaign-touch.js

@@ -0,0 +1,227 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { FieldValue } from "firebase-admin/firestore";
+import { EMAIL_DELIVERIES_COLLECTION } from "@aglyn/tenant-data-admin/server/email-delivery-log";
+import { emailSuppressionKey } from "@aglyn/tenant-data-admin/server/email-suppression";
+import firebaseAdmin from "@aglyn/tenant-data-admin/server/firebase-admin";
+const defaultFirestore = ()=>firebaseAdmin.app().firestore();
+/*==========================================
+ * THE CAMPAIGN TOUCH — which campaign this person last CLICKED, per site.
+ *
+ * The delivery log's engagement rollup (`email-delivery-log.ts`) answers "is
+ * this person still listening". It cannot answer "which email brought them
+ * here", because it keeps instants and not identities, and that second
+ * question is what attribution is: an order or a sign-up arrives, and
+ * something has to say which campaign preceded it.
+ *
+ * ## On the person's own delivery document
+ *
+ * The alternative was a per-host collection of touch documents, and it fails
+ * on erasure: an erasure arrives as an ADDRESS and knows nothing about which
+ * sites have mailed it, so a per-host collection would be a record of a
+ * person's clicks that an erasure request could not reach. On the person's
+ * document in the platform's delivery log (`emailDeliveries/{key}`) it is
+ * one field, keyed by the same hash every suppression list uses. The
+ * platform's address erasure asks this plugin to forget the person through
+ * the conversion-credit contract (`plugin-conversion-credit.ts`), and
+ * {@link eraseEmailCampaignTouches} deletes the field — a click is the same
+ * personal fact as the open recorded next to it.
+ *
+ * ## A CLICK ONLY
+ *
+ * The delivery log's `ENGAGEMENT_TYPES` include opens because the control
+ * they feed REFUSES to mail people, and the generous signal is the correct
+ * one for a refusal. This is the opposite kind of decision — it CREDITS a
+ * campaign with money — so it takes the strict signal. Since Apple's Mail Privacy Protection an open is
+ * substantially a statement about the recipient's mail client, and crediting
+ * revenue to one would credit whichever campaign most recently reached an
+ * Apple Mail user with orders from people who never read it.
+ *
+ * ## Per host, and capped
+ *
+ * A single global touch would credit site A's campaign with site B's order,
+ * or refuse both — the send path refuses cross-site reach and the revenue
+ * join has to agree with it. So the field is a map keyed by host, and a map
+ * on a document has to be bounded: past {@link EMAIL_TOUCH_MAX_HOSTS} the
+ * oldest touch is evicted, inside the transaction the forward-only rule
+ * already pays for. A person who clicks mail from eleven different sites
+ * loses their oldest click, which costs an attribution rather than a fact
+ * anybody else reads.
+ *=========================================*/ /** The field on `emailDeliveries/{key}` holding the per-host touches. */ export const EMAIL_TOUCH_FIELD = 'campaignTouches';
+/**
+ * How many sites' touches one person's document keeps.
+ *
+ * A cap, not a page size: the map lives in a document with a 1 MiB ceiling
+ * and nothing else bounds how many sites may mail one address.
+ */ export const EMAIL_TOUCH_MAX_HOSTS = 10;
+/** Reads the touch map off a person document's data, defensively. */ function touchesFrom(data) {
+    const raw = data == null ? void 0 : data[EMAIL_TOUCH_FIELD];
+    if (!raw || typeof raw !== 'object') return {};
+    const found = {};
+    for (const [hostId, entry] of Object.entries(raw)){
+        var _ref, _ref1, _ref2, _ref3;
+        const campaignId = String((_ref = entry == null ? void 0 : entry.campaignId) != null ? _ref : '');
+        const atMs = Number((_ref1 = entry == null ? void 0 : entry.atMs) != null ? _ref1 : 0);
+        if (!campaignId || !Number.isFinite(atMs) || atMs <= 0) continue;
+        const sequenceId = String((_ref2 = entry == null ? void 0 : entry.sequenceId) != null ? _ref2 : '');
+        const enrollmentId = String((_ref3 = entry == null ? void 0 : entry.enrollmentId) != null ? _ref3 : '');
+        found[hostId] = _extends({
+            campaignId,
+            atMs
+        }, sequenceId && enrollmentId ? {
+            sequenceId,
+            enrollmentId
+        } : {});
+    }
+    return found;
+}
+/**
+ * Records that this person clicked this campaign's mail. Never throws.
+ *
+ * Forward-only, in a transaction, for the reason the delivery log's
+ * `recordPersonEngagement` is: provider delivery is at-least-once and unordered, so a replayed click
+ * from last month must not displace this week's. That same property is what
+ * makes this idempotent — a redelivered event finds its own instant already
+ * stored and writes nothing.
+ *
+ * @returns whether the touch moved forward.
+ */ export async function recordEmailCampaignTouch(touch, firestore) {
+    var _touch_hostId, _touch_campaignId, _touch_sequenceId, _touch_enrollmentId;
+    const key = emailSuppressionKey(touch.email);
+    const hostId = String((_touch_hostId = touch.hostId) != null ? _touch_hostId : '');
+    const campaignId = String((_touch_campaignId = touch.campaignId) != null ? _touch_campaignId : '');
+    const atMs = Number(touch.atMs);
+    if (!key || !hostId || !campaignId) return false;
+    if (!Number.isFinite(atMs) || atMs <= 0) return false;
+    const sequenceId = String((_touch_sequenceId = touch.sequenceId) != null ? _touch_sequenceId : '');
+    const enrollmentId = String((_touch_enrollmentId = touch.enrollmentId) != null ? _touch_enrollmentId : '');
+    const viaSequence = sequenceId && enrollmentId ? {
+        sequenceId,
+        enrollmentId
+    } : {};
+    try {
+        const db = firestore != null ? firestore : defaultFirestore();
+        const ref = db.collection(EMAIL_DELIVERIES_COLLECTION).doc(key);
+        let moved = false;
+        await db.runTransaction(async (transaction)=>{
+            var _ref;
+            moved = false;
+            const snapshot = await transaction.get(ref);
+            const stored = touchesFrom((_ref = snapshot.exists ? snapshot.data() : null) != null ? _ref : {});
+            const held = stored[hostId];
+            // Not newer than what is already there, so nothing is written. An
+            // out-of-order or replayed event is the ordinary case this skips.
+            if (held && held.atMs >= atMs) return;
+            /*
+       * A merge-set merges nested maps at depth, so a campaign click after a
+       * sequence click would keep the sequence's ids beside the new campaign
+       * unless they are deleted by name: the two are written as the value
+       * or as `FieldValue.delete()` whenever the held entry carried them.
+       */ const dropSequence = (held == null ? void 0 : held.sequenceId) && !('sequenceId' in viaSequence) ? {
+                sequenceId: FieldValue.delete(),
+                enrollmentId: FieldValue.delete()
+            } : {};
+            const update = {
+                [hostId]: _extends({
+                    campaignId,
+                    atMs
+                }, viaSequence, dropSequence)
+            };
+            /*
+       * EVICTION, and only when this host is NEW to the map. Replacing an
+       * existing host's touch cannot grow it, so the cap is checked exactly
+       * where the map can cross it. The oldest goes, because the window makes
+       * an old touch the one least likely to be credited with anything.
+       *
+       * `FieldValue.delete()` INSIDE the map: a merge-set merges nested maps
+       * at depth, which is what keeps every other host's touch — and is also
+       * why an evicted key has to be deleted explicitly rather than by
+       * omission.
+       */ if (!held && Object.keys(stored).length >= EMAIL_TOUCH_MAX_HOSTS) {
+                const oldest = Object.entries(stored).sort((a, b)=>a[1].atMs - b[1].atMs || a[0].localeCompare(b[0]))[0];
+                if (oldest) update[oldest[0]] = FieldValue.delete();
+            }
+            transaction.set(ref, {
+                [EMAIL_TOUCH_FIELD]: update,
+                updatedAt: FieldValue.serverTimestamp()
+            }, {
+                merge: true
+            });
+            moved = true;
+        });
+        return moved;
+    } catch (error) {
+        console.error('[email-campaign-touch] campaign touch write failed', error);
+        return false;
+    }
+}
+/**
+ * The last campaign this person clicked on this site, or `null`.
+ *
+ * One keyed document read — no query, no index, and nothing that can be
+ * truncated. `null` for an address we hold no touch for AND for a read that
+ * failed, which are the same answer on purpose: both mean "we cannot say
+ * which campaign preceded this order", and the only safe thing to do with
+ * that is credit nobody.
+ */ export async function readEmailCampaignTouch(email, hostId, firestore) {
+    const key = emailSuppressionKey(email);
+    if (!key || !hostId) return null;
+    try {
+        var _snapshot_data;
+        const db = firestore != null ? firestore : defaultFirestore();
+        const snapshot = await db.collection(EMAIL_DELIVERIES_COLLECTION).doc(key).get();
+        const held = touchesFrom((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {})[hostId];
+        if (!held) return null;
+        return _extends({
+            hostId,
+            campaignId: held.campaignId,
+            clickedAtMs: held.atMs
+        }, held.sequenceId && held.enrollmentId ? {
+            sequenceId: held.sequenceId,
+            enrollmentId: held.enrollmentId
+        } : {});
+    } catch (error) {
+        console.error('[email-campaign-touch] campaign touch read failed', error);
+        return null;
+    }
+}
+/**
+ * Forgets every site's touch for one person, by `emailSuppressionKey` — the
+ * erasure's half of this module. Never throws; answers whether the field
+ * was on the document to delete.
+ *
+ * `update()` rather than a merge-set: a person the log never held has no
+ * document, and an erasure must not leave one behind holding a deletion.
+ */ export async function eraseEmailCampaignTouches(key, firestore) {
+    if (!key || typeof key !== 'string') return false;
+    try {
+        var _snapshot_data;
+        const db = firestore != null ? firestore : defaultFirestore();
+        const ref = db.collection(EMAIL_DELIVERIES_COLLECTION).doc(key);
+        const snapshot = await ref.get();
+        if (!snapshot.exists || !(EMAIL_TOUCH_FIELD in ((_snapshot_data = snapshot.data()) != null ? _snapshot_data : {}))) return false;
+        await ref.update({
+            [EMAIL_TOUCH_FIELD]: FieldValue.delete()
+        });
+        return true;
+    } catch (error) {
+        console.error('[email-campaign-touch] erasure failed', error);
+        return false;
+    }
+}
+
+//# sourceMappingURL=email-campaign-touch.js.map

package/src/lib/server/email-campaign-touch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/server/email-campaign-touch.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { EMAIL_DELIVERIES_COLLECTION } from '@aglyn/tenant-data-admin/server/email-delivery-log'\nimport { emailSuppressionKey } from '@aglyn/tenant-data-admin/server/email-suppression'\nimport firebaseAdmin from '@aglyn/tenant-data-admin/server/firebase-admin'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\n/*==========================================\n * THE CAMPAIGN TOUCH — which campaign this person last CLICKED, per site.\n *\n * The delivery log's engagement rollup (`email-delivery-log.ts`) answers \"is\n * this person still listening\". It cannot answer \"which email brought them\n * here\", because it keeps instants and not identities, and that second\n * question is what attribution is: an order or a sign-up arrives, and\n * something has to say which campaign preceded it.\n *\n * ## On the person's own delivery document\n *\n * The alternative was a per-host collection of touch documents, and it fails\n * on erasure: an erasure arrives as an ADDRESS and knows nothing about which\n * sites have mailed it, so a per-host collection would be a record of a\n * person's clicks that an erasure request could not reach. On the person's\n * document in the platform's delivery log (`emailDeliveries/{key}`) it is\n * one field, keyed by the same hash every suppression list uses. The\n * platform's address erasure asks this plugin to forget the person through\n * the conversion-credit contract (`plugin-conversion-credit.ts`), and\n * {@link eraseEmailCampaignTouches} deletes the field — a click is the same\n * personal fact as the open recorded next to it.\n *\n * ## A CLICK ONLY\n *\n * The delivery log's `ENGAGEMENT_TYPES` include opens because the control\n * they feed REFUSES to mail people, and the generous signal is the correct\n * one for a refusal. This is the opposite kind of decision — it CREDITS a\n * campaign with money — so it takes the strict signal. Since Apple's Mail Privacy Protection an open is\n * substantially a statement about the recipient's mail client, and crediting\n * revenue to one would credit whichever campaign most recently reached an\n * Apple Mail user with orders from people who never read it.\n *\n * ## Per host, and capped\n *\n * A single global touch would credit site A's campaign with site B's order,\n * or refuse both — the send path refuses cross-site reach and the revenue\n * join has to agree with it. So the field is a map keyed by host, and a map\n * on a document has to be bounded: past {@link EMAIL_TOUCH_MAX_HOSTS} the\n * oldest touch is evicted, inside the transaction the forward-only rule\n * already pays for. A person who clicks mail from eleven different sites\n * loses their oldest click, which costs an attribution rather than a fact\n * anybody else reads.\n *=========================================*/\n\n/** The field on `emailDeliveries/{key}` holding the per-host touches. */\nexport const EMAIL_TOUCH_FIELD = 'campaignTouches'\n\n/**\n * How many sites' touches one person's document keeps.\n *\n * A cap, not a page size: the map lives in a document with a 1 MiB ceiling\n * and nothing else bounds how many sites may mail one address.\n */\nexport const EMAIL_TOUCH_MAX_HOSTS = 10\n\n/**\n * The last campaign one person clicked on one site.\n *\n * A click on a SEQUENCE email (AGL-3254) is the same touch with two more\n * facts: the sequence and the enrollment the email went out under. The\n * campaign is then the container the sequence is in, and the identify\n * moments this touch is credited to read as the sequence's rather than as\n * a campaign send's.\n */\nexport interface EmailCampaignTouch {\n  hostId: string\n  campaignId: string\n  /** When the click happened, epoch ms — the provider's instant. */\n  clickedAtMs: number\n  sequenceId?: string\n  enrollmentId?: string\n}\n\n/** One host's entry in the touch map, as stored. */\ninterface StoredTouch {\n  campaignId: string\n  atMs: number\n  sequenceId?: string\n  enrollmentId?: string\n}\n\n/** Reads the touch map off a person document's data, defensively. */\nfunction touchesFrom(\n  data: Record<string, unknown> | null | undefined,\n): Record<string, StoredTouch> {\n  const raw = data?.[EMAIL_TOUCH_FIELD]\n  if (!raw || typeof raw !== 'object') return {}\n  const found: Record<string, StoredTouch> = {}\n  for (const [hostId, entry] of Object.entries(\n    raw as Record<\n      string,\n      { campaignId?: unknown; atMs?: unknown; sequenceId?: unknown; enrollmentId?: unknown }\n    >,\n  )) {\n    const campaignId = String(entry?.campaignId ?? '')\n    const atMs = Number(entry?.atMs ?? 0)\n    if (!campaignId || !Number.isFinite(atMs) || atMs <= 0) continue\n    const sequenceId = String(entry?.sequenceId ?? '')\n    const enrollmentId = String(entry?.enrollmentId ?? '')\n    found[hostId] = {\n      campaignId,\n      atMs,\n      ...(sequenceId && enrollmentId ? { sequenceId, enrollmentId } : {}),\n    }\n  }\n  return found\n}\n\n/**\n * Records that this person clicked this campaign's mail. Never throws.\n *\n * Forward-only, in a transaction, for the reason the delivery log's\n * `recordPersonEngagement` is: provider delivery is at-least-once and unordered, so a replayed click\n * from last month must not displace this week's. That same property is what\n * makes this idempotent — a redelivered event finds its own instant already\n * stored and writes nothing.\n *\n * @returns whether the touch moved forward.\n */\nexport async function recordEmailCampaignTouch(\n  touch: {\n    email: string | null | undefined\n    hostId: string\n    campaignId: string\n    atMs: number\n    /** Both or neither: a sequence click names the enrollment it came through. */\n    sequenceId?: string\n    enrollmentId?: string\n  },\n  firestore?: any,\n): Promise<boolean> {\n  const key = emailSuppressionKey(touch.email)\n  const hostId = String(touch.hostId ?? '')\n  const campaignId = String(touch.campaignId ?? '')\n  const atMs = Number(touch.atMs)\n  if (!key || !hostId || !campaignId) return false\n  if (!Number.isFinite(atMs) || atMs <= 0) return false\n  const sequenceId = String(touch.sequenceId ?? '')\n  const enrollmentId = String(touch.enrollmentId ?? '')\n  const viaSequence = sequenceId && enrollmentId ? { sequenceId, enrollmentId } : {}\n\n  try {\n    const db = firestore ?? defaultFirestore()\n    const ref = db.collection(EMAIL_DELIVERIES_COLLECTION).doc(key)\n    let moved = false\n    await db.runTransaction(async (transaction: any) => {\n      moved = false\n      const snapshot = await transaction.get(ref)\n      const stored = touchesFrom(\n        (snapshot.exists ? snapshot.data() : null) ?? {},\n      )\n      const held = stored[hostId]\n      // Not newer than what is already there, so nothing is written. An\n      // out-of-order or replayed event is the ordinary case this skips.\n      if (held && held.atMs >= atMs) return\n\n      /*\n       * A merge-set merges nested maps at depth, so a campaign click after a\n       * sequence click would keep the sequence's ids beside the new campaign\n       * unless they are deleted by name: the two are written as the value\n       * or as `FieldValue.delete()` whenever the held entry carried them.\n       */\n      const dropSequence =\n        held?.sequenceId && !('sequenceId' in viaSequence)\n          ? { sequenceId: FieldValue.delete(), enrollmentId: FieldValue.delete() }\n          : {}\n      const update: Record<string, unknown> = {\n        [hostId]: { campaignId, atMs, ...viaSequence, ...dropSequence },\n      }\n      /*\n       * EVICTION, and only when this host is NEW to the map. Replacing an\n       * existing host's touch cannot grow it, so the cap is checked exactly\n       * where the map can cross it. The oldest goes, because the window makes\n       * an old touch the one least likely to be credited with anything.\n       *\n       * `FieldValue.delete()` INSIDE the map: a merge-set merges nested maps\n       * at depth, which is what keeps every other host's touch — and is also\n       * why an evicted key has to be deleted explicitly rather than by\n       * omission.\n       */\n      if (!held && Object.keys(stored).length >= EMAIL_TOUCH_MAX_HOSTS) {\n        const oldest = Object.entries(stored).sort(\n          (a, b) => a[1].atMs - b[1].atMs || a[0].localeCompare(b[0]),\n        )[0]\n        if (oldest) update[oldest[0]] = FieldValue.delete()\n      }\n\n      transaction.set(\n        ref,\n        { [EMAIL_TOUCH_FIELD]: update, updatedAt: FieldValue.serverTimestamp() },\n        { merge: true },\n      )\n      moved = true\n    })\n    return moved\n  } catch (error) {\n    console.error('[email-campaign-touch] campaign touch write failed', error)\n    return false\n  }\n}\n\n/**\n * The last campaign this person clicked on this site, or `null`.\n *\n * One keyed document read — no query, no index, and nothing that can be\n * truncated. `null` for an address we hold no touch for AND for a read that\n * failed, which are the same answer on purpose: both mean \"we cannot say\n * which campaign preceded this order\", and the only safe thing to do with\n * that is credit nobody.\n */\nexport async function readEmailCampaignTouch(\n  email: string | null | undefined,\n  hostId: string,\n  firestore?: any,\n): Promise<EmailCampaignTouch | null> {\n  const key = emailSuppressionKey(email)\n  if (!key || !hostId) return null\n  try {\n    const db = firestore ?? defaultFirestore()\n    const snapshot = await db\n      .collection(EMAIL_DELIVERIES_COLLECTION)\n      .doc(key)\n      .get()\n    const held = touchesFrom(snapshot.data() ?? {})[hostId]\n    if (!held) return null\n    return {\n      hostId,\n      campaignId: held.campaignId,\n      clickedAtMs: held.atMs,\n      ...(held.sequenceId && held.enrollmentId\n        ? { sequenceId: held.sequenceId, enrollmentId: held.enrollmentId }\n        : {}),\n    }\n  } catch (error) {\n    console.error('[email-campaign-touch] campaign touch read failed', error)\n    return null\n  }\n}\n\n/**\n * Forgets every site's touch for one person, by `emailSuppressionKey` — the\n * erasure's half of this module. Never throws; answers whether the field\n * was on the document to delete.\n *\n * `update()` rather than a merge-set: a person the log never held has no\n * document, and an erasure must not leave one behind holding a deletion.\n */\nexport async function eraseEmailCampaignTouches(\n  key: string | null | undefined,\n  firestore?: any,\n): Promise<boolean> {\n  if (!key || typeof key !== 'string') return false\n  try {\n    const db = firestore ?? defaultFirestore()\n    const ref = db.collection(EMAIL_DELIVERIES_COLLECTION).doc(key)\n    const snapshot = await ref.get()\n    if (!snapshot.exists || !(EMAIL_TOUCH_FIELD in (snapshot.data() ?? {}))) return false\n    await ref.update({ [EMAIL_TOUCH_FIELD]: FieldValue.delete() })\n    return true\n  } catch (error) {\n    console.error('[email-campaign-touch] erasure failed', error)\n    return false\n  }\n}\n"],"names":["FieldValue","EMAIL_DELIVERIES_COLLECTION","emailSuppressionKey","firebaseAdmin","defaultFirestore","app","firestore","EMAIL_TOUCH_FIELD","EMAIL_TOUCH_MAX_HOSTS","touchesFrom","data","raw","found","hostId","entry","Object","entries","campaignId","String","atMs","Number","isFinite","sequenceId","enrollmentId","recordEmailCampaignTouch","touch","key","email","viaSequence","db","ref","collection","doc","moved","runTransaction","transaction","snapshot","get","stored","exists","held","dropSequence","delete","update","keys","length","oldest","sort","a","b","localeCompare","set","updatedAt","serverTimestamp","merge","error","console","readEmailCampaignTouch","clickedAtMs","eraseEmailCampaignTouches"],"mappings":"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"}

package/src/lib/server/email-events.js

@@ -38,7 +38,9 @@ import { emailSearchTokens, suppressEmail } from "@aglyn/tenant-data-admin/serve
 // Same leaf-import reasoning again: the per-recipient delivery log is the only
 // record staff have of what we sent someone, and a mocked-away writer is a
 // green test over an empty log.
-import { recordEmailCampaignTouch, recordEmailDeliveryEvents, recordPersonEngagement } from "@aglyn/tenant-data-admin/server/email-delivery-log";
+import { recordEmailDeliveryEvents, recordPersonEngagement } from "@aglyn/tenant-data-admin/server/email-delivery-log";
+// This plugin's touch map, on the same person document.
+import { recordEmailCampaignTouch } from "./email-campaign-touch.js";
 // The contact's own stamp is the record system's, asked through the core's
 // seam: what the record page, the list and the re-engagement audience read.
 import { stampRecordEmailEngagement } from "@aglyn/aglyn/plugin-manager/plugin-record-email-state";
@@ -48,7 +50,7 @@ import { getOrgForHost } from "@aglyn/tenant-data-admin/server/organizations";
 // The leaf again: which document a delivery event counts against is the
 // question every counter below depends on, and a stub would answer it for
 // them.
-import { resolveCampaignSendRef } from "@aglyn/tenant-data-admin/server/campaign-conversion-attribution";
+import { resolveCampaignSendRef } from "./campaign-conversion-attribution.js";
 import { recordEmailReputationFailure } from "@aglyn/tenant-data-admin/server/email-sender-reputation";
 // The leaf again: the ledger is what holds a sending domain's bulk mail, and
 // a wholesale mock would green a webhook that taught it nothing.
@@ -57,7 +59,7 @@ import { recordDeliverabilityFromDeliveryEvents } from "@aglyn/tenant-data-admin
 // renders them (`@aglyn/shared-ui-email-campaigns/model`) rather than here, so
 // the shape the webhook writes and the shape the report reads cannot drift
 // into two definitions of what a "link" is.
-import { CAMPAIGN_LINK_ROLLUP_MAX, campaignLinkKey } from "@aglyn/shared-ui-email-campaigns/model";
+import { SEND_LINK_ROLLUP_MAX, sendLinkKey } from "@aglyn/shared-ui-email-campaigns/model/send-report";
 import { createHash } from "crypto";
 import { FieldValue } from "firebase-admin/firestore";
 import { assignExperimentVariant } from "../model/experiments.js";
@@ -263,7 +265,7 @@ import { suppressionId } from "./campaign-send.js";
         // contain `.`, `/` or `~`, and every URL contains at least two of them.
         // The URL itself rides in the value, so nothing has to be un-hashed.
         const key = createHash('sha256').update(link).digest('hex').slice(0, 32);
-        if (links[key] === undefined && Object.keys(links).length >= CAMPAIGN_LINK_ROLLUP_MAX) {
+        if (links[key] === undefined && Object.keys(links).length >= SEND_LINK_ROLLUP_MAX) {
             transaction.set(ref, {
                 overflowClicks: FieldValue.increment(1)
             }, {
@@ -658,7 +660,7 @@ import { suppressionId } from "./campaign-send.js";
        * ONE DOCUMENT, not a document per URL. The report then reads the whole
        * table with a single `getDoc`, and the map cannot grow without bound
        * because the transaction refuses a new key past the cap and counts the
-       * click as overflow instead. `campaignLinkKey` drops the query string,
+       * click as overflow instead. `sendLinkKey` drops the query string,
        * so a link personalised per recipient cannot mint a row per recipient
        * — see that function for why that is a correctness requirement and not
        * only a size one.
@@ -675,7 +677,7 @@ import { suppressionId } from "./campaign-send.js";
                     await recordCampaignLinkClick({
                         firestore,
                         campaignRef,
-                        link: campaignLinkKey(data == null ? void 0 : (_data_click = data.click) == null ? void 0 : _data_click.link)
+                        link: sendLinkKey(data == null ? void 0 : (_data_click = data.click) == null ? void 0 : _data_click.link)
                     }).catch(()=>undefined);
                 }
                 /*==========================================