@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/campaign-conversion-attribution.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @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 { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey } from './campaign-attribution-store';
+/**
+ * THE IDENTIFY-MOMENT JOIN — a form, a lead, a contact or a booking, credited
+ * to the campaign that led to it.
+ *
+ * ## Why there is a second join at all, and why it is not a second SCHEME
+ *
+ * `email-revenue-attribution.ts` credits an ORDER by looking the buyer's
+ * address up in the touch map a click wrote. That works because an order
+ * names its buyer. Every other outcome a campaign causes is produced by
+ * somebody who was anonymous until the instant they produced it: they arrive
+ * from a campaign link, browse, and only become identifiable when they submit
+ * a form, sign up, book or check out. There is no address to look up until
+ * the very moment being attributed.
+ *
+ * So the touch is carried on the VISITOR (`campaign-touch.ts`) and attached
+ * here, at each moment they become somebody. What is NOT rebuilt is the
+ * model: the same seven-day window, the same last-click rule, the same
+ * `model`/`windowDays` stamped onto every record so a report can say what it
+ * counted. The email channel is not re-derived either — it is READ from the
+ * touch the delivery webhook already wrote, so a campaign email and a
+ * campaign ad are two inputs to one comparison rather than two schemes with
+ * two answers.
+ *
+ * ## Last touch, across both channels
+ *
+ * At the identify moment there can be two candidate touches:
+ *
+ *  - the WEB touch the visitor's device carried, from an ad, a partner link
+ *    or a social post; and
+ *  - the EMAIL touch on `emailDeliveries/{personKey}.campaignTouches[hostId]`,
+ *    written server-side when they clicked a campaign's mail.
+ *
+ * Both are window-checked and the LATER one wins. Splitting the outcome
+ * between them is the multi-touch model the revenue work rejected for the
+ * reason that applies here unchanged: a rule the merchant did not choose
+ * produces a figure nobody can check. One outcome, one campaign, and a rule
+ * stated on the record.
+ *
+ * ## No campaign touch means NO RECORD
+ *
+ * Direct traffic writes nothing at all, and there is deliberately no fallback
+ * — no "most recent campaign on this site", no referrer inference, no
+ * `utm_source=direct`. A conversion nobody can be credited with is a
+ * conversion nobody is credited with, and the absence of a record is how the
+ * report says so. The cost of a miss is one uncounted outcome; the cost of a
+ * guess is a campaign that reads as effective because it was the last one to
+ * run.
+ *
+ * ## Three reads at most, and usually one
+ *
+ * Resolving a touch costs ONE keyed document read, and only when the visitor
+ * gave an address — no query, no index, nothing that can be truncated. A door
+ * resolves once per request and hands the result to every writer beneath it,
+ * so a form submission that creates a submission, a contact and a lead pays
+ * for the lookup once rather than three times.
+ *
+ * ## Never throws
+ *
+ * The same contract as the revenue join and for the same reason: the visitor
+ * has already done the thing being attributed and the record of it is already
+ * written. A lost attribution understates a campaign; a thrown one loses a
+ * lead.
+ */
+/**
+ * The collection and the erasure sweep, re-exported so a caller needs one
+ * import for the whole join. They are DEFINED in a leaf module because the
+ * sweep runs from `email-delivery-log.ts`, which this file reads — see
+ * `campaign-attribution-store.ts` for why that cycle is not merely untidy.
+ */
+export { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey, };
+/** The single conversion rollup document under an email campaign. */
+export declare const CAMPAIGN_CONVERSIONS_REPORT_DOC = "conversions";
+/**
+ * Which identify moment a record credits.
+ *
+ * Kept apart rather than summed, which is the whole reason the kind is on the
+ * record. One form submission by a new person creates a submission, a contact
+ * and possibly a lead — three true statements about one visitor action — and
+ * a report that added them would treble every campaign's conversions. A
+ * reader asks for one kind at a time, exactly as the revenue rollup buckets
+ * by currency and never totals across them.
+ */
+export type CampaignConversionKind = 'form' | 'lead' | 'contact' | 'booking';
+/** Which channel the credited touch arrived through. */
+export type CampaignTouchChannel = 'email' | 'web';
+/** The touch a conversion is credited to, once both channels have been asked. */
+export interface ResolvedCampaignTouch {
+    channel: CampaignTouchChannel;
+    /** The campaign document, when the touch was a click on our own mail. */
+    campaignId?: string;
+    /** `utm_source`, when the touch was a link on the web. */
+    source?: string;
+    /** `utm_medium`, when the touch was a link on the web. */
+    medium?: string;
+    /** `utm_campaign`, when the touch was a link on the web. */
+    campaign?: string;
+    /** When the visitor followed the campaign link, epoch ms. */
+    touchedAtMs: number;
+    /**
+     * `sha256` of the normalized address the touch was resolved against, when
+     * the visitor gave one. The handle an erasure erases by — see
+     * {@link eraseCampaignAttributionsForPersonKey}.
+     */
+    personKey?: string;
+}
+/** What one conversion attribution record holds. */
+export interface CampaignConversionRecord extends ResolvedCampaignTouch {
+    kind: CampaignConversionKind;
+    /** The submission, lead, contact or booking this credits. */
+    refId: string;
+    /** When the visitor became identifiable. */
+    convertedAtMs: number;
+    /** The model this credit was decided under. */
+    model: string;
+    /** The window, in days, it was decided inside. */
+    windowDays: number;
+}
+/**
+ * The document id for one conversion.
+ *
+ * `{kind}:{refId}`, so the same submission credited twice is the same
+ * document — which is what makes {@link attributeCampaignConversion}'s
+ * `create()` idempotent. Scoped by kind because the ids come from different
+ * collections and a booking id has no reason to be distinct from a form
+ * submission's.
+ */
+export declare function campaignConversionId(kind: CampaignConversionKind, refId: string): string;
+/**
+ * The campaign touch to credit a conversion happening now, or `null`.
+ *
+ * Called ONCE per conversion request, at the door, and the result handed to
+ * every writer beneath it. See the module docblock for the cost argument.
+ *
+ * @returns the winning touch, or `null` when neither channel has one inside
+ *          the window — which is the ordinary case and writes nothing.
+ */
+export declare function resolveCampaignTouch(options: {
+    hostId: string;
+    /**
+     * The wire form the conversion request carried, when the door reports
+     * one. Re-parsed through the allowlist that wrote it rather than trusted:
+     * it arrives from the visitor's browser, so it may claim no more than an
+     * inbound URL could.
+     */
+    wire?: unknown;
+    /** The address the visitor identified with, raw. */
+    email?: unknown;
+    /** When they identified themselves. Defaults to now. */
+    atMs?: number;
+}, firestore?: any): Promise<ResolvedCampaignTouch | null>;
+/**
+ * Credits one conversion to the campaign the visitor last came from.
+ *
+ * ## Why the record is a document and not a field
+ *
+ * The revenue join's three reasons, and the first is decisive here too.
+ * `create()` fails when the document already exists, which is exact
+ * idempotency for free: a retried form POST, a redelivered booking webhook
+ * and a re-run capture all land here a second time and must all leave the
+ * rollup where they found it. Second, the four kinds live in four different
+ * collections — a contact is org-scoped and shared across every site in the
+ * org — so there is no one document a field could go on. Third, the
+ * submission, the lead and the booking are read by the inbox, the export and
+ * the fulfilment path, and none of them wants a field about marketing.
+ *
+ * ## The rollup exists for the EMAIL channel only
+ *
+ * A campaign document is a real entity with a real id, so its conversions
+ * roll up under it beside the revenue the same join already credits it with.
+ * A web campaign is a LABEL the marketer typed into a URL, with no document,
+ * no id and no bound on how many distinct values exist — the same unbounded
+ * key space the analytics collector caps its per-day label map against. A
+ * rollup keyed on it would be a map anybody who can vary a query string can
+ * grow. So the web channel's records stand on their own and a report reads
+ * them; see the module's report seam note.
+ *
+ * @returns the record written, or `null` when nothing was credited.
+ */
+export declare function attributeCampaignConversion(options: {
+    hostId: string;
+    kind: CampaignConversionKind;
+    /** The submission, lead, contact or booking being credited. */
+    refId: string;
+    /** The touch {@link resolveCampaignTouch} picked, or `null` for direct. */
+    touch: ResolvedCampaignTouch | null | undefined;
+    /** When the visitor became identifiable. Defaults to now. */
+    convertedAtMs?: number;
+}, firestore?: any): Promise<CampaignConversionRecord | null>;

package/src/lib/server/campaign-conversion-attribution.js

@@ -0,0 +1,279 @@
+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 { parseCampaignTouch } from "@aglyn/aglyn/app-utils/campaign-touch";
+/*
+ * Stamped from the REVENUE join's constants, aliased at the import.
+ *
+ * They are spelled `EMAIL_` because that is where both halves of that join
+ * could reach them, not because the window is an email fact — it is the
+ * platform's one answer to how long a touch may be credited. Reading them
+ * from there is what makes a lead's record and an order's record carry the
+ * same rule rather than two that happen to agree.
+ */ import { EMAIL_ATTRIBUTION_MODEL as ATTRIBUTION_MODEL, EMAIL_ATTRIBUTION_WINDOW_DAYS as ATTRIBUTION_WINDOW_DAYS, emailTouchIsInWindow } from "@aglyn/shared-util-email/email-revenue-window";
+import { personKey } from "@aglyn/aglyn/app-utils/person-key";
+import { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey } from "./campaign-attribution-store.js";
+import { readEmailCampaignTouch } from "./email-delivery-log.js";
+import { isDocumentId } from "./document-id.js";
+import firebaseAdmin from "./firebase-admin.js";
+const defaultFirestore = ()=>firebaseAdmin.app().firestore();
+/**
+ * THE IDENTIFY-MOMENT JOIN — a form, a lead, a contact or a booking, credited
+ * to the campaign that led to it.
+ *
+ * ## Why there is a second join at all, and why it is not a second SCHEME
+ *
+ * `email-revenue-attribution.ts` credits an ORDER by looking the buyer's
+ * address up in the touch map a click wrote. That works because an order
+ * names its buyer. Every other outcome a campaign causes is produced by
+ * somebody who was anonymous until the instant they produced it: they arrive
+ * from a campaign link, browse, and only become identifiable when they submit
+ * a form, sign up, book or check out. There is no address to look up until
+ * the very moment being attributed.
+ *
+ * So the touch is carried on the VISITOR (`campaign-touch.ts`) and attached
+ * here, at each moment they become somebody. What is NOT rebuilt is the
+ * model: the same seven-day window, the same last-click rule, the same
+ * `model`/`windowDays` stamped onto every record so a report can say what it
+ * counted. The email channel is not re-derived either — it is READ from the
+ * touch the delivery webhook already wrote, so a campaign email and a
+ * campaign ad are two inputs to one comparison rather than two schemes with
+ * two answers.
+ *
+ * ## Last touch, across both channels
+ *
+ * At the identify moment there can be two candidate touches:
+ *
+ *  - the WEB touch the visitor's device carried, from an ad, a partner link
+ *    or a social post; and
+ *  - the EMAIL touch on `emailDeliveries/{personKey}.campaignTouches[hostId]`,
+ *    written server-side when they clicked a campaign's mail.
+ *
+ * Both are window-checked and the LATER one wins. Splitting the outcome
+ * between them is the multi-touch model the revenue work rejected for the
+ * reason that applies here unchanged: a rule the merchant did not choose
+ * produces a figure nobody can check. One outcome, one campaign, and a rule
+ * stated on the record.
+ *
+ * ## No campaign touch means NO RECORD
+ *
+ * Direct traffic writes nothing at all, and there is deliberately no fallback
+ * — no "most recent campaign on this site", no referrer inference, no
+ * `utm_source=direct`. A conversion nobody can be credited with is a
+ * conversion nobody is credited with, and the absence of a record is how the
+ * report says so. The cost of a miss is one uncounted outcome; the cost of a
+ * guess is a campaign that reads as effective because it was the last one to
+ * run.
+ *
+ * ## Three reads at most, and usually one
+ *
+ * Resolving a touch costs ONE keyed document read, and only when the visitor
+ * gave an address — no query, no index, nothing that can be truncated. A door
+ * resolves once per request and hands the result to every writer beneath it,
+ * so a form submission that creates a submission, a contact and a lead pays
+ * for the lookup once rather than three times.
+ *
+ * ## Never throws
+ *
+ * The same contract as the revenue join and for the same reason: the visitor
+ * has already done the thing being attributed and the record of it is already
+ * written. A lost attribution understates a campaign; a thrown one loses a
+ * lead.
+ */ /**
+ * The collection and the erasure sweep, re-exported so a caller needs one
+ * import for the whole join. They are DEFINED in a leaf module because the
+ * sweep runs from `email-delivery-log.ts`, which this file reads — see
+ * `campaign-attribution-store.ts` for why that cycle is not merely untidy.
+ */ export { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey,  };
+/** The single conversion rollup document under an email campaign. */ export const CAMPAIGN_CONVERSIONS_REPORT_DOC = 'conversions';
+/**
+ * The document id for one conversion.
+ *
+ * `{kind}:{refId}`, so the same submission credited twice is the same
+ * document — which is what makes {@link attributeCampaignConversion}'s
+ * `create()` idempotent. Scoped by kind because the ids come from different
+ * collections and a booking id has no reason to be distinct from a form
+ * submission's.
+ */ export function campaignConversionId(kind, refId) {
+    return `${kind}:${refId}`;
+}
+/**
+ * The campaign touch to credit a conversion happening now, or `null`.
+ *
+ * Called ONCE per conversion request, at the door, and the result handed to
+ * every writer beneath it. See the module docblock for the cost argument.
+ *
+ * @returns the winning touch, or `null` when neither channel has one inside
+ *          the window — which is the ordinary case and writes nothing.
+ */ export async function resolveCampaignTouch(options, firestore) {
+    try {
+        var _options_hostId, _options_atMs, _options_email;
+        const hostId = String((_options_hostId = options.hostId) != null ? _options_hostId : '');
+        if (!isDocumentId(hostId)) return null;
+        const convertedAtMs = Number((_options_atMs = options.atMs) != null ? _options_atMs : Date.now());
+        if (!Number.isFinite(convertedAtMs) || convertedAtMs <= 0) return null;
+        // The window is enforced inside the parser, so an expired or
+        // future-dated wire value answers null here exactly as it does in the
+        // browser that decided whether to send it.
+        const web = parseCampaignTouch(options.wire, convertedAtMs);
+        const key = personKey(options.email);
+        /*
+     * The email channel is only askable of somebody who named an address, and
+     * that is the whole reason this join needs the web channel at all. No
+     * address means no keyed read: the ordinary anonymous conversion costs
+     * nothing here.
+     */ const emailTouch = key ? await readEmailCampaignTouch(String((_options_email = options.email) != null ? _options_email : ''), hostId, firestore != null ? firestore : defaultFirestore()) : null;
+        const emailInWindow = emailTouch && isDocumentId(emailTouch.campaignId) && emailTouchIsInWindow(emailTouch.clickedAtMs, convertedAtMs) ? emailTouch : null;
+        /*
+     * LAST TOUCH decides, and a tie goes to email. A tie is only reachable
+     * when the two instants are the same millisecond, and in that case the
+     * email touch is the better evidence: it was recorded by the provider's
+     * own click event on the server, while the web touch is a value the
+     * visitor's device supplied.
+     */ const emailWins = emailInWindow && (!web || emailInWindow.clickedAtMs >= web.atMs);
+        if (emailWins) {
+            return _extends({
+                channel: 'email',
+                campaignId: emailInWindow.campaignId,
+                touchedAtMs: emailInWindow.clickedAtMs
+            }, key ? {
+                personKey: key
+            } : {});
+        }
+        if (!web) return null;
+        return _extends({
+            channel: 'web'
+        }, web.source ? {
+            source: web.source
+        } : {}, web.medium ? {
+            medium: web.medium
+        } : {}, web.campaign ? {
+            campaign: web.campaign
+        } : {}, {
+            touchedAtMs: web.atMs
+        }, key ? {
+            personKey: key
+        } : {});
+    } catch (error) {
+        console.error('resolveCampaignTouch failed', error);
+        return null;
+    }
+}
+/**
+ * Credits one conversion to the campaign the visitor last came from.
+ *
+ * ## Why the record is a document and not a field
+ *
+ * The revenue join's three reasons, and the first is decisive here too.
+ * `create()` fails when the document already exists, which is exact
+ * idempotency for free: a retried form POST, a redelivered booking webhook
+ * and a re-run capture all land here a second time and must all leave the
+ * rollup where they found it. Second, the four kinds live in four different
+ * collections — a contact is org-scoped and shared across every site in the
+ * org — so there is no one document a field could go on. Third, the
+ * submission, the lead and the booking are read by the inbox, the export and
+ * the fulfilment path, and none of them wants a field about marketing.
+ *
+ * ## The rollup exists for the EMAIL channel only
+ *
+ * A campaign document is a real entity with a real id, so its conversions
+ * roll up under it beside the revenue the same join already credits it with.
+ * A web campaign is a LABEL the marketer typed into a URL, with no document,
+ * no id and no bound on how many distinct values exist — the same unbounded
+ * key space the analytics collector caps its per-day label map against. A
+ * rollup keyed on it would be a map anybody who can vary a query string can
+ * grow. So the web channel's records stand on their own and a report reads
+ * them; see the module's report seam note.
+ *
+ * @returns the record written, or `null` when nothing was credited.
+ */ export async function attributeCampaignConversion(options, firestore) {
+    try {
+        var _options_hostId, _options_refId, _options_convertedAtMs;
+        const { touch } = options;
+        if (!touch) return null;
+        const hostId = String((_options_hostId = options.hostId) != null ? _options_hostId : '');
+        const refId = String((_options_refId = options.refId) != null ? _options_refId : '');
+        if (!isDocumentId(hostId) || !isDocumentId(refId)) return null;
+        const convertedAtMs = Number((_options_convertedAtMs = options.convertedAtMs) != null ? _options_convertedAtMs : Date.now());
+        if (!Number.isFinite(convertedAtMs) || convertedAtMs <= 0) return null;
+        // Re-checked at the write rather than trusted from the resolve. The two
+        // are separated by the writes that produced the thing being credited, and
+        // a touch that has aged out between them is a touch outside the window.
+        if (!emailTouchIsInWindow(touch.touchedAtMs, convertedAtMs)) return null;
+        const record = _extends({
+            kind: options.kind,
+            refId,
+            channel: touch.channel
+        }, touch.campaignId ? {
+            campaignId: touch.campaignId
+        } : {}, touch.source ? {
+            source: touch.source
+        } : {}, touch.medium ? {
+            medium: touch.medium
+        } : {}, touch.campaign ? {
+            campaign: touch.campaign
+        } : {}, {
+            touchedAtMs: touch.touchedAtMs,
+            convertedAtMs,
+            model: ATTRIBUTION_MODEL,
+            windowDays: ATTRIBUTION_WINDOW_DAYS
+        }, touch.personKey ? {
+            personKey: touch.personKey
+        } : {});
+        const db = firestore != null ? firestore : defaultFirestore();
+        const hostRef = db.collection('hosts').doc(hostId);
+        /*
+     * `create()`, never `set()` — the revenue join's argument, unchanged. The
+     * ALREADY_EXISTS failure IS the idempotency, and the rollup below is
+     * reached only when the create succeeded, so the two can never disagree
+     * about whether this conversion was counted.
+     */ try {
+            await hostRef.collection(CAMPAIGN_ATTRIBUTIONS_COLLECTION).doc(campaignConversionId(options.kind, refId)).create(_extends({}, record, {
+                createdAt: FieldValue.serverTimestamp()
+            }));
+        } catch (unused) {
+            return null;
+        }
+        if (touch.channel === 'email' && touch.campaignId) {
+            /*
+       * A merge-set that CREATES, for the reason `reports/revenue` gives: this
+       * writes a document UNDER a campaign, so a campaign that no longer
+       * exists gains an orphaned report rather than being resurrected as a
+       * husk in the merchant's history — and the campaign was proven to exist
+       * when its click wrote the touch.
+       *
+       * Every figure is an increment, so two conversions settling at once
+       * both land.
+       */ await hostRef.collection('campaigns').doc(touch.campaignId).collection('reports').doc(CAMPAIGN_CONVERSIONS_REPORT_DOC).set({
+                model: ATTRIBUTION_MODEL,
+                windowDays: ATTRIBUTION_WINDOW_DAYS,
+                byKind: {
+                    [options.kind]: FieldValue.increment(1)
+                },
+                updatedAt: FieldValue.serverTimestamp()
+            }, {
+                merge: true
+            });
+        }
+        return record;
+    } catch (error) {
+        console.error('attributeCampaignConversion failed', error);
+        return null;
+    }
+}
+
+//# sourceMappingURL=campaign-conversion-attribution.js.map

package/src/lib/server/campaign-conversion-attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/campaign-conversion-attribution.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 {\n  parseCampaignTouch,\n  type CampaignTouch,\n} from '@aglyn/aglyn/app-utils/campaign-touch'\n/*\n * Stamped from the REVENUE join's constants, aliased at the import.\n *\n * They are spelled `EMAIL_` because that is where both halves of that join\n * could reach them, not because the window is an email fact — it is the\n * platform's one answer to how long a touch may be credited. Reading them\n * from there is what makes a lead's record and an order's record carry the\n * same rule rather than two that happen to agree.\n */\nimport {\n  EMAIL_ATTRIBUTION_MODEL as ATTRIBUTION_MODEL,\n  EMAIL_ATTRIBUTION_WINDOW_DAYS as ATTRIBUTION_WINDOW_DAYS,\n  emailTouchIsInWindow,\n} from '@aglyn/shared-util-email/email-revenue-window'\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\nimport {\n  CAMPAIGN_ATTRIBUTIONS_COLLECTION,\n  eraseCampaignAttributionsForPersonKey,\n} from './campaign-attribution-store'\nimport { readEmailCampaignTouch } from './email-delivery-log'\nimport { isDocumentId } from './document-id'\nimport firebaseAdmin from './firebase-admin'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\n/**\n * THE IDENTIFY-MOMENT JOIN — a form, a lead, a contact or a booking, credited\n * to the campaign that led to it.\n *\n * ## Why there is a second join at all, and why it is not a second SCHEME\n *\n * `email-revenue-attribution.ts` credits an ORDER by looking the buyer's\n * address up in the touch map a click wrote. That works because an order\n * names its buyer. Every other outcome a campaign causes is produced by\n * somebody who was anonymous until the instant they produced it: they arrive\n * from a campaign link, browse, and only become identifiable when they submit\n * a form, sign up, book or check out. There is no address to look up until\n * the very moment being attributed.\n *\n * So the touch is carried on the VISITOR (`campaign-touch.ts`) and attached\n * here, at each moment they become somebody. What is NOT rebuilt is the\n * model: the same seven-day window, the same last-click rule, the same\n * `model`/`windowDays` stamped onto every record so a report can say what it\n * counted. The email channel is not re-derived either — it is READ from the\n * touch the delivery webhook already wrote, so a campaign email and a\n * campaign ad are two inputs to one comparison rather than two schemes with\n * two answers.\n *\n * ## Last touch, across both channels\n *\n * At the identify moment there can be two candidate touches:\n *\n *  - the WEB touch the visitor's device carried, from an ad, a partner link\n *    or a social post; and\n *  - the EMAIL touch on `emailDeliveries/{personKey}.campaignTouches[hostId]`,\n *    written server-side when they clicked a campaign's mail.\n *\n * Both are window-checked and the LATER one wins. Splitting the outcome\n * between them is the multi-touch model the revenue work rejected for the\n * reason that applies here unchanged: a rule the merchant did not choose\n * produces a figure nobody can check. One outcome, one campaign, and a rule\n * stated on the record.\n *\n * ## No campaign touch means NO RECORD\n *\n * Direct traffic writes nothing at all, and there is deliberately no fallback\n * — no \"most recent campaign on this site\", no referrer inference, no\n * `utm_source=direct`. A conversion nobody can be credited with is a\n * conversion nobody is credited with, and the absence of a record is how the\n * report says so. The cost of a miss is one uncounted outcome; the cost of a\n * guess is a campaign that reads as effective because it was the last one to\n * run.\n *\n * ## Three reads at most, and usually one\n *\n * Resolving a touch costs ONE keyed document read, and only when the visitor\n * gave an address — no query, no index, nothing that can be truncated. A door\n * resolves once per request and hands the result to every writer beneath it,\n * so a form submission that creates a submission, a contact and a lead pays\n * for the lookup once rather than three times.\n *\n * ## Never throws\n *\n * The same contract as the revenue join and for the same reason: the visitor\n * has already done the thing being attributed and the record of it is already\n * written. A lost attribution understates a campaign; a thrown one loses a\n * lead.\n */\n\n/**\n * The collection and the erasure sweep, re-exported so a caller needs one\n * import for the whole join. They are DEFINED in a leaf module because the\n * sweep runs from `email-delivery-log.ts`, which this file reads — see\n * `campaign-attribution-store.ts` for why that cycle is not merely untidy.\n */\nexport {\n  CAMPAIGN_ATTRIBUTIONS_COLLECTION,\n  eraseCampaignAttributionsForPersonKey,\n}\n\n/** The single conversion rollup document under an email campaign. */\nexport const CAMPAIGN_CONVERSIONS_REPORT_DOC = 'conversions'\n\n/**\n * Which identify moment a record credits.\n *\n * Kept apart rather than summed, which is the whole reason the kind is on the\n * record. One form submission by a new person creates a submission, a contact\n * and possibly a lead — three true statements about one visitor action — and\n * a report that added them would treble every campaign's conversions. A\n * reader asks for one kind at a time, exactly as the revenue rollup buckets\n * by currency and never totals across them.\n */\nexport type CampaignConversionKind = 'form' | 'lead' | 'contact' | 'booking'\n\n/** Which channel the credited touch arrived through. */\nexport type CampaignTouchChannel = 'email' | 'web'\n\n/** The touch a conversion is credited to, once both channels have been asked. */\nexport interface ResolvedCampaignTouch {\n  channel: CampaignTouchChannel\n  /** The campaign document, when the touch was a click on our own mail. */\n  campaignId?: string\n  /** `utm_source`, when the touch was a link on the web. */\n  source?: string\n  /** `utm_medium`, when the touch was a link on the web. */\n  medium?: string\n  /** `utm_campaign`, when the touch was a link on the web. */\n  campaign?: string\n  /** When the visitor followed the campaign link, epoch ms. */\n  touchedAtMs: number\n  /**\n   * `sha256` of the normalized address the touch was resolved against, when\n   * the visitor gave one. The handle an erasure erases by — see\n   * {@link eraseCampaignAttributionsForPersonKey}.\n   */\n  personKey?: string\n}\n\n/** What one conversion attribution record holds. */\nexport interface CampaignConversionRecord extends ResolvedCampaignTouch {\n  kind: CampaignConversionKind\n  /** The submission, lead, contact or booking this credits. */\n  refId: string\n  /** When the visitor became identifiable. */\n  convertedAtMs: number\n  /** The model this credit was decided under. */\n  model: string\n  /** The window, in days, it was decided inside. */\n  windowDays: number\n}\n\n/**\n * The document id for one conversion.\n *\n * `{kind}:{refId}`, so the same submission credited twice is the same\n * document — which is what makes {@link attributeCampaignConversion}'s\n * `create()` idempotent. Scoped by kind because the ids come from different\n * collections and a booking id has no reason to be distinct from a form\n * submission's.\n */\nexport function campaignConversionId(\n  kind: CampaignConversionKind,\n  refId: string,\n): string {\n  return `${kind}:${refId}`\n}\n\n/**\n * The campaign touch to credit a conversion happening now, or `null`.\n *\n * Called ONCE per conversion request, at the door, and the result handed to\n * every writer beneath it. See the module docblock for the cost argument.\n *\n * @returns the winning touch, or `null` when neither channel has one inside\n *          the window — which is the ordinary case and writes nothing.\n */\nexport async function resolveCampaignTouch(\n  options: {\n    hostId: string\n    /**\n     * The wire form the conversion request carried, when the door reports\n     * one. Re-parsed through the allowlist that wrote it rather than trusted:\n     * it arrives from the visitor's browser, so it may claim no more than an\n     * inbound URL could.\n     */\n    wire?: unknown\n    /** The address the visitor identified with, raw. */\n    email?: unknown\n    /** When they identified themselves. Defaults to now. */\n    atMs?: number\n  },\n  firestore?: any,\n): Promise<ResolvedCampaignTouch | null> {\n  try {\n    const hostId = String(options.hostId ?? '')\n    if (!isDocumentId(hostId)) return null\n    const convertedAtMs = Number(options.atMs ?? Date.now())\n    if (!Number.isFinite(convertedAtMs) || convertedAtMs <= 0) return null\n\n    // The window is enforced inside the parser, so an expired or\n    // future-dated wire value answers null here exactly as it does in the\n    // browser that decided whether to send it.\n    const web: CampaignTouch | null = parseCampaignTouch(\n      options.wire,\n      convertedAtMs,\n    )\n\n    const key = personKey(options.email)\n    /*\n     * The email channel is only askable of somebody who named an address, and\n     * that is the whole reason this join needs the web channel at all. No\n     * address means no keyed read: the ordinary anonymous conversion costs\n     * nothing here.\n     */\n    const emailTouch = key\n      ? await readEmailCampaignTouch(\n          String(options.email ?? ''),\n          hostId,\n          firestore ?? defaultFirestore(),\n        )\n      : null\n    const emailInWindow =\n      emailTouch &&\n      isDocumentId(emailTouch.campaignId) &&\n      emailTouchIsInWindow(emailTouch.clickedAtMs, convertedAtMs)\n        ? emailTouch\n        : null\n\n    /*\n     * LAST TOUCH decides, and a tie goes to email. A tie is only reachable\n     * when the two instants are the same millisecond, and in that case the\n     * email touch is the better evidence: it was recorded by the provider's\n     * own click event on the server, while the web touch is a value the\n     * visitor's device supplied.\n     */\n    const emailWins =\n      emailInWindow && (!web || emailInWindow.clickedAtMs >= web.atMs)\n    if (emailWins) {\n      return {\n        channel: 'email',\n        campaignId: emailInWindow.campaignId,\n        touchedAtMs: emailInWindow.clickedAtMs,\n        ...(key ? { personKey: key } : {}),\n      }\n    }\n    if (!web) return null\n    return {\n      channel: 'web',\n      ...(web.source ? { source: web.source } : {}),\n      ...(web.medium ? { medium: web.medium } : {}),\n      ...(web.campaign ? { campaign: web.campaign } : {}),\n      touchedAtMs: web.atMs,\n      ...(key ? { personKey: key } : {}),\n    }\n  } catch (error) {\n    console.error('resolveCampaignTouch failed', error)\n    return null\n  }\n}\n\n/**\n * Credits one conversion to the campaign the visitor last came from.\n *\n * ## Why the record is a document and not a field\n *\n * The revenue join's three reasons, and the first is decisive here too.\n * `create()` fails when the document already exists, which is exact\n * idempotency for free: a retried form POST, a redelivered booking webhook\n * and a re-run capture all land here a second time and must all leave the\n * rollup where they found it. Second, the four kinds live in four different\n * collections — a contact is org-scoped and shared across every site in the\n * org — so there is no one document a field could go on. Third, the\n * submission, the lead and the booking are read by the inbox, the export and\n * the fulfilment path, and none of them wants a field about marketing.\n *\n * ## The rollup exists for the EMAIL channel only\n *\n * A campaign document is a real entity with a real id, so its conversions\n * roll up under it beside the revenue the same join already credits it with.\n * A web campaign is a LABEL the marketer typed into a URL, with no document,\n * no id and no bound on how many distinct values exist — the same unbounded\n * key space the analytics collector caps its per-day label map against. A\n * rollup keyed on it would be a map anybody who can vary a query string can\n * grow. So the web channel's records stand on their own and a report reads\n * them; see the module's report seam note.\n *\n * @returns the record written, or `null` when nothing was credited.\n */\nexport async function attributeCampaignConversion(\n  options: {\n    hostId: string\n    kind: CampaignConversionKind\n    /** The submission, lead, contact or booking being credited. */\n    refId: string\n    /** The touch {@link resolveCampaignTouch} picked, or `null` for direct. */\n    touch: ResolvedCampaignTouch | null | undefined\n    /** When the visitor became identifiable. Defaults to now. */\n    convertedAtMs?: number\n  },\n  firestore?: any,\n): Promise<CampaignConversionRecord | null> {\n  try {\n    const { touch } = options\n    if (!touch) return null\n    const hostId = String(options.hostId ?? '')\n    const refId = String(options.refId ?? '')\n    if (!isDocumentId(hostId) || !isDocumentId(refId)) return null\n    const convertedAtMs = Number(options.convertedAtMs ?? Date.now())\n    if (!Number.isFinite(convertedAtMs) || convertedAtMs <= 0) return null\n    // Re-checked at the write rather than trusted from the resolve. The two\n    // are separated by the writes that produced the thing being credited, and\n    // a touch that has aged out between them is a touch outside the window.\n    if (!emailTouchIsInWindow(touch.touchedAtMs, convertedAtMs)) return null\n\n    const record: CampaignConversionRecord = {\n      kind: options.kind,\n      refId,\n      channel: touch.channel,\n      ...(touch.campaignId ? { campaignId: touch.campaignId } : {}),\n      ...(touch.source ? { source: touch.source } : {}),\n      ...(touch.medium ? { medium: touch.medium } : {}),\n      ...(touch.campaign ? { campaign: touch.campaign } : {}),\n      touchedAtMs: touch.touchedAtMs,\n      convertedAtMs,\n      model: ATTRIBUTION_MODEL,\n      windowDays: ATTRIBUTION_WINDOW_DAYS,\n      ...(touch.personKey ? { personKey: touch.personKey } : {}),\n    }\n\n    const db = firestore ?? defaultFirestore()\n    const hostRef = db.collection('hosts').doc(hostId)\n    /*\n     * `create()`, never `set()` — the revenue join's argument, unchanged. The\n     * ALREADY_EXISTS failure IS the idempotency, and the rollup below is\n     * reached only when the create succeeded, so the two can never disagree\n     * about whether this conversion was counted.\n     */\n    try {\n      await hostRef\n        .collection(CAMPAIGN_ATTRIBUTIONS_COLLECTION)\n        .doc(campaignConversionId(options.kind, refId))\n        .create({ ...record, createdAt: FieldValue.serverTimestamp() })\n    } catch {\n      return null\n    }\n\n    if (touch.channel === 'email' && touch.campaignId) {\n      /*\n       * A merge-set that CREATES, for the reason `reports/revenue` gives: this\n       * writes a document UNDER a campaign, so a campaign that no longer\n       * exists gains an orphaned report rather than being resurrected as a\n       * husk in the merchant's history — and the campaign was proven to exist\n       * when its click wrote the touch.\n       *\n       * Every figure is an increment, so two conversions settling at once\n       * both land.\n       */\n      await hostRef\n        .collection('campaigns')\n        .doc(touch.campaignId)\n        .collection('reports')\n        .doc(CAMPAIGN_CONVERSIONS_REPORT_DOC)\n        .set(\n          {\n            model: ATTRIBUTION_MODEL,\n            windowDays: ATTRIBUTION_WINDOW_DAYS,\n            byKind: { [options.kind]: FieldValue.increment(1) },\n            updatedAt: FieldValue.serverTimestamp(),\n          },\n          { merge: true },\n        )\n    }\n\n    return record\n  } catch (error) {\n    console.error('attributeCampaignConversion failed', error)\n    return null\n  }\n}\n"],"names":["FieldValue","parseCampaignTouch","EMAIL_ATTRIBUTION_MODEL","ATTRIBUTION_MODEL","EMAIL_ATTRIBUTION_WINDOW_DAYS","ATTRIBUTION_WINDOW_DAYS","emailTouchIsInWindow","personKey","CAMPAIGN_ATTRIBUTIONS_COLLECTION","eraseCampaignAttributionsForPersonKey","readEmailCampaignTouch","isDocumentId","firebaseAdmin","defaultFirestore","app","firestore","CAMPAIGN_CONVERSIONS_REPORT_DOC","campaignConversionId","kind","refId","resolveCampaignTouch","options","hostId","String","convertedAtMs","Number","atMs","Date","now","isFinite","web","wire","key","email","emailTouch","emailInWindow","campaignId","clickedAtMs","emailWins","channel","touchedAtMs","source","medium","campaign","error","console","attributeCampaignConversion","touch","record","model","windowDays","db","hostRef","collection","doc","create","createdAt","serverTimestamp","set","byKind","increment","updatedAt","merge"],"mappings":"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"}