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

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

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

package/src/clients/transports/iframeLifecycleManager.ts

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

package/src/index.ts

@@ -12,6 +12,8 @@ export { type LocalesKey, locales } from "./constants/locales";
 
 // Types
 export type {
+    AttributionDefaults,
+    AttributionParams,
     ClientLifecycleEvent,
     CompressedData,
     Currency,
@@ -19,6 +21,9 @@ export type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
     DisplayModalParamsType,
+    // RPC Sharing page
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
     EmbeddedViewActionReferred,
     EmbeddedViewActionSharing,
     EstimatedReward,
@@ -47,6 +52,7 @@ export type {
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
     LoginModalStepType,
+    MerchantConfigResponse,
     ModalRpcMetadata,
     ModalRpcStepsInput,
     ModalRpcStepsResultType,
@@ -58,12 +64,16 @@ export type {
     OpenSsoReturnType,
     PrepareSsoParamsType,
     PrepareSsoReturnType,
+    ResolvedPlacement,
+    ResolvedSdkConfig,
     RewardTier,
+    SdkResolvedConfig,
     // RPC Interaction
     SendInteractionParamsType,
     SendTransactionModalStepType,
     SendTransactionReturnType,
     SendTransactionTxType,
+    SharingPageProduct,
     SiweAuthenticateModalStepType,
     SiweAuthenticateReturnType,
     SiweAuthenticationParams,
@@ -72,8 +82,9 @@ export type {
     // Tracking
     TrackArrivalParams,
     TrackArrivalResult,
-    UtmParams,
     // Rpc
+    UserReferralStatusType,
+    UtmParams,
     WalletStatusReturnType,
 } from "./types";
 export { isV1Context, isV2Context } from "./types";
@@ -84,29 +95,38 @@ export {
     base64urlEncode,
     baseIframeProps,
     type CompressedSsoData,
-    clearMerchantIdCache,
+    clearAllCache,
     compressJsonToB64,
     createIframe,
     DEEP_LINK_SCHEME,
     type DeepLinkFallbackOptions,
     decompressJsonFromB64,
     FrakContextManager,
-    type FrakEvent,
     type FullSsoParams,
-    fetchMerchantId,
     findIframeInOpener,
     formatAmount,
     generateSsoUrl,
     getBackendUrl,
+    getCache,
     getClientId,
     getCurrencyAmountKey,
     getSupportedCurrency,
     getSupportedLocale,
     isChromiumAndroid,
     isFrakDeepLink,
-    resolveMerchantId,
+    isInAppBrowser,
+    isIOS,
+    type MergeAttributionInput,
+    mergeAttribution,
+    redirectToExternalBrowser,
+    sdkConfigStore,
     toAndroidIntentUrl,
     trackEvent,
     triggerDeepLinkWithFallback,
+    withCache,
 } from "./utils";
+export type {
+    SdkEventMap,
+    SdkHandshakeFailureReason,
+} from "./utils/analytics";
 export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/stubs/rrweb.ts

@@ -0,0 +1,9 @@
+/**
+ * Stub for rrweb. The @openpanel/web package statically imports `record` from
+ * rrweb even when session replay is disabled. This stub replaces the module so
+ * that rrweb is not included in the bundle.
+ * @see https://github.com/Openpanel-dev/openpanel/issues/336
+ */
+export function record() {
+    return () => {};
+}

package/src/types/config.ts

@@ -1,3 +1,5 @@
+import type { AttributionDefaults } from "./tracking";
+
 /**
  * All the currencies available
  * @category Config
@@ -27,7 +29,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 +73,20 @@ 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;
+    /**
+     * Default attribution params (UTM / via / ref) appended to outbound
+     * sharing URLs. Per-call `displaySharingPage` overrides win, then backend
+     * config, then this SDK-level default. `utm_content` is intentionally
+     * excluded — it is per-content/per-product, never a merchant-wide default.
+     */
+    attribution?: AttributionDefaults;
 };
 
 /**
@@ -111,7 +127,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

@@ -11,19 +11,31 @@ export type FrakContextV1 = {
 };
 
 /**
- * V2 Frak Context — anonymous-first referral context.
- * Contains the sharer's clientId, merchantId, and link creation timestamp.
+ * V2 Frak Context — anonymous-first referral context with optional wallet.
+ *
+ * Carries merchant context (`m`) and creation timestamp (`t`) unconditionally.
+ * Identifies the sharer via either the anonymous clientId (`c`) or, when the
+ * sharer is authenticated, the stronger wallet identifier (`w`). A valid V2
+ * context MUST contain at least one of `c` or `w`; both may be present when
+ * a logged-in user shares a link (best attribution signal).
+ *
+ * `w` takes precedence as the source of truth because the wallet is bound to
+ * the user's WebAuthn credential, survives localStorage clears, and is global
+ * across merchants — unlike `c`, which is a per-browser UUID.
+ *
  * @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;
+    /** Sharer's anonymous clientId (UUID from localStorage). Optional when `w` is provided. */
+    c?: string;
+    /** Sharer's wallet address. Preferred source of truth when the sharer is authenticated. Optional when `c` is provided. */
+    w?: Address;
 };
 
 /**

package/src/types/index.ts

@@ -17,11 +17,16 @@ export type {
 // Utils
 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 {
@@ -31,6 +36,12 @@ export type {
     ModalRpcStepsResultType,
     ModalStepTypes,
 } from "./rpc/displayModal";
+// Sharing page related
+export type {
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
+    SharingPageProduct,
+} from "./rpc/displaySharingPage";
 export type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
@@ -65,9 +76,12 @@ export type {
     PrepareSsoReturnType,
     SsoMetadata,
 } from "./rpc/sso";
+export type { UserReferralStatusType } from "./rpc/userReferralStatus";
 export type { WalletStatusReturnType } from "./rpc/walletStatus";
 // Tracking
 export type {
+    AttributionDefaults,
+    AttributionParams,
     TrackArrivalParams,
     TrackArrivalResult,
     UtmParams,

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,29 @@ 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;
+        /**
+         * Persistent per-origin anonymous id generated on the partner site
+         * (SDK-side localStorage). Propagated here so the listener can
+         * set it as an OpenPanel global property and stitch SDK events
+         * with listener events in the same funnel.
+         */
+        sdkAnonymousId?: string;
+        sdkConfig?: ResolvedSdkConfig;
+    };
+};