@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.2c88e0f4

package/src/clients/createIFrameFrakClient.ts

@@ -0,0 +1,290 @@
+import {
+    createRpcClient,
+    FrakRpcError,
+    type RpcClient,
+    RpcErrorCodes,
+} from "@frak-labs/frame-connector";
+import { OpenPanel } from "@openpanel/web";
+import type { FrakLifecycleEvent } from "../types";
+import type { FrakClient } from "../types/client";
+import type { FrakWalletSdkConfig } from "../types/config";
+import type { IFrameRpcSchema } from "../types/rpc";
+import { BACKUP_KEY } from "../utils/constants";
+import { setupSsoUrlListener } from "../utils/ssoUrlListener";
+
+import { DebugInfoGatherer } from "./DebugInfo";
+import {
+    createIFrameLifecycleManager,
+    type IframeLifecycleManager,
+} from "./transports/iframeLifecycleManager";
+
+type SdkRpcClient = RpcClient<IFrameRpcSchema, FrakLifecycleEvent>;
+
+/**
+ * Create a new iframe Frak client
+ * @param args
+ * @param args.config - The configuration to use for the Frak Wallet SDK.
+ *   When `config.domain` is set, it is forwarded to the iframe handshake so the listener resolves the correct merchant in tunneled/proxied environments (e.g. Shopify dev with Cloudflare tunnel).
+ * @param args.iframe - The iframe to use for the communication
+ * @returns The created Frak Client
+ *
+ * @example
+ * const frakConfig: FrakWalletSdkConfig = {
+ *     metadata: {
+ *         name: "My app title",
+ *     },
+ * }
+ * const iframe = await createIframe({ config: frakConfig });
+ * const client = createIFrameFrakClient({ config: frakConfig, iframe });
+ */
+export function createIFrameFrakClient({
+    config,
+    iframe,
+}: {
+    config: FrakWalletSdkConfig;
+    iframe: HTMLIFrameElement;
+}): FrakClient {
+    const frakWalletUrl = config?.walletUrl ?? "https://wallet.frak.id";
+
+    // Create lifecycle manager
+    const lifecycleManager = createIFrameLifecycleManager({
+        iframe,
+        targetOrigin: frakWalletUrl,
+        configDomain: config.domain,
+    });
+
+    // Create our debug info gatherer
+    const debugInfo = new DebugInfoGatherer(config, iframe);
+
+    // Validate iframe
+    if (!iframe.contentWindow) {
+        throw new FrakRpcError(
+            RpcErrorCodes.configError,
+            "The iframe does not have a content window"
+        );
+    }
+
+    // Create RPC client with middleware and lifecycle handlers
+    const rpcClient = createRpcClient<IFrameRpcSchema, FrakLifecycleEvent>({
+        emittingTransport: iframe.contentWindow,
+        listeningTransport: window,
+        targetOrigin: frakWalletUrl,
+        middleware: [
+            // Ensure we are connected before sending request
+            {
+                async onRequest(_message, ctx) {
+                    // Ensure the iframe is connected
+                    const isConnected = await lifecycleManager.isConnected;
+                    if (!isConnected) {
+                        throw new FrakRpcError(
+                            RpcErrorCodes.clientNotConnected,
+                            "The iframe provider isn't connected yet"
+                        );
+                    }
+                    return ctx;
+                },
+            },
+            // Save debug info
+            {
+                onRequest(message, ctx) {
+                    debugInfo.setLastRequest(message);
+                    return ctx;
+                },
+                onResponse(message, response) {
+                    debugInfo.setLastResponse(message, response);
+                    return response;
+                },
+            },
+        ],
+        // Add lifecycle handlers to process iframe lifecycle events
+        lifecycleHandlers: {
+            iframeLifecycle: async (event, _context) => {
+                // Delegate to lifecycle manager  (cast for type compatibility)
+                await lifecycleManager.handleEvent(event);
+            },
+        },
+    });
+
+    // Setup heartbeat
+    const stopHeartbeat = setupHeartbeat(rpcClient, lifecycleManager);
+
+    // Build our destroy function
+    const destroy = async () => {
+        // Stop heartbeat
+        stopHeartbeat();
+        // Cleanup the RPC client
+        rpcClient.cleanup();
+        // Remove the iframe
+        iframe.remove();
+    };
+
+    // Init open panel
+    let openPanel: OpenPanel | undefined;
+    if (
+        process.env.OPEN_PANEL_API_URL &&
+        process.env.OPEN_PANEL_SDK_CLIENT_ID
+    ) {
+        console.log("[Frak SDK] Initializing OpenPanel");
+        openPanel = new OpenPanel({
+            apiUrl: process.env.OPEN_PANEL_API_URL,
+            clientId: process.env.OPEN_PANEL_SDK_CLIENT_ID,
+            trackScreenViews: true,
+            trackOutgoingLinks: true,
+            trackAttributes: false,
+            // We use a filter to ensure we got the open panel instance initialized
+            //  A bit hacky, but this way we are sure that we got everything needed for the first event ever sent
+            filter: ({ type, payload }) => {
+                if (type !== "track") return true;
+                if (!payload?.properties) return true;
+
+                // Check if we we got the properties once initialized
+                if (!("sdkVersion" in payload.properties)) {
+                    payload.properties = {
+                        ...payload.properties,
+                        sdkVersion: process.env.SDK_VERSION,
+                    };
+                }
+
+                return true;
+            },
+        });
+        openPanel.setGlobalProperties({
+            sdkVersion: process.env.SDK_VERSION,
+        });
+        openPanel.init();
+    }
+
+    // Perform the post connection setup
+    const waitForSetup = postConnectionSetup({
+        config,
+        rpcClient,
+        lifecycleManager,
+    }).then(() => debugInfo.updateSetupStatus(true));
+
+    return {
+        config,
+        debugInfo,
+        waitForConnection: lifecycleManager.isConnected,
+        waitForSetup,
+        request: rpcClient.request,
+        listenerRequest: rpcClient.listen,
+        destroy,
+        openPanel,
+    };
+}
+
+/**
+ * Setup the heartbeat
+ * @param rpcClient - RPC client to send lifecycle events
+ * @param lifecycleManager - Lifecycle manager to track connection
+ */
+function setupHeartbeat(
+    rpcClient: SdkRpcClient,
+    lifecycleManager: IframeLifecycleManager
+) {
+    const HEARTBEAT_INTERVAL = 1_000; // Send heartbeat every 100ms until we are connected
+    const HEARTBEAT_TIMEOUT = 30_000; // 30 seconds timeout
+    let heartbeatInterval: NodeJS.Timeout;
+    let timeoutId: NodeJS.Timeout;
+
+    const sendHeartbeat = () =>
+        rpcClient.sendLifecycle({
+            clientLifecycle: "heartbeat",
+        });
+
+    // Start sending heartbeats
+    async function startHeartbeat() {
+        sendHeartbeat(); // Send initial heartbeat
+        heartbeatInterval = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL);
+
+        // Set up timeout
+        timeoutId = setTimeout(() => {
+            stopHeartbeat();
+            console.log("Heartbeat timeout: connection failed");
+        }, HEARTBEAT_TIMEOUT);
+
+        // Once connected, stop it
+        await lifecycleManager.isConnected;
+
+        // We are now connected, stop the heartbeat
+        stopHeartbeat();
+    }
+
+    // Stop sending heartbeats
+    function stopHeartbeat() {
+        if (heartbeatInterval) {
+            clearInterval(heartbeatInterval);
+        }
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+
+    startHeartbeat();
+
+    // Return cleanup function
+    return stopHeartbeat;
+}
+
+/**
+ * Perform the post connection setup
+ * @param config - SDK configuration
+ * @param rpcClient - RPC client to send lifecycle events
+ * @param lifecycleManager - Lifecycle manager to track connection
+ */
+async function postConnectionSetup({
+    config,
+    rpcClient,
+    lifecycleManager,
+}: {
+    config: FrakWalletSdkConfig;
+    rpcClient: SdkRpcClient;
+    lifecycleManager: IframeLifecycleManager;
+}): Promise<void> {
+    // Wait for the handler to be connected
+    await lifecycleManager.isConnected;
+
+    // Setup SSO URL listener to detect and forward SSO redirects
+    // This checks for ?sso= parameter and forwards compressed data to iframe
+    setupSsoUrlListener(rpcClient, lifecycleManager.isConnected);
+
+    // Push raw CSS if needed
+    async function pushCss() {
+        const cssLink = config.customizations?.css;
+        if (!cssLink) return;
+
+        const message = {
+            clientLifecycle: "modal-css" as const,
+            data: { cssLink },
+        };
+        rpcClient.sendLifecycle(message);
+    }
+
+    // Push i18n if needed
+    async function pushI18n() {
+        const i18n = config.customizations?.i18n;
+        if (!i18n) return;
+
+        const message = {
+            clientLifecycle: "modal-i18n" as const,
+            data: { i18n },
+        };
+        rpcClient.sendLifecycle(message);
+    }
+
+    // Push local backup if needed
+    async function pushBackup() {
+        if (typeof window === "undefined") return;
+
+        const backup = window.localStorage.getItem(BACKUP_KEY);
+        if (!backup) return;
+
+        const message = {
+            clientLifecycle: "restore-backup" as const,
+            data: { backup },
+        };
+        rpcClient.sendLifecycle(message);
+    }
+
+    await Promise.allSettled([pushCss(), pushI18n(), pushBackup()]);
+}

package/src/clients/index.ts

@@ -0,0 +1,3 @@
+export { createIFrameFrakClient } from "./createIFrameFrakClient";
+export { DebugInfoGatherer } from "./DebugInfo";
+export { setupClient } from "./setupClient";

package/src/clients/setupClient.test.ts

@@ -0,0 +1,343 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+// Mock dependencies
+vi.mock("../utils", () => ({
+    createIframe: vi.fn(),
+    getSupportedCurrency: vi.fn((currency) => currency || "eur"),
+}));
+
+vi.mock("./createIFrameFrakClient", () => ({
+    createIFrameFrakClient: vi.fn(),
+}));
+
+describe("setupClient", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    describe("client setup", () => {
+        test("should create iframe with prepared config", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: Promise.resolve(true),
+            };
+
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            await setupClient({ config });
+
+            expect(createIframe).toHaveBeenCalledWith({
+                config: expect.objectContaining({
+                    metadata: expect.objectContaining({
+                        name: "Test App",
+                        currency: "eur",
+                    }),
+                }),
+            });
+        });
+
+        test("should preserve custom currency in config", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+            const { getSupportedCurrency } = await import("../utils");
+
+            const mockIframe = document.createElement("iframe");
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: Promise.resolve(true),
+            };
+
+            vi.mocked(getSupportedCurrency).mockReturnValue("usd");
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                    currency: "usd" as const,
+                },
+            };
+
+            await setupClient({ config });
+
+            expect(getSupportedCurrency).toHaveBeenCalledWith("usd");
+            expect(createIframe).toHaveBeenCalledWith({
+                config: expect.objectContaining({
+                    metadata: expect.objectContaining({
+                        currency: "usd",
+                    }),
+                }),
+            });
+        });
+
+        test("should return undefined when iframe creation fails", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+
+            vi.mocked(createIframe).mockResolvedValue(undefined);
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            const result = await setupClient({ config });
+
+            expect(result).toBeUndefined();
+        });
+
+        test("should create FrakClient with iframe", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: Promise.resolve(true),
+            };
+
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            await setupClient({ config });
+
+            expect(createIFrameFrakClient).toHaveBeenCalledWith({
+                config: expect.objectContaining({
+                    metadata: expect.objectContaining({
+                        name: "Test App",
+                    }),
+                }),
+                iframe: mockIframe,
+            });
+        });
+
+        test("should wait for client setup", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const setupPromise = Promise.resolve();
+            const mockClient = {
+                waitForSetup: setupPromise,
+                waitForConnection: Promise.resolve(true),
+            };
+
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            await setupClient({ config });
+
+            // Verify setup was awaited
+            await expect(setupPromise).resolves.toBeUndefined();
+        });
+
+        test("should wait for connection", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const connectionPromise = Promise.resolve(true);
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: connectionPromise,
+            };
+
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            await setupClient({ config });
+
+            // Verify connection was awaited
+            await expect(connectionPromise).resolves.toBe(true);
+        });
+
+        test("should return undefined when connection fails", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: Promise.resolve(false),
+            };
+
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            const result = await setupClient({ config });
+
+            expect(result).toBeUndefined();
+        });
+
+        test("should return client when setup successful", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: Promise.resolve(true),
+                request: vi.fn(),
+            };
+
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            const result = await setupClient({ config });
+
+            expect(result).toBe(mockClient);
+        });
+    });
+
+    describe("config preparation", () => {
+        test("should use default currency when none provided", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+            const { getSupportedCurrency } = await import("../utils");
+
+            const mockIframe = document.createElement("iframe");
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: Promise.resolve(true),
+            };
+
+            vi.mocked(getSupportedCurrency).mockReturnValue("eur");
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                },
+            };
+
+            await setupClient({ config });
+
+            expect(getSupportedCurrency).toHaveBeenCalledWith(undefined);
+        });
+
+        test("should merge metadata with prepared config", async () => {
+            const { setupClient } = await import("./setupClient");
+            const { createIframe } = await import("../utils");
+            const { createIFrameFrakClient } = await import(
+                "./createIFrameFrakClient"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const mockClient = {
+                waitForSetup: Promise.resolve(),
+                waitForConnection: Promise.resolve(true),
+            };
+
+            vi.mocked(createIframe).mockResolvedValue(mockIframe);
+            vi.mocked(createIFrameFrakClient).mockReturnValue(
+                mockClient as any
+            );
+
+            const config = {
+                metadata: {
+                    name: "Test App",
+                    css: {
+                        primaryColor: "#ff0000",
+                    },
+                },
+            };
+
+            await setupClient({ config });
+
+            expect(createIframe).toHaveBeenCalledWith({
+                config: expect.objectContaining({
+                    metadata: expect.objectContaining({
+                        name: "Test App",
+                        css: {
+                            primaryColor: "#ff0000",
+                        },
+                        currency: "eur",
+                    }),
+                }),
+            });
+        });
+    });
+});

package/src/clients/setupClient.ts

@@ -0,0 +1,73 @@
+import { createIFrameFrakClient } from "../clients";
+import type { FrakClient, FrakWalletSdkConfig } from "../types";
+import { createIframe, getSupportedCurrency } from "../utils";
+
+/**
+ * Directly setup the Frak client with an iframe
+ * Return when the FrakClient is ready (setup and communication estbalished with the wallet)
+ *
+ * @param config - The configuration to use for the Frak Wallet SDK
+ * @returns a Promise with the Frak Client
+ *
+ * @example
+ * const frakConfig: FrakWalletSdkConfig = {
+ *     metadata: {
+ *         name: "My app title",
+ *     },
+ * }
+ * const client = await setupClient({ config: frakConfig });
+ */
+export async function setupClient({
+    config,
+}: {
+    config: FrakWalletSdkConfig;
+}): Promise<FrakClient | undefined> {
+    // Prepare the config
+    const preparedConfig = prepareConfig(config);
+
+    // Create our iframe
+    const iframe = await createIframe({
+        config: preparedConfig,
+    });
+
+    if (!iframe) {
+        console.error("Failed to create iframe");
+        return;
+    }
+
+    // Create our client
+    const client = createIFrameFrakClient({
+        config: preparedConfig,
+        iframe,
+    });
+
+    // Wait for the client to be all setup
+    await client.waitForSetup;
+
+    // Wait for the connection to be established
+    const waitForConnection = await client.waitForConnection;
+    if (!waitForConnection) {
+        console.error("Failed to connect to client");
+        return;
+    }
+
+    return client;
+}
+
+/**
+ * Prepare the config for the Frak Client
+ * @param config - The configuration to use for the Frak Wallet SDK
+ * @returns The prepared configuration with the supported currency
+ */
+function prepareConfig(config: FrakWalletSdkConfig): FrakWalletSdkConfig {
+    // Get the supported currency (e.g. "eur")
+    const supportedCurrency = getSupportedCurrency(config.metadata?.currency);
+
+    return {
+        ...config,
+        metadata: {
+            ...config.metadata,
+            currency: supportedCurrency,
+        },
+    };
+}