@domino-sdk/relay 1.60.0 → 1.62.0

package/dist/react/index.d.ts

@@ -1,21 +1,23 @@
-import { B as Badge, b as MemberBadges, O as Offer, e as Redemption } from '../offers-CqXfMIxq.js';
-import { b as ParticipantSession, R as RelayEvent, P as ParticipantActivity, M as MemberSummary } from '../participant-activity-DHL8QYks.js';
-import { g as RelayError, R as RelayClient, m as SubmissionDraft } from '../client-Cw1pB5sv.js';
-import { P as Page, H as collectionViewSchema, l as QuestView, a as CreatorAccountProvider, i as QuestOutcomeQuery, g as QuestOutcome } from '../pages-Bti7g5mX.js';
-export { C as CreatorAccount, b as CreatorAccounts } from '../pages-Bti7g5mX.js';
+import { B as Badge, c as MemberBadges, O as Offer, f as Redemption } from '../offers-DhAtss4_.js';
+import { b as ParticipantSession, R as RelayEvent, P as ParticipantActivity, M as MemberSummary } from '../participant-activity-D-Drp24G.js';
+import { g as RelayError, R as RelayClient, m as SubmissionDraft } from '../client-B-hbHX30.js';
+import { P as Page, s as RewardDeliveryAction, e as CreatorAccountProvider, K as KnownConsentChannel, M as MemberConsent, n as QuestOutcomeQuery, l as QuestOutcome } from '../pages-B8q8Y_dQ.js';
+export { C as ConsentChannel, b as ConsentSource, c as ConsentState, d as CreatorAccount, f as CreatorAccounts, g as KnownConsentSource, h as KnownConsentState } from '../pages-B8q8Y_dQ.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as z from 'zod';
 import { z as z$1 } from 'zod';
-import { E as Entitlement, a as AttemptStatus, f as PointEntry, e as PointBalances, j as PointLedgerReference, T as TieredRewardReference } from '../schema-CwbRkmlr.js';
-import { a as AuthProvider, A as AccountConnection } from '../accounts-DoabriBX.js';
-export { T as TelegramAccountConnection, b as TelegramSignInMethods } from '../accounts-DoabriBX.js';
-import { c as SignInMethods, C as CosmosChains, d as SignInOption, f as SignInUnavailable, T as TelegramSignInOption, g as SignInWallet, D as DiscoveredWallet } from '../telegram-browser-CTJh4Ro_.js';
-export { a as EmailSignInOption, O as OAuthSignInOption, b as SignInIcon, W as WalletSignInOption, t as telegramMiniAppInitData } from '../telegram-browser-CTJh4Ro_.js';
-import { m as WalletSigner, k as WalletSignInNetwork, L as LinkedWallet, g as ProfileUpdate, f as ProfileSummary, b as ProfileCompletion, e as ProfileReferral } from '../wallet-DZWL7lJH.js';
-import { h as LeaderboardPlacement, b2 as referralSummarySchema, g as LeaderboardPage } from '../groups-9Jm3peq3.js';
-import '../submission-input-D9EGH_yb.js';
-import '../action-DBzILFx9.js';
+import { l as collectionViewSchema, b as QuestView } from '../catalog--ZIlskAo.js';
+import { E as Entitlement, b as AttemptStatus, V as AttemptCodeSource, c as AuthProvider, J as SignInProvider, A as AccountConnection, I as SignInAccountStatus, p as LeaderboardPlacement, dL as referralSummarySchema, o as LeaderboardPage, u as PointEntry, t as PointBalances, y as PointLedgerReference, U as TieredRewardReference } from '../accounts-CCqCKCVx.js';
+export { S as SignInAccount, N as SignInProviderOption } from '../accounts-CCqCKCVx.js';
+import { c as SignInMethods, C as CosmosChains, d as SignInOption, P as ProviderSignInOption, f as SignInUnavailable, T as TelegramSignInOption, g as SignInWallet, D as DiscoveredWallet } from '../telegram-browser-BCE7zdOb.js';
+export { a as EmailSignInOption, O as OAuthSignInOption, b as SignInIcon, W as WalletSignInOption, t as telegramMiniAppInitData } from '../telegram-browser-BCE7zdOb.js';
+import { m as WalletSigner, k as WalletSignInNetwork, L as LinkedWallet, g as ProfileUpdate, f as ProfileSummary, b as ProfileCompletion, e as ProfileReferral } from '../wallet-DTO7SXj7.js';
+export { T as TelegramAccountConnection, a as TelegramSignInMethods } from '../submission-input-DHGKhXfp.js';
+import '../tracker-data-Hb1uQnk5.js';
+import '../request-error-D_dUPLwo.js';
+import '../action-9Xl0StBg.js';
+import '../sign-in-providers-BkjcDsFF.js';
 
 /**
  * A query's identity: plain JSON values, outermost group first, such as
@@ -360,12 +362,14 @@ declare const relayKeys: {
     readonly experience: readonly ["experience"];
     /** `useMe`. */
     readonly me: readonly ["me"];
-    /** `useAccounts`. */
+    /** `useAccounts`, `useAccount`, `useTelegramAccount`, `useCreatorAccounts`. */
     readonly accounts: readonly ["accounts"];
     /** `useWallets`. */
     readonly wallets: readonly ["wallets"];
     /** `useMyProfile`, `useProfile`, `useProfileCompletions`, `useProfileReferral`. */
     readonly profiles: readonly ["profiles"];
+    /** `useConsent`. */
+    readonly consent: readonly ["consent"];
     /** `useLeaderboard`, `useLeaderboardPlacement`, `useLeaderboardHistory`. */
     readonly leaderboards: readonly ["leaderboards"];
     /** `useReferralSummary`. */
@@ -759,12 +763,17 @@ declare function useDeliveries(options?: QueryOptions): MemberQuery<{
 }>;
 
 /**
- * All a participant sees of a reward Domino delivers elsewhere, such as a
- * Discord role. Attempts, errors, and role IDs stay out of the page.
+ * All a participant sees of a Discord role Domino grants for a quest. Attempts,
+ * errors, and role IDs stay out of the page.
  */
 type RoleDelivery = {
     quest: string;
     status: string;
+    /**
+     * Raw rows from `me.rewardDeliveries()` carry it; only `grant-role` rows are
+     * roles. Rows without it count as roles.
+     */
+    action?: RewardDeliveryAction;
     revokedAt?: number | null;
     reconciliation?: {
         status: string;
@@ -775,8 +784,10 @@ type KnownRoleDeliveryStatus = "pending" | "failed" | "granted";
 /** Where one quest's role deliveries stand, as a code an app can localize; open for new codes. */
 type RoleDeliveryStatus = KnownRoleDeliveryStatus | (string & {});
 /**
- * Where one quest's roles stand, or null when it delivers nothing. This never
- * changes whether the quest is completed: the role follows the completion.
+ * Where one quest's roles stand, or null when it grants no role. Takes rows from
+ * `useExperience` or raw `me.rewardDeliveries()` rows; announcement rows never
+ * count. This never changes whether the quest is completed: the role follows
+ * the completion.
  * `failed` means Domino gave up; only the organizer can grant the role now.
  */
 declare function roleDeliveryStatus(deliveries: readonly RoleDelivery[], quest: string): RoleDeliveryStatus | null;
@@ -787,7 +798,7 @@ declare function roleDeliveryLabel(status: RoleDeliveryStatus | null): "Role del
  * The signed-in participant's quests and collections, polled for the whole app by one observer,
  * which pauses while the tab is hidden. `data` holds `quests` and `collections`; `signed-out`
  * means nobody is signed in. `deliveries` lists Discord roles earned from quests and whether each
- * has arrived yet.
+ * has arrived yet; announcement (`post-message`) deliveries are left out.
  */
 declare function useExperience(): MemberQuery<ExperienceData> & {
     deliveries: readonly RoleDelivery[];
@@ -1017,6 +1028,7 @@ declare function useQuest(observed: QuestView): {
             kind: "once";
         } | {
             kind: "keyed";
+            across?: "members" | undefined;
         };
         progress: {
             current: number;
@@ -1138,6 +1150,7 @@ declare function useQuest(observed: QuestView): {
                 };
                 release?: string | undefined;
             } | undefined;
+            codeSource?: AttemptCodeSource | null | undefined;
         } | null;
         release: string;
         interaction: "url" | "text" | "staff" | "claim" | "automatic" | "quiz" | "photo";
@@ -1461,6 +1474,7 @@ declare function useQuestAction(observed: QuestView): {
             kind: "once";
         } | {
             kind: "keyed";
+            across?: "members" | undefined;
         };
         progress: {
             current: number;
@@ -1582,6 +1596,7 @@ declare function useQuestAction(observed: QuestView): {
                 };
                 release?: string | undefined;
             } | undefined;
+            codeSource?: AttemptCodeSource | null | undefined;
         } | null;
         release: string;
         interaction: "url" | "text" | "staff" | "claim" | "automatic" | "quiz" | "photo";
@@ -1865,14 +1880,26 @@ declare function useSignIn(): {
     sendCode: (email: string) => Promise<void>;
     verifyCode: (code: string) => Promise<void>;
     startOver: () => void;
-    withProvider: (provider: OAuthProvider) => Promise<void>;
-    /** Signs in, or signs up, with a wallet; the wallet asks the participant to sign a message. */
+    /**
+     * Leaves for the provider's consent screen: any of `providers().signInProviders`, Telegram
+     * included.
+     */
+    withProvider: (provider: SignInProvider) => Promise<void>;
+    /**
+     * Signs in, or signs up, with a wallet; the wallet asks the participant to sign a message. A
+     * wallet that can watch its accounts, such as an EVM browser wallet, is followed: switching
+     * to another account in it, or locking it, signs out.
+     */
     withWallet: (signer: WalletSigner) => Promise<void>;
-    /** Leaves for Telegram Login, where the platform configured it. */
+    /**
+     * Leaves for Telegram Login, where the platform configured it.
+     *
+     * @deprecated Use `withProvider("telegram")`. Removed in 2.0.0.
+     */
     withTelegram: () => Promise<void>;
     /**
      * Signs in, or signs up, inside a Telegram Mini App the project enabled, with its launch data
-     * (`telegramMiniAppInitData()`).
+     * (`telegramMiniAppInitData()` from `@domino-sdk/relay/telegram`).
      */
     withTelegramMiniApp: (initData: string) => Promise<void>;
 };
@@ -1909,8 +1936,18 @@ declare function useSignInOptions(input?: {
     cosmos?: CosmosChains;
 }): {
     options: SignInOption[] | null;
+    /**
+     * Every sign-in provider the platform configured, Telegram included, in Relay's order: render
+     * these in place of the `oauth` entries of `options`, which SDK 1.x keeps to `AuthProvider`.
+     * Null while `options` is.
+     */
+    signInProviders: ProviderSignInOption[] | null;
     unavailable: SignInUnavailable[];
-    /** Telegram Login, to render beside `options`; null when the platform did not configure it. */
+    /**
+     * Telegram Login, to render beside `options`; null when the platform did not configure it.
+     *
+     * @deprecated Use the `"telegram"` entry of `signInProviders`. Removed in 2.0.0.
+     */
     telegram: TelegramSignInOption | null;
     /** Why the project's methods could not be read; the options are then email alone. */
     methodsError: RelayError | null;
@@ -2006,11 +2043,87 @@ declare function useAccounts(): {
     error: RelayError | null;
     refresh(): Promise<void>;
 };
+/**
+ * The signed-in participant's account on one sign-in provider in `data`, any of
+ * `providers().signInProviders`, Telegram included; null while Relay lists no such provider.
+ * It behaves as `useAccounts()` does: `connect()` leaves for the provider's consent screen and
+ * comes back linked, the account is read again when the window regains focus and after a
+ * disconnect, and a failure lands in `actionError`.
+ */
+declare function useAccount(provider: SignInProvider): {
+    connect: () => Promise<boolean>;
+    disconnect: () => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    /** True when the account can be used to verify quests right now. */
+    isConnected: boolean;
+    status: "loading";
+    data: undefined;
+    error: null;
+    refresh(): Promise<void>;
+} | {
+    connect: () => Promise<boolean>;
+    disconnect: () => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    /** True when the account can be used to verify quests right now. */
+    isConnected: boolean;
+    status: "error";
+    data: undefined;
+    error: RelayError;
+    refresh(): Promise<void>;
+} | {
+    connect: () => Promise<boolean>;
+    disconnect: () => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    /** True when the account can be used to verify quests right now. */
+    isConnected: boolean;
+    status: "signed-out";
+    data: undefined;
+    error: null;
+    refresh(): Promise<void>;
+} | {
+    connect: () => Promise<boolean>;
+    disconnect: () => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    /** True when the account can be used to verify quests right now. */
+    isConnected: boolean;
+    status: "ready";
+    data: {
+        provider: SignInProvider;
+        configured: boolean;
+        status: SignInAccountStatus;
+        subject: string | null;
+        revision: number;
+    } | null;
+    error: RelayError | null;
+    refresh(): Promise<void>;
+};
 /**
  * The signed-in participant's Telegram account in `data`. Telegram is not one of `useAccounts()`'s
  * providers in SDK 1.x, so it has this hook of its own, with the same behavior: `connect()` leaves
  * for Telegram Login, `connectMiniApp(initData)` links the user who opened a Telegram Mini App,
  * and a failure lands in `actionError`.
+ *
+ * @deprecated Use `useAccount("telegram")`, which reads, connects and disconnects the same account.
+ * Inside a Mini App, link it with `withTelegram(relay).telegram.miniApp.connect(initData)` from
+ * `@domino-sdk/relay/telegram`, then call
+ * `invalidate([relayKeys.accounts, relayKeys.experience])` from `useInvalidate()`, as
+ * `connectMiniApp` does. Removed in 2.0.0.
  */
 declare function useTelegramAccount(): {
     connect: () => Promise<boolean>;
@@ -2393,6 +2506,76 @@ declare function useProfileCompletions(profile: string, options?: {
     limit?: number;
 }): PagedQuery<ProfileCompletion>;
 
+/**
+ * The signed-in member's marketing consent in `data`, one entry per channel they chose on, and
+ * the changes to it. Show the checkbox in your app and pass its label as `wording`: Relay records
+ * the exact text with its own time. A channel missing from `data` has no record, which is not the
+ * same as withdrawn.
+ *
+ * `grant` and `withdraw` never reject: they resolve true once saved, `isPending` is true while one
+ * runs, and a failure lands in `actionError` until `resetAction()`. Each change is bound to the
+ * session the consent was read with.
+ *
+ * @experimental A minor release can change the consent API.
+ */
+declare function useConsent(): {
+    /** Records the member's opt-in on `channel`, with the wording they saw. */
+    grant: (channel: KnownConsentChannel, wording: string) => Promise<boolean>;
+    /** Records the member's opt-out on `channel`, with the wording they saw if there was any. */
+    withdraw: (channel: KnownConsentChannel, wording?: string) => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    status: "loading";
+    data: undefined;
+    error: null;
+    refresh(): Promise<void>;
+} | {
+    /** Records the member's opt-in on `channel`, with the wording they saw. */
+    grant: (channel: KnownConsentChannel, wording: string) => Promise<boolean>;
+    /** Records the member's opt-out on `channel`, with the wording they saw if there was any. */
+    withdraw: (channel: KnownConsentChannel, wording?: string) => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    status: "error";
+    data: undefined;
+    error: RelayError;
+    refresh(): Promise<void>;
+} | {
+    /** Records the member's opt-in on `channel`, with the wording they saw. */
+    grant: (channel: KnownConsentChannel, wording: string) => Promise<boolean>;
+    /** Records the member's opt-out on `channel`, with the wording they saw if there was any. */
+    withdraw: (channel: KnownConsentChannel, wording?: string) => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    status: "signed-out";
+    data: undefined;
+    error: null;
+    refresh(): Promise<void>;
+} | {
+    /** Records the member's opt-in on `channel`, with the wording they saw. */
+    grant: (channel: KnownConsentChannel, wording: string) => Promise<boolean>;
+    /** Records the member's opt-out on `channel`, with the wording they saw if there was any. */
+    withdraw: (channel: KnownConsentChannel, wording?: string) => Promise<boolean>;
+    isPending: boolean;
+    actionError: RelayError | null;
+    resetAction: () => void;
+    retry: () => Promise<boolean>;
+    settle: () => boolean;
+    status: "ready";
+    data: MemberConsent[];
+    error: RelayError | null;
+    refresh(): Promise<void>;
+};
+
 type ReferralSummary = z$1.infer<typeof referralSummarySchema>;
 /**
  * Keeps an invitation code from the landing URL (`?ref=CODE` by default)
@@ -2429,7 +2612,8 @@ type Invitation = {
  * signed in. Render it once near the app root so the code survives sign-in.
  *
  * Domino rejects self-referrals, cycles, codes from another project, and
- * invitations accepted after the participant's first completion. Show the
+ * invitations accepted after the participant completed a quest other than a
+ * referral program's qualifying quest. Show the
  * reason; `accept(code)` also serves a manual "Have a code?" input. Once
  * accepted, the referral summary and referral progress are read again.
  */
@@ -2529,4 +2713,4 @@ declare function usePointLedgers(): Query<PointLedgerReference[]>;
  */
 declare function useTieredRewards(): Query<TieredRewardReference[]>;
 
-export { type Collection, CosmosChains, CreatorAccountProvider, 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 QuestActionState, 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, TelegramSignInOption, canRepeat, canSubmit, captureReferralCode, completionCountText, isAutomatic, isConnected, isCoolingDown, isFinished, progressOf, questActionState, questGroups, questStatus, questStatusText, relayKeys, roleDeliveryLabel, roleDeliveryStatus, useAccounts, useActivity, useBadgeCatalog, useBadges, useBalances, useCreatorAccounts, useDeliveries, useEntitlements, useExperience, useInvalidate, useInvitation, useLeaderboard, useLeaderboardHistory, useLeaderboardPlacement, useMe, useMemberPages, useMemberQuery, useMyProfile, useOffers, usePointHistory, usePointLedgers, useProfile, useProfileBadges, useProfileCompletions, useProfileReferral, useQuest, useQuestAction, useQuestOutcomes, useRedeemOffer, useReferralSummary, useRelay, useRelayAction, useRelayMutation, useRelayPages, useRelayQuery, useSession, useSetQueryData, useSignIn, useSignInMethods, useSignInOptions, useSignInWallets, useSignOut, useTelegramAccount, useTieredRewards, useWalletDiscovery, useWallets };
+export { type Collection, CosmosChains, CreatorAccountProvider, DiscoveredWallet, type ExperienceData, type Invitation, KnownConsentChannel, type KnownQuestStatusCode, type KnownRoleDeliveryStatus, MemberConsent, 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, ProviderSignInOption, type Query, type QueryContext, type QueryKey, type QueryOptions, type QueryRead, type QuerySnapshot, type QuestActionState, 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, SignInProvider, SignInUnavailable, SignInWallet, TelegramSignInOption, canRepeat, canSubmit, captureReferralCode, completionCountText, isAutomatic, isConnected, isCoolingDown, isFinished, progressOf, questActionState, questGroups, questStatus, questStatusText, relayKeys, roleDeliveryLabel, roleDeliveryStatus, useAccount, useAccounts, useActivity, useBadgeCatalog, useBadges, useBalances, useConsent, useCreatorAccounts, useDeliveries, useEntitlements, useExperience, useInvalidate, useInvitation, useLeaderboard, useLeaderboardHistory, useLeaderboardPlacement, useMe, useMemberPages, useMemberQuery, useMyProfile, useOffers, usePointHistory, usePointLedgers, useProfile, useProfileBadges, useProfileCompletions, useProfileReferral, useQuest, useQuestAction, useQuestOutcomes, useRedeemOffer, useReferralSummary, useRelay, useRelayAction, useRelayMutation, useRelayPages, useRelayQuery, useSession, useSetQueryData, useSignIn, useSignInMethods, useSignInOptions, useSignInWallets, useSignOut, useTelegramAccount, useTieredRewards, useWalletDiscovery, useWallets };