@frak-labs/core-sdk 0.2.1-beta.b38eef2e → 0.2.1-beta.d04602ec

package/dist/{siweAuthenticate-CnCZ7mok.d.ts → siweAuthenticate-Dc_Yg9Bg.d.cts}

@@ -1,13 +1,14 @@
-import { A as SendTransactionModalStepType, B as PrepareSsoReturnType, E as ModalRpcMetadata, F as SiweAuthenticationParams, H as FinalActionType, I as LoginModalStepType, O as ModalRpcStepsResultType, P as SiweAuthenticateReturnType, T as DisplayModalParamsType, U as FinalModalStepType, b as DisplayEmbeddedWalletResultType, h as GetMerchantInformationReturnType, i as FrakContext, j as SendTransactionReturnType, k as ModalStepTypes, l as FrakClient, p as WalletStatusReturnType, v as SendInteractionParamsType, y as DisplayEmbeddedWalletParamsType, z as PrepareSsoParamsType } from "./openSso-CMzwvaCa.js";
+import { A as ModalRpcMetadata, B as LoginModalStepType, D as DisplaySharingPageResultType, E as DisplaySharingPageParamsType, F as SendTransactionReturnType, K as FinalActionType, M as ModalRpcStepsResultType, N as ModalStepTypes, P as SendTransactionModalStepType, R as SiweAuthenticateReturnType, U as PrepareSsoParamsType, W as PrepareSsoReturnType, b as DisplayEmbeddedWalletParamsType, g as GetMerchantInformationReturnType, i as FrakContext, k as DisplayModalParamsType, l as FrakClient, m as UserReferralStatusType, p as WalletStatusReturnType, q as FinalModalStepType, x as DisplayEmbeddedWalletResultType, y as SendInteractionParamsType, z as SiweAuthenticationParams } from "./openSso-CebB8mFv.cjs";
 
 //#region src/actions/displayEmbeddedWallet.d.ts
 /**
  * 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
  */
-declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbeddedWalletParamsType): Promise<DisplayEmbeddedWalletResultType>;
+declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbeddedWalletParamsType, placement?: string): Promise<DisplayEmbeddedWalletResultType>;
 //#endregion
 //#region src/actions/displayModal.d.ts
 /**
@@ -16,6 +17,7 @@ declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbedd
  * @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.
@@ -115,7 +117,41 @@ declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbedd
 declare function displayModal<T extends ModalStepTypes[] = ModalStepTypes[]>(client: FrakClient, {
   steps,
   metadata
-}: DisplayModalParamsType<T>): Promise<ModalRpcStepsResultType<T>>;
+}: DisplayModalParamsType<T>, placement?: string): Promise<ModalRpcStepsResultType<T>>;
+//#endregion
+//#region src/actions/displaySharingPage.d.ts
+/**
+ * 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"
+ * ```
+ */
+declare function displaySharingPage(client: FrakClient, params: DisplaySharingPageParamsType, placement?: string): Promise<DisplaySharingPageResultType>;
 //#endregion
 //#region src/actions/ensureIdentity.d.ts
 /**
@@ -144,13 +180,50 @@ declare function ensureIdentity(interactionToken: string): Promise<void>;
 //#endregion
 //#region src/actions/getMerchantInformation.d.ts
 /**
- * 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
  */
-declare function getMerchantInformation(client: FrakClient): Promise<GetMerchantInformationReturnType>;
+declare function getMerchantInformation(client: FrakClient, options?: {
+  cacheTime?: number;
+}): Promise<GetMerchantInformationReturnType>;
+//#endregion
+//#region src/actions/getUserReferralStatus.d.ts
+/**
+ * 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");
+ * }
+ * ```
+ */
+declare function getUserReferralStatus(client: FrakClient, options?: {
+  cacheTime?: number;
+}): Promise<UserReferralStatusType | null>;
 //#endregion
 //#region src/actions/prepareSso.d.ts
 /**
@@ -256,6 +329,26 @@ declare function referralInteraction(client: FrakClient, {
   options?: ProcessReferralOptions;
 }): Promise<("idle" | "processing" | "success" | "no-referrer" | "self-referral") | undefined>;
 //#endregion
+//#region src/actions/referral/setupReferral.d.ts
+/**
+ * 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.
+ */
+declare 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
+ */
+declare function setupReferral(client: FrakClient): Promise<void>;
+//#endregion
 //#region src/actions/sendInteraction.d.ts
 /**
  * Send an interaction to the backend via the listener RPC.
@@ -322,7 +415,7 @@ declare function sendInteraction(client: FrakClient, params: SendInteractionPara
  * }
  *
  * @remarks
- * - Merchant id is resolved in this order: explicit `args.merchantId`, `frak-merchant-id` from session storage, then `fetchMerchantId()`.
+ * - Merchant id is resolved in this order: explicit `args.merchantId`, then `sdkConfigStore.resolveMerchantId()` (config store → sessionStorage → backend fetch).
  * - This function supports anonymous users and will use the `x-frak-client-id` header when available.
  * - At least one identity source must exist (`frak-wallet-interaction-token` or `x-frak-client-id`), otherwise the tracking request is skipped.
  * - This function will print a warning if used in a non-browser environment or if no identity / merchant id can be resolved.
@@ -380,8 +473,9 @@ type ModalStepBuilder<Steps extends ModalStepTypes[] = ModalStepTypes[]> = {
   /**
    * Display the modal
    * @param metadataOverride - Function returning optional metadata to override the current modal metadata
+   * @param placement - Optional placement ID to associate with this modal display
    */
-  display: (metadataOverride?: (current?: ModalRpcMetadata) => ModalRpcMetadata | undefined) => Promise<ModalRpcStepsResultType<Steps>>;
+  display: (metadataOverride?: (current?: ModalRpcMetadata) => ModalRpcMetadata | undefined, placement?: string) => Promise<ModalRpcStepsResultType<Steps>>;
 };
 /**
  * Represent the output type of the modal builder
@@ -529,4 +623,4 @@ declare function siweAuthenticate(client: FrakClient, {
   metadata
 }: SiweAuthenticateModalParams): Promise<SiweAuthenticateReturnType>;
 //#endregion
-export { displayModal as _, ModalBuilder as a, watchWalletStatus as c, referralInteraction as d, ProcessReferralOptions as f, ensureIdentity as g, getMerchantInformation as h, sendTransaction as i, trackPurchaseStatus as l, prepareSso as m, siweAuthenticate as n, ModalStepBuilder as o, processReferral as p, SendTransactionParams as r, modalBuilder as s, SiweAuthenticateModalParams as t, sendInteraction as u, displayEmbeddedWallet as v };
+export { displayEmbeddedWallet as S, getUserReferralStatus as _, ModalBuilder as a, displaySharingPage as b, watchWalletStatus as c, REFERRAL_SUCCESS_EVENT as d, setupReferral as f, prepareSso as g, processReferral as h, sendTransaction as i, trackPurchaseStatus as l, ProcessReferralOptions as m, siweAuthenticate as n, ModalStepBuilder as o, referralInteraction as p, SendTransactionParams as r, modalBuilder as s, SiweAuthenticateModalParams as t, sendInteraction as u, getMerchantInformation as v, displayModal as x, ensureIdentity as y };

package/dist/{siweAuthenticate-CVigMOxz.d.cts → siweAuthenticate-Ddhl-o4N.d.ts}

@@ -1,13 +1,14 @@
-import { A as SendTransactionModalStepType, B as PrepareSsoReturnType, E as ModalRpcMetadata, F as SiweAuthenticationParams, H as FinalActionType, I as LoginModalStepType, O as ModalRpcStepsResultType, P as SiweAuthenticateReturnType, T as DisplayModalParamsType, U as FinalModalStepType, b as DisplayEmbeddedWalletResultType, h as GetMerchantInformationReturnType, i as FrakContext, j as SendTransactionReturnType, k as ModalStepTypes, l as FrakClient, p as WalletStatusReturnType, v as SendInteractionParamsType, y as DisplayEmbeddedWalletParamsType, z as PrepareSsoParamsType } from "./openSso-B0g7-807.cjs";
+import { A as ModalRpcMetadata, B as LoginModalStepType, D as DisplaySharingPageResultType, E as DisplaySharingPageParamsType, F as SendTransactionReturnType, K as FinalActionType, M as ModalRpcStepsResultType, N as ModalStepTypes, P as SendTransactionModalStepType, R as SiweAuthenticateReturnType, U as PrepareSsoParamsType, W as PrepareSsoReturnType, b as DisplayEmbeddedWalletParamsType, g as GetMerchantInformationReturnType, i as FrakContext, k as DisplayModalParamsType, l as FrakClient, m as UserReferralStatusType, p as WalletStatusReturnType, q as FinalModalStepType, x as DisplayEmbeddedWalletResultType, y as SendInteractionParamsType, z as SiweAuthenticationParams } from "./openSso-CMZM06uR.js";
 
 //#region src/actions/displayEmbeddedWallet.d.ts
 /**
  * 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
  */
-declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbeddedWalletParamsType): Promise<DisplayEmbeddedWalletResultType>;
+declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbeddedWalletParamsType, placement?: string): Promise<DisplayEmbeddedWalletResultType>;
 //#endregion
 //#region src/actions/displayModal.d.ts
 /**
@@ -16,6 +17,7 @@ declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbedd
  * @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.
@@ -115,7 +117,41 @@ declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbedd
 declare function displayModal<T extends ModalStepTypes[] = ModalStepTypes[]>(client: FrakClient, {
   steps,
   metadata
-}: DisplayModalParamsType<T>): Promise<ModalRpcStepsResultType<T>>;
+}: DisplayModalParamsType<T>, placement?: string): Promise<ModalRpcStepsResultType<T>>;
+//#endregion
+//#region src/actions/displaySharingPage.d.ts
+/**
+ * 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"
+ * ```
+ */
+declare function displaySharingPage(client: FrakClient, params: DisplaySharingPageParamsType, placement?: string): Promise<DisplaySharingPageResultType>;
 //#endregion
 //#region src/actions/ensureIdentity.d.ts
 /**
@@ -144,13 +180,50 @@ declare function ensureIdentity(interactionToken: string): Promise<void>;
 //#endregion
 //#region src/actions/getMerchantInformation.d.ts
 /**
- * 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
  */
-declare function getMerchantInformation(client: FrakClient): Promise<GetMerchantInformationReturnType>;
+declare function getMerchantInformation(client: FrakClient, options?: {
+  cacheTime?: number;
+}): Promise<GetMerchantInformationReturnType>;
+//#endregion
+//#region src/actions/getUserReferralStatus.d.ts
+/**
+ * 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");
+ * }
+ * ```
+ */
+declare function getUserReferralStatus(client: FrakClient, options?: {
+  cacheTime?: number;
+}): Promise<UserReferralStatusType | null>;
 //#endregion
 //#region src/actions/prepareSso.d.ts
 /**
@@ -256,6 +329,26 @@ declare function referralInteraction(client: FrakClient, {
   options?: ProcessReferralOptions;
 }): Promise<("idle" | "processing" | "success" | "no-referrer" | "self-referral") | undefined>;
 //#endregion
+//#region src/actions/referral/setupReferral.d.ts
+/**
+ * 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.
+ */
+declare 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
+ */
+declare function setupReferral(client: FrakClient): Promise<void>;
+//#endregion
 //#region src/actions/sendInteraction.d.ts
 /**
  * Send an interaction to the backend via the listener RPC.
@@ -322,7 +415,7 @@ declare function sendInteraction(client: FrakClient, params: SendInteractionPara
  * }
  *
  * @remarks
- * - Merchant id is resolved in this order: explicit `args.merchantId`, `frak-merchant-id` from session storage, then `fetchMerchantId()`.
+ * - Merchant id is resolved in this order: explicit `args.merchantId`, then `sdkConfigStore.resolveMerchantId()` (config store → sessionStorage → backend fetch).
  * - This function supports anonymous users and will use the `x-frak-client-id` header when available.
  * - At least one identity source must exist (`frak-wallet-interaction-token` or `x-frak-client-id`), otherwise the tracking request is skipped.
  * - This function will print a warning if used in a non-browser environment or if no identity / merchant id can be resolved.
@@ -380,8 +473,9 @@ type ModalStepBuilder<Steps extends ModalStepTypes[] = ModalStepTypes[]> = {
   /**
    * Display the modal
    * @param metadataOverride - Function returning optional metadata to override the current modal metadata
+   * @param placement - Optional placement ID to associate with this modal display
    */
-  display: (metadataOverride?: (current?: ModalRpcMetadata) => ModalRpcMetadata | undefined) => Promise<ModalRpcStepsResultType<Steps>>;
+  display: (metadataOverride?: (current?: ModalRpcMetadata) => ModalRpcMetadata | undefined, placement?: string) => Promise<ModalRpcStepsResultType<Steps>>;
 };
 /**
  * Represent the output type of the modal builder
@@ -529,4 +623,4 @@ declare function siweAuthenticate(client: FrakClient, {
   metadata
 }: SiweAuthenticateModalParams): Promise<SiweAuthenticateReturnType>;
 //#endregion
-export { displayModal as _, ModalBuilder as a, watchWalletStatus as c, referralInteraction as d, ProcessReferralOptions as f, ensureIdentity as g, getMerchantInformation as h, sendTransaction as i, trackPurchaseStatus as l, prepareSso as m, siweAuthenticate as n, ModalStepBuilder as o, processReferral as p, SendTransactionParams as r, modalBuilder as s, SiweAuthenticateModalParams as t, sendInteraction as u, displayEmbeddedWallet as v };
+export { displayEmbeddedWallet as S, getUserReferralStatus as _, ModalBuilder as a, displaySharingPage as b, watchWalletStatus as c, REFERRAL_SUCCESS_EVENT as d, setupReferral as f, prepareSso as g, processReferral as h, sendTransaction as i, trackPurchaseStatus as l, ProcessReferralOptions as m, siweAuthenticate as n, ModalStepBuilder as o, referralInteraction as p, SendTransactionParams as r, modalBuilder as s, SiweAuthenticateModalParams as t, sendInteraction as u, getMerchantInformation as v, displayModal as x, ensureIdentity as y };

package/dist/trackEvent-Ce1XlsIE.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(ee({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 ee(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 h=`menubar=no,status=no,scrollbars=no,fullscreen=no,width=500, height=800`,g=`frak-sso`;async function _(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,h);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 y(e){return e.includes(`localhost:3000`)||e.includes(`localhost:3010`)}function b(e){return y(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 x(e){if(e)return b(e);if(typeof window<`u`){let e=window.FrakSetup?.client?.config?.walletUrl;if(e)return b(e)}return v}var S=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 C=new S(1024),w=new S(1024),T=3e4;async function E(e,{cacheKey:t,cacheTime:n=T}){if(n>0){let e=w.get(t);if(e&&Date.now()-e.created<n)return e.data}let r=C.get(t);r||(r=e(),C.set(t,r));try{let e=await r;return w.set(t,{data:e,created:Date.now()}),e}finally{C.delete(t)}}function D(e){return{clear:()=>{C.delete(e),w.delete(e)},has:(t=T)=>{let n=w.get(e);return n?Date.now()-n.created<t:!1}}}function O(){C.clear(),w.clear()}function k(e){return a(f(e))}function te(e){return`r`in e&&!(`v`in e)}function A(e){return`v`in e&&e.v===2}const j=`fCtx`;function M(e){if(e)try{return A(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 N(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 P({url:e}){if(!e)return null;let t=new URL(e).searchParams.get(j);return t?N(t):null}function F({url:e,context:t}){if(!e)return null;let n=M(t);if(!n)return null;let r=new URL(e);return r.searchParams.set(j,n),r.toString()}function I(e){let t=new URL(e);return t.searchParams.delete(j),t.toString()}function ne({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?I(n):F({url:n,context:t}),r&&window.history.replaceState(null,``,r.toString())}const L={compress:M,decompress:N,parse:P,update:F,remove:I,replaceUrl:ne},R=`__frakSdkConfig`,z=`frak-config-cache`,B=`frak-merchant-id`,V={key:z},H=typeof window<`u`;function U(){return{isResolved:!1,merchantId:``}}let W=null;function G(){if(!H)return null;try{let e=localStorage.getItem(V.key);if(!e)return null;let t=JSON.parse(e);return t.config?.isResolved?(W=t,t):null}catch{return null}}function K(){return(W??G())?.config}function q(){let e=W??G();return e?Date.now()-e.timestamp<3e4:!1}function J(e){if(!(!H||!e.isResolved))try{let t={config:e,timestamp:Date.now()};localStorage.setItem(V.key,JSON.stringify(t)),W=t}catch{}}function Y(){if(H){W=null;try{localStorage.removeItem(V.key)}catch{}}}function X(){H&&(window[R]||(window[R]=K()??U()))}X();function Z(){return H?window[R]??U():U()}function Q(e){H&&window.dispatchEvent(new CustomEvent(`frak:config`,{detail:e}))}function re(e){return e??(H?window.location.hostname:``)}async function ie(e,t,n){try{let r=x(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(H)try{sessionStorage.setItem(B,o.merchantId)}catch{}return o}catch(e){console.warn(`[Frak SDK] Failed to fetch merchant config:`,e);return}}const $={getConfig:Z,get isResolved(){return Z().isResolved},get isCacheFresh(){return q()},setCacheScope(e,t){V.key=`${z}:${`${e}:${t??``}`}`,W=null},setConfig(e){if(H&&(window[R]=e),J(e),Q(e),H&&e.merchantId)try{sessionStorage.setItem(B,e.merchantId)}catch{}},reset(){let e=K()??U();H&&(window[R]=e),Q(e)},clearCache(){if(Y(),O(),H)try{sessionStorage.removeItem(B)}catch{}},resolve(e,t,n){let r=re(e);return r?E(async()=>{let e=await ie(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=Z();if(e.isResolved&&e.merchantId)return e.merchantId;if(H)try{return sessionStorage.getItem(B)??void 0}catch{}},async resolveMerchantId(e,t){return $.getMerchantId()||(await $.resolve(e,t))?.merchantId}};function ae(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 _,A as a,D as c,_ as d,h as f,f as g,p as h,te as i,E as l,m,$ as n,k as o,g as p,L as r,O as s,ae as t,x as u,u as v,l as y};

package/dist/trackEvent-CvbJTTqA.cjs

@@ -0,0 +1 @@
+let e=require(`viem`),t=require(`@frak-labs/frame-connector`);const n=`frak-client-id`;function r(){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 i(){if(typeof window>`u`||!window.localStorage)return console.warn(`[Frak SDK] No Window / localStorage available to save the clientId`),r();let e=localStorage.getItem(n);return e||(e=r(),localStorage.setItem(n,e)),e}function a({domain:t}={}){return(0,e.keccak256)((0,e.toHex)((t??window.location.host).replace(`www.`,``)))}function o(e){return btoa(Array.from(e,e=>String.fromCharCode(e)).join(``)).replace(/\+/g,`-`).replace(/\//g,`_`).replace(/=+$/,``)}function s(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 c(e){return o((0,t.jsonEncode)(e))}function l(e,t,n,r,i,a){let o=c(u({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 u(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 d=`menubar=no,status=no,scrollbars=no,fullscreen=no,width=500, height=800`,f=`frak-sso`;async function p(e,t){let{metadata:n,customizations:r,walletUrl:o}=e.config;if(t.openInSameWindow??!!t.redirectUrl)return await e.request({method:`frak_openSso`,params:[t,n.name,r?.css]});let s=t.ssoPopupUrl??l(o??`https://wallet.frak.id`,t,a(),n.name,i(),r?.css),c=window.open(s,f,d);if(!c)throw Error(`Popup was blocked. Please allow popups for this site.`);return c.focus(),await e.request({method:`frak_openSso`,params:[t,n.name,r?.css]})??{}}const m=`https://backend.frak.id`;function h(e){return e.includes(`localhost:3000`)||e.includes(`localhost:3010`)}function g(e){return h(e)?`https://localhost:3030`:e.includes(`wallet-dev.frak.id`)||e.includes(`wallet.gcp-dev.frak.id`)?`https://backend.gcp-dev.frak.id`:m}function _(e){if(e)return g(e);if(typeof window<`u`){let e=window.FrakSetup?.client?.config?.walletUrl;if(e)return g(e)}return m}var v=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 y=new v(1024),b=new v(1024),x=3e4;async function S(e,{cacheKey:t,cacheTime:n=x}){if(n>0){let e=b.get(t);if(e&&Date.now()-e.created<n)return e.data}let r=y.get(t);r||(r=e(),y.set(t,r));try{let e=await r;return b.set(t,{data:e,created:Date.now()}),e}finally{y.delete(t)}}function C(e){return{clear:()=>{y.delete(e),b.delete(e)},has:(t=x)=>{let n=b.get(e);return n?Date.now()-n.created<t:!1}}}function w(){y.clear(),b.clear()}function T(e){return(0,t.jsonDecode)(s(e))}function E(e){return`r`in e&&!(`v`in e)}function D(e){return`v`in e&&e.v===2}const O=`fCtx`;function k(t){if(t)try{return D(t)?!t.c||!t.m||!t.t?void 0:c({v:2,c:t.c,m:t.m,t:t.t}):o((0,e.hexToBytes)(t.r))}catch(e){console.error(`Error compressing Frak context`,{e,context:t})}}function A(t){if(!(!t||t.length===0))try{let n=T(t);if(n&&typeof n==`object`&&n.v===2)return n.c&&n.m&&n.t?{v:2,c:n.c,m:n.m,t:n.t}:void 0;let r=(0,e.bytesToHex)(s(t),{size:20});if((0,e.isAddress)(r))return{r}}catch(e){console.error(`Error decompressing Frak context`,{e,context:t})}}function j({url:e}){if(!e)return null;let t=new URL(e).searchParams.get(O);return t?A(t):null}function M({url:e,context:t}){if(!e)return null;let n=k(t);if(!n)return null;let r=new URL(e);return r.searchParams.set(O,n),r.toString()}function N(e){let t=new URL(e);return t.searchParams.delete(O),t.toString()}function P({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?N(n):M({url:n,context:t}),r&&window.history.replaceState(null,``,r.toString())}const F={compress:k,decompress:A,parse:j,update:M,remove:N,replaceUrl:P},I=`__frakSdkConfig`,L=`frak-config-cache`,R=`frak-merchant-id`,z={key:L},B=typeof window<`u`;function V(){return{isResolved:!1,merchantId:``}}let H=null;function U(){if(!B)return null;try{let e=localStorage.getItem(z.key);if(!e)return null;let t=JSON.parse(e);return t.config?.isResolved?(H=t,t):null}catch{return null}}function W(){return(H??U())?.config}function G(){let e=H??U();return e?Date.now()-e.timestamp<3e4:!1}function K(e){if(!(!B||!e.isResolved))try{let t={config:e,timestamp:Date.now()};localStorage.setItem(z.key,JSON.stringify(t)),H=t}catch{}}function q(){if(B){H=null;try{localStorage.removeItem(z.key)}catch{}}}function J(){B&&(window[I]||(window[I]=W()??V()))}J();function Y(){return B?window[I]??V():V()}function X(e){B&&window.dispatchEvent(new CustomEvent(`frak:config`,{detail:e}))}function Z(e){return e??(B?window.location.hostname:``)}async function Q(e,t,n){try{let r=_(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(B)try{sessionStorage.setItem(R,o.merchantId)}catch{}return o}catch(e){console.warn(`[Frak SDK] Failed to fetch merchant config:`,e);return}}const $={getConfig:Y,get isResolved(){return Y().isResolved},get isCacheFresh(){return G()},setCacheScope(e,t){z.key=`${L}:${`${e}:${t??``}`}`,H=null},setConfig(e){if(B&&(window[I]=e),K(e),X(e),B&&e.merchantId)try{sessionStorage.setItem(R,e.merchantId)}catch{}},reset(){let e=W()??V();B&&(window[I]=e),X(e)},clearCache(){if(q(),w(),B)try{sessionStorage.removeItem(R)}catch{}},resolve(e,t,n){let r=Z(e);return r?S(async()=>{let e=await Q(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=Y();if(e.isResolved&&e.merchantId)return e.merchantId;if(B)try{return sessionStorage.getItem(R)??void 0}catch{}},async resolveMerchantId(e,t){return $.getMerchantId()||(await $.resolve(e,t))?.merchantId}};function ee(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)}}Object.defineProperty(exports,`_`,{enumerable:!0,get:function(){return o}}),Object.defineProperty(exports,`a`,{enumerable:!0,get:function(){return D}}),Object.defineProperty(exports,`c`,{enumerable:!0,get:function(){return C}}),Object.defineProperty(exports,`d`,{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,`f`,{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,`g`,{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,`h`,{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,`i`,{enumerable:!0,get:function(){return E}}),Object.defineProperty(exports,`l`,{enumerable:!0,get:function(){return S}}),Object.defineProperty(exports,`m`,{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return $}}),Object.defineProperty(exports,`o`,{enumerable:!0,get:function(){return T}}),Object.defineProperty(exports,`p`,{enumerable:!0,get:function(){return f}}),Object.defineProperty(exports,`r`,{enumerable:!0,get:function(){return F}}),Object.defineProperty(exports,`s`,{enumerable:!0,get:function(){return w}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return ee}}),Object.defineProperty(exports,`u`,{enumerable:!0,get:function(){return _}}),Object.defineProperty(exports,`v`,{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,`y`,{enumerable:!0,get:function(){return i}});

package/package.json

@@ -11,7 +11,7 @@
       "url": "https://twitter.com/QNivelais"
     }
   ],
-  "version": "0.2.1-beta.b38eef2e",
+  "version": "0.2.1-beta.d04602ec",
   "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,22 @@
     "viem": "^2.x"
   },
   "dependencies": {
-    "@frak-labs/frame-connector": "0.2.0-beta.b38eef2e",
-    "@openpanel/web": "^1.0.7"
+    "@frak-labs/frame-connector": "0.2.0-beta.d04602ec",
+    "@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/jsdom": "^28.0.0",
     "@types/node": "^24.10.13",
-    "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/ui": "^4.0.18",
-    "jsdom": "^28.0.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/ui": "^4.1.0",
+    "jsdom": "^29.0.0",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "viem": "^2.39.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }

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/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,
+        }
+    );
+}