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

package/src/types/resolvedConfig.ts

@@ -0,0 +1,104 @@
+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";
+            useReward?: boolean;
+            css?: string;
+        };
+        buttonWallet?: {
+            position?: "bottom-right" | "bottom-left";
+            css?: string;
+        };
+        openInApp?: {
+            text?: 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/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.ts

@@ -38,7 +38,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,7 +53,7 @@ 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)
  */
@@ -77,6 +77,7 @@ export type IFrameRpcSchema = [
             requests: ModalRpcStepsInput,
             metadata: ModalRpcMetadata | undefined,
             configMetadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: ModalRpcStepsResultType;
     },
@@ -89,7 +90,7 @@ export type IFrameRpcSchema = [
         Method: "frak_prepareSso";
         Parameters: [
             params: PrepareSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: PrepareSsoReturnType;
@@ -104,7 +105,7 @@ export type IFrameRpcSchema = [
         Method: "frak_openSso";
         Parameters: [
             params: OpenSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: OpenSsoReturnType;
@@ -130,6 +131,7 @@ export type IFrameRpcSchema = [
         Parameters: [
             request: DisplayEmbeddedWalletParamsType,
             metadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: DisplayEmbeddedWalletResultType;
     },
@@ -137,7 +139,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";

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

@@ -22,11 +22,7 @@ export {
     createIframe,
     findIframeInOpener,
 } from "./iframeHelper";
-export {
-    clearMerchantIdCache,
-    fetchMerchantId,
-    resolveMerchantId,
-} from "./merchantId";
+export { sdkConfigStore } from "./sdkConfigStore";
 export {
     type AppSpecificSsoMetadata,
     type CompressedSsoData,

package/src/utils/sdkConfigStore.test.ts

@@ -0,0 +1,405 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { sdkConfigStore } from "./sdkConfigStore";
+
+vi.mock("./backendUrl", () => ({
+    getBackendUrl: vi.fn((walletUrl?: string) => {
+        if (walletUrl?.includes("localhost")) {
+            return "http://localhost:3030";
+        }
+        return "https://backend.frak.id";
+    }),
+}));
+
+describe("sdkConfigStore", () => {
+    beforeEach(() => {
+        sdkConfigStore.clearCache();
+        window.sessionStorage.clear();
+        window.localStorage.clear();
+        window.__frakSdkConfig = undefined;
+        vi.clearAllMocks();
+        vi.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe("sdkConfigStore.resolve", () => {
+        it("should fetch from backend when not cached", async () => {
+            const mockResponse = {
+                merchantId: "merchant-123",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result = await sdkConfigStore.resolve("shop.example.com");
+
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=shop.example.com"
+            );
+        });
+
+        it("should return cached response on subsequent calls", async () => {
+            const mockResponse = {
+                merchantId: "merchant-456",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result1 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result1).toEqual(mockResponse);
+
+            const result2 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result2).toEqual(mockResponse);
+
+            expect(global.fetch).toHaveBeenCalledTimes(1);
+        });
+
+        it("should deduplicate concurrent requests", async () => {
+            const mockResponse = {
+                merchantId: "merchant-789",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const [result1, result2, result3] = await Promise.all([
+                sdkConfigStore.resolve("shop.example.com"),
+                sdkConfigStore.resolve("shop.example.com"),
+                sdkConfigStore.resolve("shop.example.com"),
+            ]);
+
+            expect(result1).toEqual(mockResponse);
+            expect(result2).toEqual(mockResponse);
+            expect(result3).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledTimes(1);
+        });
+
+        it("should use window.location.hostname when domain not provided", async () => {
+            const mockResponse = {
+                merchantId: "merchant-default",
+                name: "Test",
+                domain: "example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            Object.defineProperty(window, "location", {
+                value: { hostname: "example.com" },
+                writable: true,
+            });
+
+            const result = await sdkConfigStore.resolve();
+
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=example.com"
+            );
+        });
+
+        it("should return undefined when domain is empty", async () => {
+            global.fetch = vi.fn();
+
+            const result = await sdkConfigStore.resolve("");
+
+            expect(result).toBeUndefined();
+            expect(global.fetch).not.toHaveBeenCalled();
+        });
+
+        it("should handle fetch errors gracefully", async () => {
+            global.fetch = vi
+                .fn()
+                .mockRejectedValueOnce(new Error("Network error"));
+
+            const result = await sdkConfigStore.resolve("shop.example.com");
+
+            expect(result).toBeUndefined();
+            expect(console.warn).toHaveBeenCalledWith(
+                "[Frak SDK] Failed to fetch merchant config:",
+                expect.any(Error)
+            );
+        });
+
+        it("should handle non-ok response (404, 500)", async () => {
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: false,
+                status: 404,
+            });
+
+            const result = await sdkConfigStore.resolve("nonexistent.com");
+
+            expect(result).toBeUndefined();
+            expect(console.warn).toHaveBeenCalledWith(
+                "[Frak SDK] Merchant lookup failed for domain nonexistent.com: 404"
+            );
+        });
+
+        it("should use custom walletUrl to derive backend URL", async () => {
+            const mockResponse = {
+                merchantId: "merchant-local",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result = await sdkConfigStore.resolve(
+                "shop.example.com",
+                "http://localhost:3000"
+            );
+
+            expect(result).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledWith(
+                "http://localhost:3030/user/merchant/resolve?domain=shop.example.com"
+            );
+        });
+
+        it("should encode domain in URL query parameter", async () => {
+            const mockResponse = {
+                merchantId: "merchant-encoded",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const domainWithSpecialChars = "shop.example.com?test=1&foo=bar";
+            await sdkConfigStore.resolve(domainWithSpecialChars);
+
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=shop.example.com%3Ftest%3D1%26foo%3Dbar"
+            );
+        });
+
+        it("should write merchantId to sessionStorage as 'frak-merchant-id'", async () => {
+            const mockResponse = {
+                merchantId: "merchant-persisted",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            await sdkConfigStore.resolve("shop.example.com");
+
+            expect(window.sessionStorage.getItem("frak-merchant-id")).toBe(
+                "merchant-persisted"
+            );
+        });
+
+        it("should pass lang parameter to backend when provided", async () => {
+            const mockResponse = {
+                merchantId: "merchant-lang",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            await sdkConfigStore.resolve("shop.example.com", undefined, "fr");
+
+            expect(global.fetch).toHaveBeenCalledWith(
+                "https://backend.frak.id/user/merchant/resolve?domain=shop.example.com&lang=fr"
+            );
+        });
+    });
+
+    describe("sdkConfigStore.getMerchantId", () => {
+        it("should return merchantId from resolved config", () => {
+            window.__frakSdkConfig = {
+                isResolved: true,
+                merchantId: "config-merchant-123",
+            };
+
+            const result = sdkConfigStore.getMerchantId();
+
+            expect(result).toBe("config-merchant-123");
+        });
+
+        it("should fall back to sessionStorage", () => {
+            window.__frakSdkConfig = {
+                isResolved: false,
+                merchantId: "",
+            };
+            window.sessionStorage.setItem(
+                "frak-merchant-id",
+                "session-merchant-456"
+            );
+
+            const result = sdkConfigStore.getMerchantId();
+
+            expect(result).toBe("session-merchant-456");
+        });
+
+        it("should return undefined when nothing cached", () => {
+            window.__frakSdkConfig = {
+                isResolved: false,
+                merchantId: "",
+            };
+
+            const result = sdkConfigStore.getMerchantId();
+
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("sdkConfigStore.resolveMerchantId", () => {
+        it("should return merchantId from store without fetch", async () => {
+            window.__frakSdkConfig = {
+                isResolved: true,
+                merchantId: "store-merchant-123",
+            };
+            global.fetch = vi.fn();
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBe("store-merchant-123");
+            expect(global.fetch).not.toHaveBeenCalled();
+        });
+
+        it("should return merchantId from sessionStorage without fetch", async () => {
+            window.__frakSdkConfig = {
+                isResolved: false,
+                merchantId: "",
+            };
+            window.sessionStorage.setItem(
+                "frak-merchant-id",
+                "session-merchant-789"
+            );
+            global.fetch = vi.fn();
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBe("session-merchant-789");
+            expect(global.fetch).not.toHaveBeenCalled();
+        });
+
+        it("should fetch from backend as last resort", async () => {
+            const mockResponse = {
+                merchantId: "fetched-merchant-456",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            Object.defineProperty(window, "location", {
+                value: { hostname: "shop.example.com" },
+                writable: true,
+            });
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBe("fetched-merchant-456");
+            expect(global.fetch).toHaveBeenCalled();
+        });
+
+        it("should return undefined when fetch fails", async () => {
+            global.fetch = vi
+                .fn()
+                .mockRejectedValueOnce(new Error("Network error"));
+
+            Object.defineProperty(window, "location", {
+                value: { hostname: "shop.example.com" },
+                writable: true,
+            });
+
+            const result = await sdkConfigStore.resolveMerchantId();
+
+            expect(result).toBeUndefined();
+        });
+    });
+
+    describe("sdkConfigStore.clearCache", () => {
+        it("should clear all caches and allow re-fetching", async () => {
+            const mockResponse = {
+                merchantId: "merchant-clear-test",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValue({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            const result1 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result1).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledTimes(1);
+
+            sdkConfigStore.clearCache();
+
+            const result2 = await sdkConfigStore.resolve("shop.example.com");
+            expect(result2).toEqual(mockResponse);
+            expect(global.fetch).toHaveBeenCalledTimes(2);
+        });
+
+        it("should clear sessionStorage frak-merchant-id", async () => {
+            const mockResponse = {
+                merchantId: "merchant-session-clear",
+                name: "Test",
+                domain: "shop.example.com",
+                allowedDomains: [],
+            };
+
+            global.fetch = vi.fn().mockResolvedValueOnce({
+                ok: true,
+                json: async () => mockResponse,
+            });
+
+            await sdkConfigStore.resolve("shop.example.com");
+            expect(window.sessionStorage.getItem("frak-merchant-id")).toBe(
+                "merchant-session-clear"
+            );
+
+            sdkConfigStore.clearCache();
+
+            expect(
+                window.sessionStorage.getItem("frak-merchant-id")
+            ).toBeNull();
+        });
+    });
+});