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

package/src/actions/prepareSso.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Tests for prepareSso action
+ * Tests SSO URL generation via RPC
+ */
+
+import { describe, expect, it, vi } from "../../tests/vitest-fixtures";
+import type {
+    FrakClient,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+} from "../types";
+import { prepareSso } from "./prepareSso";
+
+describe("prepareSso", () => {
+    describe("success cases", () => {
+        it("should call client.request with correct method and params", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?params=xyz",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "Test App", undefined],
+            });
+        });
+
+        it("should return SSO URL", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?params=abc123",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: false,
+            };
+
+            const result = await prepareSso(mockClient, params);
+
+            expect(result).toEqual(mockResponse);
+            expect(result.ssoUrl).toBe(
+                "https://wallet.frak.id/sso?params=abc123"
+            );
+        });
+
+        it("should include custom CSS when provided", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?params=custom",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Styled App",
+                    },
+                    customizations: {
+                        css: "body { background: red; }",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "Styled App", "body { background: red; }"],
+            });
+        });
+
+        it("should handle params with redirectUrl", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?redirect=https://example.com",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                redirectUrl: "https://example.com/callback",
+                directExit: false,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "Test App", undefined],
+            });
+        });
+
+        it("should handle params with metadata", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?metadata=xyz",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "App with Metadata",
+                        logoUrl: "https://example.com/logo.png",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                metadata: {
+                    logoUrl: "https://custom.com/logo.png",
+                    homepageLink: "https://custom.com",
+                },
+                directExit: true,
+            };
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "App with Metadata", undefined],
+            });
+        });
+
+        it("should pass client metadata name to request", async () => {
+            const mockResponse: PrepareSsoReturnType = {
+                ssoUrl: "https://wallet.frak.id/sso?name=MyApp",
+            };
+
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "MyApp",
+                        logoUrl: "https://example.com/logo.png",
+                    },
+                    customizations: {
+                        css: "body { color: blue; }",
+                    },
+                },
+                request: vi.fn().mockResolvedValue(mockResponse),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {};
+
+            await prepareSso(mockClient, params);
+
+            expect(mockClient.request).toHaveBeenCalledWith({
+                method: "frak_prepareSso",
+                params: [params, "MyApp", "body { color: blue; }"],
+            });
+        });
+    });
+
+    describe("error handling", () => {
+        it("should propagate errors from client.request", async () => {
+            const error = new Error("SSO preparation failed");
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockRejectedValue(error),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {
+                directExit: true,
+            };
+
+            await expect(prepareSso(mockClient, params)).rejects.toThrow(
+                "SSO preparation failed"
+            );
+        });
+
+        it("should handle network errors", async () => {
+            const error = new Error("Network timeout");
+            const mockClient = {
+                config: {
+                    metadata: {
+                        name: "Test App",
+                    },
+                },
+                request: vi.fn().mockRejectedValue(error),
+            } as unknown as FrakClient;
+
+            const params: PrepareSsoParamsType = {};
+
+            await expect(prepareSso(mockClient, params)).rejects.toThrow(
+                "Network timeout"
+            );
+        });
+    });
+});

package/src/actions/prepareSso.ts

@@ -0,0 +1,48 @@
+import type {
+    FrakClient,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+} from "../types";
+
+/**
+ * Generate SSO URL without opening popup
+ *
+ * This is a **synchronous**, client-side function that generates the SSO URL
+ * without any RPC calls to the wallet iframe. Use this when you need:
+ * - Custom URL modifications before opening popup
+ * - Pre-generation for advanced popup strategies
+ * - URL inspection/logging before SSO flow
+ *
+ * @param client - The current Frak Client
+ * @param args - The SSO parameters
+ * @returns Object containing the generated ssoUrl
+ *
+ * @example
+ * ```ts
+ * // Generate URL for inspection
+ * const { ssoUrl } = prepareSso(client, {
+ *   metadata: { logoUrl: "..." },
+ *   directExit: true
+ * });
+ * console.log("Opening SSO:", ssoUrl);
+ *
+ * // Add custom params
+ * const customUrl = `${ssoUrl}&tracking=abc123`;
+ * await openSso(client, { metadata, ssoPopupUrl: customUrl });
+ * ```
+ *
+ * @remarks
+ * For most use cases, just use `openSso()` which handles URL generation automatically.
+ * Only use `prepareSso()` when you need explicit control over the URL.
+ */
+export async function prepareSso(
+    client: FrakClient,
+    args: PrepareSsoParamsType
+): Promise<PrepareSsoReturnType> {
+    const { metadata, customizations } = client.config;
+
+    return await client.request({
+        method: "frak_prepareSso",
+        params: [args, metadata.name, customizations?.css],
+    });
+}

package/src/actions/referral/processReferral.ts

@@ -0,0 +1,230 @@
+import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
+import { type Address, type Hex, isAddressEqual } from "viem";
+import { ReferralInteractionEncoder } from "../../interactions";
+import type {
+    DisplayEmbeddedWalletParamsType,
+    FrakClient,
+    FrakContext,
+    WalletStatusReturnType,
+} from "../../types";
+import { FrakContextManager, trackEvent } from "../../utils";
+import { displayEmbeddedWallet, sendInteraction } from "../index";
+
+/**
+ * The different states of the referral process
+ * @inline
+ */
+type ReferralState =
+    | "idle"
+    | "processing"
+    | "success"
+    | "no-wallet"
+    | "no-session"
+    | "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. Check if the user has an interaction session or not
+ *  4.1 If not, display a modal for the user to open a session
+ *  5. Push the referred interaction
+ *  6. Update the current url with the right data
+ *  7. 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.productId - The product id to interact with (if not specified will be recomputed from the current domain)
+ * @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 sendInteraction} for more details on the interaction submission part
+ * @see {@link ReferralInteractionEncoder} for more details about the referred interaction
+ * @see {@link @frak-labs/core-sdk!ModalStepTypes} for more details on each modal steps types
+ */
+export async function processReferral(
+    client: FrakClient,
+    {
+        walletStatus,
+        frakContext,
+        modalConfig,
+        productId,
+        options,
+    }: {
+        walletStatus?: WalletStatusReturnType;
+        frakContext?: Partial<FrakContext> | null;
+        modalConfig?: DisplayEmbeddedWalletParamsType;
+        productId?: Hex;
+        options?: ProcessReferralOptions;
+    }
+) {
+    // 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,
+        });
+    }
+
+    // Helper function to push the interaction
+    async function pushReferralInteraction(referrer: Address) {
+        const interaction = ReferralInteractionEncoder.referred({
+            referrer,
+        });
+        await Promise.allSettled([
+            // Send the interaction
+            sendInteraction(client, { productId, interaction }),
+            // Track the event
+            trackEvent(client, "user_referred", {
+                properties: {
+                    referrer: referrer,
+                },
+            }),
+        ]);
+    }
+
+    try {
+        // Do the core processing logic
+        const { status, currentWallet } = await processReferralLogic({
+            initialWalletStatus: walletStatus,
+            getFreshWalletStatus,
+            pushReferralInteraction,
+            frakContext,
+        });
+
+        // Update the current url with the right data
+        FrakContextManager.replaceUrl({
+            url: window.location?.href,
+            context: options?.alwaysAppendUrl ? { r: currentWallet } : null,
+        });
+
+        return status;
+    } catch (error) {
+        console.log("Error processing referral", { error });
+        // 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);
+    }
+}
+
+/**
+ * Automatically submit a referral interaction when detected
+ *   -> And automatically set the referral context in the url
+ * @param walletStatus
+ * @param frakContext
+ */
+async function processReferralLogic({
+    initialWalletStatus,
+    getFreshWalletStatus,
+    pushReferralInteraction,
+    frakContext,
+}: {
+    initialWalletStatus?: WalletStatusReturnType;
+    getFreshWalletStatus: () => Promise<Address | undefined>;
+    pushReferralInteraction: (referrer: Address) => Promise<void>;
+    frakContext?: Partial<FrakContext> | null;
+}) {
+    // Get the current wallet, without auto displaying the modal
+    let currentWallet = initialWalletStatus?.wallet;
+    if (!frakContext?.r) {
+        return { status: "no-referrer", currentWallet } as const;
+    }
+
+    // We have a referral, so if we don't have a current wallet, display the modal
+    if (!currentWallet) {
+        currentWallet = await getFreshWalletStatus();
+    }
+
+    if (currentWallet && isAddressEqual(frakContext.r, currentWallet)) {
+        return { status: "self-referral", currentWallet } as const;
+    }
+
+    // If the current wallet doesn't have an interaction session, display the modal
+    if (!initialWalletStatus?.interactionSession) {
+        currentWallet = await getFreshWalletStatus();
+    }
+
+    // Push the referred interaction
+    await pushReferralInteraction(frakContext.r);
+    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, or no interaction session
+    if (!walletStatus?.interactionSession) {
+        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";
+            case RpcErrorCodes.serverErrorForInteractionDelegation:
+                return "no-session";
+            default:
+                return "error";
+        }
+    }
+    return "error";
+}

package/src/actions/referral/referralInteraction.ts

@@ -0,0 +1,57 @@
+import type { Hex } from "viem";
+import type { DisplayEmbeddedWalletParamsType, FrakClient } from "../../types";
+import { FrakContextManager } from "../../utils";
+import { watchWalletStatus } from "../index";
+import {
+    type ProcessReferralOptions,
+    processReferral,
+} from "./processReferral";
+
+/**
+ * Function used to display a modal
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.productId - The product id to interact with (if not specified will be recomputed from the current domain)
+ * @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,
+    {
+        productId,
+        modalConfig,
+        options,
+    }: {
+        productId?: Hex;
+        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,
+            productId,
+            options,
+        });
+    } catch (error) {
+        console.warn("Error processing referral", { error });
+    }
+    return;
+}