@civitai/blocks-react 0.58.1 → 0.60.0

package/README.md

@@ -469,6 +469,48 @@ const { purchased, newBalance } = await openPurchaseModal(suggestedAmount);
 if (purchased) { /* retry the generation */ }
 ```
 
+### `useGoodPurchase()`
+
+Sell a **digital good** — a manifest-declared entitlement the platform sells to the viewer for Buzz on your app's behalf. Requires the `goods:purchase:self` scope **and** a `goods` entry in your manifest; without both the endpoint answers 404.
+
+```tsx
+const { purchase, loading, error } = useGoodPurchase();
+const { entitlement } = await purchase(
+  { goodId: 'extra-slots', expectedPriceBuzz: 250 },
+  { topUpOnInsufficientFunds: true },
+);
+```
+
+🔴 **The platform renders no confirmation for the purchase itself** — this is a plain authed POST on the block token, so whatever the viewer confirms is *your* UI. Spend is bounded by the manifest-reviewed price and the viewer's daily cap, but a good can be priced near that cap where a tip cannot. Show the price and require an explicit action.
+
+`{ topUpOnInsufficientFunds: true }` opens `useBuzzPurchase()` on an `insufficient_funds` refusal and retries **once with the same idempotency key** — but only if the viewer actually bought Buzz. **Pass `expectedPriceBuzz` with it**, or the modal opens with no suggested amount and the retry can re-refuse after real fiat was spent. It keys on the *reason*, never on "the call failed", so it never offers Buzz for a failure Buzz cannot fix.
+
+Refusals reject with a `GoodPurchaseRefusal` carrying `status` and, where the server sends one, `reason`. `reason` is **`undefined`** for the endpoint's own refusals (404, 429, daily-cap 400, every idempotency refusal) — only service-level ones populate it, so always fall back to `status` and `message`.
+
+Two rejections are **not** refusals, and `name` tells them apart: the 30s bound rejects with a plain `Error` naming the timeout — a real failure, the charge may have landed, retry with the **same** `idempotencyKey` — while an unmount rejects with `name === 'AbortError'`, the usual signal that the component navigated away and there is nothing to report. That split is decided by the **abort state**, so it holds wherever the abort lands, the body read included. The one exception runs the other way: a refusal the hook had already parsed stays a `GoodPurchaseRefusal` even if an abort fires in the same tick — `reason` is worth more than the abort wrapper. So ignoring `AbortError` never swallows a refusal or a timeout.
+
+### `useEntitlements()`
+
+What the viewer owns **from this app** — the read half of the goods rail. Scope `goods:read:self`, which is consent-exempt: the reply is scoped server-side to your own app, so a read-only block needs no purchase power and triggers no re-consent prompt.
+
+```tsx
+function PaidFeature() {
+  const { owns, loading, error, unauthenticated, refetch } = useEntitlements();
+  if (loading) return <Spinner />;
+  if (unauthenticated) return <SignInToBuy />;        // a logged-out viewer
+  if (error) return <RetryNotice onRetry={refetch} />; // NOT "you own nothing"
+  return owns('extra-slots') ? <Unlocked /> : <BuyButton onDone={refetch} />;
+}
+```
+
+🔴 **`owns()` returns `false` when the viewer owns nothing AND when the read failed**, so never gate paid content on it alone — check `loading`, `unauthenticated` and `error` first, in that order. A block that paywalls on `!owns(id)` takes away something the viewer paid for on every transient failure. `unauthenticated` exists because a **page** app is a public surface, so a logged-out viewer is the common path rather than an edge.
+
+🔴 **`unauthenticated` is derived from the viewer, not from a response.** It is `isSignedIn(useBlockContext().viewer) === false` once `BLOCK_INIT` has landed — so it is known *before* any request, and an anonymous viewer costs **no round trip**: the hook skips the GET entirely and settles with `error === null`, because nothing failed. It stays `false` until init lands (a pre-init viewer is *unknown*, not absent), so a block that never gets embedded reaches its host-origin error rather than a sign-in screen.
+
+🔴 **No 403 is ever read as "not signed in"** — and a predicate that tried to be was **dead code**. The endpoint runs under `withBlockScope(…, { requiredScope: 'goods:read:self' })`, whose `:self` arm rejects an anonymous subject as `code: 'context_binding'`, so there is no reachable uncoded 403 on this route; keying on `context_binding` instead would be worse, since the same code covers a wrong `modelId`. Every 403 therefore reaches `error` with the server's own wording — including the one you will actually hit, `insufficient_scope`, a manifest that forgot `goods:read:self`. Read `error.message`, not the status.
+
+Call `refetch()` after a successful purchase to reflect it without a remount.
+
 ### `useBuzzBalance()`
 
 The signed-in viewer's per-pool Buzz balance (`{ blue, green, yellow }` — the
@@ -1403,6 +1445,7 @@ what went stale in [#334](https://github.com/civitai/civitai-app-starters/issues
 | `createMockHost` | A framework-agnostic fake of the embedding host — answers every `*_RESULT` message, with knobs for generation cost/latency/failure, Buzz balance, app + shared storage, consent, maturity. Returns a `MockHost`; call `.install()` and keep the returned teardown. **No network, no Buzz.** |
 | `readMockHostUrlOptions` | Reads the harness URL toggles (`?viewer` `?consent` `?fail` `?theme` `?pick` `?balance` `?latency` `?seed` …) into a `Partial<MockHostOptions>`. `Harness` applies it for you; call it directly only in a hand-rolled harness. |
 | `Harness` | The React wrapper: installs a `createMockHost` on mount, tears it down on unmount, and renders an optional on-screen outbound-message log. Takes every `MockHostOptions` field plus `applyUrlToggles` and `showLog`. |
+| `installPopoverShim` | Stands in for the HTML popover API, which neither `jsdom` nor `happy-dom` implements at any version. Needed only if your own code calls `showPopover`/`hidePopover`/`togglePopover` or queries `:popover-open` — `@civitai/components`' own elements do not. Returns a `PopoverShimHandle`; inert (`installed: false`) in a real browser. **Read [Testing overlay elements](#testing-overlay-elements) first: it does not make trigger clicks work.** |
 
 <!-- TESTING-SURFACE:VALUES:END -->
 
@@ -1430,6 +1473,8 @@ MockHostScenarioPatch
 MockSharedScenario
 MockSharedSeed
 MockStorageScenario
+PopoverShimHandle
+PopoverShimOptions
 ```
 
 <!-- TESTING-SURFACE:TYPES:END -->
@@ -1459,6 +1504,57 @@ host.setScenario({ failMode: 'none' });   // live-tune mid-test
 uninstall();
 ```
 
+### Testing overlay elements
+
+`<civitai-menu>`, and anything else that opens a panel, live in an environment
+that is **incomplete** rather than merely different. Two facts, both measured on
+happy-dom 20.9.0; neither is a bug in the components.
+
+**1. There is no popover API.** `showPopover`, `hidePopover` and `togglePopover`
+are `undefined` on happy-dom 20.x and on jsdom 25 and 30 alike. `:popover-open`
+is worse than absent: it is **unreliable**, and the unreliability is not a
+property of your runner's version. It resolves through `nwsapi` under jsdom, so
+the same jsdom 25.0.1 both throws `DOMException: unknown pseudo-class selector`
+and returns `false` depending on which `nwsapi` your lockfile pulled in
+(measured: `false` on nwsapi 2.2.28). `@civitai/components`' own elements no
+longer read it, which is what takes that variable off the table for them. Install
+the shim if **your** code touches the API:
+
+```ts
+import { installPopoverShim } from '@civitai/blocks-react/testing';
+
+const shim = installPopoverShim();
+// …
+shim.uninstall();
+```
+
+It is inert in a real browser (`installed: false`), so it is safe to call from a
+setup file shared between a happy-dom project and a browser-mode project.
+
+**2. 🔴 UNDER happy-dom A TRIGGER CLICK DOES NOTHING, and the shim does not change
+that.** A click on light-DOM content assigned to a `<slot>` reaches the **host** (a
+listener there fires once) but **not** a listener on the `<slot>` element — and
+that is the node Lit binds `@click` to. So the click dispatches, bubbles, and
+then the handler is never called: no throw, no state change, a test that quietly
+does nothing. jsdom (25 and 30) *does* deliver it, so this one is happy-dom's
+alone — which is exactly why the shim **measures** it rather than asserting it:
+`installPopoverShim` probes on install, reports the answer as
+`handle.slottedClicksReachSlots`, and `console.warn`s when it is `false`.
+
+**Drive overlay elements through their methods:**
+
+```ts
+menu.show();                 // ✅ works in every DOM
+await menu.updateComplete;
+
+triggerButton.click();       // ❌ silently does nothing under happy-dom
+```
+
+Also absent, because they need layout and a hit-testing event path: the top
+layer, anchor positioning, and **light dismiss** (a click outside a shown panel
+does not close it). If what you are testing is one of those, use a real browser —
+this repo's own `browser` vitest project is the worked example.
+
 ### In a dev harness
 
 ```tsx

package/dist/hooks/useEntitlements.d.ts

@@ -0,0 +1,112 @@
+/** One thing the viewer owns, as the platform recorded it. */
+export interface Entitlement {
+    /** The `id` of the good from this app's manifest. */
+    goodId: string;
+    /** `good` for an ordinary purchase, `app_unlock` for a paid-app unlock. */
+    kind: string;
+    /** The opaque payload the manifest declared. The platform never interprets it. */
+    payload: Record<string, unknown>;
+    grantedAt: string;
+}
+export interface UseEntitlements {
+    /**
+     * What the viewer owns, or `null` until the first successful fetch.
+     *
+     * Stays `null` for an anonymous viewer, who is never asked: see
+     * {@link UseEntitlements.unauthenticated}. `owns()` is `false` either way,
+     * which is the right answer for someone with no account to own anything on.
+     */
+    entitlements: Entitlement[] | null;
+    /** `true` while a fetch (initial or `refetch`) is in flight. */
+    loading: boolean;
+    /**
+     * The last fetch's failure, or `null`. Cleared at the start of the next fetch.
+     * Also carries the NO-HOST-ORIGIN terminal state: if `BLOCK_INIT` never lands,
+     * `loading` drops to `false` and this becomes a named `Error` after
+     * {@link HOST_ORIGIN_WAIT_MS} rather than the hook spinning forever.
+     */
+    error: Error | null;
+    /** Re-read entitlements (e.g. immediately after a successful purchase). */
+    refetch: () => void;
+    /**
+     * `true` when there is NO SIGNED-IN VIEWER, so there is nobody for this app
+     * to have sold anything to.
+     *
+     * 🔴 THIS IS THE ONE CASE WHERE "you own nothing" IS THE RIGHT ANSWER, and
+     * without it the guidance on `error` produces the wrong screen. A page App
+     * Block is a PUBLIC surface: a logged-out viewer's block token carries an
+     * anonymous subject and the endpoint refuses it — so rendering a retry notice
+     * on `error` alone would show every anonymous first paint a button that can
+     * never succeed. Branch on this first: show the unpurchased/sign-in state,
+     * not a failure.
+     *
+     * 🔴 DERIVED FROM THE VIEWER, NOT FROM A RESPONSE, and that is the whole
+     * point. It is `isSignedIn(useBlockContext().viewer) === false` once
+     * `BLOCK_INIT` has landed — `null` viewer means anonymous, the one wire value
+     * every host version agrees on (`ViewerInfo` / `isSignedIn` in
+     * `@civitai/app-sdk/blocks` carry the adjudication). Three consequences worth
+     * knowing:
+     *
+     *   - It is knowable BEFORE any request fires, so an anonymous viewer costs
+     *     no round trip: the hook SKIPS the GET entirely (see `refetch`).
+     *   - `error` stays `null` for an anonymous viewer. Nothing failed; we never
+     *     asked. A retry notice would be wrong twice over.
+     *   - It is `false` until `BLOCK_INIT` lands, because before that the viewer
+     *     is UNKNOWN rather than absent (the pre-init snapshot's `viewer` is also
+     *     `null`). A block that never gets init therefore reaches its terminal
+     *     `error` with this flag `false` — an unembedded block is not a sign-in
+     *     problem, and `test/hostOriginAbsent.test.tsx` pins exactly that.
+     *
+     * 🔴 IT IS NOT "the status was 403", AND A RESPONSE-DERIVED PREDICATE CANNOT
+     * WORK HERE. A 403 on this route has seven producers, and the anonymous case
+     * is NOT one of the uncoded ones: `withBlockScope` puts `goods:read:self` in
+     * its `:self` arm, so an anonymous subject is rejected as
+     * `code: 'context_binding'` — the same code a wrong `modelId` produces. There
+     * is no reachable uncoded 403 on this route, so an earlier
+     * `status === 403 && code == null` predicate could never fire, and keying on
+     * `context_binding` would conflate "not signed in" with a context mismatch.
+     * Every 403 now reaches `error` with the server's own wording, which is where
+     * a developer can read the cause — including the likeliest one in practice, a
+     * manifest missing `goods:read:self` (`insufficient_scope`).
+     */
+    unauthenticated: boolean;
+    /**
+     * `true` if the viewer owns `goodId`. 🔴 Returns `false` while
+     * `entitlements` is still `null`, which is ALSO what a failed read looks
+     * like — so never gate paid content on this alone without checking
+     * `loading` and `error`. A refused read renders as "you own nothing", and
+     * treating that as authoritative takes away something the viewer paid for.
+     */
+    owns: (goodId: string) => boolean;
+}
+/**
+ * Read what the viewer owns FROM THIS APP through the block-token-gated
+ * `GET /api/v1/blocks/entitlements` REST endpoint (scope `goods:read:self`).
+ *
+ * The reply is scoped server-side to the calling app's own `appBlockId`, so an
+ * app can only ever see what it itself sold — which is why this scope is
+ * consent-EXEMPT: there is no third-party data to consent to. A read-only app
+ * that just wants to render "you own this" therefore needs no purchase power
+ * and triggers no re-consent prompt; only `goods:purchase:self` does.
+ *
+ * Revoked entitlements are excluded by the server — "what do I own" must not
+ * include what was taken back.
+ *
+ * Only the LATEST request may write state: a reply superseded by a newer
+ * `refetch`, or one landing after unmount, is dropped.
+ *
+ * An ANONYMOUS viewer is answered without a request: `unauthenticated` is read
+ * off `BLOCK_INIT`'s viewer, so the hook settles to `loading: false` with no
+ * `error` and never issues the GET the server would refuse anyway.
+ *
+ * @example
+ * const { owns, loading, error, unauthenticated, refetch } = useEntitlements();
+ * if (loading) return <Spinner />;
+ * // Order matters. `unauthenticated` is the state no retry can clear — a
+ * // logged-out viewer of a public page block — and it is NOT an `error`.
+ * if (unauthenticated) return <SignInToBuy />;
+ * if (error) return <RetryNotice onRetry={refetch} />;   // NOT "you own nothing"
+ * return owns('extra-slots') ? <Unlocked /> : <BuyButton onDone={refetch} />;
+ */
+export declare function useEntitlements(): UseEntitlements;
+//# sourceMappingURL=useEntitlements.d.ts.map

package/dist/hooks/useEntitlements.js

@@ -0,0 +1,176 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isSignedIn } from '@civitai/app-sdk/blocks';
+import { useBlockContext } from './useBlockContext.js';
+import { useBlockToken } from './useBlockToken.js';
+import { useHostOrigin } from './useHostOrigin.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
+/**
+ * Backstop timeout for the direct REST entitlements GET (see {@link useTip} /
+ * {@link useGenerationResources} for why direct-fetch hooks need their own bound).
+ */
+const ENTITLEMENTS_TIMEOUT_MS = 30_000;
+/**
+ * How long the hook waits for `useHostOrigin()` before declaring the block
+ * un-embedded. A BOUND, not an immediate error: the host origin is absent on
+ * EVERY boot and lands a tick or two after mount with `BLOCK_INIT`, so erroring
+ * on the first `!host` would flash a spurious error on every healthy block.
+ * Only its CONTINUED absence is the fault.
+ *
+ * Equal to {@link ENTITLEMENTS_TIMEOUT_MS} by coincidence, not derivation: this
+ * bounds a wait for the HOST to introduce itself, that one bounds a request
+ * already in flight. Two constants so tuning either cannot retune the other.
+ */
+const HOST_ORIGIN_WAIT_MS = 30_000;
+/**
+ * Read what the viewer owns FROM THIS APP through the block-token-gated
+ * `GET /api/v1/blocks/entitlements` REST endpoint (scope `goods:read:self`).
+ *
+ * The reply is scoped server-side to the calling app's own `appBlockId`, so an
+ * app can only ever see what it itself sold — which is why this scope is
+ * consent-EXEMPT: there is no third-party data to consent to. A read-only app
+ * that just wants to render "you own this" therefore needs no purchase power
+ * and triggers no re-consent prompt; only `goods:purchase:self` does.
+ *
+ * Revoked entitlements are excluded by the server — "what do I own" must not
+ * include what was taken back.
+ *
+ * Only the LATEST request may write state: a reply superseded by a newer
+ * `refetch`, or one landing after unmount, is dropped.
+ *
+ * An ANONYMOUS viewer is answered without a request: `unauthenticated` is read
+ * off `BLOCK_INIT`'s viewer, so the hook settles to `loading: false` with no
+ * `error` and never issues the GET the server would refuse anyway.
+ *
+ * @example
+ * const { owns, loading, error, unauthenticated, refetch } = useEntitlements();
+ * if (loading) return <Spinner />;
+ * // Order matters. `unauthenticated` is the state no retry can clear — a
+ * // logged-out viewer of a public page block — and it is NOT an `error`.
+ * if (unauthenticated) return <SignInToBuy />;
+ * if (error) return <RetryNotice onRetry={refetch} />;   // NOT "you own nothing"
+ * return owns('extra-slots') ? <Unlocked /> : <BuyButton onDone={refetch} />;
+ */
+export function useEntitlements() {
+    const host = useHostOrigin();
+    const { raw } = useBlockToken();
+    const { ready, viewer } = useBlockContext();
+    const [entitlements, setEntitlements] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // 🔴 DERIVED, NOT STATE. `ready` is load-bearing and is the whole reason this
+    // is not a bare `!isSignedIn(viewer)`: the pre-`BLOCK_INIT` snapshot also
+    // carries `viewer: null`, so without the gate every block would report
+    // "signed out" for the first frames of every healthy boot — and a block whose
+    // init NEVER lands would report it forever, sending an embedded block's
+    // terminal host-origin error to a sign-in screen it cannot act on.
+    const anonymous = ready && !isSignedIn(viewer);
+    // Not a sequencing guard: drained only by the unmount cleanup, so it exists
+    // to abort on unmount and let a superseded request's socket close.
+    // `useRequestSequencer` supplies the latest-wins predicate.
+    const inFlight = useRef(new Set());
+    const seq = useRequestSequencer();
+    useEffect(() => {
+        const controllers = inFlight.current;
+        return () => {
+            for (const c of controllers)
+                c.abort();
+            controllers.clear();
+        };
+    }, []);
+    // Bounded wait for the host origin. Re-armed whenever `host` changes and
+    // cleared the moment one arrives, so the terminal error is reachable ONLY
+    // when the origin is still absent a full HOST_ORIGIN_WAIT_MS after mount.
+    useEffect(() => {
+        if (host)
+            return;
+        const id = setTimeout(() => {
+            setLoading(false);
+            setError(new Error(`useEntitlements: host origin not established after ${HOST_ORIGIN_WAIT_MS}ms (no BLOCK_INIT — the block is probably not embedded).`));
+        }, HOST_ORIGIN_WAIT_MS);
+        return () => clearTimeout(id);
+    }, [host, seq]);
+    const refetch = useCallback(() => {
+        if (!host)
+            return;
+        // 🔴 ANONYMOUS VIEWERS ARE ANSWERED WITHOUT A REQUEST — a deliberate choice,
+        // not an omission. Entitlements are bound to the token SUBJECT, and an
+        // anonymous subject can hold none, so the server's answer is knowable and
+        // constant (a `context_binding` 403 from `withBlockScope`'s `:self` arm).
+        // A page block is a PUBLIC surface, so this is the common path rather than
+        // an edge: firing the GET would spend a round trip per anonymous paint to
+        // learn something `BLOCK_INIT` already said, and would leave a 403 in every
+        // developer's network tab that reads as a bug in their manifest.
+        //
+        // `error` is left NULL on purpose. Nothing failed — `unauthenticated` is
+        // the terminal state, and it is the one the documented render order checks
+        // before `error`.
+        if (anonymous) {
+            seq.begin(); // invalidate any in-flight read from a previous signed-in state
+            setEntitlements(null);
+            setError(null);
+            setLoading(false);
+            return;
+        }
+        const token = seq.begin();
+        setLoading(true);
+        setError(null);
+        const controller = new AbortController();
+        inFlight.current.add(controller);
+        const timeoutId = setTimeout(() => controller.abort(), ENTITLEMENTS_TIMEOUT_MS);
+        fetch(`${host}/api/v1/blocks/entitlements`, {
+            headers: { Authorization: `Bearer ${raw}` },
+            signal: controller.signal,
+        })
+            .then(async (res) => {
+            const body = (await res.json().catch(() => null));
+            if (!seq.isCurrent(token))
+                return;
+            if (!res.ok || body == null || !Array.isArray(body.entitlements)) {
+                // 🔴 NO RESPONSE IS EVER CLASSIFIED AS "NOT SIGNED IN" HERE, AND THAT
+                // IS THE FIX RATHER THAN AN OVERSIGHT. `unauthenticated` is derived
+                // from the viewer (see the field's doc); by the time a reply lands we
+                // already know a viewer was signed in, because otherwise no request
+                // was issued at all.
+                //
+                // The predicate that used to live here — `status === 403 && code ==
+                // null` — was DEAD. `src/pages/api/v1/blocks/entitlements.ts` wraps
+                // the handler in `withBlockScope(…, { requiredScope: 'goods:read:self'
+                // })`, and that middleware puts a `:self` scope with an anonymous
+                // subject in its `context_binding` arm, so the anonymous 403 arrives
+                // CODED. No uncoded 403 is reachable on this route, so the flag could
+                // never fire for the one case it exists for. Re-keying it on
+                // `context_binding` would be worse: that code is also what a wrong
+                // `modelId` and an array-form query param produce, so a signed-in
+                // viewer would be told to sign in.
+                //
+                // So every 403 — coded or not, parseable or not — surfaces on `error`
+                // with the server's own wording, which is where a developer can read
+                // the real cause. Pinned by the CONTROL cases in
+                // `test/useEntitlements.test.tsx`.
+                throw new Error(body?.error ?? `entitlements request failed (${res.status})`);
+            }
+            setEntitlements(body.entitlements);
+            setLoading(false);
+        })
+            .catch((err) => {
+            if (!seq.isCurrent(token))
+                return;
+            setError(controller.signal.aborted
+                ? new Error(`useEntitlements: request aborted (timed out after ${ENTITLEMENTS_TIMEOUT_MS}ms or the hook unmounted).`)
+                : err instanceof Error
+                    ? err
+                    : new Error(String(err)));
+            setLoading(false);
+        })
+            .finally(() => {
+            clearTimeout(timeoutId);
+            inFlight.current.delete(controller);
+        });
+    }, [anonymous, host, raw, seq]);
+    useEffect(() => {
+        refetch();
+    }, [refetch]);
+    const owns = useCallback((goodId) => (entitlements ?? []).some((e) => e.goodId === goodId), [entitlements]);
+    return { entitlements, loading, error, unauthenticated: anonymous, refetch, owns };
+}
+//# sourceMappingURL=useEntitlements.js.map

package/dist/hooks/useGoodPurchase.d.ts

@@ -0,0 +1,147 @@
+import type { Entitlement } from './useEntitlements.js';
+/** Which good to buy, and optionally the price the app showed the viewer. */
+export interface GoodPurchaseParams {
+    /** The `id` of a good declared in this app's approved manifest. */
+    goodId: string;
+    /**
+     * The price the app DISPLAYED. Optional, and worth passing: the server
+     * charges its OWN price and refuses when this disagrees, so sending it turns
+     * "the app showed a stale price" into a clean refusal instead of a viewer
+     * being charged an amount they never saw.
+     */
+    expectedPriceBuzz?: number;
+}
+/** Optional per-purchase controls. */
+export interface GoodPurchaseOptions {
+    /**
+     * A STABLE idempotency key for this logical purchase. Reuse the SAME value
+     * when RETRYING a purchase whose response was lost (timeout / network drop)
+     * so the server replays the first terminal result instead of charging twice.
+     * Omit → a fresh key per `purchase()` call.
+     */
+    idempotencyKey?: string;
+    /**
+     * When the viewer cannot afford the good, open the host's Buzz top-up modal
+     * and — only if they actually bought Buzz — retry the purchase ONCE.
+     * Default `false`, so the refusal surfaces and the app decides.
+     *
+     * ⚠️ PASS `expectedPriceBuzz` WITH THIS. It is what the modal is opened with,
+     * so without it the viewer sees no suggested amount, may top up less than the
+     * good costs, and the single retry re-refuses `insufficient_funds` after real
+     * fiat was spent. The option works without it; it just works worse in the one
+     * direction that costs the viewer money.
+     *
+     * 🔴 THE RETRY REUSES THE SAME IDEMPOTENCY KEY, DELIBERATELY. The server's
+     * own comment on this path is that an `insufficient_funds` refusal leaves the
+     * key FREE precisely because "an identical retry CAN reach a different
+     * verdict — a top-up"; it caches terminal results, not this one. Minting a
+     * fresh key here would work too, but it would make a lost response on the
+     * retry unrecoverable, which is the thing idempotency keys exist to prevent.
+     *
+     * ⚠️ RECONCILED WITH THE OPPOSITE POLICY NEXT DOOR, which a reader will hit.
+     * `useBuzzWorkflow` states twice that a resolved-failed budget "is the cue to
+     * call `useBuzzPurchase().openPurchaseModal()`" — i.e. the APP decides — and
+     * warns that "routing a rejection into a top-up sells Buzz for a failure Buzz
+     * cannot fix". That policy is right for a generation, and this option does not
+     * contradict it: it defaults to `false`, and it keys on the REASON
+     * (`insufficient_funds`) rather than on "the call failed", so it never offers
+     * Buzz for a failure Buzz cannot fix. What it buys, and the only reason it is
+     * in the library at all rather than left to each app, is the same-key retry
+     * above — a server contract an app gets wrong in the expensive direction.
+     */
+    topUpOnInsufficientFunds?: boolean;
+}
+/** The successful purchase echo the endpoint returns. */
+export interface GoodPurchaseResult {
+    ok: true;
+    purchase: {
+        id: string;
+        goodId: string;
+        priceBuzz: number;
+    };
+    entitlement: Entitlement;
+}
+/**
+ * A refusal the server produced deliberately, as opposed to a transport
+ * failure.
+ *
+ * `reason` is the machine-readable discriminator where one exists — branch on it
+ * rather than on `message`, which is viewer-facing copy and will be reworded.
+ *
+ * 🔴 `reason` IS OFTEN `undefined`, AND A CONSUMER MUST HANDLE THAT. Only the
+ * SERVICE-level refusals carry one (`insufficient_funds`, `ledger_conflict`,
+ * `charge_failed`, `charge_unknown`, the price-disagreement and
+ * already-owned cases). The ENDPOINT's own refusals return `{ error }` alone:
+ * the 404 for an unavailable good, the 429 rate limit, the daily-cap 400 and
+ * every idempotency refusal (409 / 422 / 503). So a `switch (reason)` with no
+ * default silently swallows a material fraction of real failures — always fall
+ * back to `status` plus `message`.
+ */
+export declare class GoodPurchaseRefusal extends Error {
+    readonly status: number;
+    readonly reason: string | undefined;
+    constructor(message: string, status: number, reason?: string);
+}
+export interface UseGoodPurchase {
+    /**
+     * Buy a manifest-declared good for the viewer. Resolves with the server's
+     * echo, including the entitlement it granted. REJECTS with a
+     * {@link GoodPurchaseRefusal} on any 4xx/5xx — read `reason` to tell
+     * `insufficient_funds` from a stale price or a rate limit.
+     *
+     * Two non-refusal rejections, distinguishable by `name`:
+     * - the 30s bound elapsed → a plain `Error` naming the timeout. A REAL
+     *   failure; the charge may have landed, so retry with the SAME
+     *   `idempotencyKey`.
+     * - the hook unmounted first → an `Error` with `name === 'AbortError'`, so a
+     *   caller that ignores navigate-away rejections can keep doing so. The same
+     *   same-key retry advice applies if the component comes back.
+     *
+     * 🔴 THAT CLASSIFICATION IS DECIDED BY THE ABORT STATE, NOT BY WHETHER A BODY
+     * PARSED, and it holds wherever the abort lands — including DURING the body
+     * read, which is the common shape when the headers arrive first. The one
+     * documented exception is the opposite race: a refusal the server had already
+     * delivered AND the hook had already parsed stays a {@link GoodPurchaseRefusal}
+     * even if the abort fires in the same tick, because a refusal we actually read
+     * is more informative than an abort, and `reason` is what the top-up branch
+     * needs. So an `AbortError` here never hides a refusal, and a refusal here
+     * never hides a timeout.
+     */
+    purchase: (params: GoodPurchaseParams, options?: GoodPurchaseOptions) => Promise<GoodPurchaseResult>;
+    /** `true` while a purchase POST is in flight. */
+    loading: boolean;
+    /** The last purchase's failure, or `null`. Cleared at the start of the next call. */
+    error: Error | null;
+}
+/**
+ * Buy a DIGITAL GOOD for the viewer through the block-token-gated
+ * `POST /api/v1/blocks/goods/purchase` REST endpoint (scope
+ * `goods:purchase:self`).
+ *
+ * Direct-fetch against the VALIDATED host origin (`useHostOrigin()`) with the
+ * block bearer token, the same security-reviewed pattern as {@link useTip}. The
+ * BUYER is always the token subject — the server self-binds it and the block
+ * never supplies a user id, so there is no client-supplied value on the money
+ * path.
+ *
+ * 🔴 BUYING A GOOD AND BUYING BUZZ ARE OPPOSITE DIRECTIONS, AND THIS HOOK
+ * TOUCHES BOTH. A good is Buzz flowing FROM the viewer TO the app owner. The
+ * top-up modal this hook can open ({@link useBuzzPurchase}) is fiat flowing INTO
+ * the viewer's balance. They are different rails with different ledgers; the
+ * only thing they share is that one can unblock the other.
+ *
+ * ⚠️ THE PLATFORM RENDERS NO CONFIRMATION FOR THE PURCHASE ITSELF. This is a
+ * plain authed POST, so whatever confirm UI the viewer sees is the APP's. Spend
+ * is bounded by the good's manifest-reviewed price and the viewer's daily cap,
+ * but a good can be priced near that cap where a tip cannot — so show the price
+ * and get an explicit action before calling this.
+ *
+ * @example
+ * const { purchase, loading, error } = useGoodPurchase();
+ * const { entitlement } = await purchase(
+ *   { goodId: 'extra-slots', expectedPriceBuzz: 250 },
+ *   { topUpOnInsufficientFunds: true },
+ * );
+ */
+export declare function useGoodPurchase(): UseGoodPurchase;
+//# sourceMappingURL=useGoodPurchase.d.ts.map