@owlmeans/web-payment 0.1.18-rc.2 → 0.1.18-rc.21

package/tests/harness/consumer-fixtures.ts

@@ -0,0 +1,105 @@
+import {
+  CancellationStatus, ConsumerRegion, PurchaseKind, TaxBehavior, TaxEstimateStatus, TaxType, WithdrawalStatus,
+} from '@owlmeans/payment'
+import type {
+  AmountCheckoutPolicy, CheckoutLimitView, ConsumerRightsLinks, PerformanceConsentView, PriceEstimate,
+  SubscriptionStartView, WithdrawalCandidateList,
+} from '@owlmeans/payment'
+
+/** Canned consumer-rights data for the Playwright harness — no server, no Stripe. */
+
+export const TRADER = 'Example Trader'
+
+/** Links per language — a toggle switches them with the text. */
+export const LINKS: Record<string, ConsumerRightsLinks> = Object.fromEntries(['en', 'de', 'fr', 'pl', 'es'].map(lng => {
+  const prefix = lng === 'en' ? '' : `/${lng}`
+  return [lng, {
+    billingTerms: `https://example.test${prefix}/legal/billing-terms`,
+    withdrawalInformation: `https://example.test${prefix}/legal/withdrawal`,
+    withdrawalFunction: `https://example.test${prefix}/legal/withdraw`,
+  }]
+}))
+
+export const linksOf = (lng: string): ConsumerRightsLinks => LINKS[lng] ?? LINKS.en
+
+export const consentView = (lng: string): PerformanceConsentView => ({
+  required: true, region: ConsumerRegion.Eu, country: lng.toUpperCase(), language: lng, trader: TRADER,
+  textVersion: 'terms-2026-09', copyVersion: '2026-09-23', links: linksOf(lng),
+  purchases: [
+    {
+      purchaseId: 'pur_1', contractRef: 'CR-260923-AB12CD', kind: PurchaseKind.TopUp,
+      purchasedAt: new Date('2026-09-23T10:00:00Z'), deadline: new Date('2026-10-09T00:00:00Z'),
+      productSku: 'credits', amountTotalMinor: 1_256, currency: 'eur', withdrawable: true,
+    },
+    {
+      purchaseId: 'pur_2', contractRef: 'CR-260926-EF34GH', kind: PurchaseKind.TopUp,
+      purchasedAt: new Date('2026-09-26T09:30:00Z'), deadline: new Date('2026-10-14T00:00:00Z'),
+      productSku: 'credits', amountTotalMinor: 2_460, currency: 'eur', withdrawable: true,
+    },
+  ],
+  deadline: new Date('2026-10-14T00:00:00Z'),
+  at: new Date('2026-09-27T12:00:00Z'),
+})
+
+export const startView = (lng: string): SubscriptionStartView => ({
+  required: true, planSku: 'pro-monthly', language: lng, trader: TRADER, textVersion: 'terms-2026-09',
+  copyVersion: '2026-09-23', links: linksOf(lng), region: ConsumerRegion.Eu,
+})
+
+/** What the account withdrawal list answers on the wire — dates as ISO strings. */
+export const withdrawalList = (lng: string): WithdrawalCandidateList => JSON.parse(JSON.stringify({
+  language: lng, links: linksOf(lng), name: 'Marie Curie', email: 'marie@example.test',
+  candidates: [
+    {
+      purchaseId: 'pur_1', contractRef: 'CR-260923-AB12CD', kind: PurchaseKind.TopUp,
+      purchasedAt: new Date('2026-09-23T10:00:00Z'), deadline: new Date('2026-10-09T00:00:00Z'),
+      amountTotalMinor: 1_256, currency: 'eur', automatic: true,
+      estimate: { refundMinor: 942, currency: 'eur', timeDeductionMinor: 0, unitsDeductionMinor: 314, unitsUsed: 125_000, unitsGranted: 500_000 },
+    },
+    {
+      purchaseId: 'pur_3', contractRef: 'CR-260925-ZZ99YY', kind: PurchaseKind.Subscription,
+      purchasedAt: new Date('2026-09-25T08:00:00Z'), deadline: new Date('2026-10-10T00:00:00Z'),
+      amountTotalMinor: 2_460, currency: 'eur', automatic: true, estimate: null,
+    },
+  ],
+})) as WithdrawalCandidateList
+
+export const withdrawalReceipt = {
+  declarationId: 'wd_7Kq2', receivedAt: '2026-09-27T14:05:09.000Z', content: { name: 'Marie Curie' }, mailed: true,
+  status: WithdrawalStatus.Refunded, refundMinor: 942, currency: 'eur',
+}
+
+export const publicReceipt = {
+  declarationId: 'wd_pub1', receivedAt: '2026-09-27T14:05:09.000Z', content: {}, mailed: true,
+}
+
+export const cancellationReceipt = {
+  declarationId: 'cn_4Rt8', receivedAt: '2026-09-27T16:30:00.000Z', content: {}, mailed: true,
+  status: CancellationStatus.Scheduled, effectiveAt: '2026-10-31T00:00:00.000Z',
+}
+
+export const POLICY: AmountCheckoutPolicy = {
+  currency: 'usd', minimumMinor: 500, maximumMinor: 50_000, defaultMinor: 1_000,
+  presetsMinor: [1_000, 2_000, 5_000, 10_000], fixedMinor: 0, rateBps: 200,
+}
+
+export const PER_PURCHASE_LIMIT: CheckoutLimitView = {
+  productSku: 'credits', currency: 'usd', minimumMinor: 500, maximumMinor: 2_500, narrowed: true, blocked: false,
+  reason: 'per-purchase', resetsAt: new Date('2026-10-01T09:00:00Z'),
+}
+
+export const BLOCKED_LIMIT: CheckoutLimitView = {
+  productSku: 'credits', currency: 'usd', minimumMinor: 500, maximumMinor: 0, narrowed: true, blocked: true,
+  reason: 'window', resetsAt: new Date('2026-09-30T12:00:00Z'), remainingMinor: 0,
+}
+
+/** An estimate for a LOCKED billing country: the requested country is ignored. */
+export const lockedEstimate = (subtotalMinor: number): PriceEstimate => ({
+  country: 'DE', source: 'profile', locked: true, region: ConsumerRegion.Eu, currency: 'usd',
+  behavior: TaxBehavior.Exclusive,
+  tax: {
+    status: TaxEstimateStatus.Taxed, subtotalMinor, taxMinor: Math.round(subtotalMinor * 0.19),
+    totalMinor: subtotalMinor + Math.round(subtotalMinor * 0.19), scalable: true,
+    rates: [{ type: TaxType.Vat, percentage: '19', ratePpm: 190_000, country: 'DE' }],
+  },
+})

package/tests/harness/consumer.tsx

@@ -0,0 +1,197 @@
+import { useState, type ReactElement } from 'react'
+import type { RegisteredEntrypoint } from '@owlmeans/entrypoint'
+import type {
+  CancellationBody, DeclarationReceipt, PerformanceConsentBody, PerformanceConsentResponse, PerformanceConsentView,
+  PriceEstimate, WithdrawalBody, WithdrawalCandidateList,
+} from '@owlmeans/payment'
+import { AmountCheckoutDialog, PriceEstimateSummary, usePriceEstimate } from '../../src/index.js'
+import {
+  CancellationForm, PerformanceConsentDialog, PerformanceConsentProvider, SubscriptionStartDialog, WithdrawalDialog,
+  WithdrawalForm, WithdrawalFunctionButton, isConsentDeclined, useCancellation, useConsentGate, useWithdrawal,
+} from '../../src/consumer/index.js'
+import {
+  BLOCKED_LIMIT, LINKS, PER_PURCHASE_LIMIT, POLICY, cancellationReceipt, consentView, lockedEstimate, publicReceipt,
+  startView, withdrawalList, withdrawalReceipt,
+} from './consumer-fixtures.js'
+
+const params = new URLSearchParams(window.location.search)
+const lng = params.get('lng') ?? 'en'
+
+/** A fake bound protocol: records the request and answers after a short, real delay. */
+const fake = <Response,>(answer: (request: { body?: unknown }) => Response, record?: (request: unknown) => void) => ({
+  call: async (request: { body?: unknown } = {}) => {
+    record?.(request)
+    await new Promise(resolve => setTimeout(resolve, 50))
+    return answer(request)
+  },
+}) as unknown as RegisteredEntrypoint<any, Response>
+
+const Output = ({ id, value }: { id: string, value: unknown }) =>
+  <output id={id}>{value == null ? '' : typeof value === 'string' ? value : JSON.stringify(value)}</output>
+
+const ConsentCase = () => {
+  const [open, setOpen] = useState(true)
+  const [result, setResult] = useState<unknown>(null)
+  return <main className="p-6">
+    <Output id="consent-result" value={result} />
+    <Output id="dialog-state" value={open ? 'open' : 'closed'} />
+    <PerformanceConsentDialog
+      open={open} onOpenChange={setOpen} view={consentView(lng)} links={LINKS}
+      onConfirm={body => { setResult(body); setOpen(false) }}
+      onDecline={() => { setResult('declined'); setOpen(false) }}
+    />
+  </main>
+}
+
+const StartCase = () => {
+  const [open, setOpen] = useState(true)
+  const [result, setResult] = useState<unknown>(null)
+  return <main className="p-6">
+    <Output id="start-result" value={result} />
+    <SubscriptionStartDialog
+      open={open} onOpenChange={setOpen} view={startView(lng)} planTitle="Pro" links={LINKS}
+      price={<span>€20.00 / month</span>}
+      onConfirm={body => { setResult(body); setOpen(false) }}
+      onDecline={() => { setResult('declined'); setOpen(false) }}
+    />
+  </main>
+}
+
+const WithdrawalCase = () => {
+  const [open, setOpen] = useState(false)
+  const [sent, setSent] = useState<unknown>(null)
+  const [entries] = useState(() => ({
+    list: fake<WithdrawalCandidateList>(() => withdrawalList(lng)),
+    withdraw: fake<DeclarationReceipt>(() => withdrawalReceipt, request => setSent((request as { body: WithdrawalBody }).body)),
+  }))
+  const withdrawal = useWithdrawal(entries.list, entries.withdraw, { enabled: true })
+  return <main className="grid gap-4 p-6">
+    <Output id="withdrawal-body" value={sent} />
+    <div><WithdrawalFunctionButton language={lng} onClick={() => setOpen(true)} /></div>
+    <WithdrawalDialog
+      open={open} onOpenChange={next => { setOpen(next); if (!next) withdrawal.reset() }}
+      mode="in-app" language={lng} {...withdrawal.form}
+    />
+  </main>
+}
+
+const WithdrawalPublicCase = () => {
+  const [sent, setSent] = useState<unknown>(null)
+  const [entry] = useState(() => fake<DeclarationReceipt>(() => publicReceipt, request => setSent((request as { body: WithdrawalBody }).body)))
+  const withdrawal = useWithdrawal(null, entry)
+  return <main className="p-6">
+    <Output id="withdrawal-body" value={sent} />
+    <WithdrawalForm mode="public" language={lng} {...withdrawal.form} />
+  </main>
+}
+
+const CancellationCase = () => {
+  const [sent, setSent] = useState<unknown>(null)
+  const [printed, setPrinted] = useState(false)
+  const [entry] = useState(() => fake<DeclarationReceipt>(() => cancellationReceipt, request => setSent((request as { body: CancellationBody }).body)))
+  const cancellation = useCancellation(entry)
+  return <main className="p-6">
+    <Output id="cancellation-body" value={sent} />
+    <Output id="printed" value={printed ? 'printed' : ''} />
+    <CancellationForm mode="public" language={lng} onPrint={() => setPrinted(true)} {...cancellation.form} />
+  </main>
+}
+
+const LimitCase = () => {
+  const [open, setOpen] = useState(true)
+  const [confirmed, setConfirmed] = useState<number | null>(null)
+  const blocked = params.get('blocked') === 'true'
+  return <main className="p-6">
+    <Output id="confirmed" value={confirmed == null ? '' : String(confirmed)} />
+    <AmountCheckoutDialog
+      open={open} onOpenChange={setOpen} policy={POLICY} onConfirm={setConfirmed}
+      limit={blocked ? BLOCKED_LIMIT : PER_PURCHASE_LIMIT}
+      legalNote={<span data-harness-legal-note="">Only unused credits are reimbursed on withdrawal.</span>}
+    />
+  </main>
+}
+
+const CountryLockedCase = () => {
+  const [requested, setRequested] = useState<string[]>([])
+  const [entry] = useState(() => fake<PriceEstimate>(
+    () => lockedEstimate(2_000),
+    request => setRequested(held => [...held, (request as { body?: { country?: string } }).body?.country ?? '']),
+  ))
+  const estimate = usePriceEstimate(entry, { enabled: true })
+  return <main className="p-6">
+    <Output id="requested" value={requested} />
+    <Output id="locked" value={String(estimate.locked === true)} />
+    <PriceEstimateSummary control={estimate} subtotalMinor={2_000} currency="usd" />
+  </main>
+}
+
+/** `withConsent` against a protocol refused ONCE with a bare 428 — a production incident body. */
+const GateButtons = () => {
+  const gate = useConsentGate()
+  const [result, setResult] = useState('')
+  const [calls, setCalls] = useState(0)
+  const [refusals] = useState(() => ({ left: 1 }))
+  const run = async () => {
+    let made = 0
+    try {
+      await gate.withConsent(async () => {
+        made++
+        setCalls(made)
+        if (refusals.left > 0) {
+          refusals.left--
+          throw new Error('api:client:status:428:0b6f8a3e-8f0e-4b9f-9c55-2f1f0f6f2a11')
+        }
+        return 'done'
+      })
+      setResult(`ok:${made}`)
+    } catch (e) {
+      setResult(isConsentDeclined(e) ? `declined:${made}` : `error:${made}`)
+    }
+  }
+  const ensure = async () => { setResult(`ensure:${String(await gate.ensure())}`) }
+  return <>
+    <Output id="gate-result" value={result} />
+    <Output id="gate-calls" value={String(calls)} />
+    <button type="button" id="gate-run" onClick={() => void run()}>Run</button>
+    <button type="button" id="gate-ensure" onClick={() => void ensure()}>Ensure</button>
+  </>
+}
+
+const ConsentGateCase = () => {
+  const [state] = useState(() => ({ consented: false }))
+  const [recorded, setRecorded] = useState<unknown>(null)
+  const [entries] = useState(() => ({
+    view: fake<PerformanceConsentView>(() => JSON.parse(JSON.stringify(
+      state.consented ? { ...consentView(lng), required: false, purchases: [] } : consentView(lng),
+    ))),
+    record: fake<PerformanceConsentResponse>(request => {
+      state.consented = true
+      const body = (request as { body: PerformanceConsentBody }).body
+      return { consentId: 'cons_1', consentedAt: new Date().toISOString(), purchaseIds: body.purchaseIds, mailed: true } as never
+    }, request => setRecorded((request as { body: unknown }).body)),
+  }))
+  return <main className="grid gap-2 p-6">
+    <Output id="recorded" value={recorded} />
+    <PerformanceConsentProvider view={entries.view} record={entries.record} options={{ links: LINKS }}>
+      <GateButtons />
+    </PerformanceConsentProvider>
+  </main>
+}
+
+const CASES: Record<string, () => ReactElement> = {
+  consent: ConsentCase,
+  start: StartCase,
+  withdrawal: WithdrawalCase,
+  'withdrawal-public': WithdrawalPublicCase,
+  cancellation: CancellationCase,
+  limit: LimitCase,
+  'country-locked': CountryLockedCase,
+  'consent-gate': ConsentGateCase,
+}
+
+export const isConsumerCase = (name: string | null): name is string => name != null && name in CASES
+
+export const ConsumerCase = ({ name }: { name: string }) => {
+  const Case = CASES[name]
+  return <Case />
+}

package/tests/harness/entitlement.tsx

@@ -0,0 +1,159 @@
+import { useState } from 'react'
+import type { RegisteredEntrypoint } from '@owlmeans/entrypoint'
+import {
+  LimitKind, LimitWindow, SubscriptionStatus, TaxBehavior, TaxEstimateStatus, TaxType,
+  capabilityViewsOf, entitlementViewOf, limitViewsOf,
+  type EntitlementPlanView, type EntitlementView, type PlanCapability, type LimitDeclaration,
+  type PriceEstimate, type ProductPlan,
+} from '@owlmeans/payment'
+import {
+  CapabilityList, CountrySelect, LimitMeter, PlanCard, PriceEstimateAmount, useCapability,
+  useEntitlementView, useLimit, usePriceEstimate,
+} from '../../src/index.js'
+
+const AT = new Date('2026-09-16T12:00:00Z')
+const SUBSCRIBED = new Date('2026-01-01T00:00:00Z')
+const PROMO_UNTIL = new Date('2026-12-31T00:00:00Z')
+
+const pro: EntitlementPlanView = {
+  sku: 'pro-monthly', productSku: 'pro', title: 'Pro', rank: 10, free: false,
+  status: SubscriptionStatus.Active, paygate: 'stripe', subscribedAt: SUBSCRIBED,
+}
+const free: EntitlementPlanView = {
+  sku: 'free-plan', productSku: 'pro', title: 'Free', rank: 0, free: true,
+  status: SubscriptionStatus.Active, paygate: 'internal',
+}
+
+const PLANS: Record<string, EntitlementPlanView> = {
+  renews: { ...pro, periodEnd: new Date('2026-10-16T00:00:00Z') },
+  trial: { ...pro, status: SubscriptionStatus.Trial, trialEnd: new Date('2026-09-30T00:00:00Z') },
+  'past-due': { ...pro, status: SubscriptionStatus.PastDue, pastDue: true, periodEnd: new Date('2026-10-16T00:00:00Z') },
+  'cancel-scheduled': { ...pro, cancelAtPeriodEnd: true, periodEnd: new Date('2026-10-16T00:00:00Z') },
+  paused: { ...pro, status: SubscriptionStatus.Suspended, pausedAt: new Date('2026-09-01T00:00:00Z') },
+  free,
+  active: pro,
+}
+
+const capabilities: PlanCapability[] = [
+  { scope: 'feature', permissions: { whitelabel: true, 'custom-domain': true } },
+  { scope: 'feature', permissions: { 'local-llm': true }, promo: { until: PROMO_UNTIL } },
+  { scope: 'feature', permissions: { conversions: true }, promo: { until: PROMO_UNTIL, grandfather: true } },
+  { scope: 'feature', permissions: { beta: true }, promo: { until: new Date('2026-09-01T00:00:00Z') } },
+]
+
+const limits: Record<string, LimitDeclaration> = {
+  seats: { kind: LimitKind.Window, window: LimitWindow.Month, limit: 5 },
+  exports: { kind: LimitKind.Window, window: LimitWindow.Day, limit: 2 },
+  projects: { kind: LimitKind.Lifetime, limit: 0 },
+  sites: { kind: LimitKind.Occupancy, limit: 3, promo: { until: PROMO_UNTIL } },
+}
+
+const usage = [
+  { key: 'seats', window: '2026-09', used: 3 },
+  { key: 'exports', window: '2026-09-16', used: 2 },
+  { key: 'sites', window: 'occupancy', used: 1 },
+]
+
+const LABELS: Record<string, string> = {
+  'feature:whitelabel': 'White label',
+  'feature:local-llm': 'Local models',
+  'feature:conversions': 'Conversions',
+  'feature:beta': 'Beta programme',
+}
+
+const Pieces = () => {
+  const [acted, setActed] = useState('')
+  const capabilityRows = capabilityViewsOf({ capabilities }, SUBSCRIBED, AT)
+  const limitRows = limitViewsOf({ limits }, usage, SUBSCRIBED, AT)
+  const label = (key: string) => `${key[0].toUpperCase()}${key.slice(1)}`
+
+  return <main className="grid gap-6 p-6">
+    <section data-case="plans" className="grid gap-4">
+      {Object.entries(PLANS).map(([name, plan]) => <div key={name} data-case={name}><PlanCard plan={plan} /></div>)}
+    </section>
+    <section data-case="offers" className="grid gap-4">
+      <div data-case="offer-current">
+        <PlanCard plan={free} offer={{ sku: 'free-plan', title: 'Free', priceLabel: '$0' }} actionLabel="Manage" onAction={setActed} />
+      </div>
+      <div data-case="offer-upgrade">
+        <PlanCard plan={free} offer={{ sku: 'pro-monthly', title: 'Pro', priceLabel: '$20 / month', highlight: true }}
+          actionLabel="Upgrade" onAction={setActed}>
+          <p>Everything in Free, and more.</p>
+        </PlanCard>
+      </div>
+      <div data-case="offer-pending">
+        <PlanCard plan={free} offer={{ sku: 'pro-monthly', title: 'Pro', priceLabel: '$20 / month' }}
+          actionLabel="Upgrade" onAction={setActed} pending />
+      </div>
+      <output id="acted">{acted}</output>
+    </section>
+    <section data-case="limits" className="grid gap-4">
+      {limitRows.map(limit => <LimitMeter key={limit.key} limit={limit} label={label(limit.key)} />)}
+      <div data-case="no-reset"><LimitMeter limit={limitRows[0]} label="Seats" showReset={false} compact /></div>
+    </section>
+    <section data-case="capabilities"><CapabilityList capabilities={capabilityRows} labels={LABELS} /></section>
+    <section data-case="only-granted"><CapabilityList capabilities={capabilityRows} labels={LABELS} onlyGranted /></section>
+  </main>
+}
+
+/** What a server answers: the view through JSON, every date an ISO string. */
+const wireView = JSON.parse(JSON.stringify(entitlementViewOf(
+  { capabilities, limits } as unknown as ProductPlan, PLANS.renews, usage, AT,
+))) as EntitlementView
+
+const HookView = () => {
+  const [entry] = useState(() => ({
+    call: async () => {
+      await new Promise(resolve => setTimeout(resolve, 800))
+      return wireView
+    },
+  }) as unknown as RegisteredEntrypoint<{}, EntitlementView>)
+  const view = useEntitlementView(entry)
+  const whitelabel = useCapability(view, 'feature:whitelabel')
+  const seats = useLimit(view, 'seats')
+
+  return <main className="grid gap-4 p-6">
+    <output id="capability">{String(whitelabel)}</output>
+    <output id="seats">{seats == null ? 'null' : `${seats.used}/${seats.limit}:${seats.ratio}`}</output>
+    {view != null && <PlanCard plan={view.plan} />}
+    {view != null && view.limits.map(limit => <LimitMeter key={limit.key} limit={limit} label={limit.key} />)}
+  </main>
+}
+
+const PLAN_SUBTOTAL: Record<string, number> = { 'pro-monthly': 2_000, 'team-monthly': 5_000 }
+
+/** A fake `account.priceEstimate` that actually varies with the body it's called with. */
+const fakeEstimateEntry = () => ({
+  call: async ({ body }: { body?: { planSku?: string, country?: string } }) => {
+    await new Promise(resolve => setTimeout(resolve, 50))
+    const subtotalMinor = PLAN_SUBTOTAL[body?.planSku ?? ''] ?? 1_000
+    const country = body?.country
+    const tax: PriceEstimate['tax'] = country == null
+      ? { status: TaxEstimateStatus.LocationRequired, subtotalMinor, taxMinor: 0, totalMinor: subtotalMinor, scalable: false, rates: [] }
+      : country === 'PL'
+        ? {
+          status: TaxEstimateStatus.Taxed, subtotalMinor, taxMinor: Math.round(subtotalMinor * 0.23),
+          totalMinor: subtotalMinor + Math.round(subtotalMinor * 0.23), scalable: true,
+          rates: [{ type: TaxType.Vat, percentage: '23', ratePpm: 230_000, country: 'PL' }],
+        }
+        : { status: TaxEstimateStatus.None, subtotalMinor, taxMinor: 0, totalMinor: subtotalMinor, scalable: true, rates: [] }
+    return { country, source: 'request', currency: 'usd', behavior: TaxBehavior.Exclusive, tax } satisfies PriceEstimate
+  },
+}) as unknown as RegisteredEntrypoint<{ body?: { planSku?: string, country?: string } }, PriceEstimate>
+
+/** One `CountrySelect` driving two independent, controlled `usePriceEstimate` calls. */
+const SharedEstimateCase = () => {
+  const [entry] = useState(fakeEstimateEntry)
+  const [country, setCountry] = useState('')
+  const pro = usePriceEstimate(entry, { enabled: true, country, onCountryChange: setCountry }, { body: { planSku: 'pro-monthly' } })
+  const team = usePriceEstimate(entry, { enabled: true, country, onCountryChange: setCountry }, { body: { planSku: 'team-monthly' } })
+
+  return <main className="grid gap-4 p-6">
+    <CountrySelect value={country} onChange={setCountry} />
+    <div data-case="pro"><PriceEstimateAmount control={pro} subtotalMinor={2_000} currency="usd" /></div>
+    <div data-case="team"><PriceEstimateAmount control={team} subtotalMinor={5_000} currency="usd" /></div>
+  </main>
+}
+
+export const EntitlementCase = ({ name }: { name: string }) =>
+  name === 'hook' ? <HookView /> : name === 'shared-estimate' ? <SharedEstimateCase /> : <Pieces />

package/tests/harness/estimate-fixtures.ts

@@ -0,0 +1,48 @@
+import { TaxBehavior, TaxEstimateStatus, TaxType } from '@owlmeans/payment'
+import type { PriceEstimate } from '@owlmeans/payment'
+import type { PriceEstimateControl } from '../../src/index.js'
+
+/** Canned `PriceEstimateControl`s for the Playwright harness — no server, no Stripe. */
+export const ESTIMATE_FIXTURES: Record<string, PriceEstimateControl> = {
+  pl: {
+    country: 'PL', loading: false, failed: false, onCountryChange: () => {},
+    estimate: {
+      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 },
+    } satisfies PriceEstimate,
+  },
+  reverse: {
+    country: 'DE', loading: false, failed: false, onCountryChange: () => {},
+    estimate: {
+      country: 'DE', source: 'request', currency: 'usd', behavior: TaxBehavior.Exclusive,
+      tax: {
+        status: TaxEstimateStatus.ReverseCharge, subtotalMinor: 1_021, taxMinor: 0, totalMinor: 1_021,
+        scalable: true, rates: [],
+      },
+    } satisfies PriceEstimate,
+  },
+  'at-checkout': {
+    country: 'US', loading: false, failed: false, onCountryChange: () => {},
+    estimate: {
+      country: 'US', source: 'request', currency: 'usd', behavior: TaxBehavior.Exclusive,
+      tax: {
+        status: TaxEstimateStatus.AtCheckout, subtotalMinor: 1_021, taxMinor: 0, totalMinor: 1_021,
+        scalable: false, rates: [],
+      },
+    } satisfies PriceEstimate,
+  },
+  'location-required': {
+    country: '', loading: false, failed: false, onCountryChange: () => {},
+    estimate: {
+      currency: 'usd', behavior: TaxBehavior.Exclusive,
+      tax: {
+        status: TaxEstimateStatus.LocationRequired, subtotalMinor: 1_021, taxMinor: 0, totalMinor: 1_021,
+        scalable: false, rates: [],
+      },
+    } satisfies PriceEstimate,
+  },
+}

package/tests/harness/mount.tsx

@@ -2,18 +2,23 @@ import { useState } from 'react'
 import { createRoot } from 'react-dom/client'
 import { I18nContext } from '@owlmeans/client-i18n'
 import { AmountCheckoutDialog } from '../../src/index.js'
+import { ConsumerCase, isConsumerCase } from './consumer.js'
+import { EntitlementCase } from './entitlement.js'
+import { ESTIMATE_FIXTURES } from './estimate-fixtures.js'
 
 const params = new URLSearchParams(window.location.search)
 const pending = params.get('pending') === 'true'
+const scenario = params.get('case')
+const estimateCase = params.get('estimate')
 const policy = {
   currency: 'usd', minimumMinor: 500, maximumMinor: 50_000, defaultMinor: 1_000,
   presetsMinor: [1_000, 2_000, 5_000, 10_000], fixedMinor: 0, rateBps: 200,
 }
 
-const App = () => {
+const Dialog = () => {
   const [open, setOpen] = useState(true)
   const [confirmed, setConfirmed] = useState<number | null>(null)
-  return <I18nContext config={{ service: 'web-payment-test', i18n: { defaultLng: 'en' } } as never}>
+  return <>
     <output id="dialog-state">{open ? 'open' : 'closed'}</output>
     <output id="confirmed">{confirmed ?? ''}</output>
     <AmountCheckoutDialog
@@ -22,8 +27,19 @@ const App = () => {
       policy={policy}
       pending={pending}
       onConfirm={setConfirmed}
+      estimate={estimateCase != null ? ESTIMATE_FIXTURES[estimateCase] : undefined}
     />
-  </I18nContext>
+  </>
 }
 
+/** `?ui=` is the interface language; `?lng=` (read by the consumer cases) the contract language. */
+const ui = params.get('ui') ?? 'en'
+const LANGUAGES = ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr']
+
+const App = () => <I18nContext config={{ service: 'web-payment-test', i18n: { defaultLng: ui, supportedLngs: LANGUAGES } } as never}>
+  {scenario == null
+    ? <Dialog />
+    : isConsumerCase(scenario) ? <ConsumerCase name={scenario} /> : <EntitlementCase name={scenario} />}
+</I18nContext>
+
 createRoot(document.getElementById('root')!).render(<App />)

package/tests/i18n.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'bun:test'
+import { CancellationStatus, PurchaseKind, WithdrawalStatus } from '@owlmeans/payment'
 import en from '../src/i18n/en.json'
 import pl from '../src/i18n/pl.json'
 import ru from '../src/i18n/ru.json'
@@ -6,16 +7,85 @@ import be from '../src/i18n/be.json'
 import uk from '../src/i18n/uk.json'
 import es from '../src/i18n/es.json'
 import de from '../src/i18n/de.json'
+import fr from '../src/i18n/fr.json'
+
+type Messages = { [key: string]: string | Messages }
+
+/** Every leaf as `branch.key` → message, however deep the resource nests. */
+const leaves = (messages: Messages, prefix = ''): Map<string, unknown> => {
+  const found = new Map<string, unknown>()
+  for (const [key, value] of Object.entries(messages)) {
+    const path = prefix === '' ? key : `${prefix}.${key}`
+    if (value != null && typeof value === 'object') {
+      for (const [leaf, message] of leaves(value, path)) found.set(leaf, message)
+    } else {
+      found.set(path, value)
+    }
+  }
+  return found
+}
+
+const placeholders = (message: string): string[] =>
+  [...message.matchAll(/\{\{\s*([\w-]+)\s*\}\}/g)].map(match => match[1]).sort()
+
+/**
+ * What no payment text may say in any language (UCPD art. 6(1)(g)): the right of withdrawal
+ * EXPIRES for what was used, and unused credits ARE reimbursed — nothing is "non-refundable".
+ */
+const FORBIDDEN = /non-?refundable|nicht erstattungsf|non rembours|bezzwrotn|no reembolsable|невозвратн|неповоротн|незваротн/i
 
 describe('web-payment localization', () => {
-  const translations = { en, pl, ru, be, uk, es, de }
-
-  test('ships all seven library languages with exact key parity', () => {
-    const expected = Object.keys(en['amount-checkout']).sort()
-    expect(Object.keys(translations).sort()).toEqual(['be', 'de', 'en', 'es', 'pl', 'ru', 'uk'])
-    for (const messages of Object.values(translations)) {
-      expect(Object.keys(messages['amount-checkout']).sort()).toEqual(expected)
-      expect(Object.values(messages['amount-checkout']).every(value => value.trim().length > 0)).toBe(true)
+  const translations: Record<string, Messages> = { en, pl, ru, be, uk, es, de, fr }
+  const reference = leaves(en)
+
+  test('ships all eight library languages with exact key parity at every depth', () => {
+    expect(Object.keys(translations).sort()).toEqual(['be', 'de', 'en', 'es', 'fr', 'pl', 'ru', 'uk'])
+    for (const key of [
+      'amount-checkout.title', 'amount-checkout.above-limit', 'entitlement.status.renews-on', 'estimate.country-locked',
+      'checkout-limit.note', 'checkout-limit.reason.per-purchase', 'checkout-limit.reason.window', 'checkout-limit.reason.hold',
+      'consumer.show-in', 'consumer.review', 'consumer.receipt', 'withdrawal.status.refunded', 'cancellation.status.scheduled',
+    ]) {
+      expect({ key, present: reference.has(key) }).toEqual({ key, present: true })
+    }
+    for (const [lng, messages] of Object.entries(translations)) {
+      const found = leaves(messages)
+      expect({ lng, keys: [...found.keys()].sort() }).toEqual({ lng, keys: [...reference.keys()].sort() })
+      for (const [key, message] of found) {
+        expect({ lng, key, filled: typeof message === 'string' && message.trim().length > 0 })
+          .toEqual({ lng, key, filled: true })
+      }
+    }
+  })
+
+  test('keeps the interpolation placeholders of every message', () => {
+    for (const [lng, messages] of Object.entries(translations)) {
+      for (const [key, message] of leaves(messages)) {
+        expect({ lng, key, placeholders: placeholders(String(message)) })
+          .toEqual({ lng, key, placeholders: placeholders(String(reference.get(key))) })
+      }
+    }
+  })
+
+  test('phrases every status and kind a receipt or a candidate can carry, in every language', () => {
+    const required = [
+      ...Object.values(WithdrawalStatus).map(status => `withdrawal.status.${status}`),
+      ...Object.values(CancellationStatus).map(status => `cancellation.status.${status}`),
+      ...Object.values(PurchaseKind).map(kind => `withdrawal.kind.${kind}`),
+    ]
+    expect(required).toContain('cancellation.status.review')
+    for (const [lng, messages] of Object.entries(translations)) {
+      const found = leaves(messages)
+      for (const key of required) {
+        expect({ lng, key, present: typeof found.get(key) === 'string' }).toEqual({ lng, key, present: true })
+      }
+    }
+  })
+
+  test('never calls anything non-refundable, in any language', () => {
+    for (const [lng, messages] of Object.entries(translations)) {
+      for (const [key, message] of leaves(messages)) {
+        expect({ lng, key, forbidden: FORBIDDEN.test(String(message)) }).toEqual({ lng, key, forbidden: false })
+      }
     }
   })
 })