@frak-labs/core-sdk 0.0.19 → 0.1.0-beta.8d103039

package/src/types/config.ts

@@ -0,0 +1,111 @@
+/**
+ * All the currencies available
+ * @category Config
+ */
+export type Currency = "eur" | "usd" | "gbp";
+
+/**
+ * All the languages available
+ * @category Config
+ */
+export type Language = "fr" | "en";
+
+/**
+ * Configuration for the Frak Wallet SDK
+ * @category Config
+ */
+export type FrakWalletSdkConfig = {
+    /**
+     * The Frak wallet url
+     * @defaultValue "https://wallet.frak.id"
+     */
+    walletUrl?: string;
+    /**
+     * Some metadata about your implementation of the Frak SDK
+     */
+    metadata: {
+        /**
+         * Your application name (will be displayed in a few modals and in SSO)
+         */
+        name: string;
+        /**
+         * Language to display in the modal
+         * If undefined, will default to the browser language
+         */
+        lang?: Language;
+        /**
+         * The currency to display in the modal
+         * @defaultValue `"eur"`
+         */
+        currency?: Currency;
+        /**
+         * The logo URL that will be displayed in a few components
+         */
+        logoUrl?: string;
+        /**
+         * The homepage link that could be displayed in a few components
+         */
+        homepageLink?: string;
+    };
+    /**
+     * Some customization for the modal
+     */
+    customizations?: {
+        /**
+         * Custom CSS styles to apply to the modals and components
+         */
+        css?: `${string}.css`;
+        /**
+         * Custom i18n configuration for the modal
+         */
+        i18n?: I18nConfig;
+    };
+    /**
+     * The domain name of your application
+     * @defaultValue window.location.host
+     */
+    domain?: string;
+};
+
+/**
+ * Custom i18n configuration for the modal
+ *  See [i18next json format](https://www.i18next.com/misc/json-format#i18next-json-v4)
+ *
+ * Available variables
+ *  - `{{ productName }}` : The name of your website (`metadata.name`)
+ *  - `{{ productOrigin }}` : The origin url of your website
+ *  - `{{ estimatedReward }}` : The estimated reward for the user (based on the specific `targetInteraction` you can specify, or the max referrer reward if no target interaction is specified)
+ *
+ * Context of the translation [see i18n context](https://www.i18next.com/translation-function/context)
+ *  - For modal display, the key of the final action (`sharing`, `reward`, or undefined)
+ *  - For embedded wallet display, the key of the logged in action (`sharing` or undefined)
+ *
+ * @example
+ * ```ts
+ * // Multi language config
+ * const multiI18n = {
+ *  fr: {
+ *      "sdk.modal.title": "Titre de modal",
+ *      "sdk.modal.description": "Description de modal, avec {{ estimatedReward }} de gains possible",
+ *  },
+ *  en: "https://example.com/en.json"
+ * }
+ *
+ * // Single language config
+ * const singleI18n = {
+ *      "sdk.modal.title": "Modal title",
+ *      "sdk.modal.description": "Modal description, with {{ estimatedReward }} of gains possible",
+ * }
+ * ```
+ *
+ * @category Config
+ */
+export type I18nConfig =
+    | Record<Language, LocalizedI18nConfig>
+    | LocalizedI18nConfig;
+
+/**
+ * A localized i18n config
+ * @category Config
+ */
+export type LocalizedI18nConfig = `${string}.css` | { [key: string]: string };

package/src/types/context.ts

@@ -0,0 +1,13 @@
+import type { Address } from "viem";
+
+/**
+ * The current Frak Context
+ *
+ * For now, only contain a referrer address.
+ *
+ * @ignore
+ */
+export type FrakContext = {
+    // Referrer address
+    r: Address;
+};

package/src/types/index.ts

@@ -0,0 +1,70 @@
+// Rpc related
+export type { WalletStatusReturnType } from "./rpc/walletStatus";
+export type {
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    LoggedOutEmbeddedView,
+    LoggedInEmbeddedView,
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+} from "./rpc/embedded";
+export type {
+    SsoMetadata,
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+} from "./rpc/sso";
+export type {
+    TokenAmountType,
+    GetProductInformationReturnType,
+} from "./rpc/productInformation";
+export type {
+    PreparedInteraction,
+    SendInteractionParamsType,
+    SendInteractionReturnType,
+} from "./rpc/interaction";
+export type { IFrameRpcSchema } from "./rpc";
+// Client related
+export type { FrakClient } from "./client";
+export type { IFrameTransport, FrakLifecycleEvent } from "./transport";
+export type {
+    IFrameLifecycleEvent,
+    ClientLifecycleEvent,
+} from "./lifecycle";
+export type {
+    FrakWalletSdkConfig,
+    Currency,
+    Language,
+    I18nConfig,
+    LocalizedI18nConfig,
+} from "./config";
+export type {
+    CompressedData,
+    HashProtectedData,
+    KeyProvider,
+} from "./compression";
+// Modal related
+export type {
+    ModalStepTypes,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+    DisplayModalParamsType,
+    ModalRpcMetadata,
+} from "./rpc/displayModal";
+export type {
+    ModalStepMetadata,
+    LoginModalStepType,
+    SiweAuthenticateModalStepType,
+    SiweAuthenticationParams,
+    SiweAuthenticateReturnType,
+    SendTransactionTxType,
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+    OpenInteractionSessionReturnType,
+    OpenInteractionSessionModalStepType,
+    FinalModalStepType,
+    FinalActionType,
+} from "./rpc/modal";
+// Utils
+export type { FrakContext } from "./context";

package/src/types/lifecycle/client.ts

@@ -0,0 +1,46 @@
+import type { I18nConfig } from "../config";
+
+/**
+ * Event related to the iframe lifecycle
+ * @ignore
+ */
+export type ClientLifecycleEvent =
+    | CustomCssEvent
+    | CustomI18nEvent
+    | RestoreBackupEvent
+    | HearbeatEvent
+    | HandshakeResponse
+    | SsoRedirectCompleteEvent;
+
+type CustomCssEvent = {
+    clientLifecycle: "modal-css";
+    data: { cssLink: string };
+};
+
+type CustomI18nEvent = {
+    clientLifecycle: "modal-i18n";
+    data: { i18n: I18nConfig };
+};
+
+type RestoreBackupEvent = {
+    clientLifecycle: "restore-backup";
+    data: { backup: string };
+};
+
+type HearbeatEvent = {
+    clientLifecycle: "heartbeat";
+    data?: never;
+};
+
+type HandshakeResponse = {
+    clientLifecycle: "handshake-response";
+    data: {
+        token: string;
+        currentUrl: string;
+    };
+};
+
+type SsoRedirectCompleteEvent = {
+    clientLifecycle: "sso-redirect-complete";
+    data: { compressed: string };
+};

package/src/types/lifecycle/iframe.ts

@@ -0,0 +1,35 @@
+/**
+ * Event related to the iframe lifecycle
+ * @ignore
+ */
+export type IFrameLifecycleEvent =
+    | {
+          iframeLifecycle: "connected" | "show" | "hide" | "remove-backup";
+          data?: never;
+      }
+    | DoBackupEvent
+    | HandshakeRequestEvent
+    | RedirectRequestEvent;
+
+type DoBackupEvent = {
+    iframeLifecycle: "do-backup";
+    data: { backup?: string };
+};
+
+type HandshakeRequestEvent = {
+    iframeLifecycle: "handshake";
+    data: {
+        token: string;
+    };
+};
+
+type RedirectRequestEvent = {
+    iframeLifecycle: "redirect";
+    data: {
+        /**
+         * The base url to redirect to
+         *  If it contain a query param `u`, the client need will suffix the current url to the base url
+         */
+        baseRedirectUrl: string;
+    };
+};

package/src/types/lifecycle/index.ts

@@ -0,0 +1,2 @@
+export type { IFrameLifecycleEvent } from "./iframe";
+export type { ClientLifecycleEvent } from "./client";

package/src/types/rpc/displayModal.ts

@@ -0,0 +1,84 @@
+import type { FullInteractionTypesKey } from "../../constants/interactionTypes";
+import type { I18nConfig } from "../config";
+import type {
+    FinalModalStepType,
+    LoginModalStepType,
+    OpenInteractionSessionModalStepType,
+    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
+    | OpenInteractionSessionModalStepType
+    | 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?: FullInteractionTypesKey;
+    /**
+     * 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 { FullInteractionTypesKey } 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?: FullInteractionTypesKey;
+        /**
+         * 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,43 @@
+import type { Hex } 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
+ * @group RPC Schema
+ */
+export type SendInteractionReturnType = {
+    /**
+     * The id of the interaction in the interaction pool
+     */
+    delegationId: string;
+};

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,20 @@
+export type { LoginModalStepType } from "./login";
+export type {
+    SiweAuthenticateModalStepType,
+    SiweAuthenticationParams,
+    SiweAuthenticateReturnType,
+} from "./siweAuthenticate";
+export type {
+    SendTransactionModalStepType,
+    SendTransactionTxType,
+    SendTransactionReturnType,
+} from "./transaction";
+export type {
+    OpenInteractionSessionReturnType,
+    OpenInteractionSessionModalStepType,
+} from "./openSession";
+export type { ModalStepMetadata } from "./generic";
+export type {
+    FinalModalStepType,
+    FinalActionType,
+} from "./final";