@frak-labs/core-sdk 0.1.0-beta.6e0d8026 → 0.1.0-beta.8d103039

package/package.json

@@ -11,7 +11,7 @@
       "url": "https://twitter.com/QNivelais"
     }
   ],
-  "version": "0.1.0-beta.6e0d8026",
+  "version": "0.1.0-beta.8d103039",
   "description": "Core SDK of the Frak wallet, low level library to interact directly with the frak ecosystem.",
   "repository": {
     "url": "https://github.com/frak-id/wallet",
@@ -34,7 +34,8 @@
   "type": "module",
   "files": [
     "/dist",
-    "/cdn"
+    "/cdn",
+    "/src"
   ],
   "browser": "./cdn/bundle.js",
   "exports": {

package/src/actions/displayEmbeddedWallet.ts

@@ -0,0 +1,20 @@
+import type {
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    FrakClient,
+} from "../types";
+
+/**
+ * Function used to display the Frak embedded wallet popup
+ * @param client - The current Frak Client
+ * @param params - The parameter used to customise the embedded wallet
+ */
+export async function displayEmbeddedWallet(
+    client: FrakClient,
+    params: DisplayEmbeddedWalletParamsType
+): Promise<DisplayEmbeddedWalletResultType> {
+    return await client.request({
+        method: "frak_displayEmbeddedWallet",
+        params: [params, client.config.metadata],
+    });
+}

package/src/actions/displayModal.ts

@@ -0,0 +1,131 @@
+import type {
+    DisplayModalParamsType,
+    FrakClient,
+    ModalRpcStepsResultType,
+    ModalStepTypes,
+} from "../types";
+
+/**
+ * Function used to display a modal
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.steps - The different steps of the modal
+ * @param args.metadata - The metadata for the modal (customization, etc)
+ * @returns The result of each modal steps
+ *
+ * @description This function will display a modal to the user with the provided steps and metadata.
+ *
+ * @remarks
+ * - The UI of the displayed modal can be configured with the `customCss` property in the `customizations.css` field of the top-level config.
+ * - The `login` and `openSession` steps will be automatically skipped if the user is already logged in or has an active session. It's safe to include these steps in all cases to ensure proper user state.
+ * - Steps are automatically reordered in the following sequence:
+ *     1. `login` (if needed)
+ *     2. `openSession` (if needed)
+ *     3. All other steps in the order specified
+ *     4. `success` (if included, always last)
+ *
+ * @example
+ * Simple sharing modal with steps:
+ *  1. Login (Skipped if already logged in)
+ *  2. Open a session (Skipped if already opened)
+ *  3. Display a success message with sharing link option
+ *
+ * ```ts
+ * const results = await displayModal(frakConfig, {
+ *     steps: {
+ *         // Simple login with no SSO, nor customization
+ *         login: { allowSso: false },
+ *         // Simple session opening, with no customization
+ *         openSession: {},
+ *         // Success message
+ *         final: {
+ *             action: { key: "reward" },
+ *             // Skip this step, it will be only displayed in the stepper within the modal
+ *             autoSkip: true,
+ *         },
+ *     },
+ * });
+ *
+ * console.log("Login step - wallet", results.login.wallet);
+ * console.log("Open session step - start + end", {
+ *     start: results.openSession.startTimestamp,
+ *     end: results.openSession.endTimestamp,
+ * });
+ * ```
+ *
+ * @example
+ * A full modal example, with a few customization options, with the steps:
+ *  1. Login (Skipped if already logged in)
+ *  2. Open a session (Skipped if already opened)
+ *  3. Authenticate via SIWE
+ *  4. Send a transaction
+ *  5. Display a success message with sharing link options
+ *
+ * ```ts
+ * const results = await displayModal(frakConfig, {
+ *     steps: {
+ *         // Login step
+ *         login: {
+ *             allowSso: true,
+ *             ssoMetadata: {
+ *                 logoUrl: "https://my-app.com/logo.png",
+ *                 homepageLink: "https://my-app.com",
+ *             },
+ *         },
+ *         // Simple session opening, with no customisation
+ *         openSession: {},
+ *         // Siwe authentication
+ *         siweAuthenticate: {
+ *             siwe: {
+ *                 domain: "my-app.com",
+ *                 uri: "https://my-app.com/",
+ *                 nonce: generateSiweNonce(),
+ *                 version: "1",
+ *             },
+ *         },
+ *         // Send batched transaction
+ *         sendTransaction: {
+ *             tx: [
+ *                 { to: "0xdeadbeef", data: "0xdeadbeef" },
+ *                 { to: "0xdeadbeef", data: "0xdeadbeef" },
+ *             ],
+ *         },
+ *         // Success message with sharing options
+ *         final: {
+ *             action: {
+ *                 key: "sharing",
+ *                 options: {
+ *                     popupTitle: "Share the app",
+ *                     text: "Discover my super app website",
+ *                     link: "https://my-app.com",
+ *                 },
+ *             },
+ *             dismissedMetadata: {
+ *                 title: "Dismiss",
+ *                 description: "You won't be rewarded for this sharing action",
+ *             },
+ *         },
+ *     },
+ *     metadata: {
+ *         // Header of desktop modals
+ *         header: {
+ *             title: "My-App",
+ *             icon: "https://my-app.com/logo.png",
+ *         },
+ *         // Context that will be present in every modal steps
+ *         context: "My-app overkill flow",
+ *     },
+ * });
+ * ```
+ */
+export async function displayModal<
+    T extends ModalStepTypes[] = ModalStepTypes[],
+>(
+    client: FrakClient,
+    { steps, metadata }: DisplayModalParamsType<T>
+): Promise<ModalRpcStepsResultType<T>> {
+    return (await client.request({
+        method: "frak_displayModal",
+        params: [steps, metadata, client.config.metadata],
+    })) as ModalRpcStepsResultType<T>;
+}

package/src/actions/getProductInformation.ts

@@ -0,0 +1,14 @@
+import type { FrakClient, GetProductInformationReturnType } from "../types";
+
+/**
+ * Function used to get the current product information
+ * @param client - The current Frak Client
+ * @returns The product information in a promise
+ */
+export async function getProductInformation(
+    client: FrakClient
+): Promise<GetProductInformationReturnType> {
+    return await client.request({
+        method: "frak_getProductInformation",
+    });
+}

package/src/actions/index.ts

@@ -0,0 +1,29 @@
+export { watchWalletStatus } from "./watchWalletStatus";
+export { sendInteraction } from "./sendInteraction";
+export { displayModal } from "./displayModal";
+export { displayEmbeddedWallet } from "./displayEmbeddedWallet";
+export { openSso } from "./openSso";
+export { prepareSso } from "./prepareSso";
+export { getProductInformation } from "./getProductInformation";
+// Helper to track the purchase status
+export { trackPurchaseStatus } from "./trackPurchaseStatus";
+// Modal wrappers
+export {
+    siweAuthenticate,
+    type SiweAuthenticateModalParams,
+} from "./wrapper/siweAuthenticate";
+export {
+    sendTransaction,
+    type SendTransactionParams,
+} from "./wrapper/sendTransaction";
+export {
+    modalBuilder,
+    type ModalStepBuilder,
+    type ModalBuilder,
+} from "./wrapper/modalBuilder";
+// Referral interaction
+export { referralInteraction } from "./referral/referralInteraction";
+export {
+    processReferral,
+    type ProcessReferralOptions,
+} from "./referral/processReferral";

package/src/actions/openSso.ts

@@ -0,0 +1,116 @@
+import type {
+    FrakClient,
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+} from "../types";
+import { computeProductId } from "../utils/computeProductId";
+import { generateSsoUrl } from "../utils/sso";
+
+// SSO popup configuration
+export const ssoPopupFeatures =
+    "menubar=no,status=no,scrollbars=no,fullscreen=no,width=500, height=800";
+export const ssoPopupName = "frak-sso";
+
+/**
+ * Function used to open the SSO
+ * @param client - The current Frak Client
+ * @param args - The SSO parameters
+ *
+ * @description Two SSO flow modes:
+ *
+ * **Redirect Mode** (openInSameWindow: true):
+ * - Wallet generates URL and triggers redirect
+ * - Used when redirectUrl is provided
+ *
+ * **Popup Mode** (openInSameWindow: false/omitted):
+ * - SDK generates URL client-side (or uses provided ssoPopupUrl)
+ * - Opens popup synchronously (prevents popup blockers)
+ * - Waits for SSO completion via postMessage
+ *
+ * @example
+ * First we build the sso metadata
+ * ```ts
+ * // Build the metadata
+ * const metadata: SsoMetadata = {
+ *     logoUrl: "https://my-app.com/logo.png",
+ *     homepageLink: "https://my-app.com",
+ * };
+ * ```
+ *
+ * Then, either use it with direct exit (and so user is directly redirected to your website), or a custom redirect URL
+ * :::code-group
+ * ```ts [Popup (default)]
+ * // Opens in popup, SDK generates URL automatically
+ * await openSso(frakConfig, {
+ *     directExit: true,
+ *     metadata,
+ * });
+ * ```
+ * ```ts [Redirect]
+ * // Opens in same window with redirect
+ * await openSso(frakConfig, {
+ *     redirectUrl: "https://my-app.com/frak-sso",
+ *     metadata,
+ *     openInSameWindow: true,
+ * });
+ * ```
+ * ```ts [Custom popup URL]
+ * // Advanced: provide custom SSO URL
+ * const { ssoUrl } = await prepareSso(frakConfig, { metadata });
+ * await openSso(frakConfig, {
+ *     metadata,
+ *     ssoPopupUrl: `${ssoUrl}&custom=param`,
+ * });
+ * ```
+ * :::
+ */
+export async function openSso(
+    client: FrakClient,
+    args: OpenSsoParamsType
+): Promise<OpenSsoReturnType> {
+    const { metadata, customizations, walletUrl } = client.config;
+
+    // Check if redirect mode (default to true if redirectUrl present)
+    const isRedirectMode = args.openInSameWindow ?? !!args.redirectUrl;
+
+    if (isRedirectMode) {
+        // Redirect flow: Wallet generates URL and triggers redirect via lifecycle event
+        // This must happen on wallet side because only the iframe can trigger the redirect
+        return await client.request({
+            method: "frak_openSso",
+            params: [args, metadata.name, customizations?.css],
+        });
+    }
+
+    // Popup flow: Generate URL on SDK side and open synchronously
+    // This ensures window.open() is called in same tick as user gesture (no popup blocker)
+
+    // Step 1: Generate or use provided SSO URL
+    const ssoUrl =
+        args.ssoPopupUrl ??
+        generateSsoUrl(
+            walletUrl ?? "https://wallet.frak.id",
+            args,
+            computeProductId(),
+            metadata.name,
+            customizations?.css
+        );
+
+    // Step 2: Open popup synchronously (critical for popup blocker prevention)
+    const popup = window.open(ssoUrl, ssoPopupName, ssoPopupFeatures);
+    if (!popup) {
+        throw new Error(
+            "Popup was blocked. Please allow popups for this site."
+        );
+    }
+    popup.focus();
+
+    // Step 3: Wait for SSO completion via RPC
+    // The wallet iframe will resolve this when SSO page sends sso_complete message
+    const result = await client.request({
+        method: "frak_openSso",
+        params: [args, metadata.name, customizations?.css],
+    });
+
+    return result ?? {};
+}

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 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 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;
+}