@frak-labs/react-sdk 0.1.1 → 0.2.0

package/src/hook/useGetMerchantInformation.ts

@@ -0,0 +1,56 @@
+import type { GetMerchantInformationReturnType } from "@frak-labs/core-sdk";
+import { getMerchantInformation } from "@frak-labs/core-sdk/actions";
+import { ClientNotFound, type FrakRpcError } from "@frak-labs/frame-connector";
+import { type UseQueryOptions, useQuery } from "@tanstack/react-query";
+import { useFrakClient } from "./useFrakClient";
+
+/** @ignore */
+type QueryOptions = Omit<
+    UseQueryOptions<
+        GetMerchantInformationReturnType,
+        FrakRpcError,
+        GetMerchantInformationReturnType
+    >,
+    "queryKey" | "queryFn"
+>;
+
+/** @inline */
+interface UseGetMerchantInformationParams {
+    /**
+     * Optional query options, see {@link @tanstack/react-query!useQuery | `useQuery()`} for more infos
+     */
+    query?: QueryOptions;
+}
+
+/**
+ * Hook that return a query helping to get the current merchant information
+ *
+ * It's a {@link @tanstack/react-query!home | `tanstack`} wrapper around the {@link @frak-labs/core-sdk!actions.getMerchantInformation | `getMerchantInformation()`} action
+ *
+ * @param args - Optional config object with `query` for customizing the underlying {@link @tanstack/react-query!useQuery | `useQuery()`}
+ *
+ * @group hooks
+ *
+ * @returns
+ * The query hook wrapping the `getMerchantInformation()` action
+ * The `data` result is a {@link @frak-labs/core-sdk!index.GetMerchantInformationReturnType | `GetMerchantInformationReturnType`}
+ *
+ * @see {@link @frak-labs/core-sdk!actions.getMerchantInformation | `getMerchantInformation()`} for more info about the underlying action
+ * @see {@link @tanstack/react-query!useQuery | `useQuery()`} for more info about the useQuery options and response
+ */
+export function useGetMerchantInformation({
+    query,
+}: UseGetMerchantInformationParams = {}) {
+    const client = useFrakClient();
+
+    return useQuery({
+        ...query,
+        queryKey: ["frak-sdk", "get-merchant-information"],
+        queryFn: async () => {
+            if (!client) {
+                throw new ClientNotFound();
+            }
+            return getMerchantInformation(client);
+        },
+    });
+}

package/src/hook/useOpenSso.test.ts

@@ -0,0 +1,202 @@
+/**
+ * Tests for useOpenSso hook
+ * Tests TanStack Mutation wrapper for opening SSO
+ */
+
+import { vi } from "vitest";
+
+vi.mock("@frak-labs/core-sdk/actions");
+
+import type { OpenSsoReturnType } from "@frak-labs/core-sdk";
+import { openSso } 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 { useOpenSso } from "./useOpenSso";
+
+describe("useOpenSso", () => {
+    test("should throw ClientNotFound when client is not available", async ({
+        queryWrapper,
+    }) => {
+        const { result } = renderHook(() => useOpenSso(), {
+            wrapper: queryWrapper.wrapper,
+        });
+
+        await waitFor(() => {
+            expect(result.current.mutate).toBeDefined();
+        });
+
+        result.current.mutate({});
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toBeInstanceOf(ClientNotFound);
+    });
+
+    test("should open SSO successfully", async ({ mockFrakProviders }) => {
+        const mockResult = undefined as unknown as OpenSsoReturnType;
+
+        vi.mocked(openSso).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useOpenSso(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({});
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(openSso).toHaveBeenCalledTimes(1);
+    });
+
+    test("should open SSO with redirectUrl", async ({ mockFrakProviders }) => {
+        const mockResult = undefined as unknown as OpenSsoReturnType;
+
+        vi.mocked(openSso).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useOpenSso(), {
+            wrapper: mockFrakProviders,
+        });
+
+        const redirectUrl = "https://example.com/callback";
+
+        result.current.mutate({
+            redirectUrl,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(openSso).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.objectContaining({
+                redirectUrl,
+            })
+        );
+    });
+
+    test("should open SSO with metadata", async ({ mockFrakProviders }) => {
+        const mockResult = undefined as unknown as OpenSsoReturnType;
+
+        vi.mocked(openSso).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useOpenSso(), {
+            wrapper: mockFrakProviders,
+        });
+
+        const metadata = {
+            logoUrl: "https://example.com/logo.png",
+            homepageLink: "https://example.com",
+        };
+
+        result.current.mutate({
+            metadata,
+            directExit: true,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(openSso).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.objectContaining({
+                metadata,
+                directExit: true,
+            })
+        );
+    });
+
+    test("should handle mutateAsync", async ({ mockFrakProviders }) => {
+        const mockResult = undefined as unknown as OpenSsoReturnType;
+
+        vi.mocked(openSso).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useOpenSso(), {
+            wrapper: mockFrakProviders,
+        });
+
+        await result.current.mutateAsync({
+            directExit: false,
+        });
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+    });
+
+    test("should handle RPC errors", async ({ mockFrakProviders }) => {
+        const error = new Error("SSO open failed");
+        vi.mocked(openSso).mockRejectedValue(error);
+
+        const { result } = renderHook(() => useOpenSso(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({});
+
+        await waitFor(() => {
+            expect(result.current.isError).toBe(true);
+        });
+
+        expect(result.current.error).toEqual(error);
+    });
+
+    test("should handle mutation options", async ({ mockFrakProviders }) => {
+        const mockResult = undefined as unknown as OpenSsoReturnType;
+
+        vi.mocked(openSso).mockResolvedValue(mockResult);
+
+        const onSuccess = vi.fn();
+        const onError = vi.fn();
+
+        const { result } = renderHook(
+            () =>
+                useOpenSso({
+                    mutations: {
+                        onSuccess,
+                        onError,
+                    },
+                }),
+            {
+                wrapper: mockFrakProviders,
+            }
+        );
+
+        result.current.mutate({});
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        expect(onSuccess).toHaveBeenCalled();
+        expect(onError).not.toHaveBeenCalled();
+    });
+
+    test("should reset mutation state", async ({ mockFrakProviders }) => {
+        const mockResult = undefined as unknown as OpenSsoReturnType;
+
+        vi.mocked(openSso).mockResolvedValue(mockResult);
+
+        const { result } = renderHook(() => useOpenSso(), {
+            wrapper: mockFrakProviders,
+        });
+
+        result.current.mutate({});
+
+        await waitFor(() => {
+            expect(result.current.isSuccess).toBe(true);
+        });
+
+        result.current.reset();
+
+        await waitFor(() => {
+            expect(result.current.isIdle).toBe(true);
+        });
+    });
+});

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