@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.1e44255d

package/src/actions/referral/referralInteraction.ts

@@ -0,0 +1,52 @@
+import type { DisplayEmbeddedWalletParamsType, FrakClient } from "../../types";
+import { FrakContextManager } from "../../utils";
+import { watchWalletStatus } from "../index";
+import {
+    type ProcessReferralOptions,
+    processReferral,
+} from "./processReferral";
+
+/**
+ * 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
+ *
+ * @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;
+    } = {}
+) {
+    // 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,
+            options,
+        });
+    } catch (error) {
+        console.warn("Error processing referral", { error });
+    }
+    return;
+}

package/src/actions/sendInteraction.ts

@@ -0,0 +1,56 @@
+import type { FrakClient } from "../types";
+import type { SendInteractionParamsType } from "../types/rpc/interaction";
+import { getClientId } from "../utils/clientId";
+
+/**
+ * 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
+ * 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",
+ * });
+ * ```
+ *
+ * @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" },
+ * });
+ * ```
+ */
+export async function sendInteraction(
+    client: FrakClient,
+    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);
+    }
+}

package/src/actions/trackPurchaseStatus.test.ts

@@ -0,0 +1,500 @@
+import { vi } from "vitest";
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    test,
+} from "../../tests/vitest-fixtures";
+
+vi.mock("../utils/clientId", () => ({
+    getClientId: vi.fn().mockReturnValue("test-client-id"),
+}));
+
+vi.mock("../utils/merchantId", () => ({
+    fetchMerchantId: vi.fn().mockResolvedValue(undefined),
+}));
+
+import { getClientId } from "../utils/clientId";
+import { fetchMerchantId } from "../utils/merchantId";
+import { trackPurchaseStatus } from "./trackPurchaseStatus";
+
+describe.sequential("trackPurchaseStatus", () => {
+    const TRACK_PURCHASE_URL = "https://backend.frak.id/user/track/purchase";
+
+    let mockSessionStorage: {
+        getItem: ReturnType<typeof vi.fn>;
+        setItem: ReturnType<typeof vi.fn>;
+        removeItem: ReturnType<typeof vi.fn>;
+    };
+    let mockLocalStorage: {
+        getItem: ReturnType<typeof vi.fn>;
+        setItem: ReturnType<typeof vi.fn>;
+        removeItem: ReturnType<typeof vi.fn>;
+    };
+    let fetchSpy: ReturnType<typeof vi.fn>;
+    let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+    function setupStorage(values: {
+        interactionToken?: string | null;
+        merchantId?: string | null;
+        clientId?: string | null;
+    }) {
+        mockSessionStorage.getItem.mockImplementation((key: string) => {
+            if (key === "frak-wallet-interaction-token") {
+                return values.interactionToken ?? null;
+            }
+            if (key === "frak-merchant-id") {
+                return values.merchantId ?? null;
+            }
+            return null;
+        });
+
+        mockLocalStorage.getItem.mockImplementation((key: string) => {
+            if (key === "frak-client-id") {
+                return values.clientId ?? null;
+            }
+            return null;
+        });
+    }
+
+    function getTrackingRequests() {
+        return fetchSpy.mock.calls.filter(
+            ([url]) => url === TRACK_PURCHASE_URL
+        );
+    }
+
+    function getLastTrackingRequest() {
+        return getTrackingRequests().at(-1);
+    }
+
+    beforeEach(() => {
+        mockSessionStorage = {
+            getItem: vi.fn(),
+            setItem: vi.fn(),
+            removeItem: vi.fn(),
+        };
+
+        mockLocalStorage = {
+            getItem: vi.fn(),
+            setItem: vi.fn(),
+            removeItem: vi.fn(),
+        };
+
+        Object.defineProperty(window, "sessionStorage", {
+            value: mockSessionStorage,
+            writable: true,
+            configurable: true,
+        });
+
+        Object.defineProperty(window, "localStorage", {
+            value: mockLocalStorage,
+            writable: true,
+            configurable: true,
+        });
+
+        setupStorage({
+            interactionToken: "token-123",
+            merchantId: null,
+            clientId: "test-client-id",
+        });
+
+        vi.mocked(getClientId).mockReturnValue("test-client-id");
+        vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+
+        fetchSpy = vi.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+        });
+        global.fetch = fetchSpy as typeof fetch;
+
+        consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        consoleWarnSpy.mockRestore();
+        vi.clearAllMocks();
+    });
+
+    describe("successful tracking", () => {
+        test("should send POST request with correct parameters including merchantId", async () => {
+            const callCountBefore = getTrackingRequests().length;
+
+            await trackPurchaseStatus({
+                customerId: "cust-456",
+                orderId: "order-789",
+                token: "purchase-token",
+                merchantId: "merchant-explicit",
+            });
+
+            expect(getTrackingRequests().length).toBe(callCountBefore + 1);
+            expect(getLastTrackingRequest()).toEqual([
+                TRACK_PURCHASE_URL,
+                {
+                    method: "POST",
+                    headers: {
+                        Accept: "application/json",
+                        "Content-Type": "application/json",
+                        "x-wallet-sdk-auth": "token-123",
+                        "x-frak-client-id": "test-client-id",
+                    },
+                    body: JSON.stringify({
+                        customerId: "cust-456",
+                        orderId: "order-789",
+                        token: "purchase-token",
+                        merchantId: "merchant-explicit",
+                    }),
+                },
+            ]);
+        });
+
+        test("should include x-frak-client-id header", async () => {
+            setupStorage({
+                interactionToken: null,
+                merchantId: null,
+                clientId: "test-client-id",
+            });
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+                merchantId: "merchant-1",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                headers: Record<string, string>;
+            };
+            expect(requestInit.headers).toEqual({
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-frak-client-id": "test-client-id",
+            });
+        });
+
+        test("should include x-wallet-sdk-auth header when interaction token exists", async () => {
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+                merchantId: "merchant-1",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                headers: Record<string, string>;
+            };
+            expect(requestInit.headers).toEqual({
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-wallet-sdk-auth": "token-123",
+                "x-frak-client-id": "test-client-id",
+            });
+        });
+
+        test("should handle numeric customerId and orderId", async () => {
+            await trackPurchaseStatus({
+                customerId: 12345,
+                orderId: 67890,
+                token: "purchase-token",
+                merchantId: "merchant-1",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                body: string;
+            };
+            expect(requestInit.body).toBe(
+                JSON.stringify({
+                    customerId: 12345,
+                    orderId: 67890,
+                    token: "purchase-token",
+                    merchantId: "merchant-1",
+                })
+            );
+        });
+
+        test("should use new endpoint URL /user/track/purchase", async () => {
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+                merchantId: "merchant-1",
+            });
+
+            expect(getLastTrackingRequest()?.[0]).toBe(TRACK_PURCHASE_URL);
+        });
+    });
+
+    describe("merchantId resolution", () => {
+        test("should resolve merchantId from explicit param first", async () => {
+            setupStorage({
+                interactionToken: "token-123",
+                merchantId: "session-merchant-id",
+                clientId: "test-client-id",
+            });
+            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
+            const merchantLookupCallsBefore =
+                vi.mocked(fetchMerchantId).mock.calls.length;
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+                merchantId: "explicit-merchant-id",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                body: string;
+            };
+            expect(requestInit.body).toBe(
+                JSON.stringify({
+                    customerId: "cust-1",
+                    orderId: "order-1",
+                    token: "token-1",
+                    merchantId: "explicit-merchant-id",
+                })
+            );
+            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
+                merchantLookupCallsBefore
+            );
+        });
+
+        test("should fall back to sessionStorage for merchantId", async () => {
+            setupStorage({
+                interactionToken: "token-123",
+                merchantId: "session-merchant-id",
+                clientId: "test-client-id",
+            });
+            const merchantLookupCallsBefore =
+                vi.mocked(fetchMerchantId).mock.calls.length;
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                body: string;
+            };
+            expect(requestInit.body).toBe(
+                JSON.stringify({
+                    customerId: "cust-1",
+                    orderId: "order-1",
+                    token: "token-1",
+                    merchantId: "session-merchant-id",
+                })
+            );
+            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
+                merchantLookupCallsBefore
+            );
+        });
+
+        test("should fall back to fetchMerchantId when no explicit or sessionStorage", async () => {
+            setupStorage({
+                interactionToken: "token-123",
+                merchantId: null,
+                clientId: "test-client-id",
+            });
+            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                body: string;
+            };
+            expect(requestInit.body).toBe(
+                JSON.stringify({
+                    customerId: "cust-1",
+                    orderId: "order-1",
+                    token: "token-1",
+                    merchantId: "fetched-merchant-id",
+                })
+            );
+        });
+
+        test("should warn and skip when no merchantId available", async () => {
+            setupStorage({
+                interactionToken: "token-123",
+                merchantId: null,
+                clientId: "test-client-id",
+            });
+            vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+            const callCountBefore = getTrackingRequests().length;
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+            });
+
+            expect(consoleWarnSpy).toHaveBeenCalledWith(
+                "[Frak] No merchant id found, skipping purchase check"
+            );
+            expect(getTrackingRequests().length).toBe(callCountBefore);
+        });
+    });
+
+    describe("anonymous user support", () => {
+        test("should send request with only x-frak-client-id when no interaction token", async () => {
+            setupStorage({
+                interactionToken: null,
+                merchantId: null,
+                clientId: "test-client-id",
+            });
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+                merchantId: "merchant-1",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                headers: Record<string, string>;
+            };
+            expect(requestInit.headers).toEqual({
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-frak-client-id": "test-client-id",
+            });
+        });
+
+        test("should send request with both headers when both available", async () => {
+            setupStorage({
+                interactionToken: "token-123",
+                merchantId: null,
+                clientId: "test-client-id",
+            });
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+                merchantId: "merchant-1",
+            });
+
+            const requestInit = getLastTrackingRequest()?.[1] as {
+                headers: Record<string, string>;
+            };
+            expect(requestInit.headers).toEqual({
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-wallet-sdk-auth": "token-123",
+                "x-frak-client-id": "test-client-id",
+            });
+        });
+
+        test("should skip when no identity available", async () => {
+            setupStorage({
+                interactionToken: null,
+                merchantId: "merchant-1",
+                clientId: null,
+            });
+            vi.mocked(getClientId).mockReturnValue("");
+            const callCountBefore = getTrackingRequests().length;
+
+            await trackPurchaseStatus({
+                customerId: "cust-1",
+                orderId: "order-1",
+                token: "token-1",
+            });
+
+            expect(consoleWarnSpy).toHaveBeenCalledWith(
+                "[Frak] No identity found, skipping purchase check"
+            );
+            expect(getTrackingRequests().length).toBe(callCountBefore);
+        });
+    });
+
+    describe("missing identity", () => {
+        test("should warn when no identity sources available", async () => {
+            setupStorage({
+                interactionToken: null,
+                merchantId: "merchant-1",
+                clientId: null,
+            });
+            vi.mocked(getClientId).mockReturnValue("");
+            const callCountBefore = getTrackingRequests().length;
+
+            await trackPurchaseStatus({
+                customerId: "cust-456",
+                orderId: "order-789",
+                token: "purchase-token",
+            });
+
+            expect(consoleWarnSpy).toHaveBeenCalledWith(
+                "[Frak] No identity found, skipping purchase check"
+            );
+            expect(getTrackingRequests().length).toBe(callCountBefore);
+        });
+    });
+
+    describe("non-browser environment", () => {
+        test("should warn and skip when window is undefined", async () => {
+            const savedWindow = globalThis.window;
+            Reflect.deleteProperty(globalThis, "window");
+            const callCountBefore = getTrackingRequests().length;
+
+            try {
+                await trackPurchaseStatus({
+                    customerId: "cust-1",
+                    orderId: "order-1",
+                    token: "token-1",
+                    merchantId: "merchant-1",
+                });
+            } finally {
+                Object.defineProperty(globalThis, "window", {
+                    value: savedWindow,
+                    writable: true,
+                    configurable: true,
+                });
+            }
+
+            expect(consoleWarnSpy).toHaveBeenCalledWith(
+                "[Frak] No window found, can't track purchase"
+            );
+            expect(getTrackingRequests().length).toBe(callCountBefore);
+        });
+    });
+
+    describe("network errors", () => {
+        test("should handle fetch rejection", async () => {
+            vi.mocked(getClientId).mockReturnValue("test-client-id");
+            setupStorage({
+                interactionToken: "token-123",
+                merchantId: null,
+                clientId: "test-client-id",
+            });
+            fetchSpy.mockRejectedValueOnce(new Error("Network error"));
+
+            await expect(
+                trackPurchaseStatus({
+                    customerId: "cust-456",
+                    orderId: "order-789",
+                    token: "purchase-token",
+                    merchantId: "merchant-1",
+                })
+            ).rejects.toThrow("Network error");
+        });
+
+        test("should handle fetch with error response", async () => {
+            fetchSpy.mockResolvedValue({
+                ok: false,
+                status: 500,
+            });
+
+            await trackPurchaseStatus({
+                customerId: "cust-456",
+                orderId: "order-789",
+                token: "purchase-token",
+                merchantId: "merchant-1",
+            });
+
+            expect(fetchSpy).toHaveBeenCalled();
+        });
+    });
+});

package/src/actions/trackPurchaseStatus.ts

@@ -0,0 +1,90 @@
+import { getBackendUrl } from "../utils/backendUrl";
+import { getClientId } from "../utils/clientId";
+import { fetchMerchantId } from "../utils/merchantId";
+
+/**
+ * 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
+ * @param args.merchantId - Optional explicit merchant id to use for the tracking request
+ *
+ * @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,
+ *     merchantId: "your-merchant-id",
+ *   };
+ *
+ *   await trackPurchaseStatus(payload);
+ * }
+ *
+ * @remarks
+ * - Merchant id is resolved in this order: explicit `args.merchantId`, `frak-merchant-id` from session storage, then `fetchMerchantId()`.
+ * - 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.
+ */
+export async function trackPurchaseStatus(args: {
+    customerId: string | number;
+    orderId: string | number;
+    token: string;
+    merchantId?: 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"
+    );
+
+    const clientId = getClientId();
+    if (!interactionToken && !clientId) {
+        console.warn("[Frak] No identity found, skipping purchase check");
+        return;
+    }
+
+    const merchantIdFromStorage =
+        window.sessionStorage.getItem("frak-merchant-id");
+    const merchantId =
+        args.merchantId ?? merchantIdFromStorage ?? (await fetchMerchantId());
+
+    if (!merchantId) {
+        console.warn("[Frak] No merchant id found, skipping purchase check");
+        return;
+    }
+
+    const headers: Record<string, string> = {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+    };
+
+    if (interactionToken) {
+        headers["x-wallet-sdk-auth"] = interactionToken;
+    }
+
+    if (clientId) {
+        headers["x-frak-client-id"] = clientId;
+    }
+
+    // Submit the listening request
+    const backendUrl = getBackendUrl();
+    await fetch(`${backendUrl}/user/track/purchase`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            customerId: args.customerId,
+            orderId: args.orderId,
+            token: args.token,
+            merchantId,
+        }),
+    });
+}