@frak-labs/react-sdk 0.1.1 → 0.2.0-beta.7898df5b

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

@@ -0,0 +1,309 @@
+/**
+ * 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,
+            options: undefined,
+        });
+    });
+
+    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,73 @@
+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.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({
+    options,
+}: {
+    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,
+                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";

package/src/hook/useDisplayModal.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Tests for useDisplayModal hook
+ * Tests TanStack Mutation wrapper for displaying modals
+ */
+
+import { vi } from "vitest";
+
+vi.mock("@frak-labs/core-sdk/actions");
+
+import type {
+    LoginModalStepType,
+    ModalRpcStepsResultType,
+    SendTransactionModalStepType,
+} from "@frak-labs/core-sdk";
+import { displayModal } 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 { useDisplayModal } from "./useDisplayModal";
+
+describe("useDisplayModal", () => {
+    test("should throw ClientNotFound when client is not available", async ({
+        queryWrapper,
+    }) => {
+        const { result } = renderHook(() => useDisplayModal(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(result.current.mutate).toBeDefined();
+        });
+
+        result.current.mutate({
+            steps: {
+                login: {},
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toBeInstanceOf(ClientNotFound);
+    });
+
+    test("should display modal with login step", async ({
+        mockFrakProviders,
+    }) => {
+        const mockResult: ModalRpcStepsResultType<[LoginModalStepType]> = {
+            login: {
+                wallet: "0x1234567890123456789012345678901234567890",
+            },
+        };
+
+        vi.mocked(displayModal).mockResolvedValue(mockResult as any);
+
+        const { result } = renderHook(
+            () => useDisplayModal<[LoginModalStepType]>(),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        result.current.mutate({
+            steps: {
+                login: {},
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockResult);
+        expect(displayModal).toHaveBeenCalledTimes(1);
+    });
+
+    test("should display modal with sendTransaction step", async ({
+        mockFrakProviders,
+    }) => {
+        const mockResult: ModalRpcStepsResultType<
+            [SendTransactionModalStepType]
+        > = {
+            sendTransaction: {
+                hash: "0x1234567890123456789012345678901234567890123456789012345678901234",
+            },
+        };
+
+        vi.mocked(displayModal).mockResolvedValue(mockResult as any);
+
+        const { result } = renderHook(
+            () => useDisplayModal<[SendTransactionModalStepType]>(),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        result.current.mutate({
+            steps: {
+                sendTransaction: {
+                    tx: {
+                        to: "0x1234567890123456789012345678901234567890",
+                        data: "0x",
+                    },
+                },
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockResult);
+    });
+
+    test("should display modal with custom metadata", async ({
+        mockFrakProviders,
+    }) => {
+        const mockResult: ModalRpcStepsResultType<[LoginModalStepType]> = {
+            login: { wallet: "0x1234567890123456789012345678901234567890" },
+        };
+
+        vi.mocked(displayModal).mockResolvedValue(mockResult as any);
+
+        const { result } = renderHook(
+            () => useDisplayModal<[LoginModalStepType]>(),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        result.current.mutate({
+            steps: {
+                login: {},
+            },
+            metadata: {
+                header: {
+                    title: "Custom Login",
+                },
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(displayModal).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.objectContaining({
+                metadata: expect.objectContaining({
+                    header: {
+                        title: "Custom Login",
+                    },
+                }),
+            })
+        );
+    });
+
+    test("should handle mutateAsync", async ({ mockFrakProviders }) => {
+        const mockResult: ModalRpcStepsResultType<[LoginModalStepType]> = {
+            login: { wallet: "0x1234567890123456789012345678901234567890" },
+        };
+
+        vi.mocked(displayModal).mockResolvedValue(mockResult as any);
+
+        const { result } = renderHook(
+            () => useDisplayModal<[LoginModalStepType]>(),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        const response = await result.current.mutateAsync({
+            steps: {
+                login: {},
+            },
+        });
+
+        expect(response).toEqual(mockResult);
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+    });
+
+    test("should handle RPC errors", async ({ mockFrakProviders }) => {
+        const error = new Error("Modal display failed");
+        vi.mocked(displayModal).mockRejectedValue(error);
+
+        const { result } = renderHook(() => useDisplayModal(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({
+            steps: {
+                login: {},
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toEqual(error);
+    });
+
+    test("should handle mutation options", async ({ mockFrakProviders }) => {
+        const mockResult: ModalRpcStepsResultType<[LoginModalStepType]> = {
+            login: { wallet: "0x1234567890123456789012345678901234567890" },
+        };
+
+        vi.mocked(displayModal).mockResolvedValue(mockResult as any);
+
+        const onSuccess = vi.fn();
+        const onError = vi.fn();
+
+        const { result } = renderHook(
+            () =>
+                useDisplayModal<[LoginModalStepType]>({
+                    mutations: {
+                        onSuccess,
+                        onError,
+                    },
+                }),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        result.current.mutate({
+            steps: {
+                login: {},
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(onSuccess).toHaveBeenCalled();
+        expect(onError).not.toHaveBeenCalled();
+    });
+
+    test("should reset mutation state", async ({ mockFrakProviders }) => {
+        const mockResult: ModalRpcStepsResultType<[LoginModalStepType]> = {
+            login: { wallet: "0x1234567890123456789012345678901234567890" },
+        };
+
+        vi.mocked(displayModal).mockResolvedValue(mockResult as any);
+
+        const { result } = renderHook(
+            () => useDisplayModal<[LoginModalStepType]>(),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        result.current.mutate({
+            steps: {
+                login: {},
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        result.current.reset();
+
+        await waitFor(() => {
+            expect(result.current.data).toBeUndefined();
+            expect(result.current.isIdle).toBe(true);
+        });
+    });
+});