@frak-labs/core-sdk 0.2.0 → 0.2.1-beta.06c52c98

package/dist/{openSso-BCJGchIb.d.cts → openSso-B8v3Vtnh.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,97 @@ 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";
+      useReward?: boolean;
+      css?: string;
+    };
+    buttonWallet?: {
+      position?: "bottom-right" | "bottom-left";
+      css?: string;
+    };
+    openInApp?: {
+      text?: 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 +231,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 +243,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 +267,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: {
@@ -679,8 +749,11 @@ type DisplayEmbeddedWalletResultType = {
  * @group RPC Schema
  */
 type SendInteractionParamsType = {
-  type: "arrival";
+  type: "arrival"; /** @deprecated V1 legacy — use referrerClientId for v2 */
   referrerWallet?: Address;
+  referrerClientId?: string;
+  referrerMerchantId?: string; /** Epoch seconds timestamp from the referral link creation */
+  referralTimestamp?: number;
   landingUrl?: string;
   utmSource?: string;
   utmMedium?: string;
@@ -688,7 +761,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;
@@ -812,7 +887,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)
  *
@@ -827,7 +902,7 @@ 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)
  */
@@ -847,7 +922,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;
 },
 /**
@@ -857,7 +932,7 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_prepareSso";
-  Parameters: [params: PrepareSsoParamsType, name: string, customCss?: string];
+  Parameters: [params: PrepareSsoParamsType, name?: string, customCss?: string];
   ReturnType: PrepareSsoReturnType;
 },
 /**
@@ -868,7 +943,7 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_openSso";
-  Parameters: [params: OpenSsoParamsType, name: string, customCss?: string];
+  Parameters: [params: OpenSsoParamsType, name?: string, customCss?: string];
   ReturnType: OpenSsoReturnType;
 },
 /**
@@ -889,14 +964,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";
@@ -951,15 +1026,45 @@ type FrakClient = {
 //#endregion
 //#region src/types/context.d.ts
 /**
- * The current Frak Context
+ * V1 (legacy) Frak Context — contains only the referrer wallet address.
+ * Used for backward compatibility with old sharing links.
+ * @ignore
+ */
+type FrakContextV1 = {
+  /** Referrer wallet address */r: Address;
+};
+/**
+ * V2 Frak Context — anonymous-first referral context.
+ * Contains the sharer's clientId, merchantId, and link creation timestamp.
+ * @ignore
+ */
+type FrakContextV2 = {
+  /** Version discriminator */v: 2; /** Sharer's anonymous clientId (UUID from localStorage) */
+  c: string; /** Merchant ID (UUID) */
+  m: string; /** Link creation timestamp (epoch seconds) */
+  t: number;
+};
+/**
+ * The current Frak Context — union of all versions.
  *
- * For now, only contain a referrer address.
+ * - No `v` field → V1 (legacy wallet address)
+ * - `v: 2` → V2 (anonymous clientId-based)
  *
  * @ignore
  */
-type FrakContext = {
-  r: Address;
-};
+type FrakContext = FrakContextV1 | FrakContextV2;
+/**
+ * Type guard: check if a context is V1 (legacy wallet address).
+ * @param ctx - The Frak context to check
+ * @returns True if the context is a V1 context
+ */
+declare function isV1Context(ctx: FrakContext): ctx is FrakContextV1;
+/**
+ * Type guard: check if a context is V2 (anonymous clientId-based).
+ * @param ctx - The Frak context to check
+ * @returns True if the context is a V2 context
+ */
+declare function isV2Context(ctx: FrakContext): ctx is FrakContextV2;
 //#endregion
 //#region src/actions/openSso.d.ts
 declare const ssoPopupFeatures = "menubar=no,status=no,scrollbars=no,fullscreen=no,width=500, height=800";
@@ -1019,4 +1124,4 @@ declare const ssoPopupName = "frak-sso";
  */
 declare function openSso(client: FrakClient, args: OpenSsoParamsType): Promise<OpenSsoReturnType>;
 //#endregion
-export { SiweAuthenticateReturnType as A, ModalStepMetadata as B, ModalRpcStepsInput as C, SendTransactionReturnType as D, SendTransactionModalStepType as E, PrepareSsoParamsType as F, FrakWalletSdkConfig as G, IFrameLifecycleEvent as H, PrepareSsoReturnType as I, LocalizedI18nConfig as J, I18nConfig as K, SsoMetadata as L, LoginModalStepType as M, OpenSsoParamsType as N, SendTransactionTxType as O, OpenSsoReturnType as P, FinalActionType as R, ModalRpcMetadata as S, ModalStepTypes as T, ClientLifecycleEvent as U, InteractionTypeKey as V, Currency as W, LoggedOutEmbeddedView as _, FrakClient as a, LoggedInEmbeddedView as b, IFrameRpcSchema as c, GetMerchantInformationReturnType as d, RewardTier as f, DisplayEmbeddedWalletResultType as g, DisplayEmbeddedWalletParamsType as h, FrakContext as i, SiweAuthenticationParams as j, SiweAuthenticateModalStepType as k, WalletStatusReturnType as l, SendInteractionParamsType as m, ssoPopupFeatures as n, FrakLifecycleEvent as o, TokenAmountType as p, Language as q, ssoPopupName as r, IFrameTransport as s, openSso as t, EstimatedReward as u, EmbeddedViewActionReferred as v, ModalRpcStepsResultType as w, DisplayModalParamsType as x, EmbeddedViewActionSharing as y, FinalModalStepType as z };
+export { FrakWalletSdkConfig as $, 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, MerchantConfigResponse as J, IFrameLifecycleEvent as K, OpenSsoParamsType as L, SendTransactionTxType as M, SiweAuthenticateModalStepType as N, ModalRpcStepsResultType as O, SiweAuthenticateReturnType as P, Currency as Q, OpenSsoReturnType as R, EmbeddedViewActionReferred as S, DisplayModalParamsType as T, FinalModalStepType as U, SsoMetadata as V, ModalStepMetadata as W, ResolvedSdkConfig as X, ResolvedPlacement as Y, SdkResolvedConfig as Z, TokenAmountType as _, FrakContextV1 as a, DisplayEmbeddedWalletResultType as b, isV2Context as c, IFrameTransport as d, I18nConfig as et, 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, LocalizedI18nConfig as nt, FrakContextV2 as o, WalletStatusReturnType as p, ClientLifecycleEvent as q, ssoPopupName as r, isV1Context as s, openSso as t, Language as tt, FrakLifecycleEvent as u, SendInteractionParamsType as v, LoggedInEmbeddedView as w, LoggedOutEmbeddedView as x, DisplayEmbeddedWalletParamsType as y, PrepareSsoParamsType as z };