@frak-labs/core-sdk 0.2.0 → 0.2.1

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/index.ts

@@ -28,6 +28,8 @@ export type {
     FrakClient,
     // Utils
     FrakContext,
+    FrakContextV1,
+    FrakContextV2,
     FrakLifecycleEvent,
     // Config
     FrakWalletSdkConfig,
@@ -74,6 +76,7 @@ export type {
     // Rpc
     WalletStatusReturnType,
 } from "./types";
+export { isV1Context, isV2Context } from "./types";
 // Utils
 export {
     type AppSpecificSsoMetadata,

package/src/types/context.ts

@@ -1,13 +1,55 @@
 import type { Address } from "viem";
 
 /**
- * The current Frak Context
- *
- * For now, only contain a referrer address.
- *
+ * V1 (legacy) Frak Context — contains only the referrer wallet address.
+ * Used for backward compatibility with old sharing links.
  * @ignore
  */
-export type FrakContext = {
-    // Referrer address
+export type FrakContextV1 = {
+    /** Referrer wallet address */
     r: Address;
 };
+
+/**
+ * V2 Frak Context — anonymous-first referral context.
+ * Contains the sharer's clientId, merchantId, and link creation timestamp.
+ * @ignore
+ */
+export type FrakContextV2 = {
+    /** Version discriminator */
+    v: 2;
+    /** Sharer's anonymous clientId (UUID from localStorage) */
+    c: string;
+    /** Merchant ID (UUID) */
+    m: string;
+    /** Link creation timestamp (epoch seconds) */
+    t: number;
+};
+
+/**
+ * The current Frak Context — union of all versions.
+ *
+ * - No `v` field → V1 (legacy wallet address)
+ * - `v: 2` → V2 (anonymous clientId-based)
+ *
+ * @ignore
+ */
+export type FrakContext = FrakContextV1 | FrakContextV2;
+
+/**
+ * Type guard: check if a context is V1 (legacy wallet address).
+ * @param ctx - The Frak context to check
+ * @returns True if the context is a V1 context
+ */
+export function isV1Context(ctx: FrakContext): ctx is FrakContextV1 {
+    return "r" in ctx && !("v" in ctx);
+}
+
+/**
+ * Type guard: check if a context is V2 (anonymous clientId-based).
+ * @param ctx - The Frak context to check
+ * @returns True if the context is a V2 context
+ */
+export function isV2Context(ctx: FrakContext): ctx is FrakContextV2 {
+    return "v" in ctx && ctx.v === 2;
+}

package/src/types/index.ts

@@ -15,7 +15,8 @@ export type {
     LocalizedI18nConfig,
 } from "./config";
 // Utils
-export type { FrakContext } from "./context";
+export type { FrakContext, FrakContextV1, FrakContextV2 } from "./context";
+export { isV1Context, isV2Context } from "./context";
 
 export type {
     ClientLifecycleEvent,

package/src/types/rpc/interaction.ts

@@ -11,7 +11,12 @@ import type { Address } from "viem";
 export type SendInteractionParamsType =
     | {
           type: "arrival";
+          /** @deprecated V1 legacy — use referrerClientId for v2 */
           referrerWallet?: Address;
+          referrerClientId?: string;
+          referrerMerchantId?: string;
+          /** Epoch seconds timestamp from the referral link creation */
+          referralTimestamp?: number;
           landingUrl?: string;
           utmSource?: string;
           utmMedium?: string;

package/src/types/tracking.ts

@@ -1,14 +1,5 @@
-/**
- * Types for arrival tracking and referral attribution
- * @category Tracking
- */
-
 import type { Address } from "viem";
 
-/**
- * UTM parameters for marketing attribution
- * @category Tracking
- */
 export type UtmParams = {
     source?: string;
     medium?: string;
@@ -17,29 +8,17 @@ export type UtmParams = {
     content?: string;
 };
 
-/**
- * Parameters for tracking an arrival event
- * @category Tracking
- */
 export type TrackArrivalParams = {
-    /**
-     * The referrer wallet address (from fCtx URL param)
-     */
+    /** @deprecated V1 legacy — use referrerClientId for v2 contexts */
     referrerWallet?: Address;
-    /**
-     * The landing page URL (defaults to current page)
-     */
+    referrerClientId?: string;
+    referrerMerchantId?: string;
+    /** Epoch seconds timestamp from the referral link creation */
+    referralTimestamp?: number;
     landingUrl?: string;
-    /**
-     * UTM parameters for marketing attribution
-     */
     utmParams?: UtmParams;
 };
 
-/**
- * Result from tracking an arrival event
- * @category Tracking
- */
 export type TrackArrivalResult = {
     success: boolean;
     identityGroupId?: string;
@@ -47,14 +26,6 @@ export type TrackArrivalResult = {
     error?: string;
 };
 
-/**
- * Internal params passed to the trackArrival action
- * Includes merchantId resolved from config or fetch
- * @internal
- */
 export type TrackArrivalInternalParams = TrackArrivalParams & {
-    /**
-     * The merchant ID (UUID from dashboard)
-     */
     merchantId: string;
 };