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

package/src/lib/app-utils/upgrade-proposal.d.ts

@@ -44,6 +44,20 @@ export declare function normalizeUpgradeProposalNote(note: unknown): string | un
  * button opens a checkout for an unknown tier is worse than no card.
  */
 export declare function readUpgradeProposal(org: Partial<AglynOrgBilling> | null | undefined): OrgUpgradeProposal | null;
+/**
+ * The bundle half of a proposal (AGL-3956) as it is stored: add-ons through
+ * the shared parser and fitted to the plan, an interval only when one was
+ * chosen, a coupon only when it reads as a code, and the Aglyn AI tier
+ * (AGL-3965) only with the AI add-on — an `ai:<tier>` entry, or the stored
+ * `aiTier`. Whatever cannot be honored is left out rather than stored, so
+ * Billing is never asked to preselect something the checkout would refuse.
+ */
+export declare function normalizeUpgradeProposalBundle(plan: OrgPlan, input: {
+    addons?: unknown;
+    interval?: unknown;
+    coupon?: unknown;
+    aiTier?: unknown;
+} | null | undefined): Pick<OrgUpgradeProposal, 'addons' | 'interval' | 'coupon' | 'aiTier'>;
 /**
  * The proposal the workspace should be shown: the stored one, while no
  * subscription is live.
@@ -55,12 +69,23 @@ export declare function readUpgradeProposal(org: Partial<AglynOrgBilling> | null
  * clears the field then, and this hides it in the meantime.
  */
 export declare function standingUpgradeProposal(org: Partial<AglynOrgBilling> | null | undefined): OrgUpgradeProposal | null;
-/** The plan intent a proposal carries into Billing: the plan, no interval. */
-export declare function upgradeProposalIntent(proposal: Pick<OrgUpgradeProposal, 'plan'>): OnboardingPlanIntent;
-/** Where the proposal's button goes: Billing, with the plan preselected. */
-export declare function upgradeProposalDestination(orgSlug: string, proposal: Pick<OrgUpgradeProposal, 'plan'>): string;
+type ProposalBundle = Pick<OrgUpgradeProposal, 'plan'> & Partial<Pick<OrgUpgradeProposal, 'addons' | 'interval' | 'coupon' | 'aiTier'>>;
+/**
+ * The intent a proposal carries into Billing: the plan, and the add-ons,
+ * cadence and coupon staff proposed with it (AGL-3956) — the same fields the
+ * bundle checkout link carries (AGL-3955), so the proposal card and the link
+ * land on the same preselected page.
+ */
+export declare function upgradeProposalIntent(proposal: ProposalBundle): OnboardingPlanIntent;
+/** Where the proposal's button goes: Billing, with the bundle preselected. */
+export declare function upgradeProposalDestination(orgSlug: string, proposal: ProposalBundle): string;
+/** "Starter with Site Care, billed yearly, code BOOTH25". */
+export declare function upgradeProposalSummary(proposal: ProposalBundle, options?: {
+    brand?: string;
+}): string;
 /** "Acme's Aglyn team proposed the Starter plan". */
 export declare function upgradeProposalHeadline(proposal: Pick<OrgUpgradeProposal, 'plan'>, options: {
     orgName?: string | null;
     productName: string;
 }): string;
+export {};

package/src/lib/app-utils/upgrade-proposal.js

@@ -23,9 +23,10 @@
  * `orgs/{orgId}.upgradeProposal`; this module decides whether it still
  * stands, what it may name, and where the button under it goes.
  */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { describeBundle, fitBundleAddonsToPlan, hasBundleAddons, normalizeBundleCoupon, parseBundleAddons } from "./bundle-intent.js";
 import { onboardingDestination } from "./onboarding-deep-link.js";
 import { isLiveSubscriptionStatus } from "./org-billing-doc.js";
-import { PLAN_LABELS, SELF_SERVE_PLANS } from "./plan-entitlements.js";
+import { isAiTierId, PLAN_LABELS, SELF_SERVE_PLANS } from "./plan-entitlements.js";
 /** The longest staff note a proposal carries. */ export const UPGRADE_PROPOSAL_NOTE_MAX = 500;
 /**
  * The plans staff may propose: every tier a customer can buy themselves,
@@ -51,12 +52,36 @@ export function isUpgradeProposalPlan(plan) {
         return null;
     }
     const note = normalizeUpgradeProposalNote(raw.note);
+    const bundle = normalizeUpgradeProposalBundle(raw.plan, raw);
     return _extends({
         plan: raw.plan,
         proposedBy: typeof raw.proposedBy === 'string' ? raw.proposedBy : '',
         proposedAt: Number.isFinite(raw.proposedAt) ? Number(raw.proposedAt) : 0
     }, note ? {
         note
+    } : {}, bundle);
+}
+/**
+ * The bundle half of a proposal (AGL-3956) as it is stored: add-ons through
+ * the shared parser and fitted to the plan, an interval only when one was
+ * chosen, a coupon only when it reads as a code, and the Aglyn AI tier
+ * (AGL-3965) only with the AI add-on — an `ai:<tier>` entry, or the stored
+ * `aiTier`. Whatever cannot be honored is left out rather than stored, so
+ * Billing is never asked to preselect something the checkout would refuse.
+ */ export function normalizeUpgradeProposalBundle(plan, input) {
+    const parsed = parseBundleAddons(input == null ? void 0 : input.addons);
+    const addons = fitBundleAddonsToPlan(parsed.addons, plan).addons;
+    const interval = (input == null ? void 0 : input.interval) === 'year' || (input == null ? void 0 : input.interval) === 'month' ? input.interval : undefined;
+    const coupon = normalizeBundleCoupon(input == null ? void 0 : input.coupon);
+    const aiTier = addons.aiAddon ? isAiTierId(input == null ? void 0 : input.aiTier) ? input.aiTier : parsed.aiTier : undefined;
+    return _extends({}, hasBundleAddons(addons) ? {
+        addons
+    } : {}, interval ? {
+        interval
+    } : {}, coupon ? {
+        coupon
+    } : {}, aiTier ? {
+        aiTier
     } : {});
 }
 /**
@@ -72,19 +97,45 @@ export function isUpgradeProposalPlan(plan) {
     if (isLiveSubscriptionStatus(org == null ? void 0 : org.billingStatus)) return null;
     return readUpgradeProposal(org);
 }
-/** The plan intent a proposal carries into Billing: the plan, no interval. */ export function upgradeProposalIntent(proposal) {
-    return {
+/**
+ * The intent a proposal carries into Billing: the plan, and the add-ons,
+ * cadence and coupon staff proposed with it (AGL-3956) — the same fields the
+ * bundle checkout link carries (AGL-3955), so the proposal card and the link
+ * land on the same preselected page.
+ */ export function upgradeProposalIntent(proposal) {
+    const addons = fitBundleAddonsToPlan(proposal.addons, proposal.plan).addons;
+    const coupon = normalizeBundleCoupon(proposal.coupon);
+    const interval = proposal.interval === 'year' || proposal.interval === 'month' ? proposal.interval : null;
+    return _extends({
         plan: proposal.plan,
-        interval: 'month',
-        // The proposal names a plan, not a cadence, so the page keeps whatever
-        // its toggle says rather than being told "monthly".
-        intervalStated: false,
+        interval: interval != null ? interval : 'month',
+        // A proposal with no cadence names a plan, not a cadence, so the page
+        // keeps whatever its toggle says rather than being told "monthly".
+        intervalStated: interval !== null,
         contactSales: false
-    };
+    }, addons.aiAddon ? {
+        ai: true
+    } : {}, addons.aiAddon && isAiTierId(proposal.aiTier) ? {
+        aiTier: proposal.aiTier
+    } : {}, hasBundleAddons(addons) ? {
+        addons
+    } : {}, coupon ? {
+        coupon
+    } : {});
 }
-/** Where the proposal's button goes: Billing, with the plan preselected. */ export function upgradeProposalDestination(orgSlug, proposal) {
+/** Where the proposal's button goes: Billing, with the bundle preselected. */ export function upgradeProposalDestination(orgSlug, proposal) {
     return onboardingDestination(orgSlug, upgradeProposalIntent(proposal));
 }
+/** "Starter with Site Care, billed yearly, code BOOTH25". */ export function upgradeProposalSummary(proposal, options = {}) {
+    var _proposal_addons, _proposal_interval, _proposal_coupon, _proposal_aiTier;
+    return describeBundle({
+        plan: proposal.plan,
+        addons: (_proposal_addons = proposal.addons) != null ? _proposal_addons : null,
+        interval: (_proposal_interval = proposal.interval) != null ? _proposal_interval : null,
+        coupon: (_proposal_coupon = proposal.coupon) != null ? _proposal_coupon : null,
+        aiTier: (_proposal_aiTier = proposal.aiTier) != null ? _proposal_aiTier : null
+    }, options);
+}
 /** "Acme's Aglyn team proposed the Starter plan". */ export function upgradeProposalHeadline(proposal, options) {
     var _options_orgName;
     const workspace = (_options_orgName = options.orgName) == null ? void 0 : _options_orgName.trim();

package/src/lib/app-utils/upgrade-proposal.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/upgrade-proposal.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 platform team's request that a workspace move to a paid plan\n * (AGL-3466), read in one place.\n *\n * A workspace staff build for a client is handed over first and sold second:\n * the client joins, looks around on whatever the workspace already has, and\n * only then is asked to upgrade. Staff record that ask as\n * `orgs/{orgId}.upgradeProposal`; this module decides whether it still\n * stands, what it may name, and where the button under it goes.\n */\n\nimport type {\n  AglynOrgBilling,\n  OrgPlan,\n  OrgUpgradeProposal,\n} from '../foundation/definitions/org-billing.types'\nimport {\n  onboardingDestination,\n  type OnboardingPlanIntent,\n} from './onboarding-deep-link'\nimport { isLiveSubscriptionStatus } from './org-billing-doc'\nimport { PLAN_LABELS, SELF_SERVE_PLANS } from './plan-entitlements'\n\n/** The longest staff note a proposal carries. */\nexport const UPGRADE_PROPOSAL_NOTE_MAX = 500\n\n/**\n * The plans staff may propose: every tier a customer can buy themselves,\n * less Free, which is not a purchase. Enterprise is quoted per deal, so it\n * is never proposed through a checkout link.\n */\nexport const UPGRADE_PROPOSAL_PLANS: readonly OrgPlan[] = SELF_SERVE_PLANS.filter(\n  (plan) => plan !== 'free',\n)\n\nexport function isUpgradeProposalPlan(plan: unknown): plan is OrgPlan {\n  return (\n    typeof plan === 'string' &&\n    (UPGRADE_PROPOSAL_PLANS as readonly string[]).includes(plan)\n  )\n}\n\n/** A staff note as it is stored: trimmed, bounded, and absent when blank. */\nexport function normalizeUpgradeProposalNote(note: unknown): string | undefined {\n  if (typeof note !== 'string') return undefined\n  const trimmed = note.trim().slice(0, UPGRADE_PROPOSAL_NOTE_MAX)\n  return trimmed || undefined\n}\n\n/**\n * The stored proposal, narrowed, or null when there is none worth showing.\n *\n * A proposal naming a plan this build cannot sell reads as none: a card whose\n * button opens a checkout for an unknown tier is worse than no card.\n */\nexport function readUpgradeProposal(\n  org: Partial<AglynOrgBilling> | null | undefined,\n): OrgUpgradeProposal | null {\n  const raw = org?.upgradeProposal as Partial<OrgUpgradeProposal> | null | undefined\n  if (!raw || typeof raw !== 'object' || !isUpgradeProposalPlan(raw.plan)) {\n    return null\n  }\n  const note = normalizeUpgradeProposalNote(raw.note)\n  return {\n    plan: raw.plan,\n    proposedBy: typeof raw.proposedBy === 'string' ? raw.proposedBy : '',\n    proposedAt: Number.isFinite(raw.proposedAt) ? Number(raw.proposedAt) : 0,\n    ...(note ? { note } : {}),\n  }\n}\n\n/**\n * The proposal the workspace should be shown: the stored one, while no\n * subscription is live.\n *\n * `billingStatus` is the org document's mirror of the subscription status,\n * readable by every member, so this answers from the document the console\n * already holds. A live subscription means the workspace has bought a plan,\n * which settles the question the proposal asked; `writeOrgBilling`'s caller\n * clears the field then, and this hides it in the meantime.\n */\nexport function standingUpgradeProposal(\n  org: Partial<AglynOrgBilling> | null | undefined,\n): OrgUpgradeProposal | null {\n  if (isLiveSubscriptionStatus(org?.billingStatus)) return null\n  return readUpgradeProposal(org)\n}\n\n/** The plan intent a proposal carries into Billing: the plan, no interval. */\nexport function upgradeProposalIntent(\n  proposal: Pick<OrgUpgradeProposal, 'plan'>,\n): OnboardingPlanIntent {\n  return {\n    plan: proposal.plan,\n    interval: 'month',\n    // The proposal names a plan, not a cadence, so the page keeps whatever\n    // its toggle says rather than being told \"monthly\".\n    intervalStated: false,\n    contactSales: false,\n  }\n}\n\n/** Where the proposal's button goes: Billing, with the plan preselected. */\nexport function upgradeProposalDestination(\n  orgSlug: string,\n  proposal: Pick<OrgUpgradeProposal, 'plan'>,\n): string {\n  return onboardingDestination(orgSlug, upgradeProposalIntent(proposal))\n}\n\n/** \"Acme's Aglyn team proposed the Starter plan\". */\nexport function upgradeProposalHeadline(\n  proposal: Pick<OrgUpgradeProposal, 'plan'>,\n  options: { orgName?: string | null; productName: string },\n): string {\n  const workspace = options.orgName?.trim()\n  const team = workspace\n    ? `${workspace}'s ${options.productName} team`\n    : `Your ${options.productName} team`\n  return `${team} proposed the ${PLAN_LABELS[proposal.plan]} plan`\n}\n"],"names":["onboardingDestination","isLiveSubscriptionStatus","PLAN_LABELS","SELF_SERVE_PLANS","UPGRADE_PROPOSAL_NOTE_MAX","UPGRADE_PROPOSAL_PLANS","filter","plan","isUpgradeProposalPlan","includes","normalizeUpgradeProposalNote","note","undefined","trimmed","trim","slice","readUpgradeProposal","org","raw","upgradeProposal","proposedBy","proposedAt","Number","isFinite","standingUpgradeProposal","billingStatus","upgradeProposalIntent","proposal","interval","intervalStated","contactSales","upgradeProposalDestination","orgSlug","upgradeProposalHeadline","options","workspace","orgName","team","productName"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;CASC;AAOD,SACEA,qBAAqB,QAEhB,4BAAwB;AAC/B,SAASC,wBAAwB,QAAQ,uBAAmB;AAC5D,SAASC,WAAW,EAAEC,gBAAgB,QAAQ,yBAAqB;AAEnE,+CAA+C,GAC/C,OAAO,MAAMC,4BAA4B,IAAG;AAE5C;;;;CAIC,GACD,OAAO,MAAMC,yBAA6CF,iBAAiBG,MAAM,CAC/E,CAACC,OAASA,SAAS,QACpB;AAED,OAAO,SAASC,sBAAsBD,IAAa;IACjD,OACE,OAAOA,SAAS,YAChB,AAACF,uBAA6CI,QAAQ,CAACF;AAE3D;AAEA,2EAA2E,GAC3E,OAAO,SAASG,6BAA6BC,IAAa;IACxD,IAAI,OAAOA,SAAS,UAAU,OAAOC;IACrC,MAAMC,UAAUF,KAAKG,IAAI,GAAGC,KAAK,CAAC,GAAGX;IACrC,OAAOS,WAAWD;AACpB;AAEA;;;;;CAKC,GACD,OAAO,SAASI,oBACdC,GAAgD;IAEhD,MAAMC,MAAMD,uBAAAA,IAAKE,eAAe;IAChC,IAAI,CAACD,OAAO,OAAOA,QAAQ,YAAY,CAACV,sBAAsBU,IAAIX,IAAI,GAAG;QACvE,OAAO;IACT;IACA,MAAMI,OAAOD,6BAA6BQ,IAAIP,IAAI;IAClD,OAAO;QACLJ,MAAMW,IAAIX,IAAI;QACda,YAAY,OAAOF,IAAIE,UAAU,KAAK,WAAWF,IAAIE,UAAU,GAAG;QAClEC,YAAYC,OAAOC,QAAQ,CAACL,IAAIG,UAAU,IAAIC,OAAOJ,IAAIG,UAAU,IAAI;OACnEV,OAAO;QAAEA;IAAK,IAAI,CAAC;AAE3B;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASa,wBACdP,GAAgD;IAEhD,IAAIhB,yBAAyBgB,uBAAAA,IAAKQ,aAAa,GAAG,OAAO;IACzD,OAAOT,oBAAoBC;AAC7B;AAEA,4EAA4E,GAC5E,OAAO,SAASS,sBACdC,QAA0C;IAE1C,OAAO;QACLpB,MAAMoB,SAASpB,IAAI;QACnBqB,UAAU;QACV,uEAAuE;QACvE,oDAAoD;QACpDC,gBAAgB;QAChBC,cAAc;IAChB;AACF;AAEA,0EAA0E,GAC1E,OAAO,SAASC,2BACdC,OAAe,EACfL,QAA0C;IAE1C,OAAO3B,sBAAsBgC,SAASN,sBAAsBC;AAC9D;AAEA,mDAAmD,GACnD,OAAO,SAASM,wBACdN,QAA0C,EAC1CO,OAAyD;QAEvCA;IAAlB,MAAMC,aAAYD,mBAAAA,QAAQE,OAAO,qBAAfF,iBAAiBpB,IAAI;IACvC,MAAMuB,OAAOF,YACT,GAAGA,UAAU,GAAG,EAAED,QAAQI,WAAW,CAAC,KAAK,CAAC,GAC5C,CAAC,KAAK,EAAEJ,QAAQI,WAAW,CAAC,KAAK,CAAC;IACtC,OAAO,GAAGD,KAAK,cAAc,EAAEnC,WAAW,CAACyB,SAASpB,IAAI,CAAC,CAAC,KAAK,CAAC;AAClE"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/upgrade-proposal.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 platform team's request that a workspace move to a paid plan\n * (AGL-3466), read in one place.\n *\n * A workspace staff build for a client is handed over first and sold second:\n * the client joins, looks around on whatever the workspace already has, and\n * only then is asked to upgrade. Staff record that ask as\n * `orgs/{orgId}.upgradeProposal`; this module decides whether it still\n * stands, what it may name, and where the button under it goes.\n */\n\nimport type {\n  AglynOrgBilling,\n  OrgPlan,\n  OrgUpgradeProposal,\n} from '../foundation/definitions/org-billing.types'\nimport {\n  describeBundle,\n  fitBundleAddonsToPlan,\n  hasBundleAddons,\n  normalizeBundleCoupon,\n  parseBundleAddons,\n  type BundleAddons,\n} from './bundle-intent'\nimport {\n  onboardingDestination,\n  type OnboardingPlanIntent,\n} from './onboarding-deep-link'\nimport { isLiveSubscriptionStatus } from './org-billing-doc'\nimport { isAiTierId, PLAN_LABELS, SELF_SERVE_PLANS } from './plan-entitlements'\n\n/** The longest staff note a proposal carries. */\nexport const UPGRADE_PROPOSAL_NOTE_MAX = 500\n\n/**\n * The plans staff may propose: every tier a customer can buy themselves,\n * less Free, which is not a purchase. Enterprise is quoted per deal, so it\n * is never proposed through a checkout link.\n */\nexport const UPGRADE_PROPOSAL_PLANS: readonly OrgPlan[] = SELF_SERVE_PLANS.filter(\n  (plan) => plan !== 'free',\n)\n\nexport function isUpgradeProposalPlan(plan: unknown): plan is OrgPlan {\n  return (\n    typeof plan === 'string' &&\n    (UPGRADE_PROPOSAL_PLANS as readonly string[]).includes(plan)\n  )\n}\n\n/** A staff note as it is stored: trimmed, bounded, and absent when blank. */\nexport function normalizeUpgradeProposalNote(note: unknown): string | undefined {\n  if (typeof note !== 'string') return undefined\n  const trimmed = note.trim().slice(0, UPGRADE_PROPOSAL_NOTE_MAX)\n  return trimmed || undefined\n}\n\n/**\n * The stored proposal, narrowed, or null when there is none worth showing.\n *\n * A proposal naming a plan this build cannot sell reads as none: a card whose\n * button opens a checkout for an unknown tier is worse than no card.\n */\nexport function readUpgradeProposal(\n  org: Partial<AglynOrgBilling> | null | undefined,\n): OrgUpgradeProposal | null {\n  const raw = org?.upgradeProposal as Partial<OrgUpgradeProposal> | null | undefined\n  if (!raw || typeof raw !== 'object' || !isUpgradeProposalPlan(raw.plan)) {\n    return null\n  }\n  const note = normalizeUpgradeProposalNote(raw.note)\n  const bundle = normalizeUpgradeProposalBundle(raw.plan, raw)\n  return {\n    plan: raw.plan,\n    proposedBy: typeof raw.proposedBy === 'string' ? raw.proposedBy : '',\n    proposedAt: Number.isFinite(raw.proposedAt) ? Number(raw.proposedAt) : 0,\n    ...(note ? { note } : {}),\n    ...bundle,\n  }\n}\n\n/**\n * The bundle half of a proposal (AGL-3956) as it is stored: add-ons through\n * the shared parser and fitted to the plan, an interval only when one was\n * chosen, a coupon only when it reads as a code, and the Aglyn AI tier\n * (AGL-3965) only with the AI add-on — an `ai:<tier>` entry, or the stored\n * `aiTier`. Whatever cannot be honored is left out rather than stored, so\n * Billing is never asked to preselect something the checkout would refuse.\n */\nexport function normalizeUpgradeProposalBundle(\n  plan: OrgPlan,\n  input:\n    | { addons?: unknown; interval?: unknown; coupon?: unknown; aiTier?: unknown }\n    | null\n    | undefined,\n): Pick<OrgUpgradeProposal, 'addons' | 'interval' | 'coupon' | 'aiTier'> {\n  const parsed = parseBundleAddons(input?.addons)\n  const addons: BundleAddons = fitBundleAddonsToPlan(parsed.addons, plan).addons\n  const interval =\n    input?.interval === 'year' || input?.interval === 'month' ? input.interval : undefined\n  const coupon = normalizeBundleCoupon(input?.coupon)\n  const aiTier = addons.aiAddon\n    ? isAiTierId(input?.aiTier)\n      ? input.aiTier\n      : parsed.aiTier\n    : undefined\n  return {\n    ...(hasBundleAddons(addons) ? { addons } : {}),\n    ...(interval ? { interval } : {}),\n    ...(coupon ? { coupon } : {}),\n    ...(aiTier ? { aiTier } : {}),\n  }\n}\n\n/**\n * The proposal the workspace should be shown: the stored one, while no\n * subscription is live.\n *\n * `billingStatus` is the org document's mirror of the subscription status,\n * readable by every member, so this answers from the document the console\n * already holds. A live subscription means the workspace has bought a plan,\n * which settles the question the proposal asked; `writeOrgBilling`'s caller\n * clears the field then, and this hides it in the meantime.\n */\nexport function standingUpgradeProposal(\n  org: Partial<AglynOrgBilling> | null | undefined,\n): OrgUpgradeProposal | null {\n  if (isLiveSubscriptionStatus(org?.billingStatus)) return null\n  return readUpgradeProposal(org)\n}\n\ntype ProposalBundle = Pick<OrgUpgradeProposal, 'plan'> &\n  Partial<Pick<OrgUpgradeProposal, 'addons' | 'interval' | 'coupon' | 'aiTier'>>\n\n/**\n * The intent a proposal carries into Billing: the plan, and the add-ons,\n * cadence and coupon staff proposed with it (AGL-3956) — the same fields the\n * bundle checkout link carries (AGL-3955), so the proposal card and the link\n * land on the same preselected page.\n */\nexport function upgradeProposalIntent(proposal: ProposalBundle): OnboardingPlanIntent {\n  const addons = fitBundleAddonsToPlan(proposal.addons, proposal.plan).addons\n  const coupon = normalizeBundleCoupon(proposal.coupon)\n  const interval = proposal.interval === 'year' || proposal.interval === 'month'\n    ? proposal.interval\n    : null\n  return {\n    plan: proposal.plan,\n    interval: interval ?? 'month',\n    // A proposal with no cadence names a plan, not a cadence, so the page\n    // keeps whatever its toggle says rather than being told \"monthly\".\n    intervalStated: interval !== null,\n    contactSales: false,\n    ...(addons.aiAddon ? { ai: true as const } : {}),\n    ...(addons.aiAddon && isAiTierId(proposal.aiTier) ? { aiTier: proposal.aiTier } : {}),\n    ...(hasBundleAddons(addons) ? { addons } : {}),\n    ...(coupon ? { coupon } : {}),\n  }\n}\n\n/** Where the proposal's button goes: Billing, with the bundle preselected. */\nexport function upgradeProposalDestination(\n  orgSlug: string,\n  proposal: ProposalBundle,\n): string {\n  return onboardingDestination(orgSlug, upgradeProposalIntent(proposal))\n}\n\n/** \"Starter with Site Care, billed yearly, code BOOTH25\". */\nexport function upgradeProposalSummary(\n  proposal: ProposalBundle,\n  options: { brand?: string } = {},\n): string {\n  return describeBundle(\n    {\n      plan: proposal.plan,\n      addons: proposal.addons ?? null,\n      interval: proposal.interval ?? null,\n      coupon: proposal.coupon ?? null,\n      aiTier: proposal.aiTier ?? null,\n    },\n    options,\n  )\n}\n\n/** \"Acme's Aglyn team proposed the Starter plan\". */\nexport function upgradeProposalHeadline(\n  proposal: Pick<OrgUpgradeProposal, 'plan'>,\n  options: { orgName?: string | null; productName: string },\n): string {\n  const workspace = options.orgName?.trim()\n  const team = workspace\n    ? `${workspace}'s ${options.productName} team`\n    : `Your ${options.productName} team`\n  return `${team} proposed the ${PLAN_LABELS[proposal.plan]} plan`\n}\n"],"names":["describeBundle","fitBundleAddonsToPlan","hasBundleAddons","normalizeBundleCoupon","parseBundleAddons","onboardingDestination","isLiveSubscriptionStatus","isAiTierId","PLAN_LABELS","SELF_SERVE_PLANS","UPGRADE_PROPOSAL_NOTE_MAX","UPGRADE_PROPOSAL_PLANS","filter","plan","isUpgradeProposalPlan","includes","normalizeUpgradeProposalNote","note","undefined","trimmed","trim","slice","readUpgradeProposal","org","raw","upgradeProposal","bundle","normalizeUpgradeProposalBundle","proposedBy","proposedAt","Number","isFinite","input","parsed","addons","interval","coupon","aiTier","aiAddon","standingUpgradeProposal","billingStatus","upgradeProposalIntent","proposal","intervalStated","contactSales","ai","upgradeProposalDestination","orgSlug","upgradeProposalSummary","options","upgradeProposalHeadline","workspace","orgName","team","productName"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;CASC;AAOD,SACEA,cAAc,EACdC,qBAAqB,EACrBC,eAAe,EACfC,qBAAqB,EACrBC,iBAAiB,QAEZ,qBAAiB;AACxB,SACEC,qBAAqB,QAEhB,4BAAwB;AAC/B,SAASC,wBAAwB,QAAQ,uBAAmB;AAC5D,SAASC,UAAU,EAAEC,WAAW,EAAEC,gBAAgB,QAAQ,yBAAqB;AAE/E,+CAA+C,GAC/C,OAAO,MAAMC,4BAA4B,IAAG;AAE5C;;;;CAIC,GACD,OAAO,MAAMC,yBAA6CF,iBAAiBG,MAAM,CAC/E,CAACC,OAASA,SAAS,QACpB;AAED,OAAO,SAASC,sBAAsBD,IAAa;IACjD,OACE,OAAOA,SAAS,YAChB,AAACF,uBAA6CI,QAAQ,CAACF;AAE3D;AAEA,2EAA2E,GAC3E,OAAO,SAASG,6BAA6BC,IAAa;IACxD,IAAI,OAAOA,SAAS,UAAU,OAAOC;IACrC,MAAMC,UAAUF,KAAKG,IAAI,GAAGC,KAAK,CAAC,GAAGX;IACrC,OAAOS,WAAWD;AACpB;AAEA;;;;;CAKC,GACD,OAAO,SAASI,oBACdC,GAAgD;IAEhD,MAAMC,MAAMD,uBAAAA,IAAKE,eAAe;IAChC,IAAI,CAACD,OAAO,OAAOA,QAAQ,YAAY,CAACV,sBAAsBU,IAAIX,IAAI,GAAG;QACvE,OAAO;IACT;IACA,MAAMI,OAAOD,6BAA6BQ,IAAIP,IAAI;IAClD,MAAMS,SAASC,+BAA+BH,IAAIX,IAAI,EAAEW;IACxD,OAAO;QACLX,MAAMW,IAAIX,IAAI;QACde,YAAY,OAAOJ,IAAII,UAAU,KAAK,WAAWJ,IAAII,UAAU,GAAG;QAClEC,YAAYC,OAAOC,QAAQ,CAACP,IAAIK,UAAU,IAAIC,OAAON,IAAIK,UAAU,IAAI;OACnEZ,OAAO;QAAEA;IAAK,IAAI,CAAC,GACpBS;AAEP;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,+BACdd,IAAa,EACbmB,KAGa;IAEb,MAAMC,SAAS7B,kBAAkB4B,yBAAAA,MAAOE,MAAM;IAC9C,MAAMA,SAAuBjC,sBAAsBgC,OAAOC,MAAM,EAAErB,MAAMqB,MAAM;IAC9E,MAAMC,WACJH,CAAAA,yBAAAA,MAAOG,QAAQ,MAAK,UAAUH,CAAAA,yBAAAA,MAAOG,QAAQ,MAAK,UAAUH,MAAMG,QAAQ,GAAGjB;IAC/E,MAAMkB,SAASjC,sBAAsB6B,yBAAAA,MAAOI,MAAM;IAClD,MAAMC,SAASH,OAAOI,OAAO,GACzB/B,WAAWyB,yBAAAA,MAAOK,MAAM,IACtBL,MAAMK,MAAM,GACZJ,OAAOI,MAAM,GACfnB;IACJ,OAAO,aACDhB,gBAAgBgC,UAAU;QAAEA;IAAO,IAAI,CAAC,GACxCC,WAAW;QAAEA;IAAS,IAAI,CAAC,GAC3BC,SAAS;QAAEA;IAAO,IAAI,CAAC,GACvBC,SAAS;QAAEA;IAAO,IAAI,CAAC;AAE/B;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASE,wBACdhB,GAAgD;IAEhD,IAAIjB,yBAAyBiB,uBAAAA,IAAKiB,aAAa,GAAG,OAAO;IACzD,OAAOlB,oBAAoBC;AAC7B;AAKA;;;;;CAKC,GACD,OAAO,SAASkB,sBAAsBC,QAAwB;IAC5D,MAAMR,SAASjC,sBAAsByC,SAASR,MAAM,EAAEQ,SAAS7B,IAAI,EAAEqB,MAAM;IAC3E,MAAME,SAASjC,sBAAsBuC,SAASN,MAAM;IACpD,MAAMD,WAAWO,SAASP,QAAQ,KAAK,UAAUO,SAASP,QAAQ,KAAK,UACnEO,SAASP,QAAQ,GACjB;IACJ,OAAO;QACLtB,MAAM6B,SAAS7B,IAAI;QACnBsB,QAAQ,EAAEA,mBAAAA,WAAY;QACtB,sEAAsE;QACtE,mEAAmE;QACnEQ,gBAAgBR,aAAa;QAC7BS,cAAc;OACVV,OAAOI,OAAO,GAAG;QAAEO,IAAI;IAAc,IAAI,CAAC,GAC1CX,OAAOI,OAAO,IAAI/B,WAAWmC,SAASL,MAAM,IAAI;QAAEA,QAAQK,SAASL,MAAM;IAAC,IAAI,CAAC,GAC/EnC,gBAAgBgC,UAAU;QAAEA;IAAO,IAAI,CAAC,GACxCE,SAAS;QAAEA;IAAO,IAAI,CAAC;AAE/B;AAEA,4EAA4E,GAC5E,OAAO,SAASU,2BACdC,OAAe,EACfL,QAAwB;IAExB,OAAOrC,sBAAsB0C,SAASN,sBAAsBC;AAC9D;AAEA,2DAA2D,GAC3D,OAAO,SAASM,uBACdN,QAAwB,EACxBO,UAA8B,CAAC,CAAC;QAKpBP,kBACEA,oBACFA,kBACAA;IANZ,OAAO1C,eACL;QACEa,MAAM6B,SAAS7B,IAAI;QACnBqB,MAAM,GAAEQ,mBAAAA,SAASR,MAAM,YAAfQ,mBAAmB;QAC3BP,QAAQ,GAAEO,qBAAAA,SAASP,QAAQ,YAAjBO,qBAAqB;QAC/BN,MAAM,GAAEM,mBAAAA,SAASN,MAAM,YAAfM,mBAAmB;QAC3BL,MAAM,GAAEK,mBAAAA,SAASL,MAAM,YAAfK,mBAAmB;IAC7B,GACAO;AAEJ;AAEA,mDAAmD,GACnD,OAAO,SAASC,wBACdR,QAA0C,EAC1CO,OAAyD;QAEvCA;IAAlB,MAAME,aAAYF,mBAAAA,QAAQG,OAAO,qBAAfH,iBAAiB7B,IAAI;IACvC,MAAMiC,OAAOF,YACT,GAAGA,UAAU,GAAG,EAAEF,QAAQK,WAAW,CAAC,KAAK,CAAC,GAC5C,CAAC,KAAK,EAAEL,QAAQK,WAAW,CAAC,KAAK,CAAC;IACtC,OAAO,GAAGD,KAAK,cAAc,EAAE7C,WAAW,CAACkC,SAAS7B,IAAI,CAAC,CAAC,KAAK,CAAC;AAClE"}

package/src/lib/foundation/definitions/org-billing.types.d.ts

@@ -135,11 +135,10 @@ export interface CoreOrgFeatureFlags {
      * generate-section rung every tier from Pro up carries. This is the
      * expensive rung: a generated surface carries the node tree, the catalog
      * and the theme in and iterates, so it draws credits by the hundreds where
-     * a question draws tens. No self-serve tier includes it; the Aglyn AI
-     * add-on (`OrgSeatAddons.aiAddon`) switches it on and adds the credit band
-     * that funds it, and `resolveOrgEntitlements` flips this flag together
-     * with `aiAssist` when the add-on is present. Enterprise carries it in the
-     * agreement.
+     * a question draws tens. Since AGL-3965 every plan carries it: the plan's
+     * included `assistCreditsPerMonth` pays for generation and assist alike
+     * (one pool), an Aglyn AI tier adds credits on top, and Free's taste keeps
+     * its own wall. Enterprise carries it in the agreement.
      */
     aiGenerative?: boolean;
     /** No-code workflow builder (AGL-101). */
@@ -661,6 +660,11 @@ export interface OrgPlanComp {
     /** When it was granted — the server's clock. */
     grantedAt: ITimestamp | null;
 }
+/**
+ * The Aglyn AI tiers (AGL-3965), smallest first. Sold on their own to any
+ * paid plan; the figures are `AI_TIERS` in `plan-entitlements.ts`.
+ */
+export type AiTierId = 'spark' | 'boost' | 'plus' | 'max' | 'ultra' | 'studio';
 /**
  * Paid addon quantities (AGL-112/524) purchased on top of the plan's
  * included allowances, billed as items on the org's Stripe subscription.
@@ -716,11 +720,10 @@ export interface OrgSeatAddons {
     /**
      * Aglyn AI org-wide toggle, 0/1 (AGL-2896). One purchase covers every
      * host in the org, the way Event Calendar does: `resolveOrgEntitlements`
-     * reads any quantity >= 1 as one, adds the plan's
-     * `AI_ADDON_CREDITS_PER_MONTH` band to `assistCreditsPerMonth`, and
-     * switches `features.aiGenerative` and `features.aiAssist` on. Priced per
-     * plan at `PlanPricing.aiAddonMonthlyUsd`; `null` there means the plan
-     * does not sell it.
+     * reads any quantity >= 1 as one and adds the purchased tier's credits
+     * (`AI_TIERS[org.aiTier].credits`, AGL-3965) to `assistCreditsPerMonth`.
+     * WHICH tier is `AglynOrgBilling.aiTier`; the price is the tier's, on any
+     * paid plan (`planSellsAiTiers`).
      */
     aiAddon?: number;
 }
@@ -1142,6 +1145,18 @@ export interface AglynOrgBilling extends AglynDocument {
     enabledPlugins?: string[];
     /** Purchased addon seats (AGL-112); billed monthly per seat. */
     seatAddons?: OrgSeatAddons;
+    /**
+     * Which Aglyn AI tier `seatAddons.aiAddon` is (AGL-3965): Spark through
+     * Studio, read off the subscription's AI item by the webhook and the
+     * add-ons route, and written beside `seatAddons` by the same writes. An
+     * ENTITLEMENT INPUT like `seatAddons`, so Admin-SDK-only.
+     *
+     * Absent on an org whose add-on was bought before tiers existed: it then
+     * reads as the tier with that plan's old band and price
+     * (`LEGACY_AI_ADDON_TIER_BY_PLAN`), so no bill and no credit figure moved.
+     * `null` once written means no tier is held.
+     */
+    aiTier?: AiTierId | null;
     /**
      * POS register seats assigned out of the org pool (AGL-1775). An
      * ENTITLEMENT INPUT: it raises a per-site cap, so it is Admin-SDK-only.
@@ -1259,6 +1274,21 @@ export interface OrgUpgradeProposal {
     proposedAt: number;
     /** An optional line from staff, shown with the proposal. */
     note?: string;
+    /**
+     * The add-ons proposed with the plan (AGL-3956), by `org.seatAddons` kind,
+     * fitted to what the plan sells. Billing preselects them beside the plan.
+     */
+    addons?: Partial<Record<keyof Required<OrgSeatAddons>, number>>;
+    /** The cadence proposed, when staff chose one; absent leaves Billing's toggle alone. */
+    interval?: 'month' | 'year';
+    /** A promotion code minted on the staff Coupons page, applied at checkout. */
+    coupon?: string;
+    /**
+     * The Aglyn AI tier proposed with the AI add-on (AGL-3965), written
+     * `ai:<tier>` in the add-on list. Absent, checkout sells the plan's
+     * default tier.
+     */
+    aiTier?: AiTierId;
 }
 /**
  * What the CRM lets an organization decide for every site at once