@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/analytics-environment.js

@@ -0,0 +1,152 @@
+/**
+ * @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.
+ */ /**
+ * Whether THIS BUILD is allowed to report to Google Analytics at all
+ * (AGL-2067).
+ *
+ * ## The hole this closes
+ *
+ * Neither app gated GA on the deployment environment. The console called
+ * `initializeAnalytics` unconditionally and `apps/console/.env.development.local`
+ * points at the PRODUCTION measurement id, so every `next dev` session produced
+ * real `session_start` / `first_visit` / `page_view` hits in the live property;
+ * the tenant runtime mounted its tag wherever the resolved host carried an id,
+ * which on a preview deploy of `aglyn.com` is our own.
+ *
+ * That is not hypothetical. `docs/ANALYTICS.md` records the archived Marketing
+ * property's entire year-to-date history as 30 views / 6 users, ~24 of them
+ * `/signin` on Vercel PREVIEW urls of the console. Preview traffic reaching a
+ * production property is most of what that property ever recorded.
+ *
+ * `apps/docs` already got this right — the Docusaurus gtag plugin returns null
+ * unless `NODE_ENV === 'production'` — so this is the same rule, made
+ * available to the two apps that lacked it.
+ *
+ * ## Why this is better than the stamp for the dev case
+ *
+ * `traffic_type: 'internal'` only helps once a matching GA4 data filter exists
+ * in the property, and a filter is not retroactive: a hit that ships today is
+ * counted today. Not emitting at all needs no console configuration and cannot
+ * be got wrong later.
+ *
+ * ## The three signals, and why the default leans LOUD
+ *
+ * - `NODE_ENV !== 'production'` — every `next dev`, every jest run, every
+ *   local e2e. Never emits.
+ * - `deployEnv` is `preview` or `development` — a Vercel preview build has
+ *   `NODE_ENV === 'production'` (it is a production build), so nothing else
+ *   catches it. `VERCEL_ENV` is server-only, so each app maps it into the
+ *   client bundle through its `next.config` `env` block; assuming Vercel's
+ *   "automatically expose system environment variables" setting is on would
+ *   be a gate that silently is not there.
+ * - `deployEnv` unknown with `NODE_ENV === 'production'` — **emits.** That is
+ *   the self-host case (Docker + bring-your-own-Firebase), which points at the
+ *   operator's own Firebase project and their own GA property. Defaulting
+ *   those to silence would break a customer's analytics to protect ours, which
+ *   is the worse failure; our own builds are the ones that carry the marker.
+ * - **The document is served from a loopback host — never emits**, whatever
+ *   the other three say. The signals above are all build-time, and a build is
+ *   not a deployment: `next start`, `docker compose up` from a clone, and a
+ *   production container run locally all carry `NODE_ENV === 'production'`
+ *   with no `VERCEL_ENV`, which is byte-for-byte the self-host case the rule
+ *   above deliberately lets through. Run against
+ *   `apps/console/.env.development.local`, whose measurement id is the live
+ *   `G-YW5PG16YTM`, that path reports a developer's laptop as production
+ *   traffic — and it is not theoretical: `localhost` was 145 sessions of a
+ *   609-session month, arriving as `localhost:4200 / referral`, which also
+ *   overwrites the acquisition source of every session it touches.
+ *
+ *   The host is the one signal that separates the two cases, because a real
+ *   self-hosted deployment is reached at a real name. It is read from
+ *   `location` at call time and is therefore absent server-side, where it
+ *   changes nothing — the check can only ever tighten the client decision,
+ *   which is where the tag actually boots.
+ *
+ * ## The escape hatch
+ *
+ * `NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD=1` re-enables emission where the rules
+ * above would silence it, for the times someone genuinely needs to exercise
+ * the taxonomy against GA DebugView. It is deliberately paired with
+ * `analyticsEnvironmentForcesInternal`, so a build using it stamps
+ * `traffic_type: 'internal'` on everything unconditionally — the hatch cannot
+ * become the leak it exists beside.
+ */ /** The env var that re-enables analytics where this module would silence it. */ export const ANALYTICS_ALLOW_NONPROD_ENV = 'NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD';
+/** The deploy-environment values that are never our production surface. */ const NON_PRODUCTION_DEPLOY_ENVS = new Set([
+    'preview',
+    'development'
+]);
+/**
+ * Hostnames that mean "this machine, talking to itself".
+ *
+ * `.localhost` is matched as a suffix because the self-hosting compose serves
+ * a site subdomain as `{subdomain}.localhost:4500`, and RFC 6761 reserves the
+ * whole tree for exactly this purpose, so nothing real can be lost to it.
+ */ function isLoopbackHostname(hostname) {
+    const host = hostname.trim().toLowerCase().replace(/^\[/, '').replace(/]$/, '');
+    if (host === '') return false;
+    if (host === 'localhost' || host.endsWith('.localhost')) return true;
+    if (host === '::1' || host === '0.0.0.0') return true;
+    return /^127\./.test(host);
+}
+/**
+ * The build's own environment.
+ *
+ * Read through `process.env` at CALL time rather than captured at module load,
+ * so a spec can drive every branch — the alternative is a module constant that
+ * can only ever be observed in one state, which is the shape of a check that
+ * cannot fail.
+ */ export function readAnalyticsEnvironment() {
+    var _globalThis_location;
+    return {
+        nodeEnv: process.env.NODE_ENV,
+        deployEnv: process.env.NEXT_PUBLIC_DEPLOY_ENV,
+        allowNonProduction: process.env[ANALYTICS_ALLOW_NONPROD_ENV],
+        hostname: (_globalThis_location = globalThis.location) == null ? void 0 : _globalThis_location.hostname
+    };
+}
+/** Whether this build is one of our real production deployments. */ function isProductionSurface(env) {
+    if (env.nodeEnv !== 'production') return false;
+    if (isLoopbackHostname(env.hostname || '')) return false;
+    const deployEnv = (env.deployEnv || '').toLowerCase();
+    return !NON_PRODUCTION_DEPLOY_ENVS.has(deployEnv);
+}
+/** Whether the escape hatch is set to something meaning "yes". */ function allowsNonProduction(env) {
+    const raw = (env.allowNonProduction || '').trim().toLowerCase();
+    return raw !== '' && raw !== '0' && raw !== 'false' && raw !== 'off';
+}
+/**
+ * Whether this build may load a Google Analytics tag and send hits at all.
+ *
+ * The one question both apps ask. `false` means the tag is never created —
+ * not created and then suppressed — because a resident tag re-creates `_ga`
+ * and reports on its own (the AGL-1608 lesson), and because "no tag" is the
+ * only state that needs no filter to be true.
+ */ export function analyticsMayEmit(env = readAnalyticsEnvironment()) {
+    return isProductionSurface(env) || allowsNonProduction(env);
+}
+/**
+ * Whether every hit from this build must carry `traffic_type: 'internal'`
+ * regardless of who is signed in or what the browser opted into.
+ *
+ * True only for a non-production build running with the escape hatch on —
+ * i.e. exactly the builds that emit *because someone asked them to*, which are
+ * by definition ours. Keeps the hatch from reopening the hole.
+ */ export function analyticsEnvironmentForcesInternal(env = readAnalyticsEnvironment()) {
+    return !isProductionSurface(env) && allowsNonProduction(env);
+}
+export default analyticsMayEmit;
+
+//# sourceMappingURL=analytics-environment.js.map

package/src/lib/app-utils/analytics-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/analytics-environment.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 * Whether THIS BUILD is allowed to report to Google Analytics at all\n * (AGL-2067).\n *\n * ## The hole this closes\n *\n * Neither app gated GA on the deployment environment. The console called\n * `initializeAnalytics` unconditionally and `apps/console/.env.development.local`\n * points at the PRODUCTION measurement id, so every `next dev` session produced\n * real `session_start` / `first_visit` / `page_view` hits in the live property;\n * the tenant runtime mounted its tag wherever the resolved host carried an id,\n * which on a preview deploy of `aglyn.com` is our own.\n *\n * That is not hypothetical. `docs/ANALYTICS.md` records the archived Marketing\n * property's entire year-to-date history as 30 views / 6 users, ~24 of them\n * `/signin` on Vercel PREVIEW urls of the console. Preview traffic reaching a\n * production property is most of what that property ever recorded.\n *\n * `apps/docs` already got this right — the Docusaurus gtag plugin returns null\n * unless `NODE_ENV === 'production'` — so this is the same rule, made\n * available to the two apps that lacked it.\n *\n * ## Why this is better than the stamp for the dev case\n *\n * `traffic_type: 'internal'` only helps once a matching GA4 data filter exists\n * in the property, and a filter is not retroactive: a hit that ships today is\n * counted today. Not emitting at all needs no console configuration and cannot\n * be got wrong later.\n *\n * ## The three signals, and why the default leans LOUD\n *\n * - `NODE_ENV !== 'production'` — every `next dev`, every jest run, every\n *   local e2e. Never emits.\n * - `deployEnv` is `preview` or `development` — a Vercel preview build has\n *   `NODE_ENV === 'production'` (it is a production build), so nothing else\n *   catches it. `VERCEL_ENV` is server-only, so each app maps it into the\n *   client bundle through its `next.config` `env` block; assuming Vercel's\n *   \"automatically expose system environment variables\" setting is on would\n *   be a gate that silently is not there.\n * - `deployEnv` unknown with `NODE_ENV === 'production'` — **emits.** That is\n *   the self-host case (Docker + bring-your-own-Firebase), which points at the\n *   operator's own Firebase project and their own GA property. Defaulting\n *   those to silence would break a customer's analytics to protect ours, which\n *   is the worse failure; our own builds are the ones that carry the marker.\n * - **The document is served from a loopback host — never emits**, whatever\n *   the other three say. The signals above are all build-time, and a build is\n *   not a deployment: `next start`, `docker compose up` from a clone, and a\n *   production container run locally all carry `NODE_ENV === 'production'`\n *   with no `VERCEL_ENV`, which is byte-for-byte the self-host case the rule\n *   above deliberately lets through. Run against\n *   `apps/console/.env.development.local`, whose measurement id is the live\n *   `G-YW5PG16YTM`, that path reports a developer's laptop as production\n *   traffic — and it is not theoretical: `localhost` was 145 sessions of a\n *   609-session month, arriving as `localhost:4200 / referral`, which also\n *   overwrites the acquisition source of every session it touches.\n *\n *   The host is the one signal that separates the two cases, because a real\n *   self-hosted deployment is reached at a real name. It is read from\n *   `location` at call time and is therefore absent server-side, where it\n *   changes nothing — the check can only ever tighten the client decision,\n *   which is where the tag actually boots.\n *\n * ## The escape hatch\n *\n * `NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD=1` re-enables emission where the rules\n * above would silence it, for the times someone genuinely needs to exercise\n * the taxonomy against GA DebugView. It is deliberately paired with\n * `analyticsEnvironmentForcesInternal`, so a build using it stamps\n * `traffic_type: 'internal'` on everything unconditionally — the hatch cannot\n * become the leak it exists beside.\n */\n\n/** The env var that re-enables analytics where this module would silence it. */\nexport const ANALYTICS_ALLOW_NONPROD_ENV = 'NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD'\n\n/** The deploy-environment values that are never our production surface. */\nconst NON_PRODUCTION_DEPLOY_ENVS = new Set(['preview', 'development'])\n\n/**\n * Hostnames that mean \"this machine, talking to itself\".\n *\n * `.localhost` is matched as a suffix because the self-hosting compose serves\n * a site subdomain as `{subdomain}.localhost:4500`, and RFC 6761 reserves the\n * whole tree for exactly this purpose, so nothing real can be lost to it.\n */\nfunction isLoopbackHostname(hostname: string): boolean {\n  const host = hostname.trim().toLowerCase().replace(/^\\[/, '').replace(/]$/, '')\n  if (host === '') return false\n  if (host === 'localhost' || host.endsWith('.localhost')) return true\n  if (host === '::1' || host === '0.0.0.0') return true\n  return /^127\\./.test(host)\n}\n\nexport interface AnalyticsEnvironment {\n  /** `process.env.NODE_ENV`. */\n  nodeEnv?: string | null\n  /** `VERCEL_ENV`, mapped into the client bundle by each app's next.config. */\n  deployEnv?: string | null\n  /** The escape hatch's raw value. */\n  allowNonProduction?: string | null\n  /**\n   * The host this document is served from, absent server-side.\n   *\n   * Undefined is NOT loopback: a server render has no location and must keep\n   * the build-time answer, or the tenant's `<Script>` would stop rendering on\n   * every real deployment.\n   */\n  hostname?: string | null\n}\n\n/**\n * The build's own environment.\n *\n * Read through `process.env` at CALL time rather than captured at module load,\n * so a spec can drive every branch — the alternative is a module constant that\n * can only ever be observed in one state, which is the shape of a check that\n * cannot fail.\n */\nexport function readAnalyticsEnvironment(): AnalyticsEnvironment {\n  return {\n    nodeEnv: process.env.NODE_ENV,\n    deployEnv: process.env.NEXT_PUBLIC_DEPLOY_ENV,\n    allowNonProduction: process.env[ANALYTICS_ALLOW_NONPROD_ENV],\n    hostname: globalThis.location?.hostname,\n  }\n}\n\n/** Whether this build is one of our real production deployments. */\nfunction isProductionSurface(env: AnalyticsEnvironment): boolean {\n  if (env.nodeEnv !== 'production') return false\n  if (isLoopbackHostname(env.hostname || '')) return false\n  const deployEnv = (env.deployEnv || '').toLowerCase()\n  return !NON_PRODUCTION_DEPLOY_ENVS.has(deployEnv)\n}\n\n/** Whether the escape hatch is set to something meaning \"yes\". */\nfunction allowsNonProduction(env: AnalyticsEnvironment): boolean {\n  const raw = (env.allowNonProduction || '').trim().toLowerCase()\n  return raw !== '' && raw !== '0' && raw !== 'false' && raw !== 'off'\n}\n\n/**\n * Whether this build may load a Google Analytics tag and send hits at all.\n *\n * The one question both apps ask. `false` means the tag is never created —\n * not created and then suppressed — because a resident tag re-creates `_ga`\n * and reports on its own (the AGL-1608 lesson), and because \"no tag\" is the\n * only state that needs no filter to be true.\n */\nexport function analyticsMayEmit(\n  env: AnalyticsEnvironment = readAnalyticsEnvironment(),\n): boolean {\n  return isProductionSurface(env) || allowsNonProduction(env)\n}\n\n/**\n * Whether every hit from this build must carry `traffic_type: 'internal'`\n * regardless of who is signed in or what the browser opted into.\n *\n * True only for a non-production build running with the escape hatch on —\n * i.e. exactly the builds that emit *because someone asked them to*, which are\n * by definition ours. Keeps the hatch from reopening the hole.\n */\nexport function analyticsEnvironmentForcesInternal(\n  env: AnalyticsEnvironment = readAnalyticsEnvironment(),\n): boolean {\n  return !isProductionSurface(env) && allowsNonProduction(env)\n}\n\nexport default analyticsMayEmit\n"],"names":["ANALYTICS_ALLOW_NONPROD_ENV","NON_PRODUCTION_DEPLOY_ENVS","Set","isLoopbackHostname","hostname","host","trim","toLowerCase","replace","endsWith","test","readAnalyticsEnvironment","globalThis","nodeEnv","process","env","NODE_ENV","deployEnv","NEXT_PUBLIC_DEPLOY_ENV","allowNonProduction","location","isProductionSurface","has","allowsNonProduction","raw","analyticsMayEmit","analyticsEnvironmentForcesInternal"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEC,GAED,8EAA8E,GAC9E,OAAO,MAAMA,8BAA8B,sCAAqC;AAEhF,yEAAyE,GACzE,MAAMC,6BAA6B,IAAIC,IAAI;IAAC;IAAW;CAAc;AAErE;;;;;;CAMC,GACD,SAASC,mBAAmBC,QAAgB;IAC1C,MAAMC,OAAOD,SAASE,IAAI,GAAGC,WAAW,GAAGC,OAAO,CAAC,OAAO,IAAIA,OAAO,CAAC,MAAM;IAC5E,IAAIH,SAAS,IAAI,OAAO;IACxB,IAAIA,SAAS,eAAeA,KAAKI,QAAQ,CAAC,eAAe,OAAO;IAChE,IAAIJ,SAAS,SAASA,SAAS,WAAW,OAAO;IACjD,OAAO,SAASK,IAAI,CAACL;AACvB;AAmBA;;;;;;;CAOC,GACD,OAAO,SAASM;QAKFC;IAJZ,OAAO;QACLC,SAASC,QAAQC,GAAG,CAACC,QAAQ;QAC7BC,WAAWH,QAAQC,GAAG,CAACG,sBAAsB;QAC7CC,oBAAoBL,QAAQC,GAAG,CAACf,4BAA4B;QAC5DI,QAAQ,GAAEQ,uBAAAA,WAAWQ,QAAQ,qBAAnBR,qBAAqBR,QAAQ;IACzC;AACF;AAEA,kEAAkE,GAClE,SAASiB,oBAAoBN,GAAyB;IACpD,IAAIA,IAAIF,OAAO,KAAK,cAAc,OAAO;IACzC,IAAIV,mBAAmBY,IAAIX,QAAQ,IAAI,KAAK,OAAO;IACnD,MAAMa,YAAY,AAACF,CAAAA,IAAIE,SAAS,IAAI,EAAC,EAAGV,WAAW;IACnD,OAAO,CAACN,2BAA2BqB,GAAG,CAACL;AACzC;AAEA,gEAAgE,GAChE,SAASM,oBAAoBR,GAAyB;IACpD,MAAMS,MAAM,AAACT,CAAAA,IAAII,kBAAkB,IAAI,EAAC,EAAGb,IAAI,GAAGC,WAAW;IAC7D,OAAOiB,QAAQ,MAAMA,QAAQ,OAAOA,QAAQ,WAAWA,QAAQ;AACjE;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,iBACdV,MAA4BJ,0BAA0B;IAEtD,OAAOU,oBAAoBN,QAAQQ,oBAAoBR;AACzD;AAEA;;;;;;;CAOC,GACD,OAAO,SAASW,mCACdX,MAA4BJ,0BAA0B;IAEtD,OAAO,CAACU,oBAAoBN,QAAQQ,oBAAoBR;AAC1D;AAEA,eAAeU,iBAAgB"}