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

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: {

package/src/types/resolvedConfig.ts

@@ -0,0 +1,104 @@
+import type { Currency, Language } from "./config";
+
+/**
+ * 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";
+            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
+ */
+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>;
+};
+
+/**
+ * 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>;
+};

package/src/types/rpc/interaction.ts

@@ -11,7 +11,12 @@ import type { Address } from "viem";
 export type SendInteractionParamsType =
     | {
           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;
@@ -21,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.ts

@@ -38,7 +38,7 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  *  - 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)
  *
@@ -53,7 +53,7 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  *  - 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)
  */
@@ -77,6 +77,7 @@ export type IFrameRpcSchema = [
             requests: ModalRpcStepsInput,
             metadata: ModalRpcMetadata | undefined,
             configMetadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: ModalRpcStepsResultType;
     },
@@ -89,7 +90,7 @@ export type IFrameRpcSchema = [
         Method: "frak_prepareSso";
         Parameters: [
             params: PrepareSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: PrepareSsoReturnType;
@@ -104,7 +105,7 @@ export type IFrameRpcSchema = [
         Method: "frak_openSso";
         Parameters: [
             params: OpenSsoParamsType,
-            name: string,
+            name?: string,
             customCss?: string,
         ];
         ReturnType: OpenSsoReturnType;
@@ -130,6 +131,7 @@ export type IFrameRpcSchema = [
         Parameters: [
             request: DisplayEmbeddedWalletParamsType,
             metadata: FrakWalletSdkConfig["metadata"],
+            placement?: string,
         ];
         ReturnType: DisplayEmbeddedWalletResultType;
     },
@@ -137,7 +139,7 @@ export type IFrameRpcSchema = [
      * 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";

package/src/types/tracking.ts

@@ -1,14 +1,5 @@
-/**
- * Types for arrival tracking and referral attribution
- * @category Tracking
- */
-
 import type { Address } from "viem";
 
-/**
- * UTM parameters for marketing attribution
- * @category Tracking
- */
 export type UtmParams = {
     source?: string;
     medium?: string;
@@ -17,29 +8,17 @@ export type UtmParams = {
     content?: string;
 };
 
-/**
- * Parameters for tracking an arrival event
- * @category Tracking
- */
 export type TrackArrivalParams = {
-    /**
-     * The referrer wallet address (from fCtx URL param)
-     */
+    /** @deprecated V1 legacy — use referrerClientId for v2 contexts */
     referrerWallet?: Address;
-    /**
-     * The landing page URL (defaults to current page)
-     */
+    referrerClientId?: string;
+    referrerMerchantId?: string;
+    /** Epoch seconds timestamp from the referral link creation */
+    referralTimestamp?: number;
     landingUrl?: string;
-    /**
-     * UTM parameters for marketing attribution
-     */
     utmParams?: UtmParams;
 };
 
-/**
- * Result from tracking an arrival event
- * @category Tracking
- */
 export type TrackArrivalResult = {
     success: boolean;
     identityGroupId?: string;
@@ -47,14 +26,6 @@ export type TrackArrivalResult = {
     error?: string;
 };
 
-/**
- * Internal params passed to the trackArrival action
- * Includes merchantId resolved from config or fetch
- * @internal
- */
 export type TrackArrivalInternalParams = TrackArrivalParams & {
-    /**
-     * The merchant ID (UUID from dashboard)
-     */
     merchantId: string;
 };