@frak-labs/core-sdk 0.0.19 → 0.1.0-beta.00226d62

package/src/actions/displayModal.test.ts

@@ -0,0 +1,387 @@
+/**
+ * Tests for displayModal action
+ * Tests modal display via RPC with various step configurations
+ */
+
+import type { Address } from "viem";
+import { describe, expect, it, vi } from "../../tests/vitest-fixtures";
+import type {
+    DisplayModalParamsType,
+    FrakClient,
+    ModalStepTypes,
+} from "../types";
+import { displayModal } from "./displayModal";
+
+describe("displayModal", () => {
+    describe("basic modal display", () => {
+        it("should call client.request with correct method and params", async () => {
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: { allowSso: true },
+                },
+            };
+
+            await displayModal(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_displayModal",
+                params: [params.steps, params.metadata, { name: "Test App" }],
+            });
+        });
+
+        it("should return modal results", async () => {
+            const mockResponse = {
+                login: {
+                    wallet: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+                },
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: { allowSso: false },
+                },
+            };
+
+            const result = await displayModal(mockClient, params);
+
+            expect(result).toEqual(mockResponse);
+        });
+    });
+
+    describe("modal with multiple steps", () => {
+        it("should handle login + openSession steps", async () => {
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+                openSession: {
+                    startTimestamp: 1234567890,
+                    endTimestamp: 1234567900,
+                },
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: { allowSso: true },
+                    openSession: {},
+                },
+            };
+
+            const result = await displayModal(mockClient, params);
+
+            expect(result).toEqual(mockResponse);
+        });
+
+        it("should handle full modal flow", async () => {
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+                openSession: {
+                    startTimestamp: 1234567890,
+                    endTimestamp: 1234567900,
+                },
+                sendTransaction: {
+                    hash: "0xtxhash" as `0x${string}`,
+                },
+                final: {},
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                        logoUrl: "https://example.com/logo.png",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: { allowSso: true },
+                    openSession: {},
+                    sendTransaction: {
+                        tx: [
+                            {
+                                to: "0xdeadbeef" as Address,
+                                data: "0xdata" as `0x${string}`,
+                            },
+                        ],
+                    },
+                    final: {
+                        action: { key: "reward" },
+                    },
+                },
+            };
+
+            const result = await displayModal(mockClient, params);
+
+            expect(result).toEqual(mockResponse);
+        });
+    });
+
+    describe("modal with metadata", () => {
+        it("should pass metadata to request", async () => {
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: { allowSso: true },
+                },
+                metadata: {
+                    header: {
+                        title: "My Custom Title",
+                        icon: "https://example.com/icon.png",
+                    },
+                },
+            };
+
+            await displayModal(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_displayModal",
+                params: [
+                    params.steps,
+                    {
+                        header: {
+                            title: "My Custom Title",
+                            icon: "https://example.com/icon.png",
+                        },
+                    },
+                    { name: "Test App" },
+                ],
+            });
+        });
+
+        it("should work without metadata", async () => {
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: { allowSso: true },
+                },
+            };
+
+            await displayModal(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_displayModal",
+                params: [params.steps, undefined, { name: "Test App" }],
+            });
+        });
+    });
+
+    describe("modal with SSO metadata", () => {
+        it("should handle SSO metadata in login step", async () => {
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: {
+                        allowSso: true,
+                        ssoMetadata: {
+                            logoUrl: "https://example.com/logo.png",
+                            homepageLink: "https://example.com",
+                        },
+                    },
+                },
+            };
+
+            await displayModal(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_displayModal",
+                params: [params.steps, undefined, { name: "Test App" }],
+            });
+        });
+    });
+
+    describe("modal with sharing action", () => {
+        it("should handle sharing final action", async () => {
+            const mockResponse = {
+                final: {},
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    final: {
+                        action: {
+                            key: "sharing",
+                            options: {
+                                popupTitle: "Share the app",
+                                text: "Discover my app",
+                                link: "https://example.com",
+                            },
+                        },
+                    },
+                },
+            };
+
+            await displayModal(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_displayModal",
+                params: [params.steps, undefined, { name: "Test App" }],
+            });
+        });
+
+        it("should handle reward final action", async () => {
+            const mockResponse = {
+                final: {},
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    final: {
+                        action: { key: "reward" },
+                        autoSkip: true,
+                    },
+                },
+            };
+
+            await displayModal(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_displayModal",
+                params: [params.steps, undefined, { name: "Test App" }],
+            });
+        });
+    });
+
+    describe("error handling", () => {
+        it("should propagate errors from client.request", async () => {
+            const error = new Error("Modal display failed");
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockRejectedValue(error),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    login: { allowSso: true },
+                },
+            };
+
+            await expect(displayModal(mockClient, params)).rejects.toThrow(
+                "Modal display failed"
+            );
+        });
+
+        it("should handle network errors", async () => {
+            const error = new Error("Network timeout");
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockRejectedValue(error),
+            } as unknown as FrakClient;
+
+            const params: DisplayModalParamsType<ModalStepTypes[]> = {
+                steps: {
+                    openSession: {},
+                },
+            };
+
+            await expect(displayModal(mockClient, params)).rejects.toThrow(
+                "Network timeout"
+            );
+        });
+    });
+});

package/src/actions/displayModal.ts

@@ -0,0 +1,131 @@
+import type {
+    DisplayModalParamsType,
+    FrakClient,
+    ModalRpcStepsResultType,
+    ModalStepTypes,
+} from "../types";
+
+/**
+ * Function used to display a modal
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.steps - The different steps of the modal
+ * @param args.metadata - The metadata for the modal (customization, etc)
+ * @returns The result of each modal steps
+ *
+ * @description This function will display a modal to the user with the provided steps and metadata.
+ *
+ * @remarks
+ * - The UI of the displayed modal can be configured with the `customCss` property in the `customizations.css` field of the top-level config.
+ * - The `login` and `openSession` steps will be automatically skipped if the user is already logged in or has an active session. It's safe to include these steps in all cases to ensure proper user state.
+ * - Steps are automatically reordered in the following sequence:
+ *     1. `login` (if needed)
+ *     2. `openSession` (if needed)
+ *     3. All other steps in the order specified
+ *     4. `success` (if included, always last)
+ *
+ * @example
+ * Simple sharing modal with steps:
+ *  1. Login (Skipped if already logged in)
+ *  2. Open a session (Skipped if already opened)
+ *  3. Display a success message with sharing link option
+ *
+ * ```ts
+ * const results = await displayModal(frakConfig, {
+ *     steps: {
+ *         // Simple login with no SSO, nor customization
+ *         login: { allowSso: false },
+ *         // Simple session opening, with no customization
+ *         openSession: {},
+ *         // Success message
+ *         final: {
+ *             action: { key: "reward" },
+ *             // Skip this step, it will be only displayed in the stepper within the modal
+ *             autoSkip: true,
+ *         },
+ *     },
+ * });
+ *
+ * console.log("Login step - wallet", results.login.wallet);
+ * console.log("Open session step - start + end", {
+ *     start: results.openSession.startTimestamp,
+ *     end: results.openSession.endTimestamp,
+ * });
+ * ```
+ *
+ * @example
+ * A full modal example, with a few customization options, with the steps:
+ *  1. Login (Skipped if already logged in)
+ *  2. Open a session (Skipped if already opened)
+ *  3. Authenticate via SIWE
+ *  4. Send a transaction
+ *  5. Display a success message with sharing link options
+ *
+ * ```ts
+ * const results = await displayModal(frakConfig, {
+ *     steps: {
+ *         // Login step
+ *         login: {
+ *             allowSso: true,
+ *             ssoMetadata: {
+ *                 logoUrl: "https://my-app.com/logo.png",
+ *                 homepageLink: "https://my-app.com",
+ *             },
+ *         },
+ *         // Simple session opening, with no customisation
+ *         openSession: {},
+ *         // Siwe authentication
+ *         siweAuthenticate: {
+ *             siwe: {
+ *                 domain: "my-app.com",
+ *                 uri: "https://my-app.com/",
+ *                 nonce: generateSiweNonce(),
+ *                 version: "1",
+ *             },
+ *         },
+ *         // Send batched transaction
+ *         sendTransaction: {
+ *             tx: [
+ *                 { to: "0xdeadbeef", data: "0xdeadbeef" },
+ *                 { to: "0xdeadbeef", data: "0xdeadbeef" },
+ *             ],
+ *         },
+ *         // Success message with sharing options
+ *         final: {
+ *             action: {
+ *                 key: "sharing",
+ *                 options: {
+ *                     popupTitle: "Share the app",
+ *                     text: "Discover my super app website",
+ *                     link: "https://my-app.com",
+ *                 },
+ *             },
+ *             dismissedMetadata: {
+ *                 title: "Dismiss",
+ *                 description: "You won't be rewarded for this sharing action",
+ *             },
+ *         },
+ *     },
+ *     metadata: {
+ *         // Header of desktop modals
+ *         header: {
+ *             title: "My-App",
+ *             icon: "https://my-app.com/logo.png",
+ *         },
+ *         // Context that will be present in every modal steps
+ *         context: "My-app overkill flow",
+ *     },
+ * });
+ * ```
+ */
+export async function displayModal<
+    T extends ModalStepTypes[] = ModalStepTypes[],
+>(
+    client: FrakClient,
+    { steps, metadata }: DisplayModalParamsType<T>
+): Promise<ModalRpcStepsResultType<T>> {
+    return (await client.request({
+        method: "frak_displayModal",
+        params: [steps, metadata, client.config.metadata],
+    })) as ModalRpcStepsResultType<T>;
+}

package/src/actions/getProductInformation.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Tests for getProductInformation action
+ * Tests fetching product information via RPC
+ */
+
+import type { Address, Hex } from "viem";
+import { describe, expect, it, vi } from "../../tests/vitest-fixtures";
+import type { FrakClient, GetProductInformationReturnType } from "../types";
+import { getProductInformation } from "./getProductInformation";
+
+describe("getProductInformation", () => {
+    describe("success cases", () => {
+        it("should call client.request with correct method", async () => {
+            const mockResponse: GetProductInformationReturnType = {
+                id: "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex,
+                onChainMetadata: {
+                    name: "Test Product",
+                    domain: "example.com",
+                    productTypes: ["press"],
+                },
+                rewards: [],
+            };
+
+            const mockClient = {
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            await getProductInformation(mockClient);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_getProductInformation",
+            });
+        });
+
+        it("should return product information", async () => {
+            const mockResponse: GetProductInformationReturnType = {
+                id: "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex,
+                onChainMetadata: {
+                    name: "Test Product",
+                    domain: "example.com",
+                    productTypes: ["press"],
+                },
+                rewards: [],
+            };
+
+            const mockClient = {
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const result = await getProductInformation(mockClient);
+
+            expect(result).toEqual(mockResponse);
+        });
+
+        it("should return product information with rewards", async () => {
+            const mockResponse: GetProductInformationReturnType = {
+                id: "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex,
+                onChainMetadata: {
+                    name: "Test Product",
+                    domain: "example.com",
+                    productTypes: ["press", "purchase"],
+                },
+                maxReferrer: {
+                    amount: 100,
+                    eurAmount: 10,
+                    usdAmount: 12,
+                    gbpAmount: 9,
+                },
+                maxReferee: {
+                    amount: 50,
+                    eurAmount: 5,
+                    usdAmount: 6,
+                    gbpAmount: 4.5,
+                },
+                rewards: [
+                    {
+                        token: "0x1234567890123456789012345678901234567890" as Address,
+                        campaign:
+                            "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+                        interactionTypeKey: "press.readArticle",
+                        referrer: {
+                            amount: 10,
+                            eurAmount: 1,
+                            usdAmount: 1.2,
+                            gbpAmount: 0.9,
+                        },
+                        referee: {
+                            amount: 5,
+                            eurAmount: 0.5,
+                            usdAmount: 0.6,
+                            gbpAmount: 0.45,
+                        },
+                    },
+                ],
+            };
+
+            const mockClient = {
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const result = await getProductInformation(mockClient);
+
+            expect(result).toEqual(mockResponse);
+            expect(result.rewards).toHaveLength(1);
+            expect(result.maxReferrer).toBeDefined();
+            expect(result.maxReferee).toBeDefined();
+        });
+    });
+
+    describe("error handling", () => {
+        it("should propagate errors from client.request", async () => {
+            const error = new Error("RPC request failed");
+            const mockClient = {
+                request: vi.fn().mockRejectedValue(error),
+            } as unknown as FrakClient;
+
+            await expect(getProductInformation(mockClient)).rejects.toThrow(
+                "RPC request failed"
+            );
+        });
+
+        it("should handle network timeout errors", async () => {
+            const error = new Error("Request timeout");
+            const mockClient = {
+                request: vi.fn().mockRejectedValue(error),
+            } as unknown as FrakClient;
+
+            await expect(getProductInformation(mockClient)).rejects.toThrow(
+                "Request timeout"
+            );
+        });
+    });
+});

package/src/actions/getProductInformation.ts

@@ -0,0 +1,14 @@
+import type { FrakClient, GetProductInformationReturnType } from "../types";
+
+/**
+ * Function used to get the current product information
+ * @param client - The current Frak Client
+ * @returns The product information in a promise
+ */
+export async function getProductInformation(
+    client: FrakClient
+): Promise<GetProductInformationReturnType> {
+    return await client.request({
+        method: "frak_getProductInformation",
+    });
+}

package/src/actions/index.ts

@@ -0,0 +1,29 @@
+export { displayEmbeddedWallet } from "./displayEmbeddedWallet";
+export { displayModal } from "./displayModal";
+export { getProductInformation } from "./getProductInformation";
+export { openSso } from "./openSso";
+export { prepareSso } from "./prepareSso";
+export {
+    type ProcessReferralOptions,
+    processReferral,
+} from "./referral/processReferral";
+// Referral interaction
+export { referralInteraction } from "./referral/referralInteraction";
+export { sendInteraction } from "./sendInteraction";
+// Helper to track the purchase status
+export { trackPurchaseStatus } from "./trackPurchaseStatus";
+export { watchWalletStatus } from "./watchWalletStatus";
+export {
+    type ModalBuilder,
+    type ModalStepBuilder,
+    modalBuilder,
+} from "./wrapper/modalBuilder";
+export {
+    type SendTransactionParams,
+    sendTransaction,
+} from "./wrapper/sendTransaction";
+// Modal wrappers
+export {
+    type SiweAuthenticateModalParams,
+    siweAuthenticate,
+} from "./wrapper/siweAuthenticate";