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

package/dist/{openSso-B0g7-807.d.cts → openSso-CMZM06uR.d.ts}

@@ -1,6 +1,6 @@
-import { OpenPanel } from "@openpanel/web";
-import { LifecycleMessage, RpcClient } from "@frak-labs/frame-connector";
 import { Address, Hex } from "viem";
+import { LifecycleMessage, RpcClient } from "@frak-labs/frame-connector";
+import { OpenPanel } from "@openpanel/web";
 import { SiweMessage } from "viem/siwe";
 
 //#region src/types/config.d.ts
@@ -31,7 +31,7 @@ type FrakWalletSdkConfig = {
     /**
      * Your application name (will be displayed in a few modals and in SSO)
      */
-    name: string;
+    name?: string;
     /**
      * Your merchant ID from the Frak dashboard (UUID format)
      * Used for referral tracking and analytics
@@ -75,6 +75,13 @@ type FrakWalletSdkConfig = {
    * @defaultValue window.location.host
    */
   domain?: string;
+  /**
+   * Wait for backend config before rendering components.
+   * When true (default), components show a spinner until backend config is resolved.
+   * When false, components render immediately with SDK static config / HTML attributes.
+   * @defaultValue true
+   */
+  waitForBackendConfig?: boolean;
 };
 /**
  * Custom i18n configuration for the modal
@@ -111,19 +118,115 @@ type FrakWalletSdkConfig = {
  */
 type I18nConfig = Record<Language, LocalizedI18nConfig> | LocalizedI18nConfig;
 /**
- * A localized i18n config
+ * A localized i18n config (inline objects only — URL-based i18n removed)
  * @category Config
  */
-type LocalizedI18nConfig = `${string}.css` | {
+type LocalizedI18nConfig = {
   [key: string]: string;
 };
 //#endregion
+//#region src/types/resolvedConfig.d.ts
+/**
+ * Response from the merchant resolve endpoint
+ * @category Config
+ */
+type MerchantConfigResponse = {
+  merchantId: string;
+  name: string;
+  domain: string;
+  allowedDomains: string[];
+  sdkConfig?: ResolvedSdkConfig;
+};
+/**
+ * Resolved placement config from backend
+ * Translations already flattened: default + lang-specific merged into one record
+ * @category Config
+ */
+type ResolvedPlacement = {
+  /** Per-component configuration within this placement */components?: {
+    buttonShare?: {
+      text?: string;
+      noRewardText?: string;
+      clickAction?: "embedded-wallet" | "share-modal" | "sharing-page";
+      useReward?: boolean;
+      css?: string;
+    };
+    buttonWallet?: {
+      position?: "right" | "left";
+      css?: string;
+    };
+    openInApp?: {
+      text?: string;
+      css?: string;
+    };
+    postPurchase?: {
+      refereeText?: string;
+      refereeNoRewardText?: string;
+      referrerText?: string;
+      referrerNoRewardText?: string;
+      ctaText?: string;
+      ctaNoRewardText?: string;
+      css?: string;
+    };
+    banner?: {
+      referralTitle?: string;
+      referralDescription?: string;
+      referralCta?: string;
+      inappTitle?: string;
+      inappDescription?: string;
+      inappCta?: string;
+      css?: string;
+    };
+  };
+  targetInteraction?: string; /** Already flattened: default + lang-specific merged into one record */
+  translations?: Record<string, string>; /** Global placement CSS (applied to modals/listener) */
+  css?: string;
+};
+/**
+ * Resolved SDK config from backend `/resolve` endpoint
+ * Language resolution and translation merging already applied
+ * @category Config
+ */
+type ResolvedSdkConfig = {
+  name?: string;
+  logoUrl?: string;
+  homepageLink?: string;
+  currency?: Currency;
+  lang?: Language; /** When true, all SDK components should be hidden */
+  hidden?: boolean;
+  css?: string;
+  translations?: Record<string, string>;
+  placements?: Record<string, ResolvedPlacement>;
+};
+/**
+ * Internal SDK config store state
+ * Merged config: backend > SDK static > defaults
+ * Components subscribe to this reactively
+ * @category Config
+ */
+type SdkResolvedConfig = {
+  /** Whether the backend config has been resolved */isResolved: boolean; /** Merchant ID from resolution */
+  merchantId: string; /** Domain returned by the resolve endpoint */
+  domain?: string; /** Domains allowed for this merchant (used by iframe trust check) */
+  allowedDomains?: string[]; /** Whether the resolve returned a backend sdkConfig object */
+  hasRawSdkConfig?: boolean; /** Merged metadata fields */
+  name?: string;
+  logoUrl?: string;
+  homepageLink?: string;
+  lang?: Language;
+  currency?: Currency; /** When true, all SDK components should be hidden */
+  hidden?: boolean; /** Global CSS from backend config (passed to iframe) */
+  css?: string; /** Global translations (for reference / component fallback) */
+  translations?: Record<string, string>; /** Named placements (keyed by placement ID) */
+  placements?: Record<string, ResolvedPlacement>;
+};
+//#endregion
 //#region src/types/lifecycle/client.d.ts
 /**
  * Event related to the iframe lifecycle
  * @ignore
  */
-type ClientLifecycleEvent = CustomCssEvent | CustomI18nEvent | RestoreBackupEvent | HearbeatEvent | HandshakeResponse | SsoRedirectCompleteEvent | DeepLinkFailedEvent;
+type ClientLifecycleEvent = CustomCssEvent | CustomI18nEvent | RestoreBackupEvent | HearbeatEvent | SsoRedirectCompleteEvent | DeepLinkFailedEvent | ResolvedConfigEvent;
 type CustomCssEvent = {
   clientLifecycle: "modal-css";
   data: {
@@ -146,30 +249,6 @@ type HearbeatEvent = {
   clientLifecycle: "heartbeat";
   data?: never;
 };
-type HandshakeResponse = {
-  clientLifecycle: "handshake-response";
-  data: {
-    token: string;
-    currentUrl: string;
-    /**
-     * Pending merge token extracted from URL (?fmt= parameter)
-     * When present, listener should execute identity merge in background
-     * URL is cleaned after handshake response is sent
-     */
-    pendingMergeToken?: string;
-    /**
-     * Client ID for identity tracking (belt & suspenders fallback)
-     * Primary delivery is via iframe URL query param; handshake is backup for SSR
-     */
-    clientId?: string;
-    /**
-     * Explicit domain from SDK config (FrakWalletSdkConfig.domain)
-     * When present, listener should prefer this over URL-derived domain
-     * for merchant resolution (handles proxied/tunneled environments)
-     */
-    configDomain?: string;
-  };
-};
 type SsoRedirectCompleteEvent = {
   clientLifecycle: "sso-redirect-complete";
   data: {
@@ -182,6 +261,21 @@ type DeepLinkFailedEvent = {
     originalUrl: string;
   };
 };
+type ResolvedConfigEvent = {
+  clientLifecycle: "resolved-config";
+  data: {
+    merchantId: string; /** The domain the backend resolved this config for */
+    domain: string; /** All domains registered for this merchant (for domain proof) */
+    allowedDomains: string[]; /** Full URL of the parent page (for interaction tracking) */
+    sourceUrl: string;
+    /**
+     * Pending merge token extracted from URL (?fmt= parameter).
+     * When present, listener should execute identity merge in background.
+     */
+    pendingMergeToken?: string;
+    sdkConfig?: ResolvedSdkConfig;
+  };
+};
 //#endregion
 //#region src/types/lifecycle/iframe.d.ts
 /**
@@ -191,19 +285,13 @@ type DeepLinkFailedEvent = {
 type IFrameLifecycleEvent = {
   iframeLifecycle: "connected" | "show" | "hide" | "remove-backup";
   data?: never;
-} | DoBackupEvent | HandshakeRequestEvent | RedirectRequestEvent;
+} | DoBackupEvent | RedirectRequestEvent;
 type DoBackupEvent = {
   iframeLifecycle: "do-backup";
   data: {
     backup?: string;
   };
 };
-type HandshakeRequestEvent = {
-  iframeLifecycle: "handshake";
-  data: {
-    token: string;
-  };
-};
 type RedirectRequestEvent = {
   iframeLifecycle: "redirect";
   data: {
@@ -534,6 +622,80 @@ type DisplayModalParamsType<T extends ModalStepTypes[]> = {
   metadata?: ModalRpcMetadata;
 };
 //#endregion
+//#region src/types/rpc/displaySharingPage.d.ts
+/**
+ * Product information to display on the sharing page
+ * @group Sharing Page
+ */
+type SharingPageProduct = {
+  /**
+   * The product title / name
+   */
+  title: string;
+  /**
+   * Optional product image URL
+   */
+  imageUrl?: string;
+};
+/**
+ * Parameters to display the sharing page
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+type DisplaySharingPageParamsType = {
+  /**
+   * Products to showcase on the sharing page
+   * If provided, they will be displayed in a product card section
+   */
+  products?: SharingPageProduct[];
+  /**
+   * Optional link override for sharing
+   * If not provided, the sharing link will be generated from the current page URL + merchant context
+   */
+  link?: string;
+  /**
+   * Optional metadata overrides for the sharing page
+   */
+  metadata?: {
+    /**
+     * Logo override for the sharing page header
+     */
+    logo?: string;
+    /**
+     * Link to the homepage of the calling website
+     */
+    homepageLink?: string;
+    /**
+     * The target interaction behind this sharing page
+     */
+    targetInteraction?: InteractionTypeKey;
+    /**
+     * i18n overrides for the sharing page
+     */
+    i18n?: I18nConfig;
+  };
+};
+/**
+ * Result of the sharing page display
+ * @group Sharing Page
+ * @group RPC Schema
+ */
+type DisplaySharingPageResultType = {
+  /**
+   * The action the user took
+   * - "shared": User used the native share dialog
+   * - "copied": User copied the link to clipboard
+   * - "dismissed": User dismissed the sharing page without acting
+   */
+  action: "shared" | "copied" | "dismissed";
+  /**
+   * The install URL for the Frak app
+   * Can be used as a fallback to redirect the user to the install page
+   * from the merchant's top-level page (e.g. via `window.location.href`)
+   */
+  installUrl?: string;
+};
+//#endregion
 //#region src/types/rpc/embedded/loggedIn.d.ts
 /**
  * The different type of action we can have on the embedded view (once the user is logged in)
@@ -691,7 +853,9 @@ type SendInteractionParamsType = {
   utmTerm?: string;
   utmContent?: string;
 } | {
-  type: "sharing";
+  type: "sharing"; /** Epoch seconds timestamp matching the V2 context `t` field embedded in the referral link URL, used for backend correlation */
+  sharingTimestamp?: number; /** Merchant order ID linking this sharing event to a purchase (stays server-side, never in URL) */
+  purchaseId?: string;
 } | {
   type: "custom";
   customType: string;
@@ -769,6 +933,28 @@ type GetMerchantInformationReturnType = {
   }[];
 };
 //#endregion
+//#region src/types/rpc/userReferralStatus.d.ts
+/**
+ * User referral status returned by `frak_getUserReferralStatus`.
+ *
+ * Generic referral context for the current user on a merchant.
+ * Used by components like `<frak-post-purchase>` and `<frak-referred-banner>`
+ * to adapt their display based on the user's referral relationship.
+ *
+ * Returns `null` when the user's identity cannot be resolved
+ * (e.g. no clientId and no wallet session).
+ *
+ * @group RPC Schema
+ */
+type UserReferralStatusType = {
+  /**
+   * Whether the user was referred to this merchant by someone else.
+   *
+   * `true` means a referral link exists where this user is the referee.
+   */
+  isReferred: boolean;
+};
+//#endregion
 //#region src/types/rpc/walletStatus.d.ts
 /**
  * RPC Response for the method `frak_listenToWalletStatus`
@@ -815,7 +1001,7 @@ type WalletNotConnected = {
  *  - Response Type: stream (emits updates when wallet status changes)
  *
  * #### frak_displayModal
- * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
  * - Returns: {@link ModalRpcStepsResultType}
  * - Response Type: promise (one-shot)
  *
@@ -830,9 +1016,14 @@ type WalletNotConnected = {
  *  - Response Type: promise (one-shot)
  *
  * #### frak_displayEmbeddedWallet
- * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
  * - Returns: {@link DisplayEmbeddedWalletResultType}
  * - Response Type: promise (one-shot)
+ *
+ * #### frak_displaySharingPage
+ * - Params: [request: {@link DisplaySharingPageParamsType}, configMetadata: {@link FrakWalletSdkConfig}["metadata"], placement?: string]
+ * - Returns: {@link DisplaySharingPageResultType}
+ * - Response Type: promise (one-shot)
  */
 type IFrameRpcSchema = [
 /**
@@ -850,7 +1041,7 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_displayModal";
-  Parameters: [requests: ModalRpcStepsInput, metadata: ModalRpcMetadata | undefined, configMetadata: FrakWalletSdkConfig["metadata"]];
+  Parameters: [requests: ModalRpcStepsInput, metadata: ModalRpcMetadata | undefined, configMetadata: FrakWalletSdkConfig["metadata"], placement?: string];
   ReturnType: ModalRpcStepsResultType;
 },
 /**
@@ -860,7 +1051,7 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_prepareSso";
-  Parameters: [params: PrepareSsoParamsType, name: string, customCss?: string];
+  Parameters: [params: PrepareSsoParamsType, name?: string, customCss?: string];
   ReturnType: PrepareSsoReturnType;
 },
 /**
@@ -871,7 +1062,7 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_openSso";
-  Parameters: [params: OpenSsoParamsType, name: string, customCss?: string];
+  Parameters: [params: OpenSsoParamsType, name?: string, customCss?: string];
   ReturnType: OpenSsoReturnType;
 },
 /**
@@ -892,14 +1083,14 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_displayEmbeddedWallet";
-  Parameters: [request: DisplayEmbeddedWalletParamsType, metadata: FrakWalletSdkConfig["metadata"]];
+  Parameters: [request: DisplayEmbeddedWalletParamsType, metadata: FrakWalletSdkConfig["metadata"], placement?: string];
   ReturnType: DisplayEmbeddedWalletResultType;
 },
 /**
  * Method to send interactions (arrival, sharing, custom events)
  * Fire-and-forget method - no return value expected
  * merchantId is resolved from context
- * clientId is passed via metadata as safeguard against handshake race condition
+ * clientId is passed via metadata as safeguard against race conditions
  */
 {
   Method: "frak_sendInteraction";
@@ -907,6 +1098,27 @@ type IFrameRpcSchema = [
     clientId?: string;
   }];
   ReturnType: undefined;
+},
+/**
+ * Method to get the current user's referral status on this merchant.
+ * Returns whether the user was referred (has a referral link as referee).
+ * Returns null when the user's identity cannot be resolved.
+ * This is a one-shot request.
+ */
+{
+  Method: "frak_getUserReferralStatus";
+  Parameters?: undefined;
+  ReturnType: UserReferralStatusType | null;
+},
+/**
+ * Method to display a sharing page with product info and sharing buttons
+ * Resolves on first user action (share/copy) but the page stays visible
+ * This is a one-shot request
+ */
+{
+  Method: "frak_displaySharingPage";
+  Parameters: [request: DisplaySharingPageParamsType, configMetadata: FrakWalletSdkConfig["metadata"], placement?: string];
+  ReturnType: DisplaySharingPageResultType;
 }];
 //#endregion
 //#region src/types/transport.d.ts
@@ -1052,4 +1264,4 @@ declare const ssoPopupName = "frak-sso";
  */
 declare function openSso(client: FrakClient, args: OpenSsoParamsType): Promise<OpenSsoReturnType>;
 //#endregion
-export { SendTransactionModalStepType as A, PrepareSsoReturnType as B, EmbeddedViewActionSharing as C, ModalRpcStepsInput as D, ModalRpcMetadata as E, SiweAuthenticationParams as F, InteractionTypeKey as G, FinalActionType as H, LoginModalStepType as I, Currency as J, IFrameLifecycleEvent as K, OpenSsoParamsType as L, SendTransactionTxType as M, SiweAuthenticateModalStepType as N, ModalRpcStepsResultType as O, SiweAuthenticateReturnType as P, LocalizedI18nConfig as Q, OpenSsoReturnType as R, EmbeddedViewActionReferred as S, DisplayModalParamsType as T, FinalModalStepType as U, SsoMetadata as V, ModalStepMetadata as W, I18nConfig as X, FrakWalletSdkConfig as Y, Language as Z, TokenAmountType as _, FrakContextV1 as a, DisplayEmbeddedWalletResultType as b, isV2Context as c, IFrameTransport as d, IFrameRpcSchema as f, RewardTier as g, GetMerchantInformationReturnType as h, FrakContext as i, SendTransactionReturnType as j, ModalStepTypes as k, FrakClient as l, EstimatedReward as m, ssoPopupFeatures as n, FrakContextV2 as o, WalletStatusReturnType as p, ClientLifecycleEvent as q, ssoPopupName as r, isV1Context as s, openSso as t, FrakLifecycleEvent as u, SendInteractionParamsType as v, LoggedInEmbeddedView as w, LoggedOutEmbeddedView as x, DisplayEmbeddedWalletParamsType as y, PrepareSsoParamsType as z };
+export { ResolvedPlacement as $, ModalRpcMetadata as A, LoginModalStepType as B, EmbeddedViewActionReferred as C, DisplaySharingPageResultType as D, DisplaySharingPageParamsType as E, SendTransactionReturnType as F, SsoMetadata as G, OpenSsoReturnType as H, SendTransactionTxType as I, ModalStepMetadata as J, FinalActionType as K, SiweAuthenticateModalStepType as L, ModalRpcStepsResultType as M, ModalStepTypes as N, SharingPageProduct as O, SendTransactionModalStepType as P, MerchantConfigResponse as Q, SiweAuthenticateReturnType as R, LoggedOutEmbeddedView as S, LoggedInEmbeddedView as T, PrepareSsoParamsType as U, OpenSsoParamsType as V, PrepareSsoReturnType as W, IFrameLifecycleEvent as X, InteractionTypeKey as Y, ClientLifecycleEvent as Z, RewardTier as _, FrakContextV1 as a, Language as at, DisplayEmbeddedWalletParamsType as b, isV2Context as c, IFrameTransport as d, ResolvedSdkConfig as et, IFrameRpcSchema as f, GetMerchantInformationReturnType as g, EstimatedReward as h, FrakContext as i, I18nConfig as it, ModalRpcStepsInput as j, DisplayModalParamsType as k, FrakClient as l, UserReferralStatusType as m, ssoPopupFeatures as n, Currency as nt, FrakContextV2 as o, LocalizedI18nConfig as ot, WalletStatusReturnType as p, FinalModalStepType as q, ssoPopupName as r, FrakWalletSdkConfig as rt, isV1Context as s, openSso as t, SdkResolvedConfig as tt, FrakLifecycleEvent as u, TokenAmountType as v, EmbeddedViewActionSharing as w, DisplayEmbeddedWalletResultType as x, SendInteractionParamsType as y, SiweAuthenticationParams as z };