@owlmeans/payment 0.1.18-rc.8 → 0.1.18

package/tests/consumer-wire.spec.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import {
+  BillingProfileViewSchema, CancellationBodySchema, CancellationReceiptSchema, ConsumerRegion,
+  ConsumerRightsError, ConsumerRightsPolicySchema, CreateCheckoutBodySchema,
+  makeConsumerRightsPolicy, PerformanceConsentBodySchema, PerformanceConsentViewSchema,
+  PlanPriceListSchema, PlanStatus, PlanDuration, PriceEstimateSchema, ProductPlanSchema,
+  PurchaseKind, SubscriptionStartViewSchema, TaxBehavior, TaxEstimateStatus, WithdrawalBodySchema,
+  WithdrawalCandidateListSchema, WithdrawalStatus, WithdrawalReceiptSchema, CancellationKind,
+  CancellationStatus, consumerReviveHelper,
+} from '../src/index.js'
+import type {
+  PerformanceConsentView, PurchaseView, SubscriptionStartView, WithdrawalCandidateList,
+} from '../src/index.js'
+
+const ajv = new Ajv({ strict: false, validateFormats: false })
+const wire = <T>(value: T): unknown => JSON.parse(JSON.stringify(value))
+
+const links = { billingTerms: 'https://example.com/terms', withdrawalInformation: 'https://example.com/withdrawal' }
+const purchase: PurchaseView = {
+  purchaseId: 'stripe:cs_test_1', contractRef: 'CR-260923-ABC123', kind: PurchaseKind.TopUp,
+  purchasedAt: new Date('2026-09-23T10:00:00.000Z'), deadline: new Date('2026-10-09T00:00:00.000Z'),
+  productSku: 'credits-product', amountTotalMinor: 3075, currency: 'eur', withdrawable: true,
+}
+
+describe('consumer-rights wire shapes', () => {
+  test('a consent view crosses as ISO strings and revives', () => {
+    const view: PerformanceConsentView = {
+      required: true, region: ConsumerRegion.Eu, country: 'PL', language: 'pl', trader: 'Trader Ltd',
+      textVersion: '2026-09-23', copyVersion: '2026-09-23', links, purchases: [purchase],
+      deadline: purchase.deadline, at: new Date('2026-09-24T08:00:00.000Z'),
+    }
+    const sent = wire(view) as PerformanceConsentView
+    expect(ajv.validate(PerformanceConsentViewSchema, sent)).toBe(true)
+    expect(typeof sent.at).toBe('string')
+    const revived = consumerReviveHelper.reviveConsentView(sent)
+    expect(revived.at).toEqual(view.at)
+    expect(revived.purchases[0].purchasedAt).toEqual(purchase.purchasedAt)
+    expect(revived.purchases[0].deadline).toEqual(purchase.deadline)
+    expect(consumerReviveHelper.reviveConsentView(revived)).toEqual(revived)
+  })
+
+  test('a consent view carries the copy variant it is rendered with', () => {
+    const view: PerformanceConsentView = {
+      required: true, region: ConsumerRegion.Eu, country: 'DE', language: 'de', trader: 'Trader Ltd',
+      context: 'included', textVersion: '2026-09-23', copyVersion: '2026-09-23', links, purchases: [purchase],
+      at: new Date('2026-09-24T08:00:00.000Z'),
+    }
+    const sent = wire(view) as PerformanceConsentView
+    expect(ajv.validate(PerformanceConsentViewSchema, sent)).toBe(true)
+    expect(consumerReviveHelper.reviveConsentView(sent).context).toBe('included')
+    expect(ajv.validate(PerformanceConsentViewSchema, { ...sent, context: 'Included' })).toBe(false)
+    expect(ajv.validate(PerformanceConsentViewSchema, { ...sent, context: '' })).toBe(false)
+  })
+
+  test('a policy declares a consent context: carried, validated, a malformed one refused', () => {
+    const declared = makeConsumerRightsPolicy({ textVersion: 'v1', links: { en: links }, consentContext: 'included' })
+    expect(declared.consentContext).toBe('included')
+    expect(ajv.validate(ConsumerRightsPolicySchema, wire(declared))).toBe(true)
+    expect(ajv.validate(ConsumerRightsPolicySchema, { ...declared, consentContext: 'in cluded' })).toBe(false)
+    expect(makeConsumerRightsPolicy({ textVersion: 'v1', links: { en: links } })).not.toHaveProperty('consentContext')
+    for (const consentContext of ['Included', '_included', 'in cluded', '']) {
+      const declare = () => makeConsumerRightsPolicy({ textVersion: 'v1', links: { en: links }, consentContext })
+      expect(declare).toThrow(ConsumerRightsError)
+      expect(declare).toThrow('payment:consumer-rights:policy:consent-context')
+    }
+  })
+
+  test('a consent body must acknowledge', () => {
+    const body = { purchaseIds: ['stripe:cs_test_1'], textVersion: '2026-09-23', language: 'de', acknowledged: true }
+    expect(ajv.validate(PerformanceConsentBodySchema, body)).toBe(true)
+    expect(ajv.validate(PerformanceConsentBodySchema, { ...body, acknowledged: false })).toBe(false)
+    expect(ajv.validate(PerformanceConsentBodySchema, { ...body, uiLanguage: 'en' })).toBe(true)
+    expect(ajv.validate(PerformanceConsentBodySchema, { ...body, language: 'German' })).toBe(false)
+  })
+
+  test('a withdrawal or cancellation asks only for name, contract and e-mail, plus a honeypot', () => {
+    expect(ajv.validate(WithdrawalBodySchema, { contractRef: 'CR-260923-ABC123', name: 'Anna', email: 'anna@example.eu' })).toBe(true)
+    expect(ajv.validate(WithdrawalBodySchema, { name: 'Anna', email: 'anna@example.eu', honeypot: '' })).toBe(true)
+    expect(ajv.validate(WithdrawalBodySchema, { name: 'Anna', email: 'not-an-address' })).toBe(false)
+    expect(ajv.validate(WithdrawalBodySchema, { name: 'Anna', email: 'anna@example.eu', address: 'x' })).toBe(false)
+    const cancel = { kind: CancellationKind.Ordinary, name: 'Anna', effective: 'date', date: '2026-12-31', email: 'anna@example.eu' }
+    expect(ajv.validate(CancellationBodySchema, cancel)).toBe(true)
+    expect(ajv.validate(CancellationBodySchema, { ...cancel, date: '31.12.2026' })).toBe(false)
+  })
+
+  test('receipts and candidate lists revive their dates', () => {
+    const receipt = {
+      declarationId: 'decl-1', receivedAt: new Date('2026-09-25T09:30:00.000Z'), content: { name: 'Anna' }, mailed: true,
+      status: WithdrawalStatus.Refunded, refundMinor: 3075, currency: 'eur',
+    }
+    expect(ajv.validate(WithdrawalReceiptSchema, wire(receipt))).toBe(true)
+    expect(consumerReviveHelper.reviveReceipt(wire(receipt) as typeof receipt).receivedAt).toEqual(receipt.receivedAt)
+    const cancellation = { ...receipt, status: CancellationStatus.Scheduled, effectiveAt: new Date('2026-10-31T00:00:00.000Z') }
+    delete (cancellation as Partial<typeof cancellation>).refundMinor
+    delete (cancellation as Partial<typeof cancellation>).currency
+    expect(ajv.validate(CancellationReceiptSchema, wire(cancellation))).toBe(true)
+    expect(consumerReviveHelper.reviveReceipt(wire(cancellation) as typeof cancellation).effectiveAt).toEqual(cancellation.effectiveAt)
+
+    const list: WithdrawalCandidateList = {
+      candidates: [{
+        purchaseId: purchase.purchaseId, contractRef: purchase.contractRef, kind: purchase.kind,
+        purchasedAt: purchase.purchasedAt, deadline: purchase.deadline!, amountTotalMinor: 3075, currency: 'eur',
+        estimate: { refundMinor: 3075, currency: 'eur', timeDeductionMinor: 0, unitsDeductionMinor: 0 }, automatic: true,
+      }],
+      language: 'de', links,
+    }
+    expect(ajv.validate(WithdrawalCandidateListSchema, wire(list))).toBe(true)
+    expect(consumerReviveHelper.reviveWithdrawalList(wire(list) as WithdrawalCandidateList).candidates[0].deadline).toEqual(purchase.deadline!)
+  })
+
+  test('profile, start view and plan prices', () => {
+    expect(ajv.validate(BillingProfileViewSchema, {
+      country: null, region: null, currency: null, locked: false, language: 'en', inScope: true,
+    })).toBe(true)
+    expect(ajv.validate(SubscriptionStartViewSchema, {
+      required: true, planSku: 'pro-monthly', language: 'fr', trader: 'Trader Ltd', textVersion: 'v1',
+      copyVersion: 'v1', links, region: ConsumerRegion.Eu,
+    })).toBe(true)
+    expect(ajv.validate(PlanPriceListSchema, { prices: [
+      { planSku: 'pro-monthly', currency: 'eur', unitAmountMinor: 1709, default: true, taxBehavior: TaxBehavior.Exclusive, interval: 'month' },
+      { planSku: 'pro-monthly', currency: 'usd', unitAmountMinor: 2000, default: false },
+    ] })).toBe(true)
+  })
+
+  test('a start view carries the copy variant of its plan; a malformed one is refused', () => {
+    const view: SubscriptionStartView = {
+      required: true, planSku: 'pro-split', language: 'pl', trader: 'Trader Ltd', context: 'units', textVersion: 'v1',
+      copyVersion: 'v1', links, region: ConsumerRegion.Eu,
+    }
+    expect(ajv.validate(SubscriptionStartViewSchema, wire(view))).toBe(true)
+    expect((wire(view) as SubscriptionStartView).context).toBe('units')
+    for (const context of ['Units', '', '_units', 'un its']) {
+      expect([context, ajv.validate(SubscriptionStartViewSchema, { ...view, context })]).toEqual([context, false])
+    }
+  })
+})
+
+describe('extended catalogue and checkout shapes', () => {
+  test('a checkout body carries the declared country and the start request', () => {
+    expect(ajv.validate(CreateCheckoutBodySchema, {
+      productSku: 'pro-product', planSku: 'pro-monthly', entitySlug: 'acme', service: 'manager', country: 'PL',
+      startRequestId: 'start-1',
+    })).toBe(true)
+    expect(ajv.validate(CreateCheckoutBodySchema, {
+      productSku: 'pro-product', entitySlug: 'acme', service: 'manager', country: 'pl',
+    })).toBe(false)
+  })
+
+  test('an estimate may come from the locked profile', () => {
+    expect(ajv.validate(PriceEstimateSchema, {
+      country: 'PL', source: 'profile', locked: true, region: ConsumerRegion.Eu, currency: 'eur',
+      behavior: TaxBehavior.Exclusive,
+      tax: { status: TaxEstimateStatus.Taxed, subtotalMinor: 100, taxMinor: 23, totalMinor: 123, scalable: true, rates: [] },
+    })).toBe(true)
+  })
+
+  test('a plan declares its withdrawal components', () => {
+    const plan = {
+      productSku: 'pro-product', sku: 'pro-monthly', status: PlanStatus.Active, duration: PlanDuration.Monthly,
+      price: 20, title: 'Pro',
+      withdrawal: { components: [
+        { key: 'services', basis: 'time', shareMinor: 1000 }, { key: 'credits', basis: 'units', shareMinor: 1000 },
+      ] },
+    }
+    expect(ajv.validate(ProductPlanSchema, plan)).toBe(true)
+    expect(ajv.validate(ProductPlanSchema, { ...plan, withdrawal: { components: [{ key: 'x', basis: 'days', shareMinor: 1 }] } })).toBe(false)
+    expect(ajv.validate(ProductPlanSchema, { ...plan, withdrawal: { components: [] } })).toBe(false)
+  })
+})

package/tests/contract.spec.ts

@@ -0,0 +1,183 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import {
+  COUNTRY_CURRENCIES, CreateCheckoutBodySchema, DEFAULT_PRICING_POLICY, EntitlementViewSchema,
+  LimitKind, LimitWindow, PlanDuration, PlanStatus, PortalFlow, PortalLinkBodySchema,
+  PriceEstimateBodySchema, PriceEstimateSchema, PricingPolicySchema, ProductPlanSchema,
+  SubscriptionStatus, TaxBehavior, TaxEstimateStatus, TaxType, ENTITLING_STATUSES, TERMINAL_STATUSES,
+  entitlementViewHelper,
+} from '../src/index.js'
+import * as payment from '../src/index.js'
+import type { PriceEstimate, ProductPlan } from '../src/index.js'
+
+const ajv = new Ajv({ strict: false, validateFormats: false })
+
+const plan: ProductPlan = {
+  productSku: 'pro-product', sku: 'pro-monthly', status: PlanStatus.Active,
+  duration: PlanDuration.Monthly, price: 20, title: 'Pro', rank: 10, gateways: ['stripe'],
+  capabilities: [{
+    scope: 'feature', permissions: { whitelabel: true },
+    promo: { until: new Date('2026-10-01T00:00:00.000Z'), grandfather: true },
+  }],
+  limits: {
+    seats: { kind: LimitKind.Occupancy, limit: 3 },
+    exports: { kind: LimitKind.Window, window: LimitWindow.Month, limit: 10, unit: 'file' },
+  },
+}
+
+describe('statuses', () => {
+  test('past-due still entitles; the terminal set does not overlap it', () => {
+    expect(ENTITLING_STATUSES).toEqual([SubscriptionStatus.Active, SubscriptionStatus.Trial, SubscriptionStatus.PastDue])
+    expect(TERMINAL_STATUSES.some(status => ENTITLING_STATUSES.includes(status))).toBe(false)
+    expect(Object.isFrozen(ENTITLING_STATUSES)).toBe(true)
+  })
+
+  test('a free tier is a plan and a one-time purchase a fulfillment, never a subscription status', () => {
+    expect(Object.values(SubscriptionStatus)).not.toContain('free')
+    expect(Object.values(SubscriptionStatus)).not.toContain('consumable')
+  })
+})
+
+describe('plan declarations', () => {
+  const validate = ajv.compile(ProductPlanSchema)
+
+  test('accept rank, free, gateways, promos and limit declarations', () => {
+    expect(validate(plan)).toBe(true)
+    expect(validate({ ...plan, free: true, price: 0, gateways: [], rank: 0 })).toBe(true)
+  })
+
+  test('status is a PLAN status, not a subscription status', () => {
+    expect(validate({ ...plan, status: PlanStatus.Hidden })).toBe(true)
+    expect(validate({ ...plan, status: SubscriptionStatus.Trial })).toBe(false)
+  })
+
+  test('reject an unknown limit kind', () => {
+    expect(validate({ ...plan, limits: { seats: { kind: 'forever', limit: 1 } } })).toBe(false)
+  })
+
+  test('reject paygate alias maps and the misspelled suspension date', () => {
+    expect(validate({ ...plan, suspendedAt: new Date() })).toBe(true)
+    expect(validate({ ...plan, payagateAliases: { stripe: 'price_1' } })).toBe(false)
+    expect(validate({ ...plan, supsendedAt: new Date() })).toBe(false)
+  })
+})
+
+describe('wire shapes', () => {
+  test('the entitlement view schema accepts a full view as the wire carries it', () => {
+    const view = entitlementViewHelper.entitlementViewOf(plan, {
+      sku: plan.sku, productSku: plan.productSku, title: plan.title, rank: 10, free: false,
+      status: SubscriptionStatus.PastDue, paygate: 'stripe', subscriptionId: 'sub_1', pastDue: true,
+      subscribedAt: new Date('2026-09-01T00:00:00.000Z'), periodEnd: new Date('2026-10-01T00:00:00.000Z'),
+      fallbackSku: 'free-plan',
+    }, [{ key: 'seats', window: 'occupancy', used: 1 }], new Date('2026-10-15T00:00:00.000Z'))
+    const validate = ajv.compile(EntitlementViewSchema)
+
+    expect(validate(JSON.parse(JSON.stringify(view)))).toBe(true)
+    expect(validate({ ...JSON.parse(JSON.stringify(view)), entityId: 'internal' })).toBe(false)
+  })
+
+  test('a portal link body names a flow', () => {
+    const validate = ajv.compile(PortalLinkBodySchema)
+    expect(validate({ flow: PortalFlow.Change, planSku: 'pro-monthly', returnUrl: 'https://app.test/billing' })).toBe(true)
+    expect(validate({ flow: 'refund' })).toBe(false)
+    expect(validate({ flow: PortalFlow.Manage, entityId: 'internal' })).toBe(false)
+  })
+
+  test('a checkout body takes a plan sku and never an entity id', () => {
+    const validate = ajv.compile(CreateCheckoutBodySchema)
+    const body = { productSku: 'pro-product', planSku: 'pro-monthly', entitySlug: 'acme', service: 'app' }
+    expect(validate(body)).toBe(true)
+    expect(validate({ ...body, entitySlug: undefined, entityId: 'internal' })).toBe(false)
+    expect(validate({ ...body, planSku: undefined, sku: 'pro-monthly' })).toBe(false)
+  })
+
+  test('an amount checkout body takes integer minor units only', () => {
+    const validate = ajv.compile(CreateCheckoutBodySchema)
+    const body = { productSku: 'credit-pack', entitySlug: 'acme', service: 'app' }
+    expect(validate({ ...body, amountMinor: 500 })).toBe(true)
+    expect(validate({ ...body, amountMinor: 500.5 })).toBe(false)
+  })
+})
+
+describe('country currencies', () => {
+  test('every key is an uppercase alpha-2 code and every value a lowercase alpha-3 currency', () => {
+    for (const [country, currency] of Object.entries(COUNTRY_CURRENCIES)) {
+      expect(country).toMatch(/^[A-Z]{2}$/)
+      expect(currency).toMatch(/^[a-z]{3}$/)
+    }
+  })
+
+  test('keys are unique and the reference points hold', () => {
+    const keys = Object.keys(COUNTRY_CURRENCIES)
+    expect(new Set(keys).size).toBe(keys.length)
+    expect(COUNTRY_CURRENCIES.PL).toBe('pln')
+    expect(COUNTRY_CURRENCIES.DE).toBe('eur')
+    expect(COUNTRY_CURRENCIES.US).toBe('usd')
+  })
+})
+
+describe('pricing policy and price estimate schemas', () => {
+  const validatePolicy = ajv.compile(PricingPolicySchema)
+  const validateBody = ajv.compile(PriceEstimateBodySchema)
+  const validateEstimate = ajv.compile(PriceEstimateSchema)
+
+  test('the default policy round-trips through its own schema', () => {
+    expect(validatePolicy(JSON.parse(JSON.stringify(DEFAULT_PRICING_POLICY)))).toBe(true)
+  })
+
+  test('the policy carries no Stripe-specific field (api version, migration switch)', () => {
+    for (const forbidden of ['fxApiVersion', 'migrateUnspecifiedPrices', 'stripe']) {
+      expect(validatePolicy({ ...DEFAULT_PRICING_POLICY, [forbidden]: 'x' })).toBe(false)
+    }
+  })
+
+  test('a price estimate body accepts an empty body, a plan and a country, never an entity id', () => {
+    expect(validateBody({})).toBe(true)
+    expect(validateBody({ planSku: 'vib-pro-monthly' })).toBe(true)
+    expect(validateBody({ country: 'PL' })).toBe(true)
+    expect(validateBody({ country: 'pl' })).toBe(false)
+    expect(validateBody({ country: 'POL' })).toBe(false)
+    expect(validateBody({ entityId: 'internal' })).toBe(false)
+  })
+
+  test('a price estimate survives a JSON round trip and rejects an extra property', () => {
+    const estimate: PriceEstimate = {
+      country: 'PL', source: 'request', currency: 'usd', behavior: TaxBehavior.Exclusive,
+      tax: {
+        status: TaxEstimateStatus.Taxed, subtotalMinor: 1_021, taxMinor: 235, totalMinor: 1_256,
+        scalable: true, rates: [{ type: TaxType.Vat, percentage: '23', ratePpm: 230_000, country: 'PL' }],
+      },
+      local: { currency: 'pln', exchangeRate: 0.25, fxFeeRate: 0.02 },
+    }
+    expect(validateEstimate(JSON.parse(JSON.stringify(estimate)))).toBe(true)
+    expect(validateEstimate({ ...JSON.parse(JSON.stringify(estimate)), extra: true })).toBe(false)
+  })
+})
+
+describe('package surface', () => {
+  test('declares no protocols: an application declares its own checkout and portal protocols', () => {
+    for (const name of ['paymentApi', 'entrypoints', 'serviceEntrypoints']) {
+      expect(payment).not.toHaveProperty(name)
+    }
+  })
+
+  test('carries no subscription record, propagation body or legacy limit schemas', () => {
+    for (const name of [
+      'PlanSubscriptionSchema', 'SubscriptionPropagateBodySchema', 'SubscriptionPropogateBodySchema',
+      'LimitConfigSchema', 'CapabilityUsageSchema',
+    ]) {
+      expect(payment).not.toHaveProperty(name)
+    }
+  })
+})
+
+describe('webhook signature refusal', () => {
+  test('a missing or unverifiable signature is a client error, still a PaygateError', async () => {
+    const { PaygateError, PaygateSignatureError } = await import('../src/errors.js')
+    const error = new PaygateSignatureError()
+    expect(error).toBeInstanceOf(PaygateError)
+    expect(error.message).toContain('signature')
+    expect((error.constructor as unknown as { httpStatus: number }).httpStatus).toBe(400)
+    expect((PaygateError as unknown as { httpStatus?: number }).httpStatus).toBeUndefined()
+  })
+})

package/tests/entitlement.spec.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect } from 'bun:test'
+import { entitlementParamHelper } from '../src/entitlement.js'
+import { CAPABILITY_FEATURE_SCOPE, CAPABILITY_LIMIT_SCOPE, ENTITLEMENT_GATE, LIMIT_GATE } from '../src/consts.js'
+import type { PermissionSet } from '@owlmeans/auth'
+
+const pro: PermissionSet[] = [
+  { scope: 'renewable', permissions: { production: 1, credits: 5000 } },
+  { scope: CAPABILITY_FEATURE_SCOPE, permissions: { 'branding--whitelabel': true, 'domain--custom': true } },
+]
+
+describe('the parameter grammar', () => {
+  test('a bare permission has no scope and no floor', () => {
+    expect(entitlementParamHelper.parseEntitlementParam('domain--custom')).toEqual({ permission: 'domain--custom' })
+  })
+
+  test('a scope is everything before the first colon', () => {
+    expect(entitlementParamHelper.parseEntitlementParam('feature:branding--whitelabel'))
+      .toEqual({ scope: 'feature', permission: 'branding--whitelabel' })
+  })
+
+  test('a floor is parsed as a number', () => {
+    expect(entitlementParamHelper.parseEntitlementParam('renewable:credits>=100'))
+      .toEqual({ scope: 'renewable', permission: 'credits', atLeast: 100 })
+  })
+
+  test('formatting round-trips', () => {
+    for (const param of ['domain--custom', 'feature:branding--whitelabel', 'renewable:credits>=100']) {
+      expect(entitlementParamHelper.formatEntitlementParam(entitlementParamHelper.parseEntitlementParam(param))).toBe(param)
+    }
+  })
+})
+
+describe('the predicate', () => {
+  test('a held feature passes', () => {
+    expect(entitlementParamHelper.hasEntitlement(pro, 'feature:branding--whitelabel')).toBe(true)
+  })
+
+  test('a feature nobody granted does not', () => {
+    expect(entitlementParamHelper.hasEntitlement(pro, 'feature:branding--nonexistent')).toBe(false)
+  })
+
+  test('a scope that does not match is not consulted', () => {
+    expect(entitlementParamHelper.hasEntitlement(pro, 'renewable:branding--whitelabel')).toBe(false)
+    // …and without a scope, any set may answer.
+    expect(entitlementParamHelper.hasEntitlement(pro, 'branding--whitelabel')).toBe(true)
+  })
+
+  test('a numeric floor compares', () => {
+    expect(entitlementParamHelper.hasEntitlement(pro, 'renewable:credits>=5000')).toBe(true)
+    expect(entitlementParamHelper.hasEntitlement(pro, 'renewable:credits>=5001')).toBe(false)
+  })
+
+  test('a boolean cannot satisfy a numeric floor', () => {
+    expect(entitlementParamHelper.hasEntitlement(pro, 'feature:branding--whitelabel>=1')).toBe(false)
+  })
+
+  test('an explicit false is not a grant', () => {
+    expect(entitlementParamHelper.hasEntitlement([{ scope: 'feature', permissions: { x: false } }], 'feature:x')).toBe(false)
+    expect(entitlementParamHelper.hasEntitlement([{ scope: 'feature', permissions: { x: null } }], 'feature:x')).toBe(false)
+  })
+
+  test('no capabilities at all is a refusal, never a pass', () => {
+    expect(entitlementParamHelper.hasEntitlement(undefined, 'feature:branding--whitelabel')).toBe(false)
+    expect(entitlementParamHelper.hasEntitlement([], 'feature:branding--whitelabel')).toBe(false)
+  })
+
+  test('a malformed parameter refuses rather than throwing', () => {
+    // A gate that crashed on a typo would take down the endpoint it guards.
+    expect(() => entitlementParamHelper.hasEntitlement(pro, '')).not.toThrow()
+    expect(entitlementParamHelper.hasEntitlement(pro, '')).toBe(false)
+    expect(entitlementParamHelper.hasEntitlement(pro, 'feature:')).toBe(false)
+    expect(entitlementParamHelper.hasEntitlement(pro, 'renewable:credits>=abc')).toBe(true)
+  })
+})
+
+describe('limits are not capabilities', () => {
+  test('a limit parameter never passes the capability predicate', () => {
+    // Even a set that (wrongly) carries the reserved scope cannot answer a limit requirement.
+    const misdeclared = [...pro, { scope: CAPABILITY_LIMIT_SCOPE, permissions: { seats: 5 } }]
+    expect(entitlementParamHelper.hasEntitlement(pro, 'limit:seats')).toBe(false)
+    expect(entitlementParamHelper.hasEntitlement(misdeclared, 'limit:seats')).toBe(false)
+    expect(entitlementParamHelper.hasEntitlement(misdeclared, 'limit:seats>=1')).toBe(false)
+  })
+
+  test('the two gates are distinct aliases', () => {
+    expect(ENTITLEMENT_GATE).toBe('entitlement-gate')
+    expect(LIMIT_GATE).toBe('limit-gate')
+  })
+})
+
+describe('listing', () => {
+  test('unions every granted capability, scoped', () => {
+    expect(entitlementParamHelper.entitlementList(pro).sort()).toEqual([
+      'feature:branding--whitelabel', 'feature:domain--custom',
+      'renewable:credits', 'renewable:production',
+    ])
+  })
+
+  test('skips what is not granted', () => {
+    expect(entitlementParamHelper.entitlementList([{ scope: 'feature', permissions: { a: true, b: false, c: null } }]))
+      .toEqual(['feature:a'])
+  })
+})

package/tests/errors.spec.ts

@@ -0,0 +1,168 @@
+import { describe, expect, test } from 'bun:test'
+import { AuthForbidden } from '@owlmeans/auth'
+import { ResilientError } from '@owlmeans/error'
+import { SUPPORTED_LNGS } from '@owlmeans/i18n'
+import * as payment from '../src/index.js'
+import {
+  BillingCountryLocked, CancellationUnavailable, CapabilityRequired, CheckoutLimitExceeded, ConsentKind,
+  consentRefusalOf, ConsumerRightsError, ConsumerRightsRefusal, EntitlementRefusal, LimitExhausted, LimitMisdeclared,
+  LimitUnknown, PerformanceConsentRequired, PlanRequired, PortalUnavailable, SubscriptionStartRequired,
+  WebhookSetupError, WithdrawalUnavailable, WithdrawalUnavailableReason,
+} from '../src/index.js'
+
+/** The canonical set plus French, which this package ships and registers too. */
+const LANGUAGES = [...SUPPORTED_LNGS, 'fr'] as const
+
+const roundTrip = <T extends ResilientError>(error: T): ResilientError =>
+  ResilientError.ensure(ResilientError.marshal(error))
+
+describe('refusals', () => {
+  test('are forbidden, so an HTTP boundary answers 403', () => {
+    expect(new CapabilityRequired('feature:whitelabel')).toBeInstanceOf(AuthForbidden)
+    expect(new LimitExhausted({ key: 'seats', used: 3, limit: 3 })).toBeInstanceOf(EntitlementRefusal)
+    expect(new LimitUnknown('seats')).not.toBeInstanceOf(AuthForbidden)
+  })
+
+  test('a capability refusal keeps its parameters across a marshal', () => {
+    const error = new CapabilityRequired(['feature:whitelabel', 'feature:custom-domain'])
+    expect(error.message).toContain('capability-required:feature:whitelabel|feature:custom-domain')
+
+    const back = roundTrip(error)
+    expect(back).toBeInstanceOf(CapabilityRequired)
+    expect(back.type).toBe(CapabilityRequired.typeName)
+    expect((back as CapabilityRequired).params).toEqual(['feature:whitelabel', 'feature:custom-domain'])
+  })
+
+  test('a limit refusal keeps its key, counts and reset across a marshal', () => {
+    const resetsAt = new Date('2026-10-01T00:00:00.000Z')
+    const error = new LimitExhausted({ key: 'seats', used: 3, limit: 3, resetsAt })
+    expect(error.message).toContain('limit-exhausted:seats:3/3:2026-10-01T00:00:00.000Z')
+
+    const back = roundTrip(error) as LimitExhausted
+    expect(back).toBeInstanceOf(LimitExhausted)
+    expect(back).toMatchObject({ limitKey: 'seats', used: 3, limit: 3, resetsAt })
+  })
+
+  test('a limit that never renews marshals without a reset', () => {
+    const back = roundTrip(new LimitExhausted({ key: 'imports', used: 1, limit: 1 })) as LimitExhausted
+    expect(back).toMatchObject({ limitKey: 'imports', used: 1, limit: 1 })
+    expect(back.resetsAt).toBeUndefined()
+    expect(roundTrip(new PortalUnavailable('customer'))).toBeInstanceOf(PortalUnavailable)
+  })
+})
+
+describe('declared HTTP status', () => {
+  const statusOf = (error: Error): unknown => (error.constructor as { httpStatus?: unknown }).httpStatus
+
+  test('a portal with nothing to act on is a conflict, and stays one across a marshal', () => {
+    expect(statusOf(new PortalUnavailable('subscription'))).toBe(409)
+    expect(statusOf(roundTrip(new PortalUnavailable('customer')))).toBe(409)
+  })
+
+  test('faults declare nothing, so an HTTP boundary answers 500', () => {
+    for (const error of [
+      new LimitUnknown('seats'), new LimitMisdeclared('seats'), new PlanRequired('x'), new WebhookSetupError('x'),
+    ]) {
+      expect(statusOf(error)).toBeUndefined()
+    }
+  })
+
+  test('refusals declare nothing either — they are AuthForbidden, which a boundary answers 403', () => {
+    expect(statusOf(new CapabilityRequired('feature:whitelabel'))).toBeUndefined()
+    expect(new LimitExhausted({ key: 'seats', used: 1, limit: 1 })).toBeInstanceOf(AuthForbidden)
+  })
+})
+
+const errorClasses = Object.values(payment as Record<string, unknown>).filter(
+  (value): value is { typeName: string } =>
+    typeof value === 'function' && value.prototype instanceof ResilientError,
+)
+
+describe('error messages', () => {
+  const load = async (lng: string): Promise<Record<string, string>> =>
+    (await import(`../src/i18n/errors/${lng}.json`, { with: { type: 'json' } })).default
+
+  test('every language carries the same non-empty keys', async () => {
+    const en = await load('en')
+    for (const lng of LANGUAGES) {
+      const messages = await load(lng)
+      expect(Object.keys(messages).sort()).toEqual(Object.keys(en).sort())
+      expect(Object.values(messages).every(message => message.trim() !== '')).toBe(true)
+    }
+  })
+
+  test('no message calls anything non-refundable', async () => {
+    for (const lng of LANGUAGES) {
+      const messages = Object.values(await load(lng)).join('\n')
+      expect(messages).not.toMatch(/non[-\s]?refundable|nicht\s+erstattungsf|non\s+rembours|bezzwrotn|no\s+reembolsable|невозвратн|неповоротн|незваротн/i)
+    }
+  })
+
+  test('every error type of the package has a message', async () => {
+    const en = await load('en')
+    expect(errorClasses.length).toBeGreaterThan(10)
+    for (const errorClass of errorClasses) {
+      expect(en).toHaveProperty([errorClass.typeName])
+    }
+  })
+})
+
+describe('consumer-rights refusals', () => {
+  const statusOf = (error: Error): unknown => (error.constructor as { httpStatus?: unknown }).httpStatus
+  const deadline = new Date('2026-10-09T00:00:00.000Z')
+  const resetsAt = new Date('2026-09-30T12:00:00.000Z')
+
+  test('declare 428 and 409 and are never forbidden; the fault declares nothing', () => {
+    expect(statusOf(new PerformanceConsentRequired({ pending: 1 }))).toBe(428)
+    expect(statusOf(new SubscriptionStartRequired('pro-monthly'))).toBe(428)
+    expect(statusOf(new BillingCountryLocked({ country: 'PL' }))).toBe(409)
+    expect(statusOf(new WithdrawalUnavailable(WithdrawalUnavailableReason.Expired))).toBe(409)
+    expect(statusOf(new CancellationUnavailable('no-subscription'))).toBe(409)
+    expect(statusOf(new CheckoutLimitExceeded({ reason: 'window', maximumMinor: 0, currency: 'usd' }))).toBe(409)
+    expect(statusOf(new ConsumerRightsError('policy:links'))).toBeUndefined()
+    for (const error of [
+      new PerformanceConsentRequired({ pending: 1 }), new SubscriptionStartRequired('x'), new BillingCountryLocked({ country: 'PL' }),
+      new WithdrawalUnavailable('expired'), new CancellationUnavailable('ended'),
+      new CheckoutLimitExceeded({ reason: 'x', maximumMinor: 1, currency: 'usd' }),
+    ]) {
+      expect(error).not.toBeInstanceOf(AuthForbidden)
+    }
+    expect(new PerformanceConsentRequired({ pending: 1 })).toBeInstanceOf(ConsumerRightsRefusal)
+    expect(new CheckoutLimitExceeded({ reason: 'x', maximumMinor: 1, currency: 'usd' })).not.toBeInstanceOf(ConsumerRightsError)
+  })
+
+  test('keep their fields across a marshal, with markers the wire can match', () => {
+    const consent = new PerformanceConsentRequired({ pending: 2, deadline })
+    expect(consent.message).toBe('payment:consumer-rights:performance-consent-required:2:2026-10-09T00:00:00.000Z')
+    const consentBack = roundTrip(consent) as PerformanceConsentRequired
+    expect(consentBack).toBeInstanceOf(PerformanceConsentRequired)
+    expect(consentBack).toMatchObject({ pending: 2, deadline })
+    expect(statusOf(consentBack)).toBe(428)
+    expect((roundTrip(new PerformanceConsentRequired({ pending: 1 })) as PerformanceConsentRequired).deadline).toBeUndefined()
+
+    const start = roundTrip(new SubscriptionStartRequired('pro:monthly/eu')) as SubscriptionStartRequired
+    expect(start.message).toBe('payment:consumer-rights:subscription-start-required:pro%3Amonthly%2Feu')
+    expect(start.planSku).toBe('pro:monthly/eu')
+
+    expect(roundTrip(new BillingCountryLocked({ country: 'PL', requested: 'DE' }))).toMatchObject({ country: 'PL', requested: 'DE' })
+    expect(roundTrip(new BillingCountryLocked({ country: 'PL' }))).toMatchObject({ country: 'PL', requested: undefined })
+    expect(roundTrip(new WithdrawalUnavailable('performed'))).toMatchObject({ reason: 'performed' })
+    expect(roundTrip(new CancellationUnavailable('no-subscription'))).toMatchObject({ reason: 'no-subscription' })
+
+    const limit = new CheckoutLimitExceeded({ reason: 'window:7d', maximumMinor: 2500, currency: 'USD', resetsAt })
+    expect(limit.message).toBe('payment:checkout-limit-exceeded:window%3A7d:2500:usd:2026-09-30T12:00:00.000Z')
+    expect(roundTrip(limit)).toMatchObject({ reason: 'window:7d', maximumMinor: 2500, currency: 'usd', resetsAt })
+  })
+
+  test('consentRefusalOf reads the class, a marshaled error, or a marker', () => {
+    expect(consentRefusalOf(new PerformanceConsentRequired({ pending: 1 }))).toBe(ConsentKind.Performance)
+    expect(consentRefusalOf(new SubscriptionStartRequired('pro-monthly'))).toBe(ConsentKind.SubscriptionStart)
+    expect(consentRefusalOf(ResilientError.marshal(new PerformanceConsentRequired({ pending: 3 })))).toBe(ConsentKind.Performance)
+    expect(consentRefusalOf({ type: PerformanceConsentRequired.typeName, message: 'x' })).toBe(ConsentKind.Performance)
+    expect(consentRefusalOf(new Error('upstream: subscription-start-required:pro'))).toBe(ConsentKind.SubscriptionStart)
+    expect(consentRefusalOf(new BillingCountryLocked({ country: 'PL' }))).toBeNull()
+    expect(consentRefusalOf(new Error('plain'))).toBeNull()
+    expect(consentRefusalOf(null)).toBeNull()
+    expect(consentRefusalOf('performance-consent-required')).toBeNull()
+  })
+})