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

package/src/hook/useOpenSso.ts

@@ -0,0 +1,51 @@
+import type { OpenSsoParamsType, OpenSsoReturnType } from "@frak-labs/core-sdk";
+import { openSso } 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 = Omit<
+    UseMutationOptions<OpenSsoReturnType, FrakRpcError, OpenSsoParamsType>,
+    "mutationFn" | "mutationKey"
+>;
+
+/** @inline */
+interface UseOpenSsoParams {
+    /**
+     * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
+     */
+    mutations?: MutationOptions;
+}
+
+/**
+ * Hook that return a mutation helping to open the SSO page
+ *
+ * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.openSso | `openSso()`} action
+ *
+ * @param args - Optional config object with `mutations` for customizing the underlying {@link @tanstack/react-query!useMutation | `useMutation()`}
+ *
+ * @group hooks
+ *
+ * @returns
+ * The mutation hook wrapping the `openSso()` action
+ * The `mutate` and `mutateAsync` argument is of type {@link @frak-labs/core-sdk!index.OpenSsoParamsType | `OpenSsoParamsType`}
+ * The mutation doesn't output any value
+ *
+ * @see {@link @frak-labs/core-sdk!actions.openSso | `openSso()`} 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 useOpenSso({ mutations }: UseOpenSsoParams = {}) {
+    const client = useFrakClient();
+
+    return useMutation({
+        ...mutations,
+        mutationKey: ["frak-sdk", "open-sso"],
+        mutationFn: async (params: OpenSsoParamsType) => {
+            if (!client) {
+                throw new ClientNotFound();
+            }
+            return openSso(client, params);
+        },
+    });
+}

package/src/hook/usePrepareSso.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Tests for usePrepareSso hook
+ * Tests TanStack Query wrapper for preparing SSO URLs
+ */
+
+import { vi } from "vitest";
+
+vi.mock("@frak-labs/core-sdk/actions");
+
+import type { PrepareSsoReturnType } from "@frak-labs/core-sdk";
+import { prepareSso } 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 { usePrepareSso } from "./usePrepareSso";
+
+describe("usePrepareSso", () => {
+    test("should throw ClientNotFound when client is not available", async ({
+        queryWrapper,
+    }) => {
+        const { result } = renderHook(
+            () => usePrepareSso({ directExit: true }),
+            {
+                wrapper: queryWrapper.wrapper,
+            }
+        );
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toBeInstanceOf(ClientNotFound);
+    });
+
+    test("should prepare SSO URL successfully", async ({
+        mockFrakProviders,
+    }) => {
+        const mockSsoResult: PrepareSsoReturnType = {
+            ssoUrl: "https://wallet-test.frak.id/sso?params=xyz",
+        };
+
+        vi.mocked(prepareSso).mockResolvedValue(mockSsoResult);
+
+        const { result } = renderHook(
+            () => usePrepareSso({ directExit: true }),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockSsoResult);
+        expect(result.current.data?.ssoUrl).toContain("sso");
+    });
+
+    test("should handle SSO params with redirectUrl", async ({
+        mockFrakProviders,
+    }) => {
+        const mockSsoResult: PrepareSsoReturnType = {
+            ssoUrl: "https://wallet-test.frak.id/sso?redirect=example.com",
+        };
+
+        vi.mocked(prepareSso).mockResolvedValue(mockSsoResult);
+
+        const { result } = renderHook(
+            () =>
+                usePrepareSso({
+                    redirectUrl: "https://example.com/callback",
+                    directExit: false,
+                }),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockSsoResult);
+        expect(prepareSso).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.objectContaining({
+                redirectUrl: "https://example.com/callback",
+                directExit: false,
+            })
+        );
+    });
+
+    test("should handle SSO params with metadata", async ({
+        mockFrakProviders,
+    }) => {
+        const mockSsoResult: PrepareSsoReturnType = {
+            ssoUrl: "https://wallet-test.frak.id/sso?metadata=xyz",
+        };
+
+        vi.mocked(prepareSso).mockResolvedValue(mockSsoResult);
+
+        const { result } = renderHook(
+            () =>
+                usePrepareSso({
+                    metadata: {
+                        logoUrl: "https://example.com/logo.png",
+                        homepageLink: "https://example.com",
+                    },
+                    directExit: true,
+                }),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockSsoResult);
+    });
+
+    test("should handle RPC errors", async ({ mockFrakProviders }) => {
+        const error = new Error("SSO preparation failed");
+        vi.mocked(prepareSso).mockRejectedValue(error);
+
+        const { result } = renderHook(
+            () => usePrepareSso({ directExit: true }),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toEqual(error);
+    });
+
+    test("should update query key with params", async ({
+        mockFrakProviders,
+    }) => {
+        const mockSsoResult: PrepareSsoReturnType = {
+            ssoUrl: "https://wallet-test.frak.id/sso?params=abc",
+        };
+
+        vi.mocked(prepareSso).mockResolvedValue(mockSsoResult);
+
+        const params = {
+            directExit: false,
+            redirectUrl: "https://example.com",
+        };
+
+        const { result, rerender } = renderHook(() => usePrepareSso(params), {
+            wrapper: mockFrakProviders,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockSsoResult);
+
+        // Query key includes params, so changes should trigger re-fetch
+        rerender();
+        expect(result.current.data).toEqual(mockSsoResult);
+    });
+
+    test("should call prepareSso with client and params", async ({
+        mockFrakProviders,
+        mockFrakClient,
+    }) => {
+        const mockSsoResult: PrepareSsoReturnType = {
+            ssoUrl: "https://wallet-test.frak.id/sso?test=123",
+        };
+
+        vi.mocked(prepareSso).mockResolvedValue(mockSsoResult);
+
+        const params = {
+            directExit: true,
+            metadata: {
+                logoUrl: "https://example.com/logo.png",
+            },
+        };
+
+        const { result } = renderHook(() => usePrepareSso(params), {
+            wrapper: mockFrakProviders,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(prepareSso).toHaveBeenCalledWith(mockFrakClient, params);
+    });
+});

package/src/hook/usePrepareSso.ts

@@ -0,0 +1,55 @@
+import type { PrepareSsoParamsType } from "@frak-labs/core-sdk";
+import { prepareSso } from "@frak-labs/core-sdk/actions";
+import { ClientNotFound } from "@frak-labs/frame-connector";
+import { useQuery } from "@tanstack/react-query";
+import { useFrakClient } from "./useFrakClient";
+
+/**
+ * Hook that generates SSO URL for popup flow
+ *
+ * This is a **synchronous** hook (no async calls) that generates the SSO URL
+ * client-side without communicating with the wallet iframe.
+ *
+ * @param params - SSO parameters for URL generation
+ *
+ * @group hooks
+ *
+ * @returns
+ * Object containing:
+ * - `ssoUrl`: Generated SSO URL (or undefined if client not ready)
+ * - `isReady`: Boolean indicating if URL is available
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { data } = usePrepareSso({
+ *     metadata: { logoUrl: "..." },
+ *     directExit: true
+ *   });
+ *
+ *   const handleClick = () => {
+ *     if (ssoUrl) {
+ *       window.open(data?.ssoUrl, "_blank");
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleClick} disabled={!isReady}>Login</button>;
+ * }
+ * ```
+ *
+ * @see {@link @frak-labs/core-sdk!actions.prepareSso | `prepareSso()`} for the underlying action
+ * @see {@link @frak-labs/core-sdk!actions.openSso | `openSso()`} for the recommended high-level API
+ */
+export function usePrepareSso(params: PrepareSsoParamsType) {
+    const client = useFrakClient();
+
+    return useQuery({
+        queryKey: ["frak-sdk", "prepare-sso", params],
+        queryFn: async () => {
+            if (!client) {
+                throw new ClientNotFound();
+            }
+            return prepareSso(client, params);
+        },
+    });
+}

package/src/hook/useSendTransaction.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Tests for useSendTransactionAction hook
+ * Tests TanStack Mutation wrapper for sending transactions
+ */
+
+import { vi } from "vitest";
+
+vi.mock("@frak-labs/core-sdk/actions");
+
+import type { SendTransactionReturnType } from "@frak-labs/core-sdk";
+import { sendTransaction } from "@frak-labs/core-sdk/actions";
+import { ClientNotFound } from "@frak-labs/frame-connector";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { Hex } from "viem";
+import { describe, expect, test } from "../../tests/vitest-fixtures";
+import { useSendTransactionAction } from "./useSendTransaction";
+
+describe("useSendTransactionAction", () => {
+    test("should throw ClientNotFound when client is not available", async ({
+        queryWrapper,
+    }) => {
+        const { result } = renderHook(() => useSendTransactionAction(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(result.current.mutate).toBeDefined();
+        });
+
+        result.current.mutate({
+            tx: {
+                to: "0x1234567890123456789012345678901234567890",
+                data: "0x",
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toBeInstanceOf(ClientNotFound);
+    });
+
+    test("should send transaction successfully", async ({
+        mockFrakProviders,
+    }) => {
+        const mockResult: SendTransactionReturnType = {
+            hash: "0xabcdef1234567890" as Hex,
+        };
+
+        vi.mocked(sendTransaction).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useSendTransactionAction(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({
+            tx: {
+                to: "0x1234567890123456789012345678901234567890",
+                data: "0x",
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockResult);
+        expect(sendTransaction).toHaveBeenCalledTimes(1);
+    });
+
+    test("should send transaction with metadata", async ({
+        mockFrakProviders,
+    }) => {
+        const mockResult: SendTransactionReturnType = {
+            hash: "0xhash123" as Hex,
+        };
+
+        vi.mocked(sendTransaction).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useSendTransactionAction(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({
+            tx: {
+                to: "0x1234567890123456789012345678901234567890",
+                data: "0x",
+            },
+            metadata: {
+                header: {
+                    title: "Send Transaction",
+                },
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(result.current.data).toEqual(mockResult);
+    });
+
+    test("should handle mutateAsync", async ({ mockFrakProviders }) => {
+        const mockResult: SendTransactionReturnType = {
+            hash: "0xasync123" as Hex,
+        };
+
+        vi.mocked(sendTransaction).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useSendTransactionAction(), {
+            wrapper: mockFrakProviders,
+        });
+
+        const response = await result.current.mutateAsync({
+            tx: {
+                to: "0x1234567890123456789012345678901234567890",
+                data: "0x",
+            },
+        });
+
+        expect(response).toEqual(mockResult);
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+    });
+
+    test("should handle RPC errors", async ({ mockFrakProviders }) => {
+        const error = new Error("Transaction send failed");
+        vi.mocked(sendTransaction).mockRejectedValue(error);
+
+        const { result } = renderHook(() => useSendTransactionAction(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({
+            tx: {
+                to: "0x1234567890123456789012345678901234567890",
+                data: "0x",
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toEqual(error);
+    });
+
+    test("should handle mutation options", async ({ mockFrakProviders }) => {
+        const mockResult: SendTransactionReturnType = {
+            hash: "0xoptions123" as Hex,
+        };
+
+        vi.mocked(sendTransaction).mockResolvedValue(mockResult);
+
+        const onSuccess = vi.fn();
+        const onError = vi.fn();
+
+        const { result } = renderHook(
+            () =>
+                useSendTransactionAction({
+                    mutations: {
+                        onSuccess,
+                        onError,
+                    },
+                }),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        result.current.mutate({
+            tx: {
+                to: "0x1234567890123456789012345678901234567890",
+                data: "0x",
+            },
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(onSuccess).toHaveBeenCalled();
+        expect(onError).not.toHaveBeenCalled();
+    });
+
+    test("should reset mutation state", async ({ mockFrakProviders }) => {
+        const mockResult: SendTransactionReturnType = {
+            hash: "0xreset123" as Hex,
+        };
+
+        vi.mocked(sendTransaction).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useSendTransactionAction(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({
+            tx: {
+                to: "0x1234567890123456789012345678901234567890",
+                data: "0x",
+            },
+        });
+
+        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/useSendTransaction.ts

@@ -0,0 +1,62 @@
+import type { SendTransactionReturnType } from "@frak-labs/core-sdk";
+import {
+    type SendTransactionParams,
+    sendTransaction,
+} 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 = Omit<
+    UseMutationOptions<
+        SendTransactionReturnType,
+        FrakRpcError,
+        SendTransactionParams
+    >,
+    "mutationFn" | "mutationKey"
+>;
+
+/** @inline */
+interface UseSendTransactionParams {
+    /**
+     * Optional mutation options, see {@link @tanstack/react-query!useMutation | `useMutation()`} for more infos
+     */
+    mutations?: MutationOptions;
+}
+
+/**
+ * Hook that return a mutation helping to send a transaction
+ *
+ * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.sendTransaction | `sendTransaction()`} action
+ *
+ * @param args - Optional config object with `mutations` for customizing the underlying {@link @tanstack/react-query!useMutation | `useMutation()`}
+ *
+ * @group hooks
+ *
+ * @returns
+ * The mutation hook wrapping the `sendTransaction()` action
+ * The `mutate` and `mutateAsync` argument is of type {@link @frak-labs/core-sdk!actions.SendTransactionParams | `SendTransactionParams`}
+ * The `data` result is a {@link @frak-labs/core-sdk!index.SendTransactionReturnType | `SendTransactionReturnType`}
+ *
+ * @see {@link @frak-labs/core-sdk!actions.sendTransaction | `sendTransaction()`} 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 useSendTransactionAction({
+    mutations,
+}: UseSendTransactionParams = {}) {
+    const client = useFrakClient();
+
+    return useMutation({
+        ...mutations,
+        mutationKey: ["frak-sdk", "send-transaction"],
+        mutationFn: async (params: SendTransactionParams) => {
+            if (!client) {
+                throw new ClientNotFound();
+            }
+
+            // Send the transaction
+            return sendTransaction(client, params);
+        },
+    });
+}