@frak-labs/core-sdk 0.1.1 → 0.2.0-beta.7898df5b

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

@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { getBackendUrl } from "./backendUrl";
+
+describe("getBackendUrl", () => {
+    const originalWindow = globalThis.window;
+
+    beforeEach(() => {
+        vi.stubGlobal("window", { ...originalWindow });
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    describe("with explicit walletUrl", () => {
+        test("should return localhost backend for localhost:3000", () => {
+            expect(getBackendUrl("https://localhost:3000")).toBe(
+                "http://localhost:3030"
+            );
+        });
+
+        test("should return localhost backend for localhost:3010", () => {
+            expect(getBackendUrl("https://localhost:3010")).toBe(
+                "http://localhost:3030"
+            );
+        });
+
+        test("should return dev backend for wallet-dev.frak.id", () => {
+            expect(getBackendUrl("https://wallet-dev.frak.id")).toBe(
+                "https://backend.gcp-dev.frak.id"
+            );
+        });
+
+        test("should return dev backend for wallet.gcp-dev.frak.id", () => {
+            expect(getBackendUrl("https://wallet.gcp-dev.frak.id")).toBe(
+                "https://backend.gcp-dev.frak.id"
+            );
+        });
+
+        test("should return production backend for wallet.frak.id", () => {
+            expect(getBackendUrl("https://wallet.frak.id")).toBe(
+                "https://backend.frak.id"
+            );
+        });
+
+        test("should return production backend for unknown URLs", () => {
+            expect(getBackendUrl("https://some-other-url.com")).toBe(
+                "https://backend.frak.id"
+            );
+        });
+    });
+
+    describe("with FrakSetup global config", () => {
+        test("should derive from window.FrakSetup.client.config.walletUrl", () => {
+            vi.stubGlobal("window", {
+                FrakSetup: {
+                    client: {
+                        config: {
+                            walletUrl: "https://wallet-dev.frak.id",
+                        },
+                    },
+                },
+            });
+
+            expect(getBackendUrl()).toBe("https://backend.gcp-dev.frak.id");
+        });
+
+        test("should fall back to production when FrakSetup has no walletUrl", () => {
+            vi.stubGlobal("window", {
+                FrakSetup: { client: { config: {} } },
+            });
+
+            expect(getBackendUrl()).toBe("https://backend.frak.id");
+        });
+    });
+
+    describe("fallback", () => {
+        test("should return production URL when no walletUrl and no FrakSetup", () => {
+            vi.stubGlobal("window", {});
+            expect(getBackendUrl()).toBe("https://backend.frak.id");
+        });
+    });
+});

package/src/utils/backendUrl.ts

@@ -0,0 +1,62 @@
+/**
+ * Default production backend URL
+ */
+const DEFAULT_BACKEND_URL = "https://backend.frak.id";
+
+/**
+ * Check if wallet URL is local development (port 3000 or 3010)
+ */
+function isLocalDevelopment(walletUrl: string): boolean {
+    return (
+        walletUrl.includes("localhost:3000") ||
+        walletUrl.includes("localhost:3010")
+    );
+}
+
+/**
+ * Derive backend URL from wallet URL
+ * Maps wallet URLs to their corresponding backend URLs
+ */
+function deriveBackendUrl(walletUrl: string): string {
+    if (isLocalDevelopment(walletUrl)) {
+        return "http://localhost:3030";
+    }
+    // Dev environment
+    if (
+        walletUrl.includes("wallet-dev.frak.id") ||
+        walletUrl.includes("wallet.gcp-dev.frak.id")
+    ) {
+        return "https://backend.gcp-dev.frak.id";
+    }
+    // Production
+    return DEFAULT_BACKEND_URL;
+}
+
+/**
+ * Get the backend URL for API calls
+ * Tries to derive from SDK config, falls back to production
+ *
+ * @param walletUrl - Optional wallet URL to derive from (overrides global config)
+ */
+export function getBackendUrl(walletUrl?: string): string {
+    // If explicit walletUrl provided, derive from it
+    if (walletUrl) {
+        return deriveBackendUrl(walletUrl);
+    }
+
+    // Try to get from global FrakSetup config
+    if (typeof window !== "undefined") {
+        const configWalletUrl = (
+            window as {
+                FrakSetup?: { client?: { config?: { walletUrl?: string } } };
+            }
+        ).FrakSetup?.client?.config?.walletUrl;
+
+        if (configWalletUrl) {
+            return deriveBackendUrl(configWalletUrl);
+        }
+    }
+
+    // Fallback to production
+    return DEFAULT_BACKEND_URL;
+}

package/src/utils/clientId.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getClientId } from "./clientId";
+
+describe("clientId", () => {
+    beforeEach(() => {
+        // Clear localStorage before each test
+        localStorage.clear();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe("getClientId", () => {
+        it("should generate and store a new client ID when none exists", () => {
+            const clientId = getClientId();
+
+            expect(clientId).toBeDefined();
+            expect(clientId).toMatch(
+                /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+            );
+            expect(localStorage.getItem("frak-client-id")).toBe(clientId);
+        });
+
+        it("should return existing client ID from localStorage", () => {
+            const existingId = "existing-uuid-1234";
+            localStorage.setItem("frak-client-id", existingId);
+
+            const clientId = getClientId();
+
+            expect(clientId).toBe(existingId);
+        });
+
+        it("should generate consistent UUIDs", () => {
+            const id1 = getClientId();
+            const id2 = getClientId();
+
+            expect(id1).toBe(id2);
+        });
+    });
+});

package/src/utils/clientId.ts

@@ -0,0 +1,43 @@
+/**
+ * Client ID utilities for anonymous tracking
+ * Generates and persists a UUID fingerprint for referral attribution
+ */
+
+const CLIENT_ID_KEY = "frak-client-id";
+
+/**
+ * Generate a UUID v4
+ * Uses crypto.randomUUID if available, otherwise falls back to a manual implementation
+ */
+function generateUUID(): string {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for older browsers
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+
+/**
+ * Get the client ID from localStorage, creating one if it doesn't exist
+ * @returns The client ID (UUID format)
+ */
+export function getClientId(): string {
+    if (typeof window === "undefined" || !window.localStorage) {
+        // SSR or no localStorage - generate ephemeral ID
+        console.warn(
+            "[Frak SDK] No Window / localStorage available to save the clientId"
+        );
+        return generateUUID();
+    }
+
+    let clientId = localStorage.getItem(CLIENT_ID_KEY);
+    if (!clientId) {
+        clientId = generateUUID();
+        localStorage.setItem(CLIENT_ID_KEY, clientId);
+    }
+    return clientId;
+}

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

@@ -7,7 +7,7 @@ import { vi } from "vitest";
 
 // Mock the frame-connector module - must be before imports
 vi.mock("@frak-labs/frame-connector", () => ({
-    compressJson: vi.fn((data: unknown) => {
+    jsonEncode: vi.fn((data: unknown) => {
         // Simple mock: convert JSON to Uint8Array
         const jsonString = JSON.stringify(data);
         return new TextEncoder().encode(jsonString);

package/src/utils/compression/compress.ts

@@ -1,4 +1,4 @@
-import { compressJson } from "@frak-labs/frame-connector";
+import { jsonEncode } from "@frak-labs/frame-connector";
 import { base64urlEncode } from "./b64";
 
 /**
@@ -7,5 +7,5 @@ import { base64urlEncode } from "./b64";
  * @ignore
  */
 export function compressJsonToB64(data: unknown): string {
-    return base64urlEncode(compressJson(data));
+    return base64urlEncode(jsonEncode(data));
 }

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

@@ -7,15 +7,19 @@ import { vi } from "vitest";
 
 // Mock the frame-connector module - must be before imports
 vi.mock("@frak-labs/frame-connector", () => ({
-    compressJson: vi.fn((data: unknown) => {
+    jsonEncode: 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) => {
+    jsonDecode: vi.fn((data: Uint8Array) => {
         // Simple mock: convert Uint8Array back to JSON
-        const jsonString = new TextDecoder().decode(data);
-        return JSON.parse(jsonString);
+        try {
+            const jsonString = new TextDecoder().decode(data);
+            return JSON.parse(jsonString);
+        } catch {
+            return null;
+        }
     }),
 }));
 

package/src/utils/compression/decompress.ts

@@ -1,4 +1,4 @@
-import { decompressJson } from "@frak-labs/frame-connector";
+import { jsonDecode } from "@frak-labs/frame-connector";
 import { base64urlDecode } from "./b64";
 
 /**
@@ -7,5 +7,5 @@ import { base64urlDecode } from "./b64";
  * @ignore
  */
 export function decompressJsonFromB64<T>(data: string): T | null {
-    return decompressJson(base64urlDecode(data));
+    return jsonDecode<T>(base64urlDecode(data));
 }

package/src/utils/{computeProductId.ts → computeLegacyProductId.ts}

@@ -1,10 +1,10 @@
 import { keccak256, toHex } from "viem";
 
 /**
- * Compute the product id from a domain
+ * Compute the legacy product id from a domain
  * @ignore
  */
-export function computeProductId({ domain }: { domain?: string } = {}) {
+export function computeLegacyProductId({ domain }: { domain?: string } = {}) {
     const effectiveDomain = domain ?? window.location.host;
     const normalizedDomain = effectiveDomain.replace("www.", "");
     return keccak256(toHex(normalizedDomain));

package/src/utils/constants.ts

@@ -2,3 +2,8 @@
  * The backup key for client side backup if needed
  */
 export const BACKUP_KEY = "nexus-wallet-backup";
+
+/**
+ * Deep link scheme for Frak Wallet mobile app
+ */
+export const DEEP_LINK_SCHEME = "frakwallet://";