@frak-labs/react-sdk 0.1.1 → 0.2.0

package/src/hook/useWalletStatus.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Tests for useWalletStatus hook
+ * Tests TanStack Query wrapper for watching wallet status
+ */
+
+import { vi } from "vitest";
+
+vi.mock("@frak-labs/core-sdk/actions");
+
+import type { WalletStatusReturnType } from "@frak-labs/core-sdk";
+import { watchWalletStatus } from "@frak-labs/core-sdk/actions";
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, test } from "../../tests/vitest-fixtures";
+import { useWalletStatus } from "./useWalletStatus";
+
+describe("useWalletStatus", () => {
+    test("should be disabled when client is not available", ({
+        queryWrapper,
+    }) => {
+        const { result } = renderHook(() => useWalletStatus(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        // Query should not run when client is not available
+        expect(result.current.isPending).toBe(true);
+        expect(result.current.isFetching).toBe(false);
+        expect(result.current.data).toBeUndefined();
+    });
+
+    test("should watch wallet status successfully", async ({
+        mockFrakProviders,
+    }) => {
+        const mockStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(watchWalletStatus).mockResolvedValue(mockStatus);
+
+        const { result } = renderHook(() => useWalletStatus(), {
+            wrapper: mockFrakProviders,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockStatus);
+        expect(watchWalletStatus).toHaveBeenCalledTimes(1);
+    });
+
+    test("should return not connected status", async ({
+        mockFrakProviders,
+    }) => {
+        const mockStatus: WalletStatusReturnType = {
+            key: "not-connected",
+        };
+
+        vi.mocked(watchWalletStatus).mockResolvedValue(mockStatus);
+
+        const { result } = renderHook(() => useWalletStatus(), {
+            wrapper: mockFrakProviders,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockStatus);
+        expect(result.current.data?.key).toBe("not-connected");
+    });
+
+    test("should handle RPC errors", async ({ mockFrakProviders }) => {
+        const error = new Error("Wallet status watch failed");
+        vi.mocked(watchWalletStatus).mockRejectedValue(error);
+
+        const { result } = renderHook(() => useWalletStatus(), {
+            wrapper: mockFrakProviders,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toEqual(error);
+    });
+
+    test("should pass callback to watchWalletStatus", async ({
+        mockFrakProviders,
+        mockFrakClient,
+    }) => {
+        const mockStatus: WalletStatusReturnType = {
+            key: "connected",
+            wallet: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(watchWalletStatus).mockResolvedValue(mockStatus);
+
+        const { result } = renderHook(() => useWalletStatus(), {
+            wrapper: mockFrakProviders,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(watchWalletStatus).toHaveBeenCalledWith(
+            mockFrakClient,
+            expect.any(Function)
+        );
+    });
+});

package/src/hook/useWalletStatus.ts

@@ -0,0 +1,55 @@
+import type { WalletStatusReturnType } from "@frak-labs/core-sdk";
+import { watchWalletStatus } from "@frak-labs/core-sdk/actions";
+import { ClientNotFound } from "@frak-labs/frame-connector";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { useFrakClient } from "./useFrakClient";
+
+/**
+ * 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
+ */
+export function useWalletStatus() {
+    const queryClient = useQueryClient();
+    const client = useFrakClient();
+
+    /**
+     * Callback hook when we receive an updated wallet status
+     */
+    const newStatusUpdated = useCallback(
+        (event: WalletStatusReturnType) => {
+            queryClient.setQueryData(
+                ["frak-sdk", "wallet-status-listener"],
+                event
+            );
+        },
+        [queryClient]
+    );
+
+    /**
+     * Setup the query listener
+     */
+    return useQuery<WalletStatusReturnType>({
+        gcTime: 0,
+        staleTime: 0,
+        queryKey: ["frak-sdk", "wallet-status-listener"],
+        queryFn: async () => {
+            if (!client) {
+                throw new ClientNotFound();
+            }
+
+            return watchWalletStatus(client, newStatusUpdated);
+        },
+        enabled: !!client,
+    });
+}

package/src/hook/utils/useFrakContext.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Tests for useFrakContext hook
+ * Tests hook that extracts and manages Frak context from URL
+ */
+
+import { vi } from "vitest";
+
+vi.mock("@frak-labs/core-sdk", async () => {
+    const actual = await vi.importActual<typeof import("@frak-labs/core-sdk")>(
+        "@frak-labs/core-sdk"
+    );
+    return {
+        ...actual,
+        FrakContextManager: {
+            parse: vi.fn(),
+            replaceUrl: vi.fn(),
+        },
+    };
+});
+
+vi.mock("./useWindowLocation");
+
+import type { FrakContext } from "@frak-labs/core-sdk";
+import { FrakContextManager } from "@frak-labs/core-sdk";
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { useFrakContext } from "./useFrakContext";
+import { useWindowLocation } from "./useWindowLocation";
+
+describe("useFrakContext", () => {
+    const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        consoleLogSpy.mockClear();
+    });
+
+    test("should return null when no location href", () => {
+        vi.mocked(useWindowLocation).mockReturnValue({
+            location: undefined,
+            href: undefined,
+        });
+
+        const { result } = renderHook(() => useFrakContext());
+
+        expect(result.current.frakContext).toBeNull();
+    });
+
+    test("should parse frak context from URL", () => {
+        const mockContext: FrakContext = {
+            r: "0x1234567890123456789012345678901234567890",
+        };
+
+        vi.mocked(useWindowLocation).mockReturnValue({
+            location: { href: "https://example.com?frak=test" } as Location,
+            href: "https://example.com?frak=test",
+        });
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue(mockContext);
+
+        const { result } = renderHook(() => useFrakContext());
+
+        expect(FrakContextManager.parse).toHaveBeenCalledWith({
+            url: "https://example.com?frak=test",
+        });
+        expect(result.current.frakContext).toEqual(mockContext);
+    });
+
+    test("should update context with new values", () => {
+        vi.mocked(useWindowLocation).mockReturnValue({
+            location: { href: "https://example.com" } as Location,
+            href: "https://example.com",
+        });
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue(null);
+
+        const { result } = renderHook(() => useFrakContext());
+
+        const newContext: Partial<FrakContext> = {
+            r: "0x4567890123456789012345678901234567890123",
+        };
+
+        result.current.updateContext(newContext);
+
+        expect(console.log).toHaveBeenCalledWith("Updating context", {
+            newContext,
+        });
+        expect(FrakContextManager.replaceUrl).toHaveBeenCalledWith({
+            url: "https://example.com",
+            context: newContext,
+        });
+    });
+
+    test("should memoize frak context based on href", () => {
+        const mockContext: FrakContext = {
+            r: "0x7890123456789012345678901234567890123456",
+        };
+
+        vi.mocked(useWindowLocation).mockReturnValue({
+            location: { href: "https://example.com?test=1" } as Location,
+            href: "https://example.com?test=1",
+        });
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue(mockContext);
+
+        const { result, rerender } = renderHook(() => useFrakContext());
+
+        const firstContext = result.current.frakContext;
+
+        // Rerender without changing href
+        rerender();
+
+        expect(result.current.frakContext).toBe(firstContext);
+        expect(FrakContextManager.parse).toHaveBeenCalledTimes(1);
+    });
+
+    test("should reparse context when href changes", () => {
+        const mockContext1: FrakContext = {
+            r: "0x1111111111111111111111111111111111111111",
+        };
+        const mockContext2: FrakContext = {
+            r: "0x2222222222222222222222222222222222222222",
+        };
+
+        const { rerender } = renderHook(() => useFrakContext());
+
+        vi.mocked(useWindowLocation).mockReturnValue({
+            location: { href: "https://example.com?v=1" } as Location,
+            href: "https://example.com?v=1",
+        });
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue(mockContext1);
+
+        rerender();
+
+        expect(FrakContextManager.parse).toHaveBeenCalledWith({
+            url: "https://example.com?v=1",
+        });
+
+        // Change href
+        vi.mocked(useWindowLocation).mockReturnValue({
+            location: { href: "https://example.com?v=2" } as Location,
+            href: "https://example.com?v=2",
+        });
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue(mockContext2);
+
+        rerender();
+
+        expect(FrakContextManager.parse).toHaveBeenCalledWith({
+            url: "https://example.com?v=2",
+        });
+    });
+});

package/src/hook/utils/useFrakContext.ts

@@ -0,0 +1,42 @@
+import { type FrakContext, FrakContextManager } from "@frak-labs/core-sdk";
+import { useCallback, useMemo } from "react";
+import { useWindowLocation } from "./useWindowLocation";
+
+/**
+ * Extract the current frak context from the url
+ * @ignore
+ */
+export function useFrakContext() {
+    // Get the current window location
+    const { location } = useWindowLocation();
+
+    /**
+     * Fetching and parsing the current frak context
+     */
+    const frakContext = useMemo(() => {
+        // If no url extracted yet, early exit
+        if (!location?.href) return null;
+
+        // Parse the current context
+        return FrakContextManager.parse({ url: location.href });
+    }, [location?.href]);
+
+    /**
+     * Update the current context
+     */
+    const updateContext = useCallback(
+        (newContext: Partial<FrakContext>) => {
+            console.log("Updating context", { newContext });
+            FrakContextManager.replaceUrl({
+                url: location?.href,
+                context: newContext,
+            });
+        },
+        [location?.href]
+    );
+
+    return {
+        frakContext,
+        updateContext,
+    };
+}

package/src/hook/utils/useMounted.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Tests for useMounted hook
+ * Tests that the hook correctly tracks component mount state
+ */
+
+import { renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import { useMounted } from "./useMounted";
+
+describe("useMounted", () => {
+    it("should return true after mount", async () => {
+        const { result } = renderHook(() => useMounted());
+
+        // In React Testing Library, effects run synchronously after render
+        // So by the time we check result.current, the effect has already run
+        await waitFor(() => {
+            expect(result.current).toBe(true);
+        });
+    });
+
+    it("should remain true after multiple re-renders", async () => {
+        const { result, rerender } = renderHook(() => useMounted());
+
+        // Wait for initial mount
+        await waitFor(() => {
+            expect(result.current).toBe(true);
+        });
+
+        // Re-render multiple times
+        rerender();
+        expect(result.current).toBe(true);
+
+        rerender();
+        expect(result.current).toBe(true);
+
+        rerender();
+        expect(result.current).toBe(true);
+    });
+
+    it("should be stable across re-renders", async () => {
+        const { result, rerender } = renderHook(() => useMounted());
+
+        // Wait for mount
+        await waitFor(() => {
+            expect(result.current).toBe(true);
+        });
+
+        const firstValue = result.current;
+
+        // Re-render
+        rerender();
+        const secondValue = result.current;
+
+        // Values should be the same
+        expect(firstValue).toBe(secondValue);
+        expect(firstValue).toBe(true);
+    });
+
+    it("should handle unmounting gracefully", async () => {
+        const { result, unmount } = renderHook(() => useMounted());
+
+        // Wait for mount
+        await waitFor(() => {
+            expect(result.current).toBe(true);
+        });
+
+        // Unmount should not throw
+        expect(() => unmount()).not.toThrow();
+    });
+});

package/src/hook/utils/useMounted.ts

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react";
+
+/** @ignore */
+export function useMounted() {
+    const [mounted, setMounted] = useState(false);
+
+    useEffect(() => {
+        setMounted(true);
+    }, []);
+
+    return mounted;
+}

package/src/hook/utils/useWindowLocation.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Tests for useWindowLocation hook
+ * Tests hook that tracks window.location changes
+ */
+
+import { renderHook } from "@testing-library/react";
+import { describe, expect, test, vi } from "vitest";
+import { useWindowLocation } from "./useWindowLocation";
+
+describe("useWindowLocation", () => {
+    test("should return current window location", () => {
+        const { result } = renderHook(() => useWindowLocation());
+
+        expect(result.current.location).toBeDefined();
+        expect(result.current.href).toBeDefined();
+        expect(typeof result.current.href).toBe("string");
+    });
+
+    test("should derive href from location", () => {
+        const { result } = renderHook(() => useWindowLocation());
+
+        if (result.current.location) {
+            expect(result.current.href).toBe(result.current.location.href);
+        }
+    });
+
+    test("should register popstate listener", () => {
+        const addEventListenerSpy = vi.spyOn(window, "addEventListener");
+
+        renderHook(() => useWindowLocation());
+
+        expect(addEventListenerSpy).toHaveBeenCalledWith(
+            "popstate",
+            expect.any(Function)
+        );
+
+        addEventListenerSpy.mockRestore();
+    });
+
+    test("should cleanup popstate listener on unmount", () => {
+        const removeEventListenerSpy = vi.spyOn(window, "removeEventListener");
+
+        const { unmount } = renderHook(() => useWindowLocation());
+
+        unmount();
+
+        expect(removeEventListenerSpy).toHaveBeenCalledWith(
+            "popstate",
+            expect.any(Function)
+        );
+
+        removeEventListenerSpy.mockRestore();
+    });
+});

package/src/hook/utils/useWindowLocation.ts

@@ -0,0 +1,40 @@
+import { useEffect, useMemo, useState } from "react";
+import { useMounted } from "./useMounted";
+
+/**
+ * Returns the current window location and href
+ * @ignore
+ */
+export function useWindowLocation(): {
+    location: Location | undefined;
+    href: string | undefined;
+} {
+    const isMounted = useMounted();
+    const [location, setLocation] = useState<Location | undefined>(
+        isMounted ? window.location : undefined
+    );
+
+    useEffect(() => {
+        if (!isMounted) return;
+
+        // Method to the current window location
+        function setWindowLocation() {
+            setLocation(window.location);
+        }
+
+        if (!location) {
+            setWindowLocation();
+        }
+
+        window.addEventListener("popstate", setWindowLocation);
+
+        return () => {
+            window.removeEventListener("popstate", setWindowLocation);
+        };
+    }, [isMounted, location]);
+
+    // Derive the href from the location
+    const href = useMemo(() => location?.href, [location?.href]);
+
+    return { location, href };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// Providers export
+
+// Hooks export
+export {
+    useDisplayModal,
+    useFrakClient,
+    useFrakConfig,
+    useGetMerchantInformation,
+    useOpenSso,
+    usePrepareSso,
+    useReferralInteraction,
+    useSendTransactionAction,
+    useSiweAuthenticate,
+    useWalletStatus,
+} from "./hook";
+export type {
+    FrakConfigProviderProps,
+    FrakIFrameClientProps,
+} from "./provider";
+export {
+    FrakConfigContext,
+    FrakConfigProvider,
+    FrakIFrameClientContext,
+    FrakIFrameClientProvider,
+} from "./provider";