@frak-labs/core-sdk 0.2.1-beta.d2556d47 → 0.2.1-beta.eb3cff34

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/clients/createIFrameFrakClient.ts

@@ -12,6 +12,7 @@ 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";
@@ -124,9 +125,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);
             },
         },
     });
@@ -138,6 +139,7 @@ export function createIFrameFrakClient({
         stopHeartbeat();
         rpcClient.cleanup();
         iframe.remove();
+        clearAllCache();
         sdkConfigStore.clearCache();
         sdkConfigStore.reset();
     };
@@ -316,6 +318,7 @@ async function postConnectionSetup({
                       css: raw.css,
                       translations: raw.translations,
                       placements: raw.placements,
+                      components: raw.components,
                   }
                 : {
                       isResolved: true,

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,
@@ -259,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"
@@ -291,7 +291,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(window.location.href).toBe("https://redirect.com/path");
         });
@@ -325,7 +325,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             expect(triggerDeepLinkWithFallback).toHaveBeenCalledWith(
                 "frakwallet://wallet",
@@ -370,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];
@@ -419,7 +419,7 @@ describe("createIFrameLifecycleManager", () => {
                 },
             };
 
-            await manager.handleEvent(event);
+            manager.handleEvent(event);
 
             // Should NOT call fallback detection
             expect(triggerDeepLinkWithFallback).not.toHaveBeenCalled();
@@ -445,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 () => {
@@ -463,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

@@ -32,7 +32,7 @@ const isIOSInAppBrowser = (() => {
 /** @ignore */
 export type IframeLifecycleManager = {
     isConnected: Promise<boolean>;
-    handleEvent: (messageEvent: FrakLifecycleEvent) => Promise<void>;
+    handleEvent: (messageEvent: FrakLifecycleEvent) => void;
 };
 
 /**
@@ -59,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 {
@@ -93,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
  */
@@ -100,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, {
@@ -143,7 +168,7 @@ export function createIFrameLifecycleManager({
     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;
@@ -172,7 +197,8 @@ export function createIFrameLifecycleManager({
                     iframe,
                     data.baseRedirectUrl,
                     targetOrigin,
-                    data.mergeToken
+                    data.mergeToken,
+                    data.openInNewTab
                 );
                 break;
         }

package/src/index.ts

@@ -19,6 +19,9 @@ export type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
     DisplayModalParamsType,
+    // RPC Sharing page
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
     EmbeddedViewActionReferred,
     EmbeddedViewActionSharing,
     EstimatedReward,
@@ -68,6 +71,7 @@ export type {
     SendTransactionModalStepType,
     SendTransactionReturnType,
     SendTransactionTxType,
+    SharingPageProduct,
     SiweAuthenticateModalStepType,
     SiweAuthenticateReturnType,
     SiweAuthenticationParams,
@@ -76,8 +80,9 @@ export type {
     // Tracking
     TrackArrivalParams,
     TrackArrivalResult,
-    UtmParams,
     // Rpc
+    UserReferralStatusType,
+    UtmParams,
     WalletStatusReturnType,
 } from "./types";
 export { isV1Context, isV2Context } from "./types";
@@ -88,6 +93,7 @@ export {
     base64urlEncode,
     baseIframeProps,
     type CompressedSsoData,
+    clearAllCache,
     compressJsonToB64,
     createIframe,
     DEEP_LINK_SCHEME,
@@ -100,15 +106,20 @@ export {
     formatAmount,
     generateSsoUrl,
     getBackendUrl,
+    getCache,
     getClientId,
     getCurrencyAmountKey,
     getSupportedCurrency,
     getSupportedLocale,
     isChromiumAndroid,
     isFrakDeepLink,
+    isInAppBrowser,
+    isIOS,
+    redirectToExternalBrowser,
     sdkConfigStore,
     toAndroidIntentUrl,
     trackEvent,
     triggerDeepLinkWithFallback,
+    withCache,
 } from "./utils";
 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/index.ts

@@ -36,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,
@@ -70,6 +76,7 @@ export type {
     PrepareSsoReturnType,
     SsoMetadata,
 } from "./rpc/sso";
+export type { UserReferralStatusType } from "./rpc/userReferralStatus";
 export type { WalletStatusReturnType } from "./rpc/walletStatus";
 // Tracking
 export type {

package/src/types/lifecycle/iframe.ts

@@ -29,5 +29,12 @@ type RedirectRequestEvent = {
          * Used when redirecting out of social browsers to preserve identity across contexts
          */
         mergeToken?: string;
+        /**
+         * When true, open the URL in a new tab via window.open(_blank)
+         * instead of navigating the current page.
+         * Requires the postMessage to include user activation delegation
+         * (includeUserActivation: true) so Safari allows the popup.
+         */
+        openInNewTab?: boolean;
     };
 };

package/src/types/resolvedConfig.ts

@@ -23,18 +23,37 @@ export type ResolvedPlacement = {
         buttonShare?: {
             text?: string;
             noRewardText?: string;
-            clickAction?: "embedded-wallet" | "share-modal";
+            clickAction?: "embedded-wallet" | "share-modal" | "sharing-page";
             useReward?: boolean;
             css?: string;
         };
         buttonWallet?: {
-            position?: "bottom-right" | "bottom-left";
+            position?: "right" | "left";
             css?: string;
         };
         openInApp?: {
             text?: string;
             css?: string;
         };
+        postPurchase?: {
+            badgeText?: string;
+            refereeText?: string;
+            refereeNoRewardText?: string;
+            referrerText?: string;
+            referrerNoRewardText?: string;
+            ctaText?: string;
+            ctaNoRewardText?: string;
+            css?: string;
+        };
+        banner?: {
+            referralTitle?: string;
+            referralDescription?: string;
+            referralCta?: string;
+            inappTitle?: string;
+            inappDescription?: string;
+            inappCta?: string;
+            css?: string;
+        };
     };
     targetInteraction?: string;
     /** Already flattened: default + lang-specific merged into one record */
@@ -59,6 +78,8 @@ export type ResolvedSdkConfig = {
     css?: string;
     translations?: Record<string, string>;
     placements?: Record<string, ResolvedPlacement>;
+    /** Global component defaults (used when no placement override exists) */
+    components?: ResolvedPlacement["components"];
 };
 
 /**
@@ -101,4 +122,7 @@ export type SdkResolvedConfig = {
 
     /** Named placements (keyed by placement ID) */
     placements?: Record<string, ResolvedPlacement>;
+
+    /** Global component defaults (fallback for placement-level overrides) */
+    components?: ResolvedPlacement["components"];
 };

package/src/types/rpc/displaySharingPage.ts

@@ -0,0 +1,82 @@
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
+import type { I18nConfig } from "../config";
+
+/**
+ * Product information to display on the sharing page
+ * @group Sharing Page
+ */
+export type SharingPageProduct = {
+    /**
+     * The product title / name
+     */
+    title: string;
+    /**
+     * Optional product image URL
+     */
+    imageUrl?: string;
+    /**
+     * Optional product-specific sharing link
+     * When provided and the product is selected, this link is used instead of the default sharing link
+     */
+    link?: string;
+};
+
+/**
+ * Parameters to display the sharing page
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+export type DisplaySharingPageParamsType = {
+    /**
+     * Products to showcase on the sharing page
+     * If provided, they will be displayed in a product card section
+     */
+    products?: SharingPageProduct[];
+    /**
+     * Optional link override for sharing
+     * If not provided, the sharing link will be generated from the current page URL + merchant context
+     */
+    link?: string;
+    /**
+     * Optional metadata overrides for the sharing page
+     */
+    metadata?: {
+        /**
+         * Logo override for the sharing page header
+         */
+        logo?: string;
+        /**
+         * Link to the homepage of the calling website
+         */
+        homepageLink?: string;
+        /**
+         * The target interaction behind this sharing page
+         */
+        targetInteraction?: InteractionTypeKey;
+        /**
+         * i18n overrides for the sharing page
+         */
+        i18n?: I18nConfig;
+    };
+};
+
+/**
+ * Result of the sharing page display
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+export type DisplaySharingPageResultType = {
+    /**
+     * The action the user took
+     * - "shared": User used the native share dialog
+     * - "copied": User copied the link to clipboard
+     * - "dismissed": User dismissed the sharing page without acting
+     */
+    action: "shared" | "copied" | "dismissed";
+    /**
+     * The install URL for the Frak app
+     * Can be used as a fallback to redirect the user to the install page
+     * from the merchant's top-level page (e.g. via `window.location.href`)
+     */
+    installUrl?: string;
+};

package/src/types/rpc/embedded/index.ts

@@ -9,10 +9,10 @@ import type {
 import type { LoggedOutEmbeddedView } from "./loggedOut";
 
 export type {
+    EmbeddedViewActionReferred,
     EmbeddedViewActionSharing,
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
-    EmbeddedViewActionReferred,
 };
 
 /**

package/src/types/rpc/userReferralStatus.ts

@@ -0,0 +1,20 @@
+/**
+ * User referral status returned by `frak_getUserReferralStatus`.
+ *
+ * Generic referral context for the current user on a merchant.
+ * Used by components like `<frak-post-purchase>` and `<frak-referred-banner>`
+ * to adapt their display based on the user's referral relationship.
+ *
+ * Returns `null` when the user's identity cannot be resolved
+ * (e.g. no clientId and no wallet session).
+ *
+ * @group RPC Schema
+ */
+export type UserReferralStatusType = {
+    /**
+     * Whether the user was referred to this merchant by someone else.
+     *
+     * `true` means a referral link exists where this user is the referee.
+     */
+    isReferred: boolean;
+};