@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/campaign-forwarding.js

@@ -0,0 +1,332 @@
+/**
+ * @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.
+ */ /**
+ * Carry the campaign across the domain hop (AGL-1731).
+ *
+ * `campaign-attribution.ts` is the READER half of this contract and it works.
+ * This is the half that was missing, and without it the reader was fed
+ * nothing: `aglyn.com` is a tenant published site and `app.aglyn.com` is the
+ * console, a real cross-origin hop, and no code anywhere put a `utm_*`
+ * parameter on a console-bound link. So `users/{uid}.signupCampaign` was
+ * written for exactly one population — visitors whose CTA href had a campaign
+ * typed into it by hand.
+ *
+ * A hand-typed one is worse than none. It is STATIC: `utm_source=google`
+ * authored onto the pricing button attributes every clicker to Google whether
+ * they arrived from Google, from Hacker News or from a bookmark. Confidently
+ * wrong attribution reaches the same spend decisions as absent attribution and
+ * is much harder to notice, because the report looks populated.
+ *
+ * What is needed instead is PER-VISITOR forwarding: the landing page copies
+ * the campaign off its own inbound URL onto the console-bound href, at click
+ * time, for that one visitor.
+ *
+ * ## Why a delegated listener and not `AppLink`
+ *
+ * The same reason `analytics-link-clicks.ts` gives, and it is the reason that
+ * decides this file's shape. The CTAs on `aglyn.com` are authored besigner
+ * content, not repo files; rich-text and Custom HTML anchors are written with
+ * `dangerouslySetInnerHTML` and are plain DOM anchors with no React handler at
+ * all. A prop on `AppLink` would miss them, and reaching them from `AppLink`
+ * would mean `useSearchParams` in a component the console renders on every
+ * page — a dynamic-rendering hazard on statically generated surfaces, paid on
+ * every route to fix a link on one of them. A capture-phase listener on
+ * `document` sees every anchor, costs one listener, and renders nothing.
+ *
+ * ## The two tiers, and why the storage tier is the SECOND one
+ *
+ * A visitor rarely signs up from the page the ad landed on. They land on
+ * `/?utm_source=google&...`, read `/pricing`, then click. By then the campaign
+ * is off the address bar, so reading the live URL at click time alone would
+ * capture only the minority who convert without navigating.
+ *
+ * - **Tier 1 — the live URL.** Read `window.location.search` at click time.
+ *   This touches NO storage: the parameters are already in the page the
+ *   visitor asked for. Nothing is written to their device, so there is nothing
+ *   here to consent to, and it works for every visitor including one who has
+ *   declined analytics.
+ * - **Tier 2 — the first touch of the visit**, in `sessionStorage`, which is
+ *   what survives the walk from the landing page to the pricing page.
+ *
+ * Tier 2 WINS when both exist, because first touch is the question being
+ * asked. Last touch — re-deriving the campaign from whatever URL happens to be
+ * current at signup — answers a different question and would disagree with
+ * GA4's own session attribution.
+ *
+ * ## Why tier 2 is gated on analytics consent, and tier 1 is not
+ *
+ * Tier 2 writes to the visitor's device for an analytics purpose, so it is
+ * `analytics_storage` in the consent-mode sense and it waits for the same
+ * grant the GA tag waits for (AGL-1498). The gate is not re-implemented here
+ * and no consent record is read here: the caller already computes
+ * `analyticsAllowed` for the tag and hands the same boolean down, so there is
+ * one gate and it cannot drift from itself.
+ *
+ * It is deliberately NOT gated on advertising storage. Nothing here reads or
+ * writes an advertising identifier, sets a cookie, or leaves anything that
+ * outlives the tab, and AGL-1649 has advertising denied with no route for a
+ * host to grant it — gating on a permission that cannot currently be given
+ * would be a feature that is dead by construction rather than one that is off.
+ *
+ * **Consent unresolved is not consent denied, and both are falsy.** With
+ * `strictNullChecks` off repo-wide that distinction is the sort that
+ * evaporates, so it is carried as an explicit tri-state: until the caller has
+ * actually resolved the visitor's state, tier 2 neither reads nor writes.
+ * Failing closed here costs an attribution; failing open would write to a
+ * device before the visitor answered.
+ *
+ * ## What is never done
+ *
+ * A value is only ever forwarded if this visitor literally arrived carrying
+ * it. There is no default, no inference from the referrer, and no
+ * `utm_source=direct` — a signup with no campaign must reach the console with
+ * no campaign, so that "arrived from nowhere" and "never asked" stay the
+ * distinct facts `campaign-attribution.ts` keeps them.
+ *
+ * Only links to OUR OWN console origin are touched, and the origin is supplied
+ * by the caller rather than written here — a self-host install points
+ * `NEXT_PUBLIC_CONSOLE_URL` somewhere else entirely. Decorating any other host
+ * would post our campaign labels to a third party, which is a data leak dressed
+ * up as attribution.
+ *
+ * ## One accepted consequence
+ *
+ * The tenant runtime serves `aglyn.com` AND every customer's published site,
+ * so a customer site that links to our signup forwards ITS OWN inbound
+ * campaign — an agency partner's `utm_source=their-newsletter` would land in our
+ * acquisition report describing their spend, not ours. It is not gated on
+ * "is this the operator's marketing host" deliberately: that gate needs a
+ * second configured origin to compare against, and a deployment that forgot to
+ * set it would forward NOTHING while looking perfectly healthy. A silent zero
+ * is the exact failure AGL-1731 is about, and it is worse than a few
+ * mislabelled rows that GA's own Hostname dimension can already separate.
+ */ import { CAMPAIGN_QUERY_KEYS, campaignAttributionQuery, parseCampaignAttribution } from "./campaign-attribution.js";
+/**
+ * Where the first touch of this visit is held. `sessionStorage`, so it dies
+ * with the tab: a campaign is a fact about one visit, and a value that
+ * outlived the visit would start attributing next week's organic return to
+ * this week's ad.
+ */ export const CAMPAIGN_VISIT_STORAGE_KEY = 'aglyn:campaign';
+/**
+ * Whether the visitor has granted analytics storage.
+ *
+ * `null` means NOT YET RESOLVED, and is not the same as `false`. The consent
+ * state is settled client-side after hydration, so there is a window in every
+ * pageview where the answer is genuinely unknown, and treating it as a denial
+ * would be as wrong as treating it as a grant. Tier 2 does nothing in it.
+ */ let storageConsent = null;
+/** The one listener pair on `document`, or null. Held, not flagged — the same
+ * reason `analytics-link-clicks.ts` holds its own: a boolean lets a caller
+ * install over a listener that is still attached, and re-entrant decoration is
+ * harder to see than a double-counted event. */ let installedHandler = null;
+function sessionStore() {
+    if (typeof window === 'undefined') return null;
+    // Touching the property itself can throw, not just its methods.
+    try {
+        var _window_sessionStorage;
+        return (_window_sessionStorage = window.sessionStorage) != null ? _window_sessionStorage : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * The campaign this visit began with, as far as the store can say.
+ *
+ * Re-parsed through the same allowlist that wrote it rather than trusted:
+ * `sessionStorage` is writable by anything running on the page, so the stored
+ * string can claim no more than an inbound URL could — three allowlisted keys,
+ * trimmed, email shapes refused, capped.
+ */ export function readVisitCampaign() {
+    if (storageConsent !== true) return {
+        status: 'none'
+    };
+    const store = sessionStore();
+    if (!store) return {
+        status: 'unreadable'
+    };
+    let raw;
+    try {
+        raw = store.getItem(CAMPAIGN_VISIT_STORAGE_KEY);
+    } catch (unused) {
+        return {
+            status: 'unreadable'
+        };
+    }
+    if (!raw) return {
+        status: 'none'
+    };
+    const campaign = parseCampaignAttribution(new URLSearchParams(raw));
+    return campaign ? {
+        status: 'campaign',
+        campaign
+    } : {
+        status: 'none'
+    };
+}
+/**
+ * Remember the campaign on the current URL as this visit's first touch.
+ *
+ * First touch means FIRST: an existing entry is never replaced. A second
+ * campaign arriving later in the same visit is a link the visitor followed
+ * after we already knew where they came from, and letting it overwrite would
+ * quietly turn this into last-touch.
+ *
+ * Returns what is now remembered so a caller can assert on it.
+ */ export function rememberVisitCampaign(search) {
+    const existing = readVisitCampaign();
+    if (existing.status === 'campaign') return existing.campaign;
+    if (storageConsent !== true) return null;
+    const store = sessionStore();
+    if (!store) return null;
+    const source = typeof search === 'string' ? search : typeof window === 'undefined' ? '' : window.location.search;
+    const campaign = parseCampaignAttribution(new URLSearchParams(source));
+    if (!campaign) return null;
+    try {
+        store.setItem(CAMPAIGN_VISIT_STORAGE_KEY, campaignAttributionQuery(campaign));
+    } catch (unused) {
+        // A store that refuses the write costs the walk from the landing page to
+        // the pricing page, never the click itself — tier 1 still carries a
+        // visitor who converts without navigating.
+        return null;
+    }
+    return campaign;
+}
+/**
+ * Tell this module what the visitor's analytics consent state is.
+ *
+ * Called by whoever already computed it for the tag, on every render, so a
+ * grant seeds the first touch the moment it is given and a WITHDRAWAL takes
+ * effect immediately: the stored value is dropped, not merely ignored. A
+ * visitor who changes their mind mid-visit should not leave the thing they
+ * withdrew consent for sitting on their device.
+ */ export function setCampaignForwardingConsent(allowed) {
+    storageConsent = allowed === true ? true : allowed === false ? false : null;
+    if (storageConsent === true) {
+        rememberVisitCampaign();
+        return;
+    }
+    if (storageConsent === false) {
+        const store = sessionStore();
+        if (!store) return;
+        try {
+            store.removeItem(CAMPAIGN_VISIT_STORAGE_KEY);
+        } catch (unused) {
+        // Nothing else to try, and a failed cleanup must not break the page.
+        }
+    }
+}
+/**
+ * The campaign to forward, first touch preferred.
+ *
+ * The `unreadable` case falls through to the live URL rather than to nothing,
+ * which is the point of carrying that state at all: a broken store degrades
+ * this to tier 1 rather than to silence.
+ */ export function campaignToForward(search) {
+    const stored = readVisitCampaign();
+    if (stored.status === 'campaign') return stored.campaign;
+    const live = typeof search === 'string' ? search : typeof window === 'undefined' ? '' : window.location.search;
+    return parseCampaignAttribution(new URLSearchParams(live));
+}
+function normalizeOrigin(value) {
+    if (!value) return '';
+    try {
+        return new URL(value).origin;
+    } catch (unused) {
+        return '';
+    }
+}
+/**
+ * The href a console-bound link should carry for this visitor, or null to
+ * leave it exactly as authored.
+ *
+ * Null — rather than "the href unchanged" — so that a caller cannot write back
+ * a value it did not mean to change, and so a test can tell "decided not to
+ * touch this" from "touched it and produced the same string".
+ *
+ * The three keys are replaced WHOLESALE, never merged key by key. A visitor
+ * who arrived with only `utm_source=hn` clicking a button authored with all
+ * three must not produce `source=hn` married to the author's `campaign=`: that
+ * row describes an event that never happened. Everything else on the href —
+ * `plan`, `interval`, the AGL-1535 intent — is preserved untouched.
+ */ export function decorateCampaignHref(href, baseHref, consoleOrigin, campaign) {
+    if (!campaign) return null;
+    const origin = normalizeOrigin(consoleOrigin);
+    if (!origin) return null;
+    let url;
+    try {
+        url = new URL(href, baseHref);
+    } catch (unused) {
+        return null;
+    }
+    if (url.origin !== origin) return null;
+    for (const key of CAMPAIGN_QUERY_KEYS)url.searchParams.delete(key);
+    const query = new URLSearchParams(campaignAttributionQuery(campaign));
+    query.forEach((value, key)=>url.searchParams.set(key, value));
+    const next = url.toString();
+    return next === href ? null : next;
+}
+/**
+ * Start forwarding the campaign onto console-bound links on this page.
+ *
+ * Idempotent and safe to call during render, the same contract as
+ * `installLinkClickTracking` and for the same AGL-1550 reason: an effect only
+ * runs if React commits, and a page that renders without committing would
+ * otherwise ship links with no campaign on them.
+ *
+ * Both `pointerdown` and `click` are listened for, in capture phase.
+ * `pointerdown` is what covers a middle-click, a modifier-click into a new
+ * tab, and "Copy link address" from the context menu — all of which read the
+ * href without ever firing `click`. `click` is what covers keyboard
+ * activation, which fires no pointer event at all. Decoration is idempotent,
+ * so a plain left click doing both is not a problem.
+ *
+ * Returns an uninstall function for tests and for a caller that owns the page
+ * lifecycle.
+ */ export function installCampaignForwarding(options) {
+    if (typeof document === 'undefined' || typeof window === 'undefined') {
+        return ()=>undefined;
+    }
+    if (installedHandler) return ()=>undefined;
+    const origin = normalizeOrigin(options == null ? void 0 : options.consoleOrigin);
+    if (!origin) return ()=>undefined;
+    const onActivate = (event)=>{
+        try {
+            const target = event.target;
+            if (!target || typeof target.closest !== 'function') return;
+            const anchor = target.closest('a[href]');
+            if (!anchor) return;
+            const decorated = decorateCampaignHref(anchor.getAttribute('href') || '', window.location.href, origin, campaignToForward());
+            if (decorated) anchor.setAttribute('href', decorated);
+        } catch (unused) {
+        // Attribution never breaks a navigation. A link that throws here would
+        // be a link that does not work, which costs more than the campaign does.
+        }
+    };
+    installedHandler = onActivate;
+    document.addEventListener('pointerdown', onActivate, true);
+    document.addEventListener('click', onActivate, true);
+    return resetCampaignForwarding;
+}
+/** Test seam — removes both listeners, forgets them, and forgets consent. */ export function resetCampaignForwarding() {
+    if (installedHandler && typeof document !== 'undefined') {
+        document.removeEventListener('pointerdown', installedHandler, true);
+        document.removeEventListener('click', installedHandler, true);
+    }
+    installedHandler = null;
+    storageConsent = null;
+}
+
+//# sourceMappingURL=campaign-forwarding.js.map

package/src/lib/app-utils/campaign-forwarding.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-forwarding.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 * Carry the campaign across the domain hop (AGL-1731).\n *\n * `campaign-attribution.ts` is the READER half of this contract and it works.\n * This is the half that was missing, and without it the reader was fed\n * nothing: `aglyn.com` is a tenant published site and `app.aglyn.com` is the\n * console, a real cross-origin hop, and no code anywhere put a `utm_*`\n * parameter on a console-bound link. So `users/{uid}.signupCampaign` was\n * written for exactly one population — visitors whose CTA href had a campaign\n * typed into it by hand.\n *\n * A hand-typed one is worse than none. It is STATIC: `utm_source=google`\n * authored onto the pricing button attributes every clicker to Google whether\n * they arrived from Google, from Hacker News or from a bookmark. Confidently\n * wrong attribution reaches the same spend decisions as absent attribution and\n * is much harder to notice, because the report looks populated.\n *\n * What is needed instead is PER-VISITOR forwarding: the landing page copies\n * the campaign off its own inbound URL onto the console-bound href, at click\n * time, for that one visitor.\n *\n * ## Why a delegated listener and not `AppLink`\n *\n * The same reason `analytics-link-clicks.ts` gives, and it is the reason that\n * decides this file's shape. The CTAs on `aglyn.com` are authored besigner\n * content, not repo files; rich-text and Custom HTML anchors are written with\n * `dangerouslySetInnerHTML` and are plain DOM anchors with no React handler at\n * all. A prop on `AppLink` would miss them, and reaching them from `AppLink`\n * would mean `useSearchParams` in a component the console renders on every\n * page — a dynamic-rendering hazard on statically generated surfaces, paid on\n * every route to fix a link on one of them. A capture-phase listener on\n * `document` sees every anchor, costs one listener, and renders nothing.\n *\n * ## The two tiers, and why the storage tier is the SECOND one\n *\n * A visitor rarely signs up from the page the ad landed on. They land on\n * `/?utm_source=google&...`, read `/pricing`, then click. By then the campaign\n * is off the address bar, so reading the live URL at click time alone would\n * capture only the minority who convert without navigating.\n *\n * - **Tier 1 — the live URL.** Read `window.location.search` at click time.\n *   This touches NO storage: the parameters are already in the page the\n *   visitor asked for. Nothing is written to their device, so there is nothing\n *   here to consent to, and it works for every visitor including one who has\n *   declined analytics.\n * - **Tier 2 — the first touch of the visit**, in `sessionStorage`, which is\n *   what survives the walk from the landing page to the pricing page.\n *\n * Tier 2 WINS when both exist, because first touch is the question being\n * asked. Last touch — re-deriving the campaign from whatever URL happens to be\n * current at signup — answers a different question and would disagree with\n * GA4's own session attribution.\n *\n * ## Why tier 2 is gated on analytics consent, and tier 1 is not\n *\n * Tier 2 writes to the visitor's device for an analytics purpose, so it is\n * `analytics_storage` in the consent-mode sense and it waits for the same\n * grant the GA tag waits for (AGL-1498). The gate is not re-implemented here\n * and no consent record is read here: the caller already computes\n * `analyticsAllowed` for the tag and hands the same boolean down, so there is\n * one gate and it cannot drift from itself.\n *\n * It is deliberately NOT gated on advertising storage. Nothing here reads or\n * writes an advertising identifier, sets a cookie, or leaves anything that\n * outlives the tab, and AGL-1649 has advertising denied with no route for a\n * host to grant it — gating on a permission that cannot currently be given\n * would be a feature that is dead by construction rather than one that is off.\n *\n * **Consent unresolved is not consent denied, and both are falsy.** With\n * `strictNullChecks` off repo-wide that distinction is the sort that\n * evaporates, so it is carried as an explicit tri-state: until the caller has\n * actually resolved the visitor's state, tier 2 neither reads nor writes.\n * Failing closed here costs an attribution; failing open would write to a\n * device before the visitor answered.\n *\n * ## What is never done\n *\n * A value is only ever forwarded if this visitor literally arrived carrying\n * it. There is no default, no inference from the referrer, and no\n * `utm_source=direct` — a signup with no campaign must reach the console with\n * no campaign, so that \"arrived from nowhere\" and \"never asked\" stay the\n * distinct facts `campaign-attribution.ts` keeps them.\n *\n * Only links to OUR OWN console origin are touched, and the origin is supplied\n * by the caller rather than written here — a self-host install points\n * `NEXT_PUBLIC_CONSOLE_URL` somewhere else entirely. Decorating any other host\n * would post our campaign labels to a third party, which is a data leak dressed\n * up as attribution.\n *\n * ## One accepted consequence\n *\n * The tenant runtime serves `aglyn.com` AND every customer's published site,\n * so a customer site that links to our signup forwards ITS OWN inbound\n * campaign — an agency partner's `utm_source=their-newsletter` would land in our\n * acquisition report describing their spend, not ours. It is not gated on\n * \"is this the operator's marketing host\" deliberately: that gate needs a\n * second configured origin to compare against, and a deployment that forgot to\n * set it would forward NOTHING while looking perfectly healthy. A silent zero\n * is the exact failure AGL-1731 is about, and it is worse than a few\n * mislabelled rows that GA's own Hostname dimension can already separate.\n */\n\nimport {\n  CAMPAIGN_QUERY_KEYS,\n  campaignAttributionQuery,\n  parseCampaignAttribution,\n  type CampaignAttribution,\n} from './campaign-attribution'\n\n/**\n * Where the first touch of this visit is held. `sessionStorage`, so it dies\n * with the tab: a campaign is a fact about one visit, and a value that\n * outlived the visit would start attributing next week's organic return to\n * this week's ad.\n */\nexport const CAMPAIGN_VISIT_STORAGE_KEY = 'aglyn:campaign'\n\n/**\n * What a read of the first-touch store produced.\n *\n * Three states rather than \"a campaign or null\", and the third is the whole\n * point. `sessionStorage` throws outright in some privacy modes, and a\n * `catch` that returned null would report \"this visitor named no campaign\" —\n * indistinguishable from an organic arrival, which is how an unreadable source\n * becomes a measured zero. `unreadable` is a different answer and the caller\n * treats it differently: it falls through to the live URL instead of\n * concluding anything.\n */\nexport type VisitCampaignRead =\n  | { status: 'campaign'; campaign: CampaignAttribution }\n  | { status: 'none' }\n  | { status: 'unreadable' }\n\n/**\n * Whether the visitor has granted analytics storage.\n *\n * `null` means NOT YET RESOLVED, and is not the same as `false`. The consent\n * state is settled client-side after hydration, so there is a window in every\n * pageview where the answer is genuinely unknown, and treating it as a denial\n * would be as wrong as treating it as a grant. Tier 2 does nothing in it.\n */\nlet storageConsent: boolean | null = null\n\n/** The one listener pair on `document`, or null. Held, not flagged — the same\n * reason `analytics-link-clicks.ts` holds its own: a boolean lets a caller\n * install over a listener that is still attached, and re-entrant decoration is\n * harder to see than a double-counted event. */\nlet installedHandler: ((event: Event) => void) | null = null\n\nfunction sessionStore(): Storage | null {\n  if (typeof window === 'undefined') return null\n  // Touching the property itself can throw, not just its methods.\n  try {\n    return window.sessionStorage ?? null\n  } catch {\n    return null\n  }\n}\n\n/**\n * The campaign this visit began with, as far as the store can say.\n *\n * Re-parsed through the same allowlist that wrote it rather than trusted:\n * `sessionStorage` is writable by anything running on the page, so the stored\n * string can claim no more than an inbound URL could — three allowlisted keys,\n * trimmed, email shapes refused, capped.\n */\nexport function readVisitCampaign(): VisitCampaignRead {\n  if (storageConsent !== true) return { status: 'none' }\n  const store = sessionStore()\n  if (!store) return { status: 'unreadable' }\n  let raw: string | null\n  try {\n    raw = store.getItem(CAMPAIGN_VISIT_STORAGE_KEY)\n  } catch {\n    return { status: 'unreadable' }\n  }\n  if (!raw) return { status: 'none' }\n  const campaign = parseCampaignAttribution(new URLSearchParams(raw))\n  return campaign ? { status: 'campaign', campaign } : { status: 'none' }\n}\n\n/**\n * Remember the campaign on the current URL as this visit's first touch.\n *\n * First touch means FIRST: an existing entry is never replaced. A second\n * campaign arriving later in the same visit is a link the visitor followed\n * after we already knew where they came from, and letting it overwrite would\n * quietly turn this into last-touch.\n *\n * Returns what is now remembered so a caller can assert on it.\n */\nexport function rememberVisitCampaign(search?: string): CampaignAttribution | null {\n  const existing = readVisitCampaign()\n  if (existing.status === 'campaign') return existing.campaign\n  if (storageConsent !== true) return null\n  const store = sessionStore()\n  if (!store) return null\n  const source =\n    typeof search === 'string'\n      ? search\n      : typeof window === 'undefined'\n        ? ''\n        : window.location.search\n  const campaign = parseCampaignAttribution(new URLSearchParams(source))\n  if (!campaign) return null\n  try {\n    store.setItem(CAMPAIGN_VISIT_STORAGE_KEY, campaignAttributionQuery(campaign))\n  } catch {\n    // A store that refuses the write costs the walk from the landing page to\n    // the pricing page, never the click itself — tier 1 still carries a\n    // visitor who converts without navigating.\n    return null\n  }\n  return campaign\n}\n\n/**\n * Tell this module what the visitor's analytics consent state is.\n *\n * Called by whoever already computed it for the tag, on every render, so a\n * grant seeds the first touch the moment it is given and a WITHDRAWAL takes\n * effect immediately: the stored value is dropped, not merely ignored. A\n * visitor who changes their mind mid-visit should not leave the thing they\n * withdrew consent for sitting on their device.\n */\nexport function setCampaignForwardingConsent(allowed: boolean | null): void {\n  storageConsent = allowed === true ? true : allowed === false ? false : null\n  if (storageConsent === true) {\n    rememberVisitCampaign()\n    return\n  }\n  if (storageConsent === false) {\n    const store = sessionStore()\n    if (!store) return\n    try {\n      store.removeItem(CAMPAIGN_VISIT_STORAGE_KEY)\n    } catch {\n      // Nothing else to try, and a failed cleanup must not break the page.\n    }\n  }\n}\n\n/**\n * The campaign to forward, first touch preferred.\n *\n * The `unreadable` case falls through to the live URL rather than to nothing,\n * which is the point of carrying that state at all: a broken store degrades\n * this to tier 1 rather than to silence.\n */\nexport function campaignToForward(search?: string): CampaignAttribution | null {\n  const stored = readVisitCampaign()\n  if (stored.status === 'campaign') return stored.campaign\n  const live =\n    typeof search === 'string'\n      ? search\n      : typeof window === 'undefined'\n        ? ''\n        : window.location.search\n  return parseCampaignAttribution(new URLSearchParams(live))\n}\n\nfunction normalizeOrigin(value: string | null | undefined): string {\n  if (!value) return ''\n  try {\n    return new URL(value).origin\n  } catch {\n    return ''\n  }\n}\n\n/**\n * The href a console-bound link should carry for this visitor, or null to\n * leave it exactly as authored.\n *\n * Null — rather than \"the href unchanged\" — so that a caller cannot write back\n * a value it did not mean to change, and so a test can tell \"decided not to\n * touch this\" from \"touched it and produced the same string\".\n *\n * The three keys are replaced WHOLESALE, never merged key by key. A visitor\n * who arrived with only `utm_source=hn` clicking a button authored with all\n * three must not produce `source=hn` married to the author's `campaign=`: that\n * row describes an event that never happened. Everything else on the href —\n * `plan`, `interval`, the AGL-1535 intent — is preserved untouched.\n */\nexport function decorateCampaignHref(\n  href: string,\n  baseHref: string,\n  consoleOrigin: string,\n  campaign: CampaignAttribution | null,\n): string | null {\n  if (!campaign) return null\n  const origin = normalizeOrigin(consoleOrigin)\n  if (!origin) return null\n  let url: URL\n  try {\n    url = new URL(href, baseHref)\n  } catch {\n    return null\n  }\n  if (url.origin !== origin) return null\n  for (const key of CAMPAIGN_QUERY_KEYS) url.searchParams.delete(key)\n  const query = new URLSearchParams(campaignAttributionQuery(campaign))\n  query.forEach((value, key) => url.searchParams.set(key, value))\n  const next = url.toString()\n  return next === href ? null : next\n}\n\n/**\n * Start forwarding the campaign onto console-bound links on this page.\n *\n * Idempotent and safe to call during render, the same contract as\n * `installLinkClickTracking` and for the same AGL-1550 reason: an effect only\n * runs if React commits, and a page that renders without committing would\n * otherwise ship links with no campaign on them.\n *\n * Both `pointerdown` and `click` are listened for, in capture phase.\n * `pointerdown` is what covers a middle-click, a modifier-click into a new\n * tab, and \"Copy link address\" from the context menu — all of which read the\n * href without ever firing `click`. `click` is what covers keyboard\n * activation, which fires no pointer event at all. Decoration is idempotent,\n * so a plain left click doing both is not a problem.\n *\n * Returns an uninstall function for tests and for a caller that owns the page\n * lifecycle.\n */\nexport function installCampaignForwarding(options: {\n  consoleOrigin: string\n}): () => void {\n  if (typeof document === 'undefined' || typeof window === 'undefined') {\n    return () => undefined\n  }\n  if (installedHandler) return () => undefined\n  const origin = normalizeOrigin(options?.consoleOrigin)\n  if (!origin) return () => undefined\n\n  const onActivate = (event: Event) => {\n    try {\n      const target = event.target as Element | null\n      if (!target || typeof target.closest !== 'function') return\n      const anchor = target.closest('a[href]')\n      if (!anchor) return\n      const decorated = decorateCampaignHref(\n        anchor.getAttribute('href') || '',\n        window.location.href,\n        origin,\n        campaignToForward(),\n      )\n      if (decorated) anchor.setAttribute('href', decorated)\n    } catch {\n      // Attribution never breaks a navigation. A link that throws here would\n      // be a link that does not work, which costs more than the campaign does.\n    }\n  }\n\n  installedHandler = onActivate\n  document.addEventListener('pointerdown', onActivate, true)\n  document.addEventListener('click', onActivate, true)\n  return resetCampaignForwarding\n}\n\n/** Test seam — removes both listeners, forgets them, and forgets consent. */\nexport function resetCampaignForwarding(): void {\n  if (installedHandler && typeof document !== 'undefined') {\n    document.removeEventListener('pointerdown', installedHandler, true)\n    document.removeEventListener('click', installedHandler, true)\n  }\n  installedHandler = null\n  storageConsent = null\n}\n"],"names":["CAMPAIGN_QUERY_KEYS","campaignAttributionQuery","parseCampaignAttribution","CAMPAIGN_VISIT_STORAGE_KEY","storageConsent","installedHandler","sessionStore","window","sessionStorage","readVisitCampaign","status","store","raw","getItem","campaign","URLSearchParams","rememberVisitCampaign","search","existing","source","location","setItem","setCampaignForwardingConsent","allowed","removeItem","campaignToForward","stored","live","normalizeOrigin","value","URL","origin","decorateCampaignHref","href","baseHref","consoleOrigin","url","key","searchParams","delete","query","forEach","set","next","toString","installCampaignForwarding","options","document","undefined","onActivate","event","target","closest","anchor","decorated","getAttribute","setAttribute","addEventListener","resetCampaignForwarding","removeEventListener"],"mappings":"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"}

package/src/lib/app-utils/campaign-membership.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The field naming the campaigns a resource belongs to.
+ *
+ * Not `emailCampaignId`, which is the SEND's field: on a send document the
+ * word `campaignId` already means the send's own id — it is what `cid`
+ * carries into every unsubscribe footer — so that collection needed a
+ * different word. A form, a screen and a contact have no second meaning for
+ * it, and the plural says the resource may be in more than one.
+ */
+export declare const CAMPAIGN_MEMBERSHIP_FIELD = "campaignIds";
+/**
+ * How many campaigns one resource may name.
+ *
+ * A ceiling on the FIELD, not on the product: an array Firestore has to index
+ * on every write is not the place to discover that a script has been adding
+ * an id a day for a year. Twenty is far past what a person assigns by hand
+ * and far short of anything that costs a write.
+ */
+export declare const CAMPAIGN_MEMBERSHIP_CAP = 20;
+/**
+ * A stored membership array as a clean list of ids.
+ *
+ * Deduped, trimmed, non-strings dropped, capped. Every reader goes through
+ * this because the field is written by three consoles and one automation
+ * step, and a surface that trusted the raw value would render `undefined` as
+ * a chip the first time one of them wrote a blank.
+ */
+export declare function normalizeCampaignIds(raw: unknown): string[];
+/**
+ * The campaigns a HOST resource — a form, a screen — belongs to.
+ *
+ * Host resources carry the field at the top of the document: they belong to
+ * one site, which is the same site the campaign belongs to, so there is no
+ * second holder to keep the edge away from.
+ */
+export declare function readCampaignIds(resource: Record<string, unknown> | null | undefined): string[];
+/**
+ * The dotted path to a contact's membership, inside ONE holder's facet.
+ *
+ * A contact document is shared by every site in the org — one human who
+ * touched two sites is one row — and almost nothing on it is legitimately
+ * shared. Which campaigns a merchant has filed a person under is that
+ * merchant's business record on exactly the footing their notes and tags are,
+ * so it lives at `facets.{groupId}.campaignIds` and not at the top of the
+ * document, where every other site in an agency's account could read it.
+ */
+export declare function contactCampaignFieldPath(groupId: string): string;
+/** The campaigns ONE holder has filed this contact under. */
+export declare function readContactCampaignIds(contact: Record<string, unknown> | null | undefined, groupId: string): string[];
+/**
+ * The membership a save should write, given what is on screen.
+ *
+ * Pure, and shared by the three consoles that offer the picker, because the
+ * decision each of them makes is identical and is not obvious: an EMPTY
+ * selection has to be stored as an empty array rather than as a removed
+ * field.
+ *
+ * Removing the field would read the same to every surface here — the readers
+ * above answer `[]` either way — and would be wrong for the one reader that
+ * is not a surface. `campaign-manage.ts` finds a campaign's members with
+ * `array-contains`, which matches on the automatic single-field index; that
+ * index has an entry only while the array does, so the two shapes are the
+ * same to a reader and different to a writer only in cost. Storing `[]` keeps
+ * one shape for "belongs to no campaign" across every writer, which is the
+ * property the send collection's own detach comment argues for one field
+ * over.
+ *
+ * @returns the value to store under {@link CAMPAIGN_MEMBERSHIP_FIELD}.
+ */
+export declare function campaignMembershipValue(selected: readonly string[]): string[];
+/**
+ * Whether a document's stored membership already says what a save would.
+ *
+ * Order-insensitive: a picker hands back its options' order and the stored
+ * array is in the order it was written, so comparing them literally would
+ * report a change on every open and leave Save permanently enabled.
+ */
+export declare function campaignMembershipUnchanged(stored: readonly string[], selected: readonly string[]): boolean;
+/**
+ * The host subcollections whose documents may name a campaign.
+ *
+ * The list a campaign's deletion walks, and the list this feature's coverage
+ * spec reads — so a collection that grows the picker without growing the
+ * detach fails the build rather than shipping a campaign whose removal leaves
+ * that collection pointing at nothing.
+ *
+ * Contacts are deliberately NOT here. They live on the org
+ * (`orgs/{orgId}/contacts`), not the host, and carry the field inside a
+ * per-holder facet — so they are detached by their own pass, against a field
+ * path that names the group.
+ */
+export declare const CAMPAIGN_MEMBER_HOST_COLLECTIONS: readonly ["forms", "screens"];
+export type CampaignMemberHostCollection = (typeof CAMPAIGN_MEMBER_HOST_COLLECTIONS)[number];

package/src/lib/app-utils/campaign-membership.js

@@ -0,0 +1,176 @@
+/**
+ * @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 ELSE IS IN A CAMPAIGN: the edge between a campaign and the forms,
+ * screens and people a push is coordinated across.
+ *
+ * ## The edge is a field on the RESOURCE, not a list on the campaign
+ *
+ * A campaign container lives at `hosts/{hostId}/emailCampaigns/{campaignId}`
+ * and names nothing outside itself. A send joins one by carrying
+ * `emailCampaignId`; every other member joins the same way, through
+ * {@link CAMPAIGN_MEMBERSHIP_FIELD} on its own document.
+ *
+ * Three properties decide it, and all three point the same way:
+ *
+ *  - **Reading is free where it is asked.** A form's own page reads the form
+ *    document to draw anything at all, so the campaign comes with it. A
+ *    membership collection under the campaign would make "which campaign is
+ *    this in" a query issued on mount by every resource page, for a fact one
+ *    field already carries.
+ *  - **The reduction is already gated this way.** `campaign-manage.ts` clears
+ *    `emailCampaignId` from every send before it removes a container, so no
+ *    send is left naming one that is gone. Extending that pass to the
+ *    membership field is the SAME mechanism; a membership collection would be
+ *    a second, different deletion story beside it.
+ *  - **Deleting a MEMBER can leave nothing behind.** The campaign holds no
+ *    list, so a deleted form takes its own edge with it. This matters most on
+ *    a contact: an erasure removes the document, and a membership row stored
+ *    anywhere else would survive it holding the id of a person who asked to
+ *    be forgotten.
+ *
+ * ## Plural, because a landing page outlives one campaign
+ *
+ * The field is an ARRAY. A signup form built for the spring push is the same
+ * form the summer push places, and a single-valued field would make the
+ * second assignment silently erase the first — a campaign losing a member
+ * with nothing on screen to say so. The automation step that has always
+ * written this edge (`assignCampaign`) already used `arrayUnion`, so the
+ * product has treated it as many-to-many from the start.
+ *
+ * ## Ids, never names
+ *
+ * A campaign's name is editable, and every reader here resolves the name from
+ * the campaign document at read time. Renaming a campaign therefore moves no
+ * membership: the stored value is the container's document id, which nothing
+ * rewrites.
+ */ import { contactFacetPath, readContactFacet } from "./contacts.js";
+/**
+ * The field naming the campaigns a resource belongs to.
+ *
+ * Not `emailCampaignId`, which is the SEND's field: on a send document the
+ * word `campaignId` already means the send's own id — it is what `cid`
+ * carries into every unsubscribe footer — so that collection needed a
+ * different word. A form, a screen and a contact have no second meaning for
+ * it, and the plural says the resource may be in more than one.
+ */ export const CAMPAIGN_MEMBERSHIP_FIELD = 'campaignIds';
+/**
+ * How many campaigns one resource may name.
+ *
+ * A ceiling on the FIELD, not on the product: an array Firestore has to index
+ * on every write is not the place to discover that a script has been adding
+ * an id a day for a year. Twenty is far past what a person assigns by hand
+ * and far short of anything that costs a write.
+ */ export const CAMPAIGN_MEMBERSHIP_CAP = 20;
+/**
+ * A stored membership array as a clean list of ids.
+ *
+ * Deduped, trimmed, non-strings dropped, capped. Every reader goes through
+ * this because the field is written by three consoles and one automation
+ * step, and a surface that trusted the raw value would render `undefined` as
+ * a chip the first time one of them wrote a blank.
+ */ export function normalizeCampaignIds(raw) {
+    if (!Array.isArray(raw)) return [];
+    const seen = [];
+    for (const entry of raw){
+        if (typeof entry !== 'string') continue;
+        const id = entry.trim();
+        if (!id || seen.includes(id)) continue;
+        seen.push(id);
+        if (seen.length >= CAMPAIGN_MEMBERSHIP_CAP) break;
+    }
+    return seen;
+}
+/**
+ * The campaigns a HOST resource — a form, a screen — belongs to.
+ *
+ * Host resources carry the field at the top of the document: they belong to
+ * one site, which is the same site the campaign belongs to, so there is no
+ * second holder to keep the edge away from.
+ */ export function readCampaignIds(resource) {
+    return normalizeCampaignIds((resource != null ? resource : {})[CAMPAIGN_MEMBERSHIP_FIELD]);
+}
+/**
+ * The dotted path to a contact's membership, inside ONE holder's facet.
+ *
+ * A contact document is shared by every site in the org — one human who
+ * touched two sites is one row — and almost nothing on it is legitimately
+ * shared. Which campaigns a merchant has filed a person under is that
+ * merchant's business record on exactly the footing their notes and tags are,
+ * so it lives at `facets.{groupId}.campaignIds` and not at the top of the
+ * document, where every other site in an agency's account could read it.
+ */ export function contactCampaignFieldPath(groupId) {
+    return contactFacetPath(groupId, CAMPAIGN_MEMBERSHIP_FIELD);
+}
+/** The campaigns ONE holder has filed this contact under. */ export function readContactCampaignIds(contact, groupId) {
+    return normalizeCampaignIds(readContactFacet(contact, groupId).campaignIds);
+}
+/**
+ * The membership a save should write, given what is on screen.
+ *
+ * Pure, and shared by the three consoles that offer the picker, because the
+ * decision each of them makes is identical and is not obvious: an EMPTY
+ * selection has to be stored as an empty array rather than as a removed
+ * field.
+ *
+ * Removing the field would read the same to every surface here — the readers
+ * above answer `[]` either way — and would be wrong for the one reader that
+ * is not a surface. `campaign-manage.ts` finds a campaign's members with
+ * `array-contains`, which matches on the automatic single-field index; that
+ * index has an entry only while the array does, so the two shapes are the
+ * same to a reader and different to a writer only in cost. Storing `[]` keeps
+ * one shape for "belongs to no campaign" across every writer, which is the
+ * property the send collection's own detach comment argues for one field
+ * over.
+ *
+ * @returns the value to store under {@link CAMPAIGN_MEMBERSHIP_FIELD}.
+ */ export function campaignMembershipValue(selected) {
+    return normalizeCampaignIds(selected);
+}
+/**
+ * Whether a document's stored membership already says what a save would.
+ *
+ * Order-insensitive: a picker hands back its options' order and the stored
+ * array is in the order it was written, so comparing them literally would
+ * report a change on every open and leave Save permanently enabled.
+ */ export function campaignMembershipUnchanged(stored, selected) {
+    if (stored.length !== selected.length) return false;
+    const sortedStored = [
+        ...stored
+    ].sort();
+    const sortedSelected = [
+        ...selected
+    ].sort();
+    return sortedStored.every((id, index)=>id === sortedSelected[index]);
+}
+/**
+ * The host subcollections whose documents may name a campaign.
+ *
+ * The list a campaign's deletion walks, and the list this feature's coverage
+ * spec reads — so a collection that grows the picker without growing the
+ * detach fails the build rather than shipping a campaign whose removal leaves
+ * that collection pointing at nothing.
+ *
+ * Contacts are deliberately NOT here. They live on the org
+ * (`orgs/{orgId}/contacts`), not the host, and carry the field inside a
+ * per-holder facet — so they are detached by their own pass, against a field
+ * path that names the group.
+ */ export const CAMPAIGN_MEMBER_HOST_COLLECTIONS = [
+    'forms',
+    'screens'
+];
+
+//# sourceMappingURL=campaign-membership.js.map