@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/platform-marketing-consent.js

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Marketing consent for the PLATFORM's own product email (AGL-3185).
+ *
+ * The strict policy (`marketing-consent.ts`) means a person with no declared
+ * basis is unsendable, and until this module the only doors that declared
+ * one were the marketing site's forms. Somebody who created a console account
+ * — the warmest audience the platform has — was never asked. Three console
+ * doors ask now: a checkbox on the sign-up form, a switch in the account
+ * preferences, and a one-time prompt for accounts that predate the checkbox.
+ *
+ * ## One wording, versioned
+ *
+ * Every door shows {@link PLATFORM_MARKETING_CONSENT_TEXT} and every record
+ * stores {@link PLATFORM_MARKETING_CONSENT_TEXT_VERSION} beside the exact
+ * timestamp, so "what did this person agree to" is answered by a version and
+ * not by whatever the checkbox says today. Changing the sentence is a bump of
+ * the version in the same edit.
+ *
+ * ## The record lives in two places, and the two do not disagree
+ *
+ * The decision is written by the server onto the person's own `users/{uid}`
+ * document, so the console can show a preference without reading the
+ * operator's CRM, and onto the operator's marketing contact for the same
+ * person, so the send path sees a declared basis with provenance. The
+ * contact half is written only when the deployment names a marketing host
+ * (`PLATFORM_MARKETING_HOST_ID`, read in `@aglyn/tenant-data-admin`); a
+ * self-hosted install with no audience of its own records the preference
+ * and skips the contact.
+ *
+ * ## Absence is not refusal
+ *
+ * An unticked sign-up checkbox records nothing. A switch turned off and a
+ * prompt answered "no" record a refusal, which the strict policy already
+ * honors. A prompt dismissed without an answer records only the dismissal,
+ * and the prompt stays away for {@link PLATFORM_MARKETING_PROMPT_SNOOZE_MS}.
+ *
+ * Pure and dependency-light on purpose: the sign-up page renders the text,
+ * the console route validates the body, and the server library writes the
+ * record, all from this one module.
+ */ import { MARKETING_CONSENT_FIELD, MARKETING_CONSENT_SOURCE_FIELD } from "./marketing-consent.js";
+import { PLATFORM_BRAND_NAME } from "./platform-brand.js";
+/** The console doors a decision can come through, as the record names them. */ export const PLATFORM_MARKETING_CONSENT_SOURCE_KINDS = [
+    'console-signup',
+    'console-preferences',
+    'console-prompt'
+];
+export function isPlatformMarketingConsentSourceKind(value) {
+    return PLATFORM_MARKETING_CONSENT_SOURCE_KINDS.includes(value);
+}
+/** What a door records: a grant or a refusal. Absence is never recorded. */ export const PLATFORM_MARKETING_CONSENT_DECISIONS = [
+    'granted',
+    'declined'
+];
+export function isPlatformMarketingConsentDecision(value) {
+    return PLATFORM_MARKETING_CONSENT_DECISIONS.includes(value);
+}
+/**
+ * The version of the consent wording every door shows. Bumped in the same
+ * edit as {@link platformMarketingConsentText}; a record stores the version
+ * it was shown under, so the two must move together.
+ */ export const PLATFORM_MARKETING_CONSENT_TEXT_VERSION = '2026-09-20';
+/**
+ * The sentence the person agrees to, with the deployment's brand in it.
+ *
+ * Affirmative and standalone: it names what is sent, who sends it, and that
+ * it can be stopped — never bundled with the terms acceptance, and never
+ * pre-ticked anywhere it is rendered.
+ */ export function platformMarketingConsentText(brandName) {
+    return `Send me product updates from ${brandName}. You can opt out any time.`;
+}
+/** {@link platformMarketingConsentText} for the brand this deployment wears. */ export const PLATFORM_MARKETING_CONSENT_TEXT = platformMarketingConsentText(PLATFORM_BRAND_NAME);
+/**
+ * The `users/{uid}` fields the decision is mirrored onto.
+ *
+ * The same names the contact record uses for the same facts, so one reader
+ * can parse either document. The prompt-dismissal stamp has no contact
+ * counterpart: it is about what the console asked, not what the person
+ * agreed to.
+ */ export const USER_MARKETING_CONSENT_FIELD = MARKETING_CONSENT_FIELD;
+export const USER_MARKETING_CONSENT_AT_FIELD = 'marketingConsentAtMs';
+export const USER_MARKETING_CONSENT_SOURCE_FIELD = MARKETING_CONSENT_SOURCE_FIELD;
+export const USER_MARKETING_PROMPT_DISMISSED_AT_FIELD = 'marketingConsentPromptDismissedAtMs';
+/** How long a dismissed prompt stays away: ninety days. */ export const PLATFORM_MARKETING_PROMPT_SNOOZE_MS = 90 * 24 * 60 * 60 * 1000;
+function finiteOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * Reads the decision off a `users/{uid}` document, or off no document.
+ *
+ * Every unusable value reads as its absent case rather than throwing: a
+ * malformed field must degrade to "nothing recorded", which asks again,
+ * never to a grant.
+ */ export function readPlatformMarketingConsent(document) {
+    const consent = document == null ? void 0 : document[USER_MARKETING_CONSENT_FIELD];
+    const rawSource = document == null ? void 0 : document[USER_MARKETING_CONSENT_SOURCE_FIELD];
+    const source = rawSource && typeof rawSource === 'object' && !Array.isArray(rawSource) ? rawSource : null;
+    const textVersion = source == null ? void 0 : source['textVersion'];
+    return {
+        decision: consent === true ? 'granted' : consent === false ? 'declined' : null,
+        atMs: finiteOrNull(document == null ? void 0 : document[USER_MARKETING_CONSENT_AT_FIELD]),
+        textVersion: typeof textVersion === 'string' && textVersion ? textVersion : null,
+        sourceKind: isPlatformMarketingConsentSourceKind(source == null ? void 0 : source['kind']) ? source['kind'] : null,
+        promptDismissedAtMs: finiteOrNull(document == null ? void 0 : document[USER_MARKETING_PROMPT_DISMISSED_AT_FIELD])
+    };
+}
+/**
+ * Whether the console should ask this person now.
+ *
+ * Never after a decision, in either direction: a "no" is an answer and a
+ * "yes" needs no repeating. A dismissal is not an answer, so the prompt
+ * returns once the snooze has run out.
+ */ export function platformMarketingPromptDue(state, nowMs) {
+    if (state.decision !== null) return false;
+    if (state.promptDismissedAtMs === null) return true;
+    return nowMs - state.promptDismissedAtMs >= PLATFORM_MARKETING_PROMPT_SNOOZE_MS;
+}
+/**
+ * What each door did, in prose, for whoever audits the record later.
+ *
+ * Keyed by door and decision so the sentence is decided once, here, and the
+ * three doors cannot describe the same act three different ways.
+ */ const PROVENANCE_REASONS = {
+    'console-signup': {
+        granted: 'Ticked the product-updates checkbox on the console sign-up form.',
+        declined: 'Declined product updates on the console sign-up form.'
+    },
+    'console-preferences': {
+        granted: 'Turned product updates on in the console account preferences.',
+        declined: 'Turned product updates off in the console account preferences.'
+    },
+    'console-prompt': {
+        granted: 'Answered yes to the product-updates prompt in the console.',
+        declined: 'Answered no to the product-updates prompt in the console.'
+    }
+};
+/**
+ * The provenance stored with a console decision, on both documents.
+ *
+ * `actor: 'person'` is what keeps {@link MarketingConsentSource} honest here:
+ * the reader treats provenance as an operator's assertion unless it says
+ * otherwise, and this is the person's own click, carrying which door and
+ * which wording. `by` is the account that clicked — the subject and the
+ * actor are the same human, which is the fact the field records.
+ */ export function platformMarketingConsentSource(input) {
+    return {
+        kind: input.kind,
+        by: input.uid,
+        atMs: input.atMs,
+        reason: PROVENANCE_REASONS[input.kind][input.decision],
+        textVersion: input.textVersion,
+        actor: 'person'
+    };
+}
+/**
+ * The `users/{uid}` fields a decision writes, as one merge-able object.
+ *
+ * `false` for a refusal, not a deleted field: absence is the third state and
+ * means "never asked", which a person who said no must never read as again.
+ */ export function platformMarketingUserFields(input) {
+    return {
+        [USER_MARKETING_CONSENT_FIELD]: input.decision === 'granted',
+        [USER_MARKETING_CONSENT_AT_FIELD]: input.atMs,
+        [USER_MARKETING_CONSENT_SOURCE_FIELD]: input.source
+    };
+}
+
+//# sourceMappingURL=platform-marketing-consent.js.map

package/src/lib/app-utils/platform-marketing-consent.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/platform-marketing-consent.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 * Marketing consent for the PLATFORM's own product email (AGL-3185).\n *\n * The strict policy (`marketing-consent.ts`) means a person with no declared\n * basis is unsendable, and until this module the only doors that declared\n * one were the marketing site's forms. Somebody who created a console account\n * — the warmest audience the platform has — was never asked. Three console\n * doors ask now: a checkbox on the sign-up form, a switch in the account\n * preferences, and a one-time prompt for accounts that predate the checkbox.\n *\n * ## One wording, versioned\n *\n * Every door shows {@link PLATFORM_MARKETING_CONSENT_TEXT} and every record\n * stores {@link PLATFORM_MARKETING_CONSENT_TEXT_VERSION} beside the exact\n * timestamp, so \"what did this person agree to\" is answered by a version and\n * not by whatever the checkbox says today. Changing the sentence is a bump of\n * the version in the same edit.\n *\n * ## The record lives in two places, and the two do not disagree\n *\n * The decision is written by the server onto the person's own `users/{uid}`\n * document, so the console can show a preference without reading the\n * operator's CRM, and onto the operator's marketing contact for the same\n * person, so the send path sees a declared basis with provenance. The\n * contact half is written only when the deployment names a marketing host\n * (`PLATFORM_MARKETING_HOST_ID`, read in `@aglyn/tenant-data-admin`); a\n * self-hosted install with no audience of its own records the preference\n * and skips the contact.\n *\n * ## Absence is not refusal\n *\n * An unticked sign-up checkbox records nothing. A switch turned off and a\n * prompt answered \"no\" record a refusal, which the strict policy already\n * honors. A prompt dismissed without an answer records only the dismissal,\n * and the prompt stays away for {@link PLATFORM_MARKETING_PROMPT_SNOOZE_MS}.\n *\n * Pure and dependency-light on purpose: the sign-up page renders the text,\n * the console route validates the body, and the server library writes the\n * record, all from this one module.\n */\n\nimport {\n  MARKETING_CONSENT_FIELD,\n  MARKETING_CONSENT_SOURCE_FIELD,\n  type MarketingConsentSource,\n} from './marketing-consent'\nimport { PLATFORM_BRAND_NAME } from './platform-brand'\n\n/** The console doors a decision can come through, as the record names them. */\nexport const PLATFORM_MARKETING_CONSENT_SOURCE_KINDS = [\n  'console-signup',\n  'console-preferences',\n  'console-prompt',\n] as const\n\nexport type PlatformMarketingConsentSourceKind =\n  (typeof PLATFORM_MARKETING_CONSENT_SOURCE_KINDS)[number]\n\nexport function isPlatformMarketingConsentSourceKind(\n  value: unknown,\n): value is PlatformMarketingConsentSourceKind {\n  return (PLATFORM_MARKETING_CONSENT_SOURCE_KINDS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/** What a door records: a grant or a refusal. Absence is never recorded. */\nexport const PLATFORM_MARKETING_CONSENT_DECISIONS = ['granted', 'declined'] as const\n\nexport type PlatformMarketingConsentDecision =\n  (typeof PLATFORM_MARKETING_CONSENT_DECISIONS)[number]\n\nexport function isPlatformMarketingConsentDecision(\n  value: unknown,\n): value is PlatformMarketingConsentDecision {\n  return (PLATFORM_MARKETING_CONSENT_DECISIONS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/**\n * The version of the consent wording every door shows. Bumped in the same\n * edit as {@link platformMarketingConsentText}; a record stores the version\n * it was shown under, so the two must move together.\n */\nexport const PLATFORM_MARKETING_CONSENT_TEXT_VERSION = '2026-09-20'\n\n/**\n * The sentence the person agrees to, with the deployment's brand in it.\n *\n * Affirmative and standalone: it names what is sent, who sends it, and that\n * it can be stopped — never bundled with the terms acceptance, and never\n * pre-ticked anywhere it is rendered.\n */\nexport function platformMarketingConsentText(brandName: string): string {\n  return `Send me product updates from ${brandName}. You can opt out any time.`\n}\n\n/** {@link platformMarketingConsentText} for the brand this deployment wears. */\nexport const PLATFORM_MARKETING_CONSENT_TEXT = platformMarketingConsentText(\n  PLATFORM_BRAND_NAME,\n)\n\n/**\n * The `users/{uid}` fields the decision is mirrored onto.\n *\n * The same names the contact record uses for the same facts, so one reader\n * can parse either document. The prompt-dismissal stamp has no contact\n * counterpart: it is about what the console asked, not what the person\n * agreed to.\n */\nexport const USER_MARKETING_CONSENT_FIELD = MARKETING_CONSENT_FIELD\nexport const USER_MARKETING_CONSENT_AT_FIELD = 'marketingConsentAtMs'\nexport const USER_MARKETING_CONSENT_SOURCE_FIELD = MARKETING_CONSENT_SOURCE_FIELD\nexport const USER_MARKETING_PROMPT_DISMISSED_AT_FIELD =\n  'marketingConsentPromptDismissedAtMs'\n\n/** How long a dismissed prompt stays away: ninety days. */\nexport const PLATFORM_MARKETING_PROMPT_SNOOZE_MS = 90 * 24 * 60 * 60 * 1000\n\n/** What the person's own document says about product email. */\nexport interface PlatformMarketingConsentState {\n  /** `null` when nothing has been recorded — asked, but not answered. */\n  decision: PlatformMarketingConsentDecision | null\n  /** When the decision was recorded. */\n  atMs: number | null\n  /** The wording version the decision was made under. */\n  textVersion: string | null\n  /** Which console door recorded it; `null` for a record another writer left. */\n  sourceKind: PlatformMarketingConsentSourceKind | null\n  /** When the prompt was last dismissed without an answer. */\n  promptDismissedAtMs: number | null\n}\n\nfunction finiteOrNull(value: unknown): number | null {\n  return typeof value === 'number' && Number.isFinite(value) ? value : null\n}\n\n/**\n * Reads the decision off a `users/{uid}` document, or off no document.\n *\n * Every unusable value reads as its absent case rather than throwing: a\n * malformed field must degrade to \"nothing recorded\", which asks again,\n * never to a grant.\n */\nexport function readPlatformMarketingConsent(\n  document: Record<string, unknown> | null | undefined,\n): PlatformMarketingConsentState {\n  const consent = document?.[USER_MARKETING_CONSENT_FIELD]\n  const rawSource = document?.[USER_MARKETING_CONSENT_SOURCE_FIELD]\n  const source =\n    rawSource && typeof rawSource === 'object' && !Array.isArray(rawSource)\n      ? (rawSource as Record<string, unknown>)\n      : null\n  const textVersion = source?.['textVersion']\n  return {\n    decision: consent === true ? 'granted' : consent === false ? 'declined' : null,\n    atMs: finiteOrNull(document?.[USER_MARKETING_CONSENT_AT_FIELD]),\n    textVersion:\n      typeof textVersion === 'string' && textVersion ? textVersion : null,\n    sourceKind: isPlatformMarketingConsentSourceKind(source?.['kind'])\n      ? source['kind']\n      : null,\n    promptDismissedAtMs: finiteOrNull(\n      document?.[USER_MARKETING_PROMPT_DISMISSED_AT_FIELD],\n    ),\n  }\n}\n\n/**\n * Whether the console should ask this person now.\n *\n * Never after a decision, in either direction: a \"no\" is an answer and a\n * \"yes\" needs no repeating. A dismissal is not an answer, so the prompt\n * returns once the snooze has run out.\n */\nexport function platformMarketingPromptDue(\n  state: Pick<PlatformMarketingConsentState, 'decision' | 'promptDismissedAtMs'>,\n  nowMs: number,\n): boolean {\n  if (state.decision !== null) return false\n  if (state.promptDismissedAtMs === null) return true\n  return nowMs - state.promptDismissedAtMs >= PLATFORM_MARKETING_PROMPT_SNOOZE_MS\n}\n\n/**\n * What each door did, in prose, for whoever audits the record later.\n *\n * Keyed by door and decision so the sentence is decided once, here, and the\n * three doors cannot describe the same act three different ways.\n */\nconst PROVENANCE_REASONS: Record<\n  PlatformMarketingConsentSourceKind,\n  Record<PlatformMarketingConsentDecision, string>\n> = {\n  'console-signup': {\n    granted: 'Ticked the product-updates checkbox on the console sign-up form.',\n    declined: 'Declined product updates on the console sign-up form.',\n  },\n  'console-preferences': {\n    granted: 'Turned product updates on in the console account preferences.',\n    declined: 'Turned product updates off in the console account preferences.',\n  },\n  'console-prompt': {\n    granted: 'Answered yes to the product-updates prompt in the console.',\n    declined: 'Answered no to the product-updates prompt in the console.',\n  },\n}\n\n/**\n * The provenance stored with a console decision, on both documents.\n *\n * `actor: 'person'` is what keeps {@link MarketingConsentSource} honest here:\n * the reader treats provenance as an operator's assertion unless it says\n * otherwise, and this is the person's own click, carrying which door and\n * which wording. `by` is the account that clicked — the subject and the\n * actor are the same human, which is the fact the field records.\n */\nexport function platformMarketingConsentSource(input: {\n  kind: PlatformMarketingConsentSourceKind\n  decision: PlatformMarketingConsentDecision\n  uid: string\n  atMs: number\n  textVersion: string\n}): MarketingConsentSource {\n  return {\n    kind: input.kind,\n    by: input.uid,\n    atMs: input.atMs,\n    reason: PROVENANCE_REASONS[input.kind][input.decision],\n    textVersion: input.textVersion,\n    actor: 'person',\n  }\n}\n\n/**\n * The `users/{uid}` fields a decision writes, as one merge-able object.\n *\n * `false` for a refusal, not a deleted field: absence is the third state and\n * means \"never asked\", which a person who said no must never read as again.\n */\nexport function platformMarketingUserFields(input: {\n  decision: PlatformMarketingConsentDecision\n  atMs: number\n  source: MarketingConsentSource\n}): Record<string, unknown> {\n  return {\n    [USER_MARKETING_CONSENT_FIELD]: input.decision === 'granted',\n    [USER_MARKETING_CONSENT_AT_FIELD]: input.atMs,\n    [USER_MARKETING_CONSENT_SOURCE_FIELD]: input.source,\n  }\n}\n"],"names":["MARKETING_CONSENT_FIELD","MARKETING_CONSENT_SOURCE_FIELD","PLATFORM_BRAND_NAME","PLATFORM_MARKETING_CONSENT_SOURCE_KINDS","isPlatformMarketingConsentSourceKind","value","includes","PLATFORM_MARKETING_CONSENT_DECISIONS","isPlatformMarketingConsentDecision","PLATFORM_MARKETING_CONSENT_TEXT_VERSION","platformMarketingConsentText","brandName","PLATFORM_MARKETING_CONSENT_TEXT","USER_MARKETING_CONSENT_FIELD","USER_MARKETING_CONSENT_AT_FIELD","USER_MARKETING_CONSENT_SOURCE_FIELD","USER_MARKETING_PROMPT_DISMISSED_AT_FIELD","PLATFORM_MARKETING_PROMPT_SNOOZE_MS","finiteOrNull","Number","isFinite","readPlatformMarketingConsent","document","consent","rawSource","source","Array","isArray","textVersion","decision","atMs","sourceKind","promptDismissedAtMs","platformMarketingPromptDue","state","nowMs","PROVENANCE_REASONS","granted","declined","platformMarketingConsentSource","input","kind","by","uid","reason","actor","platformMarketingUserFields"],"mappings":"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"}

package/src/lib/app-utils/platform-marketing-host.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type VisitorConsentHost } from './visitor-consent';
+/**
+ * The platform's own GA4 property. Public in every page the platform serves,
+ * so holding it in source discloses nothing.
+ *
+ * Hoisted out of `site-analytics.tsx` so the two behaviours already
+ * keyed on it and the advertising gate cannot drift onto different literals.
+ */
+export declare const PLATFORM_GA_MEASUREMENT_ID = "G-YW5PG16YTM";
+/**
+ * Whether this resolved tenant host is Aglyn's own marketing site.
+ *
+ * `false` for every customer site, for every self-hosted deployment, and for
+ * an absent or malformed host document. The default is the safe one in the
+ * sense that matters: a feature scoped by this predicate does not run.
+ */
+export declare function isPlatformMarketingHost(host: VisitorConsentHost | null | undefined): boolean;

package/src/lib/app-utils/platform-marketing-host.js

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * "Is this host AGLYN'S OWN marketing site, or a customer's?"
+ *
+ * `aglyn.com` is an ordinary tenant site on the platform — Firestore host
+ * `aglyn-marketing`, `cname: aglyn.com`, resolved through the `default:`
+ * custom-domain branch of `apps/tenant/middleware.ts`, which has no
+ * `aglyn.com` case at all. Nothing in the routing layer knows it is ours, and
+ * that is deliberate: the marketing site is dogfood, served by exactly the
+ * code a customer gets.
+ *
+ * So a feature that must run on our own site and NOWHERE else needs a
+ * discriminator, and this is the one the codebase already had.
+ *
+ * ## The mechanism: the GA4 property, not a hostname
+ *
+ * `site-analytics.tsx` has shipped this test twice already — for the
+ * marketing `content_group` axis (AGL-1857) and for the internal
+ * `traffic_type` stamp (AGL-2064) — with the argument written out both times:
+ * a customer's site configures its own measurement id, so **same-property IS
+ * the definition of "this is our surface"**. The id lived as a private
+ * constant in that file; it is hoisted here so the third reader shares the
+ * one definition rather than retyping the literal beside it.
+ *
+ * Reusing it buys three things a hostname literal would not:
+ *
+ * - **No new hardcoded host.** `selfhost-hardcoded-hosts.spec.ts` (AGL-2195)
+ *   ratchets every `aglyn.(app|com|io)` occurrence in runtime source with an
+ *   exact per-file count. A measurement id is not a hostname, so this module
+ *   adds nothing to that allowlist and nothing for a self-hoster to edit.
+ * - **It is DATA, not a build constant.** The verdict is a property of the
+ *   resolved host document. A self-hosted or white-label deployment points its
+ *   sites at its own GA property and can never match, no matter what domain it
+ *   serves — which is the correct answer, since it is not our marketing site.
+ * - **It cannot be claimed by a customer.** `gaMeasurementId` is customer
+ *   writable, so in principle a customer could type our id into their own
+ *   site's analytics field. {@link isAglynOperatedBrand} does not close that,
+ *   and neither would a hostname check on a `cname` a customer also controls.
+ *   What closes it is that this predicate only ever ADDS an Aglyn-owned tag to
+ *   an Aglyn-owned property: the worst a customer achieves by pasting our id
+ *   is polluting our own analytics, which they can already do and which
+ *   AGL-2064's stamp exists to filter. It grants them nothing and exposes no
+ *   Customer Personal Data — see `advertising-tags.ts` for why that boundary
+ *   is the one that actually matters here.
+ *
+ * ## Why the brand check too
+ *
+ * Belt and braces for the self-host shape. A Docker operator who forked the
+ * repo keeps the literal below in their build; {@link isAglynOperatedBrand}
+ * is false the moment they set `NEXT_PUBLIC_PLATFORM_BRAND_NAME`, so the
+ * predicate is false for them even if a host document somehow carried our id.
+ * Two independent conditions, and the cheaper one is not the load-bearing one.
+ *
+ * ## What this deliberately does NOT decide
+ *
+ * Anything about the CONSOLE or the DOCS site. All three of Aglyn's domains
+ * report to this same GA4 property, so the id alone does not separate
+ * marketing from `app.aglyn.com`. It does not have to: this predicate takes a
+ * tenant HOST DOCUMENT, and the console and the docs site have none — neither
+ * is served by the tenant runtime and neither renders `SiteAnalytics`. The
+ * separation there is structural (no mount point), not a matter of this
+ * function getting it right.
+ */ import { isAglynOperatedBrand } from "./platform-brand.js";
+import { resolveGaMeasurementId } from "./visitor-consent.js";
+/**
+ * The platform's own GA4 property. Public in every page the platform serves,
+ * so holding it in source discloses nothing.
+ *
+ * Hoisted out of `site-analytics.tsx` so the two behaviours already
+ * keyed on it and the advertising gate cannot drift onto different literals.
+ */ export const PLATFORM_GA_MEASUREMENT_ID = 'G-YW5PG16YTM';
+/**
+ * Whether this resolved tenant host is Aglyn's own marketing site.
+ *
+ * `false` for every customer site, for every self-hosted deployment, and for
+ * an absent or malformed host document. The default is the safe one in the
+ * sense that matters: a feature scoped by this predicate does not run.
+ */ export function isPlatformMarketingHost(host) {
+    if (isAglynOperatedBrand() === false) return false;
+    return resolveGaMeasurementId(host) === PLATFORM_GA_MEASUREMENT_ID;
+}
+
+//# sourceMappingURL=platform-marketing-host.js.map

package/src/lib/app-utils/platform-marketing-host.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/platform-marketing-host.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 * \"Is this host AGLYN'S OWN marketing site, or a customer's?\"\n *\n * `aglyn.com` is an ordinary tenant site on the platform — Firestore host\n * `aglyn-marketing`, `cname: aglyn.com`, resolved through the `default:`\n * custom-domain branch of `apps/tenant/middleware.ts`, which has no\n * `aglyn.com` case at all. Nothing in the routing layer knows it is ours, and\n * that is deliberate: the marketing site is dogfood, served by exactly the\n * code a customer gets.\n *\n * So a feature that must run on our own site and NOWHERE else needs a\n * discriminator, and this is the one the codebase already had.\n *\n * ## The mechanism: the GA4 property, not a hostname\n *\n * `site-analytics.tsx` has shipped this test twice already — for the\n * marketing `content_group` axis (AGL-1857) and for the internal\n * `traffic_type` stamp (AGL-2064) — with the argument written out both times:\n * a customer's site configures its own measurement id, so **same-property IS\n * the definition of \"this is our surface\"**. The id lived as a private\n * constant in that file; it is hoisted here so the third reader shares the\n * one definition rather than retyping the literal beside it.\n *\n * Reusing it buys three things a hostname literal would not:\n *\n * - **No new hardcoded host.** `selfhost-hardcoded-hosts.spec.ts` (AGL-2195)\n *   ratchets every `aglyn.(app|com|io)` occurrence in runtime source with an\n *   exact per-file count. A measurement id is not a hostname, so this module\n *   adds nothing to that allowlist and nothing for a self-hoster to edit.\n * - **It is DATA, not a build constant.** The verdict is a property of the\n *   resolved host document. A self-hosted or white-label deployment points its\n *   sites at its own GA property and can never match, no matter what domain it\n *   serves — which is the correct answer, since it is not our marketing site.\n * - **It cannot be claimed by a customer.** `gaMeasurementId` is customer\n *   writable, so in principle a customer could type our id into their own\n *   site's analytics field. {@link isAglynOperatedBrand} does not close that,\n *   and neither would a hostname check on a `cname` a customer also controls.\n *   What closes it is that this predicate only ever ADDS an Aglyn-owned tag to\n *   an Aglyn-owned property: the worst a customer achieves by pasting our id\n *   is polluting our own analytics, which they can already do and which\n *   AGL-2064's stamp exists to filter. It grants them nothing and exposes no\n *   Customer Personal Data — see `advertising-tags.ts` for why that boundary\n *   is the one that actually matters here.\n *\n * ## Why the brand check too\n *\n * Belt and braces for the self-host shape. A Docker operator who forked the\n * repo keeps the literal below in their build; {@link isAglynOperatedBrand}\n * is false the moment they set `NEXT_PUBLIC_PLATFORM_BRAND_NAME`, so the\n * predicate is false for them even if a host document somehow carried our id.\n * Two independent conditions, and the cheaper one is not the load-bearing one.\n *\n * ## What this deliberately does NOT decide\n *\n * Anything about the CONSOLE or the DOCS site. All three of Aglyn's domains\n * report to this same GA4 property, so the id alone does not separate\n * marketing from `app.aglyn.com`. It does not have to: this predicate takes a\n * tenant HOST DOCUMENT, and the console and the docs site have none — neither\n * is served by the tenant runtime and neither renders `SiteAnalytics`. The\n * separation there is structural (no mount point), not a matter of this\n * function getting it right.\n */\n\nimport { isAglynOperatedBrand } from './platform-brand'\nimport {\n  resolveGaMeasurementId,\n  type VisitorConsentHost,\n} from './visitor-consent'\n\n/**\n * The platform's own GA4 property. Public in every page the platform serves,\n * so holding it in source discloses nothing.\n *\n * Hoisted out of `site-analytics.tsx` so the two behaviours already\n * keyed on it and the advertising gate cannot drift onto different literals.\n */\nexport const PLATFORM_GA_MEASUREMENT_ID = 'G-YW5PG16YTM'\n\n/**\n * Whether this resolved tenant host is Aglyn's own marketing site.\n *\n * `false` for every customer site, for every self-hosted deployment, and for\n * an absent or malformed host document. The default is the safe one in the\n * sense that matters: a feature scoped by this predicate does not run.\n */\nexport function isPlatformMarketingHost(\n  host: VisitorConsentHost | null | undefined,\n): boolean {\n  if (isAglynOperatedBrand() === false) return false\n  return resolveGaMeasurementId(host) === PLATFORM_GA_MEASUREMENT_ID\n}\n"],"names":["isAglynOperatedBrand","resolveGaMeasurementId","PLATFORM_GA_MEASUREMENT_ID","isPlatformMarketingHost","host"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6DC,GAED,SAASA,oBAAoB,QAAQ,sBAAkB;AACvD,SACEC,sBAAsB,QAEjB,uBAAmB;AAE1B;;;;;;CAMC,GACD,OAAO,MAAMC,6BAA6B,eAAc;AAExD;;;;;;CAMC,GACD,OAAO,SAASC,wBACdC,IAA2C;IAE3C,IAAIJ,2BAA2B,OAAO,OAAO;IAC7C,OAAOC,uBAAuBG,UAAUF;AAC1C"}

package/src/lib/app-utils/platform-visitor-consent.d.ts

@@ -0,0 +1,252 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type StoredVisitorConsent, type VisitorConsentPosture, type VisitorConsentStatus } from './visitor-consent';
+/**
+ * The storage subject for the console's own consent record.
+ *
+ * `visitorConsentStorageKey` keys records by host id because preview
+ * deployments and localhost serve many customer sites from one origin. The
+ * console is a single surface, so it takes a constant — but it takes it
+ * through the same key builder, so a console record and a customer-site record
+ * can never collide, and a self-hosted console on the same origin as a site
+ * keeps its own.
+ *
+ * A name, not a hostname: the console is served from `app.aglyn.com`, from a
+ * custom console domain (AGL-1099c), and from localhost, and a visitor's
+ * choice is about the surface rather than about which of its origins they
+ * reached it through.
+ */
+export declare const PLATFORM_CONSENT_SUBJECT = "aglyn-console";
+/**
+ * Where the client asks which country it is visiting from.
+ *
+ * The same path the tenant runtime uses, and for the same reason: the answer
+ * is a per-visitor request header, so it cannot be baked into a render. Each
+ * app serves its own route handler at this path.
+ */
+export declare const PLATFORM_CONSENT_REGION_ENDPOINT = "/api/consent/region";
+/** Session-scoped region cache — one lookup per visit, not per pageview. */
+export declare const PLATFORM_CONSENT_REGION_CACHE_KEY = "aglyn:consent:region";
+/**
+ * Whether this surface asks its visitors about advertising storage.
+ *
+ * DERIVED from {@link PLATFORM_CONSENT_DEFAULT_COMMANDS} rather than declared
+ * as its own flag. Those commands are what the console tells gtag about ad
+ * storage, so the question and the declaration cannot drift: a surface that
+ * denies advertising in every region asks nothing, and one that grants it
+ * anywhere asks.
+ *
+ * A control whose answer changes nothing is decoration, and decoration is what
+ * teaches people to click past the controls that do matter — which is the
+ * whole reason this is derived rather than hardcoded either way.
+ *
+ * The console currently grants advertising outside the prior-consent regions,
+ * because Aglyn advertises, remarkets and retargets on its own surfaces and
+ * the Privacy Policy names this one among them. So the question IS asked, and
+ * a visitor who declines gets the signals denied and the tags torn down.
+ *
+ * `every`, so a single region-scoped grant is enough to make the question
+ * real. The console's whole visitor population is not asked about a category
+ * because one region's declaration happens to deny it.
+ */
+export declare function platformAsksAboutAdvertising(): boolean;
+/**
+ * The per-visitor posture for the console, from the country the region
+ * endpoint reports.
+ *
+ * Unknown region falls to `opt-in`, exactly as it does for a customer site:
+ * the asymmetry is a few lost analytics events on a rare headerless visit,
+ * against pre-consent tracking of a European visitor.
+ *
+ * A separate function from the tenant's `resolveConsentPosture` because it
+ * answers over a different country set (see the module comment) — and it reads
+ * that set from `platform-consent-default.ts` rather than restating it, so the
+ * console's gate and the console's consent-mode declaration can never disagree
+ * about which regions require asking first.
+ */
+export declare function platformConsentPosture(country: string | null | undefined): VisitorConsentPosture;
+/**
+ * The cookie that carries a console visitor's answer between the sibling
+ * subdomains the console is served on.
+ *
+ * ## The defect this closes
+ *
+ * `localStorage` is per ORIGIN, and the console is one application served on
+ * several hostnames of one registrable domain: `app.<domain>` and
+ * `auth.<domain>`, which is where interactive sign-in is delegated to. So a
+ * record written on one is invisible to the other.
+ *
+ * For an accept that is only a second ask — annoying, and fail-safe, since an
+ * unread record means untracked. For a REFUSAL it is worse than annoying and
+ * not fail-safe at all: outside the prior-consent regions the sibling host
+ * finds no record, resolves the posture afresh and writes `implied`, so an
+ * explicit opt-out reverts to implied consent on the next hop. A visitor
+ * cannot be expected to say no once per hostname of an application they
+ * experience as one.
+ *
+ * ## Why a cookie, and why it carries the whole record
+ *
+ * A cookie is the only client-side store that spans subdomains, and the
+ * consent record is itself strictly necessary storage — it is how a "no" is
+ * remembered — so it needs no consent of its own. It carries the whole record
+ * rather than a flag because the record is what the shared reader validates:
+ * the mirror is re-read through `readStoredVisitorConsent`, never trusted, so
+ * a hand-edited cookie cannot grant what its status does not.
+ */
+export declare const PLATFORM_CONSENT_COOKIE = "aglyn_consent";
+export declare function setPlatformConsentSharesAcrossSubdomains(shares: boolean): void;
+/**
+ * Adopt a sibling host's answer into this origin, if this origin has none.
+ *
+ * Called ONCE at boot rather than from {@link readPlatformConsent}, because
+ * that reader is consulted synchronously from the analytics gate — during the
+ * services provider's first render, and again on every consent change — and a
+ * reader with a write in it would put a storage write in a render path and
+ * repeat it forever. Boot is also early enough by construction: module scope
+ * runs before the first render, so the gate's first read already sees it.
+ *
+ * The value is written into localStorage and then read back through
+ * {@link readPlatformConsent}, which is the whole reason this is safe. The
+ * shared reader re-derives both grants from the status and rejects an
+ * unrecognized shape, so a hand-edited cookie can only ever produce a record
+ * the status supports — the same guarantee the per-origin path has.
+ *
+ * Returns whether a record was adopted, which is what makes it assertable.
+ */
+export declare function hydratePlatformConsentFromMirror(): boolean;
+/** The console visitor's stored record, or null when there is none. */
+export declare function readPlatformConsent(): StoredVisitorConsent | null;
+/**
+ * Record a console consent state.
+ *
+ * Delegates wholesale, which is what carries the withdrawal behaviour: the
+ * shared writer re-derives both grants from the status, silences any resident
+ * GA tag, sweeps the analytics and advertising cookies, drops the persistent
+ * visitor id, and dispatches `VISITOR_CONSENT_CHANGED_EVENT`. The console's
+ * analytics gate listens for that event, which is what makes a refusal act on
+ * this pageview instead of the next one.
+ */
+export declare function storePlatformConsent(state: {
+    status: VisitorConsentStatus;
+    country?: string | null;
+    advertising?: boolean;
+}): StoredVisitorConsent;
+/**
+ * The gate's whole verdict: may analytics run for this console visitor right
+ * now?
+ *
+ * Reads storage on every call rather than caching, because it is consulted
+ * synchronously from the Firebase services boot — before any effect has run,
+ * and again after a consent change — and a cached answer is exactly how a
+ * withdrawal fails to take effect until a reload.
+ *
+ * Absent record answers NO. That is the load-bearing half: an undecided
+ * visitor is a visitor the tag stays out of, whatever the reason for their
+ * being undecided, so the gate never has to ask WHY.
+ */
+export declare function platformAnalyticsAllowed(): boolean;
+/** Whether advertising storage may run for this console visitor. */
+export declare function platformAdvertisingAllowed(): boolean;
+/** The console's resolution of a visitor, with no React in it. */
+export interface ResolvedPlatformConsent {
+    stored: StoredVisitorConsent | null;
+    posture: VisitorConsentPosture | null;
+    country: string | null;
+}
+/**
+ * The country this visitor is in, or null when nothing can name one.
+ *
+ * The country half of {@link resolvePlatformConsentRegion}, kept because a
+ * caller that only wants a country should not have to know that a posture can
+ * arrive without one.
+ */
+export declare function resolvePlatformConsentCountry(): Promise<string | null>;
+/**
+ * The region signal for this visit: a country when anything can name one, and
+ * a posture when the only signal available carries one without a country.
+ *
+ * Three sources, in strict order of authority, and the order is the whole
+ * design:
+ *
+ * 1. **The session cache** — a country already resolved this visit.
+ * 2. **The region endpoint** — an edge header, which is the only source that
+ *    knows where the request actually came from.
+ * 3. **The browser's time zone** — {@link geoHintFromTimeZone}, and ONLY when
+ *    the first two produced nothing. It exists for a deployment with no geo
+ *    header at all: a self-hosted container behind a plain reverse proxy,
+ *    where every visitor would otherwise be treated as unlocatable and asked
+ *    to opt in. It is never consulted while a header answers, and a zone it
+ *    does not recognize (`null`) is treated exactly as a missing header —
+ *    strictest posture, never permission.
+ */
+export interface ResolvedConsentRegion {
+    /** The country, when a source could honestly name one. */
+    country: string | null;
+    /**
+     * A posture the country cannot express, or null to derive it from the
+     * country. Set only by the time-zone hint, which can say "not a
+     * prior-consent region" while refusing to name which country that is —
+     * `America/Chicago` is the United States in almost every case and is also
+     * Canadian and Mexican territory in places, and a country that is merely
+     * probable is worse on a stored record than an absent one.
+     */
+    posture: VisitorConsentPosture | null;
+}
+export declare function resolvePlatformConsentRegion(): Promise<ResolvedConsentRegion>;
+/**
+ * Resolve this visitor's console consent state, most binding signal first:
+ *
+ * 1. An EXPLICIT stored choice — theirs; keep it, and skip the region lookup.
+ * 2. GPC — the browser's opt-out overrides an implied default (it can arrive
+ *    after one was recorded) but never an explicit accept.
+ * 3. Any other stored record — resolved on a previous visit.
+ * 4. Nothing stored: ask the region endpoint and apply the posture. `opt-out`
+ *    records `implied` and analytics is live from this paint; `opt-in` leaves
+ *    the visitor undecided, which keeps the tag out until the banner gets a
+ *    yes.
+ *
+ * Idempotent: it reads and writes the same storage deterministically and the
+ * region lookup is session-cached, so running it twice costs one network call
+ * and reaches one answer.
+ */
+export declare function decidePlatformConsent(): Promise<ResolvedPlatformConsent>;
+/**
+ * The refusal a "no" means for a visitor in this state.
+ *
+ * `opted-out` when they were defaulted in, `declined` when they were asked
+ * first. Same gate either way; distinct record, because "how many visitors
+ * were tracked before they said no" is a question the two answers separate.
+ */
+export declare function platformRefusalStatus(stored: StoredVisitorConsent | null, posture: VisitorConsentPosture | null): VisitorConsentStatus;
+/**
+ * Whether a status the panel is about to write would grant analytics — used to
+ * label the control, never to decide the gate.
+ */
+export declare function platformStatusGrantsAnalytics(status: VisitorConsentStatus): boolean;
+/**
+ * Start the resolution WITHOUT waiting for React to commit.
+ *
+ * The gate component's effect is the normal path and does this too. It is not
+ * enough on its own: an effect only runs if React commits, and a console that
+ * renders but never commits — a suspended provider above the tree — would
+ * otherwise leave a rest-of-world visitor permanently undecided and therefore
+ * permanently unmeasured. Fire-and-forget; the answer lands in storage, so
+ * whenever the component does run it reads it rather than asking again.
+ */
+export declare function primePlatformConsent(): void;
+/** Test seam: forget which pageviews have already been primed. */
+export declare function resetPlatformConsentPriming(): void;