@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/url-slug.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/url-slug.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 * One path segment of a public URL, derived from something a human typed.\n *\n * Lowercase, runs of non-alphanumerics collapsed to a single `-`, no leading\n * or trailing dash. Deliberately LOSSY and IDEMPOTENT: the same subject\n * addresses the same URL whether the caller passes a stored id, a display\n * name, or the segment itself. `Open source` → `open-source` → `open-source`.\n *\n * ## Why this is one function and not two\n *\n * The category route (AGL-1321) and the author route (AGL-2518) both have to\n * answer the same question twice, in two directions: BUILD a link from a\n * record, and MATCH an incoming segment back to that record. Four call sites\n * for one rule — and they only work because all four normalize identically.\n * Two implementations that agree today are a bug waiting for whichever one is\n * edited first, and the failure is silent: the archive simply comes back\n * empty, which is also what an author with no posts looks like.\n *\n * Not to be confused with `slugifyDatasetFieldId` or `slugifyHeading`, which\n * are not URL segments and have their own rules (an identifier may not start\n * with a digit; a heading anchor keeps its own collision suffixes).\n */\nexport function urlSlugSegment(value: string | undefined | null): string {\n  return String(value ?? '')\n    .trim()\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '')\n}\n\nexport default urlSlugSegment\n"],"names":["urlSlugSegment","value","String","trim","toLowerCase","replace"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,SAASA,eAAeC,KAAgC;IAC7D,OAAOC,OAAOD,gBAAAA,QAAS,IACpBE,IAAI,GACJC,WAAW,GACXC,OAAO,CAAC,eAAe,KACvBA,OAAO,CAAC,YAAY;AACzB;AAEA,eAAeL,eAAc"}

package/src/lib/app-utils/usage-budget.d.ts

@@ -0,0 +1,429 @@
+/**
+ * @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.
+ */
+/**
+ * Per-org USAGE BUDGETS, modelled on a Google Cloud billing budget (AGL-1528).
+ *
+ * ## the directive, 2026-08-18, verbatim
+ *
+ *   "*our usage metering, usage alerts, budgets for usage alerts, similar to
+ *   how google cloud charges*"
+ *
+ * and, on the org-library storage decision the same day: bill from today
+ * "*but with overage protection + usage alerts, so customers don't get a
+ * surprise bill*".
+ *
+ * ## What a GCP billing budget actually is, and what this copies
+ *
+ * A GCP budget is **an amount plus a set of percentage alert rules**. It is
+ * not a cap: crossing 100% of a budget stops nothing, it sends the email that
+ * makes the bill stop being a surprise. Each rule fires **once per budget
+ * period per rule** — the console shows the budget and its progress, and the
+ * same rules push mail.
+ *
+ * This module is that shape, and only that shape:
+ *
+ *   - an **amount** (`amountUsd`), chosen by the customer;
+ *   - **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
+ *     a month of spend against a quarter of budget.
+ *
+ * ## WHY THIS IS NOT THE STORAGE CAP, AND MUST NOT BECOME IT
+ *
+ * `utils/storage-overage.ts` owns the customer's optional **hard cap**: past
+ * it uploads are refused. That is a wall, it is off by default, and it exists
+ * because the requirement was for a control "*by the end user*".
+ *
+ * A budget is the OTHER half and the softer one — it never refuses anything.
+ * The distinction is load-bearing in both directions: a budget that quietly
+ * became a cap would take a customer's site down to save them $2 (the failure
+ * mode AGL-1529 rejected on arrival), and a cap with no budget beneath it
+ * means the only warning a customer gets is the refusal itself.
+ *
+ * ## WHY DOLLARS AND NOT PERCENT-OF-QUOTA
+ *
+ * `usage-alerts` has warned at 80%/100% of individual QUOTAS since AGL-276 —
+ * sites, media storage, email sends, bandwidth. Those answer "am I near a
+ * band". They cannot answer "what will I owe", which is the question a
+ * metered customer actually has, and no sum of per-quota percentages produces
+ * it: an org at 60% of four different bands may owe nothing at all, and an
+ * org at 101% of one band may owe $40. Dollars are the customer's unit.
+ *
+ * ## THE SPEND FIGURE IS READ, NEVER RE-DERIVED
+ *
+ * `report-usage` already computes `billedCents` daily onto
+ * `orgs/{orgId}/usage/{month}` — metered infra excess at cost x 1.3, plus the
+ * data, API and contacts overages. That document is the invoice's own
+ * arithmetic, and this module takes it verbatim.
+ *
+ * A second aggregation here is the specific mistake AGL-1371 exists about:
+ * the console meter and the warning email each summed their own figures and
+ * disagreed by up to `hostLimit`x. A budget alert quoting a number the
+ * invoice will not show is worse than no budget alert, because it is believed.
+ */
+/** GCP's own default budget alert rules, and the same three here. */
+export declare const DEFAULT_BUDGET_THRESHOLD_PCTS: readonly number[];
+/** Bounds on the amount a self-serve org may set as its own budget. */
+export declare const BUDGET_MIN_USD = 1;
+export declare const BUDGET_MAX_USD = 100000;
+/**
+ * Bounds on a threshold rule, as a percentage of the amount.
+ *
+ * The ceiling is 200 rather than 100 because GCP allows rules above the
+ * budget and they are the useful ones on a runaway: an org that set $20 and
+ * is at $45 wants to hear about 200%, and a ladder that stops at 100 says
+ * exactly as much at $45 as it did at $20.
+ */
+export declare const BUDGET_THRESHOLD_MIN_PCT = 1;
+export declare const BUDGET_THRESHOLD_MAX_PCT = 200;
+/** At most this many rules, so one org cannot mail its admins 40 times. */
+export declare const BUDGET_MAX_THRESHOLDS = 6;
+/** The guard key this budget dedupes under, inside `orgs/{id}.usageAlerts`. */
+export declare const BUDGET_GUARD_KEY = "budget";
+export interface UsageBudget {
+    /** Whether the customer has set a budget at all. Absent by default. */
+    budgetSet: boolean;
+    /** The amount in USD, or `null` when no budget is set. */
+    amountUsd: number | null;
+    /**
+     * Threshold rules as percentages, ascending and deduplicated. Always the
+     * default trio when a budget exists but named no rules — a budget with an
+     * empty rule set is a budget that cannot alert, which is the defect this
+     * whole file exists to remove.
+     */
+    thresholdPcts: number[];
+}
+/**
+ * Coerces whatever is stored (or posted) into a usable ascending rule set.
+ *
+ * FAILS TO THE DEFAULT, never to empty. Every rejection path here — a blank,
+ * a string, a negative, a duplicate, an over-long list — lands on
+ * {@link DEFAULT_BUDGET_THRESHOLD_PCTS} rather than on `[]`, because an empty
+ * ladder is silence that reads as coverage.
+ */
+export declare function normalizeBudgetThresholds(input: unknown): number[];
+/**
+ * The budget this org has in force, from its raw org document.
+ *
+ * `null` amount means no budget — deliberately `null` rather than `Infinity`,
+ * matching `resolveStorageCap`: the value is serialised into the budget
+ * route's JSON and `JSON.stringify(Infinity)` is `null` anyway, so one
+ * spelling for "no budget" on both sides of the wire.
+ *
+ * An amount that is present but unusable (blank, negative, `NaN`) reads as NO
+ * budget, which is the opposite of how `resolveStorageCap` treats a corrupt
+ * CAP — and deliberately so. A corrupt cap must fall back to a low ceiling
+ * because failing open there bills someone who asked not to be billed. A
+ * budget refuses nothing, so the only cost of failing open is a missing
+ * warning, whereas inventing an amount nobody typed produces alerts about a
+ * number the customer never chose.
+ */
+export declare function resolveUsageBudget(org: Record<string, unknown> | null | undefined): UsageBudget;
+/**
+ * The HIGHEST rule this spend has crossed, or 0 for none.
+ *
+ * Highest rather than all-of-them because the dedupe guard stores one number
+ * per key (the shape `usage-alerts` has used since AGL-276), and because an
+ * org that goes from $0 to $80 against a $50 budget between two cron ticks
+ * wants one email saying 160%, not three saying 50, 90 and 100. GCP behaves
+ * the same way — the rules are notification points on one number, not a queue.
+ */
+export declare function budgetThresholdCrossed(spendUsd: number, budget: UsageBudget): number;
+/** One entry of `orgs/{orgId}.usageAlerts` — the existing guard shape. */
+export interface UsageAlertGuard {
+    month?: string;
+    threshold?: number;
+}
+/**
+ * The rule to alert on RIGHT NOW, or 0 for silence.
+ *
+ * This is the whole of the idempotency requirement and it is one expression,
+ * so a caller cannot implement half of it:
+ *
+ *   - nothing crossed -> silent;
+ *   - crossed, but a guard from THIS month already recorded that rule or a
+ *     higher one -> silent. A cron that ticks hourly must not mail hourly.
+ *   - crossed, and the guard is from a PREVIOUS month -> alert. The budget
+ *     period rolled over, and a customer who exceeded last month's budget
+ *     must hear about this month's too.
+ *
+ * The comparison is `>=` on purpose: after alerting at 100 an org that climbs
+ * to 200 alerts again (200 > 100), and an org that stays at 100 does not.
+ */
+export declare function budgetAlertDue(input: {
+    spendUsd: number;
+    budget: UsageBudget;
+    guard: UsageAlertGuard | null | undefined;
+    month: string;
+}): number;
+/**
+ * What an org is spending this month, split by where it comes from.
+ *
+ * Every field is a figure some other module already owns; nothing here is
+ * re-derived (see the header). The split exists because a budget alert that
+ * says only "$62" invites a support ticket asking what the $62 was.
+ */
+export interface OrgSpendBreakdown {
+    /**
+     * Metered infrastructure + plan-priced overages, from the invoice's own
+     * `billedCents`. This is the part that reaches a Stripe invoice.
+     */
+    meteredUsd: number;
+    /**
+     * Aglyn Assist token spend for the month, at the serving model's list
+     * rates (`orgs/{id}/assistUsage/{month}.estCostUsd`).
+     *
+     * ALWAYS REPORTED, and counted toward the budget only when
+     * {@link billsAssistTokens} says this month invoices for it — which today
+     * it does not, because Assist is a plan ENTITLEMENT (`aiAssist: true`) with
+     * no per-token price anywhere in the platform. Adding it to a customer's
+     * "you will owe" figure would be a surprise bill invented by a
+     * notification, which is precisely the thing this feature exists to stop.
+     *
+     * It is nonetheless carried here rather than left out, for two reasons that
+     * both bite: the day Assist is priced this is a one-line switch instead of
+     * a new pipeline, and — live today — {@link assistMarginBreach} reads this
+     * same number as OUR cost, which is the margin-guard half of the job.
+     */
+    assistUsd: number;
+    /** What counts against the budget: metered, plus assist when it bills. */
+    totalUsd: number;
+    /** Whether `assistUsd` entered `totalUsd`. */
+    assistBilled: boolean;
+    /**
+     * FALSE when no rollup exists for this month yet, so `meteredUsd` is 0
+     * because nothing has been computed rather than because nothing was spent.
+     *
+     * The distinction is the difference between a quiet budget and a broken
+     * one, and it is not theoretical: `usage-alerts` reads the LATEST usage
+     * rollup by `computedAt`, which on the first days of a month is still LAST
+     * month's document. Alerting from that would compare August's budget
+     * against July's spend; suppressing the alert without recording why would
+     * make a budget that never fires look like a budget that never needed to.
+     */
+    meteredFresh: boolean;
+}
+/**
+ * Whether `month`'s invoice charges for Assist tokens.
+ *
+ * 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.
+ *
+ * `BILL_ASSIST_TOKENS_FROM=YYYY-MM`. Anything else — `true`, `1`, a date, a
+ * typo — bills nothing.
+ */
+export declare function billsAssistTokens(month: string, configuredStart: string | null | undefined): boolean;
+/**
+ * Builds the month's spend from figures already read elsewhere.
+ *
+ * `rollupMonth` is compared to `month` rather than trusted: see
+ * {@link OrgSpendBreakdown.meteredFresh}.
+ */
+export declare function orgMonthlySpend(input: {
+    month: string;
+    /** `billedCents` off the latest `orgs/{id}/usage/*` document. */
+    rollupBilledCents: number | null | undefined;
+    /** The `month` field of that same document. */
+    rollupMonth: string | null | undefined;
+    /** `estCostUsd` off `orgs/{id}/assistUsage/{month}`. */
+    assistEstCostUsd: number | null | undefined;
+    /** `BILL_ASSIST_TOKENS_FROM`, verbatim. */
+    assistBilledFrom?: string | null;
+}): OrgSpendBreakdown;
+/**
+ * The customer-facing half of {@link OrgSpendBreakdown} — dollars the customer
+ * is charged, and Assist consumption in CREDITS.
+ */
+export interface PublicOrgSpend {
+    /** Metered infrastructure and plan overages, from the invoice's own figure. */
+    meteredUsd: number;
+    /**
+     * Assist consumption this month, in credits. The stored figure is
+     * `estCostUsd` — our provider bill — and a credit is the unit that expresses
+     * it without publishing it.
+     */
+    assistCredits: number;
+    /** What counts against the budget. */
+    totalUsd: number;
+    /** Whether Assist consumption entered `totalUsd`. */
+    assistBilled: boolean;
+    meteredFresh: boolean;
+}
+/**
+ * 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
+ * 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.
+ *
+ * `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.
+ *
+ * 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.
+ */
+export declare function publicOrgMonthlySpend(spend: OrgSpendBreakdown): PublicOrgSpend;
+/**
+ * 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 declare const ASSIST_ORG_MONTHLY_COGS_ALERT_USD_DEFAULT = 25;
+export declare function assistCogsAlertThresholdUsd(configured?: string | null): number;
+/**
+ * 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 declare 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 declare function assistOrgMonthlyCostLimitUsd(configured?: string | null): number | null;
+/**
+ * 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 declare function assistOperatorCeilingUsd(configured?: string | null): number | null | 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 declare function assistMarginBreach(input: {
+    assistUsd: number;
+    thresholdUsd: number;
+    guard: UsageAlertGuard | null | undefined;
+    month: string;
+}): boolean;
+/**
+ * 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 declare function assistCeilingBreach(input: {
+    assistUsd: number;
+    ceilingUsd: number | null;
+    guard: UsageAlertGuard | null | undefined;
+    month: string;
+}): boolean;
+/** The multiple {@link assistMarginBreach} would record. */
+export declare function assistMarginMultiple(assistUsd: number, thresholdUsd: number): number;