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

package/src/types.ts

@@ -1,10 +1,150 @@
-import type { AmountCheckoutPolicy, CreateCheckoutResponse } from '@owlmeans/payment'
+import type { ReactNode } from 'react'
+import type { CallOptions, RequestShape } from '@owlmeans/entrypoint'
+import type {
+  AmountCheckoutPolicy, CapabilityView, CheckoutLimitView, CreateCheckoutResponse, EntitlementPlanView, LimitView,
+  PortalLinkBody, PriceEstimate, PriceEstimateBody,
+} from '@owlmeans/payment'
 
 export type CheckoutResult = CreateCheckoutResponse
 export interface AmountCheckoutDialogProps {
   open: boolean
   onOpenChange: (open: boolean) => void
+  /** The plan's policy — or one already narrowed for the entity (`AmountPolicyView.policy`). */
   policy: AmountCheckoutPolicy
   pending?: boolean
-  onConfirm: (amountMinor: number) => Promise<void> | void
+  /** Chosen amount and, where tax estimation collected it, the billing country. */
+  onConfirm: (amountMinor: number, country?: string) => Promise<void> | void
+  /** A live tax/currency estimate for the credit line — absent: the plain "tax at checkout" note. */
+  estimate?: PriceEstimateControl
+  /**
+   * What the entity may buy now (`AmountPolicyView.limit`). The dialog narrows `policy` with it
+   * through `narrowAmountPolicy` — presets above the maximum disappear, the default is clamped —
+   * shows a `CheckoutLimitNote`, and on `blocked` disables the input and the confirm button.
+   */
+  limit?: CheckoutLimitView | null
+  /** Legal text the application places right above the buttons (a withdrawal note, terms links). */
+  legalNote?: ReactNode
+}
+
+/** What `usePriceEstimate` returns: the latest answer, the chosen country, and its lifecycle. */
+export interface PriceEstimateControl {
+  estimate: PriceEstimate | null
+  /** ISO 3166-1 alpha-2, or `''` before a country is known. */
+  country: string
+  /** A request is in flight — including the first, silent one. */
+  loading: boolean
+  /** The last request failed; `estimate` is the previous good answer, if any. */
+  failed: boolean
+  /**
+   * The country is the entity's locked billing country (an answer with `locked` or `source:
+   * 'profile'`): a picker shows it disabled, and `onCountryChange` does nothing.
+   */
+  locked?: boolean
+  onCountryChange: (country: string) => void
+}
+
+export interface CheckoutLimitNoteProps {
+  /** `null`, or a limit that narrowed nothing, renders nothing. */
+  limit: CheckoutLimitView | null | undefined
+  /** Replaces the package's sentence for the limit's `reason` (`per-purchase`, `window`, `hold`). */
+  reasonLabel?: string | ((reason: string) => string | null | undefined)
+  className?: string
+}
+
+/** The request of a price-estimate protocol: its body is a `PriceEstimateBody`. */
+export type PriceEstimateRequest = RequestShape & { body: PriceEstimateBody }
+
+type PriceEstimateCall<Request extends PriceEstimateRequest> = Omit<Request, 'body'> & {
+  body?: Omit<Request['body'], 'country'>
+}
+
+/** A price-estimate protocol's call arguments with `body.country` left to `usePriceEstimate`. */
+export type PriceEstimateArguments<Request extends PriceEstimateRequest> = {} extends PriceEstimateCall<Request>
+  ? [request?: PriceEstimateCall<Request> & CallOptions]
+  : [request: PriceEstimateCall<Request> & CallOptions]
+
+/** A limit row plus what a UI derives from it. */
+export interface LimitStatus extends LimitView {
+  /** No room for one more unit — including a limit that is not included (`limit: 0`). */
+  exhausted: boolean
+  /**
+   * How full the limit is, clamped to `[0, 1]`. A `0` ceiling reads `1` once anything is used and
+   * `0` otherwise: the ratio says how full, `exhausted` says whether anything is left.
+   */
+  ratio: number
+}
+
+/**
+ * What a plan's status line says, in precedence order: an inactive or blocked status, paused,
+ * suspended, trial, past due, cancellation scheduled, free, renews, active.
+ */
+export type PlanStatusLineKind =
+  | 'created' | 'canceled' | 'expired' | 'ended' | 'blocked'
+  | 'paused' | 'suspended' | 'trial' | 'past-due' | 'cancel-scheduled'
+  | 'free' | 'renews' | 'active'
+
+/** How a status line should be coloured: entitled and fine, needs attention, revoked, or over. */
+export type PlanStatusTone = 'ok' | 'warning' | 'critical' | 'inactive'
+
+export interface PlanStatusLine {
+  kind: PlanStatusLineKind
+  tone: PlanStatusTone
+  /** The date the line names — trial end, cancellation, pause start or renewal. */
+  date?: Date
+}
+
+/** How a promo is inscribed: free until its end, kept by a grandfathered plan, or over. */
+export type PromoInscription = 'free-until' | 'grandfathered' | 'ended'
+
+/** The request of a portal protocol: its body is a `PortalLinkBody`. */
+export type PortalRequest = RequestShape & { body: PortalLinkBody }
+
+type PortalCall<Request extends PortalRequest> = Omit<Request, 'body'> & {
+  body?: Omit<Request['body'], 'flow'>
+}
+
+/** A portal protocol's call arguments with `body.flow` left to `usePortal`. */
+export type PortalArguments<Request extends PortalRequest> = {} extends PortalCall<Request>
+  ? [request?: PortalCall<Request> & CallOptions]
+  : [request: PortalCall<Request> & CallOptions]
+
+/** A plan offered next to the entity's own — an upgrade, a downgrade, a plan comparison column. */
+export interface PlanOffer {
+  sku: string
+  title: string
+  /** The price as the application formats it (`$20 / month`); the package never formats prices. */
+  priceLabel: string
+  highlight?: boolean
+}
+
+export interface PlanCardProps {
+  /** The entity's effective plan. */
+  plan: EntitlementPlanView
+  /** Render an offered plan instead; the status line then shows only when the offer is current. */
+  offer?: PlanOffer
+  /** Defaults to `offer.sku === plan.sku` when an offer is given. */
+  current?: boolean
+  pending?: boolean
+  actionLabel?: string
+  /** Called with the rendered sku (`offer.sku`, else `plan.sku`). */
+  onAction?: (sku: string) => Promise<void> | void
+  className?: string
+  children?: ReactNode
+}
+
+export interface LimitMeterProps {
+  limit: LimitView
+  label: string
+  /** Show when a window limit resets. Default `true`. */
+  showReset?: boolean
+  compact?: boolean
+  className?: string
+}
+
+export interface CapabilityListProps {
+  capabilities: CapabilityView[]
+  /** Product copy by capability `param`; a capability without a label is not rendered. */
+  labels: Record<string, string>
+  onlyGranted?: boolean
+  className?: string
 }

package/tests/consent-refusal.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test'
+import { ResilientError } from '@owlmeans/error'
+import { ApiStatusError } from '@owlmeans/api'
+import { ConsentKind, PerformanceConsentRequired, SubscriptionStartRequired } from '@owlmeans/payment'
+import {
+  ConsentDeclined, consentRefusalKindOf, isConsentDeclined, isConsentRefusal, isPerformanceConsentRefusal,
+} from '../src/consumer/refusal.js'
+
+const INCIDENT = '0b6f8a3e-8f0e-4b9f-9c55-2f1f0f6f2a11'
+const MARKER = 'payment:consumer-rights:performance-consent-required:1:2026-10-09T00:00:00.000Z'
+
+describe('isConsentRefusal', () => {
+  test('the class, fresh and rebuilt from its marshalled form', () => {
+    const fresh = new PerformanceConsentRequired({ pending: 1, deadline: new Date('2026-10-09T00:00:00Z') })
+    expect(isConsentRefusal(fresh)).toBe(true)
+    expect(consentRefusalKindOf(fresh)).toBe(ConsentKind.Performance)
+
+    const rebuilt = ResilientError.ensure(fresh.marshal())
+    expect(isConsentRefusal(rebuilt)).toBe(true)
+    expect(isPerformanceConsentRefusal(rebuilt)).toBe(true)
+  })
+
+  test('the marker in a message, in a type, and as a stored string', () => {
+    expect(isConsentRefusal(new Error(MARKER))).toBe(true)
+    expect(isConsentRefusal({ type: PerformanceConsentRequired.typeName, message: 'rebuilt elsewhere' })).toBe(true)
+    expect(isConsentRefusal(MARKER)).toBe(true)
+  })
+
+  test('a bare 428 — a production incident body — by its status alone', () => {
+    const bare = new ApiStatusError(428, INCIDENT)
+    expect(isConsentRefusal(bare)).toBe(true)
+    expect(consentRefusalKindOf(bare)).toBe('unknown')
+    expect(isPerformanceConsentRefusal(bare)).toBe(true)
+
+    // A development body keeps its class and gets the status stamped on it.
+    const stamped = Object.assign(new Error('something else'), { responseStatus: 428 })
+    expect(isConsentRefusal(stamped)).toBe(true)
+    expect(isConsentRefusal(`api:client:status:428:${INCIDENT}`)).toBe(true)
+  })
+
+  test('wrapped: in a cause, in an error field, and in a planning commit failure', () => {
+    expect(isConsentRefusal(new Error('the action failed', { cause: new ApiStatusError(428) }))).toBe(true)
+    expect(isConsentRefusal({ message: 'job failed', error: { message: MARKER } })).toBe(true)
+    // `CommitFailed` packs the refusal's text after its own marker.
+    expect(consentRefusalKindOf(new Error(`planning:commit-failed:t1:${MARKER}`))).toBe(ConsentKind.Performance)
+    // … or carries it as a string cause.
+    expect(isConsentRefusal({ message: 'planning:commit-failed:t1', cause: `api:client:status:428:${INCIDENT}` })).toBe(true)
+    expect(isConsentRefusal(new AggregateError([new Error('other'), new PerformanceConsentRequired({ pending: 2 })]))).toBe(true)
+  })
+
+  test('the subscription start is a consent refusal, but not the one the spend dialog answers', () => {
+    const start = new SubscriptionStartRequired('pro-monthly')
+    expect(isConsentRefusal(start)).toBe(true)
+    expect(consentRefusalKindOf(start)).toBe(ConsentKind.SubscriptionStart)
+    expect(isPerformanceConsentRefusal(start)).toBe(false)
+  })
+
+  test('anything else is not one — other statuses, plain failures, a decline, nothing at all', () => {
+    expect(isConsentRefusal(new ApiStatusError(409, INCIDENT))).toBe(false)
+    expect(isConsentRefusal(new ApiStatusError(402))).toBe(false)
+    expect(isConsentRefusal(new Error('network down'))).toBe(false)
+    expect(isConsentRefusal(new ConsentDeclined())).toBe(false)
+    expect(isConsentRefusal(null)).toBe(false)
+    expect(isConsentRefusal(undefined)).toBe(false)
+    expect(isConsentRefusal('just text')).toBe(false)
+
+    const loop: { message: string, cause?: unknown } = { message: 'loop' }
+    loop.cause = loop
+    expect(isConsentRefusal(loop)).toBe(false)
+  })
+})
+
+describe('ConsentDeclined', () => {
+  test('keeps its kind across a marshal and is told apart from a refusal', () => {
+    const declined = new ConsentDeclined(ConsentKind.Performance)
+    expect(isConsentDeclined(declined)).toBe(true)
+    expect(declined.kind).toBe(ConsentKind.Performance)
+
+    const rebuilt = ResilientError.ensure(declined.marshal())
+    expect(rebuilt).toBeInstanceOf(ConsentDeclined)
+    expect((rebuilt as ConsentDeclined).kind).toBe(ConsentKind.Performance)
+  })
+})

package/tests/consumer-hooks.spec.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from 'bun:test'
+import { createElement } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
+import { ApiStatusError } from '@owlmeans/api'
+import {
+  ConsumerRegion, PerformanceConsentRequired,
+  type CancellationBody, type CancellationReceipt, type PerformanceConsentBody, type PerformanceConsentResponse,
+  type PerformanceConsentView, type WithdrawalBody, type WithdrawalCandidateList, type WithdrawalReceipt,
+} from '@owlmeans/payment'
+import { makeAsker, makeConsentGate, passThroughGate } from '../src/consumer/ensure.js'
+import { useCancellation, usePerformanceConsent, useWithdrawal } from '../src/consumer/hooks.js'
+import { useConsentGate } from '../src/consumer/provider.js'
+import { ConsentDeclined } from '../src/consumer/refusal.js'
+
+const tick = async () => await new Promise(resolve => setTimeout(resolve, 0))
+
+interface View { required: boolean }
+
+const asker = (views: Array<View | Error>) => {
+  const shown: View[] = []
+  let loads = 0
+  const control = makeAsker<[], View, boolean>({
+    load: async () => {
+      const next = views[Math.min(loads, views.length - 1)]
+      loads++
+      if (next instanceof Error) throw next
+      return next
+    },
+    required: view => view.required,
+    show: view => { shown.push(view) },
+    skip: true,
+  })
+
+  return { control, shown, loads: () => loads }
+}
+
+describe('makeAsker — the ensure() state machine', () => {
+  test('answers true at once when nothing is required, without showing anything', async () => {
+    const { control, shown } = asker([{ required: false }])
+    expect(await control.ask()).toBe(true)
+    expect(shown).toHaveLength(0)
+  })
+
+  test('shows the view and answers what the person decides', async () => {
+    const accept = asker([{ required: true }])
+    const accepted = accept.control.ask()
+    await tick()
+    expect(accept.shown).toHaveLength(1)
+    expect(accept.control.waiting()).toBe(true)
+    accept.control.settle(true)
+    expect(await accepted).toBe(true)
+    expect(accept.control.waiting()).toBe(false)
+
+    const decline = asker([{ required: true }])
+    const declined = decline.control.ask()
+    await tick()
+    decline.control.settle(false)
+    expect(await declined).toBe(false)
+  })
+
+  test('a burst of calls shares ONE pending answer and one dialog', async () => {
+    const { control, shown, loads } = asker([{ required: true }])
+    const answers = [control.ask(), control.ask(), control.ask()]
+    await tick()
+    expect(shown).toHaveLength(1)
+    expect(loads()).toBe(1)
+    control.settle(true)
+    expect(await Promise.all(answers)).toEqual([true, true, true])
+
+    // Settled: the next call reads the view afresh.
+    const next = control.ask()
+    await tick()
+    expect(loads()).toBe(2)
+    control.settle(false)
+    expect(await next).toBe(false)
+  })
+
+  test('fails open: a view that cannot be read answers the skip value', async () => {
+    const { control, shown } = asker([new Error('network down')])
+    expect(await control.ask()).toBe(true)
+    expect(shown).toHaveLength(0)
+  })
+
+  test('settling with nothing waiting does nothing', () => {
+    const { control } = asker([{ required: true }])
+    expect(() => control.settle(true)).not.toThrow()
+    expect(control.waiting()).toBe(false)
+  })
+})
+
+describe('makeConsentGate — withConsent retries exactly once', () => {
+  const counted = (failures: unknown[]) => {
+    let calls = 0
+    const action = async () => {
+      const failure = failures[calls]
+      calls++
+      if (failure != null) throw failure
+      return 'done'
+    }
+
+    return { action, calls: () => calls }
+  }
+
+  test('no refusal: runs once and never asks', async () => {
+    let asked = 0
+    const gate = makeConsentGate(async () => { asked++; return true })
+    const { action, calls } = counted([])
+    expect(await gate.withConsent(action)).toBe('done')
+    expect([calls(), asked]).toEqual([1, 0])
+  })
+
+  test('a refusal (class or bare 428) asks with force, then retries once', async () => {
+    for (const refusal of [new PerformanceConsentRequired({ pending: 1 }), new ApiStatusError(428)]) {
+      const forced: unknown[] = []
+      const gate = makeConsentGate(async opts => { forced.push(opts?.force); return true })
+      const { action, calls } = counted([refusal])
+      expect(await gate.withConsent(action)).toBe('done')
+      expect([calls(), forced]).toEqual([2, [true]])
+    }
+  })
+
+  test('a decline throws ConsentDeclined and never retries', async () => {
+    const gate = makeConsentGate(async () => false)
+    const { action, calls } = counted([new ApiStatusError(428)])
+    await expect(gate.withConsent(action)).rejects.toBeInstanceOf(ConsentDeclined)
+    expect(calls()).toBe(1)
+  })
+
+  test('a second refusal propagates — never a loop', async () => {
+    let asked = 0
+    const gate = makeConsentGate(async () => { asked++; return true })
+    const second = new ApiStatusError(428, 'second')
+    const { action, calls } = counted([new ApiStatusError(428, 'first'), second])
+    await expect(gate.withConsent(action)).rejects.toBe(second)
+    expect([calls(), asked]).toEqual([2, 1])
+  })
+
+  test('any other failure propagates without asking', async () => {
+    let asked = 0
+    const gate = makeConsentGate(async () => { asked++; return true })
+    const failure = new ApiStatusError(402)
+    await expect(gate.withConsent(async () => { throw failure })).rejects.toBe(failure)
+    expect(asked).toBe(0)
+  })
+
+  test('the pass-through gate asks nothing and lets a refusal through', async () => {
+    expect(await passThroughGate.ensure()).toBe(true)
+    const refusal = new ApiStatusError(428)
+    await expect(passThroughGate.withConsent(async () => { throw refusal })).rejects.toBe(refusal)
+  })
+})
+
+/** Render hooks once on the server and hand back what they answered. */
+const answer = <T>(hook: () => T): T => {
+  let value: T | undefined
+  const Probe = () => { value = hook(); return null }
+  renderToStaticMarkup(createElement(Probe))
+  return value as T
+}
+
+const entry = <Request extends RequestShape, Response>(call: () => Promise<Response>) =>
+  ({ call }) as unknown as RegisteredEntrypoint<Request, Response>
+
+const consentView: PerformanceConsentView = {
+  required: true, region: ConsumerRegion.Eu, country: 'DE', language: 'de', trader: 'Trader', textVersion: 'v1',
+  copyVersion: 'c1', links: { billingTerms: 'https://example.test/terms' }, purchases: [], at: new Date(),
+}
+
+describe('consumer hooks — first render', () => {
+  test('usePerformanceConsent: unknown until read, the dialog closed and wired', () => {
+    const control = answer(() => usePerformanceConsent(
+      entry<{}, PerformanceConsentView>(async () => consentView),
+      entry<{ body: PerformanceConsentBody }, PerformanceConsentResponse>(async () => ({
+        consentId: 'c', consentedAt: new Date(), purchaseIds: [], mailed: true,
+      })),
+    ))
+    expect(control.required).toBeNull()
+    expect(control.view).toBeNull()
+    expect(control.dialog.open).toBe(false)
+    expect(control.dialog.pending).toBe(false)
+    expect(typeof control.ensure).toBe('function')
+    expect(typeof control.dialog.onConfirm).toBe('function')
+    expect(control.dialog.onWithdraw).toBeUndefined()
+  })
+
+  test('useConsentGate outside a provider is the pass-through gate', async () => {
+    const gate = answer(() => useConsentGate())
+    expect(gate.required).toBeNull()
+    expect(await gate.ensure()).toBe(true)
+  })
+
+  test('useWithdrawal and useCancellation start empty and expose their form props', () => {
+    const withdrawal = answer(() => useWithdrawal(
+      entry<{}, WithdrawalCandidateList>(async () => ({ candidates: [], language: 'en', links: { billingTerms: 'https://x.test' } })),
+      entry<{ body: WithdrawalBody }, WithdrawalReceipt>(async () => { throw new Error('not called') }),
+    ))
+    expect([withdrawal.list, withdrawal.receipt, withdrawal.pending, withdrawal.form.error]).toEqual([null, null, false, false])
+
+    const cancellation = answer(() => useCancellation(
+      entry<{ body: CancellationBody }, CancellationReceipt>(async () => { throw new Error('not called') }),
+    ))
+    expect([cancellation.receipt, cancellation.pending, cancellation.form.error]).toEqual([null, false, false])
+  })
+})