@coinlist-co/react 0.4.0 → 0.5.1

package/dist/client/index.d.cts

@@ -1,14 +1,170 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode } from 'react';
-import { C as ClientConfig } from '../coinlist-client-Cah5c_aF.cjs';
-export { A as AuthState, a as CoinListClient, O as OauthClientErrorReason, b as OauthClientResult, c as createCoinListClient } from '../coinlist-client-Cah5c_aF.cjs';
-export { C as ChecklistStatus, R as RequirementStatus, a as RequirementVariant } from '../RequirementItem-B-MvcxSr.cjs';
-export { CompleteCoinListOAuthFailureReason, LoadOfferDetailsReason, LoadOfferDetailsState, LoadParticipationsReason, LoadParticipationsState, UseCoinListOfferDetailsOptions, UseCoinListOfferDetailsResult, UseCompleteCoinListOAuthOptions, UseParticipationsOptions, UseParticipationsResult, useCoinList, useCoinListOfferDetails, useCompleteCoinListOAuth, useParticipations } from './hooks/index.cjs';
-export { L as LoadOffersReason, a as LoadOffersState, b as LoadRequirementsReason, c as LoadRequirementsState, U as UseCoinListOffersOptions, d as UseCoinListOffersResult, e as UseCoinListRequirementsOptions, f as UseCoinListRequirementsResult, u as useCoinListOffers, g as useCoinListRequirements } from '../useCoinListRequirements-Cuc32Tqw.cjs';
-export { A as AuthorizationCode, B as Blockchain, C as ClientId, a as ClientSecret, b as CodeChallenge, c as CodeVerifier, d as CreateParticipationParams, e as Cursor, O as OAuthAccessToken, f as OAuthRefreshToken, g as OAuthSession, P as PaginatedResponse, h as PaginatedResponseDto, i as PaginationParams, j as Participation, k as ParticipationId, l as ParticipationStatus, m as ParticipationsPaginationParams, R as RedirectUri, W as WalletAddress, n as fetchAllPages } from '../participation-DMMEDxON.cjs';
-export { F as FaqItem, L as Link, M as Milestone, O as Offer, a as OfferDetail, b as OfferId, c as OfferOption, d as OfferOptionId, e as OfferOptionSlug, f as OfferSlug, R as Requirement, g as RequirementId, h as RequirementStatusInfo, i as RequirementStatusValue, j as RequirementType, T as TermItem } from '../requirement-XWT0T_zO.cjs';
-export { User, UserEmail, UserId } from './core/index.cjs';
+import { A as AuthorizationCode, C as CodeVerifier, a as Config, O as OAuthAccessToken, b as Offer, P as PaginationParams, c as PaginatedResponse, d as OfferId, e as OfferDetail, f as Participation, g as ParticipationsPaginationParams, h as ParticipationId, i as CreateParticipationParams, j as OfferOptionId, R as Requirement, k as RequirementStatusInfo, l as RequirementType, m as RequirementStatusValue } from '../requirement-BEO42QOr.cjs';
 
+type AuthState = 'unknown' | 'logged-in' | 'logged-out';
+/** Discriminated error reasons from {@link CoinListClient.completeOAuth}. */
+type OauthClientErrorReason = 'user_canceled' | 'missing_state' | 'invalid_state' | 'missing_code' | 'missing_code_verifier';
+type OauthClientResult = {
+    type: 'ok';
+    code: AuthorizationCode;
+    codeVerifier: CodeVerifier;
+} | {
+    type: 'error';
+    reason: OauthClientErrorReason;
+};
+
+/** Session storage keys for OAuth PKCE (used by startOauth and completeOauth). */
+declare const OAUTH_STATE_KEY = "coinlist.oauth_state";
+declare const OAUTH_CODE_VERIFIER_KEY = "coinlist.oauth_code_verifier";
+interface ClientConfig extends Config {
+    /**
+     * The SDK user must provide this function. It is responsible for fetching a
+     * valid {@link OAuthAccessToken}, or **null** for logged-out users. If your
+     * backend is in TypeScript, it is recommended to use
+     * {@link CoinListServer#accessToken} from `@/server/coinlist.server`.
+     */
+    getAccessToken: () => Promise<OAuthAccessToken | null>;
+    /**
+     * Recommended to leave undefined. Used to change the CoinList environment;
+     * default is production.
+     */
+    coinlistBaseUrl?: string;
+}
+interface CoinListClient {
+    /**
+     * Calls the provided {@link ClientConfig.getAccessToken} lambda to determine
+     * the user's {@link AuthState}. This is called automatically by {@link CoinListProvider};
+     * you typically do not need to call it yourself unless you are using the client
+     * outside of the provider.
+     */
+    init(): Promise<AuthState>;
+    /**
+     * Returns the current auth state: `'logged-in'`, `'logged-out'`, or `'unknown'`.
+     * Returns **unknown** until {@link CoinListClient.init} has completed. It is
+     * recommended to use the `const { isReady, coinlist } = useCoinList()` hook to know when
+     * the SDK has initialized, or to manually await {@link CoinListClient.init}
+     * before relying on this value.
+     */
+    getAuthState(): AuthState;
+    /**
+     * Starts the OAuth flow with PKCE. Generates a random `state` and `code_verifier`,
+     * stores them in sessionStorage (for validation in {@link CoinListClient.completeOAuth}
+     * on redirect), then redirects the user to the CoinList authorization page. After
+     * the user authorizes, they are sent back to your application's redirect URI; call
+     * {@link CoinListClient.completeOAuth} on that page to finish the flow.
+     */
+    startOAuth(): Promise<void>;
+    /**
+     * Completes the OAuth flow on the FE with PKCE and state validation. Parses the
+     * redirect URL (state, code) and validates them against sessionStorage
+     * (state, code_verifier). The state check protects against CSRF (cross-site
+     * request forgery). Call this on the frontend page the user is redirected
+     * to after authorizing.
+     *
+     * On `ok`: Call your backend to exchange the short-lived `authorizationCode`
+     * (and the returned `codeVerifier`) for a long-lived session. If your backend
+     * is in TypeScript, you can use {@link CoinListServer#completeOAuth} from
+     * `@/server/coinlist.server` (CoinListServer) to perform that exchange.
+     *
+     * On `error`: `reason` is an {@link OauthClientErrorReason} (e.g. `'missing_state'`, `'invalid_state'`) so you can switch on it and surface a message to the user.
+     */
+    completeOAuth(): OauthClientResult;
+    /**
+     * Clears the in-memory access token. Note: you need to manually
+     * also logout on the backend via CoinListServer#logout to clear the session cookie.
+     */
+    logout(): void;
+    /**
+     * Fetches all offers by iterating through every paginated response.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchOffers(): Promise<Offer[]>;
+    /**
+     * Fetches a single page of offers.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchOffersPage(params: PaginationParams): Promise<PaginatedResponse<Offer>>;
+    /**
+     * Fetches details for a given offer by its id.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchOfferDetails(id: OfferId): Promise<OfferDetail>;
+    /**
+     * Fetches all participations by iterating through every paginated response.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchParticipations(offerId?: OfferId): Promise<Participation[]>;
+    /**
+     * Fetches a single page of participations, optionally filtered by offer.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchParticipationsPage(params: ParticipationsPaginationParams): Promise<PaginatedResponse<Participation>>;
+    /**
+     * Fetches a participation by id.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchParticipation(id: ParticipationId): Promise<Participation>;
+    /**
+     * Creates a participation.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    createParticipation(params: CreateParticipationParams): Promise<Participation>;
+    /**
+     * Fetches the requirements for all options of a given offer, grouped by option ID.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchOfferRequirements(offerId: OfferId): Promise<Record<OfferOptionId, Requirement[]>>;
+    /**
+     * Fetches the user's requirement statuses for a given offer.
+     *
+     * This method must be called only when the user's {@link AuthState} is
+     * `'logged-in'`. If the user is not authenticated, it throws
+     * {@link NotAuthenticatedError}.
+     */
+    fetchRequirementStatuses(offerId: OfferId): Promise<RequirementStatusInfo[]>;
+    /**
+     * Opens the CoinList page for completing a given requirement in a new tab.
+     * For `jurisdiction` requirements there is no CTA, so this is a no-op.
+     */
+    handleRequirement(requirement: Requirement): void;
+    /**
+     * Opens the CoinList support ticket page in a new tab.
+     */
+    contactSupport(): void;
+}
+declare function createCoinListClient(config: ClientConfig): CoinListClient;
+
+type CoinListContextValue = {
+    coinlist: CoinListClient;
+    isReady: boolean;
+};
+declare const CoinListContext: react.Context<CoinListContextValue | null>;
 type CoinListProviderProps = {
     config: ClientConfig;
     children: ReactNode;
@@ -18,4 +174,365 @@ type CoinListProviderProps = {
  */
 declare function CoinListProvider({ config, children }: CoinListProviderProps): react_jsx_runtime.JSX.Element;
 
-export { ClientConfig, CoinListProvider, type CoinListProviderProps };
+interface CoinListSignInCardProps {
+    state?: 'idle' | 'error';
+    /**
+     * Called when the user clicks the sign-in button. Defaults to
+     * {@link CoinListClient#startOAuth}, which redirects to the CoinList
+     * authorization page. Pass your own handler to override this behavior.
+     */
+    onSignIn?: () => void;
+    /** Called when the user clicks the close button. When omitted, no close button is rendered. */
+    onClose?: () => void;
+    className?: string;
+}
+/**
+ * Sign-in card that prompts the user to authenticate with CoinList.
+ *
+ * Use this component only inside a tree wrapped by {@link CoinListProvider}.
+ * By default, clicking the sign-in button starts the CoinList OAuth flow via
+ * {@link CoinListClient#startOAuth}; pass `onSignIn` to override.
+ */
+declare function CoinListSignInCard({ state, onSignIn, onClose, className, }?: CoinListSignInCardProps): ReactNode;
+
+type OfferCardUi = {
+    tagline: string | null;
+    bannerUrl: string | null;
+    logoUrl: string | null;
+    formattedStartsAt: string;
+    formattedEndsAt: string;
+};
+declare const OfferCardUi: {
+    fromDomain: (offer: Offer) => OfferCardUi;
+};
+interface Props {
+    offer: OfferCardUi;
+    /** Optional click handler. When provided, the card renders as interactive. */
+    onClick?: () => void;
+    /** Optional className applied to the card root element. */
+    className?: string;
+    /** Optional className applied to an outer wrapper element. */
+    containerClassName?: string;
+}
+declare function OfferCard({ offer, onClick, className, containerClassName, }: Props): ReactNode;
+
+interface OffersGridProps {
+    /** Maximum number of columns to render when horizontal space allows. */
+    maxColumns?: number;
+    /** Optional className applied to the grid element. */
+    className?: string;
+    /** Optional className applied to the outer wrapper element. */
+    containerClassName?: string;
+    /** Optional loading slot shown while offers are being fetched. */
+    loading?: ReactNode;
+    /** Optional error slot shown when loading offers fails. */
+    error?: ReactNode;
+    /** Optional empty state slot shown when there are no available offers. */
+    emptyState?: ReactNode;
+    /** Optional per-offer click handler; when omitted, cards are not clickable. */
+    onOfferClick?: (offer: Offer) => void;
+    /**
+     * Offers pre-fetched on the server (e.g. via `CoinListServer.fetchOffers()`).
+     * When provided, the component uses this data as-is and skips the client-side fetch entirely.
+     */
+    data?: Offer[];
+}
+/**
+ * Displays a responsive grid of offers backed by {@link useOffers}.
+ *
+ * Pass `data` (pre-fetched server-side) to use that data as-is and skip
+ * the client-side fetch entirely.
+ *
+ * Uses `loading` / `error` slots when provided; otherwise renders standard
+ * fallback loading and error states. Offer cards are interactive only when
+ * `onOfferClick` is provided.
+ */
+declare function OffersGrid({ data, maxColumns, className, containerClassName, loading, error, emptyState, onOfferClick, }?: OffersGridProps): ReactNode;
+
+type RequirementVariant = 'verification' | 'wallet';
+declare const RequirementVariant: {
+    fromType(type: RequirementType): RequirementVariant;
+};
+type RequirementStatus = 'required' | 'pending' | 'completed' | 'rejected';
+declare const RequirementStatus: {
+    fromStatusValue(status: RequirementStatusValue): RequirementStatus;
+};
+type ChecklistStatus = 'inProgress' | 'eligible' | 'ineligible';
+declare const ChecklistStatus: {
+    derive(statuses: RequirementStatusInfo[]): ChecklistStatus;
+};
+type RequirementItemUi = {
+    variant: RequirementVariant;
+    status: RequirementStatus;
+    label: string;
+    description: string;
+    walletAddress?: string;
+};
+declare const RequirementItemUi: {
+    fromDomain(req: Requirement, statusInfo: RequirementStatusInfo | undefined, label: string, description: string, walletAddress?: string): RequirementItemUi;
+};
+interface RequirementItemProps {
+    ui: RequirementItemUi;
+    expanded?: boolean;
+    onToggle?: () => void;
+    walletAddress?: string;
+    className?: string;
+    onAction?: (() => void) | null;
+    onContactSupport?: (() => void) | null;
+}
+declare function RequirementItem({ ui, expanded, onToggle, className, onAction, onContactSupport, }: RequirementItemProps): react_jsx_runtime.JSX.Element;
+
+type LoadRequirementsReason = 'not-authenticated' | 'generic-error';
+type LoadRequirementsState = {
+    type: 'LOADING';
+} | {
+    type: 'ERROR';
+    reason: LoadRequirementsReason;
+} | {
+    type: 'CONTENT';
+    requirements: Record<OfferOptionId, Requirement[]>;
+    statuses: RequirementStatusInfo[];
+};
+type RequirementsData = {
+    requirements: Record<OfferOptionId, Requirement[]>;
+    statuses: RequirementStatusInfo[];
+};
+interface UseRequirementsOptions {
+    /**
+     * Requirements data pre-fetched on the server (e.g. via
+     * `CoinListServer.fetchOfferRequirements()` + `fetchRequirementStatuses()`).
+     * When provided, the hook uses this data as-is and skips the initial client-side fetch.
+     * Calling `refetch()` will still trigger a fresh fetch.
+     */
+    data?: RequirementsData;
+}
+interface UseRequirementsResult {
+    requirementsState: LoadRequirementsState;
+    /** Triggers a re-fetch of requirements and statuses. */
+    refetch: () => void;
+}
+/**
+ * Loads requirements (grouped by option ID) and requirement statuses for a
+ * given offer, then exposes them via a state machine.
+ *
+ * Pass `data` (pre-fetched server-side) to use that data as-is and skip
+ * the initial client-side fetch. Calling `refetch()` will still trigger a fresh fetch.
+ *
+ * Returns `LOADING` while CoinList is initializing or while data is being fetched.
+ * Returns `CONTENT` with requirements and statuses on success.
+ * Returns `ERROR` with:
+ * - `not-authenticated` when fetching fails with {@link NotAuthenticatedError}
+ * - `generic-error` for any other failure
+ */
+declare function useRequirements(offerId: OfferId, options?: UseRequirementsOptions): UseRequirementsResult;
+
+interface RequirementsChecklistProps {
+    offerId: OfferId;
+    optionId: OfferOptionId;
+    title: string;
+    description: string;
+    onContinue?: () => void;
+    /**
+     * Called when the user clicks a requirement's action button (e.g. "Continue", "Connect wallet").
+     * Defaults to {@link CoinListClient#handleRequirement}, which opens the corresponding CoinList
+     * page in a new tab. Pass your own handler to override this behavior, or pass `null` to disable
+     * the action button entirely.
+     */
+    onRequirementActionOverride?: ((requirement: Requirement) => void) | null;
+    /**
+     * Called when the user clicks "Contact support" on a rejected requirement.
+     * Defaults to {@link CoinListClient#contactSupport}, which opens the CoinList support ticket
+     * page in a new tab. Pass your own handler to override this behavior, or pass `null` to disable
+     * the contact support button entirely.
+     */
+    onContactSupportOverride?: ((requirement: Requirement) => void) | null;
+    /** Override the default label for a requirement type. */
+    getLabel?: (requirement: Requirement) => string;
+    /** Override the default description for a requirement type. */
+    getDescription?: (requirement: Requirement) => string | null;
+    /** Optional loading slot. */
+    loading?: ReactNode;
+    /** Optional error slot. */
+    error?: ReactNode;
+    className?: string;
+    /**
+     * Requirements data pre-fetched on the server (e.g. via
+     * `CoinListServer.fetchOfferRequirements()` + `fetchRequirementStatuses()`).
+     * When provided, the component uses this data as-is and skips the client-side fetch entirely.
+     */
+    data?: RequirementsData;
+}
+/**
+ * Connected requirements checklist that fetches requirements and statuses
+ * via {@link useRequirements} and renders requirement items for the
+ * specified option.
+ *
+ * Pass `data` (pre-fetched server-side) to use that data as-is and skip
+ * the initial client-side fetch.
+ *
+ * By default, clicking a requirement's action button opens the corresponding
+ * CoinList page in a new tab via {@link CoinListClient#handleRequirement}. It is
+ * recommended to omit `onRequirementActionOverride` and rely on this default.
+ * Pass your own handler only if you need custom navigation behavior, or `null`
+ * to disable the action button entirely.
+ */
+declare function RequirementsChecklist({ offerId, optionId, title, description, onContinue, onRequirementActionOverride, onContactSupportOverride, getLabel, getDescription, loading, error, className, data, }: RequirementsChecklistProps): ReactNode;
+
+interface UseCoinListResult {
+    /**
+     * Indicates whether the CoinList client has been initialized and ready to use.
+     * While isReady is false, then the current user state will be `unknown`.
+     */
+    isReady: boolean;
+    coinlist: CoinListClient;
+}
+declare function useCoinList(): UseCoinListResult;
+declare class CoinListClientInitializationError extends Error {
+    constructor(message?: string);
+}
+
+/**
+ * Reasons passed to {@link UseCompleteOAuthOptions.onFailure} when the
+ * OAuth callback cannot be completed. Includes PKCE / redirect validation
+ * errors from {@link CoinListClient.completeOAuth} and a dedicated value when
+ * {@link UseCompleteOAuthOptions.postOAuthComplete} fails or rejects.
+ */
+type CompleteOAuthFailureReason = OauthClientErrorReason | 'complete_request_failed';
+interface UseCompleteOAuthOptions {
+    /**
+     * Exchange the authorization code on your backend (e.g. POST to your API).
+     * Return `true` when the session was established successfully, `false` when
+     * the request completed but signing in failed. Rejections are treated like
+     * `false` and reported as {@link CompleteOAuthFailureReason}
+     * `"complete_request_failed"`.
+     */
+    postOAuthComplete: (payload: {
+        code: AuthorizationCode;
+        codeVerifier: CodeVerifier;
+    }) => Promise<boolean>;
+    /**
+     * Called when the user denied access (`error` query parameter), when
+     * {@link CoinListClient.completeOAuth} fails PKCE/state validation, or when
+     * {@link UseCompleteOAuthOptions.postOAuthComplete} fails.
+     */
+    onFailure: (reason: CompleteOAuthFailureReason) => void | Promise<void>;
+    /** Invoked after {@link UseCompleteOAuthOptions.postOAuthComplete} succeeds and {@link CoinListClient.init} has refreshed the client session. */
+    onSuccess: () => void | Promise<void>;
+}
+/**
+ * Runs the CoinList OAuth callback once on mount: validates the redirect URL via
+ * {@link CoinListClient.completeOAuth}, exchanges the code via {@link UseCompleteOAuthOptions.postOAuthComplete},
+ * refreshes tokens with {@link CoinListClient.init}, then calls {@link UseCompleteOAuthOptions.onSuccess}.
+ *
+ * Framework-agnostic: reads `window.location` like {@link CoinListClient.completeOAuth}. Supply
+ * {@link UseCompleteOAuthOptions.postOAuthComplete}, {@link UseCompleteOAuthOptions.onFailure},
+ * and {@link UseCompleteOAuthOptions.onSuccess} to perform redirects or routing in your app.
+ *
+ * Must be used within {@link CoinListProvider}.
+ */
+declare function useCompleteOAuth(options: UseCompleteOAuthOptions): void;
+
+type LoadOfferDetailsReason = 'not-authenticated' | 'generic-error';
+type LoadOfferDetailsState = {
+    type: 'LOADING';
+} | {
+    type: 'ERROR';
+    reason: LoadOfferDetailsReason;
+} | {
+    type: 'CONTENT';
+    offerDetail: OfferDetail;
+};
+interface UseOfferDetailsOptions {
+    /**
+     * Offer detail pre-fetched on the server (e.g. via `CoinListServer.fetchOfferDetails()`).
+     * When provided, the hook uses this data as-is and skips the client-side fetch entirely.
+     */
+    data?: OfferDetail;
+}
+interface UseOfferDetailsResult {
+    offerDetailsState: LoadOfferDetailsState;
+}
+/**
+ * Loads CoinList offer details for a given offer id and exposes a UI-friendly state.
+ *
+ * Pass `data` (pre-fetched server-side) to use that data as-is and skip
+ * the client-side fetch entirely.
+ *
+ * Returns `LOADING` while CoinList is initializing or while details are being fetched.
+ * Returns `CONTENT` with the offer when `fetchOfferDetails()` succeeds.
+ * Returns `ERROR` with:
+ * - `not-authenticated` when fetching fails with {@link NotAuthenticatedError}
+ * - `generic-error` for any other failure
+ */
+declare function useOfferDetails(offerId: OfferId, options?: UseOfferDetailsOptions): UseOfferDetailsResult;
+
+type LoadOffersReason = 'not-authenticated' | 'generic-error';
+type LoadOffersState = {
+    type: 'LOADING';
+} | {
+    type: 'ERROR';
+    reason: LoadOffersReason;
+} | {
+    type: 'CONTENT';
+    offers: Offer[];
+};
+interface UseOffersOptions {
+    /**
+     * Offers pre-fetched on the server (e.g. via `CoinListServer.fetchOffers()`).
+     * When provided, the hook uses this data as-is and skips the client-side fetch entirely.
+     */
+    data?: Offer[];
+}
+interface UseOffersResult {
+    offersState: LoadOffersState;
+}
+/**
+ * Loads all CoinList offers for the current user and exposes a UI-friendly state.
+ *
+ * Pass `data` (pre-fetched server-side) to use that data as-is and skip
+ * the client-side fetch entirely.
+ *
+ * Returns `LOADING` while CoinList is initializing or while offers are being fetched.
+ * Returns `CONTENT` with all offers when `fetchOffers()` succeeds.
+ * Returns `ERROR` with:
+ * - `not-authenticated` when fetching fails with {@link NotAuthenticatedError}
+ * - `generic-error` for any other failure
+ */
+declare function useOffers(options?: UseOffersOptions): UseOffersResult;
+
+type LoadParticipationsReason = 'not-authenticated' | 'generic-error';
+type LoadParticipationsState = {
+    type: 'LOADING';
+} | {
+    type: 'ERROR';
+    reason: LoadParticipationsReason;
+} | {
+    type: 'CONTENT';
+    participations: Participation[];
+};
+interface UseParticipationsOptions {
+    /**
+     * Participations pre-fetched on the server (e.g. via `CoinListServer.fetchParticipations()`).
+     * When provided, the hook uses this data as-is and skips the client-side fetch entirely.
+     */
+    data?: Participation[];
+}
+interface UseParticipationsResult {
+    participationsState: LoadParticipationsState;
+}
+/**
+ * Loads all CoinList participations for the current user and exposes a UI-friendly state.
+ * Optionally filters by offer when `offerId` is provided.
+ *
+ * Pass `data` (pre-fetched server-side) to use that data as-is and skip
+ * the client-side fetch entirely.
+ *
+ * Returns `LOADING` while CoinList is initializing or while participations are being fetched.
+ * Returns `CONTENT` with all participations when `fetchParticipations()` succeeds.
+ * Returns `ERROR` with:
+ * - `not-authenticated` when fetching fails with {@link NotAuthenticatedError}
+ * - `generic-error` for any other failure
+ */
+declare function useParticipations(offerId?: OfferId, options?: UseParticipationsOptions): UseParticipationsResult;
+
+export { type AuthState, ChecklistStatus, type ClientConfig, type CoinListClient, CoinListClientInitializationError, CoinListContext, type CoinListContextValue, CoinListProvider, type CoinListProviderProps, CoinListSignInCard, type CoinListSignInCardProps, type CompleteOAuthFailureReason, type LoadOfferDetailsReason, type LoadOfferDetailsState, type LoadOffersReason, type LoadOffersState, type LoadParticipationsReason, type LoadParticipationsState, type LoadRequirementsReason, type LoadRequirementsState, OAUTH_CODE_VERIFIER_KEY, OAUTH_STATE_KEY, type OauthClientErrorReason, type OauthClientResult, OfferCard, type Props as OfferCardProps, OfferCardUi, OffersGrid, type OffersGridProps, RequirementItem, type RequirementItemProps, RequirementItemUi, RequirementStatus, RequirementVariant, RequirementsChecklist, type RequirementsChecklistProps, type RequirementsData, type UseCoinListResult, type UseCompleteOAuthOptions, type UseOfferDetailsOptions, type UseOfferDetailsResult, type UseOffersOptions, type UseOffersResult, type UseParticipationsOptions, type UseParticipationsResult, type UseRequirementsOptions, type UseRequirementsResult, createCoinListClient, useCoinList, useCompleteOAuth, useOfferDetails, useOffers, useParticipations, useRequirements };