@frak-labs/core-sdk 0.1.1 → 0.2.0

package/src/utils/deepLinkWithFallback.test.ts

@@ -0,0 +1,243 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import {
+    isFrakDeepLink,
+    triggerDeepLinkWithFallback,
+} from "./deepLinkWithFallback";
+
+/**
+ * Set navigator.userAgent for testing platform-specific behavior
+ */
+function mockUserAgent(ua: string) {
+    Object.defineProperty(navigator, "userAgent", {
+        value: ua,
+        writable: true,
+        configurable: true,
+    });
+}
+
+const CHROME_ANDROID_UA =
+    "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36";
+const FIREFOX_ANDROID_UA =
+    "Mozilla/5.0 (Android 14; Mobile; rv:121.0) Gecko/121.0 Firefox/121.0";
+const DESKTOP_CHROME_UA =
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+
+describe("deepLinkWithFallback", () => {
+    let originalHidden: boolean;
+    let originalAddEventListener: typeof document.addEventListener;
+    let originalRemoveEventListener: typeof document.removeEventListener;
+    let originalUserAgent: string;
+    let visibilityChangeHandler: (() => void) | null = null;
+
+    beforeEach(() => {
+        vi.useFakeTimers();
+
+        // Store originals
+        originalHidden = document.hidden;
+        originalAddEventListener = document.addEventListener;
+        originalRemoveEventListener = document.removeEventListener;
+        originalUserAgent = navigator.userAgent;
+
+        // Default to desktop Chrome (non-Android)
+        mockUserAgent(DESKTOP_CHROME_UA);
+
+        // Mock document.hidden
+        Object.defineProperty(document, "hidden", {
+            value: false,
+            writable: true,
+            configurable: true,
+        });
+
+        // Mock window.location
+        Object.defineProperty(window, "location", {
+            value: { href: "https://test.com" },
+            writable: true,
+            configurable: true,
+        });
+
+        // Capture visibilitychange handler
+        visibilityChangeHandler = null;
+        document.addEventListener = vi.fn(
+            (event: string, handler: EventListener) => {
+                if (event === "visibilitychange") {
+                    visibilityChangeHandler = handler as () => void;
+                }
+            }
+        );
+        document.removeEventListener = vi.fn();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+
+        // Restore originals
+        Object.defineProperty(document, "hidden", {
+            value: originalHidden,
+            writable: true,
+            configurable: true,
+        });
+        document.addEventListener = originalAddEventListener;
+        document.removeEventListener = originalRemoveEventListener;
+        mockUserAgent(originalUserAgent);
+    });
+
+    describe("triggerDeepLinkWithFallback", () => {
+        test("should trigger deep link immediately", () => {
+            triggerDeepLinkWithFallback("frakwallet://wallet");
+
+            expect(window.location.href).toBe("frakwallet://wallet");
+        });
+
+        test("should add visibilitychange listener", () => {
+            triggerDeepLinkWithFallback("frakwallet://wallet");
+
+            expect(document.addEventListener).toHaveBeenCalledWith(
+                "visibilitychange",
+                expect.any(Function)
+            );
+        });
+
+        test("should trigger fallback callback when page stays visible after timeout", () => {
+            const onFallback = vi.fn();
+
+            triggerDeepLinkWithFallback("frakwallet://wallet", { onFallback });
+
+            // Document stays visible (app not installed)
+            Object.defineProperty(document, "hidden", {
+                value: false,
+                configurable: true,
+            });
+
+            // Advance past timeout
+            vi.advanceTimersByTime(2500);
+
+            expect(onFallback).toHaveBeenCalledTimes(1);
+        });
+
+        test("should NOT trigger fallback when page goes hidden (app opened)", () => {
+            const onFallback = vi.fn();
+
+            triggerDeepLinkWithFallback("frakwallet://wallet", { onFallback });
+
+            // Simulate app opening (page goes to background)
+            Object.defineProperty(document, "hidden", {
+                value: true,
+                configurable: true,
+            });
+            visibilityChangeHandler?.();
+
+            // Advance past timeout
+            vi.advanceTimersByTime(2500);
+
+            // Fallback should NOT be triggered
+            expect(onFallback).not.toHaveBeenCalled();
+            // Location should still be the deep link
+            expect(window.location.href).toBe("frakwallet://wallet");
+        });
+
+        test("should respect custom timeout", () => {
+            const onFallback = vi.fn();
+
+            triggerDeepLinkWithFallback("frakwallet://wallet", {
+                timeout: 1000,
+                onFallback,
+            });
+
+            // Advance to just before custom timeout
+            vi.advanceTimersByTime(999);
+            expect(onFallback).not.toHaveBeenCalled();
+
+            // Advance past custom timeout
+            vi.advanceTimersByTime(1);
+            expect(onFallback).toHaveBeenCalledTimes(1);
+        });
+
+        test("should remove event listener after timeout", () => {
+            triggerDeepLinkWithFallback("frakwallet://wallet");
+
+            // Advance past timeout
+            vi.advanceTimersByTime(2500);
+
+            expect(document.removeEventListener).toHaveBeenCalledWith(
+                "visibilitychange",
+                expect.any(Function)
+            );
+        });
+
+        test("should work without onFallback callback", () => {
+            // Should not throw
+            triggerDeepLinkWithFallback("frakwallet://wallet");
+
+            // Advance past timeout
+            vi.advanceTimersByTime(2500);
+
+            // No error should occur, callback is optional
+        });
+
+        describe("Android Intent URL conversion", () => {
+            test("should use intent:// URL on Chromium Android", () => {
+                mockUserAgent(CHROME_ANDROID_UA);
+
+                triggerDeepLinkWithFallback("frakwallet://wallet");
+
+                expect(window.location.href).toBe(
+                    "intent://wallet#Intent;scheme=frakwallet;end"
+                );
+            });
+
+            test("should preserve path and query params in intent URL", () => {
+                mockUserAgent(CHROME_ANDROID_UA);
+
+                triggerDeepLinkWithFallback(
+                    "frakwallet://pair?id=abc-123&mode=embedded"
+                );
+
+                expect(window.location.href).toBe(
+                    "intent://pair?id=abc-123&mode=embedded#Intent;scheme=frakwallet;end"
+                );
+            });
+
+            test("should use custom scheme on Firefox Android", () => {
+                mockUserAgent(FIREFOX_ANDROID_UA);
+
+                triggerDeepLinkWithFallback("frakwallet://wallet");
+
+                expect(window.location.href).toBe("frakwallet://wallet");
+            });
+
+            test("should use custom scheme on desktop Chrome", () => {
+                mockUserAgent(DESKTOP_CHROME_UA);
+
+                triggerDeepLinkWithFallback("frakwallet://wallet");
+
+                expect(window.location.href).toBe("frakwallet://wallet");
+            });
+
+            test("should not convert non-frak deep links to intent URL", () => {
+                mockUserAgent(CHROME_ANDROID_UA);
+
+                triggerDeepLinkWithFallback("https://wallet.frak.id/pair");
+
+                expect(window.location.href).toBe(
+                    "https://wallet.frak.id/pair"
+                );
+            });
+        });
+    });
+
+    describe("isFrakDeepLink", () => {
+        test("should return true for frakwallet:// URLs", () => {
+            expect(isFrakDeepLink("frakwallet://wallet")).toBe(true);
+            expect(isFrakDeepLink("frakwallet://pair?id=123")).toBe(true);
+            expect(isFrakDeepLink("frakwallet://")).toBe(true);
+        });
+
+        test("should return false for non-frakwallet URLs", () => {
+            expect(isFrakDeepLink("https://wallet.frak.id")).toBe(false);
+            expect(isFrakDeepLink("http://example.com")).toBe(false);
+            expect(isFrakDeepLink("myapp://something")).toBe(false);
+            expect(isFrakDeepLink("")).toBe(false);
+        });
+    });
+});

package/src/utils/deepLinkWithFallback.ts

@@ -0,0 +1,103 @@
+import { DEEP_LINK_SCHEME } from "./constants";
+
+/**
+ * Options for deep link with fallback
+ */
+export type DeepLinkFallbackOptions = {
+    /** Timeout in ms before triggering fallback (default: 2500ms) */
+    timeout?: number;
+    /** Callback invoked when fallback is triggered (app not installed) */
+    onFallback?: () => void;
+};
+
+/**
+ * Check if running on a Chromium-based Android browser.
+ *
+ * On Chrome Android, custom scheme deep links (e.g. frakwallet://) trigger
+ * a confirmation bar ("Continue to Frak Wallet?"). Using intent:// URLs
+ * instead bypasses this for Chromium browsers while keeping custom scheme
+ * fallback for non-Chromium browsers (e.g. Firefox) where it works fine.
+ */
+export function isChromiumAndroid(): boolean {
+    const ua = navigator.userAgent;
+    return /Android/i.test(ua) && /Chrome\/\d+/i.test(ua);
+}
+
+/**
+ * Convert a frakwallet:// deep link to an Android intent:// URL.
+ *
+ * Intent URLs let Chromium browsers open the app directly without
+ * showing the "Continue to app?" confirmation bar.
+ *
+ * Note: We intentionally omit the `package` parameter. Including it
+ * causes Chrome to redirect to the Play Store when the app is not
+ * installed, which breaks the visibility-based fallback detection.
+ * 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
+ */
+export function toAndroidIntentUrl(deepLink: string): string {
+    // Extract everything after "frakwallet://"
+    const path = deepLink.slice(DEEP_LINK_SCHEME.length);
+    return `intent://${path}#Intent;scheme=frakwallet;end`;
+}
+
+/**
+ * Trigger a deep link with visibility-based fallback detection.
+ *
+ * Uses the Page Visibility API to detect if the app opened (page goes hidden).
+ * If the page remains visible after the timeout, assumes app is not installed
+ * and invokes the onFallback callback.
+ *
+ * On Chromium Android, converts custom scheme to intent:// URL to avoid
+ * the "Continue to app?" confirmation bar.
+ *
+ * @param deepLink - The deep link URL to trigger (e.g., "frakwallet://wallet")
+ * @param options - Optional configuration (timeout, onFallback callback)
+ */
+export function triggerDeepLinkWithFallback(
+    deepLink: string,
+    options?: DeepLinkFallbackOptions
+): void {
+    const timeout = options?.timeout ?? 2500;
+
+    // Track if the app opened (page went to background)
+    let appOpened = false;
+
+    const onVisibilityChange = () => {
+        if (document.hidden) {
+            appOpened = true;
+        }
+    };
+
+    // Start listening for visibility changes
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    // On Chromium Android, use intent:// to avoid confirmation bar
+    const url =
+        isChromiumAndroid() && isFrakDeepLink(deepLink)
+            ? toAndroidIntentUrl(deepLink)
+            : deepLink;
+
+    // Trigger the deep link
+    window.location.href = url;
+
+    // Check after timeout if app opened
+    setTimeout(() => {
+        // Clean up listener
+        document.removeEventListener("visibilitychange", onVisibilityChange);
+
+        if (!appOpened) {
+            // App didn't open - trigger fallback callback
+            options?.onFallback?.();
+        }
+    }, timeout);
+}
+
+/**
+ * Check if a URL is a Frak deep link
+ */
+export function isFrakDeepLink(url: string): boolean {
+    return url.startsWith(DEEP_LINK_SCHEME);
+}

package/src/utils/formatAmount.ts

@@ -2,6 +2,12 @@ import type { Currency } from "../types";
 import { getSupportedCurrency } from "./getSupportedCurrency";
 import { getSupportedLocale } from "./getSupportedLocale";
 
+/**
+ * Format a numeric amount as a localized currency string
+ * @param amount - The raw numeric amount to format
+ * @param currency - Optional currency config; defaults to EUR/fr-FR when omitted
+ * @returns Localized currency string (e.g. "1 500 €", "$1,500")
+ */
 export function formatAmount(amount: number, currency?: Currency) {
     // Get the supported locale (e.g. "fr-FR")
     const supportedLocale = getSupportedLocale(currency);

package/src/utils/iframeHelper.test.ts

@@ -1,3 +1,9 @@
+import { vi } from "vitest";
+
+vi.mock("./clientId", () => ({
+    getClientId: vi.fn(() => "mock-client-id-for-test"),
+}));
+
 /**
  * Tests for iframe helper utilities
  * Tests iframe creation, visibility management, and finder functions
@@ -9,7 +15,6 @@ import {
     describe,
     expect,
     it,
-    vi,
 } from "../../tests/vitest-fixtures";
 import type { FrakWalletSdkConfig } from "../types";
 import {
@@ -106,7 +111,9 @@ describe("iframeHelper", () => {
         it("should set iframe src to default wallet URL", async () => {
             await createIframe({});
 
-            expect(mockIframe.src).toBe("https://wallet.frak.id/listener");
+            expect(mockIframe.src).toBe(
+                "https://wallet.frak.id/listener?clientId=mock-client-id-for-test"
+            );
         });
 
         it("should use config walletUrl when provided", async () => {
@@ -117,13 +124,17 @@ describe("iframeHelper", () => {
 
             await createIframe({ config });
 
-            expect(mockIframe.src).toBe("https://custom-wallet.com/listener");
+            expect(mockIframe.src).toBe(
+                "https://custom-wallet.com/listener?clientId=mock-client-id-for-test"
+            );
         });
 
         it("should use deprecated walletBaseUrl when provided", async () => {
             await createIframe({ walletBaseUrl: "https://legacy-wallet.com" });
 
-            expect(mockIframe.src).toBe("https://legacy-wallet.com/listener");
+            expect(mockIframe.src).toBe(
+                "https://legacy-wallet.com/listener?clientId=mock-client-id-for-test"
+            );
         });
 
         it("should prefer config.walletUrl over walletBaseUrl", async () => {
@@ -137,7 +148,9 @@ describe("iframeHelper", () => {
                 config,
             });
 
-            expect(mockIframe.src).toBe("https://new-wallet.com/listener");
+            expect(mockIframe.src).toBe(
+                "https://new-wallet.com/listener?clientId=mock-client-id-for-test"
+            );
         });
 
         it("should remove existing iframe before creating new one", async () => {

package/src/utils/iframeHelper.ts

@@ -1,4 +1,5 @@
 import type { FrakWalletSdkConfig } from "../types";
+import { getClientId } from "./clientId";
 
 /**
  * Base props for the iframe
@@ -51,13 +52,19 @@ export function createIframe({
     iframe.style.zIndex = baseIframeProps.style.zIndex.toString();
 
     changeIframeVisibility({ iframe, isVisible: false });
-    document.body.appendChild(iframe);
+
+    // Set src BEFORE appending to DOM to avoid about:blank load event
+    const walletUrl =
+        config?.walletUrl ?? walletBaseUrl ?? "https://wallet.frak.id";
+    const clientId = getClientId();
+    iframe.src = `${walletUrl}/listener?clientId=${encodeURIComponent(clientId)}`;
 
     return new Promise((resolve) => {
-        iframe?.addEventListener("load", () => resolve(iframe));
-        iframe.src = `${config?.walletUrl ?? walletBaseUrl ?? "https://wallet.frak.id"}/listener`;
+        iframe.addEventListener("load", () => resolve(iframe));
+        document.body.appendChild(iframe);
     });
 }
+
 /**
  * Change the visibility of the given iframe
  * @ignore

package/src/utils/index.ts

@@ -1,7 +1,17 @@
 export { Deferred } from "@frak-labs/frame-connector";
+export { getBackendUrl } from "./backendUrl";
+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";
+export {
+    type DeepLinkFallbackOptions,
+    isChromiumAndroid,
+    isFrakDeepLink,
+    toAndroidIntentUrl,
+    triggerDeepLinkWithFallback,
+} from "./deepLinkWithFallback";
 export { FrakContextManager } from "./FrakContext";
 export { formatAmount } from "./formatAmount";
 export { getCurrencyAmountKey } from "./getCurrencyAmountKey";
@@ -12,10 +22,15 @@ export {
     createIframe,
     findIframeInOpener,
 } from "./iframeHelper";
+export {
+    clearMerchantIdCache,
+    fetchMerchantId,
+    resolveMerchantId,
+} from "./merchantId";
 export {
     type AppSpecificSsoMetadata,
     type CompressedSsoData,
     type FullSsoParams,
     generateSsoUrl,
 } from "./sso";
-export { trackEvent } from "./trackEvent";
+export { type FrakEvent, trackEvent } from "./trackEvent";