@frak-labs/core-sdk 1.0.0 → 1.0.1

package/src/utils/FrakContext.test.ts

@@ -25,10 +25,12 @@ describe("FrakContextManager", () => {
     });
 
     describe("V2 context", () => {
+        const MERCHANT_ID = "550e8400-e29b-41d4-a716-446655440000";
+        const CLIENT_ID = "550e8400-e29b-41d4-a716-446655440001";
         const v2Context: FrakContextV2 = {
             v: 2,
-            c: "test-client-id-uuid",
-            m: "merchant-uuid-1234",
+            c: CLIENT_ID,
+            m: MERCHANT_ID,
             t: 1709654400,
         };
 
@@ -42,7 +44,7 @@ describe("FrakContextManager", () => {
                 expect(result).not.toMatch(/[+/=]/);
             });
 
-            it("should return undefined when v2 context is missing clientId", () => {
+            it("should return undefined when v2 context has neither clientId nor wallet", () => {
                 const partial = { v: 2 as const, m: "m", t: 123 };
                 const result = FrakContextManager.compress(
                     partial as FrakContextV2
@@ -50,8 +52,35 @@ describe("FrakContextManager", () => {
                 expect(result).toBeUndefined();
             });
 
+            it("should compress v2 context with wallet only (no clientId)", () => {
+                const v2WithWalletOnly: FrakContextV2 = {
+                    v: 2,
+                    m: MERCHANT_ID,
+                    t: 1709654400,
+                    w: "0x1234567890123456789012345678901234567890" as Address,
+                };
+                const result = FrakContextManager.compress(v2WithWalletOnly);
+                expect(result).toBeDefined();
+                const decompressed = FrakContextManager.decompress(result);
+                expect(decompressed).toEqual(v2WithWalletOnly);
+            });
+
+            it("should compress v2 context with both clientId and wallet", () => {
+                const v2Hybrid: FrakContextV2 = {
+                    v: 2,
+                    c: CLIENT_ID,
+                    m: MERCHANT_ID,
+                    t: 1709654400,
+                    w: "0x1234567890123456789012345678901234567890" as Address,
+                };
+                const result = FrakContextManager.compress(v2Hybrid);
+                expect(result).toBeDefined();
+                const decompressed = FrakContextManager.decompress(result);
+                expect(decompressed).toEqual(v2Hybrid);
+            });
+
             it("should return undefined when v2 context is missing merchantId", () => {
-                const partial = { v: 2 as const, c: "c", t: 123 };
+                const partial = { v: 2 as const, c: CLIENT_ID, t: 123 };
                 const result = FrakContextManager.compress(
                     partial as FrakContextV2
                 );
@@ -59,12 +88,46 @@ describe("FrakContextManager", () => {
             });
 
             it("should return undefined when v2 context is missing timestamp", () => {
-                const partial = { v: 2 as const, c: "c", m: "m" };
+                const partial = { v: 2 as const, c: CLIENT_ID, m: MERCHANT_ID };
                 const result = FrakContextManager.compress(
                     partial as FrakContextV2
                 );
                 expect(result).toBeUndefined();
             });
+
+            it("should reject v2 context with a malformed wallet address", () => {
+                const partial = {
+                    v: 2 as const,
+                    m: MERCHANT_ID,
+                    t: 1709654400,
+                    w: "0xnot-a-valid-address" as Address,
+                };
+                const result = FrakContextManager.compress(
+                    partial as FrakContextV2
+                );
+                // Invalid wallet → falls back to clientId requirement; absent here → undefined
+                expect(result).toBeUndefined();
+            });
+
+            it("should drop a malformed wallet but keep a valid clientId", () => {
+                const hybrid = {
+                    v: 2 as const,
+                    c: CLIENT_ID,
+                    m: MERCHANT_ID,
+                    t: 1709654400,
+                    w: "0xnot-a-valid-address" as Address,
+                };
+                const compressed = FrakContextManager.compress(
+                    hybrid as FrakContextV2
+                );
+                const decompressed = FrakContextManager.decompress(compressed);
+                expect(decompressed).toEqual({
+                    v: 2,
+                    c: CLIENT_ID,
+                    m: MERCHANT_ID,
+                    t: 1709654400,
+                });
+            });
         });
 
         describe("decompress", () => {
@@ -74,6 +137,22 @@ describe("FrakContextManager", () => {
 
                 expect(decompressed).toEqual(v2Context);
             });
+
+            it("should reject payloads whose header reserved bits are set", async () => {
+                // Craft a valid V2 binary payload then flip a reserved bit
+                // in the header — decompress must refuse to parse it (forward-compat guard).
+                const { encodeFrakContextV2 } = await import(
+                    "./frakContextV2Codec"
+                );
+                const { base64urlEncode } = await import("./compression/b64");
+                const encoded = encodeFrakContextV2(v2Context);
+                expect(encoded).toBeDefined();
+                const tampered = new Uint8Array(encoded as Uint8Array);
+                tampered[0] |= 0x40; // set a reserved bit
+                const payload = base64urlEncode(tampered);
+                const result = FrakContextManager.decompress(payload);
+                expect(result).toBeUndefined();
+            });
         });
 
         describe("parse", () => {
@@ -86,8 +165,8 @@ describe("FrakContextManager", () => {
                 expect(result).toBeDefined();
                 expect(result).toHaveProperty("v", 2);
                 const v2 = result as FrakContextV2;
-                expect(v2.c).toBe("test-client-id-uuid");
-                expect(v2.m).toBe("merchant-uuid-1234");
+                expect(v2.c).toBe(CLIENT_ID);
+                expect(v2.m).toBe(MERCHANT_ID);
                 expect(v2.t).toBe(1709654400);
             });
         });
@@ -121,6 +200,157 @@ describe("FrakContextManager", () => {
                 expect(result).toContain("baz=qux");
                 expect(result).toContain("fCtx=");
             });
+
+            describe("update with attribution", () => {
+                const url = "https://example.com/product";
+
+                it("should apply default attribution params when attribution is omitted", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                    });
+
+                    expect(result).toBeDefined();
+                    expect(result).toContain("fCtx=");
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        v2Context.m
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                });
+
+                it("should apply default attribution params when attribution is an empty object", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: {},
+                    });
+
+                    expect(result).toBeDefined();
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        v2Context.m
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                    expect(
+                        parsedUrl.searchParams.get("utm_content")
+                    ).toBeNull();
+                    expect(parsedUrl.searchParams.get("utm_term")).toBeNull();
+                });
+
+                it("should honor overrides over defaults", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: {
+                            utmSource: "newsletter",
+                            utmMedium: "email",
+                            utmCampaign: "spring-sale",
+                            utmContent: "hero-banner",
+                            utmTerm: "wallet",
+                            via: "partner",
+                            ref: "alice",
+                        },
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "newsletter"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "email"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        "spring-sale"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_content")).toBe(
+                        "hero-banner"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_term")).toBe(
+                        "wallet"
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("partner");
+                    expect(parsedUrl.searchParams.get("ref")).toBe("alice");
+                });
+
+                it("should preserve merchant-provided UTMs on the base URL (gap-fill)", () => {
+                    const baseUrl =
+                        "https://example.com/product?utm_source=google&utm_campaign=merchant-spring";
+                    const result = FrakContextManager.update({
+                        url: baseUrl,
+                        context: v2Context,
+                        attribution: {},
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    // Merchant-provided values preserved
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "google"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_campaign")).toBe(
+                        "merchant-spring"
+                    );
+                    // Missing ones filled by Frak defaults
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("ref")).toBe(v2Context.c);
+                });
+
+                it("should skip fields with empty-string overrides", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                        attribution: { utmContent: "", utmTerm: "" },
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    expect(parsedUrl.searchParams.has("utm_content")).toBe(
+                        false
+                    );
+                    expect(parsedUrl.searchParams.has("utm_term")).toBe(false);
+                });
+
+                it("should skip context-derived defaults for V1 (no merchantId/clientId)", () => {
+                    const v1Context: FrakContextV1 = {
+                        r: "0x1234567890123456789012345678901234567890" as Address,
+                    };
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v1Context,
+                        attribution: {},
+                    });
+
+                    const parsedUrl = new URL(result!);
+                    // Static defaults still applied
+                    expect(parsedUrl.searchParams.get("utm_source")).toBe(
+                        "frak"
+                    );
+                    expect(parsedUrl.searchParams.get("utm_medium")).toBe(
+                        "referral"
+                    );
+                    expect(parsedUrl.searchParams.get("via")).toBe("frak");
+                    // No derivable values from V1
+                    expect(parsedUrl.searchParams.has("utm_campaign")).toBe(
+                        false
+                    );
+                    expect(parsedUrl.searchParams.has("ref")).toBe(false);
+                });
+            });
         });
     });
 
@@ -416,8 +646,8 @@ describe("FrakContextManager", () => {
             const url = "https://example.com/test";
             const context: FrakContextV2 = {
                 v: 2,
-                c: "client-id",
-                m: "merchant-id",
+                c: "550e8400-e29b-41d4-a716-446655440001",
+                m: "550e8400-e29b-41d4-a716-446655440000",
                 t: 1709654400,
             };
 

package/src/utils/FrakContext.ts

@@ -1,9 +1,13 @@
 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";
-import { decompressJsonFromB64 } from "./compression/decompress";
+import { decodeFrakContextV2, encodeFrakContextV2 } from "./frakContextV2Codec";
 
 /**
  * URL parameter key for the Frak referral context
@@ -13,7 +17,8 @@ const contextKey = "fCtx";
 /**
  * Compress a Frak context into a URL-safe string.
  *
- * - V2 contexts are serialized as compressed JSON (base64url).
+ * - V2 contexts are encoded using a compact binary layout (see
+ *   {@link encodeFrakContextV2}) then base64url-encoded.
  * - V1 contexts encode the wallet address as raw bytes (base64url).
  *
  * @param context - The context to compress (V1 or V2)
@@ -23,14 +28,9 @@ 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;
-            return compressJsonToB64({
-                v: 2,
-                c: context.c,
-                m: context.m,
-                t: context.t,
-            });
+            const encoded = encodeFrakContextV2(context);
+            if (!encoded) return undefined;
+            return base64urlEncode(encoded);
         }
 
         // V1 legacy: compress wallet address as raw bytes
@@ -45,7 +45,8 @@ function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
 /**
  * Decompress a base64url string back into a Frak context.
  *
- * Attempts V2 JSON decompression first, then falls back to V1 raw bytes.
+ * V1 (exactly 20 bytes) and V2 (37, 41, or 57 bytes) are distinguished by
+ * their decoded byte length, so there is no ambiguity.
  *
  * @param context - The compressed context string
  * @returns The decompressed FrakContext, or undefined on failure
@@ -53,17 +54,16 @@ function compress(context?: FrakContextV1 | FrakContextV2): string | undefined {
 function decompress(context?: string): FrakContext | undefined {
     if (!context || context.length === 0) return;
     try {
-        // 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 };
-            }
+        const bytes = base64urlDecode(context);
+
+        // V1 is a raw 20-byte wallet address; V2 binary is always longer
+        // and starts with a header byte whose low nibble is the version.
+        if (bytes.length !== 20) {
+            const v2 = decodeFrakContextV2(bytes);
+            if (v2) return v2;
             return undefined;
         }
 
-        // Fall back to V1: raw 20-byte address
-        const bytes = base64urlDecode(context);
         const hex = bytesToHex(bytes, { size: 20 }) as Address;
         if (isAddress(hex)) {
             return { r: hex };
@@ -91,20 +91,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 +174,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";