@frak-labs/core-sdk 0.2.0 → 0.2.1

package/src/utils/FrakContext.test.ts

@@ -1,8 +1,3 @@
-/**
- * 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 {
@@ -13,7 +8,7 @@ import {
     it,
     vi,
 } from "../../tests/vitest-fixtures";
-import type { FrakContext } from "../types";
+import type { FrakContextV1, FrakContextV2 } from "../types";
 import { FrakContextManager } from "./FrakContext";
 
 describe("FrakContextManager", () => {
@@ -29,244 +24,316 @@ describe("FrakContextManager", () => {
         consoleErrorSpy.mockRestore();
     });
 
-    describe("compress", () => {
-        it("should compress context with referrer address", () => {
-            const context: Partial<FrakContext> = {
-                r: "0x1234567890123456789012345678901234567890" as Address,
-            };
+    describe("V2 context", () => {
+        const v2Context: FrakContextV2 = {
+            v: 2,
+            c: "test-client-id-uuid",
+            m: "merchant-uuid-1234",
+            t: 1709654400,
+        };
+
+        describe("compress", () => {
+            it("should compress v2 context with all fields", () => {
+                const result = FrakContextManager.compress(v2Context);
+
+                expect(result).toBeDefined();
+                expect(typeof result).toBe("string");
+                expect(result?.length).toBeGreaterThan(0);
+                expect(result).not.toMatch(/[+/=]/);
+            });
 
-            const result = FrakContextManager.compress(context);
+            it("should return undefined when v2 context is missing clientId", () => {
+                const partial = { v: 2 as const, m: "m", t: 123 };
+                const result = FrakContextManager.compress(
+                    partial as FrakContextV2
+                );
+                expect(result).toBeUndefined();
+            });
 
-            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 v2 context is missing merchantId", () => {
+                const partial = { v: 2 as const, c: "c", t: 123 };
+                const result = FrakContextManager.compress(
+                    partial as FrakContextV2
+                );
+                expect(result).toBeUndefined();
+            });
 
-        it("should return undefined when context has no referrer", () => {
-            const context: Partial<FrakContext> = {};
+            it("should return undefined when v2 context is missing timestamp", () => {
+                const partial = { v: 2 as const, c: "c", m: "m" };
+                const result = FrakContextManager.compress(
+                    partial as FrakContextV2
+                );
+                expect(result).toBeUndefined();
+            });
+        });
 
-            const result = FrakContextManager.compress(context);
+        describe("decompress", () => {
+            it("should round-trip compress and decompress v2 context", () => {
+                const compressed = FrakContextManager.compress(v2Context);
+                const decompressed = FrakContextManager.decompress(compressed);
 
-            expect(result).toBeUndefined();
+                expect(decompressed).toEqual(v2Context);
+            });
         });
 
-        it("should return undefined when context is undefined", () => {
-            const result = FrakContextManager.compress(undefined);
+        describe("parse", () => {
+            it("should parse URL with v2 fCtx parameter", () => {
+                const compressed = FrakContextManager.compress(v2Context);
+                const url = `https://example.com?fCtx=${compressed}`;
 
-            expect(result).toBeUndefined();
+                const result = FrakContextManager.parse({ url });
+
+                expect(result).toBeDefined();
+                expect(result).toHaveProperty("v", 2);
+                const v2 = result as FrakContextV2;
+                expect(v2.c).toBe("test-client-id-uuid");
+                expect(v2.m).toBe("merchant-uuid-1234");
+                expect(v2.t).toBe(1709654400);
+            });
         });
 
-        it("should handle compression errors gracefully", () => {
-            const invalidContext = {
-                r: "invalid-address" as Address,
-            };
+        describe("update", () => {
+            it("should add v2 fCtx to URL", () => {
+                const url = "https://example.com";
 
-            const result = FrakContextManager.compress(invalidContext);
+                const result = FrakContextManager.update({
+                    url,
+                    context: v2Context,
+                });
 
-            expect(consoleErrorSpy).toHaveBeenCalled();
-            expect(result).toBeUndefined();
-        });
-    });
+                expect(result).toBeDefined();
+                expect(result).toContain("fCtx=");
+                expect(result).toContain("https://example.com");
 
-    describe("decompress", () => {
-        it("should decompress valid base64url context", () => {
-            // First compress a context
-            const originalContext: FrakContext = {
-                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
-            };
-            const compressed = FrakContextManager.compress(originalContext);
+                const parsed = FrakContextManager.parse({ url: result! });
+                expect(parsed).toEqual(v2Context);
+            });
 
-            // Then decompress it
-            const result = FrakContextManager.decompress(compressed);
+            it("should preserve other URL parameters", () => {
+                const url = "https://example.com?foo=bar&baz=qux";
 
-            expect(result).toBeDefined();
-            expect(result?.r).toBe(
-                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
-            );
+                const result = FrakContextManager.update({
+                    url,
+                    context: v2Context,
+                });
+
+                expect(result).toContain("foo=bar");
+                expect(result).toContain("baz=qux");
+                expect(result).toContain("fCtx=");
+            });
         });
+    });
 
-        it("should return undefined for empty string", () => {
-            const result = FrakContextManager.decompress("");
+    describe("V1 backward compatibility", () => {
+        describe("compress", () => {
+            it("should compress context with referrer address", () => {
+                const context: FrakContextV1 = {
+                    r: "0x1234567890123456789012345678901234567890" as Address,
+                };
 
-            expect(result).toBeUndefined();
-        });
+                const result = FrakContextManager.compress(context);
 
-        it("should return undefined for undefined input", () => {
-            const result = FrakContextManager.decompress(undefined);
+                expect(result).toBeDefined();
+                expect(typeof result).toBe("string");
+                expect(result?.length).toBeGreaterThan(0);
+                expect(result).not.toMatch(/[+/=]/);
+            });
 
-            expect(result).toBeUndefined();
-        });
+            it("should return undefined when context has no referrer", () => {
+                const context = {} as FrakContextV1;
 
-        it("should handle decompression errors gracefully", () => {
-            const result = FrakContextManager.decompress(
-                "invalid-base64url!@#"
-            );
+                const result = FrakContextManager.compress(context);
 
-            expect(consoleErrorSpy).toHaveBeenCalled();
-            expect(result).toBeUndefined();
-        });
+                expect(result).toBeUndefined();
+            });
 
-        it("should round-trip compress and decompress", () => {
-            const original: FrakContext = {
-                r: "0x1234567890123456789012345678901234567890" as Address,
-            };
+            it("should return undefined when context is undefined", () => {
+                const result = FrakContextManager.compress(undefined);
 
-            const compressed = FrakContextManager.compress(original);
-            const decompressed = FrakContextManager.decompress(compressed);
+                expect(result).toBeUndefined();
+            });
 
-            expect(decompressed).toEqual(original);
+            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("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}`;
+        describe("decompress", () => {
+            it("should decompress valid v1 base64url context", () => {
+                const originalContext: FrakContextV1 = {
+                    r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+                };
+                const compressed = FrakContextManager.compress(originalContext);
 
-            const result = FrakContextManager.parse({ url });
+                const result = FrakContextManager.decompress(compressed);
 
-            expect(result).toBeDefined();
-            expect(result?.r).toBe(
-                "0x1234567890123456789012345678901234567890"
-            );
-        });
+                expect(result).toBeDefined();
+                expect((result as FrakContextV1).r).toBe(
+                    "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+                );
+            });
 
-        it("should return null for URL without fCtx parameter", () => {
-            const url = "https://example.com?other=param";
+            it("should return undefined for empty string", () => {
+                const result = FrakContextManager.decompress("");
 
-            const result = FrakContextManager.parse({ url });
+                expect(result).toBeUndefined();
+            });
 
-            expect(result).toBeNull();
-        });
+            it("should return undefined for undefined input", () => {
+                const result = FrakContextManager.decompress(undefined);
 
-        it("should return null for empty URL", () => {
-            const result = FrakContextManager.parse({ url: "" });
+                expect(result).toBeUndefined();
+            });
 
-            expect(result).toBeNull();
-        });
+            it("should handle decompression errors gracefully", () => {
+                const result = FrakContextManager.decompress(
+                    "invalid-base64url!@#"
+                );
 
-        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`;
+                expect(consoleErrorSpy).toHaveBeenCalled();
+                expect(result).toBeUndefined();
+            });
 
-            const result = FrakContextManager.parse({ url });
+            it("should round-trip compress and decompress v1", () => {
+                const original: FrakContextV1 = {
+                    r: "0x1234567890123456789012345678901234567890" as Address,
+                };
 
-            expect(result).toBeDefined();
-            expect(result?.r).toBe(
-                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
-            );
+                const compressed = FrakContextManager.compress(original);
+                const decompressed = FrakContextManager.decompress(compressed);
+
+                expect(decompressed).toEqual(original);
+            });
         });
 
-        it("should return undefined for malformed fCtx parameter", () => {
-            // Use a string that will fail base64url decoding
-            const url = "https://example.com?fCtx=!!!invalid!!!";
+        describe("parse", () => {
+            it("should parse URL with v1 fCtx parameter", () => {
+                const context: FrakContextV1 = {
+                    r: "0x1234567890123456789012345678901234567890" as Address,
+                };
+                const compressed = FrakContextManager.compress(context);
+                const url = `https://example.com?fCtx=${compressed}`;
 
-            const result = FrakContextManager.parse({ url });
+                const result = FrakContextManager.parse({ url });
 
-            // Should handle the error and return undefined
-            expect(result).toBeUndefined();
-        });
-    });
+                expect(result).toBeDefined();
+                expect((result as FrakContextV1).r).toBe(
+                    "0x1234567890123456789012345678901234567890"
+                );
+            });
 
-    describe("update", () => {
-        it("should add fCtx to URL without existing context", () => {
-            const url = "https://example.com";
-            const context: FrakContext = {
-                r: "0x1234567890123456789012345678901234567890" as Address,
-            };
+            it("should return null for URL without fCtx parameter", () => {
+                const url = "https://example.com?other=param";
 
-            const result = FrakContextManager.update({ url, context });
+                const result = FrakContextManager.parse({ url });
 
-            expect(result).toBeDefined();
-            expect(result).toContain("fCtx=");
-            expect(result).toContain("https://example.com");
-        });
+                expect(result).toBeNull();
+            });
 
-        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}`;
+            it("should return null for empty URL", () => {
+                const result = FrakContextManager.parse({ url: "" });
 
-            const newContext: FrakContext = {
-                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
-            };
+                expect(result).toBeNull();
+            });
 
-            const result = FrakContextManager.update({
-                url,
-                context: newContext,
+            it("should parse URL with multiple parameters", () => {
+                const context: FrakContextV1 = {
+                    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 as FrakContextV1).r).toBe(
+                    "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+                );
             });
 
-            expect(result).toBeDefined();
-            expect(result).toContain("fCtx=");
+            it("should return undefined for malformed fCtx parameter", () => {
+                const url = "https://example.com?fCtx=!!!invalid!!!";
 
-            // Parse the result and check it has the new referrer
-            const parsedResult = FrakContextManager.parse({ url: result! });
-            expect(parsedResult?.r).toBe(
-                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
-            );
+                const result = FrakContextManager.parse({ url });
+
+                expect(result).toBeUndefined();
+            });
         });
 
-        it("should return null when URL is undefined", () => {
-            const context: FrakContext = {
-                r: "0x1234567890123456789012345678901234567890" as Address,
-            };
+        describe("update", () => {
+            it("should add v1 fCtx to URL without existing context", () => {
+                const url = "https://example.com";
+                const context: FrakContextV1 = {
+                    r: "0x1234567890123456789012345678901234567890" as Address,
+                };
 
-            const result = FrakContextManager.update({
-                url: undefined,
-                context,
+                const result = FrakContextManager.update({ url, context });
+
+                expect(result).toBeDefined();
+                expect(result).toContain("fCtx=");
+                expect(result).toContain("https://example.com");
             });
 
-            expect(result).toBeNull();
-        });
+            it("should return null when URL is undefined", () => {
+                const context: FrakContextV1 = {
+                    r: "0x1234567890123456789012345678901234567890" as Address,
+                };
 
-        it("should return null when context has no referrer", () => {
-            const url = "https://example.com";
-            const context: Partial<FrakContext> = {};
+                const result = FrakContextManager.update({
+                    url: undefined,
+                    context,
+                });
 
-            const result = FrakContextManager.update({ url, context });
+                expect(result).toBeNull();
+            });
 
-            expect(result).toBeNull();
-        });
+            it("should return null when context has no data", () => {
+                const url = "https://example.com";
+                // Runtime robustness: invalid object shape should return null.
+                const context = {} as any;
 
-        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 });
 
-            const result = FrakContextManager.update({ url, context });
+                expect(result).toBeNull();
+            });
 
-            expect(result).toContain("foo=bar");
-            expect(result).toContain("baz=qux");
-            expect(result).toContain("fCtx=");
-        });
+            it("should preserve other URL parameters", () => {
+                const url = "https://example.com?foo=bar&baz=qux";
+                const context: FrakContextV1 = {
+                    r: "0x1234567890123456789012345678901234567890" as Address,
+                };
 
-        it("should preserve URL hash", () => {
-            const url = "https://example.com#section";
-            const context: FrakContext = {
-                r: "0x1234567890123456789012345678901234567890" as Address,
-            };
+                const result = FrakContextManager.update({ url, context });
 
-            const result = FrakContextManager.update({ url, context });
+                expect(result).toContain("foo=bar");
+                expect(result).toContain("baz=qux");
+                expect(result).toContain("fCtx=");
+            });
 
-            expect(result).toContain("#section");
-            expect(result).toContain("fCtx=");
+            it("should preserve URL hash", () => {
+                const url = "https://example.com#section";
+                const context: FrakContextV1 = {
+                    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 = {
+            const context: FrakContextV1 = {
                 r: "0x1234567890123456789012345678901234567890" as Address,
             };
             const compressed = FrakContextManager.compress(context);
@@ -279,7 +346,7 @@ describe("FrakContextManager", () => {
         });
 
         it("should preserve other parameters when removing fCtx", () => {
-            const context: FrakContext = {
+            const context: FrakContextV1 = {
                 r: "0x1234567890123456789012345678901234567890" as Address,
             };
             const compressed = FrakContextManager.compress(context);
@@ -316,7 +383,6 @@ describe("FrakContextManager", () => {
             "0x1234567890123456789012345678901234567890" as Address;
 
         beforeEach(() => {
-            // Mock window.location.href
             Object.defineProperty(window, "location", {
                 writable: true,
                 value: {
@@ -324,13 +390,12 @@ describe("FrakContextManager", () => {
                 },
             });
 
-            // Mock window.history using our test utility
             mockWindowHistory(vi);
         });
 
-        it("should update window.location with context", () => {
+        it("should update window.location with v1 context", () => {
             const url = "https://example.com/test";
-            const context: FrakContext = { r: mockAddress };
+            const context: FrakContextV1 = { r: mockAddress };
 
             FrakContextManager.replaceUrl({ url, context });
 
@@ -347,9 +412,30 @@ describe("FrakContextManager", () => {
             expect(calledUrl).toContain("fCtx=");
         });
 
+        it("should update window.location with v2 context", () => {
+            const url = "https://example.com/test";
+            const context: FrakContextV2 = {
+                v: 2,
+                c: "client-id",
+                m: "merchant-id",
+                t: 1709654400,
+            };
+
+            FrakContextManager.replaceUrl({ url, context });
+
+            const historySpy = vi.mocked(window.history.replaceState);
+            expect(historySpy).toHaveBeenCalledTimes(1);
+
+            const calledUrl = historySpy.mock.calls[0]?.[2] as string;
+            expect(calledUrl).toContain("fCtx=");
+
+            const parsed = FrakContextManager.parse({ url: calledUrl });
+            expect(parsed).toEqual(context);
+        });
+
         it("should use provided URL instead of window.location.href", () => {
             const customUrl = "https://custom.com/path";
-            const context: FrakContext = { r: mockAddress };
+            const context: FrakContextV1 = { r: mockAddress };
 
             FrakContextManager.replaceUrl({ url: customUrl, context });
 
@@ -372,9 +458,9 @@ describe("FrakContextManager", () => {
             expect(calledUrl).not.toContain("fCtx=");
         });
 
-        it("should not call replaceState when context has no referrer", () => {
+        it("should not call replaceState when context has no data", () => {
             const url = "https://example.com/test";
-            const context: Partial<FrakContext> = {};
+            const context = {} as FrakContextV1;
 
             FrakContextManager.replaceUrl({ url, context });
 
@@ -383,16 +469,14 @@ describe("FrakContextManager", () => {
         });
 
         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 };
+            const context: FrakContextV1 = { r: mockAddress };
 
-            // Should not throw error
             expect(() => {
                 FrakContextManager.replaceUrl({ url, context });
             }).not.toThrow();