@frak-labs/core-sdk 0.0.19 → 0.1.0-beta.00226d62

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

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

package/src/utils/trackEvent.ts

@@ -0,0 +1,26 @@
+import type { FrakClient } from "../types";
+
+export type FrakEvent =
+    | "share_button_clicked"
+    | "wallet_button_clicked"
+    | "share_modal_error"
+    | "user_referred";
+
+type EventProps = Record<string, unknown>;
+
+export function trackEvent(
+    client: FrakClient | undefined,
+    event: FrakEvent,
+    props: EventProps = {}
+): void {
+    if (!client) {
+        console.debug("[Frak] No client provided, skipping event tracking");
+        return;
+    }
+
+    try {
+        client.openPanel?.track(event, props);
+    } catch (e) {
+        console.debug("[Frak] Failed to track event:", event, e);
+    }
+}