@owlmeans/payment 0.1.18-rc.27 → 0.1.18-rc.29

package/README.md

@@ -1,79 +1,125 @@
 # @owlmeans/payment
 
-Payment contracts and service abstractions for product catalogs, subscriptions, and amount- or
-quantity-priced checkout.
-
-## Overview
-
-- `makePaymentService(alias?)` — creates a payment service for context registration
-- `appendPaymentService(context, alias?)` — registers the payment service in the context
-- `PaymentService` — interface for products, plans, subscriptions, and checkout session creation
-- `paymentApi` — immutable protocol declarations for subscription propagation and checkout
-- `CheckoutPricingMode` plus amount/quantity checkout policy schemas and validators
-- `chargeAmountMinor()` — integer-minor-unit processing adjustment calculation
+Payment contracts shared by a server and a browser: the product catalogue, amount- or
+quantity-priced checkout, and the entitlement model — plans that grant capabilities and counted
+limits, promos, and the entitlement view both a gate and a UI read. It talks to no paygate; a
+server integration (`@owlmeans/server-payment`) implements against these contracts.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/payment@^0.1.18-rc.24
+bun add @owlmeans/payment@^0.1.18-rc.29
 ```
 
+## Concepts
+
+- **Plan** — a catalogue record with a `rank` (higher is an upgrade) and optionally `free: true`
+  (price 0, no paygate): every entity holds some plan, even without paying.
+- **Capability** — a granted permission, written `[scope:]permission[>=n]`, asserted under
+  `ENTITLEMENT_GATE`.
+- **Limit** — a counted allowance, written `limit:<key>[>=n]`, asserted under `LIMIT_GATE`. Three
+  kinds: `window` (calendar UTC day/month), `lifetime` (never renews), `occupancy` (a held count).
+- **Promo** — `{ until, grandfather? }` on a capability set or a limit: in force before `until`,
+  or for a subscription created before it when grandfathered.
+- **Entitlement view** — the effective plan, every capability and every limit with its usage, at
+  one instant; built by pure helpers the server and the browser share.
+
 ## Usage
 
-Create a checkout session:
+Declare a plan:
 
 ```typescript
-import { paymentApi } from '@owlmeans/payment'
-
-const result = await ctx.entrypoint(
-  paymentApi.service.checkout.session.external.create,
-).call({
-  body: {
-    productSku: 'vib-tokens',
-    entitySlug,
-    service: VIB_ALIAS,
-    amountMinor: 1_000,
-    successUrl: helper.makeUrl(service)
-  }
-})
-window.location.assign(result.url)
+import { LimitKind, LimitWindow, PlanDuration, PlanStatus } from '@owlmeans/payment'
+import type { ProductPlan } from '@owlmeans/payment'
+
+const proMonthly: ProductPlan = {
+  productSku: 'pro', sku: 'pro-monthly', status: PlanStatus.Active, duration: PlanDuration.Monthly,
+  price: 20, title: 'Pro', rank: 10, gateways: ['stripe'],
+  capabilities: [
+    { scope: 'feature', permissions: { whitelabel: true } },
+    { scope: 'feature', permissions: { beta: true }, promo: { until: new Date('2027-01-01'), grandfather: true } },
+  ],
+  limits: {
+    seats: { kind: LimitKind.Occupancy, limit: 5 },
+    exports: { kind: LimitKind.Window, window: LimitWindow.Month, limit: 100, unit: 'file' },
+  },
+}
 ```
 
-## API
+Gate a route on a capability or on a limit:
 
-### `makePaymentService(alias?): PaymentService`
+```typescript
+import { ENTITLEMENT_GATE, LIMIT_GATE, entitled, formatLimitParam } from '@owlmeans/payment'
 
-Creates the payment service.
+protocol(route(WHITELABEL, '/whitelabel', backend(BASE, RouteMethod.POST)), contract(typed()),
+  entitled('feature:whitelabel'))
+protocol(route(INVITE, '/invite', backend(BASE, RouteMethod.POST)), contract(typed()),
+  { gate: { alias: LIMIT_GATE, params: [formatLimitParam('seats')] } })
+```
 
-### `PaymentService`
+Build and read an entitlement view:
 
-- `product(sku): Promise<Product>` — get a product by SKU
-- `products(): Promise<Product[]>` — list all products
-- `plans(productSku, duration): Promise<ProductPlan[]>` — list plans for a product
-- `plan(planSku): Promise<ProductPlan>` — get a plan by SKU
-- `shallowAuthentication(token): Promise<string>` — shallow auth for payment flows
-- `localize(lng, entity): Promise<Localization | null>` — get localized payment content
+```typescript
+import {
+  capabilityOf, entitlementViewOf, hasLimitRoom, limitOf, reviveEntitlementView,
+} from '@owlmeans/payment'
+
+const view = entitlementViewOf(plan, planView, usage)          // server
+const fromWire = reviveEntitlementView(await response.json())  // browser: ISO strings → Dates
+capabilityOf(fromWire, 'feature:whitelabel')
+hasLimitRoom(limitOf(fromWire, 'seats'))
+```
+
+Refuse and recover the fields on the other side of a service hop:
 
-### Types
+```typescript
+import { LimitExhausted } from '@owlmeans/payment'
+import { ResilientError } from '@owlmeans/error'
 
-- `CreateCheckoutBody` — `{ productSku, entitySlug, service, amountMinor?, successUrl?, cancelUrl? }`
-- `CreateCheckoutResponse` — `{ url: string }`
-- `AmountCheckoutPolicy` — integer minor-unit bounds, presets, currency, fixed and basis-point adjustments
-- `QuantityCheckoutPolicy` — integer quantity bounds and default
-- `SubscriptionPropagateBody` — propagation wire shape with `entitySlug`, never the stored `entityId`
-- `PlanSubscription` — `{ sku, entityId, createdAt, status, capabilities? }`
+throw new LimitExhausted({ key: 'seats', used: 5, limit: 5 })
+// …after marshal/unmarshal:
+const error = ResilientError.ensure(caught)
+if (error instanceof LimitExhausted) { error.limitKey; error.used; error.limit; error.resetsAt }
+```
 
-### Enums
+## API
 
-- `PlanDuration` — `Monthly`, `Yearly`, `Consumable`, etc.
-- `SubscriptionStatus` — `Active`, `Consumable`, `Canceled`, etc.
-- `ProductType` — product category enum
-- `PaymentEntityType` — entity classification enum
-- `CheckoutPricingMode` — `Amount` or `Quantity`
+- Catalogue: `makePaymentService(alias?)`, `appendPaymentService(ctx, alias?)`, `PaymentService`
+  (`product`, `products`, `plans`, `plan`, `allPlans`, `localize`, `shallowAuthentication`),
+  `l10nToId`, record types/prefixes.
+- Checkout: `CheckoutPricingMode`, `AmountCheckoutPolicy`/`QuantityCheckoutPolicy` (+ schemas),
+  `assertAmountCheckoutPolicy`, `assertQuantityCheckoutPolicy`, `assertCheckoutAmount`,
+  `chargeAmountMinor`, `CreateCheckoutBody` (`planSku`) / `CreateCheckoutResponse` (+ schemas),
+  `PortalFlow`, `PortalLinkBody` / `PortalLinkResponse` (+ schemas).
+- Entitlement grammar: `ENTITLEMENT_GATE`, `LIMIT_GATE`, `CAPABILITY_FEATURE_SCOPE`,
+  `CAPABILITY_LIMIT_SCOPE`, `entitled`, `parseEntitlementParam`, `formatEntitlementParam`,
+  `hasEntitlement`, `entitlementList`, `parseLimitParam`, `formatLimitParam`.
+- Statuses: `SubscriptionStatus` (incl. `PastDue`), `ENTITLING_STATUSES`, `TERMINAL_STATUSES`,
+  `INTERNAL_PAYGATE`.
+- Limits and promos: `LimitKind`, `LimitWindow`, `LimitDeclaration`, `PlanCapability`,
+  `PromoDeclaration` (+ schemas), `windowKeyOf`, `windowBoundsOf`, `LIFETIME_WINDOW`,
+  `OCCUPANCY_WINDOW`, `promoActive`, `promoViewOf`.
+- Views: `EntitlementView`, `EntitlementPlanView`, `CapabilityView`, `LimitView`, `PromoView`,
+  `LimitUsage` (+ wire schemas), `capabilityViewsOf`, `limitViewsOf`, `entitlementViewOf`,
+  `reviveEntitlementView`, `capabilityOf`, `limitOf`, `hasLimitRoom`.
+- Errors: `EntitlementRefusal` → `CapabilityRequired`, `LimitExhausted` (all `AuthForbidden`);
+  `PaymentError` family incl. `LimitUnknown`, `LimitMisdeclared`, `PlanRequired`,
+  `PlanRankConflict`, `WebhookSetupError`, `PortalUnavailable` (declares `httpStatus = 409`, so an
+  HTTP boundary answers 409; the other faults answer 500). Messages are registered under
+  `errors.<type>` in seven languages.
+
+## Common pitfalls
+
+- A limit parameter is never a capability: `hasEntitlement(sets, 'limit:x')` is always `false`.
+- A view's dates are ISO strings on the wire — revive before calling date methods.
+- A promo ends AT `until`; grandfathering needs the subscription's creation date on the plan view.
+- A refusal's fields survive a hop only through its message; catch the class, not the text.
 
 ## Related Packages
 
-- [`@owlmeans/client-payment`](../client-payment) — client-side wrapper for browser contexts
+- `@owlmeans/server-payment` — Stripe gateway, subscription store, usage ledger and the two gates
+- `@owlmeans/client-payment` — browser-side catalogue service
+- `@owlmeans/web-payment` — React hooks and pieces over the entitlement view
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -83,7 +129,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.26
+npx @owlmeans/agent-skills@^0.1.18-rc.28
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,10 +1,17 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/payment",
-  "version": "0.1.18-rc.27",
-  "generatedAt": "2026-09-15T13:15:34.374Z",
+  "version": "0.1.18-rc.29",
+  "generatedAt": "2026-09-16T17:32:31.941Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
+    {
+      "kind": "skill",
+      "name": "entitlements",
+      "category": "multi-package",
+      "file": "skills/entitlements/SKILL.md",
+      "canonicalPath": ".agents/skills/entitlements/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "payment",

package/agent-meta/skills/entitlements/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: entitlements
+description: "The OwlMeans entitlement model across @owlmeans/payment, @owlmeans/server-payment and @owlmeans/web-payment — ranked plans with a real free plan, capabilities versus counted limits, the three limit kinds, promos and grandfathering, the admission-first usage ledger and its may-over-count-never-over-admit invariant, the entitlement view the server gate and the browser both read, the two gate services, and the refusal errors. Use when deciding what a plan grants, gating a route on a feature or a quota, consuming or releasing a limit, or rendering plan state in a UI."
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Entitlements — what a plan lets an entity do
+
+An entity (the organization) always holds exactly one **effective plan**. The plan grants
+**capabilities** (may it do X?) and **limits** (how many X may it do?). A route declares what it
+needs; a gate refuses before the handler runs; the handler consumes. The browser renders the same
+answer from the same pure functions, so a disabled button and a 403 cannot disagree.
+
+## Where each half lives
+
+| Layer | Package | Owns |
+|---|---|---|
+| Contracts | `@owlmeans/payment` | Plan declarations, `LimitKind`/`LimitWindow`, promos, the param grammars, the view builders, the refusal errors, `ENTITLEMENT_GATE`/`LIMIT_GATE` |
+| Server | `@owlmeans/server-payment` | The subscription store, plan resolution, the usage ledger and its counters, the two gate services, reconciliation, the paygate lifecycle |
+| Browser | `@owlmeans/web-payment` | Hooks over a served entitlement view (`useEntitlementView`, `useCapability`, `useLimit`, `usePortal`) and presentational pieces |
+
+## Plans
+
+- **Rank orders a product's plans.** A higher `rank` is an upgrade; a plan change is classified
+  as upgrade/downgrade by rank. No two paid plans of one product share a rank.
+- **The free plan is a real plan** — `free: true`, `price: 0`, `gateways: []`, lowest rank. The
+  application grants it as an internal subscription row (`paygate: INTERNAL_PAYGATE`) when an
+  entity is created, and plan resolution falls back to it when no entitling row exists. With no
+  free plan declared and no entitling row, resolution throws `PlanRequired` — a setup fault, not a
+  refusal.
+- **The effective plan** is the highest-ranked subscription in `ENTITLING_STATUSES`
+  (`Active`, `Trial`, `PastDue`). `PastDue` still entitles and is flagged; `Suspended` revokes
+  until resumed; terminal statuses fall back to the free plan.
+- A plan names its keys, never a product's copy: every limit key an application gates on appears
+  on every plan (with `limit: 0` where not included), so "not included" is an answer, not a
+  missing row.
+
+## Capabilities versus limits
+
+| | Capability | Limit |
+|---|---|---|
+| Declared as | `PlanCapability` (a permission set) | `LimitDeclaration` under a key in `plan.limits` |
+| Asked as | `[scope:]permission[>=n]` | `limit:<key>[>=n]` |
+| Gate alias | `ENTITLEMENT_GATE` | `LIMIT_GATE` |
+| Answer | granted or not | room left in the current window |
+| Changes when | the plan changes | something is consumed or released |
+
+- `limit` is a reserved capability scope: no capability can answer a limit parameter.
+- The two gates are different aliases because an entrypoint's gates are collected per gate
+  service; one alias would let one requirement hide the other.
+- Several parameters on one gate are OR'd.
+
+## The three limit kinds
+
+| Kind | Counter window | Renews |
+|---|---|---|
+| `window` (`day` / `month`) | `YYYY-MM-DD` / `YYYY-MM`, calendar UTC | at the UTC boundary; `resetsAt` is the exclusive start of the next window |
+| `lifetime` | `lifetime` | never — the count belongs to the entity and survives plan changes, so an upgrade reads "1 of 4 used" |
+| `occupancy` | `occupancy` | never — a held count, `+1` on acquire and `-1` on release, reconciled against what actually exists |
+
+Windows are calendar UTC, never rolling and never local.
+
+## Promos and grandfathering
+
+`promo: { until, grandfather? }` on a capability set or a limit is plan metadata resolved per
+subscription:
+
+- in force while `now < until` (`now === until` is over);
+- with `grandfather`, also for a subscription created before `until`, for as long as it lasts;
+- lapsed: the capability is listed `granted: false`, the limit reads `limit: 0`, and the promo
+  view says `active: false` — the UI says the promotion ended.
+
+The server must put the subscription's creation date on the plan view (`subscribedAt`); without it
+nothing is grandfathered.
+
+## The usage ledger — admission first
+
+Limits are event-sourced with synchronous admission:
+
+- **The ledger of usage events is the source of truth; the counter per (entity, key, window) is a
+  projection.**
+- **Consume** increments the counter FIRST with an atomic conditional update (only while
+  `used <= limit - amount`), then appends the event keyed by an idempotency `eventKey`. No update
+  ⇒ `LimitExhausted`. A duplicate `eventKey` undoes the increment and replays the earlier outcome.
+- **Release** appends first, then decrements (never below zero), and is idempotent.
+- **Invariant: the counter may over-count, never over-admit.** A crash between the increment and
+  the event leaves a unit counted that nothing spent — the periodic reconciliation recomputes
+  counters from the ledger (and occupancy from reality). The opposite order would let two
+  concurrent requests both pass a read-then-write check.
+- **Key a consumption by the record it pays for** (`eventKey = <purpose>:<recordId>`,
+  `ref = recordId`). A retry, a resumed run or a second attempt on the same record replays the same
+  event instead of spending a second unit, and "was a unit already spent on this record?" is a
+  ledger read rather than a marker written onto the record.
+- Occupancy is reconciled against the live count; an entity over its ceiling is flagged
+  (`overSince`) and the application decides what to do after a grace period — a cron never
+  silently deletes customer work.
+
+## The gates — the gate refuses, the handler consumes
+
+- The **capability gate** passes when the effective plan grants any parameter. The subscription
+  is the authority: a token's explicit `false` for a permission denies, a token's own grant never
+  allows, and requiring the token permission as well is an opt-in gate option. Store errors
+  refuse.
+- The **limit gate** passes when any declared parameter has `remaining >= atLeast`. It **never
+  consumes** — checking room and spending it are different moments, and only the handler knows
+  whether the work actually started. Unparseable parameters are skipped; none left ⇒ refuse.
+- The **handler consumes** with a record-keyed `eventKey` right before the paid work starts, and
+  releases (or relies on the key's replay) when the work is undone.
+- Declare the requirement on the protocol, never inside a handler, so the route table states what
+  a feature costs.
+
+## The entitlement view
+
+One read of an entity's position, built by `entitlementViewOf(plan, planView, usage, at)`:
+
+- `plan` — sku, rank, free, status, paygate, period, trial, cancel-at-period-end, past-due,
+  fallback plan;
+- `capabilities` — one row per granted permission, `param` exactly as the gate takes it;
+- `limits` — one row per declared key with `limit`, `used`, `remaining` (floored at 0), and
+  `windowStart`/`resetsAt` for window limits;
+- `at` — when it was computed.
+
+The server serves it; the browser reads it with the same `capabilityOf` / `limitOf` /
+`hasLimitRoom` the gate logic uses. On the wire every date is an ISO string — revive
+(`reviveEntitlementView`) before using a date. In the browser `null` means "not known yet": render
+paid controls disabled rather than enabled-then-refused, and an application with its own store
+reads the view through the pure selectors rather than polling it a second time.
+
+## Refusals
+
+| Error | Means | HTTP | Fields (rebuilt after a hop) |
+|---|---|---|---|
+| `CapabilityRequired` | none of the capability parameters is granted | 403 | `params` |
+| `LimitExhausted` | no room in the current window | 403 | `limitKey`, `used`, `limit`, `resetsAt?` |
+| `LimitUnknown` · `LimitMisdeclared` · `PlanRequired` · `PlanRankConflict` | configuration faults | 500 | — |
+
+- Both refusals extend `AuthForbidden` through `EntitlementRefusal` — that is what turns them into
+  a 403 at the HTTP boundary.
+- Only `type` and `message` cross a service hop; the refusals pack their fields into the message
+  and rebuild them on unmarshal. Catch the class after `ResilientError.ensure`.
+- A UI phrases a refusal from `errors.<type>` and its fields (the reset date of an exhausted
+  window), never from the message text.
+
+## Related
+
+- [[payment]] — the contracts in detail: grammars, window algebra, schemas
+- [[server-payment]] — the Stripe lifecycle, the subscription store, the ledger and gates
+- [[web-payment]] — the hooks and pieces
+- [[error]] — marshalling and the error registry