@domino-sdk/relay 1.11.1 → 1.14.0

package/dist/react/index.d.ts

@@ -1,18 +1,19 @@
-import { b as ParticipantSession, R as RelayEvent, P as ParticipantActivity, M as MemberSummary } from '../participant-activity-DkL3nY5a.js';
-import { g as RelayError, R as RelayClient, S as SubmissionDraft } from '../client-fUSERMAC.js';
-import { P as Page, j as QuestView, g as QuestOutcomeQuery, e as QuestOutcome } from '../pages-Chb6OZSB.js';
+import { b as ParticipantSession, R as RelayEvent, P as ParticipantActivity, M as MemberSummary } from '../participant-activity-DYdUUhw2.js';
+import { g as RelayError, R as RelayClient, S as SubmissionDraft } from '../client-BTd_CyX3.js';
+import { P as Page, j as QuestView, g as QuestOutcomeQuery, e as QuestOutcome } from '../pages-nIoMT9J3.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { J as JSONType } from '../util.d-w9f9t3ua.js';
-import { E as Entitlement, a as AttemptStatus, T as TieredRewardReference } from '../schema-DEM8y8Fm.js';
-import { a as AuthProvider, A as AccountConnection } from '../submission-input-BbBJTVlT.js';
-import { c as SignInMethods, C as CosmosChains, d as SignInOption, f as SignInUnavailable, g as SignInWallet, D as DiscoveredWallet } from '../sign-in-options-iWOp9puZ.js';
-export { a as EmailSignInOption, O as OAuthSignInOption, b as SignInIcon, W as WalletSignInOption } from '../sign-in-options-iWOp9puZ.js';
+import { E as Entitlement, a as AttemptStatus, T as TieredRewardReference } from '../schema-K-Pg5lPz.js';
+import { a as AuthProvider, A as AccountConnection } from '../accounts-5ciAkCMP.js';
+import { c as SignInMethods, C as CosmosChains, d as SignInOption, f as SignInUnavailable, g as SignInWallet, D as DiscoveredWallet } from '../sign-in-options-DBjMzgnu.js';
+export { a as EmailSignInOption, O as OAuthSignInOption, b as SignInIcon, W as WalletSignInOption } from '../sign-in-options-DBjMzgnu.js';
 import { f as WalletSigner, d as WalletSignInNetwork, L as LinkedWallet } from '../wallet-CDyo-U4n.js';
-import { f as LeaderboardPlacement, b7 as referralSummarySchema, e as LeaderboardPage, i as PointBalances, j as PointEntry, n as PointLedgerReference } from '../groups-BK8ts2yK.js';
+import { f as LeaderboardPlacement, b7 as referralSummarySchema, e as LeaderboardPage, i as PointBalances, j as PointEntry, n as PointLedgerReference } from '../groups-4Jb3uYFO.js';
 import { f as ProfileUpdate, e as ProfileSummary, a as ProfileCompletion, d as ProfileReferral } from '../profiles-BHMVj0kM.js';
 import { z } from 'zod';
-import { O as Offer } from '../offers-C2FANzrG.js';
+import { O as Offer, c as Redemption } from '../offers-BFI5t-e-.js';
+import '../submission-input-CPIsJt-_.js';
 import '../request-error-D_dUPLwo.js';
 import '../action-9Xl0StBg.js';
 
@@ -62,8 +63,43 @@ type QueryOptions = {
     intervalMs?: number;
     /** Read again when the window regains focus. */
     refetchOnFocus?: boolean;
+    /**
+     * `false` reads nothing, and the query stays `loading` (or shows `initialData`) until it is
+     * enabled: for a read that waits on another value. A `null` key does the same.
+     */
+    enabled?: boolean;
+    /**
+     * How long a value stays fresh: a component that shows it again after nobody did for this long
+     * reads it again. Default 30000 ms; `Infinity` never reads again on its account.
+     */
+    staleMs?: number;
 };
 
+/** What `useMemberQuery` also takes: `select` and `suspense`. */
+type MemberQueryOptions<T, U = T> = QueryOptions & {
+    /**
+     * Derives what the hook returns from the cached value, which stays shared with every component
+     * that reads the same key. Pass a stable function: a new one derives again.
+     */
+    select?: (data: T) => U;
+    /**
+     * Suspends the component until the first value arrives, for a `<Suspense>` boundary to show its
+     * fallback, and throws a failed first read to the nearest error boundary. To try again from the
+     * boundary, `invalidate([key])` before resetting it: the failed value is forgotten and the next
+     * render reads afresh. A `signed-out` member query returns as usual. On the server, without
+     * `initialData`, it throws so that React renders the boundary in the browser instead.
+     */
+    suspense?: boolean;
+};
+/** What `useRelayQuery` also takes: `initialData`, `select` and `suspense`. */
+type RelayQueryOptions<T, U = T> = MemberQueryOptions<T, U> & {
+    /**
+     * A value to show before the first read, such as one read during server rendering: it renders
+     * on the server and while hydrating, and counts as fresh for `staleMs`. It seeds the cache of
+     * the first participant the provider learns of; another participant's cache starts empty.
+     */
+    initialData?: T | (() => T);
+};
 /** What every read hook returns: `{ status, data, error, refresh }`. */
 type Query<T> = QuerySnapshot<T> & {
     /** Reads again now, replacing a read in flight. Never rejects: a failure lands in `error`. */
@@ -105,22 +141,33 @@ type PageRead<T> = (context: QueryContext & {
  *   relay.leaderboards.list(options)
  * )
  * ```
+ *
+ * A `null` key, or `enabled: false`, reads nothing until the value it depends on is known:
+ * `useRelayQuery(board ? ["leaderboards", board] : null, ...)`. `initialData`, `select`,
+ * `staleMs` and `suspense` are described on `RelayQueryOptions`.
  */
-declare function useRelayQuery<T>(key: QueryKey, read: QueryRead<T>, options?: QueryOptions): Query<T>;
+declare function useRelayQuery<T>(key: QueryKey | null, read: QueryRead<T>, options?: RelayQueryOptions<T>): Query<T>;
+declare function useRelayQuery<T, U>(key: QueryKey | null, read: QueryRead<T>, options: RelayQueryOptions<T, U> & {
+    select: (data: T) => U;
+}): Query<U>;
 /**
  * `useRelayQuery` for reads that need a signed-in member. Nothing is read while nobody is signed
- * in, and `status` is then `signed-out`.
+ * in, and `status` is then `signed-out`. Takes the same options except `initialData`: a member's
+ * values come only from reads made with their session.
  */
-declare function useMemberQuery<T>(key: QueryKey, read: QueryRead<T>, options?: QueryOptions): MemberQuery<T>;
+declare function useMemberQuery<T>(key: QueryKey | null, read: QueryRead<T>, options?: MemberQueryOptions<T>): MemberQuery<T>;
+declare function useMemberQuery<T, U>(key: QueryKey | null, read: QueryRead<T>, options: MemberQueryOptions<T, U> & {
+    select: (data: T) => U;
+}): MemberQuery<U>;
 /**
  * A paged read (`{ cursor }` in, `{ items, nextCursor }` out) as one growing list, for pages a
  * signed-out visitor can read too. `refresh()` and an invalidation start again from the first
  * page; a page that arrives after that, or for another key or participant, is dropped rather than
- * appended.
+ * appended. A `null` key, or `enabled: false`, reads nothing.
  */
-declare function useRelayPages<T>(key: QueryKey, read: PageRead<T>, options?: QueryOptions): PagedQuery<T>;
+declare function useRelayPages<T>(key: QueryKey | null, read: PageRead<T>, options?: QueryOptions): PagedQuery<T>;
 /** `useRelayPages` for pages that need a signed-in member: `signed-out` while nobody is. */
-declare function useMemberPages<T>(key: QueryKey, read: PageRead<T>, options?: QueryOptions): MemberPagedQuery<T>;
+declare function useMemberPages<T>(key: QueryKey | null, read: PageRead<T>, options?: QueryOptions): MemberPagedQuery<T>;
 /**
  * Marks cached reads out of date after a change. Each key is a prefix: `[["leaderboards"]]`
  * reads every leaderboard on screen again and forgets the rest. With no keys, everything.
@@ -129,6 +176,13 @@ declare function useMemberPages<T>(key: QueryKey, read: PageRead<T>, options?: Q
  * `["experience"]` reads the quest experience again.
  */
 declare function useInvalidate(): (keys?: QueryKey[]) => Promise<void>;
+/**
+ * Changes a cached value at once, such as an optimistic update before a change answers: pass the
+ * new value, or a function of the current one (`undefined` before the first read). A read in
+ * flight for the key is cancelled, so it cannot overwrite the change; invalidate the key once the
+ * change settles to read the real value. Returns false, changing nothing, for a key nobody reads.
+ */
+declare function useSetQueryData(): <T>(key: QueryKey, update: T | ((current: T | undefined) => T)) => boolean;
 /**
  * Who is signed in: the session (`data`, null for a signed-out visitor) and its `member`.
  * Independent of the quest experience: a failing experience read signs nobody out.
@@ -145,25 +199,96 @@ declare function useActivity(options?: {
     intervalMs?: number;
 }): MemberQuery<ParticipantActivity>;
 
+/**
+ * How a `run` or `retry` ended. A failure carries its `error`, except when the call was refused
+ * because another one was still running.
+ */
 type RelayActionResult<T> = {
     ok: true;
     value: T;
 } | {
     ok: false;
+    error?: RelayError;
 };
+/** Where a change stands: not started (or reset), running, done, or failed. */
+type MutationStatus = "idle" | "pending" | "success" | "error";
 /**
  * One logical mutation at a time, with a key and exact callback retained across uncertain errors.
  * `run` and `retry` never reject; their result distinguishes success from failure, including a
  * successful null value. A failure appears in `error`. Pass a client or
  * session as `scope` to isolate actions when the signed-in member or project changes.
+ *
+ * `status`, `isPending` and `data` follow the latest call. `reset()` clears them and `error`, except
+ * while an uncertain write is retained: the next `run` replays it, and only `settle()` forgets it.
  */
 declare function useRelayAction<T = unknown>(scope?: unknown): {
     run: (task?: (actionId: string) => Promise<T>) => Promise<RelayActionResult<T>>;
     retry: () => Promise<RelayActionResult<T>>;
     settle: () => boolean;
+    reset: () => void;
+    status: MutationStatus;
+    isPending: boolean;
+    data: T | undefined;
+    error: RelayError | null;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
+};
+
+/** What a mutation's function receives besides its variables. */
+type MutationContext = {
+    /** The change's idempotency key. It stays the same when an uncertain change is replayed. */
+    actionId: string;
+    /** The session the cache belongs to: pass it on, so Relay refuses the change for another one. */
+    session: string | undefined;
+};
+/**
+ * What every mutation hook returns. One change runs at a time, under one key: after an uncertain
+ * failure (Relay may have applied it), `mutate` replays that same change with its key instead of
+ * starting another, and `error.recovery` says whether a replay is safe. `settle()` forgets it once
+ * you have confirmed the outcome another way.
+ */
+type Mutation<TData, TVariables = void> = {
+    /** Starts the change. Never rejects: a failure lands in `error`. */
+    mutate(variables: TVariables): void;
+    /** Starts the change and resolves what it returned, or rejects with the `RelayError`. */
+    mutateAsync(variables: TVariables): Promise<TData>;
+    status: MutationStatus;
+    /** True while the change runs. */
+    isPending: boolean;
+    /** What the last change returned, once it succeeded. */
+    data: TData | undefined;
+    /** Why the last change failed, until the next one starts or `reset()`. */
     error: RelayError | null;
+    /**
+     * Clears `status`, `data` and `error`, as before the first change. Does nothing while a change
+     * runs, or while an uncertain one is retained (see `settle()`).
+     */
+    reset(): void;
+    /** Forgets a retained uncertain change once its outcome is known. Refuses (false) while busy. */
+    settle(): boolean;
+};
+type MutationOptions<TData, TVariables> = {
+    /**
+     * The cached reads the change makes out of date, read again after it succeeds and before
+     * `mutateAsync` resolves: keys (prefixes, as for `useInvalidate`) or a function of the result.
+     */
+    invalidates?: QueryKey[] | ((data: TData, variables: TVariables) => QueryKey[]);
 };
+/**
+ * A change through the participant client, for writes no hook covers, with the same shape as the
+ * SDK's mutation hooks. `mutation` receives the variables and `{ actionId, session }`: pass the
+ * key as the write's `actionId` and the session in its request options.
+ *
+ * ```tsx
+ * const accept = useRelayMutation(
+ *   (code: string, { actionId, session }) =>
+ *     relay.referrals.accept({ code, actionId }, { session }),
+ *   { invalidates: [relayKeys.referrals] }
+ * )
+ * accept.mutate(code)
+ * ```
+ */
+declare function useRelayMutation<TData = unknown, TVariables = void>(mutation: (variables: TVariables, context: MutationContext) => Promise<TData>, options?: MutationOptions<TData, TVariables>): Mutation<TData, TVariables>;
 
 type Collection = {
     id: string;
@@ -186,20 +311,38 @@ type ExperienceData = {
  */
 declare function questGroups(experience: Pick<ExperienceData, "quests" | "collections">, order?: string[]): Collection[];
 
+/** How often `RelayProvider` reads for changes. */
+type RelayPolling = {
+    /** How often the signed-in member's activity feed is read for new events. Default 5000 ms. */
+    activityMs?: number;
+    /**
+     * How often the whole quest experience is read again, for changes no event announces (a quest
+     * published or opening) and in case the feed is missing or failing. Default 30000 ms.
+     */
+    snapshotMs?: number;
+};
+
 /** The participant client, for calls no hook covers. */
 declare function useRelay(): RelayClient;
 
 /**
- * One participant client, one quest observer and one query cache for the whole app.
+ * One participant client, one activity feed, one quest observer and one query cache for the whole
+ * app.
  *
  * `baseUrl` defaults to `/relay`, the participant proxy that `domino dev` and Domino hosting
  * provide. Pass `client` to share a client created elsewhere. A new `client` or `baseUrl` takes
  * effect at once: the old observer stops, reads in flight are cancelled, and the hooks start again
  * from an empty cache. Safe to render on the server; nothing is read until it mounts.
+ *
+ * While a member is signed in, the provider reads their activity feed every `polling.activityMs`
+ * (5 seconds) and reads again only the queries each event changes. It reads the whole quest
+ * experience every `polling.snapshotMs` (30 seconds), for changes no event announces and as the
+ * fallback when the feed is unavailable. A new `polling` value takes effect like a new client.
  */
-declare function RelayProvider({ client, baseUrl, children, }: {
+declare function RelayProvider({ client, baseUrl, polling, children, }: {
     client?: RelayClient;
     baseUrl?: string;
+    polling?: RelayPolling;
     children: ReactNode;
 }): react.JSX.Element;
 
@@ -239,7 +382,10 @@ declare const relayKeys: {
     readonly offers: readonly ["offers"];
 };
 
-/** Earned tiers and pickup/collection state, scoped to the current session. */
+/**
+ * Earned tiers and pickup/collection state, scoped to the current session. Read again when the
+ * activity feed reports a tier granted or collected, and every 30 seconds.
+ */
 declare function useEntitlements(options?: QueryOptions): MemberQuery<{
     items: ({
         [x: string]: unknown;
@@ -395,7 +541,11 @@ declare function useEntitlements(options?: QueryOptions): MemberQuery<{
         revision: number;
     })[];
 }>;
-/** Points, tier entitlements and integration deliveries, including reversed or revoked rewards. */
+/**
+ * Points, tier entitlements and integration deliveries, including reversed or revoked rewards.
+ * Read again when the activity feed reports points, a tier or a delivery change, and every 30
+ * seconds.
+ */
 declare function useDeliveries(options?: QueryOptions): MemberQuery<{
     items: ({
         [x: string]: JSONType;
@@ -1059,6 +1209,9 @@ declare function useQuest(observed: QuestView): {
     draft: SubmissionDraft | null;
     notice: QuestNotice;
     error: RelayError | null;
+    /** True while `submit`, `resume`, `retry` or `restart` runs. */
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     saved: SavedSubmission;
     /** Review and explicitly restart this terminally retired saved submission. */
@@ -1172,11 +1325,17 @@ declare function useSignInMethods(): Query<SignInMethods>;
 declare function useMe(): MemberQuery<MemberSummary>;
 /**
  * Email codes, OAuth consent and wallet signatures always happen in the participant's browser.
- * The actions keep their identity across renders, and never reject: a failure lands in `error`.
+ * The actions keep their identity across renders, and never reject: a failure lands in `error`,
+ * and `isPending` is true while one runs.
  */
 declare function useSignIn(): {
+    /** True while a sign-in action runs. */
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     error: RelayError | null;
+    /** Clears `error`, keeping a code already sent. */
+    reset: () => void;
     /** True once a code was sent and the form should ask for it. */
     codeSent: boolean;
     sendCode: (email: string) => Promise<void>;
@@ -1187,13 +1346,16 @@ declare function useSignIn(): {
     withWallet: (signer: WalletSigner) => Promise<void>;
 };
 /**
- * Signs the participant out. Once Relay confirms, the previous member's cached values are gone and
- * the member hooks report `signed-out`. `signOut` keeps its identity across renders, and rejects
- * when Relay could not sign out.
+ * Signs the participant out: `mutate()`, which never rejects, or `mutateAsync()`, which rejects
+ * when Relay could not sign out; a failure lands in `error`. Once Relay confirms, the previous
+ * member's cached values are gone and the member hooks report `signed-out`; the hook's `status`
+ * starts over at `idle` then, as changes belong to the participant they started for.
  */
-declare function useSignOut(): {
+declare function useSignOut(): Mutation<void> & {
+    /** @deprecated Use `mutateAsync`, which rejects the same way, or `mutate`. Removed in 2.0.0. */
+    signOut(): Promise<void>;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
-    signOut: () => Promise<void>;
 };
 /**
  * Every way a participant can sign in here, as one flat list: the OAuth providers and email Domino
@@ -1219,9 +1381,14 @@ declare function useSignInOptions(input?: {
     unavailable: SignInUnavailable[];
     /** Why the project's methods could not be read; the options are then email alone. */
     methodsError: RelayError | null;
+    /** True while a sign-in action runs. */
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     /** Why the last sign-in action failed. */
     error: RelayError | null;
+    /** Clears `error`, keeping an email code already sent. */
+    reset(): void;
     /** True once an email code was sent and the form should ask for it. */
     codeSent: boolean;
     /** Forgets the email code sent, to use another address. */
@@ -1236,14 +1403,17 @@ declare function isConnected(accounts: AccountConnection[] | null | undefined, p
  * Connecting leaves the page for the provider's consent screen and comes back
  * connected. The list is read again when the window regains focus and after
  * a disconnect, in every component that uses it. `connect` and `disconnect`
- * never reject: they resolve whether they succeeded, and a failure lands in
- * `actionError`.
+ * never reject: they resolve whether they succeeded, `isPending` is true while
+ * one runs, and a failure lands in `actionError` until `resetAction()`.
  */
 declare function useAccounts(): {
     connect: (provider: AuthProvider) => Promise<boolean>;
     disconnect: (provider: AuthProvider) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     isConnected: (provider: AuthProvider) => boolean;
@@ -1254,8 +1424,11 @@ declare function useAccounts(): {
 } | {
     connect: (provider: AuthProvider) => Promise<boolean>;
     disconnect: (provider: AuthProvider) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     isConnected: (provider: AuthProvider) => boolean;
@@ -1266,8 +1439,11 @@ declare function useAccounts(): {
 } | {
     connect: (provider: AuthProvider) => Promise<boolean>;
     disconnect: (provider: AuthProvider) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     isConnected: (provider: AuthProvider) => boolean;
@@ -1278,8 +1454,11 @@ declare function useAccounts(): {
 } | {
     connect: (provider: AuthProvider) => Promise<boolean>;
     disconnect: (provider: AuthProvider) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     isConnected: (provider: AuthProvider) => boolean;
@@ -1301,14 +1480,18 @@ declare function useAccounts(): {
  * Linking asks the wallet to sign a one-time message. The list is read again
  * when the window regains focus and after a link or unlink, in every component
  * that uses it. `link` and `unlink` never reject: they resolve whether they
- * succeeded, and a failure lands in `actionError`.
+ * succeeded, `isPending` is true while one runs, and a failure lands in
+ * `actionError` until `resetAction()`.
  */
 declare function useWallets(): {
     /** Links the wallet to the member the list was read for; another session is refused. */
     link: (signer: WalletSigner) => Promise<boolean>;
     unlink: (wallet: Pick<LinkedWallet, "chain" | "address">) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "loading";
@@ -1319,8 +1502,11 @@ declare function useWallets(): {
     /** Links the wallet to the member the list was read for; another session is refused. */
     link: (signer: WalletSigner) => Promise<boolean>;
     unlink: (wallet: Pick<LinkedWallet, "chain" | "address">) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "error";
@@ -1331,8 +1517,11 @@ declare function useWallets(): {
     /** Links the wallet to the member the list was read for; another session is refused. */
     link: (signer: WalletSigner) => Promise<boolean>;
     unlink: (wallet: Pick<LinkedWallet, "chain" | "address">) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "signed-out";
@@ -1343,8 +1532,11 @@ declare function useWallets(): {
     /** Links the wallet to the member the list was read for; another session is refused. */
     link: (signer: WalletSigner) => Promise<boolean>;
     unlink: (wallet: Pick<LinkedWallet, "chain" | "address">) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "ready";
@@ -1392,15 +1584,18 @@ declare function useSignInWallets(networks: readonly WalletSignInNetwork[] | nul
  * Read again when the window regains focus and after a change, in every component that uses it,
  * with the leaderboards that show the name. Each change is bound to the session the profile was
  * read with: a session that changed in between is refused rather than applied to another member.
- * `update` and `uploadAvatar` never reject: they resolve true once saved, and a failure lands in
- * `actionError`.
+ * `update` and `uploadAvatar` never reject: they resolve true once saved, `isPending` is true while
+ * one runs, and a failure lands in `actionError` until `resetAction()`.
  */
 declare function useMyProfile(): {
     update: (input: ProfileUpdate) => Promise<boolean>;
     /** Uploads a JPEG, PNG or WebP of at most 5 MB as the avatar. */
     uploadAvatar: (file: Blob) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "loading";
@@ -1411,8 +1606,11 @@ declare function useMyProfile(): {
     update: (input: ProfileUpdate) => Promise<boolean>;
     /** Uploads a JPEG, PNG or WebP of at most 5 MB as the avatar. */
     uploadAvatar: (file: Blob) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "error";
@@ -1423,8 +1621,11 @@ declare function useMyProfile(): {
     update: (input: ProfileUpdate) => Promise<boolean>;
     /** Uploads a JPEG, PNG or WebP of at most 5 MB as the avatar. */
     uploadAvatar: (file: Blob) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "signed-out";
@@ -1435,8 +1636,11 @@ declare function useMyProfile(): {
     update: (input: ProfileUpdate) => Promise<boolean>;
     /** Uploads a JPEG, PNG or WebP of at most 5 MB as the avatar. */
     uploadAvatar: (file: Blob) => Promise<boolean>;
+    isPending: boolean;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
     actionError: RelayError | null;
+    resetAction: () => void;
     retry: () => Promise<boolean>;
     settle: () => boolean;
     status: "ready";
@@ -1602,153 +1806,18 @@ declare function useQuestOutcomes(query?: Omit<QuestOutcomeQuery, "cursor">): Me
 
 /** Offers with stock and availability for the current participant, or public availability. */
 declare function useOffers(): Query<Offer[]>;
-/** Redeem an offer, then refresh offers and point balances. */
-declare function useRedeemOffer(): {
-    redeem: (offer: string) => Promise<{
-        status: "fulfilled";
-        id: string;
-        offer: string;
-        member: string;
-        reservation: string;
-        price: {
-            kind: "points";
-            balance: string;
-            amount: number;
-        };
-        reward: {
-            kind: "tier";
-            reward: {
-                id: string;
-                title: string;
-                tiers: {
-                    id: string;
-                    title: string;
-                }[];
-                inventory: {
-                    kind: "untracked";
-                };
-                fulfillment: {
-                    kind: "staff-handover";
-                } | {
-                    kind: "automatic";
-                };
-            };
-            tier: string;
-        };
-        entitlement: string;
-        revision: number;
-        redeemedAt: number;
-    } | {
-        status: "canceled";
-        canceledAt: number;
-        reason: string;
-        id: string;
-        offer: string;
-        member: string;
-        reservation: string;
-        price: {
-            kind: "points";
-            balance: string;
-            amount: number;
-        };
-        reward: {
-            kind: "tier";
-            reward: {
-                id: string;
-                title: string;
-                tiers: {
-                    id: string;
-                    title: string;
-                }[];
-                inventory: {
-                    kind: "untracked";
-                };
-                fulfillment: {
-                    kind: "staff-handover";
-                } | {
-                    kind: "automatic";
-                };
-            };
-            tier: string;
-        };
-        entitlement: string;
-        revision: number;
-        redeemedAt: number;
-    } | null>;
-    retry: () => Promise<{
-        status: "fulfilled";
-        id: string;
-        offer: string;
-        member: string;
-        reservation: string;
-        price: {
-            kind: "points";
-            balance: string;
-            amount: number;
-        };
-        reward: {
-            kind: "tier";
-            reward: {
-                id: string;
-                title: string;
-                tiers: {
-                    id: string;
-                    title: string;
-                }[];
-                inventory: {
-                    kind: "untracked";
-                };
-                fulfillment: {
-                    kind: "staff-handover";
-                } | {
-                    kind: "automatic";
-                };
-            };
-            tier: string;
-        };
-        entitlement: string;
-        revision: number;
-        redeemedAt: number;
-    } | {
-        status: "canceled";
-        canceledAt: number;
-        reason: string;
-        id: string;
-        offer: string;
-        member: string;
-        reservation: string;
-        price: {
-            kind: "points";
-            balance: string;
-            amount: number;
-        };
-        reward: {
-            kind: "tier";
-            reward: {
-                id: string;
-                title: string;
-                tiers: {
-                    id: string;
-                    title: string;
-                }[];
-                inventory: {
-                    kind: "untracked";
-                };
-                fulfillment: {
-                    kind: "staff-handover";
-                } | {
-                    kind: "automatic";
-                };
-            };
-            tier: string;
-        };
-        entitlement: string;
-        revision: number;
-        redeemedAt: number;
-    } | null>;
-    settle: () => boolean;
+/**
+ * Redeems an offer, then reads offers and point balances again: `mutate(offer)` or
+ * `mutateAsync(offer)`, with `isPending`, `error`, `data` (the redemption) and `reset()`. After an
+ * uncertain failure, `mutate` replays the same redemption with its key rather than spending again.
+ */
+declare function useRedeemOffer(): Mutation<Redemption, string> & {
+    /** @deprecated Use `mutate` or `mutateAsync`. Resolves the redemption, or null on failure. Removed in 2.0.0. */
+    redeem(offer: string): Promise<Redemption | null>;
+    /** @deprecated Use `mutate`, which replays a retained redemption. Removed in 2.0.0. */
+    retry(): Promise<Redemption | null>;
+    /** @deprecated Use `isPending`. Removed in 2.0.0. */
     busy: boolean;
-    error: RelayError | null;
 };
 
 /**
@@ -1768,4 +1837,4 @@ declare function usePointLedgers(): Query<PointLedgerReference[]>;
  */
 declare function useTieredRewards(): Query<TieredRewardReference[]>;
 
-export { type Collection, CosmosChains, DiscoveredWallet, type ExperienceData, type Invitation, type KnownQuestStatusCode, type KnownRoleDeliveryStatus, type MemberPagedQuery, type MemberQuery, type MemberSnapshot, type OAuthProvider, Page, type PageLoader, type PageRead, type PagedQuery, type Query, type QueryContext, type QueryKey, type QueryOptions, type QueryRead, type QuerySnapshot, type QuestInput, type QuestNotice, type QuestStatus, type QuestStatusCode, type QuestStatusText, type QuestTone, type ReferralSummary, type RelayActionResult, RelayClient, RelayProvider, type RoleDelivery, type RoleDeliveryStatus, type SavedSubmission, SignInMethods, SignInOption, SignInUnavailable, SignInWallet, canRepeat, canSubmit, captureReferralCode, completionCountText, isAutomatic, isConnected, isFinished, progressOf, questGroups, questStatus, questStatusText, relayKeys, roleDeliveryLabel, roleDeliveryStatus, useAccounts, useActivity, useBalances, useDeliveries, useEntitlements, useExperience, useInvalidate, useInvitation, useLeaderboard, useLeaderboardPlacement, useMe, useMemberPages, useMemberQuery, useMyProfile, useOffers, usePointHistory, usePointLedgers, useProfile, useProfileCompletions, useProfileReferral, useQuest, useQuestOutcomes, useRedeemOffer, useReferralSummary, useRelay, useRelayAction, useRelayPages, useRelayQuery, useSession, useSignIn, useSignInMethods, useSignInOptions, useSignInWallets, useSignOut, useTieredRewards, useWalletDiscovery, useWallets };
+export { type Collection, CosmosChains, DiscoveredWallet, type ExperienceData, type Invitation, type KnownQuestStatusCode, type KnownRoleDeliveryStatus, type MemberPagedQuery, type MemberQuery, type MemberQueryOptions, type MemberSnapshot, type Mutation, type MutationContext, type MutationOptions, type MutationStatus, type OAuthProvider, Page, type PageLoader, type PageRead, type PagedQuery, type Query, type QueryContext, type QueryKey, type QueryOptions, type QueryRead, type QuerySnapshot, type QuestInput, type QuestNotice, type QuestStatus, type QuestStatusCode, type QuestStatusText, type QuestTone, type ReferralSummary, type RelayActionResult, RelayClient, type RelayPolling, RelayProvider, type RelayQueryOptions, type RoleDelivery, type RoleDeliveryStatus, type SavedSubmission, SignInMethods, SignInOption, SignInUnavailable, SignInWallet, canRepeat, canSubmit, captureReferralCode, completionCountText, isAutomatic, isConnected, isFinished, progressOf, questGroups, questStatus, questStatusText, relayKeys, roleDeliveryLabel, roleDeliveryStatus, useAccounts, useActivity, useBalances, useDeliveries, useEntitlements, useExperience, useInvalidate, useInvitation, useLeaderboard, useLeaderboardPlacement, useMe, useMemberPages, useMemberQuery, useMyProfile, useOffers, usePointHistory, usePointLedgers, useProfile, useProfileCompletions, useProfileReferral, useQuest, useQuestOutcomes, useRedeemOffer, useReferralSummary, useRelay, useRelayAction, useRelayMutation, useRelayPages, useRelayQuery, useSession, useSetQueryData, useSignIn, useSignInMethods, useSignInOptions, useSignInWallets, useSignOut, useTieredRewards, useWalletDiscovery, useWallets };