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

package/src/index.ts

@@ -12,6 +12,8 @@ export { type LocalesKey, locales } from "./constants/locales";
 
 // Types
 export type {
+    AttributionDefaults,
+    AttributionParams,
     ClientLifecycleEvent,
     CompressedData,
     Currency,
@@ -19,6 +21,9 @@ export type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
     DisplayModalParamsType,
+    // RPC Sharing page
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
     EmbeddedViewActionReferred,
     EmbeddedViewActionSharing,
     EstimatedReward,
@@ -47,6 +52,7 @@ export type {
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
     LoginModalStepType,
+    MerchantConfigResponse,
     ModalRpcMetadata,
     ModalRpcStepsInput,
     ModalRpcStepsResultType,
@@ -58,12 +64,16 @@ export type {
     OpenSsoReturnType,
     PrepareSsoParamsType,
     PrepareSsoReturnType,
+    ResolvedPlacement,
+    ResolvedSdkConfig,
     RewardTier,
+    SdkResolvedConfig,
     // RPC Interaction
     SendInteractionParamsType,
     SendTransactionModalStepType,
     SendTransactionReturnType,
     SendTransactionTxType,
+    SharingPageProduct,
     SiweAuthenticateModalStepType,
     SiweAuthenticateReturnType,
     SiweAuthenticationParams,
@@ -72,8 +82,9 @@ export type {
     // Tracking
     TrackArrivalParams,
     TrackArrivalResult,
-    UtmParams,
     // Rpc
+    UserReferralStatusType,
+    UtmParams,
     WalletStatusReturnType,
 } from "./types";
 export { isV1Context, isV2Context } from "./types";
@@ -84,7 +95,7 @@ export {
     base64urlEncode,
     baseIframeProps,
     type CompressedSsoData,
-    clearMerchantIdCache,
+    clearAllCache,
     compressJsonToB64,
     createIframe,
     DEEP_LINK_SCHEME,
@@ -93,20 +104,26 @@ export {
     FrakContextManager,
     type FrakEvent,
     type FullSsoParams,
-    fetchMerchantId,
     findIframeInOpener,
     formatAmount,
     generateSsoUrl,
     getBackendUrl,
+    getCache,
     getClientId,
     getCurrencyAmountKey,
     getSupportedCurrency,
     getSupportedLocale,
     isChromiumAndroid,
     isFrakDeepLink,
-    resolveMerchantId,
+    isInAppBrowser,
+    isIOS,
+    type MergeAttributionInput,
+    mergeAttribution,
+    redirectToExternalBrowser,
+    sdkConfigStore,
     toAndroidIntentUrl,
     trackEvent,
     triggerDeepLinkWithFallback,
+    withCache,
 } from "./utils";
 export { computeLegacyProductId } from "./utils/computeLegacyProductId";

package/src/stubs/rrweb.ts

@@ -0,0 +1,9 @@
+/**
+ * Stub for rrweb. The @openpanel/web package statically imports `record` from
+ * rrweb even when session replay is disabled. This stub replaces the module so
+ * that rrweb is not included in the bundle.
+ * @see https://github.com/Openpanel-dev/openpanel/issues/336
+ */
+export function record() {
+    return () => {};
+}

package/src/types/config.ts

@@ -1,3 +1,5 @@
+import type { AttributionDefaults } from "./tracking";
+
 /**
  * All the currencies available
  * @category Config
@@ -27,7 +29,7 @@ export 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
@@ -71,6 +73,20 @@ export 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;
 };
 
 /**
@@ -111,7 +127,7 @@ export type I18nConfig =
     | LocalizedI18nConfig;
 
 /**
- * A localized i18n config
+ * A localized i18n config (inline objects only — URL-based i18n removed)
  * @category Config
  */
-export type LocalizedI18nConfig = `${string}.css` | { [key: string]: string };
+export type LocalizedI18nConfig = { [key: string]: string };

package/src/types/index.ts

@@ -17,11 +17,16 @@ export type {
 // Utils
 export type { FrakContext, FrakContextV1, FrakContextV2 } from "./context";
 export { isV1Context, isV2Context } from "./context";
-
 export type {
     ClientLifecycleEvent,
     IFrameLifecycleEvent,
 } from "./lifecycle";
+export type {
+    MerchantConfigResponse,
+    ResolvedPlacement,
+    ResolvedSdkConfig,
+    SdkResolvedConfig,
+} from "./resolvedConfig";
 export type { IFrameRpcSchema } from "./rpc";
 // Modal related
 export type {
@@ -31,6 +36,12 @@ export type {
     ModalRpcStepsResultType,
     ModalStepTypes,
 } from "./rpc/displayModal";
+// Sharing page related
+export type {
+    DisplaySharingPageParamsType,
+    DisplaySharingPageResultType,
+    SharingPageProduct,
+} from "./rpc/displaySharingPage";
 export type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
@@ -65,9 +76,12 @@ export type {
     PrepareSsoReturnType,
     SsoMetadata,
 } from "./rpc/sso";
+export type { UserReferralStatusType } from "./rpc/userReferralStatus";
 export type { WalletStatusReturnType } from "./rpc/walletStatus";
 // Tracking
 export type {
+    AttributionDefaults,
+    AttributionParams,
     TrackArrivalParams,
     TrackArrivalResult,
     UtmParams,

package/src/types/lifecycle/client.ts

@@ -1,4 +1,5 @@
 import type { I18nConfig } from "../config";
+import type { ResolvedSdkConfig } from "../resolvedConfig";
 
 /**
  * Event related to the iframe lifecycle
@@ -9,9 +10,9 @@ export type ClientLifecycleEvent =
     | CustomI18nEvent
     | RestoreBackupEvent
     | HearbeatEvent
-    | HandshakeResponse
     | SsoRedirectCompleteEvent
-    | DeepLinkFailedEvent;
+    | DeepLinkFailedEvent
+    | ResolvedConfigEvent;
 
 type CustomCssEvent = {
     clientLifecycle: "modal-css";
@@ -33,31 +34,6 @@ type HearbeatEvent = {
     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: { compressed: string };
@@ -67,3 +43,22 @@ type DeepLinkFailedEvent = {
     clientLifecycle: "deep-link-failed";
     data: { 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;
+    };
+};

package/src/types/lifecycle/iframe.ts

@@ -8,7 +8,6 @@ export type IFrameLifecycleEvent =
           data?: never;
       }
     | DoBackupEvent
-    | HandshakeRequestEvent
     | RedirectRequestEvent;
 
 type DoBackupEvent = {
@@ -16,13 +15,6 @@ type DoBackupEvent = {
     data: { backup?: string };
 };
 
-type HandshakeRequestEvent = {
-    iframeLifecycle: "handshake";
-    data: {
-        token: string;
-    };
-};
-
 type RedirectRequestEvent = {
     iframeLifecycle: "redirect";
     data: {
@@ -37,5 +29,12 @@ 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;
     };
 };

package/src/types/resolvedConfig.ts

@@ -0,0 +1,138 @@
+import type { Currency, Language } from "./config";
+import type { AttributionDefaults } from "./tracking";
+
+/**
+ * Response from the merchant resolve endpoint
+ * @category Config
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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;
+};

package/src/types/rpc/displaySharingPage.ts

@@ -0,0 +1,100 @@
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
+import type { I18nConfig } from "../config";
+import type { AttributionParams } from "../tracking";
+
+/**
+ * Product information to display on the sharing page
+ * @group Sharing Page
+ */
+export 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
+ */
+export 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
+ */
+export 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;
+};

package/src/types/rpc/embedded/index.ts

@@ -9,10 +9,10 @@ import type {
 import type { LoggedOutEmbeddedView } from "./loggedOut";
 
 export type {
+    EmbeddedViewActionReferred,
     EmbeddedViewActionSharing,
     LoggedInEmbeddedView,
     LoggedOutEmbeddedView,
-    EmbeddedViewActionReferred,
 };
 
 /**

package/src/types/rpc/interaction.ts

@@ -26,6 +26,10 @@ export type SendInteractionParamsType =
       }
     | {
           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";

package/src/types/rpc/userReferralStatus.ts

@@ -0,0 +1,20 @@
+/**
+ * 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
+ */
+export 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;
+};