@frak-labs/core-sdk 0.0.19-beta.f259d7fc → 0.1.0-beta.263acd1e

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

@@ -0,0 +1,181 @@
+/**
+ * Tests for base64url encoding and decoding utilities
+ * Tests encoding, decoding, and round-trip operations
+ */
+
+import { describe, expect, it, test } from "../../../tests/vitest-fixtures";
+import { base64urlDecode, base64urlEncode } from "./b64";
+
+describe("base64urlEncode", () => {
+    test("should encode empty Uint8Array", ({ mockUint8Arrays }) => {
+        const result = base64urlEncode(mockUint8Arrays.empty);
+
+        expect(result).toBe("");
+    });
+
+    test("should encode simple Uint8Array", ({ mockUint8Arrays }) => {
+        const result = base64urlEncode(mockUint8Arrays.simple);
+
+        // "Hello" should encode to "SGVsbG8"
+        expect(result).toBe("SGVsbG8");
+    });
+
+    test("should replace + with - for URL safety", () => {
+        // Create data that would produce + in standard base64
+        const data = new Uint8Array([0xfb, 0xff]);
+        const result = base64urlEncode(data);
+
+        // Should not contain +
+        expect(result).not.toContain("+");
+        expect(result).toContain("-");
+    });
+
+    test("should replace / with _ for URL safety", () => {
+        // Create data that would produce / in standard base64
+        const data = new Uint8Array([0xff, 0xff]);
+        const result = base64urlEncode(data);
+
+        // Should not contain /
+        expect(result).not.toContain("/");
+        expect(result).toContain("_");
+    });
+
+    test("should remove padding =", () => {
+        // Create data that would have padding
+        const data = new Uint8Array([72]); // "H" -> "SA==" in standard base64
+        const result = base64urlEncode(data);
+
+        // Should not contain =
+        expect(result).not.toContain("=");
+        expect(result).toBe("SA");
+    });
+
+    test("should handle various byte lengths", () => {
+        const lengths = [1, 2, 3, 4, 5, 10, 20];
+
+        for (const length of lengths) {
+            const data = new Uint8Array(length).fill(65); // Fill with 'A' character code
+            const result = base64urlEncode(data);
+
+            // Should produce a string
+            expect(typeof result).toBe("string");
+            expect(result.length).toBeGreaterThan(0);
+        }
+    });
+
+    test("should handle complex byte array", ({ mockUint8Arrays }) => {
+        const result = base64urlEncode(mockUint8Arrays.complex);
+
+        // Should produce valid base64url string
+        expect(result).toMatch(/^[A-Za-z0-9_-]*$/);
+    });
+});
+
+describe("base64urlDecode", () => {
+    test("should decode empty string", ({ mockBase64Strings }) => {
+        const result = base64urlDecode(mockBase64Strings.empty);
+
+        expect(result).toEqual(new Uint8Array([]));
+        expect(result.length).toBe(0);
+    });
+
+    test("should decode simple base64url string", ({ mockBase64Strings }) => {
+        const result = base64urlDecode(mockBase64Strings.simple);
+
+        // "SGVsbG8" should decode to "Hello"
+        const expected = new Uint8Array([72, 101, 108, 108, 111]);
+        expect(result).toEqual(expected);
+    });
+
+    test("should handle strings without padding", () => {
+        // Base64url strings don't have padding
+        const encoded = "SGVsbG8"; // "Hello" without padding
+        const result = base64urlDecode(encoded);
+
+        const expected = new Uint8Array([72, 101, 108, 108, 111]);
+        expect(result).toEqual(expected);
+    });
+
+    test("should reverse URL-safe character replacements", ({
+        mockBase64Strings,
+    }) => {
+        const result = base64urlDecode(mockBase64Strings.withSpecialChars);
+
+        // Should handle - and _ characters
+        expect(result).toBeInstanceOf(Uint8Array);
+    });
+
+    test("should handle various valid base64url string lengths", () => {
+        // Use valid base64url strings
+        const testStrings = ["QQ", "QUI", "QUJD", "QUJDRA"]; // "A", "AB", "ABC", "ABCD" encoded
+
+        for (const str of testStrings) {
+            const result = base64urlDecode(str);
+
+            // Should produce Uint8Array
+            expect(result).toBeInstanceOf(Uint8Array);
+        }
+    });
+});
+
+describe("base64url round-trip", () => {
+    test("should successfully round-trip empty data", ({ mockUint8Arrays }) => {
+        const encoded = base64urlEncode(mockUint8Arrays.empty);
+        const decoded = base64urlDecode(encoded);
+
+        expect(decoded).toEqual(mockUint8Arrays.empty);
+    });
+
+    test("should successfully round-trip simple data", ({
+        mockUint8Arrays,
+    }) => {
+        const encoded = base64urlEncode(mockUint8Arrays.simple);
+        const decoded = base64urlDecode(encoded);
+
+        expect(decoded).toEqual(mockUint8Arrays.simple);
+    });
+
+    test("should successfully round-trip complex data", ({
+        mockUint8Arrays,
+    }) => {
+        const encoded = base64urlEncode(mockUint8Arrays.complex);
+        const decoded = base64urlDecode(encoded);
+
+        expect(decoded).toEqual(mockUint8Arrays.complex);
+    });
+
+    it("should handle all byte values (0-255)", () => {
+        // Test with all possible byte values
+        const allBytes = new Uint8Array(256);
+        for (let i = 0; i < 256; i++) {
+            allBytes[i] = i;
+        }
+
+        const encoded = base64urlEncode(allBytes);
+        const decoded = base64urlDecode(encoded);
+
+        expect(decoded).toEqual(allBytes);
+    });
+
+    it("should preserve binary data integrity", () => {
+        const binaryData = new Uint8Array([0, 1, 127, 128, 255, 254, 100, 200]);
+
+        const encoded = base64urlEncode(binaryData);
+        const decoded = base64urlDecode(encoded);
+
+        expect(decoded).toEqual(binaryData);
+    });
+
+    it("should handle random data correctly", () => {
+        // Generate some pseudo-random data
+        const randomData = new Uint8Array(32);
+        for (let i = 0; i < 32; i++) {
+            randomData[i] = Math.floor(Math.random() * 256);
+        }
+
+        const encoded = base64urlEncode(randomData);
+        const decoded = base64urlDecode(encoded);
+
+        expect(decoded).toEqual(randomData);
+    });
+});

package/src/utils/compression/b64.ts

@@ -0,0 +1,29 @@
+/**
+ * Encode a buffer to a base64url encoded string
+ * @param buffer The buffer to encode
+ * @returns The encoded string
+ */
+export function base64urlEncode(buffer: Uint8Array): string {
+    return btoa(Array.from(buffer, (b) => String.fromCharCode(b)).join(""))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+
+/**
+ * Decode a base64url encoded string
+ * @param value The value to decode
+ * @returns The decoded value
+ */
+export function base64urlDecode(value: string): Uint8Array {
+    const m = value.length % 4;
+    return Uint8Array.from(
+        atob(
+            value
+                .replace(/-/g, "+")
+                .replace(/_/g, "/")
+                .padEnd(value.length + (m === 0 ? 0 : 4 - m), "=")
+        ),
+        (c) => c.charCodeAt(0)
+    );
+}

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", () => ({
+    compressJson: 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 { compressJson } from "@frak-labs/frame-connector";
+import { base64urlEncode } from "./b64";
+
+/**
+ * Compress json data
+ * @param data
+ * @ignore
+ */
+export function compressJsonToB64(data: unknown): string {
+    return base64urlEncode(compressJson(data));
+}

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

@@ -0,0 +1,145 @@
+/**
+ * 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", () => ({
+    compressJson: vi.fn((data: unknown) => {
+        // Simple mock: convert JSON to Uint8Array
+        const jsonString = JSON.stringify(data);
+        return new TextEncoder().encode(jsonString);
+    }),
+    decompressJson: vi.fn((data: Uint8Array) => {
+        // Simple mock: convert Uint8Array back to JSON
+        const jsonString = new TextDecoder().decode(data);
+        return JSON.parse(jsonString);
+    }),
+}));
+
+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 { decompressJson } from "@frak-labs/frame-connector";
+import { base64urlDecode } from "./b64";
+
+/**
+ * Decompress json data
+ * @param data
+ * @ignore
+ */
+export function decompressJsonFromB64<T>(data: string): T | null {
+    return decompressJson(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/computeProductId.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Tests for computeProductId utility function
+ * Tests product ID computation from domain names with normalization
+ */
+
+import { keccak256, toHex } from "viem";
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import { computeProductId } from "./computeProductId";
+
+describe("computeProductId", () => {
+    it("should compute product ID from current domain (window.location.host)", () => {
+        // In JSDOM test environment, window.location.host is "localhost:3000"
+        const productId = computeProductId();
+
+        // Should compute keccak256 hash of window.location.host
+        const expectedId = keccak256(toHex(window.location.host));
+        expect(productId).toBe(expectedId);
+    });
+
+    it("should compute product ID from custom domain", () => {
+        const customDomain = "custom-domain.com";
+        const productId = computeProductId({ domain: customDomain });
+
+        // Should compute keccak256 hash of custom domain
+        const expectedId = keccak256(toHex(customDomain));
+        expect(productId).toBe(expectedId);
+    });
+
+    it("should remove www. prefix from domain before hashing", () => {
+        const domainWithWww = "www.example.com";
+        const productId = computeProductId({ domain: domainWithWww });
+
+        // Should compute keccak256 hash of "example.com" (www. removed)
+        const expectedId = keccak256(toHex("example.com"));
+        expect(productId).toBe(expectedId);
+    });
+
+    it("should produce same product ID for domain with and without www", () => {
+        const withWww = computeProductId({ domain: "www.example.com" });
+        const withoutWww = computeProductId({ domain: "example.com" });
+
+        // Both should produce the same hash
+        expect(withWww).toBe(withoutWww);
+    });
+
+    it("should produce different product IDs for different domains", () => {
+        const domain1ProductId = computeProductId({ domain: "domain1.com" });
+        const domain2ProductId = computeProductId({ domain: "domain2.com" });
+
+        // Different domains should produce different hashes
+        expect(domain1ProductId).not.toBe(domain2ProductId);
+    });
+
+    it("should use window.location.host when domain is not provided", () => {
+        // When no domain is provided, it should default to window.location.host
+        const productId = computeProductId();
+
+        // Should produce same result as using window.location.host explicitly
+        const expectedId = keccak256(toHex(window.location.host));
+        expect(productId).toBe(expectedId);
+    });
+
+    it("should handle subdomains correctly", () => {
+        const subdomain = "blog.example.com";
+        const productId = computeProductId({ domain: subdomain });
+
+        // Should compute keccak256 hash of "blog.example.com" (subdomain preserved)
+        const expectedId = keccak256(toHex(subdomain));
+        expect(productId).toBe(expectedId);
+    });
+
+    it("should only remove www prefix, not other w-prefixed subdomains", () => {
+        const domain = "web.example.com";
+        const productId = computeProductId({ domain });
+
+        // Should NOT remove "web." prefix, only "www."
+        const expectedId = keccak256(toHex("web.example.com"));
+        expect(productId).toBe(expectedId);
+    });
+});

package/src/utils/computeProductId.ts

@@ -0,0 +1,11 @@
+import { keccak256, toHex } from "viem";
+
+/**
+ * Compute the product id from a domain
+ * @ignore
+ */
+export function computeProductId({ 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,4 @@
+/**
+ * The backup key for client side backup if needed
+ */
+export const BACKUP_KEY = "nexus-wallet-backup";