npm - @owlmeans/web-payment - Versions diffs - 0.1.18-rc.2 → 0.1.18-rc.21 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (203) hide show

package/README.md +30 -1
package/agent-meta/manifest.json +2 -2
package/agent-meta/skills/web-payment/SKILL.md +287 -20
package/build/@/components/ui/card.d.ts +10 -0
package/build/@/components/ui/card.d.ts.map +1 -0
package/build/@/components/ui/card.js +25 -0
package/build/@/components/ui/card.js.map +1 -0
package/build/@/components/ui/checkbox.d.ts +5 -0
package/build/@/components/ui/checkbox.d.ts.map +1 -0
package/build/@/components/ui/checkbox.js +6 -0
package/build/@/components/ui/checkbox.js.map +1 -0
package/build/@/components/ui/progress.d.ts +5 -0
package/build/@/components/ui/progress.d.ts.map +1 -0
package/build/@/components/ui/progress.js +11 -0
package/build/@/components/ui/progress.js.map +1 -0
package/build/@/components/ui/select.d.ts +8 -0
package/build/@/components/ui/select.d.ts.map +1 -0
package/build/@/components/ui/select.js +9 -0
package/build/@/components/ui/select.js.map +1 -0
package/build/capability-list.d.ts +7 -0
package/build/capability-list.d.ts.map +1 -0
package/build/capability-list.js +24 -0
package/build/capability-list.js.map +1 -0
package/build/checkout-limit.d.ts +11 -0
package/build/checkout-limit.d.ts.map +1 -0
package/build/checkout-limit.js +34 -0
package/build/checkout-limit.js.map +1 -0
package/build/consumer/cancellation.d.ts +20 -0
package/build/consumer/cancellation.d.ts.map +1 -0
package/build/consumer/cancellation.js +115 -0
package/build/consumer/cancellation.js.map +1 -0
package/build/consumer/copy.d.ts +23 -0
package/build/consumer/copy.d.ts.map +1 -0
package/build/consumer/copy.js +75 -0
package/build/consumer/copy.js.map +1 -0
package/build/consumer/ensure.d.ts +56 -0
package/build/consumer/ensure.d.ts.map +1 -0
package/build/consumer/ensure.js +71 -0
package/build/consumer/ensure.js.map +1 -0
package/build/consumer/fields.d.ts +43 -0
package/build/consumer/fields.d.ts.map +1 -0
package/build/consumer/fields.js +19 -0
package/build/consumer/fields.js.map +1 -0
package/build/consumer/hooks.d.ts +113 -0
package/build/consumer/hooks.d.ts.map +1 -0
package/build/consumer/hooks.js +225 -0
package/build/consumer/hooks.js.map +1 -0
package/build/consumer/index.d.ts +14 -0
package/build/consumer/index.d.ts.map +1 -0
package/build/consumer/index.js +12 -0
package/build/consumer/index.js.map +1 -0
package/build/consumer/legal.d.ts +53 -0
package/build/consumer/legal.d.ts.map +1 -0
package/build/consumer/legal.js +77 -0
package/build/consumer/legal.js.map +1 -0
package/build/consumer/performance-consent-dialog.d.ts +18 -0
package/build/consumer/performance-consent-dialog.d.ts.map +1 -0
package/build/consumer/performance-consent-dialog.js +71 -0
package/build/consumer/performance-consent-dialog.js.map +1 -0
package/build/consumer/provider.d.ts +33 -0
package/build/consumer/provider.d.ts.map +1 -0
package/build/consumer/provider.js +26 -0
package/build/consumer/provider.js.map +1 -0
package/build/consumer/refusal.d.ts +35 -0
package/build/consumer/refusal.d.ts.map +1 -0
package/build/consumer/refusal.js +98 -0
package/build/consumer/refusal.js.map +1 -0
package/build/consumer/subscription-start-dialog.d.ts +16 -0
package/build/consumer/subscription-start-dialog.d.ts.map +1 -0
package/build/consumer/subscription-start-dialog.js +43 -0
package/build/consumer/subscription-start-dialog.js.map +1 -0
package/build/consumer/types.d.ts +114 -0
package/build/consumer/types.d.ts.map +1 -0
package/build/consumer/types.js +2 -0
package/build/consumer/types.js.map +1 -0
package/build/consumer/withdrawal.d.ts +29 -0
package/build/consumer/withdrawal.d.ts.map +1 -0
package/build/consumer/withdrawal.js +140 -0
package/build/consumer/withdrawal.js.map +1 -0
package/build/copy.d.ts +14 -0
package/build/copy.d.ts.map +1 -0
package/build/copy.js +51 -0
package/build/copy.js.map +1 -0
package/build/dialog.d.ts +1 -1
package/build/dialog.d.ts.map +1 -1
package/build/dialog.js +46 -17
package/build/dialog.js.map +1 -1
package/build/entitlement.d.ts +26 -0
package/build/entitlement.d.ts.map +1 -0
package/build/entitlement.js +42 -0
package/build/entitlement.js.map +1 -0
package/build/estimate-cache.d.ts +14 -0
package/build/estimate-cache.d.ts.map +1 -0
package/build/estimate-cache.js +39 -0
package/build/estimate-cache.js.map +1 -0
package/build/estimate-summary.d.ts +64 -0
package/build/estimate-summary.d.ts.map +1 -0
package/build/estimate-summary.js +94 -0
package/build/estimate-summary.js.map +1 -0
package/build/estimate.d.ts +34 -0
package/build/estimate.d.ts.map +1 -0
package/build/estimate.js +92 -0
package/build/estimate.js.map +1 -0
package/build/format.d.ts +15 -0
package/build/format.d.ts.map +1 -0
package/build/format.js +68 -0
package/build/format.js.map +1 -0
package/build/hooks.d.ts +0 -4
package/build/hooks.d.ts.map +1 -1
package/build/hooks.js +3 -30
package/build/hooks.js.map +1 -1
package/build/i18n/be.json +1 -1
package/build/i18n/de.json +1 -1
package/build/i18n/en.json +1 -1
package/build/i18n/es.json +1 -1
package/build/i18n/fr.json +145 -0
package/build/i18n/pl.json +1 -1
package/build/i18n/ru.json +1 -1
package/build/i18n/uk.json +1 -1
package/build/i18n.d.ts +2 -1
package/build/i18n.d.ts.map +1 -1
package/build/i18n.js +11 -7
package/build/i18n.js.map +1 -1
package/build/index.d.ts +9 -0
package/build/index.d.ts.map +1 -1
package/build/index.js +9 -0
package/build/index.js.map +1 -1
package/build/limit-meter.d.ts +7 -0
package/build/limit-meter.d.ts.map +1 -0
package/build/limit-meter.js +26 -0
package/build/limit-meter.js.map +1 -0
package/build/plan-card.d.ts +7 -0
package/build/plan-card.d.ts.map +1 -0
package/build/plan-card.js +29 -0
package/build/plan-card.js.map +1 -0
package/build/poll.d.ts +7 -0
package/build/poll.d.ts.map +1 -0
package/build/poll.js +28 -0
package/build/poll.js.map +1 -0
package/build/selectors.d.ts +18 -0
package/build/selectors.d.ts.map +1 -0
package/build/selectors.js +78 -0
package/build/selectors.js.map +1 -0
package/build/types.d.ts +120 -2
package/build/types.d.ts.map +1 -1
package/package.json +22 -7
package/src/@/components/ui/card.tsx +93 -0
package/src/@/components/ui/checkbox.tsx +23 -0
package/src/@/components/ui/progress.tsx +44 -0
package/src/@/components/ui/select.tsx +62 -0
package/src/@/globals.css +10 -0
package/src/capability-list.tsx +50 -0
package/src/checkout-limit.tsx +48 -0
package/src/consumer/cancellation.tsx +214 -0
package/src/consumer/copy.ts +93 -0
package/src/consumer/ensure.ts +124 -0
package/src/consumer/fields.tsx +89 -0
package/src/consumer/hooks.ts +358 -0
package/src/consumer/index.ts +13 -0
package/src/consumer/legal.tsx +129 -0
package/src/consumer/performance-consent-dialog.tsx +132 -0
package/src/consumer/provider.tsx +49 -0
package/src/consumer/refusal.ts +110 -0
package/src/consumer/subscription-start-dialog.tsx +87 -0
package/src/consumer/types.ts +121 -0
package/src/consumer/withdrawal.tsx +279 -0
package/src/copy.tsx +62 -0
package/src/dialog.tsx +58 -25
package/src/entitlement.ts +56 -0
package/src/estimate-cache.ts +40 -0
package/src/estimate-summary.tsx +172 -0
package/src/estimate.ts +119 -0
package/src/format.ts +71 -0
package/src/hooks.ts +3 -35
package/src/i18n/be.json +1 -1
package/src/i18n/de.json +1 -1
package/src/i18n/en.json +1 -1
package/src/i18n/es.json +1 -1
package/src/i18n/fr.json +145 -0
package/src/i18n/pl.json +1 -1
package/src/i18n/ru.json +1 -1
package/src/i18n/uk.json +1 -1
package/src/i18n.ts +12 -7
package/src/index.ts +9 -0
package/src/limit-meter.tsx +55 -0
package/src/plan-card.tsx +67 -0
package/src/poll.ts +27 -0
package/src/selectors.ts +93 -0
package/src/types.ts +142 -2
package/tests/consent-refusal.spec.ts +83 -0
package/tests/consumer-hooks.spec.ts +205 -0
package/tests/consumer.spec.ts +343 -0
package/tests/context.ts +9 -0
package/tests/dialog.spec.ts +49 -0
package/tests/entitlement.spec.ts +117 -0
package/tests/estimate-cache.spec.ts +46 -0
package/tests/harness/consumer-fixtures.ts +105 -0
package/tests/harness/consumer.tsx +197 -0
package/tests/harness/entitlement.tsx +159 -0
package/tests/harness/estimate-fixtures.ts +48 -0
package/tests/harness/mount.tsx +19 -3
package/tests/i18n.spec.ts +78 -8
package/tests/pieces.spec.ts +134 -0

package/src/consumer/hooks.ts ADDED Viewed

@@ -0,0 +1,358 @@
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import type { CallArguments, RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
+import {
+  reviveConsentResponse, reviveConsentView, reviveReceipt, reviveStartResponse, reviveWithdrawalList,
+} from '@owlmeans/payment'
+import type {
+  CancellationBody, DeclarationReceipt, PerformanceConsentBody, PerformanceConsentResponse, PerformanceConsentView,
+  SubscriptionStartBody, SubscriptionStartQuery, SubscriptionStartResponse, SubscriptionStartView, WithdrawalBody,
+  WithdrawalCandidateList,
+} from '@owlmeans/payment'
+import { makeAsker, type EnsureOptions } from './ensure.js'
+import { isConsentRefusal } from './refusal.js'
+import type {
+  LegalLinksSource, PerformanceConsentDialogProps, SubscriptionStartDialogProps,
+} from './types.js'
+/** A protocol whose request carries `body`: the record, withdraw and cancel routes. */
+type BodyRequest<Body> = RequestShape & { body: Body }
+/** One call argument built by the hook — the protocol's own `CallArguments`, completed here. */
+const argsOf = <Request extends RequestShape>(request: object): CallArguments<Request> =>
+  [request] as unknown as CallArguments<Request>
+export interface UsePerformanceConsentOptions {
+  /** Read the view on mount, so `required` is known before anything asks. Default `false`. */
+  enabled?: boolean
+  uiLanguage?: string
+  links?: LegalLinksSource
+  /** Open the withdrawal function; the consent dialog closes (declined) first. */
+  onWithdraw?: () => void
+  /** After the consent was recorded — refresh an account feed, say. */
+  onRecorded?: (response: PerformanceConsentResponse) => void
+}
+export interface PerformanceConsentControl {
+  view: PerformanceConsentView | null
+  /** From the last read; `null` before any. */
+  required: boolean | null
+  /**
+   * `true` when no consent is needed or it was confirmed and recorded, `false` on a decline or a
+   * closed dialog. Reads the view fresh; a failed read answers `true`. Concurrent calls share one
+   * pending answer — one dialog.
+   */
+  ensure: (opts?: EnsureOptions) => Promise<boolean>
+  refresh: () => Promise<PerformanceConsentView | null>
+  /** Spread into ONE `PerformanceConsentDialog`. */
+  dialog: PerformanceConsentDialogProps
+}
+/**
+ * The spend consent over two protocols — the view (`consent` GET) and the record (`giveConsent`
+ * POST) of `makeConsumerRightsProtocols` — bound with `ctx.entrypoint(protocol)`.
+ */
+export const usePerformanceConsent = <RecordRequest extends BodyRequest<PerformanceConsentBody>>(
+  view: RegisteredEntrypoint<{}, PerformanceConsentView>,
+  record: RegisteredEntrypoint<RecordRequest, PerformanceConsentResponse>,
+  opts: UsePerformanceConsentOptions = {},
+): PerformanceConsentControl => {
+  const viewRef = useRef(view)
+  viewRef.current = view
+  const recordRef = useRef(record)
+  recordRef.current = record
+  const optsRef = useRef(opts)
+  optsRef.current = opts
+  const [current, setCurrent] = useState<PerformanceConsentView | null>(null)
+  const [open, setOpen] = useState(false)
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState(false)
+  const load = useCallback(async (): Promise<PerformanceConsentView> => {
+    const next = reviveConsentView(await viewRef.current.call())
+    setCurrent(next)
+    return next
+  }, [])
+  const asker = useMemo(() => makeAsker<[], PerformanceConsentView, boolean>({
+    load, required: next => next.required, skip: true,
+    show: () => { setError(false); setOpen(true) },
+  }), [load])
+  useEffect(() => {
+    if (opts.enabled === true) void load().catch(() => undefined)
+  }, [opts.enabled, load])
+  const decline = useCallback(() => {
+    setOpen(false)
+    asker.settle(false)
+  }, [asker])
+  const onConfirm = useCallback(async (body: PerformanceConsentBody) => {
+    setPending(true)
+    setError(false)
+    try {
+      const response = reviveConsentResponse(await recordRef.current.call(...argsOf<RecordRequest>({ body })))
+      setCurrent(held => held == null ? held : { ...held, required: false, purchases: [] })
+      setOpen(false)
+      asker.settle(true)
+      optsRef.current.onRecorded?.(response)
+    } catch (e) {
+      setError(true)
+      // A stale text version is refused with a 428: show the current wording to confirm again.
+      if (isConsentRefusal(e)) void load().catch(() => undefined)
+    } finally {
+      setPending(false)
+    }
+  }, [asker, load])
+  const refresh = useCallback(async () => {
+    try {
+      return await load()
+    } catch {
+      return null
+    }
+  }, [load])
+  const ensure = useCallback(async () => await asker.ask(), [asker])
+  const onWithdraw = opts.onWithdraw
+  const dialog: PerformanceConsentDialogProps = {
+    open, view: current, pending, error, onConfirm, onDecline: decline,
+    onOpenChange: next => { if (next) setOpen(true); else decline() },
+    uiLanguage: opts.uiLanguage,
+    links: opts.links,
+    onWithdraw: onWithdraw != null ? () => { decline(); onWithdraw() } : undefined,
+  }
+  return { view: current, required: current?.required ?? null, ensure, refresh, dialog }
+}
+export interface UseSubscriptionStartOptions {
+  uiLanguage?: string
+  links?: LegalLinksSource
+  onWithdraw?: () => void
+}
+export interface SubscriptionStartParams {
+  /** The plan's title as the application names it — part of the statement. */
+  planTitle: string
+  /** The price line the dialog shows above the statement. */
+  price?: ReactNode
+}
+export interface SubscriptionStartControl {
+  /**
+   * The start request id to send with the subscription checkout (`CreateCheckoutBody.
+   * startRequestId`); `''` when none is needed (or the view could not be read — the checkout's
+   * own refusal then decides); `null` when the person declined or closed the dialog.
+   */
+  ensure: (planSku: string, params: SubscriptionStartParams) => Promise<string | null>
+  view: SubscriptionStartView | null
+  /** Spread into ONE `SubscriptionStartDialog`. */
+  dialog: SubscriptionStartDialogProps
+}
+/**
+ * The subscription start request over the `start` GET (`?planSku`) and `requestStart` POST
+ * protocols, asked right before a subscription checkout.
+ */
+export const useSubscriptionStart = <
+  ViewRequest extends RequestShape & { query: SubscriptionStartQuery },
+  RecordRequest extends BodyRequest<SubscriptionStartBody>,
+>(
+  view: RegisteredEntrypoint<ViewRequest, SubscriptionStartView>,
+  record: RegisteredEntrypoint<RecordRequest, SubscriptionStartResponse>,
+  opts: UseSubscriptionStartOptions = {},
+): SubscriptionStartControl => {
+  const viewRef = useRef(view)
+  viewRef.current = view
+  const recordRef = useRef(record)
+  recordRef.current = record
+  const [current, setCurrent] = useState<SubscriptionStartView | null>(null)
+  const [params, setParams] = useState<SubscriptionStartParams>({ planTitle: '' })
+  const [open, setOpen] = useState(false)
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState(false)
+  const asker = useMemo(() => makeAsker<[string, SubscriptionStartParams], SubscriptionStartView, string | null>({
+    load: async (planSku, next) => {
+      const answer = await viewRef.current.call(...argsOf<ViewRequest>({ query: { planSku } }))
+      setCurrent(answer)
+      setParams(next)
+      return answer
+    },
+    required: next => next.required,
+    skip: '',
+    show: () => { setError(false); setOpen(true) },
+  }), [])
+  const decline = useCallback(() => {
+    setOpen(false)
+    asker.settle(null)
+  }, [asker])
+  const onConfirm = useCallback(async (body: SubscriptionStartBody) => {
+    setPending(true)
+    setError(false)
+    try {
+      const response = reviveStartResponse(await recordRef.current.call(...argsOf<RecordRequest>({ body })))
+      setOpen(false)
+      asker.settle(response.startRequestId)
+    } catch {
+      setError(true)
+    } finally {
+      setPending(false)
+    }
+  }, [asker])
+  const ensure = useCallback(async (planSku: string, next: SubscriptionStartParams) => await asker.ask(planSku, next), [asker])
+  const onWithdraw = opts.onWithdraw
+  const dialog: SubscriptionStartDialogProps = {
+    open, view: current, planTitle: params.planTitle, price: params.price, pending, error, onConfirm,
+    onDecline: decline,
+    onOpenChange: next => { if (next) setOpen(true); else decline() },
+    uiLanguage: opts.uiLanguage,
+    links: opts.links,
+    onWithdraw: onWithdraw != null ? () => { decline(); onWithdraw() } : undefined,
+  }
+  return { ensure, view: current, dialog }
+}
+export interface DeclarationControl<Body, Receipt> {
+  /** Send the declaration; the revived receipt, or `null` when it failed (`error` holds why). */
+  submit: (body: Body) => Promise<Receipt | null>
+  receipt: Receipt | null
+  pending: boolean
+  error: unknown
+  /** Forget the receipt and the error — before the form is shown again. */
+  reset: () => void
+}
+/** The submit half both statutory functions share: one protocol, one receipt. */
+const useDeclaration = <Body, Request extends BodyRequest<Body>, Receipt extends DeclarationReceipt>(
+  entry: RegisteredEntrypoint<Request, Receipt>,
+): DeclarationControl<Body, Receipt> => {
+  const entryRef = useRef(entry)
+  entryRef.current = entry
+  const [receipt, setReceipt] = useState<Receipt | null>(null)
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState<unknown>(null)
+  const submit = useCallback(async (body: Body): Promise<Receipt | null> => {
+    setPending(true)
+    setError(null)
+    try {
+      const answer = reviveReceipt(await entryRef.current.call(...argsOf<Request>({ body })))
+      setReceipt(answer)
+      return answer
+    } catch (e) {
+      setError(e)
+      return null
+    } finally {
+      setPending(false)
+    }
+  }, [])
+  const reset = useCallback(() => {
+    setReceipt(null)
+    setError(null)
+  }, [])
+  return { submit, receipt, pending, error, reset }
+}
+export interface WithdrawalControl<Receipt extends DeclarationReceipt> extends DeclarationControl<WithdrawalBody, Receipt> {
+  /** In-app: the contracts that can still be withdrawn from; `null` before the first read. */
+  list: WithdrawalCandidateList | null
+  load: () => Promise<WithdrawalCandidateList | null>
+  /** Spread into a `WithdrawalForm` / `WithdrawalDialog` (with `mode` and `language`). */
+  form: {
+    list: WithdrawalCandidateList | null
+    pending: boolean
+    error: boolean
+    receipt: Receipt | null
+    onSubmit: (body: WithdrawalBody) => Promise<Receipt | null>
+  }
+}
+/**
+ * The withdrawal function over the `withdrawals` GET (in-app; `null` on the public page) and a
+ * `withdraw` POST — the account one answers a `WithdrawalReceipt`, the public one a
+ * `DeclarationReceipt`.
+ */
+export const useWithdrawal = <Request extends BodyRequest<WithdrawalBody>, Receipt extends DeclarationReceipt>(
+  list: RegisteredEntrypoint<{}, WithdrawalCandidateList> | null,
+  withdraw: RegisteredEntrypoint<Request, Receipt>,
+  opts: { enabled?: boolean } = {},
+): WithdrawalControl<Receipt> => {
+  const listRef = useRef(list)
+  listRef.current = list
+  const [candidates, setCandidates] = useState<WithdrawalCandidateList | null>(null)
+  const declaration = useDeclaration<WithdrawalBody, Request, Receipt>(withdraw)
+  const load = useCallback(async () => {
+    if (listRef.current == null) {
+      return null
+    }
+    try {
+      const next = reviveWithdrawalList(await listRef.current.call())
+      setCandidates(next)
+      return next
+    } catch {
+      return null
+    }
+  }, [])
+  useEffect(() => {
+    if (opts.enabled === true) void load()
+  }, [opts.enabled, load])
+  return {
+    ...declaration,
+    list: candidates,
+    load,
+    form: {
+      list: candidates,
+      pending: declaration.pending,
+      error: declaration.error != null,
+      receipt: declaration.receipt,
+      onSubmit: declaration.submit,
+    },
+  }
+}
+export interface CancellationControl<Receipt extends DeclarationReceipt> extends DeclarationControl<CancellationBody, Receipt> {
+  /** Spread into a `CancellationForm` (with `mode` and `language`). */
+  form: {
+    pending: boolean
+    error: boolean
+    receipt: Receipt | null
+    onSubmit: (body: CancellationBody) => Promise<Receipt | null>
+  }
+}
+/**
+ * The cancellation function over a `cancel` POST — the account one answers a
+ * `CancellationReceipt`, the public one a `DeclarationReceipt`.
+ */
+export const useCancellation = <Request extends BodyRequest<CancellationBody>, Receipt extends DeclarationReceipt>(
+  cancel: RegisteredEntrypoint<Request, Receipt>,
+): CancellationControl<Receipt> => {
+  const declaration = useDeclaration<CancellationBody, Request, Receipt>(cancel)
+  return {
+    ...declaration,
+    form: {
+      pending: declaration.pending,
+      error: declaration.error != null,
+      receipt: declaration.receipt,
+      onSubmit: declaration.submit,
+    },
+  }
+}

package/src/consumer/index.ts ADDED Viewed

@@ -0,0 +1,13 @@
+import '../i18n.js'
+export type * from './types.js'
+export * from './refusal.js'
+export * from './ensure.js'
+export * from './copy.js'
+export { LanguageToggle, LegalLinks, linksFor, useShownLanguage, useUiLanguage } from './legal.js'
+export type { LanguageToggleProps, LegalLinksProps, ShownLanguage } from './legal.js'
+export * from './performance-consent-dialog.js'
+export * from './subscription-start-dialog.js'
+export * from './withdrawal.js'
+export * from './cancellation.js'
+export * from './hooks.js'
+export * from './provider.js'

package/src/consumer/legal.tsx ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 }