@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.10dada3f

package/src/actions/referral/setupReferral.ts

@@ -0,0 +1,32 @@
+import type { FrakClient } from "../../types";
+import { referralInteraction } from "./referralInteraction";
+
+/**
+ * Custom event name dispatched on successful referral processing.
+ *
+ * Fired once per page load when a valid referral context is found in the URL
+ * and successfully tracked. Consumers (e.g. `<frak-banner>`) listen for this
+ * to display a referral success message.
+ */
+export const REFERRAL_SUCCESS_EVENT = "frak:referral-success";
+
+/**
+ * Process referral context and emit a DOM event on success.
+ *
+ * - Calls {@link referralInteraction} to detect and track any referral in the URL
+ * - On `"success"`, dispatches a bare {@link REFERRAL_SUCCESS_EVENT} on `window`
+ * - Silently swallows errors (fire-and-forget during SDK init)
+ *
+ * @param client - The initialized Frak client
+ */
+export async function setupReferral(client: FrakClient): Promise<void> {
+    try {
+        const state = await referralInteraction(client);
+
+        if (state === "success") {
+            window.dispatchEvent(new Event(REFERRAL_SUCCESS_EVENT));
+        }
+    } catch (error) {
+        console.warn("[Frak] Referral setup failed", error);
+    }
+}

package/src/actions/trackPurchaseStatus.test.ts

@@ -11,12 +11,14 @@ vi.mock("../utils/clientId", () => ({
     getClientId: vi.fn().mockReturnValue("test-client-id"),
 }));
 
-vi.mock("../utils/merchantId", () => ({
-    fetchMerchantId: vi.fn().mockResolvedValue(undefined),
+vi.mock("../utils/sdkConfigStore", () => ({
+    sdkConfigStore: {
+        resolveMerchantId: vi.fn().mockResolvedValue(undefined),
+    },
 }));
 
 import { getClientId } from "../utils/clientId";
-import { fetchMerchantId } from "../utils/merchantId";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 import { trackPurchaseStatus } from "./trackPurchaseStatus";
 
 describe.sequential("trackPurchaseStatus", () => {
@@ -100,7 +102,9 @@ describe.sequential("trackPurchaseStatus", () => {
         });
 
         vi.mocked(getClientId).mockReturnValue("test-client-id");
-        vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+        vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+            undefined
+        );
 
         fetchSpy = vi.fn().mockResolvedValue({
             ok: true,
@@ -228,12 +232,15 @@ describe.sequential("trackPurchaseStatus", () => {
         test("should resolve merchantId from explicit param first", async () => {
             setupStorage({
                 interactionToken: "token-123",
-                merchantId: "session-merchant-id",
+                merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
-            const merchantLookupCallsBefore =
-                vi.mocked(fetchMerchantId).mock.calls.length;
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "fetched-merchant-id"
+            );
+            const merchantLookupCallsBefore = vi.mocked(
+                sdkConfigStore.resolveMerchantId
+            ).mock.calls.length;
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -253,19 +260,20 @@ describe.sequential("trackPurchaseStatus", () => {
                     merchantId: "explicit-merchant-id",
                 })
             );
-            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
-                merchantLookupCallsBefore
-            );
+            expect(
+                vi.mocked(sdkConfigStore.resolveMerchantId).mock.calls.length
+            ).toBe(merchantLookupCallsBefore);
         });
 
         test("should fall back to sessionStorage for merchantId", async () => {
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "session-merchant-id"
+            );
             setupStorage({
                 interactionToken: "token-123",
-                merchantId: "session-merchant-id",
+                merchantId: null,
                 clientId: "test-client-id",
             });
-            const merchantLookupCallsBefore =
-                vi.mocked(fetchMerchantId).mock.calls.length;
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -284,18 +292,20 @@ describe.sequential("trackPurchaseStatus", () => {
                     merchantId: "session-merchant-id",
                 })
             );
-            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
-                merchantLookupCallsBefore
-            );
+            expect(
+                vi.mocked(sdkConfigStore.resolveMerchantId)
+            ).toHaveBeenCalled();
         });
 
-        test("should fall back to fetchMerchantId when no explicit or sessionStorage", async () => {
+        test("should fall back to resolveMerchantId when no explicit merchantId", async () => {
             setupStorage({
                 interactionToken: "token-123",
                 merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "fetched-merchant-id"
+            );
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -322,7 +332,9 @@ describe.sequential("trackPurchaseStatus", () => {
                 merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                undefined
+            );
             const callCountBefore = getTrackingRequests().length;
 
             await trackPurchaseStatus({

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",
+        });
+    }
 }