@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.2c88e0f4

package/src/utils/merchantId.ts

@@ -0,0 +1,143 @@
+/**
+ * Merchant ID utilities for auto-fetching from backend
+ */
+
+import { getBackendUrl } from "./backendUrl";
+
+const MERCHANT_ID_STORAGE_KEY = "frak-merchant-id";
+
+/**
+ * Response from the merchant lookup endpoint
+ */
+type MerchantLookupResponse = {
+    merchantId: string;
+    name: string;
+    domain: string;
+};
+
+/**
+ * In-memory cache for merchantId lookups
+ * Persists for the session to avoid repeated API calls
+ */
+let cachedMerchantId: string | undefined;
+let cachePromise: Promise<string | undefined> | undefined;
+
+/**
+ * Fetch merchantId from backend by domain
+ *
+ * @param domain - The domain to lookup (defaults to current hostname)
+ * @param walletUrl - Optional wallet URL to derive backend URL
+ * @returns The merchantId if found, undefined otherwise
+ *
+ * @example
+ * ```ts
+ * const merchantId = await fetchMerchantId("shop.example.com");
+ * if (merchantId) {
+ *     // Use merchantId for tracking
+ * }
+ * ```
+ */
+export async function fetchMerchantId(
+    domain?: string,
+    walletUrl?: string
+): Promise<string | undefined> {
+    // Use in-memory cache if available
+    if (cachedMerchantId) {
+        return cachedMerchantId;
+    }
+
+    // Check sessionStorage (survives page navigations)
+    if (typeof window !== "undefined") {
+        const stored = window.sessionStorage.getItem(MERCHANT_ID_STORAGE_KEY);
+        if (stored) {
+            cachedMerchantId = stored;
+            return stored;
+        }
+    }
+
+    // If a fetch is already in progress, wait for it
+    if (cachePromise) {
+        return cachePromise;
+    }
+
+    // Start the fetch and cache the promise
+    cachePromise = fetchMerchantIdInternal(domain, walletUrl);
+    const result = await cachePromise;
+    cachePromise = undefined;
+    return result;
+}
+
+/**
+ * Internal fetch logic
+ */
+async function fetchMerchantIdInternal(
+    domain?: string,
+    walletUrl?: string
+): Promise<string | undefined> {
+    const targetDomain =
+        domain ??
+        (typeof window !== "undefined" ? window.location.hostname : "");
+    if (!targetDomain) {
+        return undefined;
+    }
+
+    try {
+        const backendUrl = getBackendUrl(walletUrl);
+        const response = await fetch(
+            `${backendUrl}/user/merchant/resolve?domain=${encodeURIComponent(targetDomain)}`
+        );
+
+        if (!response.ok) {
+            console.warn(
+                `[Frak SDK] Merchant lookup failed for domain ${targetDomain}: ${response.status}`
+            );
+            return undefined;
+        }
+
+        const data = (await response.json()) as MerchantLookupResponse;
+        cachedMerchantId = data.merchantId;
+        // Persist to sessionStorage so it survives page navigations
+        if (typeof window !== "undefined") {
+            window.sessionStorage.setItem(
+                MERCHANT_ID_STORAGE_KEY,
+                data.merchantId
+            );
+        }
+        return cachedMerchantId;
+    } catch (error) {
+        console.warn("[Frak SDK] Failed to fetch merchantId:", error);
+        return undefined;
+    }
+}
+
+/**
+ * Clear the cached merchantId
+ * Useful for testing or when switching domains
+ */
+export function clearMerchantIdCache(): void {
+    cachedMerchantId = undefined;
+    cachePromise = undefined;
+    if (typeof window !== "undefined") {
+        window.sessionStorage.removeItem(MERCHANT_ID_STORAGE_KEY);
+    }
+}
+
+/**
+ * Get merchantId from config or auto-fetch from backend
+ *
+ * @param config - The SDK config that may contain merchantId
+ * @param walletUrl - Optional wallet URL to derive backend URL
+ * @returns The merchantId if available (from config or fetch), undefined otherwise
+ */
+export async function resolveMerchantId(
+    config: { metadata?: { merchantId?: string } },
+    walletUrl?: string
+): Promise<string | undefined> {
+    // First, check config
+    if (config.metadata?.merchantId) {
+        return config.metadata.merchantId;
+    }
+
+    // Otherwise, try to fetch from backend
+    return fetchMerchantId(undefined, walletUrl);
+}

package/src/utils/sso.ts

@@ -0,0 +1,127 @@
+import type { Hex } from "viem";
+import type { PrepareSsoParamsType, SsoMetadata } from "../types";
+import { getClientId } from "./clientId";
+import { compressJsonToB64 } from "./compression/compress";
+
+export type AppSpecificSsoMetadata = SsoMetadata & {
+    name: string;
+    css?: string;
+};
+
+/**
+ * The full SSO params that will be used for compression
+ */
+export type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
+    metadata: AppSpecificSsoMetadata;
+    merchantId: string;
+    clientId: string;
+};
+
+/**
+ * Generate SSO URL with compressed parameters
+ * This mirrors the wallet's getOpenSsoLink() function
+ *
+ * @param walletUrl - Base wallet URL (e.g., "https://wallet.frak.id")
+ * @param params - SSO parameters
+ * @param merchantId - Merchant identifier
+ * @param name - Application name
+ * @param css - Optional custom CSS
+ * @param clientId - Optional client identifier (auto-generated if omitted)
+ * @returns Complete SSO URL ready to open in popup or redirect
+ *
+ * @example
+ * ```ts
+ * const ssoUrl = generateSsoUrl(
+ *   "https://wallet.frak.id",
+ *   { metadata: { logoUrl: "..." }, directExit: true },
+ *   "0x123...",
+ *   "My App"
+ * );
+ * // Returns: https://wallet.frak.id/sso?p=<compressed_base64>
+ * ```
+ */
+export function generateSsoUrl(
+    walletUrl: string,
+    params: PrepareSsoParamsType,
+    merchantId: string,
+    name: string,
+    css?: string,
+    clientId?: string
+): string {
+    // Build full params with app-specific metadata
+    const fullParams: FullSsoParams = {
+        redirectUrl: params.redirectUrl,
+        directExit: params.directExit,
+        lang: params.lang,
+        merchantId,
+        metadata: {
+            name,
+            css,
+            logoUrl: params.metadata?.logoUrl,
+            homepageLink: params.metadata?.homepageLink,
+        },
+        clientId: clientId ?? getClientId(),
+    };
+
+    // Compress params to minimal format
+    const compressedParam = ssoParamsToCompressed(fullParams);
+
+    // Encode to base64url
+    const compressedString = compressJsonToB64(compressedParam);
+
+    // Build URL matching wallet's expected format: /sso?p=<compressed>
+    const ssoUrl = new URL(walletUrl);
+    ssoUrl.pathname = "/sso";
+    ssoUrl.searchParams.set("p", compressedString);
+
+    return ssoUrl.toString();
+}
+
+/**
+ * Map full sso params to compressed sso params
+ * @param params
+ */
+function ssoParamsToCompressed(params: FullSsoParams): CompressedSsoData {
+    return {
+        r: params.redirectUrl,
+        cId: params.clientId,
+        d: params.directExit,
+        l: params.lang,
+        m: params.merchantId,
+        md: {
+            n: params.metadata?.name,
+            css: params.metadata?.css,
+            l: params.metadata?.logoUrl,
+            h: params.metadata?.homepageLink,
+        },
+    };
+}
+
+/**
+ * Type of compressed the sso data
+ */
+export type CompressedSsoData = {
+    // Potential id from backend
+    id?: Hex;
+    // Client id
+    cId: string;
+    // redirect url
+    r?: string;
+    // direct exit
+    d?: boolean;
+    // language
+    l?: "en" | "fr";
+    // merchant id
+    m: string;
+    // metadata
+    md: {
+        // merchant name
+        n: string;
+        // custom css
+        css?: string;
+        // logo
+        l?: string;
+        // home page link
+        h?: string;
+    };
+};

package/src/utils/ssoUrlListener.test.ts

@@ -0,0 +1,252 @@
+import type { RpcClient } from "@frak-labs/frame-connector";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
+import type { FrakLifecycleEvent } from "../types";
+import type { IFrameRpcSchema } from "../types/rpc";
+import { setupSsoUrlListener } from "./ssoUrlListener";
+
+describe("setupSsoUrlListener", () => {
+    let mockRpcClient: RpcClient<IFrameRpcSchema, FrakLifecycleEvent>;
+    let mockWaitForConnection: Promise<boolean>;
+    let originalLocation: Location;
+    let originalHistory: History;
+    let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+    let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        // Save original values
+        originalLocation = window.location;
+        originalHistory = window.history;
+
+        // Mock RPC client
+        mockRpcClient = {
+            sendLifecycle: vi.fn(),
+        } as any;
+
+        // Mock console methods
+        consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+        consoleErrorSpy = vi
+            .spyOn(console, "error")
+            .mockImplementation(() => {});
+
+        // Mock history.replaceState
+        window.history.replaceState = vi.fn();
+    });
+
+    afterEach(() => {
+        vi.clearAllMocks();
+        consoleLogSpy.mockRestore();
+        consoleErrorSpy.mockRestore();
+
+        // Restore original values
+        Object.defineProperty(window, "location", {
+            value: originalLocation,
+            writable: true,
+        });
+        Object.defineProperty(window, "history", {
+            value: originalHistory,
+            writable: true,
+        });
+    });
+
+    it("should do nothing when window is undefined", () => {
+        const originalWindow = global.window;
+        // @ts-expect-error - intentionally removing window for test
+        delete global.window;
+
+        setupSsoUrlListener(mockRpcClient, Promise.resolve(true));
+
+        expect(mockRpcClient.sendLifecycle).not.toHaveBeenCalled();
+
+        // Restore window
+        global.window = originalWindow;
+    });
+
+    it("should do nothing when no SSO parameter in URL", () => {
+        Object.defineProperty(window, "location", {
+            value: {
+                href: "https://example.com/test",
+            },
+            writable: true,
+        });
+
+        setupSsoUrlListener(mockRpcClient, Promise.resolve(true));
+
+        expect(mockRpcClient.sendLifecycle).not.toHaveBeenCalled();
+        expect(window.history.replaceState).not.toHaveBeenCalled();
+    });
+
+    it("should forward SSO data to iframe when connection is ready", async () => {
+        const compressedSso = "compressed-sso-data";
+        Object.defineProperty(window, "location", {
+            value: {
+                href: `https://example.com/test?sso=${compressedSso}`,
+            },
+            writable: true,
+        });
+
+        mockWaitForConnection = Promise.resolve(true);
+
+        setupSsoUrlListener(mockRpcClient, mockWaitForConnection);
+
+        await mockWaitForConnection;
+
+        // Wait for promise to resolve
+        await new Promise((resolve) => setTimeout(resolve, 0));
+
+        expect(mockRpcClient.sendLifecycle).toHaveBeenCalledWith({
+            clientLifecycle: "sso-redirect-complete",
+            data: { compressed: compressedSso },
+        });
+
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+            "[SSO URL Listener] Forwarded compressed SSO data to iframe"
+        );
+    });
+
+    it("should clean URL immediately after detecting SSO parameter", async () => {
+        const compressedSso = "compressed-sso-data";
+        const originalUrl = `https://example.com/test?sso=${compressedSso}`;
+        Object.defineProperty(window, "location", {
+            value: {
+                href: originalUrl,
+            },
+            writable: true,
+        });
+
+        mockWaitForConnection = Promise.resolve(true);
+
+        setupSsoUrlListener(mockRpcClient, mockWaitForConnection);
+
+        // URL should be cleaned immediately, before connection resolves
+        expect(window.history.replaceState).toHaveBeenCalledWith(
+            {},
+            "",
+            "https://example.com/test"
+        );
+
+        expect(consoleLogSpy).toHaveBeenCalledWith(
+            "[SSO URL Listener] SSO parameter detected and URL cleaned"
+        );
+    });
+
+    it("should handle connection promise rejection", async () => {
+        const compressedSso = "compressed-sso-data";
+        Object.defineProperty(window, "location", {
+            value: {
+                href: `https://example.com/test?sso=${compressedSso}`,
+            },
+            writable: true,
+        });
+
+        const connectionError = new Error("Connection failed");
+        mockWaitForConnection = Promise.reject(connectionError);
+
+        setupSsoUrlListener(mockRpcClient, mockWaitForConnection);
+
+        await mockWaitForConnection.catch(() => {});
+
+        // Wait for promise to reject
+        await new Promise((resolve) => setTimeout(resolve, 0));
+
+        expect(mockRpcClient.sendLifecycle).not.toHaveBeenCalled();
+        expect(consoleErrorSpy).toHaveBeenCalledWith(
+            "[SSO URL Listener] Failed to forward SSO data:",
+            connectionError
+        );
+    });
+
+    it("should handle URL with multiple parameters", async () => {
+        const compressedSso = "compressed-sso-data";
+        Object.defineProperty(window, "location", {
+            value: {
+                href: `https://example.com/test?param1=value1&sso=${compressedSso}&param2=value2`,
+            },
+            writable: true,
+        });
+
+        mockWaitForConnection = Promise.resolve(true);
+
+        setupSsoUrlListener(mockRpcClient, mockWaitForConnection);
+
+        await mockWaitForConnection;
+        await new Promise((resolve) => setTimeout(resolve, 0));
+
+        expect(mockRpcClient.sendLifecycle).toHaveBeenCalledWith({
+            clientLifecycle: "sso-redirect-complete",
+            data: { compressed: compressedSso },
+        });
+
+        // Should remove only the sso parameter
+        expect(window.history.replaceState).toHaveBeenCalledWith(
+            {},
+            "",
+            "https://example.com/test?param1=value1&param2=value2"
+        );
+    });
+
+    it("should not process empty SSO parameter", () => {
+        Object.defineProperty(window, "location", {
+            value: {
+                href: "https://example.com/test?sso=",
+            },
+            writable: true,
+        });
+
+        setupSsoUrlListener(mockRpcClient, Promise.resolve(true));
+
+        // Empty string is falsy, so it should not process
+        expect(window.history.replaceState).not.toHaveBeenCalled();
+        expect(mockRpcClient.sendLifecycle).not.toHaveBeenCalled();
+    });
+
+    it("should clean URL even if connection fails", async () => {
+        const compressedSso = "compressed-sso-data";
+        Object.defineProperty(window, "location", {
+            value: {
+                href: `https://example.com/test?sso=${compressedSso}`,
+            },
+            writable: true,
+        });
+
+        const connectionError = new Error("Connection failed");
+        mockWaitForConnection = Promise.reject(connectionError);
+
+        setupSsoUrlListener(mockRpcClient, mockWaitForConnection);
+
+        // URL should still be cleaned even if connection fails
+        expect(window.history.replaceState).toHaveBeenCalledWith(
+            {},
+            "",
+            "https://example.com/test"
+        );
+
+        await mockWaitForConnection.catch(() => {});
+        await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    it("should handle URL with hash", () => {
+        const compressedSso = "compressed-sso-data";
+        Object.defineProperty(window, "location", {
+            value: {
+                href: `https://example.com/test?sso=${compressedSso}#section`,
+            },
+            writable: true,
+        });
+
+        setupSsoUrlListener(mockRpcClient, Promise.resolve(true));
+
+        // Should preserve hash when cleaning URL
+        expect(window.history.replaceState).toHaveBeenCalledWith(
+            {},
+            "",
+            "https://example.com/test#section"
+        );
+    });
+});

package/src/utils/ssoUrlListener.ts

@@ -0,0 +1,60 @@
+import type { RpcClient } from "@frak-labs/frame-connector";
+import type { FrakLifecycleEvent } from "../types";
+import type { IFrameRpcSchema } from "../types/rpc";
+
+/**
+ * Listen for SSO redirect with compressed data in URL
+ * Forwards compressed data to iframe via lifecycle event
+ * Cleans URL immediately after detection
+ *
+ * Performance: One-shot URL check, no polling, no re-renders
+ *
+ * @param rpcClient - RPC client instance to send lifecycle events
+ * @param waitForConnection - Promise that resolves when iframe is connected
+ */
+export function setupSsoUrlListener(
+    rpcClient: RpcClient<IFrameRpcSchema, FrakLifecycleEvent>,
+    waitForConnection: Promise<boolean>
+): void {
+    if (typeof window === "undefined") {
+        return;
+    }
+
+    // One-shot URL check - no need for MutationObserver or polling
+    const url = new URL(window.location.href);
+    const compressedSso = url.searchParams.get("sso");
+
+    // Early return if no SSO parameter
+    if (!compressedSso) {
+        return;
+    }
+
+    // Forward compressed data directly to iframe (no decompression on SDK side)
+    // Iframe will decompress and process
+    waitForConnection
+        .then(() => {
+            // Send lifecycle event with compressed string
+            // This is a one-way notification, no response expected
+            rpcClient.sendLifecycle({
+                clientLifecycle: "sso-redirect-complete",
+                data: { compressed: compressedSso },
+            });
+
+            console.log(
+                "[SSO URL Listener] Forwarded compressed SSO data to iframe"
+            );
+        })
+        .catch((error) => {
+            console.error(
+                "[SSO URL Listener] Failed to forward SSO data:",
+                error
+            );
+        });
+
+    // Clean URL immediately to prevent exposure in browser history
+    // Use replaceState to avoid navigation/re-render
+    url.searchParams.delete("sso");
+    window.history.replaceState({}, "", url.toString());
+
+    console.log("[SSO URL Listener] SSO parameter detected and URL cleaned");
+}