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

package/src/lib/model/campaign-visits.js

@@ -0,0 +1,65 @@
+/**
+ * @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.
+ */ /**
+ * WHO A CAMPAIGN REACHED ON THE SITE (AGL-3461) — first visits and views of
+ * the pages filed under it.
+ *
+ * ## One document per campaign, keyed by the campaign's id
+ *
+ * `orgs/{orgId}/campaignVisitReports/{campaignId}`, beside the sequence
+ * rollup and on the same footing: counts, never a person, written only on the
+ * Admin SDK by the site collector's `campaignVisit` beacon, readable by
+ * whoever may open the campaign. Keyed by the campaign DOCUMENT, so the
+ * collection is bounded by the campaigns that exist — never by a label or a
+ * path a visitor's URL could mint.
+ *
+ * ## What each figure counts
+ *
+ *  - **Page views** — views of the pages filed under the campaign, one per
+ *    pageview, whoever the visitor is. It needs nothing from the visitor's
+ *    device, so every view counts.
+ *  - **First visits** — visitors whose first campaign touch in the
+ *    attribution window was this campaign: a page filed under it, or a link
+ *    carrying a `utm_campaign` label it declares. The device answers from the
+ *    touch it already remembers (`claimFirstCampaignTouch` in
+ *    `utm-touch.ts`): one held from the last seven days means this visit is
+ *    not a first. A visitor whose consent posture keeps nothing on their
+ *    device cannot be told from the next one and is not counted at all, so
+ *    the figure is a floor, and the page says so.
+ *
+ * Both are also kept per month, under `byMonth`, so a campaign with dates can
+ * be read for its own window. Twelve keys a year is the bound.
+ */ /** The org collection the rollups live in. */ export const CAMPAIGN_VISIT_REPORTS_COLLECTION = 'campaignVisitReports';
+function count(raw) {
+    const value = Math.floor(Number(raw != null ? raw : 0));
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * The rollup as the page reads it. `since` is the earliest month on record,
+ * so the figures say how far back they reach: they start when counting
+ * started, not when the campaign did.
+ */ export function campaignVisitsReport(rollup) {
+    var _ref, _months_;
+    const months = Object.keys((_ref = rollup == null ? void 0 : rollup.byMonth) != null ? _ref : {}).filter((month)=>/^\d{4}-\d{2}$/.test(month)).sort();
+    return {
+        recorded: Boolean(rollup),
+        views: count(rollup == null ? void 0 : rollup.views),
+        firstVisits: count(rollup == null ? void 0 : rollup.firstVisits),
+        since: (_months_ = months[0]) != null ? _months_ : ''
+    };
+}
+
+//# sourceMappingURL=campaign-visits.js.map

package/src/lib/model/campaign-visits.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/campaign-visits.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\n/**\n * WHO A CAMPAIGN REACHED ON THE SITE (AGL-3461) — first visits and views of\n * the pages filed under it.\n *\n * ## One document per campaign, keyed by the campaign's id\n *\n * `orgs/{orgId}/campaignVisitReports/{campaignId}`, beside the sequence\n * rollup and on the same footing: counts, never a person, written only on the\n * Admin SDK by the site collector's `campaignVisit` beacon, readable by\n * whoever may open the campaign. Keyed by the campaign DOCUMENT, so the\n * collection is bounded by the campaigns that exist — never by a label or a\n * path a visitor's URL could mint.\n *\n * ## What each figure counts\n *\n *  - **Page views** — views of the pages filed under the campaign, one per\n *    pageview, whoever the visitor is. It needs nothing from the visitor's\n *    device, so every view counts.\n *  - **First visits** — visitors whose first campaign touch in the\n *    attribution window was this campaign: a page filed under it, or a link\n *    carrying a `utm_campaign` label it declares. The device answers from the\n *    touch it already remembers (`claimFirstCampaignTouch` in\n *    `utm-touch.ts`): one held from the last seven days means this visit is\n *    not a first. A visitor whose consent posture keeps nothing on their\n *    device cannot be told from the next one and is not counted at all, so\n *    the figure is a floor, and the page says so.\n *\n * Both are also kept per month, under `byMonth`, so a campaign with dates can\n * be read for its own window. Twelve keys a year is the bound.\n */\n\n/** The org collection the rollups live in. */\nexport const CAMPAIGN_VISIT_REPORTS_COLLECTION = 'campaignVisitReports'\n\n/** One month's figures, under `byMonth['YYYY-MM']`. */\nexport interface CampaignVisitMonth {\n  views?: number\n  firstVisits?: number\n}\n\n/** The stored shape of `orgs/{orgId}/campaignVisitReports/{campaignId}`. */\nexport interface CampaignVisitRollup {\n  views?: number\n  firstVisits?: number\n  byMonth?: Record<string, CampaignVisitMonth>\n}\n\n/** What the campaign's page draws. */\nexport interface CampaignVisitsReport {\n  /** Whether anything has been counted at all. */\n  recorded: boolean\n  views: number\n  firstVisits: number\n  /** The first month anything was counted, `YYYY-MM`, or `''`. */\n  since: string\n}\n\nfunction count(raw: unknown): number {\n  const value = Math.floor(Number(raw ?? 0))\n  return Number.isFinite(value) && value > 0 ? value : 0\n}\n\n/**\n * The rollup as the page reads it. `since` is the earliest month on record,\n * so the figures say how far back they reach: they start when counting\n * started, not when the campaign did.\n */\nexport function campaignVisitsReport(\n  rollup: CampaignVisitRollup | null | undefined,\n): CampaignVisitsReport {\n  const months = Object.keys(rollup?.byMonth ?? {})\n    .filter((month) => /^\\d{4}-\\d{2}$/.test(month))\n    .sort()\n  return {\n    recorded: Boolean(rollup),\n    views: count(rollup?.views),\n    firstVisits: count(rollup?.firstVisits),\n    since: months[0] ?? '',\n  }\n}\n"],"names":["CAMPAIGN_VISIT_REPORTS_COLLECTION","count","raw","value","Math","floor","Number","isFinite","campaignVisitsReport","rollup","months","Object","keys","byMonth","filter","month","test","sort","recorded","Boolean","views","firstVisits","since"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GAED,4CAA4C,GAC5C,OAAO,MAAMA,oCAAoC,uBAAsB;AAyBvE,SAASC,MAAMC,GAAY;IACzB,MAAMC,QAAQC,KAAKC,KAAK,CAACC,OAAOJ,cAAAA,MAAO;IACvC,OAAOI,OAAOC,QAAQ,CAACJ,UAAUA,QAAQ,IAAIA,QAAQ;AACvD;AAEA;;;;CAIC,GACD,OAAO,SAASK,qBACdC,MAA8C;cASrCC;IAPT,MAAMA,SAASC,OAAOC,IAAI,SAACH,0BAAAA,OAAQI,OAAO,mBAAI,CAAC,GAC5CC,MAAM,CAAC,CAACC,QAAU,gBAAgBC,IAAI,CAACD,QACvCE,IAAI;IACP,OAAO;QACLC,UAAUC,QAAQV;QAClBW,OAAOnB,MAAMQ,0BAAAA,OAAQW,KAAK;QAC1BC,aAAapB,MAAMQ,0BAAAA,OAAQY,WAAW;QACtCC,KAAK,GAAEZ,WAAAA,MAAM,CAAC,EAAE,YAATA,WAAa;IACtB;AACF"}

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

@@ -55,6 +55,17 @@ import { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey
  * produces a figure nobody can check. One outcome, one campaign, and a rule
  * stated on the record.
  *
+ * ## And a page filed under a campaign (AGL-3461)
+ *
+ * A third touch needs no label and no click: the visitor viewed a page the
+ * merchant filed under a campaign. The device carries it beside the labels
+ * (`utm-touch.ts`), the server credits it only while the campaign exists and
+ * the page is still filed under it (`campaign-touch-targets.ts`), and it
+ * competes with the winning click under {@link pickCampaignTouch}. A label a
+ * campaign declares as its own (`utmCampaigns` on the container) names that
+ * campaign the same way. Both are recorded with the CONTAINER's id as
+ * `campaignId`, under the `last-touch` model.
+ *
  * ## No campaign touch means NO RECORD
  *
  * Direct traffic writes nothing at all, and there is deliberately no fallback
@@ -110,16 +121,21 @@ export type CampaignConversionKind = 'form' | 'lead' | 'contact' | 'booking';
  * every other booking, and nothing in this join has to know what a
  * sequence is.
  */
-export type CampaignTouchChannel = 'email' | 'web' | 'sequence';
-/** The touch a conversion is credited to, once both channels have been asked. */
+export type CampaignTouchChannel = 'email' | 'web' | 'sequence' | 'page';
+/** The touch a conversion is credited to, once every channel has been asked. */
 export interface ResolvedCampaignTouch {
     channel: CampaignTouchChannel;
     /**
      * The campaign document, when the touch was a click on our own mail — or
      * the campaign CONTAINER (`emailCampaigns/{id}`) a sequence is in, for a
-     * sequence touch.
+     * sequence touch, the page was filed under, for a page touch, or that
+     * declares the label, for a web touch whose label one does (AGL-3461).
      */
     campaignId?: string;
+    /** The screen the visitor viewed, for a `page` touch. */
+    screenId?: string;
+    /** That page's path, for a `page` touch. */
+    path?: string;
     /** The sequence the touch came through, for a `sequence` touch. */
     sequenceId?: string;
     /** The enrollment the touch came through, for a `sequence` touch. */
@@ -184,6 +200,21 @@ export declare function resolveCampaignTouch(options: {
     /** When they identified themselves. Defaults to now. */
     atMs?: number;
 }, firestore?: any): Promise<ResolvedCampaignTouch | null>;
+/**
+ * THE RULE, between a click and a page (AGL-3461) — `CAMPAIGN_TOUCH_MODEL`
+ * says it in words.
+ *
+ * Within one visit a click that names a campaign keeps the credit for the
+ * page it landed on: the visitor clicked a campaign's mail or a link labeled
+ * for a campaign and READ the page because of it, and handing the credit to
+ * the page would take every landing page's conversions away from the email
+ * that sent the reader there. A bare label yields to the page, because the
+ * page names a campaign and the label names nothing anybody can open.
+ *
+ * Further apart, the later wins, which is the last-touch rule every other
+ * pair already follows.
+ */
+export declare function pickCampaignTouch(click: ResolvedCampaignTouch | null, page: ResolvedCampaignTouch | null): ResolvedCampaignTouch | null;
 /**
  * Credits one conversion to the campaign the visitor last came from.
  *

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

@@ -15,7 +15,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ import { FieldValue } from "firebase-admin/firestore";
-import { parseUtmTouch } from "@aglyn/aglyn/app-utils/utm-touch";
+import { parsePageTouch, parseUtmTouch } from "@aglyn/aglyn/app-utils/utm-touch";
 /*
  * Stamped from the REVENUE join's constants, aliased at the import.
  *
@@ -24,13 +24,19 @@ import { parseUtmTouch } from "@aglyn/aglyn/app-utils/utm-touch";
  * 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 { EMAIL_ATTRIBUTION_WINDOW_DAYS as ATTRIBUTION_WINDOW_DAYS, emailTouchIsInWindow } from "@aglyn/shared-util-email/email-revenue-window";
+/*
+ * The identify moment's own rule (AGL-3461): a page filed under a campaign is
+ * a touch here, and it is not a click, so these records say `last-touch` where
+ * an order's say `last-click`. The window above is still the one both share.
+ */ import { CAMPAIGN_TOUCH_MODEL as ATTRIBUTION_MODEL, CAMPAIGN_VISIT_MS } from "../model/campaign-conversions.js";
 import { personKey } from "@aglyn/aglyn/app-utils/person-key";
 import { CAMPAIGN_ATTRIBUTIONS_COLLECTION, eraseCampaignAttributionsForPersonKey } from "./campaign-attribution-store.js";
 import { isDocumentId } from "@aglyn/tenant-data-admin/server/document-id";
 import firebaseAdmin from "@aglyn/tenant-data-admin/server/firebase-admin";
 import { resolveOrgIdForHost } from "@aglyn/tenant-data-admin/server/organizations";
 import { readEmailCampaignTouch } from "./email-campaign-touch.js";
+import { campaignForUtmLabel, filedCampaignForPage } from "./campaign-touch-targets.js";
 const defaultFirestore = ()=>firebaseAdmin.app().firestore();
 /**
  * THE IDENTIFY-MOMENT JOIN — a form, a lead, a contact or a booking, credited
@@ -71,6 +77,17 @@ const defaultFirestore = ()=>firebaseAdmin.app().firestore();
  * produces a figure nobody can check. One outcome, one campaign, and a rule
  * stated on the record.
  *
+ * ## And a page filed under a campaign (AGL-3461)
+ *
+ * A third touch needs no label and no click: the visitor viewed a page the
+ * merchant filed under a campaign. The device carries it beside the labels
+ * (`utm-touch.ts`), the server credits it only while the campaign exists and
+ * the page is still filed under it (`campaign-touch-targets.ts`), and it
+ * competes with the winning click under {@link pickCampaignTouch}. A label a
+ * campaign declares as its own (`utmCampaigns` on the container) names that
+ * campaign the same way. Both are recorded with the CONTAINER's id as
+ * `campaignId`, under the `last-touch` model.
+ *
  * ## No campaign touch means NO RECORD
  *
  * Direct traffic writes nothing at all, and there is deliberately no fallback
@@ -127,28 +144,45 @@ const defaultFirestore = ()=>firebaseAdmin.app().firestore();
         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 = parseUtmTouch(options.wire, convertedAtMs);
+        const db = firestore != null ? firestore : defaultFirestore();
+        /*
+     * The window is enforced inside the parsers, so an expired wire value
+     * answers null here exactly as it does in the browser that decided
+     * whether to send it.
+     *
+     * Both instants on the wire are the VISITOR'S clock, and a device running
+     * a few minutes fast would date the page it is reading after the
+     * conversion the server is recording — refused as "a touch after the
+     * conversion", which is the receipt rule, not a clock rule. So the parse
+     * allows {@link CLIENT_CLOCK_SKEW_MS} of future and clamps it to the
+     * conversion; the write re-checks the window against the server's own
+     * instant either way.
+     */ const web = clampToConversion(parseUtmTouch(options.wire, convertedAtMs + CLIENT_CLOCK_SKEW_MS), convertedAtMs);
+        const page = clampToConversion(parsePageTouch(options.wire, convertedAtMs + CLIENT_CLOCK_SKEW_MS), 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 emailTouch = key ? await readEmailCampaignTouch(String((_options_email = options.email) != null ? _options_email : ''), hostId, db) : 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.
+     * The org owns the campaigns a page or a label can name. Asked only when
+     * the visitor carried one of those, so the ordinary conversion pays
+     * nothing for it — and the lookup is request-cached besides.
+     */ const orgId = page || (web == null ? void 0 : web.campaign) ? await resolveOrgIdForHost(hostId).catch(()=>null) : null;
+        /*
+     * A CLICK first — the later of the campaign email and the labeled link,
+     * 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);
+        let click = null;
         if (emailWins) {
             const viaSequence = emailInWindow.sequenceId && emailInWindow.enrollmentId;
-            return _extends({
+            click = _extends({
                 channel: viaSequence ? 'sequence' : 'email',
                 campaignId: emailInWindow.campaignId
             }, viaSequence ? {
@@ -159,26 +193,90 @@ const defaultFirestore = ()=>firebaseAdmin.app().firestore();
             }, key ? {
                 personKey: key
             } : {});
+        } else if (web) {
+            // A label a campaign declares names that campaign (AGL-3461); any other
+            // label stays the text it is.
+            const declared = orgId && web.campaign ? await campaignForUtmLabel({
+                orgId,
+                hostId,
+                label: web.campaign
+            }, db) : null;
+            click = _extends({
+                channel: 'web'
+            }, declared ? {
+                campaignId: declared.id
+            } : {}, web.source ? {
+                source: web.source
+            } : {}, web.medium ? {
+                medium: web.medium
+            } : {}, web.campaign ? {
+                campaign: web.campaign
+            } : {}, {
+                touchedAtMs: web.atMs
+            }, 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
+        /*
+     * THEN THE PAGE (AGL-3461), checked against what is stored: the campaign
+     * still exists and the page is still filed under it. Read only when there
+     * is one — and never when the click it would compete with is in the same
+     * visit and names a campaign, because that click wins without it.
+     */ const pageCouldWin = page && orgId && !((click == null ? void 0 : click.campaignId) && Math.abs(page.atMs - click.touchedAtMs) <= CAMPAIGN_VISIT_MS);
+        const filed = pageCouldWin ? await filedCampaignForPage({
+            orgId,
+            hostId,
+            screenId: page.screenId,
+            campaignIds: page.containerIds
+        }, db) : null;
+        const pageTouch = page && filed ? _extends({
+            channel: 'page',
+            campaignId: filed.id,
+            screenId: page.screenId
+        }, page.path ? {
+            path: page.path
         } : {}, {
-            touchedAtMs: web.atMs
+            touchedAtMs: page.atMs
         }, key ? {
             personKey: key
-        } : {});
+        } : {}) : null;
+        return pickCampaignTouch(click, pageTouch);
     } catch (error) {
         console.error('resolveCampaignTouch failed', error);
         return null;
     }
 }
+/**
+ * How far ahead of the server a visitor's clock may run before the touch it
+ * dates is refused as after the conversion.
+ */ const CLIENT_CLOCK_SKEW_MS = 5 * 60 * 1000;
+/** A parsed touch with an instant no later than the conversion. */ function clampToConversion(touch, convertedAtMs) {
+    if (!touch) return null;
+    return touch.atMs > convertedAtMs ? _extends({}, touch, {
+        atMs: convertedAtMs
+    }) : touch;
+}
+/**
+ * THE RULE, between a click and a page (AGL-3461) — `CAMPAIGN_TOUCH_MODEL`
+ * says it in words.
+ *
+ * Within one visit a click that names a campaign keeps the credit for the
+ * page it landed on: the visitor clicked a campaign's mail or a link labeled
+ * for a campaign and READ the page because of it, and handing the credit to
+ * the page would take every landing page's conversions away from the email
+ * that sent the reader there. A bare label yields to the page, because the
+ * page names a campaign and the label names nothing anybody can open.
+ *
+ * Further apart, the later wins, which is the last-touch rule every other
+ * pair already follows.
+ */ export function pickCampaignTouch(click, page) {
+    if (!page) return click;
+    if (!click) return page;
+    if (Math.abs(page.touchedAtMs - click.touchedAtMs) <= CAMPAIGN_VISIT_MS) {
+        return click.campaignId ? click : page;
+    }
+    return page.touchedAtMs > click.touchedAtMs ? page : click;
+}
 /**
  * Credits one conversion to the campaign the visitor last came from.
  *
@@ -236,6 +334,10 @@ const defaultFirestore = ()=>firebaseAdmin.app().firestore();
             medium: touch.medium
         } : {}, touch.campaign ? {
             campaign: touch.campaign
+        } : {}, touch.screenId ? {
+            screenId: touch.screenId
+        } : {}, touch.path ? {
+            path: touch.path
         } : {}, {
             touchedAtMs: touch.touchedAtMs,
             convertedAtMs,

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/marketing/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, type DocumentReference, type Firestore } from 'firebase-admin/firestore'\nimport {\n  parseUtmTouch,\n  type UtmTouch,\n} from '@aglyn/aglyn/app-utils/utm-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 { isDocumentId } from '@aglyn/tenant-data-admin/server/document-id'\nimport firebaseAdmin from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations'\nimport { readEmailCampaignTouch } from './email-campaign-touch'\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 (`utm-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 *    (`email-campaign-touch.ts`), written server-side when they clicked a\n *    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 — see\n * `campaign-attribution-store.ts` for why.\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/**\n * Which channel the credited touch arrived through.\n *\n * `sequence` (AGL-3254) is a click on, or the sending of, a one-to-one\n * email a rep's sequence sent. It is read off the same touch map as the\n * email channel — the Outreach click route stamps it there with the\n * sequence and the enrollment beside the campaign the sequence is in — so\n * a booking made from a sequence link is credited by the door that credits\n * every other booking, and nothing in this join has to know what a\n * sequence is.\n */\nexport type CampaignTouchChannel = 'email' | 'web' | 'sequence'\n\n/** The touch a conversion is credited to, once both channels have been asked. */\nexport interface ResolvedCampaignTouch {\n  channel: CampaignTouchChannel\n  /**\n   * The campaign document, when the touch was a click on our own mail — or\n   * the campaign CONTAINER (`emailCampaigns/{id}`) a sequence is in, for a\n   * sequence touch.\n   */\n  campaignId?: string\n  /** The sequence the touch came through, for a `sequence` touch. */\n  sequenceId?: string\n  /** The enrollment the touch came through, for a `sequence` touch. */\n  enrollmentId?: 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: UtmTouch | null = parseUtmTouch(\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      const viaSequence = emailInWindow.sequenceId && emailInWindow.enrollmentId\n      return {\n        channel: viaSequence ? 'sequence' : 'email',\n        campaignId: emailInWindow.campaignId,\n        ...(viaSequence\n          ? { sequenceId: emailInWindow.sequenceId, enrollmentId: emailInWindow.enrollmentId }\n          : {}),\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.sequenceId ? { sequenceId: touch.sequenceId } : {}),\n      ...(touch.enrollmentId ? { enrollmentId: touch.enrollmentId } : {}),\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    /*\n     * The send the touch names (`touch.campaignId` is a SEND id on the email\n     * channel), wherever it is: the org's `campaigns` collection, or the\n     * site's for a send the migration has not reached. A send in neither\n     * place was discarded, and its rollup is skipped — the record above\n     * already says what was credited.\n     */\n    const sendRef =\n      touch.channel === 'email' && touch.campaignId && isDocumentId(touch.campaignId)\n        ? await resolveCampaignSendRef({ hostId, sendId: touch.campaignId, firestore: db })\n        : null\n    if (sendRef) {\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 sendRef\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    /*\n     * A SEQUENCE touch rolls up under the campaign's sequences report, and\n     * only a booking does: \"meetings booked from a sequence link\" is the one\n     * identify moment a sequence's own outcomes do not already count. The\n     * form, lead and contact kinds stand as records — visible on the record\n     * they credit and on the site's conversions list — and never in\n     * `byKind`, whose caveat promises the reader campaign emails only.\n     */\n    if (touch.channel === 'sequence' && touch.campaignId && options.kind === 'booking') {\n      await creditCampaignSequenceOutcome(\n        { hostId, campaignIds: [touch.campaignId], outcome: 'meetings', atMs: convertedAtMs },\n        db,\n      )\n    }\n\n    return record\n  } catch (error) {\n    console.error('attributeCampaignConversion failed', error)\n    return null\n  }\n}\n\n/*==========================================\n * WHAT A CAMPAIGN'S SEQUENCES PRODUCED (AGL-3254).\n *\n * A sequence joins a campaign the way a form does, and the Outreach runtime\n * credits what each enrollment produced — enrolled, first email sent, a\n * reply, a meeting booked from a sequence link, an enrolled lead converted\n * — to every campaign the sequence was in when the person was enrolled. The\n * counts live in `orgs/{orgId}/campaignSequenceReports/{campaignId}`, beside\n * the org's containers: one document per campaign, server-only like every\n * other report here, and never inside the campaign container, which the\n * history list reads.\n *\n * Idempotency is the CALLER's: a plugin credits an outcome once per\n * enrollment from a state change that happens once — the enrollment is\n * created once, its first email is the first, its status moves to replied\n * once, its lead converts once — so this writer is a plain increment and\n * keeps no per-enrollment record of its own.\n *=========================================*/\n\n/**\n * The per-org collection of sequence rollups. Restated from the reader\n * (`model/campaign-report.ts`) and asserted equal by\n * the reader's spec.\n */\nexport const CAMPAIGN_SEQUENCE_REPORTS_COLLECTION = 'campaignSequenceReports'\n\n/** The outcomes the runtime credits, in funnel order. */\nexport const CAMPAIGN_SEQUENCE_OUTCOMES = [\n  'enrolled',\n  'sent',\n  'replied',\n  'meetings',\n  'converted',\n] as const\n\nexport type CampaignSequenceOutcome = (typeof CAMPAIGN_SEQUENCE_OUTCOMES)[number]\n\n/**\n * Credits one outcome, for one enrollment, to every campaign named.\n *\n * Never throws, and never refuses the batch for one bad id: the outcome\n * has already happened, and a campaign that is gone gains an orphaned\n * report rather than blocking the credit to one that is not — the\n * conversions rollup's own argument for a merge-set that creates.\n *\n * @returns how many campaigns were credited.\n */\nexport async function creditCampaignSequenceOutcome(\n  options: {\n    /** The site the enrollment emails for; resolves the org when none is given. */\n    hostId: string\n    /**\n     * The org whose containers the campaigns are, when the caller holds it —\n     * an enrollment is an org document, so its routes do. Saves the\n     * `hostIndex` read.\n     */\n    orgId?: string | null\n    /** The campaigns the enrollment carries; unusable ids are skipped. */\n    campaignIds: readonly string[]\n    outcome: CampaignSequenceOutcome\n    /** When the outcome happened. Defaults to now. */\n    atMs?: number\n  },\n  firestore?: any,\n): Promise<number> {\n  try {\n    if (!(CAMPAIGN_SEQUENCE_OUTCOMES as readonly string[]).includes(options.outcome)) return 0\n    const atMs = Number(options.atMs ?? Date.now())\n    const ids = [...new Set(options.campaignIds.map((id) => String(id ?? '').trim()))].filter(\n      (id) => isDocumentId(id),\n    )\n    if (!ids.length) return 0\n    const hostId = String(options.hostId ?? '')\n    const given = String(options.orgId ?? '')\n    const orgId = isDocumentId(given)\n      ? given\n      : isDocumentId(hostId)\n        ? await resolveOrgIdForHost(hostId)\n        : null\n    if (!orgId || !isDocumentId(orgId)) return 0\n    const db = firestore ?? defaultFirestore()\n    await Promise.all(\n      ids.map((campaignId) =>\n        orgCampaignSequenceReportRef(orgId, campaignId, db).set(\n          {\n            byOutcome: { [options.outcome]: FieldValue.increment(1) },\n            ...(Number.isFinite(atMs) && atMs > 0 ? { updatedAtMs: atMs } : {}),\n            updatedAt: FieldValue.serverTimestamp(),\n          },\n          { merge: true },\n        ),\n      ),\n    )\n    return ids.length\n  } catch (error) {\n    console.error('creditCampaignSequenceOutcome failed', error)\n    return 0\n  }\n}\n\n/*==========================================\n * WHERE A SEND IS (AGL-3273)\n *=========================================*/\n\n/**\n * WHERE A SEND IS, given only what a link or a delivery event carries.\n *\n * Campaign containers and sends belong to the organization\n * (`orgs/{orgId}/emailCampaigns`, `orgs/{orgId}/campaigns`, AGL-3273). Every\n * reader that starts from inside the product already holds the org id and\n * addresses those collections directly. This module is for the readers that\n * start OUTSIDE it — the unsubscribe link, the provider's delivery webhook,\n * the conversion join — which hold a site id and a send id and nothing else,\n * because that is what was signed into the link or tagged on the message\n * when it went out, possibly years ago.\n *\n * ## The fallback, and why it stays\n *\n * The site path (`hosts/{hostId}/campaigns/{sendId}`) is where every send\n * lived before the move, and the migration copies each one up under its\n * existing id. Between a deployment of this code and the migration reaching\n * an org, the send is still only at the site; and an interrupted migration\n * leaves some sends behind. A reader that looked only at the org would, in\n * that window, drop an unsubscribe's count or a bounce — and a bounce that\n * is dropped is an address that gets mailed again. So the org is asked\n * first and the site second. After the migration the second read never\n * happens, because the first one answers.\n *\n * The collection names are spelled here, beside the join that is this\n * lookup's first reader; `campaign-container.ts` documents the same strings.\n */\n\nconst sendRefFirestore = (): Firestore => firebaseAdmin.app().firestore()\n\n/** `orgs/{orgId}/campaigns` — one document per email send. */\nconst ORG_SENDS = 'campaigns'\n\n/** `orgs/{orgId}/campaignSequenceReports` — keyed by the container id. */\nconst ORG_SEQUENCE_REPORTS = 'campaignSequenceReports'\n\n/** `orgs/{orgId}/campaigns/{sendId}`. */\nexport function orgCampaignSendRef(\n  orgId: string,\n  sendId: string,\n  firestore: Firestore = sendRefFirestore(),\n): DocumentReference {\n  return firestore.collection('orgs').doc(orgId).collection(ORG_SENDS).doc(sendId)\n}\n\n/** `orgs/{orgId}/campaignSequenceReports/{campaignId}`. */\nexport function orgCampaignSequenceReportRef(\n  orgId: string,\n  campaignId: string,\n  firestore: Firestore = sendRefFirestore(),\n): DocumentReference {\n  return firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(ORG_SEQUENCE_REPORTS)\n    .doc(campaignId)\n}\n\n/** The pre-AGL-3273 location, read only as the fallback described above. */\nfunction legacySiteSendRef(\n  hostId: string,\n  sendId: string,\n  firestore: Firestore,\n): DocumentReference {\n  return firestore.collection('hosts').doc(hostId).collection(ORG_SENDS).doc(sendId)\n}\n\nexport interface ResolveCampaignSendRefInput {\n  /** The site the link or the message tag names. */\n  hostId: string\n  /** The send id (`cid` on a link, `campaignId` on a message tag). */\n  sendId: string\n  /**\n   * The org, when the caller already has it — a message tag minted since\n   * AGL-3273 carries it. Saves the `hostIndex` read.\n   */\n  orgId?: string | null\n  firestore?: Firestore\n}\n\n/**\n * The send's document, wherever it currently is. Null when neither location\n * holds it — a send id from a link whose send was discarded, or a forged one.\n *\n * Costs one read after the migration (the org document), plus the\n * `hostIndex` lookup when the caller has no org id; that lookup is\n * request-cached.\n */\nexport async function resolveCampaignSendRef(\n  input: ResolveCampaignSendRefInput,\n): Promise<DocumentReference | null> {\n  const { hostId, sendId } = input\n  if (!hostId || !sendId || sendId.includes('/') || hostId.includes('/')) return null\n  const firestore = input.firestore ?? sendRefFirestore()\n  const orgId = input.orgId || (await resolveOrgIdForHost(hostId))\n  if (orgId) {\n    const orgRef = orgCampaignSendRef(orgId, sendId, firestore)\n    if ((await orgRef.get()).exists) return orgRef\n  }\n  const siteRef = legacySiteSendRef(hostId, sendId, firestore)\n  if ((await siteRef.get()).exists) return siteRef\n  return null\n}\n"],"names":["FieldValue","parseUtmTouch","EMAIL_ATTRIBUTION_MODEL","ATTRIBUTION_MODEL","EMAIL_ATTRIBUTION_WINDOW_DAYS","ATTRIBUTION_WINDOW_DAYS","emailTouchIsInWindow","personKey","CAMPAIGN_ATTRIBUTIONS_COLLECTION","eraseCampaignAttributionsForPersonKey","isDocumentId","firebaseAdmin","resolveOrgIdForHost","readEmailCampaignTouch","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","viaSequence","sequenceId","enrollmentId","channel","touchedAtMs","source","medium","campaign","error","console","attributeCampaignConversion","touch","record","model","windowDays","db","hostRef","collection","doc","create","createdAt","serverTimestamp","sendRef","resolveCampaignSendRef","sendId","set","byKind","increment","updatedAt","merge","creditCampaignSequenceOutcome","campaignIds","outcome","CAMPAIGN_SEQUENCE_REPORTS_COLLECTION","CAMPAIGN_SEQUENCE_OUTCOMES","includes","ids","Set","map","id","trim","filter","length","given","orgId","Promise","all","orgCampaignSequenceReportRef","byOutcome","updatedAtMs","sendRefFirestore","ORG_SENDS","ORG_SEQUENCE_REPORTS","orgCampaignSendRef","legacySiteSendRef","input","orgRef","get","exists","siteRef"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/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, type DocumentReference, type Firestore } from 'firebase-admin/firestore'\nimport {\n  parsePageTouch,\n  parseUtmTouch,\n  type PageTouch,\n  type UtmTouch,\n} from '@aglyn/aglyn/app-utils/utm-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_WINDOW_DAYS as ATTRIBUTION_WINDOW_DAYS,\n  emailTouchIsInWindow,\n} from '@aglyn/shared-util-email/email-revenue-window'\n/*\n * The identify moment's own rule (AGL-3461): a page filed under a campaign is\n * a touch here, and it is not a click, so these records say `last-touch` where\n * an order's say `last-click`. The window above is still the one both share.\n */\nimport {\n  CAMPAIGN_TOUCH_MODEL as ATTRIBUTION_MODEL,\n  CAMPAIGN_VISIT_MS,\n} from '../model/campaign-conversions'\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\nimport {\n  CAMPAIGN_ATTRIBUTIONS_COLLECTION,\n  eraseCampaignAttributionsForPersonKey,\n} from './campaign-attribution-store'\nimport { isDocumentId } from '@aglyn/tenant-data-admin/server/document-id'\nimport firebaseAdmin from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations'\nimport { readEmailCampaignTouch } from './email-campaign-touch'\nimport { campaignForUtmLabel, filedCampaignForPage } from './campaign-touch-targets'\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 (`utm-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 *    (`email-campaign-touch.ts`), written server-side when they clicked a\n *    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 * ## And a page filed under a campaign (AGL-3461)\n *\n * A third touch needs no label and no click: the visitor viewed a page the\n * merchant filed under a campaign. The device carries it beside the labels\n * (`utm-touch.ts`), the server credits it only while the campaign exists and\n * the page is still filed under it (`campaign-touch-targets.ts`), and it\n * competes with the winning click under {@link pickCampaignTouch}. A label a\n * campaign declares as its own (`utmCampaigns` on the container) names that\n * campaign the same way. Both are recorded with the CONTAINER's id as\n * `campaignId`, under the `last-touch` model.\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 — see\n * `campaign-attribution-store.ts` for why.\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/**\n * Which channel the credited touch arrived through.\n *\n * `sequence` (AGL-3254) is a click on, or the sending of, a one-to-one\n * email a rep's sequence sent. It is read off the same touch map as the\n * email channel — the Outreach click route stamps it there with the\n * sequence and the enrollment beside the campaign the sequence is in — so\n * a booking made from a sequence link is credited by the door that credits\n * every other booking, and nothing in this join has to know what a\n * sequence is.\n */\nexport type CampaignTouchChannel = 'email' | 'web' | 'sequence' | 'page'\n\n/** The touch a conversion is credited to, once every channel has been asked. */\nexport interface ResolvedCampaignTouch {\n  channel: CampaignTouchChannel\n  /**\n   * The campaign document, when the touch was a click on our own mail — or\n   * the campaign CONTAINER (`emailCampaigns/{id}`) a sequence is in, for a\n   * sequence touch, the page was filed under, for a page touch, or that\n   * declares the label, for a web touch whose label one does (AGL-3461).\n   */\n  campaignId?: string\n  /** The screen the visitor viewed, for a `page` touch. */\n  screenId?: string\n  /** That page's path, for a `page` touch. */\n  path?: string\n  /** The sequence the touch came through, for a `sequence` touch. */\n  sequenceId?: string\n  /** The enrollment the touch came through, for a `sequence` touch. */\n  enrollmentId?: 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    const db = firestore ?? defaultFirestore()\n\n    /*\n     * The window is enforced inside the parsers, so an expired wire value\n     * answers null here exactly as it does in the browser that decided\n     * whether to send it.\n     *\n     * Both instants on the wire are the VISITOR'S clock, and a device running\n     * a few minutes fast would date the page it is reading after the\n     * conversion the server is recording — refused as \"a touch after the\n     * conversion\", which is the receipt rule, not a clock rule. So the parse\n     * allows {@link CLIENT_CLOCK_SKEW_MS} of future and clamps it to the\n     * conversion; the write re-checks the window against the server's own\n     * instant either way.\n     */\n    const web = clampToConversion(\n      parseUtmTouch(options.wire, convertedAtMs + CLIENT_CLOCK_SKEW_MS),\n      convertedAtMs,\n    )\n    const page = clampToConversion(\n      parsePageTouch(options.wire, convertedAtMs + CLIENT_CLOCK_SKEW_MS),\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(String(options.email ?? ''), hostId, db)\n      : null\n    const emailInWindow =\n      emailTouch &&\n      isDocumentId(emailTouch.campaignId) &&\n      emailTouchIsInWindow(emailTouch.clickedAtMs, convertedAtMs)\n        ? emailTouch\n        : null\n\n    /*\n     * The org owns the campaigns a page or a label can name. Asked only when\n     * the visitor carried one of those, so the ordinary conversion pays\n     * nothing for it — and the lookup is request-cached besides.\n     */\n    const orgId =\n      page || web?.campaign\n        ? await resolveOrgIdForHost(hostId).catch(() => null)\n        : null\n\n    /*\n     * A CLICK first — the later of the campaign email and the labeled link,\n     * and a tie goes to email. A tie is only reachable when the two instants\n     * are the same millisecond, and in that case the email touch is the better\n     * evidence: it was recorded by the provider's own click event on the\n     * server, while the web touch is a value the visitor's device supplied.\n     */\n    const emailWins =\n      emailInWindow && (!web || emailInWindow.clickedAtMs >= web.atMs)\n    let click: ResolvedCampaignTouch | null = null\n    if (emailWins) {\n      const viaSequence = emailInWindow.sequenceId && emailInWindow.enrollmentId\n      click = {\n        channel: viaSequence ? 'sequence' : 'email',\n        campaignId: emailInWindow.campaignId,\n        ...(viaSequence\n          ? { sequenceId: emailInWindow.sequenceId, enrollmentId: emailInWindow.enrollmentId }\n          : {}),\n        touchedAtMs: emailInWindow.clickedAtMs,\n        ...(key ? { personKey: key } : {}),\n      }\n    } else if (web) {\n      // A label a campaign declares names that campaign (AGL-3461); any other\n      // label stays the text it is.\n      const declared =\n        orgId && web.campaign\n          ? await campaignForUtmLabel({ orgId, hostId, label: web.campaign }, db)\n          : null\n      click = {\n        channel: 'web',\n        ...(declared ? { campaignId: declared.id } : {}),\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    }\n\n    /*\n     * THEN THE PAGE (AGL-3461), checked against what is stored: the campaign\n     * still exists and the page is still filed under it. Read only when there\n     * is one — and never when the click it would compete with is in the same\n     * visit and names a campaign, because that click wins without it.\n     */\n    const pageCouldWin =\n      page &&\n      orgId &&\n      !(\n        click?.campaignId &&\n        Math.abs(page.atMs - click.touchedAtMs) <= CAMPAIGN_VISIT_MS\n      )\n    const filed = pageCouldWin\n      ? await filedCampaignForPage(\n          {\n            orgId,\n            hostId,\n            screenId: page.screenId,\n            campaignIds: page.containerIds,\n          },\n          db,\n        )\n      : null\n    const pageTouch: ResolvedCampaignTouch | null =\n      page && filed\n        ? {\n            channel: 'page',\n            campaignId: filed.id,\n            screenId: page.screenId,\n            ...(page.path ? { path: page.path } : {}),\n            touchedAtMs: page.atMs,\n            ...(key ? { personKey: key } : {}),\n          }\n        : null\n\n    return pickCampaignTouch(click, pageTouch)\n  } catch (error) {\n    console.error('resolveCampaignTouch failed', error)\n    return null\n  }\n}\n\n/**\n * How far ahead of the server a visitor's clock may run before the touch it\n * dates is refused as after the conversion.\n */\nconst CLIENT_CLOCK_SKEW_MS = 5 * 60 * 1000\n\n/** A parsed touch with an instant no later than the conversion. */\nfunction clampToConversion<T extends UtmTouch | PageTouch>(\n  touch: T | null,\n  convertedAtMs: number,\n): T | null {\n  if (!touch) return null\n  return touch.atMs > convertedAtMs ? { ...touch, atMs: convertedAtMs } : touch\n}\n\n/**\n * THE RULE, between a click and a page (AGL-3461) — `CAMPAIGN_TOUCH_MODEL`\n * says it in words.\n *\n * Within one visit a click that names a campaign keeps the credit for the\n * page it landed on: the visitor clicked a campaign's mail or a link labeled\n * for a campaign and READ the page because of it, and handing the credit to\n * the page would take every landing page's conversions away from the email\n * that sent the reader there. A bare label yields to the page, because the\n * page names a campaign and the label names nothing anybody can open.\n *\n * Further apart, the later wins, which is the last-touch rule every other\n * pair already follows.\n */\nexport function pickCampaignTouch(\n  click: ResolvedCampaignTouch | null,\n  page: ResolvedCampaignTouch | null,\n): ResolvedCampaignTouch | null {\n  if (!page) return click\n  if (!click) return page\n  if (Math.abs(page.touchedAtMs - click.touchedAtMs) <= CAMPAIGN_VISIT_MS) {\n    return click.campaignId ? click : page\n  }\n  return page.touchedAtMs > click.touchedAtMs ? page : click\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.sequenceId ? { sequenceId: touch.sequenceId } : {}),\n      ...(touch.enrollmentId ? { enrollmentId: touch.enrollmentId } : {}),\n      ...(touch.source ? { source: touch.source } : {}),\n      ...(touch.medium ? { medium: touch.medium } : {}),\n      ...(touch.campaign ? { campaign: touch.campaign } : {}),\n      ...(touch.screenId ? { screenId: touch.screenId } : {}),\n      ...(touch.path ? { path: touch.path } : {}),\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    /*\n     * The send the touch names (`touch.campaignId` is a SEND id on the email\n     * channel), wherever it is: the org's `campaigns` collection, or the\n     * site's for a send the migration has not reached. A send in neither\n     * place was discarded, and its rollup is skipped — the record above\n     * already says what was credited.\n     */\n    const sendRef =\n      touch.channel === 'email' && touch.campaignId && isDocumentId(touch.campaignId)\n        ? await resolveCampaignSendRef({ hostId, sendId: touch.campaignId, firestore: db })\n        : null\n    if (sendRef) {\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 sendRef\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    /*\n     * A SEQUENCE touch rolls up under the campaign's sequences report, and\n     * only a booking does: \"meetings booked from a sequence link\" is the one\n     * identify moment a sequence's own outcomes do not already count. The\n     * form, lead and contact kinds stand as records — visible on the record\n     * they credit and on the site's conversions list — and never in\n     * `byKind`, whose caveat promises the reader campaign emails only.\n     */\n    if (touch.channel === 'sequence' && touch.campaignId && options.kind === 'booking') {\n      await creditCampaignSequenceOutcome(\n        { hostId, campaignIds: [touch.campaignId], outcome: 'meetings', atMs: convertedAtMs },\n        db,\n      )\n    }\n\n    return record\n  } catch (error) {\n    console.error('attributeCampaignConversion failed', error)\n    return null\n  }\n}\n\n/*==========================================\n * WHAT A CAMPAIGN'S SEQUENCES PRODUCED (AGL-3254).\n *\n * A sequence joins a campaign the way a form does, and the Outreach runtime\n * credits what each enrollment produced — enrolled, first email sent, a\n * reply, a meeting booked from a sequence link, an enrolled lead converted\n * — to every campaign the sequence was in when the person was enrolled. The\n * counts live in `orgs/{orgId}/campaignSequenceReports/{campaignId}`, beside\n * the org's containers: one document per campaign, server-only like every\n * other report here, and never inside the campaign container, which the\n * history list reads.\n *\n * Idempotency is the CALLER's: a plugin credits an outcome once per\n * enrollment from a state change that happens once — the enrollment is\n * created once, its first email is the first, its status moves to replied\n * once, its lead converts once — so this writer is a plain increment and\n * keeps no per-enrollment record of its own.\n *=========================================*/\n\n/**\n * The per-org collection of sequence rollups. Restated from the reader\n * (`model/campaign-report.ts`) and asserted equal by\n * the reader's spec.\n */\nexport const CAMPAIGN_SEQUENCE_REPORTS_COLLECTION = 'campaignSequenceReports'\n\n/** The outcomes the runtime credits, in funnel order. */\nexport const CAMPAIGN_SEQUENCE_OUTCOMES = [\n  'enrolled',\n  'sent',\n  'replied',\n  'meetings',\n  'converted',\n] as const\n\nexport type CampaignSequenceOutcome = (typeof CAMPAIGN_SEQUENCE_OUTCOMES)[number]\n\n/**\n * Credits one outcome, for one enrollment, to every campaign named.\n *\n * Never throws, and never refuses the batch for one bad id: the outcome\n * has already happened, and a campaign that is gone gains an orphaned\n * report rather than blocking the credit to one that is not — the\n * conversions rollup's own argument for a merge-set that creates.\n *\n * @returns how many campaigns were credited.\n */\nexport async function creditCampaignSequenceOutcome(\n  options: {\n    /** The site the enrollment emails for; resolves the org when none is given. */\n    hostId: string\n    /**\n     * The org whose containers the campaigns are, when the caller holds it —\n     * an enrollment is an org document, so its routes do. Saves the\n     * `hostIndex` read.\n     */\n    orgId?: string | null\n    /** The campaigns the enrollment carries; unusable ids are skipped. */\n    campaignIds: readonly string[]\n    outcome: CampaignSequenceOutcome\n    /** When the outcome happened. Defaults to now. */\n    atMs?: number\n  },\n  firestore?: any,\n): Promise<number> {\n  try {\n    if (!(CAMPAIGN_SEQUENCE_OUTCOMES as readonly string[]).includes(options.outcome)) return 0\n    const atMs = Number(options.atMs ?? Date.now())\n    const ids = [...new Set(options.campaignIds.map((id) => String(id ?? '').trim()))].filter(\n      (id) => isDocumentId(id),\n    )\n    if (!ids.length) return 0\n    const hostId = String(options.hostId ?? '')\n    const given = String(options.orgId ?? '')\n    const orgId = isDocumentId(given)\n      ? given\n      : isDocumentId(hostId)\n        ? await resolveOrgIdForHost(hostId)\n        : null\n    if (!orgId || !isDocumentId(orgId)) return 0\n    const db = firestore ?? defaultFirestore()\n    await Promise.all(\n      ids.map((campaignId) =>\n        orgCampaignSequenceReportRef(orgId, campaignId, db).set(\n          {\n            byOutcome: { [options.outcome]: FieldValue.increment(1) },\n            ...(Number.isFinite(atMs) && atMs > 0 ? { updatedAtMs: atMs } : {}),\n            updatedAt: FieldValue.serverTimestamp(),\n          },\n          { merge: true },\n        ),\n      ),\n    )\n    return ids.length\n  } catch (error) {\n    console.error('creditCampaignSequenceOutcome failed', error)\n    return 0\n  }\n}\n\n/*==========================================\n * WHERE A SEND IS (AGL-3273)\n *=========================================*/\n\n/**\n * WHERE A SEND IS, given only what a link or a delivery event carries.\n *\n * Campaign containers and sends belong to the organization\n * (`orgs/{orgId}/emailCampaigns`, `orgs/{orgId}/campaigns`, AGL-3273). Every\n * reader that starts from inside the product already holds the org id and\n * addresses those collections directly. This module is for the readers that\n * start OUTSIDE it — the unsubscribe link, the provider's delivery webhook,\n * the conversion join — which hold a site id and a send id and nothing else,\n * because that is what was signed into the link or tagged on the message\n * when it went out, possibly years ago.\n *\n * ## The fallback, and why it stays\n *\n * The site path (`hosts/{hostId}/campaigns/{sendId}`) is where every send\n * lived before the move, and the migration copies each one up under its\n * existing id. Between a deployment of this code and the migration reaching\n * an org, the send is still only at the site; and an interrupted migration\n * leaves some sends behind. A reader that looked only at the org would, in\n * that window, drop an unsubscribe's count or a bounce — and a bounce that\n * is dropped is an address that gets mailed again. So the org is asked\n * first and the site second. After the migration the second read never\n * happens, because the first one answers.\n *\n * The collection names are spelled here, beside the join that is this\n * lookup's first reader; `campaign-container.ts` documents the same strings.\n */\n\nconst sendRefFirestore = (): Firestore => firebaseAdmin.app().firestore()\n\n/** `orgs/{orgId}/campaigns` — one document per email send. */\nconst ORG_SENDS = 'campaigns'\n\n/** `orgs/{orgId}/campaignSequenceReports` — keyed by the container id. */\nconst ORG_SEQUENCE_REPORTS = 'campaignSequenceReports'\n\n/** `orgs/{orgId}/campaigns/{sendId}`. */\nexport function orgCampaignSendRef(\n  orgId: string,\n  sendId: string,\n  firestore: Firestore = sendRefFirestore(),\n): DocumentReference {\n  return firestore.collection('orgs').doc(orgId).collection(ORG_SENDS).doc(sendId)\n}\n\n/** `orgs/{orgId}/campaignSequenceReports/{campaignId}`. */\nexport function orgCampaignSequenceReportRef(\n  orgId: string,\n  campaignId: string,\n  firestore: Firestore = sendRefFirestore(),\n): DocumentReference {\n  return firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(ORG_SEQUENCE_REPORTS)\n    .doc(campaignId)\n}\n\n/** The pre-AGL-3273 location, read only as the fallback described above. */\nfunction legacySiteSendRef(\n  hostId: string,\n  sendId: string,\n  firestore: Firestore,\n): DocumentReference {\n  return firestore.collection('hosts').doc(hostId).collection(ORG_SENDS).doc(sendId)\n}\n\nexport interface ResolveCampaignSendRefInput {\n  /** The site the link or the message tag names. */\n  hostId: string\n  /** The send id (`cid` on a link, `campaignId` on a message tag). */\n  sendId: string\n  /**\n   * The org, when the caller already has it — a message tag minted since\n   * AGL-3273 carries it. Saves the `hostIndex` read.\n   */\n  orgId?: string | null\n  firestore?: Firestore\n}\n\n/**\n * The send's document, wherever it currently is. Null when neither location\n * holds it — a send id from a link whose send was discarded, or a forged one.\n *\n * Costs one read after the migration (the org document), plus the\n * `hostIndex` lookup when the caller has no org id; that lookup is\n * request-cached.\n */\nexport async function resolveCampaignSendRef(\n  input: ResolveCampaignSendRefInput,\n): Promise<DocumentReference | null> {\n  const { hostId, sendId } = input\n  if (!hostId || !sendId || sendId.includes('/') || hostId.includes('/')) return null\n  const firestore = input.firestore ?? sendRefFirestore()\n  const orgId = input.orgId || (await resolveOrgIdForHost(hostId))\n  if (orgId) {\n    const orgRef = orgCampaignSendRef(orgId, sendId, firestore)\n    if ((await orgRef.get()).exists) return orgRef\n  }\n  const siteRef = legacySiteSendRef(hostId, sendId, firestore)\n  if ((await siteRef.get()).exists) return siteRef\n  return null\n}\n"],"names":["FieldValue","parsePageTouch","parseUtmTouch","EMAIL_ATTRIBUTION_WINDOW_DAYS","ATTRIBUTION_WINDOW_DAYS","emailTouchIsInWindow","CAMPAIGN_TOUCH_MODEL","ATTRIBUTION_MODEL","CAMPAIGN_VISIT_MS","personKey","CAMPAIGN_ATTRIBUTIONS_COLLECTION","eraseCampaignAttributionsForPersonKey","isDocumentId","firebaseAdmin","resolveOrgIdForHost","readEmailCampaignTouch","campaignForUtmLabel","filedCampaignForPage","defaultFirestore","app","firestore","CAMPAIGN_CONVERSIONS_REPORT_DOC","campaignConversionId","kind","refId","resolveCampaignTouch","options","hostId","String","convertedAtMs","Number","atMs","Date","now","isFinite","db","web","clampToConversion","wire","CLIENT_CLOCK_SKEW_MS","page","key","email","emailTouch","emailInWindow","campaignId","clickedAtMs","orgId","campaign","catch","emailWins","click","viaSequence","sequenceId","enrollmentId","channel","touchedAtMs","declared","label","id","source","medium","pageCouldWin","Math","abs","filed","screenId","campaignIds","containerIds","pageTouch","path","pickCampaignTouch","error","console","touch","attributeCampaignConversion","record","model","windowDays","hostRef","collection","doc","create","createdAt","serverTimestamp","sendRef","resolveCampaignSendRef","sendId","set","byKind","increment","updatedAt","merge","creditCampaignSequenceOutcome","outcome","CAMPAIGN_SEQUENCE_REPORTS_COLLECTION","CAMPAIGN_SEQUENCE_OUTCOMES","includes","ids","Set","map","trim","filter","length","given","Promise","all","orgCampaignSequenceReportRef","byOutcome","updatedAtMs","sendRefFirestore","ORG_SENDS","ORG_SEQUENCE_REPORTS","orgCampaignSendRef","legacySiteSendRef","input","orgRef","get","exists","siteRef"],"mappings":"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"}

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

@@ -0,0 +1,61 @@
+/**
+ * @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.
+ */
+/** A campaign container, as much of it as a touch's credit needs. */
+export interface LiveCampaign {
+    id: string;
+    name: string;
+}
+/**
+ * The campaign at `orgs/{orgId}/emailCampaigns/{campaignId}`, or `null` when
+ * it does not exist or its owner retired it.
+ */
+export declare function readLiveCampaign(options: {
+    orgId: string;
+    campaignId: string;
+}, firestore: any): Promise<LiveCampaign | null>;
+/**
+ * The campaigns a site's screen is filed under right now, or `null` when the
+ * screen does not exist.
+ */
+export declare function readScreenCampaignIds(options: {
+    hostId: string;
+    screenId: string;
+}, firestore: any): Promise<string[] | null>;
+/**
+ * Of the campaigns a page touch carries, the first that the page is STILL
+ * filed under and that still exists — or `null`.
+ *
+ * The touch carries the screen's campaigns in the screen's own order, so a
+ * page filed under two campaigns credits the one it names first. One
+ * outcome, one campaign: crediting both would count one visitor's form twice
+ * across the org's campaigns.
+ */
+export declare function filedCampaignForPage(options: {
+    orgId: string;
+    hostId: string;
+    screenId: string;
+    campaignIds: readonly string[];
+}, firestore: any): Promise<LiveCampaign | null>;
+/**
+ * The one live campaign placed on this site that declares `label` among its
+ * `utmCampaigns`, or `null` — for no such campaign, and for two.
+ */
+export declare function campaignForUtmLabel(options: {
+    orgId: string;
+    hostId: string;
+    label: string | null | undefined;
+}, firestore: any): Promise<LiveCampaign | null>;