@owlmeans/payment 0.1.18-rc.8 → 0.1.18

package/src/consumer/copy.ts

@@ -0,0 +1,121 @@
+import { LIB_NAMESPACE, resolveI18nResource } from '@owlmeans/i18n'
+import '../i18n.js'
+import { ConsentKind, CONSUMER_RIGHTS_RESOURCE } from '../consts.js'
+import { ConsumerRightsError } from '../errors.js'
+import type { ProductPlan } from '../types.js'
+import { consumerRightsPolicyHelper } from './policy.js'
+import type { ConsentStatement, CopyTree, CopyValues, LegalLabels } from './types.js'
+import type { ConsumerCopyHelper } from './copy/types.js'
+
+const isTree = (value: unknown): value is CopyTree =>
+  value != null && typeof value === 'object' && !Array.isArray(value)
+
+export const createConsumerCopyHelper = (): ConsumerCopyHelper => {
+  const merge = (base: CopyTree, over: Record<string, unknown>): CopyTree => {
+    const result: CopyTree = { ...base }
+    for (const [key, value] of Object.entries(over)) {
+      const current = result[key]
+      if (isTree(value)) {
+        result[key] = merge(isTree(current) ? current : {}, value)
+      } else if (typeof value === 'string') {
+        result[key] = value
+      }
+    }
+
+    return result
+  }
+
+  const resolve = (lng: string): Record<string, unknown> | null =>
+    resolveI18nResource(lng, CONSUMER_RIGHTS_RESOURCE, LIB_NAMESPACE)
+
+  const consumerRightsCopy = (lng: string): CopyTree => {
+    const base = consumerRightsPolicyHelper.baseLanguageOf(lng)
+    let copy = merge({}, resolve('en') ?? {})
+    if (base !== '' && base !== 'en') {
+      copy = merge(copy, resolve(base) ?? {})
+    }
+    if (lng !== base && lng.trim() !== '') {
+      copy = merge(copy, resolve(lng) ?? {})
+    }
+
+    return copy
+  }
+
+  const textAt = (copy: CopyTree, path: string): string | undefined => {
+    const value = path.split('.').reduce<unknown>((node, key) => isTree(node) ? node[key] : undefined, copy)
+
+    return typeof value === 'string' ? value : undefined
+  }
+
+  const consumerText = (lng: string, path: string, vars: CopyValues = {}, context?: string): string => {
+    const copy = consumerRightsCopy(lng)
+    const variant = context != null && context !== '' ? `${path}_${context}` : null
+    const key = variant != null && textAt(copy, variant) != null ? variant : path
+    const value = textAt(copy, key)
+    if (value == null) {
+      throw new ConsumerRightsError(`copy:${path}`)
+    }
+
+    return value.replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_, name: string) => {
+      const filled = vars[name]
+      if (filled == null) {
+        throw new ConsumerRightsError(`copy:${key}:${name}`)
+      }
+
+      return String(filled)
+    })
+  }
+
+  const placeholdersOf = (text: string): string[] =>
+    [...new Set([...text.matchAll(/\{\{\s*([\w-]+)\s*\}\}/g)].map(match => match[1]))]
+
+  const legalLabelsOf = (lng: string): LegalLabels => ({
+    withdrawal: {
+      function: consumerText(lng, 'withdrawal.function'),
+      confirm: consumerText(lng, 'withdrawal.confirm'),
+    },
+    cancellation: {
+      function: consumerText(lng, 'cancellation.function'),
+      confirm: consumerText(lng, 'cancellation.confirm'),
+    },
+  })
+
+  const startContextOf = (plan: Pick<ProductPlan, 'withdrawal'> | null | undefined): 'units' | undefined =>
+    plan?.withdrawal?.components?.some(component => component.basis === 'units') === true ? 'units' : undefined
+
+  const consentStatementOf = (
+    lng: string, kind: ConsentKind, vars: { trader: string, plan?: string, context?: string },
+  ): ConsentStatement => {
+    const branch = kind === ConsentKind.SubscriptionStart ? 'subscription-start' : 'performance-consent'
+    const values: CopyValues = { trader: vars.trader, ...(vars.plan != null ? { plan: vars.plan } : {}) }
+
+    return {
+      request: consumerText(lng, `${branch}.request`, values, vars.context),
+      acknowledgement: consumerText(lng, `${branch}.acknowledgement`, values, vars.context),
+      checkbox: consumerText(lng, `${branch}.checkbox`, values, vars.context),
+    }
+  }
+
+  return { consumerRightsCopy, consumerText, placeholdersOf, legalLabelsOf, startContextOf, consentStatementOf }
+}
+
+export const consumerCopyHelper = createConsumerCopyHelper()
+
+/** @deprecated compat:factory-refactor — use `consumerCopyHelper.consumerRightsCopy(…)` */
+export const consumerRightsCopy = (lng: string): CopyTree => consumerCopyHelper.consumerRightsCopy(lng)
+
+/** @deprecated compat:factory-refactor — use `consumerCopyHelper.consumerText(…)` */
+export const consumerText = (lng: string, path: string, vars?: CopyValues, context?: string): string =>
+  consumerCopyHelper.consumerText(lng, path, vars, context)
+
+/** @deprecated compat:factory-refactor — use `consumerCopyHelper.legalLabelsOf(…)` */
+export const legalLabelsOf = (lng: string): LegalLabels => consumerCopyHelper.legalLabelsOf(lng)
+
+/** @deprecated compat:factory-refactor — use `consumerCopyHelper.startContextOf(…)` */
+export const startContextOf = (plan: Pick<ProductPlan, 'withdrawal'> | null | undefined): 'units' | undefined =>
+  consumerCopyHelper.startContextOf(plan)
+
+/** @deprecated compat:factory-refactor — use `consumerCopyHelper.consentStatementOf(…)` */
+export const consentStatementOf = (
+  lng: string, kind: ConsentKind, vars: { trader: string, plan?: string, context?: string },
+): ConsentStatement => consumerCopyHelper.consentStatementOf(lng, kind, vars)

package/src/consumer/deadline/types.ts

@@ -0,0 +1,30 @@
+import type { DeadlinePolicy } from '../types.local.js'
+import type { WithdrawalDeadlineRule, WithdrawalWindow } from '../types.js'
+
+/** The withdrawal period: its exclusive end, its last day for display, and whether it is open. */
+export interface WithdrawalDeadlineHelper {
+  /**
+   * The EXCLUSIVE end of a withdrawal period — the first instant at which it is over.
+   *
+   * The period starts the day after the purchase (the purchase day is not counted) and lasts `days`
+   * UTC calendar days; a last day on a Saturday or Sunday moves to the Monday after; `marginDays`
+   * are then added for public holidays and time zones; the result is the 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 (14 days, margin 5). Shown to a person as its last included day
+   * (`lastWithdrawalDayOf`), never as the exclusive instant.
+   *
+   * @throws ConsumerRightsError (`deadline`) for an invalid date or rule.
+   */
+  withdrawalDeadlineOf: (purchasedAt: Date, rule?: WithdrawalDeadlineRule | DeadlinePolicy) => Date
+  /**
+   * The last day a withdrawal is still in time, for display: the UTC calendar day of `deadline − 1 ms`
+   * (a deadline is the EXCLUSIVE first instant after the period). 2026-10-13T00:00Z → 2026-10-12;
+   * show it as a UTC date, "until the end of 12 October 2026".
+   */
+  lastWithdrawalDayOf: (deadline: Date) => Date
+  /**
+   * Whether a withdrawal window is open at `at`: a deadline exists, `at` is before it, and the
+   * purchase was neither withdrawn from nor refunded. A bare deadline is accepted as well.
+   */
+  withdrawalOpen: (window: WithdrawalWindow | Date | null | undefined, at?: Date) => boolean
+}

package/src/consumer/deadline.ts

@@ -0,0 +1,61 @@
+import { ConsumerRightsError } from '../errors.js'
+import { DAY_MS } from './consts.js'
+import type { DeadlinePolicy } from './types.local.js'
+import type { WithdrawalDeadlineRule, WithdrawalWindow } from './types.js'
+import type { WithdrawalDeadlineHelper } from './deadline/types.js'
+
+export const createWithdrawalDeadlineHelper = (): WithdrawalDeadlineHelper => {
+  const ruleOf = (rule?: WithdrawalDeadlineRule | DeadlinePolicy): Required<WithdrawalDeadlineRule> => {
+    if (rule != null && 'withdrawalDays' in rule) {
+      return { days: rule.withdrawalDays, weekendRollover: rule.deadline.weekendRollover, marginDays: rule.deadline.marginDays }
+    }
+
+    return { days: rule?.days ?? 14, weekendRollover: rule?.weekendRollover ?? true, marginDays: rule?.marginDays ?? 5 }
+  }
+
+  const withdrawalDeadlineOf = (purchasedAt: Date, rule?: WithdrawalDeadlineRule | DeadlinePolicy): Date => {
+    const { days, weekendRollover, marginDays } = ruleOf(rule)
+    if (Number.isNaN(purchasedAt.getTime()) || !Number.isSafeInteger(days) || days < 0
+      || !Number.isSafeInteger(marginDays) || marginDays < 0) {
+      throw new ConsumerRightsError('deadline')
+    }
+    const purchaseDay = Date.UTC(purchasedAt.getUTCFullYear(), purchasedAt.getUTCMonth(), purchasedAt.getUTCDate())
+    let lastDay = purchaseDay + days * DAY_MS
+    if (weekendRollover) {
+      const weekday = new Date(lastDay).getUTCDay()
+      lastDay += weekday === 6 ? 2 * DAY_MS : weekday === 0 ? DAY_MS : 0
+    }
+
+    return new Date(lastDay + (marginDays + 1) * DAY_MS)
+  }
+
+  const lastWithdrawalDayOf = (deadline: Date): Date => {
+    const last = new Date(deadline.getTime() - 1)
+
+    return new Date(Date.UTC(last.getUTCFullYear(), last.getUTCMonth(), last.getUTCDate()))
+  }
+
+  const withdrawalOpen = (window: WithdrawalWindow | Date | null | undefined, at: Date = new Date()): boolean => {
+    if (window == null) {
+      return false
+    }
+    const { deadline, withdrawnAt, refundedAt } = window instanceof Date ? { deadline: window } as WithdrawalWindow : window
+
+    return deadline != null && withdrawnAt == null && refundedAt == null && at.getTime() < deadline.getTime()
+  }
+
+  return { withdrawalDeadlineOf, lastWithdrawalDayOf, withdrawalOpen }
+}
+
+export const withdrawalDeadlineHelper = createWithdrawalDeadlineHelper()
+
+/** @deprecated compat:factory-refactor — use `withdrawalDeadlineHelper.withdrawalDeadlineOf(…)` */
+export const withdrawalDeadlineOf = (purchasedAt: Date, rule?: WithdrawalDeadlineRule | DeadlinePolicy): Date =>
+  withdrawalDeadlineHelper.withdrawalDeadlineOf(purchasedAt, rule)
+
+/** @deprecated compat:factory-refactor — use `withdrawalDeadlineHelper.lastWithdrawalDayOf(…)` */
+export const lastWithdrawalDayOf = (deadline: Date): Date => withdrawalDeadlineHelper.lastWithdrawalDayOf(deadline)
+
+/** @deprecated compat:factory-refactor — use `withdrawalDeadlineHelper.withdrawalOpen(…)` */
+export const withdrawalOpen = (window: WithdrawalWindow | Date | null | undefined, at?: Date): boolean =>
+  withdrawalDeadlineHelper.withdrawalOpen(window, at)

package/src/consumer/fifo/types.ts

@@ -0,0 +1,17 @@
+import type { FifoAllocation, FifoLot, FifoLotUsage, FifoSpend } from '../types.js'
+
+/** First-in-first-out allocation of spends over granted lots. */
+export interface FifoHelper {
+  /**
+   * First in, first out: every spend, in time order, takes from the oldest lot granted AT OR BEFORE
+   * it that still has units, then the next one; what no such lot covers is `unallocated` (a lot
+   * granted later never pays for an earlier spend). Lots come back in grant order. Pure — the input
+   * arrays are not reordered.
+   */
+  allocateFifo: (lots: FifoLot[], spends: FifoSpend[]) => FifoAllocation
+  /**
+   * The units of a lot used strictly AFTER an instant — its consent. Without one (`null`), nothing
+   * is deductible: before consent the consumer bears no cost.
+   */
+  unitsUsedAfter: (lot: Pick<FifoLotUsage, 'slices'>, after: Date | null | undefined) => number
+}

package/src/consumer/fifo.ts

@@ -0,0 +1,42 @@
+import type { FifoAllocation, FifoLot, FifoLotUsage, FifoSpend } from './types.js'
+import type { FifoHelper } from './fifo/types.js'
+
+export const createFifoHelper = (): FifoHelper => {
+  const allocateFifo = (lots: FifoLot[], spends: FifoSpend[]): FifoAllocation => {
+    const usage: FifoLotUsage[] = [...lots]
+      .map((lot, index) => ({ lot, index }))
+      .sort((a, b) => a.lot.at.getTime() - b.lot.at.getTime() || a.index - b.index)
+      .map(({ lot }) => ({ id: lot.id, at: lot.at, granted: Math.max(0, lot.units), used: 0, slices: [] }))
+    const ordered = [...spends]
+      .map((spend, index) => ({ spend, index }))
+      .sort((a, b) => a.spend.at.getTime() - b.spend.at.getTime() || a.index - b.index)
+
+    let unallocated = 0
+    for (const { spend } of ordered) {
+      let left = Math.max(0, spend.units)
+      for (const lot of usage) {
+        if (left <= 0 || lot.at.getTime() > spend.at.getTime()) {
+          break
+        }
+        const take = Math.min(left, lot.granted - lot.used)
+        if (take > 0) {
+          lot.used += take
+          lot.slices.push({ at: spend.at, units: take })
+          left -= take
+        }
+      }
+      unallocated += left
+    }
+
+    return { lots: usage, unallocated }
+  }
+
+  const unitsUsedAfter = (lot: Pick<FifoLotUsage, 'slices'>, after: Date | null | undefined): number =>
+    after == null ? 0 : lot.slices
+      .filter(slice => slice.at.getTime() > after.getTime())
+      .reduce((sum, slice) => sum + slice.units, 0)
+
+  return { allocateFifo, unitsUsedAfter }
+}
+
+export const fifoHelper = createFifoHelper()

package/src/consumer/index.ts

@@ -0,0 +1,17 @@
+export * from './policy.js'
+export * from './consts.js'
+export type * from './types.js'
+export type * from './copy/types.js'
+export type * from './deadline/types.js'
+export type * from './fifo/types.js'
+export type * from './policy/types.js'
+export type * from './refund/types.js'
+export type * from './revive/types.js'
+export * from './deadline.js'
+export * from './refund.js'
+export * from './fifo.js'
+export * from './cancel.js'
+export * from './copy.js'
+export * from './refusal.js'
+export * from './revive.js'
+export * from './protocols.js'

package/src/consumer/policy/types.ts

@@ -0,0 +1,20 @@
+import type { ConsumerRightsLinks, ConsumerRightsPolicy } from '../../types.js'
+
+/** The consumer-rights policy's invariants, its languages and its links. */
+export interface ConsumerRightsPolicyHelper {
+  /**
+   * @throws ConsumerRightsError (`policy:<field>`) when the text version is empty, a country or a
+   * currency is malformed, the period is shorter than 14 days, the margin is outside 0..7 days, the
+   * consent context is not a lowercase key, the default language has no links, a link is not an
+   * absolute https URL, or the withdrawal information is missing while the withdrawal function or the
+   * performance consent is on.
+   */
+  assertConsumerRightsPolicy: (policy: ConsumerRightsPolicy) => ConsumerRightsPolicy
+  /** `de-DE` → `de`. */
+  baseLanguageOf: (lng: string | null | undefined) => string
+  /**
+   * The links of one language, field by field over the default language's — a language that only
+   * translates the Billing Terms still points at the default withdrawal information.
+   */
+  linksOf: (policy: Pick<ConsumerRightsPolicy, 'links' | 'defaultLanguage'>, lng?: string | null) => ConsumerRightsLinks
+}

package/src/consumer/policy.ts

@@ -0,0 +1,101 @@
+import { ConsumerRightsError } from '../errors.js'
+import type { ConsumerRightsLinks, ConsumerRightsPolicy } from '../types.js'
+import { CONSENT_CONTEXT, COUNTRY, CURRENCY } from './consts.local.js'
+import { DEFAULT_CONSUMER_RIGHTS } from './consts.js'
+import type { ConsumerRightsDeclaration } from './types.js'
+import type { ConsumerRightsPolicyHelper } from './policy/types.js'
+
+/**
+ * A declaration filled with `DEFAULT_CONSUMER_RIGHTS` and asserted. Only the policy's own fields are
+ * copied — anything else on `def` (a server's mail options) never reaches the advertised record.
+ */
+export const makeConsumerRightsPolicy = (def: ConsumerRightsDeclaration): ConsumerRightsPolicy => {
+  const defaults = DEFAULT_CONSUMER_RIGHTS
+  const present = <K extends string, V>(key: K, value: V | undefined): { [P in K]?: V } =>
+    (value == null ? {} : { [key]: value }) as { [P in K]?: V }
+
+  return consumerRightsPolicyHelper.assertConsumerRightsPolicy({
+    textVersion: def.textVersion,
+    countries: [...(def.countries ?? defaults.countries)].map(country => country.toUpperCase()),
+    unknownCountry: def.unknownCountry ?? defaults.unknownCountry,
+    withdrawalDays: def.withdrawalDays ?? defaults.withdrawalDays,
+    deadline: { ...defaults.deadline, ...def.deadline },
+    mechanisms: { ...defaults.mechanisms, ...def.mechanisms },
+    ...present('currencies', def.currencies),
+    ...present('languages', def.languages),
+    defaultLanguage: def.defaultLanguage ?? defaults.defaultLanguage,
+    links: def.links,
+    ...present('renewalOpensWindow', def.renewalOpensWindow ?? defaults.renewalOpensWindow),
+    ...present('startRequestTtlSeconds', def.startRequestTtlSeconds ?? defaults.startRequestTtlSeconds),
+    ...present('exemptBusinesses', def.exemptBusinesses ?? defaults.exemptBusinesses),
+    ...present('consentContext', def.consentContext),
+  })
+}
+
+export const createConsumerRightsPolicyHelper = (): ConsumerRightsPolicyHelper => {
+  const isHttpsUrl = (value: unknown): boolean => {
+    if (typeof value !== 'string') {
+      return false
+    }
+    try {
+      return new URL(value).protocol === 'https:'
+    } catch {
+      return false
+    }
+  }
+
+  const fail = (field: string): never => {
+    throw new ConsumerRightsError(`policy:${field}`)
+  }
+
+  const assertConsumerRightsPolicy = (policy: ConsumerRightsPolicy): ConsumerRightsPolicy => {
+    if (typeof policy.textVersion !== 'string' || policy.textVersion.trim() === '') fail('text-version')
+    if (policy.mechanisms == null || typeof policy.mechanisms !== 'object') fail('mechanisms')
+    if (!Array.isArray(policy.countries) || policy.countries.some(country => !COUNTRY.test(country))) fail('countries')
+    if (policy.unknownCountry !== 'protect' && policy.unknownCountry !== 'ignore') fail('unknown-country')
+    if (!Number.isSafeInteger(policy.withdrawalDays) || policy.withdrawalDays < 14) fail('withdrawal-days')
+    const margin = policy.deadline?.marginDays ?? -1
+    if (!Number.isSafeInteger(margin) || margin < 0 || margin > 7) fail('margin-days')
+    if (Object.values(policy.currencies ?? {}).some(currency => !CURRENCY.test(currency ?? ''))) fail('currencies')
+    if (policy.startRequestTtlSeconds != null
+      && (!Number.isSafeInteger(policy.startRequestTtlSeconds) || policy.startRequestTtlSeconds < 1)) fail('start-request-ttl')
+    if (policy.consentContext != null && !CONSENT_CONTEXT.test(policy.consentContext)) fail('consent-context')
+
+    const defaults = policy.links?.[policy.defaultLanguage]
+    if (defaults == null || !isHttpsUrl(defaults.billingTerms)) fail('links')
+    for (const [lng, links] of Object.entries(policy.links)) {
+      if (Object.values(links).some(url => url != null && !isHttpsUrl(url))) fail(`links:${lng}`)
+    }
+    if ((policy.mechanisms.withdrawal || policy.mechanisms.performanceConsent) && defaults!.withdrawalInformation == null) {
+      fail('links:withdrawal-information')
+    }
+
+    return policy
+  }
+
+  const baseLanguageOf = (lng: string | null | undefined): string =>
+    (lng ?? '').trim().split(/[-_]/)[0].toLowerCase()
+
+  const linksOf = (policy: Pick<ConsumerRightsPolicy, 'links' | 'defaultLanguage'>, lng?: string | null): ConsumerRightsLinks => {
+    const fallback = policy.links[policy.defaultLanguage]
+    const own = lng != null ? policy.links[lng] ?? policy.links[baseLanguageOf(lng)] : undefined
+
+    return { ...fallback, ...Object.fromEntries(Object.entries(own ?? {}).filter(([, url]) => url != null)) } as ConsumerRightsLinks
+  }
+
+  return { assertConsumerRightsPolicy, baseLanguageOf, linksOf }
+}
+
+export const consumerRightsPolicyHelper = createConsumerRightsPolicyHelper()
+
+/** @deprecated compat:factory-refactor — use `consumerRightsPolicyHelper.assertConsumerRightsPolicy(…)` */
+export const assertConsumerRightsPolicy = (policy: ConsumerRightsPolicy): ConsumerRightsPolicy =>
+  consumerRightsPolicyHelper.assertConsumerRightsPolicy(policy)
+
+/** @deprecated compat:factory-refactor — use `consumerRightsPolicyHelper.baseLanguageOf(…)` */
+export const baseLanguageOf = (lng: string | null | undefined): string => consumerRightsPolicyHelper.baseLanguageOf(lng)
+
+/** @deprecated compat:factory-refactor — use `consumerRightsPolicyHelper.linksOf(…)` */
+export const linksOf = (
+  policy: Pick<ConsumerRightsPolicy, 'links' | 'defaultLanguage'>, lng?: string | null,
+): ConsumerRightsLinks => consumerRightsPolicyHelper.linksOf(policy, lng)

package/src/consumer/protocols.ts

@@ -0,0 +1,116 @@
+import { contract, openProtocol, protocol, typed, type EntrypointProtocol, type OpenRequest, type OpenValue } from '@owlmeans/entrypoint'
+import { backend, frontend, route, RouteMethod } from '@owlmeans/route'
+import {
+  BillingProfileViewSchema, CancellationBodySchema, CancellationReceiptSchema, ConsumerRightsPublicViewSchema,
+  DeclarationReceiptSchema, PerformanceConsentBodySchema, PerformanceConsentResponseSchema,
+  PerformanceConsentViewSchema, PurchaseListSchema, SubscriptionStartBodySchema, SubscriptionStartQuerySchema,
+  SubscriptionStartResponseSchema, SubscriptionStartViewSchema, WithdrawalBodySchema,
+  WithdrawalCandidateListSchema, WithdrawalReceiptSchema,
+} from '../model/consumer.js'
+import type { SubscriptionStartQuery } from '../types.js'
+import { CONSUMER_RIGHTS_API_PATH, CONSUMER_RIGHTS_CANCELLATION_SCREEN_PATH, CONSUMER_RIGHTS_PUBLIC_PATH, CONSUMER_RIGHTS_WITHDRAWAL_SCREEN_PATH } from './consts.js'
+import type { ConsumerRightsAccountProtocols, ConsumerRightsProtocolOptions, ConsumerRightsProtocols, ConsumerRightsPublicProtocols, ConsumerRightsScreens } from './types.js'
+
+
+const get = (alias: string, path: string, parent: EntrypointProtocol<OpenRequest, OpenValue>) =>
+  route(alias, path, backend({ parent, method: RouteMethod.GET }))
+
+const post = (alias: string, path: string, parent: EntrypointProtocol<OpenRequest, OpenValue>) =>
+  route(alias, path, backend({ parent, method: RouteMethod.POST }))
+
+/**
+ * The standard consumer-rights protocol tree, the way `makeMarketingConsentProtocols` builds
+ * its own:
+ *
+ * - `base` under the application's guarded `parent` (its account base, whose guards and gate
+ *   every route inherits) with `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`;
+ * - with `public`, an UNGUARDED `public` subtree — `policy` GET `/policy`, `withdraw` POST
+ *   `/withdrawal`, `cancel` POST `/cancellation` — like `paymentGate.webhook`, plus optional
+ *   sticky frontend `screens`.
+ *
+ * Aliases are `<prefix>:<name>` (`<prefix>:public:<name>` below `public`). A tree with neither a
+ * parent nor guards is a declaration error: the account routes act on the caller's own records.
+ * Absent parts are left out of the tree rather than set to `undefined`, so `protocols(tree)` and
+ * `mapProtocols(tree, …)` walk it as is.
+ */
+export const makeConsumerRightsProtocols = <O extends ConsumerRightsProtocolOptions>(opts: O): ConsumerRightsProtocols<O> => {
+  if (opts.parent == null && opts.guards == null) {
+    throw new SyntaxError('consumer-rights: the account routes need either a parent or explicit guards')
+  }
+  const alias = (name: string): string => `${opts.prefix}:${name}`
+  const path = opts.path ?? CONSUMER_RIGHTS_API_PATH
+
+  const base = opts.parent != null
+    ? openProtocol(route(alias('base'), path, backend({ parent: opts.parent })))
+    : openProtocol(route(alias('base'), path, backend()), {
+        guards: opts.guards,
+        ...(opts.gate != null ? { gate: opts.gate } : {}),
+      })
+
+  const account: ConsumerRightsAccountProtocols = {
+    base,
+    profile: protocol(get(alias('profile'), '/profile', base), contract(BillingProfileViewSchema)),
+    purchases: protocol(get(alias('purchases'), '/purchases', base), contract(PurchaseListSchema)),
+    consent: protocol(get(alias('consent'), '/consent', base), contract(PerformanceConsentViewSchema)),
+    giveConsent: protocol(
+      post(alias('consent:give'), '/consent', base),
+      contract(PerformanceConsentBodySchema, PerformanceConsentResponseSchema),
+    ),
+    start: protocol(
+      get(alias('start'), '/start', base),
+      contract.request({ query: typed<SubscriptionStartQuery>(SubscriptionStartQuerySchema) }, SubscriptionStartViewSchema),
+    ),
+    requestStart: protocol(
+      post(alias('start:request'), '/start', base),
+      contract(SubscriptionStartBodySchema, SubscriptionStartResponseSchema),
+    ),
+    withdrawals: protocol(get(alias('withdrawals'), '/withdrawal', base), contract(WithdrawalCandidateListSchema)),
+    withdraw: protocol(
+      post(alias('withdraw'), '/withdrawal', base),
+      contract(WithdrawalBodySchema, WithdrawalReceiptSchema),
+    ),
+    cancel: protocol(
+      post(alias('cancel'), '/cancellation', base),
+      contract(CancellationBodySchema, CancellationReceiptSchema),
+    ),
+  }
+  if (opts.public == null || opts.public === false) {
+    return account as ConsumerRightsProtocols<O>
+  }
+
+  const pub = opts.public
+  const publicAlias = (name: string): string => alias(`public:${name}`)
+  const publicBase = openProtocol(route(
+    publicAlias('base'), pub.path ?? CONSUMER_RIGHTS_PUBLIC_PATH, backend(pub.parent != null ? { parent: pub.parent } : null),
+  ))
+  const publicTree: ConsumerRightsPublicProtocols = {
+    base: publicBase,
+    policy: protocol(get(publicAlias('policy'), '/policy', publicBase), contract(ConsumerRightsPublicViewSchema)),
+    withdraw: protocol(
+      post(publicAlias('withdraw'), '/withdrawal', publicBase),
+      contract(WithdrawalBodySchema, DeclarationReceiptSchema),
+    ),
+    cancel: protocol(
+      post(publicAlias('cancel'), '/cancellation', publicBase),
+      contract(CancellationBodySchema, DeclarationReceiptSchema),
+    ),
+  }
+  const screens = pub.screens == null ? {} : {
+    screens: {
+      // Top-level frontend screens, `sticky` so the router keeps them regardless of `cfg.service`
+      // filtering — the same shape as every other legal page.
+      withdrawal: openProtocol(route(
+        publicAlias('screen:withdrawal'), pub.screens.withdrawal ?? CONSUMER_RIGHTS_WITHDRAWAL_SCREEN_PATH,
+        frontend({ parent: pub.screens.parent }),
+      ), { sticky: true }),
+      cancellation: openProtocol(route(
+        publicAlias('screen:cancellation'), pub.screens.cancellation ?? CONSUMER_RIGHTS_CANCELLATION_SCREEN_PATH,
+        frontend({ parent: pub.screens.parent }),
+      ), { sticky: true }),
+    } satisfies ConsumerRightsScreens,
+  }
+
+  return { ...account, public: { ...publicTree, ...screens } } as unknown as ConsumerRightsProtocols<O>
+}

package/src/consumer/refund/types.ts

@@ -0,0 +1,27 @@
+import type { OneTimeRefund, OneTimeRefundInput, SubscriptionRefund, SubscriptionRefundInput } from '../types.js'
+
+/** The refund a withdrawal owes, computed in BigInt and rounded in the consumer's favour. */
+export interface WithdrawalRefundHelper {
+  /**
+   * Split `totalMinor` in proportion to `shares` by the largest remainder: every part is the floor
+   * of its exact share, and the units left over go one each to the largest fractional parts (the
+   * earlier part on a tie). The parts always sum to the total. All-zero shares split evenly.
+   */
+  splitByShares: (totalMinor: number, shares: number[]) => number[]
+  /**
+   * The refund of a one-time purchase (prepaid credits):
+   * `min(paid − refunded, ceil(paid × (granted − used) / granted))`. Nothing granted means nothing
+   * performed — the whole unrefunded amount. 1256 paid, 125 000 of 500 000 used → 942.
+   */
+  oneTimeWithdrawalRefund: (input: OneTimeRefundInput) => OneTimeRefund
+  /**
+   * The refund of a subscription's first invoice (CJEU C-641/19 PE Digital). The net price splits
+   * into its components by `shareMinor` (largest remainder). A `time` component loses
+   * `floor(c × elapsedDays / periodDays)`, the days counted from `max(periodStart,
+   * servicesRequestedAt)` and floored — and nothing without a start request. A `units` component
+   * loses `floor(c × used / granted)`. The gross refund is `ceil(paid × refundNet / net)`, capped at
+   * what is still unrefunded. Net 2000 / paid 2460, services 1000 at 3 of 30 days (−100), credits
+   * 1000 with 100 000 of 500 000 used (−200) → net 1700, gross 2091.
+   */
+  subscriptionWithdrawalRefund: (input: SubscriptionRefundInput) => SubscriptionRefund
+}