@frak-labs/core-sdk 1.0.2 → 1.1.0-beta.d970d1ee

package/src/actions/trackPurchaseStatus.test.ts

@@ -7,18 +7,18 @@ import {
     test,
 } from "../../tests/vitest-fixtures";
 
-vi.mock("../utils/clientId", () => ({
+vi.mock("../config/clientId", () => ({
     getClientId: vi.fn().mockReturnValue("test-client-id"),
 }));
 
-vi.mock("../utils/sdkConfigStore", () => ({
+vi.mock("../config/sdkConfigStore", () => ({
     sdkConfigStore: {
         resolveMerchantId: vi.fn().mockResolvedValue(undefined),
     },
 }));
 
-import { getClientId } from "../utils/clientId";
-import { sdkConfigStore } from "../utils/sdkConfigStore";
+import { getClientId } from "../config/clientId";
+import { sdkConfigStore } from "../config/sdkConfigStore";
 import { trackPurchaseStatus } from "./trackPurchaseStatus";
 
 describe.sequential("trackPurchaseStatus", () => {

package/src/actions/trackPurchaseStatus.ts

@@ -1,6 +1,6 @@
-import { getBackendUrl } from "../utils/backendUrl";
-import { getClientId } from "../utils/clientId";
-import { sdkConfigStore } from "../utils/sdkConfigStore";
+import { getBackendUrl } from "../config/backendUrl";
+import { getClientId } from "../config/clientId";
+import { sdkConfigStore } from "../config/sdkConfigStore";
 
 /**
  * Function used to track the status of a purchase

package/src/actions/wrapper/siweAuthenticate.test.ts

@@ -4,10 +4,6 @@ vi.mock("../displayModal", () => ({
     displayModal: vi.fn(),
 }));
 
-vi.mock("viem/siwe", () => ({
-    generateSiweNonce: vi.fn(() => "mock-nonce-123456"),
-}));
-
 import type { Address, Hex } from "viem";
 import { describe, expect, it } from "../../../tests/vitest-fixtures";
 import type { FrakClient } from "../../types";
@@ -65,7 +61,7 @@ describe("siweAuthenticate", () => {
                     siweAuthenticate: {
                         siwe: expect.objectContaining({
                             domain: "example.com",
-                            nonce: "mock-nonce-123456",
+                            nonce: expect.stringMatching(/^[0-9a-f]{96}$/),
                             uri: "https://example.com",
                             version: "1",
                         }),

package/src/actions/wrapper/siweAuthenticate.ts

@@ -1,4 +1,3 @@
-import { generateSiweNonce } from "viem/siwe";
 import type {
     FrakClient,
     ModalRpcMetadata,
@@ -7,6 +6,31 @@ import type {
 } from "../../types";
 import { displayModal } from "../displayModal";
 
+/**
+ * Generate a random EIP-4361-compatible nonce.
+ *
+ * Matches viem/siwe's `generateSiweNonce` shape (96 alphanumeric chars) but
+ * inlined here to avoid pulling viem's runtime utilities into the bundle.
+ * Uses `crypto.getRandomValues` when available (browsers, modern Node) and
+ * falls back to `Math.random` for the rare environment without WebCrypto.
+ */
+function generateSiweNonce(length = 96): string {
+    const byteCount = Math.ceil(length / 2);
+    let hex = "";
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        const bytes = new Uint8Array(byteCount);
+        crypto.getRandomValues(bytes);
+        for (let i = 0; i < bytes.length; i++) {
+            hex += bytes[i].toString(16).padStart(2, "0");
+        }
+    } else {
+        for (let i = 0; i < byteCount; i++) {
+            hex += ((Math.random() * 256) | 0).toString(16).padStart(2, "0");
+        }
+    }
+    return hex.substring(0, length);
+}
+
 /**
  * Parameter used to directly show a modal used to authenticate with SIWE
  * @inline

package/src/clients/createIFrameFrakClient.ts

@@ -6,17 +6,16 @@ import {
     RpcErrorCodes,
 } from "@frak-labs/frame-connector";
 import { OpenPanel } from "@openpanel/web";
+import { getClientId } from "../config/clientId";
+import { sdkConfigStore } from "../config/sdkConfigStore";
+import { BACKUP_KEY } from "../constants";
 import type { FrakLifecycleEvent } from "../types";
 import type { FrakClient } from "../types/client";
 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";
-import { DebugInfoGatherer } from "./DebugInfo";
+import { setupSsoUrlListener } from "./ssoUrlListener";
 import {
     createIFrameLifecycleManager,
     type IframeLifecycleManager,
@@ -84,9 +83,6 @@ export function createIFrameFrakClient({
     // lifecycle manager resolves the `isConnected` promise.
     const handshakeStartedAt = Date.now();
 
-    // Create our debug info gatherer
-    const debugInfo = new DebugInfoGatherer(config, iframe);
-
     // Validate iframe
     if (!iframe.contentWindow) {
         throw new FrakRpcError(
@@ -115,17 +111,6 @@ export function createIFrameFrakClient({
                     return ctx;
                 },
             },
-            // Save debug info
-            {
-                onRequest(message, ctx) {
-                    debugInfo.setLastRequest(message);
-                    return ctx;
-                },
-                onResponse(message, response) {
-                    debugInfo.setLastResponse(message, response);
-                    return response;
-                },
-            },
         ],
         // Add lifecycle handlers to process iframe lifecycle events
         lifecycleHandlers: {
@@ -227,7 +212,7 @@ export function createIFrameFrakClient({
         contextSent,
         openPanel,
     })
-        .then(() => debugInfo.updateSetupStatus(true))
+        .then(() => {})
         .catch((err) => {
             contextSent.reject(err);
             throw err;
@@ -235,7 +220,6 @@ export function createIFrameFrakClient({
 
     return {
         config,
-        debugInfo,
         waitForConnection: lifecycleManager.isConnected,
         waitForSetup,
         request: rpcClient.request,

package/src/clients/index.ts

@@ -1,3 +1,2 @@
 export { createIFrameFrakClient } from "./createIFrameFrakClient";
-export { DebugInfoGatherer } from "./DebugInfo";
 export { setupClient } from "./setupClient";

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

@@ -16,19 +16,19 @@ vi.mock("@frak-labs/frame-connector", () => ({
     },
 }));
 
-vi.mock("../../utils/constants", () => ({
+vi.mock("../../constants", () => ({
     BACKUP_KEY: "frak-backup-key",
 }));
 
-vi.mock("../../utils/iframeHelper", () => ({
+vi.mock("../../utils/iframe/iframeHelper", () => ({
     changeIframeVisibility: vi.fn(),
 }));
 
-vi.mock("../../utils/clientId", () => ({
+vi.mock("../../config/clientId", () => ({
     getClientId: vi.fn(() => "mock-client-id"),
 }));
 
-vi.mock("../../utils/deepLinkWithFallback", () => ({
+vi.mock("../../utils/browser/deepLinkWithFallback", () => ({
     isFrakDeepLink: vi.fn((url: string) => url.startsWith("frakwallet://")),
     triggerDeepLinkWithFallback: vi.fn(),
 }));
@@ -185,7 +185,7 @@ describe("createIFrameLifecycleManager", () => {
                 "./iframeLifecycleManager"
             );
             const { changeIframeVisibility } = await import(
-                "../../utils/iframeHelper"
+                "../../utils/iframe/iframeHelper"
             );
 
             const mockIframe = document.createElement("iframe");
@@ -211,7 +211,7 @@ describe("createIFrameLifecycleManager", () => {
                 "./iframeLifecycleManager"
             );
             const { changeIframeVisibility } = await import(
-                "../../utils/iframeHelper"
+                "../../utils/iframe/iframeHelper"
             );
 
             const mockIframe = document.createElement("iframe");
@@ -301,7 +301,7 @@ describe("createIFrameLifecycleManager", () => {
                 "./iframeLifecycleManager"
             );
             const { triggerDeepLinkWithFallback } = await import(
-                "../../utils/deepLinkWithFallback"
+                "../../utils/browser/deepLinkWithFallback"
             );
 
             Object.defineProperty(window, "location", {
@@ -340,7 +340,7 @@ describe("createIFrameLifecycleManager", () => {
                 "./iframeLifecycleManager"
             );
             const { triggerDeepLinkWithFallback } = await import(
-                "../../utils/deepLinkWithFallback"
+                "../../utils/browser/deepLinkWithFallback"
             );
 
             Object.defineProperty(window, "location", {
@@ -396,7 +396,7 @@ describe("createIFrameLifecycleManager", () => {
                 "./iframeLifecycleManager"
             );
             const { triggerDeepLinkWithFallback } = await import(
-                "../../utils/deepLinkWithFallback"
+                "../../utils/browser/deepLinkWithFallback"
             );
 
             Object.defineProperty(window, "location", {
@@ -453,7 +453,7 @@ describe("createIFrameLifecycleManager", () => {
                 "./iframeLifecycleManager"
             );
             const { changeIframeVisibility } = await import(
-                "../../utils/iframeHelper"
+                "../../utils/iframe/iframeHelper"
             );
 
             const mockIframe = document.createElement("iframe");

package/src/clients/transports/iframeLifecycleManager.ts

@@ -1,11 +1,11 @@
 import { Deferred } from "@frak-labs/frame-connector";
+import { BACKUP_KEY } from "../../constants";
 import type { FrakLifecycleEvent } from "../../types";
-import { BACKUP_KEY } from "../../utils/constants";
 import {
     isFrakDeepLink,
     triggerDeepLinkWithFallback,
-} from "../../utils/deepLinkWithFallback";
-import { changeIframeVisibility } from "../../utils/iframeHelper";
+} from "../../utils/browser/deepLinkWithFallback";
+import { changeIframeVisibility } from "../../utils/iframe/iframeHelper";
 
 /**
  * Detect iOS in-app browsers (Instagram, Facebook) where server-side

package/src/config/index.ts

@@ -0,0 +1,3 @@
+export { getBackendUrl } from "./backendUrl";
+export { getClientId } from "./clientId";
+export { sdkConfigStore } from "./sdkConfigStore";

package/src/{utils → config}/sdkConfigStore.ts

@@ -14,8 +14,8 @@ import type {
     MerchantConfigResponse,
     SdkResolvedConfig,
 } from "../types/resolvedConfig";
+import { clearAllCache, withCache } from "../utils/cache";
 import { getBackendUrl } from "./backendUrl";
-import { clearAllCache, withCache } from "./cache";
 
 const GLOBAL_KEY = "__frakSdkConfig";
 const CACHE_TTL = 30_000; // 30 seconds

package/src/{utils/constants.test.ts → constants.test.ts}

@@ -1,9 +1,4 @@
-/**
- * Tests for constants
- * Tests backup key constant value
- */
-
-import { describe, expect, it } from "../../tests/vitest-fixtures";
+import { describe, expect, it } from "../tests/vitest-fixtures";
 import { BACKUP_KEY } from "./constants";
 
 describe("constants", () => {

package/src/constants.ts

@@ -0,0 +1,15 @@
+/**
+ * The backup key for client side backup if needed
+ */
+export const BACKUP_KEY = "nexus-wallet-backup";
+
+/**
+ * Deep link scheme for Frak Wallet mobile app.
+ *
+ * Replaced at build time via tsdown/Vite `define`. Defaults to the prod scheme;
+ * in-monorepo dev builds (listener at wallet-dev.frak.id) override this with
+ * `frakwallet-dev://` so deep links open the dev wallet variant (id.frak.wallet.dev).
+ * External integrators consuming the published NPM/CDN bundle always see the prod scheme.
+ */
+export const DEEP_LINK_SCHEME: string =
+    process.env.DEEP_LINK_SCHEME ?? "frakwallet://";

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
@@ -24,7 +24,7 @@ export function isChromiumAndroid(): boolean {
 }
 
 /**
- * Convert a frakwallet:// deep link to an Android intent:// URL.
+ * Convert a Frak deep link to an Android intent:// URL.
  *
  * Intent URLs let Chromium browsers open the app directly without
  * showing the "Continue to app?" confirmation bar.
@@ -35,12 +35,17 @@ export function isChromiumAndroid(): boolean {
  * Without `package`, Chrome simply does nothing when the app is
  * missing, allowing the fallback mechanism to fire correctly.
  *
- * Format: intent://path#Intent;scheme=frakwallet;end
+ * The scheme is derived from `DEEP_LINK_SCHEME` so the dev variant
+ * (`frakwallet-dev://`) routes to the dev app shell, not prod.
+ *
+ * Format: intent://path#Intent;scheme=<scheme>;end
  */
+const DEEP_LINK_SCHEME_NAME = DEEP_LINK_SCHEME.replace("://", "");
+
 export function toAndroidIntentUrl(deepLink: string): string {
-    // Extract everything after "frakwallet://"
+    // Extract everything after the scheme (e.g. "frakwallet://" or "frakwallet-dev://")
     const path = deepLink.slice(DEEP_LINK_SCHEME.length);
-    return `intent://${path}#Intent;scheme=frakwallet;end`;
+    return `intent://${path}#Intent;scheme=${DEEP_LINK_SCHEME_NAME};end`;
 }
 
 /**