@frak-labs/core-sdk 0.1.0 → 0.1.1-beta.4dfea079

package/src/types/rpc/displayModal.ts

@@ -0,0 +1,82 @@
+import type { InteractionTypeKey } from "../../constants/interactionTypes";
+import type { I18nConfig } from "../config";
+import type {
+    FinalModalStepType,
+    LoginModalStepType,
+    SendTransactionModalStepType,
+    SiweAuthenticateModalStepType,
+} from "./modal";
+
+/**
+ * Generic type of steps we will display in the modal to the end user
+ * @group Modal Display
+ */
+export type ModalStepTypes =
+    | LoginModalStepType
+    | SiweAuthenticateModalStepType
+    | SendTransactionModalStepType
+    | FinalModalStepType;
+
+/**
+ * Type for the result of a modal request
+ * Just the `returns` type of each `ModalStepTypes`
+ * @typeParam T - The list of modal steps we expect to have in the modal
+ * @group Modal Display
+ * @group RPC Schema
+ */
+export type ModalRpcStepsResultType<
+    T extends ModalStepTypes[] = ModalStepTypes[],
+> = {
+    [K in T[number]["key"]]: Extract<T[number], { key: K }>["returns"];
+};
+
+/**
+ * Type for the RPC input of a modal
+ * Just the `params` type of each `ModalStepTypes`
+ * @typeParam T - The list of modal steps we expect to have in the modal
+ * @group Modal Display
+ * @group RPC Schema
+ */
+export type ModalRpcStepsInput<T extends ModalStepTypes[] = ModalStepTypes[]> =
+    {
+        [K in T[number]["key"]]?: Extract<T[number], { key: K }>["params"];
+    };
+
+/**
+ * RPC metadata for the modal, used on top level modal configuration
+ * @group Modal Display
+ * @group RPC Schema
+ */
+export type ModalRpcMetadata = {
+    header?: {
+        title?: string;
+        icon?: string;
+    };
+    targetInteraction?: InteractionTypeKey;
+    /**
+     * Some i18n override for the displayed modal (i.e. update the displayed text only for this modal)
+     */
+    i18n?: I18nConfig;
+} & (
+    | {
+          isDismissible: true;
+          /**
+           * @deprecated Use `config.customizations.i18n` or `metadata.i18n` instead
+           */
+          dismissActionTxt?: string;
+      }
+    | {
+          isDismissible?: false;
+          dismissActionTxt?: never;
+      }
+);
+
+/**
+ * Params used to display a modal
+ * @typeParam T - The list of modal steps we expect to have in the modal
+ * @group Modal Display
+ */
+export type DisplayModalParamsType<T extends ModalStepTypes[]> = {
+    steps: ModalRpcStepsInput<T>;
+    metadata?: ModalRpcMetadata;
+};

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

@@ -0,0 +1,68 @@
+import type { Address } from "viem";
+import type { InteractionTypeKey } from "../../../constants/interactionTypes";
+import type { I18nConfig } from "../../config";
+import type {
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+    LoggedInEmbeddedView,
+} from "./loggedIn";
+import type { LoggedOutEmbeddedView } from "./loggedOut";
+
+export type {
+    EmbeddedViewActionSharing,
+    LoggedInEmbeddedView,
+    LoggedOutEmbeddedView,
+    EmbeddedViewActionReferred,
+};
+
+/**
+ * The params used to display the embedded wallet
+ *
+ * @group Embedded wallet
+ */
+export type DisplayEmbeddedWalletParamsType = {
+    /**
+     * The embedded view to display once the user is logged in
+     */
+    loggedIn?: LoggedInEmbeddedView;
+    /**
+     * The embedded view to display once the user is logged out
+     */
+    loggedOut?: LoggedOutEmbeddedView;
+    /**
+     * Some metadata to customize the embedded view
+     */
+    metadata?: {
+        /**
+         * The logo to display on the embedded wallet
+         * If undefined, will default to no logo displayed
+         */
+        logo?: string;
+        /**
+         * Link to the homepage of the calling website
+         * If undefined, will default to the domain of the calling website
+         */
+        homepageLink?: string;
+        /**
+         * The target interaction behind this modal
+         */
+        targetInteraction?: InteractionTypeKey;
+        /**
+         * The position of the component
+         */
+        position?: "left" | "right";
+        /**
+         * Some i18n override for the displayed modal (i.e. update the displayed text only for this modal)
+         */
+        i18n?: I18nConfig;
+    };
+};
+
+/**
+ * The result of the display embedded wallet rpc request
+ *
+ * @group Embedded wallet
+ */
+export type DisplayEmbeddedWalletResultType = {
+    wallet: Address;
+};

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

@@ -0,0 +1,55 @@
+/**
+ * The different type of action we can have on the embedded view (once the user is logged in)
+ *
+ * @group Embedded wallet
+ */
+export type EmbeddedViewActionSharing = {
+    key: "sharing";
+
+    /**
+     * Some sharing options
+     */
+    options?: {
+        /**
+         * The title that will be displayed on the system popup once the system sharing window is open
+         * @deprecated Use the top level `config.metadata.i18n` instead
+         */
+        popupTitle?: string;
+        /**
+         * The text that will be shared alongside the link.
+         * Can contain the variable `{LINK}` to specify where the link is placed, otherwise it will be added at the end
+         * @deprecated Use the top level `config.metadata.i18n` instead
+         */
+        text?: string;
+        /**
+         * The link to be shared (will be suffixed with the Frak sharing context)
+         */
+        link?: string;
+    };
+};
+
+/**
+ * The action to display on the logged out embedded view when the user is referred
+ *
+ * @group Embedded wallet
+ */
+export type EmbeddedViewActionReferred = {
+    key: "referred";
+
+    /**
+     * No options for a referred action
+     */
+    options?: never;
+};
+
+/**
+ * Some configuration options for the embedded view
+ *
+ * @group Embedded wallet
+ */
+export type LoggedInEmbeddedView = {
+    /**
+     * The main action to display on the logged in embedded view
+     */
+    action?: EmbeddedViewActionSharing | EmbeddedViewActionReferred;
+};

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

@@ -0,0 +1,28 @@
+/**
+ * The view when a user is logged out
+ * @group Embedded wallet
+ */
+export type LoggedOutEmbeddedView = {
+    /**
+     * Metadata option when displaying the embedded view
+     */
+    metadata?: {
+        /**
+         * The main CTA for the logged out view
+         *  - can include some variable, available ones are:
+         *      - `{REWARD}` -> The maximum reward a user can receive when interacting on your website
+         *  - can be formatted in markdown
+         *
+         * If not set, it will default to a internationalized message
+         * @deprecated Use the top level `config.customizations.i18n`, or `metadata.i18n` instead
+         */
+        text?: string;
+        /**
+         * The text that will be displayed on the login button
+         *
+         * If not set, it will default to a internationalized message
+         * @deprecated Use the top level `config.customizations.i18n`, or `metadata.i18n` instead
+         */
+        buttonText?: string;
+    };
+};

package/src/types/rpc/interaction.ts

@@ -0,0 +1,30 @@
+import type { Address } from "viem";
+
+/**
+ * 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 SendInteractionParamsType =
+    | {
+          type: "arrival";
+          referrerWallet?: Address;
+          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/final.ts

@@ -0,0 +1,46 @@
+import type { GenericModalStepType, ModalStepMetadata } from "./generic";
+
+/**
+ * The final modal step type, could be used to display sharing options or a success reward screen.
+ *
+ * **Input**: What type final step to display?
+ * **Output**: None
+ *
+ * @group Modal Display
+ */
+export type FinalModalStepType = GenericModalStepType<
+    "final",
+    {
+        // Custom metadata in the case it was dismissed
+        dismissedMetadata?: ModalStepMetadata["metadata"];
+        // Action to perform on this final step
+        action: FinalActionType;
+        // Do we want to auto skip this step (don't display anything to the user, once we reached it we exit)
+        autoSkip?: boolean;
+    },
+    object
+>;
+
+/**
+ * The different types of final actions we can display in the final step
+ * @group Modal Display
+ */
+export type FinalActionType =
+    | {
+          key: "sharing";
+          options?: {
+              /**
+               * @deprecated Use the top level `config.metadata.i18n` instead
+               */
+              popupTitle?: string;
+              /**
+               * @deprecated Use the top level `config.metadata.i18n` instead
+               */
+              text?: string;
+              link?: string;
+          };
+      }
+    | {
+          key: "reward";
+          options?: never;
+      };

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

@@ -0,0 +1,46 @@
+/**
+ * Represent a generic modal step type
+ * @ignore
+ * @inline
+ */
+export type GenericModalStepType<TKey, TParams, TReturns> = {
+    key: TKey;
+    params: TParams extends never
+        ? ModalStepMetadata
+        : ModalStepMetadata & TParams;
+    returns: TReturns;
+};
+
+/**
+ * Metadata that can be used to customize a modal step
+ * @group Modal Display
+ * @deprecated Use the top level `config.customizations.i18n`, or `metadata.i18n` instead
+ */
+export type ModalStepMetadata = {
+    metadata?: {
+        /**
+         * Custom title for the step
+         * If none provided, it will use an internationalized text
+         * @deprecated Use the top level `config.customizations.i18n`, or `metadata.i18n` instead
+         */
+        title?: string;
+        /**
+         * Custom description for the step
+         * If none provided, it will use an internationalized text
+         * @deprecated Use the top level `config.customizations.i18n`, or `metadata.i18n` instead
+         */
+        description?: string;
+        /**
+         * Custom text for the primary action of the step
+         * If none provided, it will use an internationalized text
+         * @deprecated Use the top level `config.customizations.i18n`, or `metadata.i18n` instead
+         */
+        primaryActionText?: string;
+        /**
+         * Custom text for the secondary action of the step
+         * If none provided, it will use an internationalized text
+         * @deprecated Use the top level `config.customizations.i18n`, or `metadata.i18n` instead
+         */
+        secondaryActionText?: string;
+    };
+};

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

@@ -0,0 +1,16 @@
+export type {
+    FinalActionType,
+    FinalModalStepType,
+} from "./final";
+export type { ModalStepMetadata } from "./generic";
+export type { LoginModalStepType } from "./login";
+export type {
+    SiweAuthenticateModalStepType,
+    SiweAuthenticateReturnType,
+    SiweAuthenticationParams,
+} from "./siweAuthenticate";
+export type {
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+    SendTransactionTxType,
+} from "./transaction";

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

@@ -0,0 +1,36 @@
+import type { Address, Hex } from "viem";
+import type { SsoMetadata } from "../sso";
+import type { GenericModalStepType } from "./generic";
+
+/** @inline */
+type LoginWithSso = {
+    allowSso: true;
+    // Optional metadata for the SSO (if not provided, will be recomputed from the top level wallet sdk)
+    ssoMetadata?: SsoMetadata;
+};
+
+/** @inline */
+type LoginWithoutSso = {
+    allowSso?: false;
+    ssoMetadata?: never;
+};
+
+/**
+ * The login step for a Modal
+ *
+ * **Input**: Do we allow SSO or not? Is yes then the SSO metadata
+ * **Output**: The logged in wallet address
+ *
+ * @group Modal Display
+ */
+export type LoginModalStepType = GenericModalStepType<
+    "login",
+    LoginWithSso | LoginWithoutSso,
+    {
+        wallet: Address;
+        webauthnProof?: {
+            challenge: Hex;
+            authenticatorResponse: string;
+        };
+    }
+>;

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

@@ -0,0 +1,37 @@
+import type { Hex } from "viem";
+import type { SiweMessage } from "viem/siwe";
+import type { GenericModalStepType } from "./generic";
+
+/**
+ * Parameters used send a SIWE rpc request
+ */
+export type SiweAuthenticationParams = Omit<
+    SiweMessage,
+    "address" | "chainId" | "expirationTime" | "issuedAt" | "notBefore"
+> & {
+    expirationTimeTimestamp?: number;
+    notBeforeTimestamp?: number;
+};
+
+/**
+ * Return type of the Siwe transaction rpc request
+ * @inline
+ */
+export type SiweAuthenticateReturnType = {
+    signature: Hex;
+    message: string;
+};
+
+/**
+ * The SIWE authentication step for a Modal
+ *
+ * **Input**: SIWE message parameters
+ * **Output**: SIWE result (message signed and wallet signature)
+ *
+ * @group Modal Display
+ */
+export type SiweAuthenticateModalStepType = GenericModalStepType<
+    "siweAuthenticate",
+    { siwe: SiweAuthenticationParams },
+    SiweAuthenticateReturnType
+>;

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

@@ -0,0 +1,33 @@
+import type { Address, Hex } from "viem";
+import type { GenericModalStepType } from "./generic";
+
+/**
+ * Generic format representing a tx to be sent
+ */
+export type SendTransactionTxType = {
+    to: Address;
+    data?: Hex;
+    value?: Hex;
+};
+
+/**
+ * Return type of the send transaction rpc request
+ * @inline
+ */
+export type SendTransactionReturnType = {
+    hash: Hex;
+};
+
+/**
+ * The send transaction step for a Modal
+ *
+ * **Input**: Either a single tx or an array of tx to be sent
+ * **Output**: The hash of the tx(s) hash (in case of multiple tx, still returns a single hash because it's bundled on the wallet level)
+ *
+ * @group Modal Display
+ */
+export type SendTransactionModalStepType = GenericModalStepType<
+    "sendTransaction",
+    { tx: SendTransactionTxType | SendTransactionTxType[] },
+    SendTransactionReturnType
+>;

package/src/types/rpc/sso.ts

@@ -0,0 +1,80 @@
+import type { Hex } from "viem";
+
+/**
+ * SSO Metadata
+ */
+export type SsoMetadata = {
+    /**
+     * URL to your client, if provided will be displayed in the SSO header
+     */
+    logoUrl?: string;
+    /**
+     * Link to your homepage, if referenced your app name will contain a link on the sso page
+     */
+    homepageLink?: string;
+};
+
+/**
+ * Params for preparing SSO (generating URL)
+ * Same as OpenSsoParamsType but without openInSameWindow (popup-only operation)
+ * @group RPC Schema
+ */
+export type PrepareSsoParamsType = {
+    /**
+     * Redirect URL after the SSO (optional)
+     */
+    redirectUrl?: string;
+    /**
+     * If the SSO should directly exit after completion
+     * @defaultValue true
+     */
+    directExit?: boolean;
+    /**
+     * Language of the SSO page (optional)
+     * It will default to the current user language (or "en" if unsupported language)
+     */
+    lang?: "en" | "fr";
+    /**
+     * Custom SSO metadata
+     */
+    metadata?: SsoMetadata;
+};
+
+/**
+ * Response after preparing SSO
+ * @group RPC Schema
+ */
+export type PrepareSsoReturnType = {
+    /**
+     * The SSO URL that should be opened in a popup
+     */
+    ssoUrl: string;
+};
+
+/**
+ * Response after an SSO has been openned
+ */
+export type OpenSsoReturnType = {
+    /**
+     * Optional wallet address, returned when SSO completes via postMessage
+     * Note: Only present when SSO flow completes (not immediately on open)
+     */
+    wallet?: Hex;
+};
+
+/**
+ * Params to start a SSO
+ * @group RPC Schema
+ */
+export type OpenSsoParamsType = PrepareSsoParamsType & {
+    /**
+     * Indicate whether we want todo the flow within the same window context, or if we want to do it with an external popup window openned
+     * Note: Default true if redirectUrl is present, otherwise, false
+     */
+    openInSameWindow?: boolean;
+
+    /**
+     * Custom SSO popup url if user want additionnal customisation
+     */
+    ssoPopupUrl?: string;
+};

package/src/types/rpc/walletStatus.ts

@@ -0,0 +1,29 @@
+import type { Address } from "viem";
+
+/**
+ * RPC Response for the method `frak_listenToWalletStatus`
+ * @group RPC Schema
+ */
+export type WalletStatusReturnType = WalletConnected | WalletNotConnected;
+
+/**
+ * @ignore
+ * @inline
+ */
+export type WalletConnected = {
+    key: "connected";
+    // The user wallet address
+    wallet: Address;
+    // The interaction token, used to push interactions to the backend
+    interactionToken?: string;
+};
+
+/**
+ * @ignore
+ * @inline
+ */
+export type WalletNotConnected = {
+    key: "not-connected";
+    wallet?: never;
+    interactionToken?: never;
+};