@frak-labs/core-sdk 0.2.0 → 0.2.1-beta.06c52c98

package/src/utils/FrakContext.ts

@@ -1,20 +1,39 @@
-import { type Address, bytesToHex, hexToBytes } from "viem";
-import type { FrakContext } from "../types";
+import { type Address, bytesToHex, hexToBytes, isAddress } from "viem";
+import type { FrakContext, FrakContextV1, FrakContextV2 } from "../types";
+import { isV2Context } from "../types";
 import { base64urlDecode, base64urlEncode } from "./compression/b64";
+import { compressJsonToB64 } from "./compression/compress";
+import { decompressJsonFromB64 } from "./compression/decompress";
 
 /**
- * The context key
+ * URL parameter key for the Frak referral context
  */
 const contextKey = "fCtx";
 
 /**
- * Compress the current Frak context
- * @param context - The context to be compressed
- * @returns A compressed string containing the Frak context
+ * Compress a Frak context into a URL-safe string.
+ *
+ * - V2 contexts are serialized as compressed JSON (base64url).
+ * - V1 contexts encode the wallet address as raw bytes (base64url).
+ *
+ * @param context - The context to compress (V1 or V2)
+ * @returns A compressed base64url string, or undefined on failure
  */
-function compress(context?: Partial<FrakContext>): string | undefined {
-    if (!context?.r) return;
+function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
+    if (!context) return;
     try {
+        if (isV2Context(context)) {
+            // Runtime validation: all V2 fields must be present and truthy
+            if (!context.c || !context.m || !context.t) return undefined;
+            return compressJsonToB64({
+                v: 2,
+                c: context.c,
+                m: context.m,
+                t: context.t,
+            });
+        }
+
+        // V1 legacy: compress wallet address as raw bytes
         const bytes = hexToBytes(context.r);
         return base64urlEncode(bytes);
     } catch (e) {
@@ -24,15 +43,31 @@ function compress(context?: Partial<FrakContext>): string | 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
+ * Decompress a base64url string back into a Frak context.
+ *
+ * Attempts V2 JSON decompression first, then falls back to V1 raw bytes.
+ *
+ * @param context - The compressed context string
+ * @returns The decompressed FrakContext, or undefined on failure
  */
 function decompress(context?: string): FrakContext | undefined {
     if (!context || context.length === 0) return;
     try {
+        // Try V2 JSON first — V2 payloads are longer than V1's 20-byte address
+        const json = decompressJsonFromB64<FrakContextV2>(context);
+        if (json && typeof json === "object" && json.v === 2) {
+            if (json.c && json.m && json.t) {
+                return { v: 2, c: json.c, m: json.m, t: json.t };
+            }
+            return undefined;
+        }
+
+        // Fall back to V1: raw 20-byte address
         const bytes = base64urlDecode(context);
-        return { r: bytesToHex(bytes, { size: 20 }) as Address };
+        const hex = bytesToHex(bytes, { size: 20 }) as Address;
+        if (isAddress(hex)) {
+            return { r: hex };
+        }
     } catch (e) {
         console.error("Error decompressing Frak context", { e, context });
     }
@@ -40,113 +75,100 @@ function decompress(context?: string): FrakContext | undefined {
 }
 
 /**
- * Parse the current URL into a Frak Context
+ * Parse a URL to extract the Frak referral context from the `fCtx` query parameter.
+ *
  * @param args
- * @param args.url - The url to parse
- * @returns The parsed Frak context
+ * @param args.url - The URL to parse
+ * @returns The parsed FrakContext, or null if absent
  */
-function parse({ url }: { url: string }) {
+function parse({ url }: { url: string }): FrakContext | null | undefined {
     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
+ * Add or replace the `fCtx` query parameter in a URL with the given 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
+ * @param args.url - The URL to update
+ * @param args.context - The context to embed (V1 or V2)
+ * @returns The updated URL string, or null on failure
  */
 function update({
     url,
     context,
 }: {
     url?: string;
-    context: Partial<FrakContext>;
-}) {
+    context: FrakContextV1 | FrakContextV2;
+}): string | null {
     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);
+    const compressedContext = compress(context);
     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
+ * Remove the `fCtx` query parameter from a URL.
+ *
+ * @param url - The URL to strip the context from
+ * @returns The cleaned URL string
  */
-function remove(url: string) {
+function remove(url: string): string {
     const urlObj = new URL(url);
     urlObj.searchParams.delete(contextKey);
     return urlObj.toString();
 }
 
 /**
- * Replace the current url with the given Frak context
+ * Replace the current browser URL with an updated Frak context.
+ *
+ * - If `context` is non-null, embeds it via {@link update}.
+ * - If `context` is null, strips the context via {@link remove}.
+ *
  * @param args
- * @param args.url - The url to update
- * @param args.context - The context to update
+ * @param args.url - Base URL (defaults to `window.location.href`)
+ * @param args.context - Context to set, or null to remove
  */
 function replaceUrl({
     url: baseUrl,
     context,
 }: {
     url?: string;
-    context: Partial<FrakContext> | null;
+    context: FrakContextV1 | FrakContextV2 | 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,
-        });
+        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
+ * Manager for Frak referral context in URLs.
+ *
+ * Handles compression, decompression, URL parsing, and browser history updates
+ * for both V1 (wallet address) and V2 (anonymous clientId) referral contexts.
  */
 export const FrakContextManager = {
     compress,

package/src/utils/backendUrl.test.ts

@@ -15,13 +15,13 @@ describe("getBackendUrl", () => {
     describe("with explicit walletUrl", () => {
         test("should return localhost backend for localhost:3000", () => {
             expect(getBackendUrl("https://localhost:3000")).toBe(
-                "http://localhost:3030"
+                "https://localhost:3030"
             );
         });
 
         test("should return localhost backend for localhost:3010", () => {
             expect(getBackendUrl("https://localhost:3010")).toBe(
-                "http://localhost:3030"
+                "https://localhost:3030"
             );
         });
 

package/src/utils/backendUrl.ts

@@ -19,7 +19,7 @@ function isLocalDevelopment(walletUrl: string): boolean {
  */
 function deriveBackendUrl(walletUrl: string): string {
     if (isLocalDevelopment(walletUrl)) {
-        return "http://localhost:3030";
+        return "https://localhost:3030";
     }
     // Dev environment
     if (

package/src/utils/index.ts

@@ -22,11 +22,7 @@ export {
     createIframe,
     findIframeInOpener,
 } from "./iframeHelper";
-export {
-    clearMerchantIdCache,
-    fetchMerchantId,
-    resolveMerchantId,
-} from "./merchantId";
+export { sdkConfigStore } from "./sdkConfigStore";
 export {
     type AppSpecificSsoMetadata,
     type CompressedSsoData,

package/src/utils/sdkConfigStore.test.ts

@@ -0,0 +1,405 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { sdkConfigStore } from "./sdkConfigStore";
+
+vi.mock("./backendUrl", () => ({
+    getBackendUrl: vi.fn((walletUrl?: string) => {
+        if (walletUrl?.includes("localhost")) {
+            return "http://localhost:3030";
+        }
+        return "https://backend.frak.id";
+    }),
+}));
+
+describe("sdkConfigStore", () => {
+    beforeEach(() => {
+        sdkConfigStore.clearCache();
+        window.sessionStorage.clear();
+        window.localStorage.clear();
+        window.__frakSdkConfig = undefined;
+        vi.clearAllMocks();
+        vi.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe("sdkConfigStore.resolve", () => {
+        it("should fetch from backend when not cached", async () => {
+            const mockResponse = {
+                merchantId: "merchant-123",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result = await sdkConfigStore.resolve("shop.example.com");
+
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=shop.example.com"
+            );
+        });
+
+        it("should return cached response on subsequent calls", async () => {
+            const mockResponse = {
+                merchantId: "merchant-456",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result1 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result1).toEqual(mockResponse);
+
+            const result2 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result2).toEqual(mockResponse);
+
+            expect(global.fetch).toHaveBeenCalledTimes(1);
+        });
+
+        it("should deduplicate concurrent requests", async () => {
+            const mockResponse = {
+                merchantId: "merchant-789",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const [result1, result2, result3] = await Promise.all([
+                sdkConfigStore.resolve("shop.example.com"),
+                sdkConfigStore.resolve("shop.example.com"),
+                sdkConfigStore.resolve("shop.example.com"),
+            ]);
+
+            expect(result1).toEqual(mockResponse);
+            expect(result2).toEqual(mockResponse);
+            expect(result3).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledTimes(1);
+        });
+
+        it("should use window.location.hostname when domain not provided", async () => {
+            const mockResponse = {
+                merchantId: "merchant-default",
+                name: "Test",
+                domain: "example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            Object.defineProperty(window, "location", {
+                value: { hostname: "example.com" },
+                writable: true,
+            });
+
+            const result = await sdkConfigStore.resolve();
+
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=example.com"
+            );
+        });
+
+        it("should return undefined when domain is empty", async () => {
+            global.fetch = vi.fn();
+
+            const result = await sdkConfigStore.resolve("");
+
+            expect(result).toBeUndefined();
+            expect(global.fetch).not.toHaveBeenCalled();
+        });
+
+        it("should handle fetch errors gracefully", async () => {
+            global.fetch = vi
+                .fn()
+                .mockRejectedValueOnce(new Error("Network error"));
+
+            const result = await sdkConfigStore.resolve("shop.example.com");
+
+            expect(result).toBeUndefined();
+            expect(console.warn).toHaveBeenCalledWith(
+                "[Frak SDK] Failed to fetch merchant config:",
+                expect.any(Error)
+            );
+        });
+
+        it("should handle non-ok response (404, 500)", async () => {
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: false,
+                status: 404,
+            });
+
+            const result = await sdkConfigStore.resolve("nonexistent.com");
+
+            expect(result).toBeUndefined();
+            expect(console.warn).toHaveBeenCalledWith(
+                "[Frak SDK] Merchant lookup failed for domain nonexistent.com: 404"
+            );
+        });
+
+        it("should use custom walletUrl to derive backend URL", async () => {
+            const mockResponse = {
+                merchantId: "merchant-local",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result = await sdkConfigStore.resolve(
+                "shop.example.com",
+                "http://localhost:3000"
+            );
+
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                "http://localhost:3030/user/merchant/resolve?domain=shop.example.com"
+            );
+        });
+
+        it("should encode domain in URL query parameter", async () => {
+            const mockResponse = {
+                merchantId: "merchant-encoded",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const domainWithSpecialChars = "shop.example.com?test=1&foo=bar";
+            await sdkConfigStore.resolve(domainWithSpecialChars);
+
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=shop.example.com%3Ftest%3D1%26foo%3Dbar"
+            );
+        });
+
+        it("should write merchantId to sessionStorage as 'frak-merchant-id'", async () => {
+            const mockResponse = {
+                merchantId: "merchant-persisted",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            await sdkConfigStore.resolve("shop.example.com");
+
+            expect(window.sessionStorage.getItem("frak-merchant-id")).toBe(
+                "merchant-persisted"
+            );
+        });
+
+        it("should pass lang parameter to backend when provided", async () => {
+            const mockResponse = {
+                merchantId: "merchant-lang",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            await sdkConfigStore.resolve("shop.example.com", undefined, "fr");
+
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=shop.example.com&lang=fr"
+            );
+        });
+    });
+
+    describe("sdkConfigStore.getMerchantId", () => {
+        it("should return merchantId from resolved config", () => {
+            window.__frakSdkConfig = {
+                isResolved: true,
+                merchantId: "config-merchant-123",
+            };
+
+            const result = sdkConfigStore.getMerchantId();
+
+            expect(result).toBe("config-merchant-123");
+        });
+
+        it("should fall back to sessionStorage", () => {
+            window.__frakSdkConfig = {
+                isResolved: false,
+                merchantId: "",
+            };
+            window.sessionStorage.setItem(
+                "frak-merchant-id",
+                "session-merchant-456"
+            );
+
+            const result = sdkConfigStore.getMerchantId();
+
+            expect(result).toBe("session-merchant-456");
+        });
+
+        it("should return undefined when nothing cached", () => {
+            window.__frakSdkConfig = {
+                isResolved: false,
+                merchantId: "",
+            };
+
+            const result = sdkConfigStore.getMerchantId();
+
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("sdkConfigStore.resolveMerchantId", () => {
+        it("should return merchantId from store without fetch", async () => {
+            window.__frakSdkConfig = {
+                isResolved: true,
+                merchantId: "store-merchant-123",
+            };
+            global.fetch = vi.fn();
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBe("store-merchant-123");
+            expect(global.fetch).not.toHaveBeenCalled();
+        });
+
+        it("should return merchantId from sessionStorage without fetch", async () => {
+            window.__frakSdkConfig = {
+                isResolved: false,
+                merchantId: "",
+            };
+            window.sessionStorage.setItem(
+                "frak-merchant-id",
+                "session-merchant-789"
+            );
+            global.fetch = vi.fn();
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBe("session-merchant-789");
+            expect(global.fetch).not.toHaveBeenCalled();
+        });
+
+        it("should fetch from backend as last resort", async () => {
+            const mockResponse = {
+                merchantId: "fetched-merchant-456",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            Object.defineProperty(window, "location", {
+                value: { hostname: "shop.example.com" },
+                writable: true,
+            });
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBe("fetched-merchant-456");
+            expect(global.fetch).toHaveBeenCalled();
+        });
+
+        it("should return undefined when fetch fails", async () => {
+            global.fetch = vi
+                .fn()
+                .mockRejectedValueOnce(new Error("Network error"));
+
+            Object.defineProperty(window, "location", {
+                value: { hostname: "shop.example.com" },
+                writable: true,
+            });
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("sdkConfigStore.clearCache", () => {
+        it("should clear all caches and allow re-fetching", async () => {
+            const mockResponse = {
+                merchantId: "merchant-clear-test",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValue({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result1 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result1).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledTimes(1);
+
+            sdkConfigStore.clearCache();
+
+            const result2 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result2).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledTimes(2);
+        });
+
+        it("should clear sessionStorage frak-merchant-id", async () => {
+            const mockResponse = {
+                merchantId: "merchant-session-clear",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            await sdkConfigStore.resolve("shop.example.com");
+            expect(window.sessionStorage.getItem("frak-merchant-id")).toBe(
+                "merchant-session-clear"
+            );
+
+            sdkConfigStore.clearCache();
+
+            expect(
+                window.sessionStorage.getItem("frak-merchant-id")
+            ).toBeNull();
+        });
+    });
+});