@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.1e44255d

package/src/utils/compression/compress.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Tests for compressJsonToB64 utility function
+ * Tests JSON compression to base64url-encoded string
+ */
+
+import { vi } from "vitest";
+
+// Mock the frame-connector module - must be before imports
+vi.mock("@frak-labs/frame-connector", () => ({
+    jsonEncode: vi.fn((data: unknown) => {
+        // Simple mock: convert JSON to Uint8Array
+        const jsonString = JSON.stringify(data);
+        return new TextEncoder().encode(jsonString);
+    }),
+}));
+
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import { compressJsonToB64 } from "./compress";
+
+describe("compressJsonToB64", () => {
+    describe("success cases", () => {
+        it("should compress and encode simple object", () => {
+            const data = { key: "value" };
+            const result = compressJsonToB64(data);
+
+            // Result should be a base64url-encoded string
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+            // Base64url should not contain +, /, or = characters
+            expect(result).not.toMatch(/[+/=]/);
+        });
+
+        it("should compress and encode array data", () => {
+            const data = [1, 2, 3, 4, 5];
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+            expect(result).not.toMatch(/[+/=]/);
+        });
+
+        it("should compress and encode nested object", () => {
+            const data = {
+                user: {
+                    name: "John",
+                    address: {
+                        city: "Paris",
+                        country: "France",
+                    },
+                },
+            };
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+        });
+
+        it("should compress and encode string data", () => {
+            const data = "Hello, World!";
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+        });
+
+        it("should compress and encode number data", () => {
+            const data = 12345;
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+        });
+
+        it("should compress and encode boolean data", () => {
+            const data = true;
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+        });
+
+        it("should compress and encode null", () => {
+            const data = null;
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+        });
+    });
+
+    describe("edge cases", () => {
+        it("should handle empty object", () => {
+            const data = {};
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+        });
+
+        it("should handle empty array", () => {
+            const data: unknown[] = [];
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+        });
+
+        it("should handle empty string", () => {
+            const data = "";
+            const result = compressJsonToB64(data);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+        });
+    });
+});

package/src/utils/compression/compress.ts

@@ -0,0 +1,11 @@
+import { jsonEncode } from "@frak-labs/frame-connector";
+import { base64urlEncode } from "./b64";
+
+/**
+ * Compress json data
+ * @param data
+ * @ignore
+ */
+export function compressJsonToB64(data: unknown): string {
+    return base64urlEncode(jsonEncode(data));
+}

package/src/utils/compression/decompress.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Tests for decompressJsonFromB64 utility function
+ * Tests decompression of base64url-encoded JSON strings
+ */
+
+import { vi } from "vitest";
+
+// Mock the frame-connector module - must be before imports
+vi.mock("@frak-labs/frame-connector", () => ({
+    jsonEncode: vi.fn((data: unknown) => {
+        // Simple mock: convert JSON to Uint8Array
+        const jsonString = JSON.stringify(data);
+        return new TextEncoder().encode(jsonString);
+    }),
+    jsonDecode: vi.fn((data: Uint8Array) => {
+        // Simple mock: convert Uint8Array back to JSON
+        try {
+            const jsonString = new TextDecoder().decode(data);
+            return JSON.parse(jsonString);
+        } catch {
+            return null;
+        }
+    }),
+}));
+
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import { compressJsonToB64 } from "./compress";
+import { decompressJsonFromB64 } from "./decompress";
+
+describe("decompressJsonFromB64", () => {
+    describe("success cases", () => {
+        it("should decompress simple object", () => {
+            const original = { key: "value" };
+            const compressed = compressJsonToB64(original);
+            const decompressed =
+                decompressJsonFromB64<typeof original>(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+
+        it("should decompress array data", () => {
+            const original = [1, 2, 3, 4, 5];
+            const compressed = compressJsonToB64(original);
+            const decompressed =
+                decompressJsonFromB64<typeof original>(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+
+        it("should decompress nested object", () => {
+            const original = {
+                user: {
+                    name: "John",
+                    address: {
+                        city: "Paris",
+                        country: "France",
+                    },
+                },
+            };
+            const compressed = compressJsonToB64(original);
+            const decompressed =
+                decompressJsonFromB64<typeof original>(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+
+        it("should decompress string data", () => {
+            const original = "Hello, World!";
+            const compressed = compressJsonToB64(original);
+            const decompressed = decompressJsonFromB64<string>(compressed);
+
+            expect(decompressed).toBe(original);
+        });
+
+        it("should decompress number data", () => {
+            const original = 12345;
+            const compressed = compressJsonToB64(original);
+            const decompressed = decompressJsonFromB64<number>(compressed);
+
+            expect(decompressed).toBe(original);
+        });
+
+        it("should decompress boolean data", () => {
+            const original = true;
+            const compressed = compressJsonToB64(original);
+            const decompressed = decompressJsonFromB64<boolean>(compressed);
+
+            expect(decompressed).toBe(original);
+        });
+
+        it("should decompress null", () => {
+            const original = null;
+            const compressed = compressJsonToB64(original);
+            const decompressed = decompressJsonFromB64<null>(compressed);
+
+            expect(decompressed).toBeNull();
+        });
+    });
+
+    describe("round-trip compression", () => {
+        it("should preserve data through compress-decompress cycle", () => {
+            const original = {
+                id: 123,
+                name: "Test User",
+                tags: ["tag1", "tag2", "tag3"],
+                metadata: {
+                    created: "2024-01-01",
+                    updated: "2024-01-02",
+                },
+            };
+
+            const compressed = compressJsonToB64(original);
+            const decompressed =
+                decompressJsonFromB64<typeof original>(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+
+        it("should handle empty object round-trip", () => {
+            const original = {};
+            const compressed = compressJsonToB64(original);
+            const decompressed =
+                decompressJsonFromB64<typeof original>(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+
+        it("should handle empty array round-trip", () => {
+            const original: unknown[] = [];
+            const compressed = compressJsonToB64(original);
+            const decompressed =
+                decompressJsonFromB64<typeof original>(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+    });
+
+    describe("edge cases", () => {
+        it("should handle empty object round-trip gracefully", () => {
+            // Empty objects should compress and decompress correctly
+            const original = {};
+            const compressed = compressJsonToB64(original);
+            const decompressed =
+                decompressJsonFromB64<typeof original>(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+    });
+});

package/src/utils/compression/decompress.ts

@@ -0,0 +1,11 @@
+import { jsonDecode } from "@frak-labs/frame-connector";
+import { base64urlDecode } from "./b64";
+
+/**
+ * Decompress json data
+ * @param data
+ * @ignore
+ */
+export function decompressJsonFromB64<T>(data: string): T | null {
+    return jsonDecode<T>(base64urlDecode(data));
+}

package/src/utils/compression/index.ts

@@ -0,0 +1,3 @@
+export { base64urlDecode, base64urlEncode } from "./b64";
+export { compressJsonToB64 } from "./compress";
+export { decompressJsonFromB64 } from "./decompress";

package/src/utils/computeLegacyProductId.ts

@@ -0,0 +1,11 @@
+import { keccak256, toHex } from "viem";
+
+/**
+ * Compute the legacy product id from a domain
+ * @ignore
+ */
+export function computeLegacyProductId({ domain }: { domain?: string } = {}) {
+    const effectiveDomain = domain ?? window.location.host;
+    const normalizedDomain = effectiveDomain.replace("www.", "");
+    return keccak256(toHex(normalizedDomain));
+}

package/src/utils/constants.test.ts

@@ -0,0 +1,23 @@
+/**
+ * Tests for constants
+ * Tests backup key constant value
+ */
+
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import { BACKUP_KEY } from "./constants";
+
+describe("constants", () => {
+    describe("BACKUP_KEY", () => {
+        it("should have correct backup key value", () => {
+            expect(BACKUP_KEY).toBe("nexus-wallet-backup");
+        });
+
+        it("should be a string", () => {
+            expect(typeof BACKUP_KEY).toBe("string");
+        });
+
+        it("should not be empty", () => {
+            expect(BACKUP_KEY.length).toBeGreaterThan(0);
+        });
+    });
+});

package/src/utils/constants.ts

@@ -0,0 +1,9 @@
+/**
+ * The backup key for client side backup if needed
+ */
+export const BACKUP_KEY = "nexus-wallet-backup";
+
+/**
+ * Deep link scheme for Frak Wallet mobile app
+ */
+export const DEEP_LINK_SCHEME = "frakwallet://";

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);
+}