@frak-labs/core-sdk 0.2.0 → 0.2.1-beta.06c52c98

package/src/actions/referral/processReferral.ts

@@ -1,232 +1,186 @@
-import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
-import { type Address, isAddressEqual } from "viem";
+import { isAddressEqual } from "viem";
 import type {
-    DisplayEmbeddedWalletParamsType,
     FrakClient,
     FrakContext,
+    FrakContextV2,
     WalletStatusReturnType,
 } from "../../types";
-import { FrakContextManager, trackEvent } from "../../utils";
-import { displayEmbeddedWallet } from "../displayEmbeddedWallet";
+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"
-    | "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
+ * Track an arrival event if the context version is recognized.
+ * Sends both tracking analytics and the arrival interaction RPC.
  *
- * @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
+ * @returns true if the context was valid and tracked, false otherwise
  */
-export async function processReferral(
+function trackArrivalIfValid(
     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",
-                    },
-                },
+    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,
-        });
-    }
-
-    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,
+        sendInteraction(client, {
+            type: "arrival",
+            referrerClientId: frakContext.c,
+            referrerMerchantId: frakContext.m,
+            referralTimestamp: frakContext.t,
+            landingUrl,
         });
+        return true;
+    }
 
-        // 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,
         });
+        return true;
+    }
 
-        // Update the current url with the right data
-        FrakContextManager.replaceUrl({
-            url: window.location?.href,
-            context: options?.alwaysAppendUrl
-                ? { r: walletStatus?.wallet }
-                : null,
-        });
+    return false;
+}
 
-        // And map the error a state
-        return mapErrorToState(error);
-    }
+/**
+ * Build a V2 context representing the current user for URL replacement.
+ * @returns A V2 context, or null if clientId or merchantId is unavailable
+ */
+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),
+    };
 }
 
 /**
- * Process referral logic - ensure user is logged in and check for self-referral
+ * Client-side self-referral preflight check.
+ * Prevents unnecessary backend round-trips for obvious self-referrals.
  */
-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();
+function isSelfReferral(
+    frakContext: FrakContext,
+    walletStatus?: WalletStatusReturnType
+): boolean {
+    if (isV2Context(frakContext)) {
+        return getClientId() === frakContext.c;
     }
-
-    // Check for self-referral
-    if (currentWallet && isAddressEqual(frakContext.r, currentWallet)) {
-        return { status: "self-referral", currentWallet } as const;
+    if (isV1Context(frakContext) && walletStatus?.wallet) {
+        return isAddressEqual(frakContext.r, walletStatus.wallet);
     }
-
-    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, display modal
-    if (walletStatus?.key !== "connected") {
-        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";
-            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

@@ -69,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);
@@ -77,14 +76,12 @@ describe("referralInteraction", () => {
         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,
         });
     });
@@ -110,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")
@@ -139,7 +138,6 @@ describe("referralInteraction", () => {
         expect(processReferral).toHaveBeenCalledWith(
             mockClient,
             expect.objectContaining({
-                modalConfig: undefined,
                 options: undefined,
             })
         );

package/src/actions/referral/referralInteraction.ts

@@ -1,4 +1,4 @@
-import type { DisplayEmbeddedWalletParamsType, FrakClient } from "../../types";
+import type { FrakClient } from "../../types";
 import { FrakContextManager } from "../../utils";
 import { watchWalletStatus } from "../index";
 import {
@@ -10,7 +10,6 @@ import {
  * 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
@@ -18,15 +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,
     {
-        modalConfig,
         options,
     }: {
-        modalConfig?: DisplayEmbeddedWalletParamsType;
         options?: ProcessReferralOptions;
     } = {}
 ) {
@@ -39,10 +35,9 @@ export async function referralInteraction(
     const currentWalletStatus = await watchWalletStatus(client);
 
     try {
-        return await processReferral(client, {
+        return processReferral(client, {
             walletStatus: currentWalletStatus,
             frakContext,
-            modalConfig,
             options,
         });
     } catch (error) {

package/src/actions/trackPurchaseStatus.test.ts

@@ -11,12 +11,14 @@ vi.mock("../utils/clientId", () => ({
     getClientId: vi.fn().mockReturnValue("test-client-id"),
 }));
 
-vi.mock("../utils/merchantId", () => ({
-    fetchMerchantId: vi.fn().mockResolvedValue(undefined),
+vi.mock("../utils/sdkConfigStore", () => ({
+    sdkConfigStore: {
+        resolveMerchantId: vi.fn().mockResolvedValue(undefined),
+    },
 }));
 
 import { getClientId } from "../utils/clientId";
-import { fetchMerchantId } from "../utils/merchantId";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 import { trackPurchaseStatus } from "./trackPurchaseStatus";
 
 describe.sequential("trackPurchaseStatus", () => {
@@ -100,7 +102,9 @@ describe.sequential("trackPurchaseStatus", () => {
         });
 
         vi.mocked(getClientId).mockReturnValue("test-client-id");
-        vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+        vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+            undefined
+        );
 
         fetchSpy = vi.fn().mockResolvedValue({
             ok: true,
@@ -228,12 +232,15 @@ describe.sequential("trackPurchaseStatus", () => {
         test("should resolve merchantId from explicit param first", async () => {
             setupStorage({
                 interactionToken: "token-123",
-                merchantId: "session-merchant-id",
+                merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
-            const merchantLookupCallsBefore =
-                vi.mocked(fetchMerchantId).mock.calls.length;
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "fetched-merchant-id"
+            );
+            const merchantLookupCallsBefore = vi.mocked(
+                sdkConfigStore.resolveMerchantId
+            ).mock.calls.length;
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -253,19 +260,20 @@ describe.sequential("trackPurchaseStatus", () => {
                     merchantId: "explicit-merchant-id",
                 })
             );
-            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
-                merchantLookupCallsBefore
-            );
+            expect(
+                vi.mocked(sdkConfigStore.resolveMerchantId).mock.calls.length
+            ).toBe(merchantLookupCallsBefore);
         });
 
         test("should fall back to sessionStorage for merchantId", async () => {
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "session-merchant-id"
+            );
             setupStorage({
                 interactionToken: "token-123",
-                merchantId: "session-merchant-id",
+                merchantId: null,
                 clientId: "test-client-id",
             });
-            const merchantLookupCallsBefore =
-                vi.mocked(fetchMerchantId).mock.calls.length;
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -284,18 +292,20 @@ describe.sequential("trackPurchaseStatus", () => {
                     merchantId: "session-merchant-id",
                 })
             );
-            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
-                merchantLookupCallsBefore
-            );
+            expect(
+                vi.mocked(sdkConfigStore.resolveMerchantId)
+            ).toHaveBeenCalled();
         });
 
-        test("should fall back to fetchMerchantId when no explicit or sessionStorage", async () => {
+        test("should fall back to resolveMerchantId when no explicit merchantId", async () => {
             setupStorage({
                 interactionToken: "token-123",
                 merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "fetched-merchant-id"
+            );
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -322,7 +332,9 @@ describe.sequential("trackPurchaseStatus", () => {
                 merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                undefined
+            );
             const callCountBefore = getTrackingRequests().length;
 
             await trackPurchaseStatus({

package/src/actions/trackPurchaseStatus.ts

@@ -1,6 +1,6 @@
 import { getBackendUrl } from "../utils/backendUrl";
 import { getClientId } from "../utils/clientId";
-import { fetchMerchantId } from "../utils/merchantId";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 
 /**
  * Function used to track the status of a purchase
@@ -26,7 +26,7 @@ import { fetchMerchantId } from "../utils/merchantId";
  * }
  *
  * @remarks
- * - Merchant id is resolved in this order: explicit `args.merchantId`, `frak-merchant-id` from session storage, then `fetchMerchantId()`.
+ * - Merchant id is resolved in this order: explicit `args.merchantId`, then `sdkConfigStore.resolveMerchantId()` (config store → sessionStorage → backend fetch).
  * - This function supports anonymous users and will use the `x-frak-client-id` header when available.
  * - At least one identity source must exist (`frak-wallet-interaction-token` or `x-frak-client-id`), otherwise the tracking request is skipped.
  * - This function will print a warning if used in a non-browser environment or if no identity / merchant id can be resolved.
@@ -52,10 +52,8 @@ export async function trackPurchaseStatus(args: {
         return;
     }
 
-    const merchantIdFromStorage =
-        window.sessionStorage.getItem("frak-merchant-id");
     const merchantId =
-        args.merchantId ?? merchantIdFromStorage ?? (await fetchMerchantId());
+        args.merchantId ?? (await sdkConfigStore.resolveMerchantId());
 
     if (!merchantId) {
         console.warn("[Frak] No merchant id found, skipping purchase check");

package/src/actions/wrapper/modalBuilder.test.ts

@@ -196,7 +196,8 @@ describe("modalBuilder", () => {
 
             expect(displayModal).toHaveBeenCalledWith(
                 mockClient,
-                builder.params
+                builder.params,
+                undefined
             );
         });
 
@@ -216,7 +217,8 @@ describe("modalBuilder", () => {
                 mockClient,
                 expect.objectContaining({
                     metadata: { header: { title: "Overridden" } },
-                })
+                }),
+                undefined
             );
         });
 

package/src/actions/wrapper/modalBuilder.ts

@@ -46,11 +46,13 @@ export type ModalStepBuilder<
     /**
      * Display the modal
      * @param metadataOverride - Function returning optional metadata to override the current modal metadata
+     * @param placement - Optional placement ID to associate with this modal display
      */
     display: (
         metadataOverride?: (
             current?: ModalRpcMetadata
-        ) => ModalRpcMetadata | undefined
+        ) => ModalRpcMetadata | undefined,
+        placement?: string
     ) => Promise<ModalRpcStepsResultType<Steps>>;
 };
 
@@ -177,27 +179,23 @@ function modalStepsBuilder<CurrentSteps extends ModalStepTypes[]>(
         );
     }
 
-    // Function to display it
     async function display(
         metadataOverride?: (
             current?: ModalRpcMetadata
-        ) => ModalRpcMetadata | undefined
+        ) => ModalRpcMetadata | undefined,
+        placement?: string
     ) {
-        // If we have a metadata override, apply it
         if (metadataOverride) {
             params.metadata = metadataOverride(params.metadata ?? {});
         }
-        return await displayModal(client, params);
+        return await displayModal(client, params, placement);
     }
 
     return {
-        // Access current modal params
         params,
-        // Function to add new steps
         sendTx,
         reward,
         sharing,
-        // Display the modal
         display,
     };
 }