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

package/src/lib/app-utils/subscription-topics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/subscription-topics.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 { PLUGIN_SUBSCRIPTION_TOPICS_DECLARED } from '../plugin-manager/plugin-subscription-topics.generated'\n\n/**\n * SUBSCRIPTION TOPICS — the streams a recipient can leave one at a time.\n *\n * The mail rail's per-stream consent: every marketing-purpose message names\n * the stream it belongs to, its unsubscribe link carries that stream, and the\n * send path refuses a recipient who left it. That obligation is owed on every\n * such message whichever plugin sends it — a campaign, a newsletter, a\n * restock alert, an automation, the operator's own product updates — so the\n * state and the policy are the platform's. What a plugin brings is the\n * STREAMS it sends under, which it declares (`plugins.config.json` →\n * `subscriptionTopics`, compiled into {@link DECLARED_SUBSCRIPTION_TOPICS}).\n *\n * ## The gap this closes\n *\n * `docs/specs/email-competitive-gaps.md` §1f records the only row in that\n * table where every competitor has something and we had nothing: \"Preference\n * center / subscription topics — unsubscribe is all-or-nothing per site\".\n * A recipient who wanted the newsletter but not the sales mail had exactly one\n * lever, and pulling it took the newsletter too. The lever people reach for\n * when the only unsubscribe is total is \"report spam\", which is a complaint,\n * which is the sending domain's problem and therefore every tenant's.\n *\n * ## Scope: definitions are ORG-shared, opt-outs are PER-SITE\n *\n * The topic CATALOG an org authors — renaming, re-describing, archiving a\n * built-in stream, adding its own — is stored by the plugin that manages it,\n * under the organization, where lists live and for the same reason: a topic is\n * authored editorial content that an agency writes once and points several\n * sites at.\n *\n * A recipient's OPT-OUT is per site, at `hosts/{hostId}/topicOptOuts`. It sits\n * beside `hosts/{hostId}/suppressions`, which is per site, and it answers the\n * same shape of question one notch finer: the suppression says \"nothing from\n * this site\", the opt-out says \"not this stream from this site\". Two facts\n * about one person that live at different scopes would make \"may I mail this\n * person about product updates\" a question with two answers. It also keeps\n * the unauthenticated preference page honest — the signed link names a host\n * and nothing else, so a per-site read is exactly what the link authorizes.\n *\n * ## Why the built-ins are declared and not seeded documents\n *\n * A seeding migration would have to run against every org, would leave any org\n * created while it was mid-flight with none, and — like every backfill — is a\n * thing that gets written and then not run. So the declared streams are the\n * floor of the catalog rather than its initial contents: present for every\n * org from the moment a plugin declares one, with no write anywhere, and a\n * stored document at the same id renames, re-describes or archives one. The\n * catalog a reader sees is {@link mergeSubscriptionTopics} of the two.\n */\n\n/** One subscribable stream. */\nexport interface SubscriptionTopic {\n  /**\n   * The stored id. Rides in the unsubscribe link's `tid` and is covered by\n   * its signature, so it is treated as persisted — rename the {@link name},\n   * never the id.\n   */\n  id: string\n  /** What the recipient sees on the preference page. */\n  name: string\n  /** One sentence of \"what will I get\", shown under the name. */\n  description: string\n  /**\n   * Retired. An archived topic stays in the catalog for the send path and the\n   * preference page's history, and is hidden from the composer's picker —\n   * campaigns already sent under it must go on resolving, or their unsubscribe\n   * links stop naming anything.\n   */\n  archived?: boolean\n  /**\n   * Whether joining this stream needs a confirmation click.\n   *\n   * `undefined` — the ordinary state — means \"whatever the site says\", which\n   * is what {@link topicRequiresDoubleOptIn} resolves. A stored `true` or\n   * `false` is a decision made about THIS stream and overrides the site: a\n   * merchant who confirms their newsletter and not their order-related\n   * product updates is expressing something real, and a per-site switch alone\n   * cannot hold it.\n   */\n  doubleOptIn?: boolean\n}\n\n/**\n * DOUBLE OPT-IN — per topic, defaulting per site.\n *\n * `docs/specs/email-competitive-gaps.md` P8. Of the ten vendors surveyed\n * **none mandates it**, so this is an option and never a default: the field\n * above is absent everywhere until a merchant turns it on, and the site\n * default is off.\n *\n * ## Why per topic, with a per-site default\n *\n * Three reasons, and the first is the one that decides it.\n *\n * The recipient-facing vocabulary is ALREADY per topic. The signed link\n * carries `tid`, the opt-out record is keyed by topic, and the preference\n * page is a list of topics. A confirmation scoped to anything else would need\n * a second vocabulary to express \"confirmed for what\", and the recipient\n * would meet both.\n *\n * It is also the axis the compared products chose — Brevo and Klaviyo offer\n * double opt-in per LIST — and a topic is our per-list.\n *\n * The site default exists because the merchant who wants this usually wants\n * it everywhere: in the jurisdictions where a DOI is the accepted proof of\n * consent, \"on for the newsletter but not for the four others\" is not the\n * answer they are after, and asking them to set it on each topic they now\n * have plus each one they later add is the shape that gets half-done.\n *\n * ## What it must have to be worth anything\n *\n * ActiveCampaign is the implementation worth copying because it has teeth:\n * an unconfirmed subscriber lands in a real quarantine and \"you cannot send\n * any emails to contacts that have this status\". Recording a pending\n * confirmation that the send path then ignores is Customer.io's DIY recipe,\n * whose own documentation warns that it \"doesn't automatically check this\n * attribute before sending messages\" — a fact stored and not enforced. So the\n * state below is read by `filterTopicSendable`, in the same pass that reads\n * the opt-outs.\n *\n * ## On the law, precisely\n *\n * No jurisdiction verified requires double opt-in by statute. They require\n * prior express consent plus a burden of proof on the sender — EU ePrivacy\n * Art. 13(1), German UWG §7(2), Canada's CASL s.13. Germany's own\n * certification body says a DOI is not required by law and then explains why\n * everyone does it anyway: the proof has so far been recognized by the courts\n * exclusively via a DOI. The law requires provable consent; a DOI is the\n * accepted proof.\n */\nexport const DEFAULT_SITE_DOUBLE_OPT_IN = false\n\n/**\n * How long a confirmation link stays good.\n *\n * 72 hours, Klaviyo's number rather than one of our own. Brevo's is 30 days,\n * which is long enough that the click stops being evidence of anything\n * contemporaneous; the point of the confirmation is to show that the person\n * holding that mailbox wanted this, and a month-old click shows it much less\n * well than a same-day one.\n *\n * Expiry stops the LINK working. It does not make an unconfirmed address\n * mailable — see {@link readTopicSubscriptionState}, where the two are\n * deliberately separate questions.\n */\nexport const DOUBLE_OPT_IN_EXPIRY_MS = 72 * 60 * 60 * 1000\n\n/**\n * Whether joining `topic` on this site needs a confirmation click.\n *\n * The topic's own setting when it has one, the site's otherwise. `false`\n * stored on a topic is a real answer and not an absence, which is what lets a\n * merchant confirm everything except their order-related stream.\n */\nexport function topicRequiresDoubleOptIn(\n  topic: Pick<SubscriptionTopic, 'doubleOptIn'> | null | undefined,\n  siteDefault: boolean = DEFAULT_SITE_DOUBLE_OPT_IN,\n): boolean {\n  return typeof topic?.doubleOptIn === 'boolean'\n    ? topic.doubleOptIn\n    : siteDefault === true\n}\n\n/** What one person's record says about one stream on one site. */\nexport type TopicSubscriptionState =\n  /** They may be mailed about this. */\n  | 'subscribed'\n  /** Asked to join and has not confirmed. NOT mailable. */\n  | 'pending'\n  /** Left this stream and has not rejoined. NOT mailable. */\n  | 'opted-out'\n\n/** One entry in a `topicOptOuts` document's `topics` map, as stored. */\nexport interface TopicSubscriptionEntry {\n  optedOutAt?: unknown\n  resubscribedAt?: unknown\n  /** When a confirmation was asked for. */\n  pendingAt?: unknown\n  /** When they confirmed, or absent/null while they have not. */\n  confirmedAt?: unknown\n}\n\n/**\n * What an entry means, in one place, for every reader.\n *\n * ## Why this is a function and not a field test at each site\n *\n * There were two fields and one test — \"an entry with no `resubscribedAt` is a\n * live opt-out\" — written out at three call sites. Adding a third and fourth\n * field breaks that test everywhere it appears at once: a CONFIRMED entry\n * carries `pendingAt` and `confirmedAt` and no `resubscribedAt`, so the old\n * shorthand reads it as somebody who left. Nobody would find that by reading\n * one call site.\n *\n * ## Precedence: a refusal outranks a pending confirmation\n *\n * Somebody who left a stream and never rejoined is opted out even if a\n * confirmation was once asked of them, because leaving is the more recent and\n * more explicit act — and because a pending confirmation that could outrank a\n * refusal would be a way to re-arm sending by asking again.\n *\n * ## An EXPIRED confirmation is still not a subscriber\n *\n * Expiry stops the link working; it does not admit anybody. The alternative —\n * treating a lapsed pending record as subscribed — would make the whole\n * mechanism a delay rather than a gate, and waiting it out would be the way\n * past it.\n */\nexport function readTopicSubscriptionState(\n  entry: TopicSubscriptionEntry | null | undefined,\n): TopicSubscriptionState {\n  if (!entry) return 'subscribed'\n  if (entry.optedOutAt && !entry.resubscribedAt) return 'opted-out'\n  if (entry.pendingAt && !entry.confirmedAt) return 'pending'\n  return 'subscribed'\n}\n\n/**\n * Whether a confirmation request is too old to be acted on.\n *\n * A separate question from {@link readTopicSubscriptionState} on purpose: one\n * answers \"may we mail them\", the other answers \"does this link still work\",\n * and collapsing them is how an expiry comes to admit somebody.\n */\nexport function doubleOptInExpired(\n  pendingAtMs: number | null | undefined,\n  nowMs: number,\n): boolean {\n  const at = Number(pendingAtMs)\n  if (!Number.isFinite(at) || at <= 0) return true\n  return nowMs - at > DOUBLE_OPT_IN_EXPIRY_MS\n}\n\n/** `hosts/{hostId}/topicOptOuts/{emailKey}` — one document per recipient. */\nexport const TOPIC_OPT_OUTS_SUBCOLLECTION = 'topicOptOuts'\n\n/** One stream a plugin declares, as compiled from `plugins.config.json`. */\nexport interface DeclaredSubscriptionTopic {\n  /** The plugin that sends under it. */\n  pluginId: string\n  /**\n   * A wire value: a Firestore path component and a colon-joined component of\n   * the unsubscribe link's signed subject. Changing one orphans every opt-out\n   * already recorded against it.\n   */\n  id: string\n  name: string\n  description: string\n  /** Its place on the preference page. */\n  order: number\n  /** The stream a message belongs to when it names none. */\n  default?: true\n}\n\n/**\n * The catalog every org has before anyone opens the console: the streams the\n * plugins declare, in preference-page order.\n *\n * A handful, not a dozen. A preference page whose value is \"leave one stream\n * without leaving all of them\" stops working the moment the list is long\n * enough that reading it is a chore, and a merchant who needs another can add\n * one. The ids are the generic names an unsubscribing recipient can recognize\n * without knowing anything about the sender's internal vocabulary.\n */\nexport const DECLARED_SUBSCRIPTION_TOPICS: readonly SubscriptionTopic[] =\n  PLUGIN_SUBSCRIPTION_TOPICS_DECLARED.map(({ id, name, description }) => ({\n    id,\n    name,\n    description,\n  }))\n\n/**\n * The stream a message belongs to when its author picked none: the one a\n * plugin declares `default`, or `''` when none does.\n *\n * Every campaign resolves to SOME topic while one is declared, because a\n * campaign with no topic would mint an unsubscribe link the preference page\n * cannot place — it could offer the catalog but not say which entry this\n * message was, which is the one thing the recipient came to the page knowing.\n */\nexport const DEFAULT_SUBSCRIPTION_TOPIC_ID: string =\n  PLUGIN_SUBSCRIPTION_TOPICS_DECLARED.find((topic) => topic.default)?.id ?? ''\n\n/**\n * WHICH STREAM AN AUTOMATED EMAIL BELONGS TO — the one answer, named once.\n *\n * An immediate reply belongs to no stream unless the step named one; anything\n * that goes out on the merchant's schedule belongs to the default stream, as a\n * campaign does. See `FlowEmailScope` for why the two differ.\n *\n * The rule is read TWICE per send — the flow gate filters on it, and the\n * executor signs it into the opt-out link so the preference page opens on the\n * stream the recipient was trying to leave rather than on a list they have to\n * search — so it lives here, in the pure leaf both sides can import, rather\n * than beside either reader. Two spellings of it is how a link comes to name\n * a stream the gate did not check.\n *\n * @returns the topic id, or `''` for a message that belongs to no stream —\n *          which is not \"the default topic\", and must not be signed into a\n *          link as one.\n */\nexport function flowSubscriptionTopicId(\n  topicId: string | null | undefined,\n  scope?: 'scheduled' | 'immediate',\n): string {\n  const named = String(topicId ?? '').trim()\n  return scope === 'immediate' ? named : named || DEFAULT_SUBSCRIPTION_TOPIC_ID\n}\n\n/**\n * Whether `value` may be a topic id.\n *\n * Two constraints, and the second is the load-bearing one. The id becomes a\n * Firestore path component, so it carries `isDocumentId`'s rules; and it\n * becomes a COLON-JOINED component of the unsubscribe link's signed subject,\n * so a colon inside it would let one signed subject be read as two different\n * parameter tuples. See `signatureMatches` in the email plugin's\n * `unsubscribe-link.ts` for what that ambiguity would buy.\n */\nexport function isSubscriptionTopicId(value: unknown): value is string {\n  return (\n    typeof value === 'string' &&\n    value.length > 0 &&\n    value.length <= 120 &&\n    !value.includes('/') &&\n    !value.includes(':') &&\n    value !== '.' &&\n    value !== '..' &&\n    !/^__.*__$/.test(value)\n  )\n}\n\n/** Coerces one stored document into a topic, or `null` if it is not one. */\nexport function normalizeSubscriptionTopic(\n  id: unknown,\n  data: Record<string, unknown> | null | undefined,\n): SubscriptionTopic | null {\n  if (!isSubscriptionTopicId(id)) return null\n  const name = String(data?.['name'] ?? '').trim()\n  return {\n    id,\n    // A nameless stored document falls back to the id rather than rendering a\n    // blank checkbox on the preference page. The console refuses to create\n    // one; a restore or an API write is not bound by that.\n    name: name || id,\n    description: String(data?.['description'] ?? '').trim(),\n    ...(data?.['archived'] === true ? { archived: true as const } : {}),\n    /*\n     * Carried only when the document actually holds a boolean.\n     *\n     * A missing field and a stored `false` are different answers here —\n     * `topicRequiresDoubleOptIn` reads absence as \"ask the site\" and `false`\n     * as \"not this stream, whatever the site says\" — so coercing with `===\n     * true` the way `archived` does would erase the second of the three\n     * states this field has.\n     */\n    ...(typeof data?.['doubleOptIn'] === 'boolean'\n      ? { doubleOptIn: data['doubleOptIn'] as boolean }\n      : {}),\n  }\n}\n\n/**\n * The catalog a reader sees: the built-in floor, overlaid by whatever the org\n * has stored, plus the org's own topics.\n *\n * Overlay rather than replace, so an org that adds one custom topic does not\n * thereby delete the four every one of its recipients has been unsubscribing\n * against. A built-in is removed by storing it `archived`, which is a\n * decision someone made rather than a side effect of making a different one.\n *\n * Sorted with the built-ins first in their declared order and custom topics\n * alphabetically after, so the preference page's checkbox order is stable\n * across renders and across sites.\n */\nexport function mergeSubscriptionTopics(\n  stored: readonly SubscriptionTopic[] | null | undefined,\n): SubscriptionTopic[] {\n  const overrides = new Map<string, SubscriptionTopic>()\n  for (const topic of stored ?? []) {\n    if (isSubscriptionTopicId(topic?.id)) overrides.set(topic.id, topic)\n  }\n  const builtIn = DECLARED_SUBSCRIPTION_TOPICS.map(\n    (topic) => overrides.get(topic.id) ?? topic,\n  )\n  const custom = [...overrides.values()]\n    .filter((topic) => !DECLARED_SUBSCRIPTION_TOPICS.some((it) => it.id === topic.id))\n    .sort((a, b) => a.name.localeCompare(b.name))\n  return [...builtIn, ...custom]\n}\n\n/**\n * The catalog minus retired topics — what a composer's picker and a\n * preference page's checkboxes offer.\n *\n * The send path deliberately does NOT filter through this: a scheduled\n * campaign whose topic was archived between scheduling and sending still\n * belongs to that topic, and re-pointing it at something else would attribute\n * the unsubscribes to the wrong stream.\n */\nexport function activeSubscriptionTopics(\n  topics: readonly SubscriptionTopic[],\n): SubscriptionTopic[] {\n  return topics.filter((topic) => !topic.archived)\n}\n\n/**\n * The topic a campaign belongs to, given what it stored and what the org\n * offers.\n *\n * Resolves an unknown or missing id to the default rather than to nothing: a\n * campaign sent before topics existed carries no `topicId`, and its\n * unsubscribe links are in inboxes right now. They must land on a preference\n * page that names A topic, not on one that says the message came from\n * nowhere.\n */\nexport function resolveSubscriptionTopic(\n  topicId: string | null | undefined,\n  topics: readonly SubscriptionTopic[],\n): SubscriptionTopic {\n  const found = topicId\n    ? topics.find((topic) => topic.id === topicId)\n    : undefined\n  if (found) return found\n  return (\n    topics.find((topic) => topic.id === DEFAULT_SUBSCRIPTION_TOPIC_ID) ??\n    topics[0] ?? {\n      id: DEFAULT_SUBSCRIPTION_TOPIC_ID,\n      name: 'Email',\n      description: '',\n    }\n  )\n}\n"],"names":["PLUGIN_SUBSCRIPTION_TOPICS_DECLARED","DEFAULT_SITE_DOUBLE_OPT_IN","DOUBLE_OPT_IN_EXPIRY_MS","topicRequiresDoubleOptIn","topic","siteDefault","doubleOptIn","readTopicSubscriptionState","entry","optedOutAt","resubscribedAt","pendingAt","confirmedAt","doubleOptInExpired","pendingAtMs","nowMs","at","Number","isFinite","TOPIC_OPT_OUTS_SUBCOLLECTION","DECLARED_SUBSCRIPTION_TOPICS","map","id","name","description","DEFAULT_SUBSCRIPTION_TOPIC_ID","find","default","flowSubscriptionTopicId","topicId","scope","named","String","trim","isSubscriptionTopicId","value","length","includes","test","normalizeSubscriptionTopic","data","archived","mergeSubscriptionTopics","stored","overrides","Map","set","builtIn","get","custom","values","filter","some","it","sort","a","b","localeCompare","activeSubscriptionTopics","topics","resolveSubscriptionTopic","found","undefined"],"mappings":";;IA4SEA;AA5SF;;;;;;;;;;;;;;;CAeC,GAED,SAASA,mCAAmC,QAAQ,4DAAwD;AAoF5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CC,GACD,OAAO,MAAMC,6BAA6B,MAAK;AAE/C;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC,0BAA0B,KAAK,KAAK,KAAK,KAAI;AAE1D;;;;;;CAMC,GACD,OAAO,SAASC,yBACdC,KAAgE,EAChEC,cAAuBJ,0BAA0B;IAEjD,OAAO,QAAOG,yBAAAA,MAAOE,WAAW,MAAK,YACjCF,MAAME,WAAW,GACjBD,gBAAgB;AACtB;AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,SAASE,2BACdC,KAAgD;IAEhD,IAAI,CAACA,OAAO,OAAO;IACnB,IAAIA,MAAMC,UAAU,IAAI,CAACD,MAAME,cAAc,EAAE,OAAO;IACtD,IAAIF,MAAMG,SAAS,IAAI,CAACH,MAAMI,WAAW,EAAE,OAAO;IAClD,OAAO;AACT;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,mBACdC,WAAsC,EACtCC,KAAa;IAEb,MAAMC,KAAKC,OAAOH;IAClB,IAAI,CAACG,OAAOC,QAAQ,CAACF,OAAOA,MAAM,GAAG,OAAO;IAC5C,OAAOD,QAAQC,KAAKd;AACtB;AAEA,2EAA2E,GAC3E,OAAO,MAAMiB,+BAA+B,eAAc;AAoB1D;;;;;;;;;CASC,GACD,OAAO,MAAMC,+BACXpB,oCAAoCqB,GAAG,CAAC,CAAC,EAAEC,EAAE,EAAEC,IAAI,EAAEC,WAAW,EAAE,GAAM,CAAA;QACtEF;QACAC;QACAC;IACF,CAAA,GAAG;AAEL;;;;;;;;CAQC,GACD,OAAO,MAAMC,yCACXzB,4CAAAA,oCAAoC0B,IAAI,CAAC,CAACtB,QAAUA,MAAMuB,OAAO,sBAAjE3B,0CAAoEsB,EAAE,mBAAI,GAAE;AAE9E;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASM,wBACdC,OAAkC,EAClCC,KAAiC;IAEjC,MAAMC,QAAQC,OAAOH,kBAAAA,UAAW,IAAII,IAAI;IACxC,OAAOH,UAAU,cAAcC,QAAQA,SAASN;AAClD;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASS,sBAAsBC,KAAc;IAClD,OACE,OAAOA,UAAU,YACjBA,MAAMC,MAAM,GAAG,KACfD,MAAMC,MAAM,IAAI,OAChB,CAACD,MAAME,QAAQ,CAAC,QAChB,CAACF,MAAME,QAAQ,CAAC,QAChBF,UAAU,OACVA,UAAU,QACV,CAAC,WAAWG,IAAI,CAACH;AAErB;AAEA,0EAA0E,GAC1E,OAAO,SAASI,2BACdjB,EAAW,EACXkB,IAAgD;;IAEhD,IAAI,CAACN,sBAAsBZ,KAAK,OAAO;IACvC,MAAMC,OAAOS,eAAOQ,wBAAAA,IAAM,CAAC,OAAO,mBAAI,IAAIP,IAAI;IAC9C,OAAO;QACLX;QACA,0EAA0E;QAC1E,uEAAuE;QACvE,uDAAuD;QACvDC,MAAMA,QAAQD;QACdE,aAAaQ,gBAAOQ,wBAAAA,IAAM,CAAC,cAAc,oBAAI,IAAIP,IAAI;OACjDO,CAAAA,wBAAAA,IAAM,CAAC,WAAW,MAAK,OAAO;QAAEC,UAAU;IAAc,IAAI,CAAC,GAU7D,QAAOD,wBAAAA,IAAM,CAAC,cAAc,MAAK,YACjC;QAAElC,aAAakC,IAAI,CAAC,cAAc;IAAY,IAC9C,CAAC;AAET;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASE,wBACdC,MAAuD;IAEvD,MAAMC,YAAY,IAAIC;IACtB,KAAK,MAAMzC,SAASuC,iBAAAA,SAAU,EAAE,CAAE;QAChC,IAAIT,sBAAsB9B,yBAAAA,MAAOkB,EAAE,GAAGsB,UAAUE,GAAG,CAAC1C,MAAMkB,EAAE,EAAElB;IAChE;IACA,MAAM2C,UAAU3B,6BAA6BC,GAAG,CAC9C,CAACjB;YAAUwC;gBAAAA,iBAAAA,UAAUI,GAAG,CAAC5C,MAAMkB,EAAE,aAAtBsB,iBAA2BxC;;IAExC,MAAM6C,SAAS;WAAIL,UAAUM,MAAM;KAAG,CACnCC,MAAM,CAAC,CAAC/C,QAAU,CAACgB,6BAA6BgC,IAAI,CAAC,CAACC,KAAOA,GAAG/B,EAAE,KAAKlB,MAAMkB,EAAE,GAC/EgC,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEhC,IAAI,CAACkC,aAAa,CAACD,EAAEjC,IAAI;IAC7C,OAAO;WAAIwB;WAAYE;KAAO;AAChC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASS,yBACdC,MAAoC;IAEpC,OAAOA,OAAOR,MAAM,CAAC,CAAC/C,QAAU,CAACA,MAAMqC,QAAQ;AACjD;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASmB,yBACd/B,OAAkC,EAClC8B,MAAoC;QAOlCA,MAAAA;IALF,MAAME,QAAQhC,UACV8B,OAAOjC,IAAI,CAAC,CAACtB,QAAUA,MAAMkB,EAAE,KAAKO,WACpCiC;IACJ,IAAID,OAAO,OAAOA;IAClB,QACEF,QAAAA,eAAAA,OAAOjC,IAAI,CAAC,CAACtB,QAAUA,MAAMkB,EAAE,KAAKG,0CAApCkC,eACAA,MAAM,CAAC,EAAE,YADTA,OACa;QACXrC,IAAIG;QACJF,MAAM;QACNC,aAAa;IACf;AAEJ"}

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

@@ -40,9 +40,9 @@
  *   - **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
@@ -173,6 +173,24 @@ export declare function budgetAlertDue(input: {
     guard: UsageAlertGuard | null | undefined;
     month: string;
 }): number;
+/**
+ * One plugin's line of the month's spend, as its `spendLines` declaration
+ * names it (`plugin-usage-axes.ts`).
+ */
+export interface OrgSpendLine {
+    id: string;
+    pluginId: string;
+    label: string;
+    /**
+     * The month's figure in dollars at the rates the plugin bills, read off the
+     * document the declaration names. For a line declared with a `unit` these
+     * dollars are the platform's cost and never cross to a customer's browser
+     * (see {@link publicOrgMonthlySpend}).
+     */
+    usd: number;
+    /** Whether `usd` entered `totalUsd` — see {@link billsFromMonth}. */
+    billed: boolean;
+}
 /**
  * What an org is spending this month, split by where it comes from.
  *
@@ -187,26 +205,21 @@ export interface OrgSpendBreakdown {
      */
     meteredUsd: number;
     /**
-     * Aglyn Assist token spend for the month, at the serving model's list
-     * rates (`orgs/{id}/assistUsage/{month}.estCostUsd`).
+     * Each plugin's line, in catalog order.
      *
-     * 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.
+     * ALWAYS REPORTED, and counted toward the budget only once the line's own
+     * start month says this month is charged for it. Until then the plugin's
+     * usage is an entitlement with no price anywhere in the platform, and adding
+     * it to a customer's "you will owe" figure would be a surprise bill invented
+     * by a notification — 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.
+     * Carried rather than left out for two reasons that both bite: the day a
+     * line is priced this is a deployment variable instead of a new pipeline,
+     * and a plugin's staff alert reads its own line as the platform's cost.
      */
-    assistUsd: number;
-    /** What counts against the budget: metered, plus assist when it bills. */
+    lines: readonly OrgSpendLine[];
+    /** What counts against the budget: metered, plus every billed line. */
     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.
@@ -221,22 +234,23 @@ export interface OrgSpendBreakdown {
     meteredFresh: boolean;
 }
 /**
- * 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.
+ * Anything but a `YYYY-MM` — `true`, `1`, a date, a typo — bills nothing.
  */
-export declare function billsAssistTokens(month: string, configuredStart: string | null | undefined): boolean;
+export declare function billsFromMonth(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}.
+ * {@link OrgSpendBreakdown.meteredFresh}. Every declared spend line is
+ * reported, read as nothing when its document was not read.
  */
 export declare function orgMonthlySpend(input: {
     month: string;
@@ -244,186 +258,57 @@ export declare function orgMonthlySpend(input: {
     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;
+    /**
+     * Each declared spend line's figure, keyed by line id: the `live.field` of
+     * its month document, as read.
+     */
+    lineReadings?: Readonly<Record<string, unknown>>;
+    /** The deployment's variables, holding each line's start month. */
+    env?: Readonly<Record<string, string | undefined>>;
 }): OrgSpendBreakdown;
+/** A spend line as a customer's browser receives it. */
+export interface PublicOrgSpendLine {
+    id: string;
+    label: string;
+    billed: boolean;
+    /**
+     * The month's figure in the line's declared unit (`ceil(dollars / unit
+     * cost)`), or `null` for a line declared without one.
+     */
+    units: number | null;
+    /** What the unit is called, or `null` for a line without one. */
+    unitLabel: string | null;
+    /** Dollars, only for a line declared WITHOUT a unit; `null` otherwise. */
+    usd: number | null;
+}
 /**
  * The customer-facing half of {@link OrgSpendBreakdown} — dollars the customer
- * is charged, and Assist consumption in CREDITS.
+ * is charged, and each plugin's line in the unit it declared.
  */
 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;
+    lines: PublicOrgSpendLine[];
     /** 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
+ * 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 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;