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

package/src/types/rpc.ts

@@ -0,0 +1,158 @@
+import type { Hex } from "viem";
+import type { FrakWalletSdkConfig } from "./config";
+import type {
+    ModalRpcMetadata,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+} from "./rpc/displayModal";
+import type {
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+} from "./rpc/embedded";
+import type {
+    PreparedInteraction,
+    SendInteractionReturnType,
+} from "./rpc/interaction";
+import type { GetProductInformationReturnType } from "./rpc/productInformation";
+import type {
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+} from "./rpc/sso";
+import type { WalletStatusReturnType } from "./rpc/walletStatus";
+
+/**
+ * RPC interface that's used for the iframe communication
+ *
+ * Define all the methods available within the iFrame RPC client with response type annotations
+ *
+ * @group RPC Schema
+ *
+ * @remarks
+ * Each method in the schema now includes a ResponseType field that indicates:
+ * - "promise": One-shot request that resolves once
+ * - "stream": Streaming request that can emit multiple values
+ *
+ * ### Methods:
+ *
+ * #### frak_listenToWalletStatus
+ *  - Params: None
+ *  - Returns: {@link WalletStatusReturnType}
+ *  - Response Type: stream (emits updates when wallet status changes)
+ *
+ * #### frak_displayModal
+ * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Returns: {@link ModalRpcStepsResultType}
+ * - Response Type: promise (one-shot)
+ *
+ * #### frak_sendInteraction
+ *  - Params: [productId: Hex, interaction: {@link PreparedInteraction}, signature?: Hex]
+ *  - Returns: {@link SendInteractionReturnType}
+ *  - Response Type: promise (one-shot)
+ *
+ * #### frak_sso
+ *  - Params: [params: {@link OpenSsoParamsType}, name: string, customCss?: string]
+ *  - Returns: {@link OpenSsoReturnType}
+ *  - Response Type: promise (one-shot)
+ *
+ * #### frak_getProductInformation
+ *  - Params: None
+ *  - Returns: {@link GetProductInformationReturnType}
+ *  - Response Type: promise (one-shot)
+ *
+ * #### frak_displayEmbeddedWallet
+ * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Returns: {@link DisplayEmbeddedWalletResultType}
+ * - Response Type: promise (one-shot)
+ */
+export type IFrameRpcSchema = [
+    /**
+     * Method used to listen to the wallet status
+     * This is a streaming method that emits updates when wallet status changes
+     */
+    {
+        Method: "frak_listenToWalletStatus";
+        Parameters?: undefined;
+        ReturnType: WalletStatusReturnType;
+    },
+    /**
+     * Method to display a modal with the provided steps
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_displayModal";
+        Parameters: [
+            requests: ModalRpcStepsInput,
+            metadata: ModalRpcMetadata | undefined,
+            configMetadata: FrakWalletSdkConfig["metadata"],
+        ];
+        ReturnType: ModalRpcStepsResultType;
+    },
+    /**
+     * Method to transmit a user interaction
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_sendInteraction";
+        Parameters: [
+            productId: Hex,
+            interaction: PreparedInteraction,
+            signature?: Hex,
+        ];
+        ReturnType: SendInteractionReturnType;
+    },
+    /**
+     * Method to prepare SSO (generate URL for popup)
+     * Returns the SSO URL that should be opened in a popup
+     * Only used for popup flows (not redirect flows)
+     */
+    {
+        Method: "frak_prepareSso";
+        Parameters: [
+            params: PrepareSsoParamsType,
+            name: string,
+            customCss?: string,
+        ];
+        ReturnType: PrepareSsoReturnType;
+    },
+    /**
+     * Method to open/trigger SSO
+     * Either triggers redirect (if openInSameWindow/redirectUrl)
+     * Or waits for popup completion (if popup mode)
+     * This method handles BOTH redirect and popup flows
+     */
+    {
+        Method: "frak_openSso";
+        Parameters: [
+            params: OpenSsoParamsType,
+            name: string,
+            customCss?: string,
+        ];
+        ReturnType: OpenSsoReturnType;
+    },
+    /**
+     * Method to get current product information's
+     *  - Is product minted?
+     *  - Does it have running campaign?
+     *  - Estimated reward on actions
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_getProductInformation";
+        Parameters?: undefined;
+        ReturnType: GetProductInformationReturnType;
+    },
+    /**
+     * Method to show the embedded wallet, with potential customization
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_displayEmbeddedWallet";
+        Parameters: [
+            request: DisplayEmbeddedWalletParamsType,
+            metadata: FrakWalletSdkConfig["metadata"],
+        ];
+        ReturnType: DisplayEmbeddedWalletResultType;
+    },
+];

package/src/types/transport.ts

@@ -0,0 +1,34 @@
+import type { LifecycleMessage, RpcClient } from "@frak-labs/frame-connector";
+import type { ClientLifecycleEvent, IFrameLifecycleEvent } from "./lifecycle";
+import type { IFrameRpcSchema } from "./rpc";
+
+/**
+ * IFrame transport interface
+ */
+export type IFrameTransport = {
+    /**
+     * Wait for the connection to be established
+     */
+    waitForConnection: Promise<boolean>;
+    /**
+     * Wait for the setup to be done
+     */
+    waitForSetup: Promise<void>;
+    /**
+     * Function used to perform a single request via the iframe transport
+     */
+    request: RpcClient<IFrameRpcSchema, LifecycleMessage>["request"];
+    /**
+     * Function used to listen to a request response via the iframe transport
+     */
+    listenerRequest: RpcClient<IFrameRpcSchema, LifecycleMessage>["listen"];
+    /**
+     * Function used to destroy the iframe transport
+     */
+    destroy: () => Promise<void>;
+};
+
+/**
+ * Represent an iframe event
+ */
+export type FrakLifecycleEvent = IFrameLifecycleEvent | ClientLifecycleEvent;

package/src/utils/FrakContext.test.ts

@@ -0,0 +1,338 @@
+/**
+ * Tests for FrakContextManager utility
+ * Tests Frak context compression, URL parsing, and management
+ */
+
+import type { Address } from "viem";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
+import type { FrakContext } from "../types";
+import { FrakContextManager } from "./FrakContext";
+
+describe("FrakContextManager", () => {
+    let consoleErrorSpy: any;
+
+    beforeEach(() => {
+        consoleErrorSpy = vi
+            .spyOn(console, "error")
+            .mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        consoleErrorSpy.mockRestore();
+    });
+
+    describe("compress", () => {
+        it("should compress context with referrer address", () => {
+            const context: Partial<FrakContext> = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.compress(context);
+
+            expect(result).toBeDefined();
+            expect(typeof result).toBe("string");
+            expect(result?.length).toBeGreaterThan(0);
+            // Base64url should not contain +, /, or =
+            expect(result).not.toMatch(/[+/=]/);
+        });
+
+        it("should return undefined when context has no referrer", () => {
+            const context: Partial<FrakContext> = {};
+
+            const result = FrakContextManager.compress(context);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should return undefined when context is undefined", () => {
+            const result = FrakContextManager.compress(undefined);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should handle compression errors gracefully", () => {
+            const invalidContext = {
+                r: "invalid-address" as Address,
+            };
+
+            const result = FrakContextManager.compress(invalidContext);
+
+            expect(consoleErrorSpy).toHaveBeenCalled();
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("decompress", () => {
+        it("should decompress valid base64url context", () => {
+            // First compress a context
+            const originalContext: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+            const compressed = FrakContextManager.compress(originalContext);
+
+            // Then decompress it
+            const result = FrakContextManager.decompress(compressed);
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return undefined for empty string", () => {
+            const result = FrakContextManager.decompress("");
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should return undefined for undefined input", () => {
+            const result = FrakContextManager.decompress(undefined);
+
+            expect(result).toBeUndefined();
+        });
+
+        it("should handle decompression errors gracefully", () => {
+            const result = FrakContextManager.decompress(
+                "invalid-base64url!@#"
+            );
+
+            expect(consoleErrorSpy).toHaveBeenCalled();
+            expect(result).toBeUndefined();
+        });
+
+        it("should round-trip compress and decompress", () => {
+            const original: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const compressed = FrakContextManager.compress(original);
+            const decompressed = FrakContextManager.decompress(compressed);
+
+            expect(decompressed).toEqual(original);
+        });
+    });
+
+    describe("parse", () => {
+        it("should parse URL with fCtx parameter", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0x1234567890123456789012345678901234567890"
+            );
+        });
+
+        it("should return null for URL without fCtx parameter", () => {
+            const url = "https://example.com?other=param";
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeNull();
+        });
+
+        it("should return null for empty URL", () => {
+            const result = FrakContextManager.parse({ url: "" });
+
+            expect(result).toBeNull();
+        });
+
+        it("should parse URL with multiple parameters", () => {
+            const context: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?foo=bar&fCtx=${compressed}&baz=qux`;
+
+            const result = FrakContextManager.parse({ url });
+
+            expect(result).toBeDefined();
+            expect(result?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return undefined for malformed fCtx parameter", () => {
+            // Use a string that will fail base64url decoding
+            const url = "https://example.com?fCtx=!!!invalid!!!";
+
+            const result = FrakContextManager.parse({ url });
+
+            // Should handle the error and return undefined
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("update", () => {
+        it("should add fCtx to URL without existing context", () => {
+            const url = "https://example.com";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toBeDefined();
+            expect(result).toContain("fCtx=");
+            expect(result).toContain("https://example.com");
+        });
+
+        it("should merge with existing context in URL", () => {
+            const existingContext: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(existingContext);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const newContext: FrakContext = {
+                r: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address,
+            };
+
+            const result = FrakContextManager.update({
+                url,
+                context: newContext,
+            });
+
+            expect(result).toBeDefined();
+            expect(result).toContain("fCtx=");
+
+            // Parse the result and check it has the new referrer
+            const parsedResult = FrakContextManager.parse({ url: result! });
+            expect(parsedResult?.r).toBe(
+                "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
+            );
+        });
+
+        it("should return null when URL is undefined", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({
+                url: undefined,
+                context,
+            });
+
+            expect(result).toBeNull();
+        });
+
+        it("should return null when context has no referrer", () => {
+            const url = "https://example.com";
+            const context: Partial<FrakContext> = {};
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toBeNull();
+        });
+
+        it("should preserve other URL parameters", () => {
+            const url = "https://example.com?foo=bar&baz=qux";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("foo=bar");
+            expect(result).toContain("baz=qux");
+            expect(result).toContain("fCtx=");
+        });
+
+        it("should preserve URL hash", () => {
+            const url = "https://example.com#section";
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+
+            const result = FrakContextManager.update({ url, context });
+
+            expect(result).toContain("#section");
+            expect(result).toContain("fCtx=");
+        });
+    });
+
+    describe("remove", () => {
+        it("should remove fCtx parameter from URL", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?fCtx=${compressed}`;
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toBe("https://example.com/");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should preserve other parameters when removing fCtx", () => {
+            const context: FrakContext = {
+                r: "0x1234567890123456789012345678901234567890" as Address,
+            };
+            const compressed = FrakContextManager.compress(context);
+            const url = `https://example.com?foo=bar&fCtx=${compressed}&baz=qux`;
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("foo=bar");
+            expect(result).toContain("baz=qux");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should handle URL without fCtx parameter", () => {
+            const url = "https://example.com?foo=bar";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("foo=bar");
+            expect(result).not.toContain("fCtx");
+        });
+
+        it("should preserve URL hash", () => {
+            const url = "https://example.com?fCtx=test#section";
+
+            const result = FrakContextManager.remove(url);
+
+            expect(result).toContain("#section");
+            expect(result).not.toContain("fCtx");
+        });
+    });
+
+    describe("replaceUrl", () => {
+        // Note: replaceUrl tests are skipped because window.location cannot be mocked
+        // in JSDOM environment. The function is primarily used for browser DOM manipulation
+        // and is tested through integration/E2E tests.
+
+        it.skip("should update window.location with context", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should use provided URL instead of window.location.href", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should remove fCtx when context is null", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should not call replaceState when context has no referrer", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+
+        it.skip("should handle missing window gracefully", () => {
+            // Skip: Cannot mock window.location in JSDOM
+        });
+    });
+});

package/src/utils/FrakContext.ts

@@ -0,0 +1,158 @@
+import { type Address, bytesToHex, hexToBytes } from "viem";
+import type { FrakContext } from "../types";
+import { base64urlDecode, base64urlEncode } from "./compression/b64";
+
+/**
+ * The context key
+ */
+const contextKey = "fCtx";
+
+/**
+ * Compress the current Frak context
+ * @param context - The context to be compressed
+ * @returns A compressed string containing the Frak context
+ */
+function compress(context?: Partial<FrakContext>): string | undefined {
+    if (!context?.r) return;
+    try {
+        const bytes = hexToBytes(context.r);
+        return base64urlEncode(bytes);
+    } catch (e) {
+        console.error("Error compressing Frak context", { e, context });
+    }
+    return undefined;
+}
+
+/**
+ * Decompress the given Frak context
+ * @param context - The raw context to be decompressed into a `FrakContext`
+ * @returns The decompressed Frak context, or undefined if it fails
+ */
+function decompress(context?: string): FrakContext | undefined {
+    if (!context || context.length === 0) return;
+    try {
+        const bytes = base64urlDecode(context);
+        return { r: bytesToHex(bytes, { size: 20 }) as Address };
+    } catch (e) {
+        console.error("Error decompressing Frak context", { e, context });
+    }
+    return undefined;
+}
+
+/**
+ * Parse the current URL into a Frak Context
+ * @param args
+ * @param args.url - The url to parse
+ * @returns The parsed Frak context
+ */
+function parse({ url }: { url: string }) {
+    if (!url) return null;
+
+    // Check if the url contain the frak context key
+    const urlObj = new URL(url);
+    const frakContext = urlObj.searchParams.get(contextKey);
+    if (!frakContext) return null;
+
+    // Decompress and return it
+    return decompress(frakContext);
+}
+
+/**
+ * Populate the current url with the given Frak context
+ * @param args
+ * @param args.url - The url to update
+ * @param args.context - The context to update
+ * @returns The new url with the Frak context
+ */
+function update({
+    url,
+    context,
+}: {
+    url?: string;
+    context: Partial<FrakContext>;
+}) {
+    if (!url) return null;
+
+    // Parse the current context
+    const currentContext = parse({ url });
+
+    // Merge the current context with the new context
+    const mergedContext = currentContext
+        ? { ...currentContext, ...context }
+        : context;
+
+    // If we don't have a referrer, early exit
+    if (!mergedContext.r) return null;
+
+    // Compress it
+    const compressedContext = compress(mergedContext);
+    if (!compressedContext) return null;
+
+    // Build the new url and return it
+    const urlObj = new URL(url);
+    urlObj.searchParams.set(contextKey, compressedContext);
+    return urlObj.toString();
+}
+
+/**
+ * Remove Frak context from current url
+ * @param url - The url to update
+ * @returns The new url without the Frak context
+ */
+function remove(url: string) {
+    const urlObj = new URL(url);
+    urlObj.searchParams.delete(contextKey);
+    return urlObj.toString();
+}
+
+/**
+ * Replace the current url with the given Frak context
+ * @param args
+ * @param args.url - The url to update
+ * @param args.context - The context to update
+ */
+function replaceUrl({
+    url: baseUrl,
+    context,
+}: {
+    url?: string;
+    context: Partial<FrakContext> | null;
+}) {
+    // If no window here early exit
+    if (!window.location?.href || typeof window === "undefined") {
+        console.error("No window found, can't update context");
+        return;
+    }
+
+    // If no url, try to use the current one
+    const url = baseUrl ?? window.location.href;
+
+    // Get our new url with the frak context
+    let newUrl: string | null;
+    if (context !== null) {
+        newUrl = update({
+            url,
+            context,
+        });
+    } else {
+        newUrl = remove(url);
+    }
+
+    // If no new url, early exit
+    if (!newUrl) return;
+
+    // Update the url
+    window.history.replaceState(null, "", newUrl.toString());
+}
+
+/**
+ * Export our frak context
+ */
+export const FrakContextManager = {
+    compress,
+    decompress,
+    parse,
+    update,
+    remove,
+    replaceUrl,
+};