@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.1e44255d

package/src/actions/displayModal.ts

@@ -0,0 +1,120 @@
+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` step will be automatically skipped if the user is already logged in. It's safe to include this step in all cases to ensure proper user state.
+ * - Steps are automatically reordered in the following sequence:
+ *     1. `login` (if needed)
+ *     2. All other steps in the order specified
+ *     3. `success` (if included, always last)
+ *
+ * @example
+ * Simple sharing modal with steps:
+ *  1. Login (Skipped if already logged in)
+ *  2. 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 },
+ *         // 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);
+ * ```
+ *
+ * @example
+ * A full modal example, with a few customization options, with the steps:
+ *  1. Login (Skipped if already logged in)
+ *  2. Authenticate via SIWE
+ *  3. Send a transaction
+ *  4. 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",
+ *             },
+ *         },
+ *         // 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/ensureIdentity.ts

@@ -0,0 +1,68 @@
+import { getBackendUrl } from "../utils/backendUrl";
+import { getClientId } from "../utils/clientId";
+import { fetchMerchantId } from "../utils/merchantId";
+
+const ENSURE_STORAGE_PREFIX = "frak-identity-ensured-";
+
+/**
+ * Ensure the current wallet ↔ clientId link exists on the backend.
+ *
+ * Called automatically by {@link watchWalletStatus} when a connected wallet
+ * status is received. Acts as a failsafe: if the primary merge (SSO, pairing,
+ * login/register) missed or silently failed, this ensures the link is
+ * eventually established.
+ *
+ * The call is:
+ * - **Idempotent** — if already linked, backend returns immediately
+ * - **Deduplicated** — only fires once per browser session per merchant
+ * - **Fire-and-forget** — errors are logged but never thrown
+ *
+ * @param interactionToken - The SDK JWT from wallet status (x-wallet-sdk-auth)
+ *
+ * @example
+ * ```ts
+ * // Usually called automatically via watchWalletStatus side effect.
+ * // Can also be called manually if needed:
+ * await ensureIdentity("eyJhbGciOi...");
+ * ```
+ */
+export async function ensureIdentity(interactionToken: string): Promise<void> {
+    if (typeof window === "undefined") {
+        return;
+    }
+
+    const clientId = getClientId();
+    if (!clientId) {
+        return;
+    }
+
+    const merchantId = await fetchMerchantId();
+    if (!merchantId) {
+        return;
+    }
+
+    const storageKey = `${ENSURE_STORAGE_PREFIX}${merchantId}`;
+    if (window.sessionStorage.getItem(storageKey)) {
+        return;
+    }
+
+    try {
+        const backendUrl = getBackendUrl();
+        const response = await fetch(`${backendUrl}/user/identity/ensure`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-wallet-sdk-auth": interactionToken,
+                "x-frak-client-id": clientId,
+            },
+            body: JSON.stringify({ merchantId }),
+        });
+
+        if (response.ok) {
+            window.sessionStorage.setItem(storageKey, "1");
+        }
+    } catch {
+        // Fire-and-forget — retry on next session
+    }
+}

package/src/actions/getMerchantInformation.test.ts

@@ -0,0 +1,116 @@
+import type { Address, Hex } from "viem";
+import { describe, expect, it, vi } from "../../tests/vitest-fixtures";
+import type { FrakClient, GetMerchantInformationReturnType } from "../types";
+import { getMerchantInformation } from "./getMerchantInformation";
+
+describe("getMerchantInformation", () => {
+    describe("success cases", () => {
+        it("should call client.request with correct method", async () => {
+            const mockResponse: GetMerchantInformationReturnType = {
+                id: "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex,
+                onChainMetadata: {
+                    name: "Test Merchant",
+                    domain: "example.com",
+                },
+                rewards: [],
+            };
+
+            const mockClient = {
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            await getMerchantInformation(mockClient);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_getMerchantInformation",
+            });
+        });
+
+        it("should return merchant information", async () => {
+            const mockResponse: GetMerchantInformationReturnType = {
+                id: "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex,
+                onChainMetadata: {
+                    name: "Test Merchant",
+                    domain: "example.com",
+                },
+                rewards: [],
+            };
+
+            const mockClient = {
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const result = await getMerchantInformation(mockClient);
+
+            expect(result).toEqual(mockResponse);
+        });
+
+        it("should return merchant information with rewards", async () => {
+            const mockResponse: GetMerchantInformationReturnType = {
+                id: "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex,
+                onChainMetadata: {
+                    name: "Test Merchant",
+                    domain: "example.com",
+                },
+                rewards: [
+                    {
+                        token: "0x1234567890123456789012345678901234567890" as Address,
+                        campaignId: "campaign-1",
+                        interactionTypeKey: "referral",
+                        referrer: {
+                            payoutType: "fixed",
+                            amount: {
+                                amount: 10,
+                                eurAmount: 1,
+                                usdAmount: 1.2,
+                                gbpAmount: 0.9,
+                            },
+                        },
+                        referee: {
+                            payoutType: "fixed",
+                            amount: {
+                                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 getMerchantInformation(mockClient);
+
+            expect(result).toEqual(mockResponse);
+            expect(result.rewards).toHaveLength(1);
+        });
+    });
+
+    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(getMerchantInformation(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(getMerchantInformation(mockClient)).rejects.toThrow(
+                "Request timeout"
+            );
+        });
+    });
+});

package/src/actions/getMerchantInformation.ts

@@ -0,0 +1,16 @@
+import type { FrakClient, GetMerchantInformationReturnType } from "../types";
+
+/**
+ * Fetch the current merchant information (name, rewards, tiers) from the wallet iframe
+ * @param client - The current Frak Client
+ * @returns The merchant information including available reward tiers
+ *
+ * @see {@link @frak-labs/core-sdk!index.GetMerchantInformationReturnType | `GetMerchantInformationReturnType`} for the return type shape
+ */
+export async function getMerchantInformation(
+    client: FrakClient
+): Promise<GetMerchantInformationReturnType> {
+    return await client.request({
+        method: "frak_getMerchantInformation",
+    });
+}

package/src/actions/index.ts

@@ -0,0 +1,30 @@
+export { displayEmbeddedWallet } from "./displayEmbeddedWallet";
+export { displayModal } from "./displayModal";
+export { ensureIdentity } from "./ensureIdentity";
+export { getMerchantInformation } from "./getMerchantInformation";
+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";
+// Modal wrappers
+export {
+    type ModalBuilder,
+    type ModalStepBuilder,
+    modalBuilder,
+} from "./wrapper/modalBuilder";
+export {
+    type SendTransactionParams,
+    sendTransaction,
+} from "./wrapper/sendTransaction";
+export {
+    type SiweAuthenticateModalParams,
+    siweAuthenticate,
+} from "./wrapper/siweAuthenticate";

package/src/actions/openSso.ts

@@ -0,0 +1,118 @@
+import type {
+    FrakClient,
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+} from "../types";
+import { getClientId } from "../utils/clientId";
+import { computeLegacyProductId } from "../utils/computeLegacyProductId";
+import { generateSsoUrl } from "../utils/sso";
+
+// SSO popup configuration
+export const ssoPopupFeatures =
+    "menubar=no,status=no,scrollbars=no,fullscreen=no,width=500, height=800";
+export const ssoPopupName = "frak-sso";
+
+/**
+ * Function used to open the SSO
+ * @param client - The current Frak Client
+ * @param args - The SSO parameters
+ *
+ * @description Two SSO flow modes:
+ *
+ * **Redirect Mode** (openInSameWindow: true):
+ * - Wallet generates URL and triggers redirect
+ * - Used when redirectUrl is provided
+ *
+ * **Popup Mode** (openInSameWindow: false/omitted):
+ * - SDK generates URL client-side (or uses provided ssoPopupUrl)
+ * - Opens popup synchronously (prevents popup blockers)
+ * - Waits for SSO completion via postMessage
+ *
+ * @example
+ * First we build the sso metadata
+ * ```ts
+ * // Build the metadata
+ * const metadata: SsoMetadata = {
+ *     logoUrl: "https://my-app.com/logo.png",
+ *     homepageLink: "https://my-app.com",
+ * };
+ * ```
+ *
+ * Then, either use it with direct exit (and so user is directly redirected to your website), or a custom redirect URL
+ * :::code-group
+ * ```ts [Popup (default)]
+ * // Opens in popup, SDK generates URL automatically
+ * await openSso(frakConfig, {
+ *     directExit: true,
+ *     metadata,
+ * });
+ * ```
+ * ```ts [Redirect]
+ * // Opens in same window with redirect
+ * await openSso(frakConfig, {
+ *     redirectUrl: "https://my-app.com/frak-sso",
+ *     metadata,
+ *     openInSameWindow: true,
+ * });
+ * ```
+ * ```ts [Custom popup URL]
+ * // Advanced: provide custom SSO URL
+ * const { ssoUrl } = await prepareSso(frakConfig, { metadata });
+ * await openSso(frakConfig, {
+ *     metadata,
+ *     ssoPopupUrl: `${ssoUrl}&custom=param`,
+ * });
+ * ```
+ * :::
+ */
+export async function openSso(
+    client: FrakClient,
+    args: OpenSsoParamsType
+): Promise<OpenSsoReturnType> {
+    const { metadata, customizations, walletUrl } = client.config;
+
+    // Check if redirect mode (default to true if redirectUrl present)
+    const isRedirectMode = args.openInSameWindow ?? !!args.redirectUrl;
+
+    if (isRedirectMode) {
+        // Redirect flow: Wallet generates URL and triggers redirect via lifecycle event
+        // This must happen on wallet side because only the iframe can trigger the redirect
+        return await client.request({
+            method: "frak_openSso",
+            params: [args, metadata.name, customizations?.css],
+        });
+    }
+
+    // Popup flow: Generate URL on SDK side and open synchronously
+    // This ensures window.open() is called in same tick as user gesture (no popup blocker)
+
+    // Step 1: Generate or use provided SSO URL
+    const ssoUrl =
+        args.ssoPopupUrl ??
+        generateSsoUrl(
+            walletUrl ?? "https://wallet.frak.id",
+            args,
+            computeLegacyProductId(),
+            metadata.name,
+            getClientId(),
+            customizations?.css
+        );
+
+    // Step 2: Open popup synchronously (critical for popup blocker prevention)
+    const popup = window.open(ssoUrl, ssoPopupName, ssoPopupFeatures);
+    if (!popup) {
+        throw new Error(
+            "Popup was blocked. Please allow popups for this site."
+        );
+    }
+    popup.focus();
+
+    // Step 3: Wait for SSO completion via RPC
+    // The wallet iframe will resolve this when SSO page sends sso_complete message
+    const result = await client.request({
+        method: "frak_openSso",
+        params: [args, metadata.name, customizations?.css],
+    });
+
+    return result ?? {};
+}

package/src/actions/prepareSso.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Tests for prepareSso action
+ * Tests SSO URL generation via RPC
+ */
+
+import { describe, expect, it, vi } from "../../tests/vitest-fixtures";
+import type {
+    FrakClient,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+} from "../types";
+import { prepareSso } from "./prepareSso";
+
+describe("prepareSso", () => {
+    describe("success cases", () => {
+        it("should call client.request with correct method and params", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?params=xyz",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "Test App", undefined],
+            });
+        });
+
+        it("should return SSO URL", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?params=abc123",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: false,
+            };
+
+            const result = await prepareSso(mockClient, params);
+
+            expect(result).toEqual(mockResponse);
+            expect(result.ssoUrl).toBe(
+                "https://wallet.frak.id/sso?params=abc123"
+            );
+        });
+
+        it("should include custom CSS when provided", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?params=custom",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Styled App",
+                    },
+                    customizations: {
+                        css: "body { background: red; }",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "Styled App", "body { background: red; }"],
+            });
+        });
+
+        it("should handle params with redirectUrl", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?redirect=https://example.com",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                redirectUrl: "https://example.com/callback",
+                directExit: false,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "Test App", undefined],
+            });
+        });
+
+        it("should handle params with metadata", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?metadata=xyz",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "App with Metadata",
+                        logoUrl: "https://example.com/logo.png",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    logoUrl: "https://custom.com/logo.png",
+                    homepageLink: "https://custom.com",
+                },
+                directExit: true,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "App with Metadata", undefined],
+            });
+        });
+
+        it("should pass client metadata name to request", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?name=MyApp",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "MyApp",
+                        logoUrl: "https://example.com/logo.png",
+                    },
+                    customizations: {
+                        css: "body { color: blue; }",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {};
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "MyApp", "body { color: blue; }"],
+            });
+        });
+    });
+
+    describe("error handling", () => {
+        it("should propagate errors from client.request", async () => {
+            const error = new Error("SSO preparation failed");
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockRejectedValue(error),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+
+            await expect(prepareSso(mockClient, params)).rejects.toThrow(
+                "SSO preparation 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: PrepareSsoParamsType = {};
+
+            await expect(prepareSso(mockClient, params)).rejects.toThrow(
+                "Network timeout"
+            );
+        });
+    });
+});