@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.4dfea079

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

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,40 @@
+/**
+ * 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
+        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/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);
+    });
+});

package/src/utils/compression/b64.ts

@@ -0,0 +1,29 @@
+/**
+ * Encode a buffer to a base64url encoded string
+ * @param buffer The buffer to encode
+ * @returns The encoded string
+ */
+export function base64urlEncode(buffer: Uint8Array): string {
+    return btoa(Array.from(buffer, (b) => String.fromCharCode(b)).join(""))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+
+/**
+ * Decode a base64url encoded string
+ * @param value The value to decode
+ * @returns The decoded value
+ */
+export function base64urlDecode(value: string): Uint8Array {
+    const m = value.length % 4;
+    return Uint8Array.from(
+        atob(
+            value
+                .replace(/-/g, "+")
+                .replace(/_/g, "/")
+                .padEnd(value.length + (m === 0 ? 0 : 4 - m), "=")
+        ),
+        (c) => c.charCodeAt(0)
+    );
+}