@frak-labs/react-sdk/dist/index.d.ts

React SDK of the Frak wallet, low level library to interact directly with the frak ecosystem.

import { ProcessReferralOptions, SendTransactionParams, SiweAuthenticateModalParams } from "@frak-labs/core-sdk/actions";
import { FrakRpcError } from "@frak-labs/frame-connector";
import { UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
import { CSSProperties, PropsWithChildren, ReactNode } from "react";
import { DisplayModalParamsType, DisplaySharingPageParamsType, DisplaySharingPageResultType, FrakClient, FrakWalletSdkConfig, GetMerchantInformationReturnType, ModalRpcStepsResultType, ModalStepTypes, OpenSsoArgsType, OpenSsoReturnType, PrepareSsoParamsType, SendTransactionReturnType, SiweAuthenticateReturnType, UserReferralStatusType, WalletStatusReturnType } from "@frak-labs/core-sdk";
//#region src/hook/helper/useReferralInteraction.d.ts
/**
 * Helper hook to automatically submit a referral interaction when detected
 *
 * Runs once when the Frak client becomes available.
 *
 * @group hooks
 *
 * @param args
 * @param args.options - Some options for the referral interaction
 *
 * @returns  The resulting referral state, or a potential error
 *
 * @description This function will automatically handle the referral interaction process
 *
 * @see {@link @frak-labs/core-sdk!actions.referralInteraction | `referralInteraction()`} for more details on the automatic referral handling process
 */
declare function useReferralInteraction({ options }?: {
  options?: ProcessReferralOptions;
}): Error | "success" | "idle" | "processing" | "no-referrer" | "self-referral";
//#endregion
//#region src/hook/useDisplayModal.d.ts
/** @ignore */
type MutationOptions$4<T extends ModalStepTypes[]> = Omit<UseMutationOptions<ModalRpcStepsResultType<T>, FrakRpcError, DisplayModalParamsType<T> & {
  placement?: string;
}>, "mutationFn" | "mutationKey">;
/** @inline */
interface UseDisplayModalParams<T extends ModalStepTypes[] = ModalStepTypes[]> {
  /**
   * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
   */
  mutations?: MutationOptions$4<T>;
}
/**
 * Hook that return a mutation helping to display a modal to the user
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.displayModal | `displayModal()`} action
 *
 * @param args - Optional config object with `mutations` for customizing the underlying {@link @tanstack/react-query!useMutation | `useMutation()`}
 *
 * @typeParam T
 * The modal steps types to display (the result will correspond to the steps types asked in params)
 * An array of {@link @frak-labs/core-sdk!index.ModalStepTypes | `ModalStepTypes`}
 * If not provided, it will default to a generic array of `ModalStepTypes`
 *
 * @group hooks
 *
 * @returns
 * The mutation hook wrapping the `displayModal()` action
 * The `mutate` and `mutateAsync` argument is of type {@link @frak-labs/core-sdk!index.DisplayModalParamsType | `DisplayModalParamsType<T>`}, with type params `T` being the modal steps types to display
 * The `data` result is a {@link @frak-labs/core-sdk!index.ModalRpcStepsResultType | `ModalRpcStepsResultType`}
 *
 * @see {@link @frak-labs/core-sdk!actions.displayModal | `displayModal()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useMutation | `useMutation()`} for more info about the mutation options and response
 */
declare function useDisplayModal<T extends ModalStepTypes[] = ModalStepTypes[]>({ mutations }?: UseDisplayModalParams<T>): import("@tanstack/react-query").UseMutationResult<ModalRpcStepsResultType<T>, FrakRpcError<undefined>, DisplayModalParamsType<T> & {
  placement?: string;
}, unknown>;
//#endregion
//#region src/hook/useDisplaySharingPage.d.ts
/** @ignore */
type MutationOptions$3 = Omit<UseMutationOptions<DisplaySharingPageResultType, FrakRpcError, DisplaySharingPageParamsType & {
  placement?: string;
}>, "mutationFn" | "mutationKey">;
/** @inline */
interface UseDisplaySharingPageParams {
  /**
   * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
   */
  mutations?: MutationOptions$3;
}
/**
 * Hook that return a mutation helping to display a sharing page to the user
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.displaySharingPage | `displaySharingPage()`} action
 *
 * @param args - Optional config object with `mutations` for customizing the underlying {@link @tanstack/react-query!useMutation | `useMutation()`}
 *
 * @group hooks
 *
 * @returns
 * The mutation hook wrapping the `displaySharingPage()` action
 * The `mutate` and `mutateAsync` argument is of type {@link @frak-labs/core-sdk!index.DisplaySharingPageParamsType | `DisplaySharingPageParamsType`} with optional `placement`
 * The `data` result is a {@link @frak-labs/core-sdk!index.DisplaySharingPageResultType | `DisplaySharingPageResultType`}
 *
 * @see {@link @frak-labs/core-sdk!actions.displaySharingPage | `displaySharingPage()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useMutation | `useMutation()`} for more info about the mutation options and response
 */
declare function useDisplaySharingPage({ mutations }?: UseDisplaySharingPageParams): import("@tanstack/react-query").UseMutationResult<DisplaySharingPageResultType, FrakRpcError<undefined>, DisplaySharingPageParamsType & {
  placement?: string;
}, unknown>;
//#endregion
//#region src/hook/useFrakClient.d.ts
/**
 * Get the current Frak client
 *
 * @group hooks
 */
declare function useFrakClient(): import("@frak-labs/core-sdk").FrakClient | undefined;
//#endregion
//#region src/hook/useFrakConfig.d.ts
/**
 * Get the current Frak config
 * @throws {FrakRpcError} if the config is not found (only if this hooks is used outside a FrakConfigProvider)
 * @group hooks
 *
 * @see {@link @frak-labs/react-sdk!FrakConfigProvider | FrakConfigProvider} for the config provider
 * @see {@link @frak-labs/core-sdk!index.FrakWalletSdkConfig | FrakWalletSdkConfig} for the config type
 */
declare function useFrakConfig(): import("@frak-labs/core-sdk").FrakWalletSdkConfig;
//#endregion
//#region src/hook/useGetMerchantInformation.d.ts
/** @ignore */
type QueryOptions$2 = Omit<UseQueryOptions<GetMerchantInformationReturnType, FrakRpcError, GetMerchantInformationReturnType>, "queryKey" | "queryFn">;
/** @inline */
interface UseGetMerchantInformationParams {
  /**
   * Optional query options, see {@link @tanstack/react-query!useQuery | `useQuery()`} for more infos
   */
  query?: QueryOptions$2;
  /**
   * Time in ms to cache the result at the core SDK level. Default: 30_000 (30s). Set to 0 to disable.
   */
  cacheTime?: number;
}
/**
 * Hook that return a query helping to get the current merchant information
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.getMerchantInformation | `getMerchantInformation()`} action
 *
 * @param args - Optional config object with `query` for customizing the underlying {@link @tanstack/react-query!useQuery | `useQuery()`}
 *
 * @group hooks
 *
 * @returns
 * The query hook wrapping the `getMerchantInformation()` action
 * The `data` result is a {@link @frak-labs/core-sdk!index.GetMerchantInformationReturnType | `GetMerchantInformationReturnType`}
 *
 * @see {@link @frak-labs/core-sdk!actions.getMerchantInformation | `getMerchantInformation()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useQuery | `useQuery()`} for more info about the useQuery options and response
 */
declare function useGetMerchantInformation({ query, cacheTime }?: UseGetMerchantInformationParams): import("@tanstack/react-query").UseQueryResult<NoInfer<GetMerchantInformationReturnType>, FrakRpcError<undefined>>;
//#endregion
//#region src/hook/useGetMergeToken.d.ts
/** @ignore */
type QueryOptions$1 = Omit<UseQueryOptions<string | null, FrakRpcError, string | null>, "queryKey" | "queryFn">;
/** @inline */
interface UseGetMergeTokenParams {
  /**
   * Optional query options, see {@link @tanstack/react-query!useQuery | `useQuery()`} for more infos
   */
  query?: QueryOptions$1;
  /**
   * Time in ms to cache the result at the core SDK level. Default: 30_000 (30s). Set to 0 to disable.
   */
  cacheTime?: number;
}
/**
 * Hook that return a query to fetch a merge token for the current anonymous identity
 *
 * Used by in-app browser redirect flows to preserve identity
 * when switching from a WebView to the system browser.
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.getMergeToken | `getMergeToken()`} action
 *
 * @param args - Optional config object with `query` for customizing the underlying {@link @tanstack/react-query!useQuery | `useQuery()`}
 *
 * @group hooks
 *
 * @returns
 * The query hook wrapping the `getMergeToken()` action
 * The `data` result is a `string | null`
 *
 * @see {@link @frak-labs/core-sdk!actions.getMergeToken | `getMergeToken()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useQuery | `useQuery()`} for more info about the useQuery options and response
 */
declare function useGetMergeToken({ query, cacheTime }?: UseGetMergeTokenParams): import("@tanstack/react-query").UseQueryResult<string | null, FrakRpcError<undefined>>;
//#endregion
//#region src/hook/useGetUserReferralStatus.d.ts
/** @ignore */
type QueryOptions = Omit<UseQueryOptions<UserReferralStatusType | null, FrakRpcError, UserReferralStatusType | null>, "queryKey" | "queryFn">;
/** @inline */
interface UseGetUserReferralStatusParams {
  /**
   * Optional query options, see {@link @tanstack/react-query!useQuery | `useQuery()`} for more infos
   */
  query?: QueryOptions;
  /**
   * Time in ms to cache the result at the core SDK level. Default: 30_000 (30s). Set to 0 to disable.
   */
  cacheTime?: number;
}
/**
 * Hook that return a query to fetch the current user's referral status on the current merchant
 *
 * Returns `null` when the user's identity cannot be resolved.
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.getUserReferralStatus | `getUserReferralStatus()`} action
 *
 * @param args - Optional config object with `query` for customizing the underlying {@link @tanstack/react-query!useQuery | `useQuery()`}
 *
 * @group hooks
 *
 * @returns
 * The query hook wrapping the `getUserReferralStatus()` action
 * The `data` result is a {@link @frak-labs/core-sdk!index.UserReferralStatusType | `UserReferralStatusType`} or `null`
 *
 * @see {@link @frak-labs/core-sdk!actions.getUserReferralStatus | `getUserReferralStatus()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useQuery | `useQuery()`} for more info about the useQuery options and response
 */
declare function useGetUserReferralStatus({ query, cacheTime }?: UseGetUserReferralStatusParams): import("@tanstack/react-query").UseQueryResult<NoInfer<UserReferralStatusType | null>, FrakRpcError<undefined>>;
//#endregion
//#region src/hook/useOpenSso.d.ts
/** @ignore */
type MutationOptions$2 = Omit<UseMutationOptions<OpenSsoReturnType, FrakRpcError, OpenSsoArgsType>, "mutationFn" | "mutationKey">;
/** @inline */
interface UseOpenSsoParams {
  /**
   * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
   */
  mutations?: MutationOptions$2;
}
/**
 * Hook that return a mutation helping to open the SSO page
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.openSso | `openSso()`} action
 *
 * @param args - Optional config object with `mutations` for customizing the underlying {@link @tanstack/react-query!useMutation | `useMutation()`}
 *
 * @group hooks
 *
 * @returns
 * The mutation hook wrapping the `openSso()` action
 * The `mutate` and `mutateAsync` argument is of type {@link @frak-labs/core-sdk!index.OpenSsoArgsType | `OpenSsoArgsType`}:
 * either the full SSO params, or `{ ssoUrl }` from {@link usePrepareSsoUrl | `usePrepareSsoUrl()`}
 * to open the popup without awaiting anything first.
 * The mutation doesn't output any value
 *
 * @see {@link @frak-labs/core-sdk!actions.openSso | `openSso()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useMutation | `useMutation()`} for more info about the mutation options and response
 */
declare function useOpenSso({ mutations }?: UseOpenSsoParams): import("@tanstack/react-query").UseMutationResult<OpenSsoReturnType, FrakRpcError<undefined>, OpenSsoArgsType, unknown>;
//#endregion
//#region src/hook/usePrepareSso.d.ts
/**
 * Hook that generates SSO URL for popup flow
 *
 * This is a **synchronous** hook (no async calls) that generates the SSO URL
 * client-side without communicating with the wallet iframe.
 *
 * @param params - SSO parameters for URL generation
 *
 * @group hooks
 *
 * @returns
 * Object containing:
 * - `ssoUrl`: Generated SSO URL (or undefined if client not ready)
 * - `isReady`: Boolean indicating if URL is available
 *
 * @example
 * ```tsx
 * function MyComponent() {
 *   const { data } = usePrepareSso({
 *     metadata: { logoUrl: "..." },
 *     directExit: true
 *   });
 *
 *   const handleClick = () => {
 *     if (ssoUrl) {
 *       window.open(data?.ssoUrl, "_blank");
 *     }
 *   };
 *
 *   return <button onClick={handleClick} disabled={!isReady}>Login</button>;
 * }
 * ```
 *
 * @see {@link @frak-labs/core-sdk!actions.prepareSso | `prepareSso()`} for the underlying action
 * @see {@link @frak-labs/core-sdk!actions.openSso | `openSso()`} for the recommended high-level API
 */
declare function usePrepareSso(params: PrepareSsoParamsType): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@frak-labs/core-sdk").PrepareSsoReturnType>, Error>;
//#endregion
//#region src/hook/usePrepareSsoUrl.d.ts
/**
 * Hook that builds the SSO popup URL ahead of the user's click.
 *
 * Wraps {@link @frak-labs/core-sdk!actions.prepareSsoUrl | `prepareSsoUrl()`}
 * in a {@link @tanstack/react-query!useQuery | `useQuery()`}, so the URL is
 * resolved while the page is idle. Handing the result to `useOpenSso()` as
 * `{ ssoUrl }` lets the popup open in the same tick as the click, which is
 * what keeps popup blockers out of the flow.
 *
 * @param params - SSO parameters for URL generation
 *
 * @group hooks
 *
 * @returns The query wrapping the `prepareSsoUrl()` action, resolving to
 * `{ ssoUrl }`
 *
 * @example
 * ```tsx
 * const { data } = usePrepareSsoUrl({ metadata });
 * const { mutate: openSso } = useOpenSso();
 *
 * <button
 *     disabled={!data}
 *     onClick={() => data && openSso({ ssoUrl: data.ssoUrl })}
 * >
 *     Login
 * </button>
 * ```
 *
 * @remarks
 * The URL embeds a proof-of-possession valid for 10 minutes. Past that the SSO
 * still opens and the user still logs in — only the anonymous-to-wallet
 * identity link is lost. On a page that can sit open for a long time, refetch
 * rather than holding one URL indefinitely.
 *
 * @see {@link @frak-labs/core-sdk!actions.prepareSsoUrl | `prepareSsoUrl()`} for the underlying action
 * @see {@link useOpenSso | `useOpenSso()`} for opening the prepared URL
 */
declare function usePrepareSsoUrl(params: PrepareSsoParamsType): import("@tanstack/react-query").UseQueryResult<NoInfer<import("@frak-labs/core-sdk").PrepareSsoReturnType>, Error>;
//#endregion
//#region src/hook/useSendTransaction.d.ts
/** @ignore */
type MutationOptions$1 = Omit<UseMutationOptions<SendTransactionReturnType, FrakRpcError, SendTransactionParams>, "mutationFn" | "mutationKey">;
/** @inline */
interface UseSendTransactionParams {
  /**
   * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
   */
  mutations?: MutationOptions$1;
}
/**
 * Hook that return a mutation helping to send a transaction
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.sendTransaction | `sendTransaction()`} action
 *
 * @param args - Optional config object with `mutations` for customizing the underlying {@link @tanstack/react-query!useMutation | `useMutation()`}
 *
 * @group hooks
 *
 * @returns
 * The mutation hook wrapping the `sendTransaction()` action
 * The `mutate` and `mutateAsync` argument is of type {@link @frak-labs/core-sdk!actions.SendTransactionParams | `SendTransactionParams`}
 * The `data` result is a {@link @frak-labs/core-sdk!index.SendTransactionReturnType | `SendTransactionReturnType`}
 *
 * @see {@link @frak-labs/core-sdk!actions.sendTransaction | `sendTransaction()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useMutation | `useMutation()`} for more info about the mutation options and response
 */
declare function useSendTransactionAction({ mutations }?: UseSendTransactionParams): import("@tanstack/react-query").UseMutationResult<SendTransactionReturnType, FrakRpcError<undefined>, SendTransactionParams, unknown>;
//#endregion
//#region src/hook/useSetupReferral.d.ts
/**
 * Hook that automatically processes referral context and emits a DOM event on success
 *
 * Runs once when the Frak client becomes available. Fire-and-forget — the referral
 * result is tracked via a `"frak:referral-success"` DOM event on `window`, not via
 * the returned query data.
 *
 * @group hooks
 *
 * @returns The query handle (data is not meaningful — listen for `REFERRAL_SUCCESS_EVENT` on `window` instead)
 *
 * @see {@link @frak-labs/core-sdk!actions.setupReferral | `setupReferral()`} for more info about the underlying action
 * @see {@link @frak-labs/core-sdk!actions.REFERRAL_SUCCESS_EVENT | `REFERRAL_SUCCESS_EVENT`} for the event name constant
 */
declare function useSetupReferral(): import("@tanstack/react-query").UseQueryResult<null, Error>;
//#endregion
//#region src/hook/useSiweAuthenticate.d.ts
/** @inline */
type MutationOptions = Omit<UseMutationOptions<SiweAuthenticateReturnType, FrakRpcError, SiweAuthenticateModalParams>, "mutationFn" | "mutationKey">;
/** @ignore */
interface UseSiweAuthenticateParams {
  /**
   * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
   */
  mutations?: MutationOptions;
}
/**
 * Hook that return a mutation helping to send perform a SIWE authentication
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.siweAuthenticate | `siweAuthenticate()`} action
 *
 * @param args - Optional config object with `mutations` for customizing the underlying {@link @tanstack/react-query!useMutation | `useMutation()`}
 *
 * @group hooks
 *
 * @returns
 * The mutation hook wrapping the `siweAuthenticate()` action
 * The `mutate` and `mutateAsync` argument is of type {@link @frak-labs/core-sdk!actions.SiweAuthenticateModalParams | `SiweAuthenticateModalParams`}
 * The `data` result is a {@link @frak-labs/core-sdk!index.SiweAuthenticateReturnType | `SiweAuthenticateReturnType`}
 *
 * @see {@link @frak-labs/core-sdk!actions.siweAuthenticate | `siweAuthenticate()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useMutation | `useMutation()`} for more info about the mutation options and response
 */
declare function useSiweAuthenticate({ mutations }?: UseSiweAuthenticateParams): import("@tanstack/react-query").UseMutationResult<SiweAuthenticateReturnType, FrakRpcError<undefined>, SiweAuthenticateModalParams, unknown>;
//#endregion
//#region src/hook/useWalletStatus.d.ts
/**
 * Hook that return a query helping to get the current wallet status.
 *
 * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.watchWalletStatus | `watchWalletStatus()`} action
 *
 * @group hooks
 *
 * @returns
 * The query hook wrapping the `watchWalletStatus()` action
 * The `data` result is a {@link @frak-labs/core-sdk!index.WalletStatusReturnType | `WalletStatusReturnType`}
 *
 * @see {@link @frak-labs/core-sdk!actions.watchWalletStatus | `watchWalletStatus()`} for more info about the underlying action
 * @see {@link @tanstack/react-query!useQuery | `useQuery()`} for more info about the useQuery response
 */
declare function useWalletStatus(): import("@tanstack/react-query").UseQueryResult<NoInfer<WalletStatusReturnType>, Error>;
//#endregion
//#region src/provider/FrakConfigProvider.d.ts
/**
 * The context that will keep the Frak Wallet SDK configuration
 * @ignore
 */
declare const FrakConfigContext: import("react").Context<FrakWalletSdkConfig | undefined>;
/**
 * Props to instantiate the Frak Wallet SDK configuration provider
 *
 * @group provider
 */
type FrakConfigProviderProps = {
  /**
   * The wanted Frak configuration
   * @see {@link @frak-labs/core-sdk!index.FrakWalletSdkConfig | FrakWalletSdkConfig}
   */
  config: FrakWalletSdkConfig;
};
/**
 * Simple config provider for the Frak Wallet SDK
 *
 * Should be wrapped within a {@link @tanstack/react-query!QueryClientProvider | `QueryClientProvider`}
 *
 * @group provider
 *
 * @param parameters
 */
declare function FrakConfigProvider(parameters: PropsWithChildren<FrakConfigProviderProps>): import("react").FunctionComponentElement<import("react").ProviderProps<FrakWalletSdkConfig | undefined>>;
//#endregion
//#region src/provider/FrakIFrameClientProvider.d.ts
/**
 * The context that will keep the Frak Wallet SDK client
 * @ignore
 */
declare const FrakIFrameClientContext: import("react").Context<FrakClient | undefined>;
/**
 * Props to instantiate the Frak Wallet SDK configuration provider
 *
 * @group provider
 */
type FrakIFrameClientProps = {
  config: FrakWalletSdkConfig;
};
/**
 * IFrame client provider for the Frak Wallet SDK
 * It will automatically create the frak wallet iFrame (required for the wallet to communicate with the SDK securely), and provide it in the context
 *
 * @group provider
 *
 * @remarks
 * This provider must be wrapped within a {@link FrakConfigProvider} to work properly
 *
 * @param args
 * @param args.style - Some custom styles to apply to the iFrame
 * @param args.children - Descedant components that will have access to the Frak Client
 */
declare function FrakIFrameClientProvider({ style, children }: {
  style?: CSSProperties;
  children?: ReactNode;
}): import("react").FunctionComponentElement<import("react").FragmentProps>;
//#endregion
export { FrakConfigContext, FrakConfigProvider, type FrakConfigProviderProps, FrakIFrameClientContext, type FrakIFrameClientProps, FrakIFrameClientProvider, useDisplayModal, useDisplaySharingPage, useFrakClient, useFrakConfig, useGetMerchantInformation, useGetMergeToken, useGetUserReferralStatus, useOpenSso, usePrepareSso, usePrepareSsoUrl, useReferralInteraction, useSendTransactionAction, useSetupReferral, useSiweAuthenticate, useWalletStatus };