@pithy-sh/payments 0.1.0

package/src/client/hooks.ts

@@ -0,0 +1,590 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  type EntitlementView,
+  getEntitlements,
+  openBillingPortal,
+  openStoreSubscriptions,
+  type PaddleCheckoutHandoff,
+  type PaymentsClientOptions,
+  type PaymentsClientRail,
+  type PaymentsFailure,
+  type PaymentsHostedRail,
+  type PurchaseView,
+  restorePurchases,
+  startCheckout,
+  submitPurchase,
+} from "./api";
+import { openPaddleCheckout, type PaddleCheckoutOptions } from "./checkout";
+import {
+  loadPaddle,
+  type PaddleJs,
+  type PaddleOptions,
+  type PaddlePriceQuery,
+  type PaddleSetup,
+  type PricePreview,
+  previewPrices,
+  priceQueryKey,
+} from "./paddle";
+
+/**
+ * The headless client surface: six hooks a paywall, a pricing page, a subscription screen, and a route
+ * guard are built out of.
+ *
+ * **They live here rather than in a scaffolded `.tsx` on purpose.** `pithy ui add` writes a file once and
+ * may never rewrite it, which is the right ownership rule and is exactly why a frozen paywall ages badly:
+ * store rules move — price-change consent prompts, external purchase link entitlements, subscription
+ * management requirements — and a purchase flow living in the adopter's repo is one Pithy cannot fix for
+ * them. So the hook owns the calls, the redirect-and-return dance, the error mapping and the entitlement
+ * reads, and upgrades with a minor release; the stub renders and styles, calling these rather than
+ * reimplementing them. Principle 3, applied to the client.
+ *
+ * `react` is an **optional** peer dependency, and this module is reachable only by its own deep path
+ * (`@pithy-sh/payments/src/client/hooks`). It is deliberately absent from `src/index.ts` — that is what
+ * keeps React out of a Worker bundle that composes payments.
+ *
+ * Cookie/session throughout, because `./api` is: same-origin, `credentials: "include"`, no token in web
+ * storage, no bearer header. Bearer stays the mobile path.
+ *
+ * **Nothing here throws, and nothing here is a security boundary.** A refusal is a message to render, and
+ * the server's `requireEntitlement()` is the gate; these exist so a user is sent to the paywall rather than
+ * shown a 403.
+ *
+ * **A failed read is not an answer, and each hook says so in the way its caller needs.** `useEntitlement`
+ * is a lock, so it fails closed — `entitled` stays false — and reports `readFailure` beside it so a screen
+ * can tell "you don't have Pro" from "we couldn't check". `useSubscription` *names the plan*, where failing
+ * closed would be a lie: an empty entitlement list is a positive claim that the account is on the free
+ * floor, so it reports the failure instead of rendering one.
+ */
+
+/**
+ * Hold the newest value without making it a dependency.
+ *
+ * Every hook below takes an options object, and a caller writing `useEntitlement("pro", { basePath })`
+ * inline creates a new object every render. Depending on it would re-run the effect forever. So the
+ * effects depend on the one thing that can actually change the request — `basePath`, a string — and read
+ * the rest through this.
+ */
+function useLatest<T>(value: T): { current: T } {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+
+/** Whether a component is still mounted. Every async completion checks it before setting state. */
+function useLive(): { current: boolean } {
+  const live = useRef(true);
+  useEffect(() => {
+    live.current = true;
+    return () => {
+      live.current = false;
+    };
+  }, []);
+  return live;
+}
+
+/** What {@link useEntitlement} gives a screen. */
+export interface UseEntitlement {
+  /** Whether the caller holds the key right now. `false` while loading — a paywall fails closed. */
+  entitled: boolean;
+  /** Whether the first read is still in flight. */
+  loading: boolean;
+  /**
+   * Why the last read could not be made, or null.
+   *
+   * Distinct from `entitled: false`, which is an answer. This is the absence of one, and a screen that
+   * says "you don't have Pro" and one that says "we couldn't check" are different screens. `entitled`
+   * still fails closed while this is set — the lock holds, it just admits it is guessing.
+   */
+  readFailure: PaymentsFailure | null;
+  /** Re-read. Call it after a purchase completes. */
+  refresh: () => void;
+}
+
+/**
+ * Whether the caller holds `key`.
+ *
+ * Starts `false`, always. Starting `true` would flash the paid screen to everyone for one frame, which is
+ * both a leak and worse to look at than a spinner. An unreachable Worker reads as not entitled for the
+ * same reason: the server check is the boundary, so failing closed here costs nothing.
+ *
+ * The failing-closed happens *here*, visibly, rather than inside {@link getEntitlements} — a lock is a
+ * refusal and can carry an escape route on it, which is what `readFailure` is. A caller that names the
+ * plan instead of locking it must not inherit this choice; see {@link useSubscription}.
+ */
+export function useEntitlement(key: string, options?: PaymentsClientOptions): UseEntitlement {
+  const [entitled, setEntitled] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [readFailure, setReadFailure] = useState<PaymentsFailure | null>(null);
+  const latest = useLatest(options);
+  const live = useLive();
+  const basePath = options?.basePath;
+
+  const refresh = useCallback(() => {
+    setLoading(true);
+    // `basePath` is read here rather than off the ref, so it is a real dependency: it is the one option
+    // that changes the request, and a project that moved its routes must re-read. Everything else comes
+    // through the ref, which is why an inline options object does not restart this on every render.
+    void getEntitlements({ ...latest.current, basePath }).then((result) => {
+      if (!live.current) return;
+      // Fail closed on the answer, report the failure beside it. Both, not either.
+      setEntitled(result.ok && result.value.some((entitlement) => entitlement.key === key && entitlement.granted));
+      setReadFailure(result.ok ? null : result.failure);
+      setLoading(false);
+    });
+  }, [key, basePath, latest, live]);
+
+  useEffect(refresh, [refresh]);
+
+  return { entitled, loading, readFailure, refresh };
+}
+
+/** What {@link useSubscription} gives a subscription screen. */
+export interface UseSubscription {
+  /** Every entitlement the caller holds, as the server resolved it. */
+  entitlements: readonly EntitlementView[];
+  /** Whether any entitlement grants right now — the "is this account paid" answer, without naming a key. */
+  subscribed: boolean;
+  /** Whether the read is in flight. */
+  loading: boolean;
+  /** Re-read. */
+  refresh: () => void;
+  /** Open Stripe's Billing Portal for this caller. Resolves once the browser has been sent, or refused. */
+  manage: () => Promise<void>;
+  /** Send the visitor to a store's own subscription page — the only management a web page can offer there. */
+  manageStore: (rail: "apple" | "google") => void;
+  /** Whether a portal session is being created. */
+  managing: boolean;
+  /** The last refusal of something the subscriber *asked for* — opening the portal — or null. */
+  failure: PaymentsFailure | null;
+  /**
+   * Why the entitlements could not be read, or null. Kept apart from `failure` deliberately.
+   *
+   * This screen names the plan, and free is the floor of every ladder: an empty `entitlements` is a
+   * positive claim that the account is on the cheapest tier. Rendering that from a read that never
+   * happened tells a paying customer they are on Free and offers to sell them what they have. So a
+   * failed read leaves `entitlements` empty *and* says so here, and a screen must consult this before
+   * it renders a tier name. Collapsing it into `failure` would let a stale portal refusal mask it.
+   */
+  readFailure: PaymentsFailure | null;
+}
+
+/**
+ * The caller's standing entitlements, and the one action a subscriber needs.
+ *
+ * Managing a subscription is the store's job, not Pithy's — Stripe's Billing Portal owns cancellation,
+ * card changes and plan moves, under Stripe's own rules and its own compliance. Apple and Google
+ * subscriptions are managed in their own apps, which a web screen can only link to.
+ */
+export function useSubscription(options?: PaymentsClientOptions): UseSubscription {
+  const [entitlements, setEntitlements] = useState<readonly EntitlementView[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [managing, setManaging] = useState(false);
+  const [failure, setFailure] = useState<PaymentsFailure | null>(null);
+  const [readFailure, setReadFailure] = useState<PaymentsFailure | null>(null);
+  const latest = useLatest(options);
+  const live = useLive();
+  const basePath = options?.basePath;
+
+  const refresh = useCallback(() => {
+    setLoading(true);
+    // `basePath` explicitly, for the reason `useEntitlement` gives: it is the option that changes the
+    // request, so it has to be a dependency rather than something read off a ref.
+    void getEntitlements({ ...latest.current, basePath }).then((result) => {
+      if (!live.current) return;
+      // A refusal leaves the previous list alone rather than blanking it — the same rule `usePurchase`
+      // follows. What a screen must not do is read the untouched list as this account's current plan,
+      // which is what `readFailure` is there to stop.
+      if (result.ok) setEntitlements(result.value);
+      setReadFailure(result.ok ? null : result.failure);
+      setLoading(false);
+    });
+  }, [basePath, latest, live]);
+
+  useEffect(refresh, [refresh]);
+
+  const manage = useCallback(async () => {
+    setManaging(true);
+    setFailure(null);
+    const refused = await openBillingPortal(latest.current);
+    if (!live.current) return;
+    setManaging(false);
+    // On success the browser is already leaving; setting state is harmless and keeps the two paths one shape.
+    if (refused) setFailure(refused);
+  }, [latest, live]);
+
+  const manageStore = useCallback(
+    (rail: "apple" | "google") => {
+      // Synchronous, and it can only fail by there being no browser — nothing to await and nothing to
+      // report that a screen could act on.
+      openStoreSubscriptions(rail, latest.current);
+    },
+    [latest],
+  );
+
+  return {
+    entitlements,
+    subscribed: entitlements.some((entitlement) => entitlement.granted),
+    loading,
+    refresh,
+    manage,
+    manageStore,
+    managing,
+    failure,
+    readFailure,
+  };
+}
+
+/** What {@link useCheckout} gives a paywall's buy button. */
+export interface UseCheckout {
+  /**
+   * Start checkout for a product.
+   *
+   * `rail` is only needed for a product sold on **more than one** hosted rail, where the server refuses to
+   * choose on the buyer's behalf. A product sold on one needs no argument.
+   */
+  start: (productId: string, options?: { rail?: PaymentsHostedRail; discountCode?: string }) => Promise<void>;
+  /** Whether a session is being created. Disable the button on it — a double click is a double session. */
+  starting: boolean;
+  /** The last refusal, or null. Cleared at the start of every attempt. */
+  failure: PaymentsFailure | null;
+  /**
+   * The handoff to open with Paddle.js, or null — set only on a rail with nowhere to navigate to.
+   *
+   * Null on a redirect rail, because the browser has already left and there is nothing for a screen to
+   * hold. Pass it to {@link usePaddleCheckout}, which opens it; a screen that never composes Paddle reads
+   * null forever and renders exactly as it did before this field existed.
+   */
+  handoff: PaddleCheckoutHandoff | null;
+}
+
+/**
+ * The web purchase path: start a checkout, and go wherever that rail goes.
+ *
+ * Apple and Google purchases happen inside a store SDK before any server hears of them, so there is no
+ * session for Pithy to create and no browser flow to start — a web paywall lists those products, it does
+ * not sell them. Stripe's and Lemon Squeezy's hosted checkouts need no SDK script and no publishable key
+ * in the page: the server mints a session, this navigates to it, and the store owns everything in between.
+ *
+ * Paddle is the one that does not leave. This hook does the same work for it — the server call, the
+ * refusal — and stops at the handoff, because opening it belongs where the container is. That is
+ * {@link usePaddleCheckout}.
+ */
+export function useCheckout(options?: PaymentsClientOptions): UseCheckout {
+  const [starting, setStarting] = useState(false);
+  const [failure, setFailure] = useState<PaymentsFailure | null>(null);
+  const [handoff, setHandoff] = useState<PaddleCheckoutHandoff | null>(null);
+  const latest = useLatest(options);
+  const live = useLive();
+
+  const start = useCallback(
+    async (productId: string, choices?: { rail?: PaymentsHostedRail; discountCode?: string }) => {
+      setStarting(true);
+      setFailure(null);
+      setHandoff(null);
+      const outcome = await startCheckout(
+        { productId, rail: choices?.rail, discountCode: choices?.discountCode },
+        latest.current,
+      );
+      if (!live.current) return;
+      setStarting(false);
+      // Exhaustive on `kind` rather than truthiness. `left` is the browser already going; `paddle` is the
+      // one outcome a screen must act on; `refused` is the only one that is a failure. Reading any of the
+      // three as another is how a buyer ends up on a page whose button did nothing.
+      if (outcome.kind === "refused") setFailure(outcome.failure);
+      else if (outcome.kind === "paddle") setHandoff(outcome.handoff);
+    },
+    [latest, live],
+  );
+
+  return { start, starting, failure, handoff };
+}
+
+/** What {@link usePaddleCheckout} gives the screen that composes Paddle. */
+export interface UsePaddleCheckout {
+  /**
+   * Whether this handoff needs a container on the page.
+   *
+   * Read it to render one, and render it unconditionally beside the button rather than deciding for
+   * yourself: the mode is `paddle.checkout` in the project's config, resolved by the server, so a project
+   * that switches from `overlay` to `inline` must not also have to edit a screen it was given a year ago.
+   */
+  inline: boolean;
+  /** Whether the checkout is being opened — the script may still be loading. */
+  opening: boolean;
+  /** Why it could not be opened, or null. */
+  failure: PaymentsFailure | null;
+}
+
+/**
+ * Open the handoff {@link useCheckout} produced, with Paddle.js, over this page or inside it.
+ *
+ * **In an effect, and that is the whole reason this is a hook rather than a line in a click handler.**
+ * Inline checkout renders into an element the screen provides, and Paddle finds it by class name at the
+ * moment `open` is called. Called from the handler that starts the checkout, the container React is about
+ * to render does not exist yet — and what Paddle does then is throw `TypeError: Cannot read properties of
+ * undefined (reading 'appendChild')` out of the click, which is not a sentence anyone can act on. An
+ * effect runs after the commit that revealed the container, so the element is there.
+ *
+ * One open per handoff. `start` mints a new transaction on every attempt, so the transaction id is what a
+ * fresh attempt looks like; a re-render with the same handoff must not open a second checkout over the
+ * first — and neither must a second *mount* of the same one. React's `StrictMode` runs every effect,
+ * cleans it up and runs it again, and that is the mode `pithy ui add` scaffolds: `client.tsx` wraps the
+ * router in it. So the transaction that has been opened is remembered, rather than the effect trusting
+ * that it runs once. The remembered id is the last one opened, not a flag — a buyer who closed the
+ * overlay and clicked Buy again arrives with a new transaction, and that one must open.
+ */
+export function usePaddleCheckout(
+  handoff: PaddleCheckoutHandoff | null,
+  options?: PaddleCheckoutOptions,
+): UsePaddleCheckout {
+  const [opening, setOpening] = useState(false);
+  const [failure, setFailure] = useState<PaymentsFailure | null>(null);
+  const latest = useLatest(options);
+  const latestHandoff = useLatest(handoff);
+  const live = useLive();
+  const transactionId = handoff?.transactionId;
+  /** The transaction this hook has already opened, so a second effect pass over it opens nothing. */
+  const opened = useRef<string | null>(null);
+
+  // `transactionId` stands in for the handoff, the way `priceQueryKey` stands in for a query: the object
+  // is rebuilt by `useCheckout` on every attempt and identity would be a fine dependency today, but a
+  // screen that builds one inline would then reopen the checkout on every render.
+  useEffect(() => {
+    const current = latestHandoff.current;
+    if (transactionId === undefined || current === null) return;
+    // StrictMode's second pass, or any remount holding the same handoff. One click bought one checkout.
+    if (opened.current === transactionId) return;
+    opened.current = transactionId;
+    setOpening(true);
+    setFailure(null);
+    void openPaddleCheckout(current, latest.current).then((refused) => {
+      if (!live.current) return;
+      setOpening(false);
+      setFailure(refused);
+    });
+  }, [transactionId, latest, latestHandoff, live]);
+
+  return { inline: handoff?.displayMode === "inline", opening, failure };
+}
+
+/** What {@link usePurchase} gives the screen that submits receipts. */
+export interface UsePurchase {
+  /** Submit one receipt for verification. */
+  submit: (rail: PaymentsClientRail, receipt: string) => Promise<void>;
+  /** Submit a store account's whole history on one rail — Restore Purchases. */
+  restore: (rail: PaymentsClientRail, receipts: readonly string[]) => Promise<void>;
+  /** The purchase the last successful submission projected, or null. */
+  purchase: PurchaseView | null;
+  /** The caller's entitlements as of the last successful write. */
+  entitlements: readonly EntitlementView[];
+  /** Whether a submission is in flight. */
+  busy: boolean;
+  /** The last refusal, or null. */
+  failure: PaymentsFailure | null;
+}
+
+/**
+ * Submitting receipts — the path that exists so a buyer sees their entitlement now rather than when the
+ * webhook lands.
+ *
+ * On the web that is the Stripe return: the success URL carries the Checkout Session id, and posting it
+ * here projects the purchase at once. On a native client it is the store SDK's transaction, and `restore`
+ * is Restore Purchases. Dropping either call costs nothing — the webhook produces the identical row, and
+ * the write is idempotent on `(rail, providerTransactionId)`.
+ *
+ * A refusal leaves `purchase` and `entitlements` exactly as they were. Clearing them would flicker a
+ * paywall back over a feature the user already owns, on nothing more than a failed second submission.
+ */
+export function usePurchase(options?: PaymentsClientOptions): UsePurchase {
+  const [purchase, setPurchase] = useState<PurchaseView | null>(null);
+  const [entitlements, setEntitlements] = useState<readonly EntitlementView[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<PaymentsFailure | null>(null);
+  const latest = useLatest(options);
+  const live = useLive();
+
+  const submit = useCallback(
+    async (rail: PaymentsClientRail, receipt: string) => {
+      setBusy(true);
+      setFailure(null);
+      const result = await submitPurchase({ rail, receipt }, latest.current);
+      if (!live.current) return;
+      setBusy(false);
+      if (!result.ok) {
+        setFailure(result.failure);
+        return;
+      }
+      setPurchase(result.value.purchase);
+      setEntitlements(result.value.entitlements);
+    },
+    [latest, live],
+  );
+
+  const restore = useCallback(
+    async (rail: PaymentsClientRail, receipts: readonly string[]) => {
+      setBusy(true);
+      setFailure(null);
+      const result = await restorePurchases({ rail, receipts }, latest.current);
+      if (!live.current) return;
+      setBusy(false);
+      if (!result.ok) {
+        setFailure(result.failure);
+        return;
+      }
+      setPurchase(result.value.purchases[0] ?? null);
+      setEntitlements(result.value.entitlements);
+    },
+    [latest, live],
+  );
+
+  return { submit, restore, purchase, entitlements, busy, failure };
+}
+
+/** What {@link usePaddle} gives a screen that has to talk to Paddle.js directly. */
+export interface UsePaddle {
+  /** The initialized Paddle.js, or null while it loads and after it fails. */
+  paddle: PaddleJs | null;
+  /** Whether the load is in flight. False forever when there is no Paddle rail to load. */
+  loading: boolean;
+  /** Why it could not load, or null. */
+  failure: PaymentsFailure | null;
+}
+
+/**
+ * Paddle.js, loaded once per page.
+ *
+ * `setup` takes null so a screen never has to guard a hook: `paymentsConfig.paddle` is null when the
+ * rail is off, and passing that through reads as "nothing to load" rather than as a failure. A pricing
+ * page for a project that does not sell through Paddle renders its own empty state; it does not show an
+ * error about a provider it never asked for.
+ *
+ * Loading is the module's job, not this hook's — mounting two components that both call it produces one
+ * script and one `Initialize`, because {@link loadPaddle} remembers the page's one load. This is the
+ * React-shaped view of it: a state a screen can render.
+ */
+export function usePaddle(setup: PaddleSetup | null, options?: PaddleOptions): UsePaddle {
+  const [paddle, setPaddle] = useState<PaddleJs | null>(null);
+  const [loading, setLoading] = useState(setup !== null);
+  const [failure, setFailure] = useState<PaymentsFailure | null>(null);
+  const latest = useLatest(options);
+  const live = useLive();
+  // The two fields, not the object: a screen writing `usePaddle(paymentsConfig.paddle)` passes a stable
+  // reference today, and one writing an object literal must not restart the load every render.
+  const clientToken = setup?.clientToken;
+  const environment = setup?.environment;
+
+  useEffect(() => {
+    if (clientToken === undefined || environment === undefined) {
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    void loadPaddle({ clientToken, environment }, latest.current).then((result) => {
+      if (!live.current) return;
+      setPaddle(result.ok ? result.value : null);
+      setFailure(result.ok ? null : result.failure);
+      setLoading(false);
+    });
+  }, [clientToken, environment, latest, live]);
+
+  return { paddle, loading, failure };
+}
+
+/** What {@link usePricePreview} gives a pricing screen. */
+export interface UsePricePreview {
+  /**
+   * What Paddle quoted this visitor, or null.
+   *
+   * Null while the first quote is in flight and null after a failure — **never a fallback figure.** A
+   * hardcoded price behind a failed lookup is the exact defect this hook exists to remove: it is wrong
+   * in every country whose tax convention differs from the one it was written in, and it is wrong
+   * silently. A page with no price and an honest sentence is worse than a right price and better than a
+   * wrong one.
+   */
+  preview: PricePreview | null;
+  /** Whether a quote is in flight. True on the first render, so a screen can hold the space. */
+  loading: boolean;
+  /** Why the last quote could not be made, or null. */
+  failure: PaymentsFailure | null;
+  /** Ask again. */
+  refresh: () => void;
+}
+
+/**
+ * What this visitor pays, read from Paddle for this visitor.
+ *
+ * **No price string appears in any screen this kit ships.** That is the whole contract. The figures come
+ * from Paddle, rendered by Paddle for the visitor's country — which is the only way one page can quote
+ * $5.44 in New York, $5.75 in Chicago, $5.00 in Berlin including €0.80 of VAT, and ¥725 in Tokyo without
+ * a table of tax rates aging in somebody's repository.
+ *
+ * `query` may be written inline. The effect depends on {@link priceQueryKey} rather than on the object,
+ * so an object literal re-created on every render re-quotes when the request changed and not before.
+ *
+ * A failure clears the previous quote rather than leaving it. The other hooks here keep their last good
+ * value on a refusal, and this one deliberately does not: a re-quote happens because the *request*
+ * changed, so the value it would be keeping is a price for something else.
+ *
+ * **Only the latest quote is rendered, whichever answers first.** Two previews can be in flight at once —
+ * an anonymous visitor's location resolves under the query, or a country picker moves — and the slower
+ * one landing last would otherwise win, putting a price for an address the visitor has left on the one
+ * screen whose entire job is showing a correct one. Superseded answers are *ignored*, not canceled:
+ * Paddle.js's `PricePreview` takes no `AbortSignal` and hands back a bare promise, so there is nothing to
+ * cancel and ignoring it is the whole of the fix. A superseded refusal is ignored the same way, which is
+ * what stops a dead request blanking a price the visitor is already reading.
+ */
+export function usePricePreview(
+  setup: PaddleSetup | null,
+  query: PaddlePriceQuery,
+  options?: PaddleOptions,
+): UsePricePreview {
+  const [preview, setPreview] = useState<PricePreview | null>(null);
+  const [loading, setLoading] = useState(setup !== null);
+  const [failure, setFailure] = useState<PaymentsFailure | null>(null);
+  const latest = useLatest(options);
+  const latestQuery = useLatest(query);
+  const live = useLive();
+  const clientToken = setup?.clientToken;
+  const environment = setup?.environment;
+  const queryKey = priceQueryKey(query);
+  /**
+   * Which quote is the current one.
+   *
+   * A counter rather than a comparison against `queryKey`, because two quotes for the *same* query race
+   * too — a screen calling `refresh` twice is the ordinary way to get there — and a key would read those
+   * two as one and let either win. Every ask takes the next number; only the holder of the last one
+   * issued may write state.
+   */
+  const issued = useRef(0);
+
+  // `queryKey` is a dependency the body never reads, and that is the design. It is what makes "the request
+  // changed" a value React can compare — the query itself is an object literal rebuilt every render, and
+  // depending on that would quote forever. Reading the key back inside would mean parsing it, which is how
+  // a serialization becomes a second source of truth for the thing it serializes.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: queryKey stands in for the query, deliberately.
+  const refresh = useCallback(() => {
+    if (clientToken === undefined || environment === undefined) {
+      setLoading(false);
+      return;
+    }
+    const ticket = ++issued.current;
+    setLoading(true);
+    void previewPrices({ clientToken, environment }, latestQuery.current, latest.current).then((result) => {
+      if (!live.current) return;
+      // A superseded answer is not a late answer to render, it is an answer to a question nobody is
+      // asking any more. It writes nothing at all — not the price, not the failure, and not `loading`,
+      // which still belongs to the quote that is out.
+      if (ticket !== issued.current) return;
+      setPreview(result.ok ? result.value : null);
+      setFailure(result.ok ? null : result.failure);
+      setLoading(false);
+    });
+  }, [clientToken, environment, queryKey, latest, latestQuery, live]);
+
+  useEffect(refresh, [refresh]);
+
+  return { preview, loading, failure, refresh };
+}