@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.10dada3f

package/src/utils/FrakContext.ts

@@ -1,5 +1,10 @@
 import { type Address, bytesToHex, hexToBytes, isAddress } from "viem";
-import type { FrakContext, FrakContextV1, FrakContextV2 } from "../types";
+import type {
+    AttributionParams,
+    FrakContext,
+    FrakContextV1,
+    FrakContextV2,
+} from "../types";
 import { isV2Context } from "../types";
 import { base64urlDecode, base64urlEncode } from "./compression/b64";
 import { compressJsonToB64 } from "./compression/compress";
@@ -23,13 +28,16 @@ function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
     if (!context) return;
     try {
         if (isV2Context(context)) {
-            // Runtime validation: all V2 fields must be present and truthy
-            if (!context.c || !context.m || !context.t) return undefined;
+            // Runtime validation: m + t are always required, and at least one of
+            // c (anonymous fingerprint) or w (wallet) must be present.
+            if (!context.m || !context.t) return undefined;
+            if (!context.c && !context.w) return undefined;
             return compressJsonToB64({
                 v: 2,
-                c: context.c,
                 m: context.m,
                 t: context.t,
+                ...(context.c ? { c: context.c } : {}),
+                ...(context.w ? { w: context.w } : {}),
             });
         }
 
@@ -56,10 +64,15 @@ function decompress(context?: string): FrakContext | undefined {
         // Try V2 JSON first — V2 payloads are longer than V1's 20-byte address
         const json = decompressJsonFromB64<FrakContextV2>(context);
         if (json && typeof json === "object" && json.v === 2) {
-            if (json.c && json.m && json.t) {
-                return { v: 2, c: json.c, m: json.m, t: json.t };
-            }
-            return undefined;
+            if (!json.m || !json.t) return undefined;
+            if (!json.c && !json.w) return undefined;
+            return {
+                v: 2,
+                m: json.m,
+                t: json.t,
+                ...(json.c ? { c: json.c } : {}),
+                ...(json.w ? { w: json.w } : {}),
+            };
         }
 
         // Fall back to V1: raw 20-byte address
@@ -91,20 +104,81 @@ function parse({ url }: { url: string }): FrakContext | null | undefined {
     return decompress(frakContext);
 }
 
+/**
+ * Default UTM medium value when attribution is requested.
+ */
+const DEFAULT_UTM_MEDIUM = "referral";
+
+/**
+ * Default utm_source / via value when attribution is requested.
+ */
+const DEFAULT_ATTRIBUTION_SOURCE = "frak";
+
+/**
+ * Resolve attribution defaults from the provided context.
+ *
+ * V2 contexts expose the merchantId (`m`) and, when anonymous, the clientId
+ * (`c`), which feed `utm_campaign` and `ref` respectively. When V2 only carries
+ * a wallet (`w`), `ref` is intentionally left unset — we don't want wallet
+ * addresses leaking into UTM params. V1 contexts have no equivalent.
+ */
+function resolveAttributionValues(
+    context: FrakContextV1 | FrakContextV2,
+    overrides: AttributionParams
+): Record<string, string | undefined> {
+    const isV2 = isV2Context(context);
+    return {
+        utm_source: overrides.utmSource ?? DEFAULT_ATTRIBUTION_SOURCE,
+        utm_medium: overrides.utmMedium ?? DEFAULT_UTM_MEDIUM,
+        utm_campaign: overrides.utmCampaign ?? (isV2 ? context.m : undefined),
+        utm_content: overrides.utmContent,
+        utm_term: overrides.utmTerm,
+        via: overrides.via ?? DEFAULT_ATTRIBUTION_SOURCE,
+        ref: overrides.ref ?? (isV2 ? context.c : undefined),
+    };
+}
+
+/**
+ * Append attribution query params to a URL using gap-fill semantics.
+ *
+ * Existing params on the URL are preserved untouched (so merchant-provided
+ * UTMs take precedence). Only missing keys are populated.
+ */
+function applyAttributionParams(
+    urlObj: URL,
+    context: FrakContextV1 | FrakContextV2,
+    attribution?: AttributionParams
+): void {
+    const values = resolveAttributionValues(context, attribution ?? {});
+    for (const [key, value] of Object.entries(values)) {
+        if (value === undefined || value === "") continue;
+        if (urlObj.searchParams.has(key)) continue;
+        urlObj.searchParams.set(key, value);
+    }
+}
+
 /**
  * Add or replace the `fCtx` query parameter in a URL with the given context.
  *
+ * Standard affiliation params (`utm_source`, `utm_medium`, `utm_campaign`,
+ * `ref`, `via`, ...) are always appended using gap-fill semantics: pre-existing
+ * params on the URL are preserved, defaults are derived from the context when
+ * applicable, and `attribution` overrides take precedence when provided.
+ *
  * @param args
  * @param args.url - The URL to update
  * @param args.context - The context to embed (V1 or V2)
+ * @param args.attribution - Optional attribution overrides. Defaults are applied even when omitted.
  * @returns The updated URL string, or null on failure
  */
 function update({
     url,
     context,
+    attribution,
 }: {
     url?: string;
     context: FrakContextV1 | FrakContextV2;
+    attribution?: AttributionParams;
 }): string | null {
     if (!url) return null;
 
@@ -113,6 +187,7 @@ function update({
 
     const urlObj = new URL(url);
     urlObj.searchParams.set(contextKey, compressedContext);
+    applyAttributionParams(urlObj, context, attribution);
     return urlObj.toString();
 }
 

package/src/utils/analytics/events/component.ts

@@ -0,0 +1,58 @@
+type ButtonBaseProps = {
+    placement?: string;
+    target_interaction?: string;
+    has_reward?: boolean;
+};
+
+type BannerVariant = "referral" | "inapp";
+type BannerOutcome = "clicked" | "dismissed";
+type PostPurchaseVariant = "referrer" | "referee";
+type ShareClickAction = "share-modal" | "embedded-wallet" | "sharing-page";
+
+export type SdkComponentEventMap = {
+    // Share button — click carries the resolved action + reward presence so
+    // we can compare per-merchant configuration impact on conversion.
+    share_button_clicked: ButtonBaseProps & {
+        click_action: ShareClickAction;
+    };
+    share_modal_error: ButtonBaseProps & {
+        error?: string;
+    };
+
+    // Wallet button (floating) — NOT actively used in production. No tracking.
+
+    // Open in app — path lets us compare deep-link destinations once we add more.
+    open_in_app_clicked: {
+        placement?: string;
+        path: string;
+    };
+    app_not_installed: {
+        placement?: string;
+        path: string;
+    };
+
+    // Banner — referral vs in-app variants share the funnel shape.
+    banner_impression: {
+        placement?: string;
+        variant: BannerVariant;
+        has_reward?: boolean;
+    };
+    banner_resolved: {
+        placement?: string;
+        variant: BannerVariant;
+        outcome: BannerOutcome;
+    };
+
+    // Post-purchase — the card drives the highest-intent entry into the
+    // referral loop; variant tells us whether we upsold a new share or
+    // celebrated an existing referee.
+    post_purchase_impression: {
+        placement?: string;
+        variant: PostPurchaseVariant;
+        has_reward?: boolean;
+    };
+    post_purchase_clicked: {
+        placement?: string;
+        variant: PostPurchaseVariant;
+    };
+};

package/src/utils/analytics/events/index.ts

@@ -0,0 +1,20 @@
+import type { SdkComponentEventMap } from "./component";
+import type { SdkLifecycleEventMap } from "./lifecycle";
+import type { SdkReferralEventMap } from "./referral";
+
+export type { SdkComponentEventMap } from "./component";
+export type {
+    SdkHandshakeFailureReason,
+    SdkLifecycleEventMap,
+} from "./lifecycle";
+export type { SdkReferralEventMap } from "./referral";
+
+/**
+ * Merged SDK event map. Consumed by the SDK's typed `trackEvent`.
+ * Stays isolated from wallet-shared because the SDK ships in partner
+ * bundles (different OpenPanel client id, no wallet-shared dependency
+ * allowed — see `packages/wallet-shared/AGENTS.md`).
+ */
+export type SdkEventMap = SdkLifecycleEventMap &
+    SdkComponentEventMap &
+    SdkReferralEventMap;

package/src/utils/analytics/events/lifecycle.ts

@@ -0,0 +1,26 @@
+export type SdkHandshakeFailureReason =
+    | "timeout"
+    | "origin"
+    | "asset_push"
+    | "unknown";
+
+export type SdkLifecycleEventMap = {
+    sdk_initialized: {
+        sdkVersion?: string;
+    };
+    sdk_iframe_connected: {
+        handshake_duration_ms: number;
+    };
+    sdk_iframe_handshake_failed: {
+        reason: SdkHandshakeFailureReason;
+    };
+    /**
+     * Emitted by the CDN bootstrap when `initFrakSdk()` throws before a
+     * client is available. Uses a transient OpenPanel instance so broken
+     * partner integrations are still captured.
+     */
+    sdk_init_failed: {
+        reason: string;
+        config_missing?: boolean;
+    };
+};

package/src/utils/analytics/events/referral.ts

@@ -0,0 +1,11 @@
+export type SdkReferralEventMap = {
+    user_referred_started: {
+        referrer?: string;
+        referrerClientId?: string;
+        referrerWallet?: string;
+        walletStatus?: string;
+    };
+    user_referred_completed: {
+        status: "success";
+    };
+};

package/src/utils/analytics/index.ts

@@ -0,0 +1,8 @@
+export type {
+    SdkComponentEventMap,
+    SdkEventMap,
+    SdkHandshakeFailureReason,
+    SdkLifecycleEventMap,
+    SdkReferralEventMap,
+} from "./events";
+export { trackEvent } from "./trackEvent";

package/src/utils/{trackEvent.test.ts → analytics/trackEvent.test.ts}

@@ -10,8 +10,8 @@ import {
     expect,
     it,
     vi,
-} from "../../tests/vitest-fixtures";
-import type { FrakClient } from "../types";
+} from "../../../tests/vitest-fixtures";
+import type { FrakClient } from "../../types";
 import { trackEvent } from "./trackEvent";
 
 describe("trackEvent", () => {
@@ -42,16 +42,19 @@ describe("trackEvent", () => {
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "share_button_clicked",
-                {}
+                undefined
             );
         });
 
         it("should track event with props", () => {
-            const props = { userId: "123", page: "home" };
-            trackEvent(mockClient, "wallet_button_clicked", props);
+            const props = {
+                placement: "footer",
+                click_action: "share-modal",
+            } as const;
+            trackEvent(mockClient, "share_button_clicked", props);
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
-                "wallet_button_clicked",
+                "share_button_clicked",
                 props
             );
         });
@@ -71,25 +74,18 @@ describe("trackEvent", () => {
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "user_referred_started",
-                {}
+                undefined
             );
         });
 
         it("should track user_referred_completed event", () => {
-            trackEvent(mockClient, "user_referred_completed");
+            trackEvent(mockClient, "user_referred_completed", {
+                status: "success",
+            });
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "user_referred_completed",
-                {}
-            );
-        });
-
-        it("should track user_referred_error event", () => {
-            trackEvent(mockClient, "user_referred_error");
-
-            expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
-                "user_referred_error",
-                {}
+                { status: "success" }
             );
         });
     });
@@ -102,7 +98,7 @@ describe("trackEvent", () => {
         });
 
         it("should log debug message when client is undefined", () => {
-            trackEvent(undefined, "wallet_button_clicked");
+            trackEvent(undefined, "share_button_clicked");
 
             expect(consoleDebugSpy).toHaveBeenCalledWith(
                 "[Frak] No client provided, skipping event tracking"
@@ -143,30 +139,26 @@ describe("trackEvent", () => {
             const clientWithoutPanel = {} as FrakClient;
 
             expect(() => {
-                trackEvent(clientWithoutPanel, "wallet_button_clicked");
+                trackEvent(clientWithoutPanel, "share_button_clicked");
             }).not.toThrow();
         });
     });
 
     describe("edge cases", () => {
-        it("should handle empty props object", () => {
-            trackEvent(mockClient, "share_button_clicked", {});
+        it("should handle typed props object", () => {
+            trackEvent(mockClient, "share_button_clicked", {
+                click_action: "share-modal",
+            });
 
             expect(mockClient.openPanel?.track).toHaveBeenCalledWith(
                 "share_button_clicked",
-                {}
+                { click_action: "share-modal" }
             );
         });
 
         it("should handle complex props object", () => {
             const complexProps = {
-                userId: "123",
-                metadata: {
-                    page: "home",
-                    section: "header",
-                },
-                tags: ["tag1", "tag2"],
-                timestamp: Date.now(),
+                status: "success" as const,
             };
 
             trackEvent(mockClient, "user_referred_completed", complexProps);

package/src/utils/analytics/trackEvent.ts

@@ -0,0 +1,34 @@
+import type { FrakClient } from "../../types";
+import type { SdkEventMap } from "./events";
+
+/**
+ * Track an analytics event via the SDK's OpenPanel instance.
+ * Fire-and-forget — silently catches errors so analytics never break a
+ * partner integration.
+ *
+ * The client must be passed explicitly because the OpenPanel instance is
+ * scoped to each `FrakClient` (a partner site may hold multiple iframes).
+ *
+ * @param client - The Frak client instance (no-op if undefined)
+ * @param event - Typed event name from the SDK event map
+ * @param properties - Typed properties for the given event
+ */
+export function trackEvent<K extends keyof SdkEventMap>(
+    client: FrakClient | undefined,
+    event: K,
+    properties?: SdkEventMap[K]
+): void {
+    if (!client) {
+        console.debug("[Frak] No client provided, skipping event tracking");
+        return;
+    }
+
+    try {
+        client.openPanel?.track(
+            event as string,
+            properties as Record<string, unknown> | undefined
+        );
+    } catch (e) {
+        console.debug("[Frak] Failed to track event:", event, e);
+    }
+}

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