@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.61e6fb99

package/src/utils/mergeAttribution.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import { mergeAttribution } from "./mergeAttribution";
+
+describe("mergeAttribution", () => {
+    describe("explicit disable", () => {
+        it("returns undefined when perCall is null", () => {
+            expect(
+                mergeAttribution({
+                    perCall: null,
+                    defaults: { utmSource: "brand" },
+                    productUtmContent: "product-123",
+                })
+            ).toBeUndefined();
+        });
+    });
+
+    describe("no inputs", () => {
+        it("returns undefined when all layers are empty", () => {
+            expect(mergeAttribution({ perCall: undefined })).toBeUndefined();
+        });
+
+        it("returns undefined when perCall is undefined and defaults is empty object", () => {
+            expect(
+                mergeAttribution({ perCall: undefined, defaults: {} })
+            ).toBeUndefined();
+        });
+    });
+
+    describe("defaults only", () => {
+        it("returns defaults when perCall is undefined", () => {
+            expect(
+                mergeAttribution({
+                    perCall: undefined,
+                    defaults: {
+                        utmSource: "brand",
+                        utmMedium: "newsletter",
+                    },
+                })
+            ).toEqual({
+                utmSource: "brand",
+                utmMedium: "newsletter",
+            });
+        });
+    });
+
+    describe("perCall only", () => {
+        it("returns perCall when defaults is undefined", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmSource: "custom", utmContent: "hero" },
+                })
+            ).toEqual({
+                utmSource: "custom",
+                utmContent: "hero",
+            });
+        });
+
+        it("returns empty object when perCall is empty and no defaults", () => {
+            // perCall: {} signals \"apply attribution with hardcoded defaults downstream\"
+            expect(mergeAttribution({ perCall: {} })).toEqual({});
+        });
+    });
+
+    describe("per-field merge (perCall wins over defaults)", () => {
+        it("merges perCall over defaults field-by-field", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmMedium: "email" },
+                    defaults: {
+                        utmSource: "brand",
+                        utmMedium: "newsletter",
+                        utmCampaign: "spring",
+                    },
+                })
+            ).toEqual({
+                utmSource: "brand",
+                utmMedium: "email",
+                utmCampaign: "spring",
+            });
+        });
+
+        it("lets perCall override every default field", () => {
+            expect(
+                mergeAttribution({
+                    perCall: {
+                        utmSource: "pc-src",
+                        utmMedium: "pc-med",
+                        utmCampaign: "pc-camp",
+                        utmTerm: "pc-term",
+                        via: "pc-via",
+                        ref: "pc-ref",
+                    },
+                    defaults: {
+                        utmSource: "def-src",
+                        utmMedium: "def-med",
+                        utmCampaign: "def-camp",
+                        utmTerm: "def-term",
+                        via: "def-via",
+                        ref: "def-ref",
+                    },
+                })
+            ).toEqual({
+                utmSource: "pc-src",
+                utmMedium: "pc-med",
+                utmCampaign: "pc-camp",
+                utmTerm: "pc-term",
+                via: "pc-via",
+                ref: "pc-ref",
+            });
+        });
+    });
+
+    describe("utm_content handling", () => {
+        it("uses productUtmContent when provided", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmContent: "fallback" },
+                    productUtmContent: "product-42",
+                })
+            ).toEqual({ utmContent: "product-42" });
+        });
+
+        it("falls back to perCall.utmContent when productUtmContent is absent", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmContent: "fallback" },
+                })
+            ).toEqual({ utmContent: "fallback" });
+        });
+
+        it("never inherits utm_content from defaults (shape excludes it)", () => {
+            // Even if a backend/SDK config erroneously contained utm_content
+            // at runtime, the merged result must not carry it.
+            expect(
+                mergeAttribution({
+                    perCall: {},
+                    // @ts-expect-error — defaults typing disallows utmContent,
+                    // but we simulate runtime data coming from a loose source.
+                    defaults: { utmContent: "should-not-leak" },
+                })
+            ).toEqual({});
+        });
+
+        it("adds attribution solely to carry a productUtmContent", () => {
+            expect(
+                mergeAttribution({
+                    perCall: undefined,
+                    productUtmContent: "product-7",
+                })
+            ).toEqual({ utmContent: "product-7" });
+        });
+    });
+});

package/src/utils/mergeAttribution.ts

@@ -0,0 +1,75 @@
+import type { AttributionDefaults, AttributionParams } from "../types/tracking";
+
+/**
+ * Inputs for {@link mergeAttribution}.
+ */
+export type MergeAttributionInput = {
+    /**
+     * Per-call attribution override passed to actions like `displaySharingPage`.
+     *
+     * - `null` explicitly disables attribution (no UTM/ref/via params are added).
+     * - `undefined` means "no per-call override" — defaults apply if present.
+     * - An object (including `{}`) merges field-by-field with defaults.
+     */
+    perCall: AttributionParams | null | undefined;
+    /**
+     * Pre-merged merchant-level defaults (backend config > SDK static config).
+     * `utm_content` is intentionally absent from this shape.
+     */
+    defaults?: AttributionDefaults;
+    /**
+     * Per-product `utm_content` override (from the currently selected
+     * `SharingPageProduct`). Takes precedence over `perCall.utmContent`.
+     */
+    productUtmContent?: string;
+};
+
+/**
+ * Merge the three attribution layers into a single {@link AttributionParams}
+ * value suitable for `FrakContextManager.update`.
+ *
+ * Priority per field:
+ *   1. `perCall` (wins)
+ *   2. `defaults` (merchant-level, backend > SDK static, already pre-merged)
+ *   3. Hardcoded fallbacks resolved later by `FrakContextManager`
+ *
+ * Special rules:
+ * - `perCall === null` returns `undefined` (explicit disable: no UTM/ref/via).
+ * - `perCall === undefined` (no opinion) yields at least `{}` so `FrakContextManager`
+ *   applies its hardcoded defaults (utm_source=frak, utm_medium=referral,
+ *   utm_campaign=<merchantId>, ref=<clientId>, via=frak).
+ * - `utm_content` never comes from `defaults`; only `productUtmContent` or
+ *   `perCall.utmContent` can populate it.
+ */
+export function mergeAttribution({
+    perCall,
+    defaults,
+    productUtmContent,
+}: MergeAttributionInput): AttributionParams | undefined {
+    // Explicit disable
+    if (perCall === null) return undefined;
+
+    const hasPerCall = perCall !== undefined;
+    const hasDefaults =
+        defaults !== undefined && Object.keys(defaults).length > 0;
+    const hasProductUtm =
+        productUtmContent !== undefined && productUtmContent !== "";
+
+    if (!hasPerCall && !hasDefaults && !hasProductUtm) return undefined;
+
+    // Per-field merge: per-call wins over defaults.
+    const merged: AttributionParams = {
+        ...defaults,
+        ...(perCall ?? {}),
+    };
+
+    // utm_content priority: productUtmContent > perCall.utmContent; never from defaults.
+    const utmContent = productUtmContent ?? perCall?.utmContent;
+    if (utmContent !== undefined && utmContent !== "") {
+        merged.utmContent = utmContent;
+    } else {
+        delete merged.utmContent;
+    }
+
+    return merged;
+}

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();
+        });
+    });
+});