@frak-labs/react-sdk 0.1.1 → 0.2.0

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";