@frak-labs/core-sdk 0.0.19-beta.f259d7fc → 0.1.0-beta.263acd1e

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,35 @@
+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 delegator if needed
+    interactionToken?: string;
+    // The current onchain interaction session of the user
+    interactionSession?: {
+        startTimestamp: number;
+        endTimestamp: number;
+    };
+};
+
+/**
+ * @ignore
+ * @inline
+ */
+export type WalletNotConnected = {
+    key: "not-connected";
+    wallet?: never;
+    interactionToken?: never;
+    interactionSession?: never;
+};

package/src/types/rpc.ts

@@ -0,0 +1,158 @@
+import type { Hex } from "viem";
+import type { FrakWalletSdkConfig } from "./config";
+import type {
+    ModalRpcMetadata,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+} from "./rpc/displayModal";
+import type {
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+} from "./rpc/embedded";
+import type {
+    PreparedInteraction,
+    SendInteractionReturnType,
+} from "./rpc/interaction";
+import type { GetProductInformationReturnType } from "./rpc/productInformation";
+import type {
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+} from "./rpc/sso";
+import type { WalletStatusReturnType } from "./rpc/walletStatus";
+
+/**
+ * RPC interface that's used for the iframe communication
+ *
+ * Define all the methods available within the iFrame RPC client with response type annotations
+ *
+ * @group RPC Schema
+ *
+ * @remarks
+ * Each method in the schema now includes a ResponseType field that indicates:
+ * - "promise": One-shot request that resolves once
+ * - "stream": Streaming request that can emit multiple values
+ *
+ * ### Methods:
+ *
+ * #### frak_listenToWalletStatus
+ *  - Params: None
+ *  - Returns: {@link WalletStatusReturnType}
+ *  - Response Type: stream (emits updates when wallet status changes)
+ *
+ * #### frak_displayModal
+ * - Params: [requests: {@link ModalRpcStepsInput}, metadata?: {@link ModalRpcMetadata}, configMetadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - 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
+ *  - Params: None
+ *  - Returns: {@link GetProductInformationReturnType}
+ *  - Response Type: promise (one-shot)
+ *
+ * #### frak_displayEmbeddedWallet
+ * - Params: [request: {@link DisplayEmbeddedWalletParamsType}, metadata: {@link FrakWalletSdkConfig}["metadata"]]
+ * - Returns: {@link DisplayEmbeddedWalletResultType}
+ * - Response Type: promise (one-shot)
+ */
+export type IFrameRpcSchema = [
+    /**
+     * Method used to listen to the wallet status
+     * This is a streaming method that emits updates when wallet status changes
+     */
+    {
+        Method: "frak_listenToWalletStatus";
+        Parameters?: undefined;
+        ReturnType: WalletStatusReturnType;
+    },
+    /**
+     * Method to display a modal with the provided steps
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_displayModal";
+        Parameters: [
+            requests: ModalRpcStepsInput,
+            metadata: ModalRpcMetadata | undefined,
+            configMetadata: FrakWalletSdkConfig["metadata"],
+        ];
+        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
+     * Only used for popup flows (not redirect flows)
+     */
+    {
+        Method: "frak_prepareSso";
+        Parameters: [
+            params: PrepareSsoParamsType,
+            name: string,
+            customCss?: string,
+        ];
+        ReturnType: PrepareSsoReturnType;
+    },
+    /**
+     * Method to open/trigger SSO
+     * Either triggers redirect (if openInSameWindow/redirectUrl)
+     * Or waits for popup completion (if popup mode)
+     * This method handles BOTH redirect and popup flows
+     */
+    {
+        Method: "frak_openSso";
+        Parameters: [
+            params: OpenSsoParamsType,
+            name: string,
+            customCss?: string,
+        ];
+        ReturnType: OpenSsoReturnType;
+    },
+    /**
+     * Method to get current product information's
+     *  - Is product minted?
+     *  - Does it have running campaign?
+     *  - Estimated reward on actions
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_getProductInformation";
+        Parameters?: undefined;
+        ReturnType: GetProductInformationReturnType;
+    },
+    /**
+     * Method to show the embedded wallet, with potential customization
+     * This is a one-shot request
+     */
+    {
+        Method: "frak_displayEmbeddedWallet";
+        Parameters: [
+            request: DisplayEmbeddedWalletParamsType,
+            metadata: FrakWalletSdkConfig["metadata"],
+        ];
+        ReturnType: DisplayEmbeddedWalletResultType;
+    },
+];

package/src/types/transport.ts

@@ -0,0 +1,34 @@
+import type { LifecycleMessage, RpcClient } from "@frak-labs/frame-connector";
+import type { ClientLifecycleEvent, IFrameLifecycleEvent } from "./lifecycle";
+import type { IFrameRpcSchema } from "./rpc";
+
+/**
+ * IFrame transport interface
+ */
+export type IFrameTransport = {
+    /**
+     * Wait for the connection to be established
+     */
+    waitForConnection: Promise<boolean>;
+    /**
+     * Wait for the setup to be done
+     */
+    waitForSetup: Promise<void>;
+    /**
+     * Function used to perform a single request via the iframe transport
+     */
+    request: RpcClient<IFrameRpcSchema, LifecycleMessage>["request"];
+    /**
+     * Function used to listen to a request response via the iframe transport
+     */
+    listenerRequest: RpcClient<IFrameRpcSchema, LifecycleMessage>["listen"];
+    /**
+     * Function used to destroy the iframe transport
+     */
+    destroy: () => Promise<void>;
+};
+
+/**
+ * Represent an iframe event
+ */
+export type FrakLifecycleEvent = IFrameLifecycleEvent | ClientLifecycleEvent;