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

package/src/actions/referral/processReferral.ts

@@ -54,15 +54,15 @@ function trackArrivalIfValid(
 
     if (isV2Context(frakContext)) {
         trackEvent(client, "user_referred_started", {
-            properties: {
-                referrerClientId: frakContext.c,
-                walletStatus: walletStatus?.key,
-            },
+            referrerClientId: frakContext.c,
+            referrerWallet: frakContext.w,
+            walletStatus: walletStatus?.key,
         });
         sendInteraction(client, {
             type: "arrival",
             referrerClientId: frakContext.c,
             referrerMerchantId: frakContext.m,
+            referrerWallet: frakContext.w,
             referralTimestamp: frakContext.t,
             landingUrl,
         });
@@ -71,10 +71,8 @@ function trackArrivalIfValid(
 
     if (isV1Context(frakContext)) {
         trackEvent(client, "user_referred_started", {
-            properties: {
-                referrer: frakContext.r,
-                walletStatus: walletStatus?.key,
-            },
+            referrer: frakContext.r,
+            walletStatus: walletStatus?.key,
         });
         sendInteraction(client, {
             type: "arrival",
@@ -111,7 +109,14 @@ function isSelfReferral(
     walletStatus?: WalletStatusReturnType
 ): boolean {
     if (isV2Context(frakContext)) {
-        return getClientId() === frakContext.c;
+        // Wallet match takes precedence — it's the strongest signal we have.
+        if (frakContext.w && walletStatus?.wallet) {
+            return isAddressEqual(frakContext.w, walletStatus.wallet);
+        }
+        if (frakContext.c) {
+            return getClientId() === frakContext.c;
+        }
+        return false;
     }
     if (isV1Context(frakContext) && walletStatus?.wallet) {
         return isAddressEqual(frakContext.r, walletStatus.wallet);
@@ -177,9 +182,7 @@ export function processReferral(
     });
 
     trackEvent(client, "user_referred_completed", {
-        properties: {
-            status: "success",
-        },
+        status: "success",
     });
 
     return "success";

package/src/clients/createIFrameFrakClient.ts

@@ -80,6 +80,10 @@ export function createIFrameFrakClient({
     // Resolved after first resolved-config is sent to iframe (prevents RPC before context exists)
     const contextSent = new Deferred<void>();
 
+    // Handshake timing: measured from client creation until the iframe
+    // lifecycle manager resolves the `isConnected` promise.
+    const handshakeStartedAt = Date.now();
+
     // Create our debug info gatherer
     const debugInfo = new DebugInfoGatherer(config, iframe);
 
@@ -180,6 +184,38 @@ export function createIFrameFrakClient({
             userAnonymousClientId: getClientId(),
         });
         openPanel.init();
+        openPanel.track("sdk_initialized", {
+            sdkVersion: process.env.SDK_VERSION,
+        });
+
+        // Race the connection against the heartbeat timeout so we can
+        // distinguish "connected" from "timeout" cleanly without touching
+        // the heartbeat plumbing. 30s matches `HEARTBEAT_TIMEOUT`.
+        let settled = false;
+        const timeoutHandle = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            openPanel?.track("sdk_iframe_handshake_failed", {
+                reason: "timeout",
+            });
+        }, 30_000);
+        lifecycleManager.isConnected
+            .then(() => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeoutHandle);
+                openPanel?.track("sdk_iframe_connected", {
+                    handshake_duration_ms: Date.now() - handshakeStartedAt,
+                });
+            })
+            .catch(() => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(timeoutHandle);
+                openPanel?.track("sdk_iframe_handshake_failed", {
+                    reason: "unknown",
+                });
+            });
     }
 
     // Perform the post connection setup
@@ -189,6 +225,7 @@ export function createIFrameFrakClient({
         lifecycleManager,
         configPromise,
         contextSent,
+        openPanel,
     })
         .then(() => debugInfo.updateSetupStatus(true))
         .catch((err) => {
@@ -273,12 +310,14 @@ async function postConnectionSetup({
     lifecycleManager,
     configPromise,
     contextSent,
+    openPanel,
 }: {
     config: FrakWalletSdkConfig;
     rpcClient: SdkRpcClient;
     lifecycleManager: IframeLifecycleManager;
     configPromise: Promise<MerchantConfigResult> | undefined;
     contextSent: Deferred<void>;
+    openPanel: OpenPanel | undefined;
 }): Promise<void> {
     await lifecycleManager.isConnected;
 
@@ -342,7 +381,11 @@ async function postConnectionSetup({
         );
     };
 
-    // Send the resolved-config lifecycle event to the iframe
+    // Send the resolved-config lifecycle event to the iframe.
+    // This is where we also update SDK-side OpenPanel global props with
+    // `merchantId` + `domain` (first time they are known) so every
+    // subsequent SDK event is merchant-attributed. We pass
+    // `sdkAnonymousId` through so the listener can join SDK funnels.
     let mergeTokenConsumed = false;
     const sendLifecycleConfig = (resolved: SdkResolvedConfig) => {
         const token = mergeTokenConsumed ? undefined : pendingMergeToken;
@@ -365,6 +408,17 @@ async function postConnectionSetup({
               ? { attribution: resolved.attribution }
               : undefined;
 
+        const sdkAnonymousId = getClientId();
+
+        if (openPanel) {
+            const current = openPanel.global ?? {};
+            openPanel.setGlobalProperties({
+                ...current,
+                merchantId: resolved.merchantId,
+                domain: resolved.domain ?? "",
+            });
+        }
+
         rpcClient.sendLifecycle({
             clientLifecycle: "resolved-config",
             data: {
@@ -372,6 +426,7 @@ async function postConnectionSetup({
                 domain: resolved.domain ?? "",
                 allowedDomains: resolved.allowedDomains ?? [],
                 sourceUrl: window.location.href,
+                ...(sdkAnonymousId && { sdkAnonymousId }),
                 ...(token && { pendingMergeToken: token }),
                 ...(sdkConfig && { sdkConfig }),
             },
@@ -423,5 +478,20 @@ async function postConnectionSetup({
         });
     }
 
-    await Promise.allSettled([pushCss(), pushI18n(), pushBackup()]);
+    // Inspect each setup result — a failed CSS/i18n/backup push leaves the
+    // partner UI in a broken-but-connected state (iframe reports
+    // `sdk_iframe_connected`, user sees no modal styles / wrong locale).
+    // Surface it as a distinct handshake reason so dashboards can
+    // distinguish timeout vs. asset-push failures.
+    const results = await Promise.allSettled([
+        pushCss(),
+        pushI18n(),
+        pushBackup(),
+    ]);
+    const hasFailedAssetPush = results.some((r) => r.status === "rejected");
+    if (hasFailedAssetPush) {
+        openPanel?.track("sdk_iframe_handshake_failed", {
+            reason: "asset_push",
+        });
+    }
 }

package/src/index.ts

@@ -102,7 +102,6 @@ export {
     type DeepLinkFallbackOptions,
     decompressJsonFromB64,
     FrakContextManager,
-    type FrakEvent,
     type FullSsoParams,
     findIframeInOpener,
     formatAmount,
@@ -126,4 +125,8 @@ export {
     triggerDeepLinkWithFallback,
     withCache,
 } from "./utils";
+export type {
+    SdkEventMap,
+    SdkHandshakeFailureReason,
+} from "./utils/analytics";
 export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/types/context.ts

@@ -11,19 +11,31 @@ export type FrakContextV1 = {
 };
 
 /**
- * V2 Frak Context — anonymous-first referral context.
- * Contains the sharer's clientId, merchantId, and link creation timestamp.
+ * V2 Frak Context — anonymous-first referral context with optional wallet.
+ *
+ * Carries merchant context (`m`) and creation timestamp (`t`) unconditionally.
+ * Identifies the sharer via either the anonymous clientId (`c`) or, when the
+ * sharer is authenticated, the stronger wallet identifier (`w`). A valid V2
+ * context MUST contain at least one of `c` or `w`; both may be present when
+ * a logged-in user shares a link (best attribution signal).
+ *
+ * `w` takes precedence as the source of truth because the wallet is bound to
+ * the user's WebAuthn credential, survives localStorage clears, and is global
+ * across merchants — unlike `c`, which is a per-browser UUID.
+ *
  * @ignore
  */
 export type FrakContextV2 = {
     /** Version discriminator */
     v: 2;
-    /** Sharer's anonymous clientId (UUID from localStorage) */
-    c: string;
     /** Merchant ID (UUID) */
     m: string;
     /** Link creation timestamp (epoch seconds) */
     t: number;
+    /** Sharer's anonymous clientId (UUID from localStorage). Optional when `w` is provided. */
+    c?: string;
+    /** Sharer's wallet address. Preferred source of truth when the sharer is authenticated. Optional when `c` is provided. */
+    w?: Address;
 };
 
 /**

package/src/types/lifecycle/client.ts

@@ -59,6 +59,13 @@ type ResolvedConfigEvent = {
          * When present, listener should execute identity merge in background.
          */
         pendingMergeToken?: string;
+        /**
+         * Persistent per-origin anonymous id generated on the partner site
+         * (SDK-side localStorage). Propagated here so the listener can
+         * set it as an OpenPanel global property and stitch SDK events
+         * with listener events in the same funnel.
+         */
+        sdkAnonymousId?: string;
         sdkConfig?: ResolvedSdkConfig;
     };
 };

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(
@@ -125,7 +152,7 @@ describe("FrakContextManager", () => {
             describe("update with attribution", () => {
                 const url = "https://example.com/product";
 
-                it("should not add attribution params when attribution is omitted", () => {
+                it("should apply default attribution params when attribution is omitted", () => {
                     const result = FrakContextManager.update({
                         url,
                         context: v2Context,
@@ -133,11 +160,18 @@ describe("FrakContextManager", () => {
 
                     expect(result).toBeDefined();
                     expect(result).toContain("fCtx=");
-                    expect(result).not.toContain("utm_source");
-                    expect(result).not.toContain("utm_medium");
-                    expect(result).not.toContain("utm_campaign");
-                    expect(result).not.toContain("ref=");
-                    expect(result).not.toContain("via=");
+                    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", () => {

package/src/utils/FrakContext.ts

@@ -28,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 } : {}),
             });
         }
 
@@ -61,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
@@ -109,9 +117,10 @@ const DEFAULT_ATTRIBUTION_SOURCE = "frak";
 /**
  * Resolve attribution defaults from the provided context.
  *
- * V2 contexts expose the merchantId (`m`) and clientId (`c`), which feed
- * `utm_campaign` and `ref` respectively. V1 contexts have no equivalent, so
- * only the static defaults (`utm_source`, `utm_medium`, `via`) apply.
+ * 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,
@@ -151,15 +160,15 @@ function applyAttributionParams(
 /**
  * Add or replace the `fCtx` query parameter in a URL with the given context.
  *
- * When `attribution` is provided (even as an empty object), standard affiliation
- * params (`utm_source`, `utm_medium`, `utm_campaign`, `ref`, `via`, ...) are
- * also appended using gap-fill semantics: pre-existing params on the URL are
- * preserved, and defaults are derived from the context when applicable.
+ * 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. Omit to skip UTM/ref params.
+ * @param args.attribution - Optional attribution overrides. Defaults are applied even when omitted.
  * @returns The updated URL string, or null on failure
  */
 function update({

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);