@frak-labs/core-sdk 0.2.1 → 1.0.0

package/src/actions/displayModal.ts

@@ -11,6 +11,7 @@ import type {
  * @param args
  * @param args.steps - The different steps of the modal
  * @param args.metadata - The metadata for the modal (customization, etc)
+ * @param placement - Optional placement ID to associate with this modal display
  * @returns The result of each modal steps
  *
  * @description This function will display a modal to the user with the provided steps and metadata.
@@ -111,10 +112,13 @@ export async function displayModal<
     T extends ModalStepTypes[] = ModalStepTypes[],
 >(
     client: FrakClient,
-    { steps, metadata }: DisplayModalParamsType<T>
+    { steps, metadata }: DisplayModalParamsType<T>,
+    placement?: string
 ): Promise<ModalRpcStepsResultType<T>> {
     return (await client.request({
         method: "frak_displayModal",
-        params: [steps, metadata, client.config.metadata],
+        params: placement
+            ? [steps, metadata, client.config.metadata, placement]
+            : [steps, metadata, client.config.metadata],
     })) as ModalRpcStepsResultType<T>;
 }

package/src/actions/displaySharingPage.ts

@@ -0,0 +1,49 @@
+import type {
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
+    FrakClient,
+} from "../types";
+
+/**
+ * Function used to display a sharing page
+ * @param client - The current Frak Client
+ * @param params - The parameters to customize the sharing page (products, link override, metadata)
+ * @param placement - Optional placement ID to associate with this display request
+ * @returns The result indicating the user's action (shared, copied, or dismissed)
+ *
+ * @description This function will display a full-page sharing UI to the user,
+ * showing product info, estimated rewards, sharing steps, FAQ, and share/copy buttons.
+ * The sharing link is generated from the user's wallet context + merchant info.
+ *
+ * @remarks
+ * - The promise resolves on the first user action (share or copy) but the page stays visible
+ * - The user can continue to share/copy multiple times after the initial resolution
+ * - Dismissing the page after a share/copy action is a no-op (promise already resolved)
+ * - If the user dismisses without any action, the promise resolves with `{ action: "dismissed" }`
+ *
+ * @example
+ * ```ts
+ * const result = await displaySharingPage(frakClient, {
+ *     products: [
+ *         {
+ *             title: "Babies camel cuir velours bout carré",
+ *             imageUrl: "https://example.com/product.jpg",
+ *         },
+ *     ],
+ * });
+ *
+ * console.log("User action:", result.action); // "shared" | "copied" | "dismissed"
+ * ```
+ */
+export async function displaySharingPage(
+    client: FrakClient,
+    params: DisplaySharingPageParamsType,
+    placement?: string
+): Promise<DisplaySharingPageResultType> {
+    return await client.request({
+        method: "frak_displaySharingPage",
+        params: placement
+            ? [params, client.config.metadata, placement]
+            : [params, client.config.metadata],
+    });
+}

package/src/actions/ensureIdentity.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";
 
 const ENSURE_STORAGE_PREFIX = "frak-identity-ensured-";
 
@@ -36,7 +36,7 @@ export async function ensureIdentity(interactionToken: string): Promise<void> {
         return;
     }
 
-    const merchantId = await fetchMerchantId();
+    const merchantId = await sdkConfigStore.resolveMerchantId();
     if (!merchantId) {
         return;
     }

package/src/actions/getMerchantInformation.test.ts

@@ -1,9 +1,21 @@
 import type { Address, Hex } from "viem";
-import { describe, expect, it, vi } from "../../tests/vitest-fixtures";
+import {
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
 import type { FrakClient, GetMerchantInformationReturnType } from "../types";
+import { clearAllCache } from "../utils/cache";
 import { getMerchantInformation } from "./getMerchantInformation";
 
 describe("getMerchantInformation", () => {
+    // Clear cache between tests to ensure isolation
+    beforeEach(() => {
+        clearAllCache();
+    });
+
     describe("success cases", () => {
         it("should call client.request with correct method", async () => {
             const mockResponse: GetMerchantInformationReturnType = {

package/src/actions/getMerchantInformation.ts

@@ -1,16 +1,31 @@
 import type { FrakClient, GetMerchantInformationReturnType } from "../types";
+import { withCache } from "../utils/cache";
 
 /**
- * Fetch the current merchant information (name, rewards, tiers) from the wallet iframe
+ * Fetch the current merchant information (name, rewards, tiers) from the wallet iframe.
+ *
+ * Results are cached in memory for 30 seconds by default. Concurrent calls
+ * while a request is in-flight are deduplicated automatically.
+ *
  * @param client - The current Frak Client
+ * @param options - Optional cache configuration
+ * @param options.cacheTime - Time in ms to cache the result. Default: 30_000 (30s). Set to 0 to disable.
  * @returns The merchant information including available reward tiers
  *
  * @see {@link @frak-labs/core-sdk!index.GetMerchantInformationReturnType | `GetMerchantInformationReturnType`} for the return type shape
  */
 export async function getMerchantInformation(
-    client: FrakClient
+    client: FrakClient,
+    options?: { cacheTime?: number }
 ): Promise<GetMerchantInformationReturnType> {
-    return await client.request({
-        method: "frak_getMerchantInformation",
-    });
+    return withCache(
+        () =>
+            client.request({
+                method: "frak_getMerchantInformation",
+            }),
+        {
+            cacheKey: "frak_getMerchantInformation",
+            cacheTime: options?.cacheTime,
+        }
+    );
 }

package/src/actions/getMergeToken.ts

@@ -0,0 +1,33 @@
+import type { FrakClient } from "../types";
+import { withCache } from "../utils/cache";
+
+/**
+ * Fetch a merge token for the current anonymous identity.
+ *
+ * Used by in-app browser redirect flows to preserve identity
+ * when switching from a WebView to the system browser.
+ * The token is appended as `?fmt=` to the redirect URL.
+ *
+ * Results are cached in memory for 30 seconds by default. Concurrent calls
+ * while a request is in-flight are deduplicated automatically.
+ *
+ * @param client - The current Frak Client
+ * @param options - Optional cache configuration
+ * @param options.cacheTime - Time in ms to cache the result. Default: 30_000 (30s). Set to 0 to disable.
+ * @returns The merge token string, or null if unavailable
+ */
+export async function getMergeToken(
+    client: FrakClient,
+    options?: { cacheTime?: number }
+): Promise<string | null> {
+    return withCache(
+        () =>
+            client.request({
+                method: "frak_getMergeToken",
+            }),
+        {
+            cacheKey: "frak_getMergeToken",
+            cacheTime: options?.cacheTime,
+        }
+    );
+}

package/src/actions/getUserReferralStatus.ts

@@ -0,0 +1,42 @@
+import type { FrakClient, UserReferralStatusType } from "../types";
+import { withCache } from "../utils/cache";
+
+/**
+ * Fetch the current user's referral status on the current merchant.
+ *
+ * The listener resolves the user's identity (via clientId or wallet session)
+ * and checks whether a referral link exists where the user is the referee.
+ *
+ * Results are cached in memory for 30 seconds by default. Concurrent calls
+ * while a request is in-flight are deduplicated automatically.
+ *
+ * Returns `null` when the user's identity cannot be resolved.
+ *
+ * @param client - The current Frak Client
+ * @param options - Optional cache configuration
+ * @param options.cacheTime - Time in ms to cache the result. Default: 30_000 (30s). Set to 0 to disable.
+ * @returns The user's referral status, or `null` if identity cannot be resolved
+ *
+ * @example
+ * ```ts
+ * const status = await getUserReferralStatus(client);
+ * if (status?.isReferred) {
+ *   console.log("User was referred to this merchant");
+ * }
+ * ```
+ */
+export async function getUserReferralStatus(
+    client: FrakClient,
+    options?: { cacheTime?: number }
+): Promise<UserReferralStatusType | null> {
+    return withCache(
+        () =>
+            client.request({
+                method: "frak_getUserReferralStatus",
+            }),
+        {
+            cacheKey: "frak_getUserReferralStatus",
+            cacheTime: options?.cacheTime,
+        }
+    );
+}

package/src/actions/index.ts

@@ -1,15 +1,22 @@
 export { displayEmbeddedWallet } from "./displayEmbeddedWallet";
 export { displayModal } from "./displayModal";
+export { displaySharingPage } from "./displaySharingPage";
 export { ensureIdentity } from "./ensureIdentity";
 export { getMerchantInformation } from "./getMerchantInformation";
+export { getMergeToken } from "./getMergeToken";
+export { getUserReferralStatus } from "./getUserReferralStatus";
 export { openSso } from "./openSso";
 export { prepareSso } from "./prepareSso";
 export {
     type ProcessReferralOptions,
     processReferral,
 } from "./referral/processReferral";
-// Referral interaction
+// Referral
 export { referralInteraction } from "./referral/referralInteraction";
+export {
+    REFERRAL_SUCCESS_EVENT,
+    setupReferral,
+} from "./referral/setupReferral";
 export { sendInteraction } from "./sendInteraction";
 // Helper to track the purchase status
 export { trackPurchaseStatus } from "./trackPurchaseStatus";

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

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { REFERRAL_SUCCESS_EVENT, setupReferral } from "./setupReferral";
+
+vi.mock("./referralInteraction", () => ({
+    referralInteraction: vi.fn(),
+}));
+
+import { referralInteraction } from "./referralInteraction";
+
+describe("setupReferral", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it("should dispatch referral success event on successful referral", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue("success");
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).toHaveBeenCalledTimes(1);
+        expect(listener).toHaveBeenCalledWith(expect.any(Event));
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should not dispatch event when referral state is not success", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue("no-referrer");
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should not dispatch event when referral returns undefined", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue(undefined);
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should silently catch errors and log warning", async () => {
+        vi.mocked(referralInteraction).mockRejectedValue(
+            new Error("network failure")
+        );
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+        expect(warnSpy).toHaveBeenCalledWith(
+            "[Frak] Referral setup failed",
+            expect.any(Error)
+        );
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+        warnSpy.mockRestore();
+    });
+
+    it("should export the correct event name constant", () => {
+        expect(REFERRAL_SUCCESS_EVENT).toBe("frak:referral-success");
+    });
+});

package/src/actions/referral/setupReferral.ts

@@ -0,0 +1,32 @@
+import type { FrakClient } from "../../types";
+import { referralInteraction } from "./referralInteraction";
+
+/**
+ * Custom event name dispatched on successful referral processing.
+ *
+ * Fired once per page load when a valid referral context is found in the URL
+ * and successfully tracked. Consumers (e.g. `<frak-banner>`) listen for this
+ * to display a referral success message.
+ */
+export const REFERRAL_SUCCESS_EVENT = "frak:referral-success";
+
+/**
+ * Process referral context and emit a DOM event on success.
+ *
+ * - Calls {@link referralInteraction} to detect and track any referral in the URL
+ * - On `"success"`, dispatches a bare {@link REFERRAL_SUCCESS_EVENT} on `window`
+ * - Silently swallows errors (fire-and-forget during SDK init)
+ *
+ * @param client - The initialized Frak client
+ */
+export async function setupReferral(client: FrakClient): Promise<void> {
+    try {
+        const state = await referralInteraction(client);
+
+        if (state === "success") {
+            window.dispatchEvent(new Event(REFERRAL_SUCCESS_EVENT));
+        }
+    } catch (error) {
+        console.warn("[Frak] Referral setup failed", 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,
     };
 }