@frak-labs/core-sdk 1.0.0-beta.7f085fb7 → 1.0.0-beta.a7645eaa

package/src/utils/FrakContext.test.ts

@@ -42,7 +42,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,6 +50,33 @@ describe("FrakContextManager", () => {
                 expect(result).toBeUndefined();
             });
 
+            it("should compress v2 context with wallet only (no clientId)", () => {
+                const v2WithWalletOnly: FrakContextV2 = {
+                    v: 2,
+                    m: "merchant-uuid-1234",
+                    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: "test-client-id-uuid",
+                    m: "merchant-uuid-1234",
+                    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 result = FrakContextManager.compress(
@@ -65,6 +92,40 @@ describe("FrakContextManager", () => {
                 );
                 expect(result).toBeUndefined();
             });
+
+            it("should reject v2 context with a malformed wallet address", () => {
+                const partial = {
+                    v: 2 as const,
+                    m: "merchant-uuid",
+                    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: "valid-client-id",
+                    m: "merchant-uuid",
+                    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: "valid-client-id",
+                    m: "merchant-uuid",
+                    t: 1709654400,
+                });
+            });
         });
 
         describe("decompress", () => {
@@ -74,6 +135,28 @@ describe("FrakContextManager", () => {
 
                 expect(decompressed).toEqual(v2Context);
             });
+
+            it("should drop malformed `w` field on decompress (defense against crafted URLs)", async () => {
+                // Manually compress a payload bypassing client-side validation
+                // by reaching into the underlying compressJsonToB64.
+                const { compressJsonToB64 } = await import(
+                    "./compression/compress"
+                );
+                const malformed = compressJsonToB64({
+                    v: 2,
+                    c: "valid-client-id",
+                    m: "merchant-uuid",
+                    t: 1709654400,
+                    w: "0xnot-a-real-address",
+                });
+                const result = FrakContextManager.decompress(malformed);
+                expect(result).toEqual({
+                    v: 2,
+                    c: "valid-client-id",
+                    m: "merchant-uuid",
+                    t: 1709654400,
+                });
+            });
         });
 
         describe("parse", () => {
@@ -121,6 +204,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);
+                });
+            });
         });
     });
 

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,17 @@ 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 (valid wallet) must be present.
+            if (!context.m || !context.t) return undefined;
+            const hasValidWallet = context.w && isAddress(context.w);
+            if (!context.c && !hasValidWallet) return undefined;
             return compressJsonToB64({
                 v: 2,
-                c: context.c,
                 m: context.m,
                 t: context.t,
+                ...(context.c ? { c: context.c } : {}),
+                ...(hasValidWallet ? { w: context.w } : {}),
             });
         }
 
@@ -56,10 +65,18 @@ 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;
+            // Validate `w` with isAddress() — protects self-referral checks and
+            // URL replacement from crafted payloads carrying a malformed wallet.
+            const hasValidWallet = json.w && isAddress(json.w);
+            if (!json.c && !hasValidWallet) return undefined;
+            return {
+                v: 2,
+                m: json.m,
+                t: json.t,
+                ...(json.c ? { c: json.c } : {}),
+                ...(hasValidWallet ? { w: json.w } : {}),
+            };
         }
 
         // Fall back to V1: raw 20-byte address
@@ -91,20 +108,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 +191,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);