@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.4dfea079

package/src/actions/referral/processReferral.test.ts

@@ -0,0 +1,248 @@
+import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
+import type { Address } from "viem";
+import { vi } from "vitest"; // Keep vi from vitest for vi.mock() hoisting
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+} from "../../../tests/vitest-fixtures";
+import type {
+    FrakClient,
+    FrakContext,
+    WalletStatusReturnType,
+} from "../../types";
+import { processReferral } from "./processReferral";
+
+// Mock dependencies
+vi.mock("../displayEmbeddedWallet", () => ({
+    displayEmbeddedWallet: vi.fn(),
+}));
+
+vi.mock("../sendInteraction", () => ({
+    sendInteraction: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("../../utils", () => ({
+    FrakContextManager: {
+        replaceUrl: vi.fn(),
+    },
+    trackEvent: vi.fn(),
+    resolveMerchantId: vi.fn().mockResolvedValue(undefined),
+}));
+
+describe("processReferral", () => {
+    let mockClient: FrakClient;
+    let mockAddress: Address;
+    let mockReferrerAddress: Address;
+    let mockWalletStatus: WalletStatusReturnType;
+    let mockFrakContext: Partial<FrakContext>;
+
+    beforeEach(async () => {
+        vi.clearAllMocks();
+
+        mockAddress = "0x1234567890123456789012345678901234567890" as Address;
+        mockReferrerAddress =
+            "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" as Address;
+
+        mockClient = {
+            openPanel: {
+                track: vi.fn(),
+            },
+            config: {
+                metadata: {
+                    name: "Test App",
+                },
+                domain: "example.com",
+            },
+            request: vi.fn(),
+        } as unknown as FrakClient;
+
+        mockWalletStatus = {
+            key: "connected" as const,
+            wallet: mockAddress,
+        };
+
+        mockFrakContext = {
+            r: mockReferrerAddress,
+        };
+
+        // Mock window.location
+        Object.defineProperty(window, "location", {
+            value: {
+                href: "https://example.com/test",
+            },
+            writable: true,
+        });
+    });
+
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it("should return 'no-referrer' when frakContext has no referrer", async () => {
+        const result = await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: {},
+        });
+
+        expect(result).toBe("no-referrer");
+    });
+
+    it("should return 'no-referrer' when frakContext is null", async () => {
+        const result = await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: null,
+        });
+
+        expect(result).toBe("no-referrer");
+    });
+
+    it("should return 'self-referral' when referrer equals current wallet", async () => {
+        const result = await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: {
+                r: mockAddress, // Same as wallet
+            },
+        });
+
+        expect(result).toBe("self-referral");
+    });
+
+    it("should successfully process referral when all conditions are met", async () => {
+        const utils = await import("../../utils");
+
+        const result = await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: mockFrakContext,
+        });
+
+        expect(result).toBe("success");
+
+        expect(utils.trackEvent).toHaveBeenCalledWith(
+            mockClient,
+            "user_referred_started",
+            {
+                properties: {
+                    referrer: mockReferrerAddress,
+                    walletStatus: "connected",
+                },
+            }
+        );
+
+        expect(utils.trackEvent).toHaveBeenCalledWith(
+            mockClient,
+            "user_referred_completed",
+            {
+                properties: {
+                    status: "success",
+                    referrer: mockReferrerAddress,
+                    wallet: mockAddress,
+                },
+            }
+        );
+    });
+
+    it("should handle wallet not connected scenario", async () => {
+        const { displayEmbeddedWallet } = await import(
+            "../displayEmbeddedWallet"
+        );
+
+        // Mock displayEmbeddedWallet to return a wallet
+        vi.mocked(displayEmbeddedWallet).mockResolvedValue({
+            wallet: mockAddress,
+        } as any);
+
+        const result = await processReferral(mockClient, {
+            walletStatus: undefined,
+            frakContext: mockFrakContext,
+        });
+
+        expect(result).toBe("success");
+        expect(displayEmbeddedWallet).toHaveBeenCalled();
+    });
+
+    it("should return 'no-wallet' when wallet connection fails", async () => {
+        const { displayEmbeddedWallet } = await import(
+            "../displayEmbeddedWallet"
+        );
+
+        const error = new FrakRpcError(
+            RpcErrorCodes.walletNotConnected,
+            "Wallet not connected"
+        );
+        vi.mocked(displayEmbeddedWallet).mockRejectedValue(error);
+
+        const result = await processReferral(mockClient, {
+            walletStatus: undefined,
+            frakContext: mockFrakContext,
+        });
+
+        expect(result).toBe("no-wallet");
+    });
+
+    it("should return 'error' for unknown errors", async () => {
+        const { displayEmbeddedWallet } = await import(
+            "../displayEmbeddedWallet"
+        );
+
+        const error = new Error("Unknown error");
+        vi.mocked(displayEmbeddedWallet).mockRejectedValue(error);
+
+        const result = await processReferral(mockClient, {
+            walletStatus: undefined,
+            frakContext: mockFrakContext,
+        });
+
+        expect(result).toBe("error");
+    });
+
+    it("should update URL context when alwaysAppendUrl is true", async () => {
+        const utils = await import("../../utils");
+
+        await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: mockFrakContext,
+            options: {
+                alwaysAppendUrl: true,
+            },
+        });
+
+        expect(utils.FrakContextManager.replaceUrl).toHaveBeenCalledWith({
+            url: window.location.href,
+            context: { r: mockAddress },
+        });
+    });
+
+    it("should remove URL context when alwaysAppendUrl is false", async () => {
+        const utils = await import("../../utils");
+
+        await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: mockFrakContext,
+            options: {
+                alwaysAppendUrl: false,
+            },
+        });
+
+        expect(utils.FrakContextManager.replaceUrl).toHaveBeenCalledWith({
+            url: window.location.href,
+            context: null,
+        });
+    });
+
+    it("should remove URL context by default", async () => {
+        const utils = await import("../../utils");
+
+        await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: mockFrakContext,
+        });
+
+        expect(utils.FrakContextManager.replaceUrl).toHaveBeenCalledWith({
+            url: window.location.href,
+            context: null,
+        });
+    });
+});

package/src/actions/referral/processReferral.ts

@@ -0,0 +1,232 @@
+import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
+import { type Address, isAddressEqual } from "viem";
+import type {
+    DisplayEmbeddedWalletParamsType,
+    FrakClient,
+    FrakContext,
+    WalletStatusReturnType,
+} from "../../types";
+import { FrakContextManager, trackEvent } from "../../utils";
+import { displayEmbeddedWallet } from "../displayEmbeddedWallet";
+import { sendInteraction } from "../sendInteraction";
+
+/**
+ * The different states of the referral process
+ * @inline
+ */
+type ReferralState =
+    | "idle"
+    | "processing"
+    | "success"
+    | "no-wallet"
+    | "error"
+    | "no-referrer"
+    | "self-referral";
+
+/**
+ * Options for the referral auto-interaction process
+ */
+export type ProcessReferralOptions = {
+    /**
+     * If we want to always append the url with the frak context or not
+     * @defaultValue false
+     */
+    alwaysAppendUrl?: boolean;
+};
+
+/**
+ * This function handle all the heavy lifting of the referral interaction process
+ *  1. Check if the user has been referred or not (if not, early exit)
+ *  2. Then check if the user is logged in or not
+ *  2.1 If not logged in, try a soft login, if it fail, display a modal for the user to login
+ *  3. Check if that's not a self-referral (if yes, early exit)
+ *  4. Track the referral event
+ *  5. Update the current url with the right data
+ *  6. Return the resulting referral state
+ *
+ *  If any error occurs during the process, the function will catch it and return an error state
+ *
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.walletStatus - The current user wallet status
+ * @param args.frakContext - The current frak context
+ * @param args.modalConfig - The modal configuration to display if the user is not logged in
+ * @param args.options - Some options for the referral interaction
+ * @returns  A promise with the resulting referral state
+ *
+ * @see {@link displayModal} for more details about the displayed modal
+ * @see {@link @frak-labs/core-sdk!ModalStepTypes} for more details on each modal steps types
+ */
+export async function processReferral(
+    client: FrakClient,
+    {
+        walletStatus,
+        frakContext,
+        modalConfig,
+        options,
+    }: {
+        walletStatus?: WalletStatusReturnType;
+        frakContext?: Partial<FrakContext> | null;
+        modalConfig?: DisplayEmbeddedWalletParamsType;
+        options?: ProcessReferralOptions;
+    }
+) {
+    // Early exit if we don't have any referral informations
+    if (!frakContext?.r) {
+        return "no-referrer";
+    }
+
+    // If we got a context, log an event
+    trackEvent(client, "user_referred_started", {
+        properties: {
+            referrer: frakContext?.r,
+            walletStatus: walletStatus?.key,
+        },
+    });
+
+    sendInteraction(client, {
+        type: "arrival",
+        referrerWallet: frakContext.r,
+        landingUrl:
+            typeof window !== "undefined" ? window.location.href : undefined,
+    });
+
+    // Helper to fetch a fresh wallet status
+    let walletRequest = false;
+    async function getFreshWalletStatus() {
+        if (walletRequest) {
+            return;
+        }
+        walletRequest = true;
+        return ensureWalletConnected(client, {
+            modalConfig: {
+                ...modalConfig,
+                loggedIn: {
+                    action: {
+                        key: "referred",
+                    },
+                },
+            },
+            walletStatus,
+        });
+    }
+
+    try {
+        // Do the core processing logic
+        const { status, currentWallet } = await processReferralLogic({
+            initialWalletStatus: walletStatus,
+            getFreshWalletStatus,
+            // We can enforce this type cause of the condition at the start
+            frakContext: frakContext as Pick<FrakContext, "r">,
+        });
+
+        // Update the current url with the right data
+        FrakContextManager.replaceUrl({
+            url: window.location?.href,
+            context: options?.alwaysAppendUrl ? { r: currentWallet } : null,
+        });
+
+        // Track the event
+        trackEvent(client, "user_referred_completed", {
+            properties: {
+                status,
+                referrer: frakContext?.r,
+                wallet: currentWallet,
+            },
+        });
+
+        return status;
+    } catch (error) {
+        console.log("Error processing referral", { error });
+
+        // Track the error event
+        trackEvent(client, "user_referred_error", {
+            properties: {
+                referrer: frakContext?.r,
+                error:
+                    error instanceof FrakRpcError
+                        ? `[${error.code}] ${error.name} - ${error.message}`
+                        : error instanceof Error
+                          ? error.message
+                          : "undefined",
+            },
+        });
+
+        // Update the current url with the right data
+        FrakContextManager.replaceUrl({
+            url: window.location?.href,
+            context: options?.alwaysAppendUrl
+                ? { r: walletStatus?.wallet }
+                : null,
+        });
+
+        // And map the error a state
+        return mapErrorToState(error);
+    }
+}
+
+/**
+ * Process referral logic - ensure user is logged in and check for self-referral
+ */
+async function processReferralLogic({
+    initialWalletStatus,
+    getFreshWalletStatus,
+    frakContext,
+}: {
+    initialWalletStatus?: WalletStatusReturnType;
+    getFreshWalletStatus: () => Promise<Address | undefined>;
+    frakContext: Pick<FrakContext, "r">;
+}) {
+    // Get the current wallet, without auto displaying the modal
+    let currentWallet = initialWalletStatus?.wallet;
+
+    // If we don't have a current wallet, display the modal to log in
+    if (!currentWallet) {
+        currentWallet = await getFreshWalletStatus();
+    }
+
+    // Check for self-referral
+    if (currentWallet && isAddressEqual(frakContext.r, currentWallet)) {
+        return { status: "self-referral", currentWallet } as const;
+    }
+
+    return { status: "success", currentWallet } as const;
+}
+
+/**
+ * Helper to ensure a wallet is connected, and display a modal if we got everything needed
+ */
+async function ensureWalletConnected(
+    client: FrakClient,
+    {
+        modalConfig,
+        walletStatus,
+    }: {
+        modalConfig?: DisplayEmbeddedWalletParamsType;
+        walletStatus?: WalletStatusReturnType;
+    }
+) {
+    // If wallet not connected, display modal
+    if (walletStatus?.key !== "connected") {
+        const result = await displayEmbeddedWallet(client, modalConfig ?? {});
+        return result?.wallet ?? undefined;
+    }
+
+    return walletStatus.wallet ?? undefined;
+}
+
+/**
+ * Helper to map an error to a state
+ * @param error
+ */
+function mapErrorToState(error: unknown): ReferralState {
+    if (error instanceof FrakRpcError) {
+        switch (error.code) {
+            case RpcErrorCodes.walletNotConnected:
+                return "no-wallet";
+            default:
+                return "error";
+        }
+    }
+    return "error";
+}

package/src/actions/referral/referralInteraction.test.ts

@@ -0,0 +1,147 @@
+import type { Hex } from "viem";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { referralInteraction } from "./referralInteraction";
+
+vi.mock("../../utils", () => ({
+    FrakContextManager: {
+        parse: vi.fn(),
+    },
+}));
+
+vi.mock("../index", () => ({
+    watchWalletStatus: vi.fn(),
+}));
+
+vi.mock("./processReferral", () => ({
+    processReferral: vi.fn(),
+}));
+
+describe("referralInteraction", () => {
+    const mockClient = {
+        request: vi.fn(),
+    } as any;
+
+    beforeEach(() => {
+        vi.clearAllMocks();
+        Object.defineProperty(global, "window", {
+            value: { location: { href: "https://example.com?frak=test" } },
+            writable: true,
+        });
+    });
+
+    test("should parse context from window location", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        await referralInteraction(mockClient);
+
+        expect(FrakContextManager.parse).toHaveBeenCalledWith({
+            url: "https://example.com?frak=test",
+        });
+    });
+
+    test("should get current wallet status", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue({
+            key: "connected",
+            wallet: "0x123" as Hex,
+        } as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        await referralInteraction(mockClient);
+
+        expect(watchWalletStatus).toHaveBeenCalledWith(mockClient);
+    });
+
+    test("should call processReferral with all parameters", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        const mockContext = { r: "0xreferrer" as Hex };
+        const mockWalletStatus = { wallet: "0x123" as Hex };
+        const mockModalConfig = { type: "login" };
+        const mockOptions = { alwaysAppendUrl: true };
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue(mockContext as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(mockWalletStatus as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        await referralInteraction(mockClient, {
+            modalConfig: mockModalConfig as any,
+            options: mockOptions,
+        });
+
+        expect(processReferral).toHaveBeenCalledWith(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: mockContext,
+            modalConfig: mockModalConfig,
+            options: mockOptions,
+        });
+    });
+
+    test("should return result from processReferral", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockResolvedValue("success");
+
+        const result = await referralInteraction(mockClient);
+
+        expect(result).toBe("success");
+    });
+
+    test("should return undefined on error", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockRejectedValue(new Error("Test error"));
+
+        const consoleSpy = vi
+            .spyOn(console, "warn")
+            .mockImplementation(() => {});
+
+        const result = await referralInteraction(mockClient);
+
+        expect(result).toBeUndefined();
+        expect(consoleSpy).toHaveBeenCalled();
+
+        consoleSpy.mockRestore();
+    });
+
+    test("should work with empty options", async () => {
+        const { FrakContextManager } = await import("../../utils");
+        const { watchWalletStatus } = await import("../index");
+        const { processReferral } = await import("./processReferral");
+
+        vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
+        vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
+        vi.mocked(processReferral).mockResolvedValue("no-referrer");
+
+        const result = await referralInteraction(mockClient, {});
+
+        expect(result).toBe("no-referrer");
+        expect(processReferral).toHaveBeenCalledWith(
+            mockClient,
+            expect.objectContaining({
+                modalConfig: undefined,
+                options: undefined,
+            })
+        );
+    });
+});

package/src/actions/referral/referralInteraction.ts

@@ -0,0 +1,52 @@
+import type { DisplayEmbeddedWalletParamsType, FrakClient } from "../../types";
+import { FrakContextManager } from "../../utils";
+import { watchWalletStatus } from "../index";
+import {
+    type ProcessReferralOptions,
+    processReferral,
+} from "./processReferral";
+
+/**
+ * Function used to handle referral interactions
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.modalConfig - The modal configuration to display if the user is not logged in
+ * @param args.options - Some options for the referral interaction
+ *
+ * @returns  A promise with the resulting referral state, or undefined in case of an error
+ *
+ * @description This function will automatically handle the referral interaction process
+ *
+ * @see {@link processReferral} for more details on the automatic referral handling process
+ * @see {@link @frak-labs/core-sdk!ModalStepTypes} for more details on each modal steps types
+ */
+export async function referralInteraction(
+    client: FrakClient,
+    {
+        modalConfig,
+        options,
+    }: {
+        modalConfig?: DisplayEmbeddedWalletParamsType;
+        options?: ProcessReferralOptions;
+    } = {}
+) {
+    // Get the current frak context
+    const frakContext = FrakContextManager.parse({
+        url: window.location.href,
+    });
+
+    // Get the current wallet status
+    const currentWalletStatus = await watchWalletStatus(client);
+
+    try {
+        return await processReferral(client, {
+            walletStatus: currentWalletStatus,
+            frakContext,
+            modalConfig,
+            options,
+        });
+    } catch (error) {
+        console.warn("Error processing referral", { error });
+    }
+    return;
+}

package/src/actions/sendInteraction.ts

@@ -0,0 +1,24 @@
+import type { FrakClient } from "../types";
+import type { SendInteractionParamsType } from "../types/rpc/interaction";
+
+/**
+ * Send an interaction to the backend via the listener RPC.
+ * Fire-and-forget: errors are caught and logged, not thrown.
+ *
+ * @param client - The Frak client instance
+ * @param params - The interaction parameters
+ */
+export async function sendInteraction(
+    client: FrakClient,
+    params: SendInteractionParamsType
+): Promise<void> {
+    try {
+        await client.request({
+            method: "frak_sendInteraction",
+            params: [params],
+        });
+    } catch {
+        // Silent failure - fire-and-forget
+        console.warn("[Frak SDK] Failed to send interaction:", params.type);
+    }
+}