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

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

package/src/actions/sendInteraction.ts

@@ -0,0 +1,32 @@
+import type {
+    FrakClient,
+    SendInteractionParamsType,
+    SendInteractionReturnType,
+} from "../types";
+import { computeProductId } from "../utils/computeProductId";
+
+/**
+ * Function used to send an interaction
+ * @param client - The current Frak Client
+ * @param args
+ *
+ * @example
+ * const interaction = PressInteractionEncoder.openArticle({
+ *     articleId: keccak256(toHex("article-slug")),
+ * });
+ * const { delegationId } = await sendInteraction(frakConfig, {
+ *     interaction,
+ * });
+ * console.log("Delegated interaction id", delegationId);
+ */
+export async function sendInteraction(
+    client: FrakClient,
+    { productId, interaction, validation }: SendInteractionParamsType
+): Promise<SendInteractionReturnType> {
+    const pId = productId ?? computeProductId(client.config);
+
+    return await client.request({
+        method: "frak_sendInteraction",
+        params: [pId, interaction, validation],
+    });
+}

package/src/actions/trackPurchaseStatus.ts

@@ -0,0 +1,53 @@
+/**
+ * Function used to track the status of a purchase
+ * when a purchase is tracked, the `purchaseCompleted` interactions will be automatically send for the user when we receive the purchase confirmation via webhook.
+ *
+ * @param args.customerId - The customer id that made the purchase (on your side)
+ * @param args.orderId - The order id of the purchase (on your side)
+ * @param args.token - The token of the purchase
+ *
+ * @description This function will send a request to the backend to listen for the purchase status.
+ *
+ * @example
+ * async function trackPurchase(checkout) {
+ *   const payload = {
+ *     customerId: checkout.order.customer.id,
+ *     orderId: checkout.order.id,
+ *     token: checkout.token,
+ *   };
+ *
+ *   await trackPurchaseStatus(payload);
+ * }
+ *
+ * @remarks
+ * - The `trackPurchaseStatus` function requires the `frak-wallet-interaction-token` stored in the session storage to authenticate the request.
+ * - This function will print a warning if used in a non-browser environment or if the wallet interaction token is not available.
+ */
+export async function trackPurchaseStatus(args: {
+    customerId: string | number;
+    orderId: string | number;
+    token: string;
+}) {
+    if (typeof window === "undefined") {
+        console.warn("[Frak] No window found, can't track purchase");
+        return;
+    }
+    const interactionToken = window.sessionStorage.getItem(
+        "frak-wallet-interaction-token"
+    );
+    if (!interactionToken) {
+        console.warn("[Frak] No frak session found, skipping purchase check");
+        return;
+    }
+
+    // Submit the listening request
+    await fetch("https://backend.frak.id/interactions/listenForPurchase", {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "x-wallet-sdk-auth": interactionToken,
+        },
+        body: JSON.stringify(args),
+    });
+}

package/src/actions/watchWalletStatus.ts

@@ -0,0 +1,94 @@
+import { Deferred } from "@frak-labs/frame-connector";
+import type { FrakClient } from "../types/client";
+import type { WalletStatusReturnType } from "../types/rpc/walletStatus";
+
+/**
+ * Function used to watch the current frak wallet status
+ * @param client - The current Frak Client
+ * @param callback - The callback that will receive any wallet status change
+ * @returns A promise resolving with the initial wallet status
+ *
+ * @description This function will return the current wallet status, and will listen to any change in the wallet status.
+ *
+ * @example
+ * await watchWalletStatus(frakConfig, (status: WalletStatusReturnType) => {
+ *     if (status.key === "connected") {
+ *         console.log("Wallet connected:", status.wallet);
+ *         console.log("Current interaction session:", status.interactionSession);
+ *     } else {
+ *         console.log("Wallet not connected");
+ *     }
+ * });
+ */
+export function watchWalletStatus(
+    client: FrakClient,
+    callback?: (status: WalletStatusReturnType) => void
+): Promise<WalletStatusReturnType> {
+    // If no callback is provided, just do a request with deferred result
+    if (!callback) {
+        return client
+            .request({ method: "frak_listenToWalletStatus" })
+            .then((result) => {
+                // Handle side effects of this request
+                walletStatusSideEffect(client, result);
+
+                // Return the result
+                return result;
+            });
+    }
+
+    // Otherwise, listen to the wallet status and return the first one received
+    const firstResult = new Deferred<WalletStatusReturnType>();
+    let hasResolved = false;
+
+    // Start the listening request, and return the first result
+    client.listenerRequest(
+        {
+            method: "frak_listenToWalletStatus",
+        },
+        (status) => {
+            // Handle side effects of this request
+            walletStatusSideEffect(client, status);
+
+            // Transmit the status to the callback
+            callback(status);
+
+            // If the promise hasn't resolved yet, resolve it
+            if (!hasResolved) {
+                firstResult.resolve(status);
+                hasResolved = true;
+            }
+        }
+    );
+
+    return firstResult.promise;
+}
+
+/**
+ * Helper to save a potential interaction token
+ * @param interactionToken
+ */
+function walletStatusSideEffect(
+    client: FrakClient,
+    status: WalletStatusReturnType
+) {
+    if (typeof window === "undefined") {
+        return;
+    }
+
+    // Update the global properties
+    client.openPanel?.setGlobalProperties({
+        wallet: status.wallet ?? null,
+    });
+
+    if (status.interactionToken) {
+        // If we got an interaction token, save it
+        window.sessionStorage.setItem(
+            "frak-wallet-interaction-token",
+            status.interactionToken
+        );
+    } else {
+        // Otherwise, remove it
+        window.sessionStorage.removeItem("frak-wallet-interaction-token");
+    }
+}

package/src/actions/wrapper/modalBuilder.ts

@@ -0,0 +1,212 @@
+import type {
+    DisplayModalParamsType,
+    FinalActionType,
+    FinalModalStepType,
+    FrakClient,
+    LoginModalStepType,
+    ModalRpcMetadata,
+    ModalRpcStepsResultType,
+    ModalStepTypes,
+    OpenInteractionSessionModalStepType,
+    SendTransactionModalStepType,
+} from "../../types";
+import { displayModal } from "../displayModal";
+
+/**
+ * Represent the type of the modal step builder
+ */
+export type ModalStepBuilder<
+    Steps extends ModalStepTypes[] = ModalStepTypes[],
+> = {
+    /**
+     * The current modal params
+     */
+    params: DisplayModalParamsType<Steps>;
+    /**
+     * Add a send transaction step to the modal
+     */
+    sendTx: (
+        options: SendTransactionModalStepType["params"]
+    ) => ModalStepBuilder<[...Steps, SendTransactionModalStepType]>;
+    /**
+     * Add a final step of type reward to the modal
+     */
+    reward: (
+        options?: Omit<FinalModalStepType["params"], "action">
+    ) => ModalStepBuilder<[...Steps, FinalModalStepType]>;
+    /**
+     * Add a final step of type sharing to the modal
+     */
+    sharing: (
+        sharingOptions?: Extract<
+            FinalActionType,
+            { key: "sharing" }
+        >["options"],
+        options?: Omit<FinalModalStepType["params"], "action">
+    ) => ModalStepBuilder<[...Steps, FinalModalStepType]>;
+    /**
+     * Display the modal
+     * @param metadataOverride - Function returning optional metadata to override the current modal metadata
+     */
+    display: (
+        metadataOverride?: (
+            current?: ModalRpcMetadata
+        ) => ModalRpcMetadata | undefined
+    ) => Promise<ModalRpcStepsResultType<Steps>>;
+};
+
+/**
+ * Represent the output type of the modal builder
+ */
+export type ModalBuilder = ModalStepBuilder<
+    [LoginModalStepType, OpenInteractionSessionModalStepType]
+>;
+
+/**
+ * Helper to craft Frak modal, and share a base initial config
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.metadata - Common modal metadata (customisation, language etc)
+ * @param args.login - Login step parameters
+ * @param args.openSession - Open session step parameters
+ *
+ * @description This function will create a modal builder with the provided metadata, login and open session parameters.
+ *
+ * @example
+ * Here is an example of how to use the `modalBuilder` to create and display a sharing modal:
+ *
+ * ```js
+ * // Create the modal builder
+ * const modalBuilder = window.FrakSDK.modalBuilder(frakClient, baseModalConfig);
+ *
+ * // Configure the information to be shared via the sharing link
+ * const sharingConfig = {
+ *   popupTitle: "Share this with your friends",
+ *   text: "Discover our product!",
+ *   link: window.location.href,
+ * };
+ *
+ * // Display the sharing modal
+ * function modalShare() {
+ *   modalBuilder.sharing(sharingConfig).display();
+ * }
+ * ```
+ *
+ * @see {@link ModalStepTypes} for more info about each modal step types and their parameters
+ * @see {@link ModalRpcMetadata} for more info about the metadata that can be passed to the modal
+ * @see {@link ModalRpcStepsResultType} for more info about the result of each modal steps
+ * @see {@link displayModal} for more info about how the modal is displayed
+ */
+export function modalBuilder(
+    client: FrakClient,
+    {
+        metadata,
+        login,
+        openSession,
+    }: {
+        metadata?: ModalRpcMetadata;
+        login?: LoginModalStepType["params"];
+        openSession?: OpenInteractionSessionModalStepType["params"];
+    }
+): ModalBuilder {
+    // Build the initial modal params
+    const baseParams: DisplayModalParamsType<
+        [LoginModalStepType, OpenInteractionSessionModalStepType]
+    > = {
+        steps: {
+            login: login ?? {},
+            openSession: openSession ?? {},
+        },
+        metadata,
+    };
+
+    // Return the step builder
+    return modalStepsBuilder(client, baseParams);
+}
+
+/**
+ * Modal step builder, allowing to add new steps to the modal, and to build and display it
+ */
+function modalStepsBuilder<CurrentSteps extends ModalStepTypes[]>(
+    client: FrakClient,
+    params: DisplayModalParamsType<CurrentSteps>
+): ModalStepBuilder<CurrentSteps> {
+    // Function add the send tx step
+    function sendTx(options: SendTransactionModalStepType["params"]) {
+        return modalStepsBuilder<
+            [...CurrentSteps, SendTransactionModalStepType]
+        >(client, {
+            ...params,
+            steps: {
+                ...params.steps,
+                sendTransaction: options,
+            },
+        } as DisplayModalParamsType<
+            [...CurrentSteps, SendTransactionModalStepType]
+        >);
+    }
+
+    // Function to add a reward step at the end
+    function reward(options?: Omit<FinalModalStepType["params"], "action">) {
+        return modalStepsBuilder<[...CurrentSteps, FinalModalStepType]>(
+            client,
+            {
+                ...params,
+                steps: {
+                    ...params.steps,
+                    final: {
+                        ...options,
+                        action: { key: "reward" },
+                    },
+                },
+            } as DisplayModalParamsType<[...CurrentSteps, FinalModalStepType]>
+        );
+    }
+
+    // Function to add sharing step at the end
+    function sharing(
+        sharingOptions?: Extract<
+            FinalActionType,
+            { key: "sharing" }
+        >["options"],
+        options?: Omit<FinalModalStepType["params"], "action">
+    ) {
+        return modalStepsBuilder<[...CurrentSteps, FinalModalStepType]>(
+            client,
+            {
+                ...params,
+                steps: {
+                    ...params.steps,
+                    final: {
+                        ...options,
+                        action: { key: "sharing", options: sharingOptions },
+                    },
+                },
+            } as DisplayModalParamsType<[...CurrentSteps, FinalModalStepType]>
+        );
+    }
+
+    // Function to display it
+    async function display(
+        metadataOverride?: (
+            current?: ModalRpcMetadata
+        ) => ModalRpcMetadata | undefined
+    ) {
+        // If we have a metadata override, apply it
+        if (metadataOverride) {
+            params.metadata = metadataOverride(params.metadata ?? {});
+        }
+        return await displayModal(client, params);
+    }
+
+    return {
+        // Access current modal params
+        params,
+        // Function to add new steps
+        sendTx,
+        reward,
+        sharing,
+        // Display the modal
+        display,
+    };
+}