@frak-labs/react-sdk 0.1.0 → 0.1.1-beta.4dfea079

package/dist/index.js

@@ -1 +1 @@
-import{Fragment as t,createContext as e,createElement as n,useCallback as r,useContext as o,useEffect as a,useMemo as i,useState as u}from"react";import{FrakContextManager as l,baseIframeProps as f,createIFrameFrakClient as s}from"@frak-labs/core-sdk";import{ClientNotFound as c,FrakRpcError as d,RpcErrorCodes as w}from"@frak-labs/frame-connector";import{displayModal as m,getProductInformation as k,openSso as y,processReferral as p,sendInteraction as h,sendTransaction as F,siweAuthenticate as v,watchWalletStatus as g}from"@frak-labs/core-sdk/actions";import{useMutation as C,useQuery as K,useQueryClient as q}from"@tanstack/react-query";let x=e(void 0);function b(t){let{children:e,config:r}=t;return n(x.Provider,{value:{...r,walletUrl:r.walletUrl??"https://wallet.frak.id",domain:r.domain??("undefined"!=typeof window?window?.location?.host:void 0)??"not-found"}},e)}function I(){let t=o(x);if(!t)throw new d(w.configError,"Frak config not found");return t}let P=e(void 0);function S({style:e,children:r}){let o=I(),[a,i]=u(void 0),l=n("iframe",{...f,src:`${o.walletUrl}/listener`,style:e??f.style,ref:t=>{t&&!a&&i(s({iframe:t,config:o}))}}),c=n(P.Provider,{value:a},r);return n(t,null,l,c)}function T(){return o(P)}function U(){let t=q(),e=T(),n=r(e=>{t.setQueryData(["frak-sdk","wallet-status-listener"],e)},[t]);return K({gcTime:0,staleTime:0,queryKey:["frak-sdk","wallet-status-listener"],queryFn:async()=>{if(!e)throw new c;return g(e,n)},enabled:!!e})}function E({mutations:t}={}){let e=T();return C({...t,mutationKey:["frak-sdk","send-transaction"],mutationFn:async t=>{if(!e)throw new c;return F(e,t)}})}function A({mutations:t}={}){let e=T();return C({...t,mutationKey:["frak-sdk","send-interaction"],mutationFn:async t=>{if(!e)throw new c;return h(e,t)}})}function D({mutations:t}={}){let e=T();return C({...t,mutationKey:["frak-sdk","siwe-authenticate",e?.config.domain??"no-domain"],mutationFn:async t=>{if(!e)throw new c;return v(e,t)}})}function L({productId:t,modalConfig:e,options:n}={}){let o=T(),{frakContext:f}=function(){let{location:t}=function(){let t=function(){let[t,e]=u(!1);return a(()=>{e(!0)},[]),t}(),[e,n]=u(t?window.location:void 0);a(()=>{if(t)return e||r(),window.addEventListener("popstate",r),()=>{window.removeEventListener("popstate",r)};function r(){n(window.location)}},[t,e]);let r=i(()=>e?.href,[e?.href]);return{location:e,href:r}}();return{frakContext:i(()=>t?.href?l.parse({url:t.href}):null,[t?.href]),updateContext:r(e=>{console.log("Updating context",{newContext:e}),l.replaceUrl({url:t?.href,context:e})},[t?.href])}}(),{data:s}=U(),{data:d,error:w,status:m}=K({gcTime:0,staleTime:0,queryKey:["frak-sdk","auto-referral-interaction",f?.r??"no-referrer",s?.key??"no-wallet-status",t??"no-product-id"],queryFn:()=>{if(!o)throw new c;return p(o,{walletStatus:s,frakContext:f,modalConfig:e,productId:t,options:n})},enabled:!!s});return i(()=>"pending"===m?"processing":"error"===m?w:d||"idle",[d,m,w])}function G({mutations:t}={}){let e=T();return C({...t,mutationKey:["frak-sdk","display-modal"],mutationFn:async t=>{if(!e)throw new c;return m(e,t)}})}function M({mutations:t}={}){let e=T();return C({...t,mutationKey:["frak-sdk","open-sso"],mutationFn:async t=>{if(!e)throw new c;return y(e,t)}})}function O({query:t}={}){let e=T();return K({...t,queryKey:["frak-sdk","get-product-information"],queryFn:async()=>{if(!e)throw new c;return k(e)}})}export{x as FrakConfigContext,b as FrakConfigProvider,P as FrakIFrameClientContext,S as FrakIFrameClientProvider,G as useDisplayModal,T as useFrakClient,I as useFrakConfig,O as useGetProductInformation,M as useOpenSso,L as useReferralInteraction,A as useSendInteraction,E as useSendTransactionAction,D as useSiweAuthenticate,U as useWalletStatus};
+import{displayModal as e,getMerchantInformation as t,openSso as n,prepareSso as r,processReferral as i,sendTransaction as a,siweAuthenticate as o,watchWalletStatus as s}from"@frak-labs/core-sdk/actions";import{ClientNotFound as c,FrakRpcError as l,RpcErrorCodes as u}from"@frak-labs/frame-connector";import{useMutation as d,useQuery as f,useQueryClient as p}from"@tanstack/react-query";import{Fragment as m,createContext as h,createElement as g,useCallback as _,useContext as v,useEffect as y,useMemo as b,useState as x}from"react";import{FrakContextManager as S,baseIframeProps as C,createIFrameFrakClient as w}from"@frak-labs/core-sdk";const T=h(void 0);function E(e){let{children:t,config:n}=e;return g(T.Provider,{value:{...n,walletUrl:n.walletUrl??`https://wallet.frak.id`,domain:n.domain??(typeof window<`u`?window?.location?.host:void 0)??`not-found`}},t)}const D=h(void 0);function O({style:e,children:t}){let n=I(),[r,i]=x(void 0);return g(m,null,g(`iframe`,{...C,src:`${n.walletUrl}/listener`,style:e??C.style,ref:e=>{!e||r||i(w({iframe:e,config:n}))}}),g(D.Provider,{value:r},t))}function k(){return v(D)}function A(){let e=p(),t=k(),n=_(t=>{e.setQueryData([`frak-sdk`,`wallet-status-listener`],t)},[e]);return f({gcTime:0,staleTime:0,queryKey:[`frak-sdk`,`wallet-status-listener`],queryFn:async()=>{if(!t)throw new c;return s(t,n)},enabled:!!t})}function j(){let[e,t]=x(!1);return y(()=>{t(!0)},[]),e}function M(){let e=j(),[t,n]=x(e?window.location:void 0);return y(()=>{if(!e)return;function r(){n(window.location)}return t||r(),window.addEventListener(`popstate`,r),()=>{window.removeEventListener(`popstate`,r)}},[e,t]),{location:t,href:b(()=>t?.href,[t?.href])}}function N(){let{location:e}=M();return{frakContext:b(()=>e?.href?S.parse({url:e.href}):null,[e?.href]),updateContext:_(t=>{console.log(`Updating context`,{newContext:t}),S.replaceUrl({url:e?.href,context:t})},[e?.href])}}function P({modalConfig:e,options:t}={}){let n=k(),{frakContext:r}=N(),{data:a}=A(),{data:o,error:s,status:l}=f({gcTime:0,staleTime:0,queryKey:[`frak-sdk`,`auto-referral-interaction`,r?.r??`no-referrer`,a?.key??`no-wallet-status`],queryFn:()=>{if(!n)throw new c;return i(n,{walletStatus:a,frakContext:r,modalConfig:e,options:t})},enabled:!!a});return b(()=>l===`pending`?`processing`:l===`error`?s:o||`idle`,[o,l,s])}function F({mutations:t}={}){let n=k();return d({...t,mutationKey:[`frak-sdk`,`display-modal`],mutationFn:async t=>{if(!n)throw new c;return e(n,t)}})}function I(){let e=v(T);if(!e)throw new l(u.configError,`Frak config not found`);return e}function L({query:e}={}){let n=k();return f({...e,queryKey:[`frak-sdk`,`get-merchant-information`],queryFn:async()=>{if(!n)throw new c;return t(n)}})}function R({mutations:e}={}){let t=k();return d({...e,mutationKey:[`frak-sdk`,`open-sso`],mutationFn:async e=>{if(!t)throw new c;return n(t,e)}})}function z(e){let t=k();return f({queryKey:[`frak-sdk`,`prepare-sso`,e],queryFn:async()=>{if(!t)throw new c;return r(t,e)}})}function B({mutations:e}={}){let t=k();return d({...e,mutationKey:[`frak-sdk`,`send-transaction`],mutationFn:async e=>{if(!t)throw new c;return a(t,e)}})}function V({mutations:e}={}){let t=k();return d({...e,mutationKey:[`frak-sdk`,`siwe-authenticate`,t?.config.domain??`no-domain`],mutationFn:async e=>{if(!t)throw new c;return o(t,e)}})}export{T as FrakConfigContext,E as FrakConfigProvider,D as FrakIFrameClientContext,O as FrakIFrameClientProvider,F as useDisplayModal,k as useFrakClient,I as useFrakConfig,L as useGetMerchantInformation,R as useOpenSso,z as usePrepareSso,P as useReferralInteraction,B as useSendTransactionAction,V as useSiweAuthenticate,A as useWalletStatus};

package/package.json

@@ -11,7 +11,7 @@
       "url": "https://twitter.com/QNivelais"
     }
   ],
-  "version": "0.1.0",
+  "version": "0.1.1-beta.4dfea079",
   "description": "React SDK of the Frak wallet, low level library to interact directly with the frak ecosystem.",
   "repository": {
     "url": "https://github.com/frak-id/wallet",
@@ -33,12 +33,14 @@
   },
   "type": "module",
   "files": [
-    "/dist"
+    "/dist",
+    "/src"
   ],
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.cts",
   "exports": {
     ".": {
+      "development": "./src/index.ts",
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
@@ -54,16 +56,19 @@
     "format:check": "biome check .",
     "format": "biome check --write .",
     "clean": "rimraf dist",
-    "build": "rslib build",
-    "build:watch": "rslib build --watch",
+    "build": "tsdown",
+    "build:watch": "tsdown --watch",
     "check-exports": "attw --pack .",
     "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
     "prepublish": "bun run lint && bun run build",
     "publish": "echo 'Publishing react...'"
   },
   "dependencies": {
-    "@frak-labs/frame-connector": "0.1.0",
-    "@frak-labs/core-sdk": "0.1.0"
+    "@frak-labs/frame-connector": "0.1.0-beta.4dfea079",
+    "@frak-labs/core-sdk": "0.1.1-beta.4dfea079"
   },
   "peerDependencies": {
     "viem": "^2.x",
@@ -72,14 +77,24 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@microsoft/api-extractor": "^7.52.8",
-    "@rsbuild/plugin-react": "^1.3.2",
-    "@rslib/core": "^0.9.2",
-    "@types/node": "^24",
+    "@frak-labs/dev-tooling": "0.0.0",
+    "@frak-labs/test-foundation": "0.1.0",
+    "@frak-labs/wallet-shared": "0.0.1",
+    "@tanstack/react-query": "^5.90.20",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/react-hooks": "^8.0.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jsdom": "^27.0.0",
+    "@types/node": "^24.10.13",
+    "@types/react": "19.2.13",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "jsdom": "^28.0.0",
+    "react": "^19.2.4",
+    "tsdown": "^0.20.3",
     "typescript": "^5",
-    "@frak-labs/dev-tooling": "0.0.0"
-  },
-  "browserslist": [
-    "extends @frak-labs/browserslist-config"
-  ]
+    "viem": "^2.39.0",
+    "vitest": "^4.0.18"
+  }
 }

package/src/hook/helper/useReferralInteraction.test.ts

@@ -0,0 +1,358 @@
+/**
+ * Tests for useReferralInteraction hook
+ * Tests automatic referral interaction submission
+ */
+
+import { vi } from "vitest";
+
+vi.mock("@frak-labs/core-sdk/actions");
+vi.mock("../useFrakClient");
+vi.mock("../useWalletStatus");
+vi.mock("../utils/useFrakContext");
+
+import type { FrakContext, WalletStatusReturnType } from "@frak-labs/core-sdk";
+import { processReferral } from "@frak-labs/core-sdk/actions";
+import { ClientNotFound } from "@frak-labs/frame-connector";
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, test } from "../../../tests/vitest-fixtures";
+import { useFrakClient } from "../useFrakClient";
+import { useWalletStatus } from "../useWalletStatus";
+import { useFrakContext } from "../utils/useFrakContext";
+import { useReferralInteraction } from "./useReferralInteraction";
+
+describe("useReferralInteraction", () => {
+    test("should return processing when wallet status is not available", ({
+        queryWrapper,
+        mockFrakClient,
+    }) => {
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: null,
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: undefined,
+            isSuccess: false,
+            isPending: true,
+        } as ReturnType<typeof useWalletStatus>);
+
+        const { result } = renderHook(() => useReferralInteraction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        // Query is disabled when wallet status is not available, status remains pending
+        expect(result.current).toBe("processing");
+    });
+
+    test("should process referral successfully", async ({
+        queryWrapper,
+        mockFrakClient,
+    }) => {
+        const mockReferralState = "success";
+
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        const mockFrakContext: FrakContext = {
+            r: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: mockFrakContext,
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+        vi.mocked(processReferral).mockResolvedValue(mockReferralState);
+
+        const { result } = renderHook(() => useReferralInteraction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(result.current).toEqual(mockReferralState);
+        });
+
+        expect(processReferral).toHaveBeenCalledWith(mockFrakClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: mockFrakContext,
+            modalConfig: undefined,
+            options: undefined,
+        });
+    });
+
+    test("should process referral with modalConfig", async ({
+        queryWrapper,
+        mockFrakClient,
+    }) => {
+        const mockReferralState = "success";
+
+        const modalConfig = {
+            metadata: {
+                logo: "https://example.com/logo.png",
+            },
+        };
+
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: { r: "0x4567890123456789012345678901234567890123" },
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+        vi.mocked(processReferral).mockResolvedValue(mockReferralState);
+
+        const { result } = renderHook(
+            () => useReferralInteraction({ modalConfig }),
+            {
+                wrapper: queryWrapper.wrapper,
+            }
+        );
+
+        await waitFor(() => {
+            expect(result.current).toEqual(mockReferralState);
+        });
+
+        expect(processReferral).toHaveBeenCalledWith(
+            mockFrakClient,
+            expect.objectContaining({
+                modalConfig,
+            })
+        );
+    });
+
+    test("should process referral with options", async ({
+        queryWrapper,
+        mockFrakClient,
+    }) => {
+        const mockReferralState = "success";
+
+        const options = {
+            alwaysAppendUrl: true,
+        };
+
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: { r: "0x7890123456789012345678901234567890123456" },
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+        vi.mocked(processReferral).mockResolvedValue(mockReferralState);
+
+        const { result } = renderHook(
+            () => useReferralInteraction({ options }),
+            {
+                wrapper: queryWrapper.wrapper,
+            }
+        );
+
+        await waitFor(() => {
+            expect(result.current).toEqual(mockReferralState);
+        });
+
+        expect(processReferral).toHaveBeenCalledWith(
+            mockFrakClient,
+            expect.objectContaining({
+                options,
+            })
+        );
+    });
+
+    test("should handle processing state", ({
+        queryWrapper,
+        mockFrakClient,
+    }) => {
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: { r: "0x9999999999999999999999999999999999999999" },
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+
+        // Mock processReferral to never resolve (simulate pending)
+        vi.mocked(processReferral).mockImplementation(
+            () => new Promise(() => {})
+        );
+
+        const { result } = renderHook(() => useReferralInteraction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        expect(result.current).toBe("processing");
+    });
+
+    test("should handle errors", async ({ queryWrapper, mockFrakClient }) => {
+        const error = new Error("Referral processing failed");
+
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: { r: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" },
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+        vi.mocked(processReferral).mockRejectedValue(error);
+
+        const { result } = renderHook(() => useReferralInteraction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(result.current).toEqual(error);
+        });
+    });
+
+    test("should throw ClientNotFound when client is not available", async ({
+        queryWrapper,
+    }) => {
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(undefined);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: { r: "0xcccccccccccccccccccccccccccccccccccccccc" },
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+
+        const { result } = renderHook(() => useReferralInteraction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(result.current).toBeInstanceOf(ClientNotFound);
+        });
+    });
+
+    test("should update query key when referrer changes", async ({
+        queryWrapper,
+        mockFrakClient,
+    }) => {
+        const mockReferralState = "success";
+
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+        vi.mocked(processReferral).mockResolvedValue(mockReferralState);
+
+        // Start with one referrer
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: { r: "0x1111111111111111111111111111111111111111" },
+            updateContext: vi.fn(),
+        });
+
+        const { rerender } = renderHook(() => useReferralInteraction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(processReferral).toHaveBeenCalledTimes(1);
+        });
+
+        // Change referrer
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: { r: "0x2222222222222222222222222222222222222222" },
+            updateContext: vi.fn(),
+        });
+
+        rerender();
+
+        // Query should re-run with new referrer
+        await waitFor(() => {
+            expect(processReferral).toHaveBeenCalledTimes(2);
+        });
+    });
+
+    test("should handle no referrer in context", async ({
+        queryWrapper,
+        mockFrakClient,
+    }) => {
+        const mockReferralState = "success";
+
+        const mockWalletStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useFrakClient).mockReturnValue(mockFrakClient);
+        vi.mocked(useFrakContext).mockReturnValue({
+            frakContext: null, // No referrer
+            updateContext: vi.fn(),
+        });
+        vi.mocked(useWalletStatus).mockReturnValue({
+            data: mockWalletStatus,
+            isSuccess: true,
+            isPending: false,
+        } as ReturnType<typeof useWalletStatus>);
+        vi.mocked(processReferral).mockResolvedValue(mockReferralState);
+
+        const { result } = renderHook(() => useReferralInteraction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(result.current).toEqual(mockReferralState);
+        });
+
+        expect(processReferral).toHaveBeenCalledWith(
+            mockFrakClient,
+            expect.objectContaining({
+                frakContext: null,
+            })
+        );
+    });
+});

package/src/hook/helper/useReferralInteraction.ts

@@ -0,0 +1,78 @@
+import type { DisplayEmbeddedWalletParamsType } from "@frak-labs/core-sdk";
+import {
+    type ProcessReferralOptions,
+    processReferral,
+} from "@frak-labs/core-sdk/actions";
+import { ClientNotFound } from "@frak-labs/frame-connector";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { useFrakClient } from "../useFrakClient";
+import { useWalletStatus } from "../useWalletStatus";
+import { useFrakContext } from "../utils/useFrakContext";
+
+/**
+ * Helper hook to automatically submit a referral interaction when detected
+ *
+ * @group hooks
+ *
+ * @param args
+ * @param args.modalConfig - The modal configuration to display if the user is not logged in
+ * @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.processReferral | `processReferral()`} for more details on the automatic referral handling process
+ */
+export function useReferralInteraction({
+    modalConfig,
+    options,
+}: {
+    modalConfig?: DisplayEmbeddedWalletParamsType;
+    options?: ProcessReferralOptions;
+} = {}) {
+    // Get the frak client
+    const client = useFrakClient();
+
+    // Get the current frak context
+    const { frakContext } = useFrakContext();
+
+    // Get the wallet status
+    const { data: walletStatus } = useWalletStatus();
+
+    // Setup the query that will transmit the referral interaction
+    const {
+        data: referralState,
+        error,
+        status,
+    } = useQuery({
+        gcTime: 0,
+        staleTime: 0,
+        queryKey: [
+            "frak-sdk",
+            "auto-referral-interaction",
+            frakContext?.r ?? "no-referrer",
+            walletStatus?.key ?? "no-wallet-status",
+        ],
+        queryFn: () => {
+            if (!client) {
+                throw new ClientNotFound();
+            }
+
+            return processReferral(client, {
+                walletStatus,
+                frakContext,
+                modalConfig,
+                options,
+            });
+        },
+        enabled: !!walletStatus,
+    });
+
+    return useMemo(() => {
+        if (status === "pending") return "processing";
+        if (status === "error") return error;
+        return referralState || "idle";
+    }, [referralState, status, error]);
+}

package/src/hook/index.ts

@@ -0,0 +1,10 @@
+export { useReferralInteraction } from "./helper/useReferralInteraction";
+export { useDisplayModal } from "./useDisplayModal";
+export { useFrakClient } from "./useFrakClient";
+export { useFrakConfig } from "./useFrakConfig";
+export { useGetMerchantInformation } from "./useGetMerchantInformation";
+export { useOpenSso } from "./useOpenSso";
+export { usePrepareSso } from "./usePrepareSso";
+export { useSendTransactionAction } from "./useSendTransaction";
+export { useSiweAuthenticate } from "./useSiweAuthenticate";
+export { useWalletStatus } from "./useWalletStatus";