@frak-labs/core-sdk 0.1.1 → 0.2.0

package/src/actions/referral/processReferral.ts

@@ -1,6 +1,5 @@
 import { FrakRpcError, RpcErrorCodes } from "@frak-labs/frame-connector";
-import { type Address, type Hex, isAddressEqual } from "viem";
-import { ReferralInteractionEncoder } from "../../interactions";
+import { type Address, isAddressEqual } from "viem";
 import type {
     DisplayEmbeddedWalletParamsType,
     FrakClient,
@@ -8,7 +7,8 @@ import type {
     WalletStatusReturnType,
 } from "../../types";
 import { FrakContextManager, trackEvent } from "../../utils";
-import { displayEmbeddedWallet, sendInteraction } from "../index";
+import { displayEmbeddedWallet } from "../displayEmbeddedWallet";
+import { sendInteraction } from "../sendInteraction";
 
 /**
  * The different states of the referral process
@@ -19,7 +19,6 @@ type ReferralState =
     | "processing"
     | "success"
     | "no-wallet"
-    | "no-session"
     | "error"
     | "no-referrer"
     | "self-referral";
@@ -41,11 +40,9 @@ export type ProcessReferralOptions = {
  *  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
+ *  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
  *
@@ -54,13 +51,10 @@ export type ProcessReferralOptions = {
  * @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
  */
 export async function processReferral(
@@ -69,13 +63,11 @@ export async function processReferral(
         walletStatus,
         frakContext,
         modalConfig,
-        productId,
         options,
     }: {
         walletStatus?: WalletStatusReturnType;
         frakContext?: Partial<FrakContext> | null;
         modalConfig?: DisplayEmbeddedWalletParamsType;
-        productId?: Hex;
         options?: ProcessReferralOptions;
     }
 ) {
@@ -92,6 +84,13 @@ export async function processReferral(
         },
     });
 
+    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() {
@@ -112,20 +111,11 @@ export async function processReferral(
         });
     }
 
-    // Helper function to push the interaction
-    async function pushReferralInteraction(referrer: Address) {
-        const interaction = ReferralInteractionEncoder.referred({
-            referrer,
-        });
-        await sendInteraction(client, { productId, interaction });
-    }
-
     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">,
         });
@@ -176,42 +166,30 @@ export async function processReferral(
 }
 
 /**
- * Automatically submit a referral interaction when detected
- *   -> And automatically set the referral context in the url
- * @param walletStatus
- * @param frakContext
+ * Process referral logic - ensure user is logged in and check for self-referral
  */
 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;
 
-    // If we don't have a current wallet, display the modal
+    // If we don't have a current wallet, display the modal to log in
     if (!currentWallet) {
-        // Track the event
         currentWallet = await getFreshWalletStatus();
     }
 
+    // Check for self-referral
     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;
 }
 
@@ -228,8 +206,8 @@ async function ensureWalletConnected(
         walletStatus?: WalletStatusReturnType;
     }
 ) {
-    // If wallet not connected, or no interaction session
-    if (!walletStatus?.interactionSession) {
+    // If wallet not connected, display modal
+    if (walletStatus?.key !== "connected") {
         const result = await displayEmbeddedWallet(client, modalConfig ?? {});
         return result?.wallet ?? undefined;
     }
@@ -246,8 +224,6 @@ function mapErrorToState(error: unknown): ReferralState {
         switch (error.code) {
             case RpcErrorCodes.walletNotConnected:
                 return "no-wallet";
-            case RpcErrorCodes.serverErrorForInteractionDelegation:
-                return "no-session";
             default:
                 return "error";
         }

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");
 
@@ -80,7 +77,6 @@ describe("referralInteraction", () => {
         vi.mocked(processReferral).mockResolvedValue("success");
 
         await referralInteraction(mockClient, {
-            productId: mockProductId,
             modalConfig: mockModalConfig as any,
             options: mockOptions,
         });
@@ -89,7 +85,6 @@ describe("referralInteraction", () => {
             walletStatus: mockWalletStatus,
             frakContext: mockContext,
             modalConfig: mockModalConfig,
-            productId: mockProductId,
             options: mockOptions,
         });
     });
@@ -145,7 +140,6 @@ describe("referralInteraction", () => {
             mockClient,
             expect.objectContaining({
                 modalConfig: undefined,
-                productId: undefined,
                 options: undefined,
             })
         );

package/src/actions/referral/referralInteraction.ts

@@ -1,4 +1,3 @@
-import type { Hex } from "viem";
 import type { DisplayEmbeddedWalletParamsType, FrakClient } from "../../types";
 import { FrakContextManager } from "../../utils";
 import { watchWalletStatus } from "../index";
@@ -8,10 +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
  *
@@ -25,11 +23,9 @@ import {
 export async function referralInteraction(
     client: FrakClient,
     {
-        productId,
         modalConfig,
         options,
     }: {
-        productId?: Hex;
         modalConfig?: DisplayEmbeddedWalletParamsType;
         options?: ProcessReferralOptions;
     } = {}
@@ -47,7 +43,6 @@ export async function referralInteraction(
             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);
+    }
 }