@frak-labs/core-sdk 0.1.0-beta.afa252b0 → 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

@@ -0,0 +1,158 @@
+import { type Address, bytesToHex, hexToBytes } from "viem";
+import type { FrakContext } from "../types";
+import { base64urlDecode, base64urlEncode } from "./compression/b64";
+
+/**
+ * The context key
+ */
+const contextKey = "fCtx";
+
+/**
+ * Compress the current Frak context
+ * @param context - The context to be compressed
+ * @returns A compressed string containing the Frak context
+ */
+function compress(context?: Partial<FrakContext>): string | undefined {
+    if (!context?.r) return;
+    try {
+        const bytes = hexToBytes(context.r);
+        return base64urlEncode(bytes);
+    } catch (e) {
+        console.error("Error compressing Frak context", { e, context });
+    }
+    return undefined;
+}
+
+/**
+ * Decompress the given Frak context
+ * @param context - The raw context to be decompressed into a `FrakContext`
+ * @returns The decompressed Frak context, or undefined if it fails
+ */
+function decompress(context?: string): FrakContext | undefined {
+    if (!context || context.length === 0) return;
+    try {
+        const bytes = base64urlDecode(context);
+        return { r: bytesToHex(bytes, { size: 20 }) as Address };
+    } catch (e) {
+        console.error("Error decompressing Frak context", { e, context });
+    }
+    return undefined;
+}
+
+/**
+ * Parse the current URL into a Frak Context
+ * @param args
+ * @param args.url - The url to parse
+ * @returns The parsed Frak context
+ */
+function parse({ url }: { url: string }) {
+    if (!url) return null;
+
+    // Check if the url contain the frak context key
+    const urlObj = new URL(url);
+    const frakContext = urlObj.searchParams.get(contextKey);
+    if (!frakContext) return null;
+
+    // Decompress and return it
+    return decompress(frakContext);
+}
+
+/**
+ * Populate the current url with the given Frak context
+ * @param args
+ * @param args.url - The url to update
+ * @param args.context - The context to update
+ * @returns The new url with the Frak context
+ */
+function update({
+    url,
+    context,
+}: {
+    url?: string;
+    context: Partial<FrakContext>;
+}) {
+    if (!url) return null;
+
+    // Parse the current context
+    const currentContext = parse({ url });
+
+    // Merge the current context with the new context
+    const mergedContext = currentContext
+        ? { ...currentContext, ...context }
+        : context;
+
+    // If we don't have a referrer, early exit
+    if (!mergedContext.r) return null;
+
+    // Compress it
+    const compressedContext = compress(mergedContext);
+    if (!compressedContext) return null;
+
+    // Build the new url and return it
+    const urlObj = new URL(url);
+    urlObj.searchParams.set(contextKey, compressedContext);
+    return urlObj.toString();
+}
+
+/**
+ * Remove Frak context from current url
+ * @param url - The url to update
+ * @returns The new url without the Frak context
+ */
+function remove(url: string) {
+    const urlObj = new URL(url);
+    urlObj.searchParams.delete(contextKey);
+    return urlObj.toString();
+}
+
+/**
+ * Replace the current url with the given Frak context
+ * @param args
+ * @param args.url - The url to update
+ * @param args.context - The context to update
+ */
+function replaceUrl({
+    url: baseUrl,
+    context,
+}: {
+    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");
+        return;
+    }
+
+    // If no url, try to use the current one
+    const url = baseUrl ?? window.location.href;
+
+    // Get our new url with the frak context
+    let newUrl: string | null;
+    if (context !== null) {
+        newUrl = update({
+            url,
+            context,
+        });
+    } else {
+        newUrl = remove(url);
+    }
+
+    // If no new url, early exit
+    if (!newUrl) return;
+
+    // Update the url
+    window.history.replaceState(null, "", newUrl.toString());
+}
+
+/**
+ * Export our frak context
+ */
+export const FrakContextManager = {
+    compress,
+    decompress,
+    parse,
+    update,
+    remove,
+    replaceUrl,
+};