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

package/src/dialog.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useState } from 'react'
 import { useI18nLib, useLanguage } from '@owlmeans/client-i18n'
-import { assertCheckoutAmount, chargeAmountMinor } from '@owlmeans/payment'
+import { assertCheckoutAmount, chargeAmountMinor, narrowAmountPolicy } from '@owlmeans/payment'
+import type { AmountCheckoutPolicy, CheckoutLimitView } from '@owlmeans/payment'
 import { Button } from '@/components/ui/button'
 import {
   Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
@@ -8,76 +9,108 @@ import {
 import { Input } from '@/components/ui/input'
 import { Label } from '@/components/ui/label'
 import { inputAmount, parseAmountMinor } from './amount.js'
+import { CheckoutLimitNote } from './checkout-limit.js'
+import { PriceEstimateSummary } from './estimate-summary.js'
+import { money } from './format.js'
 import type { AmountCheckoutDialogProps } from './types.js'
 
-const money = (minor: number, currency: string, locale: string): string => new Intl.NumberFormat(locale, {
-  style: 'currency', currency: currency.toUpperCase(), minimumFractionDigits: 2,
-}).format(minor / 100)
+/**
+ * The policy the dialog offers: `policy` narrowed by `limit` — the same `narrowAmountPolicy` the
+ * server refuses with. A policy the package cannot narrow (an invalid one) is offered as given.
+ */
+const effectivePolicyOf = (policy: AmountCheckoutPolicy, limit?: CheckoutLimitView | null): AmountCheckoutPolicy => {
+  if (limit == null || (!limit.narrowed && !limit.blocked)) {
+    return policy
+  }
+  try {
+    return narrowAmountPolicy(policy, [{
+      maximumMinor: limit.maximumMinor,
+      reason: limit.reason ?? 'limit',
+      ...(limit.resetsAt != null ? { resetsAt: limit.resetsAt } : {}),
+      ...(limit.remainingMinor != null ? { remainingMinor: limit.remainingMinor } : {}),
+    }]).policy
+  } catch {
+    return policy
+  }
+}
 
 export const AmountCheckoutDialog = ({
-  open, onOpenChange, policy, pending = false, onConfirm,
+  open, onOpenChange, policy: basePolicy, pending = false, onConfirm, estimate, limit, legalNote,
 }: AmountCheckoutDialogProps) => {
   const t = useI18nLib('web-payment', 'amount-checkout')
   const [locale] = useLanguage()
+  const policy = useMemo(() => effectivePolicyOf(basePolicy, limit), [basePolicy, limit])
+  const blocked = limit?.blocked === true
+  // The limit, not the plan, set the maximum — also when `policy` arrives already narrowed.
+  const limited = limit != null && limit.narrowed && limit.maximumMinor <= policy.maximumMinor
   const [value, setValue] = useState(() => inputAmount(policy.defaultMinor, locale))
   useEffect(() => {
     if (open) setValue(inputAmount(policy.defaultMinor, locale))
   }, [open, policy.defaultMinor, locale])
 
   const amountMinor = useMemo(() => parseAmountMinor(value, locale), [value, locale])
-  const error = amountMinor == null
-    ? t('invalid')
-    : amountMinor < policy.minimumMinor
-      ? t('below', { amount: money(policy.minimumMinor, policy.currency, locale) })
-      : amountMinor > policy.maximumMinor
-        ? t('above', { amount: money(policy.maximumMinor, policy.currency, locale) })
-        : null
-  const valid = error == null && amountMinor != null
+  const error = blocked
+    ? null
+    : amountMinor == null
+      ? t('invalid')
+      : amountMinor < policy.minimumMinor
+        ? t('below', { amount: money(policy.minimumMinor, policy.currency, locale) })
+        : amountMinor > policy.maximumMinor
+          ? t(limited ? 'above-limit' : 'above', { amount: money(policy.maximumMinor, policy.currency, locale) })
+          : null
+  const valid = !blocked && error == null && amountMinor != null
   const chargeMinor = valid ? chargeAmountMinor(amountMinor, policy) : 0
   const adjustmentMinor = valid && amountMinor != null ? chargeMinor - amountMinor : 0
+  const locked = pending || blocked
   const submit = async () => {
-    if (amountMinor == null || !valid || pending) return
+    if (amountMinor == null || !valid || locked) return
     assertCheckoutAmount(policy, amountMinor)
-    await onConfirm(amountMinor)
+    await onConfirm(amountMinor, estimate?.country)
   }
 
   return <Dialog open={open} onOpenChange={onOpenChange}>
-    <DialogContent closeLabel={t('close')}>
+    <DialogContent closeLabel={t('close')} data-amount-checkout="" data-blocked={blocked ? 'true' : 'false'}>
       <DialogHeader>
         <DialogTitle>{t('title')}</DialogTitle>
         <DialogDescription>{t('description')}</DialogDescription>
       </DialogHeader>
       <div className="grid gap-5">
-        <div className="grid grid-cols-2 gap-2 sm:grid-cols-4" aria-label={t('presets')}>
+        {limit != null && <CheckoutLimitNote limit={limit} />}
+        {policy.presetsMinor.length > 0 && <div className="grid grid-cols-2 gap-2 sm:grid-cols-4" aria-label={t('presets')}>
           {policy.presetsMinor.map(preset => <Button
-            key={preset} type="button" variant={preset === amountMinor ? 'default' : 'outline'}
-            disabled={pending} onClick={() => setValue(inputAmount(preset, locale))}
+            key={preset} type="button" variant={preset === amountMinor ? 'default' : 'outline'} data-amount-preset={preset}
+            disabled={locked} onClick={() => setValue(inputAmount(preset, locale))}
           >{money(preset, policy.currency, locale)}</Button>)}
-        </div>
+        </div>}
         <div className="grid gap-2">
           <Label htmlFor="payment-amount">{t('custom')}</Label>
           <Input
             id="payment-amount" inputMode="decimal" autoComplete="off" value={value}
-            disabled={pending} aria-invalid={error != null} aria-describedby="payment-amount-help"
+            disabled={locked} aria-invalid={error != null} aria-describedby="payment-amount-help"
             onChange={event => setValue(event.target.value)}
           />
-          <p id="payment-amount-help" className={error == null ? 'text-muted-foreground text-xs' : 'text-destructive text-xs'}>
+          {!blocked && <p id="payment-amount-help" className={error == null ? 'text-muted-foreground text-xs' : 'text-destructive text-xs'}>
             {error ?? t('bounds', {
               minimum: money(policy.minimumMinor, policy.currency, locale),
               maximum: money(policy.maximumMinor, policy.currency, locale),
             })}
-          </p>
+          </p>}
         </div>
         <dl className="grid grid-cols-[1fr_auto] gap-x-4 gap-y-2 rounded-lg border bg-muted/30 p-4 text-sm">
           <dt className="text-muted-foreground">{t('credits')}</dt><dd>{valid && amountMinor != null ? money(amountMinor, policy.currency, locale) : '—'}</dd>
           <dt className="text-muted-foreground">{t('adjustment')}</dt><dd>{valid ? money(adjustmentMinor, policy.currency, locale) : '—'}</dd>
           <dt className="font-medium">{t('subtotal')}</dt><dd className="font-medium">{valid ? money(chargeMinor, policy.currency, locale) : '—'}</dd>
         </dl>
-        <p className="text-muted-foreground text-xs">{t('tax-note')}</p>
+        {estimate != null
+          ? valid && <PriceEstimateSummary control={estimate} subtotalMinor={chargeMinor} currency={policy.currency} />
+          : <p className="text-muted-foreground text-xs">{t('tax-note')}</p>}
+        {legalNote != null && <div className="text-muted-foreground text-xs" data-legal-note="">{legalNote}</div>}
       </div>
       <DialogFooter>
         <Button type="button" variant="outline" disabled={pending} onClick={() => onOpenChange(false)}>{t('cancel')}</Button>
-        <Button type="button" disabled={!valid || pending} onClick={() => void submit()}>{pending ? t('pending') : t('continue')}</Button>
+        <Button type="button" data-amount-confirm="" disabled={!valid || locked} onClick={() => void submit()}>
+          {pending ? t('pending') : t('continue')}
+        </Button>
       </DialogFooter>
     </DialogContent>
   </Dialog>

package/src/entitlement.ts

@@ -0,0 +1,56 @@
+import { useCallback, useMemo, useState } from 'react'
+import type { CallArguments, RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
+import { limitOf, reviveEntitlementView } from '@owlmeans/payment'
+import type { EntitlementView, PortalFlow, PortalLinkResponse } from '@owlmeans/payment'
+import { usePolled } from './poll.js'
+import { capabilityStateOf, limitStatusOf } from './selectors.js'
+import { openCheckout, type CheckoutTarget } from './service.js'
+import type { LimitStatus, PortalArguments, PortalRequest } from './types.js'
+
+/**
+ * Poll an entitlement-view protocol — `null` until the first answer. The view is revived on the way
+ * in (the wire carries ISO strings), so every date in it is a `Date`.
+ *
+ * An application that already keeps the view in its own store reads it through the pure selectors
+ * (`capabilityStateOf`, `limitStatusOf`, `planStatusLineOf`) instead of polling a second time.
+ */
+export const useEntitlementView = <Request extends RequestShape>(
+  entry: RegisteredEntrypoint<Request, EntitlementView>,
+  intervalMs: number = 60_000,
+  deps: unknown[] = [],
+  ...request: CallArguments<Request>
+): EntitlementView | null => usePolled(
+  async () => reviveEntitlementView(await entry.call(...request)), intervalMs, deps,
+)
+
+/** Whether the view grants a capability parameter; `null` while the view is unknown. */
+export const useCapability = (view: EntitlementView | null | undefined, param: string): boolean | null =>
+  useMemo(() => capabilityStateOf(view, param), [view, param])
+
+/** One limit of the view with `exhausted` and `ratio`; `null` while unknown or undeclared. */
+export const useLimit = (view: EntitlementView | null | undefined, key: string): LimitStatus | null =>
+  useMemo(() => limitStatusOf(limitOf(view, key)), [view, key])
+
+/**
+ * Open a billing-portal flow: `portal(entry, request?)` calls the portal protocol with `body.flow`
+ * set to `flow`, then sends the browser to the returned URL (same window by default). Without a DOM
+ * the navigation is inert and the response is still returned.
+ */
+export const usePortal = (flow: PortalFlow, target: CheckoutTarget = '_self') => {
+  const [pending, setPending] = useState(false)
+  const portal = useCallback(async <Request extends PortalRequest>(
+    entry: RegisteredEntrypoint<Request, PortalLinkResponse>, ...request: PortalArguments<Request>
+  ): Promise<PortalLinkResponse | null> => {
+    setPending(true)
+    try {
+      const [options] = request as [{ body?: object }?]
+      // The flow completes the body the caller's arguments deliberately leave out.
+      const args = [{ ...options, body: { ...options?.body, flow } }] as unknown as CallArguments<Request>
+      const result: PortalLinkResponse | undefined = await entry.call(...args)
+      if (result?.url != null) openCheckout(result.url, target)
+      return result ?? null
+    } finally { setPending(false) }
+  }, [flow, target])
+
+  return { portal, pending }
+}

package/src/estimate-cache.ts

@@ -0,0 +1,40 @@
+/**
+ * A small keyed TTL cache with in-flight de-duplication — the client-side twin of
+ * `@owlmeans/server-payment`'s `EstimateCache`, so opening the credit dialog twice in a row (or two
+ * mounts asking for the same plan/country) never issues a second request while the first is still
+ * on the wire, and a settled answer is reused for its TTL. A rejected fetch is never cached: the
+ * next call simply tries again.
+ */
+export class EstimateCache<T> {
+  private readonly store = new Map<string, { value: T, expiresAt: number }>()
+  private readonly inflight = new Map<string, Promise<T>>()
+
+  get(key: string): T | undefined {
+    const hit = this.store.get(key)
+    if (hit == null || hit.expiresAt <= Date.now()) {
+      return undefined
+    }
+    return hit.value
+  }
+
+  async load(key: string, ttlMs: number, factory: () => Promise<T>): Promise<T> {
+    const hit = this.get(key)
+    if (hit !== undefined) {
+      return hit
+    }
+    const pending = this.inflight.get(key)
+    if (pending != null) {
+      return pending
+    }
+    const promise = factory().then(value => {
+      this.store.set(key, { value, expiresAt: Date.now() + ttlMs })
+      this.inflight.delete(key)
+      return value
+    }).catch(error => {
+      this.inflight.delete(key)
+      throw error
+    })
+    this.inflight.set(key, promise)
+    return promise
+  }
+}

package/src/estimate-summary.tsx

@@ -0,0 +1,172 @@
+import { Fragment, useMemo, type ReactNode } from 'react'
+import { useI18nLib, useLanguage } from '@owlmeans/client-i18n'
+import { COUNTRY_CODES, TaxEstimateStatus, estimateOf } from '@owlmeans/payment'
+import { cn } from '@/lib/utils'
+import { Label } from '@/components/ui/label'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { money } from './format.js'
+import type { PriceEstimateControl } from './types.js'
+
+const localMoney = (amount: number, currency: string, locale: string): string => {
+  try {
+    return new Intl.NumberFormat(locale, { style: 'currency', currency: currency.toUpperCase() }).format(amount)
+  } catch {
+    return `${amount.toFixed(2)} ${currency.toUpperCase()}`
+  }
+}
+
+/** The country names a `<Select>` offers, in the viewer's own language and alphabetical order. */
+const useCountryOptions = (locale: string): Array<{ code: string, name: string }> => useMemo(() => {
+  let names: Intl.DisplayNames | null = null
+  try { names = new Intl.DisplayNames([locale], { type: 'region' }) } catch { names = null }
+  const collator = new Intl.Collator(locale)
+  return COUNTRY_CODES
+    .map(code => ({ code, name: names?.of(code) ?? code }))
+    .sort((a, b) => collator.compare(a.name, b.name))
+}, [locale])
+
+export interface CountrySelectProps {
+  /** ISO 3166-1 alpha-2, or `''` for the placeholder. */
+  value: string
+  onChange: (country: string) => void
+  /** Defaults to the `estimate.country` string (also the field's own label). */
+  label?: string
+  id?: string
+  className?: string
+  /** The country cannot be changed here — a billing country locked by the first purchase. */
+  disabled?: boolean
+  /** A line under the picker — why it is disabled, typically. */
+  note?: ReactNode
+}
+
+/**
+ * The billing-country picker alone — the piece `PriceEstimateSummary` composes for a single,
+ * self-contained estimate, and what a shared picker (several estimates, one country — a plan
+ * comparison table) renders once and drives every `usePriceEstimate({ country, onCountryChange })`
+ * with. Country names are the viewer's own language, alphabetically ordered.
+ *
+ * `[data-country-select]` carries `data-locked` (`"true"` while disabled) and the chosen
+ * `data-country`; the note is `[data-country-note]`.
+ */
+export const CountrySelect = ({
+  value, onChange, label, id = 'price-estimate-country', className, disabled = false, note,
+}: CountrySelectProps) => {
+  const t = useI18nLib('web-payment', 'estimate')
+  const [locale] = useLanguage()
+  const countries = useCountryOptions(locale)
+  const text = label ?? t('country')
+
+  return <div className={cn('grid gap-2', className)} data-country-select="" data-locked={disabled ? 'true' : 'false'}
+    data-country={value}>
+    <Label htmlFor={id}>{text}</Label>
+    {/* Always controlled, `''` included (no `SelectItem` ever has that value) — switching to
+        `undefined` once a country is chosen is what trips React's controlled/uncontrolled warning. */}
+    <Select value={value} onValueChange={next => { if (!disabled) onChange(next) }} disabled={disabled}>
+      <SelectTrigger id={id} aria-label={text} aria-describedby={note != null ? `${id}-note` : undefined}>
+        <SelectValue placeholder={t('country-placeholder')} />
+      </SelectTrigger>
+      <SelectContent>
+        {countries.map(({ code, name }) => <SelectItem key={code} value={code}>{name}</SelectItem>)}
+      </SelectContent>
+    </Select>
+    {note != null && <p id={`${id}-note`} className="text-muted-foreground text-xs" data-country-note="">{note}</p>}
+  </div>
+}
+
+export interface PriceEstimateAmountProps {
+  control: Pick<PriceEstimateControl, 'estimate' | 'loading' | 'failed'>
+  /** The amount to show tax and a total for — may differ from the estimate's own reference amount. */
+  subtotalMinor: number
+  currency: string
+  /** Appended after the total row, e.g. `"/ month"`. */
+  suffix?: string
+  className?: string
+}
+
+/**
+ * What Stripe Tax says at the estimate's country, with NO country picker of its own: the rate(s),
+ * an estimated total, and one sentence for whichever status leaves no number to trust (reverse
+ * charge, no tax, "at checkout", "choose a country"). Several of these may share one
+ * `CountrySelect` (a plan comparison table).
+ *
+ * A country whose currency differs from `currency` (Adaptive Pricing found a rate) shows the tax
+ * and the total in THAT currency instead, marked `≈` throughout — never both currencies at once,
+ * which would read as two different prices for the same line. The rate percentage itself is
+ * currency-agnostic and always shows as Stripe stated it.
+ *
+ * `data-price-estimate` / `data-status` are stable test hooks.
+ */
+export const PriceEstimateAmount = ({ control, subtotalMinor, currency, suffix, className }: PriceEstimateAmountProps) => {
+  const t = useI18nLib('web-payment', 'estimate')
+  const [locale] = useLanguage()
+  const { estimate, loading, failed } = control
+
+  const derived = estimate != null ? estimateOf(subtotalMinor, estimate) : null
+  const status = estimate?.tax.status
+  const numeric = status === TaxEstimateStatus.Taxed || status === TaxEstimateStatus.ReverseCharge
+    || status === TaxEstimateStatus.None
+  const rateLabel = estimate != null && estimate.tax.rates.length > 0
+    ? estimate.tax.rates
+      .map(rate => t('rate', { type: t(`tax-type.${rate.type}`), percentage: rate.percentage }))
+      .join(' + ')
+    : null
+
+  const local = derived?.local
+  const taxText = local != null
+    ? (derived?.taxMinor != null ? localMoney(local.taxAmount, local.currency, locale) : null)
+    : (derived?.taxMinor != null ? money(derived.taxMinor, currency, locale) : null)
+  const totalText = local != null
+    ? (derived?.totalMinor != null ? localMoney(local.totalAmount, local.currency, locale) : null)
+    : (derived?.totalMinor != null ? money(derived.totalMinor, currency, locale) : null)
+  const approx = local != null ? '≈ ' : ''
+
+  return <div data-price-estimate="" data-status={status ?? 'pending'} className={cn('grid gap-1.5', className)}>
+    {estimate == null && loading && <p className="text-muted-foreground text-xs">{t('loading')}</p>}
+    {estimate == null && !loading && failed && <p className="text-destructive text-xs">{t('failed')}</p>}
+
+    {estimate != null && <>
+      {numeric && taxText != null && totalText != null && <dl className="grid grid-cols-[1fr_auto] gap-x-4 gap-y-1 text-sm" data-estimate-rows="">
+        {status === TaxEstimateStatus.Taxed && rateLabel != null && <Fragment>
+          <dt className="text-muted-foreground" data-estimate-rate="">{rateLabel}</dt>
+          <dd data-estimate-tax="">{approx}{taxText}</dd>
+        </Fragment>}
+        <dt className="font-medium">{t('total')}</dt>
+        <dd className="font-medium" data-estimate-total="">
+          {approx}{totalText}{suffix != null ? ` ${suffix}` : ''}
+        </dd>
+      </dl>}
+      {numeric && local != null && <p className="text-muted-foreground text-xs" data-estimate-converted="">
+        {t('converted-note')}
+      </p>}
+      <p className="text-muted-foreground text-xs" data-estimate-status="">
+        {t(`status.${status}`)}
+      </p>
+    </>}
+  </div>
+}
+
+export interface PriceEstimateSummaryProps {
+  control: PriceEstimateControl
+  /** The amount the summary shows tax and a total for — may differ from the estimate's own reference amount. */
+  subtotalMinor: number
+  currency: string
+  /** Appended after the total row, e.g. `"/ month"`. */
+  suffix?: string
+  className?: string
+}
+
+/**
+ * A self-contained estimate: `CountrySelect` bound to the control's own `country`/`onCountryChange`,
+ * plus `PriceEstimateAmount` beneath it. What a single estimate (the credit dialog) wants; several
+ * estimates sharing one picker (a plan comparison table) compose the two pieces separately instead.
+ */
+export const PriceEstimateSummary = ({ control, subtotalMinor, currency, suffix, className }: PriceEstimateSummaryProps) => {
+  const t = useI18nLib('web-payment', 'estimate')
+  const { country, onCountryChange, locked = false } = control
+
+  return <div className={cn('grid gap-3', className)}>
+    <CountrySelect value={country} onChange={onCountryChange} disabled={locked}
+      note={locked ? t('country-locked') : undefined} />
+    <PriceEstimateAmount control={control} subtotalMinor={subtotalMinor} currency={currency} suffix={suffix} />
+  </div>
+}

package/src/estimate.ts

@@ -0,0 +1,119 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { RegisteredEntrypoint } from '@owlmeans/entrypoint'
+import type { PriceEstimate } from '@owlmeans/payment'
+import { EstimateCache } from './estimate-cache.js'
+import type { PriceEstimateArguments, PriceEstimateControl, PriceEstimateRequest } from './types.js'
+
+const DEFAULT_TTL_MS = 5 * 60_000
+
+/** Shared across every mounted dialog/estimate card in the tab — the server already caches per TTL too. */
+const cache = new EstimateCache<PriceEstimate>()
+
+export interface UsePriceEstimateOptions {
+  /** Fetch (and refetch on a country change) only while `true` — a closed dialog costs nothing. */
+  enabled: boolean
+  ttlMs?: number
+  /**
+   * Controls the country from outside (several estimates sharing one picker — a plan comparison
+   * table). Given: the hook never owns `useState` for it, never preselects from `source:
+   * 'customer'` (the owner does, once, for whichever estimate answers first), and the returned
+   * control's `onCountryChange` calls this back instead of an internal setter. Absent (the
+   * default): the hook is self-contained, exactly as a standalone dialog needs.
+   */
+  country?: string
+  onCountryChange?: (country: string) => void
+}
+
+/**
+ * A live `PriceEstimate` for one protocol/request, with a country the caller may change.
+ *
+ * Fetches once `enabled` and again on every `onCountryChange`, from a client-side cache keyed by
+ * the entry's alias, the request body and the country — a TTL match answers instantly, an identical
+ * in-flight request is shared. Uncontrolled (no `opts.country`): the first answer whose `source` is
+ * `'customer'` preselects its `country`, once, so a returning buyer sees their own country without
+ * picking it. Controlled (`opts.country` given): the country and its preselection are the caller's.
+ *
+ * An answer for a LOCKED billing country (`locked`, or `source: 'profile'`) wins over any pick: the
+ * hook adopts its country (controlled: through `opts.onCountryChange`, once), returns `locked:
+ * true`, and ignores `onCountryChange` from then on — the picker renders disabled.
+ */
+export const usePriceEstimate = <Request extends PriceEstimateRequest>(
+  entry: RegisteredEntrypoint<Request, PriceEstimate>, opts: UsePriceEstimateOptions,
+  ...request: PriceEstimateArguments<Request>
+): PriceEstimateControl => {
+  const entryRef = useRef(entry)
+  entryRef.current = entry
+  const base = (request[0] ?? {}) as { body?: Omit<Request['body'], 'country'> } & Record<string, unknown>
+  const bodyKey = JSON.stringify(base.body ?? {})
+  const controlled = opts.country !== undefined
+
+  const [internalCountry, setInternalCountry] = useState('')
+  const country = controlled ? opts.country! : internalCountry
+  const [estimate, setEstimate] = useState<PriceEstimate | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [failed, setFailed] = useState(false)
+  const preselectedRef = useRef(false)
+  const lockedRef = useRef(false)
+  const locked = estimate != null && isLockedAnswer(estimate)
+  lockedRef.current = locked
+  const onCountryChangeRef = useRef(opts.onCountryChange)
+  onCountryChangeRef.current = opts.onCountryChange
+
+  useEffect(() => {
+    if (!opts.enabled) {
+      return
+    }
+    let active = true
+    const key = `${entryRef.current.alias}:${bodyKey}:${country}`
+    const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS
+    setLoading(true)
+    setFailed(false)
+    cache.load(key, ttlMs, async () => await entryRef.current.call({
+      ...base, body: { ...(base.body ?? {}), ...(country !== '' ? { country } : {}) },
+    } as never)).then(result => {
+      if (!active) return
+      setEstimate(result)
+      setLoading(false)
+      if (isLockedAnswer(result) && result.country != null && result.country !== country) {
+        // A locked billing country overrides whatever was picked: adopt it, once per country.
+        preselectedRef.current = true
+        if (controlled) {
+          onCountryChangeRef.current?.(result.country)
+        } else {
+          setInternalCountry(result.country)
+        }
+        return
+      }
+      if (!controlled && !preselectedRef.current && country === '' && result.source === 'customer' && result.country != null) {
+        preselectedRef.current = true
+        setInternalCountry(result.country)
+      }
+    }).catch(() => {
+      if (active) {
+        setFailed(true)
+        setLoading(false)
+      }
+    })
+    return () => { active = false }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [opts.enabled, opts.ttlMs, bodyKey, country])
+
+  const onCountryChange = useCallback((next: string) => {
+    if (lockedRef.current) {
+      return
+    }
+    if (controlled) {
+      opts.onCountryChange?.(next)
+      return
+    }
+    preselectedRef.current = true
+    setInternalCountry(next)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [controlled, opts.onCountryChange])
+
+  return { estimate, country, loading, failed, locked, onCountryChange }
+}
+
+/** An answer computed for the entity's locked billing country, which no picker may change. */
+export const isLockedAnswer = (estimate: PriceEstimate): boolean =>
+  estimate.locked === true || estimate.source === 'profile'

package/src/format.ts

@@ -0,0 +1,71 @@
+import { lastWithdrawalDayOf } from '@owlmeans/payment'
+
+/** Minor units as a currency amount in a locale; an unknown locale or currency still reads. */
+export const money = (minor: number, currency: string, locale: string): string => {
+  try {
+    return new Intl.NumberFormat(locale, {
+      style: 'currency', currency: currency.toUpperCase(), minimumFractionDigits: 2,
+    }).format(minor / 100)
+  } catch {
+    return `${(minor / 100).toFixed(2)} ${currency.toUpperCase()}`
+  }
+}
+
+const dateOf = (date: Date | string | null | undefined): Date | null => {
+  if (date == null) {
+    return null
+  }
+  const value = date instanceof Date ? date : new Date(date)
+
+  return Number.isNaN(value.getTime()) ? null : value
+}
+
+/** A calendar day in UTC (`dateStyle: 'long'`); `''` for no or an unparseable date. */
+export const dayUtc = (date: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(date)
+  if (value == null) {
+    return ''
+  }
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(value)
+  } catch {
+    return value.toISOString().slice(0, 10)
+  }
+}
+
+/**
+ * The last day of a window whose deadline is EXCLUSIVE (the start of the next UTC day) — the day a
+ * consumer reads as "until". The rule is `@owlmeans/payment`'s `lastWithdrawalDayOf`, the one the
+ * server's e-mails and texts use, so the dialog and the mail never name different days.
+ */
+export const lastDayUtc = (deadline: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(deadline)
+
+  return value == null ? '' : dayUtc(lastWithdrawalDayOf(value), locale)
+}
+
+/** A date and time in UTC, to the second — the moment a declaration was received. */
+export const momentUtc = (date: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(date)
+  if (value == null) {
+    return ''
+  }
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeStyle: 'medium', timeZone: 'UTC' }).format(value)
+  } catch {
+    return value.toISOString().replace('T', ' ').slice(0, 19)
+  }
+}
+
+/** A date and time in UTC to the minute, with the zone named — when a limit rises again. */
+export const shortMomentUtc = (date: Date | string | null | undefined, locale: string): string => {
+  const value = dateOf(date)
+  if (value == null) {
+    return ''
+  }
+  try {
+    return `${new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short', timeZone: 'UTC' }).format(value)} UTC`
+  } catch {
+    return `${value.toISOString().replace('T', ' ').slice(0, 16)} UTC`
+  }
+}

package/src/hooks.ts

@@ -1,6 +1,6 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useCallback, useState } from 'react'
 import type { CallArguments, RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
-import { hasEntitlement } from '@owlmeans/payment'
+import { usePolled } from './poll.js'
 import { openCheckout, type CheckoutTarget } from './service.js'
 import type { CheckoutResult } from './types.js'
 
@@ -21,36 +21,4 @@ export const useCheckout = (target: CheckoutTarget = '_self') => {
 
 export const usePaymentBalance = <T>(
   entry: RegisteredEntrypoint<{}, T>, intervalMs: number = 60_000, deps: unknown[] = [],
-): T | null => {
-  const [balance, setBalance] = useState<T | null>(null)
-  const entryRef = useRef(entry)
-  entryRef.current = entry
-  useEffect(() => {
-    let active = true
-    const load = async () => {
-      try {
-        const value = await entryRef.current.call()
-        if (active) setBalance(value)
-      } catch { /* explicit actions own their errors */ }
-    }
-    void load()
-    const ticker = setInterval(load, intervalMs)
-    return () => { active = false; clearInterval(ticker) }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [intervalMs, ...deps])
-  return balance
-}
-
-export const useEntitlements = <T extends { entitlements?: string[] }>(
-  entry: RegisteredEntrypoint<{}, T>, intervalMs: number = 60_000, deps: unknown[] = [],
-): string[] | null => usePaymentBalance(entry, intervalMs, deps)?.entitlements ?? null
-
-export const useEntitlement = (list: string[] | null, param: string): boolean => list != null && hasEntitlement(
-  list.map(item => {
-    const colon = item.indexOf(':')
-    return colon >= 0
-      ? { scope: item.slice(0, colon), permissions: { [item.slice(colon + 1)]: true } }
-      : { scope: '', permissions: { [item]: true } }
-  }),
-  param,
-)
+): T | null => usePolled(() => entry.call(), intervalMs, deps)