@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.61e6fb99

package/dist/src-BxRYON49.js

@@ -0,0 +1,13 @@
+import{o as e,t,y as n}from"./sdkConfigStore-M37skmM8.js";import{Deferred as r,FrakRpcError as i,RpcErrorCodes as a,createRpcClient as o}from"@frak-labs/frame-connector";import{OpenPanel as s}from"@openpanel/web";const c=`nexus-wallet-backup`,l=`frakwallet://`;function u(){let e=navigator.userAgent;return/Android/i.test(e)&&/Chrome\/\d+/i.test(e)}function d(e){return`intent://${e.slice(13)}#Intent;scheme=frakwallet;end`}function f(e,t){let n=t?.timeout??2500,r=!1,i=()=>{document.hidden&&(r=!0)};document.addEventListener(`visibilitychange`,i);let a=u()&&p(e)?d(e):e;window.location.href=a,setTimeout(()=>{document.removeEventListener(`visibilitychange`,i),r||t?.onFallback?.()},n)}function p(e){return e.startsWith(l)}const m={eur:`fr-FR`,usd:`en-US`,gbp:`en-GB`};function h(e){return e&&e in m?e:`eur`}function g(e){return e?m[e]??m.eur:m.eur}function _(e,t){let n=g(t),r=h(t);return e.toLocaleString(n,{style:`currency`,currency:r,minimumFractionDigits:0,maximumFractionDigits:2})}function v(e){return e?`${e}Amount`:`eurAmount`}const y={id:`frak-wallet`,name:`frak-wallet`,title:`Frak Wallet`,allow:`publickey-credentials-get *; clipboard-write; web-share *`,style:{width:`0`,height:`0`,border:`0`,position:`absolute`,zIndex:2000001,top:`-1000px`,left:`-1000px`,colorScheme:`auto`}};function b({walletBaseUrl:e,config:t}){let r=document.querySelector(`#frak-wallet`);r&&r.remove();let i=document.createElement(`iframe`);i.id=y.id,i.name=y.name,i.allow=y.allow,i.style.zIndex=y.style.zIndex.toString(),x({iframe:i,isVisible:!1});let a=t?.walletUrl??e??`https://wallet.frak.id`,o=n();return i.src=`${a}/listener?clientId=${encodeURIComponent(o)}`,new Promise(e=>{i.addEventListener(`load`,()=>e(i)),document.body.appendChild(i)})}function x({iframe:e,isVisible:t}){if(!t){e.style.width=`0`,e.style.height=`0`,e.style.border=`0`,e.style.position=`fixed`,e.style.top=`-1000px`,e.style.left=`-1000px`;return}e.style.position=`fixed`,e.style.top=`0`,e.style.left=`0`,e.style.width=`100%`,e.style.height=`100%`,e.style.pointerEvents=`auto`}function S(e=`/listener`){if(!window.opener)return null;let t=t=>{try{return t.location.origin===window.location.origin&&t.location.pathname===e}catch{return!1}};if(t(window.opener))return window.opener;try{let e=window.opener.frames;for(let n=0;n<e.length;n++)if(t(e[n]))return e[n];return null}catch(t){return console.error(`[findIframeInOpener] Error finding iframe with pathname ${e}:`,t),null}}function C(){if(typeof navigator>`u`)return!1;let e=navigator.userAgent;return!!(/iPhone|iPad|iPod/i.test(e)||/Macintosh/i.test(e)&&navigator.maxTouchPoints>1)}const w=C();function T(){if(typeof navigator>`u`)return!1;let e=navigator.userAgent.toLowerCase();return e.includes(`instagram`)||e.includes(`fban`)||e.includes(`fbav`)||e.includes(`facebook`)}const E=T();function D(e){w&&e.startsWith(`https://`)?window.location.href=`x-safari-https://${e.slice(8)}`:w&&e.startsWith(`http://`)?window.location.href=`x-safari-http://${e.slice(7)}`:window.location.href=`https://backend.frak.id/common/social?u=${encodeURIComponent(e)}`}function O({perCall:e,defaults:t,productUtmContent:n}){if(e===null)return;let r=e!==void 0,i=t!==void 0&&Object.keys(t).length>0;if(!r&&!i&&!(n!==void 0&&n!==``))return;let a={...t,...e??{}},o=n??e?.utmContent;return o!==void 0&&o!==``?a.utmContent=o:delete a.utmContent,a}function k(e,t){if(typeof window>`u`)return;let n=new URL(window.location.href),r=n.searchParams.get(`sso`);r&&(t.then(()=>{e.sendLifecycle({clientLifecycle:`sso-redirect-complete`,data:{compressed:r}}),console.log(`[SSO URL Listener] Forwarded compressed SSO data to iframe`)}).catch(e=>{console.error(`[SSO URL Listener] Failed to forward SSO data:`,e)}),n.searchParams.delete(`sso`),window.history.replaceState({},``,n.toString()),console.log(`[SSO URL Listener] SSO parameter detected and URL cleaned`))}var A=class e{config;iframe;isSetupDone=!1;lastResponse=null;lastRequest=null;constructor(e,t){this.config=e,this.iframe=t,this.lastRequest=null,this.lastResponse=null}setLastResponse(e,t){this.lastResponse={message:e,response:t,timestamp:Date.now()}}setLastRequest(e){this.lastRequest={event:e,timestamp:Date.now()}}updateSetupStatus(e){this.isSetupDone=e}base64Encode(e){try{return btoa(JSON.stringify(e))}catch(e){return console.warn(`Failed to encode debug data`,e),btoa(`Failed to encode data`)}}getIframeStatus(){return this.iframe?{loading:this.iframe.hasAttribute(`loading`),url:this.iframe.src,readyState:this.iframe.contentDocument?.readyState?+(this.iframe.contentDocument.readyState===`complete`):-1,contentWindow:!!this.iframe.contentWindow,isConnected:this.iframe.isConnected}:null}getNavigatorInfo(){return navigator?{userAgent:navigator.userAgent,language:navigator.language,onLine:navigator.onLine,screenWidth:window.screen.width,screenHeight:window.screen.height,pixelRatio:window.devicePixelRatio}:null}gatherDebugInfo(e){let t=this.getIframeStatus(),n=this.getNavigatorInfo(),r=`Unknown`;return e instanceof i?r=`FrakRpcError: ${e.code} '${e.message}'`:e instanceof Error?r=e.message:typeof e==`string`&&(r=e),{timestamp:new Date().toISOString(),encodedUrl:btoa(window.location.href),encodedConfig:this.config?this.base64Encode(this.config):`no-config`,navigatorInfo:n?this.base64Encode(n):`no-navigator`,iframeStatus:t?this.base64Encode(t):`not-iframe`,lastRequest:this.lastRequest?this.base64Encode(this.lastRequest):`No Frak request logged`,lastResponse:this.lastResponse?this.base64Encode(this.lastResponse):`No Frak response logged`,clientStatus:this.isSetupDone?`setup`:`not-setup`,error:r}}static empty(){return new e}formatDebugInfo(e){let t=this.gatherDebugInfo(e);return`
+  Debug Information:
+  -----------------
+  Timestamp: ${t.timestamp}
+  URL: ${t.encodedUrl}
+  Config: ${t.encodedConfig}
+  Navigator Info: ${t.navigatorInfo}
+  IFrame Status: ${t.iframeStatus}
+  Last Request: ${t.lastRequest}
+  Last Response: ${t.lastResponse}
+  Client Status: ${t.clientStatus}
+  Error: ${t.error}
+  `.trim()}};const j=(()=>{if(typeof navigator>`u`)return!1;let e=navigator.userAgent;if(!(/iPhone|iPad|iPod/i.test(e)||/Macintosh/i.test(e)&&navigator.maxTouchPoints>1))return!1;let t=e.toLowerCase();return t.includes(`instagram`)||t.includes(`fban`)||t.includes(`fbav`)||t.includes(`facebook`)})();function M(e){e?localStorage.setItem(c,e):localStorage.removeItem(c)}function N(e,t){try{let n=new URL(e);if(!n.searchParams.has(`u`))return e;let r=I(window.location.href,t);return n.searchParams.delete(`u`),n.searchParams.append(`u`,r),n.toString()}catch{return e}}function P(e){let t=new URL(window.location.href);e&&t.searchParams.set(`fmt`,e);let n=t.protocol===`http:`?`x-safari-http`:`x-safari-https`;window.location.href=`${n}://${t.host}${t.pathname}${t.search}${t.hash}`}function F(e){return e.includes(`/common/social`)}function I(e,t){if(!t)return e;try{let n=new URL(e);return n.searchParams.set(`fmt`,t),n.toString()}catch{return`${e}${e.includes(`?`)?`&`:`?`}fmt=${encodeURIComponent(t)}`}}function L(e,t,n,r,i){if(i){let e=N(t,r);window.open(e,`_blank`);return}if(p(t)){let i=N(t,r);f(i,{onFallback:()=>{e.contentWindow?.postMessage({clientLifecycle:`deep-link-failed`,data:{originalUrl:i}},n)}})}else if(j&&F(t))P(r);else{let e=N(t,r);window.location.href=e}}function R({iframe:e,targetOrigin:t}){let n=new r;return{handleEvent:r=>{if(!(`iframeLifecycle`in r))return;let{iframeLifecycle:i,data:a}=r;switch(i){case`connected`:n.resolve(!0);break;case`do-backup`:M(a.backup);break;case`remove-backup`:localStorage.removeItem(c);break;case`show`:case`hide`:x({iframe:e,isVisible:i===`show`});break;case`redirect`:L(e,a.baseRedirectUrl,t,a.mergeToken,a.openInNewTab);break}},isConnected:n.promise}}function z({config:c,iframe:l}){let u=c?.walletUrl??`https://wallet.frak.id`,d=typeof navigator<`u`?navigator.language?.split(`-`)[0]:void 0,f=c.metadata.lang??(d===`en`||d===`fr`?d:void 0),p=c.domain??(typeof window<`u`?window.location.hostname:``);t.setCacheScope(p,f),t.reset();let m=t.isCacheFresh?void 0:t.resolve(c.domain,c.walletUrl,f),h=R({iframe:l,targetOrigin:u}),g=new r,_=Date.now(),v=new A(c,l);if(!l.contentWindow)throw new i(a.configError,`The iframe does not have a content window`);let y=o({emittingTransport:l.contentWindow,listeningTransport:window,targetOrigin:u,middleware:[{async onRequest(e,t){if(!await h.isConnected)throw new i(a.clientNotConnected,`The iframe provider isn't connected yet`);return await g.promise,t}},{onRequest(e,t){return v.setLastRequest(e),t},onResponse(e,t){return v.setLastResponse(e,t),t}}],lifecycleHandlers:{iframeLifecycle:(e,t)=>{h.handleEvent(e)}}}),b=B(y,h),x=async()=>{b(),y.cleanup(),l.remove(),e(),t.clearCache(),t.reset()},S;{console.log(`[Frak SDK] Initializing OpenPanel`),S=new s({apiUrl:`https://op-api.gcp.frak.id`,clientId:`6eacc8d7-49ac-4936-95e9-81ef29449570`,trackScreenViews:!0,trackOutgoingLinks:!0,trackAttributes:!1,filter:({type:e,payload:t})=>(e!==`track`||!t?.properties||`sdkVersion`in t.properties||(t.properties={...t.properties,sdkVersion:`1.0.0`,userAnonymousClientId:n()}),!0)}),S.setGlobalProperties({sdkVersion:`1.0.0`,userAnonymousClientId:n()}),S.init(),S.track(`sdk_initialized`,{sdkVersion:`1.0.0`});let e=!1,t=setTimeout(()=>{e||(e=!0,S?.track(`sdk_iframe_handshake_failed`,{reason:`timeout`}))},3e4);h.isConnected.then(()=>{e||(e=!0,clearTimeout(t),S?.track(`sdk_iframe_connected`,{handshake_duration_ms:Date.now()-_}))}).catch(()=>{e||(e=!0,clearTimeout(t),S?.track(`sdk_iframe_handshake_failed`,{reason:`unknown`}))})}let C=V({config:c,rpcClient:y,lifecycleManager:h,configPromise:m,contextSent:g,openPanel:S}).then(()=>v.updateSetupStatus(!0)).catch(e=>{throw g.reject(e),e});return{config:c,debugInfo:v,waitForConnection:h.isConnected,waitForSetup:C,request:y.request,listenerRequest:y.listen,destroy:x,openPanel:S}}function B(e,t){let n,r,i=()=>e.sendLifecycle({clientLifecycle:`heartbeat`});async function a(){i(),n=setInterval(i,1e3),r=setTimeout(()=>{o(),console.log(`Heartbeat timeout: connection failed`)},3e4),await t.isConnected,o()}function o(){n&&clearInterval(n),r&&clearTimeout(r)}return a(),o}async function V({config:e,rpcClient:r,lifecycleManager:i,configPromise:a,contextSent:o,openPanel:s}){await i.isConnected,k(r,i.isConnected);let l=new URL(window.location.href),u=l.searchParams.get(`fmt`)??void 0;u&&(l.searchParams.delete(`fmt`),window.history.replaceState({},``,l.toString()));let d=n=>{let r=n?.merchantId??e.metadata.merchantId??``,i=n?.domain??``,a=n?.allowedDomains??[],o=n?.sdkConfig,s=o?.attribution||e.attribution?{...e.attribution,...o?.attribution}:void 0;t.setConfig(o?{isResolved:!0,merchantId:r,domain:i,allowedDomains:a,hasRawSdkConfig:!0,name:o.name??e.metadata.name,logoUrl:o.logoUrl??e.metadata.logoUrl,homepageLink:o.homepageLink??e.metadata.homepageLink,lang:o.lang??e.metadata.lang,currency:o.currency??e.metadata.currency,hidden:o.hidden,css:o.css,translations:o.translations,placements:o.placements,components:o.components,attribution:s}:{isResolved:!0,merchantId:r,domain:i,allowedDomains:a,name:e.metadata.name,logoUrl:e.metadata.logoUrl,homepageLink:e.metadata.homepageLink,lang:e.metadata.lang,currency:e.metadata.currency,attribution:s})},f=!1,p=e=>{let t=f?void 0:u;f=!0;let i=e.hasRawSdkConfig?{name:e.name,logoUrl:e.logoUrl,homepageLink:e.homepageLink,lang:e.lang,currency:e.currency,hidden:e.hidden,css:e.css,translations:e.translations,placements:e.placements,attribution:e.attribution}:e.attribution?{attribution:e.attribution}:void 0,a=n();if(s){let t=s.global??{};s.setGlobalProperties({...t,merchantId:e.merchantId,domain:e.domain??``})}r.sendLifecycle({clientLifecycle:`resolved-config`,data:{merchantId:e.merchantId,domain:e.domain??``,allowedDomains:e.allowedDomains??[],sourceUrl:window.location.href,...a&&{sdkAnonymousId:a},...t&&{pendingMergeToken:t},...i&&{sdkConfig:i}}})};t.isResolved&&(p(t.getConfig()),o.resolve()),a&&(d(await a),p(t.getConfig()),o.resolve());async function m(){let t=e.customizations?.css;t&&r.sendLifecycle({clientLifecycle:`modal-css`,data:{cssLink:t}})}async function h(){let t=e.customizations?.i18n;t&&r.sendLifecycle({clientLifecycle:`modal-i18n`,data:{i18n:t}})}async function g(){if(typeof window>`u`)return;let e=window.localStorage.getItem(c);e&&r.sendLifecycle({clientLifecycle:`restore-backup`,data:{backup:e}})}(await Promise.allSettled([m(),h(),g()])).some(e=>e.status===`rejected`)&&s?.track(`sdk_iframe_handshake_failed`,{reason:`asset_push`})}async function H({config:e}){let t=U(e),n=await b({config:t});if(!n){console.error(`Failed to create iframe`);return}let r=z({config:t,iframe:n});if(await r.waitForSetup,!await r.waitForConnection){console.error(`Failed to connect to client`);return}return r}function U(e){let t=h(e.metadata?.currency);return{...e,metadata:{...e.metadata,currency:t}}}export{p as _,w as a,l as b,y as c,v as d,_ as f,u as g,m as h,O as i,b as l,h as m,z as n,E as o,g as p,A as r,D as s,H as t,S as u,d as v,f as y};

package/package.json

@@ -11,7 +11,7 @@
       "url": "https://twitter.com/QNivelais"
     }
   ],
-  "version": "0.2.1",
+  "version": "1.0.0-beta.61e6fb99",
   "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,22 +91,21 @@
     "viem": "^2.x"
   },
   "dependencies": {
-    "@frak-labs/frame-connector": "0.2.0",
-    "@openpanel/web": "^1.0.7"
+    "@frak-labs/frame-connector": "0.2.0-beta.61e6fb99",
+    "@openpanel/web": "^1.2.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@frak-labs/dev-tooling": "0.0.0",
     "@frak-labs/test-foundation": "0.1.0",
     "@rolldown/plugin-node-polyfills": "^1.0.3",
-    "@types/jsdom": "^27.0.0",
-    "@types/node": "^24.10.13",
-    "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/ui": "^4.0.18",
-    "jsdom": "^28.0.0",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.9.3",
-    "viem": "^2.39.0",
-    "vitest": "^4.0.18"
+    "@types/jsdom": "^28.0.0",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/ui": "^4.1.4",
+    "jsdom": "^29.0.0",
+    "tsdown": "^0.21.8",
+    "typescript": "^6.0.2",
+    "viem": "^2.47.16",
+    "vitest": "^4.1.4"
   }
 }

package/src/actions/displayEmbeddedWallet.ts

@@ -8,14 +8,18 @@ import type {
  * Function used to display the Frak embedded wallet popup
  * @param client - The current Frak Client
  * @param params - The parameter used to customise the embedded wallet
+ * @param placement - Optional placement ID to associate with this display request
  * @returns The embedded wallet display result
  */
 export async function displayEmbeddedWallet(
     client: FrakClient,
-    params: DisplayEmbeddedWalletParamsType
+    params: DisplayEmbeddedWalletParamsType,
+    placement?: string
 ): Promise<DisplayEmbeddedWalletResultType> {
     return await client.request({
         method: "frak_displayEmbeddedWallet",
-        params: [params, client.config.metadata],
+        params: placement
+            ? [params, client.config.metadata, placement]
+            : [params, client.config.metadata],
     });
 }

package/src/actions/displayModal.ts

@@ -11,6 +11,7 @@ import type {
  * @param args
  * @param args.steps - The different steps of the modal
  * @param args.metadata - The metadata for the modal (customization, etc)
+ * @param placement - Optional placement ID to associate with this modal display
  * @returns The result of each modal steps
  *
  * @description This function will display a modal to the user with the provided steps and metadata.
@@ -111,10 +112,13 @@ export async function displayModal<
     T extends ModalStepTypes[] = ModalStepTypes[],
 >(
     client: FrakClient,
-    { steps, metadata }: DisplayModalParamsType<T>
+    { steps, metadata }: DisplayModalParamsType<T>,
+    placement?: string
 ): Promise<ModalRpcStepsResultType<T>> {
     return (await client.request({
         method: "frak_displayModal",
-        params: [steps, metadata, client.config.metadata],
+        params: placement
+            ? [steps, metadata, client.config.metadata, placement]
+            : [steps, metadata, client.config.metadata],
     })) as ModalRpcStepsResultType<T>;
 }

package/src/actions/displaySharingPage.ts

@@ -0,0 +1,49 @@
+import type {
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
+    FrakClient,
+} from "../types";
+
+/**
+ * Function used to display a sharing page
+ * @param client - The current Frak Client
+ * @param params - The parameters to customize the sharing page (products, link override, metadata)
+ * @param placement - Optional placement ID to associate with this display request
+ * @returns The result indicating the user's action (shared, copied, or dismissed)
+ *
+ * @description This function will display a full-page sharing UI to the user,
+ * showing product info, estimated rewards, sharing steps, FAQ, and share/copy buttons.
+ * The sharing link is generated from the user's wallet context + merchant info.
+ *
+ * @remarks
+ * - The promise resolves on the first user action (share or copy) but the page stays visible
+ * - The user can continue to share/copy multiple times after the initial resolution
+ * - Dismissing the page after a share/copy action is a no-op (promise already resolved)
+ * - If the user dismisses without any action, the promise resolves with `{ action: "dismissed" }`
+ *
+ * @example
+ * ```ts
+ * const result = await displaySharingPage(frakClient, {
+ *     products: [
+ *         {
+ *             title: "Babies camel cuir velours bout carré",
+ *             imageUrl: "https://example.com/product.jpg",
+ *         },
+ *     ],
+ * });
+ *
+ * console.log("User action:", result.action); // "shared" | "copied" | "dismissed"
+ * ```
+ */
+export async function displaySharingPage(
+    client: FrakClient,
+    params: DisplaySharingPageParamsType,
+    placement?: string
+): Promise<DisplaySharingPageResultType> {
+    return await client.request({
+        method: "frak_displaySharingPage",
+        params: placement
+            ? [params, client.config.metadata, placement]
+            : [params, client.config.metadata],
+    });
+}

package/src/actions/ensureIdentity.ts

@@ -1,6 +1,6 @@
 import { getBackendUrl } from "../utils/backendUrl";
 import { getClientId } from "../utils/clientId";
-import { fetchMerchantId } from "../utils/merchantId";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 
 const ENSURE_STORAGE_PREFIX = "frak-identity-ensured-";
 
@@ -36,7 +36,7 @@ export async function ensureIdentity(interactionToken: string): Promise<void> {
         return;
     }
 
-    const merchantId = await fetchMerchantId();
+    const merchantId = await sdkConfigStore.resolveMerchantId();
     if (!merchantId) {
         return;
     }

package/src/actions/getMerchantInformation.test.ts

@@ -1,9 +1,21 @@
 import type { Address, Hex } from "viem";
-import { describe, expect, it, vi } from "../../tests/vitest-fixtures";
+import {
+    beforeEach,
+    describe,
+    expect,
+    it,
+    vi,
+} from "../../tests/vitest-fixtures";
 import type { FrakClient, GetMerchantInformationReturnType } from "../types";
+import { clearAllCache } from "../utils/cache";
 import { getMerchantInformation } from "./getMerchantInformation";
 
 describe("getMerchantInformation", () => {
+    // Clear cache between tests to ensure isolation
+    beforeEach(() => {
+        clearAllCache();
+    });
+
     describe("success cases", () => {
         it("should call client.request with correct method", async () => {
             const mockResponse: GetMerchantInformationReturnType = {

package/src/actions/getMerchantInformation.ts

@@ -1,16 +1,31 @@
 import type { FrakClient, GetMerchantInformationReturnType } from "../types";
+import { withCache } from "../utils/cache";
 
 /**
- * Fetch the current merchant information (name, rewards, tiers) from the wallet iframe
+ * Fetch the current merchant information (name, rewards, tiers) from the wallet iframe.
+ *
+ * Results are cached in memory for 30 seconds by default. Concurrent calls
+ * while a request is in-flight are deduplicated automatically.
+ *
  * @param client - The current Frak Client
+ * @param options - Optional cache configuration
+ * @param options.cacheTime - Time in ms to cache the result. Default: 30_000 (30s). Set to 0 to disable.
  * @returns The merchant information including available reward tiers
  *
  * @see {@link @frak-labs/core-sdk!index.GetMerchantInformationReturnType | `GetMerchantInformationReturnType`} for the return type shape
  */
 export async function getMerchantInformation(
-    client: FrakClient
+    client: FrakClient,
+    options?: { cacheTime?: number }
 ): Promise<GetMerchantInformationReturnType> {
-    return await client.request({
-        method: "frak_getMerchantInformation",
-    });
+    return withCache(
+        () =>
+            client.request({
+                method: "frak_getMerchantInformation",
+            }),
+        {
+            cacheKey: "frak_getMerchantInformation",
+            cacheTime: options?.cacheTime,
+        }
+    );
 }

package/src/actions/getMergeToken.ts

@@ -0,0 +1,33 @@
+import type { FrakClient } from "../types";
+import { withCache } from "../utils/cache";
+
+/**
+ * Fetch a merge token for the current anonymous identity.
+ *
+ * Used by in-app browser redirect flows to preserve identity
+ * when switching from a WebView to the system browser.
+ * The token is appended as `?fmt=` to the redirect URL.
+ *
+ * Results are cached in memory for 30 seconds by default. Concurrent calls
+ * while a request is in-flight are deduplicated automatically.
+ *
+ * @param client - The current Frak Client
+ * @param options - Optional cache configuration
+ * @param options.cacheTime - Time in ms to cache the result. Default: 30_000 (30s). Set to 0 to disable.
+ * @returns The merge token string, or null if unavailable
+ */
+export async function getMergeToken(
+    client: FrakClient,
+    options?: { cacheTime?: number }
+): Promise<string | null> {
+    return withCache(
+        () =>
+            client.request({
+                method: "frak_getMergeToken",
+            }),
+        {
+            cacheKey: "frak_getMergeToken",
+            cacheTime: options?.cacheTime,
+        }
+    );
+}

package/src/actions/getUserReferralStatus.ts

@@ -0,0 +1,42 @@
+import type { FrakClient, UserReferralStatusType } from "../types";
+import { withCache } from "../utils/cache";
+
+/**
+ * Fetch the current user's referral status on the current merchant.
+ *
+ * The listener resolves the user's identity (via clientId or wallet session)
+ * and checks whether a referral link exists where the user is the referee.
+ *
+ * Results are cached in memory for 30 seconds by default. Concurrent calls
+ * while a request is in-flight are deduplicated automatically.
+ *
+ * Returns `null` when the user's identity cannot be resolved.
+ *
+ * @param client - The current Frak Client
+ * @param options - Optional cache configuration
+ * @param options.cacheTime - Time in ms to cache the result. Default: 30_000 (30s). Set to 0 to disable.
+ * @returns The user's referral status, or `null` if identity cannot be resolved
+ *
+ * @example
+ * ```ts
+ * const status = await getUserReferralStatus(client);
+ * if (status?.isReferred) {
+ *   console.log("User was referred to this merchant");
+ * }
+ * ```
+ */
+export async function getUserReferralStatus(
+    client: FrakClient,
+    options?: { cacheTime?: number }
+): Promise<UserReferralStatusType | null> {
+    return withCache(
+        () =>
+            client.request({
+                method: "frak_getUserReferralStatus",
+            }),
+        {
+            cacheKey: "frak_getUserReferralStatus",
+            cacheTime: options?.cacheTime,
+        }
+    );
+}

package/src/actions/index.ts

@@ -1,15 +1,22 @@
 export { displayEmbeddedWallet } from "./displayEmbeddedWallet";
 export { displayModal } from "./displayModal";
+export { displaySharingPage } from "./displaySharingPage";
 export { ensureIdentity } from "./ensureIdentity";
 export { getMerchantInformation } from "./getMerchantInformation";
+export { getMergeToken } from "./getMergeToken";
+export { getUserReferralStatus } from "./getUserReferralStatus";
 export { openSso } from "./openSso";
 export { prepareSso } from "./prepareSso";
 export {
     type ProcessReferralOptions,
     processReferral,
 } from "./referral/processReferral";
-// Referral interaction
+// Referral
 export { referralInteraction } from "./referral/referralInteraction";
+export {
+    REFERRAL_SUCCESS_EVENT,
+    setupReferral,
+} from "./referral/setupReferral";
 export { sendInteraction } from "./sendInteraction";
 // Helper to track the purchase status
 export { trackPurchaseStatus } from "./trackPurchaseStatus";

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

@@ -100,10 +100,8 @@ describe("processReferral", () => {
                 mockClient,
                 "user_referred_started",
                 {
-                    properties: {
-                        referrerClientId: "referrer-client-id",
-                        walletStatus: "connected",
-                    },
+                    referrerClientId: "referrer-client-id",
+                    walletStatus: "connected",
                 }
             );
 
@@ -156,10 +154,8 @@ describe("processReferral", () => {
                 mockClient,
                 "user_referred_started",
                 {
-                    properties: {
-                        referrer: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
-                        walletStatus: "connected",
-                    },
+                    referrer: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
+                    walletStatus: "connected",
                 }
             );
         });

package/src/actions/referral/processReferral.ts

@@ -54,10 +54,8 @@ function trackArrivalIfValid(
 
     if (isV2Context(frakContext)) {
         trackEvent(client, "user_referred_started", {
-            properties: {
-                referrerClientId: frakContext.c,
-                walletStatus: walletStatus?.key,
-            },
+            referrerClientId: frakContext.c,
+            walletStatus: walletStatus?.key,
         });
         sendInteraction(client, {
             type: "arrival",
@@ -71,10 +69,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",
@@ -177,9 +173,7 @@ export function processReferral(
     });
 
     trackEvent(client, "user_referred_completed", {
-        properties: {
-            status: "success",
-        },
+        status: "success",
     });
 
     return "success";

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

@@ -0,0 +1,79 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { REFERRAL_SUCCESS_EVENT, setupReferral } from "./setupReferral";
+
+vi.mock("./referralInteraction", () => ({
+    referralInteraction: vi.fn(),
+}));
+
+import { referralInteraction } from "./referralInteraction";
+
+describe("setupReferral", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it("should dispatch referral success event on successful referral", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue("success");
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).toHaveBeenCalledTimes(1);
+        expect(listener).toHaveBeenCalledWith(expect.any(Event));
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should not dispatch event when referral state is not success", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue("no-referrer");
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should not dispatch event when referral returns undefined", async () => {
+        vi.mocked(referralInteraction).mockResolvedValue(undefined);
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+    });
+
+    it("should silently catch errors and log warning", async () => {
+        vi.mocked(referralInteraction).mockRejectedValue(
+            new Error("network failure")
+        );
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+        const listener = vi.fn();
+        window.addEventListener(REFERRAL_SUCCESS_EVENT, listener);
+
+        await setupReferral({ config: {} } as any);
+
+        expect(listener).not.toHaveBeenCalled();
+        expect(warnSpy).toHaveBeenCalledWith(
+            "[Frak] Referral setup failed",
+            expect.any(Error)
+        );
+
+        window.removeEventListener(REFERRAL_SUCCESS_EVENT, listener);
+        warnSpy.mockRestore();
+    });
+
+    it("should export the correct event name constant", () => {
+        expect(REFERRAL_SUCCESS_EVENT).toBe("frak:referral-success");
+    });
+});

package/src/actions/referral/setupReferral.ts

@@ -0,0 +1,32 @@
+import type { FrakClient } from "../../types";
+import { referralInteraction } from "./referralInteraction";
+
+/**
+ * Custom event name dispatched on successful referral processing.
+ *
+ * Fired once per page load when a valid referral context is found in the URL
+ * and successfully tracked. Consumers (e.g. `<frak-banner>`) listen for this
+ * to display a referral success message.
+ */
+export const REFERRAL_SUCCESS_EVENT = "frak:referral-success";
+
+/**
+ * Process referral context and emit a DOM event on success.
+ *
+ * - Calls {@link referralInteraction} to detect and track any referral in the URL
+ * - On `"success"`, dispatches a bare {@link REFERRAL_SUCCESS_EVENT} on `window`
+ * - Silently swallows errors (fire-and-forget during SDK init)
+ *
+ * @param client - The initialized Frak client
+ */
+export async function setupReferral(client: FrakClient): Promise<void> {
+    try {
+        const state = await referralInteraction(client);
+
+        if (state === "success") {
+            window.dispatchEvent(new Event(REFERRAL_SUCCESS_EVENT));
+        }
+    } catch (error) {
+        console.warn("[Frak] Referral setup failed", error);
+    }
+}

package/src/actions/trackPurchaseStatus.test.ts

@@ -11,12 +11,14 @@ vi.mock("../utils/clientId", () => ({
     getClientId: vi.fn().mockReturnValue("test-client-id"),
 }));
 
-vi.mock("../utils/merchantId", () => ({
-    fetchMerchantId: vi.fn().mockResolvedValue(undefined),
+vi.mock("../utils/sdkConfigStore", () => ({
+    sdkConfigStore: {
+        resolveMerchantId: vi.fn().mockResolvedValue(undefined),
+    },
 }));
 
 import { getClientId } from "../utils/clientId";
-import { fetchMerchantId } from "../utils/merchantId";
+import { sdkConfigStore } from "../utils/sdkConfigStore";
 import { trackPurchaseStatus } from "./trackPurchaseStatus";
 
 describe.sequential("trackPurchaseStatus", () => {
@@ -100,7 +102,9 @@ describe.sequential("trackPurchaseStatus", () => {
         });
 
         vi.mocked(getClientId).mockReturnValue("test-client-id");
-        vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+        vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+            undefined
+        );
 
         fetchSpy = vi.fn().mockResolvedValue({
             ok: true,
@@ -228,12 +232,15 @@ describe.sequential("trackPurchaseStatus", () => {
         test("should resolve merchantId from explicit param first", async () => {
             setupStorage({
                 interactionToken: "token-123",
-                merchantId: "session-merchant-id",
+                merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
-            const merchantLookupCallsBefore =
-                vi.mocked(fetchMerchantId).mock.calls.length;
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "fetched-merchant-id"
+            );
+            const merchantLookupCallsBefore = vi.mocked(
+                sdkConfigStore.resolveMerchantId
+            ).mock.calls.length;
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -253,19 +260,20 @@ describe.sequential("trackPurchaseStatus", () => {
                     merchantId: "explicit-merchant-id",
                 })
             );
-            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
-                merchantLookupCallsBefore
-            );
+            expect(
+                vi.mocked(sdkConfigStore.resolveMerchantId).mock.calls.length
+            ).toBe(merchantLookupCallsBefore);
         });
 
         test("should fall back to sessionStorage for merchantId", async () => {
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "session-merchant-id"
+            );
             setupStorage({
                 interactionToken: "token-123",
-                merchantId: "session-merchant-id",
+                merchantId: null,
                 clientId: "test-client-id",
             });
-            const merchantLookupCallsBefore =
-                vi.mocked(fetchMerchantId).mock.calls.length;
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -284,18 +292,20 @@ describe.sequential("trackPurchaseStatus", () => {
                     merchantId: "session-merchant-id",
                 })
             );
-            expect(vi.mocked(fetchMerchantId).mock.calls.length).toBe(
-                merchantLookupCallsBefore
-            );
+            expect(
+                vi.mocked(sdkConfigStore.resolveMerchantId)
+            ).toHaveBeenCalled();
         });
 
-        test("should fall back to fetchMerchantId when no explicit or sessionStorage", async () => {
+        test("should fall back to resolveMerchantId when no explicit merchantId", async () => {
             setupStorage({
                 interactionToken: "token-123",
                 merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue("fetched-merchant-id");
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                "fetched-merchant-id"
+            );
 
             await trackPurchaseStatus({
                 customerId: "cust-1",
@@ -322,7 +332,9 @@ describe.sequential("trackPurchaseStatus", () => {
                 merchantId: null,
                 clientId: "test-client-id",
             });
-            vi.mocked(fetchMerchantId).mockResolvedValue(undefined);
+            vi.mocked(sdkConfigStore.resolveMerchantId).mockResolvedValue(
+                undefined
+            );
             const callCountBefore = getTrackingRequests().length;
 
             await trackPurchaseStatus({