@aglyn/aglyn 1.0.0-beta.219 → 1.0.0-beta.221

package/src/lib/app-utils/usage-budget.js

@@ -13,10 +13,7 @@
  * 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.
- */ // The ONE unit conversion between our provider bill and what a customer is
-// shown. Imported here so `publicOrgMonthlySpend` cannot grow a second copy of
-// it — see that function, and the module header of `assist-credits.ts`.
-import { assistCreditsFromUsd } from "./assist-credits.js";
+ */ import { pluginSpendLines } from "../plugin-manager/plugin-usage-axes.js";
 /**
  * Per-org USAGE BUDGETS, modelled on a Google Cloud billing budget (AGL-1528).
  *
@@ -43,9 +40,9 @@ import { assistCreditsFromUsd } from "./assist-credits.js";
  *   - **threshold rules** as percentages of the amount (default 50/90/100 —
  *     GCP's own default trio);
  *   - one alert per threshold per **month**, which is our budget period
- *     because every meter underneath it (`orgs/{id}/usage/{month}`,
- *     `assistUsage/{month}`, the counters' `YYYY-MM` fields) already resets
- *     monthly. A budget period the meters do not share would silently compare
+ *     because every meter underneath it (`orgs/{id}/usage/{month}`, each
+ *     plugin's spend-line document, the counters' `YYYY-MM` fields) already
+ *     resets monthly. A budget period the meters do not share would silently compare
  *     a month of spend against a quarter of budget.
  *
  * ## WHY THIS IS NOT THE STORAGE CAP, AND MUST NOT BECOME IT
@@ -193,229 +190,96 @@ export const BUDGET_THRESHOLD_MAX_PCT = 200;
     return crossed;
 }
 /**
- * Whether `month`'s invoice charges for Assist tokens.
+ * Whether `month`'s invoice charges for a line whose deployment variable
+ * holds `configuredStart`.
  *
  * Same START-MONTH shape and the same fail-closed posture as
  * `billsOrgLibraryStorage`, and for the identical reason: a boolean flipped
  * mid-period would retroactively bill a re-run of an earlier month at that
- * month's accumulated tokens. A start month cannot reach backwards.
+ * month's accumulated usage. A start month cannot reach backwards.
  *
- * `BILL_ASSIST_TOKENS_FROM=YYYY-MM`. Anything else — `true`, `1`, a date, a
- * typo — bills nothing.
- */ export function billsAssistTokens(month, configuredStart) {
+ * Anything but a `YYYY-MM` — `true`, `1`, a date, a typo — bills nothing.
+ */ export function billsFromMonth(month, configuredStart) {
     const start = String(configuredStart != null ? configuredStart : '').trim();
     if (!/^\d{4}-\d{2}$/.test(start)) return false;
     if (!/^\d{4}-\d{2}$/.test(month)) return false;
     return month >= start;
 }
+/** A positive finite dollar figure, or 0. */ function dollars(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
 /**
  * Builds the month's spend from figures already read elsewhere.
  *
  * `rollupMonth` is compared to `month` rather than trusted: see
- * {@link OrgSpendBreakdown.meteredFresh}.
+ * {@link OrgSpendBreakdown.meteredFresh}. Every declared spend line is
+ * reported, read as nothing when its document was not read.
  */ export function orgMonthlySpend(input) {
-    const { month, rollupBilledCents, rollupMonth, assistEstCostUsd } = input;
+    const { month, rollupBilledCents, rollupMonth } = input;
     const meteredFresh = Boolean(rollupMonth) && rollupMonth === month;
     const cents = Number(rollupBilledCents);
     const meteredUsd = meteredFresh && Number.isFinite(cents) && cents > 0 ? cents / 100 : 0;
-    const assistRaw = Number(assistEstCostUsd);
-    const assistUsd = Number.isFinite(assistRaw) && assistRaw > 0 ? assistRaw : 0;
-    const assistBilled = billsAssistTokens(month, input.assistBilledFrom);
+    const lines = pluginSpendLines().map((line)=>{
+        var _input_lineReadings, _input_env;
+        return {
+            id: line.id,
+            pluginId: line.pluginId,
+            label: line.label,
+            usd: dollars((_input_lineReadings = input.lineReadings) == null ? void 0 : _input_lineReadings[line.id]),
+            billed: billsFromMonth(month, (_input_env = input.env) == null ? void 0 : _input_env[line.billedFromEnv])
+        };
+    });
     return {
         meteredUsd,
-        assistUsd,
-        assistBilled,
-        totalUsd: meteredUsd + (assistBilled ? assistUsd : 0),
+        lines,
+        totalUsd: meteredUsd + lines.reduce((sum, line)=>sum + (line.billed ? line.usd : 0), 0),
         meteredFresh
     };
 }
+/** Dollars in a unit of cost, rounded UP — spend already made never reads as less. */ function unitsOf(usd, costUsd) {
+    if (!Number.isFinite(usd) || usd <= 0) return 0;
+    return Math.ceil(usd / costUsd);
+}
 /**
  * The projection that crosses the boundary to a customer's browser.
  *
- * `OrgSpendBreakdown.assistUsd` is `orgs/{id}/assistUsage/{month}.estCostUsd`
- * verbatim — our provider bill at the serving model's list rates, not a price
+ * A line declared with a `unit` stores the platform's own cost — for the AI
+ * plugin, its provider bill at the serving model's list rates, not a price
  * and not a rate the platform publishes. Serving it to an org-scoped caller
- * puts our model choice, our per-token rates and our margin on a billing page,
- * which is the boundary `publicAssistCredits` and `publicAssistQuota` already
- * exist to hold on the assist routes. This is the same boundary, one route
- * over, and it was the last place the dollar figure still crossed it.
- *
- * `assistCreditsFromUsd` is the ONE conversion between the two units, so this
- * cannot come to disagree with the credits meter about the same month's
- * consumption.
+ * would put a model choice, per-token rates and a margin on a billing page,
+ * so such a line crosses in its unit only, through the same rounding-up
+ * conversion the plugin's own meter uses, and its dollars never do.
  *
  * `meteredUsd` and `totalUsd` stay dollars: `billedCents` is what an invoice
- * charges, which is the customer's own money and the whole subject of a budget.
+ * charges, which is the customer's own money and the whole subject of a
+ * budget.
  *
- * The two units are deliberately not summed. A budget is a dollar rule, credits
- * are not dollars, and folding one into the other would republish the cost the
- * conversion just removed.
+ * Units and dollars are deliberately not summed. A budget is a dollar rule,
+ * a unit is not a dollar, and folding one into the other would republish the
+ * cost the conversion just removed.
  */ export function publicOrgMonthlySpend(spend) {
+    const declared = new Map(pluginSpendLines().map((line)=>[
+            line.id,
+            line
+        ]));
     return {
         meteredUsd: spend.meteredUsd,
-        assistCredits: assistCreditsFromUsd(spend.assistUsd),
+        lines: spend.lines.map((line)=>{
+            var _declared_get;
+            const unit = (_declared_get = declared.get(line.id)) == null ? void 0 : _declared_get.unit;
+            return {
+                id: line.id,
+                label: line.label,
+                billed: line.billed,
+                units: unit ? unitsOf(line.usd, unit.costUsd) : null,
+                unitLabel: unit ? unit.label : null,
+                usd: unit ? null : line.usd
+            };
+        }),
         totalUsd: spend.totalUsd,
-        assistBilled: spend.assistBilled,
         meteredFresh: spend.meteredFresh
     };
 }
-/**
- * The MARGIN GUARD (the other half of the ask, and the live half).
- *
- * A customer budget protects the customer. This protects us, from the one
- * meter on the platform whose unit cost is real money paid to a third party
- * and whose ceiling is a message count rather than a dollar figure:
- * `assistEntitledMonthlyLimit` caps an entitled org at 1,000 MESSAGES a
- * month, and a thousand long, cache-cold Opus-class exchanges is a
- * three-figure bill against a subscription that did not move.
- *
- * So one org's Assist COGS crossing this threshold notifies STAFF, not the
- * customer — the customer is not being charged and has done nothing wrong.
- * Returns the threshold crossed, or 0.
- *
- * `ASSIST_ORG_MONTHLY_COGS_ALERT_USD` overrides the default and FAILS TO THE
- * DEFAULT: a blank or malformed value that disabled the guard would be
- * another alert that cannot fire.
- */ export const ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT = 25;
-export function assistCogsAlertThresholdUsd(configured) {
-    const parsed = Number(String(configured != null ? configured : '').trim());
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-        return ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT;
-    }
-    return parsed;
-}
-/**
- * The repo default spend ceiling: **$40 per org per month** (AGL-2264).
- *
- * The number is arithmetic rather than pricing. After AGL-2441 the
- * 1,000-message entitled guard bounds roughly $28/org/month of worst-case
- * spend at Sonnet, and the staff margin alert already fires at $25. $40
- * therefore sits ABOVE anything the message cap can produce at the current
- * model, so it changes no charged amount and no plan's behaviour — it is a
- * ceiling on OUR cost, not a customer price, which is why it is outside the
- * Sept-1 pricing lock. It binds only when an assumption behind that
- * arithmetic has moved: an `ASSIST_MODEL` swap to an Opus-class tier, a
- * longer prompt, or a caller finding another way to inflate input. That is
- * the failure it exists for.
- *
- * It ships as a DEFAULT rather than as an environment variable someone must
- * remember, because an unset ceiling is the fail-open this issue was opened
- * about: a fresh deployment and a self-hoster both inherit a sane bound
- * without knowing the variable exists.
- *
- * The free tier gets no separate figure and needs none — its 10 messages a
- * UTC day bound it at roughly $0.28/day, so this is a backstop it cannot
- * reach rather than a cap it runs into.
- *
- * ⚠️ It applies only to an org whose plan sells NO assist band. Agency and
- * Enterprise include more assist than $40 of spend, so the meter's
- * `assistMonthlyCeilingUsd` keeps this default off every plan that sells a
- * band — see there for which figure binds when.
- */ export const ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD = 40;
-/**
- * The per-org monthly PROVIDER-SPEND ceiling in USD — the dollar half of
- * the cap (AGL-2264), from `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD` as the caller
- * read it. Defaults to {@link ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD};
- * `off` removes it.
- *
- * Pure over the configured value, like {@link assistCogsAlertThresholdUsd}:
- * the meter that refuses at the ceiling and the cron that announces the
- * refusal read the one variable and must agree on what it means.
- *
- * The meter's message caps bound spend only through an assumed cost per
- * message, and that assumption is exactly what drifts: `ASSIST_MODEL` is an
- * env override, prompts grow, and a client controls how much history it
- * posts. The ceiling is measured against the real figure instead: the
- * running `estCostUsd` on the month's assist usage document, which the meter
- * increments at the SERVING model's rates. So it bounds the actual bill
- * rather than a forecast of it.
- *
- * The refusal is deliberately the same shape as the message refusal (a
- * reservation that did not move the counter), so an org at the ceiling
- * spends nothing at all rather than spending less. It refuses — it does
- * NOT quietly swap to a cheaper model. A silent quality drop is worse than
- * an honest stop, because nobody can tell it happened.
- *
- * ⚠️ **Fails to the DEFAULT, never to “no ceiling”.** An empty, negative or
- * unparseable value reads as unconfigured and takes the repo default, so a
- * typo cannot reopen the fail-open this exists to close. It cannot become a
- * ceiling of `$0` either — a value of zero is not “refuse everyone”, it is
- * “not a number I will honour” — because an outage across every workspace
- * would be worse than the overspend being guarded.
- *
- * Removing the ceiling therefore takes a WORD rather than a number:
- * `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD=off`. A deployment paying its own
- * provider bill may genuinely want none, and that is a decision someone
- * should have to write down rather than reach by mistyping a digit.
- */ export function assistOrgMonthlyCostLimitUsd(configured) {
-    const operator = assistOperatorCeilingUsd(configured);
-    return operator === undefined ? ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD : operator;
-}
-/**
- * The operator's ceiling exactly as CONFIGURED — three states, not two:
- * a number, `null` for the word `off`, and `undefined` for unset or
- * unparseable.
- *
- * `assistOrgMonthlyCostLimitUsd` collapses `undefined` onto the repo default
- * and is the reading every existing caller wants. The composition with a
- * plan's own band needs the third state, because "the operator wrote a
- * number" and "nobody configured anything" have to bind differently against a
- * band that was sold: an operator's figure is a decision, and the repo
- * default is a backstop for orgs that have no band of their own.
- */ export function assistOperatorCeilingUsd(configured) {
-    const raw = String(configured != null ? configured : '').trim();
-    if (raw === '') return undefined;
-    if (raw.toLowerCase() === 'off') return null;
-    const parsed = Number(raw);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-/**
- * Whether this org's Assist spend has newly crossed the margin threshold.
- *
- * Dedupes through the same guard shape and the same month semantics as the
- * customer budget, under its own key, so a staff alert and a customer alert
- * can never suppress one another.
- */ export function assistMarginBreach(input) {
-    var _ref;
-    const { assistUsd, thresholdUsd, guard, month } = input;
-    if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return false;
-    if (thresholdUsd <= 0 || assistUsd < thresholdUsd) return false;
-    // The guard records how many WHOLE multiples of the threshold have been
-    // announced, so an org at 1x is announced once and an org that climbs to 2x
-    // is announced again — an escalating cost must not go quiet because it
-    // already spoke.
-    const multiple = Math.floor(assistUsd / thresholdUsd);
-    if ((guard == null ? void 0 : guard.month) === month && Number((_ref = guard == null ? void 0 : guard.threshold) != null ? _ref : 0) >= multiple) {
-        return false;
-    }
-    return true;
-}
-/**
- * Whether this org has newly crossed the HARD spend ceiling — the one that
- * refuses (AGL-2264), as distinct from {@link assistMarginBreach}'s review
- * threshold, which only warns.
- *
- * It needs its own guard and its own announcement because the margin alert
- * cannot carry this news. That alert speaks in WHOLE MULTIPLES of its $25
- * threshold, so an org that climbs from $25 to the $40 ceiling is still at
- * 1x and stays silent — staff would learn that the assistant had stopped
- * answering for a customer only when someone complained. A ceiling that
- * refuses quietly is the same defect as a ceiling that does not refuse.
- *
- * Once per org per month: crossing is a state, not an escalating figure, and
- * the org is refused from here to the month boundary regardless of how far
- * past it the recorded spend sits.
- */ export function assistCeilingBreach(input) {
-    const { assistUsd, ceilingUsd, guard, month } = input;
-    if (ceilingUsd === null) return false;
-    if (!Number.isFinite(assistUsd) || !Number.isFinite(ceilingUsd)) return false;
-    if (ceilingUsd <= 0 || assistUsd < ceilingUsd) return false;
-    return (guard == null ? void 0 : guard.month) !== month;
-}
-/** The multiple {@link assistMarginBreach} would record. */ export function assistMarginMultiple(assistUsd, thresholdUsd) {
-    if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return 0;
-    if (thresholdUsd <= 0) return 0;
-    return Math.max(0, Math.floor(assistUsd / thresholdUsd));
-}
 
 //# sourceMappingURL=usage-budget.js.map

package/src/lib/app-utils/usage-budget.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/usage-budget.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// The ONE unit conversion between our provider bill and what a customer is\n// shown. Imported here so `publicOrgMonthlySpend` cannot grow a second copy of\n// it — see that function, and the module header of `assist-credits.ts`.\nimport { assistCreditsFromUsd } from './assist-credits'\n\n/**\n * Per-org USAGE BUDGETS, modelled on a Google Cloud billing budget (AGL-1528).\n *\n * ## the directive, 2026-08-18, verbatim\n *\n *   \"*our usage metering, usage alerts, budgets for usage alerts, similar to\n *   how google cloud charges*\"\n *\n * and, on the org-library storage decision the same day: bill from today\n * \"*but with overage protection + usage alerts, so customers don't get a\n * surprise bill*\".\n *\n * ## What a GCP billing budget actually is, and what this copies\n *\n * A GCP budget is **an amount plus a set of percentage alert rules**. It is\n * not a cap: crossing 100% of a budget stops nothing, it sends the email that\n * makes the bill stop being a surprise. Each rule fires **once per budget\n * period per rule** — the console shows the budget and its progress, and the\n * same rules push mail.\n *\n * This module is that shape, and only that shape:\n *\n *   - an **amount** (`amountUsd`), chosen by the customer;\n *   - **threshold rules** as percentages of the amount (default 50/90/100 —\n *     GCP's own default trio);\n *   - one alert per threshold per **month**, which is our budget period\n *     because every meter underneath it (`orgs/{id}/usage/{month}`,\n *     `assistUsage/{month}`, the counters' `YYYY-MM` fields) already resets\n *     monthly. A budget period the meters do not share would silently compare\n *     a month of spend against a quarter of budget.\n *\n * ## WHY THIS IS NOT THE STORAGE CAP, AND MUST NOT BECOME IT\n *\n * `utils/storage-overage.ts` owns the customer's optional **hard cap**: past\n * it uploads are refused. That is a wall, it is off by default, and it exists\n * because the requirement was for a control \"*by the end user*\".\n *\n * A budget is the OTHER half and the softer one — it never refuses anything.\n * The distinction is load-bearing in both directions: a budget that quietly\n * became a cap would take a customer's site down to save them $2 (the failure\n * mode AGL-1529 rejected on arrival), and a cap with no budget beneath it\n * means the only warning a customer gets is the refusal itself.\n *\n * ## WHY DOLLARS AND NOT PERCENT-OF-QUOTA\n *\n * `usage-alerts` has warned at 80%/100% of individual QUOTAS since AGL-276 —\n * sites, media storage, email sends, bandwidth. Those answer \"am I near a\n * band\". They cannot answer \"what will I owe\", which is the question a\n * metered customer actually has, and no sum of per-quota percentages produces\n * it: an org at 60% of four different bands may owe nothing at all, and an\n * org at 101% of one band may owe $40. Dollars are the customer's unit.\n *\n * ## THE SPEND FIGURE IS READ, NEVER RE-DERIVED\n *\n * `report-usage` already computes `billedCents` daily onto\n * `orgs/{orgId}/usage/{month}` — metered infra excess at cost x 1.3, plus the\n * data, API and contacts overages. That document is the invoice's own\n * arithmetic, and this module takes it verbatim.\n *\n * A second aggregation here is the specific mistake AGL-1371 exists about:\n * the console meter and the warning email each summed their own figures and\n * disagreed by up to `hostLimit`x. A budget alert quoting a number the\n * invoice will not show is worse than no budget alert, because it is believed.\n */\n\n/** GCP's own default budget alert rules, and the same three here. */\nexport const DEFAULT_BUDGET_THRESHOLD_PCTS: readonly number[] = [50, 90, 100]\n\n/** Bounds on the amount a self-serve org may set as its own budget. */\nexport const BUDGET_MIN_USD = 1\nexport const BUDGET_MAX_USD = 100_000\n\n/**\n * Bounds on a threshold rule, as a percentage of the amount.\n *\n * The ceiling is 200 rather than 100 because GCP allows rules above the\n * budget and they are the useful ones on a runaway: an org that set $20 and\n * is at $45 wants to hear about 200%, and a ladder that stops at 100 says\n * exactly as much at $45 as it did at $20.\n */\nexport const BUDGET_THRESHOLD_MIN_PCT = 1\nexport const BUDGET_THRESHOLD_MAX_PCT = 200\n/** At most this many rules, so one org cannot mail its admins 40 times. */\nexport const BUDGET_MAX_THRESHOLDS = 6\n\n/** The guard key this budget dedupes under, inside `orgs/{id}.usageAlerts`. */\nexport const BUDGET_GUARD_KEY = 'budget'\n\nexport interface UsageBudget {\n  /** Whether the customer has set a budget at all. Absent by default. */\n  budgetSet: boolean\n  /** The amount in USD, or `null` when no budget is set. */\n  amountUsd: number | null\n  /**\n   * Threshold rules as percentages, ascending and deduplicated. Always the\n   * default trio when a budget exists but named no rules — a budget with an\n   * empty rule set is a budget that cannot alert, which is the defect this\n   * whole file exists to remove.\n   */\n  thresholdPcts: number[]\n}\n\n/**\n * Coerces whatever is stored (or posted) into a usable ascending rule set.\n *\n * FAILS TO THE DEFAULT, never to empty. Every rejection path here — a blank,\n * a string, a negative, a duplicate, an over-long list — lands on\n * {@link DEFAULT_BUDGET_THRESHOLD_PCTS} rather than on `[]`, because an empty\n * ladder is silence that reads as coverage.\n */\nexport function normalizeBudgetThresholds(\n  input: unknown,\n): number[] {\n  const list = Array.isArray(input) ? input : []\n  const cleaned = [\n    ...new Set(\n      list\n        .map((entry) => Math.round(Number(entry)))\n        .filter(\n          (pct) =>\n            Number.isFinite(pct) &&\n            pct >= BUDGET_THRESHOLD_MIN_PCT &&\n            pct <= BUDGET_THRESHOLD_MAX_PCT,\n        ),\n    ),\n  ].sort((a, b) => a - b)\n  if (!cleaned.length) return [...DEFAULT_BUDGET_THRESHOLD_PCTS]\n  return cleaned.slice(0, BUDGET_MAX_THRESHOLDS)\n}\n\n/**\n * The budget this org has in force, from its raw org document.\n *\n * `null` amount means no budget — deliberately `null` rather than `Infinity`,\n * matching `resolveStorageCap`: the value is serialised into the budget\n * route's JSON and `JSON.stringify(Infinity)` is `null` anyway, so one\n * spelling for \"no budget\" on both sides of the wire.\n *\n * An amount that is present but unusable (blank, negative, `NaN`) reads as NO\n * budget, which is the opposite of how `resolveStorageCap` treats a corrupt\n * CAP — and deliberately so. A corrupt cap must fall back to a low ceiling\n * because failing open there bills someone who asked not to be billed. A\n * budget refuses nothing, so the only cost of failing open is a missing\n * warning, whereas inventing an amount nobody typed produces alerts about a\n * number the customer never chose.\n */\nexport function resolveUsageBudget(\n  org: Record<string, unknown> | null | undefined,\n): UsageBudget {\n  const raw = (org as any)?.usageBudget\n  const amount = Number(raw?.amountUsd)\n  if (!raw || !Number.isFinite(amount) || amount <= 0) {\n    return { budgetSet: false, amountUsd: null, thresholdPcts: [...DEFAULT_BUDGET_THRESHOLD_PCTS] }\n  }\n  return {\n    budgetSet: true,\n    amountUsd: amount,\n    thresholdPcts: normalizeBudgetThresholds(raw?.thresholdPcts),\n  }\n}\n\n/**\n * The HIGHEST rule this spend has crossed, or 0 for none.\n *\n * Highest rather than all-of-them because the dedupe guard stores one number\n * per key (the shape `usage-alerts` has used since AGL-276), and because an\n * org that goes from $0 to $80 against a $50 budget between two cron ticks\n * wants one email saying 160%, not three saying 50, 90 and 100. GCP behaves\n * the same way — the rules are notification points on one number, not a queue.\n */\nexport function budgetThresholdCrossed(\n  spendUsd: number,\n  budget: UsageBudget,\n): number {\n  if (!budget.budgetSet || budget.amountUsd == null) return 0\n  if (!Number.isFinite(budget.amountUsd) || budget.amountUsd <= 0) return 0\n  if (!Number.isFinite(spendUsd) || spendUsd <= 0) return 0\n  const pct = (spendUsd / budget.amountUsd) * 100\n  let crossed = 0\n  for (const rule of budget.thresholdPcts) {\n    if (pct >= rule && rule > crossed) crossed = rule\n  }\n  return crossed\n}\n\n/** One entry of `orgs/{orgId}.usageAlerts` — the existing guard shape. */\nexport interface UsageAlertGuard {\n  month?: string\n  threshold?: number\n}\n\n/**\n * The rule to alert on RIGHT NOW, or 0 for silence.\n *\n * This is the whole of the idempotency requirement and it is one expression,\n * so a caller cannot implement half of it:\n *\n *   - nothing crossed -> silent;\n *   - crossed, but a guard from THIS month already recorded that rule or a\n *     higher one -> silent. A cron that ticks hourly must not mail hourly.\n *   - crossed, and the guard is from a PREVIOUS month -> alert. The budget\n *     period rolled over, and a customer who exceeded last month's budget\n *     must hear about this month's too.\n *\n * The comparison is `>=` on purpose: after alerting at 100 an org that climbs\n * to 200 alerts again (200 > 100), and an org that stays at 100 does not.\n */\nexport function budgetAlertDue(input: {\n  spendUsd: number\n  budget: UsageBudget\n  guard: UsageAlertGuard | null | undefined\n  month: string\n}): number {\n  const { spendUsd, budget, guard, month } = input\n  const crossed = budgetThresholdCrossed(spendUsd, budget)\n  if (!crossed) return 0\n  if (guard?.month === month && Number(guard?.threshold ?? 0) >= crossed) {\n    return 0\n  }\n  return crossed\n}\n\n/**\n * What an org is spending this month, split by where it comes from.\n *\n * Every field is a figure some other module already owns; nothing here is\n * re-derived (see the header). The split exists because a budget alert that\n * says only \"$62\" invites a support ticket asking what the $62 was.\n */\nexport interface OrgSpendBreakdown {\n  /**\n   * Metered infrastructure + plan-priced overages, from the invoice's own\n   * `billedCents`. This is the part that reaches a Stripe invoice.\n   */\n  meteredUsd: number\n  /**\n   * Aglyn Assist token spend for the month, at the serving model's list\n   * rates (`orgs/{id}/assistUsage/{month}.estCostUsd`).\n   *\n   * ALWAYS REPORTED, and counted toward the budget only when\n   * {@link billsAssistTokens} says this month invoices for it — which today\n   * it does not, because Assist is a plan ENTITLEMENT (`aiAssist: true`) with\n   * no per-token price anywhere in the platform. Adding it to a customer's\n   * \"you will owe\" figure would be a surprise bill invented by a\n   * notification, which is precisely the thing this feature exists to stop.\n   *\n   * It is nonetheless carried here rather than left out, for two reasons that\n   * both bite: the day Assist is priced this is a one-line switch instead of\n   * a new pipeline, and — live today — {@link assistMarginBreach} reads this\n   * same number as OUR cost, which is the margin-guard half of the job.\n   */\n  assistUsd: number\n  /** What counts against the budget: metered, plus assist when it bills. */\n  totalUsd: number\n  /** Whether `assistUsd` entered `totalUsd`. */\n  assistBilled: boolean\n  /**\n   * FALSE when no rollup exists for this month yet, so `meteredUsd` is 0\n   * because nothing has been computed rather than because nothing was spent.\n   *\n   * The distinction is the difference between a quiet budget and a broken\n   * one, and it is not theoretical: `usage-alerts` reads the LATEST usage\n   * rollup by `computedAt`, which on the first days of a month is still LAST\n   * month's document. Alerting from that would compare August's budget\n   * against July's spend; suppressing the alert without recording why would\n   * make a budget that never fires look like a budget that never needed to.\n   */\n  meteredFresh: boolean\n}\n\n/**\n * Whether `month`'s invoice charges for Assist tokens.\n *\n * Same START-MONTH shape and the same fail-closed posture as\n * `billsOrgLibraryStorage`, and for the identical reason: a boolean flipped\n * mid-period would retroactively bill a re-run of an earlier month at that\n * month's accumulated tokens. A start month cannot reach backwards.\n *\n * `BILL_ASSIST_TOKENS_FROM=YYYY-MM`. Anything else — `true`, `1`, a date, a\n * typo — bills nothing.\n */\nexport function billsAssistTokens(\n  month: string,\n  configuredStart: string | null | undefined,\n): boolean {\n  const start = String(configuredStart ?? '').trim()\n  if (!/^\\d{4}-\\d{2}$/.test(start)) return false\n  if (!/^\\d{4}-\\d{2}$/.test(month)) return false\n  return month >= start\n}\n\n/**\n * Builds the month's spend from figures already read elsewhere.\n *\n * `rollupMonth` is compared to `month` rather than trusted: see\n * {@link OrgSpendBreakdown.meteredFresh}.\n */\nexport function orgMonthlySpend(input: {\n  month: string\n  /** `billedCents` off the latest `orgs/{id}/usage/*` document. */\n  rollupBilledCents: number | null | undefined\n  /** The `month` field of that same document. */\n  rollupMonth: string | null | undefined\n  /** `estCostUsd` off `orgs/{id}/assistUsage/{month}`. */\n  assistEstCostUsd: number | null | undefined\n  /** `BILL_ASSIST_TOKENS_FROM`, verbatim. */\n  assistBilledFrom?: string | null\n}): OrgSpendBreakdown {\n  const { month, rollupBilledCents, rollupMonth, assistEstCostUsd } = input\n  const meteredFresh = Boolean(rollupMonth) && rollupMonth === month\n  const cents = Number(rollupBilledCents)\n  const meteredUsd =\n    meteredFresh && Number.isFinite(cents) && cents > 0 ? cents / 100 : 0\n  const assistRaw = Number(assistEstCostUsd)\n  const assistUsd = Number.isFinite(assistRaw) && assistRaw > 0 ? assistRaw : 0\n  const assistBilled = billsAssistTokens(month, input.assistBilledFrom)\n  return {\n    meteredUsd,\n    assistUsd,\n    assistBilled,\n    totalUsd: meteredUsd + (assistBilled ? assistUsd : 0),\n    meteredFresh,\n  }\n}\n\n/**\n * The customer-facing half of {@link OrgSpendBreakdown} — dollars the customer\n * is charged, and Assist consumption in CREDITS.\n */\nexport interface PublicOrgSpend {\n  /** Metered infrastructure and plan overages, from the invoice's own figure. */\n  meteredUsd: number\n  /**\n   * Assist consumption this month, in credits. The stored figure is\n   * `estCostUsd` — our provider bill — and a credit is the unit that expresses\n   * it without publishing it.\n   */\n  assistCredits: number\n  /** What counts against the budget. */\n  totalUsd: number\n  /** Whether Assist consumption entered `totalUsd`. */\n  assistBilled: boolean\n  meteredFresh: boolean\n}\n\n/**\n * The projection that crosses the boundary to a customer's browser.\n *\n * `OrgSpendBreakdown.assistUsd` is `orgs/{id}/assistUsage/{month}.estCostUsd`\n * verbatim — our provider bill at the serving model's list rates, not a price\n * and not a rate the platform publishes. Serving it to an org-scoped caller\n * puts our model choice, our per-token rates and our margin on a billing page,\n * which is the boundary `publicAssistCredits` and `publicAssistQuota` already\n * exist to hold on the assist routes. This is the same boundary, one route\n * over, and it was the last place the dollar figure still crossed it.\n *\n * `assistCreditsFromUsd` is the ONE conversion between the two units, so this\n * cannot come to disagree with the credits meter about the same month's\n * consumption.\n *\n * `meteredUsd` and `totalUsd` stay dollars: `billedCents` is what an invoice\n * charges, which is the customer's own money and the whole subject of a budget.\n *\n * The two units are deliberately not summed. A budget is a dollar rule, credits\n * are not dollars, and folding one into the other would republish the cost the\n * conversion just removed.\n */\nexport function publicOrgMonthlySpend(spend: OrgSpendBreakdown): PublicOrgSpend {\n  return {\n    meteredUsd: spend.meteredUsd,\n    assistCredits: assistCreditsFromUsd(spend.assistUsd),\n    totalUsd: spend.totalUsd,\n    assistBilled: spend.assistBilled,\n    meteredFresh: spend.meteredFresh,\n  }\n}\n\n/**\n * The MARGIN GUARD (the other half of the ask, and the live half).\n *\n * A customer budget protects the customer. This protects us, from the one\n * meter on the platform whose unit cost is real money paid to a third party\n * and whose ceiling is a message count rather than a dollar figure:\n * `assistEntitledMonthlyLimit` caps an entitled org at 1,000 MESSAGES a\n * month, and a thousand long, cache-cold Opus-class exchanges is a\n * three-figure bill against a subscription that did not move.\n *\n * So one org's Assist COGS crossing this threshold notifies STAFF, not the\n * customer — the customer is not being charged and has done nothing wrong.\n * Returns the threshold crossed, or 0.\n *\n * `ASSIST_ORG_MONTHLY_COGS_ALERT_USD` overrides the default and FAILS TO THE\n * DEFAULT: a blank or malformed value that disabled the guard would be\n * another alert that cannot fire.\n */\nexport const ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT = 25\n\nexport function assistCogsAlertThresholdUsd(\n  configured?: string | null,\n): number {\n  const parsed = Number(String(configured ?? '').trim())\n  if (!Number.isFinite(parsed) || parsed <= 0) {\n    return ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT\n  }\n  return parsed\n}\n\n/**\n * The repo default spend ceiling: **$40 per org per month** (AGL-2264).\n *\n * The number is arithmetic rather than pricing. After AGL-2441 the\n * 1,000-message entitled guard bounds roughly $28/org/month of worst-case\n * spend at Sonnet, and the staff margin alert already fires at $25. $40\n * therefore sits ABOVE anything the message cap can produce at the current\n * model, so it changes no charged amount and no plan's behaviour — it is a\n * ceiling on OUR cost, not a customer price, which is why it is outside the\n * Sept-1 pricing lock. It binds only when an assumption behind that\n * arithmetic has moved: an `ASSIST_MODEL` swap to an Opus-class tier, a\n * longer prompt, or a caller finding another way to inflate input. That is\n * the failure it exists for.\n *\n * It ships as a DEFAULT rather than as an environment variable someone must\n * remember, because an unset ceiling is the fail-open this issue was opened\n * about: a fresh deployment and a self-hoster both inherit a sane bound\n * without knowing the variable exists.\n *\n * The free tier gets no separate figure and needs none — its 10 messages a\n * UTC day bound it at roughly $0.28/day, so this is a backstop it cannot\n * reach rather than a cap it runs into.\n *\n * ⚠️ It applies only to an org whose plan sells NO assist band. Agency and\n * Enterprise include more assist than $40 of spend, so the meter's\n * `assistMonthlyCeilingUsd` keeps this default off every plan that sells a\n * band — see there for which figure binds when.\n */\nexport const ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD = 40\n\n/**\n * The per-org monthly PROVIDER-SPEND ceiling in USD — the dollar half of\n * the cap (AGL-2264), from `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD` as the caller\n * read it. Defaults to {@link ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD};\n * `off` removes it.\n *\n * Pure over the configured value, like {@link assistCogsAlertThresholdUsd}:\n * the meter that refuses at the ceiling and the cron that announces the\n * refusal read the one variable and must agree on what it means.\n *\n * The meter's message caps bound spend only through an assumed cost per\n * message, and that assumption is exactly what drifts: `ASSIST_MODEL` is an\n * env override, prompts grow, and a client controls how much history it\n * posts. The ceiling is measured against the real figure instead: the\n * running `estCostUsd` on the month's assist usage document, which the meter\n * increments at the SERVING model's rates. So it bounds the actual bill\n * rather than a forecast of it.\n *\n * The refusal is deliberately the same shape as the message refusal (a\n * reservation that did not move the counter), so an org at the ceiling\n * spends nothing at all rather than spending less. It refuses — it does\n * NOT quietly swap to a cheaper model. A silent quality drop is worse than\n * an honest stop, because nobody can tell it happened.\n *\n * ⚠️ **Fails to the DEFAULT, never to “no ceiling”.** An empty, negative or\n * unparseable value reads as unconfigured and takes the repo default, so a\n * typo cannot reopen the fail-open this exists to close. It cannot become a\n * ceiling of `$0` either — a value of zero is not “refuse everyone”, it is\n * “not a number I will honour” — because an outage across every workspace\n * would be worse than the overspend being guarded.\n *\n * Removing the ceiling therefore takes a WORD rather than a number:\n * `ASSIST_ORG_MONTHLY_COGS_LIMIT_USD=off`. A deployment paying its own\n * provider bill may genuinely want none, and that is a decision someone\n * should have to write down rather than reach by mistyping a digit.\n */\nexport function assistOrgMonthlyCostLimitUsd(\n  configured?: string | null,\n): number | null {\n  const operator = assistOperatorCeilingUsd(configured)\n  return operator === undefined\n    ? ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD\n    : operator\n}\n\n/**\n * The operator's ceiling exactly as CONFIGURED — three states, not two:\n * a number, `null` for the word `off`, and `undefined` for unset or\n * unparseable.\n *\n * `assistOrgMonthlyCostLimitUsd` collapses `undefined` onto the repo default\n * and is the reading every existing caller wants. The composition with a\n * plan's own band needs the third state, because \"the operator wrote a\n * number\" and \"nobody configured anything\" have to bind differently against a\n * band that was sold: an operator's figure is a decision, and the repo\n * default is a backstop for orgs that have no band of their own.\n */\nexport function assistOperatorCeilingUsd(\n  configured?: string | null,\n): number | null | undefined {\n  const raw = String(configured ?? '').trim()\n  if (raw === '') return undefined\n  if (raw.toLowerCase() === 'off') return null\n  const parsed = Number(raw)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined\n}\n\n/**\n * Whether this org's Assist spend has newly crossed the margin threshold.\n *\n * Dedupes through the same guard shape and the same month semantics as the\n * customer budget, under its own key, so a staff alert and a customer alert\n * can never suppress one another.\n */\nexport function assistMarginBreach(input: {\n  assistUsd: number\n  thresholdUsd: number\n  guard: UsageAlertGuard | null | undefined\n  month: string\n}): boolean {\n  const { assistUsd, thresholdUsd, guard, month } = input\n  if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return false\n  if (thresholdUsd <= 0 || assistUsd < thresholdUsd) return false\n  // The guard records how many WHOLE multiples of the threshold have been\n  // announced, so an org at 1x is announced once and an org that climbs to 2x\n  // is announced again — an escalating cost must not go quiet because it\n  // already spoke.\n  const multiple = Math.floor(assistUsd / thresholdUsd)\n  if (guard?.month === month && Number(guard?.threshold ?? 0) >= multiple) {\n    return false\n  }\n  return true\n}\n\n/**\n * Whether this org has newly crossed the HARD spend ceiling — the one that\n * refuses (AGL-2264), as distinct from {@link assistMarginBreach}'s review\n * threshold, which only warns.\n *\n * It needs its own guard and its own announcement because the margin alert\n * cannot carry this news. That alert speaks in WHOLE MULTIPLES of its $25\n * threshold, so an org that climbs from $25 to the $40 ceiling is still at\n * 1x and stays silent — staff would learn that the assistant had stopped\n * answering for a customer only when someone complained. A ceiling that\n * refuses quietly is the same defect as a ceiling that does not refuse.\n *\n * Once per org per month: crossing is a state, not an escalating figure, and\n * the org is refused from here to the month boundary regardless of how far\n * past it the recorded spend sits.\n */\nexport function assistCeilingBreach(input: {\n  assistUsd: number\n  ceilingUsd: number | null\n  guard: UsageAlertGuard | null | undefined\n  month: string\n}): boolean {\n  const { assistUsd, ceilingUsd, guard, month } = input\n  if (ceilingUsd === null) return false\n  if (!Number.isFinite(assistUsd) || !Number.isFinite(ceilingUsd)) return false\n  if (ceilingUsd <= 0 || assistUsd < ceilingUsd) return false\n  return guard?.month !== month\n}\n\n/** The multiple {@link assistMarginBreach} would record. */\nexport function assistMarginMultiple(\n  assistUsd: number,\n  thresholdUsd: number,\n): number {\n  if (!Number.isFinite(assistUsd) || !Number.isFinite(thresholdUsd)) return 0\n  if (thresholdUsd <= 0) return 0\n  return Math.max(0, Math.floor(assistUsd / thresholdUsd))\n}\n"],"names":["assistCreditsFromUsd","DEFAULT_BUDGET_THRESHOLD_PCTS","BUDGET_MIN_USD","BUDGET_MAX_USD","BUDGET_THRESHOLD_MIN_PCT","BUDGET_THRESHOLD_MAX_PCT","BUDGET_MAX_THRESHOLDS","BUDGET_GUARD_KEY","normalizeBudgetThresholds","input","list","Array","isArray","cleaned","Set","map","entry","Math","round","Number","filter","pct","isFinite","sort","a","b","length","slice","resolveUsageBudget","org","raw","usageBudget","amount","amountUsd","budgetSet","thresholdPcts","budgetThresholdCrossed","spendUsd","budget","crossed","rule","budgetAlertDue","guard","month","threshold","billsAssistTokens","configuredStart","start","String","trim","test","orgMonthlySpend","rollupBilledCents","rollupMonth","assistEstCostUsd","meteredFresh","Boolean","cents","meteredUsd","assistRaw","assistUsd","assistBilled","assistBilledFrom","totalUsd","publicOrgMonthlySpend","spend","assistCredits","ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT","assistCogsAlertThresholdUsd","configured","parsed","ASSIST_ORG_MONTHLY_COGS_LIMIT_DEFAULT_USD","assistOrgMonthlyCostLimitUsd","operator","assistOperatorCeilingUsd","undefined","toLowerCase","assistMarginBreach","thresholdUsd","multiple","floor","assistCeilingBreach","ceilingUsd","assistMarginMultiple","max"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/usage-budget.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  pluginSpendLines,\n  type ResolvedPluginSpendLine,\n} from '../plugin-manager/plugin-usage-axes'\n\n/**\n * Per-org USAGE BUDGETS, modelled on a Google Cloud billing budget (AGL-1528).\n *\n * ## the directive, 2026-08-18, verbatim\n *\n *   \"*our usage metering, usage alerts, budgets for usage alerts, similar to\n *   how google cloud charges*\"\n *\n * and, on the org-library storage decision the same day: bill from today\n * \"*but with overage protection + usage alerts, so customers don't get a\n * surprise bill*\".\n *\n * ## What a GCP billing budget actually is, and what this copies\n *\n * A GCP budget is **an amount plus a set of percentage alert rules**. It is\n * not a cap: crossing 100% of a budget stops nothing, it sends the email that\n * makes the bill stop being a surprise. Each rule fires **once per budget\n * period per rule** — the console shows the budget and its progress, and the\n * same rules push mail.\n *\n * This module is that shape, and only that shape:\n *\n *   - an **amount** (`amountUsd`), chosen by the customer;\n *   - **threshold rules** as percentages of the amount (default 50/90/100 —\n *     GCP's own default trio);\n *   - one alert per threshold per **month**, which is our budget period\n *     because every meter underneath it (`orgs/{id}/usage/{month}`, each\n *     plugin's spend-line document, the counters' `YYYY-MM` fields) already\n *     resets monthly. A budget period the meters do not share would silently compare\n *     a month of spend against a quarter of budget.\n *\n * ## WHY THIS IS NOT THE STORAGE CAP, AND MUST NOT BECOME IT\n *\n * `utils/storage-overage.ts` owns the customer's optional **hard cap**: past\n * it uploads are refused. That is a wall, it is off by default, and it exists\n * because the requirement was for a control \"*by the end user*\".\n *\n * A budget is the OTHER half and the softer one — it never refuses anything.\n * The distinction is load-bearing in both directions: a budget that quietly\n * became a cap would take a customer's site down to save them $2 (the failure\n * mode AGL-1529 rejected on arrival), and a cap with no budget beneath it\n * means the only warning a customer gets is the refusal itself.\n *\n * ## WHY DOLLARS AND NOT PERCENT-OF-QUOTA\n *\n * `usage-alerts` has warned at 80%/100% of individual QUOTAS since AGL-276 —\n * sites, media storage, email sends, bandwidth. Those answer \"am I near a\n * band\". They cannot answer \"what will I owe\", which is the question a\n * metered customer actually has, and no sum of per-quota percentages produces\n * it: an org at 60% of four different bands may owe nothing at all, and an\n * org at 101% of one band may owe $40. Dollars are the customer's unit.\n *\n * ## THE SPEND FIGURE IS READ, NEVER RE-DERIVED\n *\n * `report-usage` already computes `billedCents` daily onto\n * `orgs/{orgId}/usage/{month}` — metered infra excess at cost x 1.3, plus the\n * data, API and contacts overages. That document is the invoice's own\n * arithmetic, and this module takes it verbatim.\n *\n * A second aggregation here is the specific mistake AGL-1371 exists about:\n * the console meter and the warning email each summed their own figures and\n * disagreed by up to `hostLimit`x. A budget alert quoting a number the\n * invoice will not show is worse than no budget alert, because it is believed.\n */\n\n/** GCP's own default budget alert rules, and the same three here. */\nexport const DEFAULT_BUDGET_THRESHOLD_PCTS: readonly number[] = [50, 90, 100]\n\n/** Bounds on the amount a self-serve org may set as its own budget. */\nexport const BUDGET_MIN_USD = 1\nexport const BUDGET_MAX_USD = 100_000\n\n/**\n * Bounds on a threshold rule, as a percentage of the amount.\n *\n * The ceiling is 200 rather than 100 because GCP allows rules above the\n * budget and they are the useful ones on a runaway: an org that set $20 and\n * is at $45 wants to hear about 200%, and a ladder that stops at 100 says\n * exactly as much at $45 as it did at $20.\n */\nexport const BUDGET_THRESHOLD_MIN_PCT = 1\nexport const BUDGET_THRESHOLD_MAX_PCT = 200\n/** At most this many rules, so one org cannot mail its admins 40 times. */\nexport const BUDGET_MAX_THRESHOLDS = 6\n\n/** The guard key this budget dedupes under, inside `orgs/{id}.usageAlerts`. */\nexport const BUDGET_GUARD_KEY = 'budget'\n\nexport interface UsageBudget {\n  /** Whether the customer has set a budget at all. Absent by default. */\n  budgetSet: boolean\n  /** The amount in USD, or `null` when no budget is set. */\n  amountUsd: number | null\n  /**\n   * Threshold rules as percentages, ascending and deduplicated. Always the\n   * default trio when a budget exists but named no rules — a budget with an\n   * empty rule set is a budget that cannot alert, which is the defect this\n   * whole file exists to remove.\n   */\n  thresholdPcts: number[]\n}\n\n/**\n * Coerces whatever is stored (or posted) into a usable ascending rule set.\n *\n * FAILS TO THE DEFAULT, never to empty. Every rejection path here — a blank,\n * a string, a negative, a duplicate, an over-long list — lands on\n * {@link DEFAULT_BUDGET_THRESHOLD_PCTS} rather than on `[]`, because an empty\n * ladder is silence that reads as coverage.\n */\nexport function normalizeBudgetThresholds(\n  input: unknown,\n): number[] {\n  const list = Array.isArray(input) ? input : []\n  const cleaned = [\n    ...new Set(\n      list\n        .map((entry) => Math.round(Number(entry)))\n        .filter(\n          (pct) =>\n            Number.isFinite(pct) &&\n            pct >= BUDGET_THRESHOLD_MIN_PCT &&\n            pct <= BUDGET_THRESHOLD_MAX_PCT,\n        ),\n    ),\n  ].sort((a, b) => a - b)\n  if (!cleaned.length) return [...DEFAULT_BUDGET_THRESHOLD_PCTS]\n  return cleaned.slice(0, BUDGET_MAX_THRESHOLDS)\n}\n\n/**\n * The budget this org has in force, from its raw org document.\n *\n * `null` amount means no budget — deliberately `null` rather than `Infinity`,\n * matching `resolveStorageCap`: the value is serialised into the budget\n * route's JSON and `JSON.stringify(Infinity)` is `null` anyway, so one\n * spelling for \"no budget\" on both sides of the wire.\n *\n * An amount that is present but unusable (blank, negative, `NaN`) reads as NO\n * budget, which is the opposite of how `resolveStorageCap` treats a corrupt\n * CAP — and deliberately so. A corrupt cap must fall back to a low ceiling\n * because failing open there bills someone who asked not to be billed. A\n * budget refuses nothing, so the only cost of failing open is a missing\n * warning, whereas inventing an amount nobody typed produces alerts about a\n * number the customer never chose.\n */\nexport function resolveUsageBudget(\n  org: Record<string, unknown> | null | undefined,\n): UsageBudget {\n  const raw = (org as any)?.usageBudget\n  const amount = Number(raw?.amountUsd)\n  if (!raw || !Number.isFinite(amount) || amount <= 0) {\n    return { budgetSet: false, amountUsd: null, thresholdPcts: [...DEFAULT_BUDGET_THRESHOLD_PCTS] }\n  }\n  return {\n    budgetSet: true,\n    amountUsd: amount,\n    thresholdPcts: normalizeBudgetThresholds(raw?.thresholdPcts),\n  }\n}\n\n/**\n * The HIGHEST rule this spend has crossed, or 0 for none.\n *\n * Highest rather than all-of-them because the dedupe guard stores one number\n * per key (the shape `usage-alerts` has used since AGL-276), and because an\n * org that goes from $0 to $80 against a $50 budget between two cron ticks\n * wants one email saying 160%, not three saying 50, 90 and 100. GCP behaves\n * the same way — the rules are notification points on one number, not a queue.\n */\nexport function budgetThresholdCrossed(\n  spendUsd: number,\n  budget: UsageBudget,\n): number {\n  if (!budget.budgetSet || budget.amountUsd == null) return 0\n  if (!Number.isFinite(budget.amountUsd) || budget.amountUsd <= 0) return 0\n  if (!Number.isFinite(spendUsd) || spendUsd <= 0) return 0\n  const pct = (spendUsd / budget.amountUsd) * 100\n  let crossed = 0\n  for (const rule of budget.thresholdPcts) {\n    if (pct >= rule && rule > crossed) crossed = rule\n  }\n  return crossed\n}\n\n/** One entry of `orgs/{orgId}.usageAlerts` — the existing guard shape. */\nexport interface UsageAlertGuard {\n  month?: string\n  threshold?: number\n}\n\n/**\n * The rule to alert on RIGHT NOW, or 0 for silence.\n *\n * This is the whole of the idempotency requirement and it is one expression,\n * so a caller cannot implement half of it:\n *\n *   - nothing crossed -> silent;\n *   - crossed, but a guard from THIS month already recorded that rule or a\n *     higher one -> silent. A cron that ticks hourly must not mail hourly.\n *   - crossed, and the guard is from a PREVIOUS month -> alert. The budget\n *     period rolled over, and a customer who exceeded last month's budget\n *     must hear about this month's too.\n *\n * The comparison is `>=` on purpose: after alerting at 100 an org that climbs\n * to 200 alerts again (200 > 100), and an org that stays at 100 does not.\n */\nexport function budgetAlertDue(input: {\n  spendUsd: number\n  budget: UsageBudget\n  guard: UsageAlertGuard | null | undefined\n  month: string\n}): number {\n  const { spendUsd, budget, guard, month } = input\n  const crossed = budgetThresholdCrossed(spendUsd, budget)\n  if (!crossed) return 0\n  if (guard?.month === month && Number(guard?.threshold ?? 0) >= crossed) {\n    return 0\n  }\n  return crossed\n}\n\n/**\n * One plugin's line of the month's spend, as its `spendLines` declaration\n * names it (`plugin-usage-axes.ts`).\n */\nexport interface OrgSpendLine {\n  id: string\n  pluginId: string\n  label: string\n  /**\n   * The month's figure in dollars at the rates the plugin bills, read off the\n   * document the declaration names. For a line declared with a `unit` these\n   * dollars are the platform's cost and never cross to a customer's browser\n   * (see {@link publicOrgMonthlySpend}).\n   */\n  usd: number\n  /** Whether `usd` entered `totalUsd` — see {@link billsFromMonth}. */\n  billed: boolean\n}\n\n/**\n * What an org is spending this month, split by where it comes from.\n *\n * Every field is a figure some other module already owns; nothing here is\n * re-derived (see the header). The split exists because a budget alert that\n * says only \"$62\" invites a support ticket asking what the $62 was.\n */\nexport interface OrgSpendBreakdown {\n  /**\n   * Metered infrastructure + plan-priced overages, from the invoice's own\n   * `billedCents`. This is the part that reaches a Stripe invoice.\n   */\n  meteredUsd: number\n  /**\n   * Each plugin's line, in catalog order.\n   *\n   * ALWAYS REPORTED, and counted toward the budget only once the line's own\n   * start month says this month is charged for it. Until then the plugin's\n   * usage is an entitlement with no price anywhere in the platform, and adding\n   * it to a customer's \"you will owe\" figure would be a surprise bill invented\n   * by a notification — precisely the thing this feature exists to stop.\n   *\n   * Carried rather than left out for two reasons that both bite: the day a\n   * line is priced this is a deployment variable instead of a new pipeline,\n   * and a plugin's staff alert reads its own line as the platform's cost.\n   */\n  lines: readonly OrgSpendLine[]\n  /** What counts against the budget: metered, plus every billed line. */\n  totalUsd: number\n  /**\n   * FALSE when no rollup exists for this month yet, so `meteredUsd` is 0\n   * because nothing has been computed rather than because nothing was spent.\n   *\n   * The distinction is the difference between a quiet budget and a broken\n   * one, and it is not theoretical: `usage-alerts` reads the LATEST usage\n   * rollup by `computedAt`, which on the first days of a month is still LAST\n   * month's document. Alerting from that would compare August's budget\n   * against July's spend; suppressing the alert without recording why would\n   * make a budget that never fires look like a budget that never needed to.\n   */\n  meteredFresh: boolean\n}\n\n/**\n * Whether `month`'s invoice charges for a line whose deployment variable\n * holds `configuredStart`.\n *\n * Same START-MONTH shape and the same fail-closed posture as\n * `billsOrgLibraryStorage`, and for the identical reason: a boolean flipped\n * mid-period would retroactively bill a re-run of an earlier month at that\n * month's accumulated usage. A start month cannot reach backwards.\n *\n * Anything but a `YYYY-MM` — `true`, `1`, a date, a typo — bills nothing.\n */\nexport function billsFromMonth(\n  month: string,\n  configuredStart: string | null | undefined,\n): boolean {\n  const start = String(configuredStart ?? '').trim()\n  if (!/^\\d{4}-\\d{2}$/.test(start)) return false\n  if (!/^\\d{4}-\\d{2}$/.test(month)) return false\n  return month >= start\n}\n\n/** A positive finite dollar figure, or 0. */\nfunction dollars(value: unknown): number {\n  const parsed = Number(value)\n  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0\n}\n\n/**\n * Builds the month's spend from figures already read elsewhere.\n *\n * `rollupMonth` is compared to `month` rather than trusted: see\n * {@link OrgSpendBreakdown.meteredFresh}. Every declared spend line is\n * reported, read as nothing when its document was not read.\n */\nexport function orgMonthlySpend(input: {\n  month: string\n  /** `billedCents` off the latest `orgs/{id}/usage/*` document. */\n  rollupBilledCents: number | null | undefined\n  /** The `month` field of that same document. */\n  rollupMonth: string | null | undefined\n  /**\n   * Each declared spend line's figure, keyed by line id: the `live.field` of\n   * its month document, as read.\n   */\n  lineReadings?: Readonly<Record<string, unknown>>\n  /** The deployment's variables, holding each line's start month. */\n  env?: Readonly<Record<string, string | undefined>>\n}): OrgSpendBreakdown {\n  const { month, rollupBilledCents, rollupMonth } = input\n  const meteredFresh = Boolean(rollupMonth) && rollupMonth === month\n  const cents = Number(rollupBilledCents)\n  const meteredUsd =\n    meteredFresh && Number.isFinite(cents) && cents > 0 ? cents / 100 : 0\n  const lines = pluginSpendLines().map(\n    (line): OrgSpendLine => ({\n      id: line.id,\n      pluginId: line.pluginId,\n      label: line.label,\n      usd: dollars(input.lineReadings?.[line.id]),\n      billed: billsFromMonth(month, input.env?.[line.billedFromEnv]),\n    }),\n  )\n  return {\n    meteredUsd,\n    lines,\n    totalUsd:\n      meteredUsd +\n      lines.reduce((sum, line) => sum + (line.billed ? line.usd : 0), 0),\n    meteredFresh,\n  }\n}\n\n/** A spend line as a customer's browser receives it. */\nexport interface PublicOrgSpendLine {\n  id: string\n  label: string\n  billed: boolean\n  /**\n   * The month's figure in the line's declared unit (`ceil(dollars / unit\n   * cost)`), or `null` for a line declared without one.\n   */\n  units: number | null\n  /** What the unit is called, or `null` for a line without one. */\n  unitLabel: string | null\n  /** Dollars, only for a line declared WITHOUT a unit; `null` otherwise. */\n  usd: number | null\n}\n\n/**\n * The customer-facing half of {@link OrgSpendBreakdown} — dollars the customer\n * is charged, and each plugin's line in the unit it declared.\n */\nexport interface PublicOrgSpend {\n  /** Metered infrastructure and plan overages, from the invoice's own figure. */\n  meteredUsd: number\n  lines: PublicOrgSpendLine[]\n  /** What counts against the budget. */\n  totalUsd: number\n  meteredFresh: boolean\n}\n\n/** Dollars in a unit of cost, rounded UP — spend already made never reads as less. */\nfunction unitsOf(usd: number, costUsd: number): number {\n  if (!Number.isFinite(usd) || usd <= 0) return 0\n  return Math.ceil(usd / costUsd)\n}\n\n/**\n * The projection that crosses the boundary to a customer's browser.\n *\n * A line declared with a `unit` stores the platform's own cost — for the AI\n * plugin, its provider bill at the serving model's list rates, not a price\n * and not a rate the platform publishes. Serving it to an org-scoped caller\n * would put a model choice, per-token rates and a margin on a billing page,\n * so such a line crosses in its unit only, through the same rounding-up\n * conversion the plugin's own meter uses, and its dollars never do.\n *\n * `meteredUsd` and `totalUsd` stay dollars: `billedCents` is what an invoice\n * charges, which is the customer's own money and the whole subject of a\n * budget.\n *\n * Units and dollars are deliberately not summed. A budget is a dollar rule,\n * a unit is not a dollar, and folding one into the other would republish the\n * cost the conversion just removed.\n */\nexport function publicOrgMonthlySpend(spend: OrgSpendBreakdown): PublicOrgSpend {\n  const declared = new Map<string, ResolvedPluginSpendLine>(\n    pluginSpendLines().map((line) => [line.id, line]),\n  )\n  return {\n    meteredUsd: spend.meteredUsd,\n    lines: spend.lines.map((line) => {\n      const unit = declared.get(line.id)?.unit\n      return {\n        id: line.id,\n        label: line.label,\n        billed: line.billed,\n        units: unit ? unitsOf(line.usd, unit.costUsd) : null,\n        unitLabel: unit ? unit.label : null,\n        usd: unit ? null : line.usd,\n      }\n    }),\n    totalUsd: spend.totalUsd,\n    meteredFresh: spend.meteredFresh,\n  }\n}\n"],"names":["pluginSpendLines","DEFAULT_BUDGET_THRESHOLD_PCTS","BUDGET_MIN_USD","BUDGET_MAX_USD","BUDGET_THRESHOLD_MIN_PCT","BUDGET_THRESHOLD_MAX_PCT","BUDGET_MAX_THRESHOLDS","BUDGET_GUARD_KEY","normalizeBudgetThresholds","input","list","Array","isArray","cleaned","Set","map","entry","Math","round","Number","filter","pct","isFinite","sort","a","b","length","slice","resolveUsageBudget","org","raw","usageBudget","amount","amountUsd","budgetSet","thresholdPcts","budgetThresholdCrossed","spendUsd","budget","crossed","rule","budgetAlertDue","guard","month","threshold","billsFromMonth","configuredStart","start","String","trim","test","dollars","value","parsed","orgMonthlySpend","rollupBilledCents","rollupMonth","meteredFresh","Boolean","cents","meteredUsd","lines","line","id","pluginId","label","usd","lineReadings","billed","env","billedFromEnv","totalUsd","reduce","sum","unitsOf","costUsd","ceil","publicOrgMonthlySpend","spend","declared","Map","unit","get","units","unitLabel"],"mappings":"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"}

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

@@ -21,7 +21,7 @@
  * Named for what it parses, the web's UTM labels. The `campaign` in
  * `utm_campaign` is the label an ad push carries; it is not the Marketing
  * plugin's campaign, and nothing here reads one. What a site's own visitors
- * carry to the moment they identify is `campaign-touch.ts`'s.
+ * carry to the moment they identify is `utm-touch.ts`'s.
  *
  * Until this existed a paid click, an organic visit and a partner link
  * arrived indistinguishable: `sign_up` carried `method` and nothing else, so

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

@@ -21,7 +21,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * Named for what it parses, the web's UTM labels. The `campaign` in
  * `utm_campaign` is the label an ad push carries; it is not the Marketing
  * plugin's campaign, and nothing here reads one. What a site's own visitors
- * carry to the moment they identify is `campaign-touch.ts`'s.
+ * carry to the moment they identify is `utm-touch.ts`'s.
  *
  * Until this existed a paid click, an organic visit and a partner link
  * arrived indistinguishable: `sign_up` carried `method` and nothing else, so

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

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

package/src/lib/app-utils/{campaign-touch.d.ts → utm-touch.d.ts}

@@ -15,8 +15,13 @@
  * limitations under the License.
  */
 /**
- * THE VISITOR'S HALF OF CAMPAIGN ATTRIBUTION — the touch that has to survive
- * the gap between arriving from a campaign and becoming somebody.
+ * THE VISITOR'S HALF OF ATTRIBUTION — the UTM touch that has to survive the
+ * gap between arriving from a labeled link and becoming somebody.
+ *
+ * The labels are the web's (`utm_source`/`utm_medium`/`utm_campaign`), not
+ * any plugin's model: every door that identifies a visitor — a form, a
+ * booking, a signup — attaches the touch, and whichever plugin credits its
+ * campaigns reads it on the server.
  *
  * ## The gap this exists to cross
  *
@@ -125,8 +130,11 @@ import { type UtmAttribution } from './utm-attribution';
 export declare const ATTRIBUTION_WINDOW_DAYS = 7;
 /** The same window in milliseconds. */
 export declare const ATTRIBUTION_WINDOW_MS: number;
-/** Where the touch is held. Namespaced like every other key this app sets. */
-export declare const CAMPAIGN_TOUCH_STORAGE_KEY = "aglyn:campaign-touch";
+/**
+ * Where the touch is held. Namespaced like every other key this app sets, and
+ * spelled as visitors' devices already hold it.
+ */
+export declare const UTM_TOUCH_STORAGE_KEY = "aglyn:campaign-touch";
 /**
  * The parameter the touch's instant rides under inside the wire form.
  *
@@ -135,17 +143,17 @@ export declare const CAMPAIGN_TOUCH_STORAGE_KEY = "aglyn:campaign-touch";
  * by it or have to widen it. `t` is outside the allowlist and read
  * separately.
  */
-export declare const CAMPAIGN_TOUCH_TIME_KEY = "t";
+export declare const UTM_TOUCH_TIME_KEY = "t";
 /** A campaign the visitor arrived from, and when they arrived from it. */
-export interface CampaignTouch extends UtmAttribution {
+export interface UtmTouch extends UtmAttribution {
     /** When the visitor followed the campaign link, epoch ms. */
     atMs: number;
 }
 /**
  * The canonical stored form of a touch — the ONLY place it is written, so it
- * cannot drift from what {@link parseCampaignTouch} reads back.
+ * cannot drift from what {@link parseUtmTouch} reads back.
  */
-export declare function campaignTouchWire(touch: CampaignTouch | null | undefined): string;
+export declare function utmTouchWire(touch: UtmTouch | null | undefined): string;
 /**
  * Read a stored or transmitted touch back, or `null`.
  *
@@ -155,7 +163,7 @@ export declare function campaignTouchWire(touch: CampaignTouch | null | undefine
  * future is refused for the reason the revenue join refuses one: a click
  * after the conversion is the receipt, not the cause.
  */
-export declare function parseCampaignTouch(wire: unknown, nowMs?: number): CampaignTouch | null;
+export declare function parseUtmTouch(wire: unknown, nowMs?: number): UtmTouch | null;
 /**
  * Tell this module what the visitor's analytics consent state is.
  *
@@ -163,7 +171,7 @@ export declare function parseCampaignTouch(wire: unknown, nowMs?: number): Campa
  * grant remembers the arrival the moment it is given and a withdrawal drops
  * the stored touch immediately.
  */
-export declare function setCampaignTouchConsent(allowed: boolean | null): void;
+export declare function setUtmTouchConsent(allowed: boolean | null): void;
 /**
  * Remember the campaign on the current URL as this visitor's latest touch.
  *
@@ -174,7 +182,7 @@ export declare function setCampaignTouchConsent(allowed: boolean | null): void;
  *
  * @returns what is now remembered, or `null`.
  */
-export declare function rememberCampaignTouch(search?: string, nowMs?: number): CampaignTouch | null;
+export declare function rememberUtmTouch(search?: string, nowMs?: number): UtmTouch | null;
 /**
  * The touch to credit a conversion happening right now, or `null`.
  *
@@ -191,7 +199,7 @@ export declare function rememberCampaignTouch(search?: string, nowMs?: number):
  * device would be keeping a record of where somebody came from for no purpose
  * anything reads. The read that finds it removes it.
  */
-export declare function readCampaignTouch(nowMs?: number): CampaignTouch | null;
+export declare function readUtmTouch(nowMs?: number): UtmTouch | null;
 /**
  * The fragment a conversion request spreads into its body, or `{}`.
  *
@@ -201,6 +209,6 @@ export declare function readCampaignTouch(nowMs?: number): CampaignTouch | null;
  * never `campaignTouch: undefined`, so that "arrived from nowhere" and "this
  * door does not report" stay distinguishable on the wire.
  */
-export declare function campaignTouchField(nowMs?: number): {
+export declare function utmTouchField(nowMs?: number): {
     campaignTouch?: string;
 };