@frak-labs/core-sdk 0.1.0-beta.afa252b0 → 0.1.0-beta.c7e026e5

package/src/actions/wrapper/modalBuilder.test.ts

@@ -0,0 +1,253 @@
+import { vi } from "vitest";
+
+vi.mock("../displayModal", () => ({
+    displayModal: vi.fn(),
+}));
+
+import type { Address } from "viem";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import type { FrakClient } from "../../types";
+import { modalBuilder } from "./modalBuilder";
+
+describe("modalBuilder", () => {
+    const mockClient = {
+        config: {
+            metadata: {
+                name: "Test App",
+            },
+        },
+        request: vi.fn(),
+    } as unknown as FrakClient;
+
+    describe("initialization", () => {
+        it("should create builder with base params", () => {
+            const builder = modalBuilder(mockClient, {});
+
+            expect(builder.params).toBeDefined();
+            expect(builder.params.steps.login).toEqual({});
+            expect(builder.params.steps.openSession).toEqual({});
+        });
+
+        it("should create builder with custom login params", () => {
+            const builder = modalBuilder(mockClient, {
+                login: { allowSso: true },
+            });
+
+            expect(builder.params.steps.login).toEqual({ allowSso: true });
+        });
+
+        it("should create builder with custom openSession params", () => {
+            const builder = modalBuilder(mockClient, {
+                openSession: {},
+            });
+
+            expect(builder.params.steps.openSession).toEqual({});
+        });
+
+        it("should create builder with metadata", () => {
+            const builder = modalBuilder(mockClient, {
+                metadata: {
+                    header: { title: "Test Title" },
+                },
+            });
+
+            expect(builder.params.metadata).toEqual({
+                header: { title: "Test Title" },
+            });
+        });
+    });
+
+    describe("sendTx step", () => {
+        it("should add sendTransaction step", () => {
+            const builder = modalBuilder(mockClient, {});
+            const withTx = builder.sendTx({
+                tx: {
+                    to: "0x1234567890123456789012345678901234567890" as Address,
+                    data: "0xdata" as `0x${string}`,
+                },
+            });
+
+            expect(withTx.params.steps.sendTransaction).toEqual({
+                tx: {
+                    to: "0x1234567890123456789012345678901234567890",
+                    data: "0xdata",
+                },
+            });
+        });
+
+        it("should preserve previous steps when adding sendTx", () => {
+            const builder = modalBuilder(mockClient, {
+                login: { allowSso: true },
+            });
+            const withTx = builder.sendTx({
+                tx: {
+                    to: "0x1234567890123456789012345678901234567890" as Address,
+                },
+            });
+
+            expect(withTx.params.steps.login).toEqual({ allowSso: true });
+            expect(withTx.params.steps.sendTransaction).toBeDefined();
+        });
+    });
+
+    describe("reward step", () => {
+        it("should add reward final step", () => {
+            const builder = modalBuilder(mockClient, {});
+            const withReward = builder.reward();
+
+            expect(withReward.params.steps.final).toEqual({
+                action: { key: "reward" },
+            });
+        });
+
+        it("should add reward step with options", () => {
+            const builder = modalBuilder(mockClient, {});
+            const withReward = builder.reward({
+                autoSkip: true,
+            });
+
+            expect(withReward.params.steps.final).toEqual({
+                autoSkip: true,
+                action: { key: "reward" },
+            });
+        });
+    });
+
+    describe("sharing step", () => {
+        it("should add sharing final step", () => {
+            const builder = modalBuilder(mockClient, {});
+            const withSharing = builder.sharing({
+                popupTitle: "Share!",
+                text: "Check this out",
+                link: "https://example.com",
+            });
+
+            expect(withSharing.params.steps.final).toEqual({
+                action: {
+                    key: "sharing",
+                    options: {
+                        popupTitle: "Share!",
+                        text: "Check this out",
+                        link: "https://example.com",
+                    },
+                },
+            });
+        });
+
+        it("should add sharing step with additional options", () => {
+            const builder = modalBuilder(mockClient, {});
+            const withSharing = builder.sharing(
+                { text: "Share text", link: "https://example.com" },
+                { autoSkip: false }
+            );
+
+            expect(withSharing.params.steps.final).toEqual({
+                autoSkip: false,
+                action: {
+                    key: "sharing",
+                    options: {
+                        text: "Share text",
+                        link: "https://example.com",
+                    },
+                },
+            });
+        });
+    });
+
+    describe("chaining", () => {
+        it("should chain sendTx and reward", () => {
+            const builder = modalBuilder(mockClient, {});
+            const chained = builder
+                .sendTx({
+                    tx: {
+                        to: "0x1234567890123456789012345678901234567890" as Address,
+                    },
+                })
+                .reward();
+
+            expect(chained.params.steps.sendTransaction).toBeDefined();
+            expect(chained.params.steps.final).toEqual({
+                action: { key: "reward" },
+            });
+        });
+
+        it("should chain sendTx and sharing", () => {
+            const builder = modalBuilder(mockClient, {});
+            const chained = builder
+                .sendTx({
+                    tx: {
+                        to: "0x1234567890123456789012345678901234567890" as Address,
+                    },
+                })
+                .sharing({ link: "https://example.com" });
+
+            expect(chained.params.steps.sendTransaction).toBeDefined();
+            expect(chained.params.steps.final?.action).toEqual({
+                key: "sharing",
+                options: { link: "https://example.com" },
+            });
+        });
+    });
+
+    describe("display", () => {
+        it("should call displayModal when display is invoked", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+                openSession: {
+                    startTimestamp: 1234567890,
+                    endTimestamp: 1234567900,
+                },
+            };
+            vi.mocked(displayModal).mockResolvedValue(mockResponse as any);
+
+            const builder = modalBuilder(mockClient, {});
+            await builder.display();
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClient,
+                builder.params
+            );
+        });
+
+        it("should apply metadata override when provided", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({} as any);
+
+            const builder = modalBuilder(mockClient, {
+                metadata: { header: { title: "Original" } },
+            });
+            await builder.display(() => ({
+                header: { title: "Overridden" },
+            }));
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClient,
+                expect.objectContaining({
+                    metadata: { header: { title: "Overridden" } },
+                })
+            );
+        });
+
+        it("should return displayModal result", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+                openSession: {},
+            };
+            vi.mocked(displayModal).mockResolvedValue(mockResponse as any);
+
+            const builder = modalBuilder(mockClient, {});
+            const result = await builder.display();
+
+            expect(result).toEqual(mockResponse);
+        });
+    });
+});

package/src/actions/wrapper/modalBuilder.ts

@@ -0,0 +1,212 @@
+import type {
+    DisplayModalParamsType,
+    FinalActionType,
+    FinalModalStepType,
+    FrakClient,
+    LoginModalStepType,
+    ModalRpcMetadata,
+    ModalRpcStepsResultType,
+    ModalStepTypes,
+    OpenInteractionSessionModalStepType,
+    SendTransactionModalStepType,
+} from "../../types";
+import { displayModal } from "../displayModal";
+
+/**
+ * Represent the type of the modal step builder
+ */
+export type ModalStepBuilder<
+    Steps extends ModalStepTypes[] = ModalStepTypes[],
+> = {
+    /**
+     * The current modal params
+     */
+    params: DisplayModalParamsType<Steps>;
+    /**
+     * Add a send transaction step to the modal
+     */
+    sendTx: (
+        options: SendTransactionModalStepType["params"]
+    ) => ModalStepBuilder<[...Steps, SendTransactionModalStepType]>;
+    /**
+     * Add a final step of type reward to the modal
+     */
+    reward: (
+        options?: Omit<FinalModalStepType["params"], "action">
+    ) => ModalStepBuilder<[...Steps, FinalModalStepType]>;
+    /**
+     * Add a final step of type sharing to the modal
+     */
+    sharing: (
+        sharingOptions?: Extract<
+            FinalActionType,
+            { key: "sharing" }
+        >["options"],
+        options?: Omit<FinalModalStepType["params"], "action">
+    ) => ModalStepBuilder<[...Steps, FinalModalStepType]>;
+    /**
+     * Display the modal
+     * @param metadataOverride - Function returning optional metadata to override the current modal metadata
+     */
+    display: (
+        metadataOverride?: (
+            current?: ModalRpcMetadata
+        ) => ModalRpcMetadata | undefined
+    ) => Promise<ModalRpcStepsResultType<Steps>>;
+};
+
+/**
+ * Represent the output type of the modal builder
+ */
+export type ModalBuilder = ModalStepBuilder<
+    [LoginModalStepType, OpenInteractionSessionModalStepType]
+>;
+
+/**
+ * Helper to craft Frak modal, and share a base initial config
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.metadata - Common modal metadata (customisation, language etc)
+ * @param args.login - Login step parameters
+ * @param args.openSession - Open session step parameters
+ *
+ * @description This function will create a modal builder with the provided metadata, login and open session parameters.
+ *
+ * @example
+ * Here is an example of how to use the `modalBuilder` to create and display a sharing modal:
+ *
+ * ```js
+ * // Create the modal builder
+ * const modalBuilder = window.FrakSDK.modalBuilder(frakClient, baseModalConfig);
+ *
+ * // Configure the information to be shared via the sharing link
+ * const sharingConfig = {
+ *   popupTitle: "Share this with your friends",
+ *   text: "Discover our product!",
+ *   link: window.location.href,
+ * };
+ *
+ * // Display the sharing modal
+ * function modalShare() {
+ *   modalBuilder.sharing(sharingConfig).display();
+ * }
+ * ```
+ *
+ * @see {@link ModalStepTypes} for more info about each modal step types and their parameters
+ * @see {@link ModalRpcMetadata} for more info about the metadata that can be passed to the modal
+ * @see {@link ModalRpcStepsResultType} for more info about the result of each modal steps
+ * @see {@link displayModal} for more info about how the modal is displayed
+ */
+export function modalBuilder(
+    client: FrakClient,
+    {
+        metadata,
+        login,
+        openSession,
+    }: {
+        metadata?: ModalRpcMetadata;
+        login?: LoginModalStepType["params"];
+        openSession?: OpenInteractionSessionModalStepType["params"];
+    }
+): ModalBuilder {
+    // Build the initial modal params
+    const baseParams: DisplayModalParamsType<
+        [LoginModalStepType, OpenInteractionSessionModalStepType]
+    > = {
+        steps: {
+            login: login ?? {},
+            openSession: openSession ?? {},
+        },
+        metadata,
+    };
+
+    // Return the step builder
+    return modalStepsBuilder(client, baseParams);
+}
+
+/**
+ * Modal step builder, allowing to add new steps to the modal, and to build and display it
+ */
+function modalStepsBuilder<CurrentSteps extends ModalStepTypes[]>(
+    client: FrakClient,
+    params: DisplayModalParamsType<CurrentSteps>
+): ModalStepBuilder<CurrentSteps> {
+    // Function add the send tx step
+    function sendTx(options: SendTransactionModalStepType["params"]) {
+        return modalStepsBuilder<
+            [...CurrentSteps, SendTransactionModalStepType]
+        >(client, {
+            ...params,
+            steps: {
+                ...params.steps,
+                sendTransaction: options,
+            },
+        } as DisplayModalParamsType<
+            [...CurrentSteps, SendTransactionModalStepType]
+        >);
+    }
+
+    // Function to add a reward step at the end
+    function reward(options?: Omit<FinalModalStepType["params"], "action">) {
+        return modalStepsBuilder<[...CurrentSteps, FinalModalStepType]>(
+            client,
+            {
+                ...params,
+                steps: {
+                    ...params.steps,
+                    final: {
+                        ...options,
+                        action: { key: "reward" },
+                    },
+                },
+            } as DisplayModalParamsType<[...CurrentSteps, FinalModalStepType]>
+        );
+    }
+
+    // Function to add sharing step at the end
+    function sharing(
+        sharingOptions?: Extract<
+            FinalActionType,
+            { key: "sharing" }
+        >["options"],
+        options?: Omit<FinalModalStepType["params"], "action">
+    ) {
+        return modalStepsBuilder<[...CurrentSteps, FinalModalStepType]>(
+            client,
+            {
+                ...params,
+                steps: {
+                    ...params.steps,
+                    final: {
+                        ...options,
+                        action: { key: "sharing", options: sharingOptions },
+                    },
+                },
+            } as DisplayModalParamsType<[...CurrentSteps, FinalModalStepType]>
+        );
+    }
+
+    // Function to display it
+    async function display(
+        metadataOverride?: (
+            current?: ModalRpcMetadata
+        ) => ModalRpcMetadata | undefined
+    ) {
+        // If we have a metadata override, apply it
+        if (metadataOverride) {
+            params.metadata = metadataOverride(params.metadata ?? {});
+        }
+        return await displayModal(client, params);
+    }
+
+    return {
+        // Access current modal params
+        params,
+        // Function to add new steps
+        sendTx,
+        reward,
+        sharing,
+        // Display the modal
+        display,
+    };
+}

package/src/actions/wrapper/sendTransaction.test.ts

@@ -0,0 +1,164 @@
+import { vi } from "vitest";
+
+vi.mock("../displayModal", () => ({
+    displayModal: vi.fn(),
+}));
+
+import type { Address, Hex } from "viem";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import type { FrakClient } from "../../types";
+import { sendTransaction } from "./sendTransaction";
+
+describe("sendTransaction", () => {
+    const mockClient = {
+        config: {
+            metadata: {
+                name: "Test App",
+            },
+        },
+        request: vi.fn(),
+    } as unknown as FrakClient;
+
+    describe("basic usage", () => {
+        it("should call displayModal with correct params for single tx", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            const mockTxHash =
+                "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" as Hex;
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+                sendTransaction: { hash: mockTxHash },
+            } as any);
+
+            const txParams = {
+                to: "0x1234567890123456789012345678901234567890" as Address,
+                data: "0xdeadbeef" as Hex,
+            };
+
+            await sendTransaction(mockClient, { tx: txParams });
+
+            expect(displayModal).toHaveBeenCalledWith(mockClient, {
+                metadata: undefined,
+                steps: {
+                    login: {},
+                    sendTransaction: { tx: txParams },
+                },
+            });
+        });
+
+        it("should return transaction hash", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            const mockTxHash =
+                "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" as Hex;
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+                sendTransaction: { hash: mockTxHash },
+            } as any);
+
+            const result = await sendTransaction(mockClient, {
+                tx: {
+                    to: "0x1234567890123456789012345678901234567890" as Address,
+                },
+            });
+
+            expect(result).toEqual({ hash: mockTxHash });
+        });
+    });
+
+    describe("batched transactions", () => {
+        it("should handle multiple transactions", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            const mockTxHash =
+                "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" as Hex;
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                sendTransaction: { hash: mockTxHash },
+            } as any);
+
+            const txParams = [
+                {
+                    to: "0x1234567890123456789012345678901234567890" as Address,
+                    data: "0xdata1" as Hex,
+                },
+                {
+                    to: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+                    data: "0xdata2" as Hex,
+                },
+            ];
+
+            await sendTransaction(mockClient, { tx: txParams });
+
+            expect(displayModal).toHaveBeenCalledWith(mockClient, {
+                metadata: undefined,
+                steps: {
+                    login: {},
+                    sendTransaction: { tx: txParams },
+                },
+            });
+        });
+    });
+
+    describe("with metadata", () => {
+        it("should pass metadata to displayModal", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                sendTransaction: { hash: "0x123" as Hex },
+            } as any);
+
+            const metadata = {
+                header: {
+                    title: "Send ETH",
+                    icon: "https://example.com/icon.png",
+                },
+                context: "Send 100 wei to recipient",
+            };
+
+            await sendTransaction(mockClient, {
+                tx: {
+                    to: "0x1234567890123456789012345678901234567890" as Address,
+                    value: "0x64" as Hex,
+                },
+                metadata,
+            });
+
+            expect(displayModal).toHaveBeenCalledWith(mockClient, {
+                metadata,
+                steps: {
+                    login: {},
+                    sendTransaction: {
+                        tx: {
+                            to: "0x1234567890123456789012345678901234567890",
+                            value: "0x64",
+                        },
+                    },
+                },
+            });
+        });
+    });
+
+    describe("error handling", () => {
+        it("should propagate errors from displayModal", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockRejectedValue(
+                new Error("Transaction rejected")
+            );
+
+            await expect(
+                sendTransaction(mockClient, {
+                    tx: {
+                        to: "0x1234567890123456789012345678901234567890" as Address,
+                    },
+                })
+            ).rejects.toThrow("Transaction rejected");
+        });
+    });
+});

package/src/actions/wrapper/sendTransaction.ts

@@ -0,0 +1,62 @@
+import type {
+    FrakClient,
+    ModalRpcMetadata,
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+} from "../../types";
+import { displayModal } from "../displayModal";
+
+/**
+ * Parameters to directly show a modal used to send a transaction
+ * @inline
+ */
+export type SendTransactionParams = {
+    /**
+     * The transaction to be sent (either a single tx or multiple ones)
+     */
+    tx: SendTransactionModalStepType["params"]["tx"];
+    /**
+     * Custom metadata to be passed to the modal
+     */
+    metadata?: ModalRpcMetadata;
+};
+
+/**
+ * Function used to send a user transaction, simple wrapper around the displayModal function to ease the send transaction process
+ * @param client - The current Frak Client
+ * @param args - The parameters
+ * @returns The hash of the transaction that was sent in a promise
+ *
+ * @description This function will display a modal to the user with the provided transaction and metadata.
+ *
+ * @example
+ * const { hash } = await sendTransaction(frakConfig, {
+ *     tx: {
+ *         to: "0xdeadbeef",
+ *         value: toHex(100n),
+ *     },
+ *     metadata: {
+ *         header: {
+ *             title: "Sending eth",
+ *         },
+ *         context: "Send 100wei to 0xdeadbeef",
+ *     },
+ * });
+ * console.log("Transaction hash:", hash);
+ */
+export async function sendTransaction(
+    client: FrakClient,
+    { tx, metadata }: SendTransactionParams
+): Promise<SendTransactionReturnType> {
+    // Trigger a modal with login options
+    const result = await displayModal(client, {
+        metadata,
+        steps: {
+            login: {},
+            sendTransaction: { tx },
+        },
+    });
+
+    // Return the tx result only
+    return result.sendTransaction;
+}