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

package/src/consumer/ensure.ts

@@ -0,0 +1,124 @@
+import { ConsentKind } from '@owlmeans/payment'
+import { ConsentDeclined, isPerformanceConsentRefusal } from './refusal.js'
+
+export interface AskerOptions<Args extends unknown[], View, Answer> {
+  /** Read the current view. */
+  load: (...args: Args) => Promise<View>
+  /** Whether the view asks the person anything. */
+  required: (view: View) => boolean
+  /** Show the view to the person (open the dialog). */
+  show: (view: View) => void
+  /**
+   * The answer when nothing needs asking — and when the read FAILS: the server's refusal stays
+   * the authority, and a flaky read must never block work that needs no consent.
+   */
+  skip: Answer
+}
+
+export interface Asker<Args extends unknown[], Answer> {
+  /** Read, and ask only when the view requires it. Concurrent calls share ONE pending answer. */
+  ask: (...args: Args) => Promise<Answer>
+  /** Answer the pending `ask` (the dialog confirmed or was declined); nothing when none waits. */
+  settle: (answer: Answer) => void
+  /** Whether an `ask` is waiting for the person. */
+  waiting: () => boolean
+}
+
+/**
+ * Read a view, show it when it asks for something, and answer once the person has — the state
+ * machine behind `usePerformanceConsent().ensure` and `useSubscriptionStart().ensure`, free of
+ * React so it is testable on its own. A burst of calls opens one dialog: they all get its answer.
+ */
+export const makeAsker = <Args extends unknown[], View, Answer>(
+  opts: AskerOptions<Args, View, Answer>,
+): Asker<Args, Answer> => {
+  let inflight: Promise<Answer> | null = null
+  let resolver: ((answer: Answer) => void) | null = null
+
+  const run = async (args: Args): Promise<Answer> => {
+    let view: View
+    try {
+      view = await opts.load(...args)
+    } catch {
+      return opts.skip
+    }
+    if (!opts.required(view)) {
+      return opts.skip
+    }
+
+    return await new Promise<Answer>(resolve => {
+      resolver = resolve
+      opts.show(view)
+    })
+  }
+
+  return {
+    ask: async (...args) => {
+      if (inflight == null) {
+        inflight = run(args).finally(() => {
+          inflight = null
+          resolver = null
+        })
+      }
+
+      return await inflight
+    },
+    settle: answer => {
+      const resolve = resolver
+      resolver = null
+      resolve?.(answer)
+    },
+    waiting: () => resolver != null,
+  }
+}
+
+export interface EnsureOptions {
+  /**
+   * Asked after the server refused with a 428 although the last answer said nothing was needed.
+   * The view is always read fresh; `force` records why the caller asks.
+   */
+  force?: boolean
+}
+
+export interface ConsentGate {
+  /**
+   * `true` when nothing needs consent or the person confirmed and it was recorded; `false` when
+   * they declined or closed the dialog. A failed read answers `true`. One pending answer is shared.
+   */
+  ensure: (opts?: EnsureOptions) => Promise<boolean>
+  /**
+   * Run `action`; when it is refused for the spend consent (`isPerformanceConsentRefusal` — the
+   * class, its marker, or a bare 428, also wrapped inside another error), ask with
+   * `ensure({ force: true })` and run it again exactly ONCE. A decline throws `ConsentDeclined`;
+   * a second refusal, or any other failure, propagates as it is.
+   */
+  withConsent: <T>(action: () => Promise<T>) => Promise<T>
+}
+
+/** A gate over an `ensure` — what `useConsentGate` answers inside a `PerformanceConsentProvider`. */
+export const makeConsentGate = (ensure: ConsentGate['ensure']): ConsentGate => ({
+  ensure,
+  withConsent: async <T>(action: () => Promise<T>): Promise<T> => {
+    try {
+      return await action()
+    } catch (e) {
+      if (!isPerformanceConsentRefusal(e)) {
+        throw e
+      }
+      if (!await ensure({ force: true })) {
+        throw new ConsentDeclined(ConsentKind.Performance)
+      }
+
+      return await action()
+    }
+  },
+})
+
+/**
+ * The gate outside any provider: nothing can be asked, so `ensure` answers `true` and a refusal
+ * propagates unchanged.
+ */
+export const passThroughGate: ConsentGate = {
+  ensure: async () => true,
+  withConsent: async action => await action(),
+}

package/src/consumer/fields.tsx

@@ -0,0 +1,89 @@
+import type { ReactNode } from 'react'
+import { cn } from '@/lib/utils'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+
+/** The shape the platform validates an e-mail address with (`@owlmeans/payment` `EmailSchema`). */
+export const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+$/
+
+export const isEmail = (value: string): boolean => value.length >= 3 && value.length <= 254 && EMAIL_PATTERN.test(value)
+
+export interface FieldProps {
+  id: string
+  label: string
+  value: string
+  onChange: (value: string) => void
+  error?: string | null
+  type?: 'text' | 'email' | 'date'
+  autoComplete?: string
+  disabled?: boolean
+  min?: string
+  /** A `data-*` hook for tests (`data-withdrawal-field="name"`). */
+  hook?: Record<string, string>
+  multiline?: boolean
+}
+
+export const Field = ({
+  id, label, value, onChange, error, type = 'text', autoComplete, disabled, min, hook, multiline = false,
+}: FieldProps) => <div className="grid gap-1.5">
+  <Label htmlFor={id}>{label}</Label>
+  {multiline
+    ? <textarea
+      id={id} value={value} disabled={disabled} rows={3} maxLength={2000} aria-invalid={error != null}
+      aria-describedby={error != null ? `${id}-error` : undefined} onChange={event => onChange(event.target.value)}
+      className={cn(
+        'border-input bg-background placeholder:text-muted-foreground w-full min-w-0 rounded-md border px-3 py-2 text-sm shadow-xs outline-none',
+        'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] disabled:opacity-50 aria-invalid:border-destructive',
+      )}
+      {...hook}
+    />
+    : <Input
+      id={id} type={type} value={value} disabled={disabled} autoComplete={autoComplete} min={min}
+      aria-invalid={error != null} aria-describedby={error != null ? `${id}-error` : undefined}
+      onChange={event => onChange(event.target.value)} {...hook}
+    />}
+  {error != null && <p id={`${id}-error`} className="text-destructive text-xs">{error}</p>}
+</div>
+
+export interface ChoiceProps {
+  id: string
+  name: string
+  checked: boolean
+  onSelect: () => void
+  disabled?: boolean
+  hook?: Record<string, string>
+  children: ReactNode
+}
+
+/** One option of a radio group — a native radio, so the group needs no extra primitive. */
+export const Choice = ({ id, name, checked, onSelect, disabled, hook, children }: ChoiceProps) => <label
+  htmlFor={id}
+  className={cn('flex cursor-pointer items-start gap-3 rounded-md border p-3 text-sm', checked && 'border-primary bg-muted/30')}
+>
+  <input
+    id={id} type="radio" name={name} checked={checked} disabled={disabled} onChange={onSelect}
+    className="accent-primary mt-0.5 size-4 shrink-0" {...hook}
+  />
+  <span className="grid gap-0.5">{children}</span>
+</label>
+
+export interface HoneypotProps {
+  id: string
+  label: string
+  value: string
+  onChange: (value: string) => void
+}
+
+/**
+ * A field a person never sees or reaches: off screen, out of the tab order and hidden from
+ * assistive technology, with a plausible name a form-filling bot completes. A filled one marks the
+ * declaration as a bot's, which the server answers like any other (it never says so).
+ */
+export const Honeypot = ({ id, label, value, onChange }: HoneypotProps) => <div
+  aria-hidden="true" data-honeypot=""
+  style={{ position: 'absolute', left: '-10000px', top: 'auto', width: 1, height: 1, overflow: 'hidden' }}
+>
+  <label htmlFor={id}>{label}</label>
+  <input id={id} name="website" type="text" tabIndex={-1} autoComplete="off" value={value}
+    onChange={event => onChange(event.target.value)} />
+</div>

package/src/consumer/hooks.ts

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

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