@frak-labs/core-sdk 0.1.0-beta.8d103039 → 0.1.0-beta.b0bd1f8a

package/src/utils/FrakContext.test.ts

@@ -0,0 +1,407 @@
+/**
+ * Tests for FrakContextManager utility
+ * Tests Frak context compression, URL parsing, and management
+ */
+
+import { mockWindowHistory } from "@frak-labs/test-foundation";
+import type { Address } from "viem";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
+import type { FrakContext } from "../types";
+import { FrakContextManager } from "./FrakContext";
+
+describe("FrakContextManager", () => {
+    let consoleErrorSpy: any;
+
+    beforeEach(() => {
+        consoleErrorSpy = vi
+            .spyOn(console, "error")
+            .mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        consoleErrorSpy.mockRestore();
+    });
+
+    describe("compress", () => {
+        it("should compress context with referrer address", () => {
+            const context: Partial<FrakContext> = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.compress(context);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result?.length).toBeGreaterThan(0);
+            // Base64url should not contain +, /, or =
+            expect(result).not.toMatch(/[+/=]/);
+        });
+
+        it("should return undefined when context has no referrer", () => {
+            const context: Partial<FrakContext> = {};
+
+            const result = FrakContextManager.compress(context);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should return undefined when context is undefined", () => {
+            const result = FrakContextManager.compress(undefined);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should handle compression errors gracefully", () => {
+            const invalidContext = {
+                r: "invalid-address" as Address,
+            };
+
+            const result = FrakContextManager.compress(invalidContext);
+
+            expect(consoleErrorSpy).toHaveBeenCalled();
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("decompress", () => {
+        it("should decompress valid base64url context", () => {
+            // First compress a context
+            const originalContext: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+            const compressed = FrakContextManager.compress(originalContext);
+
+            // Then decompress it
+            const result = FrakContextManager.decompress(compressed);
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return undefined for empty string", () => {
+            const result = FrakContextManager.decompress("");
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should return undefined for undefined input", () => {
+            const result = FrakContextManager.decompress(undefined);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should handle decompression errors gracefully", () => {
+            const result = FrakContextManager.decompress(
+                "invalid-base64url!@#"
+            );
+
+            expect(consoleErrorSpy).toHaveBeenCalled();
+            expect(result).toBeUndefined();
+        });
+
+        it("should round-trip compress and decompress", () => {
+            const original: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const compressed = FrakContextManager.compress(original);
+            const decompressed = FrakContextManager.decompress(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+    });
+
+    describe("parse", () => {
+        it("should parse URL with fCtx parameter", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0x1234567890123456789012345678901234567890"
+            );
+        });
+
+        it("should return null for URL without fCtx parameter", () => {
+            const url = "https://example.com?other=param";
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeNull();
+        });
+
+        it("should return null for empty URL", () => {
+            const result = FrakContextManager.parse({ url: "" });
+
+            expect(result).toBeNull();
+        });
+
+        it("should parse URL with multiple parameters", () => {
+            const context: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?foo=bar&fCtx=${compressed}&baz=qux`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return undefined for malformed fCtx parameter", () => {
+            // Use a string that will fail base64url decoding
+            const url = "https://example.com?fCtx=!!!invalid!!!";
+
+            const result = FrakContextManager.parse({ url });
+
+            // Should handle the error and return undefined
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("update", () => {
+        it("should add fCtx to URL without existing context", () => {
+            const url = "https://example.com";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toBeDefined();
+            expect(result).toContain("fCtx=");
+            expect(result).toContain("https://example.com");
+        });
+
+        it("should merge with existing context in URL", () => {
+            const existingContext: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(existingContext);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const newContext: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+
+            const result = FrakContextManager.update({
+                url,
+                context: newContext,
+            });
+
+            expect(result).toBeDefined();
+            expect(result).toContain("fCtx=");
+
+            // Parse the result and check it has the new referrer
+            const parsedResult = FrakContextManager.parse({ url: result! });
+            expect(parsedResult?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return null when URL is undefined", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({
+                url: undefined,
+                context,
+            });
+
+            expect(result).toBeNull();
+        });
+
+        it("should return null when context has no referrer", () => {
+            const url = "https://example.com";
+            const context: Partial<FrakContext> = {};
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toBeNull();
+        });
+
+        it("should preserve other URL parameters", () => {
+            const url = "https://example.com?foo=bar&baz=qux";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("foo=bar");
+            expect(result).toContain("baz=qux");
+            expect(result).toContain("fCtx=");
+        });
+
+        it("should preserve URL hash", () => {
+            const url = "https://example.com#section";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("#section");
+            expect(result).toContain("fCtx=");
+        });
+    });
+
+    describe("remove", () => {
+        it("should remove fCtx parameter from URL", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toBe("https://example.com/");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should preserve other parameters when removing fCtx", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?foo=bar&fCtx=${compressed}&baz=qux`;
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("foo=bar");
+            expect(result).toContain("baz=qux");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should handle URL without fCtx parameter", () => {
+            const url = "https://example.com?foo=bar";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("foo=bar");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should preserve URL hash", () => {
+            const url = "https://example.com?fCtx=test#section";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("#section");
+            expect(result).not.toContain("fCtx");
+        });
+    });
+
+    describe("replaceUrl", () => {
+        const mockAddress =
+            "0x1234567890123456789012345678901234567890" as Address;
+
+        beforeEach(() => {
+            // Mock window.location.href
+            Object.defineProperty(window, "location", {
+                writable: true,
+                value: {
+                    href: "https://example.com/page",
+                },
+            });
+
+            // Mock window.history using our test utility
+            mockWindowHistory(vi);
+        });
+
+        it("should update window.location with context", () => {
+            const url = "https://example.com/test";
+            const context: FrakContext = { r: mockAddress };
+
+            FrakContextManager.replaceUrl({ url, context });
+
+            const historySpy = vi.mocked(window.history.replaceState);
+            expect(historySpy).toHaveBeenCalledTimes(1);
+            expect(historySpy).toHaveBeenCalledWith(
+                null,
+                "",
+                expect.stringContaining("fCtx=")
+            );
+
+            const calledUrl = historySpy.mock.calls[0]?.[2] as string;
+            expect(calledUrl).toContain("https://example.com/test");
+            expect(calledUrl).toContain("fCtx=");
+        });
+
+        it("should use provided URL instead of window.location.href", () => {
+            const customUrl = "https://custom.com/path";
+            const context: FrakContext = { r: mockAddress };
+
+            FrakContextManager.replaceUrl({ url: customUrl, context });
+
+            const historySpy = vi.mocked(window.history.replaceState);
+            const calledUrl = historySpy.mock.calls[0]?.[2] as string;
+
+            expect(calledUrl).toContain("https://custom.com/path");
+            expect(calledUrl).not.toContain("https://example.com/page");
+        });
+
+        it("should remove fCtx when context is null", () => {
+            const url = "https://example.com/test?fCtx=existing";
+
+            FrakContextManager.replaceUrl({ url, context: null });
+
+            const historySpy = vi.mocked(window.history.replaceState);
+            expect(historySpy).toHaveBeenCalledTimes(1);
+
+            const calledUrl = historySpy.mock.calls[0]?.[2] as string;
+            expect(calledUrl).not.toContain("fCtx=");
+        });
+
+        it("should not call replaceState when context has no referrer", () => {
+            const url = "https://example.com/test";
+            const context: Partial<FrakContext> = {};
+
+            FrakContextManager.replaceUrl({ url, context });
+
+            const historySpy = vi.mocked(window.history.replaceState);
+            expect(historySpy).not.toHaveBeenCalled();
+        });
+
+        it("should handle missing window gracefully", () => {
+            // Remove window.location to simulate missing window
+            Object.defineProperty(window, "location", {
+                writable: true,
+                value: undefined,
+            });
+
+            const url = "https://example.com/test";
+            const context: FrakContext = { r: mockAddress };
+
+            // Should not throw error
+            expect(() => {
+                FrakContextManager.replaceUrl({ url, context });
+            }).not.toThrow();
+
+            const historySpy = vi.mocked(window.history.replaceState);
+            expect(historySpy).not.toHaveBeenCalled();
+            expect(consoleErrorSpy).toHaveBeenCalledWith(
+                "No window found, can't update context"
+            );
+        });
+    });
+});

package/src/utils/FrakContext.ts

@@ -67,7 +67,10 @@ function parse({ url }: { url: string }) {
 function update({
     url,
     context,
-}: { url?: string; context: Partial<FrakContext> }) {
+}: {
+    url?: string;
+    context: Partial<FrakContext>;
+}) {
     if (!url) return null;
 
     // Parse the current context
@@ -111,7 +114,10 @@ function remove(url: string) {
 function replaceUrl({
     url: baseUrl,
     context,
-}: { url?: string; context: Partial<FrakContext> | null }) {
+}: {
+    url?: string;
+    context: Partial<FrakContext> | null;
+}) {
     // If no window here early exit
     if (!window.location?.href || typeof window === "undefined") {
         console.error("No window found, can't update context");

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