@frak-labs/react-sdk 0.1.1 → 0.2.0

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);
+        });
+    });
+});

package/src/hook/useDisplayModal.ts

@@ -0,0 +1,68 @@
+import type {
+    DisplayModalParamsType,
+    ModalRpcStepsResultType,
+    ModalStepTypes,
+} from "@frak-labs/core-sdk";
+import { displayModal } from "@frak-labs/core-sdk/actions";
+import { ClientNotFound, type FrakRpcError } from "@frak-labs/frame-connector";
+import { type UseMutationOptions, useMutation } from "@tanstack/react-query";
+import { useFrakClient } from "./useFrakClient";
+
+/** @ignore */
+type MutationOptions<T extends ModalStepTypes[]> = Omit<
+    UseMutationOptions<
+        ModalRpcStepsResultType<T>,
+        FrakRpcError,
+        DisplayModalParamsType<T>
+    >,
+    "mutationFn" | "mutationKey"
+>;
+
+/** @inline */
+interface UseDisplayModalParams<T extends ModalStepTypes[] = ModalStepTypes[]> {
+    /**
+     * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
+     */
+    mutations?: MutationOptions<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
+ */
+export function useDisplayModal<T extends ModalStepTypes[] = ModalStepTypes[]>({
+    mutations,
+}: UseDisplayModalParams<T> = {}) {
+    const client = useFrakClient();
+
+    return useMutation({
+        ...mutations,
+        mutationKey: ["frak-sdk", "display-modal"],
+        mutationFn: async (args: DisplayModalParamsType<T>) => {
+            if (!client) {
+                throw new ClientNotFound();
+            }
+
+            // Ask to display the modal
+            return displayModal(client, args);
+        },
+    });
+}

package/src/hook/useFrakClient.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Tests for useFrakClient hook
+ * Tests that the hook correctly retrieves the FrakClient from context
+ */
+
+import { renderHook } from "@testing-library/react";
+import { createElement } from "react";
+import { describe, expect, test } from "../../tests/vitest-fixtures";
+import { FrakIFrameClientContext } from "../provider/FrakIFrameClientProvider";
+import { useFrakClient } from "./useFrakClient";
+
+describe("useFrakClient", () => {
+    test("should return undefined when used outside provider", () => {
+        const { result } = renderHook(() => useFrakClient());
+
+        expect(result.current).toBeUndefined();
+    });
+
+    test("should return client when used inside provider", ({
+        mockFrakClient,
+    }) => {
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            createElement(
+                FrakIFrameClientContext.Provider,
+                { value: mockFrakClient },
+                children
+            );
+
+        const { result } = renderHook(() => useFrakClient(), {
+            wrapper,
+        });
+
+        expect(result.current).toBe(mockFrakClient);
+    });
+
+    test("should return the same client instance across re-renders", ({
+        mockFrakClient,
+    }) => {
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            createElement(
+                FrakIFrameClientContext.Provider,
+                { value: mockFrakClient },
+                children
+            );
+
+        const { result, rerender } = renderHook(() => useFrakClient(), {
+            wrapper,
+        });
+
+        const firstClient = result.current;
+        rerender();
+        const secondClient = result.current;
+
+        expect(firstClient).toBe(secondClient);
+        expect(firstClient).toBe(mockFrakClient);
+    });
+
+    test("should update when provider value changes", ({
+        mockFrakClient,
+        mockFrakConfig,
+    }) => {
+        const newMockClient = {
+            ...mockFrakClient,
+            config: {
+                ...mockFrakConfig,
+                domain: "new-domain.com",
+            },
+        };
+
+        let currentClient = mockFrakClient;
+
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            createElement(
+                FrakIFrameClientContext.Provider,
+                { value: currentClient },
+                children
+            );
+
+        const { result, rerender } = renderHook(() => useFrakClient(), {
+            wrapper,
+        });
+
+        // Initially returns first client
+        expect(result.current).toBe(mockFrakClient);
+
+        // Update the client in provider
+        currentClient = newMockClient;
+        rerender();
+
+        // Should return new client
+        expect(result.current).toBe(newMockClient);
+        expect(result.current?.config.domain).toBe("new-domain.com");
+    });
+
+    test("should handle client becoming undefined", ({ mockFrakClient }) => {
+        let currentClient: typeof mockFrakClient | undefined = mockFrakClient;
+
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            createElement(
+                FrakIFrameClientContext.Provider,
+                { value: currentClient },
+                children
+            );
+
+        const { result, rerender } = renderHook(() => useFrakClient(), {
+            wrapper,
+        });
+
+        // Initially returns client
+        expect(result.current).toBe(mockFrakClient);
+
+        // Set client to undefined
+        currentClient = undefined;
+        rerender();
+
+        // Should return undefined
+        expect(result.current).toBeUndefined();
+    });
+});

package/src/hook/useFrakClient.ts

@@ -0,0 +1,11 @@
+import { useContext } from "react";
+import { FrakIFrameClientContext } from "../provider";
+
+/**
+ * Get the current Frak client
+ *
+ * @group hooks
+ */
+export function useFrakClient() {
+    return useContext(FrakIFrameClientContext);
+}

package/src/hook/useFrakConfig.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Tests for useFrakConfig hook
+ * Tests that the hook correctly retrieves the FrakConfig from context
+ * and throws error when used outside provider
+ */
+
+import { FrakRpcError } from "@frak-labs/frame-connector";
+import { renderHook } from "@testing-library/react";
+import React from "react";
+import { describe, expect, test, vi } from "../../tests/vitest-fixtures";
+import { FrakConfigProvider } from "../provider/FrakConfigProvider";
+import { useFrakConfig } from "./useFrakConfig";
+
+describe("useFrakConfig", () => {
+    test("should throw FrakRpcError when used outside provider", () => {
+        // Mock console.error to avoid noise in test output
+        const consoleErrorSpy = vi
+            .spyOn(console, "error")
+            .mockImplementation(() => {});
+
+        expect(() => {
+            renderHook(() => useFrakConfig());
+        }).toThrow(FrakRpcError);
+
+        try {
+            renderHook(() => useFrakConfig());
+        } catch (error) {
+            expect(error).toBeInstanceOf(FrakRpcError);
+            // FrakRpcError message contains the error code
+            expect((error as FrakRpcError).message).toContain("-32002");
+        }
+
+        consoleErrorSpy.mockRestore();
+    });
+
+    test("should return config when used inside provider", ({
+        mockFrakConfig,
+    }) => {
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            React.createElement(
+                FrakConfigProvider,
+                { config: mockFrakConfig },
+                children
+            );
+
+        const { result } = renderHook(() => useFrakConfig(), {
+            wrapper,
+        });
+
+        expect(result.current).toBeDefined();
+        expect(result.current.domain).toBe(mockFrakConfig.domain);
+        expect(result.current.metadata?.name).toBe(
+            mockFrakConfig.metadata?.name
+        );
+    });
+
+    test("should apply default walletUrl if not provided", () => {
+        const configWithoutWalletUrl = {
+            domain: "example.com",
+            metadata: {
+                name: "Test App",
+            },
+        };
+
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            React.createElement(
+                FrakConfigProvider,
+                { config: configWithoutWalletUrl },
+                children
+            );
+
+        const { result } = renderHook(() => useFrakConfig(), {
+            wrapper,
+        });
+
+        expect(result.current.walletUrl).toBe("https://wallet.frak.id");
+    });
+
+    test("should use provided walletUrl if specified", ({ mockFrakConfig }) => {
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            React.createElement(
+                FrakConfigProvider,
+                { config: mockFrakConfig },
+                children
+            );
+
+        const { result } = renderHook(() => useFrakConfig(), {
+            wrapper,
+        });
+
+        expect(result.current.walletUrl).toBe(mockFrakConfig.walletUrl);
+    });
+
+    test("should return stable config across re-renders", ({
+        mockFrakConfig,
+    }) => {
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            React.createElement(
+                FrakConfigProvider,
+                { config: mockFrakConfig },
+                children
+            );
+
+        const { result, rerender } = renderHook(() => useFrakConfig(), {
+            wrapper,
+        });
+
+        const firstConfig = result.current;
+        rerender();
+        const secondConfig = result.current;
+
+        // Config values should remain stable
+        expect(firstConfig.domain).toBe(secondConfig.domain);
+        expect(firstConfig.walletUrl).toBe(secondConfig.walletUrl);
+        expect(firstConfig.domain).toBe(mockFrakConfig.domain);
+    });
+
+    test("should include all config properties", ({ mockFrakConfig }) => {
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            React.createElement(
+                FrakConfigProvider,
+                { config: mockFrakConfig },
+                children
+            );
+
+        const { result } = renderHook(() => useFrakConfig(), {
+            wrapper,
+        });
+
+        expect(result.current.domain).toBe(mockFrakConfig.domain);
+        expect(result.current.walletUrl).toBe(mockFrakConfig.walletUrl);
+        expect(result.current.metadata).toEqual(mockFrakConfig.metadata);
+        expect(result.current.customizations).toEqual(
+            mockFrakConfig.customizations
+        );
+    });
+
+    test("should handle minimal config", () => {
+        const minimalConfig = {
+            domain: "minimal.com",
+            metadata: {
+                name: "Minimal Test App",
+            },
+        };
+
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            React.createElement(
+                FrakConfigProvider,
+                { config: minimalConfig },
+                children
+            );
+
+        const { result } = renderHook(() => useFrakConfig(), {
+            wrapper,
+        });
+
+        expect(result.current.domain).toBe("minimal.com");
+        expect(result.current.walletUrl).toBe("https://wallet.frak.id");
+        expect(result.current.metadata.name).toBe("Minimal Test App");
+        expect(result.current.customizations).toBeUndefined();
+    });
+
+    test("should fallback to window.location.host if domain not provided", () => {
+        const configWithoutDomain = {
+            metadata: {
+                name: "Test App",
+            },
+        };
+
+        const wrapper = ({ children }: { children: React.ReactNode }) =>
+            React.createElement(
+                FrakConfigProvider,
+                { config: configWithoutDomain as any },
+                children
+            );
+
+        const { result } = renderHook(() => useFrakConfig(), {
+            wrapper,
+        });
+
+        // In test environment, window.location.host is "localhost:3000" (JSDOM default)
+        expect(result.current.domain).toBe(window.location.host);
+    });
+});

package/src/hook/useFrakConfig.ts

@@ -0,0 +1,22 @@
+import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
+import { useContext } from "react";
+import { FrakConfigContext } from "../provider";
+
+/**
+ * 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
+ */
+export function useFrakConfig() {
+    const config = useContext(FrakConfigContext);
+    if (!config) {
+        throw new FrakRpcError(
+            RpcErrorCodes.configError,
+            "Frak config not found"
+        );
+    }
+    return config;
+}