@frak-labs/core-sdk 1.0.0 → 1.0.1

package/src/actions/referral/processReferral.test.ts

@@ -100,10 +100,9 @@ describe("processReferral", () => {
                 mockClient,
                 "user_referred_started",
                 {
-                    properties: {
-                        referrerClientId: "referrer-client-id",
-                        walletStatus: "connected",
-                    },
+                    referrerClientId: "referrer-client-id",
+                    referrerWallet: undefined,
+                    walletStatus: "connected",
                 }
             );
 
@@ -111,6 +110,7 @@ describe("processReferral", () => {
                 type: "arrival",
                 referrerClientId: "referrer-client-id",
                 referrerMerchantId: "merchant-uuid",
+                referrerWallet: undefined,
                 referralTimestamp: 1709654400,
                 landingUrl: "https://example.com/test",
             });
@@ -135,6 +135,73 @@ describe("processReferral", () => {
             expect(result).toBe("self-referral");
             vi.mocked(utils.getClientId).mockReturnValue("test-client-id");
         });
+
+        it("should successfully process v2 referral with wallet only (no clientId)", async () => {
+            await import("../../utils");
+            const { sendInteraction } = await import("../sendInteraction");
+
+            const referrerWallet =
+                "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" as Address;
+            const v2WithWalletOnly: FrakContextV2 = {
+                v: 2,
+                m: "merchant-uuid",
+                t: 1709654400,
+                w: referrerWallet,
+            };
+
+            const result = await processReferral(mockClient, {
+                walletStatus: mockWalletStatus,
+                frakContext: v2WithWalletOnly,
+            });
+
+            expect(result).toBe("success");
+            expect(sendInteraction).toHaveBeenCalledWith(mockClient, {
+                type: "arrival",
+                referrerClientId: undefined,
+                referrerMerchantId: "merchant-uuid",
+                referrerWallet,
+                referralTimestamp: 1709654400,
+                landingUrl: "https://example.com/test",
+            });
+        });
+
+        it("should return 'self-referral' when v2 wallet matches current wallet", async () => {
+            const v2SelfReferralByWallet: FrakContextV2 = {
+                v: 2,
+                m: "merchant-uuid",
+                t: 1709654400,
+                w: mockAddress,
+            };
+
+            const result = await processReferral(mockClient, {
+                walletStatus: mockWalletStatus,
+                frakContext: v2SelfReferralByWallet,
+            });
+
+            expect(result).toBe("self-referral");
+        });
+
+        it("should prefer wallet over clientId for self-referral when both are present", async () => {
+            const utils = await import("../../utils");
+            // clientId does NOT match current user, but wallet does → still self-referral
+            vi.mocked(utils.getClientId).mockReturnValue("some-other-client");
+
+            const v2Hybrid: FrakContextV2 = {
+                v: 2,
+                c: "referrer-client-id",
+                m: "merchant-uuid",
+                t: 1709654400,
+                w: mockAddress,
+            };
+
+            const result = await processReferral(mockClient, {
+                walletStatus: mockWalletStatus,
+                frakContext: v2Hybrid,
+            });
+
+            expect(result).toBe("self-referral");
+            vi.mocked(utils.getClientId).mockReturnValue("test-client-id");
+        });
     });
 
     describe("V1 context (backward compat)", () => {
@@ -156,10 +223,8 @@ describe("processReferral", () => {
                 mockClient,
                 "user_referred_started",
                 {
-                    properties: {
-                        referrer: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
-                        walletStatus: "connected",
-                    },
+                    referrer: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+                    walletStatus: "connected",
                 }
             );
         });
@@ -202,6 +267,7 @@ describe("processReferral", () => {
                 v: 2,
                 c: "test-client-id",
                 m: "merchant-uuid",
+                w: mockAddress,
             }),
         });
     });
@@ -229,4 +295,59 @@ describe("processReferral", () => {
             context: null,
         });
     });
+
+    it("should emit wallet in replacement context when alwaysAppendUrl is true and user is connected", async () => {
+        const utils = await import("../../utils");
+        vi.mocked(utils.getClientId).mockReturnValue(null as never);
+
+        const v2Context: FrakContextV2 = {
+            v: 2,
+            c: "referrer-client-id",
+            m: "merchant-uuid",
+            t: 1709654400,
+        };
+
+        await processReferral(mockClient, {
+            walletStatus: mockWalletStatus,
+            frakContext: v2Context,
+            options: { alwaysAppendUrl: true },
+        });
+
+        // clientId is null, but wallet is available — should still emit {w, m}
+        expect(utils.FrakContextManager.replaceUrl).toHaveBeenCalledWith({
+            url: window.location.href,
+            context: expect.objectContaining({
+                v: 2,
+                m: "merchant-uuid",
+                w: mockAddress,
+            }),
+        });
+
+        vi.mocked(utils.getClientId).mockReturnValue("test-client-id");
+    });
+
+    it("should return null replacement context when both clientId and wallet are missing", async () => {
+        const utils = await import("../../utils");
+        vi.mocked(utils.getClientId).mockReturnValue(null as never);
+
+        const v2Context: FrakContextV2 = {
+            v: 2,
+            c: "referrer-client-id",
+            m: "merchant-uuid",
+            t: 1709654400,
+        };
+
+        await processReferral(mockClient, {
+            walletStatus: { key: "not-connected" as const },
+            frakContext: v2Context,
+            options: { alwaysAppendUrl: true },
+        });
+
+        expect(utils.FrakContextManager.replaceUrl).toHaveBeenCalledWith({
+            url: window.location.href,
+            context: null,
+        });
+
+        vi.mocked(utils.getClientId).mockReturnValue("test-client-id");
+    });
 });

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",
@@ -89,16 +87,23 @@ function trackArrivalIfValid(
 
 /**
  * Build a V2 context representing the current user for URL replacement.
- * @returns A V2 context, or null if clientId or merchantId is unavailable
+ *
+ * Emits both `c` (anonymous clientId) and `w` (wallet) when available — wallet
+ * is the preferred identity signal and takes attribution precedence downstream.
+ * Returns null when neither identifier is available.
  */
-function buildCurrentUserContext(merchantId: string): FrakContextV2 | null {
+function buildCurrentUserContext(
+    merchantId: string,
+    wallet?: WalletStatusReturnType["wallet"]
+): FrakContextV2 | null {
     const clientId = getClientId();
-    if (!clientId) return null;
+    if (!clientId && !wallet) return null;
     return {
         v: 2,
-        c: clientId,
         m: merchantId,
         t: Math.floor(Date.now() / 1000),
+        ...(clientId ? { c: clientId } : {}),
+        ...(wallet ? { w: wallet } : {}),
     };
 }
 
@@ -111,7 +116,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);
@@ -168,7 +180,7 @@ export function processReferral(
 
     const replaceContext =
         options?.alwaysAppendUrl && contextMerchantId
-            ? buildCurrentUserContext(contextMerchantId)
+            ? buildCurrentUserContext(contextMerchantId, walletStatus?.wallet)
             : null;
 
     FrakContextManager.replaceUrl({
@@ -177,9 +189,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;
 
@@ -300,6 +339,12 @@ async function postConnectionSetup({
         const allowedDomains = merchantConfig?.allowedDomains ?? [];
         const raw = merchantConfig?.sdkConfig;
 
+        // Per-field merge: backend wins over SDK static config.
+        const mergedAttribution =
+            raw?.attribution || config.attribution
+                ? { ...config.attribution, ...raw?.attribution }
+                : undefined;
+
         sdkConfigStore.setConfig(
             raw
                 ? {
@@ -319,6 +364,7 @@ async function postConnectionSetup({
                       translations: raw.translations,
                       placements: raw.placements,
                       components: raw.components,
+                      attribution: mergedAttribution,
                   }
                 : {
                       isResolved: true,
@@ -330,11 +376,16 @@ async function postConnectionSetup({
                       homepageLink: config.metadata.homepageLink,
                       lang: config.metadata.lang,
                       currency: config.metadata.currency,
+                      attribution: mergedAttribution,
                   }
         );
     };
 
-    // 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;
@@ -351,8 +402,22 @@ async function postConnectionSetup({
                   css: resolved.css,
                   translations: resolved.translations,
                   placements: resolved.placements,
+                  attribution: resolved.attribution,
               }
-            : undefined;
+            : resolved.attribution
+              ? { 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",
@@ -361,6 +426,7 @@ async function postConnectionSetup({
                 domain: resolved.domain ?? "",
                 allowedDomains: resolved.allowedDomains ?? [],
                 sourceUrl: window.location.href,
+                ...(sdkAnonymousId && { sdkAnonymousId }),
                 ...(token && { pendingMergeToken: token }),
                 ...(sdkConfig && { sdkConfig }),
             },
@@ -412,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

@@ -12,6 +12,8 @@ export { type LocalesKey, locales } from "./constants/locales";
 
 // Types
 export type {
+    AttributionDefaults,
+    AttributionParams,
     ClientLifecycleEvent,
     CompressedData,
     Currency,
@@ -100,7 +102,6 @@ export {
     type DeepLinkFallbackOptions,
     decompressJsonFromB64,
     FrakContextManager,
-    type FrakEvent,
     type FullSsoParams,
     findIframeInOpener,
     formatAmount,
@@ -115,6 +116,8 @@ export {
     isFrakDeepLink,
     isInAppBrowser,
     isIOS,
+    type MergeAttributionInput,
+    mergeAttribution,
     redirectToExternalBrowser,
     sdkConfigStore,
     toAndroidIntentUrl,
@@ -122,4 +125,8 @@ export {
     triggerDeepLinkWithFallback,
     withCache,
 } from "./utils";
+export type {
+    SdkEventMap,
+    SdkHandshakeFailureReason,
+} from "./utils/analytics";
 export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/types/config.ts

@@ -1,3 +1,5 @@
+import type { AttributionDefaults } from "./tracking";
+
 /**
  * All the currencies available
  * @category Config
@@ -78,6 +80,13 @@ export type FrakWalletSdkConfig = {
      * @defaultValue true
      */
     waitForBackendConfig?: boolean;
+    /**
+     * Default attribution params (UTM / via / ref) appended to outbound
+     * sharing URLs. Per-call `displaySharingPage` overrides win, then backend
+     * config, then this SDK-level default. `utm_content` is intentionally
+     * excluded — it is per-content/per-product, never a merchant-wide default.
+     */
+    attribution?: AttributionDefaults;
 };
 
 /**

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/index.ts

@@ -80,6 +80,8 @@ export type { UserReferralStatusType } from "./rpc/userReferralStatus";
 export type { WalletStatusReturnType } from "./rpc/walletStatus";
 // Tracking
 export type {
+    AttributionDefaults,
+    AttributionParams,
     TrackArrivalParams,
     TrackArrivalResult,
     UtmParams,

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/types/resolvedConfig.ts

@@ -1,4 +1,5 @@
 import type { Currency, Language } from "./config";
+import type { AttributionDefaults } from "./tracking";
 
 /**
  * Response from the merchant resolve endpoint
@@ -80,6 +81,12 @@ export type ResolvedSdkConfig = {
     placements?: Record<string, ResolvedPlacement>;
     /** Global component defaults (used when no placement override exists) */
     components?: ResolvedPlacement["components"];
+    /**
+     * Default attribution params applied when building outbound sharing URLs.
+     * Per-call overrides win over these backend defaults; `utm_content` is
+     * intentionally excluded (per-content/per-product, never a merchant default).
+     */
+    attribution?: AttributionDefaults;
 };
 
 /**
@@ -125,4 +132,7 @@ export type SdkResolvedConfig = {
 
     /** Global component defaults (fallback for placement-level overrides) */
     components?: ResolvedPlacement["components"];
+
+    /** Merged attribution defaults: backend > SDK static config */
+    attribution?: AttributionDefaults;
 };

package/src/types/rpc/displaySharingPage.ts

@@ -1,5 +1,6 @@
 import type { InteractionTypeKey } from "../../constants/interactionTypes";
 import type { I18nConfig } from "../config";
+import type { AttributionParams } from "../tracking";
 
 /**
  * Product information to display on the sharing page
@@ -19,6 +20,11 @@ export type SharingPageProduct = {
      * When provided and the product is selected, this link is used instead of the default sharing link
      */
     link?: string;
+    /**
+     * Optional `utm_content` value to apply when this product is selected.
+     * Falls back to the page-level `attribution.utmContent` when omitted.
+     */
+    utmContent?: string;
 };
 
 /**
@@ -37,6 +43,18 @@ export type DisplaySharingPageParamsType = {
      * If not provided, the sharing link will be generated from the current page URL + merchant context
      */
     link?: string;
+    /**
+     * Optional attribution overrides for the outbound sharing URL.
+     *
+     * When provided (even as an empty object), Frak adds standard affiliation
+     * params (`utm_source=frak`, `utm_medium=referral`, `utm_campaign=<merchantId>`,
+     * `ref=<clientId>`, `via=frak`) alongside `fCtx`. Existing UTMs on the base
+     * URL are preserved (gap-fill). Set this to `null` to disable attribution
+     * params entirely (only `fCtx` is added).
+     *
+     * @default {} — defaults applied
+     */
+    attribution?: AttributionParams | null;
     /**
      * Optional metadata overrides for the sharing page
      */

package/src/types/rpc/interaction.ts

@@ -11,7 +11,7 @@ import type { Address } from "viem";
 export type SendInteractionParamsType =
     | {
           type: "arrival";
-          /** @deprecated V1 legacy — use referrerClientId for v2 */
+          /** Sharer wallet address. Accepted in both V1 (legacy, wallet-only) and V2 (authenticated sharer) contexts. */
           referrerWallet?: Address;
           referrerClientId?: string;
           referrerMerchantId?: string;

package/src/types/tracking.ts

@@ -8,8 +8,44 @@ export type UtmParams = {
     content?: string;
 };
 
+/**
+ * Attribution parameters appended to outbound sharing URLs.
+ *
+ * Defaults are derived from the V2 Frak context when available:
+ * - `utmSource`: `"frak"`
+ * - `utmMedium`: `"referral"`
+ * - `utmCampaign`: merchantId (`context.m`)
+ * - `via`: `"frak"`
+ * - `ref`: clientId (`context.c`)
+ *
+ * Fields explicitly set here override the defaults. Existing params on the
+ * base URL are preserved (gap-fill policy) to respect merchant-provided UTMs.
+ */
+export type AttributionParams = {
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmContent?: string;
+    utmTerm?: string;
+    via?: string;
+    ref?: string;
+};
+
+/**
+ * Merchant-level attribution defaults.
+ *
+ * Same shape as {@link AttributionParams} minus `utmContent`, because
+ * `utm_content` describes the specific content/creative being shared and is
+ * inherently per-call or per-product (never a merchant-wide default).
+ *
+ * Used as the shape for both:
+ * - `FrakWalletSdkConfig.attribution` (SDK-side compile-time defaults)
+ * - Backend merchant-config attribution (dashboard-driven defaults)
+ */
+export type AttributionDefaults = Omit<AttributionParams, "utmContent">;
+
 export type TrackArrivalParams = {
-    /** @deprecated V1 legacy — use referrerClientId for v2 contexts */
+    /** Sharer wallet address. Accepted in both V1 (legacy) and V2 (authenticated sharer) contexts. */
     referrerWallet?: Address;
     referrerClientId?: string;
     referrerMerchantId?: string;