@frak-labs/core-sdk 1.0.2-beta.64c76510 → 1.0.2-beta.75bb63ae

package/src/context/address.ts

@@ -0,0 +1,76 @@
+import type { Address } from "viem";
+
+/**
+ * Address utilities — minimal, dependency-free replacements for the subset of
+ * `viem` helpers we used to import. Keeping these in-house lets the SDK ship
+ * without pulling viem's checksum/keccak/error chain into the bundle.
+ *
+ * Scope is intentionally narrow:
+ *  - `isAddress`: shape-only validation (no EIP-55 checksum)
+ *  - `areAddressesEqual`: case-insensitive equality
+ *  - `addressToBytes` / `bytesToAddress`: fixed 20-byte conversion
+ */
+
+/** Matches a 0x-prefixed 40-char hex string regardless of case. */
+const ADDRESS_REGEX = /^0x[a-fA-F0-9]{40}$/;
+
+/**
+ * Check whether a value is a syntactically valid Ethereum address.
+ *
+ * This intentionally skips EIP-55 checksum validation: the SDK never produces
+ * checksum-cased payloads, and downstream consumers (wallet, indexer) treat
+ * addresses case-insensitively. Avoiding the checksum path drops keccak256 +
+ * @noble/hashes from the bundle.
+ */
+export function isAddress(value: unknown): value is Address {
+    return typeof value === "string" && ADDRESS_REGEX.test(value);
+}
+
+/**
+ * Case-insensitive equality check for two Ethereum addresses.
+ *
+ * Both inputs are assumed to be syntactically valid addresses; callers that
+ * receive untrusted input should validate via {@link isAddress} first.
+ */
+export function areAddressesEqual(a: Address, b: Address): boolean {
+    return a.toLowerCase() === b.toLowerCase();
+}
+
+/**
+ * Decode a 20-byte Ethereum address into a fixed-size Uint8Array(20).
+ *
+ * Throws when the input is not exactly `0x` + 40 hex chars — callers wrap
+ * the call in try/catch (see {@link FrakContextManager.compress}) so any
+ * malformed input degrades to a graceful undefined return.
+ */
+export function addressToBytes(address: Address): Uint8Array {
+    const bytes = new Uint8Array(20);
+    for (let i = 0; i < 20; i++) {
+        const byte = Number.parseInt(
+            address.substring(2 + i * 2, 4 + i * 2),
+            16
+        );
+        if (Number.isNaN(byte)) {
+            throw new Error(`Invalid address: ${address}`);
+        }
+        bytes[i] = byte;
+    }
+    return bytes;
+}
+
+/** Lookup table avoids `padStart` overhead in the hot encode loop. */
+const HEX_BYTE = /*#__PURE__*/ Array.from({ length: 256 }, (_, i) =>
+    i.toString(16).padStart(2, "0")
+);
+
+/**
+ * Encode a 20-byte Uint8Array (or a 20-byte subarray view) into a lowercase
+ * hex Ethereum address. The caller MUST guarantee `bytes.length === 20`.
+ */
+export function bytesToAddress(bytes: Uint8Array): Address {
+    let out = "0x";
+    for (let i = 0; i < 20; i++) {
+        out += HEX_BYTE[bytes[i]];
+    }
+    return out as Address;
+}

package/src/{utils/FrakContext.test.ts → context/frakContext.test.ts}

@@ -9,7 +9,7 @@ import {
     vi,
 } from "../../tests/vitest-fixtures";
 import type { FrakContextV1, FrakContextV2 } from "../types";
-import { FrakContextManager } from "./FrakContext";
+import { FrakContextManager } from "./frakContext";
 
 describe("FrakContextManager", () => {
     let consoleErrorSpy: any;
@@ -144,7 +144,9 @@ describe("FrakContextManager", () => {
                 const { encodeFrakContextV2 } = await import(
                     "./frakContextV2Codec"
                 );
-                const { base64urlEncode } = await import("./compression/b64");
+                const { base64urlEncode } = await import(
+                    "../utils/compression/b64"
+                );
                 const encoded = encodeFrakContextV2(v2Context);
                 expect(encoded).toBeDefined();
                 const tampered = new Uint8Array(encoded as Uint8Array);

package/src/{utils/FrakContext.ts → context/frakContext.ts}

@@ -1,4 +1,3 @@
-import { type Address, bytesToHex, hexToBytes, isAddress } from "viem";
 import type {
     AttributionParams,
     FrakContext,
@@ -6,7 +5,8 @@ import type {
     FrakContextV2,
 } from "../types";
 import { isV2Context } from "../types";
-import { base64urlDecode, base64urlEncode } from "./compression/b64";
+import { base64urlDecode, base64urlEncode } from "../utils/compression/b64";
+import { addressToBytes, bytesToAddress, isAddress } from "./address";
 import { decodeFrakContextV2, encodeFrakContextV2 } from "./frakContextV2Codec";
 
 /**
@@ -34,7 +34,7 @@ function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
         }
 
         // V1 legacy: compress wallet address as raw bytes
-        const bytes = hexToBytes(context.r);
+        const bytes = addressToBytes(context.r);
         return base64urlEncode(bytes);
     } catch (e) {
         console.error("Error compressing Frak context", { e, context });
@@ -64,7 +64,7 @@ function decompress(context?: string): FrakContext | undefined {
             return undefined;
         }
 
-        const hex = bytesToHex(bytes, { size: 20 }) as Address;
+        const hex = bytesToAddress(bytes);
         if (isAddress(hex)) {
             return { r: hex };
         }

package/src/{utils → context}/frakContextV2Codec.test.ts

@@ -1,7 +1,7 @@
 import type { Address } from "viem";
 import { describe, expect, it } from "../../tests/vitest-fixtures";
 import type { FrakContextV2 } from "../types";
-import { base64urlEncode } from "./compression/b64";
+import { base64urlEncode } from "../utils/compression/b64";
 import {
     decodeFrakContextV2,
     encodeFrakContextV2,

package/src/{utils → context}/frakContextV2Codec.ts

@@ -28,8 +28,9 @@
  *
  * @ignore
  */
-import { type Address, bytesToHex, hexToBytes, isAddress } from "viem";
+import type { Address } from "viem";
 import type { FrakContextV2 } from "../types";
+import { addressToBytes, bytesToAddress, isAddress } from "./address";
 
 const VERSION_V2 = 0x02;
 const VERSION_MASK = 0x0f;
@@ -111,7 +112,7 @@ export function encodeFrakContextV2(ctx: FrakContextV2): Uint8Array | null {
     }
 
     if (hasW) {
-        buf.set(hexToBytes(ctx.w as Address), offset);
+        buf.set(addressToBytes(ctx.w as Address), offset);
         offset += ADDRESS_BYTES;
     }
 
@@ -165,10 +166,9 @@ export function decodeFrakContextV2(buf: Uint8Array): FrakContextV2 | null {
     }
 
     if (hasW) {
-        const walletHex = bytesToHex(
-            buf.subarray(offset, offset + ADDRESS_BYTES),
-            { size: ADDRESS_BYTES }
-        ) as Address;
+        const walletHex = bytesToAddress(
+            buf.subarray(offset, offset + ADDRESS_BYTES)
+        );
         if (!isAddress(walletHex)) return null;
         out.w = walletHex;
         offset += ADDRESS_BYTES;

package/src/context/index.ts

@@ -0,0 +1,6 @@
+export { areAddressesEqual } from "./address";
+export { FrakContextManager } from "./frakContext";
+export {
+    type MergeAttributionInput,
+    mergeAttribution,
+} from "./mergeAttribution";

package/src/index.ts

@@ -1,15 +1,22 @@
 // Clients
 
 export { ssoPopupFeatures, ssoPopupName } from "./actions/openSso";
+export { createIFrameFrakClient, setupClient } from "./clients";
+// Config (reactive merchant config + identity)
 export {
-    createIFrameFrakClient,
-    DebugInfoGatherer,
-    setupClient,
-} from "./clients";
-
+    getBackendUrl,
+    getClientId,
+    sdkConfigStore,
+} from "./config";
+// Constants
+export { DEEP_LINK_SCHEME } from "./constants";
 export type { InteractionTypeKey } from "./constants/interactionTypes";
-export { type LocalesKey, locales } from "./constants/locales";
-
+// Context (FrakContext URL codec + attribution merge)
+export {
+    FrakContextManager,
+    type MergeAttributionInput,
+    mergeAttribution,
+} from "./context";
 // Types
 export type {
     AttributionDefaults,
@@ -48,6 +55,7 @@ export type {
     // Compression
     KeyProvider,
     Language,
+    ListenerPreloadOption,
     LocalizedI18nConfig,
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
@@ -87,7 +95,7 @@ export type {
     UtmParams,
     WalletStatusReturnType,
 } from "./types";
-export { isV1Context, isV2Context } from "./types";
+
 // Utils
 export {
     type AppSpecificSsoMetadata,
@@ -97,30 +105,18 @@ export {
     type CompressedSsoData,
     clearAllCache,
     compressJsonToB64,
-    createIframe,
-    DEEP_LINK_SCHEME,
     type DeepLinkFallbackOptions,
     decompressJsonFromB64,
-    FrakContextManager,
     type FullSsoParams,
     findIframeInOpener,
     formatAmount,
     generateSsoUrl,
-    getBackendUrl,
-    getCache,
-    getClientId,
     getCurrencyAmountKey,
     getSupportedCurrency,
-    getSupportedLocale,
-    isChromiumAndroid,
-    isFrakDeepLink,
     isInAppBrowser,
     isIOS,
-    type MergeAttributionInput,
-    mergeAttribution,
+    isMobile,
     redirectToExternalBrowser,
-    sdkConfigStore,
-    toAndroidIntentUrl,
     trackEvent,
     triggerDeepLinkWithFallback,
     withCache,
@@ -129,4 +125,3 @@ export type {
     SdkEventMap,
     SdkHandshakeFailureReason,
 } from "./utils/analytics";
-export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/stubs/rrweb.ts

@@ -1,8 +1,12 @@
 /**
- * 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
+ * Stub for rrweb. The IIFE/CDN bundles inline every dependency
+ * (alwaysBundle catch-all), which would also pull in rrweb via the dynamic
+ * `replay` chunk loaded by @openpanel/web. Session replay is disabled in our
+ * SDK, so we alias rrweb to a noop record() to keep the CDN bundle small.
+ *
+ * The NPM ESM/CJS builds don't need this alias: @openpanel/web 1.4.1+ loads
+ * rrweb through a dynamic `import("./replay-…")`, so consumers' bundlers can
+ * tree-shake / code-split it on their own.
  */
 export function record() {
     return () => {};

package/src/types/client.ts

@@ -7,8 +7,5 @@ import type { IFrameTransport } from "./transport";
  */
 export type FrakClient = {
     config: FrakWalletSdkConfig;
-    debugInfo: {
-        formatDebugInfo: (error: Error | unknown | string) => string;
-    };
     openPanel?: OpenPanel;
 } & IFrameTransport;

package/src/types/config.ts

@@ -87,6 +87,11 @@ export type FrakWalletSdkConfig = {
      * excluded — it is per-content/per-product, never a merchant-wide default.
      */
     attribution?: AttributionDefaults;
+    /**
+     * Preload specific UI views inside the listener iframe for better UX.
+     * Default: ["sharing"]
+     */
+    preload?: ListenerPreloadOption[];
 };
 
 /**
@@ -126,6 +131,12 @@ export type I18nConfig =
     | Record<Language, LocalizedI18nConfig>
     | LocalizedI18nConfig;
 
+/**
+ * Options for preloading the listener UI
+ * @category Config
+ */
+export type ListenerPreloadOption = "modal" | "sharing";
+
 /**
  * A localized i18n config (inline objects only — URL-based i18n removed)
  * @category Config

package/src/types/index.ts

@@ -12,6 +12,7 @@ export type {
     FrakWalletSdkConfig,
     I18nConfig,
     Language,
+    ListenerPreloadOption,
     LocalizedI18nConfig,
 } from "./config";
 // Utils

package/src/utils/{deepLinkWithFallback.ts → browser/deepLinkWithFallback.ts}

@@ -1,4 +1,4 @@
-import { DEEP_LINK_SCHEME } from "./constants";
+import { DEEP_LINK_SCHEME } from "../../constants";
 
 /**
  * Options for deep link with fallback

package/src/utils/{inAppBrowser.ts → browser/inAppBrowser.ts}

@@ -16,6 +16,19 @@ function checkIsIOS(): boolean {
  */
 export const isIOS: boolean = checkIsIOS();
 
+/**
+ * Check if the current device is a mobile device (iOS, iPadOS, Android,
+ * webOS, BlackBerry, IEMobile, Opera Mini). Reuses {@link isIOS} so the
+ * iPadOS-13+ Macintosh heuristic stays in one place.
+ */
+export function isMobile(): boolean {
+    if (typeof navigator === "undefined") return false;
+    if (isIOS) return true;
+    return /Android|webOS|BlackBerry|IEMobile|Opera Mini/i.test(
+        navigator.userAgent
+    );
+}
+
 /**
  * Check if the current browser is a social media in-app browser
  * (Instagram, Facebook WebView).

package/src/utils/browser/index.ts

@@ -0,0 +1,13 @@
+export {
+    type DeepLinkFallbackOptions,
+    isChromiumAndroid,
+    isFrakDeepLink,
+    toAndroidIntentUrl,
+    triggerDeepLinkWithFallback,
+} from "./deepLinkWithFallback";
+export {
+    isInAppBrowser,
+    isIOS,
+    isMobile,
+    redirectToExternalBrowser,
+} from "./inAppBrowser";

package/src/utils/{formatAmount.test.ts → format/formatAmount.test.ts}

@@ -3,7 +3,7 @@
  * Tests currency formatting with proper locale support
  */
 
-import { describe, expect, it } from "../../tests/vitest-fixtures";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
 import { formatAmount } from "./formatAmount";
 
 describe("formatAmount", () => {

package/src/utils/{formatAmount.ts → format/formatAmount.ts}

@@ -1,4 +1,4 @@
-import type { Currency } from "../types";
+import type { Currency } from "../../types";
 import { getSupportedCurrency } from "./getSupportedCurrency";
 import { getSupportedLocale } from "./getSupportedLocale";
 

package/src/utils/{getCurrencyAmountKey.test.ts → format/getCurrencyAmountKey.test.ts}

@@ -3,8 +3,8 @@
  * Tests currency amount key generation
  */
 
-import { describe, expect, it } from "../../tests/vitest-fixtures";
-import type { Currency } from "../types";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import type { Currency } from "../../types";
 import { getCurrencyAmountKey } from "./getCurrencyAmountKey";
 
 describe("getCurrencyAmountKey", () => {

package/src/utils/{getCurrencyAmountKey.ts → format/getCurrencyAmountKey.ts}

@@ -1,4 +1,4 @@
-import type { Currency, TokenAmountType } from "../types";
+import type { Currency, TokenAmountType } from "../../types";
 
 /**
  * Get the currency amount key for a given currency

package/src/utils/{getSupportedCurrency.test.ts → format/getSupportedCurrency.test.ts}

@@ -3,8 +3,8 @@
  * Tests currency validation and fallback behavior
  */
 
-import { describe, expect, it } from "../../tests/vitest-fixtures";
-import type { Currency } from "../types";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import type { Currency } from "../../types";
 import { getSupportedCurrency } from "./getSupportedCurrency";
 
 describe("getSupportedCurrency", () => {

package/src/utils/{getSupportedCurrency.ts → format/getSupportedCurrency.ts}

@@ -1,5 +1,5 @@
-import { locales } from "../constants/locales";
-import type { Currency } from "../types";
+import { locales } from "../../constants/locales";
+import type { Currency } from "../../types";
 
 /**
  * Get the supported currency for a given currency

package/src/utils/{getSupportedLocale.test.ts → format/getSupportedLocale.test.ts}

@@ -3,9 +3,9 @@
  * Tests locale resolution from currency
  */
 
-import { describe, expect, it } from "../../tests/vitest-fixtures";
-import { locales } from "../constants/locales";
-import type { Currency } from "../types";
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import { locales } from "../../constants/locales";
+import type { Currency } from "../../types";
 import { getSupportedLocale } from "./getSupportedLocale";
 
 describe("getSupportedLocale", () => {

package/src/utils/{getSupportedLocale.ts → format/getSupportedLocale.ts}

@@ -1,5 +1,5 @@
-import { type LocalesKey, locales } from "../constants/locales";
-import type { Currency } from "../types";
+import { type LocalesKey, locales } from "../../constants/locales";
+import type { Currency } from "../../types";
 
 /**
  * Get the supported locale for a given currency

package/src/utils/format/index.ts

@@ -0,0 +1,4 @@
+export { formatAmount } from "./formatAmount";
+export { getCurrencyAmountKey } from "./getCurrencyAmountKey";
+export { getSupportedCurrency } from "./getSupportedCurrency";
+export { getSupportedLocale } from "./getSupportedLocale";

package/src/utils/{iframeHelper.test.ts → iframe/iframeHelper.test.ts}

@@ -1,6 +1,6 @@
 import { vi } from "vitest";
 
-vi.mock("./clientId", () => ({
+vi.mock("../../config/clientId", () => ({
     getClientId: vi.fn(() => "mock-client-id-for-test"),
 }));
 
@@ -15,8 +15,8 @@ import {
     describe,
     expect,
     it,
-} from "../../tests/vitest-fixtures";
-import type { FrakWalletSdkConfig } from "../types";
+} from "../../../tests/vitest-fixtures";
+import type { FrakWalletSdkConfig } from "../../types";
 import {
     baseIframeProps,
     changeIframeVisibility,

package/src/utils/{iframeHelper.ts → iframe/iframeHelper.ts}

@@ -1,6 +1,6 @@
-import type { FrakWalletSdkConfig } from "../types";
-import { getBackendUrl } from "./backendUrl";
-import { getClientId } from "./clientId";
+import { getBackendUrl } from "../../config/backendUrl";
+import { getClientId } from "../../config/clientId";
+import type { FrakWalletSdkConfig } from "../../types";
 
 /**
  * Base props for the iframe

package/src/utils/iframe/index.ts

@@ -0,0 +1,6 @@
+export {
+    baseIframeProps,
+    changeIframeVisibility,
+    createIframe,
+    findIframeInOpener,
+} from "./iframeHelper";

package/src/utils/index.ts

@@ -1,42 +1,49 @@
+// Generic, framework-agnostic utilities. Stateful concerns (config store,
+// client identifiers) live in `src/config/`; URL/binary codecs for the
+// referral context live in `src/context/`; SSO URL listener belongs to the
+// iframe client lifecycle in `src/clients/`. Keep this surface narrow.
 export { Deferred } from "@frak-labs/frame-connector";
+
+// Analytics
 export { trackEvent } from "./analytics";
-export { getBackendUrl } from "./backendUrl";
-export { clearAllCache, getCache, withCache } from "./cache";
-export { getClientId } from "./clientId";
-export { base64urlDecode, base64urlEncode } from "./compression/b64";
-export { compressJsonToB64 } from "./compression/compress";
-export { decompressJsonFromB64 } from "./compression/decompress";
-export { DEEP_LINK_SCHEME } from "./constants";
+// Browser / deep linking
 export {
     type DeepLinkFallbackOptions,
     isChromiumAndroid,
     isFrakDeepLink,
     toAndroidIntentUrl,
     triggerDeepLinkWithFallback,
-} from "./deepLinkWithFallback";
-export { FrakContextManager } from "./FrakContext";
-export { formatAmount } from "./formatAmount";
-export { getCurrencyAmountKey } from "./getCurrencyAmountKey";
-export { getSupportedCurrency } from "./getSupportedCurrency";
-export { getSupportedLocale } from "./getSupportedLocale";
-export {
-    baseIframeProps,
-    createIframe,
-    findIframeInOpener,
-} from "./iframeHelper";
+} from "./browser/deepLinkWithFallback";
 export {
     isInAppBrowser,
     isIOS,
+    isMobile,
     redirectToExternalBrowser,
-} from "./inAppBrowser";
+} from "./browser/inAppBrowser";
+// Cache
+export { clearAllCache, getCache, withCache } from "./cache";
+// Compression / encoding
+export { base64urlDecode, base64urlEncode } from "./compression/b64";
+export { compressJsonToB64 } from "./compression/compress";
+export { decompressJsonFromB64 } from "./compression/decompress";
+
+// Formatting / i18n
+export { formatAmount } from "./format/formatAmount";
+export { getCurrencyAmountKey } from "./format/getCurrencyAmountKey";
+export { getSupportedCurrency } from "./format/getSupportedCurrency";
+export { getSupportedLocale } from "./format/getSupportedLocale";
+
+// Iframe DOM helpers
 export {
-    type MergeAttributionInput,
-    mergeAttribution,
-} from "./mergeAttribution";
-export { sdkConfigStore } from "./sdkConfigStore";
+    baseIframeProps,
+    createIframe,
+    findIframeInOpener,
+} from "./iframe/iframeHelper";
+
+// SSO URL builder
 export {
     type AppSpecificSsoMetadata,
     type CompressedSsoData,
     type FullSsoParams,
     generateSsoUrl,
-} from "./sso";
+} from "./sso/sso";

package/src/utils/sso/index.ts

@@ -0,0 +1,6 @@
+export {
+    type AppSpecificSsoMetadata,
+    type CompressedSsoData,
+    type FullSsoParams,
+    generateSsoUrl,
+} from "./sso";

package/src/utils/{sso.ts → sso/sso.ts}

@@ -1,6 +1,6 @@
 import type { Hex } from "viem";
-import type { PrepareSsoParamsType, SsoMetadata } from "../types";
-import { compressJsonToB64 } from "./compression/compress";
+import type { PrepareSsoParamsType, SsoMetadata } from "../../types";
+import { compressJsonToB64 } from "../compression/compress";
 
 export type AppSpecificSsoMetadata = SsoMetadata & {
     name?: string;