@frak-labs/core-sdk 0.2.1 → 1.0.0-beta.0cd79998

package/dist/{openSso-B0g7-807.d.cts → openSso-BQ-q-_Y9.d.ts}

@@ -1,8 +1,65 @@
-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/tracking.d.ts
+type UtmParams = {
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  term?: string;
+  content?: string;
+};
+/**
+ * Attribution parameters appended to outbound sharing URLs.
+ *
+ * Defaults are derived from the V2 Frak context when available:
+ * - `utmSource`: `"frak"`
+ * - `utmMedium`: `"referral"`
+ * - `utmCampaign`: merchantId (`context.m`)
+ * - `via`: `"frak"`
+ * - `ref`: clientId (`context.c`)
+ *
+ * Fields explicitly set here override the defaults. Existing params on the
+ * base URL are preserved (gap-fill policy) to respect merchant-provided UTMs.
+ */
+type AttributionParams = {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmContent?: string;
+  utmTerm?: string;
+  via?: string;
+  ref?: string;
+};
+/**
+ * Merchant-level attribution defaults.
+ *
+ * Same shape as {@link AttributionParams} minus `utmContent`, because
+ * `utm_content` describes the specific content/creative being shared and is
+ * inherently per-call or per-product (never a merchant-wide default).
+ *
+ * Used as the shape for both:
+ * - `FrakWalletSdkConfig.attribution` (SDK-side compile-time defaults)
+ * - Backend merchant-config attribution (dashboard-driven defaults)
+ */
+type AttributionDefaults = Omit<AttributionParams, "utmContent">;
+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/types/config.d.ts
 /**
  * All the currencies available
@@ -31,7 +88,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 +132,20 @@ 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;
+  /**
+   * Default attribution params (UTM / via / ref) appended to outbound
+   * sharing URLs. Per-call `displaySharingPage` overrides win, then backend
+   * config, then this SDK-level default. `utm_content` is intentionally
+   * excluded — it is per-content/per-product, never a merchant-wide default.
+   */
+  attribution?: AttributionDefaults;
 };
 /**
  * Custom i18n configuration for the modal
@@ -111,19 +182,125 @@ 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?: {
+      badgeText?: string;
+      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>; /** Global component defaults (used when no placement override exists) */
+  components?: ResolvedPlacement["components"];
+  /**
+   * Default attribution params applied when building outbound sharing URLs.
+   * Per-call overrides win over these backend defaults; `utm_content` is
+   * intentionally excluded (per-content/per-product, never a merchant default).
+   */
+  attribution?: AttributionDefaults;
+};
+/**
+ * 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>; /** Global component defaults (fallback for placement-level overrides) */
+  components?: ResolvedPlacement["components"]; /** Merged attribution defaults: backend > SDK static config */
+  attribution?: AttributionDefaults;
+};
+//#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 +323,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 +335,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 +359,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: {
@@ -218,6 +380,13 @@ type RedirectRequestEvent = {
      * Used when redirecting out of social browsers to preserve identity across contexts
      */
     mergeToken?: string;
+    /**
+     * When true, open the URL in a new tab via window.open(_blank)
+     * instead of navigating the current page.
+     * Requires the postMessage to include user activation delegation
+     * (includeUserActivation: true) so Safari allows the popup.
+     */
+    openInNewTab?: boolean;
   };
 };
 //#endregion
@@ -534,6 +703,102 @@ 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;
+  /**
+   * Optional product-specific sharing link
+   * When provided and the product is selected, this link is used instead of the default sharing link
+   */
+  link?: string;
+  /**
+   * Optional `utm_content` value to apply when this product is selected.
+   * Falls back to the page-level `attribution.utmContent` when omitted.
+   */
+  utmContent?: 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 attribution overrides for the outbound sharing URL.
+   *
+   * When provided (even as an empty object), Frak adds standard affiliation
+   * params (`utm_source=frak`, `utm_medium=referral`, `utm_campaign=<merchantId>`,
+   * `ref=<clientId>`, `via=frak`) alongside `fCtx`. Existing UTMs on the base
+   * URL are preserved (gap-fill). Set this to `null` to disable attribution
+   * params entirely (only `fCtx` is added).
+   *
+   * @default {} — defaults applied
+   */
+  attribution?: AttributionParams | null;
+  /**
+   * 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 +956,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 +1036,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 +1104,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 +1119,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 +1144,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 +1154,7 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_prepareSso";
-  Parameters: [params: PrepareSsoParamsType, name: string, customCss?: string];
+  Parameters: [params: PrepareSsoParamsType, name?: string, customCss?: string];
   ReturnType: PrepareSsoReturnType;
 },
 /**
@@ -871,7 +1165,7 @@ type IFrameRpcSchema = [
  */
 {
   Method: "frak_openSso";
-  Parameters: [params: OpenSsoParamsType, name: string, customCss?: string];
+  Parameters: [params: OpenSsoParamsType, name?: string, customCss?: string];
   ReturnType: OpenSsoReturnType;
 },
 /**
@@ -892,14 +1186,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 +1201,39 @@ 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;
+},
+/**
+ * Method to get 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.
+ * Returns the merge token string, or null if unavailable.
+ * This is a one-shot request.
+ */
+{
+  Method: "frak_getMergeToken";
+  Parameters?: undefined;
+  ReturnType: string | null;
 }];
 //#endregion
 //#region src/types/transport.d.ts
@@ -1052,4 +1379,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, AttributionParams as ct, IFrameTransport as d, UtmParams as dt, 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, TrackArrivalParams as lt, 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, AttributionDefaults as st, openSso as t, SdkResolvedConfig as tt, FrakLifecycleEvent as u, TrackArrivalResult as ut, TokenAmountType as v, EmbeddedViewActionSharing as w, DisplayEmbeddedWalletResultType as x, SendInteractionParamsType as y, SiweAuthenticationParams as z };