@owlmeans/payment 0.1.18-rc.8 → 0.1.18

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

@@ -1,6 +1,6 @@
 ---
 name: payment
-description: How to use @owlmeans/payment — payment processing types, models, errors, paymentApi service alias for cross-service checkout calls. Auto-invoked when importing payment types or invoking checkout flows.
+description: "How to use @owlmeans/payment — provider-agnostic payment contracts, immutable payment protocols, amount/quantity checkout policies, per-entity checkout narrowing and pricing, catalogue records, entitlement gates, and the EU consumer-rights contracts (billing regions, the policy record, withdrawal/cancellation views, refund calculators, 428/409 refusals, the legal copy, protocol factories). Auto-invoked when importing payment types or errors, declaring paid routes, creating checkout, or touching consent, withdrawal or cancellation."
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,44 +8,507 @@ user-invocable: false
 # @owlmeans/payment
 
 **Layer:** Core
-**Install:** `"@owlmeans/payment": "^0.1.18-rc.7"` in `dependencies`
+**Install:** `"@owlmeans/payment": "^0.1.18"` in `dependencies`
 
-## Key Exports
+The contracts half of payments: the catalogue (products, plans, localizations), amount- and
+quantity-priced checkout, the entitlement model — plan capabilities, counted limits, promos,
+and the entitlement view the server gate and the browser both read — and the EU consumer-rights
+contracts (billing regions, the policy record, withdrawal and cancellation views, the refund
+calculators, the refusals, the legal copy, the protocol factories). It talks to no paygate: a
+server-side integration (`@owlmeans/server-payment`) implements against these, and
+`@owlmeans/client-payment` adapts the catalogue service for a browser. The model as a whole —
+admission, the usage ledger, the two gate services — is the `entitlements` skill.
+
+## Key exports
 
 | Export | Description |
-|--------|-------------|
-| `paymentApi` | Service alias tree for payment endpoints (e.g. `paymentApi.service.checkout.session.external.create`) |
-| `Payment`, `Checkout` types | Domain model shapes |
-| `paymentModules` | Entrypoint declarations to spread into `appModules` |
-| Errors | Typed payment errors |
-| Constants | Payment service aliases |
-| `model` submodule | Reusable payment models |
-| i18n | Translatable error messages |
+|---|---|
+| `makePaymentService(alias?)` · `appendPaymentService(ctx, alias?)` | The catalogue reader, registered under `DEFAULT_ALIAS` / `PAYMENT_SERVICE` (`'payment'`). |
+| `PaymentService` | `product(sku)` · `products()` · `plans(productSku, duration)` · `plan(planSku)` · `allPlans(productSku)` · `localize(lng, entity)` · `shallowAuthentication(token)` · `pricingPolicy()` · `consumerRightsPolicy()` (`null` when undeclared). |
+| `Product` · `ProductPlan` · `Localization` (+ schemas) | Catalogue records. `ProductPlan` carries `rank`, `free`, `gateways`, `suspendedAt`, `capabilities: PlanCapability[]`, `limits: { [key]: LimitDeclaration }`, `withdrawal.components` (§ Consumer rights). |
+| `PlanCapability` · `LimitDeclaration` · `PromoDeclaration` (+ schemas) | What a plan grants: a permission set, a counted allowance, a time box on either. |
+| `SubscriptionStatus` · `ENTITLING_STATUSES` · `TERMINAL_STATUSES` · `INTERNAL_PAYGATE` | Lifecycle vocabulary. `Active`/`Trial`/`PastDue` entitle; `Canceled`/`Expired`/`Ended`/`Blocked` are terminal; `Suspended` is revoked until resumed. |
+| `LimitKind` · `LimitWindow` · `PortalFlow` (+ schemas) | `window`/`lifetime`/`occupancy`; `day`/`month`; `manage`/`cancel`/`update`/`change`/`payment-method`. |
+| `ENTITLEMENT_GATE` · `LIMIT_GATE` · `CAPABILITY_FEATURE_SCOPE` · `CAPABILITY_LIMIT_SCOPE` | The two gate aliases and the two reserved scopes (`feature` for flags, `limit` for limit parameters). |
+| `entitled` · `entitlementParamHelper` (`parseEntitlementParam` · `formatEntitlementParam` · `hasEntitlement` · `entitlementList`) | The capability grammar and predicate. |
+| `planLimitHelper` (`parseLimitParam` · `formatLimitParam` · `windowKeyOf` · `windowBoundsOf`) · `LIFETIME_WINDOW` · `OCCUPANCY_WINDOW` | The limit grammar and window algebra. |
+| `promoHelper` (`promoActive` · `promoViewOf`) | Whether a promo is in force for one subscription at one instant. |
+| `EntitlementView` · `EntitlementPlanView` · `CapabilityView` · `LimitView` · `PromoView` · `LimitUsage` (+ wire schemas) | The entitlement view and its rows. |
+| `entitlementViewHelper` (`capabilityViewsOf` · `limitViewsOf` · `entitlementViewOf` · `reviveEntitlementView`) · `planLimitHelper` (`capabilityOf` · `limitOf` · `hasLimitRoom`) | Pure view builders and readers. |
+| `CreateCheckoutBody` (`planSku`, `country`, `startRequestId`) · `CreateCheckoutResponse` · `PortalLinkBody` · `PortalLinkResponse` (+ schemas) | Wire shapes an application's own checkout and portal protocols use. |
+| `CheckoutPricingMode` · `AmountCheckoutPolicy` / `QuantityCheckoutPolicy` (+ schemas) · `checkoutPricingHelper` (`assertAmountCheckoutPolicy` · `assertQuantityCheckoutPolicy` · `assertCheckoutAmount` · `chargeAmountMinor`) | Checkout pricing policies and their validation. |
+| `PricingPolicy` (+ schema) · `DEFAULT_PRICING_POLICY` · `priceEstimateHelper.assertPricingPolicy` · `TaxBehavior` · `TaxEstimateStatus` · `TaxType` (+ schemas) | Declared tax/currency behaviour (see § Pricing policy and tax estimate). |
+| `PriceEstimate` · `PriceEstimateBody` · `TaxEstimate` · `TaxRateEstimate` (+ schemas) · `priceEstimateHelper` (`estimateOf` · `ratePpmOf`) | The tax/local-currency estimate read model and its pure math. |
+| `COUNTRY_CURRENCIES` · `currencyOfCountry` · `COUNTRY_CODES` · `CountrySchema` | ISO 3166-1 → ISO 4217 reference map for a country picker. |
+| `EntitlementRefusal` · `CapabilityRequired` · `LimitExhausted` | Entitlement refusals — all `AuthForbidden` (403). |
+| `PaymentError` · `PaygateError` · `UnknownPaygate` · `PaygateMappingError` · `WebhookSetupError` · `PortalUnavailable` · `ProductError` · `UnknownProduct` · `UnknownPlan` · `PlanRequired` · `PlanRankConflict` · `LimitUnknown` · `LimitMisdeclared` · `PaymentIdentificationError` · `SubscriptionError` · `UnknownSubscription` · `ConsumerRightsError` | Faults (500), except `PortalUnavailable` (409). Importing the package registers every type's message under `errors.<type>` in eight languages (the seven of `SUPPORTED_LNGS` plus `fr`). |
+| `ConsumerRightsRefusal` · `PerformanceConsentRequired` · `SubscriptionStartRequired` (428) · `BillingCountryLocked` · `WithdrawalUnavailable` · `CancellationUnavailable` · `CheckoutLimitExceeded` (409) · `consentRefusalOf` | Consumer-rights and checkout-limit refusals — declared statuses, never `AuthForbidden` (§ Consumer rights). |
+| `ConsumerRegion` · `PurchaseKind` · `ConsentKind` · `DeclarationKind` · `DeclarationChannel` · `CancellationKind` · `WithdrawalStatus` · `CancellationStatus` · `WithdrawalUnavailableReason` · `CancellationUnavailableReason` (+ schemas) | Consumer-rights vocabulary. |
+| `EU_COUNTRIES` · `EU_CONSUMER_TERRITORIES` · `EEA_EXTRA` · `CONSUMER_RIGHTS_TERRITORIES` · `COUNTRY_LANGUAGES` · `consumerRegionHelper` (`isEuCountry` · `isEeaCountry` · `regionOf` · `inScope` · `chargeCurrencyOf` · `billingLanguageOf`) | Territories, region, scope, charge currency, legal language. |
+| `ConsumerRightsPolicy` (+ `Links`, `Mechanisms`, schemas) · `DEFAULT_CONSUMER_RIGHTS` · `makeConsumerRightsPolicy` · `consumerRightsPolicyHelper` (`assertConsumerRightsPolicy` · `linksOf`) · `CONSUMER_RIGHTS_RECORD_TYPE`/`_ID` | The consumer-rights policy record. |
+| `BillingProfileView` · `PurchaseView`/`List` · `PerformanceConsentView`/`Body`/`Response` · `SubscriptionStartView`/`Query`/`Body`/`Response` · `WithdrawalEstimate` · `WithdrawalCandidate`/`List` · `WithdrawalBody` · `DeclarationReceipt` · `WithdrawalReceipt` · `CancellationBody` · `CancellationReceipt` · `ConsumerRightsPublicView` (+ schemas) · `consumerReviveHelper.revive*` | Consumer-rights wire shapes (ISO dates) and their revivers. |
+| `withdrawalDeadlineHelper` (`withdrawalDeadlineOf` · `lastWithdrawalDayOf` · `withdrawalOpen`) · `withdrawalRefundHelper` (`oneTimeWithdrawalRefund` · `subscriptionWithdrawalRefund` · `splitByShares`) · `fifoHelper` (`allocateFifo` · `unitsUsedAfter`) · `cancellationEffectiveAt` | Pure calculators. |
+| `CONSUMER_RIGHTS_RESOURCE` · `CONSUMER_RIGHTS_COPY_VERSION` · `consumerCopyHelper` (`consumerRightsCopy` · `consumerText` · `consentStatementOf` · `startContextOf` · `legalLabelsOf` · `placeholdersOf`) | The legal copy and the start statement's variant. |
+| `makeConsumerRightsProtocols` · `makeCheckoutReadProtocols` | Protocol factories. |
+| `AmountNarrowing` · `amountNarrowingHelper` (`narrowAmountPolicy` · `amountAllowed`) · `CheckoutLimitView` · `AmountPolicyView`/`Query` · `PlanPriceView`/`List`/`PlanPricesQuery` (+ schemas) | Per-entity narrowing of an amount checkout, and synced plan prices. |
+
+Subpath: `./utils` — the `Config` / `Context` aliases to type your own context against.
+
+## The catalogue is config, not a table
+
+`PaymentService` reads everything through the context's config resource, so a deployment ships its
+catalogue the same way it ships any other configuration:
+
+| Record | Id | Type |
+|---|---|---|
+| product | `product:<sku>` | `PRODUCT_RECORD_TYPE` |
+| plan | `plan:<planSku>` | `PLAN_RECORD_TYPE` |
+| localization | `l10nToId(l10n, true)` → `l10n:<entityType>:<sku>:<lng>` | `L10N_RECORD_TYPE` |
+
+`product` and `plan` read the record with the config resource's `get`, which **throws
+`UnknownRecordError`** (`@owlmeans/resource`) when the id is absent rather than returning null — so
+that, not `UnknownProduct` / `UnknownPlan`, is what a checkout for a sku outside the catalogue
+raises. `localize` is the opposite: it reads with `load`, tries the asked-for language, falls back
+to the default one, and returns `null` when neither exists, because a missing translation is a
+display problem and never a reason to fail a call.
+
+## Declaring plans
+
+- **Every plan of a product has a `rank`; a higher rank is an upgrade.** An absent rank reads as
+  `0`. Plan changes are classified by rank, and the effective plan of an entity is its
+  highest-ranked entitling subscription — two plans of one product at one rank make both
+  questions unanswerable.
+- **The free tier is a real plan**: `free: true`, `price: 0`, `gateways: []`, usually `rank: 0`.
+  Every entity holds some plan, so a gate never has to special-case "no subscription".
+- **`gateways`** names the paygates a plan is sold through; a free plan has none.
+- **`status` is a `PlanStatus`** (active, hidden, archived …) — the catalogue state of the plan,
+  never a subscription's lifecycle.
+- Plan records use the record date convention (`DateSchema` from `@owlmeans/auth`, a `Date`
+  object); wire shapes do not (below).
+
+## Capabilities and limits are different things
+
+A **capability** is granted: a permission in a `PlanCapability` set, asked for as
+
+    [<scope>:]<permission>[>=<n>]
+
+`feature:branding--whitelabel` · `renewable:credits>=100` · `production--standalone`
+
+A **limit** is counted: a `LimitDeclaration` under a key in `plan.limits`, asked for as
+
+    limit:<key>[>=<n>]
+
+- **`limit` is a reserved scope.** A plan never declares a capability set under it,
+  `entitlementParamHelper.hasEntitlement` answers `false` for any `limit:` parameter, and the view
+  builders skip such a set. A limit requirement can therefore never be satisfied by a capability
+  grant.
+- **One grammar, two gate services.** Capability parameters go to `ENTITLEMENT_GATE`
+  (`entitled(params)` is sugar for it), limit parameters to `LIMIT_GATE`
+  (`{ gate: { alias: LIMIT_GATE, params: [planLimitHelper.formatLimitParam(key)] } }`). The aliases
+  differ because the framework collects an entrypoint's gates per gate service — one alias would let
+  one requirement hide the other.
+- **`@` is deliberately not part of the grammar.** That is `@owlmeans/iam`'s resource-selector
+  syntax; reusing it would make two different things look identical in a route declaration.
+- **Keep flags, magnitudes and counts apart.** `CAPABILITY_FEATURE_SCOPE` carries booleans; a
+  granted magnitude nothing spends (`renewable:credits>=100`) lives under its own scope; anything
+  spent against a ceiling is a limit. Merged, the purchase that spends a quota takes the feature
+  with it.
+- **A floor is a numeric question.** `>=n` passes only for a number at least that big — a boolean
+  flag, however true, does not answer it. For a limit, `>=n` asks for `n` units of room.
+- **A malformed parameter answers `false` / `null`, it never throws.**
+  `entitlementParamHelper.hasEntitlement` refuses, `planLimitHelper.parseLimitParam` returns `null`
+  for a capability parameter, a bare key, an empty key or a floor that is not positive. A gate that
+  crashed on a typo would take down the endpoint it guards.
+- **Declare the requirement on the protocol, not in the handler.** The framework asserts gates
+  before the handler is entered, so the route table states what a feature costs. Several
+  parameters of one gate are OR'd. The gate services themselves live in the server integration.
+
+## The three limit kinds
 
-## Subpath Exports
+| Kind | Window key (`planLimitHelper.windowKeyOf`) | Renews | Typical use |
+|---|---|---|---|
+| `window` + `day` | `YYYY-MM-DD` | at UTC midnight | per-day actions |
+| `window` + `month` | `YYYY-MM` | on the 1st, UTC | per-month actions |
+| `lifetime` | `lifetime` | never — the count belongs to the entity and survives plan changes | "N ever" |
+| `occupancy` | `occupancy` | never — held `+1` / released `-1`, reconciled against reality | "N at once" |
 
-- `./utils` — payment helpers
+- Windows are **calendar UTC**, never rolling and never local: two servers in two zones must agree
+  on which counter a unit lands in.
+- `planLimitHelper.windowBoundsOf(window, at)` returns `start` inclusive and `resetsAt`
+  **exclusive** — `resetsAt` is the first instant of the next window and already belongs to it.
+- A `window` limit without a known `window` (or an unknown kind) throws `LimitMisdeclared`: a
+  misdeclared plan is loud, not a silently unlimited one.
+- `limit: 0` means "not included" — a declared key with no room, which a UI renders as such.
 
-## Usage
+## Promos
 
-Spread the entrypoints into your app, then call them via `ctx.entrypoint(paymentApi....)`:
+`promo: { until: Date, grandfather?: boolean }` on a capability set or a limit.
 
-```typescript
-import { paymentApi, paymentModules } from '@owlmeans/payment'
-import type { CreateCheckoutResponse } from '@owlmeans/payment'
-import type { ClientEntrypoint } from '@owlmeans/entrypoint'
+- In force while `at < until`. **`at === until` is over.**
+- With `grandfather: true`, also in force for a subscription created before `until`, forever.
+- A lapsed promo makes a capability `granted: false` and a limit's `limit: 0` — the row stays in
+  the view with `promo.active: false`, so a UI can say the promotion ended rather than pretend the
+  feature never existed.
+- `promoHelper.promoViewOf` → `{ until, grandfathered, active }` is what a UI inscribes: active and
+  not grandfathered ⇒ "free until"; grandfathered ⇒ "kept for your plan"; inactive ⇒ "ended".
+- An unparseable `until` is never in force.
 
-export const appModules = [...modules, ...paymentModules]
+## The entitlement view
+
+`entitlementViewHelper.entitlementViewOf(plan, planView, usage, at?)` is the one read of what an
+entity may do:
+
+- `plan` — the `EntitlementPlanView` the caller resolved (sku, rank, free, status, paygate,
+  period, trial, cancel-at-period-end, past-due, fallback). **Promos are measured against
+  `planView.subscribedAt`** — set it to the subscription's creation date, or nothing is
+  grandfathered.
+- `capabilities` — its `capabilityViewsOf`: one row per non-null, non-false permission, `param`
+  exactly as the capability gate takes it.
+- `limits` — its `limitViewsOf`: one row per declared key; `used` from the `LimitUsage` row of the
+  CURRENT window (none ⇒ `0`); `remaining = max(0, limit - used)`; `windowStart`/`resetsAt` only
+  for a window limit.
+- Read it with `planLimitHelper.capabilityOf(view, param)` (the same predicate as the gate, over
+  granted rows), `planLimitHelper.limitOf(view, key)` and
+  `planLimitHelper.hasLimitRoom(limitView, atLeast)`. The server gate and the browser call the same
+  functions, so the UI's "disabled" and the server's refusal cannot disagree.
+- **The wire carries dates as ISO strings.** The view schemas describe that
+  (`{ type: 'string', format: 'date-time' }`): a response serializer writes a `Date` through it as
+  ISO, while the record convention (`DateSchema`, an object) would serialize it as `{}`. A browser
+  calls `entitlementViewHelper.reviveEntitlementView` before touching a date.
+
+## Refusals and faults
+
+- **A refusal extends `AuthForbidden`** (through `EntitlementRefusal`), so an HTTP boundary answers
+  403.
+  - `CapabilityRequired(params)` — message marker `capability-required:<a|b>`, field `params`.
+  - `LimitExhausted({ key, used, limit, resetsAt? })` — marker
+    `limit-exhausted:<key>:<used>/<limit>[:<ISO>]`, fields `limitKey`, `used`, `limit`,
+    `resetsAt`.
+- **Only `type` and `message` survive a marshal.** Both refusals pack their fields into the
+  message and rebuild them in `finalizeUnmarshal()`; catch the class after
+  `ResilientError.ensure`, never parse the text yourself.
+- **Consumer-rights and checkout-limit refusals are not entitlement refusals**: they declare
+  428/409 and never extend `AuthForbidden` (§ Consumer rights).
+- **Faults are not refusals**: `LimitUnknown` (a key no plan declares), `LimitMisdeclared`,
+  `PlanRequired` (no plan resolvable, not even a free one), `PlanRankConflict`,
+  `WebhookSetupError` are `PaymentError`s — a configuration or setup problem, not the user's plan
+  saying no — and declare no status, so an HTTP boundary answers 500.
+- **`PortalUnavailable` is the entity's state, not a fault**: no paygate customer, no entitling
+  subscription, no plan or item for the flow. It is a `PaymentError` declaring
+  `static httpStatus = 409`, which `@owlmeans/server-api` answers as 409 Conflict. A new payment
+  error that is the caller's condition declares its 4xx the same way; one that is a fault declares
+  nothing.
+- A UI phrases any of them from `errors.<type>`; the package registers those messages.
+
+## Checkout
+
+`CreateCheckoutBody` is the wire body of a checkout: `productSku`, `planSku` for a subscription,
+`entitySlug` (the only organization value on a public body — a server resolves the stable
+`entityId` before persisting anything), `service`, `amountMinor` for an amount checkout, return
+URLs, `country` (the declared billing country; a locked profile overrides it) and
+`startRequestId` (the subscription start request recorded just before). The package declares no
+fixed checkout protocols: an application declares its own checkout and portal protocols over
+`CreateCheckoutBodySchema` / `PortalLinkBodySchema`; `PortalLinkBody.flow` picks the portal flow
+and `planSku` names the target of a `change`. The read side and the consumer-rights surface come
+as factories (§ Protocol factories).
+
+### Amount checkout
+
+`amountMinor` is the net value credited to the customer, in integer currency minor units. The
+policy bounds that value; fees and tax do not enlarge the credit. Gross up the pre-tax charge with:
 
-// In a handler:
-const [result] = await ctx.entrypoint<ClientEntrypoint<CreateCheckoutResponse>>(
-  paymentApi.service.checkout.session.external.create
-).call({
-  body: { productSku: 'tokens', entityId, service: VIB_ALIAS, successUrl: helper.makeUrl(service) }
-})
 ```
+ceil((amountMinor + fixedMinor) * 10_000 / (10_000 - rateBps))
+```
+
+Validate the whole policy when configuration is declared, then validate every selected amount at
+the backend boundary. Minimum, default, maximum, preset entries, fixed adjustment and basis-point
+rate are safe integers; presets are unique/in-range and the rate is below 100%. The maximum applies
+to `amountMinor`, not the adjusted checkout subtotal or tax-inclusive total.
+
+Quantity checkout remains supported. It uses its reusable unit price and quantity policy; do not
+infer a pricing mode from the presence of `amountMinor`.
+
+### Narrowing an amount checkout per entity
+
+The plan's `amountPolicy` is the same for everyone; what one entity may buy NOW is narrower when a
+checkout plugin (a spending tier, a rolling cap, a fraud hold) answers an `AmountNarrowing`
+`{ maximumMinor, reason, resetsAt?, remainingMinor? }`.
+`amountNarrowingHelper.narrowAmountPolicy(base, narrowings, { productSku?, planSku? })` is the one
+computation the server's refusal and the dialog's control share, so they cannot disagree:
+
+- the maximum is the smallest of the base maximum and every narrowing's (negative or fractional
+  values floor at 0); `reason`/`resetsAt`/`remainingMinor` come from the narrowing that set it,
+  the first on a tie;
+- presets above the maximum are dropped, the default is clamped into `[minimum, maximum]`;
+- `limit` is `null` when nothing lowered the base maximum — no note to show;
+- **`limit.blocked`** (`limit.maximumMinor < base.minimumMinor`) means no amount may be bought now.
+  The returned `policy` is then still a VALID policy
+  (`checkoutPricingHelper.assertAmountCheckoutPolicy` accepts it), pinned to the minimum with no
+  presets, so a validator never throws — but it is NOT an offer of the minimum: a UI disables the
+  input and the confirm button on `blocked`, and a server refuses every amount with
+  `CheckoutLimitExceeded`. `amountNarrowingHelper.amountAllowed(view, amount)` answers exactly that.
+
+`CheckoutLimitExceeded` (409) packs `checkout-limit-exceeded:<encodeURIComponent(reason)>:
+<maximumMinor>:<currency>[:<resetsAt ISO>]` and rebuilds `reason`, `maximumMinor`, `currency`,
+`resetsAt`. It is a payment refusal, not an entitlement one.
+
+## Pricing policy and tax estimate
+
+`PricingPolicy` (a `PRICING_POLICY_RECORD_ID` singleton config record, `declarePaymentPricing` in
+`@owlmeans/server-payment`) is what a checkout-owning application declares once for tax and
+currency behaviour: `tax.automatic` (Stripe Tax on the session), `tax.behavior` (a synced price's
+`TaxBehavior.Exclusive`/`Inclusive`, absent = leave it `unspecified`), `tax.collectTaxId`,
+`tax.estimate` / `currency.estimate` (serve a tax/local-currency estimate endpoint — the estimate
+requires `tax.automatic`, the currency one requires `currency.adaptive`), `currency.adaptive`
+(Stripe Adaptive Pricing on the session), `currency.adaptiveFeeRate` (the conversion fee Adaptive
+Pricing adds to Stripe's base rate, a fraction in `[0, 1)` — Stripe says 2–4% and picks it per
+currency; it needs `currency.adaptive`; absent, an estimate keeps the FX Quotes' own 2% fee, which
+is NOT what Checkout charges). `PaymentService.pricingPolicy()` reads the declared record
+or `DEFAULT_PRICING_POLICY` — the fixed behaviour every checkout had before this policy existed
+(automatic tax and tax-id collection on, no forced behavior, no Adaptive Pricing, no estimate), so
+an application that declares nothing sees no change.
+
+`PriceEstimate` (built by `@owlmeans/server-payment`'s gateway, `estimatePrice`) is the read model:
+`country`/`source` (`'request'`/`'customer'`, or `'profile'` with `locked: true` when the entity's
+billing country is locked and overrides the request — a picker then shows it and does not change
+it), `region`, `currency`, `behavior`, `tax: TaxEstimate` (`status`
+one of `TaxEstimateStatus` — `taxed`/`reverse-charge`/`none`/`at-checkout`/`location-required` —
+plus `subtotalMinor`/`taxMinor`/`totalMinor`, `scalable`, and `rates: TaxRateEstimate[]` with
+`ratePpm` parsed by `priceEstimateHelper.ratePpmOf` from Stripe's `percentage_decimal`, never
+`Number(x) * 10_000`), and an optional `local` (currency + `exchangeRate`, from Stripe's FX Quotes:
+the quote's `base_rate / (1 + currency.adaptiveFeeRate)` when the fee is declared, else its
+`exchange_rate`; `fxFeeRate` is the fee that rate includes).
+The pure helper `priceEstimateHelper.estimateOf(amountMinor, estimate)` re-derives tax and a total
+for a DIFFERENT amount than the estimate's own reference one — exact only when `scalable` and the
+behavior is `Exclusive`; both `taxMinor`/`totalMinor` come back `null` otherwise, meaning "computed
+at checkout", never a wrong number. When the source estimate carries `local`, the result's own
+`local` gives the subtotal, tax and total in THAT currency
+(`subtotalAmount`/`taxAmount`/`totalAmount`, major units) alongside the integration-currency ones —
+a UI shows one or the other, marking the local figures `≈`, never both side by side.
+`COUNTRY_CURRENCIES` / `currencyOfCountry` / `COUNTRY_CODES` is a reference ISO 3166-1 → ISO 4217
+map for a country picker and the local-currency lookup — not a Stripe list, and a country absent
+from it still gets a tax estimate, just no local-currency line.
+
+## Consumer rights (EU withdrawal, cancellation, country lock)
+
+The contracts behind the right of withdrawal (CRD Art. 9–16, the Art. 11a withdrawal function),
+the cancellation function (§ 312k BGB / L215-1-1) and a billing country fixed at the first
+purchase. `@owlmeans/server-payment` records, enforces and mails; `@owlmeans/web-payment` renders.
+Nothing here is product copy — the trader, plan and product names are placeholders.
+
+### Territories, region, scope
+
+- `EU_COUNTRIES` (27, Greece is `GR`), `EU_CONSUMER_TERRITORIES` (plus AX, GF, GP, MQ, RE, YT, MF —
+  consumer law applies there even where EU VAT does not), `EEA_EXTRA` (IS, LI, NO) and their union
+  `CONSUMER_RIGHTS_TERRITORIES`, the default `policy.countries`.
+- `consumerRegionHelper.regionOf(country, policy?)`: `Eu` inside the policy's territories, `Other`
+  outside, `null` for no country. `consumerRegionHelper.inScope(region, country, policy)`: a known
+  country decides by the territories, else a known region, else `unknownCountry` — `'protect'` by
+  default, so an unknown buyer is protected.
+- `consumerRegionHelper.chargeCurrencyOf(region, policy, fallback)`: the policy's currency for the
+  region; an unknown region reads as `Eu`. The display currency is the charge currency, everywhere.
+- `consumerRegionHelper.billingLanguageOf(country, policy?, fallback?)`: `policy.languages`, then
+  `COUNTRY_LANGUAGES` (unambiguous countries only — BE, LU, CH are absent), then `fallback`, then
+  `policy.defaultLanguage`. Legal copy is shown in this language, with a toggle to the UI language.
+
+### The policy record
+
+`ConsumerRightsPolicy` is a singleton config record (`CONSUMER_RIGHTS_RECORD_ID`), declared by the
+server integration through `makeConsumerRightsPolicy(def)` — `DEFAULT_CONSUMER_RIGHTS` filled in
+(14 days, weekend rollover, margin 5 — a period ending on a public holiday runs to the next working
+day and holiday clusters need up to five, no per-country calendar is kept —, every mechanism OFF,
+`defaultLanguage: 'en'`, start requests
+usable 3600 s) — and `consumerRightsPolicyHelper.assertConsumerRightsPolicy` (non-empty
+`textVersion`, `^[A-Z]{2}$` countries, `withdrawalDays >= 14`, margin 0..7, lowercase currencies,
+https links, the default language present, `withdrawalInformation` required while `withdrawal` or
+`performanceConsent` is on, `consentContext` a lowercase key `^[a-z][a-z0-9-]*$`; throws
+`ConsumerRightsError('policy:<field>')`). It carries only public links, territories, switches and
+the consent context — mail options live in a backend-only plugin config — so it is ADVERTISED to the
+browser like the pricing policy. **`consentContext`** names the copy variant of the performance
+consent (`'included'`: the credit limits included in a plan are used first, so the consent covers
+topped-up credits once those limits have run out): the server records and mails, and the dialog
+shows, the `_<context>` texts (§ The legal copy); absent, the base texts.
+`PaymentService.consumerRightsPolicy()` answers `null` when none is declared: no consumer-rights
+behaviour at all. `consumerRightsPolicyHelper.linksOf(policy, lng)` merges a language's links field
+by field over the default language's (`de-AT` reads `de`).
+
+`ProductPlan.withdrawal.components: PlanWithdrawalComponent[]` (`{ key, basis: 'time' | 'units',
+shareMinor }`) states the separately priced parts of a subscription (CJEU C-641/19 PE Digital:
+without them the whole price is pro rata by time). The same declaration picks the subscription start
+statement: a `units` part makes it the `_units` variant (`consumerCopyHelper.startContextOf`, § The
+legal copy).
+
+### Wire views
+
+Every view schema carries dates as ISO strings (as `model/view.ts` does) and is revived with its
+`consumerReviveHelper.revive*` member (`reviveConsentView`, `revivePurchase`/`List`,
+`reviveBillingProfile`, `reviveConsentResponse`, `reviveStartResponse`, `reviveWithdrawalList`,
+`reviveReceipt`, `reviveCheckoutLimit`, `reviveAmountPolicyView`) — idempotent. A nullable enum on
+the wire lists `null` in its enum (ajv rejects `null` otherwise). The consent and start views carry
+`trader`, the name the statement is rendered with, and `context`, the variant it is rendered with —
+the consent view the policy's `consentContext`, the start view
+`consumerCopyHelper.startContextOf(plan)` (`'units'`), each absent for the base — so the server's
+record and the dialog's text are identical. `WithdrawalBody` and `CancellationBody` ask only for
+name, contract and e-mail (plus the cancellation kind, reason and date) and accept an optional
+`honeypot` a person never fills. A public declaration answers `DeclarationReceipt` — what was
+declared and when, never whether a contract matched.
+
+### Calculators — always in the consumer's favour
+
+All amounts in BigInt; a deduction rounds DOWN, a refund rounds UP, a refund never exceeds what is
+still unrefunded.
+
+- `withdrawalDeadlineHelper.withdrawalDeadlineOf(purchasedAt, rule | policy)` → the EXCLUSIVE end:
+  the purchase's UTC day + `days`, a Saturday/Sunday last day moved to Monday, + `marginDays`, start
+  of the next UTC day. Wed 2026-09-23 → 2026-10-13T00:00Z; Sat 2026-09-26 → 2026-10-18T00:00Z; Sun
+  2026-12-20 → 2027-01-10T00:00Z (margin 5). `withdrawalDeadlineHelper.withdrawalOpen(window, at)` —
+  before the deadline, not withdrawn, not refunded. **A person is shown the last included day**,
+  `withdrawalDeadlineHelper.lastWithdrawalDayOf(deadline)` (the UTC day of `deadline − 1 ms`),
+  phrased "until the end of <date>" — never the exclusive instant.
+- `withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor, refundedMinor?, unitsGranted, unitsUsed })`
+  → `min(paid − refunded, ceil(paid × (granted − used) / granted))`; `unitsUsed` is the deduction —
+  units used AFTER consent (none before it) plus debt settled from the lot plus units already
+  clawed back (`@owlmeans/server-payment` passes the meter's `usedAfter + settled + clawed`);
+  returns `unitsReturned`. 1256 paid, 125k of 500k used → 942.
+- `withdrawalRefundHelper.subscriptionWithdrawalRefund(...)` splits `netMinor` by the components
+  (its `splitByShares`, largest remainder); a `time` part loses
+  `floor(c × elapsedDays / periodDays)` counted from `max(periodStart, servicesRequestedAt)` —
+  NOTHING without a start request; a `units` part loses `floor(c × used / granted)`; gross =
+  `ceil(paid × refundNet / net)`. Net 2000 / paid 2460, 3 of 30 days and 100k of 500k used → 2091.
+- `fifoHelper.allocateFifo(lots, spends)` — a spend takes the oldest lot granted at or before it;
+  overflow is `unallocated`. `fifoHelper.unitsUsedAfter(lot, consentedAt)` counts slices strictly
+  after the consent, `0` without one.
+- `cancellationEffectiveAt(periodEnd, 'month' | 'year', requested?)` — the period end, or the first
+  boundary on or after a later requested date (end-of-month clamped from the anchor).
+
+### Refusals
+
+`ConsumerRightsRefusal` extends `ConsumerRightsError` (a `PaymentError`), NEVER `AuthForbidden`:
+an HTTP boundary tests that family first, and a 403 would hide the status a client acts on. Each
+refusal declares `static httpStatus`, packs its fields into the message and rebuilds them in
+`finalizeUnmarshal()` (the marker is read after its LAST occurrence, so a registry rebuild of a
+doubled prefix still parses):
+
+| Class | Status | Marker (after `payment:consumer-rights:`) | Fields |
+|---|---|---|---|
+| `PerformanceConsentRequired` | 428 | `performance-consent-required:<pending>[:<deadline ISO>]` | `pending`, `deadline` |
+| `SubscriptionStartRequired` | 428 | `subscription-start-required:<encodeURIComponent(planSku)>` | `planSku` (pass it raw) |
+| `BillingCountryLocked` | 409 | `billing-country-locked:<country>[:<requested>]` | `country`, `requested` |
+| `WithdrawalUnavailable` | 409 | `withdrawal-unavailable:<WithdrawalUnavailableReason>` | `reason` |
+| `CancellationUnavailable` | 409 | `cancellation-unavailable:<CancellationUnavailableReason>` | `reason` |
+
+`consentRefusalOf(e)` → `'performance' | 'subscription-start' | null`: the class after
+`ResilientError.ensure`, else the marker or type name in `message`/`type`. A production body
+carries only an incident id — a bare 428 is the caller's to read with `@owlmeans/api/status`.
+
+### The legal copy
+
+The i18n resource `payment-consumer-rights` (`CONSUMER_RIGHTS_RESOURCE`, library tier, `lib`
+namespace), in en pl ru be uk es de fr, versioned by `CONSUMER_RIGHTS_COPY_VERSION` (bump it on ANY
+change to a bundle). Branches: `performance-consent`, `subscription-start` (`title`, `intro`,
+`request`, `acknowledgement`, `checkbox` = request + space + acknowledgement, `confirm`,
+`decline`; the consent branch also `purchase`; the start branch's `request`/`acknowledgement`/
+`checkbox` also as `_units`), `withdrawal`, `cancellation` (form labels and the
+statutory buttons `function` / `confirm`), `links`, `checkout` (`terms-acceptance.{in-scope,
+other}` markdown, `renewal.{month, year, after-submit}`, `price.{exclusive, inclusive, exclusive-tax}` (VAT wording for the territories, "applicable tax" for a buyer outside them), `top-up`,
+`top-up-note`), `email.{common, consent, start (`rule` + `rule_units`), purchase, withdrawal, cancellation}` (the purchase
+mail carries the CRD Annex I(A) withdrawal information with the function's address and the Annex
+I(B) model form, per language from the national models; there `{{trader}}` is the trader's whole
+identity — legal name, address, e-mail; a `review` withdrawal receipt promises the reimbursement
+within the statutory 14 days; `email.cancellation.review` answers an extraordinary cancellation,
+whose status is `CancellationStatus.Review`), `credit-note.memo`. In the consent and start
+STATEMENTS `{{trader}}` is the trader's short name.
+
+- Read it with `consumerCopyHelper.consumerRightsCopy(lng)` (any language, merged key by key over
+  English, no i18next instance, never drains a bundle — `i18nHelper.resolveI18nResource`),
+  `consumerCopyHelper.consumerText(lng, path, vars, context?)` (fills `{{name}}`; throws
+  `ConsumerRightsError('copy:<path>[:<name>]')` on a missing text or value — a legal text never goes
+  out with a hole), `consumerCopyHelper.consentStatementOf(lng, kind, { trader, plan?, context? })`
+  (the exact statement the dialog shows, the server records and the mail repeats) and
+  `consumerCopyHelper.legalLabelsOf(lng)`.
+- **Context variants** (the i18next context suffix): with a `context`,
+  `consumerCopyHelper.consumerText` reads `<path>_<context>` first and the base `path` only where no
+  such variant exists (a missing value then names the variant: `copy:<path>_<context>:<name>`); an
+  empty context is none. `consumerCopyHelper.consentStatementOf` passes its `context` to all three
+  texts. Shipped variants, all eight languages, same placeholders as the base keys, each request
+  keeping the base request's statutory opening verbatim; a new variant lands in every language at
+  once, with its base key's placeholders:
+  - `performance-consent.{title,intro,request,checkbox}_included` — the consuming platform's
+    vocabulary: "topped-up credits" (pl doładowane, ru пополненные, be папоўненыя, uk поповнені, es
+    recargados, de aufgeladene, fr rechargés) are spent once "the credit limits included in my plan"
+    (a plan's non-monetary credits) have run out; `checkbox_included` = `request_included` + space +
+    the BASE `acknowledgement` (generic "credits", so `acknowledgement` has no variant).
+  - **The subscription start statement follows the plan's withdrawal arithmetic.** The BASE
+    `subscription-start.{request,acknowledgement,checkbox}` and `email.start.rule` describe the
+    common case — the plan withdrawn pro rata by the DAYS ELAPSED only ("starts the {{plan}}
+    services — including the AI work within the usage the plan includes — now …; … I pay for the
+    services provided until then, pro rata by the days elapsed, and everything else is
+    reimbursed"); `…_units` (`checkbox_units` = `request_units` + space + `acknowledgement_units`)
+    describe the split — services pro rata by time, the right of withdrawal expiring for the
+    included units used. `consumerCopyHelper.startContextOf(plan)` is the ONE decision: `'units'`
+    exactly when the plan's `withdrawal.components` has a `basis: 'units'` part, else `undefined`.
+    Every renderer takes the context from it — the server's start view, the recorded statement and
+    the start mail, and the dialog (from the view's `context`) — so the statement on screen is the
+    one recorded. `title`, `intro`, `confirm`, `decline` have no `_units` variant. Generic statutory
+    text (the purchase mail's withdrawal information) stays generic.
+- Statutory labels are pinned by a test: en "Withdraw from contract here" / "Confirm withdrawal",
+  "Cancel contracts here" / "Cancel now"; de "Vertrag widerrufen" / "Widerruf bestätigen",
+  "Verträge hier kündigen" / "Jetzt kündigen"; fr "Renoncer au contrat ici" / "Confirmer la
+  rétractation", "Résilier votre contrat" / "Notification de la résiliation"; pl "Odstąp od umowy
+  tutaj" / "Potwierdź odstąpienie od umowy", "Wypowiedz umowę tutaj" / "Wypowiedz teraz"; es
+  "Desistir del contrato aquí" / "Confirmar el desistimiento", "Cancelar contratos aquí" /
+  "Cancelar ahora"; uk/ru/be are courtesy translations.
+- The express request uses the statutory verbs (PL "Żądam i wyrażam wyraźną zgodę … Przyjmuję do
+  wiadomości …", DE "Ich verlange ausdrücklich und stimme ausdrücklich zu … Mir ist bekannt …", FR
+  "Je demande expressément et j’accepte expressément … Je reconnais perdre …"). Every start
+  request — base and `_units`, every language — opens with the same three words as that language's
+  performance request (pinned by the copy spec).
+- Wording rule, enforced by a scan of every language: say "the right of withdrawal expires" and
+  "only unused credits are reimbursed" — never non-refundable / nicht erstattungsfähig / non
+  remboursable / bezzwrotny / no reembolsable / невозвратный / неповоротний / незваротны.
+- Paygate texts (`checkout.*`) stay within 1200 characters after interpolating long URLs.
+- An application overrides a text with `i18nHelper.addI18nApp(lng, CONSUMER_RIGHTS_RESOURCE, data,
+  { ns: LIB_NAMESPACE })`; every placeholder of a text must match its English master.
+
+### Protocol factories
+
+`makeConsumerRightsProtocols({ prefix, parent | guards (+ gate), path = '/consumer-rights',
+public?: false | { path = '/public/consumer-rights', parent?, screens?: { withdrawal?,
+cancellation?, parent? } } })`, the `makeMarketingConsentProtocols` way:
+
+- account subtree under the app's GUARDED parent (its guards and gate inherited): `base`,
+  `profile` GET `/profile`, `purchases` GET `/purchases`, `consent` GET / `giveConsent` POST
+  `/consent`, `start` GET `/start?planSku` / `requestStart` POST `/start`, `withdrawals` GET /
+  `withdraw` POST `/withdrawal`, `cancel` POST `/cancellation`; aliases `<prefix>:<name>`
+  (`consent:give`, `start:request`);
+- `public` (only when declared): `base`, `policy` GET `/policy`, `withdraw` POST `/withdrawal`,
+  `cancel` POST `/cancellation` — NO guard and NO gate (like `paymentGate.webhook`; a public
+  `parent` must be unguarded), receipts typed `DeclarationReceipt`; `screens` declares BOTH sticky
+  frontend routes (`/legal/withdraw`, `/legal/cancel` by default); aliases `<prefix>:public:<name>`;
+- neither `parent` nor `guards` is a `SyntaxError`; absent parts are left OUT of the tree (never
+  `undefined`), so `protocols(tree)` and `mapProtocols` walk it as is.
+
+`makeCheckoutReadProtocols({ prefix, parent | guards })` → `base` (`/checkout`), `amountPolicy`
+GET `/amount-policy?productSku&planSku` (`AmountPolicyView`) and `planPrices` GET
+`/plan-prices?productSku` (`PlanPriceList`).
+
+## `shallowAuthentication` identifies, it does not authorize
+
+It reads the `profileId` out of an envelope token WITHOUT verifying the signature, and throws
+`PaymentIdentificationError` when there is no token or no profile in it. Use it to correlate a
+checkout return with a visitor; never as the basis of an access decision — that is a gate's job.
 
 ## Depends On
 
-- `@owlmeans/entrypoint`, `@owlmeans/route`
-- `@owlmeans/auth`, `@owlmeans/error`, `@owlmeans/i18n`
+- `@owlmeans/entrypoint` · `@owlmeans/route` · `@owlmeans/config` · `@owlmeans/resource`
+- `@owlmeans/auth` (`PermissionSet`, `AuthForbidden`) · `@owlmeans/basic-envelope` · `@owlmeans/context`
+- `@owlmeans/error` · `@owlmeans/i18n` · `@owlmeans/api-config` · peer `ajv`
+
+## Related
+
+- [[entitlements]] — the model across packages: admission, the usage ledger, the gates
+- [[server-payment]] — the Stripe gateway, subscription store, usage ledger and gate services
+- [[web-payment]] — hooks and pieces over the entitlement view
+- [[client-payment]] — the browser-side adaptation of the catalogue service
+- [[iam]] — `PermissionSet` and the resource-selector syntax entitlements deliberately avoid

package/build/advertise.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=advertise.d.ts.map

package/build/advertise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertise.d.ts","sourceRoot":"","sources":["../src/advertise.ts"],"names":[],"mappings":""}

package/build/advertise.js

@@ -0,0 +1,10 @@
+import { CONFIG_RECORD } from '@owlmeans/context';
+import { apiConfigPlugin, every } from '@owlmeans/api-config';
+import { advertisedRecordTypes } from './consts.local.js';
+apiConfigPlugin({
+    allow: {
+        [CONFIG_RECORD]: every(true, value => value != null && typeof value === 'object'
+            && advertisedRecordTypes.has(value.recordType ?? '')),
+    },
+});
+//# sourceMappingURL=advertise.js.map

package/build/advertise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertise.js","sourceRoot":"","sources":["../src/advertise.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAEzD,eAAe,CAAC;IACd,KAAK,EAAE;QACL,CAAC,aAAa,CAAC,EAAE,KAAK,CACpB,IAAI,EACJ,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;eAC9C,qBAAqB,CAAC,GAAG,CAAE,KAAiC,CAAC,UAAU,IAAI,EAAE,CAAC,CACpF;KACF;CACF,CAAC,CAAA"}

package/build/checkout/consts.d.ts

@@ -0,0 +1,2 @@
+export declare const CHECKOUT_READ_API_PATH = "/checkout";
+//# sourceMappingURL=consts.d.ts.map

package/build/checkout/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../src/checkout/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,cAAc,CAAA"}

package/build/checkout/consts.js

@@ -0,0 +1,2 @@
+export const CHECKOUT_READ_API_PATH = '/checkout';
+//# sourceMappingURL=consts.js.map

package/build/checkout/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../../src/checkout/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAA"}

package/build/checkout/index.d.ts

@@ -0,0 +1,6 @@
+export * from './narrow.js';
+export type * from './types.js';
+export type * from './narrow/types.js';
+export * from './protocols.js';
+export * from './consts.js';
+//# sourceMappingURL=index.d.ts.map

package/build/checkout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkout/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,mBAAmB,CAAA;AACtC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA"}

package/build/checkout/index.js

@@ -0,0 +1,4 @@
+export * from './narrow.js';
+export * from './protocols.js';
+export * from './consts.js';
+//# sourceMappingURL=index.js.map

package/build/checkout/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkout/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAG3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA"}