@frak-labs/core-sdk 0.1.0-beta.afa252b0 → 0.1.0-beta.b0bd1f8a

package/src/utils/sso.test.ts

@@ -0,0 +1,361 @@
+/**
+ * Tests for SSO URL generation utility
+ * Tests generateSsoUrl and compressed parameter formatting
+ */
+
+import { vi } from "vitest";
+
+// Mock compression functions
+vi.mock("./compression/compress", () => ({
+    compressJsonToB64: vi.fn((data: unknown) => {
+        // Return base64url-like string for testing
+        return `compressed_${JSON.stringify(data)}`;
+    }),
+}));
+
+import type { Hex } from "viem";
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import type { PrepareSsoParamsType } from "../types";
+import { compressJsonToB64 } from "./compression/compress";
+import { generateSsoUrl } from "./sso";
+
+describe("generateSsoUrl", () => {
+    const mockProductId =
+        "0x1234567890123456789012345678901234567890123456789012345678901234" as Hex;
+    const walletUrl = "https://wallet.frak.id";
+
+    describe("basic URL generation", () => {
+        it("should generate SSO URL with basic params", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "Test App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("https://wallet.frak.id/sso");
+            expect(result).toContain("?p=");
+        });
+
+        it("should include compressed parameters in URL", () => {
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+            const name = "My App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("?p=compressed_");
+            expect(compressJsonToB64).toHaveBeenCalled();
+        });
+
+        it("should set /sso pathname", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            const url = new URL(result);
+            expect(url.pathname).toBe("/sso");
+        });
+
+        it("should preserve wallet base URL", () => {
+            const customWalletUrl = "https://custom-wallet.com";
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            const result = generateSsoUrl(
+                customWalletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("https://custom-wallet.com/sso");
+        });
+    });
+
+    describe("parameter compression format", () => {
+        it("should compress params with name and productId", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "Test App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    p: mockProductId,
+                    m: expect.objectContaining({
+                        n: name,
+                    }),
+                })
+            );
+        });
+
+        it("should include redirectUrl in compressed params", () => {
+            const params: PrepareSsoParamsType = {
+                redirectUrl: "https://example.com/callback",
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    r: "https://example.com/callback",
+                })
+            );
+        });
+
+        it("should include directExit in compressed params", () => {
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    d: true,
+                })
+            );
+        });
+
+        it("should include lang in compressed params", () => {
+            const params: PrepareSsoParamsType = {
+                lang: "fr",
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    l: "fr",
+                })
+            );
+        });
+
+        it("should include custom CSS when provided", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+            const css = "body { color: red; }";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name, css);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        css: "body { color: red; }",
+                    }),
+                })
+            );
+        });
+
+        it("should include metadata logoUrl", () => {
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    logoUrl: "https://example.com/logo.png",
+                },
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        l: "https://example.com/logo.png",
+                    }),
+                })
+            );
+        });
+
+        it("should include metadata homepageLink", () => {
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    homepageLink: "https://example.com",
+                },
+            };
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        h: "https://example.com",
+                    }),
+                })
+            );
+        });
+
+        it("should include all metadata fields together", () => {
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    logoUrl: "https://example.com/logo.png",
+                    homepageLink: "https://example.com",
+                },
+            };
+            const name = "Full App";
+            const css = "body { background: blue; }";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name, css);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: {
+                        n: "Full App",
+                        css: "body { background: blue; }",
+                        l: "https://example.com/logo.png",
+                        h: "https://example.com",
+                    },
+                })
+            );
+        });
+    });
+
+    describe("full parameter combinations", () => {
+        it("should handle all parameters together", () => {
+            const params: PrepareSsoParamsType = {
+                redirectUrl: "https://example.com/callback",
+                directExit: false,
+                lang: "fr",
+                metadata: {
+                    logoUrl: "https://example.com/logo.png",
+                    homepageLink: "https://example.com/home",
+                },
+            };
+            const name = "Complete App";
+            const css = "body { margin: 0; }";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name,
+                css
+            );
+
+            expect(result).toContain("https://wallet.frak.id/sso");
+            expect(result).toContain("?p=");
+            expect(compressJsonToB64).toHaveBeenCalledWith({
+                r: "https://example.com/callback",
+                d: false,
+                l: "fr",
+                p: mockProductId,
+                m: {
+                    n: "Complete App",
+                    css: "body { margin: 0; }",
+                    l: "https://example.com/logo.png",
+                    h: "https://example.com/home",
+                },
+            });
+        });
+
+        it("should handle minimal parameters", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "Minimal App";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toBeDefined();
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    p: mockProductId,
+                    m: expect.objectContaining({
+                        n: "Minimal App",
+                    }),
+                })
+            );
+        });
+    });
+
+    describe("edge cases", () => {
+        it("should handle empty name", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "";
+
+            const result = generateSsoUrl(
+                walletUrl,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toBeDefined();
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        n: "",
+                    }),
+                })
+            );
+        });
+
+        it("should handle undefined optional parameters", () => {
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, mockProductId, name, undefined);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    m: expect.objectContaining({
+                        n: "App",
+                        css: undefined,
+                    }),
+                })
+            );
+        });
+
+        it("should handle wallet URL with trailing slash", () => {
+            const walletUrlWithSlash = "https://wallet.frak.id/";
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            const result = generateSsoUrl(
+                walletUrlWithSlash,
+                params,
+                mockProductId,
+                name
+            );
+
+            expect(result).toContain("https://wallet.frak.id/sso");
+        });
+
+        it("should handle different product IDs", () => {
+            const differentProductId =
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdabcdefabcdefabcdefabcd" as Hex;
+            const params: PrepareSsoParamsType = {};
+            const name = "App";
+
+            generateSsoUrl(walletUrl, params, differentProductId, name);
+
+            expect(compressJsonToB64).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    p: differentProductId,
+                })
+            );
+        });
+    });
+});

package/src/utils/sso.ts

@@ -0,0 +1,119 @@
+import type { Hex } from "viem";
+import type { PrepareSsoParamsType, SsoMetadata } from "../types";
+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;
+    productId: Hex;
+};
+
+/**
+ * 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 productId - Product identifier
+ * @param name - Application name
+ * @param css - Optional custom CSS
+ * @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,
+    productId: Hex,
+    name: string,
+    css?: string
+): string {
+    // Build full params with app-specific metadata
+    const fullParams: FullSsoParams = {
+        redirectUrl: params.redirectUrl,
+        directExit: params.directExit,
+        lang: params.lang,
+        productId,
+        metadata: {
+            name,
+            css,
+            logoUrl: params.metadata?.logoUrl,
+            homepageLink: params.metadata?.homepageLink,
+        },
+    };
+
+    // 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) {
+    return {
+        r: params.redirectUrl,
+        d: params.directExit,
+        l: params.lang,
+        p: params.productId,
+        m: {
+            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;
+    // redirect url
+    r?: string;
+    // direct exit
+    d?: boolean;
+    // language
+    l?: "en" | "fr";
+    // product id
+    p: Hex;
+    // metadata
+    m: {
+        // product name
+        n: string;
+        // custom css
+        css?: string;
+        // logo
+        l?: string;
+        // home page link
+        h?: string;
+    };
+};

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");
+}

package/src/utils/trackEvent.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Tests for trackEvent utility function
+ * Tests OpenPanel event tracking wrapper
+ */
+
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
+import type { FrakClient } from "../types";
+import { trackEvent } from "./trackEvent";
+
+describe("trackEvent", () => {
+    let mockClient: FrakClient;
+    let consoleDebugSpy: any;
+
+    beforeEach(() => {
+        // Create mock client
+        mockClient = {
+            openPanel: {
+                track: vi.fn(),
+            },
+        } as unknown as FrakClient;
+
+        // Spy on console.debug
+        consoleDebugSpy = vi
+            .spyOn(console, "debug")
+            .mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        consoleDebugSpy.mockRestore();
+    });
+
+    describe("success cases", () => {
+        it("should track event with client", () => {
+            trackEvent(mockClient, "share_button_clicked");
+
+            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
+                "share_button_clicked",
+                {}
+            );
+        });
+
+        it("should track event with props", () => {
+            const props = { userId: "123", page: "home" };
+            trackEvent(mockClient, "wallet_button_clicked", props);
+
+            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
+                "wallet_button_clicked",
+                props
+            );
+        });
+
+        it("should track share_modal_error event", () => {
+            const props = { error: "Network error" };
+            trackEvent(mockClient, "share_modal_error", props);
+
+            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
+                "share_modal_error",
+                props
+            );
+        });
+
+        it("should track user_referred event", () => {
+            trackEvent(mockClient, "user_referred");
+
+            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
+                "user_referred",
+                {}
+            );
+        });
+    });
+
+    describe("without client", () => {
+        it("should not throw when client is undefined", () => {
+            expect(() => {
+                trackEvent(undefined, "share_button_clicked");
+            }).not.toThrow();
+        });
+
+        it("should log debug message when client is undefined", () => {
+            trackEvent(undefined, "wallet_button_clicked");
+
+            expect(consoleDebugSpy).toHaveBeenCalledWith(
+                "[Frak] No client provided, skipping event tracking"
+            );
+        });
+
+        it("should not call track when client is undefined", () => {
+            const trackMock = vi.fn();
+            const undefinedClient = undefined;
+
+            trackEvent(undefinedClient, "share_button_clicked");
+
+            expect(trackMock).not.toHaveBeenCalled();
+        });
+    });
+
+    describe("error handling", () => {
+        it("should catch and log errors from track()", () => {
+            const error = new Error("Track failed");
+            mockClient.openPanel = {
+                track: vi.fn().mockImplementation(() => {
+                    throw error;
+                }),
+            } as any;
+
+            expect(() => {
+                trackEvent(mockClient, "share_button_clicked");
+            }).not.toThrow();
+
+            expect(consoleDebugSpy).toHaveBeenCalledWith(
+                "[Frak] Failed to track event:",
+                "share_button_clicked",
+                error
+            );
+        });
+
+        it("should not throw when openPanel is undefined", () => {
+            const clientWithoutPanel = {} as FrakClient;
+
+            expect(() => {
+                trackEvent(clientWithoutPanel, "wallet_button_clicked");
+            }).not.toThrow();
+        });
+    });
+
+    describe("edge cases", () => {
+        it("should handle empty props object", () => {
+            trackEvent(mockClient, "share_button_clicked", {});
+
+            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
+                "share_button_clicked",
+                {}
+            );
+        });
+
+        it("should handle complex props object", () => {
+            const complexProps = {
+                userId: "123",
+                metadata: {
+                    page: "home",
+                    section: "header",
+                },
+                tags: ["tag1", "tag2"],
+                timestamp: Date.now(),
+            };
+
+            trackEvent(mockClient, "user_referred", complexProps);
+
+            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
+                "user_referred",
+                complexProps
+            );
+        });
+    });
+});