@owlmeans/payment 0.1.18-rc.8 → 0.1.18

package/src/consumer/refund.ts

@@ -0,0 +1,136 @@
+import { ConsumerRightsError } from '../errors.js'
+import type { PlanWithdrawalComponent } from '../types.js'
+import { DAY_MS } from './consts.js'
+import type { OneTimeRefund, OneTimeRefundInput, SubscriptionRefund, SubscriptionRefundComponent, SubscriptionRefundInput } from './types.js'
+import type { WithdrawalRefundHelper } from './refund/types.js'
+
+// Every amount is computed in BigInt and rounded in the consumer's favour: a deduction rounds
+// down, a refund rounds up, and a refund never exceeds what is still unrefunded.
+
+const big = (value: number, field: string): bigint => {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new ConsumerRightsError(`refund:${field}`)
+  }
+
+  return BigInt(value)
+}
+
+/** A usage figure: fractions round DOWN (fewer units used, more reimbursed). */
+const units = (value: number, field: string): bigint => {
+  if (!Number.isFinite(value)) {
+    throw new ConsumerRightsError(`refund:${field}`)
+  }
+
+  return BigInt(Math.max(0, Math.floor(value)))
+}
+
+const ceilDiv = (a: bigint, b: bigint): bigint => (a + b - 1n) / b
+const min = (a: bigint, b: bigint): bigint => a < b ? a : b
+const clamp = (value: bigint, low: bigint, high: bigint): bigint => value < low ? low : value > high ? high : value
+
+export const createWithdrawalRefundHelper = (): WithdrawalRefundHelper => {
+  const splitByShares = (totalMinor: number, shares: number[]): number[] => {
+    if (shares.length === 0) {
+      return []
+    }
+    const total = big(totalMinor, 'total')
+    const weights = shares.map((share, index) => big(share, `share:${index}`))
+    const even = weights.every(weight => weight === 0n)
+    const effective = even ? weights.map(() => 1n) : weights
+    const sum = effective.reduce((acc, weight) => acc + weight, 0n)
+    const parts = effective.map(weight => (total * weight) / sum)
+    const remainders = effective.map((weight, index) => ({ index, rest: (total * weight) % sum }))
+    let left = total - parts.reduce((acc, part) => acc + part, 0n)
+    remainders.sort((a, b) => a.rest === b.rest ? a.index - b.index : a.rest > b.rest ? -1 : 1)
+    for (const { index } of remainders) {
+      if (left === 0n) {
+        break
+      }
+      parts[index] += 1n
+      left -= 1n
+    }
+
+    return parts.map(Number)
+  }
+
+  const oneTimeWithdrawalRefund = (input: OneTimeRefundInput): OneTimeRefund => {
+    const paid = big(input.paidMinor, 'paid')
+    const open = paid - min(paid, big(input.refundedMinor ?? 0, 'refunded'))
+    const granted = units(input.unitsGranted, 'granted')
+    if (granted === 0n) {
+      return { refundMinor: Number(open), netRatio: 1, unitsReturned: 0 }
+    }
+    const unused = granted - clamp(units(input.unitsUsed, 'used'), 0n, granted)
+
+    return {
+      refundMinor: Number(min(open, ceilDiv(paid * unused, granted))),
+      netRatio: Number(unused) / Number(granted),
+      unitsReturned: Number(unused),
+    }
+  }
+
+  const subscriptionWithdrawalRefund = (input: SubscriptionRefundInput): SubscriptionRefund => {
+    const paid = big(input.paidMinor, 'paid')
+    const open = paid - min(paid, big(input.refundedMinor ?? 0, 'refunded'))
+    const net = big(input.netMinor, 'net')
+    const declared = input.components != null && input.components.length > 0
+      ? input.components
+      : [{ key: 'price', basis: 'time', shareMinor: input.netMinor } satisfies PlanWithdrawalComponent]
+    const amounts = splitByShares(input.netMinor, declared.map(component => component.shareMinor))
+
+    const span = input.periodEnd.getTime() - input.periodStart.getTime()
+    if (Number.isNaN(span) || Number.isNaN(input.withdrawnAt.getTime())) {
+      throw new ConsumerRightsError('refund:period')
+    }
+    const periodDays = Math.max(1, Math.round(span / DAY_MS))
+    const requestedAt = input.servicesRequestedAt
+    const from = requestedAt == null ? null : Math.max(input.periodStart.getTime(), requestedAt.getTime())
+    const elapsedDays = from == null ? 0
+      : Math.min(periodDays, Math.max(0, Math.floor((input.withdrawnAt.getTime() - from) / DAY_MS)))
+
+    const granted = input.units != null ? units(input.units.granted, 'granted') : 0n
+    const used = input.units != null ? clamp(units(input.units.used, 'used'), 0n, granted) : 0n
+
+    let timeDeduction = 0n
+    let unitsDeduction = 0n
+    const components = declared.map((component, index): SubscriptionRefundComponent => {
+      const amount = BigInt(amounts[index])
+      let deduction = 0n
+      if (component.basis === 'time') {
+        deduction = (amount * BigInt(elapsedDays)) / BigInt(periodDays)
+        timeDeduction += deduction
+      } else if (granted > 0n) {
+        deduction = (amount * used) / granted
+        unitsDeduction += deduction
+      }
+
+      return { ...component, amountMinor: amounts[index], deductionMinor: Number(deduction) }
+    })
+
+    const refundNet = net - min(net, timeDeduction + unitsDeduction)
+    const refund = net === 0n ? open : min(open, ceilDiv(paid * refundNet, net))
+
+    return {
+      refundMinor: Number(refund),
+      refundNetMinor: Number(refundNet),
+      timeDeductionMinor: Number(timeDeduction),
+      unitsDeductionMinor: Number(unitsDeduction),
+      elapsedDays,
+      periodDays,
+      ...(input.units != null ? { unitsUsed: Number(used), unitsGranted: Number(granted) } : {}),
+      components,
+    }
+  }
+
+  return { splitByShares, oneTimeWithdrawalRefund, subscriptionWithdrawalRefund }
+}
+
+export const withdrawalRefundHelper = createWithdrawalRefundHelper()
+
+/** @deprecated compat:factory-refactor — use `withdrawalRefundHelper.oneTimeWithdrawalRefund(…)` */
+export const oneTimeWithdrawalRefund = (input: OneTimeRefundInput): OneTimeRefund =>
+  withdrawalRefundHelper.oneTimeWithdrawalRefund(input)
+
+/** @deprecated compat:factory-refactor — use `withdrawalRefundHelper.subscriptionWithdrawalRefund(…)` */
+export const subscriptionWithdrawalRefund = (input: SubscriptionRefundInput): SubscriptionRefund =>
+  withdrawalRefundHelper.subscriptionWithdrawalRefund(input)

package/src/consumer/refusal.ts

@@ -0,0 +1,35 @@
+import { isResilientError, ResilientError } from '@owlmeans/error'
+import { ConsentKind } from '../consts.js'
+import { PerformanceConsentRequired, SubscriptionStartRequired } from '../errors.js'
+import { CONSENT_REFUSAL_MARKERS } from './consts.local.js'
+
+/**
+ * Which express request a refusal asks for: `performance` (spend consent), `subscription-start`,
+ * or `null` for anything else. Recognises the class after `ResilientError.ensure` — a marshaled
+ * error that crossed a hop is rebuilt first — and otherwise the marker or type name in the
+ * `message` or `type`, so an error wrapped by another layer still answers. A bare HTTP 428 with
+ * no marker (a production incident body) is the caller's to check (`@owlmeans/api/status`).
+ */
+export const consentRefusalOf = (error: unknown): ConsentKind | null => {
+  if (error == null || typeof error !== 'object') {
+    return null
+  }
+  let candidate: unknown = error
+  if (!isResilientError(error) && error instanceof Error) {
+    try {
+      candidate = ResilientError.ensure(error)
+    } catch {
+      candidate = error
+    }
+  }
+  if (candidate instanceof PerformanceConsentRequired) {
+    return ConsentKind.Performance
+  }
+  if (candidate instanceof SubscriptionStartRequired) {
+    return ConsentKind.SubscriptionStart
+  }
+  const { message, type } = error as { message?: unknown, type?: unknown }
+  const texts = [message, type].filter((text): text is string => typeof text === 'string')
+
+  return CONSENT_REFUSAL_MARKERS.find(([marker]) => texts.some(text => text.includes(marker)))?.[1] ?? null
+}

package/src/consumer/revive/types.ts

@@ -0,0 +1,23 @@
+import type {
+  AmountPolicyView, BillingProfileView, CancellationReceipt, CheckoutLimitView, DeclarationReceipt,
+  PerformanceConsentResponse, PerformanceConsentView, PurchaseList, PurchaseView, SubscriptionStartResponse,
+  WithdrawalCandidateList, WithdrawalReceipt,
+} from '../../types.js'
+
+/**
+ * The consumer-rights wire values with their dates turned back into `Date`s. Each reviver copies
+ * the value; a value that already holds dates is copied as is, so reviving twice is harmless.
+ */
+export interface ConsumerReviveHelper {
+  revivePurchase: (purchase: PurchaseView) => PurchaseView
+  revivePurchaseList: (list: PurchaseList) => PurchaseList
+  reviveBillingProfile: (profile: BillingProfileView) => BillingProfileView
+  reviveConsentView: (view: PerformanceConsentView) => PerformanceConsentView
+  reviveConsentResponse: (response: PerformanceConsentResponse) => PerformanceConsentResponse
+  reviveStartResponse: (response: SubscriptionStartResponse) => SubscriptionStartResponse
+  reviveWithdrawalList: (list: WithdrawalCandidateList) => WithdrawalCandidateList
+  /** Any declaration receipt — withdrawal or cancellation. */
+  reviveReceipt: <T extends DeclarationReceipt | WithdrawalReceipt | CancellationReceipt>(receipt: T) => T
+  reviveCheckoutLimit: (limit: CheckoutLimitView) => CheckoutLimitView
+  reviveAmountPolicyView: (view: AmountPolicyView) => AmountPolicyView
+}

package/src/consumer/revive.ts

@@ -0,0 +1,82 @@
+import type {
+  AmountPolicyView, BillingProfileView, CancellationReceipt, CheckoutLimitView, DeclarationReceipt,
+  PerformanceConsentResponse, PerformanceConsentView, PurchaseList, PurchaseView, SubscriptionStartResponse,
+  WithdrawalCandidate, WithdrawalCandidateList, WithdrawalReceipt,
+} from '../types.js'
+import type { Dated } from './types.local.js'
+import type { ConsumerReviveHelper } from './revive/types.js'
+
+// The wire carries every date as an ISO string (see `model/consumer.ts`). Each reviver copies the
+// value and turns the named fields back into `Date`s; a value that already holds dates is copied
+// as is, so reviving twice is harmless.
+
+export const createConsumerReviveHelper = (): ConsumerReviveHelper => {
+  const revive = <T>(value: T, fields: readonly string[]): T => {
+    const copy: Dated = { ...(value as Dated) }
+    for (const field of fields) {
+      const raw = copy[field]
+      if (raw != null && !(raw instanceof Date)) {
+        copy[field] = new Date(raw as string)
+      }
+    }
+
+    return copy as T
+  }
+
+  const revivePurchase = (purchase: PurchaseView): PurchaseView =>
+    revive(purchase, ['purchasedAt', 'deadline', 'consentedAt', 'withdrawnAt'])
+
+  const revivePurchaseList = (list: PurchaseList): PurchaseList =>
+    ({ ...list, purchases: list.purchases.map(revivePurchase) })
+
+  const reviveBillingProfile = (profile: BillingProfileView): BillingProfileView =>
+    revive(profile, ['lockedAt'])
+
+  const reviveConsentView = (view: PerformanceConsentView): PerformanceConsentView => ({
+    ...revive(view, ['deadline', 'at']),
+    purchases: view.purchases.map(revivePurchase),
+  })
+
+  const reviveConsentResponse = (response: PerformanceConsentResponse): PerformanceConsentResponse =>
+    revive(response, ['consentedAt'])
+
+  const reviveStartResponse = (response: SubscriptionStartResponse): SubscriptionStartResponse =>
+    revive(response, ['requestedAt', 'expiresAt'])
+
+  const reviveCandidate = (candidate: WithdrawalCandidate): WithdrawalCandidate =>
+    revive(candidate, ['purchasedAt', 'deadline'])
+
+  const reviveWithdrawalList = (list: WithdrawalCandidateList): WithdrawalCandidateList =>
+    ({ ...list, candidates: list.candidates.map(reviveCandidate) })
+
+  const reviveReceipt = <T extends DeclarationReceipt | WithdrawalReceipt | CancellationReceipt>(receipt: T): T =>
+    revive(receipt, ['receivedAt', 'effectiveAt'])
+
+  const reviveCheckoutLimit = (limit: CheckoutLimitView): CheckoutLimitView =>
+    revive(limit, ['resetsAt'])
+
+  const reviveAmountPolicyView = (view: AmountPolicyView): AmountPolicyView =>
+    ({ ...view, limit: view.limit == null ? null : reviveCheckoutLimit(view.limit) })
+
+  return {
+    revivePurchase, revivePurchaseList, reviveBillingProfile, reviveConsentView, reviveConsentResponse,
+    reviveStartResponse, reviveWithdrawalList, reviveReceipt, reviveCheckoutLimit, reviveAmountPolicyView,
+  }
+}
+
+export const consumerReviveHelper = createConsumerReviveHelper()
+
+/** @deprecated compat:factory-refactor — use `consumerReviveHelper.revivePurchaseList(…)` */
+export const revivePurchaseList = (list: PurchaseList): PurchaseList => consumerReviveHelper.revivePurchaseList(list)
+
+/** @deprecated compat:factory-refactor — use `consumerReviveHelper.reviveBillingProfile(…)` */
+export const reviveBillingProfile = (profile: BillingProfileView): BillingProfileView =>
+  consumerReviveHelper.reviveBillingProfile(profile)
+
+/** @deprecated compat:factory-refactor — use `consumerReviveHelper.reviveConsentView(…)` */
+export const reviveConsentView = (view: PerformanceConsentView): PerformanceConsentView =>
+  consumerReviveHelper.reviveConsentView(view)
+
+/** @deprecated compat:factory-refactor — use `consumerReviveHelper.reviveAmountPolicyView(…)` */
+export const reviveAmountPolicyView = (view: AmountPolicyView): AmountPolicyView =>
+  consumerReviveHelper.reviveAmountPolicyView(view)

package/src/consumer/types.local.ts

@@ -0,0 +1,10 @@
+import type { ConsumerRightsPolicy } from '../types.js'
+import type { ConsumerRightsPublicProtocols, ConsumerRightsScreens } from './types.js'
+
+export interface DeadlinePolicy extends Pick<ConsumerRightsPolicy, 'withdrawalDays' | 'deadline'> {}
+
+export type PublicOf<P> = P extends { screens: object }
+  ? ConsumerRightsPublicProtocols & { screens: ConsumerRightsScreens }
+  : ConsumerRightsPublicProtocols
+
+export type Dated = Record<string, unknown>

package/src/consumer/types.ts

@@ -0,0 +1,189 @@
+import type { ConsumerRightsMechanisms, ConsumerRightsPolicy, BillingProfileView, CancellationBody, CancellationReceipt, ConsumerRightsPublicView, DeclarationReceipt, PerformanceConsentBody, PerformanceConsentResponse, PerformanceConsentView, PurchaseList, SubscriptionStartBody, SubscriptionStartQuery, SubscriptionStartResponse, SubscriptionStartView, WithdrawalBody, WithdrawalCandidateList, WithdrawalReceipt, PlanWithdrawalComponent } from '../types.js'
+import type { RouteParent } from '@owlmeans/route'
+import type { EntrypointOptions, EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
+import type { PublicOf } from './types.local.js'
+
+export type BillingInterval = 'month' | 'year'
+
+/** A copy bundle: nested keys, string leaves. */
+export interface CopyTree {
+  [key: string]: string | CopyTree
+}
+
+export type CopyValues = Record<string, string | number>
+
+export interface LegalLabels {
+  withdrawal: { function: string, confirm: string }
+  cancellation: { function: string, confirm: string }
+}
+
+export interface ConsentStatement {
+  request: string
+  acknowledgement: string
+  /** The checkbox text: the request and the acknowledgement together. */
+  checkbox: string
+}
+
+export interface WithdrawalDeadlineRule {
+  /** Default 14. */
+  days?: number
+  /** A period ending on a Saturday or Sunday ends on the Monday after. Default on. */
+  weekendRollover?: boolean
+  /** Whole days added after the rollover, covering public holidays. Default 5. */
+  marginDays?: number
+}
+
+/** What decides whether a purchase can still be withdrawn from. */
+export interface WithdrawalWindow {
+  deadline?: Date | null
+  withdrawnAt?: Date | null
+  refundedAt?: Date | null
+}
+
+/** Units granted at one instant — a purchase's credits. */
+export interface FifoLot {
+  id: string
+  units: number
+  at: Date
+}
+
+/** Units spent at one instant. */
+export interface FifoSpend {
+  units: number
+  at: Date
+}
+
+/** One lot after allocation, with every slice of it a spend took. */
+export interface FifoLotUsage {
+  id: string
+  at: Date
+  granted: number
+  used: number
+  slices: Array<{ at: Date, units: number }>
+}
+
+export interface FifoAllocation {
+  lots: FifoLotUsage[]
+  /** Spent units no lot granted at or before the spend could cover. */
+  unallocated: number
+}
+
+// Kept as a type: its parts redeclare the same keys with narrower types, which interface `extends` refuses.
+/** What an application must state itself; everything else defaults. */
+export type ConsumerRightsDeclaration = Partial<Omit<ConsumerRightsPolicy, 'mechanisms' | 'deadline'>>
+  & Pick<ConsumerRightsPolicy, 'textVersion' | 'links'>
+  & { mechanisms?: Partial<ConsumerRightsMechanisms>, deadline?: Partial<ConsumerRightsPolicy['deadline']> }
+
+export interface ConsumerRightsPublicOptions {
+  /** Default `/public/consumer-rights`. */
+  path?: string
+  /** An UNGUARDED parent only — whatever it guards, this subtree inherits. */
+  parent?: RouteParent
+  /**
+   * Declare the two public frontend screens (sticky, like every legal page): the withdrawal
+   * function and the cancellation page. Both or neither.
+   */
+  screens?: { withdrawal?: string, cancellation?: string, parent?: RouteParent }
+}
+
+export interface ConsumerRightsProtocolOptions {
+  /** Alias prefix of every declaration, e.g. `my-app:account:consumer`. */
+  prefix: string
+  /** The application's guarded parent (its account base) — its guards and gate are inherited. */
+  parent?: RouteParent
+  /** Guards of a tree mounted without a parent. */
+  guards?: EntrypointOptions['guards']
+  gate?: EntrypointOptions['gate']
+  /** Default `/consumer-rights`. */
+  path?: string
+  /** The unguarded public subtree; absent or `false` declares none. */
+  public?: false | ConsumerRightsPublicOptions
+}
+
+/** The guarded account subtree: one entity's own purchases, consents and declarations. */
+export interface ConsumerRightsAccountProtocols {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  profile: EntrypointProtocol<{}, BillingProfileView>
+  purchases: EntrypointProtocol<{}, PurchaseList>
+  consent: EntrypointProtocol<{}, PerformanceConsentView>
+  giveConsent: EntrypointProtocol<{ body: PerformanceConsentBody }, PerformanceConsentResponse>
+  start: EntrypointProtocol<{ query: SubscriptionStartQuery }, SubscriptionStartView>
+  requestStart: EntrypointProtocol<{ body: SubscriptionStartBody }, SubscriptionStartResponse>
+  withdrawals: EntrypointProtocol<{}, WithdrawalCandidateList>
+  withdraw: EntrypointProtocol<{ body: WithdrawalBody }, WithdrawalReceipt>
+  cancel: EntrypointProtocol<{ body: CancellationBody }, CancellationReceipt>
+}
+
+export interface ConsumerRightsScreens {
+  withdrawal: EntrypointProtocol<OpenRequest, OpenValue>
+  cancellation: EntrypointProtocol<OpenRequest, OpenValue>
+}
+
+/**
+ * The unguarded public subtree: reachable WITHOUT a login (§ 312k BGB). Its receipts carry only
+ * what was declared and when — never whether a contract matched.
+ */
+export interface ConsumerRightsPublicProtocols {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  policy: EntrypointProtocol<{}, ConsumerRightsPublicView>
+  withdraw: EntrypointProtocol<{ body: WithdrawalBody }, DeclarationReceipt>
+  cancel: EntrypointProtocol<{ body: CancellationBody }, DeclarationReceipt>
+}
+
+/** The tree for given options — `public` (and its `screens`) present only when declared. */
+export type ConsumerRightsProtocols<O extends ConsumerRightsProtocolOptions = ConsumerRightsProtocolOptions> =
+  O['public'] extends ConsumerRightsPublicOptions
+    ? ConsumerRightsAccountProtocols & { public: PublicOf<O['public']> }
+    : ConsumerRightsAccountProtocols
+
+export interface OneTimeRefundInput {
+  paidMinor: number
+  /** Already refunded (an earlier partial refund); the refund never exceeds the rest. */
+  refundedMinor?: number
+  unitsGranted: number
+  /** Units used AFTER consent — before it, the consumer bears no cost. Clamped to `0..granted`. */
+  unitsUsed: number
+}
+
+export interface OneTimeRefund {
+  refundMinor: number
+  /** The share of the purchase that is unused: `(granted − used) / granted`. */
+  netRatio: number
+  /** The unused units a withdrawal takes back. */
+  unitsReturned: number
+}
+
+export interface SubscriptionRefundInput {
+  paidMinor: number
+  refundedMinor?: number
+  /** The price net of tax — the base the components split and the deductions come from. */
+  netMinor: number
+  /** Absent or empty: the whole price is one `time` component. */
+  components?: PlanWithdrawalComponent[]
+  periodStart: Date
+  periodEnd: Date
+  /** When the consumer expressly requested the services. None: no time deduction at all. */
+  servicesRequestedAt?: Date | null
+  withdrawnAt: Date
+  /** Units granted with the purchase and used after consent — applied to every `units` component. */
+  units?: { granted: number, used: number } | null
+}
+
+export interface SubscriptionRefundComponent extends PlanWithdrawalComponent {
+  /** The component's part of `netMinor`. */
+  amountMinor: number
+  deductionMinor: number
+}
+
+export interface SubscriptionRefund {
+  /** Gross (tax-inclusive) refund, capped at what is still unrefunded. */
+  refundMinor: number
+  refundNetMinor: number
+  timeDeductionMinor: number
+  unitsDeductionMinor: number
+  elapsedDays: number
+  periodDays: number
+  unitsUsed?: number
+  unitsGranted?: number
+  components: SubscriptionRefundComponent[]
+}

package/src/countries.ts

@@ -0,0 +1,5 @@
+import { COUNTRY_CURRENCIES } from './consts.js'
+
+/** The lowercase ISO 4217 currency of a country, or `null` when this map has no entry for it. */
+export const currencyOfCountry = (country: string): string | null =>
+  COUNTRY_CURRENCIES[country.toUpperCase()] ?? null

package/src/entitled.ts

@@ -0,0 +1,20 @@
+import type { EntrypointOptions } from '@owlmeans/entrypoint'
+import { ENTITLEMENT_GATE } from './consts.js'
+
+/**
+ * Declare that an entrypoint needs a paid capability.
+ *
+ * Compatibility sugar over the protocol option
+ * `{ gate: { alias: ENTITLEMENT_GATE, params } }` so a route reads as what it means. Several
+ * parameters are OR'd, matching every other gate in the framework.
+ *
+ * Putting the requirement HERE rather than in a handler is the point: the framework asserts a gate
+ * before the handler is entered, so the route table states what a feature costs and no new
+ * endpoint can forget to check.
+ */
+export const entitled = (
+  params: string | string[], opts?: EntrypointOptions,
+): EntrypointOptions => ({
+  ...opts,
+  gate: { alias: ENTITLEMENT_GATE, params },
+})

package/src/entitlement/types.ts

@@ -0,0 +1,29 @@
+import type { PermissionSet } from '@owlmeans/auth'
+import type { EntitlementParam } from '../types.js'
+
+/** The entitlement parameter grammar and the capability predicate the server gate and the browser share. */
+export interface EntitlementParamHelper {
+  /**
+   * Grammar: `[<scope>:]<permission>[>=<n>]`.
+   *
+   * `feature:branding--whitelabel` · `renewable:credits>=100` · `production--standalone`
+   *
+   * `@` is deliberately not part of it: that is `@owlmeans/iam`'s resource-selector syntax, and a
+   * grammar that reused it would make two different things look the same in a route declaration.
+   */
+  parseEntitlementParam: (param: string) => EntitlementParam
+  formatEntitlementParam: (parsed: EntitlementParam) => string
+  /**
+   * Whether a union of capability sets satisfies one requirement.
+   *
+   * Pure, and shared by the server gate and the browser: the UI has to know whether to render a
+   * control disabled, and a second implementation of the rule for the client would eventually
+   * disagree with the one that actually refuses.
+   *
+   * A malformed parameter answers `false` rather than throwing. A gate that crashed on a typo would
+   * take down the endpoint it guards, which is a strictly worse failure than refusing it.
+   */
+  hasEntitlement: (capabilities: PermissionSet[] | undefined, param: string) => boolean
+  /** Everything a union grants, formatted back into parameters. The wire shape of a client read. */
+  entitlementList: (capabilities: PermissionSet[] | undefined) => string[]
+}

package/src/entitlement.ts

@@ -0,0 +1,86 @@
+import type { PermissionSet } from '@owlmeans/auth'
+import { CAPABILITY_LIMIT_SCOPE } from './consts.js'
+import type { EntitlementParam } from './types.js'
+import type { EntitlementParamHelper } from './entitlement/types.js'
+
+export const createEntitlementParamHelper = (): EntitlementParamHelper => {
+  const parseEntitlementParam = (param: string): EntitlementParam => {
+    const [scoped, floor] = param.split('>=')
+    const colon = scoped.indexOf(':')
+    const parsed: EntitlementParam = colon >= 0
+      ? { scope: scoped.slice(0, colon), permission: scoped.slice(colon + 1) }
+      : { permission: scoped }
+
+    if (floor != null) {
+      const value = Number.parseFloat(floor)
+      if (!Number.isNaN(value)) {
+        parsed.atLeast = value
+      }
+    }
+
+    return parsed
+  }
+
+  const formatEntitlementParam = (parsed: EntitlementParam): string =>
+    `${parsed.scope != null ? `${parsed.scope}:` : ''}${parsed.permission}` +
+    `${parsed.atLeast != null ? `>=${parsed.atLeast}` : ''}`
+
+  const hasEntitlement = (
+    capabilities: PermissionSet[] | undefined, param: string
+  ): boolean => {
+    if (capabilities == null || capabilities.length < 1) {
+      return false
+    }
+    if (typeof param !== 'string') {
+      return false
+    }
+    const { scope, permission, atLeast } = parseEntitlementParam(param)
+    // A limit is never a capability: its room is counted, not granted.
+    if (permission === '' || scope === CAPABILITY_LIMIT_SCOPE) {
+      return false
+    }
+
+    return capabilities.some(set => {
+      if (scope != null && set.scope !== scope) {
+        return false
+      }
+      const held = set.permissions?.[permission]
+      if (held == null || held === false) {
+        return false
+      }
+
+      // A floor is a numeric question: a boolean flag, however true, does not answer it.
+      return atLeast != null ? typeof held === 'number' && held >= atLeast : true
+    })
+  }
+
+  const entitlementList = (capabilities: PermissionSet[] | undefined): string[] => {
+    const list: string[] = []
+    for (const set of capabilities ?? []) {
+      for (const [permission, value] of Object.entries(set.permissions ?? {})) {
+        if (value == null || value === false) {
+          continue
+        }
+        list.push(formatEntitlementParam({ scope: set.scope, permission }))
+      }
+    }
+
+    return [...new Set(list)]
+  }
+
+  return { parseEntitlementParam, formatEntitlementParam, hasEntitlement, entitlementList }
+}
+
+export const entitlementParamHelper = createEntitlementParamHelper()
+
+/** @deprecated compat:factory-refactor — use `entitlementParamHelper.parseEntitlementParam(…)` */
+export const parseEntitlementParam = (param: string): EntitlementParam =>
+  entitlementParamHelper.parseEntitlementParam(param)
+
+/** @deprecated compat:factory-refactor — use `entitlementParamHelper.formatEntitlementParam(…)` */
+export const formatEntitlementParam = (parsed: EntitlementParam): string =>
+  entitlementParamHelper.formatEntitlementParam(parsed)
+
+/** @deprecated compat:factory-refactor — use `entitlementParamHelper.hasEntitlement(…)` */
+export const hasEntitlement = (capabilities: PermissionSet[] | undefined, param: string): boolean =>
+  entitlementParamHelper.hasEntitlement(capabilities, param)