Plans

The plans module models the catalogue. A PlanGrid groups the plans sold to one audience (teachers, learners) with its own order. A Plan is a tier of a grid: its identity (planKey), its labels, its position (rank) and the entitlement preset a subscription to it grants. A PlanPrice is how a plan is paid for: one row per billing interval the tier is sold on. A plan says what the subscriber gets; a price says how it is paid for. What a subscription to a plan produces is covered in Subscriptions and Entitlements.

Consumers: the admin (the whole catalogue, archived rows included, and every write), the API (the on-sale listing of a grid, the checkout), the subscription reconciliation (resolving a provider price id to the plan whose preset it buys) and the payment adapter.

The services take no ServiceContext: the catalogue is global, not owned by a subject.

Domain

PlanGrid

A catalogue of plans sold to one audience. A plan's rank is unique inside its grid only. A subject may hold one subscription per grid, and their entitlements add up. A subscription reaches its grid through its price and the plan that price sells.

PlanGridPatch is Partial<Pick<PlanGrid, "providerPortalConfigurationId">>: the key is the identity the apps ask for, only the grid's settings are ever patched.

Plan

PlanPreset is the sparse preset, only the keys a plan sells: { limits: GrantLimits; features: ReadonlySet<FeatureKey> }. It is structurally the shape a grant contributes, so resolution reuses the merge rules of the entitlements module. Unlimited is Number.POSITIVE_INFINITY.

NewPlan picks planKey, gridId, labels, rank, preset, providerProductId, status, purchasable. PlanPatch is Partial<Omit<NewPlan, "planKey" | "gridId">>: the key is the identity and the grid is fixed, neither is ever patched.

PlanPrice

How a plan is paid for: the billing interval, the displayed TTC amount in integer cents, an optional trial, and the provider's price id. One plan has one price row per interval it is sold on, which is how the same tier is sold monthly and yearly without duplicating the row or its preset. A price is immutable once subscribers hold it: changing what a plan costs archives the row and adds another, so a subscriber keeps the price it bought (grandfathering) and the history stays readable.

NewPlanPrice picks planId, billingInterval, intervalCount, priceCents, currency, providerPriceId, trialDays, status. PlanPricePatch is Partial<Pick<NewPlanPrice, "providerPriceId" | "status">>: what a price costs never changes.

isPlanKeyFormat("pro"); // => true
isPlanKeyFormat("sur-devis"); // => true
isPlanKeyFormat("Pro Plus"); // => false: lowercase slug only

isPlanOnSale({ status: "archived" }); // => false: listed nowhere, still serving its subscribers
isPlanPriceOnSale({ status: "active" }); // => true

monthlyAmountCents({ priceCents: 11_900, intervalCount: 1, billingInterval: "year" }); // => 992
monthlyAmountCents({ priceCents: 2700, intervalCount: 3, billingInterval: "month" }); // => 900

Application

PlansService

createPlansService(deps: PlansServiceDeps): PlansService, with deps = { planGrids, planGridsRead, plans, plansRead, planPrices, planPricesRead }, the canonical pairs of the catalogue's three tables. Reads the catalogue and validates every write to it. Validation is hand-rolled so the domain stays schema-free; the storage layer re-validates the preset JSON at its own boundary.

PlansCatalogueReader is the catalogue as a consumer that may not change it sees it: Pick<PlansService, "listGrids" | "getGridById" | "getGridByKey" | "listOnSale" | "getById" | "getByPlanKey" | "getByProviderProductId" | "listPrices" | "getPriceById" | "getPriceByProviderPriceId" | "getByProviderPriceId">. It is named in the module so a consumer never re-lists the method names.

Two validators are exported for previews:

export function teachersCatalogue(
  repositories: PlansServiceDeps
): Promise<PlanWithPrices[]> {
  const catalogue = createPlansService(repositories);
  // Active plans of the grid ascending by rank, each with its active prices.
  // Throws NotFoundError(PLAN_GRID_NOT_FOUND) for an unknown grid key.
  return catalogue.listOnSale("teachers");
}

export async function createTier(
  repositories: PlansServiceDeps,
  input: NewPlan
) {
  const catalogue = createPlansService(repositories);
  const plan = await catalogue.create(input);
  // Sell it monthly; the provider price id is bound later by the pricing service.
  const price = await catalogue.createPrice({
    planId: plan.id,
    billingInterval: "month",
    intervalCount: 1,
    priceCents: 1900,
    currency: "EUR",
    providerPriceId: null,
    trialDays: 14,
    status: "active",
  });
  return { plan, price };
}

PlanPricingService

createPlanPricingService(deps: PlanPricingServiceDeps): PlanPricingService, with deps = { plans: Pick<PlansService, "getById" | "listPrices" | "getPriceById" | "createPrice" | "updatePrice">; catalogue: CatalogueProvider; logger? }. Changing what a plan costs is one action across two systems: the provider price is created under the plan's product, the previous live price of the interval is archived, the new row is written, and the previous provider price is archived last. A price is immutable on both sides, so there is no update, only this replacement.

Nothing here owns a transaction, so the writes after the provider create are compensated by hand: a failure archives the provider price just created and puts the previous row back on sale. The database is the source of truth once its writes land; a failure archiving the previous provider price is logged (provider price left active), and the provider's price events flag the drift.

PublishPlanPriceInput picks planId, billingInterval, intervalCount, priceCents, currency, trialDays from NewPlanPrice.

export function changePrice(
  repositories: PlansServiceDeps,
  catalogue: CatalogueProvider,
  input: PublishPlanPriceInput
) {
  const pricing = createPlanPricingService({
    plans: createPlansService(repositories),
    catalogue,
  });
  // Creates the provider price under the plan's product, archives the previous
  // live price of the interval on both sides, and stores the new row.
  return pricing.publishPrice(input);
}

Ports

The catalogue repositories

Each of the catalogue's three tables binds a canonical pair, read side Pick<ReadRepository<…>, "findMany">. Reads are status-blind unless the query filters on status, so an archived tier or price still resolves for the subscribers it grandfathers. Every lookup the service offers (by id, key, rank, provider product, provider price) is a query, not a port method.

Every plan and price update stamps updatedAt. The service answers the written row by reading it back after writeOne or update.

CatalogueProvider

The provider side of the price catalogue. The adapter owns every provider object; the domain only ever sees provider ids. @workspace/payment/server implements it with createStripeCatalogueProvider.

Errors

Fixtures

@workspace/training/factories exports makePlanGrid, makePlan, makeNewPlan, makePlanPrice, makeNewPlanPrice and makePlanWithPrices, all (faker, overrides). makeNewPlan gives the key a random suffix so parallel tests never collide; makeNewPlanPrice is a monthly price before the provider price exists.

export function fixtures(faker: Faker) {
  const grid = makePlanGrid(faker, { gridKey: "teachers" });
  const newPlan = makeNewPlan(faker, { gridId: grid.id, rank: 1 });
  const sold = makePlanWithPrices(faker, { gridId: grid.id });
  const newPrice = makeNewPlanPrice(faker, { planId: sold.id, billingInterval: "year" });
  return { grid, newPlan, sold, newPrice };
}