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

package/dist/{computeLegacyProductId-b5cUWdAm.d.ts → index-ByVpu25D.d.cts}

@@ -1,5 +1,5 @@
-import { J as Currency, V as SsoMetadata, Y as FrakWalletSdkConfig, _ as TokenAmountType, a as FrakContextV1, i as FrakContext, l as FrakClient, o as FrakContextV2, z as PrepareSsoParamsType } from "./openSso-CMzwvaCa.js";
-import { Address, Hex } from "viem";
+import { G as SsoMetadata, Q as MerchantConfigResponse, U as PrepareSsoParamsType, a as FrakContextV1, at as Language, ct as AttributionParams, i as FrakContext, l as FrakClient, nt as Currency, o as FrakContextV2, rt as FrakWalletSdkConfig, st as AttributionDefaults, tt as SdkResolvedConfig, v as TokenAmountType } from "./openSso-qjaccFd0.cjs";
+import { Hex } from "viem";
 import { RpcMessage, RpcResponse } from "@frak-labs/frame-connector";
 
 //#region src/types/compression.d.ts
@@ -22,35 +22,12 @@ type HashProtectedData<DataType> = Readonly<DataType & {
  */
 type KeyProvider<DataType> = (value: DataType) => string[];
 //#endregion
-//#region src/types/tracking.d.ts
-type UtmParams = {
-  source?: string;
-  medium?: string;
-  campaign?: string;
-  term?: string;
-  content?: string;
-};
-type TrackArrivalParams = {
-  /** @deprecated V1 legacy — use referrerClientId for v2 contexts */referrerWallet?: Address;
-  referrerClientId?: string;
-  referrerMerchantId?: string; /** Epoch seconds timestamp from the referral link creation */
-  referralTimestamp?: number;
-  landingUrl?: string;
-  utmParams?: UtmParams;
-};
-type TrackArrivalResult = {
-  success: boolean;
-  identityGroupId?: string;
-  touchpointId?: string;
-  error?: string;
-};
-//#endregion
 //#region src/clients/createIFrameFrakClient.d.ts
 /**
  * Create a new iframe Frak client
  * @param args
  * @param args.config - The configuration to use for the Frak Wallet SDK.
- *   When `config.domain` is set, it is forwarded to the iframe handshake so the listener resolves the correct merchant in tunneled/proxied environments (e.g. Shopify dev with Cloudflare tunnel).
+ *   When `config.domain` is set, it is used to resolve the correct merchant config in tunneled/proxied environments (e.g. Shopify dev with Cloudflare tunnel).
  * @param args.iframe - The iframe to use for the communication
  * @returns The created Frak Client
  *
@@ -134,6 +111,111 @@ declare const locales: {
   readonly gbp: "en-GB";
 };
 //#endregion
+//#region src/utils/analytics/events/component.d.ts
+type ButtonBaseProps = {
+  placement?: string;
+  target_interaction?: string;
+  has_reward?: boolean;
+};
+type BannerVariant = "referral" | "inapp";
+type BannerOutcome = "clicked" | "dismissed";
+type PostPurchaseVariant = "referrer" | "referee";
+type ShareClickAction = "share-modal" | "embedded-wallet" | "sharing-page";
+type SdkComponentEventMap = {
+  share_button_clicked: ButtonBaseProps & {
+    click_action: ShareClickAction;
+  };
+  share_modal_error: ButtonBaseProps & {
+    error?: string;
+  };
+  open_in_app_clicked: {
+    placement?: string;
+    path: string;
+  };
+  app_not_installed: {
+    placement?: string;
+    path: string;
+  };
+  banner_impression: {
+    placement?: string;
+    variant: BannerVariant;
+    has_reward?: boolean;
+  };
+  banner_resolved: {
+    placement?: string;
+    variant: BannerVariant;
+    outcome: BannerOutcome;
+  };
+  post_purchase_impression: {
+    placement?: string;
+    variant: PostPurchaseVariant;
+    has_reward?: boolean;
+  };
+  post_purchase_clicked: {
+    placement?: string;
+    variant: PostPurchaseVariant;
+  };
+};
+//#endregion
+//#region src/utils/analytics/events/lifecycle.d.ts
+type SdkHandshakeFailureReason = "timeout" | "origin" | "asset_push" | "unknown";
+type SdkLifecycleEventMap = {
+  sdk_initialized: {
+    sdkVersion?: string;
+  };
+  sdk_iframe_connected: {
+    handshake_duration_ms: number;
+  };
+  sdk_iframe_handshake_failed: {
+    reason: SdkHandshakeFailureReason;
+  };
+  /**
+   * Emitted by the CDN bootstrap when `initFrakSdk()` throws before a
+   * client is available. Uses a transient OpenPanel instance so broken
+   * partner integrations are still captured.
+   */
+  sdk_init_failed: {
+    reason: string;
+    config_missing?: boolean;
+  };
+};
+//#endregion
+//#region src/utils/analytics/events/referral.d.ts
+type SdkReferralEventMap = {
+  user_referred_started: {
+    referrer?: string;
+    referrerClientId?: string;
+    walletStatus?: string;
+  };
+  user_referred_completed: {
+    status: "success";
+  };
+};
+//#endregion
+//#region src/utils/analytics/events/index.d.ts
+/**
+ * Merged SDK event map. Consumed by the SDK's typed `trackEvent`.
+ * Stays isolated from wallet-shared because the SDK ships in partner
+ * bundles (different OpenPanel client id, no wallet-shared dependency
+ * allowed — see `packages/wallet-shared/AGENTS.md`).
+ */
+type SdkEventMap = SdkLifecycleEventMap & SdkComponentEventMap & SdkReferralEventMap;
+//#endregion
+//#region src/utils/analytics/trackEvent.d.ts
+/**
+ * Track an analytics event via the SDK's OpenPanel instance.
+ * Fire-and-forget — silently catches errors so analytics never break a
+ * partner integration.
+ *
+ * The client must be passed explicitly because the OpenPanel instance is
+ * scoped to each `FrakClient` (a partner site may hold multiple iframes).
+ *
+ * @param client - The Frak client instance (no-op if undefined)
+ * @param event - Typed event name from the SDK event map
+ * @param properties - Typed properties for the given event
+ */
+declare function trackEvent<K extends keyof SdkEventMap>(client: FrakClient | undefined, event: K, properties?: SdkEventMap[K]): void;
+//#endregion
 //#region src/utils/backendUrl.d.ts
 /**
  * Get the backend URL for API calls
@@ -143,6 +225,50 @@ declare const locales: {
  */
 declare function getBackendUrl(walletUrl?: string): string;
 //#endregion
+//#region src/utils/cache/withCache.d.ts
+type WithCacheOptions = {
+  /** The key to cache the data against */cacheKey: string; /** Time in ms that cached data will remain valid. Default: 30_000 (30s). Set to 0 to disable caching. */
+  cacheTime?: number;
+};
+/**
+ * Returns the result of a given promise, and caches the result for
+ * subsequent invocations against a provided cache key.
+ *
+ * Also deduplicates concurrent calls — if multiple callers request the same
+ * cache key while the promise is pending, they share the same promise.
+ *
+ * @example
+ * ```ts
+ * // First call fetches, subsequent calls return cached data for 30s
+ * const data = await withCache(
+ *     () => client.request({ method: "frak_getMerchantInformation" }),
+ *     { cacheKey: "merchantInfo", cacheTime: 30_000 }
+ * );
+ * ```
+ */
+declare function withCache<TData>(fn: () => Promise<TData>, {
+  cacheKey,
+  cacheTime
+}: WithCacheOptions): Promise<TData>;
+/**
+ * Get a cache handle for a specific key, useful for manual invalidation.
+ *
+ * @example
+ * ```ts
+ * // Invalidate merchant info cache after a mutation
+ * getCache("frak_getMerchantInformation").clear();
+ * ```
+ */
+declare function getCache(cacheKey: string): {
+  /** Clear both the pending promise and the cached response */clear: () => void; /** Check if a non-expired response exists */
+  has: (cacheTime?: number) => boolean;
+};
+/**
+ * Clear all cached data (both pending promises and resolved responses).
+ * Called automatically when the client is destroyed.
+ */
+declare function clearAllCache(): void;
+//#endregion
 //#region src/utils/clientId.d.ts
 /**
  * Client ID utilities for anonymous tracking
@@ -276,17 +402,25 @@ declare function parse({
 /**
  * Add or replace the `fCtx` query parameter in a URL with the given context.
  *
+ * Standard affiliation params (`utm_source`, `utm_medium`, `utm_campaign`,
+ * `ref`, `via`, ...) are always appended using gap-fill semantics: pre-existing
+ * params on the URL are preserved, defaults are derived from the context when
+ * applicable, and `attribution` overrides take precedence when provided.
+ *
  * @param args
  * @param args.url - The URL to update
  * @param args.context - The context to embed (V1 or V2)
+ * @param args.attribution - Optional attribution overrides. Defaults are applied even when omitted.
  * @returns The updated URL string, or null on failure
  */
 declare function update({
   url,
-  context
+  context,
+  attribution
 }: {
   url?: string;
   context: FrakContextV1 | FrakContextV2;
+  attribution?: AttributionParams;
 }): string | null;
 /**
  * Remove the `fCtx` query parameter from a URL.
@@ -415,47 +549,104 @@ declare function createIframe({
  */
 declare function findIframeInOpener(pathname?: string): Window | null;
 //#endregion
-//#region src/utils/merchantId.d.ts
+//#region src/utils/inAppBrowser.d.ts
+/**
+ * Whether the current device runs iOS (including iPadOS 13+).
+ */
+declare const isIOS: boolean;
 /**
- * Merchant ID utilities for auto-fetching from backend
+ * Whether the current browser is a social media in-app browser
+ * (Instagram, Facebook).
  */
+declare const isInAppBrowser: boolean;
 /**
- * Fetch merchantId from backend by domain
+ * Redirect to external browser from in-app WebView.
  *
- * @param domain - The domain to lookup (defaults to current hostname)
- * @param walletUrl - Optional wallet URL to derive backend URL
- * @returns The merchantId if found, undefined otherwise
+ * - **iOS**: Uses `x-safari-https://` scheme — server-side 302 redirects
+ *   to custom URL schemes are silently swallowed by WKWebView.
+ *   Direct `window.location.href` assignment works (confirmed iOS 17+).
  *
- * @example
- * ```ts
- * const merchantId = await fetchMerchantId("shop.example.com");
- * if (merchantId) {
- *     // Use merchantId for tracking
- * }
- * ```
+ * - **Android**: Uses backend `/common/social` endpoint which returns a PDF
+ *   Content-Type response, forcing the WebView to hand off to the default browser.
+ *
+ * @param targetUrl - The URL to open in the external browser
  */
-declare function fetchMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
+declare function redirectToExternalBrowser(targetUrl: string): void;
+//#endregion
+//#region src/utils/mergeAttribution.d.ts
 /**
- * Clear the cached merchantId
- * Useful for testing or when switching domains
+ * Inputs for {@link mergeAttribution}.
  */
-declare function clearMerchantIdCache(): void;
+type MergeAttributionInput = {
+  /**
+   * Per-call attribution override passed to actions like `displaySharingPage`.
+   *
+   * - `null` explicitly disables attribution (no UTM/ref/via params are added).
+   * - `undefined` means "no per-call override" — defaults apply if present.
+   * - An object (including `{}`) merges field-by-field with defaults.
+   */
+  perCall: AttributionParams | null | undefined;
+  /**
+   * Pre-merged merchant-level defaults (backend config > SDK static config).
+   * `utm_content` is intentionally absent from this shape.
+   */
+  defaults?: AttributionDefaults;
+  /**
+   * Per-product `utm_content` override (from the currently selected
+   * `SharingPageProduct`). Takes precedence over `perCall.utmContent`.
+   */
+  productUtmContent?: string;
+};
 /**
- * Get merchantId from config or auto-fetch from backend
+ * Merge the three attribution layers into a single {@link AttributionParams}
+ * value suitable for `FrakContextManager.update`.
  *
- * @param config - The SDK config that may contain merchantId
- * @param walletUrl - Optional wallet URL to derive backend URL
- * @returns The merchantId if available (from config or fetch), undefined otherwise
- */
-declare function resolveMerchantId(config: {
-  metadata?: {
-    merchantId?: string;
-  };
-}, walletUrl?: string): Promise<string | undefined>;
+ * Priority per field:
+ *   1. `perCall` (wins)
+ *   2. `defaults` (merchant-level, backend > SDK static, already pre-merged)
+ *   3. Hardcoded fallbacks resolved later by `FrakContextManager`
+ *
+ * Special rules:
+ * - `perCall === null` returns `undefined` (explicit disable: no UTM/ref/via).
+ * - `perCall === undefined` (no opinion) yields at least `{}` so `FrakContextManager`
+ *   applies its hardcoded defaults (utm_source=frak, utm_medium=referral,
+ *   utm_campaign=<merchantId>, ref=<clientId>, via=frak).
+ * - `utm_content` never comes from `defaults`; only `productUtmContent` or
+ *   `perCall.utmContent` can populate it.
+ */
+declare function mergeAttribution({
+  perCall,
+  defaults,
+  productUtmContent
+}: MergeAttributionInput): AttributionParams | undefined;
+//#endregion
+//#region src/utils/sdkConfigStore.d.ts
+declare const GLOBAL_KEY = "__frakSdkConfig";
+declare global {
+  interface Window {
+    [GLOBAL_KEY]?: SdkResolvedConfig;
+  }
+  interface WindowEventMap {
+    "frak:config": CustomEvent<SdkResolvedConfig>;
+  }
+}
+declare function getConfig(): SdkResolvedConfig;
+declare const sdkConfigStore: {
+  getConfig: typeof getConfig;
+  readonly isResolved: boolean;
+  readonly isCacheFresh: boolean;
+  setCacheScope(domain: string, lang?: string): void;
+  setConfig(config: SdkResolvedConfig): void;
+  reset(): void;
+  clearCache(): void;
+  resolve(domain?: string, walletUrl?: string, lang?: Language): Promise<MerchantConfigResponse | undefined>;
+  getMerchantId(): string | undefined;
+  resolveMerchantId(domain?: string, walletUrl?: string): Promise<string | undefined>;
+};
 //#endregion
 //#region src/utils/sso.d.ts
 type AppSpecificSsoMetadata = SsoMetadata & {
-  name: string;
+  name?: string;
   css?: string;
 };
 /**
@@ -489,7 +680,7 @@ type FullSsoParams = Omit<PrepareSsoParamsType, "metadata"> & {
  * // Returns: https://wallet.frak.id/sso?p=<compressed_base64>
  * ```
  */
-declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string, clientId: string, css?: string): string;
+declare function generateSsoUrl(walletUrl: string, params: PrepareSsoParamsType, merchantId: string, name: string | undefined, clientId: string, css?: string): string;
 /**
  * Type of compressed the sso data
  */
@@ -501,28 +692,13 @@ type CompressedSsoData = {
   l?: "en" | "fr";
   m: string;
   md: {
-    n: string;
+    n?: string;
     css?: string;
     l?: string;
     h?: string;
   };
 };
 //#endregion
-//#region src/utils/trackEvent.d.ts
-/**
- * Analytics event names emitted by the SDK
- */
-type FrakEvent = "share_button_clicked" | "wallet_button_clicked" | "open_in_app_clicked" | "open_in_app_login_clicked" | "app_not_installed" | "share_modal_error" | "user_referred_started" | "user_referred_completed" | "user_referred_error";
-type EventProps = Record<string, unknown>;
-/**
- * Track an analytics event via OpenPanel.
- * Fire-and-forget: silently catches errors.
- * @param client - The Frak client instance (no-op if undefined)
- * @param event - The event name to track
- * @param props - Optional event properties
- */
-declare function trackEvent(client: FrakClient | undefined, event: FrakEvent, props?: EventProps): void;
-//#endregion
 //#region src/utils/computeLegacyProductId.d.ts
 /**
  * Compute the legacy product id from a domain
@@ -534,4 +710,4 @@ declare function computeLegacyProductId({
   domain?: string;
 }): `0x${string}`;
 //#endregion
-export { getBackendUrl as A, HashProtectedData as B, triggerDeepLinkWithFallback as C, base64urlDecode as D, compressJsonToB64 as E, createIFrameFrakClient as F, TrackArrivalParams as I, TrackArrivalResult as L, locales as M, setupClient as N, base64urlEncode as O, DebugInfoGatherer as P, UtmParams as R, toAndroidIntentUrl as S, decompressJsonFromB64 as T, KeyProvider as V, formatAmount as _, CompressedSsoData as a, isChromiumAndroid as b, clearMerchantIdCache as c, baseIframeProps as d, createIframe as f, getCurrencyAmountKey as g, getSupportedCurrency as h, AppSpecificSsoMetadata as i, LocalesKey as j, getClientId as k, fetchMerchantId as l, getSupportedLocale as m, FrakEvent as n, FullSsoParams as o, findIframeInOpener as p, trackEvent as r, generateSsoUrl as s, computeLegacyProductId as t, resolveMerchantId as u, FrakContextManager as v, DEEP_LINK_SCHEME as w, isFrakDeepLink as x, DeepLinkFallbackOptions as y, CompressedData as z };
+export { getClientId as A, setupClient as B, toAndroidIntentUrl as C, compressJsonToB64 as D, decompressJsonFromB64 as E, trackEvent as F, KeyProvider as G, createIFrameFrakClient as H, SdkEventMap as I, SdkHandshakeFailureReason as L, getCache as M, withCache as N, base64urlDecode as O, getBackendUrl as P, LocalesKey as R, isFrakDeepLink as S, DEEP_LINK_SCHEME as T, CompressedData as U, DebugInfoGatherer as V, HashProtectedData as W, getCurrencyAmountKey as _, generateSsoUrl as a, DeepLinkFallbackOptions as b, mergeAttribution as c, redirectToExternalBrowser as d, baseIframeProps as f, getSupportedCurrency as g, getSupportedLocale as h, FullSsoParams as i, clearAllCache as j, base64urlEncode as k, isIOS as l, findIframeInOpener as m, AppSpecificSsoMetadata as n, sdkConfigStore as o, createIframe as p, CompressedSsoData as r, MergeAttributionInput as s, computeLegacyProductId as t, isInAppBrowser as u, formatAmount as v, triggerDeepLinkWithFallback as w, isChromiumAndroid as x, FrakContextManager as y, locales as z };

package/dist/{siweAuthenticate-CnCZ7mok.d.ts → index-CGyEOo9J.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-qjaccFd0.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,70 @@ 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/getMergeToken.d.ts
+/**
+ * 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
+ */
+declare function getMergeToken(client: FrakClient, options?: {
+  cacheTime?: number;
+}): Promise<string | null>;
+//#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 +349,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 +435,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 +493,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 +643,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 C, displayModal as S, getUserReferralStatus as _, ModalBuilder as a, ensureIdentity 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, getMergeToken as v, displaySharingPage as x, getMerchantInformation as y };