@frak-labs/core-sdk 0.1.1 → 0.2.0-beta.7898df5b

package/dist/{index-d8xS4ryI.d.ts → siweAuthenticate-CVigMOxz.d.cts}

@@ -1,13 +1,11 @@
-import { A as SiweAuthenticateReturnType, B as FinalActionType, D as SendTransactionReturnType, E as SendTransactionModalStepType, L as PrepareSsoParamsType, M as OpenInteractionSessionModalStepType, P as LoginModalStepType, R as PrepareSsoReturnType, S as ModalRpcMetadata, T as ModalStepTypes, V as FinalModalStepType, a as FrakClient, g as DisplayEmbeddedWalletResultType, h as DisplayEmbeddedWalletParamsType, i as FrakContext, j as SiweAuthenticationParams, l as WalletStatusReturnType, u as GetProductInformationReturnType, w as ModalRpcStepsResultType, x as DisplayModalParamsType } from "./openSso-DsKJ4y0j.js";
-import { n as SendInteractionParamsType, r as SendInteractionReturnType } from "./interaction-KX1h9a7V.js";
-import { Hex } from "viem";
+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";
 
 //#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
+ * @returns The embedded wallet display result
  */
 declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbeddedWalletParamsType): Promise<DisplayEmbeddedWalletResultType>;
 //#endregion
@@ -24,26 +22,22 @@ declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbedd
  *
  * @remarks
  * - The UI of the displayed modal can be configured with the `customCss` property in the `customizations.css` field of the top-level config.
- * - The `login` and `openSession` steps will be automatically skipped if the user is already logged in or has an active session. It's safe to include these steps in all cases to ensure proper user state.
+ * - The `login` step will be automatically skipped if the user is already logged in. It's safe to include this step in all cases to ensure proper user state.
  * - Steps are automatically reordered in the following sequence:
  *     1. `login` (if needed)
- *     2. `openSession` (if needed)
- *     3. All other steps in the order specified
- *     4. `success` (if included, always last)
+ *     2. All other steps in the order specified
+ *     3. `success` (if included, always last)
  *
  * @example
  * Simple sharing modal with steps:
  *  1. Login (Skipped if already logged in)
- *  2. Open a session (Skipped if already opened)
- *  3. Display a success message with sharing link option
+ *  2. Display a success message with sharing link option
  *
  * ```ts
  * const results = await displayModal(frakConfig, {
  *     steps: {
  *         // Simple login with no SSO, nor customization
  *         login: { allowSso: false },
- *         // Simple session opening, with no customization
- *         openSession: {},
  *         // Success message
  *         final: {
  *             action: { key: "reward" },
@@ -54,19 +48,14 @@ declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbedd
  * });
  *
  * console.log("Login step - wallet", results.login.wallet);
- * console.log("Open session step - start + end", {
- *     start: results.openSession.startTimestamp,
- *     end: results.openSession.endTimestamp,
- * });
  * ```
  *
  * @example
  * A full modal example, with a few customization options, with the steps:
  *  1. Login (Skipped if already logged in)
- *  2. Open a session (Skipped if already opened)
- *  3. Authenticate via SIWE
- *  4. Send a transaction
- *  5. Display a success message with sharing link options
+ *  2. Authenticate via SIWE
+ *  3. Send a transaction
+ *  4. Display a success message with sharing link options
  *
  * ```ts
  * const results = await displayModal(frakConfig, {
@@ -79,8 +68,6 @@ declare function displayEmbeddedWallet(client: FrakClient, params: DisplayEmbedd
  *                 homepageLink: "https://my-app.com",
  *             },
  *         },
- *         // Simple session opening, with no customisation
- *         openSession: {},
  *         // Siwe authentication
  *         siweAuthenticate: {
  *             siwe: {
@@ -130,13 +117,40 @@ declare function displayModal<T extends ModalStepTypes[] = ModalStepTypes[]>(cli
   metadata
 }: DisplayModalParamsType<T>): Promise<ModalRpcStepsResultType<T>>;
 //#endregion
-//#region src/actions/getProductInformation.d.ts
+//#region src/actions/ensureIdentity.d.ts
 /**
- * Function used to get the current product information
+ * Ensure the current wallet ↔ clientId link exists on the backend.
+ *
+ * Called automatically by {@link watchWalletStatus} when a connected wallet
+ * status is received. Acts as a failsafe: if the primary merge (SSO, pairing,
+ * login/register) missed or silently failed, this ensures the link is
+ * eventually established.
+ *
+ * The call is:
+ * - **Idempotent** — if already linked, backend returns immediately
+ * - **Deduplicated** — only fires once per browser session per merchant
+ * - **Fire-and-forget** — errors are logged but never thrown
+ *
+ * @param interactionToken - The SDK JWT from wallet status (x-wallet-sdk-auth)
+ *
+ * @example
+ * ```ts
+ * // Usually called automatically via watchWalletStatus side effect.
+ * // Can also be called manually if needed:
+ * await ensureIdentity("eyJhbGciOi...");
+ * ```
+ */
+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
  * @param client - The current Frak Client
- * @returns The product information in a promise
+ * @returns The merchant information including available reward tiers
+ *
+ * @see {@link @frak-labs/core-sdk!index.GetMerchantInformationReturnType | `GetMerchantInformationReturnType`} for the return type shape
  */
-declare function getProductInformation(client: FrakClient): Promise<GetProductInformationReturnType>;
+declare function getMerchantInformation(client: FrakClient): Promise<GetMerchantInformationReturnType>;
 //#endregion
 //#region src/actions/prepareSso.d.ts
 /**
@@ -174,69 +188,60 @@ declare function prepareSso(client: FrakClient, args: PrepareSsoParamsType): Pro
 //#endregion
 //#region src/actions/referral/processReferral.d.ts
 /**
- * The different states of the referral process
- * @inline
- */
-type ReferralState = "idle" | "processing" | "success" | "no-wallet" | "no-session" | "error" | "no-referrer" | "self-referral";
-/**
- * Options for the referral auto-interaction process
+ * Options for the referral auto-interaction process.
  */
 type ProcessReferralOptions = {
   /**
-   * If we want to always append the url with the frak context or not
+   * If true, always replace the URL with the current user's referral context
+   * so the next visitor gets referred by this user.
    * @defaultValue false
    */
   alwaysAppendUrl?: boolean;
+  /**
+   * Merchant ID for building the current user's referral context.
+   * Required when `alwaysAppendUrl` is true and the incoming context is V1.
+   * For V2 contexts, the merchantId is already embedded in the context.
+   */
+  merchantId?: string;
 };
 /**
- * This function handle all the heavy lifting of the referral interaction process
- *  1. Check if the user has been referred or not (if not, early exit)
- *  2. Then check if the user is logged in or not
- *  2.1 If not logged in, try a soft login, if it fail, display a modal for the user to login
- *  3. Check if that's not a self-referral (if yes, early exit)
- *  4. Check if the user has an interaction session or not
- *  4.1 If not, display a modal for the user to open a session
- *  5. Push the referred interaction
- *  6. Update the current url with the right data
- *  7. Return the resulting referral state
- *
- *  If any error occurs during the process, the function will catch it and return an error state
+ * The different states of the referral process.
+ * @inline
+ */
+type ReferralState = "idle" | "processing" | "success" | "no-referrer" | "self-referral";
+/**
+ * Handle the full referral interaction flow:
+ *
+ *  1. Check if the user has been referred (if not, early exit)
+ *  2. Preflight self-referral check (if yes, early exit)
+ *  3. Track the arrival event
+ *  4. Replace the current URL with the user's own referral context
+ *  5. Return the resulting referral state
  *
  * @param client - The current Frak Client
  * @param args
  * @param args.walletStatus - The current user wallet status
- * @param args.frakContext - The current frak context
- * @param args.modalConfig - The modal configuration to display if the user is not logged in
- * @param args.productId - The product id to interact with (if not specified will be recomputed from the current domain)
- * @param args.options - Some options for the referral interaction
- * @returns  A promise with the resulting referral state
+ * @param args.frakContext - The referral context parsed from the URL
+ * @param args.options - Options for URL replacement and merchant context
+ * @returns The referral state
  *
- * @see {@link displayModal} for more details about the displayed modal
- * @see {@link sendInteraction} for more details on the interaction submission part
- * @see {@link ReferralInteractionEncoder} for more details about the referred interaction
- * @see {@link @frak-labs/core-sdk!ModalStepTypes} for more details on each modal steps types
+ * @see {@link @frak-labs/core-sdk!ModalStepTypes} for modal step types
  */
 declare function processReferral(client: FrakClient, {
   walletStatus,
   frakContext,
-  modalConfig,
-  productId,
   options
 }: {
   walletStatus?: WalletStatusReturnType;
-  frakContext?: Partial<FrakContext> | null;
-  modalConfig?: DisplayEmbeddedWalletParamsType;
-  productId?: Hex;
+  frakContext?: FrakContext | null;
   options?: ProcessReferralOptions;
-}): Promise<ReferralState>;
+}): ReferralState;
 //#endregion
 //#region src/actions/referral/referralInteraction.d.ts
 /**
- * Function used to display a modal
+ * Function used to handle referral interactions
  * @param client - The current Frak Client
  * @param args
- * @param args.productId - The product id to interact with (if not specified will be recomputed from the current domain)
- * @param args.modalConfig - The modal configuration to display if the user is not logged in
  * @param args.options - Some options for the referral interaction
  *
  * @returns  A promise with the resulting referral state, or undefined in case of an error
@@ -244,38 +249,53 @@ declare function processReferral(client: FrakClient, {
  * @description This function will automatically handle the referral interaction process
  *
  * @see {@link processReferral} for more details on the automatic referral handling process
- * @see {@link @frak-labs/core-sdk!ModalStepTypes} for more details on each modal steps types
  */
 declare function referralInteraction(client: FrakClient, {
-  productId,
-  modalConfig,
   options
 }?: {
-  productId?: Hex;
-  modalConfig?: DisplayEmbeddedWalletParamsType;
   options?: ProcessReferralOptions;
-}): Promise<("no-referrer" | "self-referral" | "success" | "idle" | "processing" | "no-wallet" | "no-session" | "error") | undefined>;
+}): Promise<("idle" | "processing" | "success" | "no-referrer" | "self-referral") | undefined>;
 //#endregion
 //#region src/actions/sendInteraction.d.ts
 /**
- * Function used to send an interaction
- * @param client - The current Frak Client
- * @param args
+ * Send an interaction to the backend via the listener RPC.
+ * Fire-and-forget: errors are caught and logged, not thrown.
+ *
+ * @param client - The Frak client instance
+ * @param params - The interaction parameters
+ *
+ * @description Sends a user interaction event through the wallet iframe RPC. Supports three interaction types: arrival tracking, sharing events, and custom interactions.
  *
  * @example
- * const interaction = PressInteractionEncoder.openArticle({
- *     articleId: keccak256(toHex("article-slug")),
+ * Track a user arrival with referral attribution:
+ * ```ts
+ * await sendInteraction(client, {
+ *     type: "arrival",
+ *     referrerWallet: "0x1234...abcd",
+ *     landingUrl: window.location.href,
+ *     utmSource: "twitter",
+ *     utmMedium: "social",
+ *     utmCampaign: "launch-2026",
  * });
- * const { delegationId } = await sendInteraction(frakConfig, {
- *     interaction,
+ * ```
+ *
+ * @example
+ * Track a sharing event:
+ * ```ts
+ * await sendInteraction(client, { type: "sharing" });
+ * ```
+ *
+ * @example
+ * Send a custom interaction:
+ * ```ts
+ * await sendInteraction(client, {
+ *     type: "custom",
+ *     customType: "newsletter_signup",
+ *     data: { email: "user@example.com" },
  * });
- * console.log("Delegated interaction id", delegationId);
+ * ```
  */
-declare function sendInteraction(client: FrakClient, {
-  productId,
-  interaction,
-  validation
-}: SendInteractionParamsType): Promise<SendInteractionReturnType>;
+declare function sendInteraction(client: FrakClient, params: SendInteractionParamsType): Promise<void>;
 //#endregion
 //#region src/actions/trackPurchaseStatus.d.ts
 /**
@@ -285,6 +305,7 @@ declare function sendInteraction(client: FrakClient, {
  * @param args.customerId - The customer id that made the purchase (on your side)
  * @param args.orderId - The order id of the purchase (on your side)
  * @param args.token - The token of the purchase
+ * @param args.merchantId - Optional explicit merchant id to use for the tracking request
  *
  * @description This function will send a request to the backend to listen for the purchase status.
  *
@@ -294,19 +315,23 @@ declare function sendInteraction(client: FrakClient, {
  *     customerId: checkout.order.customer.id,
  *     orderId: checkout.order.id,
  *     token: checkout.token,
+ *     merchantId: "your-merchant-id",
  *   };
  *
  *   await trackPurchaseStatus(payload);
  * }
  *
  * @remarks
- * - The `trackPurchaseStatus` function requires the `frak-wallet-interaction-token` stored in the session storage to authenticate the request.
- * - This function will print a warning if used in a non-browser environment or if the wallet interaction token is not available.
+ * - Merchant id is resolved in this order: explicit `args.merchantId`, `frak-merchant-id` from session storage, then `fetchMerchantId()`.
+ * - 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.
  */
 declare function trackPurchaseStatus(args: {
   customerId: string | number;
   orderId: string | number;
   token: string;
+  merchantId?: string;
 }): Promise<void>;
 //#endregion
 //#region src/actions/watchWalletStatus.d.ts
@@ -322,7 +347,6 @@ declare function trackPurchaseStatus(args: {
  * await watchWalletStatus(frakConfig, (status: WalletStatusReturnType) => {
  *     if (status.key === "connected") {
  *         console.log("Wallet connected:", status.wallet);
- *         console.log("Current interaction session:", status.interactionSession);
  *     } else {
  *         console.log("Wallet not connected");
  *     }
@@ -362,16 +386,15 @@ type ModalStepBuilder<Steps extends ModalStepTypes[] = ModalStepTypes[]> = {
 /**
  * Represent the output type of the modal builder
  */
-type ModalBuilder = ModalStepBuilder<[LoginModalStepType, OpenInteractionSessionModalStepType]>;
+type ModalBuilder = ModalStepBuilder<[LoginModalStepType]>;
 /**
  * Helper to craft Frak modal, and share a base initial config
  * @param client - The current Frak Client
  * @param args
  * @param args.metadata - Common modal metadata (customisation, language etc)
  * @param args.login - Login step parameters
- * @param args.openSession - Open session step parameters
  *
- * @description This function will create a modal builder with the provided metadata, login and open session parameters.
+ * @description This function will create a modal builder with the provided metadata and login parameters.
  *
  * @example
  * Here is an example of how to use the `modalBuilder` to create and display a sharing modal:
@@ -400,12 +423,10 @@ type ModalBuilder = ModalStepBuilder<[LoginModalStepType, OpenInteractionSession
  */
 declare function modalBuilder(client: FrakClient, {
   metadata,
-  login,
-  openSession
+  login
 }: {
   metadata?: ModalRpcMetadata;
   login?: LoginModalStepType["params"];
-  openSession?: OpenInteractionSessionModalStepType["params"];
 }): ModalBuilder;
 //#endregion
 //#region src/actions/wrapper/sendTransaction.d.ts
@@ -508,4 +529,4 @@ declare function siweAuthenticate(client: FrakClient, {
   metadata
 }: SiweAuthenticateModalParams): Promise<SiweAuthenticateReturnType>;
 //#endregion
-export { displayEmbeddedWallet as _, ModalBuilder as a, watchWalletStatus as c, referralInteraction as d, ProcessReferralOptions as f, displayModal as g, getProductInformation 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 };
+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 };