@frak-labs/core-sdk 0.2.1-beta.eb3cff34 → 1.0.0-beta.0cd79998

package/dist/trackEvent-DdykyX0U.js

@@ -0,0 +1 @@
+import{bytesToHex as e,hexToBytes as t,isAddress as n,keccak256 as r,toHex as i}from"viem";import{jsonDecode as a,jsonEncode as o}from"@frak-labs/frame-connector";const s=`frak-client-id`;function c(){return typeof crypto<`u`&&crypto.randomUUID?crypto.randomUUID():`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.replace(/[xy]/g,e=>{let t=Math.random()*16|0;return(e===`x`?t:t&3|8).toString(16)})}function l(){if(typeof window>`u`||!window.localStorage)return console.warn(`[Frak SDK] No Window / localStorage available to save the clientId`),c();let e=localStorage.getItem(s);return e||(e=c(),localStorage.setItem(s,e)),e}function u({domain:e}={}){return r(i((e??window.location.host).replace(`www.`,``)))}function d(e){return btoa(Array.from(e,e=>String.fromCharCode(e)).join(``)).replace(/\+/g,`-`).replace(/\//g,`_`).replace(/=+$/,``)}function f(e){let t=e.length%4;return Uint8Array.from(atob(e.replace(/-/g,`+`).replace(/_/g,`/`).padEnd(e.length+(t===0?0:4-t),`=`)),e=>e.charCodeAt(0))}function p(e){return d(o(e))}function m(e,t,n,r,i,a){let o=p(h({redirectUrl:t.redirectUrl,directExit:t.directExit,lang:t.lang,merchantId:n,metadata:{name:r,css:a,logoUrl:t.metadata?.logoUrl,homepageLink:t.metadata?.homepageLink},clientId:i})),s=new URL(e);return s.pathname=`/sso`,s.searchParams.set(`p`,o),s.toString()}function h(e){return{r:e.redirectUrl,cId:e.clientId,d:e.directExit,l:e.lang,m:e.merchantId,md:{n:e.metadata?.name,css:e.metadata?.css,l:e.metadata?.logoUrl,h:e.metadata?.homepageLink}}}const g=`menubar=no,status=no,scrollbars=no,fullscreen=no,width=500, height=800`,_=`frak-sso`;async function ee(e,t){let{metadata:n,customizations:r,walletUrl:i}=e.config;if(t.openInSameWindow??!!t.redirectUrl)return await e.request({method:`frak_openSso`,params:[t,n.name,r?.css]});let a=t.ssoPopupUrl??m(i??`https://wallet.frak.id`,t,u(),n.name,l(),r?.css),o=window.open(a,_,g);if(!o)throw Error(`Popup was blocked. Please allow popups for this site.`);return o.focus(),await e.request({method:`frak_openSso`,params:[t,n.name,r?.css]})??{}}const v=`https://backend.frak.id`;function te(e){return e.includes(`localhost:3000`)||e.includes(`localhost:3010`)}function y(e){return te(e)?`https://localhost:3030`:e.includes(`wallet-dev.frak.id`)||e.includes(`wallet.gcp-dev.frak.id`)?`https://backend.gcp-dev.frak.id`:v}function b(e){if(e)return y(e);if(typeof window<`u`){let e=window.FrakSetup?.client?.config?.walletUrl;if(e)return y(e)}return v}var x=class extends Map{maxSize;constructor(e){super(),this.maxSize=e}get(e){let t=super.get(e);return super.has(e)&&(super.delete(e),super.set(e,t)),t}set(e,t){if(super.has(e)&&super.delete(e),super.set(e,t),this.maxSize&&this.size>this.maxSize){let e=super.keys().next().value;e!==void 0&&super.delete(e)}return this}};const S=new x(1024),C=new x(1024),w=3e4,T=new x(1024);async function E(e,{cacheKey:t,cacheTime:n=w}){if(n>0){let e=C.get(t);if(e&&Date.now()-e.created<n)return e.data}let r=T.get(t);if(r&&Date.now()-r<1e3)throw Error(`Cache: ${t} recently failed, backing off`);let i=S.get(t);i||(i=e(),S.set(t,i));try{let e=await i;return C.set(t,{data:e,created:Date.now()}),T.delete(t),e}catch(e){throw T.set(t,Date.now()),e}finally{S.delete(t)}}function D(e){return{clear:()=>{S.delete(e),C.delete(e)},has:(t=w)=>{let n=C.get(e);return n?Date.now()-n.created<t:!1}}}function O(){S.clear(),C.clear(),T.clear()}function k(e){return a(f(e))}function A(e){return`r`in e&&!(`v`in e)}function j(e){return`v`in e&&e.v===2}const M=`fCtx`;function N(e){if(e)try{return j(e)?!e.c||!e.m||!e.t?void 0:p({v:2,c:e.c,m:e.m,t:e.t}):d(t(e.r))}catch(t){console.error(`Error compressing Frak context`,{e:t,context:e})}}function P(t){if(!(!t||t.length===0))try{let r=k(t);if(r&&typeof r==`object`&&r.v===2)return r.c&&r.m&&r.t?{v:2,c:r.c,m:r.m,t:r.t}:void 0;let i=e(f(t),{size:20});if(n(i))return{r:i}}catch(e){console.error(`Error decompressing Frak context`,{e,context:t})}}function ne({url:e}){if(!e)return null;let t=new URL(e).searchParams.get(M);return t?P(t):null}const F=`frak`;function I(e,t){let n=j(e);return{utm_source:t.utmSource??F,utm_medium:t.utmMedium??`referral`,utm_campaign:t.utmCampaign??(n?e.m:void 0),utm_content:t.utmContent,utm_term:t.utmTerm,via:t.via??F,ref:t.ref??(n?e.c:void 0)}}function L(e,t,n){let r=I(t,n??{});for(let[t,n]of Object.entries(r))n===void 0||n===``||e.searchParams.has(t)||e.searchParams.set(t,n)}function R({url:e,context:t,attribution:n}){if(!e)return null;let r=N(t);if(!r)return null;let i=new URL(e);return i.searchParams.set(M,r),L(i,t,n),i.toString()}function z(e){let t=new URL(e);return t.searchParams.delete(M),t.toString()}function B({url:e,context:t}){if(!window.location?.href||typeof window>`u`){console.error(`No window found, can't update context`);return}let n=e??window.location.href,r;r=t===null?z(n):R({url:n,context:t}),r&&window.history.replaceState(null,``,r.toString())}const re={compress:N,decompress:P,parse:ne,update:R,remove:z,replaceUrl:B},V=`__frakSdkConfig`,H=`frak-config-cache`,U=`frak-merchant-id`,W={key:H},G=typeof window<`u`;function K(){return{isResolved:!1,merchantId:``}}let q=null;function J(){if(!G)return null;try{let e=localStorage.getItem(W.key);if(!e)return null;let t=JSON.parse(e);return t.config?.isResolved?(q=t,t):null}catch{return null}}function Y(){return(q??J())?.config}function ie(){let e=q??J();return e?Date.now()-e.timestamp<3e4:!1}function ae(e){if(!(!G||!e.isResolved))try{let t={config:e,timestamp:Date.now()};localStorage.setItem(W.key,JSON.stringify(t)),q=t}catch{}}function oe(){if(G){q=null;try{localStorage.removeItem(W.key)}catch{}}}function se(){G&&(window[V]||(window[V]=Y()??K()))}se();function X(){return G?window[V]??K():K()}function Z(e){G&&window.dispatchEvent(new CustomEvent(`frak:config`,{detail:e}))}function Q(e){return e??(G?window.location.hostname:``)}async function ce(e,t,n){try{let r=b(t),i=n?`&lang=${encodeURIComponent(n)}`:``,a=await fetch(`${r}/user/merchant/resolve?domain=${encodeURIComponent(e)}${i}`);if(!a.ok){console.warn(`[Frak SDK] Merchant lookup failed for domain ${e}: ${a.status}`);return}let o=await a.json();if(G)try{sessionStorage.setItem(U,o.merchantId)}catch{}return o}catch(e){console.warn(`[Frak SDK] Failed to fetch merchant config:`,e);return}}const $={getConfig:X,get isResolved(){return X().isResolved},get isCacheFresh(){return ie()},setCacheScope(e,t){W.key=`${H}:${`${e}:${t??``}`}`,q=null},setConfig(e){if(G&&(window[V]=e),ae(e),Z(e),G&&e.merchantId)try{sessionStorage.setItem(U,e.merchantId)}catch{}},reset(){let e=Y()??K();G&&(window[V]=e),Z(e)},clearCache(){if(oe(),O(),G)try{sessionStorage.removeItem(U)}catch{}},resolve(e,t,n){let r=Q(e);return r?E(async()=>{let e=await ce(r,t,n);if(!e)throw Error(`Config resolution returned empty`);return e},{cacheKey:`sdkConfig:${r}:${n??``}`,cacheTime:1/0}).catch(()=>void 0):Promise.resolve(void 0)},getMerchantId(){let e=X();if(e.isResolved&&e.merchantId)return e.merchantId;if(G)try{return sessionStorage.getItem(U)??void 0}catch{}},async resolveMerchantId(e,t){return $.getMerchantId()||(await $.resolve(e,t))?.merchantId}};function le(e,t,n={}){if(!e){console.debug(`[Frak] No client provided, skipping event tracking`);return}try{e.openPanel?.track(t,n)}catch(e){console.debug(`[Frak] Failed to track event:`,t,e)}}export{d as _,j as a,D as c,ee as d,g as f,f as g,p as h,A as i,E as l,m,$ as n,k as o,_ as p,re as r,O as s,le as t,b as u,u as v,l as y};

package/package.json

@@ -11,7 +11,7 @@
       "url": "https://twitter.com/QNivelais"
     }
   ],
-  "version": "0.2.1-beta.eb3cff34",
+  "version": "1.0.0-beta.0cd79998",
   "description": "Core SDK of the Frak wallet, low level library to interact directly with the frak ecosystem.",
   "repository": {
     "url": "https://github.com/frak-id/wallet",
@@ -91,7 +91,7 @@
     "viem": "^2.x"
   },
   "dependencies": {
-    "@frak-labs/frame-connector": "0.2.0-beta.eb3cff34",
+    "@frak-labs/frame-connector": "0.2.0-beta.0cd79998",
     "@openpanel/web": "^1.2.0"
   },
   "devDependencies": {

package/src/clients/createIFrameFrakClient.ts

@@ -300,6 +300,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 +325,7 @@ async function postConnectionSetup({
                       translations: raw.translations,
                       placements: raw.placements,
                       components: raw.components,
+                      attribution: mergedAttribution,
                   }
                 : {
                       isResolved: true,
@@ -330,6 +337,7 @@ async function postConnectionSetup({
                       homepageLink: config.metadata.homepageLink,
                       lang: config.metadata.lang,
                       currency: config.metadata.currency,
+                      attribution: mergedAttribution,
                   }
         );
     };
@@ -351,8 +359,11 @@ async function postConnectionSetup({
                   css: resolved.css,
                   translations: resolved.translations,
                   placements: resolved.placements,
+                  attribution: resolved.attribution,
               }
-            : undefined;
+            : resolved.attribution
+              ? { attribution: resolved.attribution }
+              : undefined;
 
         rpcClient.sendLifecycle({
             clientLifecycle: "resolved-config",

package/src/index.ts

@@ -12,6 +12,8 @@ export { type LocalesKey, locales } from "./constants/locales";
 
 // Types
 export type {
+    AttributionDefaults,
+    AttributionParams,
     ClientLifecycleEvent,
     CompressedData,
     Currency,
@@ -115,6 +117,8 @@ export {
     isFrakDeepLink,
     isInAppBrowser,
     isIOS,
+    type MergeAttributionInput,
+    mergeAttribution,
     redirectToExternalBrowser,
     sdkConfigStore,
     toAndroidIntentUrl,

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

@@ -8,6 +8,42 @@ 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 */
     referrerWallet?: Address;

package/src/utils/FrakContext.test.ts

@@ -121,6 +121,150 @@ describe("FrakContextManager", () => {
                 expect(result).toContain("baz=qux");
                 expect(result).toContain("fCtx=");
             });
+
+            describe("update with attribution", () => {
+                const url = "https://example.com/product";
+
+                it("should not add attribution params when attribution is omitted", () => {
+                    const result = FrakContextManager.update({
+                        url,
+                        context: v2Context,
+                    });
+
+                    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=");
+                });
+
+                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";
@@ -91,20 +96,80 @@ 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 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.
+ */
+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.
  *
+ * 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.
+ *
  * @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.
  * @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 +178,7 @@ function update({
 
     const urlObj = new URL(url);
     urlObj.searchParams.set(contextKey, compressedContext);
+    applyAttributionParams(urlObj, context, attribution);
     return urlObj.toString();
 }
 

package/src/utils/index.ts

@@ -28,6 +28,10 @@ export {
     isIOS,
     redirectToExternalBrowser,
 } from "./inAppBrowser";
+export {
+    type MergeAttributionInput,
+    mergeAttribution,
+} from "./mergeAttribution";
 export { sdkConfigStore } from "./sdkConfigStore";
 export {
     type AppSpecificSsoMetadata,

package/src/utils/mergeAttribution.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "../../tests/vitest-fixtures";
+import { mergeAttribution } from "./mergeAttribution";
+
+describe("mergeAttribution", () => {
+    describe("explicit disable", () => {
+        it("returns undefined when perCall is null", () => {
+            expect(
+                mergeAttribution({
+                    perCall: null,
+                    defaults: { utmSource: "brand" },
+                    productUtmContent: "product-123",
+                })
+            ).toBeUndefined();
+        });
+    });
+
+    describe("no inputs", () => {
+        it("returns undefined when all layers are empty", () => {
+            expect(mergeAttribution({ perCall: undefined })).toBeUndefined();
+        });
+
+        it("returns undefined when perCall is undefined and defaults is empty object", () => {
+            expect(
+                mergeAttribution({ perCall: undefined, defaults: {} })
+            ).toBeUndefined();
+        });
+    });
+
+    describe("defaults only", () => {
+        it("returns defaults when perCall is undefined", () => {
+            expect(
+                mergeAttribution({
+                    perCall: undefined,
+                    defaults: {
+                        utmSource: "brand",
+                        utmMedium: "newsletter",
+                    },
+                })
+            ).toEqual({
+                utmSource: "brand",
+                utmMedium: "newsletter",
+            });
+        });
+    });
+
+    describe("perCall only", () => {
+        it("returns perCall when defaults is undefined", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmSource: "custom", utmContent: "hero" },
+                })
+            ).toEqual({
+                utmSource: "custom",
+                utmContent: "hero",
+            });
+        });
+
+        it("returns empty object when perCall is empty and no defaults", () => {
+            // perCall: {} signals \"apply attribution with hardcoded defaults downstream\"
+            expect(mergeAttribution({ perCall: {} })).toEqual({});
+        });
+    });
+
+    describe("per-field merge (perCall wins over defaults)", () => {
+        it("merges perCall over defaults field-by-field", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmMedium: "email" },
+                    defaults: {
+                        utmSource: "brand",
+                        utmMedium: "newsletter",
+                        utmCampaign: "spring",
+                    },
+                })
+            ).toEqual({
+                utmSource: "brand",
+                utmMedium: "email",
+                utmCampaign: "spring",
+            });
+        });
+
+        it("lets perCall override every default field", () => {
+            expect(
+                mergeAttribution({
+                    perCall: {
+                        utmSource: "pc-src",
+                        utmMedium: "pc-med",
+                        utmCampaign: "pc-camp",
+                        utmTerm: "pc-term",
+                        via: "pc-via",
+                        ref: "pc-ref",
+                    },
+                    defaults: {
+                        utmSource: "def-src",
+                        utmMedium: "def-med",
+                        utmCampaign: "def-camp",
+                        utmTerm: "def-term",
+                        via: "def-via",
+                        ref: "def-ref",
+                    },
+                })
+            ).toEqual({
+                utmSource: "pc-src",
+                utmMedium: "pc-med",
+                utmCampaign: "pc-camp",
+                utmTerm: "pc-term",
+                via: "pc-via",
+                ref: "pc-ref",
+            });
+        });
+    });
+
+    describe("utm_content handling", () => {
+        it("uses productUtmContent when provided", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmContent: "fallback" },
+                    productUtmContent: "product-42",
+                })
+            ).toEqual({ utmContent: "product-42" });
+        });
+
+        it("falls back to perCall.utmContent when productUtmContent is absent", () => {
+            expect(
+                mergeAttribution({
+                    perCall: { utmContent: "fallback" },
+                })
+            ).toEqual({ utmContent: "fallback" });
+        });
+
+        it("never inherits utm_content from defaults (shape excludes it)", () => {
+            // Even if a backend/SDK config erroneously contained utm_content
+            // at runtime, the merged result must not carry it.
+            expect(
+                mergeAttribution({
+                    perCall: {},
+                    // @ts-expect-error — defaults typing disallows utmContent,
+                    // but we simulate runtime data coming from a loose source.
+                    defaults: { utmContent: "should-not-leak" },
+                })
+            ).toEqual({});
+        });
+
+        it("adds attribution solely to carry a productUtmContent", () => {
+            expect(
+                mergeAttribution({
+                    perCall: undefined,
+                    productUtmContent: "product-7",
+                })
+            ).toEqual({ utmContent: "product-7" });
+        });
+    });
+});