@frak-labs/core-sdk 0.2.0 → 0.2.1-beta.06c52c98

package/src/clients/createIFrameFrakClient.ts

@@ -1,5 +1,6 @@
 import {
     createRpcClient,
+    Deferred,
     FrakRpcError,
     type RpcClient,
     RpcErrorCodes,
@@ -8,9 +9,11 @@ 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 { BACKUP_KEY } from "../utils/constants";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 import { setupSsoUrlListener } from "../utils/ssoUrlListener";
 import { DebugInfoGatherer } from "./DebugInfo";
 import {
@@ -19,12 +22,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 +50,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 +96,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 +106,7 @@ export function createIFrameFrakClient({
                             "The iframe provider isn't connected yet"
                         );
                     }
+                    await contextSent.promise;
                     return ctx;
                 },
             },
@@ -108,14 +134,12 @@ 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();
+        sdkConfigStore.clearCache();
+        sdkConfigStore.reset();
     };
 
     // Init open panel
@@ -161,7 +185,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 +269,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()]);

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

@@ -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(

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,
@@ -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
  */
@@ -167,17 +130,14 @@ 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>();
@@ -206,10 +166,6 @@ 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(

package/src/index.ts

@@ -28,6 +28,8 @@ export type {
     FrakClient,
     // Utils
     FrakContext,
+    FrakContextV1,
+    FrakContextV2,
     FrakLifecycleEvent,
     // Config
     FrakWalletSdkConfig,
@@ -45,6 +47,7 @@ export type {
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
     LoginModalStepType,
+    MerchantConfigResponse,
     ModalRpcMetadata,
     ModalRpcStepsInput,
     ModalRpcStepsResultType,
@@ -56,7 +59,10 @@ export type {
     OpenSsoReturnType,
     PrepareSsoParamsType,
     PrepareSsoReturnType,
+    ResolvedPlacement,
+    ResolvedSdkConfig,
     RewardTier,
+    SdkResolvedConfig,
     // RPC Interaction
     SendInteractionParamsType,
     SendTransactionModalStepType,
@@ -74,6 +80,7 @@ export type {
     // Rpc
     WalletStatusReturnType,
 } from "./types";
+export { isV1Context, isV2Context } from "./types";
 // Utils
 export {
     type AppSpecificSsoMetadata,
@@ -81,7 +88,6 @@ export {
     base64urlEncode,
     baseIframeProps,
     type CompressedSsoData,
-    clearMerchantIdCache,
     compressJsonToB64,
     createIframe,
     DEEP_LINK_SCHEME,
@@ -90,7 +96,6 @@ export {
     FrakContextManager,
     type FrakEvent,
     type FullSsoParams,
-    fetchMerchantId,
     findIframeInOpener,
     formatAmount,
     generateSsoUrl,
@@ -101,7 +106,7 @@ export {
     getSupportedLocale,
     isChromiumAndroid,
     isFrakDeepLink,
-    resolveMerchantId,
+    sdkConfigStore,
     toAndroidIntentUrl,
     trackEvent,
     triggerDeepLinkWithFallback,

package/src/types/config.ts

@@ -27,7 +27,7 @@ export type FrakWalletSdkConfig = {
         /**
          * Your application name (will be displayed in a few modals and in SSO)
          */
-        name: string;
+        name?: string;
         /**
          * Your merchant ID from the Frak dashboard (UUID format)
          * Used for referral tracking and analytics
@@ -71,6 +71,13 @@ export type FrakWalletSdkConfig = {
      * @defaultValue window.location.host
      */
     domain?: string;
+    /**
+     * Wait for backend config before rendering components.
+     * When true (default), components show a spinner until backend config is resolved.
+     * When false, components render immediately with SDK static config / HTML attributes.
+     * @defaultValue true
+     */
+    waitForBackendConfig?: boolean;
 };
 
 /**
@@ -111,7 +118,7 @@ export type I18nConfig =
     | LocalizedI18nConfig;
 
 /**
- * A localized i18n config
+ * A localized i18n config (inline objects only — URL-based i18n removed)
  * @category Config
  */
-export type LocalizedI18nConfig = `${string}.css` | { [key: string]: string };
+export type LocalizedI18nConfig = { [key: string]: string };

package/src/types/context.ts

@@ -1,13 +1,55 @@
 import type { Address } from "viem";
 
 /**
- * The current Frak Context
- *
- * For now, only contain a referrer address.
- *
+ * V1 (legacy) Frak Context — contains only the referrer wallet address.
+ * Used for backward compatibility with old sharing links.
  * @ignore
  */
-export type FrakContext = {
-    // Referrer address
+export type FrakContextV1 = {
+    /** Referrer wallet address */
     r: Address;
 };
+
+/**
+ * V2 Frak Context — anonymous-first referral context.
+ * Contains the sharer's clientId, merchantId, and link creation timestamp.
+ * @ignore
+ */
+export type FrakContextV2 = {
+    /** Version discriminator */
+    v: 2;
+    /** Sharer's anonymous clientId (UUID from localStorage) */
+    c: string;
+    /** Merchant ID (UUID) */
+    m: string;
+    /** Link creation timestamp (epoch seconds) */
+    t: number;
+};
+
+/**
+ * The current Frak Context — union of all versions.
+ *
+ * - No `v` field → V1 (legacy wallet address)
+ * - `v: 2` → V2 (anonymous clientId-based)
+ *
+ * @ignore
+ */
+export type FrakContext = FrakContextV1 | FrakContextV2;
+
+/**
+ * Type guard: check if a context is V1 (legacy wallet address).
+ * @param ctx - The Frak context to check
+ * @returns True if the context is a V1 context
+ */
+export function isV1Context(ctx: FrakContext): ctx is FrakContextV1 {
+    return "r" in ctx && !("v" in ctx);
+}
+
+/**
+ * Type guard: check if a context is V2 (anonymous clientId-based).
+ * @param ctx - The Frak context to check
+ * @returns True if the context is a V2 context
+ */
+export function isV2Context(ctx: FrakContext): ctx is FrakContextV2 {
+    return "v" in ctx && ctx.v === 2;
+}

package/src/types/index.ts

@@ -15,12 +15,18 @@ export type {
     LocalizedI18nConfig,
 } from "./config";
 // Utils
-export type { FrakContext } from "./context";
-
+export type { FrakContext, FrakContextV1, FrakContextV2 } from "./context";
+export { isV1Context, isV2Context } from "./context";
 export type {
     ClientLifecycleEvent,
     IFrameLifecycleEvent,
 } from "./lifecycle";
+export type {
+    MerchantConfigResponse,
+    ResolvedPlacement,
+    ResolvedSdkConfig,
+    SdkResolvedConfig,
+} from "./resolvedConfig";
 export type { IFrameRpcSchema } from "./rpc";
 // Modal related
 export type {

package/src/types/lifecycle/client.ts

@@ -1,4 +1,5 @@
 import type { I18nConfig } from "../config";
+import type { ResolvedSdkConfig } from "../resolvedConfig";
 
 /**
  * Event related to the iframe lifecycle
@@ -9,9 +10,9 @@ export type ClientLifecycleEvent =
     | CustomI18nEvent
     | RestoreBackupEvent
     | HearbeatEvent
-    | HandshakeResponse
     | SsoRedirectCompleteEvent
-    | DeepLinkFailedEvent;
+    | DeepLinkFailedEvent
+    | ResolvedConfigEvent;
 
 type CustomCssEvent = {
     clientLifecycle: "modal-css";
@@ -33,31 +34,6 @@ type HearbeatEvent = {
     data?: never;
 };
 
-type HandshakeResponse = {
-    clientLifecycle: "handshake-response";
-    data: {
-        token: string;
-        currentUrl: string;
-        /**
-         * Pending merge token extracted from URL (?fmt= parameter)
-         * When present, listener should execute identity merge in background
-         * URL is cleaned after handshake response is sent
-         */
-        pendingMergeToken?: string;
-        /**
-         * Client ID for identity tracking (belt & suspenders fallback)
-         * Primary delivery is via iframe URL query param; handshake is backup for SSR
-         */
-        clientId?: string;
-        /**
-         * Explicit domain from SDK config (FrakWalletSdkConfig.domain)
-         * When present, listener should prefer this over URL-derived domain
-         * for merchant resolution (handles proxied/tunneled environments)
-         */
-        configDomain?: string;
-    };
-};
-
 type SsoRedirectCompleteEvent = {
     clientLifecycle: "sso-redirect-complete";
     data: { compressed: string };
@@ -67,3 +43,22 @@ type DeepLinkFailedEvent = {
     clientLifecycle: "deep-link-failed";
     data: { originalUrl: string };
 };
+
+type ResolvedConfigEvent = {
+    clientLifecycle: "resolved-config";
+    data: {
+        merchantId: string;
+        /** The domain the backend resolved this config for */
+        domain: string;
+        /** All domains registered for this merchant (for domain proof) */
+        allowedDomains: string[];
+        /** Full URL of the parent page (for interaction tracking) */
+        sourceUrl: string;
+        /**
+         * Pending merge token extracted from URL (?fmt= parameter).
+         * When present, listener should execute identity merge in background.
+         */
+        pendingMergeToken?: string;
+        sdkConfig?: ResolvedSdkConfig;
+    };
+};