@arnaudjnn/billing-tools 0.55.0 → 0.57.0

package/dist/plan-model.js

@@ -0,0 +1,342 @@
+// What a plan IS, as data — and the normaliser that turns any accepted shape
+// into one internal form.
+//
+// ZERO IMPORTS, deliberately. `plans.ts` imports `billing.ts` → `stripe`, so
+// anything defined there can never be read by a browser bundle or a docs
+// generator. The plan model has to be readable by both (a pricing card and a
+// markdown table are the same derivation), so it lives here on its own, like
+// `ui/limits.ts` does for the same reason.
+//
+// ── Why five axes instead of one ────────────────────────────────────────────
+//
+// A plan used to be `{ seats, tokensPerSeat, price, seatTypes?, allowanceMode? }`
+// and that shape can only really express one product: per-seat, with a per-seat
+// pack. Everything else was squeezed into `allowanceMode`, which despite its
+// name does exactly ONE thing — skip the per-seat cap. There was no org-level
+// allowance anywhere, so "we don't care about seats, here is a package of N tool
+// requests" was unrepresentable, and a plan-level `tokensPerSeat` on such a plan
+// was simply never read.
+//
+// What varies between products turns out to be five independent things:
+//
+//   sells      what Stripe charges for      (nothing | seats | flat)
+//   grant      what is CREDITED as money    (none | purchased_seats | …)
+//   cap        what is INCLUDED, as a limit (wallet | per_seat | pool)
+//   replenish  how to get more              (purchase | autoReload | request)
+//   sale       whether it can be bought     (free | self_serve | quote | legacy)
+//
+// Only `sells` is a discriminated union, because it alone decides which other
+// fields are REQUIRED and what `ensurePlans` mints. Tagging all five under one
+// `kind` would need a member per combination (`flat_pool_block_quote`), so the
+// rest are plain fields with defaults derived from `sells`.
+//
+// ── Why `grant` and `cap` are different axes ────────────────────────────────
+//
+// This is the distinction the old model was missing, and it is a money bug, not
+// a modelling preference. `grant` credits the Stripe customer balance. A Stripe
+// credit balance AUTO-APPLIES to the customer's next invoice and cannot be
+// opted out of — measured: granting 1000 tokens to a customer on a €21.04 seat
+// produced an invoice with `starting_balance: -1000` and `amount_due: 1104`. So
+// crediting a plan's "included" allowance discounts its own renewal by half, and
+// an annual pool credited as money would invoice year two at zero.
+//
+// An included allowance is therefore a `cap`: a window that usage is COUNTED
+// against, with no money moving. Credit stays what it is actually for —
+// PURCHASED tokens (a top-up), which the customer really can spend.
+export const INTERVALS = ["monthly", "yearly"];
+export const isLegacyPlan = (d) => !("sells" in d);
+/**
+ * Identity helper for a plans config.
+ *
+ * Annotating with `PlanCatalog` widens the keys to `string` and loses `display`
+ * autocomplete; this keeps the literal types while still checking the shape.
+ */
+export function definePlans(plans) {
+    return plans;
+}
+const hasPrice = (p) => p.monthly > 0 || p.yearly > 0;
+function normalizeSeatTypes(seatTypes) {
+    return Object.entries(seatTypes).map(([key, s]) => {
+        const legacy = s;
+        const spec = s;
+        return {
+            key,
+            price: s.price,
+            includedTokens: s.includedTokens ?? 0,
+            min: spec.min ?? 0,
+            // `seats` was the legacy name for a per-type cap.
+            max: spec.max ?? legacy.seats ?? null,
+            shared: spec.shared ?? false,
+            display: spec.display ?? (legacy.label ? { label: legacy.label } : null),
+        };
+    });
+}
+/** Intervals a price actually exists for, so a plan can't advertise an interval
+ *  Stripe has no price for. */
+function soldIntervals(declared, price, seatTypes) {
+    if (declared)
+        return declared;
+    const has = (i) => (price ? price[i] > 0 : false) || seatTypes.some((s) => s.price[i] > 0);
+    return INTERVALS.filter(has);
+}
+export function normalizePlan(key, spec) {
+    if (!isLegacyPlan(spec)) {
+        const seatTypes = spec.sells.kind === "seats" ? normalizeSeatTypes(spec.sells.seatTypes) : [];
+        const price = spec.sells.kind === "flat" ? spec.sells.price : null;
+        const declared = spec.sells.kind === "nothing" ? [] : spec.sells.intervals;
+        return {
+            key,
+            sells: spec.sells,
+            grant: spec.grant ?? { kind: spec.sells.kind === "seats" ? "purchased_seats" : "none" },
+            cap: spec.cap ?? { kind: spec.sells.kind === "seats" ? "per_seat" : "wallet" },
+            replenish: spec.replenish ?? {},
+            sale: spec.sale,
+            limits: { members: spec.limits?.members ?? null },
+            display: spec.display ?? null,
+            intervals: soldIntervals(declared, price, seatTypes),
+            seatTypes,
+            price,
+            legacy: false,
+        };
+    }
+    // Legacy. Every mapping here is behaviour-preserving; the property to hold is
+    // that no legacy config can produce `cap: "pool"`, so the new entitlement
+    // path stays dead until a config opts in.
+    const seatTypes = spec.seatTypes ? normalizeSeatTypes(spec.seatTypes) : [];
+    const sells = spec.seatTypes
+        ? { kind: "seats", seatTypes: spec.seatTypes }
+        : hasPrice(spec.price)
+            ? { kind: "flat", price: spec.price }
+            : { kind: "nothing" };
+    const grant = spec.seatTypes
+        ? { kind: "purchased_seats" }
+        : hasPrice(spec.price)
+            ? { kind: "per_member", tokens: spec.tokensPerSeat }
+            : { kind: "none" };
+    return {
+        key,
+        sells,
+        grant,
+        // "global" meant "no cap", full stop.
+        cap: spec.allowanceMode === "global"
+            ? { kind: "wallet" }
+            : { kind: "per_seat", onExhausted: "block" },
+        replenish: {},
+        // Not knowable from the legacy shape, so it is guessed from whether ANY
+        // price exists — note a seat-typed plan whose every seat is 0 mints no
+        // Stripe price and therefore cannot be bought, which the old `price > 0`
+        // test on the plan-level amount got wrong in both directions. The doctor
+        // warns either way, because guessing this is what sold a quote-only plan.
+        sale: soldIntervals(undefined, sells.kind === "flat" ? spec.price : null, seatTypes).length === 0
+            ? "free"
+            : "self_serve",
+        limits: { members: spec.seats },
+        display: null,
+        intervals: soldIntervals(undefined, sells.kind === "flat" ? spec.price : null, seatTypes),
+        seatTypes,
+        price: sells.kind === "flat" ? spec.price : null,
+        legacy: true,
+    };
+}
+export function normalizePlans(plans) {
+    return Object.entries(plans).map(([key, spec]) => normalizePlan(key, spec));
+}
+export function planModel(plans, key) {
+    if (!key)
+        return null;
+    const spec = plans[key];
+    return spec ? normalizePlan(key, spec) : null;
+}
+/** Plan keys matching a predicate, e.g. `plansWhere(PLANS, p => p.sale === "self_serve")`.
+ *  Replaces the several hand-maintained lists of "which plans can be bought". */
+export function plansWhere(plans, predicate) {
+    return normalizePlans(plans)
+        .filter(predicate)
+        .map((m) => m.key);
+}
+/** Plans a customer can buy without talking to anyone. */
+export const selfServePlans = (plans) => plansWhere(plans, (p) => p.sale === "self_serve" && p.sells.kind !== "nothing");
+/** Where a seat stepper starts: each type's `min`, with the plan's `minSeats`
+ *  absorbed by the first non-shared type so the default basket is already valid. */
+export function defaultBasket(model) {
+    const basket = {};
+    for (const s of model.seatTypes)
+        basket[s.key] = s.min;
+    if (model.sells.kind !== "seats")
+        return basket;
+    const min = model.sells.minSeats ?? 0;
+    const total = Object.values(basket).reduce((a, b) => a + b, 0);
+    if (total < min) {
+        const first = model.seatTypes.find((s) => !s.shared) ?? model.seatTypes[0];
+        if (first)
+            basket[first.key] = (basket[first.key] ?? 0) + (min - total);
+    }
+    return basket;
+}
+/**
+ * Everything wrong with a basket, as data.
+ *
+ * Pure and network-free, so it can run in a stepper and at the checkout
+ * boundary from one implementation. `seats` and the per-type caps were declared
+ * for a long time and enforced nowhere: a crafted request could buy any
+ * quantity of any seat type, including fifty of a seat meant to be unique.
+ */
+export function validateBasket(plans, opts) {
+    const model = planModel(plans, opts.plan);
+    if (!model)
+        return [{ code: "unknown_plan" }];
+    const problems = [];
+    const purchasing = (opts.for ?? "purchase") === "purchase";
+    if (purchasing && model.sale !== "self_serve") {
+        problems.push({ code: "not_purchasable", sale: model.sale });
+    }
+    if (opts.interval && model.intervals.length && !model.intervals.includes(opts.interval)) {
+        problems.push({ code: "interval_unavailable", interval: opts.interval });
+    }
+    if (model.sells.kind !== "seats")
+        return problems;
+    const seats = opts.seats ?? {};
+    const known = new Map(model.seatTypes.map((s) => [s.key, s]));
+    let total = 0;
+    for (const [key, qty] of Object.entries(seats)) {
+        if (qty <= 0)
+            continue;
+        const type = known.get(key);
+        if (!type) {
+            problems.push({ code: "unknown_seat_type", seatType: key });
+            continue;
+        }
+        total += qty;
+        if (type.max !== null && qty > type.max) {
+            problems.push({ code: "seat_type_limit", seatType: key, max: type.max, got: qty });
+        }
+    }
+    const min = model.sells.minSeats ?? 0;
+    if (total < min)
+        problems.push({ code: "below_minimum", min, got: total });
+    const max = model.sells.maxSeats ?? null;
+    if (max !== null && total > max)
+        problems.push({ code: "seat_limit", max, got: total });
+    const members = model.limits.members;
+    if (members !== null && total > members) {
+        problems.push({ code: "member_limit", max: members, got: total });
+    }
+    return problems;
+}
+/** One-line summary of a basket problem, for an error message. */
+export function describeBasketProblem(p) {
+    switch (p.code) {
+        case "unknown_plan":
+            return "Unknown plan";
+        case "not_purchasable":
+            return `This plan is not self-serve (${p.sale})`;
+        case "unknown_seat_type":
+            return `Unknown seat type "${p.seatType}"`;
+        case "below_minimum":
+            return `At least ${p.min} seats are required (got ${p.got})`;
+        case "seat_limit":
+            return `At most ${p.max} seats (got ${p.got})`;
+        case "seat_type_limit":
+            return `At most ${p.max} "${p.seatType}" seat(s) (got ${p.got})`;
+        case "member_limit":
+            return `This plan allows at most ${p.max} members (got ${p.got})`;
+        case "interval_unavailable":
+            return `This plan is not sold ${p.interval}`;
+    }
+}
+// ── Allowance sizing ────────────────────────────────────────────────────────
+/** Tokens to CREDIT for a paid cycle. Zero for `grant: none`, which is now the
+ *  default for anything whose allowance is an entitlement. */
+export function grantFor(model, ctx) {
+    if (!model)
+        return 0;
+    switch (model.grant.kind) {
+        case "none":
+            return 0;
+        case "fixed":
+            return model.grant.tokens;
+        case "per_member":
+            // The old flat path floored the count at 1 — a subscription with no
+            // recorded members still granted one seat's worth.
+            return model.grant.tokens * Math.max(1, ctx.memberCount ?? 0);
+        case "purchased_seats": {
+            const counts = ctx.seatCounts ?? {};
+            let sum = 0;
+            for (const s of model.seatTypes)
+                sum += s.includedTokens * (counts[s.key] ?? 0);
+            return sum;
+        }
+    }
+}
+/** The org-wide entitlement for a cycle, or null when the plan has no pool.
+ *  Falls back to the grant size when a plan both pools and credits. */
+export function poolSizeOf(model) {
+    if (!model || model.cap.kind !== "pool")
+        return null;
+    if (model.cap.tokens != null)
+        return model.cap.tokens;
+    return model.grant.kind === "fixed" ? model.grant.tokens : 0;
+}
+/** The pack a caller is entitled to for the cycle, or null when uncapped. */
+export function packSizeOf(model, seatType) {
+    if (!model || model.cap.kind !== "per_seat" || !seatType)
+        return null;
+    const type = model.seatTypes.find((s) => s.key === seatType);
+    return type ? type.includedTokens : null;
+}
+/**
+ * What to do when a window is used up.
+ *
+ * An agent's usage overflows into the wallet; a person's blocks. That was
+ * previously a hardcoded `caller.kind === "user"` test in the meter, so the
+ * caller kind is still honoured — a legacy config has no way to mark a seat type
+ * as shared, and changing behaviour for it silently is not on. A config that
+ * DOES declare `shared: true` gets the same answer without depending on how the
+ * call arrived.
+ */
+export function exhaustedPolicy(model, caller) {
+    if (!model)
+        return "wallet";
+    if (caller?.kind === "api")
+        return "wallet";
+    const type = caller?.seatType
+        ? model.seatTypes.find((s) => s.key === caller.seatType)
+        : undefined;
+    if (type?.shared)
+        return "wallet";
+    if (model.cap.kind === "pool")
+        return model.cap.onExhausted ?? "block";
+    if (model.cap.kind === "per_seat")
+        return model.cap.onExhausted ?? "block";
+    return "wallet";
+}
+const startOfMonthUTC = (now) => {
+    const d = new Date(now);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
+};
+/**
+ * The window usage is measured over.
+ *
+ * The SUBSCRIPTION period, when one is known — an annual pool measured over
+ * calendar months would reset twelve times a year, handing out twelve times the
+ * package. The calendar month remains the fallback for an org with no
+ * subscription (a free plan, or a pure wallet), which is what this library did
+ * unconditionally before.
+ *
+ * `rollover` widens the window to the subscription's start instead, which is all
+ * "unused allowance carries over" has to mean.
+ */
+export function cycleWindowFor(model, period, now = Date.now()) {
+    const ms = (v) => v == null ? null : typeof v === "number" ? v : Date.parse(v) || null;
+    const start = ms(period?.start);
+    const end = ms(period?.end);
+    const rollover = model?.cap.kind === "pool" && model.cap.rollover === true;
+    if (start && (rollover || start <= now)) {
+        const from = start;
+        const until = rollover ? null : end;
+        return { start: from, end: until, key: new Date(from).toISOString().slice(0, 10) };
+    }
+    const month = startOfMonthUTC(now);
+    return { start: month, end: null, key: new Date(month).toISOString().slice(0, 7) };
+}
+//# sourceMappingURL=plan-model.js.map

package/dist/plan-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-model.js","sourceRoot":"","sources":["../src/plan-model.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,0BAA0B;AAC1B,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,2CAA2C;AAC3C,EAAE;AACF,+EAA+E;AAC/E,EAAE;AACF,kFAAkF;AAClF,gFAAgF;AAChF,6EAA6E;AAC7E,8EAA8E;AAC9E,iFAAiF;AACjF,iFAAiF;AACjF,yBAAyB;AACzB,EAAE;AACF,wEAAwE;AACxE,EAAE;AACF,qEAAqE;AACrE,yEAAyE;AACzE,uEAAuE;AACvE,8EAA8E;AAC9E,iFAAiF;AACjF,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,4DAA4D;AAC5D,EAAE;AACF,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,2EAA2E;AAC3E,+EAA+E;AAC/E,gFAAgF;AAChF,iFAAiF;AACjF,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,oEAAoE;AAcpE,MAAM,CAAC,MAAM,SAAS,GAA+B,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AA+P3E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAqB,EAAgB,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;AAErF;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAA+C,KAAQ;IAChF,OAAO,KAAK,CAAC;AACf,CAAC;AAkCD,MAAM,QAAQ,GAAG,CAAC,CAAgB,EAAW,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAE9E,SAAS,kBAAkB,CACzB,SAAqD;IAErD,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE;QAChD,MAAM,MAAM,GAAG,CAAgB,CAAC;QAChC,MAAM,IAAI,GAAG,CAAiB,CAAC;QAC/B,OAAO;YACL,GAAG;YACH,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,cAAc,EAAE,CAAC,CAAC,cAAc,IAAI,CAAC;YACrC,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;YAClB,kDAAkD;YAClD,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,MAAM,CAAC,KAAK,IAAI,IAAI;YACrC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,KAAK;YAC5B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SACzE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;+BAC+B;AAC/B,SAAS,aAAa,CACpB,QAAgD,EAChD,KAA2B,EAC3B,SAAoC;IAEpC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,GAAG,GAAG,CAAC,CAAkB,EAAE,EAAE,CACjC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1E,OAAO,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,IAAwB;IACjE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,SAAS,GACb,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACnE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;QAC3E,OAAO;YACL,GAAG;YACH,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,EAAE;YACvF,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;YAC9E,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE;YAC/B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,IAAI,IAAI,EAAE;YACjD,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,IAAI;YAC7B,SAAS,EAAE,aAAa,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,CAAC;YACpD,SAAS;YACT,KAAK;YACL,MAAM,EAAE,KAAK;SACd,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,0EAA0E;IAC1E,0CAA0C;IAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,MAAM,KAAK,GAAU,IAAI,CAAC,SAAS;QACjC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;QAC9C,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YACpB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;YACrC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAU,IAAI,CAAC,SAAS;QACjC,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE;QAC7B,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YACpB,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE;YACpD,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO;QACL,GAAG;QACH,KAAK;QACL,KAAK;QACL,sCAAsC;QACtC,GAAG,EACD,IAAI,CAAC,aAAa,KAAK,QAAQ;YAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE;YACpB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE;QAChD,SAAS,EAAE,EAAE;QACb,wEAAwE;QACxE,uEAAuE;QACvE,yEAAyE;QACzE,yEAAyE;QACzE,0EAA0E;QAC1E,IAAI,EAAE,aAAa,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC;YAC/F,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,YAAY;QAChB,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE;QAC/B,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,aAAa,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC;QACzF,SAAS;QACT,KAAK,EAAE,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;QAChD,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAkB;IAC/C,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAkB,EAAE,GAA8B;IAC1E,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED;iFACiF;AACjF,MAAM,UAAU,UAAU,CACxB,KAAkB,EAClB,SAAwC;IAExC,OAAO,cAAc,CAAC,KAAK,CAAC;SACzB,MAAM,CAAC,SAAS,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAkB,EAAY,EAAE,CAC7D,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;AAMlF;oFACoF;AACpF,MAAM,UAAU,aAAa,CAAC,KAAgB;IAC5C,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS;QAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;IACvD,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,MAAM,CAAC;IAChD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/D,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QAChB,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,KAAK;YAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAYD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAkB,EAClB,IAOC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;IAE9C,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,UAAU,CAAC,KAAK,UAAU,CAAC;IAC3D,IAAI,UAAU,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxF,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC;IAElD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,IAAI,CAAC;YAAE,SAAS;QACvB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;YAC5D,SAAS;QACX,CAAC;QACD,KAAK,IAAI,GAAG,CAAC;QACb,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;IACtC,IAAI,KAAK,GAAG,GAAG;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3E,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC;IACzC,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,GAAG,GAAG;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACxF,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC;IACrC,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;QACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,qBAAqB,CAAC,CAAgB;IACpD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;QACxB,KAAK,iBAAiB;YACpB,OAAO,gCAAgC,CAAC,CAAC,IAAI,GAAG,CAAC;QACnD,KAAK,mBAAmB;YACtB,OAAO,sBAAsB,CAAC,CAAC,QAAQ,GAAG,CAAC;QAC7C,KAAK,eAAe;YAClB,OAAO,YAAY,CAAC,CAAC,GAAG,4BAA4B,CAAC,CAAC,GAAG,GAAG,CAAC;QAC/D,KAAK,YAAY;YACf,OAAO,WAAW,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,GAAG,GAAG,CAAC;QACjD,KAAK,iBAAiB;YACpB,OAAO,WAAW,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,QAAQ,kBAAkB,CAAC,CAAC,GAAG,GAAG,CAAC;QACnE,KAAK,cAAc;YACjB,OAAO,4BAA4B,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,GAAG,GAAG,CAAC;QACpE,KAAK,sBAAsB;YACzB,OAAO,yBAAyB,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjD,CAAC;AACH,CAAC;AAED,+EAA+E;AAE/E;8DAC8D;AAC9D,MAAM,UAAU,QAAQ,CACtB,KAAuB,EACvB,GAAsD;IAEtD,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,QAAQ,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACzB,KAAK,MAAM;YACT,OAAO,CAAC,CAAC;QACX,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;QAC5B,KAAK,YAAY;YACf,oEAAoE;YACpE,mDAAmD;YACnD,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;QAChE,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;YACpC,IAAI,GAAG,GAAG,CAAC,CAAC;YACZ,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS;gBAAE,GAAG,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAChF,OAAO,GAAG,CAAC;QACb,CAAC;IACH,CAAC;AACH,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,UAAU,CAAC,KAAuB;IAChD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;IACtD,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAC,KAAuB,EAAE,QAA4B;IAC9E,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtE,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAuB,EACvB,MAAqD;IAErD,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5B,IAAI,MAAM,EAAE,IAAI,KAAK,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,EAAE,QAAQ;QAC3B,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,QAAQ,CAAC;QACxD,CAAC,CAAC,SAAS,CAAC;IACd,IAAI,IAAI,EAAE,MAAM;QAAE,OAAO,QAAQ,CAAC;IAClC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC;IACvE,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,CAAC;IAC3E,OAAO,QAAQ,CAAC;AAClB,CAAC;AAaD,MAAM,eAAe,GAAG,CAAC,GAAW,EAAU,EAAE;IAC9C,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAuB,EACvB,MAA+E,EAC/E,MAAc,IAAI,CAAC,GAAG,EAAE;IAExB,MAAM,EAAE,GAAG,CAAC,CAAqC,EAAiB,EAAE,CAClE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACvE,MAAM,KAAK,GAAG,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,EAAE,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC;IAE3E,IAAI,KAAK,IAAI,CAAC,QAAQ,IAAI,KAAK,IAAI,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,KAAK,CAAC;QACnB,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IACrF,CAAC;IACD,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACnC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACrF,CAAC"}

package/dist/plans.d.ts

@@ -1,46 +1,7 @@
 import type Stripe from "stripe";
-/** One seat type within a plan (e.g. `standard` vs `premium`). Each type has
- *  its own recurring per-seat price and included-token allowance, so a plan's
- *  subscription carries one line item per seat type (quantity = members of that
- *  type). Introduced for the Claude-style Standard/Premium seat model. */
-export interface SeatTypeDef {
-    /** Per-seat recurring price (cents). 0 = free (no Stripe price). */
-    price: {
-        monthly: number;
-        yearly: number;
-    };
-    /** Included tokens granted per seat of THIS type, per billing cycle. */
-    includedTokens: number;
-    /** Optional cap on seats of this type (null/undefined = unlimited). */
-    seats?: number | null;
-    /** Optional display label. */
-    label?: string;
-}
-export interface PlanDef {
-    /** Max members per workspace. null = unlimited. */
-    seats: number | null;
-    /** Included tokens granted per seat, per billing cycle (flat model). */
-    tokensPerSeat: number;
-    /** Recurring price in the smallest currency unit (cents). 0 = free (no Stripe price). */
-    price: {
-        monthly: number;
-        yearly: number;
-    };
-    /** Optional multi-seat-type pricing. When present, `ensurePlans` mints one
-     *  Stripe price per (plan, seatType, interval), the subscription carries one
-     *  line item per seat type, and included tokens sum per type
-     *  (`includedTokensByType`). When ABSENT the flat {seats, tokensPerSeat,
-     *  price} model applies unchanged — existing consumers are unaffected. */
-    seatTypes?: Record<string, SeatTypeDef>;
-    /** How usage is metered against the plan's seats (default `per_seat`):
-     *   • `per_seat` — each seat has its own per-cycle pack (user seats capped
-     *     personally; the API seat is a shared pool + top-up).
-     *   • `global`   — pay per seat, but NO per-seat cap: all usage draws one
-     *     committed workspace token pool (e.g. an Enterprise annual commitment). */
-    allowanceMode?: "per_seat" | "global";
-}
-export type PlansConfig = Record<string, PlanDef>;
-export type BillingInterval = "monthly" | "yearly";
+import { type BillingInterval, type PlanCatalog, type Sale, type SeatTypeDef } from "./plan-model.js";
+export type { BillingInterval, Money, IntervalPrice, SeatTypeDef, SeatTypeSpec, SeatTypeDisplay, PlanDef, PlanSpec, PlanDisplay, PlanLimits, PlansConfig, PlanCatalog, PlanModel, NormalSeatType, Sells, Grant, Cap, Exhausted, Replenish, Sale, Quantities, BasketProblem, CycleWindow, } from "./plan-model.js";
+export { definePlans, isLegacyPlan, normalizePlan, normalizePlans, planModel, plansWhere, selfServePlans, defaultBasket, validateBasket, describeBasketProblem, grantFor, poolSizeOf, packSizeOf, exhaustedPolicy, cycleWindowFor, } from "./plan-model.js";
 export declare const DEFAULT_SEAT_TYPES: Record<string, SeatTypeDef>;
 export declare const lookupKeyFor: (plan: string, interval: BillingInterval, seatType?: string) => string;
 export interface EnsuredPrice {
@@ -56,7 +17,7 @@ export interface EnsuredPrice {
 /** Idempotently create/reconcile Stripe products + prices for the paid plans.
  *  Returns the resolved price for every paid plan × interval. Free plans (both
  *  prices 0) create no Stripe objects. Safe to call on every boot / first use. */
-export declare function ensurePlans(plans: PlansConfig, opts?: {
+export declare function ensurePlans(plans: PlanCatalog, opts?: {
     currency?: string;
     taxBehavior?: Stripe.Price.TaxBehavior;
     /**
@@ -115,7 +76,7 @@ export interface MigrateSubscriptionsResult {
  * price attached by hand in the Dashboard is never moved out from under you.
  */
 export declare function migrateSubscriptions(opts: {
-    plans: PlansConfig;
+    plans: PlanCatalog;
     plan: string;
     interval: BillingInterval;
     currency?: string;
@@ -136,7 +97,7 @@ export type PlanPrices = ReadonlyMap<string, string>;
  *
  * Look ids up with `lookupKeyFor(plan, interval, seatType)`.
  */
-export declare function resolvePlanPrices(plans: PlansConfig, opts?: {
+export declare function resolvePlanPrices(plans: PlanCatalog, opts?: {
     currency?: string;
     taxBehavior?: Stripe.Price.TaxBehavior;
 }): Promise<PlanPrices>;
@@ -157,12 +118,23 @@ export declare function planForPriceId(priceId: string): Promise<string | null>;
  *  flat (non-seat-typed) price. */
 export declare function seatTypeForPriceId(priceId: string): Promise<string | null>;
 /** Seat limit for a plan (null = unlimited, undefined plan = null). */
-export declare function seatLimit(plans: PlansConfig, plan: string): number | null;
-/** Included tokens for `seatCount` members on a plan (per cycle, flat model). */
-export declare function includedTokens(plans: PlansConfig, plan: string, seatCount: number): number;
-/** Included tokens for a seat-typed plan given member counts per seat type
- *  (per cycle): Σ seatTypes[t].includedTokens × counts[t]. Falls back to the
- *  flat `includedTokens` (over the total member count) for plans without seat
- *  types, so callers can use it uniformly. */
-export declare function includedTokensByType(plans: PlansConfig, plan: string | null, counts: Record<string, number>): number;
+/** Member limit for a plan (null = unlimited, unknown plan = null). */
+export declare function seatLimit(plans: PlanCatalog, plan: string): number | null;
+/** Per-type seat cap, or null when that type is unlimited. This is what makes a
+ *  `max: 1` shared API seat mean something. */
+export declare function seatTypeLimit(plans: PlanCatalog, plan: string, seatType: string): number | null;
+/** How a plan is sold, which decides whether any checkout path may accept it. */
+export declare function planSale(plans: PlanCatalog, plan: string): Sale | null;
+/**
+ * Tokens to CREDIT for `seatCount` members on a plan, per cycle.
+ *
+ * Now expressed over `grant`, so a plan whose allowance is an ENTITLEMENT
+ * (`grant: none`, the default for everything but a credit-selling plan) returns
+ * 0 — crediting it would discount that plan's own invoice.
+ */
+export declare function includedTokens(plans: PlanCatalog, plan: string, seatCount: number): number;
+/** Tokens to CREDIT given purchased counts per seat type. Falls back to the
+ *  member-count form for plans without seat types, so callers can use it
+ *  uniformly. */
+export declare function includedTokensByType(plans: PlanCatalog, plan: string | null, counts: Record<string, number>): number;
 //# sourceMappingURL=plans.d.ts.map

package/dist/plans.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAWjC;;;0EAG0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,mDAAmD;IACnD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C;;;;8EAI0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxC;;;;oFAIgF;IAChF,aAAa,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC;CACvC;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAClD,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,CAAC;AAQnD,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAI1D,CAAC;AASF,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,EACZ,UAAU,eAAe,EACzB,WAAW,MAAM,KAChB,MAAgF,CAAC;AAEpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,CAAC;IAC1B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAgFD;;kFAEkF;AAClF,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE;IACJ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC;IACvC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;CAC7B,GACL,OAAO,CAAC,YAAY,EAAE,CAAC,CA0FzB;AAcD,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC;;;;;;;OAOG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC,wBAAwB,CAAC,iBAAiB,CAAC;IACtE,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4FtC;AAoCD,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAWrD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,WAAW,CAAA;CAAO,GACvE,OAAO,CAAC,UAAU,CAAC,CAkBrB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;4CAC4C;AAC5C,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBxB;AAED,2EAA2E;AAC3E,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO5E;AAED;mCACmC;AACnC,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOhF;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEzE;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAC5B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,CAIR;AAED;;;8CAG8C;AAC9C,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAYR"}
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"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"}

package/dist/plans.js

@@ -1,4 +1,6 @@
 import { getStripe } from "./billing.js";
+import { grantFor, INTERVALS, normalizePlans, planModel, } from "./plan-model.js";
+export { definePlans, isLegacyPlan, normalizePlan, normalizePlans, planModel, plansWhere, selfServePlans, defaultBasket, validateBasket, describeBasketProblem, grantFor, poolSizeOf, packSizeOf, exhaustedPolicy, cycleWindowFor, } from "./plan-model.js";
 // Library DEFAULT seat types, priced in USD (the lib's default currency — see
 // ensurePlans `opts.currency ?? "usd"`). Consumers use these as-is or override
 // (scartoffie, for instance, sets currency "eur" and its own EUR amounts).
@@ -10,7 +12,6 @@ export const DEFAULT_SEAT_TYPES = {
     premium: { label: "Premium", price: { monthly: 12500, yearly: 120000 }, includedTokens: 5000 }, // $125/mo · $100/mo annually
     api: { label: "API", price: { monthly: 62500, yearly: 600000 }, includedTokens: 25000, seats: 1 }, // ≈ 5× premium, one per workspace
 };
-const INTERVALS = ["monthly", "yearly"];
 const STRIPE_INTERVAL = {
     monthly: "month",
     yearly: "year",
@@ -22,21 +23,34 @@ const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
  *  intervals/seat types produce no Stripe object, so they're dropped here. */
 function priceSpecs(plans) {
     const specs = [];
-    for (const [plan, def] of Object.entries(plans)) {
+    for (const model of normalizePlans(plans)) {
         const of = (interval, amount, seatType) => {
-            if (amount > 0) {
-                specs.push({ plan, interval, seatType, amount, lookupKey: lookupKeyFor(plan, interval, seatType) });
+            // A plan can decline an interval — an annual-only commitment declares
+            // `intervals: ["yearly"]` and no monthly price is ever minted for it.
+            if (amount > 0 && model.intervals.includes(interval)) {
+                specs.push({
+                    plan: model.key,
+                    interval,
+                    seatType,
+                    amount,
+                    lookupKey: lookupKeyFor(model.key, interval, seatType),
+                });
             }
         };
-        if (def.seatTypes) {
-            for (const [seatType, st] of Object.entries(def.seatTypes)) {
+        switch (model.sells.kind) {
+            case "seats":
+                for (const seat of model.seatTypes) {
+                    for (const interval of INTERVALS)
+                        of(interval, seat.price[interval], seat.key);
+                }
+                break;
+            case "flat":
                 for (const interval of INTERVALS)
-                    of(interval, st.price[interval], seatType);
-            }
-        }
-        else {
-            for (const interval of INTERVALS)
-                of(interval, def.price[interval]);
+                    of(interval, model.sells.price[interval]);
+                break;
+            case "nothing":
+                // Free, or a pure prepaid wallet: no Stripe object at all.
+                break;
         }
     }
     return specs;
@@ -140,7 +154,9 @@ export async function ensurePlans(plans, opts = {}) {
         let productId = productByPlan.get(plan);
         if (!productId) {
             const product = await stripe.products.create({
-                name: cap(plan),
+                // The display name when the config has one, so the Stripe Dashboard and
+                // an invoice line read like the product rather than like its key.
+                name: planModel(plans, plan)?.display?.name ?? cap(plan),
                 metadata: { managedBy: MANAGED_BY, plan },
             });
             productId = product.id;
@@ -397,32 +413,37 @@ export async function seatTypeForPriceId(priceId) {
     }
 }
 /** Seat limit for a plan (null = unlimited, undefined plan = null). */
+/** Member limit for a plan (null = unlimited, unknown plan = null). */
 export function seatLimit(plans, plan) {
-    return plans[plan]?.seats ?? null;
+    return planModel(plans, plan)?.limits.members ?? null;
+}
+/** Per-type seat cap, or null when that type is unlimited. This is what makes a
+ *  `max: 1` shared API seat mean something. */
+export function seatTypeLimit(plans, plan, seatType) {
+    return planModel(plans, plan)?.seatTypes.find((s) => s.key === seatType)?.max ?? null;
 }
-/** Included tokens for `seatCount` members on a plan (per cycle, flat model). */
+/** How a plan is sold, which decides whether any checkout path may accept it. */
+export function planSale(plans, plan) {
+    return planModel(plans, plan)?.sale ?? null;
+}
+/**
+ * Tokens to CREDIT for `seatCount` members on a plan, per cycle.
+ *
+ * Now expressed over `grant`, so a plan whose allowance is an ENTITLEMENT
+ * (`grant: none`, the default for everything but a credit-selling plan) returns
+ * 0 — crediting it would discount that plan's own invoice.
+ */
 export function includedTokens(plans, plan, seatCount) {
-    const def = plans[plan];
-    if (!def)
-        return 0;
-    return def.tokensPerSeat * Math.max(1, seatCount);
+    return grantFor(planModel(plans, plan), { memberCount: seatCount });
 }
-/** Included tokens for a seat-typed plan given member counts per seat type
- *  (per cycle): Σ seatTypes[t].includedTokens × counts[t]. Falls back to the
- *  flat `includedTokens` (over the total member count) for plans without seat
- *  types, so callers can use it uniformly. */
+/** Tokens to CREDIT given purchased counts per seat type. Falls back to the
+ *  member-count form for plans without seat types, so callers can use it
+ *  uniformly. */
 export function includedTokensByType(plans, plan, counts) {
-    const def = plan ? plans[plan] : undefined;
-    if (!def)
+    const model = planModel(plans, plan);
+    if (!model)
         return 0;
-    if (!def.seatTypes) {
-        const total = Object.values(counts).reduce((a, b) => a + b, 0);
-        return includedTokens(plans, plan, total);
-    }
-    let sum = 0;
-    for (const [type, st] of Object.entries(def.seatTypes)) {
-        sum += st.includedTokens * (counts[type] ?? 0);
-    }
-    return sum;
+    const total = Object.values(counts).reduce((a, b) => a + b, 0);
+    return grantFor(model, { seatCounts: counts, memberCount: total });
 }
 //# sourceMappingURL=plans.js.map