@frak-labs/core-sdk 0.1.1 → 0.2.0-beta.7898df5b

package/src/actions/referral/processReferral.ts

@@ -1,256 +1,186 @@
-import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
-import { type Address, type Hex, isAddressEqual } from "viem";
-import { ReferralInteractionEncoder } from "../../interactions";
+import { isAddressEqual } from "viem";
 import type {
-    DisplayEmbeddedWalletParamsType,
     FrakClient,
     FrakContext,
+    FrakContextV2,
     WalletStatusReturnType,
 } from "../../types";
-import { FrakContextManager, trackEvent } from "../../utils";
-import { displayEmbeddedWallet, sendInteraction } from "../index";
+import { isV1Context, isV2Context } from "../../types";
+import { FrakContextManager, getClientId, trackEvent } from "../../utils";
+import { sendInteraction } from "../sendInteraction";
 
 /**
- * The different states of the referral process
+ * Options for the referral auto-interaction process.
+ */
+export type ProcessReferralOptions = {
+    /**
+     * If true, always replace the URL with the current user's referral context
+     * so the next visitor gets referred by this user.
+     * @defaultValue false
+     */
+    alwaysAppendUrl?: boolean;
+    /**
+     * Merchant ID for building the current user's referral context.
+     * Required when `alwaysAppendUrl` is true and the incoming context is V1.
+     * For V2 contexts, the merchantId is already embedded in the context.
+     */
+    merchantId?: string;
+};
+
+/**
+ * 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
+ * Track an arrival event if the context version is recognized.
+ * Sends both tracking analytics and the arrival interaction RPC.
  *
- *  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
+ * @returns true if the context was valid and tracked, false otherwise
  */
-export async function processReferral(
+function trackArrivalIfValid(
     client: FrakClient,
-    {
-        walletStatus,
-        frakContext,
-        modalConfig,
-        productId,
-        options,
-    }: {
-        walletStatus?: WalletStatusReturnType;
-        frakContext?: Partial<FrakContext> | null;
-        modalConfig?: DisplayEmbeddedWalletParamsType;
-        productId?: Hex;
-        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,
-        },
-    });
-
-    // 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",
-                    },
-                },
+    frakContext: FrakContext,
+    walletStatus?: WalletStatusReturnType
+): boolean {
+    const landingUrl =
+        typeof window !== "undefined" ? window.location.href : undefined;
+
+    if (isV2Context(frakContext)) {
+        trackEvent(client, "user_referred_started", {
+            properties: {
+                referrerClientId: frakContext.c,
+                walletStatus: walletStatus?.key,
             },
-            walletStatus,
         });
-    }
-
-    // Helper function to push the interaction
-    async function pushReferralInteraction(referrer: Address) {
-        const interaction = ReferralInteractionEncoder.referred({
-            referrer,
+        sendInteraction(client, {
+            type: "arrival",
+            referrerClientId: frakContext.c,
+            referrerMerchantId: frakContext.m,
+            referralTimestamp: frakContext.t,
+            landingUrl,
         });
-        await sendInteraction(client, { productId, interaction });
+        return true;
     }
 
-    try {
-        // Do the core processing logic
-        const { status, currentWallet } = await processReferralLogic({
-            initialWalletStatus: walletStatus,
-            getFreshWalletStatus,
-            pushReferralInteraction,
-            // 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", {
+    if (isV1Context(frakContext)) {
+        trackEvent(client, "user_referred_started", {
             properties: {
-                status,
-                referrer: frakContext?.r,
-                wallet: currentWallet,
+                referrer: frakContext.r,
+                walletStatus: walletStatus?.key,
             },
         });
-
-        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",
-            },
+        sendInteraction(client, {
+            type: "arrival",
+            referrerWallet: frakContext.r,
+            landingUrl,
         });
-
-        // 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);
+        return true;
     }
+
+    return false;
 }
 
 /**
- * Automatically submit a referral interaction when detected
- *   -> And automatically set the referral context in the url
- * @param walletStatus
- * @param frakContext
+ * Build a V2 context representing the current user for URL replacement.
+ * @returns A V2 context, or null if clientId or merchantId is unavailable
  */
-async function processReferralLogic({
-    initialWalletStatus,
-    getFreshWalletStatus,
-    pushReferralInteraction,
-    frakContext,
-}: {
-    initialWalletStatus?: WalletStatusReturnType;
-    getFreshWalletStatus: () => Promise<Address | undefined>;
-    pushReferralInteraction: (referrer: Address) => Promise<void>;
-    frakContext: Pick<FrakContext, "r">;
-}) {
-    // Get the current wallet, without auto displaying the modal
-    let currentWallet = initialWalletStatus?.wallet;
+function buildCurrentUserContext(merchantId: string): FrakContextV2 | null {
+    const clientId = getClientId();
+    if (!clientId) return null;
+    return {
+        v: 2,
+        c: clientId,
+        m: merchantId,
+        t: Math.floor(Date.now() / 1000),
+    };
+}
 
-    // If we don't have a current wallet, display the modal
-    if (!currentWallet) {
-        // Track the event
-        currentWallet = await getFreshWalletStatus();
+/**
+ * Client-side self-referral preflight check.
+ * Prevents unnecessary backend round-trips for obvious self-referrals.
+ */
+function isSelfReferral(
+    frakContext: FrakContext,
+    walletStatus?: WalletStatusReturnType
+): boolean {
+    if (isV2Context(frakContext)) {
+        return getClientId() === frakContext.c;
     }
-
-    if (currentWallet && isAddressEqual(frakContext.r, currentWallet)) {
-        return { status: "self-referral", currentWallet } as const;
+    if (isV1Context(frakContext) && walletStatus?.wallet) {
+        return isAddressEqual(frakContext.r, walletStatus.wallet);
     }
-
-    // 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;
+    return false;
 }
 
 /**
- * Helper to ensure a wallet is connected, and display a modal if we got everything needed
+ * Handle the full referral interaction flow:
+ *
+ *  1. Check if the user has been referred (if not, early exit)
+ *  2. Preflight self-referral check (if yes, early exit)
+ *  3. Track the arrival event
+ *  4. Replace the current URL with the user's own referral context
+ *  5. Return the resulting referral state
+ *
+ * @param client - The current Frak Client
+ * @param args
+ * @param args.walletStatus - The current user wallet status
+ * @param args.frakContext - The referral context parsed from the URL
+ * @param args.options - Options for URL replacement and merchant context
+ * @returns The referral state
+ *
+ * @see {@link @frak-labs/core-sdk!ModalStepTypes} for modal step types
  */
-async function ensureWalletConnected(
+export function processReferral(
     client: FrakClient,
     {
-        modalConfig,
         walletStatus,
+        frakContext,
+        options,
     }: {
-        modalConfig?: DisplayEmbeddedWalletParamsType;
         walletStatus?: WalletStatusReturnType;
+        frakContext?: FrakContext | null;
+        options?: ProcessReferralOptions;
     }
-) {
-    // If wallet not connected, or no interaction session
-    if (!walletStatus?.interactionSession) {
-        const result = await displayEmbeddedWallet(client, modalConfig ?? {});
-        return result?.wallet ?? undefined;
+): ReferralState {
+    if (!frakContext) {
+        return "no-referrer";
     }
 
-    return walletStatus.wallet ?? undefined;
-}
+    if (isSelfReferral(frakContext, walletStatus)) {
+        return "self-referral";
+    }
 
-/**
- * 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";
-        }
+    if (!trackArrivalIfValid(client, frakContext, walletStatus)) {
+        return "no-referrer";
     }
-    return "error";
+
+    // V2 context embeds merchantId; V1 falls back to options
+    const contextMerchantId = isV2Context(frakContext)
+        ? frakContext.m
+        : options?.merchantId;
+
+    const replaceContext =
+        options?.alwaysAppendUrl && contextMerchantId
+            ? buildCurrentUserContext(contextMerchantId)
+            : null;
+
+    FrakContextManager.replaceUrl({
+        url: window.location?.href,
+        context: replaceContext,
+    });
+
+    trackEvent(client, "user_referred_completed", {
+        properties: {
+            status: "success",
+        },
+    });
+
+    return "success";
 }

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

@@ -21,9 +21,6 @@ describe("referralInteraction", () => {
         request: vi.fn(),
     } as any;
 
-    const mockProductId =
-        "0x0000000000000000000000000000000000000000000000000000000000000002" as Hex;
-
     beforeEach(() => {
         vi.clearAllMocks();
         Object.defineProperty(global, "window", {
@@ -55,8 +52,8 @@ describe("referralInteraction", () => {
 
         vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
         vi.mocked(watchWalletStatus).mockResolvedValue({
+            key: "connected",
             wallet: "0x123" as Hex,
-            interactionSession: true,
         } as any);
         vi.mocked(processReferral).mockResolvedValue("success");
 
@@ -72,7 +69,6 @@ describe("referralInteraction", () => {
 
         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);
@@ -80,16 +76,12 @@ describe("referralInteraction", () => {
         vi.mocked(processReferral).mockResolvedValue("success");
 
         await referralInteraction(mockClient, {
-            productId: mockProductId,
-            modalConfig: mockModalConfig as any,
             options: mockOptions,
         });
 
         expect(processReferral).toHaveBeenCalledWith(mockClient, {
             walletStatus: mockWalletStatus,
             frakContext: mockContext,
-            modalConfig: mockModalConfig,
-            productId: mockProductId,
             options: mockOptions,
         });
     });
@@ -115,7 +107,9 @@ describe("referralInteraction", () => {
 
         vi.mocked(FrakContextManager.parse).mockReturnValue({} as any);
         vi.mocked(watchWalletStatus).mockResolvedValue(null as any);
-        vi.mocked(processReferral).mockRejectedValue(new Error("Test error"));
+        vi.mocked(processReferral).mockImplementation(() => {
+            throw new Error("Test error");
+        });
 
         const consoleSpy = vi
             .spyOn(console, "warn")
@@ -144,8 +138,6 @@ describe("referralInteraction", () => {
         expect(processReferral).toHaveBeenCalledWith(
             mockClient,
             expect.objectContaining({
-                modalConfig: undefined,
-                productId: undefined,
                 options: undefined,
             })
         );

package/src/actions/referral/referralInteraction.ts

@@ -1,5 +1,4 @@
-import type { Hex } from "viem";
-import type { DisplayEmbeddedWalletParamsType, FrakClient } from "../../types";
+import type { FrakClient } from "../../types";
 import { FrakContextManager } from "../../utils";
 import { watchWalletStatus } from "../index";
 import {
@@ -8,11 +7,9 @@ import {
 } from "./processReferral";
 
 /**
- * Function used to display a modal
+ * Function used to handle referral interactions
  * @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
@@ -20,17 +17,12 @@ import {
  * @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;
     } = {}
 ) {
@@ -43,11 +35,9 @@ export async function referralInteraction(
     const currentWalletStatus = await watchWalletStatus(client);
 
     try {
-        return await processReferral(client, {
+        return processReferral(client, {
             walletStatus: currentWalletStatus,
             frakContext,
-            modalConfig,
-            productId,
             options,
         });
     } catch (error) {

package/src/actions/sendInteraction.ts

@@ -1,32 +1,56 @@
-import type {
-    FrakClient,
-    SendInteractionParamsType,
-    SendInteractionReturnType,
-} from "../types";
-import { computeProductId } from "../utils/computeProductId";
+import type { FrakClient } from "../types";
+import type { SendInteractionParamsType } from "../types/rpc/interaction";
+import { getClientId } from "../utils/clientId";
 
 /**
- * Function used to send an interaction
- * @param client - The current Frak Client
- * @param args
+ * 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
+ *
+ * @description Sends a user interaction event through the wallet iframe RPC. Supports three interaction types: arrival tracking, sharing events, and custom interactions.
  *
  * @example
- * const interaction = PressInteractionEncoder.openArticle({
- *     articleId: keccak256(toHex("article-slug")),
+ * Track a user arrival with referral attribution:
+ * ```ts
+ * await sendInteraction(client, {
+ *     type: "arrival",
+ *     referrerWallet: "0x1234...abcd",
+ *     landingUrl: window.location.href,
+ *     utmSource: "twitter",
+ *     utmMedium: "social",
+ *     utmCampaign: "launch-2026",
  * });
- * const { delegationId } = await sendInteraction(frakConfig, {
- *     interaction,
+ * ```
+ *
+ * @example
+ * Track a sharing event:
+ * ```ts
+ * await sendInteraction(client, { type: "sharing" });
+ * ```
+ *
+ * @example
+ * Send a custom interaction:
+ * ```ts
+ * await sendInteraction(client, {
+ *     type: "custom",
+ *     customType: "newsletter_signup",
+ *     data: { email: "user@example.com" },
  * });
- * 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],
-    });
+    params: SendInteractionParamsType
+): Promise<void> {
+    try {
+        await client.request({
+            method: "frak_sendInteraction",
+            params: [params, { clientId: getClientId() }],
+        });
+    } catch {
+        // Silent failure - fire-and-forget
+        console.warn("[Frak SDK] Failed to send interaction:", params.type);
+    }
 }