@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.61e6fb99

package/src/actions/trackPurchaseStatus.ts

@@ -1,6 +1,6 @@
 import { getBackendUrl } from "../utils/backendUrl";
 import { getClientId } from "../utils/clientId";
-import { fetchMerchantId } from "../utils/merchantId";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 
 /**
  * Function used to track the status of a purchase
@@ -26,7 +26,7 @@ import { fetchMerchantId } from "../utils/merchantId";
  * }
  *
  * @remarks
- * - Merchant id is resolved in this order: explicit `args.merchantId`, `frak-merchant-id` from session storage, then `fetchMerchantId()`.
+ * - Merchant id is resolved in this order: explicit `args.merchantId`, then `sdkConfigStore.resolveMerchantId()` (config store → sessionStorage → backend fetch).
  * - This function supports anonymous users and will use the `x-frak-client-id` header when available.
  * - At least one identity source must exist (`frak-wallet-interaction-token` or `x-frak-client-id`), otherwise the tracking request is skipped.
  * - This function will print a warning if used in a non-browser environment or if no identity / merchant id can be resolved.
@@ -52,10 +52,8 @@ export async function trackPurchaseStatus(args: {
         return;
     }
 
-    const merchantIdFromStorage =
-        window.sessionStorage.getItem("frak-merchant-id");
     const merchantId =
-        args.merchantId ?? merchantIdFromStorage ?? (await fetchMerchantId());
+        args.merchantId ?? (await sdkConfigStore.resolveMerchantId());
 
     if (!merchantId) {
         console.warn("[Frak] No merchant id found, skipping purchase check");

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

@@ -196,7 +196,8 @@ describe("modalBuilder", () => {
 
             expect(displayModal).toHaveBeenCalledWith(
                 mockClient,
-                builder.params
+                builder.params,
+                undefined
             );
         });
 
@@ -216,7 +217,8 @@ describe("modalBuilder", () => {
                 mockClient,
                 expect.objectContaining({
                     metadata: { header: { title: "Overridden" } },
-                })
+                }),
+                undefined
             );
         });
 

package/src/actions/wrapper/modalBuilder.ts

@@ -46,11 +46,13 @@ export type ModalStepBuilder<
     /**
      * Display the modal
      * @param metadataOverride - Function returning optional metadata to override the current modal metadata
+     * @param placement - Optional placement ID to associate with this modal display
      */
     display: (
         metadataOverride?: (
             current?: ModalRpcMetadata
-        ) => ModalRpcMetadata | undefined
+        ) => ModalRpcMetadata | undefined,
+        placement?: string
     ) => Promise<ModalRpcStepsResultType<Steps>>;
 };
 
@@ -177,27 +179,23 @@ function modalStepsBuilder<CurrentSteps extends ModalStepTypes[]>(
         );
     }
 
-    // Function to display it
     async function display(
         metadataOverride?: (
             current?: ModalRpcMetadata
-        ) => ModalRpcMetadata | undefined
+        ) => ModalRpcMetadata | undefined,
+        placement?: string
     ) {
-        // If we have a metadata override, apply it
         if (metadataOverride) {
             params.metadata = metadataOverride(params.metadata ?? {});
         }
-        return await displayModal(client, params);
+        return await displayModal(client, params, placement);
     }
 
     return {
-        // Access current modal params
         params,
-        // Function to add new steps
         sendTx,
         reward,
         sharing,
-        // Display the modal
         display,
     };
 }

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,39 @@ 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>();
+
+    // Handshake timing: measured from client creation until the iframe
+    // lifecycle manager resolves the `isConnected` promise.
+    const handshakeStartedAt = Date.now();
+
     // Create our debug info gatherer
     const debugInfo = new DebugInfoGatherer(config, iframe);
 
@@ -70,10 +101,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 +111,7 @@ export function createIFrameFrakClient({
                             "The iframe provider isn't connected yet"
                         );
                     }
+                    await contextSent.promise;
                     return ctx;
                 },
             },
@@ -98,9 +129,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 +139,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
@@ -154,6 +184,38 @@ export function createIFrameFrakClient({
             userAnonymousClientId: getClientId(),
         });
         openPanel.init();
+        openPanel.track("sdk_initialized", {
+            sdkVersion: process.env.SDK_VERSION,
+        });
+
+        // Race the connection against the heartbeat timeout so we can
+        // distinguish "connected" from "timeout" cleanly without touching
+        // the heartbeat plumbing. 30s matches `HEARTBEAT_TIMEOUT`.
+        let settled = false;
+        const timeoutHandle = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            openPanel?.track("sdk_iframe_handshake_failed", {
+                reason: "timeout",
+            });
+        }, 30_000);
+        lifecycleManager.isConnected
+            .then(() => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeoutHandle);
+                openPanel?.track("sdk_iframe_connected", {
+                    handshake_duration_ms: Date.now() - handshakeStartedAt,
+                });
+            })
+            .catch(() => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeoutHandle);
+                openPanel?.track("sdk_iframe_handshake_failed", {
+                    reason: "unknown",
+                });
+            });
     }
 
     // Perform the post connection setup
@@ -161,7 +223,15 @@ export function createIFrameFrakClient({
         config,
         rpcClient,
         lifecycleManager,
-    }).then(() => debugInfo.updateSetupStatus(true));
+        configPromise,
+        contextSent,
+        openPanel,
+    })
+        .then(() => debugInfo.updateSetupStatus(true))
+        .catch((err) => {
+            contextSent.reject(err);
+            throw err;
+        });
 
     return {
         config,
@@ -238,55 +308,190 @@ async function postConnectionSetup({
     config,
     rpcClient,
     lifecycleManager,
+    configPromise,
+    contextSent,
+    openPanel,
 }: {
     config: FrakWalletSdkConfig;
     rpcClient: SdkRpcClient;
     lifecycleManager: IframeLifecycleManager;
+    configPromise: Promise<MerchantConfigResult> | undefined;
+    contextSent: Deferred<void>;
+    openPanel: OpenPanel | undefined;
 }): 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;
+
+        // Per-field merge: backend wins over SDK static config.
+        const mergedAttribution =
+            raw?.attribution || config.attribution
+                ? { ...config.attribution, ...raw?.attribution }
+                : undefined;
+
+        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,
+                      attribution: mergedAttribution,
+                  }
+                : {
+                      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,
+                      attribution: mergedAttribution,
+                  }
+        );
+    };
+
+    // Send the resolved-config lifecycle event to the iframe.
+    // This is where we also update SDK-side OpenPanel global props with
+    // `merchantId` + `domain` (first time they are known) so every
+    // subsequent SDK event is merchant-attributed. We pass
+    // `sdkAnonymousId` through so the listener can join SDK funnels.
+    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,
+                  attribution: resolved.attribution,
+              }
+            : resolved.attribution
+              ? { attribution: resolved.attribution }
+              : undefined;
+
+        const sdkAnonymousId = getClientId();
+
+        if (openPanel) {
+            const current = openPanel.global ?? {};
+            openPanel.setGlobalProperties({
+                ...current,
+                merchantId: resolved.merchantId,
+                domain: resolved.domain ?? "",
+            });
+        }
+
+        rpcClient.sendLifecycle({
+            clientLifecycle: "resolved-config",
+            data: {
+                merchantId: resolved.merchantId,
+                domain: resolved.domain ?? "",
+                allowedDomains: resolved.allowedDomains ?? [],
+                sourceUrl: window.location.href,
+                ...(sdkAnonymousId && { sdkAnonymousId }),
+                ...(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()]);
+    // Inspect each setup result — a failed CSS/i18n/backup push leaves the
+    // partner UI in a broken-but-connected state (iframe reports
+    // `sdk_iframe_connected`, user sees no modal styles / wrong locale).
+    // Surface it as a distinct handshake reason so dashboards can
+    // distinguish timeout vs. asset-push failures.
+    const results = await Promise.allSettled([
+        pushCss(),
+        pushI18n(),
+        pushBackup(),
+    ]);
+    const hasFailedAssetPush = results.some((r) => r.status === "rejected");
+    if (hasFailedAssetPush) {
+        openPanel?.track("sdk_iframe_handshake_failed", {
+            reason: "asset_push",
+        });
+    }
 }

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();