@aglyn/aglyn 1.0.0-beta.270 → 1.0.0-beta.272

package/src/lib/app-utils/owner-approval-record.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/owner-approval-record.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 * THE OWNER'S RECORDED YES (AGL-3959).\n *\n * Paid work beyond what a subscription includes is billed only after the\n * owner agreed to it, and the owner never clicks anything in the console to\n * agree: they say yes to a person — at the booth, on the phone, by text or by\n * email — and STAFF record how and when. Saving the record emails the owner a\n * confirmation, and that email is the written record.\n *\n * This module is the record's shape and its rules, with no Firestore and no\n * product in it, so any staff surface that bills by an approval reads it the\n * same way: Site Care's extra time first, and the flat-quoted project invoice\n * (AGL-3970) after it. A correction never edits a record in place: it is a\n * new record with `version` one higher, `corrected: true` and the reason, and\n * the old one stays in the request's history.\n */\n\n/** How the owner said yes. */\nexport const OWNER_APPROVAL_CHANNELS = ['in-person', 'phone', 'text', 'email'] as const\n\nexport type OwnerApprovalChannel = (typeof OWNER_APPROVAL_CHANNELS)[number]\n\n/** The channel as a sentence reads it: \"by phone\", \"in person\". */\nexport const OWNER_APPROVAL_CHANNEL_WORDS: Readonly<Record<OwnerApprovalChannel, string>> = {\n  'in-person': 'in person',\n  phone: 'by phone',\n  text: 'by text message',\n  email: 'by email',\n}\n\n/** The channel as a picker labels it. */\nexport const OWNER_APPROVAL_CHANNEL_LABELS: Readonly<Record<OwnerApprovalChannel, string>> = {\n  'in-person': 'In person',\n  phone: 'Phone call',\n  text: 'Text message',\n  email: 'Email',\n}\n\n/** The longest approval an hourly record may carry, in hours. */\nexport const OWNER_APPROVAL_MAX_HOURS = 40\n\n/** The longest note or reason a record keeps. */\nexport const OWNER_APPROVAL_NOTE_MAX = 500\n\n/** One recorded yes. Written by staff, read by the close and the emails. */\nexport interface OwnerApprovalRecord {\n  /** Whole hours the owner agreed to, at most. */\n  hours: number\n  /** The published hourly rate the owner agreed to, in whole dollars. */\n  rateUsd: number\n  channel: OwnerApprovalChannel\n  /** When the owner said yes, epoch ms. */\n  approvedAtMs: number\n  /** When staff recorded it, epoch ms. */\n  recordedAtMs: number\n  recordedByUid: string\n  recordedByEmail: string | null\n  /** What the owner said yes to, in staff's words; optional. */\n  note: string | null\n  /** 1 for the first record; each correction is one higher. */\n  version: number\n  /** True on every record after the first. */\n  corrected: boolean\n  /** Why it was corrected; required when `corrected`. */\n  correctionReason: string | null\n}\n\nexport type OwnerApprovalInputResult =\n  | { ok: true; record: OwnerApprovalRecord }\n  | { ok: false; error: string }\n\n/** A trimmed, bounded string, or null when blank. */\nfunction cleanText(value: unknown, max: number): string | null {\n  const text = typeof value === 'string' ? value.trim().slice(0, max) : ''\n  return text ? text : null\n}\n\n/**\n * Reads what staff typed into a record, refusing anything the record cannot\n * honestly say. `previous` is the record it corrects, when there is one: a\n * correction needs a reason, and the reason is what the history and the\n * re-sent confirmation say changed.\n */\nexport function readOwnerApprovalInput(\n  raw: Readonly<Record<string, unknown>> | null | undefined,\n  context: {\n    rateUsd: number\n    nowMs: number\n    by: { uid: string; email: string | null }\n    previous?: OwnerApprovalRecord | null\n    /**\n     * The most hours the record may carry; `OWNER_APPROVAL_MAX_HOURS` unless\n     * the surface says otherwise. A flat-quoted project (AGL-3970) records\n     * the quote's own whole hours, which a redesign can take past a week.\n     */\n    maxHours?: number\n  },\n): OwnerApprovalInputResult {\n  const hours = Number(raw?.['hours'])\n  const maxHours = context.maxHours ?? OWNER_APPROVAL_MAX_HOURS\n  if (!Number.isInteger(hours) || hours < 1 || hours > maxHours) {\n    return {\n      ok: false,\n      error: `Enter the hours the owner approved, a whole number from 1 to ${maxHours}.`,\n    }\n  }\n  const channel = String(raw?.['channel'] ?? '') as OwnerApprovalChannel\n  if (!OWNER_APPROVAL_CHANNELS.includes(channel)) {\n    return { ok: false, error: 'Choose how the owner said yes.' }\n  }\n  const approvedAtMs = Number(raw?.['approvedAtMs'])\n  if (!Number.isFinite(approvedAtMs) || approvedAtMs <= 0) {\n    return { ok: false, error: 'Enter when the owner said yes.' }\n  }\n  // A minute of clock skew is allowed; a yes recorded for tomorrow is not one\n  // anybody has heard yet.\n  if (approvedAtMs > context.nowMs + 60_000) {\n    return { ok: false, error: 'The owner’s yes cannot be in the future.' }\n  }\n  const previous = context.previous ?? null\n  const correctionReason = cleanText(raw?.['reason'], OWNER_APPROVAL_NOTE_MAX)\n  if (previous && !correctionReason) {\n    return { ok: false, error: 'Say why the approval is being corrected.' }\n  }\n  return {\n    ok: true,\n    record: {\n      hours,\n      rateUsd: context.rateUsd,\n      channel,\n      approvedAtMs: Math.floor(approvedAtMs),\n      recordedAtMs: context.nowMs,\n      recordedByUid: context.by.uid,\n      recordedByEmail: context.by.email,\n      note: cleanText(raw?.['note'], OWNER_APPROVAL_NOTE_MAX),\n      version: previous ? Math.max(1, Number(previous.version) || 1) + 1 : 1,\n      corrected: Boolean(previous),\n      correctionReason: previous ? correctionReason : null,\n    },\n  }\n}\n\n/** A stored record read back defensively, or null when it is not one. */\nexport function readOwnerApprovalRecord(value: unknown): OwnerApprovalRecord | null {\n  if (!value || typeof value !== 'object') return null\n  const record = value as Partial<OwnerApprovalRecord>\n  const hours = Number(record.hours)\n  if (!Number.isInteger(hours) || hours < 1) return null\n  if (!OWNER_APPROVAL_CHANNELS.includes(record.channel as OwnerApprovalChannel)) return null\n  return {\n    hours,\n    rateUsd: Number(record.rateUsd) || 0,\n    channel: record.channel as OwnerApprovalChannel,\n    approvedAtMs: Number(record.approvedAtMs) || 0,\n    recordedAtMs: Number(record.recordedAtMs) || 0,\n    recordedByUid: String(record.recordedByUid ?? ''),\n    recordedByEmail: record.recordedByEmail ?? null,\n    note: record.note ?? null,\n    version: Number(record.version) || 1,\n    corrected: record.corrected === true,\n    correctionReason: record.correctionReason ?? null,\n  }\n}\n\n/** \"2 hours\", \"1 hour\". */\nexport function describeHours(hours: number): string {\n  return `${hours} ${hours === 1 ? 'hour' : 'hours'}`\n}\n\n/**\n * The confirmation's one sentence, in the owner's words: what they agreed\n * to, how and when.\n */\nexport function ownerApprovalSentence(\n  record: Pick<OwnerApprovalRecord, 'hours' | 'rateUsd' | 'channel' | 'approvedAtMs'>,\n  what: string,\n  formatDate: (ms: number) => string,\n): string {\n  return (\n    `You approved up to ${describeHours(record.hours)} of extra time at ` +\n    `$${record.rateUsd} an hour for “${what}”, ` +\n    `${OWNER_APPROVAL_CHANNEL_WORDS[record.channel]} on ${formatDate(record.approvedAtMs)}.`\n  )\n}\n"],"names":["OWNER_APPROVAL_CHANNELS","OWNER_APPROVAL_CHANNEL_WORDS","phone","text","email","OWNER_APPROVAL_CHANNEL_LABELS","OWNER_APPROVAL_MAX_HOURS","OWNER_APPROVAL_NOTE_MAX","cleanText","value","max","trim","slice","readOwnerApprovalInput","raw","context","hours","Number","maxHours","isInteger","ok","error","channel","String","includes","approvedAtMs","isFinite","nowMs","previous","correctionReason","record","rateUsd","Math","floor","recordedAtMs","recordedByUid","by","uid","recordedByEmail","note","version","corrected","Boolean","readOwnerApprovalRecord","describeHours","ownerApprovalSentence","what","formatDate"],"mappings":"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"}

package/src/lib/app-utils/plan-card-meters.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @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.
+ */
+/**
+ * The native apps' plan card (AGL-3992): the usage meters it rotates through,
+ * which one leads for what is on screen, and in what order the rest follow.
+ *
+ * ONE mapping for both apps, generated into the native contracts, so the
+ * Apple and Kotlin cards cannot drift. Every meter here is one the console's
+ * Billing › Usage page already meters, read from the same source it reads,
+ * against the same entitlement; none is invented for the card:
+ *
+ * | meter            | Usage page label                              | used                                   | limit                       |
+ * | ---------------- | --------------------------------------------- | -------------------------------------- | --------------------------- |
+ * | `storage`        | Storage (organization)                        | `/api/media/storage` usedBytes         | its allowanceMb             |
+ * | `bandwidth`      | Bandwidth (this month, organization)          | `/api/billing/host-usage`, every site + the org | `bandwidthGb`       |
+ * | `emailSends`     | Campaign emails (this month, organization)    | `orgs/{org}/counters/campaignEmailSends` | `emailSendsPerMonth`      |
+ * | `aiCredits`      | AI credits (this month)                       | `/api/ai/billing/credits`              | `assistCreditsPerMonth`     |
+ * | `dataStorage`    | Data storage (organization)                   | `orgs/{org}/usage/{month}` dataStorageMb | `dataStorageMbPerOrg`     |
+ * | `seats`          | Team seats (incl. you)                        | `/api/orgs/members?counts=1`           | the managers seat quota     |
+ * | `pages`          | Pages (a site's)                              | `/api/hosts/usage` screens             | `screensPerHost`            |
+ * | `forms`          | Saved forms (a site's)                        | `hosts/{host}/forms` count             | `formsPerHost`              |
+ * | `sites`          | Sites                                         | the workspace's sites                  | `hostLimit`                 |
+ *
+ * A label is the page's own, without its parenthesis ("(this month,
+ * organization)", "(incl. you)"): the card is one line wide and already headed
+ * by the workspace and plan, and a tap opens the Usage page that says the rest.
+ */
+declare const METERS: readonly ["storage", "bandwidth", "emailSends", "aiCredits", "dataStorage", "seats", "pages", "forms", "sites"];
+export type PlanCardMeter = (typeof METERS)[number];
+/**
+ * The meters the card can show, in the order a tie between two equally full
+ * meters is broken. Plain `string[]` and records below, as the native
+ * contracts generator reads values; `satisfies` keeps them total.
+ */
+export declare const PLAN_CARD_METERS: string[];
+/** Each meter's label: the Usage page's own words, without their parenthesis. */
+export declare const PLAN_CARD_METER_LABELS: Record<string, string>;
+/** The unit a meter's figures are written in, as the Usage page writes them; empty for a count. */
+export declare const PLAN_CARD_METER_UNITS: Record<string, string>;
+declare const CONTEXTS: readonly ["media", "website", "email", "ai", "forms", "data", "team", "sites"];
+export type PlanCardContext = (typeof CONTEXTS)[number];
+/** What the screen in front is about, for the meter that leads. */
+export declare const PLAN_CARD_CONTEXTS: string[];
+/** The meters that lead for each context, in order; the rest follow by how full they are. */
+export declare const PLAN_CARD_CONTEXT_METERS: Record<string, string[]>;
+/**
+ * Each screen's context, by the screen id the native nav manifest opens (its
+ * rows' `screen`). A screen not named here has none, and the fullest meter
+ * leads. A site's Home is the website's front door; the workspace's Home has
+ * no context (`planCardContext`).
+ */
+export declare const PLAN_CARD_SCREEN_CONTEXTS: Record<string, string>;
+/** The screen id of Home, which is a site's website when the window stands in a site. */
+export declare const PLAN_CARD_HOME_SCREEN = "shell.home";
+/** How long one meter stays before the card moves on, slowly (Zach: "auto rotates slowly"). */
+export declare const PLAN_CARD_ADVANCE_MS = 8000;
+/** The share from which a meter warns, as the console's meter does (`USAGE_METER_WARNING_PCT`, 80). */
+export declare const PLAN_CARD_WARNING_SHARE = 0.8;
+/** One meter's reading: `null` where the read failed or the plan does not cap it. */
+export interface PlanCardReading {
+    meter: string;
+    used: number | null;
+    limit: number | null;
+}
+/** The context of the screen in front: a site's Home is its website; a screen not mapped has none. */
+export declare function planCardContext(screen: string | null, inSite: boolean): string | null;
+/**
+ * The order the card shows its meters in: the context's own meters first, in
+ * the mapping's order, then every other meter fullest first (a tie keeps
+ * `PLAN_CARD_METERS`' order). A meter that failed to read or that the plan
+ * does not cap is left out. Sites leads only on the Sites list: elsewhere it
+ * follows every other meter, however full, because a missing site is the
+ * limit a workspace is least likely to upgrade for.
+ */
+export declare function planCardMeterOrder(readings: readonly PlanCardReading[], context: string | null): string[];
+/**
+ * Whether the card shows at all: a meter to draw, and either a plan the viewer
+ * can upgrade (the workspace menu's "Upgrade plan" rule) or a meter at its
+ * warning share, which every plan is told about.
+ */
+export declare function planCardShows(readings: readonly PlanCardReading[], offersUpgrade: boolean): boolean;
+export {};

package/src/lib/app-utils/plan-card-meters.js

@@ -0,0 +1,197 @@
+/**
+ * @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.
+ */ /**
+ * The native apps' plan card (AGL-3992): the usage meters it rotates through,
+ * which one leads for what is on screen, and in what order the rest follow.
+ *
+ * ONE mapping for both apps, generated into the native contracts, so the
+ * Apple and Kotlin cards cannot drift. Every meter here is one the console's
+ * Billing › Usage page already meters, read from the same source it reads,
+ * against the same entitlement; none is invented for the card:
+ *
+ * | meter            | Usage page label                              | used                                   | limit                       |
+ * | ---------------- | --------------------------------------------- | -------------------------------------- | --------------------------- |
+ * | `storage`        | Storage (organization)                        | `/api/media/storage` usedBytes         | its allowanceMb             |
+ * | `bandwidth`      | Bandwidth (this month, organization)          | `/api/billing/host-usage`, every site + the org | `bandwidthGb`       |
+ * | `emailSends`     | Campaign emails (this month, organization)    | `orgs/{org}/counters/campaignEmailSends` | `emailSendsPerMonth`      |
+ * | `aiCredits`      | AI credits (this month)                       | `/api/ai/billing/credits`              | `assistCreditsPerMonth`     |
+ * | `dataStorage`    | Data storage (organization)                   | `orgs/{org}/usage/{month}` dataStorageMb | `dataStorageMbPerOrg`     |
+ * | `seats`          | Team seats (incl. you)                        | `/api/orgs/members?counts=1`           | the managers seat quota     |
+ * | `pages`          | Pages (a site's)                              | `/api/hosts/usage` screens             | `screensPerHost`            |
+ * | `forms`          | Saved forms (a site's)                        | `hosts/{host}/forms` count             | `formsPerHost`              |
+ * | `sites`          | Sites                                         | the workspace's sites                  | `hostLimit`                 |
+ *
+ * A label is the page's own, without its parenthesis ("(this month,
+ * organization)", "(incl. you)"): the card is one line wide and already headed
+ * by the workspace and plan, and a tap opens the Usage page that says the rest.
+ */ const METERS = [
+    'storage',
+    'bandwidth',
+    'emailSends',
+    'aiCredits',
+    'dataStorage',
+    'seats',
+    'pages',
+    'forms',
+    'sites'
+];
+/**
+ * The meters the card can show, in the order a tie between two equally full
+ * meters is broken. Plain `string[]` and records below, as the native
+ * contracts generator reads values; `satisfies` keeps them total.
+ */ export const PLAN_CARD_METERS = [
+    ...METERS
+];
+/** Each meter's label: the Usage page's own words, without their parenthesis. */ export const PLAN_CARD_METER_LABELS = {
+    storage: 'Storage',
+    bandwidth: 'Bandwidth',
+    emailSends: 'Campaign emails',
+    aiCredits: 'AI credits',
+    dataStorage: 'Data storage',
+    seats: 'Team seats',
+    pages: 'Pages',
+    forms: 'Saved forms',
+    sites: 'Sites'
+};
+/** The unit a meter's figures are written in, as the Usage page writes them; empty for a count. */ export const PLAN_CARD_METER_UNITS = {
+    storage: 'MB',
+    bandwidth: 'GB',
+    emailSends: '',
+    aiCredits: '',
+    dataStorage: 'MB',
+    seats: '',
+    pages: '',
+    forms: '',
+    sites: ''
+};
+const CONTEXTS = [
+    'media',
+    'website',
+    'email',
+    'ai',
+    'forms',
+    'data',
+    'team',
+    'sites'
+];
+/** What the screen in front is about, for the meter that leads. */ export const PLAN_CARD_CONTEXTS = [
+    ...CONTEXTS
+];
+/** The meters that lead for each context, in order; the rest follow by how full they are. */ export const PLAN_CARD_CONTEXT_METERS = {
+    media: [
+        'storage'
+    ],
+    website: [
+        'bandwidth'
+    ],
+    email: [
+        'emailSends'
+    ],
+    ai: [
+        'aiCredits'
+    ],
+    forms: [
+        'forms'
+    ],
+    data: [
+        'dataStorage'
+    ],
+    team: [
+        'seats'
+    ],
+    sites: [
+        'sites'
+    ]
+};
+/**
+ * Each screen's context, by the screen id the native nav manifest opens (its
+ * rows' `screen`). A screen not named here has none, and the fullest meter
+ * leads. A site's Home is the website's front door; the workspace's Home has
+ * no context (`planCardContext`).
+ */ export const PLAN_CARD_SCREEN_CONTEXTS = {
+    'site.media': 'media',
+    'site.pages': 'website',
+    'logic.page': 'website',
+    'shell.analytics': 'website',
+    'email.messages': 'email',
+    'marketing.overview': 'email',
+    'outreach.sequences': 'email',
+    'ai.jobs': 'ai',
+    'ai.credits': 'ai',
+    'forms.list': 'forms',
+    'data.datasets': 'data',
+    'core.team': 'team',
+    'core.team.roles': 'team',
+    'core.team.activity': 'team',
+    'core.site.users': 'team',
+    'site.sites': 'sites'
+};
+/** The screen id of Home, which is a site's website when the window stands in a site. */ export const PLAN_CARD_HOME_SCREEN = 'shell.home';
+/** How long one meter stays before the card moves on, slowly (Zach: "auto rotates slowly"). */ export const PLAN_CARD_ADVANCE_MS = 8000;
+/** The share from which a meter warns, as the console's meter does (`USAGE_METER_WARNING_PCT`, 80). */ export const PLAN_CARD_WARNING_SHARE = 0.8;
+/** The context of the screen in front: a site's Home is its website; a screen not mapped has none. */ export function planCardContext(screen, inSite) {
+    var _PLAN_CARD_SCREEN_CONTEXTS_screen;
+    if (!screen) return null;
+    if (screen === PLAN_CARD_HOME_SCREEN) return inSite ? 'website' : null;
+    return (_PLAN_CARD_SCREEN_CONTEXTS_screen = PLAN_CARD_SCREEN_CONTEXTS[screen]) != null ? _PLAN_CARD_SCREEN_CONTEXTS_screen : null;
+}
+/** A meter the card can draw: read, capped (an unlimited quota arrives as `null`), and with something to cap. */ function drawable(reading) {
+    return typeof reading.used === 'number' && Number.isFinite(reading.used) && typeof reading.limit === 'number' && Number.isFinite(reading.limit) && reading.limit > 0;
+}
+function rank(meter) {
+    const index = PLAN_CARD_METERS.indexOf(meter);
+    return index < 0 ? PLAN_CARD_METERS.length : index;
+}
+/**
+ * The order the card shows its meters in: the context's own meters first, in
+ * the mapping's order, then every other meter fullest first (a tie keeps
+ * `PLAN_CARD_METERS`' order). A meter that failed to read or that the plan
+ * does not cap is left out. Sites leads only on the Sites list: elsewhere it
+ * follows every other meter, however full, because a missing site is the
+ * limit a workspace is least likely to upgrade for.
+ */ export function planCardMeterOrder(readings, context) {
+    const shown = readings.filter(drawable);
+    const seen = new Set();
+    const unique = shown.filter((reading)=>{
+        if (seen.has(reading.meter)) return false;
+        seen.add(reading.meter);
+        return true;
+    });
+    const leading = context && PLAN_CARD_CONTEXT_METERS[context] || [];
+    const lead = leading.filter((meter)=>unique.some((reading)=>reading.meter === meter));
+    const rest = unique.filter((reading)=>!lead.includes(reading.meter)).sort((a, b)=>{
+        const aSites = a.meter === 'sites';
+        const bSites = b.meter === 'sites';
+        if (aSites !== bSites) return aSites ? 1 : -1;
+        const byShare = b.used / b.limit - a.used / a.limit;
+        return byShare !== 0 ? byShare : rank(a.meter) - rank(b.meter);
+    }).map((reading)=>reading.meter);
+    return [
+        ...lead,
+        ...rest
+    ];
+}
+/**
+ * Whether the card shows at all: a meter to draw, and either a plan the viewer
+ * can upgrade (the workspace menu's "Upgrade plan" rule) or a meter at its
+ * warning share, which every plan is told about.
+ */ export function planCardShows(readings, offersUpgrade) {
+    const shown = readings.filter(drawable);
+    if (!shown.length) return false;
+    return offersUpgrade || shown.some((reading)=>reading.used / reading.limit >= PLAN_CARD_WARNING_SHARE);
+}
+
+//# sourceMappingURL=plan-card-meters.js.map

package/src/lib/app-utils/plan-card-meters.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/plan-card-meters.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 * The native apps' plan card (AGL-3992): the usage meters it rotates through,\n * which one leads for what is on screen, and in what order the rest follow.\n *\n * ONE mapping for both apps, generated into the native contracts, so the\n * Apple and Kotlin cards cannot drift. Every meter here is one the console's\n * Billing › Usage page already meters, read from the same source it reads,\n * against the same entitlement; none is invented for the card:\n *\n * | meter            | Usage page label                              | used                                   | limit                       |\n * | ---------------- | --------------------------------------------- | -------------------------------------- | --------------------------- |\n * | `storage`        | Storage (organization)                        | `/api/media/storage` usedBytes         | its allowanceMb             |\n * | `bandwidth`      | Bandwidth (this month, organization)          | `/api/billing/host-usage`, every site + the org | `bandwidthGb`       |\n * | `emailSends`     | Campaign emails (this month, organization)    | `orgs/{org}/counters/campaignEmailSends` | `emailSendsPerMonth`      |\n * | `aiCredits`      | AI credits (this month)                       | `/api/ai/billing/credits`              | `assistCreditsPerMonth`     |\n * | `dataStorage`    | Data storage (organization)                   | `orgs/{org}/usage/{month}` dataStorageMb | `dataStorageMbPerOrg`     |\n * | `seats`          | Team seats (incl. you)                        | `/api/orgs/members?counts=1`           | the managers seat quota     |\n * | `pages`          | Pages (a site's)                              | `/api/hosts/usage` screens             | `screensPerHost`            |\n * | `forms`          | Saved forms (a site's)                        | `hosts/{host}/forms` count             | `formsPerHost`              |\n * | `sites`          | Sites                                         | the workspace's sites                  | `hostLimit`                 |\n *\n * A label is the page's own, without its parenthesis (\"(this month,\n * organization)\", \"(incl. you)\"): the card is one line wide and already headed\n * by the workspace and plan, and a tap opens the Usage page that says the rest.\n */\n\nconst METERS = [\n  'storage',\n  'bandwidth',\n  'emailSends',\n  'aiCredits',\n  'dataStorage',\n  'seats',\n  'pages',\n  'forms',\n  'sites',\n] as const\n\nexport type PlanCardMeter = (typeof METERS)[number]\n\n/**\n * The meters the card can show, in the order a tie between two equally full\n * meters is broken. Plain `string[]` and records below, as the native\n * contracts generator reads values; `satisfies` keeps them total.\n */\nexport const PLAN_CARD_METERS: string[] = [...METERS]\n\n/** Each meter's label: the Usage page's own words, without their parenthesis. */\nexport const PLAN_CARD_METER_LABELS: Record<string, string> = {\n  storage: 'Storage',\n  bandwidth: 'Bandwidth',\n  emailSends: 'Campaign emails',\n  aiCredits: 'AI credits',\n  dataStorage: 'Data storage',\n  seats: 'Team seats',\n  pages: 'Pages',\n  forms: 'Saved forms',\n  sites: 'Sites',\n} satisfies Record<PlanCardMeter, string>\n\n/** The unit a meter's figures are written in, as the Usage page writes them; empty for a count. */\nexport const PLAN_CARD_METER_UNITS: Record<string, string> = {\n  storage: 'MB',\n  bandwidth: 'GB',\n  emailSends: '',\n  aiCredits: '',\n  dataStorage: 'MB',\n  seats: '',\n  pages: '',\n  forms: '',\n  sites: '',\n} satisfies Record<PlanCardMeter, string>\n\nconst CONTEXTS = ['media', 'website', 'email', 'ai', 'forms', 'data', 'team', 'sites'] as const\n\nexport type PlanCardContext = (typeof CONTEXTS)[number]\n\n/** What the screen in front is about, for the meter that leads. */\nexport const PLAN_CARD_CONTEXTS: string[] = [...CONTEXTS]\n\n/** The meters that lead for each context, in order; the rest follow by how full they are. */\nexport const PLAN_CARD_CONTEXT_METERS: Record<string, string[]> = {\n  media: ['storage'],\n  website: ['bandwidth'],\n  email: ['emailSends'],\n  ai: ['aiCredits'],\n  forms: ['forms'],\n  data: ['dataStorage'],\n  team: ['seats'],\n  sites: ['sites'],\n} satisfies Record<PlanCardContext, PlanCardMeter[]>\n\n/**\n * Each screen's context, by the screen id the native nav manifest opens (its\n * rows' `screen`). A screen not named here has none, and the fullest meter\n * leads. A site's Home is the website's front door; the workspace's Home has\n * no context (`planCardContext`).\n */\nexport const PLAN_CARD_SCREEN_CONTEXTS: Record<string, string> = {\n  'site.media': 'media',\n  'site.pages': 'website',\n  'logic.page': 'website',\n  'shell.analytics': 'website',\n  'email.messages': 'email',\n  'marketing.overview': 'email',\n  'outreach.sequences': 'email',\n  'ai.jobs': 'ai',\n  'ai.credits': 'ai',\n  'forms.list': 'forms',\n  'data.datasets': 'data',\n  'core.team': 'team',\n  'core.team.roles': 'team',\n  'core.team.activity': 'team',\n  'core.site.users': 'team',\n  'site.sites': 'sites',\n} satisfies Record<string, PlanCardContext>\n\n/** The screen id of Home, which is a site's website when the window stands in a site. */\nexport const PLAN_CARD_HOME_SCREEN = 'shell.home'\n\n/** How long one meter stays before the card moves on, slowly (Zach: \"auto rotates slowly\"). */\nexport const PLAN_CARD_ADVANCE_MS = 8000\n\n/** The share from which a meter warns, as the console's meter does (`USAGE_METER_WARNING_PCT`, 80). */\nexport const PLAN_CARD_WARNING_SHARE = 0.8\n\n/** One meter's reading: `null` where the read failed or the plan does not cap it. */\nexport interface PlanCardReading {\n  meter: string\n  used: number | null\n  limit: number | null\n}\n\n/** The context of the screen in front: a site's Home is its website; a screen not mapped has none. */\nexport function planCardContext(screen: string | null, inSite: boolean): string | null {\n  if (!screen) return null\n  if (screen === PLAN_CARD_HOME_SCREEN) return inSite ? 'website' : null\n  return PLAN_CARD_SCREEN_CONTEXTS[screen] ?? null\n}\n\n/** A meter the card can draw: read, capped (an unlimited quota arrives as `null`), and with something to cap. */\nfunction drawable(reading: PlanCardReading): reading is PlanCardReading & { used: number; limit: number } {\n  return (\n    typeof reading.used === 'number' &&\n    Number.isFinite(reading.used) &&\n    typeof reading.limit === 'number' &&\n    Number.isFinite(reading.limit) &&\n    reading.limit > 0\n  )\n}\n\nfunction rank(meter: string): number {\n  const index = PLAN_CARD_METERS.indexOf(meter)\n  return index < 0 ? PLAN_CARD_METERS.length : index\n}\n\n/**\n * The order the card shows its meters in: the context's own meters first, in\n * the mapping's order, then every other meter fullest first (a tie keeps\n * `PLAN_CARD_METERS`' order). A meter that failed to read or that the plan\n * does not cap is left out. Sites leads only on the Sites list: elsewhere it\n * follows every other meter, however full, because a missing site is the\n * limit a workspace is least likely to upgrade for.\n */\nexport function planCardMeterOrder(\n  readings: readonly PlanCardReading[],\n  context: string | null,\n): string[] {\n  const shown = readings.filter(drawable)\n  const seen = new Set<string>()\n  const unique = shown.filter((reading) => {\n    if (seen.has(reading.meter)) return false\n    seen.add(reading.meter)\n    return true\n  })\n  const leading = (context && PLAN_CARD_CONTEXT_METERS[context]) || []\n  const lead = leading.filter((meter) => unique.some((reading) => reading.meter === meter))\n  const rest = unique\n    .filter((reading) => !lead.includes(reading.meter))\n    .sort((a, b) => {\n      const aSites = a.meter === 'sites'\n      const bSites = b.meter === 'sites'\n      if (aSites !== bSites) return aSites ? 1 : -1\n      const byShare = b.used / b.limit - a.used / a.limit\n      return byShare !== 0 ? byShare : rank(a.meter) - rank(b.meter)\n    })\n    .map((reading) => reading.meter)\n  return [...lead, ...rest]\n}\n\n/**\n * Whether the card shows at all: a meter to draw, and either a plan the viewer\n * can upgrade (the workspace menu's \"Upgrade plan\" rule) or a meter at its\n * warning share, which every plan is told about.\n */\nexport function planCardShows(readings: readonly PlanCardReading[], offersUpgrade: boolean): boolean {\n  const shown = readings.filter(drawable)\n  if (!shown.length) return false\n  return offersUpgrade || shown.some((reading) => reading.used / reading.limit >= PLAN_CARD_WARNING_SHARE)\n}\n"],"names":["METERS","PLAN_CARD_METERS","PLAN_CARD_METER_LABELS","storage","bandwidth","emailSends","aiCredits","dataStorage","seats","pages","forms","sites","PLAN_CARD_METER_UNITS","CONTEXTS","PLAN_CARD_CONTEXTS","PLAN_CARD_CONTEXT_METERS","media","website","email","ai","data","team","PLAN_CARD_SCREEN_CONTEXTS","PLAN_CARD_HOME_SCREEN","PLAN_CARD_ADVANCE_MS","PLAN_CARD_WARNING_SHARE","planCardContext","screen","inSite","drawable","reading","used","Number","isFinite","limit","rank","meter","index","indexOf","length","planCardMeterOrder","readings","context","shown","filter","seen","Set","unique","has","add","leading","lead","some","rest","includes","sort","a","b","aSites","bSites","byShare","map","planCardShows","offersUpgrade"],"mappings":"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"}

package/src/lib/app-utils/plan-entitlements.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { AglynOrgBilling, CoreOrgEntitlements, CoreOrgFeatureFlags, OrgDiscount, OrgFeatureFlags, OrgPlan, OrgSeatAddons } from '../foundation';
+import type { AglynOrgBilling, AiTierId, CoreOrgEntitlements, CoreOrgFeatureFlags, OrgDiscount, OrgFeatureFlags, OrgPlan, OrgSeatAddons } from '../foundation';
 import type { PluginOrgFeatures, PluginOrgQuotas } from '../plugin-manager/plugin-entitlement-keys';
 import { type OrgOverrideReasonCode } from './org-override-reason';
 import type { ResolvedBrandingProfile } from './platform-brand';
@@ -261,6 +261,41 @@ export declare const EVENT_CALENDAR_ADDON_MONTHLY_USD = 9;
  * the org-wide `features.siteCare` from any purchased quantity >= 1.
  */
 export declare const SITE_CARE_ADDON_MONTHLY_USD = 49;
+/**
+ * Site Care's included time (AGL-3959): about an hour of staff work a month,
+ * no rollover. `SITE_CARE_INCLUDED_BLOCK_MINUTES` is the step each request is
+ * counted against it in, always rounded up — a 10-minute change uses one
+ * 15-minute block. The timer's actual minutes are still logged beside it.
+ */
+export declare const SITE_CARE_INCLUDED_MINUTES = 60;
+/** The block a request counts against the included hour in (AGL-3959). */
+export declare const SITE_CARE_INCLUDED_BLOCK_MINUTES = 15;
+/**
+ * Site Care extra time (AGL-3959): $79 per STARTED hour past the included
+ * hour in a month. Billed in whole hours, rounded up — any part of an hour is
+ * the full rate — and never less than the hours the owner approved. Only with
+ * the owner's recorded yes, as an invoice item on the next subscription
+ * invoice; never recurring. `site-care.ts` holds the arithmetic.
+ */
+export declare const SITE_CARE_EXTRA_HOUR_USD = 79;
+/**
+ * Site Care projects (AGL-3970): work that adds a page, a form, a design or
+ * a campaign is a flat quote, never hourly. The quote is the estimated hours
+ * × `SITE_CARE_EXTRA_HOUR_USD`, rounded up to the whole hour, and never below
+ * the published starting price of the kind of project it is. These three are
+ * those starting prices, as `/pricing` publishes them.
+ */
+export declare const SITE_CARE_PROJECT_LANDING_PAGE_FROM_USD = 249;
+/** A redesign's published starting price (AGL-3970). */
+export declare const SITE_CARE_PROJECT_REDESIGN_FROM_USD = 749;
+/** A logo or brand kit's published starting price (AGL-3970). */
+export declare const SITE_CARE_PROJECT_BRAND_KIT_FROM_USD = 349;
+/**
+ * A project priced ABOVE this is billed half up front and half at launch, on
+ * two invoices from the same record; at or below it, in full up front
+ * (AGL-3970). `site-care-project.ts` holds the arithmetic.
+ */
+export declare const SITE_CARE_PROJECT_SPLIT_ABOVE_USD = 500;
 /**
  * POS Pro register add-on (AGL-329): $89/mo per extra register/location
  * (Shopify POS Pro parity). Purchased add-ons land as a per-org
@@ -269,37 +304,105 @@ export declare const SITE_CARE_ADDON_MONTHLY_USD = 49;
  */
 export declare const POS_REGISTER_ADDON_MONTHLY_USD = 89;
 /**
- * The Aglyn AI add-on's credit band (AGL-2896): the credits a month the
- * add-on ADDS to the plan's `assistCreditsPerMonth` when
- * `seatAddons.aiAddon` is set. One pool and one meter — the add-on widens
- * the band the assist meter already draws on rather than opening a second
- * one, so `resolveAssistCreditBudget`, the overage price and the hard-cap
- * switch all see one number.
- *
- * ## Sized against the add-on's own price
- *
- * A credit is `ASSIST_CREDIT_COST_USD` of provider spend, so each band is a
- * cost figure: 1,000 credits are $1.00. Every band here costs at most 50% of
- * `PlanPricing.aiAddonMonthlyUsd` at full consumption — Starter $4 of $9,
- * Pro $9 of $19, Business $19 of $39, Scale $34 of $69, Advanced $49 of
- * $99, Agency $149 of $299 — which is the same line-margin floor
- * (`ASSIST_CREDIT_MIN_MARGIN_PCT`) every retail assist rate clears.
- * `tier-margin-floor.spec.ts` holds the whole tier non-negative with the
- * add-on band at 100% and the add-on's revenue counted, and pins each band's
- * share of its price.
- *
- * ## Free and Enterprise
- *
- * Free is 0: the plan sells no add-on (`aiAddonMonthlyUsd` is null), so a
- * quantity written onto a Free org adds nothing. Enterprise is finite at
- * twice Agency's, the rule every Enterprise fallback follows since the
- * 2026-09-07 decision (AGL-2654) — never `UNLIMITED`, for the reason
- * `ENTERPRISE_ASSIST_CREDITS_PER_MONTH` gives: an unbounded band reads back
- * as zero off the wire. Enterprise carries `aiGenerative` in the agreement
- * and its price is null too, so this figure is what a contract that names
- * the add-on starts from before its own number is written.
- */
-export declare const AI_ADDON_CREDITS_PER_MONTH: Record<OrgPlan, number>;
+ * The Aglyn AI tiers (AGL-3965): credits sold on their own, to ANY paid
+ * plan, on top of what the plan includes.
+ *
+ * ## One pool
+ *
+ * Every plan's `assistCreditsPerMonth` pays for ALL of Aglyn AI — the
+ * assistant and generation alike — and `features.aiGenerative` is on for
+ * every plan. A tier ADDS `credits` to that same band in
+ * `resolveOrgEntitlements`, so `resolveAssistCreditBudget`, the overage
+ * price and the hard-cap switch all still see one number. Past the pool the
+ * plan's `extraAssistCreditsUsdPer1k` bills per 1,000 credits unless the
+ * owner turned on `assistOverage.hardCap`; a tier changes neither.
+ *
+ * ## Sized against the tier's own price
+ *
+ * A credit is `ASSIST_CREDIT_COST_USD` of provider spend, so `credits` is a
+ * cost figure: 1,000 credits are $1.00. Every tier costs at most 50% of its
+ * price at full consumption — Spark $4 of $9, Boost $9 of $19, Plus $19 of
+ * $39, Max $34 of $69, Ultra $49 of $99, Studio $149 of $299 — the same
+ * line-margin floor (`ASSIST_CREDIT_MIN_MARGIN_PCT`) every retail assist
+ * rate clears. The plan's included band is priced at 100% burn on its own
+ * tier, so a tier's margin never leans on the plan's; that is what
+ * `tier-margin-floor.spec.ts` holds, per tier.
+ *
+ * These are the six price/credit pairs the add-on was sold at per plan
+ * before AGL-3965 (Starter's $9 / 4,000 through Agency's $299 / 149,000),
+ * now chosen independently of the plan. `LEGACY_AI_ADDON_TIER_BY_PLAN` maps
+ * each old per-plan add-on to the tier with its price and band.
+ *
+ * Yearly is ×12 with no discount, as every add-on is. Studio is the top;
+ * more is an Enterprise contract. Free sells none (`planSellsAiTiers`).
+ */
+export interface AiTier {
+    /** The tier's name as a person sees it, after the product name. */
+    label: string;
+    monthlyUsd: number;
+    yearlyUsd: number;
+    /** Credits a month the tier adds to the plan's included band. */
+    credits: number;
+}
+/** The tiers, smallest first — the order every picker lists them in. */
+export declare const AI_TIER_IDS: readonly AiTierId[];
+export declare const AI_TIERS: Readonly<Record<AiTierId, AiTier>>;
+/**
+ * The tier an add-on bought before AGL-3965 is (AGL-3965): the one with the
+ * same price and the same band the plan sold it at, so a workspace that
+ * held "the Pro add-on" holds Boost — $19, 9,000 credits — and neither its
+ * bill nor its credits move. Read when `aiTier` is absent and to classify a
+ * per-plan `STRIPE_PRICE_{PLAN}_AI_ADDON` item still on a subscription.
+ */
+export declare const LEGACY_AI_ADDON_TIER_BY_PLAN: Readonly<Partial<Record<OrgPlan, AiTierId>>>;
+/**
+ * The tier a purchase that names a plan and no tier means (AGL-3965): a
+ * `?plan=pro&ai=1` deep link, a checkout posting `aiAddon: true` alone. The
+ * tier with that plan's old price and band, so a link published before tiers
+ * existed still sells what it quoted. Null where the plan sells no tier.
+ */
+export declare function defaultAiTierForPlan(plan: OrgPlan | string | null | undefined): AiTierId | null;
+/** Whether a value is one of the tier ids. */
+export declare function isAiTierId(value: unknown): value is AiTierId;
+/**
+ * The add-on key an Aglyn AI tier travels under outside the billing routes
+ * (AGL-3965): `ai:<tier>`, e.g. `ai:boost`. The ONE spelling a bundle
+ * checkout link (AGL-3955) and a hand-off proposal's add-on list (AGL-3956)
+ * name a tier by, parsed and listed here, beside the tiers, so neither
+ * restates the ids.
+ */
+export type AiTierAddonKey = `ai:${AiTierId}`;
+/** `ai:<tier>` for a tier. */
+export declare function aiTierAddonKey(tier: AiTierId): AiTierAddonKey;
+/**
+ * The tier an `ai:<tier>` key names, or null for anything else — another
+ * add-on's key, a bare `ai`, an unknown tier, a non-string. Exact and
+ * case-sensitive: a key is read off a link, and guessing is the expensive
+ * direction to be wrong in (`parseOnboardingPlanIntent` reads `?ai=` the
+ * same way).
+ */
+export declare function parseAiTierAddonKey(key: unknown): AiTierId | null;
+/** One tier as an add-on a bundle or a proposal can carry. */
+export interface AiTierAddonOption {
+    key: AiTierAddonKey;
+    tier: AiTierId;
+    label: string;
+    monthlyUsd: number;
+    yearlyUsd: number;
+    credits: number;
+}
+/**
+ * Every tier as an `ai:<tier>` add-on, smallest first — what a picker that
+ * offers "Aglyn AI" beside the other add-ons lists. Empty for a plan that
+ * sells no tier (Free, Enterprise) when a plan is given.
+ */
+export declare function listAiTierAddons(plan?: OrgPlan | string | null): AiTierAddonOption[];
+/**
+ * Whether a plan may buy an Aglyn AI tier (AGL-3965): every paid self-serve
+ * plan. Not Free, which has no subscription to carry it, and not Enterprise,
+ * whose AI is in the agreement.
+ */
+export declare function planSellsAiTiers(plan: OrgPlan | string | undefined | null): boolean;
 /**
  * The generative add-on's name as a person sees it (AGL-2896): the brand,
  * then "AI". Read from the platform brand by default and from the org's
@@ -463,41 +566,6 @@ export interface PlanPricing {
      * no unrefusable assist traffic to absorb.
      */
     extraAssistCreditsUsdPer1k: number | null;
-    /**
-     * The Aglyn AI add-on, flat per organization per month (AGL-2896); null
-     * when the plan does not sell it.
-     *
-     * ## What it buys
-     *
-     * `features.aiGenerative` — generative building and automation, the rung
-     * no self-serve tier includes — plus `AI_ADDON_CREDITS_PER_MONTH[plan]`
-     * added to the plan's assist band. It also switches `aiAssist` on, so on
-     * Starter it brings the two rungs the tier does not carry — the copy
-     * assist and the generative one — on top of the 750 credits the plan
-     * already includes (AGL-3203). It ADDS to that band; it does not replace
-     * it, on Starter or on any tier.
-     *
-     * ## Where the ladder sits
-     *
-     * Priced as an uplift on the plan rather than on its own cost: the field
-     * charges roughly 30% of the base price for an AI tier (Zylo's 2025
-     * survey puts the AI uplift at 20–37% across SaaS; aissist.io's benchmark
-     * and the Framer, Webflow and HubSpot credit add-ons sit in the same
-     * band), and the share DESCENDS with the tier — 36% of Starter's $25, 34%
-     * of Pro's, 28% of Business's, 28% of Scale's, 25% of Advanced's, 23% of
-     * Agency's — because the larger the plan the more of its price is already
-     * carrying the bands the assistant builds against.
-     *
-     * Annual is x12 of this with no discount, as every other add-on is
-     * (`orgListPriceMonthlyUsd`). The band it funds costs at most 50% of it in
-     * provider spend, the `ASSIST_CREDIT_MIN_MARGIN_PCT` floor every retail
-     * assist figure holds.
-     *
-     * Null on Free, which sells no add-on of any kind, and on Enterprise,
-     * where every figure is the "not for sale" sentinel and generative
-     * building is in the agreement.
-     */
-    aiAddonMonthlyUsd: number | null;
     /**
      * Metered overage per 1,000 CRM records beyond `contactsPerHost` (AGL-890,
      * widened to contacts + companies + deals in AGL-2611): audience bands,
@@ -1490,6 +1558,54 @@ export declare function resolveEffectivePlan(org: Partial<AglynOrgBilling> | nul
  * together rather than leaving a rate on a band that has gone.
  */
 export declare function hasAiAddon(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/**
+ * Which Aglyn AI tier the org's purchase map holds (AGL-3965), whether or
+ * not the subscription is still paying for it — `resolveAiTier` is the
+ * reading that drops a dead one. `org.aiTier` when it names a tier;
+ * otherwise, for an add-on bought before tiers existed, the tier with that
+ * plan's old price and band (`LEGACY_AI_ADDON_TIER_BY_PLAN`). Null when no
+ * add-on is held or the plan sells no tier (Free, Enterprise).
+ */
+export declare function aiTierOfPurchase(org: Partial<AglynOrgBilling> | null | undefined): AiTierId | null;
+/**
+ * The Aglyn AI tier that currently applies (AGL-3965): bought, on a
+ * subscription still paying for it, on a plan that sells tiers. The ONE
+ * reading every surface that shows or counts a tier goes through.
+ */
+export declare function resolveAiTier(org: Partial<AglynOrgBilling> | null | undefined): AiTierId | null;
+/**
+ * What `seatAddons.aiAddon` adds on an Enterprise org (AGL-2896, kept by
+ * AGL-3965): twice Studio's band, the figure the per-plan table carried as
+ * twice Agency's (the rule every Enterprise fallback follows since AGL-2654),
+ * and still what a contract that names the add-on starts from before its own
+ * number is written. Enterprise buys no tier — its AI is in the agreement —
+ * so this is the contract figure kept, not a price; finite, never
+ * `UNLIMITED`, for the reason `ENTERPRISE_ASSIST_CREDITS_PER_MONTH` gives.
+ */
+export declare const ENTERPRISE_AI_ADDON_CREDITS_PER_MONTH: number;
+/**
+ * The Aglyn AI add-on's per-unit quota as `resolveOrgEntitlements` folds it
+ * (AGL-3965): the purchased tier's credits, on a plan that sells tiers;
+ * Enterprise's contract figure (`ENTERPRISE_AI_ADDON_CREDITS_PER_MONTH`);
+ * else 0 (Free). The AI plugin declares its seat add-on with this as
+ * `quota.perUnit`.
+ */
+export declare function aiTierQuotaPerUnit(org: Partial<AglynOrgBilling> | null | undefined, plan: OrgPlan): number;
+/**
+ * The credits a month the org's Aglyn AI add-on adds to its plan's included
+ * band (AGL-3965) — 0 with none held. The SAME figure `resolveOrgEntitlements`
+ * folds into `assistCreditsPerMonth` (`aiTierQuotaPerUnit`), so a surface
+ * quoting "your tier adds" and the meter agree.
+ */
+export declare function aiTierCreditsPerMonth(org: Partial<AglynOrgBilling> | null | undefined): number;
+/**
+ * Whether this org can buy or change an Aglyn AI tier itself (AGL-3965): a
+ * plan that sells tiers, and not one a staff comp grants — a comp has no
+ * subscription to put the tier on (`compPricing`).
+ */
+export declare function orgCanBuyAiTier(org: Partial<AglynOrgBilling> | null | undefined): boolean;
+/** "Aglyn AI Boost": the product name, then the tier's. */
+export declare const aiTierName: (tier: AiTierId, brand?: string) => string;
 /**
  * Whether the org's Site Care add-on currently applies (AGL-3954): bought,
  * and on a subscription that is still paying for it, so a dead subscription