@frak-labs/core-sdk 0.1.1 → 0.2.0-beta.7898df5b

package/src/types/rpc/interaction.ts

@@ -1,43 +1,35 @@
-import type { Hex } from "viem";
+import type { Address } from "viem";
 
 /**
- * Represent a prepared user interaction, ready to be sent on-chain via the wallet
- */
-export type PreparedInteraction = {
-    handlerTypeDenominator: Hex;
-    interactionData: Hex;
-};
-
-/**
- * Parameters that will be used to send an interaction to the blockchain
- * @inline
- */
-export type SendInteractionParamsType = {
-    /**
-     * The product id where this interaction has been made
-     * @defaultValue keccak256(toHex(window.location.host))
-     */
-    productId?: Hex;
-    /**
-     * The prepared interaction, built from an Interaction Encoder
-     */
-    interaction: PreparedInteraction;
-    /**
-     * A pre-computed interaction signature
-     * If none provided, the delegated interaction validator of your product will sign it (you can manage it in the business dashboard)
-     *
-     * @defaultValue undefined
-     */
-    validation?: Hex;
-};
-
-/**
- * Return type of the send interaction rpc request
+ * Parameters for sending interactions via RPC
+ *
+ * Note: merchantId and clientId come from WalletRpcContext
+ * and are NOT included in the params - they are resolved by the listener
+ *
  * @group RPC Schema
  */
-export type SendInteractionReturnType = {
-    /**
-     * The id of the interaction in the interaction pool
-     */
-    delegationId: string;
-};
+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;
+          utmCampaign?: string;
+          utmTerm?: string;
+          utmContent?: string;
+      }
+    | {
+          type: "sharing";
+      }
+    | {
+          type: "custom";
+          customType: string;
+          data?: Record<string, unknown>;
+          idempotencyKey?: string;
+      };

package/src/types/rpc/merchantInformation.ts

@@ -0,0 +1,77 @@
+import type { Address } from "viem";
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
+
+/**
+ * The type for the amount of tokens
+ */
+export type TokenAmountType = {
+    amount: number;
+    eurAmount: number;
+    usdAmount: number;
+    gbpAmount: number;
+};
+
+/**
+ * A tier definition for tiered rewards
+ */
+export type RewardTier = {
+    minValue: number;
+    maxValue?: number;
+    amount: TokenAmountType;
+};
+
+/**
+ * Estimated reward amount — discriminated union by payout type
+ *
+ * - `fixed`: A known token amount (with fiat equivalents)
+ * - `percentage`: A percent of a purchase field (e.g. 5% of purchase_amount), with optional min/max caps
+ * - `tiered`: Amount depends on a field value matching tier brackets
+ */
+export type EstimatedReward =
+    | {
+          payoutType: "fixed";
+          amount: TokenAmountType;
+      }
+    | {
+          payoutType: "percentage";
+          percent: number;
+          percentOf: string;
+          maxAmount?: TokenAmountType;
+          minAmount?: TokenAmountType;
+      }
+    | {
+          payoutType: "tiered";
+          tierField: string;
+          tiers: RewardTier[];
+      };
+
+/**
+ * Response of the `frak_getMerchantInformation` RPC method
+ * @group RPC Schema
+ */
+export type GetMerchantInformationReturnType = {
+    /**
+     * Current merchant id
+     */
+    id: string;
+    /**
+     * Some metadata
+     */
+    onChainMetadata: {
+        /**
+         * Name of the merchant on-chain
+         */
+        name: string;
+        /**
+         * Domain of the merchant on-chain
+         */
+        domain: string;
+    };
+    rewards: {
+        token?: Address;
+        campaignId: string;
+        interactionTypeKey: InteractionTypeKey;
+        referrer?: EstimatedReward;
+        referee?: EstimatedReward;
+    }[];
+};

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

@@ -4,10 +4,6 @@ export type {
 } from "./final";
 export type { ModalStepMetadata } from "./generic";
 export type { LoginModalStepType } from "./login";
-export type {
-    OpenInteractionSessionModalStepType,
-    OpenInteractionSessionReturnType,
-} from "./openSession";
 export type {
     SiweAuthenticateModalStepType,
     SiweAuthenticateReturnType,

package/src/types/rpc/modal/login.ts

@@ -1,4 +1,4 @@
-import type { Address } from "viem";
+import type { Address, Hex } from "viem";
 import type { SsoMetadata } from "../sso";
 import type { GenericModalStepType } from "./generic";
 
@@ -28,5 +28,9 @@ export type LoginModalStepType = GenericModalStepType<
     LoginWithSso | LoginWithoutSso,
     {
         wallet: Address;
+        webauthnProof?: {
+            challenge: Hex;
+            authenticatorResponse: string;
+        };
     }
 >;

package/src/types/rpc/walletStatus.ts

@@ -14,13 +14,8 @@ export type WalletConnected = {
     key: "connected";
     // The user wallet address
     wallet: Address;
-    // The interaction token, used to push interactions to the delegator if needed
+    // The interaction token, used to push interactions to the backend
     interactionToken?: string;
-    // The current onchain interaction session of the user
-    interactionSession?: {
-        startTimestamp: number;
-        endTimestamp: number;
-    };
 };
 
 /**
@@ -31,5 +26,4 @@ export type WalletNotConnected = {
     key: "not-connected";
     wallet?: never;
     interactionToken?: never;
-    interactionSession?: never;
 };

package/src/types/rpc.ts

@@ -1,4 +1,3 @@
-import type { Hex } from "viem";
 import type { FrakWalletSdkConfig } from "./config";
 import type {
     ModalRpcMetadata,
@@ -9,11 +8,8 @@ import type {
     DisplayEmbeddedWalletParamsType,
     DisplayEmbeddedWalletResultType,
 } from "./rpc/embedded";
-import type {
-    PreparedInteraction,
-    SendInteractionReturnType,
-} from "./rpc/interaction";
-import type { GetProductInformationReturnType } from "./rpc/productInformation";
+import type { SendInteractionParamsType } from "./rpc/interaction";
+import type { GetMerchantInformationReturnType } from "./rpc/merchantInformation";
 import type {
     OpenSsoParamsType,
     OpenSsoReturnType,
@@ -46,19 +42,14 @@ import type { WalletStatusReturnType } from "./rpc/walletStatus";
  * - Returns: {@link ModalRpcStepsResultType}
  * - Response Type: promise (one-shot)
  *
- * #### frak_sendInteraction
- *  - Params: [productId: Hex, interaction: {@link PreparedInteraction}, signature?: Hex]
- *  - Returns: {@link SendInteractionReturnType}
- *  - Response Type: promise (one-shot)
- *
  * #### frak_sso
  *  - Params: [params: {@link OpenSsoParamsType}, name: string, customCss?: string]
  *  - Returns: {@link OpenSsoReturnType}
  *  - Response Type: promise (one-shot)
  *
- * #### frak_getProductInformation
+ * #### frak_getMerchantInformation
  *  - Params: None
- *  - Returns: {@link GetProductInformationReturnType}
+ *  - Returns: {@link GetMerchantInformationReturnType}
  *  - Response Type: promise (one-shot)
  *
  * #### frak_displayEmbeddedWallet
@@ -89,19 +80,6 @@ export type IFrameRpcSchema = [
         ];
         ReturnType: ModalRpcStepsResultType;
     },
-    /**
-     * Method to transmit a user interaction
-     * This is a one-shot request
-     */
-    {
-        Method: "frak_sendInteraction";
-        Parameters: [
-            productId: Hex,
-            interaction: PreparedInteraction,
-            signature?: Hex,
-        ];
-        ReturnType: SendInteractionReturnType;
-    },
     /**
      * Method to prepare SSO (generate URL for popup)
      * Returns the SSO URL that should be opened in a popup
@@ -132,16 +110,16 @@ export type IFrameRpcSchema = [
         ReturnType: OpenSsoReturnType;
     },
     /**
-     * Method to get current product information's
-     *  - Is product minted?
+     * Method to get current merchant information
+     *  - Is merchant registered?
      *  - Does it have running campaign?
      *  - Estimated reward on actions
      * This is a one-shot request
      */
     {
-        Method: "frak_getProductInformation";
+        Method: "frak_getMerchantInformation";
         Parameters?: undefined;
-        ReturnType: GetProductInformationReturnType;
+        ReturnType: GetMerchantInformationReturnType;
     },
     /**
      * Method to show the embedded wallet, with potential customization
@@ -155,4 +133,18 @@ export type IFrameRpcSchema = [
         ];
         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
+     */
+    {
+        Method: "frak_sendInteraction";
+        Parameters: [
+            interaction: SendInteractionParamsType,
+            metadata?: { clientId?: string },
+        ];
+        ReturnType: undefined;
+    },
 ];

package/src/types/tracking.ts

@@ -0,0 +1,31 @@
+import type { Address } from "viem";
+
+export type UtmParams = {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+};
+
+export 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;
+};
+
+export type TrackArrivalResult = {
+    success: boolean;
+    identityGroupId?: string;
+    touchpointId?: string;
+    error?: string;
+};
+
+export type TrackArrivalInternalParams = TrackArrivalParams & {
+    merchantId: string;
+};