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

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.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;

package/src/constants/productTypes.ts

@@ -0,0 +1,33 @@
+/**
+ * The keys for each product types
+ * @inline
+ */
+export type ProductTypesKey = keyof typeof productTypes;
+
+/**
+ * List of the product types per denominator
+ */
+export const productTypes = {
+    // content type
+    dapp: 1,
+    press: 2,
+    webshop: 3,
+    retail: 4,
+
+    // feature type
+    referral: 30,
+    purchase: 31,
+};
+
+/**
+ * Bitmask for each product types
+ */
+export const productTypesMask: Record<ProductTypesKey, bigint> = Object.entries(
+    productTypes
+).reduce(
+    (acc, [key, value]) => {
+        acc[key as ProductTypesKey] = BigInt(1) << BigInt(value);
+        return acc;
+    },
+    {} as Record<ProductTypesKey, bigint>
+);

package/src/index.ts

@@ -0,0 +1,101 @@
+// Clients
+
+export { ssoPopupFeatures, ssoPopupName } from "./actions/openSso";
+export {
+    createIFrameFrakClient,
+    DebugInfoGatherer,
+    setupClient,
+} from "./clients";
+export {
+    type FullInteractionTypesKey,
+    type InteractionTypesKey,
+    interactionTypes,
+} from "./constants/interactionTypes";
+export { type LocalesKey, locales } from "./constants/locales";
+// Constants
+export {
+    type ProductTypesKey,
+    productTypes,
+    productTypesMask,
+} from "./constants/productTypes";
+// Types
+export type {
+    ClientLifecycleEvent,
+    CompressedData,
+    Currency,
+    // RPC Embedded wallet
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    DisplayModalParamsType,
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+    FinalActionType,
+    FinalModalStepType,
+    // Client
+    FrakClient,
+    // Utils
+    FrakContext,
+    FrakLifecycleEvent,
+    // Config
+    FrakWalletSdkConfig,
+    GetProductInformationReturnType,
+    HashProtectedData,
+    I18nConfig,
+    IFrameLifecycleEvent,
+    IFrameRpcSchema,
+    // Transport
+    IFrameTransport,
+    // Compression
+    KeyProvider,
+    Language,
+    LocalizedI18nConfig,
+    LoggedInEmbeddedView,
+    LoggedOutEmbeddedView,
+    LoginModalStepType,
+    ModalRpcMetadata,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+    // RPC Modal types
+    ModalStepMetadata,
+    // RPC Modal generics
+    ModalStepTypes,
+    OpenInteractionSessionModalStepType,
+    OpenInteractionSessionReturnType,
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PreparedInteraction,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+    SendInteractionParamsType,
+    SendInteractionReturnType,
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+    SendTransactionTxType,
+    SiweAuthenticateModalStepType,
+    SiweAuthenticateReturnType,
+    SiweAuthenticationParams,
+    SsoMetadata,
+    TokenAmountType,
+    // Rpc
+    WalletStatusReturnType,
+} from "./types";
+// Utils
+export {
+    type AppSpecificSsoMetadata,
+    base64urlDecode,
+    base64urlEncode,
+    baseIframeProps,
+    type CompressedSsoData,
+    compressJsonToB64,
+    createIframe,
+    decompressJsonFromB64,
+    FrakContextManager,
+    type FullSsoParams,
+    findIframeInOpener,
+    formatAmount,
+    generateSsoUrl,
+    getCurrencyAmountKey,
+    getSupportedCurrency,
+    getSupportedLocale,
+    trackEvent,
+} from "./utils";

package/src/interactions/index.ts

@@ -0,0 +1,5 @@
+export { PressInteractionEncoder } from "./pressEncoder";
+export { PurchaseInteractionEncoder } from "./purchaseEncoder";
+export { ReferralInteractionEncoder } from "./referralEncoder";
+export { RetailInteractionEncoder } from "./retailEncoder";
+export { WebShopInteractionEncoder } from "./webshopEncoder";