@frak-labs/core-sdk 1.1.3 → 1.1.5-beta.727c2f3f

package/src/actions/referral/processReferral.ts

@@ -53,9 +53,9 @@ function trackArrivalIfValid(
 ): boolean {
     if (isV2Context(frakContext)) {
         trackEvent(client, "user_referred_started", {
-            referrerClientId: frakContext.c,
-            referrerWallet: frakContext.w,
-            walletStatus: walletStatus?.key,
+            referrer_client_id: frakContext.c,
+            referrer_wallet: frakContext.w,
+            wallet_status: walletStatus?.key,
         });
         sendInteraction(client, {
             type: "arrival",
@@ -70,7 +70,7 @@ function trackArrivalIfValid(
     if (isV1Context(frakContext)) {
         trackEvent(client, "user_referred_started", {
             referrer: frakContext.r,
-            walletStatus: walletStatus?.key,
+            wallet_status: walletStatus?.key,
         });
         sendInteraction(client, {
             type: "arrival",

package/src/clients/createIFrameFrakClient.ts

@@ -153,11 +153,11 @@ export function createIFrameFrakClient({
                 if (!payload?.properties) return true;
 
                 // Check if we we got the properties once initialized
-                if (!("sdkVersion" in payload.properties)) {
+                if (!("sdk_version" in payload.properties)) {
                     payload.properties = {
                         ...payload.properties,
-                        sdkVersion: process.env.SDK_VERSION,
-                        userAnonymousClientId: getClientId(),
+                        sdk_version: process.env.SDK_VERSION,
+                        user_anonymous_client_id: getClientId(),
                     };
                 }
 
@@ -165,12 +165,12 @@ export function createIFrameFrakClient({
             },
         });
         openPanel.setGlobalProperties({
-            sdkVersion: process.env.SDK_VERSION,
-            userAnonymousClientId: getClientId(),
+            sdk_version: process.env.SDK_VERSION,
+            user_anonymous_client_id: getClientId(),
         });
         openPanel.init();
         openPanel.track("sdk_initialized", {
-            sdkVersion: process.env.SDK_VERSION,
+            sdk_version: process.env.SDK_VERSION,
         });
 
         // Race the connection against the heartbeat timeout so we can
@@ -398,7 +398,7 @@ async function postConnectionSetup({
             const current = openPanel.global ?? {};
             openPanel.setGlobalProperties({
                 ...current,
-                merchantId: resolved.merchantId,
+                merchant_id: resolved.merchantId,
                 domain: resolved.domain ?? "",
             });
         }

package/src/clients/transports/iframeLifecycleManager.ts

@@ -5,29 +5,13 @@ import {
     isFrakDeepLink,
     triggerDeepLinkWithFallback,
 } from "../../utils/browser/deepLinkWithFallback";
+import { isInAppBrowser, isIOS } from "../../utils/browser/inAppBrowser";
 import { changeIframeVisibility } from "../../utils/iframe/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")
-    );
-})();
+// iOS in-app browsers (Instagram, Facebook) silently swallow server-side 302
+// redirects to custom URL schemes (x-safari-https://) in WKWebView; direct
+// window.location.href assignment works.
+const isIOSInAppBrowser = isIOS && isInAppBrowser;
 
 /** @ignore */
 export type IframeLifecycleManager = {

package/src/config/sdkConfigStore.ts

@@ -89,23 +89,26 @@ function removeCache(): void {
 }
 
 // ---------------------------------------------------------------------------
-// Initialise window-backed config (once per bundle boundary)
+// Initialise window-backed config (lazily, on first access)
 // ---------------------------------------------------------------------------
 
+// Seed `window.__frakSdkConfig` from the localStorage cache. Do NOT call this at
+// module top-level: that side effect contradicts `sideEffects: false` (a bundler
+// may legally drop it) and forces a localStorage read on every consumer at import.
+// It is invoked lazily from `getConfig` instead.
 function initConfig(): void {
     if (!isBrowser) return;
     if (window[GLOBAL_KEY]) return;
     window[GLOBAL_KEY] = readCache() ?? freshEmptyConfig();
 }
 
-initConfig();
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 function getConfig(): SdkResolvedConfig {
     if (!isBrowser) return freshEmptyConfig();
+    initConfig();
     return window[GLOBAL_KEY] ?? freshEmptyConfig();
 }
 

package/src/context/frakContext.test.ts

@@ -584,6 +584,61 @@ describe("FrakContextManager", () => {
         });
     });
 
+    describe("case-insensitive fCtx key", () => {
+        const context: FrakContextV2 = {
+            v: 2,
+            c: "550e8400-e29b-41d4-a716-446655440001",
+            m: "550e8400-e29b-41d4-a716-446655440000",
+            t: 1709654400,
+        };
+
+        it("should parse a lowercased fctx key with an intact value", () => {
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fctx=${compressed}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toEqual(context);
+        });
+
+        it("should parse an uppercased FCTX key with an intact value", () => {
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?FCTX=${compressed}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toEqual(context);
+        });
+
+        it("should prefer the exact-case fCtx key when both variants exist", () => {
+            const canonical = FrakContextManager.compress(context);
+            const url = `https://example.com?fctx=stale&fCtx=${canonical}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toEqual(context);
+        });
+
+        it("should remove a lowercased fctx key", () => {
+            const url = "https://example.com?fctx=abc&keep=me";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).not.toContain("fctx");
+            expect(result).toContain("keep=me");
+        });
+
+        it("should not leave a stale lowercased fctx variant on update", () => {
+            const url = "https://example.com?fctx=stale";
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("fCtx=");
+            expect(result).not.toContain("fctx=stale");
+            expect(FrakContextManager.parse({ url: result! })).toEqual(context);
+        });
+    });
+
     describe("replaceUrl", () => {
         const mockAddress =
             "0x1234567890123456789012345678901234567890" as Address;

package/src/context/frakContext.ts

@@ -6,6 +6,10 @@ import type {
 } from "../types";
 import { isV2Context } from "../types";
 import { base64urlDecode, base64urlEncode } from "../utils/compression/b64";
+import {
+    deleteQueryParamCaseInsensitive,
+    getQueryParamCaseInsensitive,
+} from "../utils/url/queryParams";
 import { addressToBytes, bytesToAddress, isAddress } from "./address";
 import { decodeFrakContextV2, encodeFrakContextV2 } from "./frakContextV2Codec";
 
@@ -77,6 +81,9 @@ function decompress(context?: string): FrakContext | undefined {
 /**
  * Parse a URL to extract the Frak referral context from the `fCtx` query parameter.
  *
+ * The key is matched case-insensitively: some link channels (emails, messaging
+ * apps) lowercase query-param keys in transit, so `fCtx` can arrive as `fctx`.
+ *
  * @param args
  * @param args.url - The URL to parse
  * @returns The parsed FrakContext, or null if absent
@@ -85,7 +92,10 @@ function parse({ url }: { url: string }): FrakContext | null | undefined {
     if (!url) return null;
 
     const urlObj = new URL(url);
-    const frakContext = urlObj.searchParams.get(contextKey);
+    const frakContext = getQueryParamCaseInsensitive(
+        urlObj.searchParams,
+        contextKey
+    );
     if (!frakContext) return null;
 
     return decompress(frakContext);
@@ -165,6 +175,7 @@ function update({
     if (!compressedContext) return null;
 
     const urlObj = new URL(url);
+    deleteQueryParamCaseInsensitive(urlObj.searchParams, contextKey);
     urlObj.searchParams.set(contextKey, compressedContext);
     applyAttributionParams(urlObj, attribution);
     return urlObj.toString();
@@ -178,7 +189,7 @@ function update({
  */
 function remove(url: string): string {
     const urlObj = new URL(url);
-    urlObj.searchParams.delete(contextKey);
+    deleteQueryParamCaseInsensitive(urlObj.searchParams, contextKey);
     return urlObj.toString();
 }
 

package/src/index.ts

@@ -107,11 +107,13 @@ export {
     compressJsonToB64,
     type DeepLinkFallbackOptions,
     decompressJsonFromB64,
+    deleteQueryParamCaseInsensitive,
     type FullSsoParams,
     findIframeInOpener,
     formatAmount,
     generateSsoUrl,
     getCurrencyAmountKey,
+    getQueryParamCaseInsensitive,
     getSupportedCurrency,
     isInAppBrowser,
     isIOS,

package/src/types/rpc/merchantInformation.ts

@@ -12,13 +12,20 @@ export type TokenAmountType = {
 };
 
 /**
- * A tier definition for tiered rewards
+ * A tier definition for tiered rewards — pays either a flat token amount
+ * or a percent of the tier field value
  */
-export type RewardTier = {
-    minValue: number;
-    maxValue?: number;
-    amount: TokenAmountType;
-};
+export type RewardTier =
+    | {
+          minValue: number;
+          maxValue?: number;
+          amount: TokenAmountType;
+      }
+    | {
+          minValue: number;
+          maxValue?: number;
+          percent: number;
+      };
 
 /**
  * Estimated reward amount — discriminated union by payout type

package/src/utils/analytics/events/lifecycle.ts

@@ -6,7 +6,7 @@ export type SdkHandshakeFailureReason =
 
 export type SdkLifecycleEventMap = {
     sdk_initialized: {
-        sdkVersion?: string;
+        sdk_version?: string;
     };
     sdk_iframe_connected: {
         handshake_duration_ms: number;

package/src/utils/analytics/events/referral.ts

@@ -1,9 +1,9 @@
 export type SdkReferralEventMap = {
     user_referred_started: {
         referrer?: string;
-        referrerClientId?: string;
-        referrerWallet?: string;
-        walletStatus?: string;
+        referrer_client_id?: string;
+        referrer_wallet?: string;
+        wallet_status?: string;
     };
     user_referred_completed: {
         status: "success";

package/src/utils/browser/deepLinkWithFallback.ts

@@ -40,7 +40,10 @@ export function isChromiumAndroid(): boolean {
  *
  * Format: intent://path#Intent;scheme=<scheme>;end
  */
-const DEEP_LINK_SCHEME_NAME = DEEP_LINK_SCHEME.replace("://", "");
+const DEEP_LINK_SCHEME_NAME = /* @__PURE__ */ DEEP_LINK_SCHEME.replace(
+    "://",
+    ""
+);
 
 export function toAndroidIntentUrl(deepLink: string): string {
     // Extract everything after the scheme (e.g. "frakwallet://" or "frakwallet-dev://")

package/src/utils/browser/inAppBrowser.ts

@@ -14,7 +14,7 @@ function checkIsIOS(): boolean {
 /**
  * Whether the current device runs iOS (including iPadOS 13+).
  */
-export const isIOS: boolean = checkIsIOS();
+export const isIOS: boolean = /* @__PURE__ */ checkIsIOS();
 
 /**
  * Check if the current device is a mobile device (iOS, iPadOS, Android,
@@ -48,7 +48,7 @@ function checkInAppBrowser(): boolean {
  * Whether the current browser is a social media in-app browser
  * (Instagram, Facebook).
  */
-export const isInAppBrowser: boolean = checkInAppBrowser();
+export const isInAppBrowser: boolean = /* @__PURE__ */ checkInAppBrowser();
 
 /**
  * Redirect to external browser from in-app WebView.

package/src/utils/cache/withCache.ts

@@ -5,20 +5,35 @@ type CacheEntry<TData> = {
     created: number;
 };
 
-/** Global cache for in-flight promises (dedup concurrent calls) */
-const promiseCache = new LruMap<Promise<unknown>>(1024);
-
-/** Global cache for resolved responses (TTL-based) */
-const responseCache = new LruMap<CacheEntry<unknown>>(1024);
-
 /** Default cache time: 30 seconds */
 export const DEFAULT_CACHE_TIME = 30_000;
 
 /** Short negative cache to avoid flooding on transient failures */
 const NEGATIVE_CACHE_TIME = 1_000;
 
-/** Tracks recently failed keys to avoid request floods */
-const failureCache = new LruMap<number>(1024);
+type CacheStore = {
+    /** In-flight promises (dedup concurrent calls) */
+    promiseCache: LruMap<Promise<unknown>>;
+    /** Resolved responses (TTL-based) */
+    responseCache: LruMap<CacheEntry<unknown>>;
+    /** Recently failed keys to avoid request floods */
+    failureCache: LruMap<number>;
+};
+
+// Allocate the three LruMaps lazily on first use rather than at module init.
+// Eager top-level allocation is a side effect at odds with `sideEffects: false`
+// and runs for every consumer that merely imports this module.
+let store: CacheStore | undefined;
+function caches(): CacheStore {
+    if (!store) {
+        store = {
+            promiseCache: new LruMap<Promise<unknown>>(1024),
+            responseCache: new LruMap<CacheEntry<unknown>>(1024),
+            failureCache: new LruMap<number>(1024),
+        };
+    }
+    return store;
+}
 
 type WithCacheOptions = {
     /** The key to cache the data against */
@@ -47,6 +62,7 @@ export async function withCache<TData>(
     fn: () => Promise<TData>,
     { cacheKey, cacheTime = DEFAULT_CACHE_TIME }: WithCacheOptions
 ): Promise<TData> {
+    const { promiseCache, responseCache, failureCache } = caches();
     // Check response cache — return immediately if fresh
     if (cacheTime > 0) {
         const cached = responseCache.get(cacheKey) as
@@ -101,11 +117,13 @@ export function getCache(cacheKey: string) {
     return {
         /** Clear both the pending promise and the cached response */
         clear: () => {
+            const { promiseCache, responseCache } = caches();
             promiseCache.delete(cacheKey);
             responseCache.delete(cacheKey);
         },
         /** Check if a non-expired response exists */
         has: (cacheTime: number = DEFAULT_CACHE_TIME) => {
+            const { responseCache } = caches();
             const cached = responseCache.get(cacheKey);
             if (!cached) return false;
             return Date.now() - cached.created < cacheTime;
@@ -118,7 +136,8 @@ export function getCache(cacheKey: string) {
  * Called automatically when the client is destroyed.
  */
 export function clearAllCache() {
-    promiseCache.clear();
-    responseCache.clear();
-    failureCache.clear();
+    if (!store) return;
+    store.promiseCache.clear();
+    store.responseCache.clear();
+    store.failureCache.clear();
 }

package/src/utils/iframe/iframeHelper.test.ts

@@ -185,6 +185,45 @@ describe("iframeHelper", () => {
 
             expect(mockIframe.style.zIndex).toBe("2000001");
         });
+
+        it("should append #preload=... when config.preload is non-empty", async () => {
+            const config: FrakWalletSdkConfig = {
+                metadata: { name: "Test" },
+                preload: ["sharing"],
+            };
+
+            await createIframe({ config });
+
+            expect(mockIframe.src).toBe(
+                "https://wallet.frak.id/listener?clientId=mock-client-id-for-test#preload=sharing"
+            );
+        });
+
+        it("should join multiple preload options with comma", async () => {
+            const config: FrakWalletSdkConfig = {
+                metadata: { name: "Test" },
+                preload: ["sharing", "modal"],
+            };
+
+            await createIframe({ config });
+
+            expect(mockIframe.src).toBe(
+                "https://wallet.frak.id/listener?clientId=mock-client-id-for-test#preload=sharing,modal"
+            );
+        });
+
+        it("should omit the preload hash when config.preload is an empty array", async () => {
+            const config: FrakWalletSdkConfig = {
+                metadata: { name: "Test" },
+                preload: [],
+            };
+
+            await createIframe({ config });
+
+            expect(mockIframe.src).toBe(
+                "https://wallet.frak.id/listener?clientId=mock-client-id-for-test"
+            );
+        });
     });
 
     describe("changeIframeVisibility", () => {

package/src/utils/iframe/iframeHelper.ts

@@ -1,6 +1,6 @@
 import { getBackendUrl } from "../../config/backendUrl";
 import { getClientId } from "../../config/clientId";
-import type { FrakWalletSdkConfig } from "../../types";
+import type { FrakWalletSdkConfig, ListenerPreloadOption } from "../../types";
 
 /**
  * Base props for the iframe
@@ -64,7 +64,11 @@ export function createIframe({
     preconnect(walletUrl);
     preconnect(getBackendUrl(walletUrl));
 
-    iframe.src = `${walletUrl}/listener?clientId=${encodeURIComponent(clientId)}`;
+    iframe.src = buildListenerUrl({
+        walletUrl,
+        clientId,
+        preload: config?.preload,
+    });
 
     return new Promise((resolve) => {
         iframe.addEventListener("load", () => resolve(iframe));
@@ -72,6 +76,31 @@ export function createIframe({
     });
 }
 
+/**
+ * Build the listener iframe URL.
+ *
+ * Query params:
+ *  - `clientId` — anonymous SDK client identifier used for funnel joining.
+ *
+ * Hash params (consumed by `apps/listener/app/bootstrap.ts#setupPreloadHints`):
+ *  - `preload=modal,sharing` — idle-warms the matching Ring 1 + Ring 2 chunks.
+ *    Skipped entirely when no preload hints are provided so the listener
+ *    doesn't pay for warm-ups that nobody asked for.
+ */
+function buildListenerUrl({
+    walletUrl,
+    clientId,
+    preload,
+}: {
+    walletUrl: string;
+    clientId: string;
+    preload?: ListenerPreloadOption[];
+}): string {
+    const base = `${walletUrl}/listener?clientId=${encodeURIComponent(clientId)}`;
+    if (!preload || preload.length === 0) return base;
+    return `${base}#preload=${preload.join(",")}`;
+}
+
 /**
  * Change the visibility of the given iframe
  * @ignore

package/src/utils/index.ts

@@ -47,3 +47,8 @@ export {
     type FullSsoParams,
     generateSsoUrl,
 } from "./sso/sso";
+// URL query params (case-insensitive key matching)
+export {
+    deleteQueryParamCaseInsensitive,
+    getQueryParamCaseInsensitive,
+} from "./url/queryParams";

package/src/utils/url/queryParams.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import {
+    deleteQueryParamCaseInsensitive,
+    getQueryParamCaseInsensitive,
+} from "./queryParams";
+
+describe("getQueryParamCaseInsensitive", () => {
+    it("reads an exact-case key", () => {
+        const params = new URLSearchParams("frakAction=share");
+        expect(getQueryParamCaseInsensitive(params, "frakAction")).toBe(
+            "share"
+        );
+    });
+
+    it("reads a fully lowercased key (email/browser mangling)", () => {
+        const params = new URLSearchParams("frakaction=share");
+        expect(getQueryParamCaseInsensitive(params, "frakAction")).toBe(
+            "share"
+        );
+    });
+
+    it("reads an uppercased key", () => {
+        const params = new URLSearchParams("FRAKACTION=share");
+        expect(getQueryParamCaseInsensitive(params, "frakAction")).toBe(
+            "share"
+        );
+    });
+
+    it("reads a mixed-case key regardless of the lookup casing", () => {
+        const params = new URLSearchParams("FrAkAcTiOn=share");
+        expect(getQueryParamCaseInsensitive(params, "FRAKACTION")).toBe(
+            "share"
+        );
+    });
+
+    it("returns null when no key matches", () => {
+        const params = new URLSearchParams("other=1");
+        expect(getQueryParamCaseInsensitive(params, "frakAction")).toBeNull();
+    });
+
+    it("prefers the exact-case key over a case-folded duplicate", () => {
+        const params = new URLSearchParams("fctx=stale&fCtx=canonical");
+        expect(getQueryParamCaseInsensitive(params, "fCtx")).toBe("canonical");
+    });
+
+    it("falls back to the first case-folded variant when no exact match", () => {
+        const params = new URLSearchParams("fctx=first&FCTX=second");
+        expect(getQueryParamCaseInsensitive(params, "fCtx")).toBe("first");
+    });
+
+    it("preserves the value casing (only the key is normalized)", () => {
+        const params = new URLSearchParams("placement=Klaviyo-Post-Purchase");
+        expect(getQueryParamCaseInsensitive(params, "PLACEMENT")).toBe(
+            "Klaviyo-Post-Purchase"
+        );
+    });
+});
+
+describe("deleteQueryParamCaseInsensitive", () => {
+    it("deletes an exact-case key", () => {
+        const params = new URLSearchParams("frakAction=share&keep=me");
+        deleteQueryParamCaseInsensitive(params, "frakAction");
+        expect(params.toString()).toBe("keep=me");
+    });
+
+    it("deletes a lowercased key", () => {
+        const params = new URLSearchParams("frakaction=share&keep=me");
+        deleteQueryParamCaseInsensitive(params, "frakAction");
+        expect(params.toString()).toBe("keep=me");
+    });
+
+    it("deletes every case variant of the key", () => {
+        const params = new URLSearchParams(
+            "frakAction=a&frakaction=b&FRAKACTION=c&keep=me"
+        );
+        deleteQueryParamCaseInsensitive(params, "frakAction");
+        expect(params.toString()).toBe("keep=me");
+    });
+
+    it("is a no-op when the key is absent", () => {
+        const params = new URLSearchParams("keep=me");
+        deleteQueryParamCaseInsensitive(params, "frakAction");
+        expect(params.toString()).toBe("keep=me");
+    });
+});

package/src/utils/url/queryParams.ts

@@ -0,0 +1,57 @@
+/**
+ * Case-insensitive helpers for reading URL query parameters.
+ *
+ * Some email tools (Klaviyo, Omnisend, Customer.io …) and a few browsers
+ * lowercase the entire URL before the recipient opens it, so a mixed-case key
+ * authored as `frakAction` or `fCtx` can arrive as `frakaction` / `fctx`. A
+ * plain `searchParams.get("frakAction")` would miss it. Matching the key
+ * ignoring case keeps UI-triggering and referral params working regardless of
+ * how the link was mangled in transit.
+ *
+ * Note: only the key is normalised. An encoded value (base64url, tokens) is not
+ * recoverable if the same channel also lowercased the value itself.
+ */
+
+/**
+ * Read a query parameter, matching its key case-insensitively.
+ *
+ * An exact-case match wins when present, so a canonical link is never shadowed
+ * by a mangled duplicate (`?fctx=stale&fCtx=real` resolves to `real`). Only when
+ * the exact key is absent do we scan for a case-folded variant.
+ *
+ * @returns the param value, or `null` when no key matches.
+ */
+export function getQueryParamCaseInsensitive(
+    searchParams: URLSearchParams,
+    key: string
+): string | null {
+    const exact = searchParams.get(key);
+    if (exact !== null) return exact;
+
+    const target = key.toLowerCase();
+    for (const [paramKey, value] of searchParams) {
+        if (paramKey.toLowerCase() === target) {
+            return value;
+        }
+    }
+    return null;
+}
+
+/**
+ * Delete every query parameter whose key matches `key` case-insensitively.
+ *
+ * Keys are collected before deletion because mutating a `URLSearchParams`
+ * while iterating it skips entries.
+ */
+export function deleteQueryParamCaseInsensitive(
+    searchParams: URLSearchParams,
+    key: string
+): void {
+    const target = key.toLowerCase();
+    const matchingKeys = [...searchParams.keys()].filter(
+        (paramKey) => paramKey.toLowerCase() === target
+    );
+    for (const paramKey of matchingKeys) {
+        searchParams.delete(paramKey);
+    }
+}