@frak-labs/core-sdk 0.2.1 → 1.0.0

package/src/clients/createIFrameFrakClient.ts

@@ -1,5 +1,6 @@
 import {
     createRpcClient,
+    Deferred,
     FrakRpcError,
     type RpcClient,
     RpcErrorCodes,
@@ -8,9 +9,12 @@ import { OpenPanel } from "@openpanel/web";
 import type { FrakLifecycleEvent } from "../types";
 import type { FrakClient } from "../types/client";
 import type { FrakWalletSdkConfig } from "../types/config";
+import type { SdkResolvedConfig } from "../types/resolvedConfig";
 import type { IFrameRpcSchema } from "../types/rpc";
 import { getClientId } from "../utils";
+import { clearAllCache } from "../utils/cache";
 import { BACKUP_KEY } from "../utils/constants";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 import { setupSsoUrlListener } from "../utils/ssoUrlListener";
 import { DebugInfoGatherer } from "./DebugInfo";
 import {
@@ -19,12 +23,13 @@ import {
 } from "./transports/iframeLifecycleManager";
 
 type SdkRpcClient = RpcClient<IFrameRpcSchema, FrakLifecycleEvent>;
+type MerchantConfigResult = Awaited<ReturnType<typeof sdkConfigStore.resolve>>;
 
 /**
  * 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).
+ *   When `config.domain` is set, it is used to resolve the correct merchant config 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
  *
@@ -46,13 +51,35 @@ export function createIFrameFrakClient({
 }): FrakClient {
     const frakWalletUrl = config?.walletUrl ?? "https://wallet.frak.id";
 
+    const browserLang =
+        typeof navigator !== "undefined"
+            ? navigator.language?.split("-")[0]
+            : undefined;
+    const detectedLang =
+        config.metadata.lang ??
+        (browserLang === "en" || browserLang === "fr"
+            ? browserLang
+            : undefined);
+    const targetDomain =
+        config.domain ??
+        (typeof window !== "undefined" ? window.location.hostname : "");
+    sdkConfigStore.setCacheScope(targetDomain, detectedLang);
+    sdkConfigStore.reset();
+
+    // Skip fetch entirely if cache is fresh, otherwise fetch (SWR)
+    const configPromise = sdkConfigStore.isCacheFresh
+        ? undefined
+        : sdkConfigStore.resolve(config.domain, config.walletUrl, detectedLang);
+
     // Create lifecycle manager
     const lifecycleManager = createIFrameLifecycleManager({
         iframe,
         targetOrigin: frakWalletUrl,
-        configDomain: config.domain,
     });
 
+    // Resolved after first resolved-config is sent to iframe (prevents RPC before context exists)
+    const contextSent = new Deferred<void>();
+
     // Create our debug info gatherer
     const debugInfo = new DebugInfoGatherer(config, iframe);
 
@@ -70,10 +97,9 @@ export function createIFrameFrakClient({
         listeningTransport: window,
         targetOrigin: frakWalletUrl,
         middleware: [
-            // Ensure we are connected before sending request
+            // Ensure we are connected and context is sent before sending request
             {
                 async onRequest(_message, ctx) {
-                    // Ensure the iframe is connected
                     const isConnected = await lifecycleManager.isConnected;
                     if (!isConnected) {
                         throw new FrakRpcError(
@@ -81,6 +107,7 @@ export function createIFrameFrakClient({
                             "The iframe provider isn't connected yet"
                         );
                     }
+                    await contextSent.promise;
                     return ctx;
                 },
             },
@@ -98,9 +125,9 @@ export function createIFrameFrakClient({
         ],
         // Add lifecycle handlers to process iframe lifecycle events
         lifecycleHandlers: {
-            iframeLifecycle: async (event, _context) => {
+            iframeLifecycle: (event, _context) => {
                 // Delegate to lifecycle manager  (cast for type compatibility)
-                await lifecycleManager.handleEvent(event);
+                lifecycleManager.handleEvent(event);
             },
         },
     });
@@ -108,14 +135,13 @@ export function createIFrameFrakClient({
     // 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();
+        clearAllCache();
+        sdkConfigStore.clearCache();
+        sdkConfigStore.reset();
     };
 
     // Init open panel
@@ -161,7 +187,14 @@ export function createIFrameFrakClient({
         config,
         rpcClient,
         lifecycleManager,
-    }).then(() => debugInfo.updateSetupStatus(true));
+        configPromise,
+        contextSent,
+    })
+        .then(() => debugInfo.updateSetupStatus(true))
+        .catch((err) => {
+            contextSent.reject(err);
+            throw err;
+        });
 
     return {
         config,
@@ -238,54 +271,145 @@ async function postConnectionSetup({
     config,
     rpcClient,
     lifecycleManager,
+    configPromise,
+    contextSent,
 }: {
     config: FrakWalletSdkConfig;
     rpcClient: SdkRpcClient;
     lifecycleManager: IframeLifecycleManager;
+    configPromise: Promise<MerchantConfigResult> | undefined;
+    contextSent: Deferred<void>;
 }): 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);
 
+    // Read and consume the pending merge token from URL (SSO identity merge)
+    const url = new URL(window.location.href);
+    const pendingMergeToken = url.searchParams.get("fmt") ?? undefined;
+    if (pendingMergeToken) {
+        url.searchParams.delete("fmt");
+        window.history.replaceState({}, "", url.toString());
+    }
+
+    // Merge a raw backend response with SDK metadata and persist to store
+    const mergeAndSetConfig = (merchantConfig: MerchantConfigResult) => {
+        const merchantId =
+            merchantConfig?.merchantId ?? config.metadata.merchantId ?? "";
+        const domain = merchantConfig?.domain ?? "";
+        const allowedDomains = merchantConfig?.allowedDomains ?? [];
+        const raw = merchantConfig?.sdkConfig;
+
+        sdkConfigStore.setConfig(
+            raw
+                ? {
+                      isResolved: true,
+                      merchantId,
+                      domain,
+                      allowedDomains,
+                      hasRawSdkConfig: true,
+                      name: raw.name ?? config.metadata.name,
+                      logoUrl: raw.logoUrl ?? config.metadata.logoUrl,
+                      homepageLink:
+                          raw.homepageLink ?? config.metadata.homepageLink,
+                      lang: raw.lang ?? config.metadata.lang,
+                      currency: raw.currency ?? config.metadata.currency,
+                      hidden: raw.hidden,
+                      css: raw.css,
+                      translations: raw.translations,
+                      placements: raw.placements,
+                      components: raw.components,
+                  }
+                : {
+                      isResolved: true,
+                      merchantId,
+                      domain,
+                      allowedDomains,
+                      name: config.metadata.name,
+                      logoUrl: config.metadata.logoUrl,
+                      homepageLink: config.metadata.homepageLink,
+                      lang: config.metadata.lang,
+                      currency: config.metadata.currency,
+                  }
+        );
+    };
+
+    // Send the resolved-config lifecycle event to the iframe
+    let mergeTokenConsumed = false;
+    const sendLifecycleConfig = (resolved: SdkResolvedConfig) => {
+        const token = mergeTokenConsumed ? undefined : pendingMergeToken;
+        mergeTokenConsumed = true;
+
+        const sdkConfig = resolved.hasRawSdkConfig
+            ? {
+                  name: resolved.name,
+                  logoUrl: resolved.logoUrl,
+                  homepageLink: resolved.homepageLink,
+                  lang: resolved.lang,
+                  currency: resolved.currency,
+                  hidden: resolved.hidden,
+                  css: resolved.css,
+                  translations: resolved.translations,
+                  placements: resolved.placements,
+              }
+            : undefined;
+
+        rpcClient.sendLifecycle({
+            clientLifecycle: "resolved-config",
+            data: {
+                merchantId: resolved.merchantId,
+                domain: resolved.domain ?? "",
+                allowedDomains: resolved.allowedDomains ?? [],
+                sourceUrl: window.location.href,
+                ...(token && { pendingMergeToken: token }),
+                ...(sdkConfig && { sdkConfig }),
+            },
+        });
+    };
+
+    // SWR: if we have cached data, send it to the iframe immediately
+    if (sdkConfigStore.isResolved) {
+        sendLifecycleConfig(sdkConfigStore.getConfig());
+        contextSent.resolve();
+    }
+
+    // If a fetch is running (stale/missing cache), wait for fresh data and update
+    if (configPromise) {
+        const merchantConfig = await configPromise;
+        mergeAndSetConfig(merchantConfig);
+        sendLifecycleConfig(sdkConfigStore.getConfig());
+        contextSent.resolve();
+    }
+
     // Push raw CSS if needed
     async function pushCss() {
         const cssLink = config.customizations?.css;
         if (!cssLink) return;
-
-        const message = {
+        rpcClient.sendLifecycle({
             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 = {
+        rpcClient.sendLifecycle({
             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 = {
+        rpcClient.sendLifecycle({
             clientLifecycle: "restore-backup" as const,
             data: { backup },
-        };
-        rpcClient.sendLifecycle(message);
+        });
     }
 
     await Promise.allSettled([pushCss(), pushI18n(), pushBackup()]);

package/src/clients/transports/iframeLifecycleManager.test.ts

@@ -102,7 +102,7 @@ describe("createIFrameLifecycleManager", () => {
                 iframeLifecycle: "connected" as const,
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             await expect(manager.isConnected).resolves.toBe(true);
         });
@@ -126,7 +126,7 @@ describe("createIFrameLifecycleManager", () => {
                 data: { backup },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(localStorage.getItem("frak-backup-key")).toBe(backup);
         });
@@ -150,7 +150,7 @@ describe("createIFrameLifecycleManager", () => {
                 data: {},
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(localStorage.getItem("frak-backup-key")).toBeNull();
         });
@@ -173,7 +173,7 @@ describe("createIFrameLifecycleManager", () => {
                 iframeLifecycle: "remove-backup" as const,
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(localStorage.getItem("frak-backup-key")).toBeNull();
         });
@@ -198,7 +198,7 @@ describe("createIFrameLifecycleManager", () => {
                 iframeLifecycle: "show" as const,
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(changeIframeVisibility).toHaveBeenCalledWith({
                 iframe: mockIframe,
@@ -224,7 +224,7 @@ describe("createIFrameLifecycleManager", () => {
                 iframeLifecycle: "hide" as const,
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(changeIframeVisibility).toHaveBeenCalledWith({
                 iframe: mockIframe,
@@ -233,86 +233,6 @@ describe("createIFrameLifecycleManager", () => {
         });
     });
 
-    describe("handshake event", () => {
-        test("should post handshake-response with token to iframe origin", async () => {
-            const { createIFrameLifecycleManager } = await import(
-                "./iframeLifecycleManager"
-            );
-
-            const mockPostMessage = vi.fn();
-            const mockIframe = {
-                src: "https://wallet.frak.id/listener",
-                contentWindow: {
-                    postMessage: mockPostMessage,
-                },
-            } as any;
-
-            const manager = createIFrameLifecycleManager({
-                iframe: mockIframe,
-                targetOrigin: WALLET_ORIGIN,
-            });
-
-            const event = {
-                iframeLifecycle: "handshake" as const,
-                data: { token: "handshake-token-123" },
-            };
-
-            await manager.handleEvent(event);
-
-            expect(mockPostMessage).toHaveBeenCalledWith(
-                {
-                    clientLifecycle: "handshake-response",
-                    data: {
-                        token: "handshake-token-123",
-                        currentUrl: "https://test.com",
-                        clientId: "mock-client-id",
-                    },
-                },
-                "https://wallet.frak.id"
-            );
-        });
-
-        test("should include current URL in handshake response", async () => {
-            const { createIFrameLifecycleManager } = await import(
-                "./iframeLifecycleManager"
-            );
-
-            Object.defineProperty(window, "location", {
-                value: { href: "https://example.com/page?param=value" },
-                writable: true,
-            });
-
-            const mockPostMessage = vi.fn();
-            const mockIframe = {
-                src: "https://wallet.frak.id/listener",
-                contentWindow: {
-                    postMessage: mockPostMessage,
-                },
-            } as any;
-
-            const manager = createIFrameLifecycleManager({
-                iframe: mockIframe,
-                targetOrigin: WALLET_ORIGIN,
-            });
-
-            const event = {
-                iframeLifecycle: "handshake" as const,
-                data: { token: "token" },
-            };
-
-            await manager.handleEvent(event);
-
-            expect(mockPostMessage).toHaveBeenCalledWith(
-                expect.objectContaining({
-                    data: expect.objectContaining({
-                        currentUrl: "https://example.com/page?param=value",
-                    }),
-                }),
-                "https://wallet.frak.id"
-            );
-        });
-    });
-
     describe("redirect event", () => {
         test("should redirect with appended current URL for HTTP URLs", async () => {
             const { createIFrameLifecycleManager } = await import(
@@ -339,7 +259,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(window.location.href).toBe(
                 "https://redirect.com/?u=https%3A%2F%2Foriginal.com"
@@ -371,7 +291,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(window.location.href).toBe("https://redirect.com/path");
         });
@@ -405,7 +325,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(triggerDeepLinkWithFallback).toHaveBeenCalledWith(
                 "frakwallet://wallet",
@@ -450,7 +370,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             // Extract the onFallback callback from the mock call
             const callArgs = (triggerDeepLinkWithFallback as any).mock.calls[0];
@@ -499,7 +419,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             // Should NOT call fallback detection
             expect(triggerDeepLinkWithFallback).not.toHaveBeenCalled();
@@ -525,7 +445,7 @@ describe("createIFrameLifecycleManager", () => {
             } as any;
 
             // Should not throw
-            await expect(manager.handleEvent(event)).resolves.toBeUndefined();
+            expect(manager.handleEvent(event)).toBeUndefined();
         });
 
         test("should only process events with iframeLifecycle", async () => {
@@ -543,13 +463,13 @@ describe("createIFrameLifecycleManager", () => {
             });
 
             // Event without iframeLifecycle
-            await manager.handleEvent({ randomEvent: "show" } as any);
+            manager.handleEvent({ randomEvent: "show" } as any);
 
             // changeIframeVisibility should not be called
             expect(changeIframeVisibility).not.toHaveBeenCalled();
 
             // Event with iframeLifecycle
-            await manager.handleEvent({ iframeLifecycle: "show" as const });
+            manager.handleEvent({ iframeLifecycle: "show" as const });
 
             // Now it should be called
             expect(changeIframeVisibility).toHaveBeenCalled();

package/src/clients/transports/iframeLifecycleManager.ts

@@ -1,6 +1,5 @@
 import { Deferred } from "@frak-labs/frame-connector";
 import type { FrakLifecycleEvent } from "../../types";
-import { getClientId } from "../../utils/clientId";
 import { BACKUP_KEY } from "../../utils/constants";
 import {
     isFrakDeepLink,
@@ -33,7 +32,7 @@ const isIOSInAppBrowser = (() => {
 /** @ignore */
 export type IframeLifecycleManager = {
     isConnected: Promise<boolean>;
-    handleEvent: (messageEvent: FrakLifecycleEvent) => Promise<void>;
+    handleEvent: (messageEvent: FrakLifecycleEvent) => void;
 };
 
 /**
@@ -47,42 +46,6 @@ function handleBackup(backup: string | undefined): void {
     }
 }
 
-/**
- * Handle handshake with iframe — sends client metadata so the listener can resolve the correct merchant
- * @param iframe - The iframe element to post the handshake response to
- * @param token - The handshake token received from the iframe
- * @param targetOrigin - The target origin for postMessage security
- * @param configDomain - Optional override domain for merchant resolution in tunneled/proxied environments
- */
-function handleHandshake(
-    iframe: HTMLIFrameElement,
-    token: string,
-    targetOrigin: string,
-    configDomain?: string
-): void {
-    const url = new URL(window.location.href);
-    const pendingMergeToken = url.searchParams.get("fmt") ?? undefined;
-
-    iframe.contentWindow?.postMessage(
-        {
-            clientLifecycle: "handshake-response",
-            data: {
-                token,
-                currentUrl: window.location.href,
-                pendingMergeToken,
-                configDomain,
-                clientId: getClientId(),
-            },
-        },
-        targetOrigin
-    );
-
-    if (pendingMergeToken) {
-        url.searchParams.delete("fmt");
-        window.history.replaceState({}, "", url.toString());
-    }
-}
-
 /**
  * Compute final redirect URL with parameter substitution
  */
@@ -96,12 +59,12 @@ function computeRedirectUrl(
             return baseRedirectUrl;
         }
 
-        redirectUrl.searchParams.delete("u");
-        redirectUrl.searchParams.append("u", window.location.href);
+        // Append merge token to the page URL so it survives
+        // the backend /common/social redirect chain
+        const finalPageUrl = appendMergeToken(window.location.href, mergeToken);
 
-        if (mergeToken) {
-            redirectUrl.searchParams.append("fmt", mergeToken);
-        }
+        redirectUrl.searchParams.delete("u");
+        redirectUrl.searchParams.append("u", finalPageUrl);
 
         return redirectUrl.toString();
     } catch {
@@ -130,6 +93,21 @@ function isSocialRedirect(url: string): boolean {
     return url.includes("/common/social");
 }
 
+/**
+ * Append merge token to a URL as the `fmt` query parameter.
+ */
+function appendMergeToken(urlString: string, mergeToken?: string): string {
+    if (!mergeToken) return urlString;
+    try {
+        const url = new URL(urlString);
+        url.searchParams.set("fmt", mergeToken);
+        return url.toString();
+    } catch {
+        const sep = urlString.includes("?") ? "&" : "?";
+        return `${urlString}${sep}fmt=${encodeURIComponent(mergeToken)}`;
+    }
+}
+
 /**
  * Handle redirect with deep link fallback
  */
@@ -137,8 +115,18 @@ function handleRedirect(
     iframe: HTMLIFrameElement,
     baseRedirectUrl: string,
     targetOrigin: string,
-    mergeToken?: string
+    mergeToken?: string,
+    openInNewTab?: boolean
 ): void {
+    // If requested, open in a new tab instead of navigating the current page.
+    // This preserves the merchant page while triggering universal links.
+    // Requires the iframe postMessage to include user activation delegation.
+    if (openInNewTab) {
+        const finalUrl = computeRedirectUrl(baseRedirectUrl, mergeToken);
+        window.open(finalUrl, "_blank");
+        return;
+    }
+
     if (isFrakDeepLink(baseRedirectUrl)) {
         const finalUrl = computeRedirectUrl(baseRedirectUrl, mergeToken);
         triggerDeepLinkWithFallback(finalUrl, {
@@ -167,23 +155,20 @@ function handleRedirect(
  * @param args
  * @param args.iframe - The iframe element used for wallet communication
  * @param args.targetOrigin - The wallet URL origin for postMessage security
- * @param args.configDomain - Optional domain override forwarded during handshake for tunneled/proxied environments
  * @ignore
  */
 export function createIFrameLifecycleManager({
     iframe,
     targetOrigin,
-    configDomain,
 }: {
     iframe: HTMLIFrameElement;
     targetOrigin: string;
-    configDomain?: string;
 }): IframeLifecycleManager {
     // Create the isConnected listener
     const isConnectedDeferred = new Deferred<boolean>();
 
     // Build the handler itself
-    const handler = async (messageEvent: FrakLifecycleEvent) => {
+    const handler = (messageEvent: FrakLifecycleEvent) => {
         if (!("iframeLifecycle" in messageEvent)) return;
 
         const { iframeLifecycle: event, data } = messageEvent;
@@ -206,17 +191,14 @@ export function createIFrameLifecycleManager({
             case "hide":
                 changeIframeVisibility({ iframe, isVisible: event === "show" });
                 break;
-            // Handshake handling
-            case "handshake":
-                handleHandshake(iframe, data.token, targetOrigin, configDomain);
-                break;
             // Redirect handling
             case "redirect":
                 handleRedirect(
                     iframe,
                     data.baseRedirectUrl,
                     targetOrigin,
-                    data.mergeToken
+                    data.mergeToken,
+                    data.openInNewTab
                 );
                 break;
         }