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

package/src/clients/DebugInfo.test.ts

@@ -0,0 +1,418 @@
+/**
+ * Tests for DebugInfoGatherer class
+ * Tests debug information gathering and formatting for error reporting
+ */
+
+import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
+import type { FrakWalletSdkConfig } from "../types";
+import { DebugInfoGatherer } from "./DebugInfo";
+
+describe("DebugInfoGatherer", () => {
+    let mockConfig: FrakWalletSdkConfig;
+    let mockIframe: HTMLIFrameElement;
+    let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        // Create mock config
+        mockConfig = {
+            metadata: {
+                name: "Test App",
+            },
+        };
+
+        // Create mock iframe
+        mockIframe = document.createElement("iframe");
+        mockIframe.src = "https://wallet.frak.id";
+        mockIframe.setAttribute("loading", "lazy");
+        document.body.appendChild(mockIframe);
+
+        // Mock iframe contentDocument
+        Object.defineProperty(mockIframe, "contentDocument", {
+            value: {
+                readyState: "complete",
+            },
+            writable: true,
+        });
+
+        // Mock iframe contentWindow
+        Object.defineProperty(mockIframe, "contentWindow", {
+            value: {},
+            writable: true,
+        });
+
+        // Spy on console.warn
+        consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        consoleWarnSpy.mockRestore();
+        document.body.removeChild(mockIframe);
+        vi.clearAllMocks();
+    });
+
+    describe("constructor", () => {
+        it("should create instance with config and iframe", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            expect(gatherer).toBeInstanceOf(DebugInfoGatherer);
+        });
+
+        it("should create instance without config and iframe", () => {
+            const gatherer = new DebugInfoGatherer();
+
+            expect(gatherer).toBeInstanceOf(DebugInfoGatherer);
+        });
+
+        it("should initialize with null lastRequest and lastResponse", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            // Access private properties through formatDebugInfo output
+            const debugInfo = gatherer.formatDebugInfo("test error");
+            expect(debugInfo).toContain("No Frak request logged");
+            expect(debugInfo).toContain("No Frak response logged");
+        });
+    });
+
+    describe("static empty()", () => {
+        it("should create empty instance", () => {
+            const gatherer = DebugInfoGatherer.empty();
+
+            expect(gatherer).toBeInstanceOf(DebugInfoGatherer);
+        });
+
+        it("should create instance without config or iframe", () => {
+            const gatherer = DebugInfoGatherer.empty();
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("no-config");
+            expect(debugInfo).toContain("not-iframe");
+        });
+    });
+
+    describe("setLastRequest", () => {
+        it("should set last request with timestamp", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+            const mockMessage = {
+                id: 1,
+                method: "test_method",
+                params: [],
+            } as any;
+
+            gatherer.setLastRequest(mockMessage);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+            expect(debugInfo).toContain("Last Request:");
+            expect(debugInfo).not.toContain("No Frak request logged");
+        });
+    });
+
+    describe("setLastResponse", () => {
+        it("should set last response with timestamp", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+            const mockMessage = {
+                id: 1,
+                method: "test_method",
+            } as any;
+            const mockResponse = {
+                id: 1,
+                result: "success",
+            } as any;
+
+            gatherer.setLastResponse(mockMessage, mockResponse);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+            expect(debugInfo).toContain("Last Response:");
+            expect(debugInfo).not.toContain("No Frak response logged");
+        });
+    });
+
+    describe("updateSetupStatus", () => {
+        it("should update setup status to true", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            gatherer.updateSetupStatus(true);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+            expect(debugInfo).toContain("Client Status: setup");
+        });
+
+        it("should update setup status to false", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            gatherer.updateSetupStatus(false);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+            expect(debugInfo).toContain("Client Status: not-setup");
+        });
+    });
+
+    describe("formatDebugInfo", () => {
+        it("should format debug info with all fields", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("Debug Information:");
+            expect(debugInfo).toContain("Timestamp:");
+            expect(debugInfo).toContain("URL:");
+            expect(debugInfo).toContain("Config:");
+            expect(debugInfo).toContain("Navigator Info:");
+            expect(debugInfo).toContain("IFrame Status:");
+            expect(debugInfo).toContain("Last Request:");
+            expect(debugInfo).toContain("Last Response:");
+            expect(debugInfo).toContain("Client Status:");
+            expect(debugInfo).toContain("Error:");
+        });
+
+        it("should format FrakRpcError correctly", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+            const error = new FrakRpcError(
+                RpcErrorCodes.walletNotConnected,
+                "Wallet not connected"
+            );
+
+            const debugInfo = gatherer.formatDebugInfo(error);
+
+            expect(debugInfo).toContain(
+                `FrakRpcError: ${RpcErrorCodes.walletNotConnected} 'Wallet not connected'`
+            );
+        });
+
+        it("should format regular Error correctly", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+            const error = new Error("Network timeout");
+
+            const debugInfo = gatherer.formatDebugInfo(error);
+
+            expect(debugInfo).toContain("Network timeout");
+        });
+
+        it("should format string error correctly", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("String error message");
+
+            expect(debugInfo).toContain("String error message");
+        });
+
+        it("should format unknown error as 'Unknown'", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo(null);
+
+            expect(debugInfo).toContain("Error: Unknown");
+        });
+
+        it("should include encoded URL", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            // URL should be base64 encoded
+            expect(debugInfo).toContain("URL:");
+            const urlMatch = debugInfo.match(/URL: (.+)/);
+            expect(urlMatch).toBeTruthy();
+            if (urlMatch) {
+                // Should be base64 encoded (alphanumeric + =)
+                expect(urlMatch[1]).toMatch(/^[A-Za-z0-9+/=]+$/);
+            }
+        });
+
+        it("should include encoded config when config is provided", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("Config:");
+            expect(debugInfo).not.toContain("no-config");
+        });
+
+        it("should show 'no-config' when config is not provided", () => {
+            const gatherer = new DebugInfoGatherer(undefined, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("Config: no-config");
+        });
+
+        it("should include iframe status when iframe is provided", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("IFrame Status:");
+            expect(debugInfo).not.toContain("not-iframe");
+        });
+
+        it("should show 'not-iframe' when iframe is not provided", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, undefined);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("IFrame Status: not-iframe");
+        });
+
+        it("should include navigator info", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("Navigator Info:");
+            expect(debugInfo).not.toContain("no-navigator");
+        });
+
+        it("should handle iframe without contentDocument", () => {
+            const iframeWithoutDoc = document.createElement("iframe");
+            Object.defineProperty(iframeWithoutDoc, "contentDocument", {
+                value: null,
+                writable: true,
+            });
+            Object.defineProperty(iframeWithoutDoc, "contentWindow", {
+                value: {},
+                writable: true,
+            });
+
+            const gatherer = new DebugInfoGatherer(
+                mockConfig,
+                iframeWithoutDoc
+            );
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("IFrame Status:");
+        });
+
+        it("should handle iframe with incomplete readyState", () => {
+            const iframeIncomplete = document.createElement("iframe");
+            Object.defineProperty(iframeIncomplete, "contentDocument", {
+                value: {
+                    readyState: "loading",
+                },
+                writable: true,
+            });
+            Object.defineProperty(iframeIncomplete, "contentWindow", {
+                value: {},
+                writable: true,
+            });
+
+            const gatherer = new DebugInfoGatherer(
+                mockConfig,
+                iframeIncomplete
+            );
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("IFrame Status:");
+        });
+
+        it("should include last request when set", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+            const mockMessage = {
+                id: 1,
+                method: "test_method",
+                params: [],
+            } as any;
+
+            gatherer.setLastRequest(mockMessage);
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("Last Request:");
+            expect(debugInfo).not.toContain("No Frak request logged");
+        });
+
+        it("should include last response when set", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+            const mockMessage = {
+                id: 1,
+                method: "test_method",
+            } as any;
+            const mockResponse = {
+                id: 1,
+                result: "success",
+            } as any;
+
+            gatherer.setLastResponse(mockMessage, mockResponse);
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("Last Response:");
+            expect(debugInfo).not.toContain("No Frak response logged");
+        });
+
+        it("should show 'No Frak request logged' when no request is set", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("No Frak request logged");
+        });
+
+        it("should show 'No Frak response logged' when no response is set", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            expect(debugInfo).toContain("No Frak response logged");
+        });
+    });
+
+    describe("base64 encoding error handling", () => {
+        it("should handle encoding errors gracefully", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+
+            // Create a circular reference that can't be JSON stringified
+            const circularObj: any = { prop: "value" };
+            circularObj.self = circularObj;
+
+            // Mock base64Encode to throw an error
+            // We can't directly test the private method, but we can test
+            // that formatDebugInfo doesn't throw when encoding fails
+            // by checking that it still produces output
+
+            const debugInfo = gatherer.formatDebugInfo("test error");
+
+            // Should still produce debug info even if encoding fails
+            expect(debugInfo).toContain("Debug Information:");
+        });
+    });
+
+    describe("integration", () => {
+        it("should format complete debug info with all data set", () => {
+            const gatherer = new DebugInfoGatherer(mockConfig, mockIframe);
+            const mockRequest = {
+                id: 1,
+                method: "frak_sendInteraction",
+                params: [],
+            } as any;
+            const mockResponse = {
+                id: 1,
+                result: { delegationId: "123" },
+            } as any;
+            const error = new FrakRpcError(
+                RpcErrorCodes.serverError,
+                "Server error"
+            );
+
+            gatherer.setLastRequest(mockRequest);
+            gatherer.setLastResponse(mockRequest, mockResponse);
+            gatherer.updateSetupStatus(true);
+
+            const debugInfo = gatherer.formatDebugInfo(error);
+
+            expect(debugInfo).toContain("Debug Information:");
+            expect(debugInfo).toContain("Client Status: setup");
+            expect(debugInfo).toContain(
+                `FrakRpcError: ${RpcErrorCodes.serverError} 'Server error'`
+            );
+            expect(debugInfo).not.toContain("No Frak request logged");
+            expect(debugInfo).not.toContain("No Frak response logged");
+        });
+    });
+});

package/src/clients/DebugInfo.ts

@@ -0,0 +1,182 @@
+import {
+    FrakRpcError,
+    type RpcMessage,
+    type RpcResponse,
+} from "@frak-labs/frame-connector";
+import type { FrakWalletSdkConfig } from "../types";
+
+type IframeStatus = {
+    loading: boolean;
+    url: string | null;
+    readyState: number;
+    contentWindow: boolean;
+    isConnected: boolean;
+};
+
+type DebugInfo = {
+    timestamp: string;
+    encodedUrl: string;
+    navigatorInfo: string;
+    encodedConfig: string;
+    iframeStatus: string;
+    lastRequest: string;
+    lastResponse: string;
+    clientStatus: string;
+    error: string;
+};
+
+type NavigatorInfo = {
+    userAgent: string;
+    language: string;
+    onLine: boolean;
+    screenWidth: number;
+    screenHeight: number;
+    pixelRatio: number;
+};
+
+/** @ignore */
+export class DebugInfoGatherer {
+    private config?: FrakWalletSdkConfig;
+    private iframe?: HTMLIFrameElement;
+    private isSetupDone = false;
+    private lastResponse: null | {
+        message: RpcMessage;
+        response: RpcResponse;
+        timestamp: number;
+    } = null;
+    private lastRequest: null | {
+        event: RpcMessage;
+        timestamp: number;
+    } = null;
+
+    constructor(config?: FrakWalletSdkConfig, iframe?: HTMLIFrameElement) {
+        this.config = config;
+        this.iframe = iframe;
+        this.lastRequest = null;
+        this.lastResponse = null;
+    }
+
+    // Update communication logs
+    public setLastResponse(message: RpcMessage, response: RpcResponse) {
+        this.lastResponse = {
+            message,
+            response,
+            timestamp: Date.now(),
+        };
+    }
+    public setLastRequest(event: RpcMessage) {
+        this.lastRequest = { event, timestamp: Date.now() };
+    }
+
+    // Update connection status
+    public updateSetupStatus(status: boolean) {
+        this.isSetupDone = status;
+    }
+
+    private base64Encode(data: object): string {
+        try {
+            return btoa(JSON.stringify(data));
+        } catch (err) {
+            console.warn("Failed to encode debug data", err);
+            return btoa("Failed to encode data");
+        }
+    }
+
+    /**
+     * Extract information from the iframe status
+     */
+    private getIframeStatus(): IframeStatus | null {
+        if (!this.iframe) {
+            return null;
+        }
+        return {
+            loading: this.iframe.hasAttribute("loading"),
+            url: this.iframe.src,
+            readyState: this.iframe.contentDocument?.readyState
+                ? this.iframe.contentDocument.readyState === "complete"
+                    ? 1
+                    : 0
+                : -1,
+            contentWindow: !!this.iframe.contentWindow,
+            isConnected: this.iframe.isConnected,
+        };
+    }
+
+    private getNavigatorInfo(): NavigatorInfo | null {
+        if (!navigator) {
+            return null;
+        }
+        return {
+            userAgent: navigator.userAgent,
+            language: navigator.language,
+            onLine: navigator.onLine,
+            screenWidth: window.screen.width,
+            screenHeight: window.screen.height,
+            pixelRatio: window.devicePixelRatio,
+        };
+    }
+
+    private gatherDebugInfo(error: Error | unknown): DebugInfo {
+        const iframeStatus = this.getIframeStatus();
+        const navigatorInfo = this.getNavigatorInfo();
+
+        // Format the error in a readable format
+        let formattedError = "Unknown";
+        if (error instanceof FrakRpcError) {
+            formattedError = `FrakRpcError: ${error.code} '${error.message}'`;
+        } else if (error instanceof Error) {
+            formattedError = error.message;
+        } else if (typeof error === "string") {
+            formattedError = error;
+        }
+
+        // Craft the debug info
+        const debugInfo: DebugInfo = {
+            timestamp: new Date().toISOString(),
+            encodedUrl: btoa(window.location.href),
+            encodedConfig: this.config
+                ? this.base64Encode(this.config)
+                : "no-config",
+            navigatorInfo: navigatorInfo
+                ? this.base64Encode(navigatorInfo)
+                : "no-navigator",
+            iframeStatus: iframeStatus
+                ? this.base64Encode(iframeStatus)
+                : "not-iframe",
+            lastRequest: this.lastRequest
+                ? this.base64Encode(this.lastRequest)
+                : "No Frak request logged",
+            lastResponse: this.lastResponse
+                ? this.base64Encode(this.lastResponse)
+                : "No Frak response logged",
+            clientStatus: this.isSetupDone ? "setup" : "not-setup",
+            error: formattedError,
+        };
+
+        return debugInfo;
+    }
+
+    public static empty(): DebugInfoGatherer {
+        return new DebugInfoGatherer();
+    }
+
+    /**
+     * Format Frak debug information
+     */
+    public formatDebugInfo(error: Error | unknown | string): string {
+        const debugInfo = this.gatherDebugInfo(error);
+        return `
+  Debug Information:
+  -----------------
+  Timestamp: ${debugInfo.timestamp}
+  URL: ${debugInfo.encodedUrl}
+  Config: ${debugInfo.encodedConfig}
+  Navigator Info: ${debugInfo.navigatorInfo}
+  IFrame Status: ${debugInfo.iframeStatus}
+  Last Request: ${debugInfo.lastRequest}
+  Last Response: ${debugInfo.lastResponse}
+  Client Status: ${debugInfo.clientStatus}
+  Error: ${debugInfo.error}
+  `.trim();
+    }
+}