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

package/src/consumer/legal.tsx

@@ -0,0 +1,129 @@
+import { Fragment, useCallback, useEffect, useState } from 'react'
+import { useLanguage } from '@owlmeans/client-i18n'
+import { baseLanguageOf } from '@owlmeans/payment'
+import type { ConsumerRightsLinks } from '@owlmeans/payment'
+import { cn } from '@/lib/utils'
+import { languageNameOf, usePaymentText, type FixedText } from './copy.js'
+import type { LegalLinksSource, PieceError } from './types.js'
+
+/** The interface language: the one given, else the active i18n language. */
+export const useUiLanguage = (uiLanguage?: string): string => {
+  const [active] = useLanguage()
+
+  return baseLanguageOf(uiLanguage ?? active) || 'en'
+}
+
+export interface ShownLanguage {
+  /** The language the legal copy is shown in now (base code). */
+  shown: string
+  /** The contract language (base code). */
+  contract: string
+  ui: string
+  /** The contract and interface languages differ, so a toggle is offered. */
+  canToggle: boolean
+  toggle: () => void
+}
+
+/**
+ * Which language a legal text is shown in: the contract language first, with a toggle to the
+ * interface language and back. `resetKey` (the dialog's `open`, say) returns it to the contract
+ * language.
+ */
+export const useShownLanguage = (contractLanguage: string, uiLanguage?: string, resetKey?: unknown): ShownLanguage => {
+  const ui = useUiLanguage(uiLanguage)
+  const contract = baseLanguageOf(contractLanguage) || ui
+  const [showUi, setShowUi] = useState(false)
+  useEffect(() => { setShowUi(false) }, [contract, resetKey])
+  const canToggle = contract !== ui
+  const toggle = useCallback(() => setShowUi(value => !value), [])
+
+  return { shown: canToggle && showUi ? ui : contract, contract, ui, canToggle, toggle }
+}
+
+export interface LanguageToggleProps {
+  language: ShownLanguage
+  /** An extra `data-*` hook of the piece that hosts the toggle (`data-consent-language-toggle`). */
+  hook?: string
+  className?: string
+}
+
+/**
+ * Switches a legal text between the contract and the interface language. Phrased in the
+ * INTERFACE language ("Show in German") — the reader who needs the toggle reads that one.
+ */
+export const LanguageToggle = ({ language, hook, className }: LanguageToggleProps) => {
+  const ui = usePaymentText(language.ui)
+  if (!language.canToggle) {
+    return null
+  }
+  const target = language.shown === language.contract ? language.ui : language.contract
+
+  return <button
+    type="button" onClick={language.toggle} data-language-toggle="" data-target-language={target}
+    {...(hook != null ? { [hook]: '' } : {})}
+    className={cn('text-primary w-fit cursor-pointer text-xs underline-offset-4 hover:underline', className)}
+  >
+    {ui('consumer.show-in', { language: languageNameOf(target, language.ui) })}
+  </button>
+}
+
+/** The links of the shown language: the source's, else the view's own. */
+export const linksFor = (language: string, own: ConsumerRightsLinks | undefined, source?: LegalLinksSource): ConsumerRightsLinks | undefined => {
+  if (source == null) {
+    return own
+  }
+  const picked = typeof source === 'function'
+    ? source(language)
+    : source[language] ?? source[baseLanguageOf(language)]
+
+  return picked ?? own
+}
+
+export interface LegalLinksProps {
+  links?: ConsumerRightsLinks
+  legal: FixedText
+  onWithdraw?: () => void
+  className?: string
+}
+
+/**
+ * "Billing Terms · Withdrawal information · Withdraw from contract here", each in the shown
+ * language: `[data-legal-link="billing-terms" | "withdrawal-information" | "withdrawal-function"]`.
+ * The withdrawal function is a button when the application opens it in-app (`onWithdraw`), else a
+ * link to its public page, else absent.
+ */
+export const LegalLinks = ({ links, legal, onWithdraw, className }: LegalLinksProps) => {
+  const anchor = (key: string, href: string | undefined, label: string) => href == null || href === ''
+    ? null
+    : <a key={key} href={href} target="_blank" rel="noopener noreferrer" data-legal-link={key}
+      className="text-primary underline-offset-4 hover:underline">{label}</a>
+  const items = [
+    anchor('billing-terms', links?.billingTerms, legal('links.billing-terms')),
+    anchor('withdrawal-information', links?.withdrawalInformation, legal('links.withdrawal-information')),
+    onWithdraw != null
+      ? <button key="withdrawal-function" type="button" onClick={onWithdraw} data-legal-link="withdrawal-function"
+        className="text-primary cursor-pointer underline-offset-4 hover:underline">{legal('links.withdrawal-function')}</button>
+      : anchor('withdrawal-function', links?.withdrawalFunction, legal('links.withdrawal-function')),
+  ].filter(item => item != null)
+  if (items.length === 0) {
+    return null
+  }
+
+  return <p className={cn('flex flex-wrap items-center gap-x-2 gap-y-1 text-xs', className)} data-legal-links="">
+    {items.map((item, index) => <Fragment key={index}>
+      {index > 0 && <span aria-hidden="true" className="text-muted-foreground">·</span>}
+      {item}
+    </Fragment>)}
+  </p>
+}
+
+/** A piece's failure line: the application's own words, or the generic sentence for `true`. */
+export const ErrorLine = ({ error, text }: { error?: PieceError, text: FixedText }) => {
+  if (error == null || error === false) {
+    return null
+  }
+
+  return <p role="alert" className="text-destructive text-sm" data-consumer-error="">
+    {error === true ? text('consumer.failed') : error}
+  </p>
+}

package/src/consumer/performance-consent-dialog.tsx

@@ -0,0 +1,132 @@
+import { useEffect, useState } from 'react'
+import type { PerformanceConsentView } from '@owlmeans/payment'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import { Checkbox } from '@/components/ui/checkbox'
+import {
+  Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
+} from '@/components/ui/dialog'
+import { Label } from '@/components/ui/label'
+import { lastDayUtc, dayUtc, money } from '../format.js'
+import { useLegalText, usePaymentText } from './copy.js'
+import { ErrorLine, LanguageToggle, LegalLinks, linksFor, useShownLanguage } from './legal.js'
+import type { PerformanceConsentDialogProps } from './types.js'
+
+/** The latest deadline of the view — its own, else the latest of its purchases. */
+const deadlineOf = (view: PerformanceConsentView): Date | undefined => {
+  if (view.deadline != null) {
+    return new Date(view.deadline)
+  }
+  const times = view.purchases
+    .map(purchase => purchase.deadline != null ? new Date(purchase.deadline).getTime() : NaN)
+    .filter(time => !Number.isNaN(time))
+
+  return times.length > 0 ? new Date(Math.max(...times)) : undefined
+}
+
+/**
+ * The express request to start performing now, asked before credits bought inside their
+ * withdrawal window are spent (CRD Art. 16(m), § 356 Abs. 5 BGB, art. 38 UoPK, L221-28).
+ *
+ * The legal copy is shown in the CONTRACT language (`view.language`) with a toggle to the
+ * interface language; the purchases it covers are listed with their deadlines; ONE checkbox
+ * carries the whole statement and starts unchecked, and the confirm button stays disabled until
+ * it is ticked. Toggling the language unticks it — the statement agreed to is the one on screen —
+ * and `onConfirm` records the language actually shown.
+ *
+ * Selectors: `[data-consent-dialog]` (with `data-language`, `data-contract-language`),
+ * `[data-consent-purchase]` (`data-purchase-id`, `data-deadline`), `[data-consent-checkbox]`,
+ * `[data-consent-confirm]`, `[data-consent-decline]`, `[data-consent-language-toggle]`,
+ * `[data-legal-link]`.
+ */
+export const PerformanceConsentDialog = ({
+  open, onOpenChange, view, uiLanguage, pending = false, error, onConfirm, onDecline, links, onWithdraw,
+  formatAmount, className,
+}: PerformanceConsentDialogProps) => {
+  const language = useShownLanguage(view?.language ?? '', uiLanguage, open)
+  const legal = useLegalText(language.shown)
+  const text = usePaymentText(language.shown)
+  const [ticked, setTicked] = useState(false)
+  useEffect(() => { setTicked(false) }, [open, language.shown, view?.textVersion])
+  if (view == null) {
+    return null
+  }
+
+  const format = (minor: number, currency: string) => formatAmount != null
+    ? formatAmount(minor, currency, language.shown) : money(minor, currency, language.shown)
+  // The same text `consentStatementOf(lng, 'performance', { trader })` renders on the server.
+  const checkbox = legal('performance-consent.checkbox', { trader: view.trader })
+  const deadline = deadlineOf(view)
+  const shownLinks = linksFor(language.shown, view.links, links)
+  const confirm = async () => {
+    if (!ticked || pending) {
+      return
+    }
+    await onConfirm({
+      purchaseIds: view.purchases.map(purchase => purchase.purchaseId),
+      textVersion: view.textVersion,
+      language: language.shown,
+      acknowledged: true,
+      uiLanguage: language.ui,
+    })
+  }
+
+  return <Dialog open={open} onOpenChange={onOpenChange}>
+    <DialogContent
+      closeLabel={text('consumer.close')}
+      data-consent-dialog="" data-performance-consent="" data-language={language.shown}
+      data-contract-language={language.contract} data-text-version={view.textVersion}
+      className={cn('max-h-[90vh] overflow-y-auto', className)}
+      {...(deadline == null ? { 'aria-describedby': undefined } : {})}
+    >
+      <DialogHeader>
+        <DialogTitle lang={language.shown}>{legal('performance-consent.title')}</DialogTitle>
+        {deadline != null && <DialogDescription lang={language.shown}>
+          {legal('performance-consent.intro', { count: view.purchases.length, deadline: lastDayUtc(deadline, language.shown) })}
+        </DialogDescription>}
+      </DialogHeader>
+      <LanguageToggle language={language} hook="data-consent-language-toggle" />
+      <div className="grid gap-4" lang={language.shown}>
+        {view.purchases.length > 0 && <section className="grid gap-2" aria-label={text('consumer.purchases')}>
+          <h3 className="text-sm font-medium">{text('consumer.purchases')}</h3>
+          <ul className="grid gap-1.5 text-sm">
+            {view.purchases.map(purchase => <li
+              key={purchase.purchaseId} data-consent-purchase="" data-purchase-id={purchase.purchaseId}
+              data-deadline={purchase.deadline != null ? new Date(purchase.deadline).toISOString() : undefined}
+              className="rounded-md border px-3 py-2"
+            >
+              {purchase.deadline != null
+                ? legal('performance-consent.purchase', {
+                  date: dayUtc(purchase.purchasedAt, language.shown),
+                  amount: format(purchase.amountTotalMinor, purchase.currency),
+                  deadline: lastDayUtc(purchase.deadline, language.shown),
+                })
+                : `${dayUtc(purchase.purchasedAt, language.shown)} (${format(purchase.amountTotalMinor, purchase.currency)})`}
+            </li>)}
+          </ul>
+        </section>}
+        <div className="flex items-start gap-3 rounded-md border p-3">
+          <Checkbox
+            id="performance-consent-checkbox" data-consent-checkbox="" checked={ticked} disabled={pending}
+            onCheckedChange={value => setTicked(value === true)} className="mt-0.5"
+          />
+          <Label htmlFor="performance-consent-checkbox" className="block text-sm leading-snug font-normal"
+            data-consent-statement="">
+            {checkbox}
+          </Label>
+        </div>
+        <LegalLinks links={shownLinks} legal={legal} onWithdraw={onWithdraw} />
+        <ErrorLine error={error} text={text} />
+      </div>
+      <DialogFooter>
+        <Button type="button" variant="outline" data-consent-decline="" disabled={pending}
+          onClick={() => onDecline != null ? onDecline() : onOpenChange(false)}>
+          {legal('performance-consent.decline')}
+        </Button>
+        <Button type="button" data-consent-confirm="" disabled={!ticked || pending} onClick={() => void confirm()}>
+          {pending ? text('consumer.pending') : legal('performance-consent.confirm')}
+        </Button>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+}

package/src/consumer/provider.tsx

@@ -0,0 +1,49 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
+import type { PerformanceConsentBody, PerformanceConsentResponse, PerformanceConsentView } from '@owlmeans/payment'
+import { makeConsentGate, passThroughGate, type ConsentGate } from './ensure.js'
+import { usePerformanceConsent, type UsePerformanceConsentOptions } from './hooks.js'
+import { PerformanceConsentDialog } from './performance-consent-dialog.js'
+
+export interface ConsentGateValue extends ConsentGate {
+  /** From the last read of the view; `null` before any, and always outside a provider. */
+  required: boolean | null
+}
+
+const ConsentGateContext = createContext<ConsentGateValue | null>(null)
+
+export interface PerformanceConsentProviderProps<RecordRequest extends RequestShape & { body: PerformanceConsentBody }> {
+  view: RegisteredEntrypoint<{}, PerformanceConsentView>
+  record: RegisteredEntrypoint<RecordRequest, PerformanceConsentResponse>
+  options?: UsePerformanceConsentOptions
+  children?: ReactNode
+}
+
+/**
+ * ONE spend-consent dialog for the whole application, and the gate every action that may spend
+ * credits reads with `useConsentGate()`: however many buttons ask at once, one dialog opens and
+ * they all get its answer.
+ */
+export const PerformanceConsentProvider = <RecordRequest extends RequestShape & { body: PerformanceConsentBody }>({
+  view, record, options, children,
+}: PerformanceConsentProviderProps<RecordRequest>) => {
+  const consent = usePerformanceConsent(view, record, options)
+  const { ensure, required } = consent
+  const value = useMemo<ConsentGateValue>(() => ({ ...makeConsentGate(ensure), required }), [ensure, required])
+
+  return <ConsentGateContext.Provider value={value}>
+    {children}
+    <PerformanceConsentDialog {...consent.dialog} />
+  </ConsentGateContext.Provider>
+}
+
+/**
+ * The application's consent gate: `ensure()` asks proactively, `withConsent(action)` runs an
+ * action and, when it is refused for the spend consent, asks and retries it exactly once
+ * (`ConsentDeclined` on a decline). Outside a `PerformanceConsentProvider` nothing can be asked:
+ * `ensure` answers `true` and a refusal propagates unchanged.
+ */
+export const useConsentGate = (): ConsentGateValue =>
+  useContext(ConsentGateContext) ?? PASS_THROUGH
+
+const PASS_THROUGH: ConsentGateValue = { ...passThroughGate, required: null }

package/src/consumer/refusal.ts

@@ -0,0 +1,110 @@
+import { ResilientError } from '@owlmeans/error'
+import { httpStatusOf } from '@owlmeans/api/status'
+import { ConsentKind, PaymentError, consentRefusalOf } from '@owlmeans/payment'
+
+/** Where a wrapping error keeps the one it wraps — `cause`, and the fields frameworks use for it. */
+const NESTED_FIELDS = ['cause', 'error', 'original', 'originalError', 'inner', 'reason'] as const
+
+/** How deep a wrapped chain is followed — a planning `CommitFailed` inside a transport error is two. */
+const MAX_DEPTH = 5
+
+const PRECONDITION_REQUIRED = 428
+
+/**
+ * Which express request a failure asks for: `performance` (spend consent), `subscription-start`,
+ * `unknown` for a bare HTTP 428 that names neither (a production body carries only an incident
+ * id), or `null` for anything else.
+ *
+ * Read on the error itself and on whatever it wraps (`cause`, `error`, `original`, `inner`, an
+ * aggregate's `errors`), and on text as well as objects, because a refusal travels in three shapes:
+ * the class (a development body, rebuilt by the registry); its marker inside another error's
+ * message or a stored string (a planning commit that failed on the refusal answers
+ * `planning:commit-failed:<transition>:<the refusal's text>`); and the bare status of a production
+ * body (`@owlmeans/api`'s `ApiStatusError`, `api:client:status:428[:<incident>]`).
+ */
+export const consentRefusalKindOf = (error: unknown): ConsentKind | 'unknown' | null => {
+  let status = false
+  const seen = new Set<unknown>()
+  const visit = (value: unknown, depth: number): ConsentKind | null => {
+    if (value == null || depth > MAX_DEPTH) {
+      return null
+    }
+    if (typeof value === 'string') {
+      const holder = { message: value }
+      if (httpStatusOf(holder) === PRECONDITION_REQUIRED) status = true
+      return consentRefusalOf(holder)
+    }
+    if (typeof value !== 'object' || seen.has(value)) {
+      return null
+    }
+    seen.add(value)
+    const kind = consentRefusalOf(value)
+    if (kind != null) {
+      return kind
+    }
+    if (httpStatusOf(value) === PRECONDITION_REQUIRED) {
+      status = true
+    }
+    for (const field of NESTED_FIELDS) {
+      const nested = visit((value as Record<string, unknown>)[field], depth + 1)
+      if (nested != null) return nested
+    }
+    const errors = (value as { errors?: unknown }).errors
+    if (Array.isArray(errors)) {
+      for (const item of errors) {
+        const nested = visit(item, depth + 1)
+        if (nested != null) return nested
+      }
+    }
+
+    return null
+  }
+  const kind = visit(error, 0)
+
+  return kind ?? (status ? 'unknown' : null)
+}
+
+/**
+ * Whether a failure is a consent refusal — the class or its marker (`consentRefusalOf`), or an
+ * HTTP 428 (`httpStatusOf`), on the error or anything it wraps. What decides that the consent
+ * dialog opens and the action is retried once.
+ */
+export const isConsentRefusal = (error: unknown): boolean => consentRefusalKindOf(error) != null
+
+/** A refusal the performance-consent dialog answers: the spend consent, or a bare 428. */
+export const isPerformanceConsentRefusal = (error: unknown): boolean => {
+  const kind = consentRefusalKindOf(error)
+
+  return kind === ConsentKind.Performance || kind === 'unknown'
+}
+
+const DECLINED_MARKER = 'consent-declined:'
+
+/**
+ * The person declined the express request, so the action that needed it did not run. Raised by
+ * `useConsentGate().withConsent` — never by a server, and never a refusal a gate retries.
+ */
+export class ConsentDeclined extends PaymentError {
+  public static override typeName: string = `${PaymentError.typeName}ConsentDeclined`
+
+  public kind: string = ConsentKind.Performance
+
+  constructor(kind: string = ConsentKind.Performance) {
+    super(`${DECLINED_MARKER}${kind}`)
+    this.type = ConsentDeclined.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const at = this.message.lastIndexOf(DECLINED_MARKER)
+    if (at >= 0) this.kind = this.message.slice(at + DECLINED_MARKER.length) || ConsentKind.Performance
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
+ResilientError.registerErrorClass(ConsentDeclined)
+
+export const isConsentDeclined = (error: unknown): error is ConsentDeclined => error instanceof ConsentDeclined

package/src/consumer/subscription-start-dialog.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useState } from 'react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/components/ui/button'
+import { Checkbox } from '@/components/ui/checkbox'
+import {
+  Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
+} from '@/components/ui/dialog'
+import { Label } from '@/components/ui/label'
+import { useLegalText, usePaymentText } from './copy.js'
+import { ErrorLine, LanguageToggle, LegalLinks, linksFor, useShownLanguage } from './legal.js'
+import type { SubscriptionStartDialogProps } from './types.js'
+
+/**
+ * The express request to start a subscription's services before its withdrawal period ends,
+ * asked BEFORE the subscription checkout (§ 357a Abs. 2 BGB, art. 35 UoPK, L221-25; CJEU C-641/19).
+ * Without it a withdrawal owes nothing for the time used.
+ *
+ * Same shape as the performance consent: the contract language first with a toggle, one
+ * unchecked checkbox carrying the whole statement, and the confirm button — "Continue to payment",
+ * the step before the paygate's own order button — disabled until it is ticked.
+ *
+ * Selectors: `[data-start-dialog]` (`data-language`, `data-contract-language`, `data-plan-sku`),
+ * `[data-start-checkbox]`, `[data-start-confirm]`, `[data-start-decline]`,
+ * `[data-start-language-toggle]`, `[data-legal-link]`.
+ */
+export const SubscriptionStartDialog = ({
+  open, onOpenChange, view, planTitle, price, uiLanguage, pending = false, error, onConfirm, onDecline, links,
+  onWithdraw, className,
+}: SubscriptionStartDialogProps) => {
+  const language = useShownLanguage(view?.language ?? '', uiLanguage, open)
+  const legal = useLegalText(language.shown)
+  const text = usePaymentText(language.shown)
+  const [ticked, setTicked] = useState(false)
+  useEffect(() => { setTicked(false) }, [open, language.shown, view?.textVersion, view?.planSku])
+  if (view == null) {
+    return null
+  }
+
+  // The same text `consentStatementOf(lng, 'subscription-start', { trader, plan })` renders on the server.
+  const checkbox = legal('subscription-start.checkbox', { trader: view.trader, plan: planTitle })
+  const shownLinks = linksFor(language.shown, view.links, links)
+  const confirm = async () => {
+    if (!ticked || pending) {
+      return
+    }
+    await onConfirm({ planSku: view.planSku, textVersion: view.textVersion, language: language.shown, acknowledged: true })
+  }
+
+  return <Dialog open={open} onOpenChange={onOpenChange}>
+    <DialogContent
+      closeLabel={text('consumer.close')}
+      data-start-dialog="" data-subscription-start="" data-language={language.shown}
+      data-contract-language={language.contract} data-plan-sku={view.planSku} data-text-version={view.textVersion}
+      className={cn('max-h-[90vh] overflow-y-auto', className)}
+    >
+      <DialogHeader>
+        <DialogTitle lang={language.shown}>{legal('subscription-start.title', { plan: planTitle })}</DialogTitle>
+        <DialogDescription lang={language.shown}>{legal('subscription-start.intro')}</DialogDescription>
+      </DialogHeader>
+      <LanguageToggle language={language} hook="data-start-language-toggle" />
+      <div className="grid gap-4" lang={language.shown}>
+        {price != null && <div className="text-sm" data-start-price="">{price}</div>}
+        <div className="flex items-start gap-3 rounded-md border p-3">
+          <Checkbox
+            id="subscription-start-checkbox" data-start-checkbox="" checked={ticked} disabled={pending}
+            onCheckedChange={value => setTicked(value === true)} className="mt-0.5"
+          />
+          <Label htmlFor="subscription-start-checkbox" className="block text-sm leading-snug font-normal"
+            data-start-statement="">
+            {checkbox}
+          </Label>
+        </div>
+        <LegalLinks links={shownLinks} legal={legal} onWithdraw={onWithdraw} />
+        <ErrorLine error={error} text={text} />
+      </div>
+      <DialogFooter>
+        <Button type="button" variant="outline" data-start-decline="" disabled={pending}
+          onClick={() => onDecline != null ? onDecline() : onOpenChange(false)}>
+          {legal('subscription-start.decline')}
+        </Button>
+        <Button type="button" data-start-confirm="" disabled={!ticked || pending} onClick={() => void confirm()}>
+          {pending ? text('consumer.pending') : legal('subscription-start.confirm')}
+        </Button>
+      </DialogFooter>
+    </DialogContent>
+  </Dialog>
+}

package/src/consumer/types.ts

@@ -0,0 +1,121 @@
+import type { ReactNode } from 'react'
+import type {
+  CancellationBody, CancellationReceipt, ConsumerRightsLinks, DeclarationReceipt, PerformanceConsentBody,
+  PerformanceConsentView, SubscriptionStartBody, SubscriptionStartView, WithdrawalBody, WithdrawalCandidateList,
+  WithdrawalReceipt,
+} from '@owlmeans/payment'
+
+/**
+ * The legal documents of a language: a record by language (`de`, `de-AT` → `de`) or a function (a
+ * policy read through `linksOf(policy, lng)`). Absent for a language, the view's own links are used.
+ */
+export type LegalLinksSource =
+  | Record<string, ConsumerRightsLinks | undefined>
+  | ((language: string) => ConsumerRightsLinks | null | undefined)
+
+/** Formats an amount of minor units for a language; the default is `Intl.NumberFormat`. */
+export type AmountFormatter = (minor: number, currency: string, language: string) => string
+
+/** `true` shows the package's generic failure sentence; a node is shown as given. */
+export type PieceError = ReactNode | boolean
+
+/** What every consumer-rights dialog shares. */
+export interface LegalDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /**
+   * The interface language — what the toggle switches to, and what the toggle itself is phrased
+   * in. Default: the active i18n language.
+   */
+  uiLanguage?: string
+  pending?: boolean
+  error?: PieceError
+  /** Links per language; default: the view's own links. */
+  links?: LegalLinksSource
+  /**
+   * Opens the withdrawal function in-app. Absent, the "withdraw from contract here" link points at
+   * the links' `withdrawalFunction` page, and is left out when there is none.
+   */
+  onWithdraw?: () => void
+  /** Called on the decline button; closing the dialog any other way is `onOpenChange(false)`. */
+  onDecline?: () => void
+  className?: string
+}
+
+export interface PerformanceConsentDialogProps extends LegalDialogProps {
+  /** `null` renders nothing. */
+  view: PerformanceConsentView | null
+  /**
+   * The express request, recorded in the language it was SHOWN in (`language`), with the
+   * interface language beside it (`uiLanguage`) — pass it to the record protocol as the body.
+   */
+  onConfirm: (body: PerformanceConsentBody) => Promise<unknown> | unknown
+  formatAmount?: AmountFormatter
+}
+
+export interface SubscriptionStartDialogProps extends LegalDialogProps {
+  view: SubscriptionStartView | null
+  /** The plan's title, as the application names it — it is part of the statement. */
+  planTitle: string
+  /** What the application shows about the price (amount, split, tax) above the statement. */
+  price?: ReactNode
+  onConfirm: (body: SubscriptionStartBody) => Promise<unknown> | unknown
+}
+
+/** Where a declaration is made: signed in (a candidate list) or on the public page (a contract reference). */
+export type DeclarationMode = 'in-app' | 'public'
+
+/** The three steps every statutory function takes: the form, the review with the statutory button, the receipt. */
+export type DeclarationStep = 'form' | 'review' | 'receipt'
+
+export interface WithdrawalFormProps {
+  mode: DeclarationMode
+  /** The language of the contract (the billing country's); the form shows its legal copy in it. */
+  language: string
+  uiLanguage?: string
+  /** In-app: the contracts that can still be withdrawn from. */
+  list?: WithdrawalCandidateList | null
+  /** Prefill. In-app, `purchaseId` (or `contractRef`) preselects a candidate. */
+  defaults?: { name?: string, email?: string, contractRef?: string, purchaseId?: string }
+  pending?: boolean
+  error?: PieceError
+  /** The answer to the submitted declaration — its presence is the receipt step. */
+  receipt?: WithdrawalReceipt | DeclarationReceipt | null
+  onSubmit: (body: WithdrawalBody) => Promise<unknown> | unknown
+  /** Offered on the receipt step. */
+  onClose?: () => void
+  formatAmount?: AmountFormatter
+  className?: string
+}
+
+export interface WithdrawalDialogProps extends Omit<WithdrawalFormProps, 'onClose' | 'className'> {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  className?: string
+}
+
+export interface WithdrawalFunctionButtonProps {
+  /** The contract language: the statutory label is shown in it. */
+  language: string
+  /** Its label in this language becomes the `title` when the two differ. Default: the active language. */
+  uiLanguage?: string
+  onClick: () => void
+  disabled?: boolean
+  variant?: 'default' | 'outline'
+  className?: string
+}
+
+export interface CancellationFormProps {
+  mode: DeclarationMode
+  language: string
+  uiLanguage?: string
+  defaults?: { name?: string, email?: string, contractRef?: string, subscriptionId?: string }
+  pending?: boolean
+  error?: PieceError
+  receipt?: CancellationReceipt | DeclarationReceipt | null
+  onSubmit: (body: CancellationBody) => Promise<unknown> | unknown
+  /** The receipt's print button; default `window.print()`. */
+  onPrint?: () => void
+  onClose?: () => void
+  className?: string
+}