@frak-labs/core-sdk 0.2.1-beta.b38eef2e → 0.2.1-beta.c7fe645d

package/src/types/resolvedConfig.ts

@@ -0,0 +1,123 @@
+import type { Currency, Language } from "./config";
+
+/**
+ * Response from the merchant resolve endpoint
+ * @category Config
+ */
+export type MerchantConfigResponse = {
+    merchantId: string;
+    name: string;
+    domain: string;
+    allowedDomains: string[];
+    sdkConfig?: ResolvedSdkConfig;
+};
+
+/**
+ * Resolved placement config from backend
+ * Translations already flattened: default + lang-specific merged into one record
+ * @category Config
+ */
+export type ResolvedPlacement = {
+    /** Per-component configuration within this placement */
+    components?: {
+        buttonShare?: {
+            text?: string;
+            noRewardText?: string;
+            clickAction?: "embedded-wallet" | "share-modal" | "sharing-page";
+            useReward?: boolean;
+            css?: string;
+        };
+        buttonWallet?: {
+            position?: "right" | "left";
+            css?: string;
+        };
+        openInApp?: {
+            text?: string;
+            css?: string;
+        };
+        postPurchase?: {
+            badgeText?: string;
+            refereeText?: string;
+            refereeNoRewardText?: string;
+            referrerText?: string;
+            referrerNoRewardText?: string;
+            ctaText?: string;
+            ctaNoRewardText?: string;
+            css?: string;
+        };
+        banner?: {
+            referralTitle?: string;
+            referralDescription?: string;
+            referralCta?: string;
+            inappTitle?: string;
+            inappDescription?: string;
+            inappCta?: string;
+            css?: string;
+        };
+    };
+    targetInteraction?: string;
+    /** Already flattened: default + lang-specific merged into one record */
+    translations?: Record<string, string>;
+    /** Global placement CSS (applied to modals/listener) */
+    css?: string;
+};
+
+/**
+ * Resolved SDK config from backend `/resolve` endpoint
+ * Language resolution and translation merging already applied
+ * @category Config
+ */
+export type ResolvedSdkConfig = {
+    name?: string;
+    logoUrl?: string;
+    homepageLink?: string;
+    currency?: Currency;
+    lang?: Language;
+    /** When true, all SDK components should be hidden */
+    hidden?: boolean;
+    css?: string;
+    translations?: Record<string, string>;
+    placements?: Record<string, ResolvedPlacement>;
+};
+
+/**
+ * Internal SDK config store state
+ * Merged config: backend > SDK static > defaults
+ * Components subscribe to this reactively
+ * @category Config
+ */
+export type SdkResolvedConfig = {
+    /** Whether the backend config has been resolved */
+    isResolved: boolean;
+
+    /** Merchant ID from resolution */
+    merchantId: string;
+
+    /** Domain returned by the resolve endpoint */
+    domain?: string;
+
+    /** Domains allowed for this merchant (used by iframe trust check) */
+    allowedDomains?: string[];
+
+    /** Whether the resolve returned a backend sdkConfig object */
+    hasRawSdkConfig?: boolean;
+
+    /** Merged metadata fields */
+    name?: string;
+    logoUrl?: string;
+    homepageLink?: string;
+    lang?: Language;
+    currency?: Currency;
+
+    /** When true, all SDK components should be hidden */
+    hidden?: boolean;
+
+    /** Global CSS from backend config (passed to iframe) */
+    css?: string;
+
+    /** Global translations (for reference / component fallback) */
+    translations?: Record<string, string>;
+
+    /** Named placements (keyed by placement ID) */
+    placements?: Record<string, ResolvedPlacement>;
+};

package/src/types/rpc/displaySharingPage.ts

@@ -0,0 +1,77 @@
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
+import type { I18nConfig } from "../config";
+
+/**
+ * Product information to display on the sharing page
+ * @group Sharing Page
+ */
+export type SharingPageProduct = {
+    /**
+     * The product title / name
+     */
+    title: string;
+    /**
+     * Optional product image URL
+     */
+    imageUrl?: string;
+};
+
+/**
+ * Parameters to display the sharing page
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+export type DisplaySharingPageParamsType = {
+    /**
+     * Products to showcase on the sharing page
+     * If provided, they will be displayed in a product card section
+     */
+    products?: SharingPageProduct[];
+    /**
+     * Optional link override for sharing
+     * If not provided, the sharing link will be generated from the current page URL + merchant context
+     */
+    link?: string;
+    /**
+     * Optional metadata overrides for the sharing page
+     */
+    metadata?: {
+        /**
+         * Logo override for the sharing page header
+         */
+        logo?: string;
+        /**
+         * Link to the homepage of the calling website
+         */
+        homepageLink?: string;
+        /**
+         * The target interaction behind this sharing page
+         */
+        targetInteraction?: InteractionTypeKey;
+        /**
+         * i18n overrides for the sharing page
+         */
+        i18n?: I18nConfig;
+    };
+};
+
+/**
+ * Result of the sharing page display
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+export type DisplaySharingPageResultType = {
+    /**
+     * The action the user took
+     * - "shared": User used the native share dialog
+     * - "copied": User copied the link to clipboard
+     * - "dismissed": User dismissed the sharing page without acting
+     */
+    action: "shared" | "copied" | "dismissed";
+    /**
+     * The install URL for the Frak app
+     * Can be used as a fallback to redirect the user to the install page
+     * from the merchant's top-level page (e.g. via `window.location.href`)
+     */
+    installUrl?: string;
+};

package/src/types/rpc/interaction.ts

@@ -26,6 +26,10 @@ export type SendInteractionParamsType =
       }
     | {
           type: "sharing";
+          /** Epoch seconds timestamp matching the V2 context `t` field embedded in the referral link URL, used for backend correlation */
+          sharingTimestamp?: number;
+          /** Merchant order ID linking this sharing event to a purchase (stays server-side, never in URL) */
+          purchaseId?: string;
       }
     | {
           type: "custom";

package/src/types/rpc/userReferralStatus.ts

@@ -0,0 +1,20 @@
+/**
+ * User referral status returned by `frak_getUserReferralStatus`.
+ *
+ * Generic referral context for the current user on a merchant.
+ * Used by components like `<frak-post-purchase>` and `<frak-referred-banner>`
+ * to adapt their display based on the user's referral relationship.
+ *
+ * Returns `null` when the user's identity cannot be resolved
+ * (e.g. no clientId and no wallet session).
+ *
+ * @group RPC Schema
+ */
+export type UserReferralStatusType = {
+    /**
+     * Whether the user was referred to this merchant by someone else.
+     *
+     * `true` means a referral link exists where this user is the referee.
+     */
+    isReferred: boolean;
+};

package/src/types/rpc.ts

@@ -4,6 +4,10 @@ import type {
     ModalRpcStepsInput,
     ModalRpcStepsResultType,
 } from "./rpc/displayModal";
+import type {
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
+} from "./rpc/displaySharingPage";
 import type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
@@ -16,6 +20,7 @@ import type {
     PrepareSsoParamsType,
     PrepareSsoReturnType,
 } from "./rpc/sso";
+import type { UserReferralStatusType } from "./rpc/userReferralStatus";
 import type { WalletStatusReturnType } from "./rpc/walletStatus";
 
 /**
@@ -38,7 +43,7 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  *  - Response Type: stream (emits updates when wallet status changes)
  *
  * #### frak_displayModal
- * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
  * - Returns: {@link ModalRpcStepsResultType}
  * - Response Type: promise (one-shot)
  *
@@ -53,9 +58,14 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  *  - Response Type: promise (one-shot)
  *
  * #### frak_displayEmbeddedWallet
- * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
  * - Returns: {@link DisplayEmbeddedWalletResultType}
  * - Response Type: promise (one-shot)
+ *
+ * #### frak_displaySharingPage
+ * - Params: [request: {@link DisplaySharingPageParamsType}, configMetadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
+ * - Returns: {@link DisplaySharingPageResultType}
+ * - Response Type: promise (one-shot)
  */
 export type IFrameRpcSchema = [
     /**
@@ -77,6 +87,7 @@ export type IFrameRpcSchema = [
             requests: ModalRpcStepsInput,
             metadata: ModalRpcMetadata | undefined,
             configMetadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: ModalRpcStepsResultType;
     },
@@ -89,7 +100,7 @@ export type IFrameRpcSchema = [
         Method: "frak_prepareSso";
         Parameters: [
             params: PrepareSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: PrepareSsoReturnType;
@@ -104,7 +115,7 @@ export type IFrameRpcSchema = [
         Method: "frak_openSso";
         Parameters: [
             params: OpenSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: OpenSsoReturnType;
@@ -130,6 +141,7 @@ export type IFrameRpcSchema = [
         Parameters: [
             request: DisplayEmbeddedWalletParamsType,
             metadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: DisplayEmbeddedWalletResultType;
     },
@@ -137,7 +149,7 @@ export type IFrameRpcSchema = [
      * Method to send interactions (arrival, sharing, custom events)
      * Fire-and-forget method - no return value expected
      * merchantId is resolved from context
-     * clientId is passed via metadata as safeguard against handshake race condition
+     * clientId is passed via metadata as safeguard against race conditions
      */
     {
         Method: "frak_sendInteraction";
@@ -147,4 +159,29 @@ export type IFrameRpcSchema = [
         ];
         ReturnType: undefined;
     },
+    /**
+     * Method to get the current user's referral status on this merchant.
+     * Returns whether the user was referred (has a referral link as referee).
+     * Returns null when the user's identity cannot be resolved.
+     * This is a one-shot request.
+     */
+    {
+        Method: "frak_getUserReferralStatus";
+        Parameters?: undefined;
+        ReturnType: UserReferralStatusType | null;
+    },
+    /**
+     * Method to display a sharing page with product info and sharing buttons
+     * Resolves on first user action (share/copy) but the page stays visible
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_displaySharingPage";
+        Parameters: [
+            request: DisplaySharingPageParamsType,
+            configMetadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
+        ];
+        ReturnType: DisplaySharingPageResultType;
+    },
 ];

package/src/utils/backendUrl.test.ts

@@ -15,13 +15,13 @@ describe("getBackendUrl", () => {
     describe("with explicit walletUrl", () => {
         test("should return localhost backend for localhost:3000", () => {
             expect(getBackendUrl("https://localhost:3000")).toBe(
-                "http://localhost:3030"
+                "https://localhost:3030"
             );
         });
 
         test("should return localhost backend for localhost:3010", () => {
             expect(getBackendUrl("https://localhost:3010")).toBe(
-                "http://localhost:3030"
+                "https://localhost:3030"
             );
         });
 

package/src/utils/backendUrl.ts

@@ -19,7 +19,7 @@ function isLocalDevelopment(walletUrl: string): boolean {
  */
 function deriveBackendUrl(walletUrl: string): string {
     if (isLocalDevelopment(walletUrl)) {
-        return "http://localhost:3030";
+        return "https://localhost:3030";
     }
     // Dev environment
     if (

package/src/utils/cache/index.ts

@@ -0,0 +1,7 @@
+export { LruMap } from "./lruMap";
+export {
+    clearAllCache,
+    DEFAULT_CACHE_TIME,
+    getCache,
+    withCache,
+} from "./withCache";

package/src/utils/cache/lruMap.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "../../../tests/vitest-fixtures";
+import { LruMap } from "./lruMap";
+
+describe("LruMap", () => {
+    it("should store and retrieve values", () => {
+        const map = new LruMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+
+        expect(map.get("a")).toBe(1);
+        expect(map.get("b")).toBe(2);
+    });
+
+    it("should evict least recently used when exceeding max size", () => {
+        const map = new LruMap<number>(2);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("c", 3); // Should evict "a"
+
+        expect(map.get("a")).toBeUndefined();
+        expect(map.get("b")).toBe(2);
+        expect(map.get("c")).toBe(3);
+    });
+
+    it("should promote accessed keys to most recently used", () => {
+        const map = new LruMap<number>(2);
+        map.set("a", 1);
+        map.set("b", 2);
+
+        // Access "a" to promote it
+        map.get("a");
+
+        // "b" is now least recently used, should be evicted
+        map.set("c", 3);
+
+        expect(map.get("a")).toBe(1);
+        expect(map.get("b")).toBeUndefined();
+        expect(map.get("c")).toBe(3);
+    });
+
+    it("should overwrite existing keys without increasing size", () => {
+        const map = new LruMap<number>(2);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("a", 10); // Overwrite, not a new entry
+
+        expect(map.size).toBe(2);
+        expect(map.get("a")).toBe(10);
+    });
+
+    it("should return undefined for missing keys", () => {
+        const map = new LruMap<number>(2);
+        expect(map.get("missing")).toBeUndefined();
+    });
+});

package/src/utils/cache/lruMap.ts

@@ -0,0 +1,38 @@
+/**
+ * Map with a LRU (Least Recently Used) eviction policy.
+ *
+ * When the map exceeds `maxSize`, the least recently accessed entry is removed.
+ * Accessing a key via `get()` promotes it to "most recently used".
+ *
+ * Adapted from viem's LruMap utility.
+ * @link https://en.wikipedia.org/wiki/Cache_replacement_policies#LRU
+ */
+export class LruMap<TValue = unknown> extends Map<string, TValue> {
+    maxSize: number;
+
+    constructor(size: number) {
+        super();
+        this.maxSize = size;
+    }
+
+    override get(key: string) {
+        const value = super.get(key);
+        if (super.has(key)) {
+            // Move to end (most recently used)
+            super.delete(key);
+            super.set(key, value as TValue);
+        }
+        return value;
+    }
+
+    override set(key: string, value: TValue) {
+        if (super.has(key)) super.delete(key);
+        super.set(key, value);
+        // Evict least recently used if over capacity
+        if (this.maxSize && this.size > this.maxSize) {
+            const firstKey = super.keys().next().value;
+            if (firstKey !== undefined) super.delete(firstKey);
+        }
+        return this;
+    }
+}

package/src/utils/cache/withCache.test.ts

@@ -0,0 +1,162 @@
+import {
+    afterEach,
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../../tests/vitest-fixtures";
+import { clearAllCache, withCache } from "./withCache";
+
+describe("withCache", () => {
+    beforeEach(() => {
+        clearAllCache();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe("caching behavior", () => {
+        it("should call fn on first invocation", async () => {
+            const fn = vi.fn().mockResolvedValue("result");
+
+            const result = await withCache(fn, {
+                cacheKey: "test-key",
+            });
+
+            expect(fn).toHaveBeenCalledOnce();
+            expect(result).toBe("result");
+        });
+
+        it("should return cached result on subsequent calls within TTL", async () => {
+            const fn = vi.fn().mockResolvedValue("result");
+
+            await withCache(fn, {
+                cacheKey: "test-key",
+                cacheTime: 10_000,
+            });
+            const result = await withCache(fn, {
+                cacheKey: "test-key",
+                cacheTime: 10_000,
+            });
+
+            expect(fn).toHaveBeenCalledOnce();
+            expect(result).toBe("result");
+        });
+
+        it("should re-fetch after cache expires", async () => {
+            vi.useFakeTimers();
+
+            const fn = vi
+                .fn()
+                .mockResolvedValueOnce("first")
+                .mockResolvedValueOnce("second");
+
+            const first = await withCache(fn, {
+                cacheKey: "test-key",
+                cacheTime: 100,
+            });
+            expect(first).toBe("first");
+
+            // Advance past TTL
+            vi.advanceTimersByTime(200);
+
+            const second = await withCache(fn, {
+                cacheKey: "test-key",
+                cacheTime: 100,
+            });
+            expect(second).toBe("second");
+            expect(fn).toHaveBeenCalledTimes(2);
+
+            vi.useRealTimers();
+        });
+
+        it("should not cache when cacheTime is 0", async () => {
+            const fn = vi.fn().mockResolvedValue("result");
+
+            await withCache(fn, { cacheKey: "test-key", cacheTime: 0 });
+            await withCache(fn, { cacheKey: "test-key", cacheTime: 0 });
+
+            expect(fn).toHaveBeenCalledTimes(2);
+        });
+
+        it("should use different caches for different keys", async () => {
+            const fnA = vi.fn().mockResolvedValue("a");
+            const fnB = vi.fn().mockResolvedValue("b");
+
+            const a = await withCache(fnA, { cacheKey: "key-a" });
+            const b = await withCache(fnB, { cacheKey: "key-b" });
+
+            expect(a).toBe("a");
+            expect(b).toBe("b");
+            expect(fnA).toHaveBeenCalledOnce();
+            expect(fnB).toHaveBeenCalledOnce();
+        });
+    });
+
+    describe("deduplication", () => {
+        it("should deduplicate concurrent calls with the same key", async () => {
+            let resolvePromise: (value: string) => void;
+            const fn = vi.fn().mockImplementation(
+                () =>
+                    new Promise<string>((resolve) => {
+                        resolvePromise = resolve;
+                    })
+            );
+
+            const promise1 = withCache(fn, { cacheKey: "dedup-key" });
+            const promise2 = withCache(fn, { cacheKey: "dedup-key" });
+
+            // fn should only be called once
+            expect(fn).toHaveBeenCalledOnce();
+
+            // Both should resolve to the same value
+            resolvePromise!("shared");
+            const [result1, result2] = await Promise.all([promise1, promise2]);
+            expect(result1).toBe("shared");
+            expect(result2).toBe("shared");
+        });
+    });
+
+    describe("error handling", () => {
+        it("should propagate errors from fn", async () => {
+            const fn = vi.fn().mockRejectedValue(new Error("fetch failed"));
+
+            await expect(
+                withCache(fn, { cacheKey: "error-key" })
+            ).rejects.toThrow("fetch failed");
+        });
+
+        it("should not cache errors — subsequent call retries", async () => {
+            const fn = vi
+                .fn()
+                .mockRejectedValueOnce(new Error("fail"))
+                .mockResolvedValueOnce("recovered");
+
+            await expect(
+                withCache(fn, { cacheKey: "retry-key" })
+            ).rejects.toThrow("fail");
+
+            const result = await withCache(fn, { cacheKey: "retry-key" });
+            expect(result).toBe("recovered");
+            expect(fn).toHaveBeenCalledTimes(2);
+        });
+    });
+
+    describe("clearAllCache", () => {
+        it("should clear all cached data", async () => {
+            const fn = vi
+                .fn()
+                .mockResolvedValueOnce("first")
+                .mockResolvedValueOnce("second");
+
+            await withCache(fn, { cacheKey: "clear-key" });
+            clearAllCache();
+            const result = await withCache(fn, { cacheKey: "clear-key" });
+
+            expect(result).toBe("second");
+            expect(fn).toHaveBeenCalledTimes(2);
+        });
+    });
+});