npm - @aglyn/aglyn - Versions diffs - 1.0.0-beta.226 → 1.0.0-beta.227 - Mend

@aglyn/aglyn 1.0.0-beta.226 → 1.0.0-beta.227

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.226",
+  "version": "1.0.0-beta.227",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -37,16 +37,16 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.226",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.226",
-    "@aglyn/shared-data-types": "1.0.0-beta.226",
-    "@aglyn/shared-util-email": "1.0.0-beta.226",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.226",
-    "@aglyn/shared-util-http": "1.0.0-beta.226",
-    "@aglyn/shared-util-logger": "1.0.0-beta.226",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.226",
-    "@aglyn/shared-util-tools": "1.0.0-beta.226",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.226",
+    "@aglyn/shared-data-enums": "1.0.0-beta.227",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.227",
+    "@aglyn/shared-data-types": "1.0.0-beta.227",
+    "@aglyn/shared-util-email": "1.0.0-beta.227",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.227",
+    "@aglyn/shared-util-http": "1.0.0-beta.227",
+    "@aglyn/shared-util-logger": "1.0.0-beta.227",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.227",
+    "@aglyn/shared-util-tools": "1.0.0-beta.227",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.227",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",

package/src/lib/app-utils/account-acquisition.d.ts CHANGED Viewed

@@ -89,6 +89,11 @@ export interface AccountAcquisition {
     utm: FirstTouchUtm | null;
     /** Which ad click ids the landing URL carried — presence only. */
     clickIds: FirstTouchClickId[];
+    /**
+     * The Google Ads campaign the click came from (`gad_campaignid`), which
+     * auto-tagging appends whether or not the ad carries a `utm_campaign`.
+     */
+    adCampaignId: string | null;
     /** How the account was created. */
     door: AcquisitionDoor;
     /** The sign-in provider it was created with: `password`, `google.com`, `saml.…`. */
@@ -150,6 +155,8 @@ export declare function organizationAcquisition(creatorRecord: unknown, creatorU
  * record at all.
  */
 export declare function readAccountAcquisition(value: unknown): AccountAcquisition | null;
+/** The Google Ads page for a campaign id, opened in whichever account is signed in. */
+export declare function googleAdsCampaignUrl(campaignId: string): string;
 /** A sign-in provider id as a person reads it. */
 export declare function providerLabel(provider: string | null | undefined): string | null;
 /**

package/src/lib/app-utils/account-acquisition.js CHANGED Viewed

@@ -98,7 +98,7 @@ function uidOf(value) {
  * a fact about the account too, and a card that renders blank would read as
  * "never asked".
  */ export function buildAccountAcquisition(input) {
-    var _ref, _touch_via, _touch_utm, _touch_click;
+    var _ref, _touch_via, _touch_utm, _touch_click, _touch_adCampaign;
     var _touch_utm1;
     const touch = sanitizeFirstTouch(input.touch, input.nowMs);
     const base = {
@@ -126,7 +126,8 @@ function uidOf(value) {
         referrerHost: touch.ref,
         viaHost: (_touch_via = touch.via) != null ? _touch_via : null,
         utm: (_touch_utm = touch.utm) != null ? _touch_utm : null,
-        clickIds: (_touch_click = touch.click) != null ? _touch_click : []
+        clickIds: (_touch_click = touch.click) != null ? _touch_click : [],
+        adCampaignId: (_touch_adCampaign = touch.adCampaign) != null ? _touch_adCampaign : null
     }, base);
 }
 /** A record for an account nothing was captured for. */ export function unknownAccountAcquisition(input) {
@@ -143,6 +144,7 @@ function uidOf(value) {
         viaHost: null,
         utm: null,
         clickIds: [],
+        adCampaignId: null,
         door: (_input_door = input.door) != null ? _input_door : 'unknown',
         provider: (_input_provider = input.provider) != null ? _input_provider : null,
         invitedToOrgId: (_input_invitedToOrgId = input.invitedToOrgId) != null ? _input_invitedToOrgId : null,
@@ -221,6 +223,7 @@ function uidOf(value) {
         viaHost: label(raw['viaHost'], 253),
         utm: Object.keys(utm).length ? utm : null,
         clickIds,
+        adCampaignId: typeof raw['adCampaignId'] === 'string' && /^\d{1,20}$/.test(raw['adCampaignId']) ? raw['adCampaignId'] : null,
         door: doorOf(raw['door']),
         provider: providerOf(raw['provider']),
         invitedToOrgId: uidOf(raw['invitedToOrgId']),
@@ -233,6 +236,9 @@ function uidOf(value) {
     if (copiedFrom) record.copiedFromUid = copiedFrom;
     return record;
 }
+/** The Google Ads page for a campaign id, opened in whichever account is signed in. */ export function googleAdsCampaignUrl(campaignId) {
+    return `https://ads.google.com/aw/campaigns?campaignId=${encodeURIComponent(campaignId)}`;
+}
 /** A sign-in provider id as a person reads it. */ export function providerLabel(provider) {
     if (!provider) return null;
     if (provider === 'password') return 'password';
@@ -244,8 +250,10 @@ function uidOf(value) {
     return provider;
 }
 function channelPhrase(record) {
+    var _record_campaign;
     const from = displayHost(record.referrerHost) || record.source;
-    const campaign = record.campaign ? `, ${record.campaign}` : '';
+    const named = (_record_campaign = record.campaign) != null ? _record_campaign : record.adCampaignId ? `campaign ${record.adCampaignId}` : null;
+    const campaign = named ? `, ${named}` : '';
     switch(record.channel){
         case 'referral':
             return `Referral from ${from}${campaign}`;

package/src/lib/app-utils/account-acquisition.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/account-acquisition.ts"],"sourcesContent":["/*\n @license\n * Copyright 2026 Aglyn LLC\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n /\n\nimport {\n classifyChannel,\n displayHost,\n sanitizeFirstTouch,\n sourceAndMedium,\n type AcquisitionChannel,\n type FirstTouchClickId,\n type FirstTouchUtm,\n} from '@aglyn/shared-util-first-touch'\n\n/\n Where an account came from, written ONCE on the account when it is created\n * (AGL-3289) — `users/{uid}.acquisition`, and on the organization created in\n * the same flow as `orgs/{orgId}.acquisition`.\n \n ## Why this exists\n \n Answering \"where did this person come from?\" for one new workspace took a\n * sales session twenty-five minutes across five tools: the staff user page\n * had no source, Firestore held nothing beyond names, and the answer — a\n * review site's referral — was finally found in an analytics property and in\n * the marketing host's daily referrer counts. The platform never stored the\n * fact on the account it was about. This record is that fact, read from one\n * card on the staff user and organization pages.\n \n ## What writes it, and what never may\n \n The capture library keeps the first touch on the visitor's device; the\n * platform turns it into this record at account creation, server-side, and\n * the rules refuse the field to every client — owner and staff alike. A\n * record the account holder could restate would be a record nobody could\n * trust. It is never overwritten: a later touch, if one is ever kept, goes\n * BESIDE it as its own field.\n \n Every field here is built from the untrusted touch by re-scrubbing it, the\n * same way the capture scrubbed it on the device, and nothing the record says\n * grants anything: it is a label for a staff reader.\n /\n\n/* The field on `users/{uid}` and `orgs/{orgId}`. /\nexport const ACCOUNT_ACQUISITION_FIELD = 'acquisition'\n\n/\n How an account was created: the signup form with a password, the signup\n * form through Google, accepting an invitation, or single sign-on.\n /\nexport const ACQUISITION_DOORS = [\n 'signup-password',\n 'signup-google',\n 'invite',\n 'sso',\n] as const\nexport type AcquisitionDoor = (typeof ACQUISITION_DOORS)[number] \| 'unknown'\n\n/* What wrote a record: a door at creation, an organization copying its creator's, or the backfill. /\nexport type AcquisitionRecordedBy = 'signup' \| 'sso' \| 'org-creation' \| 'backfill'\n\n/* Where the account-creating request came from, as the edge reported it. /\nexport interface AcquisitionGeo {\n country: string \| null\n region: string \| null\n city: string \| null\n}\n\n/* The stored record. /\nexport interface AccountAcquisition {\n v: 1\n /\n Where the visit came from, spelled the way reports spell it — a\n * `utm_source`, a referring host, `(direct)` — or `unknown` when nothing was\n * captured.\n /\n source: string\n /* `utm_medium`, or what the channel implies; null when unknown. /\n medium: string \| null\n /* `utm_campaign`, when the landing URL named one. /\n campaign: string \| null\n /* The channel, from the platform's own rule table. /\n channel: AcquisitionChannel\n /* When the first visit landed; null when it was never captured. /\n capturedAt: number \| null\n /* The first page the visitor landed on. /\n landing: { host: string; path: string } \| null\n /* The external host that sent them. /\n referrerHost: string \| null\n /* One of the platform's own hosts they came from before anything captured them. /\n viaHost: string \| null\n /* Every `utm_` the landing URL carried. /\n utm: FirstTouchUtm \| null\n /** Which ad click ids the landing URL carried — presence only. /\n clickIds: FirstTouchClickId[]\n /* How the account was created. /\n door: AcquisitionDoor\n /* The sign-in provider it was created with: `password`, `google.com`, `saml.…`. /\n provider: string \| null\n /* The organization whose invitation the person signed up to accept. /\n invitedToOrgId: string \| null\n /* Where the account-creating request came from. /\n geo: AcquisitionGeo \| null\n /* When the auth record says the account was created. /\n accountCreatedAt: number \| null\n /* When this record was written. /\n recordedAt: number\n recordedBy: AcquisitionRecordedBy\n /* On an organization's copy: the account it was copied from. /\n copiedFromUid?: string\n}\n\nconst MAX_LABEL = 100\nconst PROVIDER_SHAPE = /^[a-z0-9][a-z0-9._-]{0,63}$/i\nconst RECORDED_BY: readonly AcquisitionRecordedBy[] = [\n 'signup',\n 'sso',\n 'org-creation',\n 'backfill',\n]\n\nfunction label(value: unknown, max = MAX_LABEL): string \| null {\n if (typeof value !== 'string') return null\n const clean = value.replace(/[\\u0000-\\u001f\\u007f]/g, '').trim() // eslint-disable-line no-control-regex\n return clean ? clean.slice(0, max) : null\n}\n\nfunction doorOf(value: unknown): AcquisitionDoor {\n return (ACQUISITION_DOORS as readonly string[]).includes(value as string)\n ? (value as AcquisitionDoor)\n : 'unknown'\n}\n\nfunction providerOf(value: unknown): string \| null {\n return typeof value === 'string' && PROVIDER_SHAPE.test(value.trim())\n ? value.trim().toLowerCase()\n : null\n}\n\nfunction geoOf(value: unknown): AcquisitionGeo \| null {\n if (!value \|\| typeof value !== 'object') return null\n const raw = value as Record<string, unknown>\n const geo: AcquisitionGeo = {\n country: label(raw['country'], 8)?.toUpperCase() ?? null,\n region: label(raw['region'], 64),\n city: label(raw['city'], 64),\n }\n return geo.country \|\| geo.region \|\| geo.city ? geo : null\n}\n\nfunction millisOf(value: unknown): number \| null {\n return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null\n}\n\nfunction uidOf(value: unknown): string \| null {\n return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value) ? value : null\n}\n\n/* What a door knows when it records an account. /\nexport interface AccountAcquisitionInput {\n /* The first touch the capture kept — untrusted, from the device. /\n touch: unknown\n door: unknown\n provider?: unknown\n geo?: unknown\n invitedToOrgId?: unknown\n /* When the auth record says the account was created. /\n accountCreatedAtMs?: number \| null\n recordedBy: AcquisitionRecordedBy\n nowMs: number\n}\n\n/\n The record for an account being created now.\n \n A missing or unusable touch still produces a record — `source: 'unknown'`\n * with whatever the door knows — because \"we asked and nothing came back\" is\n * a fact about the account too, and a card that renders blank would read as\n * \"never asked\".\n /\nexport function buildAccountAcquisition(input: AccountAcquisitionInput): AccountAcquisition {\n const touch = sanitizeFirstTouch(input.touch, input.nowMs)\n const base = {\n door: doorOf(input.door),\n provider: providerOf(input.provider),\n invitedToOrgId: uidOf(input.invitedToOrgId),\n geo: geoOf(input.geo),\n accountCreatedAt: millisOf(input.accountCreatedAtMs),\n recordedAt: input.nowMs,\n recordedBy: input.recordedBy,\n }\n if (!touch) return unknownAccountAcquisition(base)\n const { source, medium } = sourceAndMedium(touch)\n return {\n v: 1,\n source,\n medium,\n campaign: touch.utm?.campaign ?? null,\n channel: classifyChannel(touch),\n capturedAt: touch.at,\n landing: { host: touch.host, path: touch.path },\n referrerHost: touch.ref,\n viaHost: touch.via ?? null,\n utm: touch.utm ?? null,\n clickIds: touch.click ?? [],\n ...base,\n }\n}\n\n/* A record for an account nothing was captured for. /\nexport function unknownAccountAcquisition(input: {\n recordedAt: number\n recordedBy: AcquisitionRecordedBy\n door?: AcquisitionDoor\n provider?: string \| null\n invitedToOrgId?: string \| null\n geo?: AcquisitionGeo \| null\n accountCreatedAt?: number \| null\n}): AccountAcquisition {\n return {\n v: 1,\n source: 'unknown',\n medium: null,\n campaign: null,\n channel: 'unknown',\n capturedAt: null,\n landing: null,\n referrerHost: null,\n viaHost: null,\n utm: null,\n clickIds: [],\n door: input.door ?? 'unknown',\n provider: input.provider ?? null,\n invitedToOrgId: input.invitedToOrgId ?? null,\n geo: input.geo ?? null,\n accountCreatedAt: input.accountCreatedAt ?? null,\n recordedAt: input.recordedAt,\n recordedBy: input.recordedBy,\n }\n}\n\n/\n The organization's copy of its creator's record, or an `unknown` one naming\n * the creator when the account has none — so an organization's card is never\n * blank either, and always says whose record it is.\n /\nexport function organizationAcquisition(\n creatorRecord: unknown,\n creatorUid: string,\n nowMs: number,\n): AccountAcquisition {\n const record = readAccountAcquisition(creatorRecord)\n const copied = record\n ? { ...record }\n : unknownAccountAcquisition({ recordedAt: nowMs, recordedBy: 'org-creation' })\n delete copied.copiedFromUid\n return { ...copied, copiedFromUid: creatorUid }\n}\n\n/\n A stored record as a reader should trust it: re-validated field by field,\n * so a document written by an older version, a backfill or a hand edit still\n * renders, and renders nothing it should not. Null when the value is not a\n * record at all.\n /\nexport function readAccountAcquisition(value: unknown): AccountAcquisition \| null {\n if (!value \|\| typeof value !== 'object') return null\n const raw = value as Record<string, unknown>\n const source = label(raw['source'])\n if (!source) return null\n const channel = raw['channel']\n const landing = raw['landing'] as Record<string, unknown> \| null\n const utmRaw = raw['utm'] as Record<string, unknown> \| null\n const utm: FirstTouchUtm = {}\n for (const key of ['source', 'medium', 'campaign', 'content', 'term'] as const) {\n const cleaned = label(utmRaw?.[key])\n if (cleaned) utm[key] = cleaned\n }\n const clickIds = Array.isArray(raw['clickIds'])\n ? (['gclid', 'fbclid', 'msclkid'] as const).filter((id) =>\n (raw['clickIds'] as unknown[]).includes(id),\n )\n : []\n const recordedBy = RECORDED_BY.includes(raw['recordedBy'] as AcquisitionRecordedBy)\n ? (raw['recordedBy'] as AcquisitionRecordedBy)\n : 'backfill'\n const record: AccountAcquisition = {\n v: 1,\n source,\n medium: label(raw['medium']),\n campaign: label(raw['campaign']),\n channel:\n typeof channel === 'string' &&\n [\n 'organic-search',\n 'paid-search',\n 'social',\n 'referral',\n 'email',\n 'direct',\n 'unknown',\n ].includes(channel)\n ? (channel as AcquisitionChannel)\n : 'unknown',\n capturedAt:\n typeof raw['capturedAt'] === 'number' && raw['capturedAt'] > 0\n ? (raw['capturedAt'] as number)\n : null,\n landing:\n landing && label(landing['host'], 253)\n ? { host: label(landing['host'], 253) as string, path: label(landing['path'], 200) ?? '/' }\n : null,\n referrerHost: label(raw['referrerHost'], 253),\n viaHost: label(raw['viaHost'], 253),\n utm: Object.keys(utm).length ? utm : null,\n clickIds,\n door: doorOf(raw['door']),\n provider: providerOf(raw['provider']),\n invitedToOrgId: uidOf(raw['invitedToOrgId']),\n geo: geoOf(raw['geo']),\n accountCreatedAt: millisOf(raw['accountCreatedAt']),\n recordedAt:\n typeof raw['recordedAt'] === 'number' ? (raw['recordedAt'] as number) : 0,\n recordedBy,\n }\n const copiedFrom = uidOf(raw['copiedFromUid'])\n if (copiedFrom) record.copiedFromUid = copiedFrom\n return record\n}\n\n/* A sign-in provider id as a person reads it. /\nexport function providerLabel(provider: string \| null \| undefined): string \| null {\n if (!provider) return null\n if (provider === 'password') return 'password'\n if (provider === 'google.com') return 'Google'\n if (provider === 'apple.com') return 'Apple'\n if (provider === 'microsoft.com') return 'Microsoft'\n if (provider === 'github.com') return 'GitHub'\n if (provider.startsWith('saml.') \|\| provider.startsWith('oidc.')) return 'single sign-on'\n return provider\n}\n\nfunction channelPhrase(record: AccountAcquisition): string {\n const from = displayHost(record.referrerHost) \|\| record.source\n const campaign = record.campaign ? `, ${record.campaign}` : ''\n switch (record.channel) {\n case 'referral':\n return `Referral from ${from}${campaign}`\n case 'organic-search':\n return `Organic search from ${from}`\n case 'paid-search':\n return `Paid search (${record.source}${campaign})`\n case 'social':\n return `Social from ${from}${campaign}`\n case 'email':\n return `Email (${record.source}${campaign})`\n case 'direct':\n return record.viaHost\n ? `Direct, first seen arriving from ${record.viaHost}`\n : 'Direct'\n default:\n return record.recordedBy === 'backfill'\n ? 'Source unknown — the account predates capture'\n : 'Source unknown — nothing was captured'\n }\n}\n\nfunction doorPhrase(record: AccountAcquisition): string {\n const provider = providerLabel(record.provider)\n switch (record.door) {\n case 'signup-password':\n return 'signed up with password'\n case 'signup-google':\n return 'signed up with Google'\n case 'invite':\n return provider\n ? `signed up from an invitation, with ${provider}`\n : 'signed up from an invitation'\n case 'sso':\n return 'signed in with single sign-on'\n default:\n return provider ? `created with ${provider}` : 'created'\n }\n}\n\n/\n The record as one sentence a staff member reads at a glance:\n * \"Referral from g2.com → /pricing → signed up with password\".\n \n The landing is a bare path when it was on `primaryHost` — the platform's own\n * home — and host-and-path anywhere else, so a docs landing says so.\n */\nexport function describeAccountAcquisition(\n record: AccountAcquisition \| null \| undefined,\n options: { primaryHost?: string \| null } = {},\n): string {\n if (!record) return 'No acquisition record'\n const parts = [channelPhrase(record)]\n if (record.landing) {\n const onPrimary =\n options.primaryHost &&\n displayHost(record.landing.host) === displayHost(options.primaryHost)\n parts.push(\n onPrimary ? record.landing.path : `${displayHost(record.landing.host)}${record.landing.path}`,\n )\n }\n parts.push(doorPhrase(record))\n return parts.join(' → ')\n}\n"],"names":["classifyChannel","displayHost","sanitizeFirstTouch","sourceAndMedium","ACCOUNT_ACQUISITION_FIELD","ACQUISITION_DOORS","MAX_LABEL","PROVIDER_SHAPE","RECORDED_BY","label","value","max","clean","replace","trim","slice","doorOf","includes","providerOf","test","toLowerCase","geoOf","raw","geo","country","toUpperCase","region","city","millisOf","Number","isFinite","uidOf","buildAccountAcquisition","input","touch","nowMs","base","door","provider","invitedToOrgId","accountCreatedAt","accountCreatedAtMs","recordedAt","recordedBy","unknownAccountAcquisition","source","medium","v","campaign","utm","channel","capturedAt","at","landing","host","path","referrerHost","ref","viaHost","via","clickIds","click","organizationAcquisition","creatorRecord","creatorUid","record","readAccountAcquisition","copied","copiedFromUid","utmRaw","key","cleaned","Array","isArray","filter","id","Object","keys","length","copiedFrom","providerLabel","startsWith","channelPhrase","from","doorPhrase","describeAccountAcquisition","options","parts","onPrimary","primaryHost","push","join"],"mappings":"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"}
1	+ {"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/account-acquisition.ts"],"sourcesContent":["/*\n @license\n * Copyright 2026 Aglyn LLC\n \n Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n \n http://www.apache.org/licenses/LICENSE-2.0\n \n Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n /\n\nimport {\n classifyChannel,\n displayHost,\n sanitizeFirstTouch,\n sourceAndMedium,\n type AcquisitionChannel,\n type FirstTouchClickId,\n type FirstTouchUtm,\n} from '@aglyn/shared-util-first-touch'\n\n/\n Where an account came from, written ONCE on the account when it is created\n * (AGL-3289) — `users/{uid}.acquisition`, and on the organization created in\n * the same flow as `orgs/{orgId}.acquisition`.\n \n ## Why this exists\n \n Answering \"where did this person come from?\" for one new workspace took a\n * sales session twenty-five minutes across five tools: the staff user page\n * had no source, Firestore held nothing beyond names, and the answer — a\n * review site's referral — was finally found in an analytics property and in\n * the marketing host's daily referrer counts. The platform never stored the\n * fact on the account it was about. This record is that fact, read from one\n * card on the staff user and organization pages.\n \n ## What writes it, and what never may\n \n The capture library keeps the first touch on the visitor's device; the\n * platform turns it into this record at account creation, server-side, and\n * the rules refuse the field to every client — owner and staff alike. A\n * record the account holder could restate would be a record nobody could\n * trust. It is never overwritten: a later touch, if one is ever kept, goes\n * BESIDE it as its own field.\n \n Every field here is built from the untrusted touch by re-scrubbing it, the\n * same way the capture scrubbed it on the device, and nothing the record says\n * grants anything: it is a label for a staff reader.\n /\n\n/* The field on `users/{uid}` and `orgs/{orgId}`. /\nexport const ACCOUNT_ACQUISITION_FIELD = 'acquisition'\n\n/\n How an account was created: the signup form with a password, the signup\n * form through Google, accepting an invitation, or single sign-on.\n /\nexport const ACQUISITION_DOORS = [\n 'signup-password',\n 'signup-google',\n 'invite',\n 'sso',\n] as const\nexport type AcquisitionDoor = (typeof ACQUISITION_DOORS)[number] \| 'unknown'\n\n/* What wrote a record: a door at creation, an organization copying its creator's, or the backfill. /\nexport type AcquisitionRecordedBy = 'signup' \| 'sso' \| 'org-creation' \| 'backfill'\n\n/* Where the account-creating request came from, as the edge reported it. /\nexport interface AcquisitionGeo {\n country: string \| null\n region: string \| null\n city: string \| null\n}\n\n/* The stored record. /\nexport interface AccountAcquisition {\n v: 1\n /\n Where the visit came from, spelled the way reports spell it — a\n * `utm_source`, a referring host, `(direct)` — or `unknown` when nothing was\n * captured.\n /\n source: string\n /* `utm_medium`, or what the channel implies; null when unknown. /\n medium: string \| null\n /* `utm_campaign`, when the landing URL named one. /\n campaign: string \| null\n /* The channel, from the platform's own rule table. /\n channel: AcquisitionChannel\n /* When the first visit landed; null when it was never captured. /\n capturedAt: number \| null\n /* The first page the visitor landed on. /\n landing: { host: string; path: string } \| null\n /* The external host that sent them. /\n referrerHost: string \| null\n /* One of the platform's own hosts they came from before anything captured them. /\n viaHost: string \| null\n /* Every `utm_` the landing URL carried. /\n utm: FirstTouchUtm \| null\n /** Which ad click ids the landing URL carried — presence only. /\n clickIds: FirstTouchClickId[]\n /\n The Google Ads campaign the click came from (`gad_campaignid`), which\n * auto-tagging appends whether or not the ad carries a `utm_campaign`.\n /\n adCampaignId: string \| null\n /* How the account was created. /\n door: AcquisitionDoor\n /* The sign-in provider it was created with: `password`, `google.com`, `saml.…`. /\n provider: string \| null\n /* The organization whose invitation the person signed up to accept. /\n invitedToOrgId: string \| null\n /* Where the account-creating request came from. /\n geo: AcquisitionGeo \| null\n /* When the auth record says the account was created. /\n accountCreatedAt: number \| null\n /* When this record was written. /\n recordedAt: number\n recordedBy: AcquisitionRecordedBy\n /* On an organization's copy: the account it was copied from. /\n copiedFromUid?: string\n}\n\nconst MAX_LABEL = 100\nconst PROVIDER_SHAPE = /^[a-z0-9][a-z0-9._-]{0,63}$/i\nconst RECORDED_BY: readonly AcquisitionRecordedBy[] = [\n 'signup',\n 'sso',\n 'org-creation',\n 'backfill',\n]\n\nfunction label(value: unknown, max = MAX_LABEL): string \| null {\n if (typeof value !== 'string') return null\n const clean = value.replace(/[\\u0000-\\u001f\\u007f]/g, '').trim() // eslint-disable-line no-control-regex\n return clean ? clean.slice(0, max) : null\n}\n\nfunction doorOf(value: unknown): AcquisitionDoor {\n return (ACQUISITION_DOORS as readonly string[]).includes(value as string)\n ? (value as AcquisitionDoor)\n : 'unknown'\n}\n\nfunction providerOf(value: unknown): string \| null {\n return typeof value === 'string' && PROVIDER_SHAPE.test(value.trim())\n ? value.trim().toLowerCase()\n : null\n}\n\nfunction geoOf(value: unknown): AcquisitionGeo \| null {\n if (!value \|\| typeof value !== 'object') return null\n const raw = value as Record<string, unknown>\n const geo: AcquisitionGeo = {\n country: label(raw['country'], 8)?.toUpperCase() ?? null,\n region: label(raw['region'], 64),\n city: label(raw['city'], 64),\n }\n return geo.country \|\| geo.region \|\| geo.city ? geo : null\n}\n\nfunction millisOf(value: unknown): number \| null {\n return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null\n}\n\nfunction uidOf(value: unknown): string \| null {\n return typeof value === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(value) ? value : null\n}\n\n/* What a door knows when it records an account. /\nexport interface AccountAcquisitionInput {\n /* The first touch the capture kept — untrusted, from the device. /\n touch: unknown\n door: unknown\n provider?: unknown\n geo?: unknown\n invitedToOrgId?: unknown\n /* When the auth record says the account was created. /\n accountCreatedAtMs?: number \| null\n recordedBy: AcquisitionRecordedBy\n nowMs: number\n}\n\n/\n The record for an account being created now.\n \n A missing or unusable touch still produces a record — `source: 'unknown'`\n * with whatever the door knows — because \"we asked and nothing came back\" is\n * a fact about the account too, and a card that renders blank would read as\n * \"never asked\".\n /\nexport function buildAccountAcquisition(input: AccountAcquisitionInput): AccountAcquisition {\n const touch = sanitizeFirstTouch(input.touch, input.nowMs)\n const base = {\n door: doorOf(input.door),\n provider: providerOf(input.provider),\n invitedToOrgId: uidOf(input.invitedToOrgId),\n geo: geoOf(input.geo),\n accountCreatedAt: millisOf(input.accountCreatedAtMs),\n recordedAt: input.nowMs,\n recordedBy: input.recordedBy,\n }\n if (!touch) return unknownAccountAcquisition(base)\n const { source, medium } = sourceAndMedium(touch)\n return {\n v: 1,\n source,\n medium,\n campaign: touch.utm?.campaign ?? null,\n channel: classifyChannel(touch),\n capturedAt: touch.at,\n landing: { host: touch.host, path: touch.path },\n referrerHost: touch.ref,\n viaHost: touch.via ?? null,\n utm: touch.utm ?? null,\n clickIds: touch.click ?? [],\n adCampaignId: touch.adCampaign ?? null,\n ...base,\n }\n}\n\n/* A record for an account nothing was captured for. /\nexport function unknownAccountAcquisition(input: {\n recordedAt: number\n recordedBy: AcquisitionRecordedBy\n door?: AcquisitionDoor\n provider?: string \| null\n invitedToOrgId?: string \| null\n geo?: AcquisitionGeo \| null\n accountCreatedAt?: number \| null\n}): AccountAcquisition {\n return {\n v: 1,\n source: 'unknown',\n medium: null,\n campaign: null,\n channel: 'unknown',\n capturedAt: null,\n landing: null,\n referrerHost: null,\n viaHost: null,\n utm: null,\n clickIds: [],\n adCampaignId: null,\n door: input.door ?? 'unknown',\n provider: input.provider ?? null,\n invitedToOrgId: input.invitedToOrgId ?? null,\n geo: input.geo ?? null,\n accountCreatedAt: input.accountCreatedAt ?? null,\n recordedAt: input.recordedAt,\n recordedBy: input.recordedBy,\n }\n}\n\n/\n The organization's copy of its creator's record, or an `unknown` one naming\n * the creator when the account has none — so an organization's card is never\n * blank either, and always says whose record it is.\n /\nexport function organizationAcquisition(\n creatorRecord: unknown,\n creatorUid: string,\n nowMs: number,\n): AccountAcquisition {\n const record = readAccountAcquisition(creatorRecord)\n const copied = record\n ? { ...record }\n : unknownAccountAcquisition({ recordedAt: nowMs, recordedBy: 'org-creation' })\n delete copied.copiedFromUid\n return { ...copied, copiedFromUid: creatorUid }\n}\n\n/\n A stored record as a reader should trust it: re-validated field by field,\n * so a document written by an older version, a backfill or a hand edit still\n * renders, and renders nothing it should not. Null when the value is not a\n * record at all.\n /\nexport function readAccountAcquisition(value: unknown): AccountAcquisition \| null {\n if (!value \|\| typeof value !== 'object') return null\n const raw = value as Record<string, unknown>\n const source = label(raw['source'])\n if (!source) return null\n const channel = raw['channel']\n const landing = raw['landing'] as Record<string, unknown> \| null\n const utmRaw = raw['utm'] as Record<string, unknown> \| null\n const utm: FirstTouchUtm = {}\n for (const key of ['source', 'medium', 'campaign', 'content', 'term'] as const) {\n const cleaned = label(utmRaw?.[key])\n if (cleaned) utm[key] = cleaned\n }\n const clickIds = Array.isArray(raw['clickIds'])\n ? (['gclid', 'fbclid', 'msclkid'] as const).filter((id) =>\n (raw['clickIds'] as unknown[]).includes(id),\n )\n : []\n const recordedBy = RECORDED_BY.includes(raw['recordedBy'] as AcquisitionRecordedBy)\n ? (raw['recordedBy'] as AcquisitionRecordedBy)\n : 'backfill'\n const record: AccountAcquisition = {\n v: 1,\n source,\n medium: label(raw['medium']),\n campaign: label(raw['campaign']),\n channel:\n typeof channel === 'string' &&\n [\n 'organic-search',\n 'paid-search',\n 'social',\n 'referral',\n 'email',\n 'direct',\n 'unknown',\n ].includes(channel)\n ? (channel as AcquisitionChannel)\n : 'unknown',\n capturedAt:\n typeof raw['capturedAt'] === 'number' && raw['capturedAt'] > 0\n ? (raw['capturedAt'] as number)\n : null,\n landing:\n landing && label(landing['host'], 253)\n ? { host: label(landing['host'], 253) as string, path: label(landing['path'], 200) ?? '/' }\n : null,\n referrerHost: label(raw['referrerHost'], 253),\n viaHost: label(raw['viaHost'], 253),\n utm: Object.keys(utm).length ? utm : null,\n clickIds,\n adCampaignId:\n typeof raw['adCampaignId'] === 'string' && /^\\d{1,20}$/.test(raw['adCampaignId'])\n ? raw['adCampaignId']\n : null,\n door: doorOf(raw['door']),\n provider: providerOf(raw['provider']),\n invitedToOrgId: uidOf(raw['invitedToOrgId']),\n geo: geoOf(raw['geo']),\n accountCreatedAt: millisOf(raw['accountCreatedAt']),\n recordedAt:\n typeof raw['recordedAt'] === 'number' ? (raw['recordedAt'] as number) : 0,\n recordedBy,\n }\n const copiedFrom = uidOf(raw['copiedFromUid'])\n if (copiedFrom) record.copiedFromUid = copiedFrom\n return record\n}\n\n/* The Google Ads page for a campaign id, opened in whichever account is signed in. /\nexport function googleAdsCampaignUrl(campaignId: string): string {\n return `https://ads.google.com/aw/campaigns?campaignId=${encodeURIComponent(campaignId)}`\n}\n\n/* A sign-in provider id as a person reads it. /\nexport function providerLabel(provider: string \| null \| undefined): string \| null {\n if (!provider) return null\n if (provider === 'password') return 'password'\n if (provider === 'google.com') return 'Google'\n if (provider === 'apple.com') return 'Apple'\n if (provider === 'microsoft.com') return 'Microsoft'\n if (provider === 'github.com') return 'GitHub'\n if (provider.startsWith('saml.') \|\| provider.startsWith('oidc.')) return 'single sign-on'\n return provider\n}\n\nfunction channelPhrase(record: AccountAcquisition): string {\n const from = displayHost(record.referrerHost) \|\| record.source\n const named = record.campaign ?? (record.adCampaignId ? `campaign ${record.adCampaignId}` : null)\n const campaign = named ? `, ${named}` : ''\n switch (record.channel) {\n case 'referral':\n return `Referral from ${from}${campaign}`\n case 'organic-search':\n return `Organic search from ${from}`\n case 'paid-search':\n return `Paid search (${record.source}${campaign})`\n case 'social':\n return `Social from ${from}${campaign}`\n case 'email':\n return `Email (${record.source}${campaign})`\n case 'direct':\n return record.viaHost\n ? `Direct, first seen arriving from ${record.viaHost}`\n : 'Direct'\n default:\n return record.recordedBy === 'backfill'\n ? 'Source unknown — the account predates capture'\n : 'Source unknown — nothing was captured'\n }\n}\n\nfunction doorPhrase(record: AccountAcquisition): string {\n const provider = providerLabel(record.provider)\n switch (record.door) {\n case 'signup-password':\n return 'signed up with password'\n case 'signup-google':\n return 'signed up with Google'\n case 'invite':\n return provider\n ? `signed up from an invitation, with ${provider}`\n : 'signed up from an invitation'\n case 'sso':\n return 'signed in with single sign-on'\n default:\n return provider ? `created with ${provider}` : 'created'\n }\n}\n\n/\n The record as one sentence a staff member reads at a glance:\n * \"Referral from g2.com → /pricing → signed up with password\".\n \n The landing is a bare path when it was on `primaryHost` — the platform's own\n * home — and host-and-path anywhere else, so a docs landing says so.\n */\nexport function describeAccountAcquisition(\n record: AccountAcquisition \| null \| undefined,\n options: { primaryHost?: string \| null } = {},\n): string {\n if (!record) return 'No acquisition record'\n const parts = [channelPhrase(record)]\n if (record.landing) {\n const onPrimary =\n options.primaryHost &&\n displayHost(record.landing.host) === displayHost(options.primaryHost)\n parts.push(\n onPrimary ? record.landing.path : `${displayHost(record.landing.host)}${record.landing.path}`,\n )\n }\n parts.push(doorPhrase(record))\n return parts.join(' → ')\n}\n"],"names":["classifyChannel","displayHost","sanitizeFirstTouch","sourceAndMedium","ACCOUNT_ACQUISITION_FIELD","ACQUISITION_DOORS","MAX_LABEL","PROVIDER_SHAPE","RECORDED_BY","label","value","max","clean","replace","trim","slice","doorOf","includes","providerOf","test","toLowerCase","geoOf","raw","geo","country","toUpperCase","region","city","millisOf","Number","isFinite","uidOf","buildAccountAcquisition","input","touch","nowMs","base","door","provider","invitedToOrgId","accountCreatedAt","accountCreatedAtMs","recordedAt","recordedBy","unknownAccountAcquisition","source","medium","v","campaign","utm","channel","capturedAt","at","landing","host","path","referrerHost","ref","viaHost","via","clickIds","click","adCampaignId","adCampaign","organizationAcquisition","creatorRecord","creatorUid","record","readAccountAcquisition","copied","copiedFromUid","utmRaw","key","cleaned","Array","isArray","filter","id","Object","keys","length","copiedFrom","googleAdsCampaignUrl","campaignId","encodeURIComponent","providerLabel","startsWith","channelPhrase","from","named","doorPhrase","describeAccountAcquisition","options","parts","onPrimary","primaryHost","push","join"],"mappings":"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"}

package/src/lib/app-utils/analytics-events.d.ts CHANGED Viewed

@@ -195,6 +195,13 @@ export interface AnalyticsEventParams {
     site_published: {
         first_publish?: boolean;
     };
+    /**
+     * Custom: no GA4 equivalent (AGL-3594). How a person chose to start a new
+     * site in the guided start: the ready-made starter, or AI.
+     */
+    site_start_choice: {
+        choice: 'starter' | 'ai';
+    };
     /** Custom: no GA4 equivalent. Stripe Connect onboarding completed. */
     stripe_connected: Record<string, never>;
     /** GA4 recommended. A plan checkout started. */

package/src/lib/app-utils/analytics-events.js CHANGED Viewed

@@ -478,6 +478,7 @@ function scrubValue(value) {
     org_created: true,
     host_created: true,
     site_published: true,
+    site_start_choice: true,
     stripe_connected: true,
     begin_checkout: true,
     purchase: true,

package/src/lib/app-utils/analytics-events.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/analytics-events.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 one GA4 event taxonomy, shared by the marketing site (tenant runtime)\n * and the console (AGL-1561). See `docs/ANALYTICS.md` for the event map and\n * which GTM-plan §6 metric each event serves.\n \n ## Why this module exists\n \n Before it, every GA event in the repo was an ad-hoc\n * `;(window as any).gtag?.('event', 'name', {...})` — five of them across the\n * marketing and commerce plugins, plus bare string literals passed to Firebase\n * `logEvent` in the console. Nothing checked the names, nothing checked the\n * params, and a typo produced a silently-missing metric rather than an error.\n * That is the failure mode analytics is worst at surfacing: the number simply\n * reads zero, and zero is indistinguishable from \"nobody did it\".\n \n So the names and their params are a TYPE here ({@link AnalyticsEventParams}),\n * and `trackEvent` is generic over it: a misspelled event name or a missing\n * required param is a compile error.\n \n That sweep missed five (AGL-1591, closed): the commerce plugin's\n * `view_item` / `add_to_cart` / `begin_checkout` and the marketing runtime's\n * `aglyn_overlay` / `aglyn_experiment`. `window.gtag` is now called in exactly\n * two places in the repo — {@link deliver} below, and `readGaClientId` above,\n * which reads rather than sends.\n \n ## Reserved names\n \n Where GA4 has a recommended event we use its exact name and its exact param\n * spelling — `sign_up`, `login`, `generate_lead`, `begin_checkout`,\n * `purchase`, `select_content` — so the built-in reports, the funnel\n * explorations and the \"key events\" toggles work without custom definitions.\n * Custom snake_case names appear only where GA4 has no standard: the four\n * activation events, which are Aglyn-specific product milestones.\n \n ## Consent (AGL-1498) — the gate is that gtag never loads\n \n On tenant sites, including aglyn.com itself, `site-analytics.tsx` renders the\n * gtag `<Script>` pair ONLY when the recorded consent state grants analytics.\n * There is therefore no `window.gtag` at all for a visitor who has not granted,\n * and {@link trackEvent} drops the event on the floor.\n \n It drops it — it does not QUEUE it. That distinction is the whole point and\n * `analytics-events.spec.ts` asserts it: an event fired before consent is gone\n * for good, and does not reappear when a later grant loads gtag. A queue would\n * quietly convert \"we did not track you\" into \"we tracked you and waited\", and\n * a replayed hit carries the pre-consent timestamp and page into GA, which is\n * exactly the thing the consent gate exists to prevent. Deliberately no retry,\n * no buffer, no flush-on-grant.\n \n ## No PII, enforced rather than promised\n \n Every payload passes through {@link sanitizeEventParams} before it reaches a\n * transport: an exact-key denylist drops the identity-bearing params someone\n * will eventually add by reflex (`email`, `org_name`, `first_name`, ...), any\n * value that looks like an email address drops its key entirely, URLs are\n * reduced to origin + pathname so query strings can never smuggle a token or\n * an address, and strings are length-capped. The console separately sets a\n * `user_id` — that is an opaque Firebase uid and is the one identifier GA is\n * allowed to hold.\n \n Sanitizing here rather than at each call site is the point: a new call site\n * cannot forget.\n \n ## Authored events (AGL-1587)\n \n One call site cannot use the taxonomy at all: the `trackGaEvent` action step,\n * whose event name and params are typed by a SITE AUTHOR in the interaction\n * builder. A closed union cannot contain a name nobody has written yet, so\n * {@link trackAuthoredEvent} is the escape hatch — and it is deliberately the\n * only one, so that untrusted input still passes {@link sanitizeEventParams}\n * rather than reaching `window.gtag` raw.\n \n The test for which door an event uses is WHO NAMED IT, not whether GA4\n * recommends the name. `aglyn_overlay` and `aglyn_experiment` are outside GA4's\n * recommended set and were candidates for the hatch (AGL-1591); they are in the\n * union instead, because a developer wrote their names and their keys, so they\n * can have compile-time checking — and because the hatch guarantees the\n * opposite of what they need. {@link resolveAuthoredEventName} refuses any name\n * we send — the union AND the server-only names beside it — precisely so that\n * \"not one of ours\" means \"authored\"; put our own events through the hatch and\n * that stops being true, authored hits stop being separable from ours in\n * reports, and an authored `aglyn_experiment` step starts voting in the\n * experiment that decides which variant ships.\n /\n\n/\n Read the browser's GA `client_id` — the identifier that ties a hit to a GA\n * user and session.\n \n Needed because `purchase` is sent SERVER-side, from the Stripe webhook,\n * where the authoritative money is (see `ga4-measurement-protocol.ts`). The\n * Measurement Protocol requires a `client_id` and a server cannot know one,\n * so it is captured here when checkout starts and carried on the Stripe\n * object's metadata. Without it the revenue still lands, but attached to a\n * synthetic user with no acquisition session — which is exactly the campaign\n * attribution the whole exercise is for.\n \n Resolves to null rather than hanging when gtag is absent (no consent, an ad\n * blocker, analytics not configured) or slow to answer. The 500ms cap matters:\n * this sits directly in front of a checkout redirect, and analytics must never\n * be able to delay a payment.\n /\nexport function readGaClientId(\n measurementId: string \| undefined \| null,\n): Promise<string \| null> {\n return new Promise((resolve) => {\n if (typeof window === 'undefined' \|\| !measurementId) return resolve(null)\n const gtag = (window as unknown as { gtag?: unknown }).gtag\n if (typeof gtag !== 'function') return resolve(null)\n let settled = false\n const finish = (value: string \| null) => {\n if (settled) return\n settled = true\n resolve(value)\n }\n // Never let a missing callback strand the checkout.\n setTimeout(() => finish(null), 500)\n try {\n ;(gtag as (...args: unknown[]) => void)(\n 'get',\n measurementId,\n 'client_id',\n (id: unknown) => finish(typeof id === 'string' && id ? id : null),\n )\n } catch {\n finish(null)\n }\n })\n}\n\n/* Which door an account was created through (AGL-1497 enumerates all four). /\nexport type SignUpMethod =\n \| 'password'\n \| 'google_popup'\n \| 'google_redirect'\n \| 'google_signin'\n\n/* How a returning user authenticated. /\nexport type LoginMethod =\n \| 'password'\n \| 'google_popup'\n \| 'google_redirect'\n \| 'sso'\n \| 'passkey'\n\n/\n A GA4 `items` entry. Only the fields we actually populate — GA accepts more,\n * but an unpopulated field is a column of nulls in every report.\n /\nexport interface AnalyticsItem {\n /* Opaque identifier — a price id, plan key or marketplace listing id. /\n item_id: string\n /* Human-readable product name. NEVER a customer or org name. /\n item_name: string\n /* Distinguishes the revenue lines: `subscription` vs `marketplace`. /\n item_category?: string\n price?: number\n quantity?: number\n}\n\n/\n The taxonomy. Adding an event means adding a line here first — which is what\n * makes `docs/ANALYTICS.md` checkable against the code rather than aspirational.\n /\nexport interface AnalyticsEventParams {\n // --- Acquisition (GTM §6: signups, cost/lead by channel) -----------------\n /\n GA4 recommended. Real account creation only, never a sign-in.\n \n The three campaign params are optional and come from\n * `utmEventParams` (AGL-1731) — present when the signup URL named a\n * campaign, absent entirely otherwise. They are what lets a September ad\n * spend be evaluated: without them a paid click, an organic visit and a\n * partner link arrive indistinguishable and the money cannot be traced to\n * an account. Named `campaign_` rather than `utm_` because these are our\n * own registered dimensions and the `utm_` spellings belong to GA's\n * automatic campaign collection.\n /\n sign_up: {\n method: SignUpMethod\n campaign_source?: string\n campaign_medium?: string\n campaign_name?: string\n }\n /* GA4 recommended. Returning user only. /\n login: { method: LoginMethod }\n /\n GA4 recommended. Fired on a SUCCESSFUL form submission — never on click,\n * never on a validation failure. `form_name` is the author-given form name,\n * which is site content and not personal data.\n /\n generate_lead: { form_name: string; form_location?: string }\n /\n GA4 recommended. A CTA click, with the section that produced it.\n \n Fired by `analytics-link-clicks.ts` (AGL-1562) from a delegated listener,\n * not per call site: an authored page has no code to add a handler to.\n /\n select_content: {\n content_type: string\n content_id: string\n /* Which product surface — see `click.surface`. /\n surface?: string\n }\n\n // --- Activation (GTM §6: % publish a site, % connect Stripe) -------------\n /* Custom: no GA4 equivalent. A new organization exists. /\n org_created: { plan?: string }\n /* Custom: no GA4 equivalent. A new site/host exists. /\n host_created: Record<string, never>\n /\n Custom: no GA4 equivalent, and the GTM plan's headline activation metric.\n * A site actually went live.\n /\n site_published: { first_publish?: boolean }\n /* Custom: no GA4 equivalent. Stripe Connect onboarding completed. /\n stripe_connected: Record<string, never>\n\n // --- Revenue (GTM §6: paid conversions, ARPA, annual mix) ---------------\n /* GA4 recommended. A plan checkout started. /\n begin_checkout: {\n currency: string\n value: number\n items: AnalyticsItem[]\n /* `monthly` \| `annual` — feeds the §6 annual-mix metric. /\n billing_interval?: string\n }\n /\n GA4 recommended. A payment actually succeeded. `transaction_id` is the\n * Stripe object id and is what makes the event idempotent in GA: GA4\n * de-duplicates purchases by transaction id, so a webhook retry cannot\n * inflate revenue.\n /\n purchase: {\n transaction_id: string\n currency: string\n value: number\n items: AnalyticsItem[]\n billing_interval?: string\n /\n GA4's shipping charged on the transaction, in currency units. Optional\n * because only a tenant STOREFRONT purchase ships anything — a plan or a\n * marketplace purchase has no shipping to report and omits it.\n \n There is deliberately no sibling `tax` (AGL-1639, AGL-1641). The\n * asymmetry is the point and is not an inconsistency to tidy away:\n * `shipping` is a COMPONENT of the `value` beside it, so reporting it\n * describes that value; `tax` is not, because `value` is already ex-tax,\n * so reporting it would assert a relationship that does not hold and\n * invite the subtraction that removes tax a second time.\n /\n shipping?: number\n }\n\n // --- Commerce (tenant storefronts, AGL-1591) -----------------------------\n /\n GA4 recommended. A product detail page was viewed on a tenant storefront.\n \n Only `items`, and only `item_id`/`item_name` within it: those are the two\n * fields the storefront actually has at this point, and an unpopulated\n * `price`/`item_category` would be a column of nulls in the merchant's\n * reports. The item id is the PRODUCT id — the same id `add_to_cart` and\n * `begin_checkout` use — which is what lets GA join the three into one\n * per-product funnel.\n /\n view_item: { items: AnalyticsItem[] }\n /\n GA4 recommended. A storefront product was added to the cart.\n \n `currency`/`value` are optional because GA4 pairs them — a `value` with no\n * `currency` is dropped by GA — so they travel together or not at all, and\n * {@link buildAddToCartParams} is what keeps that true. They are populated\n * wherever the surface holds a server-priced figure: the product detail\n * block knows the resolved variant's price and the chosen quantity, so the\n * merchant's \"value added to cart\" is a real number rather than the empty\n * column an items-only hit produces.\n /\n add_to_cart: { currency?: string; value?: number; items: AnalyticsItem[] }\n /\n GA4 recommended. The shopper looked at their cart — the funnel step\n * between {@link AnalyticsEventParams.add_to_cart} and\n * {@link AnalyticsEventParams.begin_checkout}, and the one GA4's own\n * shopping-behavior report reads to tell \"never opened the cart\" apart from\n * \"opened it and did not check out\". Without it those two collapse into one\n * drop, and the merchant cannot tell a discovery problem from a pricing one.\n \n Fired when the cart is actually ON SCREEN carrying lines — a drawer that\n * opened, or an inline cart block that resolved — never on the badge render\n * that every page of a storefront performs. An empty cart is not a view of\n * anything and reports nothing.\n /\n view_cart: { currency: string; value: number; items: AnalyticsItem[] }\n\n // --- Engagement ---------------------------------------------------------\n /\n Custom: no GA4 equivalent. An announcement bar or popup was shown,\n * dismissed or clicked on a tenant site (AGL-200/271).\n \n In the taxonomy rather than {@link trackAuthoredEvent} even though it is\n * not a GA4 recommended name: the name and every key here are written by US,\n * which is exactly what the closed union is for. See the note on\n * {@link trackAuthoredEvent} for why the two must not be mixed.\n /\n aglyn_overlay: { overlay_action: string; overlay_id?: string }\n /\n Custom: no GA4 equivalent. An experiment exposure or conversion\n * (AGL-253). `experiment_action` is `exposure` \| `conversion`.\n \n Being in the union also makes the name RESERVED against authored events,\n * which matters more here than anywhere else in this file: these are the\n * counts that decide which variant wins, and a hand-authored\n * `aglyn_experiment` step would silently vote in that election.\n /\n aglyn_experiment: {\n experiment_id: string\n variant_id: string\n experiment_action: string\n }\n /\n GA4 recommended-ish. Outbound click to docs, GitHub, etc. Fired by\n * `analytics-link-clicks.ts` (AGL-1562) rather than at a call site.\n /\n click: {\n link_domain: string\n link_id?: string\n /\n Which product surface produced the click. GA's built-in Hostname\n * dimension already separates the DOMAINS; this separates surfaces that\n * could share one, and keeps the shared click listener from having to\n * know anything about either.\n \n `site` — a tenant published site — is the only value ever SENT. `docs`\n * was designed for (AGL-1579) and is not emitted: `apps/docs` cannot\n * import `libs/`, so this listener is not installed there\n * (docs/ANALYTICS.md decision 7 has the Vercel setting that would change\n * that). Registering `surface` as a dimension and reading a one-value\n * breakdown is the trap — the absent `docs` row means \"no listener\", not\n * \"no clicks\".\n /\n surface?: string\n }\n /\n Custom: no GA4 equivalent. One Aglyn Assist message sent (AGL-1860).\n * `tier` is the capability tier served (`free` \| `entitled`);\n * `grounded` says whether docs retrieval found sections to cite —\n * ungrounded questions at volume are the docs-gap signal the data loop\n * mines. No question text: params carry no user content.\n /\n assistant_message_sent: { tier: string; grounded: boolean }\n /\n Custom: no GA4 equivalent. Explicit thumbs on an Assist answer\n * (AGL-1860). `feedback` is `up` \| `down`.\n /\n assistant_feedback: { feedback: string }\n /\n Custom: no GA4 equivalent. Aglyn Assist offered to open a page for the\n * user (AGL-1988, level 2). `action` is the registry action id — a closed\n * set, so it carries no user content.\n \n The pair below is the only read on whether the confirm gate is a real\n * choice or a speed bump people click through. A shown-to-confirmed ratio\n * near 1 means the card is not being read, and the copy has to change\n * BEFORE the ladder goes anywhere near a write.\n /\n assistant_proposal_shown: { action: string }\n /* Custom: no GA4 equivalent. The user confirmed and was navigated. /\n assistant_proposal_confirmed: { action: string }\n /\n Custom: no GA4 equivalent. An AI generation job reached `done`\n * (AGL-2904), observed from the console's jobs drawer. `kind` is the\n * closed `AiJobKind` set and `credits` the job's spend at the plan's\n * credit rate — no brief, no output: params carry no user content.\n /\n ai_job_completed: { kind: string; credits: number }\n /\n Custom: no GA4 equivalent. An AI generation job reached `failed`\n * (AGL-2904). `kind` only; the failure text is a fixed customer-safe\n * sentence and says nothing a rate could use.\n /\n ai_job_failed: { kind: string }\n\n // --- Retention (AGL-1859/AGL-1863: the leave path, measurable) -----------\n /\n Custom: no GA4 equivalent. The churn survey was answered — step 1 of the\n * cancellation/deletion funnel, and the DENOMINATOR every step below is a\n * rate against. Fired for both leave paths.\n \n `reason` is the closed `ChurnSurveyReason` set, never the free-text\n * detail: the detail is customer-written prose, it belongs in Firestore\n * where the data loop reads it, and shipping it to GA would put user\n * content in analytics params. `surface` separates a subscription cancel\n * from an account delete — counting only one understates churn by exactly\n * the orgs that chose the other.\n /\n churn_survey_submitted: { reason: string; surface: string; plan?: string }\n /\n Custom: no GA4 equivalent. The customer took the smaller tier instead of\n * leaving — a SAVE, at reduced ARPA. `from_plan`/`to_plan` are what makes\n * that tradeoff measurable rather than a win recorded without its cost.\n /\n downsell_accepted: { from_plan: string; to_plan: string; surface: string }\n /\n Custom: no GA4 equivalent. The time-boxed winback discount was accepted.\n \n `percent_off` and `duration_months` are reported because the discount is\n * bounded and the bound is the entire point (AGL-1620/AGL-1863): a retained\n * org and the margin it was retained at are one fact, and a save recorded\n * without its price reads as free.\n /\n winback_discount_accepted: {\n percent_off: number\n duration_months: number\n plan?: string\n surface: string\n }\n /\n Custom: no GA4 equivalent. They left anyway — the funnel's terminal step,\n * and the numerator for churn.\n \n `funnel_completed` is false when the cancel arrived without a funnelId\n * (support ops, Stripe dashboard). It mirrors the `funnelSkipped` marker\n * the routes write, so the GA funnel and the Firestore record agree instead\n * of quietly disagreeing about how many departures were ever surveyed.\n /\n cancellation_completed: {\n surface: string\n plan?: string\n funnel_completed: boolean\n }\n\n // --- Plan changes taken from the grid (AGL-2235, under AGL-1859 §4) ------\n /\n Custom: no GA4 equivalent. A downgrade was confirmed and SCHEDULED from\n * the billing plan grid — the same economic event `downsell_accepted`\n * records, arrived at by the other door.\n \n Why this has to exist separately: all four retention events above fire\n * from `retention-funnel.dialog.tsx` and from nowhere else. A customer who\n * moves Pro → Starter through the cancel funnel is counted; a customer who\n * moves Pro → Starter by clicking Downgrade on the plan card was counted by\n * nothing. So \"how many orgs moved down\" was unanswerable, and the number\n * that WAS answerable — `downsell_accepted` — undercounted by exactly the\n * share that took the direct route while reading like a total. A save rate\n * computed against it is wrong in the flattering direction, which is the\n * worst direction for a retention number to be wrong in.\n \n `effective_at` is the whole point of the event's name: this is the\n * asymmetric-friction arm of AGL-1859 §2, and a downgrade that has been\n * SCHEDULED is not a downgrade that has HAPPENED. Reported as the server's\n * ISO date so the gap between decision and effect — up to a full cycle, and\n * the window in which \"keep my plan\" can still save the org — is visible in\n * the data instead of being collapsed into the decision day.\n \n No amount, price or fee: pricing is locked for Sept 1, money belongs to\n * `purchase`/`refund`, and a tier pair already says what changed.\n /\n plan_downgrade_scheduled: {\n from_plan: string\n to_plan: string\n interval: string\n effective_at?: string\n }\n /\n Custom: no GA4 equivalent. An existing subscriber moved UP in place.\n \n Not `app_upgrade` — that name is GA4-RESERVED (it means an app binary\n * version bump) and a hit using it is dropped, which is silence rather than\n * pollution and therefore the harder failure to notice.\n \n `purchase` covers only the Checkout path, so before this, expansion\n * revenue from customers who ALREADY had a subscription was dark: the\n * in-place switch never opens a Checkout and never mints a new\n * subscription, so nothing in the revenue taxonomy saw it. Upgrades are the\n * half of AGL-1859 §2 that is supposed to be frictionless, and an\n * unmeasured half cannot be shown to be.\n /\n plan_upgraded: {\n from_plan: string\n to_plan: string\n interval: string\n }\n}\n\nexport type AnalyticsEventName = keyof AnalyticsEventParams\n\n/\n Where a sanitized event goes. The console registers a Firebase\n * `logEvent` transport; the tenant runtime and the plugin bundles have none\n * and fall through to `window.gtag`, which only exists once consent has been\n * granted.\n /\nexport type AnalyticsTransport = (\n name: AnalyticsEventName,\n params: Record<string, unknown>,\n) => void \| Promise<void>\n\nlet configuredTransport: AnalyticsTransport \| null = null\n\n/\n Register the transport for this surface. The console calls this once, with\n * Firebase's `logEvent`, because the console's GA is Firebase-initialised and\n * its `user_id`/user-property state lives on the Firebase Analytics instance —\n * poking `window.gtag` directly there would emit hits that miss it.\n \n The tenant runtime deliberately does NOT call this: the plugin bundles run\n * in their own realm and do not share this module instance with the host app,\n * so a module-scope singleton would be invisible to exactly the call sites\n * that need it (the form and newsletter elements). `window.gtag` is the only\n * thing genuinely shared across that boundary, and it is also the consent\n * gate, which makes the fallback the correct primary path there rather than a\n * degraded one.\n /\nexport function configureAnalyticsTransport(\n transport: AnalyticsTransport \| null,\n): void {\n configuredTransport = transport\n}\n\n/* Test seam — drops the registered transport. /\nexport function resetAnalyticsTransport(): void {\n configuredTransport = null\n}\n\n/\n Param keys that must never reach GA, matched EXACTLY. Substring matching\n * would be wrong in both directions: it would drop the legitimate\n * `form_name` / `item_name` / `link_domain`, and it would still miss a\n * creatively-named new one. The value scan below is the backstop for those.\n /\nconst DENIED_PARAM_KEYS: ReadonlySet<string> = new Set([\n 'email',\n 'email_address',\n 'user_email',\n 'name',\n 'full_name',\n 'first_name',\n 'last_name',\n 'user_name',\n 'username',\n 'customer_name',\n 'org_name',\n 'organization_name',\n 'company',\n 'company_name',\n 'phone',\n 'phone_number',\n 'address',\n 'street',\n 'postal_code',\n 'zip',\n 'ip',\n 'ip_address',\n])\n\n/* Deliberately loose — this is a \"does it smell like an address\" test. /\nconst EMAIL_SHAPED = /[^\\s@]+@[^\\s@]+\\.[^\\s@]+/\n\n/\n GA4 truncates param values at 100 chars anyway; do it ourselves, visibly.\n \n Exported because an AUTHOR types some of these (the `trackGaEvent` step's\n * parameters), and the field they type into caps its input at the same number\n * — the truncation point and the affordance that describes it have to be one\n * value, or the editor promises a length the delivery quietly shortens.\n /\nexport const ANALYTICS_PARAM_MAX_LENGTH = 100\n\nfunction scrubValue(value: string): string \| null {\n let candidate = value\n if (/^https?:\\/\\//i.test(candidate)) {\n try {\n const url = new URL(candidate)\n // Origin + pathname only: a query string is where a session token, a\n // signup email or a Stripe id ends up, and none of them belong in GA.\n candidate = `${url.origin}${url.pathname}`\n } catch {\n return null\n }\n }\n // AFTER the URL reduction, not before. A page URL routinely carries an\n // address in its query (`?email=…` on a prefilled signup link), and testing\n // the raw string would throw the whole URL away for PII that the reduction\n // was about to remove — losing the legitimate page dimension to protect\n // something already protected. Testing the REDUCED value still catches an\n // address embedded in the path itself, which the reduction keeps.\n if (EMAIL_SHAPED.test(candidate)) return null\n return candidate.slice(0, ANALYTICS_PARAM_MAX_LENGTH)\n}\n\n/\n Strip anything identity-bearing from an event payload. Exported so\n * `analytics-events.spec.ts` can assert the guarantee directly rather than\n * only through `trackEvent`.\n /\nexport function sanitizeEventParams(\n params: Record<string, unknown> \| undefined,\n): Record<string, unknown> {\n const safe: Record<string, unknown> = {}\n if (!params) return safe\n for (const [key, value] of Object.entries(params)) {\n if (DENIED_PARAM_KEYS.has(key.toLowerCase())) continue\n if (value === undefined \|\| value === null) continue\n if (typeof value === 'string') {\n const scrubbed = scrubValue(value)\n if (scrubbed === null \|\| scrubbed === '') continue\n safe[key] = scrubbed\n continue\n }\n if (typeof value === 'number' \|\| typeof value === 'boolean') {\n safe[key] = value\n continue\n }\n if (Array.isArray(value)) {\n // `items` — sanitize each entry with the same rules.\n safe[key] = value.map((entry) =>\n entry && typeof entry === 'object'\n ? sanitizeEventParams(entry as Record<string, unknown>)\n : entry,\n )\n continue\n }\n if (typeof value === 'object') {\n safe[key] = sanitizeEventParams(value as Record<string, unknown>)\n }\n // Anything else (function, symbol) is dropped.\n }\n return safe\n}\n\n/\n Fire a GA4 event.\n \n Never throws and never queues. If the surface has no transport and no\n * `window.gtag` — which on a tenant site means the visitor has not granted\n * analytics consent — the event is DROPPED, permanently. See the module\n * comment for why a queue would be the wrong answer.\n /\nexport function trackEvent<K extends AnalyticsEventName>(\n name: K,\n params: AnalyticsEventParams[K],\n): void {\n deliver(name, sanitizeEventParams(params as Record<string, unknown>))\n}\n\n/\n How long a navigation may be held waiting for a hit to reach gtag. Short\n * enough to be invisible next to a Stripe redirect, long enough to cover a\n * Firebase Analytics init that has not settled yet.\n /\nconst NAVIGATION_FLUSH_TIMEOUT_MS = 300\n\n/\n Fire a GA4 event and resolve once it has been HANDED TO gtag — for the call\n * sites that navigate away in the same tick (AGL-1580).\n \n ## What was actually losing the event\n \n Not the transport, which was the obvious suspect and the wrong one. Measured\n * against real gtag.js with every transport interposed: gtag flushes its queue\n * on pagehide through `fetch(..., { keepalive: true })`, which is precisely the\n * mechanism that survives a document teardown. Once a hit reaches gtag, a\n * navigation does not destroy it — and `transport_type: 'beacon'`, the standard\n * answer, therefore fixes nothing here.\n \n What is lost is the hit that never REACHES gtag. Firebase's `logEvent` is\n * `async` and awaits the SDK's initialization promise before calling gtag\n * (`@firebase/analytics/dist/index.cjs.js`, `logEvent$1`). While that promise is\n * already settled the continuation is a microtask, microtasks drain before the\n * queued navigation task, and the hit gets out. While it is still PENDING — the\n * first checkout of a fresh session, exactly the case that has never yet been\n * seen in the property — the continuation is scheduled behind the navigation\n * and never runs at all. Measured both ways: pending init loses the event,\n * awaiting it delivers it, nothing else changed.\n \n ## Why a timeout rather than a bare await\n \n A bare `await` on `logEvent` hands the user's redirect to the analytics\n * stack. When the analytics host is blocked — an ad blocker, a corporate proxy,\n * a consent tool that never loads — Firebase's initialization promise can stay\n * pending indefinitely, and the checkout would hang on a metric. So the wait is\n * RACED against {@link NAVIGATION_FLUSH_TIMEOUT_MS}: a blocked analytics stack\n * costs the redirect 300ms once and then it proceeds, which is the same outcome\n * the caller had before this existed. Never rejects, for the same reason\n * {@link trackEvent} never throws.\n \n On a surface with no registered transport — the tenant runtime and the plugin\n * bundles, which go straight to `window.gtag` — delivery is synchronous, so\n * this resolves immediately and costs the storefront checkout nothing at all.\n /\nexport async function trackEventBeforeNavigation<K extends AnalyticsEventName>(\n name: K,\n params: AnalyticsEventParams[K],\n): Promise<void> {\n const delivered = deliver(\n name,\n sanitizeEventParams(params as Record<string, unknown>),\n )\n // Synchronous transport (or none): already handed over, nothing to wait for.\n if (!delivered \|\| typeof delivered.then !== 'function') return\n await Promise.race([\n // A transport that REJECTS must not become an unhandled rejection, and\n // must not hold the navigation either — it has already failed.\n Promise.resolve(delivered).catch((): void => undefined),\n new Promise<void>((resolve) =>\n setTimeout(resolve, NAVIGATION_FLUSH_TIMEOUT_MS),\n ),\n ])\n}\n\n/\n Build the ONE `begin_checkout` payload, for every surface that starts a\n * checkout (AGL-1591).\n \n ## Why a constructor and not just the type\n \n Two surfaces fire this name: the console, when a plan checkout starts, and a\n * tenant storefront, when a cart checks out. Until AGL-1591 the storefront\n * fired it raw and carried `value`/`currency` only, so ONE event name arrived\n * in two shapes — and a `begin_checkout` breakdown showed two populations that\n * could not be compared, with the storefront half missing the `items` the GA4\n * ecommerce funnel is built on. Routing both through {@link trackEvent} makes\n * the compiler settle the KEYS.\n \n It does not settle the NUMBER, which is the other way two call sites of one\n * event diverge, and the more dangerous one because nothing about it looks\n * wrong: the console's annual plans are priced per-month-billed-yearly, so its\n * `value` is twelve of them, and that only stayed right because a comment said\n * so. Here `value` DERIVES from the items unless a caller states a different\n * one — a cart states its subtotal, which is authoritative after discounts —\n * so \"what the customer is about to be charged\" has one definition rather than\n * one per surface.\n \n Server-safe: pure, no DOM, so the Measurement Protocol sender can compose\n * the matching `purchase` items from the same shapes.\n /\nexport function buildBeginCheckoutParams(input: {\n items: AnalyticsItem[]\n /\n The amount actually being charged. Defaults to the sum of the items'\n * `price * quantity`, which is right whenever nothing has adjusted it.\n /\n value?: number\n /* ISO 4217. Defaults to `USD`, the only currency either surface bills in. /\n currency?: string\n /* `monthly` \| `annual`. Subscriptions only — a storefront cart has none. /\n billingInterval?: string\n}): AnalyticsEventParams['begin_checkout'] {\n return {\n ...priceItems(input),\n ...(input.billingInterval ? { billing_interval: input.billingInterval } : {}),\n }\n}\n\n/\n The `currency`/`value`/`items` triple every GA4 ecommerce step shares.\n \n Private, because a caller should reach for the named builder for the event\n * it is about to send: the names differ in what they mean by `value` even\n * though the arithmetic is identical, and the JSDoc on each is where that is\n * written down.\n /\nfunction priceItems(input: {\n items: AnalyticsItem[]\n value?: number\n currency?: string\n}): { currency: string; value: number; items: AnalyticsItem[] } {\n const items = input.items ?? []\n const summed = items.reduce(\n (total, item) => total + (item.price ?? 0) (item.quantity ?? 1),\n 0,\n )\n return {\n currency: input.currency ?? 'USD',\n // Money, so two decimals: a float sum of cents-derived prices produces\n // `59.99999999999999`, and GA would report that verbatim.\n value: Math.round((input.value ?? summed) * 100) / 100,\n items,\n }\n}\n\n/*\n Build `view_cart` — the shopper is looking at the cart's contents.\n \n `value` is the cart's subtotal as the SERVER priced it, which is what makes\n * this comparable with the `begin_checkout` the same cart sends moments later:\n * two steps of one funnel that disagreed about the size of the same cart would\n * read as shoppers editing it between screens.\n /\nexport function buildViewCartParams(input: {\n items: AnalyticsItem[]\n value?: number\n currency?: string\n}): AnalyticsEventParams['view_cart'] {\n return priceItems(input)\n}\n\n/\n Build `add_to_cart` — one product going in, not the cart's new total.\n \n `value` is what was JUST ADDED (`price * quantity`), which is GA4's\n * definition and the only one that makes the metric additive: summing a\n * running cart total over a session would count the first item once per\n * subsequent add.\n \n Callers that cannot price the line — a quick-add with no resolved variant —\n * pass items alone and the pair is omitted rather than reported as zero. A\n * zero here would read as a free product in the merchant's report.\n /\nexport function buildAddToCartParams(input: {\n items: AnalyticsItem[]\n value?: number\n currency?: string\n}): AnalyticsEventParams['add_to_cart'] {\n const priced = priceItems(input)\n if (!(priced.value > 0)) return { items: priced.items }\n return priced\n}\n\n/\n Decide `site_published`'s `first_publish` from the host's routing map as it\n * stood BEFORE the route being published was registered (AGL-1588).\n \n ## What \"first\" means, and why it is defined once\n \n Three call sites report `site_published` — `publishScreenRoute`, the\n * besigner's one-click publish, and the scheduled publish executor, the last\n * of which is server-side and sends over the Measurement Protocol. A\n * breakdown is only worth registering if all three mean the same thing by it,\n * and \"first\" has several plausible readings. This is the one they share:\n \n The host had no live route at all before this one. Not \"first for the\n * org\" — that needs a cross-host query the server path cannot make, and the\n * scheduled sender's client id is derived from the HOST anyway, so an org is\n * not a thing it can see. Not \"first for this screen\" either, which would be\n * true of every second page a site adds and would make the dimension a\n * synonym for the event.\n \n So the metric it separates is the GTM §6 activation one: `first_publish:\n * true` counts sites that came alive, where the event alone counts publishes.\n \n ## The one dishonesty, and why it does not matter\n \n Unpublishing every route and publishing again reports `true` a second time.\n * Detecting that needs publish history the routing map does not keep. It is\n * harmless for the metric it exists for, because activation is read as the\n * share of USERS who ever sent `first_publish: true`, and a user counted twice\n * is still one user.\n \n Callers pass what they already hold — the live-subscribed map in the\n * console, a read snapshot on the server — and never a map read back AFTER\n * the write, which is never empty.\n \n ## The placeholder home page is not a publish (AGL-3408)\n \n Every new site is created with a home page already routed at `/`, so read\n * literally the map is never empty and no site would ever report a first\n * publish. The host's `defaultHomeScreenId` names that placeholder, and its\n * entry is not counted: the site \"came alive\" when its owner put something on\n * it, not when the platform did. Republishing the placeholder itself after\n * editing it counts, which is the same act: that publish is read against the\n * map with the marker still set, and clears it in the same write (AGL-3478).\n /\nexport function isFirstPublishedRoute(\n routing: Record<string, unknown> \| null \| undefined,\n defaultHomeScreenId?: string \| null,\n): boolean {\n return !Object.keys(routing ?? {}).some(\n (screenId) => screenId !== defaultHomeScreenId,\n )\n}\n\n/\n The one delivery path, shared by {@link trackEvent} and\n * {@link trackAuthoredEvent}. Takes an ALREADY-sanitized payload — every\n * caller sanitizes first, which is what keeps \"a new call site cannot forget\"\n * true of the authored path too.\n /\nfunction deliver(\n name: string,\n safe: Record<string, unknown>,\n): void \| Promise<void> {\n try {\n if (configuredTransport) {\n // The transport's name parameter is the taxonomy union, which an\n // authored name is by definition outside. Nominal only: the console is\n // the sole surface that registers one and it has no authored events\n // (the interaction runtime is tenant-side), and Firebase `logEvent`\n // takes an arbitrary string regardless.\n // Returned, not discarded (AGL-1580). A transport may be ASYNC —\n // Firebase's `logEvent` awaits the SDK's initialization promise before it\n // reaches gtag at all — and a caller that is about to navigate has to be\n // able to wait for it. See `trackEventBeforeNavigation`.\n return configuredTransport(name as AnalyticsEventName, safe)\n }\n if (typeof window === 'undefined') return\n const gtag = (window as unknown as { gtag?: unknown }).gtag\n if (typeof gtag !== 'function') return\n // Synchronous, so nothing is returned and nothing needs awaiting: by the\n // time this call has returned, gtag.js already holds the hit.\n ;(gtag as (...args: unknown[]) => void)('event', name, safe)\n } catch {\n // Analytics never breaks the page — the same posture as the error beacon\n // and the pageview beacon.\n }\n}\n\n/\n The taxonomy's names at RUN time. A `Record<AnalyticsEventName, true>` rather\n * than a hand-kept array so the compiler enforces both directions: adding an\n * event to {@link AnalyticsEventParams} without adding it here is a missing-key\n * error, and a name here that is not in the taxonomy is an excess-property one.\n \n It exists for {@link trackAuthoredEvent}, which has to refuse these names —\n * a drifting copy would silently re-open the collision it is here to close.\n /\nconst TAXONOMY_EVENT_NAMES: Record<AnalyticsEventName, true> = {\n sign_up: true,\n login: true,\n generate_lead: true,\n select_content: true,\n org_created: true,\n host_created: true,\n site_published: true,\n stripe_connected: true,\n begin_checkout: true,\n purchase: true,\n view_item: true,\n add_to_cart: true,\n view_cart: true,\n aglyn_overlay: true,\n aglyn_experiment: true,\n click: true,\n assistant_message_sent: true,\n assistant_feedback: true,\n assistant_proposal_shown: true,\n assistant_proposal_confirmed: true,\n ai_job_completed: true,\n ai_job_failed: true,\n churn_survey_submitted: true,\n downsell_accepted: true,\n winback_discount_accepted: true,\n cancellation_completed: true,\n plan_downgrade_scheduled: true,\n plan_upgraded: true,\n}\n\n/* The taxonomy, enumerable. /\nexport const ANALYTICS_EVENT_NAMES = Object.keys(\n TAXONOMY_EVENT_NAMES,\n) as AnalyticsEventName[]\n\n/\n Event names WE send that this module's union cannot hold, because nothing\n * client-side ever fires them: they are emitted only by the Measurement\n * Protocol sender (`ga4-measurement-protocol.ts`), from a Stripe webhook.\n \n They still have to be RESERVED against authored names, and the reason is\n * the same one that puts `purchase` in the union — only less obvious, which\n * is why it was missed. `aglyn.com` is itself a tenant site, pointed at the\n * platform measurement id (`site-analytics.tsx`), so an authored\n * `trackGaEvent` step on our own marketing site lands in the SAME property as\n * these server hits. An authored `refund` does not merely add noise: GA4\n * treats `refund` as ecommerce and SUBTRACTS its `value` from reported\n * revenue, so a mistyped step could walk real money out of the report — the\n * `purchase` hazard, running in the direction nobody audits.\n \n Kept as a separate list rather than folded into {@link AnalyticsEventParams}\n * on purpose: adding them to the union would give {@link trackEvent} a\n * client-side door to events that must only ever come from the server, where\n * the authoritative money is. A name here is ours, is never sent from a\n * browser, and is never available to an author.\n \n This list is the reason \"not in {@link ANALYTICS_EVENT_NAMES}\" is NOT on its\n * own a sound test for \"authored\" — use {@link isReservedAnalyticsEventName}.\n /\nconst SERVER_ONLY_EVENT_NAMES: ReadonlySet<string> = new Set([\n 'refund',\n 'subscription_cancelled',\n])\n\n/\n Every event name Aglyn itself sends, from any surface — the union plus the\n * server-only names above. Exported so a caller can ask the question the two\n * separate lists no longer answer alone.\n /\nexport function isReservedAnalyticsEventName(name: string): boolean {\n return (\n TAXONOMY_EVENT_NAMES[name as AnalyticsEventName] === true \|\|\n SERVER_ONLY_EVENT_NAMES.has(name)\n )\n}\n\n/\n GA4's own reserved event names — GA drops a hit that uses one, so sending it\n * is not pollution but silence, which is the worse failure of the two because\n * nothing anywhere says so.\n /\nconst GA4_RESERVED_EVENT_NAMES: ReadonlySet<string> = new Set([\n 'ad_activeview',\n 'ad_click',\n 'ad_exposure',\n 'ad_impression',\n 'ad_query',\n 'ad_reward',\n 'adunit_exposure',\n 'app_background',\n 'app_clear_data',\n 'app_exception',\n 'app_install',\n 'app_remove',\n 'app_store_refund',\n 'app_store_subscription_cancel',\n 'app_store_subscription_convert',\n 'app_store_subscription_renew',\n 'app_update',\n 'app_upgrade',\n 'dynamic_link_app_open',\n 'dynamic_link_app_update',\n 'dynamic_link_first_open',\n 'error',\n 'first_open',\n 'first_visit',\n 'in_app_purchase',\n 'notification_dismiss',\n 'notification_foreground',\n 'notification_open',\n 'notification_receive',\n 'os_update',\n 'screen_view',\n 'session_start',\n 'user_engagement',\n])\n\n/* GA4 reserves these prefixes outright, whatever follows them. /\nconst GA4_RESERVED_PREFIXES = ['firebase_', 'google_', 'ga_'] as const\n\n/* GA4's hard limit on an event name. Over it, GA drops the event. /\nconst MAX_EVENT_NAME_LENGTH = 40\n\n/\n The outcome of putting an authored name through GA4's rules, so the\n * interaction builder can say WHY it refused a name and the runtime can drop\n * the event for the same reason.\n /\nexport interface ResolvedAuthoredEventName {\n /* The name to send, or null when the event must not be sent at all. /\n name: string \| null\n /\n `reserved` — collides with the taxonomy or with GA4's own names.\n * `unusable` — nothing survives normalization (empty, or no leading letter).\n /\n reason?: 'reserved' \| 'unusable'\n}\n\n/\n Put an authored event name through GA4's naming rules and our own.\n \n Normalization is forgiving on purpose: `\"CTA Click!\"` becomes `cta_click`\n * and still reports, where GA would have dropped it. Names already sitting in\n * published sites were never validated, so refusing them outright would delete\n * working metrics from a paying customer's property to fix a formatting nit.\n \n Collisions, in contrast, are refused rather than rewritten. On a tenant site\n * the authored events and OUR events (`generate_lead` from the form element,\n * `select_content`/`click` from the link listener) land in the same property,\n * so an authored `purchase` does not merely add noise — it mixes hand-authored\n * hits into a real revenue number. Refusing is also what keeps authored events\n * separable in reports: an event that is not one of {@link ANALYTICS_EVENT_NAMES}\n * is, by construction, authored.\n \n Deliberately NOT prefixed (`site_`) to achieve that separation. A prefix\n would rename events already flowing into customers' properties and break\n * every report and key-event conversion configured on the old name — a\n * migration cost paid by people who did nothing wrong.\n /\nexport function resolveAuthoredEventName(\n raw: string \| undefined \| null,\n): ResolvedAuthoredEventName {\n const normalized = String(raw ?? '')\n .trim()\n .toLowerCase()\n // Anything GA4 does not allow in a name becomes an underscore...\n .replace(/[^a-z0-9_]+/g, '_')\n // ...and a name must START with a letter, so drop what precedes one.\n .replace(/^[^a-z]+/, '')\n .replace(/_{2,}/g, '_')\n .slice(0, MAX_EVENT_NAME_LENGTH)\n // Truncation can leave a trailing underscore; so can the substitution.\n .replace(/_+$/, '')\n if (!normalized) return { name: null, reason: 'unusable' }\n if (\n isReservedAnalyticsEventName(normalized) \|\|\n GA4_RESERVED_EVENT_NAMES.has(normalized) \|\|\n GA4_RESERVED_PREFIXES.some((prefix) => normalized.startsWith(prefix))\n ) {\n return { name: null, reason: 'reserved' }\n }\n return { name: normalized }\n}\n\n/* One warning per distinct name per page load — an `everyTime` automation\n * would otherwise fill the console with the same line. /\nconst warnedAuthoredNames = new Set<string>()\n\n/\n Fire an event whose name and params were written by a SITE AUTHOR, not by a\n * developer — today only the `trackGaEvent` action step (AGL-1587).\n \n Same consent gate, same sanitizer, same drop-never-queue posture as\n * {@link trackEvent}; the only difference is that the name is checked at run\n * time instead of by the compiler, because there is no compiler between the\n * interaction builder and here.\n \n A refused event is dropped and warned about in the console rather than\n * surfaced in the page. Nothing here can reach the author — the code is\n * running for a VISITOR of their site, and turning the author's configuration\n * mistake into something a visitor sees would be a worse bug than the missing\n * metric. The author-facing half lives in `validateInteraction`, which refuses\n * to save a name this function would refuse to send, so a silent drop should\n * only ever happen to a step authored before AGL-1587.\n /\nexport function trackAuthoredEvent(\n name: string \| undefined \| null,\n params?: Record<string, unknown> \| null,\n): void {\n const resolved = resolveAuthoredEventName(name)\n if (!resolved.name) {\n const key = String(name ?? '')\n if (!warnedAuthoredNames.has(key)) {\n warnedAuthoredNames.add(key)\n try {\n console.warn(\n `[aglyn] analytics: the event \"${key}\" was not sent — ` +\n (resolved.reason === 'reserved'\n ? 'that name is reserved. Rename the step in the interaction builder.'\n : 'an event name must start with a letter.'),\n )\n } catch {\n // A console that throws is still not worth breaking the page for.\n }\n }\n return\n }\n deliver(resolved.name, sanitizeEventParams(params ?? undefined))\n}\n\n/* Test seam — forgets which authored names have already been warned about. */\nexport function resetAuthoredEventWarnings(): void {\n warnedAuthoredNames.clear()\n}\n"],"names":["readGaClientId","measurementId","Promise","resolve","window","gtag","settled","finish","value","setTimeout","id","configuredTransport","configureAnalyticsTransport","transport","resetAnalyticsTransport","DENIED_PARAM_KEYS","Set","EMAIL_SHAPED","ANALYTICS_PARAM_MAX_LENGTH","scrubValue","candidate","test","url","URL","origin","pathname","slice","sanitizeEventParams","params","safe","key","Object","entries","has","toLowerCase","undefined","scrubbed","Array","isArray","map","entry","trackEvent","name","deliver","NAVIGATION_FLUSH_TIMEOUT_MS","trackEventBeforeNavigation","delivered","then","race","catch","buildBeginCheckoutParams","input","priceItems","billingInterval","billing_interval","items","summed","reduce","total","item","price","quantity","currency","Math","round","buildViewCartParams","buildAddToCartParams","priced","isFirstPublishedRoute","routing","defaultHomeScreenId","keys","some","screenId","TAXONOMY_EVENT_NAMES","sign_up","login","generate_lead","select_content","org_created","host_created","site_published","stripe_connected","begin_checkout","purchase","view_item","add_to_cart","view_cart","aglyn_overlay","aglyn_experiment","click","assistant_message_sent","assistant_feedback","assistant_proposal_shown","assistant_proposal_confirmed","ai_job_completed","ai_job_failed","churn_survey_submitted","downsell_accepted","winback_discount_accepted","cancellation_completed","plan_downgrade_scheduled","plan_upgraded","ANALYTICS_EVENT_NAMES","SERVER_ONLY_EVENT_NAMES","isReservedAnalyticsEventName","GA4_RESERVED_EVENT_NAMES","GA4_RESERVED_PREFIXES","MAX_EVENT_NAME_LENGTH","resolveAuthoredEventName","raw","normalized","String","trim","replace","reason","prefix","startsWith","warnedAuthoredNames","trackAuthoredEvent","resolved","add","console","warn","resetAuthoredEventWarnings","clear"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmFC,GAED;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASA,eACdC,aAAwC;IAExC,OAAO,IAAIC,QAAQ,CAACC;QAClB,IAAI,OAAOC,WAAW,eAAe,CAACH,eAAe,OAAOE,QAAQ;QACpE,MAAME,OAAO,AAACD,OAAyCC,IAAI;QAC3D,IAAI,OAAOA,SAAS,YAAY,OAAOF,QAAQ;QAC/C,IAAIG,UAAU;QACd,MAAMC,SAAS,CAACC;YACd,IAAIF,SAAS;YACbA,UAAU;YACVH,QAAQK;QACV;QACA,oDAAoD;QACpDC,WAAW,IAAMF,OAAO,OAAO;QAC/B,IAAI;;YACAF,KACA,OACAJ,eACA,aACA,CAACS,KAAgBH,OAAO,OAAOG,OAAO,YAAYA,KAAKA,KAAK;QAEhE,EAAE,eAAM;YACNH,OAAO;QACT;IACF;AACF;AAgXA,IAAII,sBAAiD;AAErD;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,4BACdC,SAAoC;IAEpCF,sBAAsBE;AACxB;AAEA,gDAAgD,GAChD,OAAO,SAASC;IACdH,sBAAsB;AACxB;AAEA;;;;;CAKC,GACD,MAAMI,oBAAyC,IAAIC,IAAI;IACrD;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,yEAAyE,GACzE,MAAMC,eAAe;AAErB;;;;;;;CAOC,GACD,OAAO,MAAMC,6BAA6B,IAAG;AAE7C,SAASC,WAAWX,KAAa;IAC/B,IAAIY,YAAYZ;IAChB,IAAI,gBAAgBa,IAAI,CAACD,YAAY;QACnC,IAAI;YACF,MAAME,MAAM,IAAIC,IAAIH;YACpB,qEAAqE;YACrE,sEAAsE;YACtEA,YAAY,GAAGE,IAAIE,MAAM,GAAGF,IAAIG,QAAQ,EAAE;QAC5C,EAAE,eAAM;YACN,OAAO;QACT;IACF;IACA,uEAAuE;IACvE,4EAA4E;IAC5E,2EAA2E;IAC3E,wEAAwE;IACxE,0EAA0E;IAC1E,kEAAkE;IAClE,IAAIR,aAAaI,IAAI,CAACD,YAAY,OAAO;IACzC,OAAOA,UAAUM,KAAK,CAAC,GAAGR;AAC5B;AAEA;;;;CAIC,GACD,OAAO,SAASS,oBACdC,MAA2C;IAE3C,MAAMC,OAAgC,CAAC;IACvC,IAAI,CAACD,QAAQ,OAAOC;IACpB,KAAK,MAAM,CAACC,KAAKtB,MAAM,IAAIuB,OAAOC,OAAO,CAACJ,QAAS;QACjD,IAAIb,kBAAkBkB,GAAG,CAACH,IAAII,WAAW,KAAK;QAC9C,IAAI1B,UAAU2B,aAAa3B,UAAU,MAAM;QAC3C,IAAI,OAAOA,UAAU,UAAU;YAC7B,MAAM4B,WAAWjB,WAAWX;YAC5B,IAAI4B,aAAa,QAAQA,aAAa,IAAI;YAC1CP,IAAI,CAACC,IAAI,GAAGM;YACZ;QACF;QACA,IAAI,OAAO5B,UAAU,YAAY,OAAOA,UAAU,WAAW;YAC3DqB,IAAI,CAACC,IAAI,GAAGtB;YACZ;QACF;QACA,IAAI6B,MAAMC,OAAO,CAAC9B,QAAQ;YACxB,qDAAqD;YACrDqB,IAAI,CAACC,IAAI,GAAGtB,MAAM+B,GAAG,CAAC,CAACC,QACrBA,SAAS,OAAOA,UAAU,WACtBb,oBAAoBa,SACpBA;YAEN;QACF;QACA,IAAI,OAAOhC,UAAU,UAAU;YAC7BqB,IAAI,CAACC,IAAI,GAAGH,oBAAoBnB;QAClC;IACA,+CAA+C;IACjD;IACA,OAAOqB;AACT;AAEA;;;;;;;CAOC,GACD,OAAO,SAASY,WACdC,IAAO,EACPd,MAA+B;IAE/Be,QAAQD,MAAMf,oBAAoBC;AACpC;AAEA;;;;CAIC,GACD,MAAMgB,8BAA8B;AAEpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCC,GACD,OAAO,eAAeC,2BACpBH,IAAO,EACPd,MAA+B;IAE/B,MAAMkB,YAAYH,QAChBD,MACAf,oBAAoBC;IAEtB,6EAA6E;IAC7E,IAAI,CAACkB,aAAa,OAAOA,UAAUC,IAAI,KAAK,YAAY;IACxD,MAAM7C,QAAQ8C,IAAI,CAAC;QACjB,uEAAuE;QACvE,+DAA+D;QAC/D9C,QAAQC,OAAO,CAAC2C,WAAWG,KAAK,CAAC,IAAYd;QAC7C,IAAIjC,QAAc,CAACC,UACjBM,WAAWN,SAASyC;KAEvB;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,SAASM,yBAAyBC,KAWxC;IACC,OAAO,aACFC,WAAWD,QACVA,MAAME,eAAe,GAAG;QAAEC,kBAAkBH,MAAME,eAAe;IAAC,IAAI,CAAC;AAE/E;AAEA;;;;;;;CAOC,GACD,SAASD,WAAWD,KAInB;QACeA,cAMFA,iBAGSA;IATrB,MAAMI,SAAQJ,eAAAA,MAAMI,KAAK,YAAXJ,eAAe,EAAE;IAC/B,MAAMK,SAASD,MAAME,MAAM,CACzB,CAACC,OAAOC;YAAkBA,aAAoBA;eAA7BD,QAAQ,EAACC,cAAAA,KAAKC,KAAK,YAAVD,cAAc,OAAMA,iBAAAA,KAAKE,QAAQ,YAAbF,iBAAiB;OAC/D;IAEF,OAAO;QACLG,QAAQ,GAAEX,kBAAAA,MAAMW,QAAQ,YAAdX,kBAAkB;QAC5B,uEAAuE;QACvE,0DAA0D;QAC1D3C,OAAOuD,KAAKC,KAAK,CAAC,EAACb,eAAAA,MAAM3C,KAAK,YAAX2C,eAAeK,UAAU,OAAO;QACnDD;IACF;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,SAASU,oBAAoBd,KAInC;IACC,OAAOC,WAAWD;AACpB;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASe,qBAAqBf,KAIpC;IACC,MAAMgB,SAASf,WAAWD;IAC1B,IAAI,CAAEgB,CAAAA,OAAO3D,KAAK,GAAG,CAAA,GAAI,OAAO;QAAE+C,OAAOY,OAAOZ,KAAK;IAAC;IACtD,OAAOY;AACT;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CC,GACD,OAAO,SAASC,sBACdC,OAAmD,EACnDC,mBAAmC;IAEnC,OAAO,CAACvC,OAAOwC,IAAI,CAACF,kBAAAA,UAAW,CAAC,GAAGG,IAAI,CACrC,CAACC,WAAaA,aAAaH;AAE/B;AAEA;;;;;CAKC,GACD,SAAS3B,QACPD,IAAY,EACZb,IAA6B;IAE7B,IAAI;QACF,IAAIlB,qBAAqB;YACvB,iEAAiE;YACjE,uEAAuE;YACvE,oEAAoE;YACpE,oEAAoE;YACpE,wCAAwC;YACxC,iEAAiE;YACjE,0EAA0E;YAC1E,yEAAyE;YACzE,yDAAyD;YACzD,OAAOA,oBAAoB+B,MAA4Bb;QACzD;QACA,IAAI,OAAOzB,WAAW,aAAa;QACnC,MAAMC,OAAO,AAACD,OAAyCC,IAAI;QAC3D,IAAI,OAAOA,SAAS,YAAY;QAG9BA,KAAsC,SAASqC,MAAMb;IACzD,EAAE,eAAM;IACN,yEAAyE;IACzE,2BAA2B;IAC7B;AACF;AAEA;;;;;;;;CAQC,GACD,MAAM6C,uBAAyD;IAC7DC,SAAS;IACTC,OAAO;IACPC,eAAe;IACfC,gBAAgB;IAChBC,aAAa;IACbC,cAAc;IACdC,gBAAgB;IAChBC,kBAAkB;IAClBC,gBAAgB;IAChBC,UAAU;IACVC,WAAW;IACXC,aAAa;IACbC,WAAW;IACXC,eAAe;IACfC,kBAAkB;IAClBC,OAAO;IACPC,wBAAwB;IACxBC,oBAAoB;IACpBC,0BAA0B;IAC1BC,8BAA8B;IAC9BC,kBAAkB;IAClBC,eAAe;IACfC,wBAAwB;IACxBC,mBAAmB;IACnBC,2BAA2B;IAC3BC,wBAAwB;IACxBC,0BAA0B;IAC1BC,eAAe;AACjB;AAEA,8BAA8B,GAC9B,OAAO,MAAMC,wBAAwBxE,OAAOwC,IAAI,CAC9CG,sBACuB;AAEzB;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,MAAM8B,0BAA+C,IAAIxF,IAAI;IAC3D;IACA;CACD;AAED;;;;CAIC,GACD,OAAO,SAASyF,6BAA6B/D,IAAY;IACvD,OACEgC,oBAAoB,CAAChC,KAA2B,KAAK,QACrD8D,wBAAwBvE,GAAG,CAACS;AAEhC;AAEA;;;;CAIC,GACD,MAAMgE,2BAAgD,IAAI1F,IAAI;IAC5D;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,iEAAiE,GACjE,MAAM2F,wBAAwB;IAAC;IAAa;IAAW;CAAM;AAE7D,oEAAoE,GACpE,MAAMC,wBAAwB;AAiB9B;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASC,yBACdC,GAA8B;IAE9B,MAAMC,aAAaC,OAAOF,cAAAA,MAAO,IAC9BG,IAAI,GACJ/E,WAAW,EACZ,iEAAiE;KAChEgF,OAAO,CAAC,gBAAgB,IACzB,qEAAqE;KACpEA,OAAO,CAAC,YAAY,IACpBA,OAAO,CAAC,UAAU,KAClBxF,KAAK,CAAC,GAAGkF,sBACV,uEAAuE;KACtEM,OAAO,CAAC,OAAO;IAClB,IAAI,CAACH,YAAY,OAAO;QAAErE,MAAM;QAAMyE,QAAQ;IAAW;IACzD,IACEV,6BAA6BM,eAC7BL,yBAAyBzE,GAAG,CAAC8E,eAC7BJ,sBAAsBnC,IAAI,CAAC,CAAC4C,SAAWL,WAAWM,UAAU,CAACD,UAC7D;QACA,OAAO;YAAE1E,MAAM;YAAMyE,QAAQ;QAAW;IAC1C;IACA,OAAO;QAAEzE,MAAMqE;IAAW;AAC5B;AAEA;wDACwD,GACxD,MAAMO,sBAAsB,IAAItG;AAEhC;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASuG,mBACd7E,IAA+B,EAC/Bd,MAAuC;IAEvC,MAAM4F,WAAWX,yBAAyBnE;IAC1C,IAAI,CAAC8E,SAAS9E,IAAI,EAAE;QAClB,MAAMZ,MAAMkF,OAAOtE,eAAAA,OAAQ;QAC3B,IAAI,CAAC4E,oBAAoBrF,GAAG,CAACH,MAAM;YACjCwF,oBAAoBG,GAAG,CAAC3F;YACxB,IAAI;gBACF4F,QAAQC,IAAI,CACV,CAAC,8BAA8B,EAAE7F,IAAI,iBAAiB,CAAC,GACpD0F,CAAAA,SAASL,MAAM,KAAK,aACjB,uEACA,yCAAwC;YAElD,EAAE,eAAM;YACN,kEAAkE;YACpE;QACF;QACA;IACF;IACAxE,QAAQ6E,SAAS9E,IAAI,EAAEf,oBAAoBC,iBAAAA,SAAUO;AACvD;AAEA,6EAA6E,GAC7E,OAAO,SAASyF;IACdN,oBAAoBO,KAAK;AAC3B"}
1	+ {"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/analytics-events.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 one GA4 event taxonomy, shared by the marketing site (tenant runtime)\n * and the console (AGL-1561). See `docs/ANALYTICS.md` for the event map and\n * which GTM-plan §6 metric each event serves.\n \n ## Why this module exists\n \n Before it, every GA event in the repo was an ad-hoc\n * `;(window as any).gtag?.('event', 'name', {...})` — five of them across the\n * marketing and commerce plugins, plus bare string literals passed to Firebase\n * `logEvent` in the console. Nothing checked the names, nothing checked the\n * params, and a typo produced a silently-missing metric rather than an error.\n * That is the failure mode analytics is worst at surfacing: the number simply\n * reads zero, and zero is indistinguishable from \"nobody did it\".\n \n So the names and their params are a TYPE here ({@link AnalyticsEventParams}),\n * and `trackEvent` is generic over it: a misspelled event name or a missing\n * required param is a compile error.\n \n That sweep missed five (AGL-1591, closed): the commerce plugin's\n * `view_item` / `add_to_cart` / `begin_checkout` and the marketing runtime's\n * `aglyn_overlay` / `aglyn_experiment`. `window.gtag` is now called in exactly\n * two places in the repo — {@link deliver} below, and `readGaClientId` above,\n * which reads rather than sends.\n \n ## Reserved names\n \n Where GA4 has a recommended event we use its exact name and its exact param\n * spelling — `sign_up`, `login`, `generate_lead`, `begin_checkout`,\n * `purchase`, `select_content` — so the built-in reports, the funnel\n * explorations and the \"key events\" toggles work without custom definitions.\n * Custom snake_case names appear only where GA4 has no standard: the four\n * activation events, which are Aglyn-specific product milestones.\n \n ## Consent (AGL-1498) — the gate is that gtag never loads\n \n On tenant sites, including aglyn.com itself, `site-analytics.tsx` renders the\n * gtag `<Script>` pair ONLY when the recorded consent state grants analytics.\n * There is therefore no `window.gtag` at all for a visitor who has not granted,\n * and {@link trackEvent} drops the event on the floor.\n \n It drops it — it does not QUEUE it. That distinction is the whole point and\n * `analytics-events.spec.ts` asserts it: an event fired before consent is gone\n * for good, and does not reappear when a later grant loads gtag. A queue would\n * quietly convert \"we did not track you\" into \"we tracked you and waited\", and\n * a replayed hit carries the pre-consent timestamp and page into GA, which is\n * exactly the thing the consent gate exists to prevent. Deliberately no retry,\n * no buffer, no flush-on-grant.\n \n ## No PII, enforced rather than promised\n \n Every payload passes through {@link sanitizeEventParams} before it reaches a\n * transport: an exact-key denylist drops the identity-bearing params someone\n * will eventually add by reflex (`email`, `org_name`, `first_name`, ...), any\n * value that looks like an email address drops its key entirely, URLs are\n * reduced to origin + pathname so query strings can never smuggle a token or\n * an address, and strings are length-capped. The console separately sets a\n * `user_id` — that is an opaque Firebase uid and is the one identifier GA is\n * allowed to hold.\n \n Sanitizing here rather than at each call site is the point: a new call site\n * cannot forget.\n \n ## Authored events (AGL-1587)\n \n One call site cannot use the taxonomy at all: the `trackGaEvent` action step,\n * whose event name and params are typed by a SITE AUTHOR in the interaction\n * builder. A closed union cannot contain a name nobody has written yet, so\n * {@link trackAuthoredEvent} is the escape hatch — and it is deliberately the\n * only one, so that untrusted input still passes {@link sanitizeEventParams}\n * rather than reaching `window.gtag` raw.\n \n The test for which door an event uses is WHO NAMED IT, not whether GA4\n * recommends the name. `aglyn_overlay` and `aglyn_experiment` are outside GA4's\n * recommended set and were candidates for the hatch (AGL-1591); they are in the\n * union instead, because a developer wrote their names and their keys, so they\n * can have compile-time checking — and because the hatch guarantees the\n * opposite of what they need. {@link resolveAuthoredEventName} refuses any name\n * we send — the union AND the server-only names beside it — precisely so that\n * \"not one of ours\" means \"authored\"; put our own events through the hatch and\n * that stops being true, authored hits stop being separable from ours in\n * reports, and an authored `aglyn_experiment` step starts voting in the\n * experiment that decides which variant ships.\n /\n\n/\n Read the browser's GA `client_id` — the identifier that ties a hit to a GA\n * user and session.\n \n Needed because `purchase` is sent SERVER-side, from the Stripe webhook,\n * where the authoritative money is (see `ga4-measurement-protocol.ts`). The\n * Measurement Protocol requires a `client_id` and a server cannot know one,\n * so it is captured here when checkout starts and carried on the Stripe\n * object's metadata. Without it the revenue still lands, but attached to a\n * synthetic user with no acquisition session — which is exactly the campaign\n * attribution the whole exercise is for.\n \n Resolves to null rather than hanging when gtag is absent (no consent, an ad\n * blocker, analytics not configured) or slow to answer. The 500ms cap matters:\n * this sits directly in front of a checkout redirect, and analytics must never\n * be able to delay a payment.\n /\nexport function readGaClientId(\n measurementId: string \| undefined \| null,\n): Promise<string \| null> {\n return new Promise((resolve) => {\n if (typeof window === 'undefined' \|\| !measurementId) return resolve(null)\n const gtag = (window as unknown as { gtag?: unknown }).gtag\n if (typeof gtag !== 'function') return resolve(null)\n let settled = false\n const finish = (value: string \| null) => {\n if (settled) return\n settled = true\n resolve(value)\n }\n // Never let a missing callback strand the checkout.\n setTimeout(() => finish(null), 500)\n try {\n ;(gtag as (...args: unknown[]) => void)(\n 'get',\n measurementId,\n 'client_id',\n (id: unknown) => finish(typeof id === 'string' && id ? id : null),\n )\n } catch {\n finish(null)\n }\n })\n}\n\n/* Which door an account was created through (AGL-1497 enumerates all four). /\nexport type SignUpMethod =\n \| 'password'\n \| 'google_popup'\n \| 'google_redirect'\n \| 'google_signin'\n\n/* How a returning user authenticated. /\nexport type LoginMethod =\n \| 'password'\n \| 'google_popup'\n \| 'google_redirect'\n \| 'sso'\n \| 'passkey'\n\n/\n A GA4 `items` entry. Only the fields we actually populate — GA accepts more,\n * but an unpopulated field is a column of nulls in every report.\n /\nexport interface AnalyticsItem {\n /* Opaque identifier — a price id, plan key or marketplace listing id. /\n item_id: string\n /* Human-readable product name. NEVER a customer or org name. /\n item_name: string\n /* Distinguishes the revenue lines: `subscription` vs `marketplace`. /\n item_category?: string\n price?: number\n quantity?: number\n}\n\n/\n The taxonomy. Adding an event means adding a line here first — which is what\n * makes `docs/ANALYTICS.md` checkable against the code rather than aspirational.\n /\nexport interface AnalyticsEventParams {\n // --- Acquisition (GTM §6: signups, cost/lead by channel) -----------------\n /\n GA4 recommended. Real account creation only, never a sign-in.\n \n The three campaign params are optional and come from\n * `utmEventParams` (AGL-1731) — present when the signup URL named a\n * campaign, absent entirely otherwise. They are what lets a September ad\n * spend be evaluated: without them a paid click, an organic visit and a\n * partner link arrive indistinguishable and the money cannot be traced to\n * an account. Named `campaign_` rather than `utm_` because these are our\n * own registered dimensions and the `utm_` spellings belong to GA's\n * automatic campaign collection.\n /\n sign_up: {\n method: SignUpMethod\n campaign_source?: string\n campaign_medium?: string\n campaign_name?: string\n }\n /* GA4 recommended. Returning user only. /\n login: { method: LoginMethod }\n /\n GA4 recommended. Fired on a SUCCESSFUL form submission — never on click,\n * never on a validation failure. `form_name` is the author-given form name,\n * which is site content and not personal data.\n /\n generate_lead: { form_name: string; form_location?: string }\n /\n GA4 recommended. A CTA click, with the section that produced it.\n \n Fired by `analytics-link-clicks.ts` (AGL-1562) from a delegated listener,\n * not per call site: an authored page has no code to add a handler to.\n /\n select_content: {\n content_type: string\n content_id: string\n /* Which product surface — see `click.surface`. /\n surface?: string\n }\n\n // --- Activation (GTM §6: % publish a site, % connect Stripe) -------------\n /* Custom: no GA4 equivalent. A new organization exists. /\n org_created: { plan?: string }\n /* Custom: no GA4 equivalent. A new site/host exists. /\n host_created: Record<string, never>\n /\n Custom: no GA4 equivalent, and the GTM plan's headline activation metric.\n * A site actually went live.\n /\n site_published: { first_publish?: boolean }\n /\n Custom: no GA4 equivalent (AGL-3594). How a person chose to start a new\n * site in the guided start: the ready-made starter, or AI.\n /\n site_start_choice: { choice: 'starter' \| 'ai' }\n /* Custom: no GA4 equivalent. Stripe Connect onboarding completed. /\n stripe_connected: Record<string, never>\n\n // --- Revenue (GTM §6: paid conversions, ARPA, annual mix) ---------------\n /* GA4 recommended. A plan checkout started. /\n begin_checkout: {\n currency: string\n value: number\n items: AnalyticsItem[]\n /* `monthly` \| `annual` — feeds the §6 annual-mix metric. /\n billing_interval?: string\n }\n /\n GA4 recommended. A payment actually succeeded. `transaction_id` is the\n * Stripe object id and is what makes the event idempotent in GA: GA4\n * de-duplicates purchases by transaction id, so a webhook retry cannot\n * inflate revenue.\n /\n purchase: {\n transaction_id: string\n currency: string\n value: number\n items: AnalyticsItem[]\n billing_interval?: string\n /\n GA4's shipping charged on the transaction, in currency units. Optional\n * because only a tenant STOREFRONT purchase ships anything — a plan or a\n * marketplace purchase has no shipping to report and omits it.\n \n There is deliberately no sibling `tax` (AGL-1639, AGL-1641). The\n * asymmetry is the point and is not an inconsistency to tidy away:\n * `shipping` is a COMPONENT of the `value` beside it, so reporting it\n * describes that value; `tax` is not, because `value` is already ex-tax,\n * so reporting it would assert a relationship that does not hold and\n * invite the subtraction that removes tax a second time.\n /\n shipping?: number\n }\n\n // --- Commerce (tenant storefronts, AGL-1591) -----------------------------\n /\n GA4 recommended. A product detail page was viewed on a tenant storefront.\n \n Only `items`, and only `item_id`/`item_name` within it: those are the two\n * fields the storefront actually has at this point, and an unpopulated\n * `price`/`item_category` would be a column of nulls in the merchant's\n * reports. The item id is the PRODUCT id — the same id `add_to_cart` and\n * `begin_checkout` use — which is what lets GA join the three into one\n * per-product funnel.\n /\n view_item: { items: AnalyticsItem[] }\n /\n GA4 recommended. A storefront product was added to the cart.\n \n `currency`/`value` are optional because GA4 pairs them — a `value` with no\n * `currency` is dropped by GA — so they travel together or not at all, and\n * {@link buildAddToCartParams} is what keeps that true. They are populated\n * wherever the surface holds a server-priced figure: the product detail\n * block knows the resolved variant's price and the chosen quantity, so the\n * merchant's \"value added to cart\" is a real number rather than the empty\n * column an items-only hit produces.\n /\n add_to_cart: { currency?: string; value?: number; items: AnalyticsItem[] }\n /\n GA4 recommended. The shopper looked at their cart — the funnel step\n * between {@link AnalyticsEventParams.add_to_cart} and\n * {@link AnalyticsEventParams.begin_checkout}, and the one GA4's own\n * shopping-behavior report reads to tell \"never opened the cart\" apart from\n * \"opened it and did not check out\". Without it those two collapse into one\n * drop, and the merchant cannot tell a discovery problem from a pricing one.\n \n Fired when the cart is actually ON SCREEN carrying lines — a drawer that\n * opened, or an inline cart block that resolved — never on the badge render\n * that every page of a storefront performs. An empty cart is not a view of\n * anything and reports nothing.\n /\n view_cart: { currency: string; value: number; items: AnalyticsItem[] }\n\n // --- Engagement ---------------------------------------------------------\n /\n Custom: no GA4 equivalent. An announcement bar or popup was shown,\n * dismissed or clicked on a tenant site (AGL-200/271).\n \n In the taxonomy rather than {@link trackAuthoredEvent} even though it is\n * not a GA4 recommended name: the name and every key here are written by US,\n * which is exactly what the closed union is for. See the note on\n * {@link trackAuthoredEvent} for why the two must not be mixed.\n /\n aglyn_overlay: { overlay_action: string; overlay_id?: string }\n /\n Custom: no GA4 equivalent. An experiment exposure or conversion\n * (AGL-253). `experiment_action` is `exposure` \| `conversion`.\n \n Being in the union also makes the name RESERVED against authored events,\n * which matters more here than anywhere else in this file: these are the\n * counts that decide which variant wins, and a hand-authored\n * `aglyn_experiment` step would silently vote in that election.\n /\n aglyn_experiment: {\n experiment_id: string\n variant_id: string\n experiment_action: string\n }\n /\n GA4 recommended-ish. Outbound click to docs, GitHub, etc. Fired by\n * `analytics-link-clicks.ts` (AGL-1562) rather than at a call site.\n /\n click: {\n link_domain: string\n link_id?: string\n /\n Which product surface produced the click. GA's built-in Hostname\n * dimension already separates the DOMAINS; this separates surfaces that\n * could share one, and keeps the shared click listener from having to\n * know anything about either.\n \n `site` — a tenant published site — is the only value ever SENT. `docs`\n * was designed for (AGL-1579) and is not emitted: `apps/docs` cannot\n * import `libs/`, so this listener is not installed there\n * (docs/ANALYTICS.md decision 7 has the Vercel setting that would change\n * that). Registering `surface` as a dimension and reading a one-value\n * breakdown is the trap — the absent `docs` row means \"no listener\", not\n * \"no clicks\".\n /\n surface?: string\n }\n /\n Custom: no GA4 equivalent. One Aglyn Assist message sent (AGL-1860).\n * `tier` is the capability tier served (`free` \| `entitled`);\n * `grounded` says whether docs retrieval found sections to cite —\n * ungrounded questions at volume are the docs-gap signal the data loop\n * mines. No question text: params carry no user content.\n /\n assistant_message_sent: { tier: string; grounded: boolean }\n /\n Custom: no GA4 equivalent. Explicit thumbs on an Assist answer\n * (AGL-1860). `feedback` is `up` \| `down`.\n /\n assistant_feedback: { feedback: string }\n /\n Custom: no GA4 equivalent. Aglyn Assist offered to open a page for the\n * user (AGL-1988, level 2). `action` is the registry action id — a closed\n * set, so it carries no user content.\n \n The pair below is the only read on whether the confirm gate is a real\n * choice or a speed bump people click through. A shown-to-confirmed ratio\n * near 1 means the card is not being read, and the copy has to change\n * BEFORE the ladder goes anywhere near a write.\n /\n assistant_proposal_shown: { action: string }\n /* Custom: no GA4 equivalent. The user confirmed and was navigated. /\n assistant_proposal_confirmed: { action: string }\n /\n Custom: no GA4 equivalent. An AI generation job reached `done`\n * (AGL-2904), observed from the console's jobs drawer. `kind` is the\n * closed `AiJobKind` set and `credits` the job's spend at the plan's\n * credit rate — no brief, no output: params carry no user content.\n /\n ai_job_completed: { kind: string; credits: number }\n /\n Custom: no GA4 equivalent. An AI generation job reached `failed`\n * (AGL-2904). `kind` only; the failure text is a fixed customer-safe\n * sentence and says nothing a rate could use.\n /\n ai_job_failed: { kind: string }\n\n // --- Retention (AGL-1859/AGL-1863: the leave path, measurable) -----------\n /\n Custom: no GA4 equivalent. The churn survey was answered — step 1 of the\n * cancellation/deletion funnel, and the DENOMINATOR every step below is a\n * rate against. Fired for both leave paths.\n \n `reason` is the closed `ChurnSurveyReason` set, never the free-text\n * detail: the detail is customer-written prose, it belongs in Firestore\n * where the data loop reads it, and shipping it to GA would put user\n * content in analytics params. `surface` separates a subscription cancel\n * from an account delete — counting only one understates churn by exactly\n * the orgs that chose the other.\n /\n churn_survey_submitted: { reason: string; surface: string; plan?: string }\n /\n Custom: no GA4 equivalent. The customer took the smaller tier instead of\n * leaving — a SAVE, at reduced ARPA. `from_plan`/`to_plan` are what makes\n * that tradeoff measurable rather than a win recorded without its cost.\n /\n downsell_accepted: { from_plan: string; to_plan: string; surface: string }\n /\n Custom: no GA4 equivalent. The time-boxed winback discount was accepted.\n \n `percent_off` and `duration_months` are reported because the discount is\n * bounded and the bound is the entire point (AGL-1620/AGL-1863): a retained\n * org and the margin it was retained at are one fact, and a save recorded\n * without its price reads as free.\n /\n winback_discount_accepted: {\n percent_off: number\n duration_months: number\n plan?: string\n surface: string\n }\n /\n Custom: no GA4 equivalent. They left anyway — the funnel's terminal step,\n * and the numerator for churn.\n \n `funnel_completed` is false when the cancel arrived without a funnelId\n * (support ops, Stripe dashboard). It mirrors the `funnelSkipped` marker\n * the routes write, so the GA funnel and the Firestore record agree instead\n * of quietly disagreeing about how many departures were ever surveyed.\n /\n cancellation_completed: {\n surface: string\n plan?: string\n funnel_completed: boolean\n }\n\n // --- Plan changes taken from the grid (AGL-2235, under AGL-1859 §4) ------\n /\n Custom: no GA4 equivalent. A downgrade was confirmed and SCHEDULED from\n * the billing plan grid — the same economic event `downsell_accepted`\n * records, arrived at by the other door.\n \n Why this has to exist separately: all four retention events above fire\n * from `retention-funnel.dialog.tsx` and from nowhere else. A customer who\n * moves Pro → Starter through the cancel funnel is counted; a customer who\n * moves Pro → Starter by clicking Downgrade on the plan card was counted by\n * nothing. So \"how many orgs moved down\" was unanswerable, and the number\n * that WAS answerable — `downsell_accepted` — undercounted by exactly the\n * share that took the direct route while reading like a total. A save rate\n * computed against it is wrong in the flattering direction, which is the\n * worst direction for a retention number to be wrong in.\n \n `effective_at` is the whole point of the event's name: this is the\n * asymmetric-friction arm of AGL-1859 §2, and a downgrade that has been\n * SCHEDULED is not a downgrade that has HAPPENED. Reported as the server's\n * ISO date so the gap between decision and effect — up to a full cycle, and\n * the window in which \"keep my plan\" can still save the org — is visible in\n * the data instead of being collapsed into the decision day.\n \n No amount, price or fee: pricing is locked for Sept 1, money belongs to\n * `purchase`/`refund`, and a tier pair already says what changed.\n /\n plan_downgrade_scheduled: {\n from_plan: string\n to_plan: string\n interval: string\n effective_at?: string\n }\n /\n Custom: no GA4 equivalent. An existing subscriber moved UP in place.\n \n Not `app_upgrade` — that name is GA4-RESERVED (it means an app binary\n * version bump) and a hit using it is dropped, which is silence rather than\n * pollution and therefore the harder failure to notice.\n \n `purchase` covers only the Checkout path, so before this, expansion\n * revenue from customers who ALREADY had a subscription was dark: the\n * in-place switch never opens a Checkout and never mints a new\n * subscription, so nothing in the revenue taxonomy saw it. Upgrades are the\n * half of AGL-1859 §2 that is supposed to be frictionless, and an\n * unmeasured half cannot be shown to be.\n /\n plan_upgraded: {\n from_plan: string\n to_plan: string\n interval: string\n }\n}\n\nexport type AnalyticsEventName = keyof AnalyticsEventParams\n\n/\n Where a sanitized event goes. The console registers a Firebase\n * `logEvent` transport; the tenant runtime and the plugin bundles have none\n * and fall through to `window.gtag`, which only exists once consent has been\n * granted.\n /\nexport type AnalyticsTransport = (\n name: AnalyticsEventName,\n params: Record<string, unknown>,\n) => void \| Promise<void>\n\nlet configuredTransport: AnalyticsTransport \| null = null\n\n/\n Register the transport for this surface. The console calls this once, with\n * Firebase's `logEvent`, because the console's GA is Firebase-initialised and\n * its `user_id`/user-property state lives on the Firebase Analytics instance —\n * poking `window.gtag` directly there would emit hits that miss it.\n \n The tenant runtime deliberately does NOT call this: the plugin bundles run\n * in their own realm and do not share this module instance with the host app,\n * so a module-scope singleton would be invisible to exactly the call sites\n * that need it (the form and newsletter elements). `window.gtag` is the only\n * thing genuinely shared across that boundary, and it is also the consent\n * gate, which makes the fallback the correct primary path there rather than a\n * degraded one.\n /\nexport function configureAnalyticsTransport(\n transport: AnalyticsTransport \| null,\n): void {\n configuredTransport = transport\n}\n\n/* Test seam — drops the registered transport. /\nexport function resetAnalyticsTransport(): void {\n configuredTransport = null\n}\n\n/\n Param keys that must never reach GA, matched EXACTLY. Substring matching\n * would be wrong in both directions: it would drop the legitimate\n * `form_name` / `item_name` / `link_domain`, and it would still miss a\n * creatively-named new one. The value scan below is the backstop for those.\n /\nconst DENIED_PARAM_KEYS: ReadonlySet<string> = new Set([\n 'email',\n 'email_address',\n 'user_email',\n 'name',\n 'full_name',\n 'first_name',\n 'last_name',\n 'user_name',\n 'username',\n 'customer_name',\n 'org_name',\n 'organization_name',\n 'company',\n 'company_name',\n 'phone',\n 'phone_number',\n 'address',\n 'street',\n 'postal_code',\n 'zip',\n 'ip',\n 'ip_address',\n])\n\n/* Deliberately loose — this is a \"does it smell like an address\" test. /\nconst EMAIL_SHAPED = /[^\\s@]+@[^\\s@]+\\.[^\\s@]+/\n\n/\n GA4 truncates param values at 100 chars anyway; do it ourselves, visibly.\n \n Exported because an AUTHOR types some of these (the `trackGaEvent` step's\n * parameters), and the field they type into caps its input at the same number\n * — the truncation point and the affordance that describes it have to be one\n * value, or the editor promises a length the delivery quietly shortens.\n /\nexport const ANALYTICS_PARAM_MAX_LENGTH = 100\n\nfunction scrubValue(value: string): string \| null {\n let candidate = value\n if (/^https?:\\/\\//i.test(candidate)) {\n try {\n const url = new URL(candidate)\n // Origin + pathname only: a query string is where a session token, a\n // signup email or a Stripe id ends up, and none of them belong in GA.\n candidate = `${url.origin}${url.pathname}`\n } catch {\n return null\n }\n }\n // AFTER the URL reduction, not before. A page URL routinely carries an\n // address in its query (`?email=…` on a prefilled signup link), and testing\n // the raw string would throw the whole URL away for PII that the reduction\n // was about to remove — losing the legitimate page dimension to protect\n // something already protected. Testing the REDUCED value still catches an\n // address embedded in the path itself, which the reduction keeps.\n if (EMAIL_SHAPED.test(candidate)) return null\n return candidate.slice(0, ANALYTICS_PARAM_MAX_LENGTH)\n}\n\n/\n Strip anything identity-bearing from an event payload. Exported so\n * `analytics-events.spec.ts` can assert the guarantee directly rather than\n * only through `trackEvent`.\n /\nexport function sanitizeEventParams(\n params: Record<string, unknown> \| undefined,\n): Record<string, unknown> {\n const safe: Record<string, unknown> = {}\n if (!params) return safe\n for (const [key, value] of Object.entries(params)) {\n if (DENIED_PARAM_KEYS.has(key.toLowerCase())) continue\n if (value === undefined \|\| value === null) continue\n if (typeof value === 'string') {\n const scrubbed = scrubValue(value)\n if (scrubbed === null \|\| scrubbed === '') continue\n safe[key] = scrubbed\n continue\n }\n if (typeof value === 'number' \|\| typeof value === 'boolean') {\n safe[key] = value\n continue\n }\n if (Array.isArray(value)) {\n // `items` — sanitize each entry with the same rules.\n safe[key] = value.map((entry) =>\n entry && typeof entry === 'object'\n ? sanitizeEventParams(entry as Record<string, unknown>)\n : entry,\n )\n continue\n }\n if (typeof value === 'object') {\n safe[key] = sanitizeEventParams(value as Record<string, unknown>)\n }\n // Anything else (function, symbol) is dropped.\n }\n return safe\n}\n\n/\n Fire a GA4 event.\n \n Never throws and never queues. If the surface has no transport and no\n * `window.gtag` — which on a tenant site means the visitor has not granted\n * analytics consent — the event is DROPPED, permanently. See the module\n * comment for why a queue would be the wrong answer.\n /\nexport function trackEvent<K extends AnalyticsEventName>(\n name: K,\n params: AnalyticsEventParams[K],\n): void {\n deliver(name, sanitizeEventParams(params as Record<string, unknown>))\n}\n\n/\n How long a navigation may be held waiting for a hit to reach gtag. Short\n * enough to be invisible next to a Stripe redirect, long enough to cover a\n * Firebase Analytics init that has not settled yet.\n /\nconst NAVIGATION_FLUSH_TIMEOUT_MS = 300\n\n/\n Fire a GA4 event and resolve once it has been HANDED TO gtag — for the call\n * sites that navigate away in the same tick (AGL-1580).\n \n ## What was actually losing the event\n \n Not the transport, which was the obvious suspect and the wrong one. Measured\n * against real gtag.js with every transport interposed: gtag flushes its queue\n * on pagehide through `fetch(..., { keepalive: true })`, which is precisely the\n * mechanism that survives a document teardown. Once a hit reaches gtag, a\n * navigation does not destroy it — and `transport_type: 'beacon'`, the standard\n * answer, therefore fixes nothing here.\n \n What is lost is the hit that never REACHES gtag. Firebase's `logEvent` is\n * `async` and awaits the SDK's initialization promise before calling gtag\n * (`@firebase/analytics/dist/index.cjs.js`, `logEvent$1`). While that promise is\n * already settled the continuation is a microtask, microtasks drain before the\n * queued navigation task, and the hit gets out. While it is still PENDING — the\n * first checkout of a fresh session, exactly the case that has never yet been\n * seen in the property — the continuation is scheduled behind the navigation\n * and never runs at all. Measured both ways: pending init loses the event,\n * awaiting it delivers it, nothing else changed.\n \n ## Why a timeout rather than a bare await\n \n A bare `await` on `logEvent` hands the user's redirect to the analytics\n * stack. When the analytics host is blocked — an ad blocker, a corporate proxy,\n * a consent tool that never loads — Firebase's initialization promise can stay\n * pending indefinitely, and the checkout would hang on a metric. So the wait is\n * RACED against {@link NAVIGATION_FLUSH_TIMEOUT_MS}: a blocked analytics stack\n * costs the redirect 300ms once and then it proceeds, which is the same outcome\n * the caller had before this existed. Never rejects, for the same reason\n * {@link trackEvent} never throws.\n \n On a surface with no registered transport — the tenant runtime and the plugin\n * bundles, which go straight to `window.gtag` — delivery is synchronous, so\n * this resolves immediately and costs the storefront checkout nothing at all.\n /\nexport async function trackEventBeforeNavigation<K extends AnalyticsEventName>(\n name: K,\n params: AnalyticsEventParams[K],\n): Promise<void> {\n const delivered = deliver(\n name,\n sanitizeEventParams(params as Record<string, unknown>),\n )\n // Synchronous transport (or none): already handed over, nothing to wait for.\n if (!delivered \|\| typeof delivered.then !== 'function') return\n await Promise.race([\n // A transport that REJECTS must not become an unhandled rejection, and\n // must not hold the navigation either — it has already failed.\n Promise.resolve(delivered).catch((): void => undefined),\n new Promise<void>((resolve) =>\n setTimeout(resolve, NAVIGATION_FLUSH_TIMEOUT_MS),\n ),\n ])\n}\n\n/\n Build the ONE `begin_checkout` payload, for every surface that starts a\n * checkout (AGL-1591).\n \n ## Why a constructor and not just the type\n \n Two surfaces fire this name: the console, when a plan checkout starts, and a\n * tenant storefront, when a cart checks out. Until AGL-1591 the storefront\n * fired it raw and carried `value`/`currency` only, so ONE event name arrived\n * in two shapes — and a `begin_checkout` breakdown showed two populations that\n * could not be compared, with the storefront half missing the `items` the GA4\n * ecommerce funnel is built on. Routing both through {@link trackEvent} makes\n * the compiler settle the KEYS.\n \n It does not settle the NUMBER, which is the other way two call sites of one\n * event diverge, and the more dangerous one because nothing about it looks\n * wrong: the console's annual plans are priced per-month-billed-yearly, so its\n * `value` is twelve of them, and that only stayed right because a comment said\n * so. Here `value` DERIVES from the items unless a caller states a different\n * one — a cart states its subtotal, which is authoritative after discounts —\n * so \"what the customer is about to be charged\" has one definition rather than\n * one per surface.\n \n Server-safe: pure, no DOM, so the Measurement Protocol sender can compose\n * the matching `purchase` items from the same shapes.\n /\nexport function buildBeginCheckoutParams(input: {\n items: AnalyticsItem[]\n /\n The amount actually being charged. Defaults to the sum of the items'\n * `price * quantity`, which is right whenever nothing has adjusted it.\n /\n value?: number\n /* ISO 4217. Defaults to `USD`, the only currency either surface bills in. /\n currency?: string\n /* `monthly` \| `annual`. Subscriptions only — a storefront cart has none. /\n billingInterval?: string\n}): AnalyticsEventParams['begin_checkout'] {\n return {\n ...priceItems(input),\n ...(input.billingInterval ? { billing_interval: input.billingInterval } : {}),\n }\n}\n\n/\n The `currency`/`value`/`items` triple every GA4 ecommerce step shares.\n \n Private, because a caller should reach for the named builder for the event\n * it is about to send: the names differ in what they mean by `value` even\n * though the arithmetic is identical, and the JSDoc on each is where that is\n * written down.\n /\nfunction priceItems(input: {\n items: AnalyticsItem[]\n value?: number\n currency?: string\n}): { currency: string; value: number; items: AnalyticsItem[] } {\n const items = input.items ?? []\n const summed = items.reduce(\n (total, item) => total + (item.price ?? 0) (item.quantity ?? 1),\n 0,\n )\n return {\n currency: input.currency ?? 'USD',\n // Money, so two decimals: a float sum of cents-derived prices produces\n // `59.99999999999999`, and GA would report that verbatim.\n value: Math.round((input.value ?? summed) * 100) / 100,\n items,\n }\n}\n\n/*\n Build `view_cart` — the shopper is looking at the cart's contents.\n \n `value` is the cart's subtotal as the SERVER priced it, which is what makes\n * this comparable with the `begin_checkout` the same cart sends moments later:\n * two steps of one funnel that disagreed about the size of the same cart would\n * read as shoppers editing it between screens.\n /\nexport function buildViewCartParams(input: {\n items: AnalyticsItem[]\n value?: number\n currency?: string\n}): AnalyticsEventParams['view_cart'] {\n return priceItems(input)\n}\n\n/\n Build `add_to_cart` — one product going in, not the cart's new total.\n \n `value` is what was JUST ADDED (`price * quantity`), which is GA4's\n * definition and the only one that makes the metric additive: summing a\n * running cart total over a session would count the first item once per\n * subsequent add.\n \n Callers that cannot price the line — a quick-add with no resolved variant —\n * pass items alone and the pair is omitted rather than reported as zero. A\n * zero here would read as a free product in the merchant's report.\n /\nexport function buildAddToCartParams(input: {\n items: AnalyticsItem[]\n value?: number\n currency?: string\n}): AnalyticsEventParams['add_to_cart'] {\n const priced = priceItems(input)\n if (!(priced.value > 0)) return { items: priced.items }\n return priced\n}\n\n/\n Decide `site_published`'s `first_publish` from the host's routing map as it\n * stood BEFORE the route being published was registered (AGL-1588).\n \n ## What \"first\" means, and why it is defined once\n \n Three call sites report `site_published` — `publishScreenRoute`, the\n * besigner's one-click publish, and the scheduled publish executor, the last\n * of which is server-side and sends over the Measurement Protocol. A\n * breakdown is only worth registering if all three mean the same thing by it,\n * and \"first\" has several plausible readings. This is the one they share:\n \n The host had no live route at all before this one. Not \"first for the\n * org\" — that needs a cross-host query the server path cannot make, and the\n * scheduled sender's client id is derived from the HOST anyway, so an org is\n * not a thing it can see. Not \"first for this screen\" either, which would be\n * true of every second page a site adds and would make the dimension a\n * synonym for the event.\n \n So the metric it separates is the GTM §6 activation one: `first_publish:\n * true` counts sites that came alive, where the event alone counts publishes.\n \n ## The one dishonesty, and why it does not matter\n \n Unpublishing every route and publishing again reports `true` a second time.\n * Detecting that needs publish history the routing map does not keep. It is\n * harmless for the metric it exists for, because activation is read as the\n * share of USERS who ever sent `first_publish: true`, and a user counted twice\n * is still one user.\n \n Callers pass what they already hold — the live-subscribed map in the\n * console, a read snapshot on the server — and never a map read back AFTER\n * the write, which is never empty.\n \n ## The placeholder home page is not a publish (AGL-3408)\n \n Every new site is created with a home page already routed at `/`, so read\n * literally the map is never empty and no site would ever report a first\n * publish. The host's `defaultHomeScreenId` names that placeholder, and its\n * entry is not counted: the site \"came alive\" when its owner put something on\n * it, not when the platform did. Republishing the placeholder itself after\n * editing it counts, which is the same act: that publish is read against the\n * map with the marker still set, and clears it in the same write (AGL-3478).\n /\nexport function isFirstPublishedRoute(\n routing: Record<string, unknown> \| null \| undefined,\n defaultHomeScreenId?: string \| null,\n): boolean {\n return !Object.keys(routing ?? {}).some(\n (screenId) => screenId !== defaultHomeScreenId,\n )\n}\n\n/\n The one delivery path, shared by {@link trackEvent} and\n * {@link trackAuthoredEvent}. Takes an ALREADY-sanitized payload — every\n * caller sanitizes first, which is what keeps \"a new call site cannot forget\"\n * true of the authored path too.\n /\nfunction deliver(\n name: string,\n safe: Record<string, unknown>,\n): void \| Promise<void> {\n try {\n if (configuredTransport) {\n // The transport's name parameter is the taxonomy union, which an\n // authored name is by definition outside. Nominal only: the console is\n // the sole surface that registers one and it has no authored events\n // (the interaction runtime is tenant-side), and Firebase `logEvent`\n // takes an arbitrary string regardless.\n // Returned, not discarded (AGL-1580). A transport may be ASYNC —\n // Firebase's `logEvent` awaits the SDK's initialization promise before it\n // reaches gtag at all — and a caller that is about to navigate has to be\n // able to wait for it. See `trackEventBeforeNavigation`.\n return configuredTransport(name as AnalyticsEventName, safe)\n }\n if (typeof window === 'undefined') return\n const gtag = (window as unknown as { gtag?: unknown }).gtag\n if (typeof gtag !== 'function') return\n // Synchronous, so nothing is returned and nothing needs awaiting: by the\n // time this call has returned, gtag.js already holds the hit.\n ;(gtag as (...args: unknown[]) => void)('event', name, safe)\n } catch {\n // Analytics never breaks the page — the same posture as the error beacon\n // and the pageview beacon.\n }\n}\n\n/\n The taxonomy's names at RUN time. A `Record<AnalyticsEventName, true>` rather\n * than a hand-kept array so the compiler enforces both directions: adding an\n * event to {@link AnalyticsEventParams} without adding it here is a missing-key\n * error, and a name here that is not in the taxonomy is an excess-property one.\n \n It exists for {@link trackAuthoredEvent}, which has to refuse these names —\n * a drifting copy would silently re-open the collision it is here to close.\n /\nconst TAXONOMY_EVENT_NAMES: Record<AnalyticsEventName, true> = {\n sign_up: true,\n login: true,\n generate_lead: true,\n select_content: true,\n org_created: true,\n host_created: true,\n site_published: true,\n site_start_choice: true,\n stripe_connected: true,\n begin_checkout: true,\n purchase: true,\n view_item: true,\n add_to_cart: true,\n view_cart: true,\n aglyn_overlay: true,\n aglyn_experiment: true,\n click: true,\n assistant_message_sent: true,\n assistant_feedback: true,\n assistant_proposal_shown: true,\n assistant_proposal_confirmed: true,\n ai_job_completed: true,\n ai_job_failed: true,\n churn_survey_submitted: true,\n downsell_accepted: true,\n winback_discount_accepted: true,\n cancellation_completed: true,\n plan_downgrade_scheduled: true,\n plan_upgraded: true,\n}\n\n/* The taxonomy, enumerable. /\nexport const ANALYTICS_EVENT_NAMES = Object.keys(\n TAXONOMY_EVENT_NAMES,\n) as AnalyticsEventName[]\n\n/\n Event names WE send that this module's union cannot hold, because nothing\n * client-side ever fires them: they are emitted only by the Measurement\n * Protocol sender (`ga4-measurement-protocol.ts`), from a Stripe webhook.\n \n They still have to be RESERVED against authored names, and the reason is\n * the same one that puts `purchase` in the union — only less obvious, which\n * is why it was missed. `aglyn.com` is itself a tenant site, pointed at the\n * platform measurement id (`site-analytics.tsx`), so an authored\n * `trackGaEvent` step on our own marketing site lands in the SAME property as\n * these server hits. An authored `refund` does not merely add noise: GA4\n * treats `refund` as ecommerce and SUBTRACTS its `value` from reported\n * revenue, so a mistyped step could walk real money out of the report — the\n * `purchase` hazard, running in the direction nobody audits.\n \n Kept as a separate list rather than folded into {@link AnalyticsEventParams}\n * on purpose: adding them to the union would give {@link trackEvent} a\n * client-side door to events that must only ever come from the server, where\n * the authoritative money is. A name here is ours, is never sent from a\n * browser, and is never available to an author.\n \n This list is the reason \"not in {@link ANALYTICS_EVENT_NAMES}\" is NOT on its\n * own a sound test for \"authored\" — use {@link isReservedAnalyticsEventName}.\n /\nconst SERVER_ONLY_EVENT_NAMES: ReadonlySet<string> = new Set([\n 'refund',\n 'subscription_cancelled',\n])\n\n/\n Every event name Aglyn itself sends, from any surface — the union plus the\n * server-only names above. Exported so a caller can ask the question the two\n * separate lists no longer answer alone.\n /\nexport function isReservedAnalyticsEventName(name: string): boolean {\n return (\n TAXONOMY_EVENT_NAMES[name as AnalyticsEventName] === true \|\|\n SERVER_ONLY_EVENT_NAMES.has(name)\n )\n}\n\n/\n GA4's own reserved event names — GA drops a hit that uses one, so sending it\n * is not pollution but silence, which is the worse failure of the two because\n * nothing anywhere says so.\n /\nconst GA4_RESERVED_EVENT_NAMES: ReadonlySet<string> = new Set([\n 'ad_activeview',\n 'ad_click',\n 'ad_exposure',\n 'ad_impression',\n 'ad_query',\n 'ad_reward',\n 'adunit_exposure',\n 'app_background',\n 'app_clear_data',\n 'app_exception',\n 'app_install',\n 'app_remove',\n 'app_store_refund',\n 'app_store_subscription_cancel',\n 'app_store_subscription_convert',\n 'app_store_subscription_renew',\n 'app_update',\n 'app_upgrade',\n 'dynamic_link_app_open',\n 'dynamic_link_app_update',\n 'dynamic_link_first_open',\n 'error',\n 'first_open',\n 'first_visit',\n 'in_app_purchase',\n 'notification_dismiss',\n 'notification_foreground',\n 'notification_open',\n 'notification_receive',\n 'os_update',\n 'screen_view',\n 'session_start',\n 'user_engagement',\n])\n\n/* GA4 reserves these prefixes outright, whatever follows them. /\nconst GA4_RESERVED_PREFIXES = ['firebase_', 'google_', 'ga_'] as const\n\n/* GA4's hard limit on an event name. Over it, GA drops the event. /\nconst MAX_EVENT_NAME_LENGTH = 40\n\n/\n The outcome of putting an authored name through GA4's rules, so the\n * interaction builder can say WHY it refused a name and the runtime can drop\n * the event for the same reason.\n /\nexport interface ResolvedAuthoredEventName {\n /* The name to send, or null when the event must not be sent at all. /\n name: string \| null\n /\n `reserved` — collides with the taxonomy or with GA4's own names.\n * `unusable` — nothing survives normalization (empty, or no leading letter).\n /\n reason?: 'reserved' \| 'unusable'\n}\n\n/\n Put an authored event name through GA4's naming rules and our own.\n \n Normalization is forgiving on purpose: `\"CTA Click!\"` becomes `cta_click`\n * and still reports, where GA would have dropped it. Names already sitting in\n * published sites were never validated, so refusing them outright would delete\n * working metrics from a paying customer's property to fix a formatting nit.\n \n Collisions, in contrast, are refused rather than rewritten. On a tenant site\n * the authored events and OUR events (`generate_lead` from the form element,\n * `select_content`/`click` from the link listener) land in the same property,\n * so an authored `purchase` does not merely add noise — it mixes hand-authored\n * hits into a real revenue number. Refusing is also what keeps authored events\n * separable in reports: an event that is not one of {@link ANALYTICS_EVENT_NAMES}\n * is, by construction, authored.\n \n Deliberately NOT prefixed (`site_`) to achieve that separation. A prefix\n would rename events already flowing into customers' properties and break\n * every report and key-event conversion configured on the old name — a\n * migration cost paid by people who did nothing wrong.\n /\nexport function resolveAuthoredEventName(\n raw: string \| undefined \| null,\n): ResolvedAuthoredEventName {\n const normalized = String(raw ?? '')\n .trim()\n .toLowerCase()\n // Anything GA4 does not allow in a name becomes an underscore...\n .replace(/[^a-z0-9_]+/g, '_')\n // ...and a name must START with a letter, so drop what precedes one.\n .replace(/^[^a-z]+/, '')\n .replace(/_{2,}/g, '_')\n .slice(0, MAX_EVENT_NAME_LENGTH)\n // Truncation can leave a trailing underscore; so can the substitution.\n .replace(/_+$/, '')\n if (!normalized) return { name: null, reason: 'unusable' }\n if (\n isReservedAnalyticsEventName(normalized) \|\|\n GA4_RESERVED_EVENT_NAMES.has(normalized) \|\|\n GA4_RESERVED_PREFIXES.some((prefix) => normalized.startsWith(prefix))\n ) {\n return { name: null, reason: 'reserved' }\n }\n return { name: normalized }\n}\n\n/* One warning per distinct name per page load — an `everyTime` automation\n * would otherwise fill the console with the same line. /\nconst warnedAuthoredNames = new Set<string>()\n\n/\n Fire an event whose name and params were written by a SITE AUTHOR, not by a\n * developer — today only the `trackGaEvent` action step (AGL-1587).\n \n Same consent gate, same sanitizer, same drop-never-queue posture as\n * {@link trackEvent}; the only difference is that the name is checked at run\n * time instead of by the compiler, because there is no compiler between the\n * interaction builder and here.\n \n A refused event is dropped and warned about in the console rather than\n * surfaced in the page. Nothing here can reach the author — the code is\n * running for a VISITOR of their site, and turning the author's configuration\n * mistake into something a visitor sees would be a worse bug than the missing\n * metric. The author-facing half lives in `validateInteraction`, which refuses\n * to save a name this function would refuse to send, so a silent drop should\n * only ever happen to a step authored before AGL-1587.\n /\nexport function trackAuthoredEvent(\n name: string \| undefined \| null,\n params?: Record<string, unknown> \| null,\n): void {\n const resolved = resolveAuthoredEventName(name)\n if (!resolved.name) {\n const key = String(name ?? '')\n if (!warnedAuthoredNames.has(key)) {\n warnedAuthoredNames.add(key)\n try {\n console.warn(\n `[aglyn] analytics: the event \"${key}\" was not sent — ` +\n (resolved.reason === 'reserved'\n ? 'that name is reserved. Rename the step in the interaction builder.'\n : 'an event name must start with a letter.'),\n )\n } catch {\n // A console that throws is still not worth breaking the page for.\n }\n }\n return\n }\n deliver(resolved.name, sanitizeEventParams(params ?? undefined))\n}\n\n/* Test seam — forgets which authored names have already been warned about. */\nexport function resetAuthoredEventWarnings(): void {\n warnedAuthoredNames.clear()\n}\n"],"names":["readGaClientId","measurementId","Promise","resolve","window","gtag","settled","finish","value","setTimeout","id","configuredTransport","configureAnalyticsTransport","transport","resetAnalyticsTransport","DENIED_PARAM_KEYS","Set","EMAIL_SHAPED","ANALYTICS_PARAM_MAX_LENGTH","scrubValue","candidate","test","url","URL","origin","pathname","slice","sanitizeEventParams","params","safe","key","Object","entries","has","toLowerCase","undefined","scrubbed","Array","isArray","map","entry","trackEvent","name","deliver","NAVIGATION_FLUSH_TIMEOUT_MS","trackEventBeforeNavigation","delivered","then","race","catch","buildBeginCheckoutParams","input","priceItems","billingInterval","billing_interval","items","summed","reduce","total","item","price","quantity","currency","Math","round","buildViewCartParams","buildAddToCartParams","priced","isFirstPublishedRoute","routing","defaultHomeScreenId","keys","some","screenId","TAXONOMY_EVENT_NAMES","sign_up","login","generate_lead","select_content","org_created","host_created","site_published","site_start_choice","stripe_connected","begin_checkout","purchase","view_item","add_to_cart","view_cart","aglyn_overlay","aglyn_experiment","click","assistant_message_sent","assistant_feedback","assistant_proposal_shown","assistant_proposal_confirmed","ai_job_completed","ai_job_failed","churn_survey_submitted","downsell_accepted","winback_discount_accepted","cancellation_completed","plan_downgrade_scheduled","plan_upgraded","ANALYTICS_EVENT_NAMES","SERVER_ONLY_EVENT_NAMES","isReservedAnalyticsEventName","GA4_RESERVED_EVENT_NAMES","GA4_RESERVED_PREFIXES","MAX_EVENT_NAME_LENGTH","resolveAuthoredEventName","raw","normalized","String","trim","replace","reason","prefix","startsWith","warnedAuthoredNames","trackAuthoredEvent","resolved","add","console","warn","resetAuthoredEventWarnings","clear"],"mappings":"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"}

package/src/lib/app-utils/docs-help.generated.d.ts CHANGED Viewed

@@ -292,7 +292,7 @@ export declare const PLUGIN_DOCS_ANCHORS: {
     readonly aiAutomations: readonly ["#draft", "#explain", "#why-a-run-failed", "#what-is-sent", "#who-can-use-it", "#related"];
     readonly aiCrm: readonly ["#summarize-a-record", "#summaries-are-reused-until-the-record-changes", "#draft-an-email", "#match-columns", "#what-is-sent", "#who-can-use-it", "#related"];
     readonly aiExperiments: readonly ["#it-proposes-you-write", "#write-variants", "#putting-them-in", "#what-it-will-not-write", "#read-a-result", "#the-verdict", "#the-words", "#undecided", "#what-is-sent", "#who-can-use-it", "#related"];
-    readonly aiMonitoring: readonly ["#the-ai-card", "#where-else", "#one-account", "#the-spend-leaderboard", "#alerts", "#related"];
+    readonly aiMonitoring: readonly ["#the-ai-card", "#compensating-credits", "#where-else", "#one-account", "#the-spend-leaderboard", "#alerts", "#related"];
     readonly aiProducts: readonly ["#write-a-products-copy", "#write-copy-for-many-products", "#when-you-import-products", "#propose-a-first-catalog", "#propose-categories-and-discounts", "#what-the-copy-never-says", "#what-is-sent-to-the-ai-provider", "#who-can-use-it", "#related"];
     readonly aiSeo: readonly ["#write-a-pages-listing", "#write-a-products-listing", "#fix-what-the-seo-check-finds", "#apply-all-as-drafts", "#structured-data-and-llmstxt", "#related"];
     readonly aiThemes: readonly ["#change-what-you-describe-or-design-a-new-theme", "#match-your-brand", "#review-the-proposal", "#save-it-or-dont", "#who-can-use-it", "#related"];

package/src/lib/app-utils/docs-help.generated.js CHANGED Viewed

@@ -375,6 +375,7 @@ export const PLUGIN_DOCS_ANCHORS = {
     ],
     aiMonitoring: [
         '#the-ai-card',
+        '#compensating-credits',
         '#where-else',
         '#one-account',
         '#the-spend-leaderboard',