@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.0cd79998

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

@@ -0,0 +1,168 @@
+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 () => {
+            vi.useFakeTimers();
+            const fn = vi
+                .fn()
+                .mockRejectedValueOnce(new Error("fail"))
+                .mockResolvedValueOnce("recovered");
+
+            await expect(
+                withCache(fn, { cacheKey: "retry-key" })
+            ).rejects.toThrow("fail");
+
+            // Advance past the negative cache backoff (1s)
+            vi.advanceTimersByTime(1_001);
+
+            const result = await withCache(fn, { cacheKey: "retry-key" });
+            expect(result).toBe("recovered");
+            expect(fn).toHaveBeenCalledTimes(2);
+
+            vi.useRealTimers();
+        });
+    });
+
+    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);
+        });
+    });
+});

package/src/utils/cache/withCache.ts

@@ -0,0 +1,124 @@
+import { LruMap } from "./lruMap";
+
+type CacheEntry<TData> = {
+    data: TData;
+    created: number;
+};
+
+/** Global cache for in-flight promises (dedup concurrent calls) */
+const promiseCache = new LruMap<Promise<unknown>>(1024);
+
+/** Global cache for resolved responses (TTL-based) */
+const responseCache = new LruMap<CacheEntry<unknown>>(1024);
+
+/** Default cache time: 30 seconds */
+export const DEFAULT_CACHE_TIME = 30_000;
+
+/** Short negative cache to avoid flooding on transient failures */
+const NEGATIVE_CACHE_TIME = 1_000;
+
+/** Tracks recently failed keys to avoid request floods */
+const failureCache = new LruMap<number>(1024);
+
+type WithCacheOptions = {
+    /** The key to cache the data against */
+    cacheKey: string;
+    /** Time in ms that cached data will remain valid. Default: 30_000 (30s). Set to 0 to disable caching. */
+    cacheTime?: number;
+};
+
+/**
+ * Returns the result of a given promise, and caches the result for
+ * subsequent invocations against a provided cache key.
+ *
+ * Also deduplicates concurrent calls — if multiple callers request the same
+ * cache key while the promise is pending, they share the same promise.
+ *
+ * @example
+ * ```ts
+ * // First call fetches, subsequent calls return cached data for 30s
+ * const data = await withCache(
+ *     () => client.request({ method: "frak_getMerchantInformation" }),
+ *     { cacheKey: "merchantInfo", cacheTime: 30_000 }
+ * );
+ * ```
+ */
+export async function withCache<TData>(
+    fn: () => Promise<TData>,
+    { cacheKey, cacheTime = DEFAULT_CACHE_TIME }: WithCacheOptions
+): Promise<TData> {
+    // Check response cache — return immediately if fresh
+    if (cacheTime > 0) {
+        const cached = responseCache.get(cacheKey) as
+            | CacheEntry<TData>
+            | undefined;
+        if (cached) {
+            const age = Date.now() - cached.created;
+            if (age < cacheTime) return cached.data;
+        }
+    }
+
+    // Check if this key recently failed — back off briefly
+    const lastFailure = failureCache.get(cacheKey);
+    if (lastFailure && Date.now() - lastFailure < NEGATIVE_CACHE_TIME) {
+        throw new Error(`Cache: ${cacheKey} recently failed, backing off`);
+    }
+
+    // Check if there's already a pending promise (dedup concurrent calls)
+    let promise = promiseCache.get(cacheKey) as Promise<TData> | undefined;
+    if (!promise) {
+        promise = fn();
+        promiseCache.set(cacheKey, promise);
+    }
+
+    try {
+        const data = await promise;
+        // Store the response with a timestamp
+        responseCache.set(cacheKey, { data, created: Date.now() });
+        // Clear any previous failure
+        failureCache.delete(cacheKey);
+        return data;
+    } catch (error) {
+        // Record the failure timestamp
+        failureCache.set(cacheKey, Date.now());
+        throw error;
+    } finally {
+        // Clear the promise cache so subsequent calls can re-fetch after TTL
+        promiseCache.delete(cacheKey);
+    }
+}
+
+/**
+ * Get a cache handle for a specific key, useful for manual invalidation.
+ *
+ * @example
+ * ```ts
+ * // Invalidate merchant info cache after a mutation
+ * getCache("frak_getMerchantInformation").clear();
+ * ```
+ */
+export function getCache(cacheKey: string) {
+    return {
+        /** Clear both the pending promise and the cached response */
+        clear: () => {
+            promiseCache.delete(cacheKey);
+            responseCache.delete(cacheKey);
+        },
+        /** Check if a non-expired response exists */
+        has: (cacheTime: number = DEFAULT_CACHE_TIME) => {
+            const cached = responseCache.get(cacheKey);
+            if (!cached) return false;
+            return Date.now() - cached.created < cacheTime;
+        },
+    };
+}
+
+/**
+ * Clear all cached data (both pending promises and resolved responses).
+ * Called automatically when the client is destroyed.
+ */
+export function clearAllCache() {
+    promiseCache.clear();
+    responseCache.clear();
+    failureCache.clear();
+}

package/src/utils/inAppBrowser.ts

@@ -0,0 +1,60 @@
+/**
+ * Check if the current device runs iOS (including iPadOS 13+).
+ */
+function checkIsIOS(): boolean {
+    if (typeof navigator === "undefined") return false;
+    const ua = navigator.userAgent;
+    // Standard iOS devices
+    if (/iPhone|iPad|iPod/i.test(ua)) return true;
+    // iPadOS 13+ reports as Macintosh — detect via touch support
+    if (/Macintosh/i.test(ua) && navigator.maxTouchPoints > 1) return true;
+    return false;
+}
+
+/**
+ * Whether the current device runs iOS (including iPadOS 13+).
+ */
+export const isIOS: boolean = checkIsIOS();
+
+/**
+ * Check if the current browser is a social media in-app browser
+ * (Instagram, Facebook WebView).
+ */
+function checkInAppBrowser(): boolean {
+    if (typeof navigator === "undefined") return false;
+    const ua = navigator.userAgent.toLowerCase();
+    return (
+        ua.includes("instagram") ||
+        ua.includes("fban") ||
+        ua.includes("fbav") ||
+        ua.includes("facebook")
+    );
+}
+
+/**
+ * Whether the current browser is a social media in-app browser
+ * (Instagram, Facebook).
+ */
+export const isInAppBrowser: boolean = checkInAppBrowser();
+
+/**
+ * Redirect to external browser from in-app WebView.
+ *
+ * - **iOS**: Uses `x-safari-https://` scheme — server-side 302 redirects
+ *   to custom URL schemes are silently swallowed by WKWebView.
+ *   Direct `window.location.href` assignment works (confirmed iOS 17+).
+ *
+ * - **Android**: Uses backend `/common/social` endpoint which returns a PDF
+ *   Content-Type response, forcing the WebView to hand off to the default browser.
+ *
+ * @param targetUrl - The URL to open in the external browser
+ */
+export function redirectToExternalBrowser(targetUrl: string): void {
+    if (isIOS && targetUrl.startsWith("https://")) {
+        window.location.href = `x-safari-https://${targetUrl.slice(8)}`;
+    } else if (isIOS && targetUrl.startsWith("http://")) {
+        window.location.href = `x-safari-http://${targetUrl.slice(7)}`;
+    } else {
+        window.location.href = `${process.env.BACKEND_URL}/common/social?u=${encodeURIComponent(targetUrl)}`;
+    }
+}

package/src/utils/index.ts

@@ -1,5 +1,6 @@
 export { Deferred } from "@frak-labs/frame-connector";
 export { getBackendUrl } from "./backendUrl";
+export { clearAllCache, getCache, withCache } from "./cache";
 export { getClientId } from "./clientId";
 export { base64urlDecode, base64urlEncode } from "./compression/b64";
 export { compressJsonToB64 } from "./compression/compress";
@@ -23,10 +24,15 @@ export {
     findIframeInOpener,
 } from "./iframeHelper";
 export {
-    clearMerchantIdCache,
-    fetchMerchantId,
-    resolveMerchantId,
-} from "./merchantId";
+    isInAppBrowser,
+    isIOS,
+    redirectToExternalBrowser,
+} from "./inAppBrowser";
+export {
+    type MergeAttributionInput,
+    mergeAttribution,
+} from "./mergeAttribution";
+export { sdkConfigStore } from "./sdkConfigStore";
 export {
     type AppSpecificSsoMetadata,
     type CompressedSsoData,

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