@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/support-tiers.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * What support each plan actually commits to (AGL-1103).
+ *
+ * Support was one binary gate — `plan !== 'free'` — so a Starter org and an
+ * Enterprise org got the identical queue, the identical silence, and no stated
+ * target either could hold us to. The plans imply tiers; nothing implemented
+ * them.
+ *
+ * These numbers are a COMMERCIAL COMMITMENT, not an engineering choice. They
+ * are set deliberately long: a published target is easy to tighten and painful
+ * to loosen, and the only thing worse than a slow promise is a fast one that
+ * gets missed. Changing them changes what customers are owed, so they live
+ * here alone and nowhere else.
+ */
+import type { OrgPlan } from '../foundation';
+/** Ordered weakest → strongest; the queue sorts on this. */
+export type SupportTier = 'community' | 'standard' | 'business' | 'priority' | 'dedicated';
+/**
+ * A first-response window.
+ *
+ * The unit is explicit per tier rather than normalised, because the two are
+ * genuinely different promises and collapsing them hides that. "3 business
+ * days" spans a weekend; "48 hours" does not. Enterprise is quoted in clock
+ * hours precisely because it is the tier that does not stop on Friday.
+ */
+export interface ResponseWindow {
+    min: number;
+    max: number;
+    unit: 'business-days' | 'hours';
+}
+export interface SupportCommitment {
+    tier: SupportTier;
+    /** Shown to customers. */
+    label: string;
+    /** `null` means no ticket commitment — the forum is the channel. */
+    firstResponse: ResponseWindow | null;
+    /** A named human, not a queue. Enterprise only. */
+    namedManager: boolean;
+    /**
+     * Access to the community forum.
+     *
+     * True on every tier including Community, and that is the whole meaning of
+     * "forum only": a tier with no ticket commitment whose forum was also shut
+     * would have no support channel at all, which is not a tier — it is nothing
+     * wearing a tier's name.
+     */
+    forum: boolean;
+}
+/**
+ * Every plan's commitment.
+ *
+ * `Record<OrgPlan, …>` on purpose: a new plan fails to compile here rather
+ * than silently inheriting whatever the lookup's fallback happens to be, which
+ * for support means either promising something we never agreed or promising
+ * nothing to someone who paid.
+ */
+export declare const SUPPORT_BY_PLAN: Record<OrgPlan, SupportCommitment>;
+/** Strength order, weakest first — the index IS the rank. */
+export declare const SUPPORT_TIER_ORDER: SupportTier[];
+/** Higher is stronger. Used to order the staff queue. */
+export declare function supportTierRank(tier: SupportTier): number;
+export declare function supportForPlan(plan: OrgPlan | undefined | null): SupportCommitment;
+/** "7–14 business days" · "24–48 hours" · "1 business day". */
+export declare function describeResponseWindow(window: ResponseWindow | null): string | null;
+/**
+ * Advance past `count` business days, skipping Saturday and Sunday.
+ *
+ * Deliberately does NOT know about public holidays. A half-right holiday
+ * calendar is worse than none — it would quietly shorten the deadline in
+ * whichever country it did not cover, and support is answered from more than
+ * one. The stated window is long enough to absorb them; when that stops being
+ * true this needs a real calendar, not a patch.
+ */
+export declare function addBusinessDays(fromMs: number, count: number): number;
+/**
+ * When a first response is owed at the latest, or `null` if nothing is owed.
+ *
+ * Always the MAX of the window. The range is what we tell customers; the
+ * commitment is its upper bound, and that is the only number a breach can be
+ * measured against.
+ */
+export declare function responseDueAt(commitment: SupportCommitment, openedAtMs: number): number | null;
+/**
+ * Is the ladder still strictly better as plans get stronger?
+ *
+ * Exported so a test can assert it, because the failure is silent and the
+ * units differ across tiers: quoting Enterprise in business hours rather than
+ * clock hours makes it slower than Agency while every individual number still
+ * looks reasonable on its own. Compares worst cases as elapsed wall-clock from
+ * a Monday, which is the only basis on which the two units are comparable.
+ */
+export declare function ladderIsMonotonic(mondayMs: number): boolean;

package/src/lib/app-utils/support-tiers.js

@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * What support each plan actually commits to (AGL-1103).
+ *
+ * Support was one binary gate — `plan !== 'free'` — so a Starter org and an
+ * Enterprise org got the identical queue, the identical silence, and no stated
+ * target either could hold us to. The plans imply tiers; nothing implemented
+ * them.
+ *
+ * These numbers are a COMMERCIAL COMMITMENT, not an engineering choice. They
+ * are set deliberately long: a published target is easy to tighten and painful
+ * to loosen, and the only thing worse than a slow promise is a fast one that
+ * gets missed. Changing them changes what customers are owed, so they live
+ * here alone and nowhere else.
+ */ /**
+ * Every plan's commitment.
+ *
+ * `Record<OrgPlan, …>` on purpose: a new plan fails to compile here rather
+ * than silently inheriting whatever the lookup's fallback happens to be, which
+ * for support means either promising something we never agreed or promising
+ * nothing to someone who paid.
+ */ export const SUPPORT_BY_PLAN = {
+    free: {
+        tier: 'community',
+        label: 'Community',
+        firstResponse: null,
+        namedManager: false,
+        forum: true
+    },
+    starter: {
+        tier: 'community',
+        label: 'Community',
+        // Forum only, same as Free: ticket support starts at Pro. Starter pays
+        // for product, not for our time.
+        firstResponse: null,
+        namedManager: false,
+        forum: true
+    },
+    pro: {
+        tier: 'standard',
+        label: 'Standard',
+        firstResponse: {
+            min: 7,
+            max: 14,
+            unit: 'business-days'
+        },
+        namedManager: false,
+        forum: true
+    },
+    business: {
+        tier: 'business',
+        label: 'Business',
+        firstResponse: {
+            min: 4,
+            max: 6,
+            unit: 'business-days'
+        },
+        namedManager: false,
+        forum: true
+    },
+    scale: {
+        tier: 'business',
+        label: 'Business',
+        firstResponse: {
+            min: 4,
+            max: 6,
+            unit: 'business-days'
+        },
+        namedManager: false,
+        forum: true
+    },
+    advanced: {
+        tier: 'business',
+        label: 'Business',
+        firstResponse: {
+            min: 4,
+            max: 6,
+            unit: 'business-days'
+        },
+        namedManager: false,
+        forum: true
+    },
+    agency: {
+        tier: 'priority',
+        label: 'Priority',
+        firstResponse: {
+            min: 1,
+            max: 3,
+            unit: 'business-days'
+        },
+        namedManager: false,
+        forum: true
+    },
+    enterprise: {
+        tier: 'dedicated',
+        label: 'Dedicated',
+        // Quoted in CLOCK hours, and that is the point of the tier: 24–48 hours
+        // runs through a weekend, where "1–3 business days" does not. Read as
+        // business hours it would be 3–6 business days — SLOWER than Agency
+        // above, inverting the ladder. `ladderIsMonotonic` below asserts it is
+        // not, so this cannot silently regress.
+        firstResponse: {
+            min: 24,
+            max: 48,
+            unit: 'hours'
+        },
+        namedManager: true,
+        forum: true
+    }
+};
+/** Strength order, weakest first — the index IS the rank. */ export const SUPPORT_TIER_ORDER = [
+    'community',
+    'standard',
+    'business',
+    'priority',
+    'dedicated'
+];
+/** Higher is stronger. Used to order the staff queue. */ export function supportTierRank(tier) {
+    return SUPPORT_TIER_ORDER.indexOf(tier);
+}
+export function supportForPlan(plan) {
+    var _SUPPORT_BY_PLAN_plan;
+    // An unknown or missing plan gets the community tier, never a paid one:
+    // failing open here would hand an unpaid org a response target.
+    return (_SUPPORT_BY_PLAN_plan = SUPPORT_BY_PLAN[plan]) != null ? _SUPPORT_BY_PLAN_plan : SUPPORT_BY_PLAN.free;
+}
+/** "7–14 business days" · "24–48 hours" · "1 business day". */ export function describeResponseWindow(window) {
+    if (!window) return null;
+    const unit = window.unit === 'hours' ? 'hours' : window.max === 1 ? 'business day' : 'business days';
+    const range = window.min === window.max ? `${window.max}` : `${window.min}–${window.max}`;
+    return `${range} ${unit}`;
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+/**
+ * Advance past `count` business days, skipping Saturday and Sunday.
+ *
+ * Deliberately does NOT know about public holidays. A half-right holiday
+ * calendar is worse than none — it would quietly shorten the deadline in
+ * whichever country it did not cover, and support is answered from more than
+ * one. The stated window is long enough to absorb them; when that stops being
+ * true this needs a real calendar, not a patch.
+ */ export function addBusinessDays(fromMs, count) {
+    let cursor = fromMs;
+    let remaining = count;
+    while(remaining > 0){
+        cursor += DAY_MS;
+        const day = new Date(cursor).getUTCDay();
+        if (day !== 0 && day !== 6) remaining -= 1;
+    }
+    return cursor;
+}
+/**
+ * When a first response is owed at the latest, or `null` if nothing is owed.
+ *
+ * Always the MAX of the window. The range is what we tell customers; the
+ * commitment is its upper bound, and that is the only number a breach can be
+ * measured against.
+ */ export function responseDueAt(commitment, openedAtMs) {
+    const window = commitment.firstResponse;
+    if (!window) return null;
+    return window.unit === 'hours' ? openedAtMs + window.max * HOUR_MS : addBusinessDays(openedAtMs, window.max);
+}
+/**
+ * Is the ladder still strictly better as plans get stronger?
+ *
+ * Exported so a test can assert it, because the failure is silent and the
+ * units differ across tiers: quoting Enterprise in business hours rather than
+ * clock hours makes it slower than Agency while every individual number still
+ * looks reasonable on its own. Compares worst cases as elapsed wall-clock from
+ * a Monday, which is the only basis on which the two units are comparable.
+ */ export function ladderIsMonotonic(mondayMs) {
+    const seen = new Map();
+    for (const commitment of Object.values(SUPPORT_BY_PLAN)){
+        const due = responseDueAt(commitment, mondayMs);
+        if (due === null) continue;
+        const elapsed = due - mondayMs;
+        const previous = seen.get(commitment.tier);
+        // Plans sharing a tier must quote the same window.
+        if (previous !== undefined && previous !== elapsed) return false;
+        seen.set(commitment.tier, elapsed);
+    }
+    const ranked = SUPPORT_TIER_ORDER.filter((tier)=>seen.has(tier)).map((tier)=>seen.get(tier));
+    return ranked.every((value, index)=>index === 0 || value < ranked[index - 1]);
+}
+
+//# sourceMappingURL=support-tiers.js.map

package/src/lib/app-utils/support-tiers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/support-tiers.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 * What support each plan actually commits to (AGL-1103).\n *\n * Support was one binary gate — `plan !== 'free'` — so a Starter org and an\n * Enterprise org got the identical queue, the identical silence, and no stated\n * target either could hold us to. The plans imply tiers; nothing implemented\n * them.\n *\n * These numbers are a COMMERCIAL COMMITMENT, not an engineering choice. They\n * are set deliberately long: a published target is easy to tighten and painful\n * to loosen, and the only thing worse than a slow promise is a fast one that\n * gets missed. Changing them changes what customers are owed, so they live\n * here alone and nowhere else.\n */\n\nimport type { OrgPlan } from '../foundation'\n\n/** Ordered weakest → strongest; the queue sorts on this. */\nexport type SupportTier =\n  | 'community'\n  | 'standard'\n  | 'business'\n  | 'priority'\n  | 'dedicated'\n\n/**\n * A first-response window.\n *\n * The unit is explicit per tier rather than normalised, because the two are\n * genuinely different promises and collapsing them hides that. \"3 business\n * days\" spans a weekend; \"48 hours\" does not. Enterprise is quoted in clock\n * hours precisely because it is the tier that does not stop on Friday.\n */\nexport interface ResponseWindow {\n  min: number\n  max: number\n  unit: 'business-days' | 'hours'\n}\n\nexport interface SupportCommitment {\n  tier: SupportTier\n  /** Shown to customers. */\n  label: string\n  /** `null` means no ticket commitment — the forum is the channel. */\n  firstResponse: ResponseWindow | null\n  /** A named human, not a queue. Enterprise only. */\n  namedManager: boolean\n  /**\n   * Access to the community forum.\n   *\n   * True on every tier including Community, and that is the whole meaning of\n   * \"forum only\": a tier with no ticket commitment whose forum was also shut\n   * would have no support channel at all, which is not a tier — it is nothing\n   * wearing a tier's name.\n   */\n  forum: boolean\n}\n\n/**\n * Every plan's commitment.\n *\n * `Record<OrgPlan, …>` on purpose: a new plan fails to compile here rather\n * than silently inheriting whatever the lookup's fallback happens to be, which\n * for support means either promising something we never agreed or promising\n * nothing to someone who paid.\n */\nexport const SUPPORT_BY_PLAN: Record<OrgPlan, SupportCommitment> = {\n  free: {\n    tier: 'community',\n    label: 'Community',\n    firstResponse: null,\n    namedManager: false,\n    forum: true,\n  },\n  starter: {\n    tier: 'community',\n    label: 'Community',\n    // Forum only, same as Free: ticket support starts at Pro. Starter pays\n    // for product, not for our time.\n    firstResponse: null,\n    namedManager: false,\n    forum: true,\n  },\n  pro: {\n    tier: 'standard',\n    label: 'Standard',\n    firstResponse: { min: 7, max: 14, unit: 'business-days' },\n    namedManager: false,\n    forum: true,\n  },\n  business: {\n    tier: 'business',\n    label: 'Business',\n    firstResponse: { min: 4, max: 6, unit: 'business-days' },\n    namedManager: false,\n    forum: true,\n  },\n  scale: {\n    tier: 'business',\n    label: 'Business',\n    firstResponse: { min: 4, max: 6, unit: 'business-days' },\n    namedManager: false,\n    forum: true,\n  },\n  advanced: {\n    tier: 'business',\n    label: 'Business',\n    firstResponse: { min: 4, max: 6, unit: 'business-days' },\n    namedManager: false,\n    forum: true,\n  },\n  agency: {\n    tier: 'priority',\n    label: 'Priority',\n    firstResponse: { min: 1, max: 3, unit: 'business-days' },\n    namedManager: false,\n    forum: true,\n  },\n  enterprise: {\n    tier: 'dedicated',\n    label: 'Dedicated',\n    // Quoted in CLOCK hours, and that is the point of the tier: 24–48 hours\n    // runs through a weekend, where \"1–3 business days\" does not. Read as\n    // business hours it would be 3–6 business days — SLOWER than Agency\n    // above, inverting the ladder. `ladderIsMonotonic` below asserts it is\n    // not, so this cannot silently regress.\n    firstResponse: { min: 24, max: 48, unit: 'hours' },\n    namedManager: true,\n    forum: true,\n  },\n}\n\n/** Strength order, weakest first — the index IS the rank. */\nexport const SUPPORT_TIER_ORDER: SupportTier[] = [\n  'community',\n  'standard',\n  'business',\n  'priority',\n  'dedicated',\n]\n\n/** Higher is stronger. Used to order the staff queue. */\nexport function supportTierRank(tier: SupportTier): number {\n  return SUPPORT_TIER_ORDER.indexOf(tier)\n}\n\nexport function supportForPlan(plan: OrgPlan | undefined | null): SupportCommitment {\n  // An unknown or missing plan gets the community tier, never a paid one:\n  // failing open here would hand an unpaid org a response target.\n  return SUPPORT_BY_PLAN[plan as OrgPlan] ?? SUPPORT_BY_PLAN.free\n}\n\n/** \"7–14 business days\" · \"24–48 hours\" · \"1 business day\". */\nexport function describeResponseWindow(window: ResponseWindow | null): string | null {\n  if (!window) return null\n  const unit =\n    window.unit === 'hours'\n      ? 'hours'\n      : window.max === 1\n        ? 'business day'\n        : 'business days'\n  const range = window.min === window.max ? `${window.max}` : `${window.min}–${window.max}`\n  return `${range} ${unit}`\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000\nconst HOUR_MS = 60 * 60 * 1000\n\n/**\n * Advance past `count` business days, skipping Saturday and Sunday.\n *\n * Deliberately does NOT know about public holidays. A half-right holiday\n * calendar is worse than none — it would quietly shorten the deadline in\n * whichever country it did not cover, and support is answered from more than\n * one. The stated window is long enough to absorb them; when that stops being\n * true this needs a real calendar, not a patch.\n */\nexport function addBusinessDays(fromMs: number, count: number): number {\n  let cursor = fromMs\n  let remaining = count\n  while (remaining > 0) {\n    cursor += DAY_MS\n    const day = new Date(cursor).getUTCDay()\n    if (day !== 0 && day !== 6) remaining -= 1\n  }\n  return cursor\n}\n\n/**\n * When a first response is owed at the latest, or `null` if nothing is owed.\n *\n * Always the MAX of the window. The range is what we tell customers; the\n * commitment is its upper bound, and that is the only number a breach can be\n * measured against.\n */\nexport function responseDueAt(\n  commitment: SupportCommitment,\n  openedAtMs: number,\n): number | null {\n  const window = commitment.firstResponse\n  if (!window) return null\n  return window.unit === 'hours'\n    ? openedAtMs + window.max * HOUR_MS\n    : addBusinessDays(openedAtMs, window.max)\n}\n\n/**\n * Is the ladder still strictly better as plans get stronger?\n *\n * Exported so a test can assert it, because the failure is silent and the\n * units differ across tiers: quoting Enterprise in business hours rather than\n * clock hours makes it slower than Agency while every individual number still\n * looks reasonable on its own. Compares worst cases as elapsed wall-clock from\n * a Monday, which is the only basis on which the two units are comparable.\n */\nexport function ladderIsMonotonic(mondayMs: number): boolean {\n  const seen = new Map<SupportTier, number>()\n  for (const commitment of Object.values(SUPPORT_BY_PLAN)) {\n    const due = responseDueAt(commitment, mondayMs)\n    if (due === null) continue\n    const elapsed = due - mondayMs\n    const previous = seen.get(commitment.tier)\n    // Plans sharing a tier must quote the same window.\n    if (previous !== undefined && previous !== elapsed) return false\n    seen.set(commitment.tier, elapsed)\n  }\n  const ranked = SUPPORT_TIER_ORDER.filter((tier) => seen.has(tier)).map((tier) =>\n    seen.get(tier) as number,\n  )\n  return ranked.every((value, index) => index === 0 || value < ranked[index - 1])\n}\n"],"names":["SUPPORT_BY_PLAN","free","tier","label","firstResponse","namedManager","forum","starter","pro","min","max","unit","business","scale","advanced","agency","enterprise","SUPPORT_TIER_ORDER","supportTierRank","indexOf","supportForPlan","plan","describeResponseWindow","window","range","DAY_MS","HOUR_MS","addBusinessDays","fromMs","count","cursor","remaining","day","Date","getUTCDay","responseDueAt","commitment","openedAtMs","ladderIsMonotonic","mondayMs","seen","Map","Object","values","due","elapsed","previous","get","undefined","set","ranked","filter","has","map","every","value","index"],"mappings":"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"}

package/src/lib/app-utils/timezone-geo-hint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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.
+ */
+export interface TimeZoneGeoHint {
+    /**
+     * The country, when the zone identifies one honestly. `null` means "not a
+     * prior-consent region, and this cannot say which country" — a real answer
+     * for the posture, and the only truthful one for the record.
+     */
+    country: string | null;
+    /** Whether this zone sits in a region that must be asked before tracking. */
+    priorConsent: boolean;
+}
+/** The browser's IANA zone, or `''` where `Intl` cannot answer. */
+export declare function readBrowserTimeZone(): string;
+/**
+ * The region hint for an IANA zone, or `null` when it says nothing useful.
+ *
+ * `null` is the answer for an unknown zone, and callers must treat it exactly
+ * as they treat a missing header: strictest posture. It is never a licence to
+ * assume the permissive side.
+ */
+export declare function geoHintFromTimeZone(timeZone: string | null | undefined): TimeZoneGeoHint | null;

package/src/lib/app-utils/timezone-geo-hint.js

@@ -0,0 +1,180 @@
+/**
+ * @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.
+ */ /**
+ * A last-resort region signal, read from the browser's own time zone.
+ *
+ * ## Why this exists
+ *
+ * The consent posture is decided from the request's country, and the country
+ * comes from an edge header. `readRequestGeo` now tries eight of them, but a
+ * deployment can still have none: a self-hosted container behind a plain
+ * reverse proxy, a preview build, or `localhost`. Every one of those resolves
+ * to "region unknown", which is deliberately the STRICTEST posture — so the
+ * visitor is asked to opt in.
+ *
+ * That is the safe direction and it is still wrong for most of the world. It
+ * also means a self-host operator in the US sees a prior-consent banner they
+ * do not need and cannot switch off, and has no way to tell that the cause is
+ * a missing header rather than a deliberate setting.
+ *
+ * ## Why the time zone, and not an IP lookup
+ *
+ * ⛔ Deliberately NOT a geolocation service. Sending a visitor's IP address to
+ * a third party in order to decide what to ask them about privacy is its own
+ * disclosure and its own subprocessor — the cure would be worse than the
+ * problem it treats.
+ *
+ * The time zone is already in the page, costs no request, identifies no one,
+ * and is exactly as coarse as the question: this is not "where are you", it is
+ * "are you somewhere that requires asking first".
+ *
+ * ## What it will not do
+ *
+ * It never returns a country for a non-European zone. `America/Chicago` is
+ * ninety-nine percent the United States and it is also `US`, `CA` and `MX`
+ * territory in places — and the country is STORED on the consent record, where
+ * a confident guess is worse than an absent value. So the answer for those is
+ * "not a prior-consent region, country unknown", which is all the posture
+ * needs and all this can honestly say.
+ *
+ * ⚠️ A VPN, a travelling laptop or a manually-set clock can all disagree with
+ * the visitor's actual location. This ranks BELOW every header for that
+ * reason, and the strict posture is still what an unrecognized zone gets.
+ */ /**
+ * The IANA area prefixes that are never a prior-consent region.
+ *
+ * Listed positively rather than as "anything that is not Europe/": an unknown
+ * or malformed zone must fall through to the strict posture, and a negative
+ * test would hand it the permissive one.
+ */ const NON_EUROPEAN_AREAS = [
+    'America/',
+    'Asia/',
+    'Australia/',
+    'Africa/',
+    'Pacific/',
+    'Antarctica/',
+    'US/',
+    'Canada/',
+    'Brazil/',
+    'Mexico/',
+    'Japan',
+    'Singapore',
+    'Hongkong',
+    'NZ'
+];
+/**
+ * Zones inside a prior-consent country that do NOT start with `Europe/`.
+ *
+ * The EU's outermost regions and the EEA's islands are the reason this list
+ * exists: the GDPR applies in Guadeloupe and the Canaries exactly as it does
+ * in Paris and Madrid, and every one of them is filed by IANA under `America/`,
+ * `Atlantic/` or `Indian/`. Matching on `Europe/` alone would place all of
+ * them on the permissive side, which is the one direction this must never get
+ * wrong.
+ */ const PRIOR_CONSENT_NON_EUROPE_ZONES = {
+    'Atlantic/Canary': 'ES',
+    'Atlantic/Madeira': 'PT',
+    'Atlantic/Azores': 'PT',
+    'Atlantic/Reykjavik': 'IS',
+    'Atlantic/Faroe': 'DK',
+    'Atlantic/Jan_Mayen': 'NO',
+    'America/Cayenne': 'GF',
+    'America/Guadeloupe': 'GP',
+    'America/Martinique': 'MQ',
+    'America/Marigot': 'GP',
+    'America/St_Barthelemy': 'GP',
+    'Indian/Reunion': 'RE',
+    'Indian/Mayotte': 'YT',
+    'Arctic/Longyearbyen': 'NO'
+};
+/**
+ * `Europe/<City>` zones whose country is NOT in the prior-consent set.
+ *
+ * The EEA is not the same shape as the continent. Without these, a visitor in
+ * Moscow or Istanbul would be treated as a European one — harmless for the
+ * consent posture, since it only makes it stricter, but it would store a
+ * region claim that is simply untrue.
+ */ const EUROPE_ZONES_OUTSIDE_THE_SET = [
+    'Europe/Moscow',
+    'Europe/Istanbul',
+    'Europe/Kiev',
+    'Europe/Kyiv',
+    'Europe/Minsk',
+    'Europe/Belgrade',
+    'Europe/Sarajevo',
+    'Europe/Skopje',
+    'Europe/Tirane',
+    'Europe/Podgorica',
+    'Europe/Chisinau',
+    'Europe/Volgograd',
+    'Europe/Samara',
+    'Europe/Kaliningrad',
+    'Europe/Simferopol'
+];
+/** The browser's IANA zone, or `''` where `Intl` cannot answer. */ export function readBrowserTimeZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || '';
+    } catch (unused) {
+        // Some locked-down and embedded runtimes throw rather than return.
+        return '';
+    }
+}
+/**
+ * The region hint for an IANA zone, or `null` when it says nothing useful.
+ *
+ * `null` is the answer for an unknown zone, and callers must treat it exactly
+ * as they treat a missing header: strictest posture. It is never a licence to
+ * assume the permissive side.
+ */ export function geoHintFromTimeZone(timeZone) {
+    const zone = (timeZone != null ? timeZone : '').trim();
+    if (!zone) return null;
+    const mapped = PRIOR_CONSENT_NON_EUROPE_ZONES[zone];
+    if (mapped) return {
+        country: mapped,
+        priorConsent: true
+    };
+    if (zone.indexOf('Europe/') === 0) {
+        if (EUROPE_ZONES_OUTSIDE_THE_SET.indexOf(zone) >= 0) {
+            // Europe, but outside the EEA/UK/CH set. No country claim: the zone
+            // identifies a city, and several of these span more than one country.
+            return {
+                country: null,
+                priorConsent: false
+            };
+        }
+        /*
+     * Prior consent, with no country named. The posture is all that is needed
+     * and it is all this can support — `Europe/Zurich` is Switzerland, but
+     * `Europe/Brussels` is also Luxembourg's zone in practice, and a stored
+     * country that is merely probable is worse than an absent one.
+     */ return {
+            country: null,
+            priorConsent: true
+        };
+    }
+    for (const area of NON_EUROPEAN_AREAS){
+        const matches = area.endsWith('/') ? zone.indexOf(area) === 0 : zone === area;
+        if (matches) return {
+            country: null,
+            priorConsent: false
+        };
+    }
+    // UTC, GMT, `Etc/*`, a fixed offset, or anything unrecognized. A visitor
+    // hiding their zone is not a visitor to assume the permissive side about.
+    return null;
+}
+
+//# sourceMappingURL=timezone-geo-hint.js.map

package/src/lib/app-utils/timezone-geo-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/timezone-geo-hint.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 * A last-resort region signal, read from the browser's own time zone.\n *\n * ## Why this exists\n *\n * The consent posture is decided from the request's country, and the country\n * comes from an edge header. `readRequestGeo` now tries eight of them, but a\n * deployment can still have none: a self-hosted container behind a plain\n * reverse proxy, a preview build, or `localhost`. Every one of those resolves\n * to \"region unknown\", which is deliberately the STRICTEST posture — so the\n * visitor is asked to opt in.\n *\n * That is the safe direction and it is still wrong for most of the world. It\n * also means a self-host operator in the US sees a prior-consent banner they\n * do not need and cannot switch off, and has no way to tell that the cause is\n * a missing header rather than a deliberate setting.\n *\n * ## Why the time zone, and not an IP lookup\n *\n * ⛔ Deliberately NOT a geolocation service. Sending a visitor's IP address to\n * a third party in order to decide what to ask them about privacy is its own\n * disclosure and its own subprocessor — the cure would be worse than the\n * problem it treats.\n *\n * The time zone is already in the page, costs no request, identifies no one,\n * and is exactly as coarse as the question: this is not \"where are you\", it is\n * \"are you somewhere that requires asking first\".\n *\n * ## What it will not do\n *\n * It never returns a country for a non-European zone. `America/Chicago` is\n * ninety-nine percent the United States and it is also `US`, `CA` and `MX`\n * territory in places — and the country is STORED on the consent record, where\n * a confident guess is worse than an absent value. So the answer for those is\n * \"not a prior-consent region, country unknown\", which is all the posture\n * needs and all this can honestly say.\n *\n * ⚠️ A VPN, a travelling laptop or a manually-set clock can all disagree with\n * the visitor's actual location. This ranks BELOW every header for that\n * reason, and the strict posture is still what an unrecognized zone gets.\n */\n\n/**\n * The IANA area prefixes that are never a prior-consent region.\n *\n * Listed positively rather than as \"anything that is not Europe/\": an unknown\n * or malformed zone must fall through to the strict posture, and a negative\n * test would hand it the permissive one.\n */\nconst NON_EUROPEAN_AREAS = [\n  'America/',\n  'Asia/',\n  'Australia/',\n  'Africa/',\n  'Pacific/',\n  'Antarctica/',\n  'US/',\n  'Canada/',\n  'Brazil/',\n  'Mexico/',\n  'Japan',\n  'Singapore',\n  'Hongkong',\n  'NZ',\n]\n\n/**\n * Zones inside a prior-consent country that do NOT start with `Europe/`.\n *\n * The EU's outermost regions and the EEA's islands are the reason this list\n * exists: the GDPR applies in Guadeloupe and the Canaries exactly as it does\n * in Paris and Madrid, and every one of them is filed by IANA under `America/`,\n * `Atlantic/` or `Indian/`. Matching on `Europe/` alone would place all of\n * them on the permissive side, which is the one direction this must never get\n * wrong.\n */\nconst PRIOR_CONSENT_NON_EUROPE_ZONES: Readonly<Record<string, string>> = {\n  'Atlantic/Canary': 'ES',\n  'Atlantic/Madeira': 'PT',\n  'Atlantic/Azores': 'PT',\n  'Atlantic/Reykjavik': 'IS',\n  'Atlantic/Faroe': 'DK',\n  'Atlantic/Jan_Mayen': 'NO',\n  'America/Cayenne': 'GF',\n  'America/Guadeloupe': 'GP',\n  'America/Martinique': 'MQ',\n  'America/Marigot': 'GP',\n  'America/St_Barthelemy': 'GP',\n  'Indian/Reunion': 'RE',\n  'Indian/Mayotte': 'YT',\n  'Arctic/Longyearbyen': 'NO',\n}\n\n/**\n * `Europe/<City>` zones whose country is NOT in the prior-consent set.\n *\n * The EEA is not the same shape as the continent. Without these, a visitor in\n * Moscow or Istanbul would be treated as a European one — harmless for the\n * consent posture, since it only makes it stricter, but it would store a\n * region claim that is simply untrue.\n */\nconst EUROPE_ZONES_OUTSIDE_THE_SET = [\n  'Europe/Moscow',\n  'Europe/Istanbul',\n  'Europe/Kiev',\n  'Europe/Kyiv',\n  'Europe/Minsk',\n  'Europe/Belgrade',\n  'Europe/Sarajevo',\n  'Europe/Skopje',\n  'Europe/Tirane',\n  'Europe/Podgorica',\n  'Europe/Chisinau',\n  'Europe/Volgograd',\n  'Europe/Samara',\n  'Europe/Kaliningrad',\n  'Europe/Simferopol',\n]\n\nexport interface TimeZoneGeoHint {\n  /**\n   * The country, when the zone identifies one honestly. `null` means \"not a\n   * prior-consent region, and this cannot say which country\" — a real answer\n   * for the posture, and the only truthful one for the record.\n   */\n  country: string | null\n  /** Whether this zone sits in a region that must be asked before tracking. */\n  priorConsent: boolean\n}\n\n/** The browser's IANA zone, or `''` where `Intl` cannot answer. */\nexport function readBrowserTimeZone(): string {\n  try {\n    return Intl.DateTimeFormat().resolvedOptions().timeZone || ''\n  } catch {\n    // Some locked-down and embedded runtimes throw rather than return.\n    return ''\n  }\n}\n\n/**\n * The region hint for an IANA zone, or `null` when it says nothing useful.\n *\n * `null` is the answer for an unknown zone, and callers must treat it exactly\n * as they treat a missing header: strictest posture. It is never a licence to\n * assume the permissive side.\n */\nexport function geoHintFromTimeZone(\n  timeZone: string | null | undefined,\n): TimeZoneGeoHint | null {\n  const zone = (timeZone ?? '').trim()\n  if (!zone) return null\n\n  const mapped = PRIOR_CONSENT_NON_EUROPE_ZONES[zone]\n  if (mapped) return { country: mapped, priorConsent: true }\n\n  if (zone.indexOf('Europe/') === 0) {\n    if (EUROPE_ZONES_OUTSIDE_THE_SET.indexOf(zone) >= 0) {\n      // Europe, but outside the EEA/UK/CH set. No country claim: the zone\n      // identifies a city, and several of these span more than one country.\n      return { country: null, priorConsent: false }\n    }\n    /*\n     * Prior consent, with no country named. The posture is all that is needed\n     * and it is all this can support — `Europe/Zurich` is Switzerland, but\n     * `Europe/Brussels` is also Luxembourg's zone in practice, and a stored\n     * country that is merely probable is worse than an absent one.\n     */\n    return { country: null, priorConsent: true }\n  }\n\n  for (const area of NON_EUROPEAN_AREAS) {\n    const matches = area.endsWith('/') ? zone.indexOf(area) === 0 : zone === area\n    if (matches) return { country: null, priorConsent: false }\n  }\n\n  // UTC, GMT, `Etc/*`, a fixed offset, or anything unrecognized. A visitor\n  // hiding their zone is not a visitor to assume the permissive side about.\n  return null\n}\n"],"names":["NON_EUROPEAN_AREAS","PRIOR_CONSENT_NON_EUROPE_ZONES","EUROPE_ZONES_OUTSIDE_THE_SET","readBrowserTimeZone","Intl","DateTimeFormat","resolvedOptions","timeZone","geoHintFromTimeZone","zone","trim","mapped","country","priorConsent","indexOf","area","matches","endsWith"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCC,GAED;;;;;;CAMC,GACD,MAAMA,qBAAqB;IACzB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED;;;;;;;;;CASC,GACD,MAAMC,iCAAmE;IACvE,mBAAmB;IACnB,oBAAoB;IACpB,mBAAmB;IACnB,sBAAsB;IACtB,kBAAkB;IAClB,sBAAsB;IACtB,mBAAmB;IACnB,sBAAsB;IACtB,sBAAsB;IACtB,mBAAmB;IACnB,yBAAyB;IACzB,kBAAkB;IAClB,kBAAkB;IAClB,uBAAuB;AACzB;AAEA;;;;;;;CAOC,GACD,MAAMC,+BAA+B;IACnC;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAaD,iEAAiE,GACjE,OAAO,SAASC;IACd,IAAI;QACF,OAAOC,KAAKC,cAAc,GAAGC,eAAe,GAAGC,QAAQ,IAAI;IAC7D,EAAE,eAAM;QACN,mEAAmE;QACnE,OAAO;IACT;AACF;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,oBACdD,QAAmC;IAEnC,MAAME,OAAO,CAACF,mBAAAA,WAAY,IAAIG,IAAI;IAClC,IAAI,CAACD,MAAM,OAAO;IAElB,MAAME,SAASV,8BAA8B,CAACQ,KAAK;IACnD,IAAIE,QAAQ,OAAO;QAAEC,SAASD;QAAQE,cAAc;IAAK;IAEzD,IAAIJ,KAAKK,OAAO,CAAC,eAAe,GAAG;QACjC,IAAIZ,6BAA6BY,OAAO,CAACL,SAAS,GAAG;YACnD,oEAAoE;YACpE,sEAAsE;YACtE,OAAO;gBAAEG,SAAS;gBAAMC,cAAc;YAAM;QAC9C;QACA;;;;;KAKC,GACD,OAAO;YAAED,SAAS;YAAMC,cAAc;QAAK;IAC7C;IAEA,KAAK,MAAME,QAAQf,mBAAoB;QACrC,MAAMgB,UAAUD,KAAKE,QAAQ,CAAC,OAAOR,KAAKK,OAAO,CAACC,UAAU,IAAIN,SAASM;QACzE,IAAIC,SAAS,OAAO;YAAEJ,SAAS;YAAMC,cAAc;QAAM;IAC3D;IAEA,yEAAyE;IACzE,0EAA0E;IAC1E,OAAO;AACT"}