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

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';
@@ -220,6 +220,14 @@ export declare const SELF_SERVE_PLANS: OrgPlan[];
  * "free". Revenue for such an org comes from `subscription.customMonthlyUsd`.
  */
 export declare function isCustomPricedPlan(plan: OrgPlan | undefined | null): boolean;
+/**
+ * Whether a plan sells the Site Care add-on (AGL-3954): every paid self-serve
+ * plan, never `free` (no subscription to bill it on) and never a
+ * custom-priced plan (Enterprise names it in the agreement instead). An
+ * unknown plan string sells nothing. The ONE reading of that rule — the
+ * add-on ceiling, the checkout refusal and the Billing card all ask it.
+ */
+export declare function planSellsSiteCare(plan: OrgPlan | string | undefined | null): boolean;
 /** Human plan names — the ONE source every plan badge/label reads. */
 export declare const PLAN_LABELS: Record<OrgPlan, string>;
 /**
@@ -235,6 +243,59 @@ export declare const PLAN_LABELS: Record<OrgPlan, string>;
  * The marketing copy on /pricing is written against that behaviour.
  */
 export declare const EVENT_CALENDAR_ADDON_MONTHLY_USD = 9;
+/**
+ * Site Care add-on (AGL-3954): $49/mo per organization, the managed-website
+ * service. It buys staff time, not capacity: small changes to the owner's
+ * existing site (hours, prices, photos, a staff member, a seasonal banner, a
+ * section on an existing page), up to about one hour of work a month, done
+ * within two business days, minutes logged and no rollover. New pages, new
+ * forms, redesigns, brand work, photography, whole-site copy and ads are
+ * quoted separately, and it never raises a plan limit — a 26th page or a
+ * second site is still an upgrade.
+ *
+ * Flat across plans, like the Event Calendar, because the work it pays for
+ * is the same hour whichever tier the site is on; the yearly price is ×12
+ * with no discount, as every add-on's is. Sold on every paid self-serve plan
+ * and never on Free (no subscription to carry it) or Enterprise (quoted per
+ * deal) — `planSellsSiteCare` is that rule. `resolveOrgEntitlements` flips
+ * 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
@@ -243,37 +304,105 @@ export declare const EVENT_CALENDAR_ADDON_MONTHLY_USD = 9;
  */
 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
@@ -437,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,
@@ -762,6 +856,12 @@ export declare function orgListPriceMonthlyUsd(org: Partial<AglynOrgBilling> | n
  * `NaN` or a negative is none.
  */
 export declare function aiAddonUnits(addons: OrgSeatAddons | null | undefined): 0 | 1;
+/**
+ * How many Site Care add-ons a purchase map counts as: 0 or 1 (AGL-3954).
+ * Org-wide like the Aglyn AI add-on, so a quantity above one is one
+ * purchase, and a non-number, `NaN` or a negative is none.
+ */
+export declare function siteCareUnits(addons: OrgSeatAddons | null | undefined): 0 | 1;
 /**
  * A list price net of a discount (AGL-1105). Percentage discounts scale the
  * whole bill; fixed discounts subtract a flat USD amount. Never below 0, and
@@ -1458,6 +1558,62 @@ 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
+ * reads false here exactly as it drops `features.siteCare`. The reader for
+ * surfaces that ask about the purchase rather than the resolved feature —
+ * the staff org page's chip, the request intake.
+ */
+export declare function hasSiteCare(org: Partial<AglynOrgBilling> | null | undefined): boolean;
 /**
  * Numeric entitlement keys that were REMOVED from `PLAN_ENTITLEMENTS` and
  * must never be resolved again from a stored override (AGL-2133).
@@ -1504,7 +1660,7 @@ export declare const PRICE_ENTITLEMENT_KEYS: ReadonlySet<string>;
  * per-key overrides applied (features merge key-by-key too), then
  * purchased add-ons stacked on top (AGL-524): `seatAddons.hosts` raises
  * `hostLimit`, `seatAddons.eventCalendar` switches the `eventCalendar`
- * feature on, and every seat add-on a plugin declared through
+ * feature on, `seatAddons.siteCare` switches `siteCare` on, and every seat add-on a plugin declared through
  * `registerPluginEntitlements` (AGL-2940) widens the quota it names by its
  * per-plan figure per unit and switches its features on — the Aglyn AI
  * add-on (AGL-2896) is the first such declaration. (Seat/dataset add-ons