@frak-labs/core-sdk 0.1.1 → 0.2.0-beta.7898df5b

package/src/clients/transports/iframeLifecycleManager.ts

@@ -1,22 +1,183 @@
 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,
+    triggerDeepLinkWithFallback,
+} from "../../utils/deepLinkWithFallback";
 import { changeIframeVisibility } from "../../utils/iframeHelper";
 
+/**
+ * Detect iOS in-app browsers (Instagram, Facebook) where server-side
+ * 302 redirects to custom URL schemes (x-safari-https://) are silently
+ * swallowed by WKWebView. Direct window.location.href assignment works.
+ */
+const isIOSInAppBrowser = (() => {
+    if (typeof navigator === "undefined") return false;
+    const ua = navigator.userAgent;
+    // Standard iOS or iPadOS 13+ (reports as Macintosh with touch)
+    const isIOS =
+        /iPhone|iPad|iPod/i.test(ua) ||
+        (/Macintosh/i.test(ua) && navigator.maxTouchPoints > 1);
+    if (!isIOS) return false;
+    const lower = ua.toLowerCase();
+    return (
+        lower.includes("instagram") ||
+        lower.includes("fban") ||
+        lower.includes("fbav") ||
+        lower.includes("facebook")
+    );
+})();
+
 /** @ignore */
 export type IframeLifecycleManager = {
     isConnected: Promise<boolean>;
     handleEvent: (messageEvent: FrakLifecycleEvent) => Promise<void>;
 };
 
+/**
+ * Handle backup storage
+ */
+function handleBackup(backup: string | undefined): void {
+    if (backup) {
+        localStorage.setItem(BACKUP_KEY, backup);
+    } else {
+        localStorage.removeItem(BACKUP_KEY);
+    }
+}
+
+/**
+ * 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
+ */
+function computeRedirectUrl(
+    baseRedirectUrl: string,
+    mergeToken?: string
+): string {
+    try {
+        const redirectUrl = new URL(baseRedirectUrl);
+        if (!redirectUrl.searchParams.has("u")) {
+            return baseRedirectUrl;
+        }
+
+        redirectUrl.searchParams.delete("u");
+        redirectUrl.searchParams.append("u", window.location.href);
+
+        if (mergeToken) {
+            redirectUrl.searchParams.append("fmt", mergeToken);
+        }
+
+        return redirectUrl.toString();
+    } catch {
+        return baseRedirectUrl;
+    }
+}
+
+/**
+ * Redirect current page to Safari via x-safari-https:// scheme.
+ * Used on iOS in-app browsers where backend 302 → custom scheme fails.
+ */
+function redirectToSafari(mergeToken?: string) {
+    const url = new URL(window.location.href);
+    if (mergeToken) {
+        url.searchParams.set("fmt", mergeToken);
+    }
+    const scheme =
+        url.protocol === "http:" ? "x-safari-http" : "x-safari-https";
+    window.location.href = `${scheme}://${url.host}${url.pathname}${url.search}${url.hash}`;
+}
+
+/**
+ * Check if this is a social/in-app-browser escape redirect (contains /common/social)
+ */
+function isSocialRedirect(url: string): boolean {
+    return url.includes("/common/social");
+}
+
+/**
+ * Handle redirect with deep link fallback
+ */
+function handleRedirect(
+    iframe: HTMLIFrameElement,
+    baseRedirectUrl: string,
+    targetOrigin: string,
+    mergeToken?: string
+): void {
+    if (isFrakDeepLink(baseRedirectUrl)) {
+        const finalUrl = computeRedirectUrl(baseRedirectUrl, mergeToken);
+        triggerDeepLinkWithFallback(finalUrl, {
+            onFallback: () => {
+                iframe.contentWindow?.postMessage(
+                    {
+                        clientLifecycle: "deep-link-failed",
+                        data: { originalUrl: finalUrl },
+                    },
+                    targetOrigin
+                );
+            },
+        });
+    } else if (isIOSInAppBrowser && isSocialRedirect(baseRedirectUrl)) {
+        // iOS WKWebView silently swallows 302 redirects to custom URL
+        // schemes — bypass the server redirect entirely
+        redirectToSafari(mergeToken);
+    } else {
+        const finalUrl = computeRedirectUrl(baseRedirectUrl, mergeToken);
+        window.location.href = finalUrl;
+    }
+}
+
 /**
  * Create a new iframe lifecycle handler
+ * @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>();
@@ -34,11 +195,7 @@ export function createIFrameLifecycleManager({
                 break;
             // Perform a frak backup
             case "do-backup":
-                if (data.backup) {
-                    localStorage.setItem(BACKUP_KEY, data.backup);
-                } else {
-                    localStorage.removeItem(BACKUP_KEY);
-                }
+                handleBackup(data.backup);
                 break;
             // Remove frak backup
             case "remove-backup":
@@ -47,39 +204,21 @@ export function createIFrameLifecycleManager({
             // Change iframe visibility
             case "show":
             case "hide":
-                changeIframeVisibility({
-                    iframe,
-                    isVisible: event === "show",
-                });
+                changeIframeVisibility({ iframe, isVisible: event === "show" });
                 break;
             // Handshake handling
-            case "handshake": {
-                iframe.contentWindow?.postMessage(
-                    {
-                        clientLifecycle: "handshake-response",
-                        data: {
-                            token: data.token,
-                            currentUrl: window.location.href,
-                        },
-                    },
-                    "*"
-                );
+            case "handshake":
+                handleHandshake(iframe, data.token, targetOrigin, configDomain);
                 break;
-            }
             // Redirect handling
-            case "redirect": {
-                const redirectUrl = new URL(data.baseRedirectUrl);
-
-                // If we got a u append the current location dynamicly
-                if (redirectUrl.searchParams.has("u")) {
-                    redirectUrl.searchParams.delete("u");
-                    redirectUrl.searchParams.append("u", window.location.href);
-                    window.location.href = redirectUrl.toString();
-                } else {
-                    window.location.href = data.baseRedirectUrl;
-                }
+            case "redirect":
+                handleRedirect(
+                    iframe,
+                    data.baseRedirectUrl,
+                    targetOrigin,
+                    data.mergeToken
+                );
                 break;
-            }
         }
     };
 

package/src/constants/interactionTypes.ts

@@ -1,44 +1,15 @@
 /**
- * The final keys for each interaction types (e.g. `openArticle`) -> interaction type
+ * The supported interaction type keys
+ *
+ * - `referral` - User arrived via a referral link
+ * - `create_referral_link` - User created/shared a referral link
+ * - `purchase` - User completed a purchase
+ * - `custom.${string}` - Custom interaction type defined per campaign
+ *
  * @inline
  */
-export type InteractionTypesKey = {
-    [K in keyof typeof interactionTypes]: keyof (typeof interactionTypes)[K];
-}[keyof typeof interactionTypes];
-
-/**
- * The keys for each interaction types (e.g. `press.openArticle`) -> category_type.interaction_type
- * @inline
- */
-export type FullInteractionTypesKey = {
-    [Category in keyof typeof interactionTypes]: `${Category & string}.${keyof (typeof interactionTypes)[Category] & string}`;
-}[keyof typeof interactionTypes];
-
-/**
- * Each interactions types according to the product types
- */
-export const interactionTypes = {
-    press: {
-        openArticle: "0xc0a24ffb",
-        readArticle: "0xd5bd0fbe",
-    },
-    dapp: {
-        proofVerifiableStorageUpdate: "0x2ab2aeef",
-        callableVerifiableStorageUpdate: "0xa07da986",
-    },
-    webshop: {
-        open: "0xb311798f",
-    },
-    referral: {
-        referred: "0x010cc3b9",
-        createLink: "0xb2c0f17c",
-    },
-    purchase: {
-        started: "0xd87e90c3",
-        completed: "0x8403aeb4",
-        unsafeCompleted: "0x4d5b14e0",
-    },
-    retail: {
-        customerMeeting: "0x74489004",
-    },
-} as const;
+export type InteractionTypeKey =
+    | "referral"
+    | "create_referral_link"
+    | "purchase"
+    | `custom.${string}`;

package/src/index.ts

@@ -6,18 +6,10 @@ export {
     DebugInfoGatherer,
     setupClient,
 } from "./clients";
-export {
-    type FullInteractionTypesKey,
-    type InteractionTypesKey,
-    interactionTypes,
-} from "./constants/interactionTypes";
+
+export type { InteractionTypeKey } from "./constants/interactionTypes";
 export { type LocalesKey, locales } from "./constants/locales";
-// Constants
-export {
-    type ProductTypesKey,
-    productTypes,
-    productTypesMask,
-} from "./constants/productTypes";
+
 // Types
 export type {
     ClientLifecycleEvent,
@@ -29,16 +21,19 @@ export type {
     DisplayModalParamsType,
     EmbeddedViewActionReferred,
     EmbeddedViewActionSharing,
+    EstimatedReward,
     FinalActionType,
     FinalModalStepType,
     // Client
     FrakClient,
     // Utils
     FrakContext,
+    FrakContextV1,
+    FrakContextV2,
     FrakLifecycleEvent,
     // Config
     FrakWalletSdkConfig,
-    GetProductInformationReturnType,
+    GetMerchantInformationReturnType,
     HashProtectedData,
     I18nConfig,
     IFrameLifecycleEvent,
@@ -59,15 +54,13 @@ export type {
     ModalStepMetadata,
     // RPC Modal generics
     ModalStepTypes,
-    OpenInteractionSessionModalStepType,
-    OpenInteractionSessionReturnType,
     OpenSsoParamsType,
     OpenSsoReturnType,
-    PreparedInteraction,
     PrepareSsoParamsType,
     PrepareSsoReturnType,
+    RewardTier,
+    // RPC Interaction
     SendInteractionParamsType,
-    SendInteractionReturnType,
     SendTransactionModalStepType,
     SendTransactionReturnType,
     SendTransactionTxType,
@@ -76,9 +69,14 @@ export type {
     SiweAuthenticationParams,
     SsoMetadata,
     TokenAmountType,
+    // Tracking
+    TrackArrivalParams,
+    TrackArrivalResult,
+    UtmParams,
     // Rpc
     WalletStatusReturnType,
 } from "./types";
+export { isV1Context, isV2Context } from "./types";
 // Utils
 export {
     type AppSpecificSsoMetadata,
@@ -86,16 +84,29 @@ export {
     base64urlEncode,
     baseIframeProps,
     type CompressedSsoData,
+    clearMerchantIdCache,
     compressJsonToB64,
     createIframe,
+    DEEP_LINK_SCHEME,
+    type DeepLinkFallbackOptions,
     decompressJsonFromB64,
     FrakContextManager,
+    type FrakEvent,
     type FullSsoParams,
+    fetchMerchantId,
     findIframeInOpener,
     formatAmount,
     generateSsoUrl,
+    getBackendUrl,
+    getClientId,
     getCurrencyAmountKey,
     getSupportedCurrency,
     getSupportedLocale,
+    isChromiumAndroid,
+    isFrakDeepLink,
+    resolveMerchantId,
+    toAndroidIntentUrl,
     trackEvent,
+    triggerDeepLinkWithFallback,
 } from "./utils";
+export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/types/config.ts

@@ -28,6 +28,12 @@ export type FrakWalletSdkConfig = {
          * Your application name (will be displayed in a few modals and in SSO)
          */
         name: string;
+        /**
+         * Your merchant ID from the Frak dashboard (UUID format)
+         * Used for referral tracking and analytics
+         * If not provided, will be auto-fetched from the backend using your domain
+         */
+        merchantId?: string;
         /**
          * Language to display in the modal
          * If undefined, will default to the browser language

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,7 +15,9 @@ 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,
@@ -37,18 +39,18 @@ export type {
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
 } from "./rpc/embedded";
+export type { SendInteractionParamsType } from "./rpc/interaction";
 export type {
-    PreparedInteraction,
-    SendInteractionParamsType,
-    SendInteractionReturnType,
-} from "./rpc/interaction";
+    EstimatedReward,
+    GetMerchantInformationReturnType,
+    RewardTier,
+    TokenAmountType,
+} from "./rpc/merchantInformation";
 export type {
     FinalActionType,
     FinalModalStepType,
     LoginModalStepType,
     ModalStepMetadata,
-    OpenInteractionSessionModalStepType,
-    OpenInteractionSessionReturnType,
     SendTransactionModalStepType,
     SendTransactionReturnType,
     SendTransactionTxType,
@@ -56,10 +58,6 @@ export type {
     SiweAuthenticateReturnType,
     SiweAuthenticationParams,
 } from "./rpc/modal";
-export type {
-    GetProductInformationReturnType,
-    TokenAmountType,
-} from "./rpc/productInformation";
 export type {
     OpenSsoParamsType,
     OpenSsoReturnType,
@@ -68,4 +66,10 @@ export type {
     SsoMetadata,
 } from "./rpc/sso";
 export type { WalletStatusReturnType } from "./rpc/walletStatus";
+// Tracking
+export type {
+    TrackArrivalParams,
+    TrackArrivalResult,
+    UtmParams,
+} from "./tracking";
 export type { FrakLifecycleEvent, IFrameTransport } from "./transport";

package/src/types/lifecycle/client.ts

@@ -10,7 +10,8 @@ export type ClientLifecycleEvent =
     | RestoreBackupEvent
     | HearbeatEvent
     | HandshakeResponse
-    | SsoRedirectCompleteEvent;
+    | SsoRedirectCompleteEvent
+    | DeepLinkFailedEvent;
 
 type CustomCssEvent = {
     clientLifecycle: "modal-css";
@@ -37,6 +38,23 @@ type HandshakeResponse = {
     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;
     };
 };
 
@@ -44,3 +62,8 @@ type SsoRedirectCompleteEvent = {
     clientLifecycle: "sso-redirect-complete";
     data: { compressed: string };
 };
+
+type DeepLinkFailedEvent = {
+    clientLifecycle: "deep-link-failed";
+    data: { originalUrl: string };
+};

package/src/types/lifecycle/iframe.ts

@@ -31,5 +31,11 @@ type RedirectRequestEvent = {
          *  If it contain a query param `u`, the client need will suffix the current url to the base url
          */
         baseRedirectUrl: string;
+        /**
+         * Optional merge token for anonymous identity merging
+         * When provided, appended as ?fmt= query parameter to the final redirect URL
+         * Used when redirecting out of social browsers to preserve identity across contexts
+         */
+        mergeToken?: string;
     };
 };

package/src/types/rpc/displayModal.ts

@@ -1,9 +1,8 @@
-import type { FullInteractionTypesKey } from "../../constants/interactionTypes";
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
 import type { I18nConfig } from "../config";
 import type {
     FinalModalStepType,
     LoginModalStepType,
-    OpenInteractionSessionModalStepType,
     SendTransactionModalStepType,
     SiweAuthenticateModalStepType,
 } from "./modal";
@@ -16,7 +15,6 @@ export type ModalStepTypes =
     | LoginModalStepType
     | SiweAuthenticateModalStepType
     | SendTransactionModalStepType
-    | OpenInteractionSessionModalStepType
     | FinalModalStepType;
 
 /**
@@ -54,7 +52,7 @@ export type ModalRpcMetadata = {
         title?: string;
         icon?: string;
     };
-    targetInteraction?: FullInteractionTypesKey;
+    targetInteraction?: InteractionTypeKey;
     /**
      * Some i18n override for the displayed modal (i.e. update the displayed text only for this modal)
      */

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

@@ -1,5 +1,5 @@
 import type { Address } from "viem";
-import type { FullInteractionTypesKey } from "../../../constants/interactionTypes";
+import type { InteractionTypeKey } from "../../../constants/interactionTypes";
 import type { I18nConfig } from "../../config";
 import type {
     EmbeddedViewActionReferred,
@@ -46,7 +46,7 @@ export type DisplayEmbeddedWalletParamsType = {
         /**
          * The target interaction behind this modal
          */
-        targetInteraction?: FullInteractionTypesKey;
+        targetInteraction?: InteractionTypeKey;
         /**
          * The position of the component
          */