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

package/package.json

@@ -11,7 +11,7 @@
       "url": "https://twitter.com/QNivelais"
     }
   ],
-  "version": "0.1.0-beta.b0bd1f8a",
+  "version": "0.1.0-beta.c7e026e5",
   "description": "Core SDK of the Frak wallet, low level library to interact directly with the frak ecosystem.",
   "repository": {
     "url": "https://github.com/frak-id/wallet",

package/src/actions/referral/referralInteraction.test.ts

@@ -0,0 +1,153 @@
+import type { Hex } from "viem";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { referralInteraction } from "./referralInteraction";
+
+vi.mock("../../utils", () => ({
+    FrakContextManager: {
+        parse: vi.fn(),
+    },
+}));
+
+vi.mock("../index", () => ({
+    watchWalletStatus: vi.fn(),
+}));
+
+vi.mock("./processReferral", () => ({
+    processReferral: vi.fn(),
+}));
+
+describe("referralInteraction", () => {
+    const mockClient = {
+        request: vi.fn(),
+    } as any;
+
+    const mockProductId =
+        "0x0000000000000000000000000000000000000000000000000000000000000002" as Hex;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        Object.defineProperty(global, "window", {
+            value: { location: { href: "https://example.com?frak=test" } },
+            writable: true,
+        });
+    });
+
+    test("should parse context from window location", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        await referralInteraction(mockClient);
+
+        expect(FrakContextManager.parse).toHaveBeenCalledWith({
+            url: "https://example.com?frak=test",
+        });
+    });
+
+    test("should get current wallet status", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue({
+            wallet: "0x123" as Hex,
+            interactionSession: true,
+        } as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        await referralInteraction(mockClient);
+
+        expect(watchWalletStatus).toHaveBeenCalledWith(mockClient);
+    });
+
+    test("should call processReferral with all parameters", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        const mockContext = { r: "0xreferrer" as Hex };
+        const mockWalletStatus = { wallet: "0x123" as Hex };
+        const mockModalConfig = { type: "login" };
+        const mockOptions = { alwaysAppendUrl: true };
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue(mockContext as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(mockWalletStatus as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        await referralInteraction(mockClient, {
+            productId: mockProductId,
+            modalConfig: mockModalConfig as any,
+            options: mockOptions,
+        });
+
+        expect(processReferral).toHaveBeenCalledWith(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: mockContext,
+            modalConfig: mockModalConfig,
+            productId: mockProductId,
+            options: mockOptions,
+        });
+    });
+
+    test("should return result from processReferral", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        const result = await referralInteraction(mockClient);
+
+        expect(result).toBe("success");
+    });
+
+    test("should return undefined on error", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockRejectedValue(new Error("Test error"));
+
+        const consoleSpy = vi
+            .spyOn(console, "warn")
+            .mockImplementation(() => {});
+
+        const result = await referralInteraction(mockClient);
+
+        expect(result).toBeUndefined();
+        expect(consoleSpy).toHaveBeenCalled();
+
+        consoleSpy.mockRestore();
+    });
+
+    test("should work with empty options", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockResolvedValue("no-referrer");
+
+        const result = await referralInteraction(mockClient, {});
+
+        expect(result).toBe("no-referrer");
+        expect(processReferral).toHaveBeenCalledWith(
+            mockClient,
+            expect.objectContaining({
+                modalConfig: undefined,
+                productId: undefined,
+                options: undefined,
+            })
+        );
+    });
+});

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/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/siweAuthenticate.test.ts

@@ -0,0 +1,290 @@
+import { beforeEach, vi } from "vitest";
+
+vi.mock("../displayModal", () => ({
+    displayModal: vi.fn(),
+}));
+
+vi.mock("viem/siwe", () => ({
+    generateSiweNonce: vi.fn(() => "mock-nonce-123456"),
+}));
+
+import type { Address, Hex } from "viem";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import type { FrakClient } from "../../types";
+import { siweAuthenticate } from "./siweAuthenticate";
+
+describe("siweAuthenticate", () => {
+    const mockClient = {
+        config: {
+            domain: "example.com",
+            metadata: {
+                name: "Test App",
+            },
+        },
+        request: vi.fn(),
+    } as unknown as FrakClient;
+
+    const mockClientWithoutDomain = {
+        config: {
+            metadata: {
+                name: "Test App",
+            },
+        },
+        request: vi.fn(),
+    } as unknown as FrakClient;
+
+    beforeEach(() => {
+        vi.stubGlobal("window", {
+            location: {
+                host: "window.example.com",
+            },
+        });
+    });
+
+    describe("basic usage", () => {
+        it("should call displayModal with SIWE params", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            const mockResponse = {
+                login: {
+                    wallet: "0x1234567890123456789012345678901234567890" as Address,
+                },
+                siweAuthenticate: {
+                    message: "Sign in to Test App",
+                    signature: "0xsignature" as Hex,
+                },
+            };
+            vi.mocked(displayModal).mockResolvedValue(mockResponse as any);
+
+            await siweAuthenticate(mockClient, {});
+
+            expect(displayModal).toHaveBeenCalledWith(mockClient, {
+                metadata: undefined,
+                steps: {
+                    login: {},
+                    siweAuthenticate: {
+                        siwe: expect.objectContaining({
+                            domain: "example.com",
+                            nonce: "mock-nonce-123456",
+                            uri: "https://example.com",
+                            version: "1",
+                        }),
+                    },
+                },
+            });
+        });
+
+        it("should return SIWE authentication result", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            const mockSiweResult = {
+                message: "I confirm that I want to use my Frak wallet",
+                signature:
+                    "0xsig1234567890123456789012345678901234567890123456789012345678901234" as Hex,
+            };
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: mockSiweResult,
+            } as any);
+
+            const result = await siweAuthenticate(mockClient, {});
+
+            expect(result).toEqual(mockSiweResult);
+        });
+    });
+
+    describe("SIWE parameter handling", () => {
+        it("should use default statement when not provided", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: { message: "", signature: "0x" as Hex },
+            } as any);
+
+            await siweAuthenticate(mockClient, {});
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClient,
+                expect.objectContaining({
+                    steps: expect.objectContaining({
+                        siweAuthenticate: expect.objectContaining({
+                            siwe: expect.objectContaining({
+                                statement:
+                                    "I confirm that I want to use my Frak wallet on: Test App",
+                            }),
+                        }),
+                    }),
+                })
+            );
+        });
+
+        it("should use custom statement when provided", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: { message: "", signature: "0x" as Hex },
+            } as any);
+
+            await siweAuthenticate(mockClient, {
+                siwe: { statement: "Custom sign in message" },
+            });
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClient,
+                expect.objectContaining({
+                    steps: expect.objectContaining({
+                        siweAuthenticate: expect.objectContaining({
+                            siwe: expect.objectContaining({
+                                statement: "Custom sign in message",
+                            }),
+                        }),
+                    }),
+                })
+            );
+        });
+
+        it("should use custom nonce when provided", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: { message: "", signature: "0x" as Hex },
+            } as any);
+
+            await siweAuthenticate(mockClient, {
+                siwe: { nonce: "custom-nonce" },
+            });
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClient,
+                expect.objectContaining({
+                    steps: expect.objectContaining({
+                        siweAuthenticate: expect.objectContaining({
+                            siwe: expect.objectContaining({
+                                nonce: "custom-nonce",
+                            }),
+                        }),
+                    }),
+                })
+            );
+        });
+
+        it("should use window.location.host when domain not in config", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: { message: "", signature: "0x" as Hex },
+            } as any);
+
+            await siweAuthenticate(mockClientWithoutDomain, {});
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClientWithoutDomain,
+                expect.objectContaining({
+                    steps: expect.objectContaining({
+                        siweAuthenticate: expect.objectContaining({
+                            siwe: expect.objectContaining({
+                                domain: "window.example.com",
+                                uri: "https://window.example.com",
+                            }),
+                        }),
+                    }),
+                })
+            );
+        });
+
+        it("should use custom uri when provided", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: { message: "", signature: "0x" as Hex },
+            } as any);
+
+            await siweAuthenticate(mockClient, {
+                siwe: { uri: "https://custom-uri.com" },
+            });
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClient,
+                expect.objectContaining({
+                    steps: expect.objectContaining({
+                        siweAuthenticate: expect.objectContaining({
+                            siwe: expect.objectContaining({
+                                uri: "https://custom-uri.com",
+                            }),
+                        }),
+                    }),
+                })
+            );
+        });
+
+        it("should use custom version when provided", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: { message: "", signature: "0x" as Hex },
+            } as any);
+
+            await siweAuthenticate(mockClient, {
+                siwe: { version: "2" as any },
+            });
+
+            expect(displayModal).toHaveBeenCalledWith(
+                mockClient,
+                expect.objectContaining({
+                    steps: expect.objectContaining({
+                        siweAuthenticate: expect.objectContaining({
+                            siwe: expect.objectContaining({
+                                version: "2",
+                            }),
+                        }),
+                    }),
+                })
+            );
+        });
+    });
+
+    describe("with metadata", () => {
+        it("should pass metadata to displayModal", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockResolvedValue({
+                login: {},
+                siweAuthenticate: { message: "", signature: "0x" as Hex },
+            } as any);
+
+            const metadata = {
+                header: {
+                    title: "Sign In",
+                },
+                context: "Sign in to access your account",
+            };
+
+            await siweAuthenticate(mockClient, { metadata });
+
+            expect(displayModal).toHaveBeenCalledWith(mockClient, {
+                metadata,
+                steps: expect.any(Object),
+            });
+        });
+    });
+
+    describe("error handling", () => {
+        it("should propagate errors from displayModal", async () => {
+            const { displayModal } = await import("../displayModal");
+
+            vi.mocked(displayModal).mockRejectedValue(
+                new Error("SIWE authentication rejected")
+            );
+
+            await expect(siweAuthenticate(mockClient, {})).rejects.toThrow(
+                "SIWE authentication rejected"
+            );
+        });
+    });
+});