@frak-labs/core-sdk 0.2.1-beta.b38eef2e → 0.2.1-beta.d04602ec

package/src/actions/index.ts

@@ -1,15 +1,21 @@
 export { displayEmbeddedWallet } from "./displayEmbeddedWallet";
 export { displayModal } from "./displayModal";
+export { displaySharingPage } from "./displaySharingPage";
 export { ensureIdentity } from "./ensureIdentity";
 export { getMerchantInformation } from "./getMerchantInformation";
+export { getUserReferralStatus } from "./getUserReferralStatus";
 export { openSso } from "./openSso";
 export { prepareSso } from "./prepareSso";
 export {
     type ProcessReferralOptions,
     processReferral,
 } from "./referral/processReferral";
-// Referral interaction
+// Referral
 export { referralInteraction } from "./referral/referralInteraction";
+export {
+    REFERRAL_SUCCESS_EVENT,
+    setupReferral,
+} from "./referral/setupReferral";
 export { sendInteraction } from "./sendInteraction";
 // Helper to track the purchase status
 export { trackPurchaseStatus } from "./trackPurchaseStatus";

package/src/actions/referral/setupReferral.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { REFERRAL_SUCCESS_EVENT, setupReferral } from "./setupReferral";
+
+vi.mock("./referralInteraction", () => ({
+    referralInteraction: vi.fn(),
+}));
+
+import { referralInteraction } from "./referralInteraction";
+
+describe("setupReferral", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it("should dispatch referral success event on successful referral", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue("success");
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).toHaveBeenCalledTimes(1);
+        expect(listener).toHaveBeenCalledWith(expect.any(Event));
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should not dispatch event when referral state is not success", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue("no-referrer");
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should not dispatch event when referral returns undefined", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue(undefined);
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should silently catch errors and log warning", async () => {
+        vi.mocked(referralInteraction).mockRejectedValue(
+            new Error("network failure")
+        );
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+        expect(warnSpy).toHaveBeenCalledWith(
+            "[Frak] Referral setup failed",
+            expect.any(Error)
+        );
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+        warnSpy.mockRestore();
+    });
+
+    it("should export the correct event name constant", () => {
+        expect(REFERRAL_SUCCESS_EVENT).toBe("frak:referral-success");
+    });
+});

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,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;
                 },
             },
@@ -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,144 @@ 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,
+                  }
+                : {
+                      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()]);