@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,117 @@
+/**
+ * @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.
+ */
+/**
+ * Where an account came from (AGL-1731) — the campaign contract between the
+ * marketing site's links and the console's signup.
+ *
+ * Until this existed a paid click, an organic visit and a partner link
+ * arrived indistinguishable: `sign_up` carried `method` and nothing else, so
+ * no report could say which spend produced a customer. That is tolerable
+ * while nothing is being spent and not tolerable the day advertising starts,
+ * because the measurement has to exist BEFORE the traffic — a signup that
+ * lands unattributed is unattributed forever.
+ *
+ * ## Why an allowlist, and why exactly three
+ *
+ * `utm_source`, `utm_medium` and `utm_campaign` are the three axes an ad
+ * report is read on: which channel, what kind of placement, which push. They
+ * are also the three the marketing site can be told to emit without further
+ * decisions.
+ *
+ * `utm_term` and `utm_content` are deliberately OUT, matching the refusal the
+ * tenant's own first-party collector already made for its visitors
+ * (`apps/tenant/app/api/analytics/collect/route.ts`): keyword- and
+ * variant-level labels multiply cardinality without answering a question
+ * anyone asks of a signup, and a keyword string is the most likely of the
+ * five to carry something a person typed. `gclid` and bare `ref` are out for
+ * that same cardinality reason. Not for a privacy one: the property runs ads
+ * personalization ON in every region, and Google's own auto-tagging already
+ * carries the click identifier into it, so re-collecting `gclid` here would
+ * duplicate a field the platform owns rather than withhold anything.
+ *
+ * The allowlist is the privacy mechanism, not a convenience. A parser that
+ * copied "the campaign-ish parameters" would be one marketing link away from
+ * storing `?email=` against a person, and the standing rule is that personal
+ * data never travels in a URL parameter in the first place.
+ *
+ * ## Two exits, and only one of them is already guarded
+ *
+ * A parsed campaign leaves this process twice: onto the GA4 `sign_up` hit,
+ * and into `users/{uid}` so revenue can be attributed to it months later.
+ * Only the first passes `sanitizeEventParams`. The Firestore write does not,
+ * so the scrub — email shape refused, length capped, blanks dropped — lives
+ * HERE, on the way in, and both exits inherit it.
+ *
+ * ## Why the wire form is what gets stored
+ *
+ * Same contract as the AGL-1535 plan intent it rides beside: the stored value
+ * is the query string, re-parsed by this parser on the way out. `users/{uid}`
+ * is owner-writable, so a stored field is a client-FORGEABLE field. Re-parsing
+ * means a hand-edited document can claim no more than a hand-edited URL could,
+ * which is a marketing label and nothing that touches entitlement.
+ */
+/**
+ * The URL parameter names, in report order. Exported because the marketing
+ * site's links, the stored wire form and this parser all have to spell them
+ * identically — two spellings would read as two dimensions in GA4 and split
+ * every report in half.
+ */
+export declare const CAMPAIGN_QUERY_KEYS: readonly ["utm_source", "utm_medium", "utm_campaign"];
+/** A campaign, with every field optional — a partial one is still worth having. */
+export interface CampaignAttribution {
+    /** `utm_source` — the channel: `google`, `hn`, a partner's name. */
+    source?: string;
+    /** `utm_medium` — the kind of placement: `cpc`, `email`, `referral`. */
+    medium?: string;
+    /** `utm_campaign` — which push: `sept-launch`. */
+    campaign?: string;
+}
+/** What a Server Component holds before it has a `URLSearchParams`. */
+export type CampaignParamSource = URLSearchParams | Record<string, string | string[] | undefined> | null | undefined;
+/**
+ * Read the campaign off a signup URL, or null when it names none.
+ *
+ * Null rather than `{}` so a caller can branch on "was there a campaign at
+ * all". An empty object written to an account would read as "arrived from
+ * nowhere, confirmed" instead of "never asked", and those are different facts.
+ */
+export declare function parseCampaignAttribution(params: CampaignParamSource): CampaignAttribution | null;
+/**
+ * The canonical query string for a campaign — the ONLY place the stored form
+ * is written, so it cannot drift from what the parser reads back.
+ */
+export declare function campaignAttributionQuery(attribution: CampaignAttribution | null | undefined): string;
+/**
+ * The campaign as GA4 event parameters, ready to spread into `sign_up`.
+ *
+ * Renamed off the `utm_` spellings on purpose. These are OUR event parameters,
+ * registered as custom dimensions on the property (see `docs/ANALYTICS.md`);
+ * the `utm_` names belong to GA's own automatic campaign collection, and
+ * shipping a custom parameter under a name the platform also owns is how a
+ * dimension ends up meaning two things.
+ *
+ * Returns an empty object — never keys with `undefined` values — so that
+ * spreading it into an organic signup's params adds nothing at all. A
+ * `campaign_source: undefined` on every unattributed signup would survive the
+ * sanitizer as an absence but read, to whoever writes the report, as a
+ * dimension that is populated sometimes and broken the rest of the time.
+ */
+export declare function campaignEventParams(attribution: CampaignAttribution | null | undefined): {
+    campaign_source?: string;
+    campaign_medium?: string;
+    campaign_name?: string;
+};

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

@@ -0,0 +1,162 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Where an account came from (AGL-1731) — the campaign contract between the
+ * marketing site's links and the console's signup.
+ *
+ * Until this existed a paid click, an organic visit and a partner link
+ * arrived indistinguishable: `sign_up` carried `method` and nothing else, so
+ * no report could say which spend produced a customer. That is tolerable
+ * while nothing is being spent and not tolerable the day advertising starts,
+ * because the measurement has to exist BEFORE the traffic — a signup that
+ * lands unattributed is unattributed forever.
+ *
+ * ## Why an allowlist, and why exactly three
+ *
+ * `utm_source`, `utm_medium` and `utm_campaign` are the three axes an ad
+ * report is read on: which channel, what kind of placement, which push. They
+ * are also the three the marketing site can be told to emit without further
+ * decisions.
+ *
+ * `utm_term` and `utm_content` are deliberately OUT, matching the refusal the
+ * tenant's own first-party collector already made for its visitors
+ * (`apps/tenant/app/api/analytics/collect/route.ts`): keyword- and
+ * variant-level labels multiply cardinality without answering a question
+ * anyone asks of a signup, and a keyword string is the most likely of the
+ * five to carry something a person typed. `gclid` and bare `ref` are out for
+ * that same cardinality reason. Not for a privacy one: the property runs ads
+ * personalization ON in every region, and Google's own auto-tagging already
+ * carries the click identifier into it, so re-collecting `gclid` here would
+ * duplicate a field the platform owns rather than withhold anything.
+ *
+ * The allowlist is the privacy mechanism, not a convenience. A parser that
+ * copied "the campaign-ish parameters" would be one marketing link away from
+ * storing `?email=` against a person, and the standing rule is that personal
+ * data never travels in a URL parameter in the first place.
+ *
+ * ## Two exits, and only one of them is already guarded
+ *
+ * A parsed campaign leaves this process twice: onto the GA4 `sign_up` hit,
+ * and into `users/{uid}` so revenue can be attributed to it months later.
+ * Only the first passes `sanitizeEventParams`. The Firestore write does not,
+ * so the scrub — email shape refused, length capped, blanks dropped — lives
+ * HERE, on the way in, and both exits inherit it.
+ *
+ * ## Why the wire form is what gets stored
+ *
+ * Same contract as the AGL-1535 plan intent it rides beside: the stored value
+ * is the query string, re-parsed by this parser on the way out. `users/{uid}`
+ * is owner-writable, so a stored field is a client-FORGEABLE field. Re-parsing
+ * means a hand-edited document can claim no more than a hand-edited URL could,
+ * which is a marketing label and nothing that touches entitlement.
+ */ /**
+ * The URL parameter names, in report order. Exported because the marketing
+ * site's links, the stored wire form and this parser all have to spell them
+ * identically — two spellings would read as two dimensions in GA4 and split
+ * every report in half.
+ */ export const CAMPAIGN_QUERY_KEYS = [
+    'utm_source',
+    'utm_medium',
+    'utm_campaign'
+];
+/** Longest value stored or sent, matching `sanitizeEventParams`'s own cap. */ const MAX_VALUE_LENGTH = 100;
+/** The same shape test the event sanitizer uses, applied to the stored exit too. */ const EMAIL_SHAPED = /[^\s@]+@[^\s@]+\.[^\s@]+/;
+/** Which `CampaignAttribution` field each URL key fills. */ const FIELD_FOR_KEY = {
+    utm_source: 'source',
+    utm_medium: 'medium',
+    utm_campaign: 'campaign'
+};
+function rawValue(params, key) {
+    if (!params) return null;
+    if (typeof params.get === 'function') {
+        return params.get(key);
+    }
+    const value = params[key];
+    // A repeated parameter arrives as an array. The first one wins rather than
+    // being joined: `utm_medium=cpc&utm_medium=organic` is a malformed link, and
+    // inventing `cpc,organic` would put a value in the reports that no campaign
+    // ever set.
+    if (Array.isArray(value)) return value.length ? value[0] : null;
+    return typeof value === 'string' ? value : null;
+}
+/**
+ * Reduce one raw parameter to something storable, or null to drop it.
+ *
+ * Dropping the single value rather than the whole campaign is deliberate: a
+ * mail-merge link that puts an address in `utm_source` still names a real
+ * `utm_campaign`, and keeping the half that is safe beats losing the
+ * attribution to protect the half that is not.
+ */ function scrubValue(value) {
+    if (typeof value !== 'string') return null;
+    const trimmed = value.trim();
+    if (!trimmed) return null;
+    if (EMAIL_SHAPED.test(trimmed)) return null;
+    return trimmed.slice(0, MAX_VALUE_LENGTH);
+}
+/**
+ * Read the campaign off a signup URL, or null when it names none.
+ *
+ * Null rather than `{}` so a caller can branch on "was there a campaign at
+ * all". An empty object written to an account would read as "arrived from
+ * nowhere, confirmed" instead of "never asked", and those are different facts.
+ */ export function parseCampaignAttribution(params) {
+    if (!params) return null;
+    const attribution = {};
+    for (const key of CAMPAIGN_QUERY_KEYS){
+        const value = scrubValue(rawValue(params, key));
+        if (value) attribution[FIELD_FOR_KEY[key]] = value;
+    }
+    return Object.keys(attribution).length ? attribution : null;
+}
+/**
+ * The canonical query string for a campaign — the ONLY place the stored form
+ * is written, so it cannot drift from what the parser reads back.
+ */ export function campaignAttributionQuery(attribution) {
+    if (!attribution) return '';
+    const params = new URLSearchParams();
+    for (const key of CAMPAIGN_QUERY_KEYS){
+        const value = attribution[FIELD_FOR_KEY[key]];
+        if (value) params.set(key, value);
+    }
+    return params.toString();
+}
+/**
+ * The campaign as GA4 event parameters, ready to spread into `sign_up`.
+ *
+ * Renamed off the `utm_` spellings on purpose. These are OUR event parameters,
+ * registered as custom dimensions on the property (see `docs/ANALYTICS.md`);
+ * the `utm_` names belong to GA's own automatic campaign collection, and
+ * shipping a custom parameter under a name the platform also owns is how a
+ * dimension ends up meaning two things.
+ *
+ * Returns an empty object — never keys with `undefined` values — so that
+ * spreading it into an organic signup's params adds nothing at all. A
+ * `campaign_source: undefined` on every unattributed signup would survive the
+ * sanitizer as an absence but read, to whoever writes the report, as a
+ * dimension that is populated sometimes and broken the rest of the time.
+ */ export function campaignEventParams(attribution) {
+    if (!attribution) return {};
+    return _extends({}, attribution.source ? {
+        campaign_source: attribution.source
+    } : {}, attribution.medium ? {
+        campaign_medium: attribution.medium
+    } : {}, attribution.campaign ? {
+        campaign_name: attribution.campaign
+    } : {});
+}
+
+//# sourceMappingURL=campaign-attribution.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-attribution.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * Where an account came from (AGL-1731) — the campaign contract between the\n * marketing site's links and the console's signup.\n *\n * Until this existed a paid click, an organic visit and a partner link\n * arrived indistinguishable: `sign_up` carried `method` and nothing else, so\n * no report could say which spend produced a customer. That is tolerable\n * while nothing is being spent and not tolerable the day advertising starts,\n * because the measurement has to exist BEFORE the traffic — a signup that\n * lands unattributed is unattributed forever.\n *\n * ## Why an allowlist, and why exactly three\n *\n * `utm_source`, `utm_medium` and `utm_campaign` are the three axes an ad\n * report is read on: which channel, what kind of placement, which push. They\n * are also the three the marketing site can be told to emit without further\n * decisions.\n *\n * `utm_term` and `utm_content` are deliberately OUT, matching the refusal the\n * tenant's own first-party collector already made for its visitors\n * (`apps/tenant/app/api/analytics/collect/route.ts`): keyword- and\n * variant-level labels multiply cardinality without answering a question\n * anyone asks of a signup, and a keyword string is the most likely of the\n * five to carry something a person typed. `gclid` and bare `ref` are out for\n * that same cardinality reason. Not for a privacy one: the property runs ads\n * personalization ON in every region, and Google's own auto-tagging already\n * carries the click identifier into it, so re-collecting `gclid` here would\n * duplicate a field the platform owns rather than withhold anything.\n *\n * The allowlist is the privacy mechanism, not a convenience. A parser that\n * copied \"the campaign-ish parameters\" would be one marketing link away from\n * storing `?email=` against a person, and the standing rule is that personal\n * data never travels in a URL parameter in the first place.\n *\n * ## Two exits, and only one of them is already guarded\n *\n * A parsed campaign leaves this process twice: onto the GA4 `sign_up` hit,\n * and into `users/{uid}` so revenue can be attributed to it months later.\n * Only the first passes `sanitizeEventParams`. The Firestore write does not,\n * so the scrub — email shape refused, length capped, blanks dropped — lives\n * HERE, on the way in, and both exits inherit it.\n *\n * ## Why the wire form is what gets stored\n *\n * Same contract as the AGL-1535 plan intent it rides beside: the stored value\n * is the query string, re-parsed by this parser on the way out. `users/{uid}`\n * is owner-writable, so a stored field is a client-FORGEABLE field. Re-parsing\n * means a hand-edited document can claim no more than a hand-edited URL could,\n * which is a marketing label and nothing that touches entitlement.\n */\n\n/**\n * The URL parameter names, in report order. Exported because the marketing\n * site's links, the stored wire form and this parser all have to spell them\n * identically — two spellings would read as two dimensions in GA4 and split\n * every report in half.\n */\nexport const CAMPAIGN_QUERY_KEYS = [\n  'utm_source',\n  'utm_medium',\n  'utm_campaign',\n] as const\n\n/** A campaign, with every field optional — a partial one is still worth having. */\nexport interface CampaignAttribution {\n  /** `utm_source` — the channel: `google`, `hn`, a partner's name. */\n  source?: string\n  /** `utm_medium` — the kind of placement: `cpc`, `email`, `referral`. */\n  medium?: string\n  /** `utm_campaign` — which push: `sept-launch`. */\n  campaign?: string\n}\n\n/** Longest value stored or sent, matching `sanitizeEventParams`'s own cap. */\nconst MAX_VALUE_LENGTH = 100\n\n/** The same shape test the event sanitizer uses, applied to the stored exit too. */\nconst EMAIL_SHAPED = /[^\\s@]+@[^\\s@]+\\.[^\\s@]+/\n\n/** Which `CampaignAttribution` field each URL key fills. */\nconst FIELD_FOR_KEY: Record<\n  (typeof CAMPAIGN_QUERY_KEYS)[number],\n  keyof CampaignAttribution\n> = {\n  utm_source: 'source',\n  utm_medium: 'medium',\n  utm_campaign: 'campaign',\n}\n\n/** What a Server Component holds before it has a `URLSearchParams`. */\nexport type CampaignParamSource =\n  | URLSearchParams\n  | Record<string, string | string[] | undefined>\n  | null\n  | undefined\n\nfunction rawValue(params: CampaignParamSource, key: string): string | null {\n  if (!params) return null\n  if (typeof (params as URLSearchParams).get === 'function') {\n    return (params as URLSearchParams).get(key)\n  }\n  const value = (params as Record<string, string | string[] | undefined>)[key]\n  // A repeated parameter arrives as an array. The first one wins rather than\n  // being joined: `utm_medium=cpc&utm_medium=organic` is a malformed link, and\n  // inventing `cpc,organic` would put a value in the reports that no campaign\n  // ever set.\n  if (Array.isArray(value)) return value.length ? value[0] : null\n  return typeof value === 'string' ? value : null\n}\n\n/**\n * Reduce one raw parameter to something storable, or null to drop it.\n *\n * Dropping the single value rather than the whole campaign is deliberate: a\n * mail-merge link that puts an address in `utm_source` still names a real\n * `utm_campaign`, and keeping the half that is safe beats losing the\n * attribution to protect the half that is not.\n */\nfunction scrubValue(value: string | null): string | null {\n  if (typeof value !== 'string') return null\n  const trimmed = value.trim()\n  if (!trimmed) return null\n  if (EMAIL_SHAPED.test(trimmed)) return null\n  return trimmed.slice(0, MAX_VALUE_LENGTH)\n}\n\n/**\n * Read the campaign off a signup URL, or null when it names none.\n *\n * Null rather than `{}` so a caller can branch on \"was there a campaign at\n * all\". An empty object written to an account would read as \"arrived from\n * nowhere, confirmed\" instead of \"never asked\", and those are different facts.\n */\nexport function parseCampaignAttribution(\n  params: CampaignParamSource,\n): CampaignAttribution | null {\n  if (!params) return null\n  const attribution: CampaignAttribution = {}\n  for (const key of CAMPAIGN_QUERY_KEYS) {\n    const value = scrubValue(rawValue(params, key))\n    if (value) attribution[FIELD_FOR_KEY[key]] = value\n  }\n  return Object.keys(attribution).length ? attribution : null\n}\n\n/**\n * The canonical query string for a campaign — the ONLY place the stored form\n * is written, so it cannot drift from what the parser reads back.\n */\nexport function campaignAttributionQuery(\n  attribution: CampaignAttribution | null | undefined,\n): string {\n  if (!attribution) return ''\n  const params = new URLSearchParams()\n  for (const key of CAMPAIGN_QUERY_KEYS) {\n    const value = attribution[FIELD_FOR_KEY[key]]\n    if (value) params.set(key, value)\n  }\n  return params.toString()\n}\n\n/**\n * The campaign as GA4 event parameters, ready to spread into `sign_up`.\n *\n * Renamed off the `utm_` spellings on purpose. These are OUR event parameters,\n * registered as custom dimensions on the property (see `docs/ANALYTICS.md`);\n * the `utm_` names belong to GA's own automatic campaign collection, and\n * shipping a custom parameter under a name the platform also owns is how a\n * dimension ends up meaning two things.\n *\n * Returns an empty object — never keys with `undefined` values — so that\n * spreading it into an organic signup's params adds nothing at all. A\n * `campaign_source: undefined` on every unattributed signup would survive the\n * sanitizer as an absence but read, to whoever writes the report, as a\n * dimension that is populated sometimes and broken the rest of the time.\n */\nexport function campaignEventParams(\n  attribution: CampaignAttribution | null | undefined,\n): {\n  campaign_source?: string\n  campaign_medium?: string\n  campaign_name?: string\n} {\n  if (!attribution) return {}\n  return {\n    ...(attribution.source ? { campaign_source: attribution.source } : {}),\n    ...(attribution.medium ? { campaign_medium: attribution.medium } : {}),\n    ...(attribution.campaign ? { campaign_name: attribution.campaign } : {}),\n  }\n}\n"],"names":["CAMPAIGN_QUERY_KEYS","MAX_VALUE_LENGTH","EMAIL_SHAPED","FIELD_FOR_KEY","utm_source","utm_medium","utm_campaign","rawValue","params","key","get","value","Array","isArray","length","scrubValue","trimmed","trim","test","slice","parseCampaignAttribution","attribution","Object","keys","campaignAttributionQuery","URLSearchParams","set","toString","campaignEventParams","source","campaign_source","medium","campaign_medium","campaign","campaign_name"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDC,GAED;;;;;CAKC,GACD,OAAO,MAAMA,sBAAsB;IACjC;IACA;IACA;CACD,CAAS;AAYV,4EAA4E,GAC5E,MAAMC,mBAAmB;AAEzB,kFAAkF,GAClF,MAAMC,eAAe;AAErB,0DAA0D,GAC1D,MAAMC,gBAGF;IACFC,YAAY;IACZC,YAAY;IACZC,cAAc;AAChB;AASA,SAASC,SAASC,MAA2B,EAAEC,GAAW;IACxD,IAAI,CAACD,QAAQ,OAAO;IACpB,IAAI,OAAO,AAACA,OAA2BE,GAAG,KAAK,YAAY;QACzD,OAAO,AAACF,OAA2BE,GAAG,CAACD;IACzC;IACA,MAAME,QAAQ,AAACH,MAAwD,CAACC,IAAI;IAC5E,2EAA2E;IAC3E,6EAA6E;IAC7E,4EAA4E;IAC5E,YAAY;IACZ,IAAIG,MAAMC,OAAO,CAACF,QAAQ,OAAOA,MAAMG,MAAM,GAAGH,KAAK,CAAC,EAAE,GAAG;IAC3D,OAAO,OAAOA,UAAU,WAAWA,QAAQ;AAC7C;AAEA;;;;;;;CAOC,GACD,SAASI,WAAWJ,KAAoB;IACtC,IAAI,OAAOA,UAAU,UAAU,OAAO;IACtC,MAAMK,UAAUL,MAAMM,IAAI;IAC1B,IAAI,CAACD,SAAS,OAAO;IACrB,IAAId,aAAagB,IAAI,CAACF,UAAU,OAAO;IACvC,OAAOA,QAAQG,KAAK,CAAC,GAAGlB;AAC1B;AAEA;;;;;;CAMC,GACD,OAAO,SAASmB,yBACdZ,MAA2B;IAE3B,IAAI,CAACA,QAAQ,OAAO;IACpB,MAAMa,cAAmC,CAAC;IAC1C,KAAK,MAAMZ,OAAOT,oBAAqB;QACrC,MAAMW,QAAQI,WAAWR,SAASC,QAAQC;QAC1C,IAAIE,OAAOU,WAAW,CAAClB,aAAa,CAACM,IAAI,CAAC,GAAGE;IAC/C;IACA,OAAOW,OAAOC,IAAI,CAACF,aAAaP,MAAM,GAAGO,cAAc;AACzD;AAEA;;;CAGC,GACD,OAAO,SAASG,yBACdH,WAAmD;IAEnD,IAAI,CAACA,aAAa,OAAO;IACzB,MAAMb,SAAS,IAAIiB;IACnB,KAAK,MAAMhB,OAAOT,oBAAqB;QACrC,MAAMW,QAAQU,WAAW,CAAClB,aAAa,CAACM,IAAI,CAAC;QAC7C,IAAIE,OAAOH,OAAOkB,GAAG,CAACjB,KAAKE;IAC7B;IACA,OAAOH,OAAOmB,QAAQ;AACxB;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,oBACdP,WAAmD;IAMnD,IAAI,CAACA,aAAa,OAAO,CAAC;IAC1B,OAAO,aACDA,YAAYQ,MAAM,GAAG;QAAEC,iBAAiBT,YAAYQ,MAAM;IAAC,IAAI,CAAC,GAChER,YAAYU,MAAM,GAAG;QAAEC,iBAAiBX,YAAYU,MAAM;IAAC,IAAI,CAAC,GAChEV,YAAYY,QAAQ,GAAG;QAAEC,eAAeb,YAAYY,QAAQ;IAAC,IAAI,CAAC;AAE1E"}

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

@@ -0,0 +1,220 @@
+/**
+ * @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 { type CampaignAttribution } from './campaign-attribution';
+/**
+ * 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 declare const CAMPAIGN_VISIT_STORAGE_KEY = "aglyn:campaign";
+/**
+ * What a read of the first-touch store produced.
+ *
+ * Three states rather than "a campaign or null", and the third is the whole
+ * point. `sessionStorage` throws outright in some privacy modes, and a
+ * `catch` that returned null would report "this visitor named no campaign" —
+ * indistinguishable from an organic arrival, which is how an unreadable source
+ * becomes a measured zero. `unreadable` is a different answer and the caller
+ * treats it differently: it falls through to the live URL instead of
+ * concluding anything.
+ */
+export type VisitCampaignRead = {
+    status: 'campaign';
+    campaign: CampaignAttribution;
+} | {
+    status: 'none';
+} | {
+    status: 'unreadable';
+};
+/**
+ * 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 declare function readVisitCampaign(): VisitCampaignRead;
+/**
+ * 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 declare function rememberVisitCampaign(search?: string): CampaignAttribution | null;
+/**
+ * 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 declare function setCampaignForwardingConsent(allowed: boolean | null): void;
+/**
+ * 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 declare function campaignToForward(search?: string): CampaignAttribution | null;
+/**
+ * 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 declare function decorateCampaignHref(href: string, baseHref: string, consoleOrigin: string, campaign: CampaignAttribution | null): string | null;
+/**
+ * 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 declare function installCampaignForwarding(options: {
+    consoleOrigin: string;
+}): () => void;
+/** Test seam — removes both listeners, forgets them, and forgets consent. */
+export declare function resetCampaignForwarding(): void;