@owlmeans/payment 0.1.18-rc.9 → 0.1.18

package/tests/consumer-deadline.spec.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  cancellationEffectiveAt, ConsumerRightsError, DEFAULT_CONSUMER_RIGHTS, withdrawalDeadlineHelper,
+} from '../src/index.js'
+
+const at = (iso: string): Date => new Date(iso)
+
+describe('withdrawalDeadlineOf', () => {
+  test('the pinned examples: 14 days, weekend to Monday, five margin days, exclusive end of day', () => {
+    // Wed 2026-09-23 + 14 = Wed 10-07, + 5 margin = Mon 10-12 → ends at the start of 10-13.
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-23T10:15:00Z'))).toEqual(at('2026-10-13T00:00:00.000Z'))
+    // Sat 2026-09-26 + 14 = Sat 10-10 → Mon 10-12, + 5 = Sat 10-17 → ends at the start of 10-18.
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-26T08:00:00Z'))).toEqual(at('2026-10-18T00:00:00.000Z'))
+    // Sun 2026-12-20 + 14 = Sun 2027-01-03 → Mon 01-04, + 5 = Sat 01-09 → ends at the start of 01-10.
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-12-20T23:59:59Z'))).toEqual(at('2027-01-10T00:00:00.000Z'))
+  })
+
+  test('a deadline is shown as its last included day', () => {
+    expect(withdrawalDeadlineHelper.lastWithdrawalDayOf(at('2026-10-13T00:00:00.000Z'))).toEqual(at('2026-10-12T00:00:00.000Z'))
+    expect(withdrawalDeadlineHelper.lastWithdrawalDayOf(at('2027-01-10T00:00:00.000Z'))).toEqual(at('2027-01-09T00:00:00.000Z'))
+    expect(withdrawalDeadlineHelper.lastWithdrawalDayOf(at('2026-10-13T00:00:00.001Z'))).toEqual(at('2026-10-13T00:00:00.000Z'))
+  })
+
+  test('the purchase day is a UTC day, whatever the hour', () => {
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-23T00:00:00Z'))).toEqual(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-23T23:59:59.999Z')))
+  })
+
+  test('a leap day counts', () => {
+    // Tue 2028-02-15 + 14 = Tue 02-29, + 1 = 03-01 → ends at the start of 03-02.
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2028-02-15T12:00:00Z'), { marginDays: 1 })).toEqual(at('2028-03-02T00:00:00.000Z'))
+  })
+
+  test('margin 0 and no rollover', () => {
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-23T12:00:00Z'), { marginDays: 0 })).toEqual(at('2026-10-08T00:00:00.000Z'))
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-26T12:00:00Z'), { marginDays: 0, weekendRollover: false }))
+      .toEqual(at('2026-10-11T00:00:00.000Z'))
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-26T12:00:00Z'), { marginDays: 0 })).toEqual(at('2026-10-13T00:00:00.000Z'))
+  })
+
+  test('reads a policy directly', () => {
+    // Wed 2026-09-23 + 30 = Fri 10-23, + 5 = Wed 10-28 → ends at the start of 10-29.
+    expect(withdrawalDeadlineHelper.withdrawalDeadlineOf(at('2026-09-23T10:00:00Z'), { ...DEFAULT_CONSUMER_RIGHTS, withdrawalDays: 30 }))
+      .toEqual(at('2026-10-29T00:00:00.000Z'))
+  })
+
+  test('refuses an invalid date', () => {
+    expect(() => withdrawalDeadlineHelper.withdrawalDeadlineOf(new Date('nope'))).toThrow(ConsumerRightsError)
+  })
+})
+
+describe('withdrawalOpen', () => {
+  const deadline = at('2026-10-09T00:00:00.000Z')
+
+  test('open strictly before the deadline, never after a withdrawal or a refund', () => {
+    expect(withdrawalDeadlineHelper.withdrawalOpen({ deadline }, at('2026-10-08T23:59:59.999Z'))).toBe(true)
+    expect(withdrawalDeadlineHelper.withdrawalOpen({ deadline }, deadline)).toBe(false)
+    expect(withdrawalDeadlineHelper.withdrawalOpen(deadline, at('2026-10-01T00:00:00Z'))).toBe(true)
+    expect(withdrawalDeadlineHelper.withdrawalOpen({ deadline, withdrawnAt: at('2026-10-01T00:00:00Z') }, at('2026-10-02T00:00:00Z'))).toBe(false)
+    expect(withdrawalDeadlineHelper.withdrawalOpen({ deadline, refundedAt: at('2026-10-01T00:00:00Z') }, at('2026-10-02T00:00:00Z'))).toBe(false)
+    expect(withdrawalDeadlineHelper.withdrawalOpen({}, at('2026-10-02T00:00:00Z'))).toBe(false)
+    expect(withdrawalDeadlineHelper.withdrawalOpen(null)).toBe(false)
+  })
+})
+
+describe('cancellationEffectiveAt', () => {
+  const periodEnd = at('2026-10-31T10:00:00.000Z')
+
+  test('no date, or one inside the current period, ends at the period end', () => {
+    expect(cancellationEffectiveAt(periodEnd, 'month')).toEqual(periodEnd)
+    expect(cancellationEffectiveAt(periodEnd, 'month', at('2026-10-15T00:00:00Z'))).toEqual(periodEnd)
+    expect(cancellationEffectiveAt(periodEnd, 'month', periodEnd)).toEqual(periodEnd)
+  })
+
+  test('a later date ends at the first boundary on or after it, the 31st clamped per month', () => {
+    expect(cancellationEffectiveAt(periodEnd, 'month', at('2026-11-15T00:00:00Z'))).toEqual(at('2026-11-30T10:00:00.000Z'))
+    expect(cancellationEffectiveAt(periodEnd, 'month', at('2026-12-01T00:00:00Z'))).toEqual(at('2026-12-31T10:00:00.000Z'))
+    expect(cancellationEffectiveAt(periodEnd, 'month', at('2027-02-10T00:00:00Z'))).toEqual(at('2027-02-28T10:00:00.000Z'))
+    expect(cancellationEffectiveAt(periodEnd, 'month', at('2027-03-01T00:00:00Z'))).toEqual(at('2027-03-31T10:00:00.000Z'))
+    expect(cancellationEffectiveAt(periodEnd, 'year', at('2027-01-01T00:00:00Z'))).toEqual(at('2027-10-31T10:00:00.000Z'))
+  })
+
+  test('refuses an invalid date', () => {
+    expect(() => cancellationEffectiveAt(periodEnd, 'month', new Date('x'))).toThrow(ConsumerRightsError)
+  })
+})

package/tests/consumer-fifo.spec.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test'
+import { fifoHelper } from '../src/index.js'
+
+const t = (hour: number): Date => new Date(Date.UTC(2026, 8, 23, hour))
+
+describe('allocateFifo', () => {
+  test('a spend takes the oldest lot first and spills into the next', () => {
+    const { lots, unallocated } = fifoHelper.allocateFifo(
+      [{ id: 'b', units: 100, at: t(3) }, { id: 'a', units: 100, at: t(1) }],
+      [{ units: 80, at: t(4) }, { units: 50, at: t(2) }],
+    )
+    expect(lots.map(lot => lot.id)).toEqual(['a', 'b'])
+    expect(lots[0]).toMatchObject({ granted: 100, used: 100, slices: [{ at: t(2), units: 50 }, { at: t(4), units: 50 }] })
+    expect(lots[1]).toMatchObject({ granted: 100, used: 30, slices: [{ at: t(4), units: 30 }] })
+    expect(unallocated).toBe(0)
+  })
+
+  test('a lot granted after a spend never pays for it', () => {
+    const { lots, unallocated } = fifoHelper.allocateFifo([{ id: 'late', units: 100, at: t(5) }], [{ units: 40, at: t(4) }])
+    expect(lots[0].used).toBe(0)
+    expect(unallocated).toBe(40)
+  })
+
+  test('a spend at the grant instant takes from the lot', () => {
+    expect(fifoHelper.allocateFifo([{ id: 'a', units: 10, at: t(1) }], [{ units: 4, at: t(1) }]).lots[0].used).toBe(4)
+  })
+
+  test('overflow beyond every lot is unallocated', () => {
+    const { lots, unallocated } = fifoHelper.allocateFifo(
+      [{ id: 'a', units: 100, at: t(1) }, { id: 'b', units: 100, at: t(2) }],
+      [{ units: 250, at: t(3) }],
+    )
+    expect(lots.map(lot => lot.used)).toEqual([100, 100])
+    expect(unallocated).toBe(50)
+  })
+
+  test('leaves its inputs untouched', () => {
+    const lots = [{ id: 'b', units: 1, at: t(2) }, { id: 'a', units: 1, at: t(1) }]
+    const spends = [{ units: 1, at: t(3) }]
+    fifoHelper.allocateFifo(lots, spends)
+    expect(lots.map(lot => lot.id)).toEqual(['b', 'a'])
+  })
+})
+
+describe('unitsUsedAfter', () => {
+  const { lots } = fifoHelper.allocateFifo(
+    [{ id: 'a', units: 100, at: t(1) }],
+    [{ units: 10, at: t(2) }, { units: 20, at: t(3) }, { units: 30, at: t(4) }],
+  )
+
+  test('counts only the slices strictly after the consent', () => {
+    expect(fifoHelper.unitsUsedAfter(lots[0], t(1))).toBe(60)
+    expect(fifoHelper.unitsUsedAfter(lots[0], t(3))).toBe(30)
+    expect(fifoHelper.unitsUsedAfter(lots[0], t(4))).toBe(0)
+  })
+
+  test('without a consent nothing is deductible', () => {
+    expect(fifoHelper.unitsUsedAfter(lots[0], null)).toBe(0)
+    expect(fifoHelper.unitsUsedAfter(lots[0], undefined)).toBe(0)
+  })
+})

package/tests/consumer-protocols.spec.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test'
+import { AppType } from '@owlmeans/context'
+import { contract, gatesOf, protocol, protocols } from '@owlmeans/entrypoint'
+import type { EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { makeCheckoutReadProtocols, makeConsumerRightsProtocols } from '../src/index.js'
+
+const accountBase = protocol(route('spec:account:base', '/account', backend()), contract(), {
+  guards: 'spec-guard',
+  gate: { alias: 'spec-gate', params: 'spec-account-{entity}' },
+})
+
+const shape = (declaration: EntrypointProtocolDeclaration) => ({
+  alias: declaration.alias,
+  path: declaration.route.route.path,
+  method: declaration.route.route.method,
+  parent: declaration.route.route.parent,
+})
+
+describe('makeConsumerRightsProtocols', () => {
+  const tree = makeConsumerRightsProtocols({ prefix: 'spec:consumer', parent: accountBase })
+
+  test('the account subtree hangs under the guarded parent', () => {
+    expect(shape(tree.base)).toMatchObject({ alias: 'spec:consumer:base', path: '/consumer-rights', parent: accountBase.alias })
+    expect(tree.base.guards).toEqual([])
+    expect(gatesOf(tree.giveConsent, { accountBase, ...tree })).toEqual([{ alias: 'spec-gate', params: ['spec-account-{entity}'] }])
+    expect([
+      shape(tree.profile), shape(tree.purchases), shape(tree.consent), shape(tree.giveConsent), shape(tree.start),
+      shape(tree.requestStart), shape(tree.withdrawals), shape(tree.withdraw), shape(tree.cancel),
+    ]).toEqual([
+      { alias: 'spec:consumer:profile', path: '/profile', method: RouteMethod.GET, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:purchases', path: '/purchases', method: RouteMethod.GET, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:consent', path: '/consent', method: RouteMethod.GET, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:consent:give', path: '/consent', method: RouteMethod.POST, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:start', path: '/start', method: RouteMethod.GET, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:start:request', path: '/start', method: RouteMethod.POST, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:withdrawals', path: '/withdrawal', method: RouteMethod.GET, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:withdraw', path: '/withdrawal', method: RouteMethod.POST, parent: 'spec:consumer:base' },
+      { alias: 'spec:consumer:cancel', path: '/cancellation', method: RouteMethod.POST, parent: 'spec:consumer:base' },
+    ])
+  })
+
+  test('without public options there is no public key at all, so the tree flattens cleanly', () => {
+    expect('public' in tree).toBe(false)
+    expect(protocols(tree)).toHaveLength(10)
+    expect(Object.values(tree).every(value => value != null)).toBe(true)
+  })
+
+  test('declares the request and response schemas', () => {
+    expect(tree.start.contract?.requestSchemas.query).toMatchObject({ required: ['planSku'] })
+    expect(tree.giveConsent.contract?.requestSchemas.body).toMatchObject({ required: ['purchaseIds', 'textVersion', 'language', 'acknowledged'] })
+    expect(tree.withdraw.contract?.responseSchemas?.default).toMatchObject({ required: expect.arrayContaining(['status']) })
+  })
+
+  test('the public subtree has no guard and no gate, and its receipts disclose nothing', () => {
+    const open = makeConsumerRightsProtocols({ prefix: 'spec:consumer', parent: accountBase, public: {} })
+    expect(shape(open.public.base)).toMatchObject({ alias: 'spec:consumer:public:base', path: '/public/consumer-rights' })
+    expect(open.public.base.route.route.parent).toBeUndefined()
+    expect([open.public.policy, open.public.withdraw, open.public.cancel].map(shape)).toEqual([
+      { alias: 'spec:consumer:public:policy', path: '/policy', method: RouteMethod.GET, parent: 'spec:consumer:public:base' },
+      { alias: 'spec:consumer:public:withdraw', path: '/withdrawal', method: RouteMethod.POST, parent: 'spec:consumer:public:base' },
+      { alias: 'spec:consumer:public:cancel', path: '/cancellation', method: RouteMethod.POST, parent: 'spec:consumer:public:base' },
+    ])
+    for (const declaration of protocols(open.public)) {
+      expect(declaration.guards).toEqual([])
+      expect(gatesOf(declaration, open.public)).toEqual([])
+    }
+    expect(open.public.withdraw.contract?.responseSchemas?.default?.properties).not.toHaveProperty('status')
+    expect('screens' in open.public).toBe(false)
+    expect(protocols(open)).toHaveLength(14)
+  })
+
+  test('the public screens are sticky frontend routes', () => {
+    const open = makeConsumerRightsProtocols({
+      prefix: 'spec:consumer', parent: accountBase, public: { path: '/legal-api', screens: { cancellation: '/cancel' } },
+    })
+    expect(open.public.base.route.route.path).toBe('/legal-api')
+    expect(open.public.screens.cancellation).toMatchObject({ alias: 'spec:consumer:public:screen:cancellation', sticky: true })
+    expect(open.public.screens.cancellation.route.route).toMatchObject({ path: '/cancel', type: AppType.Frontend })
+    expect(open.public.screens.withdrawal.route.route).toMatchObject({ path: '/legal/withdraw', type: AppType.Frontend })
+    expect(protocols(open)).toHaveLength(16)
+  })
+
+  test('a tree with neither a parent nor guards is a declaration error; guards alone mount it', () => {
+    expect(() => makeConsumerRightsProtocols({ prefix: 'spec:bare' })).toThrow(SyntaxError)
+    const guarded = makeConsumerRightsProtocols({ prefix: 'spec:bare', guards: 'spec-guard', path: '/rights' })
+    expect(guarded.base.guards).toEqual(['spec-guard'])
+    expect(guarded.base.route.route).toMatchObject({ path: '/rights', type: AppType.Backend })
+  })
+})
+
+describe('makeCheckoutReadProtocols', () => {
+  test('amount policy and plan prices under the guarded parent, with query schemas', () => {
+    const tree = makeCheckoutReadProtocols({ prefix: 'spec:checkout', parent: accountBase })
+    expect([tree.base, tree.amountPolicy, tree.planPrices].map(shape)).toEqual([
+      { alias: 'spec:checkout:base', path: '/checkout', method: undefined, parent: accountBase.alias },
+      { alias: 'spec:checkout:amount-policy', path: '/amount-policy', method: RouteMethod.GET, parent: 'spec:checkout:base' },
+      { alias: 'spec:checkout:plan-prices', path: '/plan-prices', method: RouteMethod.GET, parent: 'spec:checkout:base' },
+    ])
+    expect(tree.amountPolicy.contract?.requestSchemas.query).toMatchObject({ required: ['productSku'] })
+    expect(() => makeCheckoutReadProtocols({ prefix: 'spec:checkout' })).toThrow(SyntaxError)
+  })
+})

package/tests/consumer-refund.spec.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'bun:test'
+import { ConsumerRightsError, withdrawalRefundHelper } from '../src/index.js'
+import type { PlanWithdrawalComponent } from '../src/index.js'
+
+const DAY = 86_400_000
+const periodStart = new Date('2026-09-01T00:00:00.000Z')
+const periodEnd = new Date(periodStart.getTime() + 30 * DAY)
+
+const components: PlanWithdrawalComponent[] = [
+  { key: 'services', basis: 'time', shareMinor: 1000 },
+  { key: 'credits', basis: 'units', shareMinor: 1000 },
+]
+
+describe('splitByShares', () => {
+  test('parts are floors of the exact share, the rest to the largest remainders, earlier first on a tie', () => {
+    expect(withdrawalRefundHelper.splitByShares(2000, [1000, 1000])).toEqual([1000, 1000])
+    expect(withdrawalRefundHelper.splitByShares(1001, [1, 1])).toEqual([501, 500])
+    expect(withdrawalRefundHelper.splitByShares(10, [1, 1, 1])).toEqual([4, 3, 3])
+    expect(withdrawalRefundHelper.splitByShares(100, [1, 2])).toEqual([33, 67])
+    expect(withdrawalRefundHelper.splitByShares(100, [0, 0])).toEqual([50, 50])
+    expect(withdrawalRefundHelper.splitByShares(0, [3, 7])).toEqual([0, 0])
+    expect(withdrawalRefundHelper.splitByShares(5, [])).toEqual([])
+  })
+
+  test('always sums to the total', () => {
+    for (const [total, shares] of [[997, [3, 5, 7]], [12345, [1, 1, 1, 1, 1, 1, 1]], [1, [2, 2, 2]]] as Array<[number, number[]]>) {
+      expect(withdrawalRefundHelper.splitByShares(total, shares).reduce((a, b) => a + b, 0)).toBe(total)
+    }
+  })
+
+  test('refuses a negative or fractional amount', () => {
+    expect(() => withdrawalRefundHelper.splitByShares(-1, [1])).toThrow(ConsumerRightsError)
+    expect(() => withdrawalRefundHelper.splitByShares(1.5, [1])).toThrow(ConsumerRightsError)
+  })
+})
+
+describe('oneTimeWithdrawalRefund', () => {
+  test('the pinned example: 1256 paid, 125k of 500k used → 942', () => {
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 1256, unitsGranted: 500_000, unitsUsed: 125_000 }))
+      .toEqual({ refundMinor: 942, netRatio: 0.75, unitsReturned: 375_000 })
+  })
+
+  test('a refund rounds up, a fraction of a used unit rounds down', () => {
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 1000, unitsGranted: 3, unitsUsed: 1 }).refundMinor).toBe(667)
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 1000, unitsGranted: 3, unitsUsed: 1.9 }).refundMinor).toBe(667)
+  })
+
+  test('nothing used returns everything; everything used returns nothing', () => {
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 2550, unitsGranted: 2500, unitsUsed: 0 }).refundMinor).toBe(2550)
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 2550, unitsGranted: 2500, unitsUsed: 9_999 }))
+      .toEqual({ refundMinor: 0, netRatio: 0, unitsReturned: 0 })
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 2550, unitsGranted: 0, unitsUsed: 0 }).refundMinor).toBe(2550)
+  })
+
+  test('never refunds more than what is still unrefunded', () => {
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 1000, refundedMinor: 500, unitsGranted: 3, unitsUsed: 1 }).refundMinor).toBe(500)
+    expect(withdrawalRefundHelper.oneTimeWithdrawalRefund({ paidMinor: 1000, refundedMinor: 1200, unitsGranted: 3, unitsUsed: 0 }).refundMinor).toBe(0)
+  })
+})
+
+describe('subscriptionWithdrawalRefund (PE Digital)', () => {
+  test('the pinned example: services 3 of 30 days, credits 100k of 500k → net 1700, gross 2091', () => {
+    const result = withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 2460, netMinor: 2000, components, periodStart, periodEnd,
+      servicesRequestedAt: periodStart, withdrawnAt: new Date(periodStart.getTime() + 3 * DAY + 3_600_000),
+      units: { granted: 500_000, used: 100_000 },
+    })
+    expect(result).toMatchObject({
+      refundMinor: 2091, refundNetMinor: 1700, timeDeductionMinor: 100, unitsDeductionMinor: 200,
+      elapsedDays: 3, periodDays: 30, unitsUsed: 100_000, unitsGranted: 500_000,
+    })
+    expect(result.components.map(component => component.deductionMinor)).toEqual([100, 200])
+  })
+
+  test('no start request means no time deduction at all', () => {
+    const result = withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 2460, netMinor: 2000, components, periodStart, periodEnd,
+      withdrawnAt: new Date(periodStart.getTime() + 10 * DAY), units: { granted: 500_000, used: 100_000 },
+    })
+    expect(result.timeDeductionMinor).toBe(0)
+    expect(result.elapsedDays).toBe(0)
+    expect(result.refundNetMinor).toBe(1800)
+    expect(result.refundMinor).toBe(2214)
+  })
+
+  test('days count from the later of the period start and the start request, floored', () => {
+    const result = withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 2000, netMinor: 2000, components, periodStart, periodEnd,
+      servicesRequestedAt: new Date(periodStart.getTime() + 2 * DAY),
+      withdrawnAt: new Date(periodStart.getTime() + 3 * DAY - 1),
+      units: { granted: 500_000, used: 0 },
+    })
+    expect(result.elapsedDays).toBe(0)
+    expect(result.refundMinor).toBe(2000)
+  })
+
+  test('deductions round down, the gross refund rounds up', () => {
+    const result = withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 1230, netMinor: 1000, components: [{ key: 'services', basis: 'time', shareMinor: 1000 }],
+      periodStart, periodEnd, servicesRequestedAt: periodStart, withdrawnAt: new Date(periodStart.getTime() + DAY),
+    })
+    // floor(1000 / 30) = 33 → net 967 → ceil(1230 × 967 / 1000) = ceil(1189.41) = 1190
+    expect(result.timeDeductionMinor).toBe(33)
+    expect(result.refundMinor).toBe(1190)
+  })
+
+  test('without declared components the whole price is time; a unit component without units deducts nothing', () => {
+    const whole = withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 3000, netMinor: 3000, periodStart, periodEnd,
+      servicesRequestedAt: periodStart, withdrawnAt: new Date(periodStart.getTime() + 15 * DAY),
+    })
+    expect(whole.components).toEqual([{ key: 'price', basis: 'time', shareMinor: 3000, amountMinor: 3000, deductionMinor: 1500 }])
+    expect(whole.refundMinor).toBe(1500)
+
+    const noUnits = withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 2000, netMinor: 2000, components, periodStart, periodEnd, withdrawnAt: periodEnd,
+    })
+    expect(noUnits.unitsDeductionMinor).toBe(0)
+    expect(noUnits.refundMinor).toBe(2000)
+  })
+
+  test('shares that do not sum to the net split it by largest remainder', () => {
+    const result = withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 1001, netMinor: 1001, components, periodStart, periodEnd, withdrawnAt: periodStart,
+    })
+    expect(result.components.map(component => component.amountMinor)).toEqual([501, 500])
+  })
+
+  test('caps at what is still unrefunded', () => {
+    expect(withdrawalRefundHelper.subscriptionWithdrawalRefund({
+      paidMinor: 2460, refundedMinor: 2000, netMinor: 2000, components, periodStart, periodEnd, withdrawnAt: periodStart,
+    }).refundMinor).toBe(460)
+  })
+})

package/tests/consumer-regions.spec.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import {
+  CONSUMER_RIGHTS_TERRITORIES, ConsumerRegion, ConsumerRightsError, ConsumerRightsPolicySchema,
+  COUNTRY_LANGUAGES, DEFAULT_CONSUMER_RIGHTS, EEA_EXTRA, EU_CONSUMER_TERRITORIES, EU_COUNTRIES,
+  makeConsumerRightsPolicy, consumerRegionHelper, consumerRightsPolicyHelper,
+} from '../src/index.js'
+import type { ConsumerRightsPolicy } from '../src/index.js'
+
+const ajv = new Ajv({ strict: false, validateFormats: false })
+
+const links = {
+  en: {
+    billingTerms: 'https://example.com/en/billing-terms',
+    withdrawalInformation: 'https://example.com/en/withdrawal',
+    withdrawalFunction: 'https://app.example.com/legal/withdraw',
+  },
+  de: { billingTerms: 'https://example.com/de/abrechnungsbedingungen' },
+}
+
+const policy = (patch: Partial<ConsumerRightsPolicy> = {}): ConsumerRightsPolicy =>
+  makeConsumerRightsPolicy({ textVersion: '2026-09-23', links, ...patch })
+
+describe('territories', () => {
+  test('the EU has 27 member states, Greece as GR', () => {
+    expect(EU_COUNTRIES).toHaveLength(27)
+    expect(new Set(EU_COUNTRIES).size).toBe(27)
+    expect(EU_COUNTRIES).toContain('GR')
+    expect(EU_COUNTRIES).not.toContain('EL')
+    expect(EU_COUNTRIES).not.toContain('GB')
+  })
+
+  test('consumer territories add Åland and the French outermost regions; the EEA adds IS, LI, NO', () => {
+    expect(EU_CONSUMER_TERRITORIES.filter(code => !EU_COUNTRIES.includes(code)).sort())
+      .toEqual(['AX', 'GF', 'GP', 'MF', 'MQ', 'RE', 'YT'])
+    expect(EEA_EXTRA).toEqual(['IS', 'LI', 'NO'])
+    expect(CONSUMER_RIGHTS_TERRITORIES).toHaveLength(27 + 7 + 3)
+    expect(DEFAULT_CONSUMER_RIGHTS.countries).toEqual([...CONSUMER_RIGHTS_TERRITORIES])
+  })
+
+  test('membership predicates are case-insensitive and exclude territories', () => {
+    expect(consumerRegionHelper.isEuCountry('pl')).toBe(true)
+    expect(consumerRegionHelper.isEuCountry('GF')).toBe(false)
+    expect(consumerRegionHelper.isEuCountry('NO')).toBe(false)
+    expect(consumerRegionHelper.isEeaCountry('NO')).toBe(true)
+    expect(consumerRegionHelper.isEeaCountry('CH')).toBe(false)
+    expect(consumerRegionHelper.isEuCountry(null)).toBe(false)
+  })
+})
+
+describe('region, scope and currency', () => {
+  test('a territory country is in the EU region; outside it is other; unknown is null', () => {
+    expect(consumerRegionHelper.regionOf('DE')).toBe(ConsumerRegion.Eu)
+    expect(consumerRegionHelper.regionOf('re')).toBe(ConsumerRegion.Eu)
+    expect(consumerRegionHelper.regionOf('NO')).toBe(ConsumerRegion.Eu)
+    expect(consumerRegionHelper.regionOf('US')).toBe(ConsumerRegion.Other)
+    expect(consumerRegionHelper.regionOf('GB')).toBe(ConsumerRegion.Other)
+    expect(consumerRegionHelper.regionOf(undefined)).toBeNull()
+    expect(consumerRegionHelper.regionOf(' ')).toBeNull()
+    expect(consumerRegionHelper.regionOf('US', { countries: ['US'] })).toBe(ConsumerRegion.Eu)
+  })
+
+  test('an unknown country is protected by default and can be ignored', () => {
+    expect(consumerRegionHelper.inScope(null, 'FR', policy())).toBe(true)
+    expect(consumerRegionHelper.inScope(null, 'US', policy())).toBe(false)
+    expect(consumerRegionHelper.inScope(null, null, policy())).toBe(true)
+    expect(consumerRegionHelper.inScope(null, null, policy({ unknownCountry: 'ignore' }))).toBe(false)
+    expect(consumerRegionHelper.inScope(ConsumerRegion.Other, null, policy())).toBe(false)
+    expect(consumerRegionHelper.inScope(null, null, null)).toBe(true)
+  })
+
+  test('the charge currency follows the region; an unknown region reads as EU', () => {
+    const declared = policy({ currencies: { eu: 'eur', other: 'usd' } })
+    expect(consumerRegionHelper.chargeCurrencyOf(ConsumerRegion.Eu, declared, 'usd')).toBe('eur')
+    expect(consumerRegionHelper.chargeCurrencyOf(ConsumerRegion.Other, declared, 'eur')).toBe('usd')
+    expect(consumerRegionHelper.chargeCurrencyOf(null, declared, 'usd')).toBe('eur')
+    expect(consumerRegionHelper.chargeCurrencyOf(ConsumerRegion.Other, policy(), 'USD')).toBe('usd')
+    expect(consumerRegionHelper.chargeCurrencyOf(ConsumerRegion.Eu, null, 'eur')).toBe('eur')
+  })
+
+  test('the legal language: policy map, then the unambiguous map, then the fallbacks', () => {
+    expect(COUNTRY_LANGUAGES).not.toHaveProperty('BE')
+    expect(COUNTRY_LANGUAGES).not.toHaveProperty('LU')
+    expect(COUNTRY_LANGUAGES).not.toHaveProperty('CH')
+    expect(consumerRegionHelper.billingLanguageOf('AT')).toBe('de')
+    expect(consumerRegionHelper.billingLanguageOf('gp')).toBe('fr')
+    expect(consumerRegionHelper.billingLanguageOf('BE', policy())).toBe('en')
+    expect(consumerRegionHelper.billingLanguageOf('BE', policy(), 'fr')).toBe('fr')
+    expect(consumerRegionHelper.billingLanguageOf('LU', policy({ languages: { LU: 'fr' } }))).toBe('fr')
+    expect(consumerRegionHelper.billingLanguageOf('PL', policy({ languages: { PL: 'en' } }))).toBe('en')
+    expect(consumerRegionHelper.billingLanguageOf(null, policy({ defaultLanguage: 'de', links: { ...links, de: links.de } }))).toBe('de')
+  })
+})
+
+describe('the policy declaration', () => {
+  test('fills the defaults and validates as a record', () => {
+    const declared = policy({ mechanisms: { withdrawal: true } } as Partial<ConsumerRightsPolicy>)
+    expect(declared).toMatchObject({
+      withdrawalDays: 14, unknownCountry: 'protect', defaultLanguage: 'en',
+      deadline: { weekendRollover: true, marginDays: 5 },
+    })
+    expect(declared.mechanisms.withdrawal).toBe(true)
+    expect(declared.mechanisms.checkoutTerms).toBe(false)
+    expect(ajv.validate(ConsumerRightsPolicySchema, declared)).toBe(true)
+  })
+
+  test('copies only its own fields — a server option never reaches the advertised record', () => {
+    const declared = makeConsumerRightsPolicy({
+      textVersion: 'v1', links, mail: { from: 'billing@example.com', bcc: ['archive@example.com'] },
+    } as Parameters<typeof makeConsumerRightsPolicy>[0])
+    expect(declared).not.toHaveProperty('mail')
+    expect(ajv.validate(ConsumerRightsPolicySchema, declared)).toBe(true)
+  })
+
+  test('rejects what the law or the wire cannot take', () => {
+    const cases: Array<[Partial<ConsumerRightsPolicy>, string]> = [
+      [{ textVersion: ' ' }, 'text-version'],
+      [{ withdrawalDays: 13 }, 'withdrawal-days'],
+      [{ deadline: { weekendRollover: true, marginDays: 8 } }, 'margin-days'],
+      [{ countries: ['Poland'] }, 'countries'],
+      [{ currencies: { eu: 'EURO' } }, 'currencies'],
+      [{ links: { de: links.de } }, 'links'],
+      [{ links: { en: { billingTerms: 'http://example.com/terms' } } }, 'links'],
+      [{ links: { ...links, de: { billingTerms: 'ftp://x' } } }, 'links:de'],
+      [{ links: { en: { billingTerms: links.en.billingTerms } }, mechanisms: { performanceConsent: true } as ConsumerRightsPolicy['mechanisms'] }, 'links:withdrawal-information'],
+    ]
+    for (const [patch, field] of cases) {
+      expect(() => policy(patch)).toThrow(`payment:consumer-rights:policy:${field}`)
+      expect(() => policy(patch)).toThrow(ConsumerRightsError)
+    }
+  })
+
+  test('links of a language fall back field by field to the default language', () => {
+    const declared = policy()
+    expect(consumerRightsPolicyHelper.linksOf(declared, 'de')).toEqual({ ...links.en, billingTerms: links.de.billingTerms })
+    expect(consumerRightsPolicyHelper.linksOf(declared, 'de-AT').billingTerms).toBe(links.de.billingTerms)
+    expect(consumerRightsPolicyHelper.linksOf(declared, 'fr')).toEqual(links.en)
+    expect(consumerRightsPolicyHelper.linksOf(declared)).toEqual(links.en)
+  })
+})