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

package/src/clients/transports/iframeLifecycleManager.test.ts

@@ -0,0 +1,399 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+// Mock dependencies
+vi.mock("@frak-labs/frame-connector", () => ({
+    Deferred: class {
+        promise: Promise<any>;
+        resolve!: (value: any) => void;
+        reject!: (error: any) => void;
+
+        constructor() {
+            this.promise = new Promise((resolve, reject) => {
+                this.resolve = resolve;
+                this.reject = reject;
+            });
+        }
+    },
+}));
+
+vi.mock("../../utils/constants", () => ({
+    BACKUP_KEY: "frak-backup-key",
+}));
+
+vi.mock("../../utils/iframeHelper", () => ({
+    changeIframeVisibility: vi.fn(),
+}));
+
+describe("createIFrameLifecycleManager", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Reset localStorage
+        localStorage.clear();
+        // Mock window.location
+        Object.defineProperty(window, "location", {
+            value: { href: "https://test.com" },
+            writable: true,
+        });
+    });
+
+    describe("manager initialization", () => {
+        test("should create manager with correct properties", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            expect(manager).toBeDefined();
+            expect(manager.isConnected).toBeInstanceOf(Promise);
+            expect(manager.handleEvent).toBeInstanceOf(Function);
+        });
+
+        test("should start with unresolved isConnected promise", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            let resolved = false;
+            manager.isConnected.then(() => {
+                resolved = true;
+            });
+
+            // Wait a tick
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            expect(resolved).toBe(false);
+        });
+    });
+
+    describe("connected event", () => {
+        test("should resolve isConnected on connected event", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                iframeLifecycle: "connected" as const,
+            };
+
+            await manager.handleEvent(event);
+
+            await expect(manager.isConnected).resolves.toBe(true);
+        });
+    });
+
+    describe("backup events", () => {
+        test("should save backup to localStorage on do-backup", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const backup = "encrypted-backup-data";
+            const event = {
+                iframeLifecycle: "do-backup" as const,
+                data: { backup },
+            };
+
+            await manager.handleEvent(event);
+
+            expect(localStorage.getItem("frak-backup-key")).toBe(backup);
+        });
+
+        test("should remove backup when data.backup is undefined", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            // First set a backup
+            localStorage.setItem("frak-backup-key", "old-backup");
+
+            const event = {
+                iframeLifecycle: "do-backup" as const,
+                data: {},
+            };
+
+            await manager.handleEvent(event);
+
+            expect(localStorage.getItem("frak-backup-key")).toBeNull();
+        });
+
+        test("should remove backup on remove-backup event", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            // First set a backup
+            localStorage.setItem("frak-backup-key", "backup-to-remove");
+
+            const event = {
+                iframeLifecycle: "remove-backup" as const,
+            };
+
+            await manager.handleEvent(event);
+
+            expect(localStorage.getItem("frak-backup-key")).toBeNull();
+        });
+    });
+
+    describe("visibility events", () => {
+        test("should show iframe on show event", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+            const { changeIframeVisibility } = await import(
+                "../../utils/iframeHelper"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                iframeLifecycle: "show" as const,
+            };
+
+            await manager.handleEvent(event);
+
+            expect(changeIframeVisibility).toHaveBeenCalledWith({
+                iframe: mockIframe,
+                isVisible: true,
+            });
+        });
+
+        test("should hide iframe on hide event", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+            const { changeIframeVisibility } = await import(
+                "../../utils/iframeHelper"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                iframeLifecycle: "hide" as const,
+            };
+
+            await manager.handleEvent(event);
+
+            expect(changeIframeVisibility).toHaveBeenCalledWith({
+                iframe: mockIframe,
+                isVisible: false,
+            });
+        });
+    });
+
+    describe("handshake event", () => {
+        test("should post handshake-response with token", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockPostMessage = vi.fn();
+            const mockIframe = {
+                contentWindow: {
+                    postMessage: mockPostMessage,
+                },
+            } as any;
+
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                iframeLifecycle: "handshake" as const,
+                data: { token: "handshake-token-123" },
+            };
+
+            await manager.handleEvent(event);
+
+            expect(mockPostMessage).toHaveBeenCalledWith(
+                {
+                    clientLifecycle: "handshake-response",
+                    data: {
+                        token: "handshake-token-123",
+                        currentUrl: "https://test.com",
+                    },
+                },
+                "*"
+            );
+        });
+
+        test("should include current URL in handshake response", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            Object.defineProperty(window, "location", {
+                value: { href: "https://example.com/page?param=value" },
+                writable: true,
+            });
+
+            const mockPostMessage = vi.fn();
+            const mockIframe = {
+                contentWindow: {
+                    postMessage: mockPostMessage,
+                },
+            } as any;
+
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                iframeLifecycle: "handshake" as const,
+                data: { token: "token" },
+            };
+
+            await manager.handleEvent(event);
+
+            expect(mockPostMessage).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    data: expect.objectContaining({
+                        currentUrl: "https://example.com/page?param=value",
+                    }),
+                }),
+                "*"
+            );
+        });
+    });
+
+    describe("redirect event", () => {
+        test("should redirect with appended current URL", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            Object.defineProperty(window, "location", {
+                value: {
+                    href: "https://original.com",
+                },
+                writable: true,
+            });
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                iframeLifecycle: "redirect" as const,
+                data: {
+                    baseRedirectUrl: "https://redirect.com?u=placeholder",
+                },
+            };
+
+            await manager.handleEvent(event);
+
+            expect(window.location.href).toBe(
+                "https://redirect.com/?u=https%3A%2F%2Foriginal.com"
+            );
+        });
+
+        test("should redirect without modification if no u parameter", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            Object.defineProperty(window, "location", {
+                value: {
+                    href: "https://original.com",
+                },
+                writable: true,
+            });
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                iframeLifecycle: "redirect" as const,
+                data: {
+                    baseRedirectUrl: "https://redirect.com/path",
+                },
+            };
+
+            await manager.handleEvent(event);
+
+            expect(window.location.href).toBe("https://redirect.com/path");
+        });
+    });
+
+    describe("event filtering", () => {
+        test("should ignore events without iframeLifecycle property", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            const event = {
+                someOtherEvent: "value",
+            } as any;
+
+            // Should not throw
+            await expect(manager.handleEvent(event)).resolves.toBeUndefined();
+        });
+
+        test("should only process events with iframeLifecycle", async () => {
+            const { createIFrameLifecycleManager } = await import(
+                "./iframeLifecycleManager"
+            );
+            const { changeIframeVisibility } = await import(
+                "../../utils/iframeHelper"
+            );
+
+            const mockIframe = document.createElement("iframe");
+            const manager = createIFrameLifecycleManager({
+                iframe: mockIframe,
+            });
+
+            // Event without iframeLifecycle
+            await manager.handleEvent({ randomEvent: "show" } as any);
+
+            // changeIframeVisibility should not be called
+            expect(changeIframeVisibility).not.toHaveBeenCalled();
+
+            // Event with iframeLifecycle
+            await manager.handleEvent({ iframeLifecycle: "show" as const });
+
+            // Now it should be called
+            expect(changeIframeVisibility).toHaveBeenCalled();
+        });
+    });
+});

package/src/clients/transports/iframeLifecycleManager.ts

@@ -0,0 +1,90 @@
+import { Deferred } from "@frak-labs/frame-connector";
+import type { FrakLifecycleEvent } from "../../types";
+import { BACKUP_KEY } from "../../utils/constants";
+import { changeIframeVisibility } from "../../utils/iframeHelper";
+
+/** @ignore */
+export type IframeLifecycleManager = {
+    isConnected: Promise<boolean>;
+    handleEvent: (messageEvent: FrakLifecycleEvent) => Promise<void>;
+};
+
+/**
+ * Create a new iframe lifecycle handler
+ * @ignore
+ */
+export function createIFrameLifecycleManager({
+    iframe,
+}: {
+    iframe: HTMLIFrameElement;
+}): IframeLifecycleManager {
+    // Create the isConnected listener
+    const isConnectedDeferred = new Deferred<boolean>();
+
+    // Build the handler itself
+    const handler = async (messageEvent: FrakLifecycleEvent) => {
+        if (!("iframeLifecycle" in messageEvent)) return;
+
+        const { iframeLifecycle: event, data } = messageEvent;
+
+        switch (event) {
+            // Resolve the isConnected promise
+            case "connected":
+                isConnectedDeferred.resolve(true);
+                break;
+            // Perform a frak backup
+            case "do-backup":
+                if (data.backup) {
+                    localStorage.setItem(BACKUP_KEY, data.backup);
+                } else {
+                    localStorage.removeItem(BACKUP_KEY);
+                }
+                break;
+            // Remove frak backup
+            case "remove-backup":
+                localStorage.removeItem(BACKUP_KEY);
+                break;
+            // Change iframe visibility
+            case "show":
+            case "hide":
+                changeIframeVisibility({
+                    iframe,
+                    isVisible: event === "show",
+                });
+                break;
+            // Handshake handling
+            case "handshake": {
+                iframe.contentWindow?.postMessage(
+                    {
+                        clientLifecycle: "handshake-response",
+                        data: {
+                            token: data.token,
+                            currentUrl: window.location.href,
+                        },
+                    },
+                    "*"
+                );
+                break;
+            }
+            // Redirect handling
+            case "redirect": {
+                const redirectUrl = new URL(data.baseRedirectUrl);
+
+                // If we got a u append the current location dynamicly
+                if (redirectUrl.searchParams.has("u")) {
+                    redirectUrl.searchParams.delete("u");
+                    redirectUrl.searchParams.append("u", window.location.href);
+                    window.location.href = redirectUrl.toString();
+                } else {
+                    window.location.href = data.baseRedirectUrl;
+                }
+                break;
+            }
+        }
+    };
+
+    return {
+        handleEvent: handler,
+        isConnected: isConnectedDeferred.promise,
+    };
+}

package/src/constants/interactionTypes.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Tests for interactionTypes constants
+ * Tests interaction type definitions and type utilities
+ */
+
+import { describe, expect, it } from "vitest";
+import { interactionTypes } from "./interactionTypes";
+
+describe("interactionTypes", () => {
+    describe("structure", () => {
+        it("should have all expected categories", () => {
+            expect(interactionTypes).toHaveProperty("press");
+            expect(interactionTypes).toHaveProperty("dapp");
+            expect(interactionTypes).toHaveProperty("webshop");
+            expect(interactionTypes).toHaveProperty("referral");
+            expect(interactionTypes).toHaveProperty("purchase");
+            expect(interactionTypes).toHaveProperty("retail");
+        });
+
+        it("should have press interactions", () => {
+            expect(interactionTypes.press).toEqual({
+                openArticle: "0xc0a24ffb",
+                readArticle: "0xd5bd0fbe",
+            });
+        });
+
+        it("should have dapp interactions", () => {
+            expect(interactionTypes.dapp).toEqual({
+                proofVerifiableStorageUpdate: "0x2ab2aeef",
+                callableVerifiableStorageUpdate: "0xa07da986",
+            });
+        });
+
+        it("should have webshop interactions", () => {
+            expect(interactionTypes.webshop).toEqual({
+                open: "0xb311798f",
+            });
+        });
+
+        it("should have referral interactions", () => {
+            expect(interactionTypes.referral).toEqual({
+                referred: "0x010cc3b9",
+                createLink: "0xb2c0f17c",
+            });
+        });
+
+        it("should have purchase interactions", () => {
+            expect(interactionTypes.purchase).toEqual({
+                started: "0xd87e90c3",
+                completed: "0x8403aeb4",
+                unsafeCompleted: "0x4d5b14e0",
+            });
+        });
+
+        it("should have retail interactions", () => {
+            expect(interactionTypes.retail).toEqual({
+                customerMeeting: "0x74489004",
+            });
+        });
+    });
+
+    describe("interaction values", () => {
+        it("should have all interaction values as hex strings", () => {
+            Object.values(interactionTypes).forEach((category) => {
+                Object.values(category).forEach((value) => {
+                    expect(value).toMatch(/^0x[a-f0-9]{8}$/);
+                });
+            });
+        });
+
+        it("should have unique interaction values across all categories", () => {
+            const allValues = Object.values(interactionTypes).flatMap(
+                (category) => Object.values(category)
+            );
+            const uniqueValues = new Set(allValues);
+            expect(allValues.length).toBe(uniqueValues.size);
+        });
+    });
+
+    describe("specific interactions", () => {
+        it("should have correct press.openArticle value", () => {
+            expect(interactionTypes.press.openArticle).toBe("0xc0a24ffb");
+        });
+
+        it("should have correct press.readArticle value", () => {
+            expect(interactionTypes.press.readArticle).toBe("0xd5bd0fbe");
+        });
+
+        it("should have correct webshop.open value", () => {
+            expect(interactionTypes.webshop.open).toBe("0xb311798f");
+        });
+
+        it("should have correct referral.referred value", () => {
+            expect(interactionTypes.referral.referred).toBe("0x010cc3b9");
+        });
+
+        it("should have correct purchase.completed value", () => {
+            expect(interactionTypes.purchase.completed).toBe("0x8403aeb4");
+        });
+
+        it("should have correct purchase.unsafeCompleted value", () => {
+            expect(interactionTypes.purchase.unsafeCompleted).toBe(
+                "0x4d5b14e0"
+            );
+        });
+
+        it("should have correct retail.customerMeeting value", () => {
+            expect(interactionTypes.retail.customerMeeting).toBe("0x74489004");
+        });
+    });
+
+    describe("type safety", () => {
+        it("should be readonly (as const)", () => {
+            // TypeScript ensures this is readonly, but we can verify structure
+            expect(Object.isFrozen(interactionTypes)).toBe(false);
+            // The values should be consistent
+            expect(typeof interactionTypes.press.openArticle).toBe("string");
+        });
+
+        it("should have consistent structure across categories", () => {
+            Object.values(interactionTypes).forEach((category) => {
+                expect(typeof category).toBe("object");
+                expect(category).not.toBeNull();
+                expect(Array.isArray(category)).toBe(false);
+            });
+        });
+    });
+});

package/src/constants/interactionTypes.ts

@@ -0,0 +1,44 @@
+/**
+ * The final keys for each interaction types (e.g. `openArticle`) -> interaction type
+ * @inline
+ */
+export type InteractionTypesKey = {
+    [K in keyof typeof interactionTypes]: keyof (typeof interactionTypes)[K];
+}[keyof typeof interactionTypes];
+
+/**
+ * The keys for each interaction types (e.g. `press.openArticle`) -> category_type.interaction_type
+ * @inline
+ */
+export type FullInteractionTypesKey = {
+    [Category in keyof typeof interactionTypes]: `${Category & string}.${keyof (typeof interactionTypes)[Category] & string}`;
+}[keyof typeof interactionTypes];
+
+/**
+ * Each interactions types according to the product types
+ */
+export const interactionTypes = {
+    press: {
+        openArticle: "0xc0a24ffb",
+        readArticle: "0xd5bd0fbe",
+    },
+    dapp: {
+        proofVerifiableStorageUpdate: "0x2ab2aeef",
+        callableVerifiableStorageUpdate: "0xa07da986",
+    },
+    webshop: {
+        open: "0xb311798f",
+    },
+    referral: {
+        referred: "0x010cc3b9",
+        createLink: "0xb2c0f17c",
+    },
+    purchase: {
+        started: "0xd87e90c3",
+        completed: "0x8403aeb4",
+        unsafeCompleted: "0x4d5b14e0",
+    },
+    retail: {
+        customerMeeting: "0x74489004",
+    },
+} as const;

package/src/constants/locales.ts

@@ -0,0 +1,14 @@
+/**
+ * The keys for each locales
+ * @inline
+ */
+export type LocalesKey = keyof typeof locales;
+
+/**
+ * Map the currency to the locale
+ */
+export const locales = {
+    eur: "fr-FR",
+    usd: "en-US",
+    gbp: "en-GB",
+} as const;