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

package/src/lib/model/campaign-conversions.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { CampaignCaveat } from '@aglyn/shared-ui-email-campaigns/model/campaign-report';
+import type { CampaignCaveat } from './campaign-report';
 /**
  * WHAT A CAMPAIGN CAUSED — the read half of the identify-moment join.
  *
@@ -56,6 +56,15 @@ import type { CampaignCaveat } from '@aglyn/shared-ui-email-campaigns/model/camp
  * this reader states that where the figure is drawn, and web-channel records
  * are read as records — see {@link campaignConversionsCoverage}.
  *
+ * ## A PAGE OR A DECLARED LABEL NAMES THE CAMPAIGN ITSELF (AGL-3461)
+ *
+ * Two more touches name a campaign CONTAINER rather than a send: a page filed
+ * under the campaign, and a `utm_campaign` label the campaign declares as its
+ * own. Their records carry the container's id as `campaignId`, so the
+ * campaign's page counts them with the same `kind` + `campaignId` aggregation
+ * it counts its sends' conversions with — keyed by a document id, so bounded
+ * by the campaigns that exist, and needing no rollup document of their own.
+ *
  * ## A CONVERSION WITH NO TOUCH IS NOT IN HERE AT ALL
  *
  * Direct traffic writes no record. There is deliberately no
@@ -87,7 +96,43 @@ export type CampaignConversionKind = (typeof CAMPAIGN_CONVERSION_KINDS)[number];
  * the campaign whose mail was clicked, plus the sequence and the enrollment
  * it came through, so a record can say which rep's outreach it credits.
  */
-export type CampaignTouchChannel = 'email' | 'web' | 'sequence';
+export type CampaignTouchChannel = 'email' | 'web' | 'sequence' | 'page';
+/**
+ * THE RULE an identify moment is credited under (AGL-3461), stamped on every
+ * record as `model` so a reader can print what was counted.
+ *
+ * `last-click` — the revenue join's rule, which an order still uses — named
+ * the later of a campaign email click and a labeled link. A page filed under a
+ * campaign is a touch too now, and it is not a click, so the identify moment
+ * says so:
+ *
+ *  - the later of a campaign email click and a link carrying `utm_` labels
+ *    wins, exactly as before;
+ *  - a page filed under a campaign competes with that winner. Within
+ *    {@link CAMPAIGN_VISIT_MINUTES} of it the two are one visit: a click that
+ *    names a campaign — its mail, or a label the campaign declares — keeps
+ *    the credit for the page it landed on, and a label that names none
+ *    yields to the page. Further apart, the later one wins;
+ *  - all of it inside the seven-day window, as before.
+ */
+export declare const CAMPAIGN_TOUCH_MODEL = "last-touch";
+/** How close a page view and a click are to be one visit, in minutes. */
+export declare const CAMPAIGN_VISIT_MINUTES = 30;
+/** The same, in milliseconds. */
+export declare const CAMPAIGN_VISIT_MS: number;
+/**
+ * The rule a record or a rollup was credited under, as one sentence a reader
+ * can check the figure against. Keyed off the STORED model, so a conversion
+ * credited under an older rule prints the rule it was credited under.
+ */
+export declare function campaignCreditRule(model: string | null | undefined, windowDays: number | null | undefined): string;
+/**
+ * The record each conversion kind credits, as its owner publishes the kind
+ * (`plugin-record-counts`, `plugin-record-lists`): a credited form names the
+ * SUBMISSION it credits, the rest the record of their own name. The owners
+ * count and read those records; this plugin only names the kind.
+ */
+export declare const CAMPAIGN_CONVERSION_RECORD_KINDS: Readonly<Record<CampaignConversionKind, string>>;
 /**
  * What a reader calls one kind, and what the count means.
  *
@@ -147,6 +192,10 @@ export interface CampaignConversionRecord {
     touchedAtMs?: number;
     /** When the visitor became identifiable, epoch ms. */
     convertedAtMs?: number;
+    /** The screen the visitor viewed, for a `page` touch (AGL-3461). */
+    screenId?: string;
+    /** That page's path, for a `page` touch. */
+    path?: string;
     model?: string;
     windowDays?: number;
 }
@@ -290,8 +339,10 @@ export declare function campaignConversionsCoverage(options: {
  *
  * The email channel names a campaign document, so the screen can link to it,
  * and so does a sequence touch: the campaign the sequence is in is a
- * container with a page. The web channel names a label the marketer typed,
- * which is text and never a link — there is nothing at the other end of it.
+ * container with a page — as does a page touch, the campaign the viewed page
+ * is filed under (AGL-3461). The web channel names a label the marketer
+ * typed, which is text unless a campaign declares the label as its own; then
+ * the record carries that campaign's id too and the screen links it.
  *
  * The `utm_` triple is joined in the order a marketer set it, with the parts
  * that are absent left out rather than filled with a placeholder.

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

@@ -60,6 +60,15 @@
  * this reader states that where the figure is drawn, and web-channel records
  * are read as records — see {@link campaignConversionsCoverage}.
  *
+ * ## A PAGE OR A DECLARED LABEL NAMES THE CAMPAIGN ITSELF (AGL-3461)
+ *
+ * Two more touches name a campaign CONTAINER rather than a send: a page filed
+ * under the campaign, and a `utm_campaign` label the campaign declares as its
+ * own. Their records carry the container's id as `campaignId`, so the
+ * campaign's page counts them with the same `kind` + `campaignId` aggregation
+ * it counts its sends' conversions with — keyed by a document id, so bounded
+ * by the campaigns that exist, and needing no rollup document of their own.
+ *
  * ## A CONVERSION WITH NO TOUCH IS NOT IN HERE AT ALL
  *
  * Direct traffic writes no record. There is deliberately no
@@ -91,6 +100,51 @@
     'contact',
     'booking'
 ];
+/**
+ * THE RULE an identify moment is credited under (AGL-3461), stamped on every
+ * record as `model` so a reader can print what was counted.
+ *
+ * `last-click` — the revenue join's rule, which an order still uses — named
+ * the later of a campaign email click and a labeled link. A page filed under a
+ * campaign is a touch too now, and it is not a click, so the identify moment
+ * says so:
+ *
+ *  - the later of a campaign email click and a link carrying `utm_` labels
+ *    wins, exactly as before;
+ *  - a page filed under a campaign competes with that winner. Within
+ *    {@link CAMPAIGN_VISIT_MINUTES} of it the two are one visit: a click that
+ *    names a campaign — its mail, or a label the campaign declares — keeps
+ *    the credit for the page it landed on, and a label that names none
+ *    yields to the page. Further apart, the later one wins;
+ *  - all of it inside the seven-day window, as before.
+ */ export const CAMPAIGN_TOUCH_MODEL = 'last-touch';
+/** How close a page view and a click are to be one visit, in minutes. */ export const CAMPAIGN_VISIT_MINUTES = 30;
+/** The same, in milliseconds. */ export const CAMPAIGN_VISIT_MS = CAMPAIGN_VISIT_MINUTES * 60 * 1000;
+/**
+ * The rule a record or a rollup was credited under, as one sentence a reader
+ * can check the figure against. Keyed off the STORED model, so a conversion
+ * credited under an older rule prints the rule it was credited under.
+ */ export function campaignCreditRule(model, windowDays) {
+    const days = Number(windowDays != null ? windowDays : 0) || EMAIL_ATTRIBUTION_WINDOW_DAYS;
+    if (model === CAMPAIGN_TOUCH_MODEL) {
+        return `Credited to the visitor’s latest campaign touch within ${days} days — a ` + 'campaign email they clicked, a link labeled for a campaign, or a page ' + `filed under one. A page viewed within ${CAMPAIGN_VISIT_MINUTES} minutes of ` + 'a click is that click’s visit, and the click keeps the credit when it ' + 'names a campaign.';
+    }
+    if (model === EMAIL_ATTRIBUTION_MODEL) {
+        return `Credited to the last campaign whose link they clicked, within ${days} days of that click.`;
+    }
+    return `Credited under the ${String(model != null ? model : 'recorded')} model, within ${days} days.`;
+}
+/**
+ * The record each conversion kind credits, as its owner publishes the kind
+ * (`plugin-record-counts`, `plugin-record-lists`): a credited form names the
+ * SUBMISSION it credits, the rest the record of their own name. The owners
+ * count and read those records; this plugin only names the kind.
+ */ export const CAMPAIGN_CONVERSION_RECORD_KINDS = {
+    form: 'formSubmission',
+    lead: 'lead',
+    contact: 'contact',
+    booking: 'booking'
+};
 export const CAMPAIGN_CONVERSION_KIND_COPY = {
     form: {
         label: 'Form submissions',
@@ -170,7 +224,7 @@ export const CAMPAIGN_CONVERSION_KIND_COPY = {
         });
         caveats.push({
             id: 'conversions-web-not-rolled-up',
-            message: 'Campaign emails only. A conversion credited to a link tagged with ' + 'utm_ parameters is recorded against that label rather than against ' + 'a campaign, so it is not in the figures above — those conversions ' + 'are listed under Conversions in the marketing console.'
+            message: 'This email only. A conversion credited to a page filed under the ' + 'campaign, or to a link labeled for it, is counted on the ' + 'campaign’s own page; one credited to a utm_ label no campaign ' + 'declares is listed under Conversions in the marketing console.'
         });
     }
     return {
@@ -228,8 +282,10 @@ export const CAMPAIGN_CONVERSION_KIND_COPY = {
  *
  * The email channel names a campaign document, so the screen can link to it,
  * and so does a sequence touch: the campaign the sequence is in is a
- * container with a page. The web channel names a label the marketer typed,
- * which is text and never a link — there is nothing at the other end of it.
+ * container with a page — as does a page touch, the campaign the viewed page
+ * is filed under (AGL-3461). The web channel names a label the marketer
+ * typed, which is text unless a campaign declares the label as its own; then
+ * the record carries that campaign's id too and the screen links it.
  *
  * The `utm_` triple is joined in the order a marketer set it, with the parts
  * that are absent left out rather than filled with a placeholder.
@@ -237,7 +293,7 @@ export const CAMPAIGN_CONVERSION_KIND_COPY = {
  * one of them invites the reader to look for a campaign called "(none)".
  */ export function campaignTouchLabel(record) {
     if (!record) return '';
-    if (record.channel === 'email' || record.channel === 'sequence') {
+    if (record.channel === 'email' || record.channel === 'sequence' || record.channel === 'page') {
         var _record_campaignId;
         return String((_record_campaignId = record.campaignId) != null ? _record_campaignId : '');
     }

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/campaign-conversions.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 * The window and the model name come from `@aglyn/shared-util-email`, for the\n * reason `campaign-revenue.ts` gives: the writer is in `tenant-data-admin`,\n * which may not import a feature plugin, and a rule defined on both sides of\n * the join drifts into a figure credited under one and printed under another.\n */\nimport {\n  EMAIL_ATTRIBUTION_MODEL,\n  EMAIL_ATTRIBUTION_WINDOW_DAYS,\n} from '@aglyn/shared-util-email'\nimport type { CampaignCaveat } from '@aglyn/shared-ui-email-campaigns/model/campaign-report'\n\n/**\n * WHAT A CAMPAIGN CAUSED — the read half of the identify-moment join.\n *\n * `campaign-revenue.ts` answers what a campaign EARNED, from orders that name\n * their buyer. This answers what it CAUSED among people who were anonymous\n * until the moment they became somebody: they arrive from a campaign link,\n * browse, and only become identifiable when they submit a form, sign up, book\n * or check out. Same window, same last-click rule, same `model`/`windowDays`\n * stamped on every record, so the two figures on one screen are two readings\n * of one rule rather than two rules that happen to agree.\n *\n * ## THE KINDS ARE NEVER SUMMED, and this module makes that structural\n *\n * One form submission by a new person writes a submission record, a contact\n * and a lead — three true statements about one visitor action. Adding them\n * would treble every campaign's conversions, and the reader would have no way\n * to see it had happened, because the sum looks like a bigger version of a\n * real number.\n *\n * So {@link CampaignConversionsReport} carries no total, no `all`, no\n * `conversions` scalar, and there is no function here that reduces the kinds.\n * A screen that wanted one would have to write the addition itself. The\n * report also raises {@link CampaignCaveat} `conversions-kinds-overlap` so\n * the reader is told WHY the four figures stand apart, rather than being left\n * to assume the product forgot to add them up.\n *\n * ## THE WEB CHANNEL HAS NO ROLLUP, and cannot be given one\n *\n * A conversion is credited to one of two touches. An EMAIL touch names a\n * campaign document — a real entity with a real id — so its conversions roll\n * up under it beside the revenue the same join credits it with. A WEB touch\n * is a `utm_` label a marketer typed into a URL: no document, no id, and no\n * bound on how many distinct values exist, because anybody who can vary a\n * query string can mint another one.\n *\n * A rollup keyed on that label is a map a stranger can grow, which is the\n * same unbounded key space the analytics collector caps its per-day label map\n * against. So the writer increments the rollup for the email channel ONLY,\n * this reader states that where the figure is drawn, and web-channel records\n * are read as records — see {@link campaignConversionsCoverage}.\n *\n * ## A CONVERSION WITH NO TOUCH IS NOT IN HERE AT ALL\n *\n * Direct traffic writes no record. There is deliberately no\n * `utm_source=direct` placeholder, no referrer inference and no \"most recent\n * campaign on this site\" fallback: a conversion nobody can be credited with\n * is a conversion nobody is credited with.\n *\n * That makes the absence of a record load-bearing, and it makes a screen\n * showing only attributed conversions a lie by omission — it renders \"we\n * credited three of these\" as \"three of these happened\".\n * {@link campaignConversionsCoverage} exists so the unattributed count is a\n * figure on the page rather than an inference nobody makes.\n */\n\n/*\n * The constants are NOT re-exported here, though `campaign-revenue.ts`\n * re-exports the same two. Both modules sit behind one barrel, and a name\n * exported twice through it is a name a bundler has to disambiguate. Every\n * screen reads the rule off `model`/`windowDays` on the report anyway, which\n * is the stored value rather than today's constant — a campaign credited\n * under an older window has to print the window it was credited under.\n */\n\n/**\n * Which identify moment a record credits.\n *\n * An array first, because the ORDER is the reading order on every screen and\n * a second list of these is a second chance to leave one out. The union is\n * derived from it rather than written twice.\n */\nexport const CAMPAIGN_CONVERSION_KINDS = [\n  'form',\n  'lead',\n  'contact',\n  'booking',\n] as const\n\n/** One identify moment. Mirrors the writer's `CampaignConversionKind`. */\nexport type CampaignConversionKind = (typeof CAMPAIGN_CONVERSION_KINDS)[number]\n\n/**\n * Which channel the credited touch arrived through.\n *\n * `sequence` (AGL-3254) is a one-to-one email a rep's sequence sent: the\n * touch names the CAMPAIGN the sequence is in, like an email touch names\n * the campaign whose mail was clicked, plus the sequence and the enrollment\n * it came through, so a record can say which rep's outreach it credits.\n */\nexport type CampaignTouchChannel = 'email' | 'web' | 'sequence'\n\n/**\n * What a reader calls one kind, and what the count means.\n *\n * The note is the half that stops the addition. Each one names a DIFFERENT\n * population of the same visitors, and saying so under every figure is what\n * makes four numbers standing apart read as deliberate rather than as a\n * missing total.\n */\nexport interface CampaignConversionKindCopy {\n  label: string\n  note: string\n}\n\nexport const CAMPAIGN_CONVERSION_KIND_COPY: Readonly<\n  Record<CampaignConversionKind, CampaignConversionKindCopy>\n> = {\n  form: {\n    label: 'Form submissions',\n    note: 'submissions credited to this campaign',\n  },\n  lead: { label: 'Leads', note: 'new leads credited to this campaign' },\n  contact: {\n    label: 'Contacts',\n    note: 'new contacts credited to this campaign',\n  },\n  booking: { label: 'Bookings', note: 'bookings credited to this campaign' },\n}\n\n/**\n * The stored shape of `campaigns/{campaignId}/reports/conversions`.\n *\n * Its own document beside `reports/revenue`, for the reason that one is: the\n * campaign document is read by the history list, the glance widget and the\n * send path, and a map that grows with what the campaign caused would enlarge\n * every one of those reads.\n */\nexport interface CampaignConversionsRollup {\n  byKind?: Partial<Record<CampaignConversionKind, number>>\n  /** The model these conversions were credited under. */\n  model?: string\n  /** The window, in days, they were credited inside. */\n  windowDays?: number\n}\n\n/**\n * The stored shape of `hosts/{hostId}/campaignAttributions/{kind}:{refId}`.\n *\n * Read-side only, and every field optional: this is a document somebody\n * else's writer produced, and a reader that assumed a field was present would\n * throw on the first record written by an older version of it.\n */\nexport interface CampaignConversionRecord {\n  kind?: CampaignConversionKind\n  /** The submission, lead, contact or booking this credits. */\n  refId?: string\n  channel?: CampaignTouchChannel\n  /**\n   * The campaign document, when the touch was a click on our own mail — or,\n   * for a `sequence` touch, the campaign container the sequence is in.\n   */\n  campaignId?: string\n  /** The sequence, when the touch was a sequence email (AGL-3254). */\n  sequenceId?: string\n  /** The enrollment the sequence email went out under (AGL-3254). */\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  /** When the visitor became identifiable, epoch ms. */\n  convertedAtMs?: number\n  model?: string\n  windowDays?: number\n}\n\n/**\n * The document id for one conversion — `{kind}:{refId}`.\n *\n * The reader's half of the writer's `campaignConversionId`. It is restated\n * here rather than imported because the writer lives in `tenant-data-admin`,\n * which a UI library may not import, and it is one line whose shape is\n * asserted in this module's spec.\n *\n * Answers `null` for an unusable pair rather than building `form:undefined`,\n * which would be a valid document path pointing at a record that can never\n * exist — a keyed read that silently reports \"not attributed\" for every\n * record on the screen.\n */\nexport function campaignConversionId(\n  kind: string | null | undefined,\n  refId: string | null | undefined,\n): string | null {\n  const k = String(kind ?? '')\n  const ref = String(refId ?? '')\n  if (!k || !ref) return null\n  if (!(CAMPAIGN_CONVERSION_KINDS as readonly string[]).includes(k)) return null\n  // A slash would leave the collection; the id scheme already spends the\n  // colon, and a ref carrying one would make the pair ambiguous.\n  if (ref.includes('/') || ref.includes(':')) return null\n  return `${k}:${ref}`\n}\n\n/** A stored count as a non-negative integer. */\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/** One kind's figure on screen. Independent of every other kind's. */\nexport interface CampaignConversionKindReport {\n  kind: CampaignConversionKind\n  label: string\n  /**\n   * Conversions of this kind, or `null` when the rollup holds no entry.\n   *\n   * `null` rather than 0 for {@link CampaignConversionsReport.recorded}'s\n   * reason, applied per kind: a site with no booking form has never written a\n   * booking conversion, and rendering that as a measured zero invites the\n   * reader to conclude the campaign failed at something it never attempted.\n   */\n  value: number | null\n  note: string\n}\n\n/** Everything the conversions section renders. */\nexport interface CampaignConversionsReport {\n  /**\n   * One entry per kind, always all four and always in\n   * {@link CAMPAIGN_CONVERSION_KINDS} order.\n   *\n   * There is deliberately NO total beside this array, and no field anywhere\n   * on this report that holds one. See the module docblock.\n   */\n  kinds: CampaignConversionKindReport[]\n  /**\n   * Whether the rollup document exists at all.\n   *\n   * `false` is NOT \"this campaign caused nothing\" — it is also every campaign\n   * sent before the join existed, and every campaign whose conversions all\n   * arrived through the web channel, which writes no rollup. The screen\n   * renders the difference rather than printing a zero for all three.\n   */\n  recorded: boolean\n  /** At least one kind holds a figure. */\n  any: boolean\n  /** The model these figures were credited under, as stored. */\n  model: string\n  /** The window they were credited inside, as stored. */\n  windowDays: number\n  caveats: CampaignCaveat[]\n}\n\n/**\n * Turns the stored rollup into the conversions section.\n *\n * Takes the rollup and nothing else. Unlike the revenue report there is no\n * denominator to hand in: a conversion RATE over delivered messages would be\n * the same defect the revenue section refuses for orders — one visitor can\n * submit two forms, so the quotient passes 100% without anything being wrong\n * — and counting distinct people would need a document per person per\n * campaign, the per-recipient read this whole surface exists to refuse.\n */\nexport function campaignConversionsReport(options: {\n  rollup: CampaignConversionsRollup | undefined\n}): CampaignConversionsReport {\n  const { rollup } = options\n  const stored = rollup?.byKind ?? {}\n  const caveats: CampaignCaveat[] = []\n\n  const kinds: CampaignConversionKindReport[] = CAMPAIGN_CONVERSION_KINDS.map(\n    (kind) => {\n      const raw = stored[kind]\n      const copy = CAMPAIGN_CONVERSION_KIND_COPY[kind]\n      return {\n        kind,\n        label: copy.label,\n        // `undefined` means the rollup has no entry for this kind, which is\n        // not a measured zero. A stored 0 is impossible — the writer only\n        // ever increments — but it is read as unrecorded for the same reason.\n        value: raw === undefined || count(raw) === 0 ? null : count(raw),\n        note: copy.note,\n      }\n    },\n  )\n\n  const any = kinds.some((entry) => entry.value !== null)\n\n  if (any) {\n    caveats.push({\n      id: 'conversions-kinds-overlap',\n      message:\n        'These figures count different things about the same visits and are ' +\n        'deliberately not added together. One person filling in one form can ' +\n        'appear as a submission, a contact and a lead, so a total would ' +\n        'count that visit three times.',\n    })\n    caveats.push({\n      id: 'conversions-web-not-rolled-up',\n      message:\n        'Campaign emails only. A conversion credited to a link tagged with ' +\n        'utm_ parameters is recorded against that label rather than against ' +\n        'a campaign, so it is not in the figures above — those conversions ' +\n        'are listed under Conversions in the marketing console.',\n    })\n  }\n\n  return {\n    kinds,\n    recorded: rollup !== undefined,\n    any,\n    model: String(rollup?.model ?? EMAIL_ATTRIBUTION_MODEL),\n    windowDays: count(rollup?.windowDays) || EMAIL_ATTRIBUTION_WINDOW_DAYS,\n    caveats,\n  }\n}\n\n/**\n * How much of one kind was credited to anything at all.\n *\n * ## Why this figure has to exist\n *\n * The join writes nothing for a conversion it cannot credit, so a list of\n * attribution records is a list of the SUCCESSES. Rendering only that turns\n * \"we credited four of these\" into \"four of these happened\", and the reader\n * draws a conclusion about their campaigns from a number that is mostly a\n * fact about how many visitors arrived without a campaign link.\n *\n * So the screen shows both halves and this computes the second. `attributed`\n * is counted over the attribution records; `total` over the records the\n * conversions themselves live in.\n *\n * ## Why the difference is a CEILING and says so\n *\n * The two counts come from different collections with different histories,\n * and the gap between them holds three things that are not the same:\n *\n *  - conversions by visitors who arrived directly, which is what the figure\n *    is meant to describe;\n *  - conversions from before the join existed, which were never eligible; and\n *  - for contacts, conversions on the org's OTHER sites, because contacts are\n *    shared across an org while attributions are per host.\n *\n * None of those can be separated from the others without a field nobody\n * writes, so `unattributed` is reported as an upper bound and\n * {@link CampaignConversionsCoverage.exact} is `false` whenever the reasons\n * apply. A figure presented as exact when it is not is the failure this\n * whole surface is built to avoid.\n */\nexport interface CampaignConversionsCoverage {\n  kind: CampaignConversionKind\n  /** Conversions of this kind credited to some campaign or label. */\n  attributed: number\n  /** Conversions of this kind that exist, credited or not. */\n  total: number\n  /** `total - attributed`, clamped at zero. An upper bound, not a count. */\n  unattributed: number\n  /**\n   * Whether `unattributed` may be read as \"arrived directly\".\n   *\n   * Always `false` today — the three reasons in the docblock all apply to\n   * every host — and kept as a field rather than hardcoded in the copy so a\n   * screen asks the model rather than restating its conclusion.\n   */\n  exact: boolean\n  caveats: CampaignCaveat[]\n}\n\n/**\n * The attributed/unattributed split for one kind.\n *\n * `total` is `null` when it could not be counted — the aggregation failed, or\n * the collection is not readable from this surface — and the split is then\n * withheld entirely rather than defaulting `total` to `attributed`, which\n * would render every conversion as attributed and is the single most\n * flattering wrong answer available here.\n */\nexport function campaignConversionsCoverage(options: {\n  kind: CampaignConversionKind\n  attributed: number | null | undefined\n  total: number | null | undefined\n  /** The kind's records live outside this host, so `total` over-counts. */\n  crossHostTotal?: boolean\n}): CampaignConversionsCoverage | null {\n  const { kind, crossHostTotal } = options\n  if (options.total == null || options.attributed == null) return null\n  const attributed = count(options.attributed)\n  const total = count(options.total)\n  const caveats: CampaignCaveat[] = []\n\n  /*\n   * CLAMPED, and only here at the point of display. The two counts are taken\n   * from two collections a moment apart, so a conversion recorded between\n   * them makes `attributed` briefly exceed `total`; a negative count of\n   * things that did not happen is not a sentence anybody can act on.\n   */\n  const unattributed = Math.max(0, total - attributed)\n\n  caveats.push({\n    id: 'conversions-unattributed-is-a-ceiling',\n    message:\n      `${unattributed.toLocaleString()} of these are not credited to any ` +\n      'campaign. Most arrived without following a campaign link and are ' +\n      'recorded as direct — nothing is guessed from a referrer, and no ' +\n      'campaign is credited for being the most recent one to run. The rest ' +\n      'are records from before campaign attribution was recorded at all, so ' +\n      'read this as an upper bound rather than a count of direct arrivals.',\n  })\n  if (crossHostTotal) {\n    caveats.push({\n      id: 'conversions-total-crosses-hosts',\n      message:\n        'Contacts are shared across every site in this organization, while ' +\n        'attributions belong to one site. The uncredited figure therefore ' +\n        'includes contacts that were created on another site and could ' +\n        'never have been credited here.',\n    })\n  }\n\n  return {\n    kind,\n    attributed,\n    total,\n    unattributed,\n    // Never true while the reasons above stand. The field exists so a screen\n    // reads the model rather than restating its conclusion in JSX.\n    exact: false,\n    caveats,\n  }\n}\n\n/**\n * How a record names the thing it was credited to.\n *\n * The email channel names a campaign document, so the screen can link to it,\n * and so does a sequence touch: the campaign the sequence is in is a\n * container with a page. The web channel names a label the marketer typed,\n * which is text and never a link — there is nothing at the other end of it.\n *\n * The `utm_` triple is joined in the order a marketer set it, with the parts\n * that are absent left out rather than filled with a placeholder.\n * `google / cpc` and `google / cpc / (none)` describe the same link, and only\n * one of them invites the reader to look for a campaign called \"(none)\".\n */\nexport function campaignTouchLabel(\n  record: CampaignConversionRecord | null | undefined,\n): string {\n  if (!record) return ''\n  if (record.channel === 'email' || record.channel === 'sequence') {\n    return String(record.campaignId ?? '')\n  }\n  const parts = [record.source, record.medium, record.campaign]\n    .map((part) => String(part ?? '').trim())\n    .filter(Boolean)\n  return parts.join(' / ')\n}\n"],"names":["EMAIL_ATTRIBUTION_MODEL","EMAIL_ATTRIBUTION_WINDOW_DAYS","CAMPAIGN_CONVERSION_KINDS","CAMPAIGN_CONVERSION_KIND_COPY","form","label","note","lead","contact","booking","campaignConversionId","kind","refId","k","String","ref","includes","count","raw","value","Math","floor","Number","isFinite","campaignConversionsReport","options","rollup","stored","byKind","caveats","kinds","map","copy","undefined","any","some","entry","push","id","message","recorded","model","windowDays","campaignConversionsCoverage","crossHostTotal","total","attributed","unattributed","max","toLocaleString","exact","campaignTouchLabel","record","channel","campaignId","parts","source","medium","campaign","part","trim","filter","Boolean","join"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/campaign-conversions.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 * The window and the model name come from `@aglyn/shared-util-email`, for the\n * reason `campaign-revenue.ts` gives: the writer is in `tenant-data-admin`,\n * which may not import a feature plugin, and a rule defined on both sides of\n * the join drifts into a figure credited under one and printed under another.\n */\nimport {\n  EMAIL_ATTRIBUTION_MODEL,\n  EMAIL_ATTRIBUTION_WINDOW_DAYS,\n} from '@aglyn/shared-util-email'\nimport type { CampaignCaveat } from './campaign-report'\n\n/**\n * WHAT A CAMPAIGN CAUSED — the read half of the identify-moment join.\n *\n * `campaign-revenue.ts` answers what a campaign EARNED, from orders that name\n * their buyer. This answers what it CAUSED among people who were anonymous\n * until the moment they became somebody: they arrive from a campaign link,\n * browse, and only become identifiable when they submit a form, sign up, book\n * or check out. Same window, same last-click rule, same `model`/`windowDays`\n * stamped on every record, so the two figures on one screen are two readings\n * of one rule rather than two rules that happen to agree.\n *\n * ## THE KINDS ARE NEVER SUMMED, and this module makes that structural\n *\n * One form submission by a new person writes a submission record, a contact\n * and a lead — three true statements about one visitor action. Adding them\n * would treble every campaign's conversions, and the reader would have no way\n * to see it had happened, because the sum looks like a bigger version of a\n * real number.\n *\n * So {@link CampaignConversionsReport} carries no total, no `all`, no\n * `conversions` scalar, and there is no function here that reduces the kinds.\n * A screen that wanted one would have to write the addition itself. The\n * report also raises {@link CampaignCaveat} `conversions-kinds-overlap` so\n * the reader is told WHY the four figures stand apart, rather than being left\n * to assume the product forgot to add them up.\n *\n * ## THE WEB CHANNEL HAS NO ROLLUP, and cannot be given one\n *\n * A conversion is credited to one of two touches. An EMAIL touch names a\n * campaign document — a real entity with a real id — so its conversions roll\n * up under it beside the revenue the same join credits it with. A WEB touch\n * is a `utm_` label a marketer typed into a URL: no document, no id, and no\n * bound on how many distinct values exist, because anybody who can vary a\n * query string can mint another one.\n *\n * A rollup keyed on that label is a map a stranger can grow, which is the\n * same unbounded key space the analytics collector caps its per-day label map\n * against. So the writer increments the rollup for the email channel ONLY,\n * this reader states that where the figure is drawn, and web-channel records\n * are read as records — see {@link campaignConversionsCoverage}.\n *\n * ## A PAGE OR A DECLARED LABEL NAMES THE CAMPAIGN ITSELF (AGL-3461)\n *\n * Two more touches name a campaign CONTAINER rather than a send: a page filed\n * under the campaign, and a `utm_campaign` label the campaign declares as its\n * own. Their records carry the container's id as `campaignId`, so the\n * campaign's page counts them with the same `kind` + `campaignId` aggregation\n * it counts its sends' conversions with — keyed by a document id, so bounded\n * by the campaigns that exist, and needing no rollup document of their own.\n *\n * ## A CONVERSION WITH NO TOUCH IS NOT IN HERE AT ALL\n *\n * Direct traffic writes no record. There is deliberately no\n * `utm_source=direct` placeholder, no referrer inference and no \"most recent\n * campaign on this site\" fallback: a conversion nobody can be credited with\n * is a conversion nobody is credited with.\n *\n * That makes the absence of a record load-bearing, and it makes a screen\n * showing only attributed conversions a lie by omission — it renders \"we\n * credited three of these\" as \"three of these happened\".\n * {@link campaignConversionsCoverage} exists so the unattributed count is a\n * figure on the page rather than an inference nobody makes.\n */\n\n/*\n * The constants are NOT re-exported here, though `campaign-revenue.ts`\n * re-exports the same two. Both modules sit behind one barrel, and a name\n * exported twice through it is a name a bundler has to disambiguate. Every\n * screen reads the rule off `model`/`windowDays` on the report anyway, which\n * is the stored value rather than today's constant — a campaign credited\n * under an older window has to print the window it was credited under.\n */\n\n/**\n * Which identify moment a record credits.\n *\n * An array first, because the ORDER is the reading order on every screen and\n * a second list of these is a second chance to leave one out. The union is\n * derived from it rather than written twice.\n */\nexport const CAMPAIGN_CONVERSION_KINDS = [\n  'form',\n  'lead',\n  'contact',\n  'booking',\n] as const\n\n/** One identify moment. Mirrors the writer's `CampaignConversionKind`. */\nexport type CampaignConversionKind = (typeof CAMPAIGN_CONVERSION_KINDS)[number]\n\n/**\n * Which channel the credited touch arrived through.\n *\n * `sequence` (AGL-3254) is a one-to-one email a rep's sequence sent: the\n * touch names the CAMPAIGN the sequence is in, like an email touch names\n * the campaign whose mail was clicked, plus the sequence and the enrollment\n * it came through, so a record can say which rep's outreach it credits.\n */\nexport type CampaignTouchChannel = 'email' | 'web' | 'sequence' | 'page'\n\n/**\n * THE RULE an identify moment is credited under (AGL-3461), stamped on every\n * record as `model` so a reader can print what was counted.\n *\n * `last-click` — the revenue join's rule, which an order still uses — named\n * the later of a campaign email click and a labeled link. A page filed under a\n * campaign is a touch too now, and it is not a click, so the identify moment\n * says so:\n *\n *  - the later of a campaign email click and a link carrying `utm_` labels\n *    wins, exactly as before;\n *  - a page filed under a campaign competes with that winner. Within\n *    {@link CAMPAIGN_VISIT_MINUTES} of it the two are one visit: a click that\n *    names a campaign — its mail, or a label the campaign declares — keeps\n *    the credit for the page it landed on, and a label that names none\n *    yields to the page. Further apart, the later one wins;\n *  - all of it inside the seven-day window, as before.\n */\nexport const CAMPAIGN_TOUCH_MODEL = 'last-touch'\n\n/** How close a page view and a click are to be one visit, in minutes. */\nexport const CAMPAIGN_VISIT_MINUTES = 30\n\n/** The same, in milliseconds. */\nexport const CAMPAIGN_VISIT_MS = CAMPAIGN_VISIT_MINUTES * 60 * 1000\n\n/**\n * The rule a record or a rollup was credited under, as one sentence a reader\n * can check the figure against. Keyed off the STORED model, so a conversion\n * credited under an older rule prints the rule it was credited under.\n */\nexport function campaignCreditRule(\n  model: string | null | undefined,\n  windowDays: number | null | undefined,\n): string {\n  const days = Number(windowDays ?? 0) || EMAIL_ATTRIBUTION_WINDOW_DAYS\n  if (model === CAMPAIGN_TOUCH_MODEL) {\n    return (\n      `Credited to the visitor’s latest campaign touch within ${days} days — a ` +\n      'campaign email they clicked, a link labeled for a campaign, or a page ' +\n      `filed under one. A page viewed within ${CAMPAIGN_VISIT_MINUTES} minutes of ` +\n      'a click is that click’s visit, and the click keeps the credit when it ' +\n      'names a campaign.'\n    )\n  }\n  if (model === EMAIL_ATTRIBUTION_MODEL) {\n    return `Credited to the last campaign whose link they clicked, within ${days} days of that click.`\n  }\n  return `Credited under the ${String(model ?? 'recorded')} model, within ${days} days.`\n}\n\n/**\n * The record each conversion kind credits, as its owner publishes the kind\n * (`plugin-record-counts`, `plugin-record-lists`): a credited form names the\n * SUBMISSION it credits, the rest the record of their own name. The owners\n * count and read those records; this plugin only names the kind.\n */\nexport const CAMPAIGN_CONVERSION_RECORD_KINDS: Readonly<\n  Record<CampaignConversionKind, string>\n> = {\n  form: 'formSubmission',\n  lead: 'lead',\n  contact: 'contact',\n  booking: 'booking',\n}\n\n/**\n * What a reader calls one kind, and what the count means.\n *\n * The note is the half that stops the addition. Each one names a DIFFERENT\n * population of the same visitors, and saying so under every figure is what\n * makes four numbers standing apart read as deliberate rather than as a\n * missing total.\n */\nexport interface CampaignConversionKindCopy {\n  label: string\n  note: string\n}\n\nexport const CAMPAIGN_CONVERSION_KIND_COPY: Readonly<\n  Record<CampaignConversionKind, CampaignConversionKindCopy>\n> = {\n  form: {\n    label: 'Form submissions',\n    note: 'submissions credited to this campaign',\n  },\n  lead: { label: 'Leads', note: 'new leads credited to this campaign' },\n  contact: {\n    label: 'Contacts',\n    note: 'new contacts credited to this campaign',\n  },\n  booking: { label: 'Bookings', note: 'bookings credited to this campaign' },\n}\n\n/**\n * The stored shape of `campaigns/{campaignId}/reports/conversions`.\n *\n * Its own document beside `reports/revenue`, for the reason that one is: the\n * campaign document is read by the history list, the glance widget and the\n * send path, and a map that grows with what the campaign caused would enlarge\n * every one of those reads.\n */\nexport interface CampaignConversionsRollup {\n  byKind?: Partial<Record<CampaignConversionKind, number>>\n  /** The model these conversions were credited under. */\n  model?: string\n  /** The window, in days, they were credited inside. */\n  windowDays?: number\n}\n\n/**\n * The stored shape of `hosts/{hostId}/campaignAttributions/{kind}:{refId}`.\n *\n * Read-side only, and every field optional: this is a document somebody\n * else's writer produced, and a reader that assumed a field was present would\n * throw on the first record written by an older version of it.\n */\nexport interface CampaignConversionRecord {\n  kind?: CampaignConversionKind\n  /** The submission, lead, contact or booking this credits. */\n  refId?: string\n  channel?: CampaignTouchChannel\n  /**\n   * The campaign document, when the touch was a click on our own mail — or,\n   * for a `sequence` touch, the campaign container the sequence is in.\n   */\n  campaignId?: string\n  /** The sequence, when the touch was a sequence email (AGL-3254). */\n  sequenceId?: string\n  /** The enrollment the sequence email went out under (AGL-3254). */\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  /** When the visitor became identifiable, epoch ms. */\n  convertedAtMs?: number\n  /** The screen the visitor viewed, for a `page` touch (AGL-3461). */\n  screenId?: string\n  /** That page's path, for a `page` touch. */\n  path?: string\n  model?: string\n  windowDays?: number\n}\n\n/**\n * The document id for one conversion — `{kind}:{refId}`.\n *\n * The reader's half of the writer's `campaignConversionId`. It is restated\n * here rather than imported because the writer lives in `tenant-data-admin`,\n * which a UI library may not import, and it is one line whose shape is\n * asserted in this module's spec.\n *\n * Answers `null` for an unusable pair rather than building `form:undefined`,\n * which would be a valid document path pointing at a record that can never\n * exist — a keyed read that silently reports \"not attributed\" for every\n * record on the screen.\n */\nexport function campaignConversionId(\n  kind: string | null | undefined,\n  refId: string | null | undefined,\n): string | null {\n  const k = String(kind ?? '')\n  const ref = String(refId ?? '')\n  if (!k || !ref) return null\n  if (!(CAMPAIGN_CONVERSION_KINDS as readonly string[]).includes(k)) return null\n  // A slash would leave the collection; the id scheme already spends the\n  // colon, and a ref carrying one would make the pair ambiguous.\n  if (ref.includes('/') || ref.includes(':')) return null\n  return `${k}:${ref}`\n}\n\n/** A stored count as a non-negative integer. */\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/** One kind's figure on screen. Independent of every other kind's. */\nexport interface CampaignConversionKindReport {\n  kind: CampaignConversionKind\n  label: string\n  /**\n   * Conversions of this kind, or `null` when the rollup holds no entry.\n   *\n   * `null` rather than 0 for {@link CampaignConversionsReport.recorded}'s\n   * reason, applied per kind: a site with no booking form has never written a\n   * booking conversion, and rendering that as a measured zero invites the\n   * reader to conclude the campaign failed at something it never attempted.\n   */\n  value: number | null\n  note: string\n}\n\n/** Everything the conversions section renders. */\nexport interface CampaignConversionsReport {\n  /**\n   * One entry per kind, always all four and always in\n   * {@link CAMPAIGN_CONVERSION_KINDS} order.\n   *\n   * There is deliberately NO total beside this array, and no field anywhere\n   * on this report that holds one. See the module docblock.\n   */\n  kinds: CampaignConversionKindReport[]\n  /**\n   * Whether the rollup document exists at all.\n   *\n   * `false` is NOT \"this campaign caused nothing\" — it is also every campaign\n   * sent before the join existed, and every campaign whose conversions all\n   * arrived through the web channel, which writes no rollup. The screen\n   * renders the difference rather than printing a zero for all three.\n   */\n  recorded: boolean\n  /** At least one kind holds a figure. */\n  any: boolean\n  /** The model these figures were credited under, as stored. */\n  model: string\n  /** The window they were credited inside, as stored. */\n  windowDays: number\n  caveats: CampaignCaveat[]\n}\n\n/**\n * Turns the stored rollup into the conversions section.\n *\n * Takes the rollup and nothing else. Unlike the revenue report there is no\n * denominator to hand in: a conversion RATE over delivered messages would be\n * the same defect the revenue section refuses for orders — one visitor can\n * submit two forms, so the quotient passes 100% without anything being wrong\n * — and counting distinct people would need a document per person per\n * campaign, the per-recipient read this whole surface exists to refuse.\n */\nexport function campaignConversionsReport(options: {\n  rollup: CampaignConversionsRollup | undefined\n}): CampaignConversionsReport {\n  const { rollup } = options\n  const stored = rollup?.byKind ?? {}\n  const caveats: CampaignCaveat[] = []\n\n  const kinds: CampaignConversionKindReport[] = CAMPAIGN_CONVERSION_KINDS.map(\n    (kind) => {\n      const raw = stored[kind]\n      const copy = CAMPAIGN_CONVERSION_KIND_COPY[kind]\n      return {\n        kind,\n        label: copy.label,\n        // `undefined` means the rollup has no entry for this kind, which is\n        // not a measured zero. A stored 0 is impossible — the writer only\n        // ever increments — but it is read as unrecorded for the same reason.\n        value: raw === undefined || count(raw) === 0 ? null : count(raw),\n        note: copy.note,\n      }\n    },\n  )\n\n  const any = kinds.some((entry) => entry.value !== null)\n\n  if (any) {\n    caveats.push({\n      id: 'conversions-kinds-overlap',\n      message:\n        'These figures count different things about the same visits and are ' +\n        'deliberately not added together. One person filling in one form can ' +\n        'appear as a submission, a contact and a lead, so a total would ' +\n        'count that visit three times.',\n    })\n    caveats.push({\n      id: 'conversions-web-not-rolled-up',\n      message:\n        'This email only. A conversion credited to a page filed under the ' +\n        'campaign, or to a link labeled for it, is counted on the ' +\n        'campaign’s own page; one credited to a utm_ label no campaign ' +\n        'declares is listed under Conversions in the marketing console.',\n    })\n  }\n\n  return {\n    kinds,\n    recorded: rollup !== undefined,\n    any,\n    model: String(rollup?.model ?? EMAIL_ATTRIBUTION_MODEL),\n    windowDays: count(rollup?.windowDays) || EMAIL_ATTRIBUTION_WINDOW_DAYS,\n    caveats,\n  }\n}\n\n/**\n * How much of one kind was credited to anything at all.\n *\n * ## Why this figure has to exist\n *\n * The join writes nothing for a conversion it cannot credit, so a list of\n * attribution records is a list of the SUCCESSES. Rendering only that turns\n * \"we credited four of these\" into \"four of these happened\", and the reader\n * draws a conclusion about their campaigns from a number that is mostly a\n * fact about how many visitors arrived without a campaign link.\n *\n * So the screen shows both halves and this computes the second. `attributed`\n * is counted over the attribution records; `total` over the records the\n * conversions themselves live in.\n *\n * ## Why the difference is a CEILING and says so\n *\n * The two counts come from different collections with different histories,\n * and the gap between them holds three things that are not the same:\n *\n *  - conversions by visitors who arrived directly, which is what the figure\n *    is meant to describe;\n *  - conversions from before the join existed, which were never eligible; and\n *  - for contacts, conversions on the org's OTHER sites, because contacts are\n *    shared across an org while attributions are per host.\n *\n * None of those can be separated from the others without a field nobody\n * writes, so `unattributed` is reported as an upper bound and\n * {@link CampaignConversionsCoverage.exact} is `false` whenever the reasons\n * apply. A figure presented as exact when it is not is the failure this\n * whole surface is built to avoid.\n */\nexport interface CampaignConversionsCoverage {\n  kind: CampaignConversionKind\n  /** Conversions of this kind credited to some campaign or label. */\n  attributed: number\n  /** Conversions of this kind that exist, credited or not. */\n  total: number\n  /** `total - attributed`, clamped at zero. An upper bound, not a count. */\n  unattributed: number\n  /**\n   * Whether `unattributed` may be read as \"arrived directly\".\n   *\n   * Always `false` today — the three reasons in the docblock all apply to\n   * every host — and kept as a field rather than hardcoded in the copy so a\n   * screen asks the model rather than restating its conclusion.\n   */\n  exact: boolean\n  caveats: CampaignCaveat[]\n}\n\n/**\n * The attributed/unattributed split for one kind.\n *\n * `total` is `null` when it could not be counted — the aggregation failed, or\n * the collection is not readable from this surface — and the split is then\n * withheld entirely rather than defaulting `total` to `attributed`, which\n * would render every conversion as attributed and is the single most\n * flattering wrong answer available here.\n */\nexport function campaignConversionsCoverage(options: {\n  kind: CampaignConversionKind\n  attributed: number | null | undefined\n  total: number | null | undefined\n  /** The kind's records live outside this host, so `total` over-counts. */\n  crossHostTotal?: boolean\n}): CampaignConversionsCoverage | null {\n  const { kind, crossHostTotal } = options\n  if (options.total == null || options.attributed == null) return null\n  const attributed = count(options.attributed)\n  const total = count(options.total)\n  const caveats: CampaignCaveat[] = []\n\n  /*\n   * CLAMPED, and only here at the point of display. The two counts are taken\n   * from two collections a moment apart, so a conversion recorded between\n   * them makes `attributed` briefly exceed `total`; a negative count of\n   * things that did not happen is not a sentence anybody can act on.\n   */\n  const unattributed = Math.max(0, total - attributed)\n\n  caveats.push({\n    id: 'conversions-unattributed-is-a-ceiling',\n    message:\n      `${unattributed.toLocaleString()} of these are not credited to any ` +\n      'campaign. Most arrived without following a campaign link and are ' +\n      'recorded as direct — nothing is guessed from a referrer, and no ' +\n      'campaign is credited for being the most recent one to run. The rest ' +\n      'are records from before campaign attribution was recorded at all, so ' +\n      'read this as an upper bound rather than a count of direct arrivals.',\n  })\n  if (crossHostTotal) {\n    caveats.push({\n      id: 'conversions-total-crosses-hosts',\n      message:\n        'Contacts are shared across every site in this organization, while ' +\n        'attributions belong to one site. The uncredited figure therefore ' +\n        'includes contacts that were created on another site and could ' +\n        'never have been credited here.',\n    })\n  }\n\n  return {\n    kind,\n    attributed,\n    total,\n    unattributed,\n    // Never true while the reasons above stand. The field exists so a screen\n    // reads the model rather than restating its conclusion in JSX.\n    exact: false,\n    caveats,\n  }\n}\n\n/**\n * How a record names the thing it was credited to.\n *\n * The email channel names a campaign document, so the screen can link to it,\n * and so does a sequence touch: the campaign the sequence is in is a\n * container with a page — as does a page touch, the campaign the viewed page\n * is filed under (AGL-3461). The web channel names a label the marketer\n * typed, which is text unless a campaign declares the label as its own; then\n * the record carries that campaign's id too and the screen links it.\n *\n * The `utm_` triple is joined in the order a marketer set it, with the parts\n * that are absent left out rather than filled with a placeholder.\n * `google / cpc` and `google / cpc / (none)` describe the same link, and only\n * one of them invites the reader to look for a campaign called \"(none)\".\n */\nexport function campaignTouchLabel(\n  record: CampaignConversionRecord | null | undefined,\n): string {\n  if (!record) return ''\n  if (\n    record.channel === 'email' ||\n    record.channel === 'sequence' ||\n    record.channel === 'page'\n  ) {\n    return String(record.campaignId ?? '')\n  }\n  const parts = [record.source, record.medium, record.campaign]\n    .map((part) => String(part ?? '').trim())\n    .filter(Boolean)\n  return parts.join(' / ')\n}\n"],"names":["EMAIL_ATTRIBUTION_MODEL","EMAIL_ATTRIBUTION_WINDOW_DAYS","CAMPAIGN_CONVERSION_KINDS","CAMPAIGN_TOUCH_MODEL","CAMPAIGN_VISIT_MINUTES","CAMPAIGN_VISIT_MS","campaignCreditRule","model","windowDays","days","Number","String","CAMPAIGN_CONVERSION_RECORD_KINDS","form","lead","contact","booking","CAMPAIGN_CONVERSION_KIND_COPY","label","note","campaignConversionId","kind","refId","k","ref","includes","count","raw","value","Math","floor","isFinite","campaignConversionsReport","options","rollup","stored","byKind","caveats","kinds","map","copy","undefined","any","some","entry","push","id","message","recorded","campaignConversionsCoverage","crossHostTotal","total","attributed","unattributed","max","toLocaleString","exact","campaignTouchLabel","record","channel","campaignId","parts","source","medium","campaign","part","trim","filter","Boolean","join"],"mappings":"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"}

package/src/lib/model/campaign-report.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @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.
+ */
+/**
+ * WHAT ONE CAMPAIGN SEND DID, AND WHAT ITS SEQUENCES PRODUCED.
+ *
+ * The rate math and the link rollup every bulk sender divides by are the mail
+ * model's (`@aglyn/shared-ui-email-campaigns/model/send-report`); this is the
+ * campaign's reading of them — which population each rate is over, the
+ * caveats that qualify a figure, and the funnel a campaign's sequences report
+ * into. It keeps the rule that module states: a rate names its denominator,
+ * or it is not reported.
+ */
+import { type SendRate, type SendStats } from '@aglyn/shared-ui-email-campaigns/model/send-report';
+/** Why a number the report would otherwise show is being withheld. */
+export interface CampaignCaveat {
+    /** Stable id, so a spec can assert on the caveat rather than its prose. */
+    id: 'delivery-unrecorded' | 'click-tracking-unrecorded' | 'audience-truncated' | 'send-deferred' | 'revenue-denominator-unrecorded' | 'revenue-multi-currency' | 'revenue-mid-flight' | 'revenue-mixed-model' | 'conversions-kinds-overlap' | 'conversions-web-not-rolled-up' | 'conversions-unattributed-is-a-ceiling' | 'conversions-total-crosses-hosts' | 'sequences-funnel-not-summed';
+    message: string;
+}
+/** One population the send measured, for the audience breakdown. */
+export interface CampaignPopulation {
+    id: string;
+    label: string;
+    count: number;
+    /** What this count is a part OF, named. */
+    ofLabel: string;
+    of: number;
+}
+/** Everything the report screen renders, decided here rather than in JSX. */
+export interface CampaignReport {
+    sent: number;
+    recipients: number;
+    delivered: number | null;
+    opens: number;
+    clicks: number;
+    uniqueOpens: number | null;
+    uniqueClicks: number | null;
+    bounced: number;
+    complained: number;
+    unsubscribes: number;
+    /** Rates, each `null` when its denominator is zero or unrecorded. */
+    rates: {
+        /** Accepted by the receiving server, over what the provider accepted. */
+        delivery: SendRate | null;
+        /** Distinct readers who opened, over delivered. */
+        open: SendRate | null;
+        /** Distinct readers who clicked, over delivered. */
+        click: SendRate | null;
+        /**
+         * Distinct clickers over distinct OPENERS — a different question from
+         * `click`, and the one the two get confused for. It answers "of the
+         * people who read it, how many acted", not "of the people who received
+         * it". Reported separately and labelled separately, never as "click
+         * rate".
+         */
+        clickToOpen: SendRate | null;
+        /** Bounced over what the provider accepted. */
+        bounce: SendRate | null;
+        /** Complaints over delivered — the number mailbox providers judge on. */
+        complaint: SendRate | null;
+        /** Unsubscribes through this campaign's link, over delivered. */
+        unsubscribe: SendRate | null;
+    };
+    populations: CampaignPopulation[];
+    caveats: CampaignCaveat[];
+}
+/**
+ * Turns a stored `stats` map into the report.
+ *
+ * ## The denominator decisions, in one place
+ *
+ * - **`delivered`** carries the engagement rates — open, click, complaint,
+ *   unsubscribe. Mail that bounced was never in front of a human, so
+ *   including it in the denominator of an open rate depresses a number that
+ *   describes the audience with a fact about the address list. This is also
+ *   the convention every other tool reports, which matters: a merchant
+ *   comparing our figure with their previous ESP's must be comparing the same
+ *   quantity.
+ * - **`sent`** carries the delivery and bounce rates, because those describe
+ *   what happened to what we handed the provider, and `delivered` is the
+ *   numerator of one of them — a rate cannot be over itself.
+ * - **`uniqueOpens`** is the open-rate numerator, not `opens`. Open EVENTS
+ *   over recipients can exceed 100% the moment one person opens twice, and a
+ *   percentage above 100 is how a reader learns the number means something
+ *   other than what it says. Both are shown; only the distinct count is
+ *   divided.
+ *
+ * ## `delivered` unknown vs. zero
+ *
+ * A campaign predating the delivery webhook records no `delivered` at all.
+ * That is reported as `null` and every rate over it is withheld, with a
+ * caveat naming the reason — rather than substituting `sent`, which would
+ * silently publish the flattered number this module exists to refuse.
+ */
+export declare function campaignReport(stats: SendStats | undefined): CampaignReport;
+/**
+ * The outcomes the runtime credits, in funnel order. An array first, because
+ * the ORDER is the reading order and a second list is a second chance to
+ * leave one out; the union is derived from it.
+ */
+export declare const CAMPAIGN_SEQUENCE_OUTCOMES: readonly ["enrolled", "sent", "replied", "meetings", "converted"];
+export type CampaignSequenceOutcome = (typeof CAMPAIGN_SEQUENCE_OUTCOMES)[number];
+/**
+ * The org collection holding one document per campaign container,
+ * `orgs/{orgId}/campaignSequenceReports/{campaignId}`.
+ */
+export declare const CAMPAIGN_SEQUENCE_REPORTS_COLLECTION = "campaignSequenceReports";
+/** What a reader calls each outcome, and what the count means. */
+export declare const CAMPAIGN_SEQUENCE_OUTCOME_COPY: Readonly<Record<CampaignSequenceOutcome, {
+    label: string;
+    note: string;
+}>>;
+/**
+ * The stored shape of `campaignSequenceReports/{campaignId}`.
+ *
+ * Read-side only, every field optional: another plugin's runtime wrote it,
+ * and a reader that assumed a field was present would throw on the first
+ * document written before the field existed.
+ */
+export interface CampaignSequencesRollup {
+    byOutcome?: Partial<Record<CampaignSequenceOutcome, number>>;
+    /** When the runtime last credited anything, epoch ms. */
+    updatedAtMs?: number;
+}
+/** One outcome's figure on screen. */
+export interface CampaignSequenceFigure {
+    outcome: CampaignSequenceOutcome;
+    label: string;
+    /** The count, or `null` when the rollup holds no entry for the outcome. */
+    value: number | null;
+    note: string;
+}
+/** Everything the Sequences section renders. */
+export interface CampaignSequencesReport {
+    /** Always all five, always in {@link CAMPAIGN_SEQUENCE_OUTCOMES} order. */
+    figures: CampaignSequenceFigure[];
+    /** Whether the rollup document exists at all — see the block header. */
+    recorded: boolean;
+    /** At least one outcome holds a figure. */
+    any: boolean;
+    caveats: CampaignCaveat[];
+}
+/** Turns the stored rollup into the Sequences section. */
+export declare function campaignSequencesReport(rollup: CampaignSequencesRollup | undefined): CampaignSequencesReport;