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

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

@@ -0,0 +1,32 @@
+import type { Address } 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;
+    }
+>;

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

@@ -0,0 +1,25 @@
+import type { GenericModalStepType } from "./generic";
+
+/**
+ * Return type of the open session modal step
+ * @inline
+ * @ignore
+ */
+export type OpenInteractionSessionReturnType = {
+    startTimestamp: number;
+    endTimestamp: number;
+};
+
+/**
+ * The open interaction session step for a Modal
+ *
+ * **Input**: None
+ * **Output**: The interactions session period (start and end timestamp)
+ *
+ * @group Modal Display
+ */
+export type OpenInteractionSessionModalStepType = GenericModalStepType<
+    "openSession",
+    object,
+    OpenInteractionSessionReturnType
+>;

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/productInformation.ts

@@ -0,0 +1,59 @@
+import type { Address, Hex } from "viem";
+import type { FullInteractionTypesKey } from "../../constants/interactionTypes";
+import type { ProductTypesKey } from "../../constants/productTypes";
+
+/**
+ * The type for the amount of tokens
+ */
+export type TokenAmountType = {
+    amount: number;
+    eurAmount: number;
+    usdAmount: number;
+    gbpAmount: number;
+};
+
+/**
+ * Response of the `frak_getProductInformation` RPC method
+ * @group RPC Schema
+ */
+export type GetProductInformationReturnType = {
+    /**
+     * Current product id
+     */
+    id: Hex;
+    /**
+     * Some metadata
+     */
+    onChainMetadata: {
+        /**
+         * Name of the product on-chain
+         */
+        name: string;
+        /**
+         * Domain of the product on-chain
+         */
+        domain: string;
+        /**
+         * The supported product types
+         */
+        productTypes: ProductTypesKey[];
+    };
+    /**
+     * The max potential reward for the referrer
+     */
+    maxReferrer?: TokenAmountType;
+    /**
+     * The max potential reward for the referee
+     */
+    maxReferee?: TokenAmountType;
+    /**
+     * List of all the potentials reward arround this product
+     */
+    rewards: {
+        token: Address;
+        campaign: Address;
+        interactionTypeKey: FullInteractionTypesKey;
+        referrer: TokenAmountType;
+        referee: TokenAmountType;
+    }[];
+};

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;

package/src/utils/FrakContext.ts

@@ -0,0 +1,152 @@
+import { type Address, bytesToHex, hexToBytes } from "viem";
+import type { FrakContext } from "../types";
+import { base64urlDecode, base64urlEncode } from "./compression/b64";
+
+/**
+ * The context key
+ */
+const contextKey = "fCtx";
+
+/**
+ * Compress the current Frak context
+ * @param context - The context to be compressed
+ * @returns A compressed string containing the Frak context
+ */
+function compress(context?: Partial<FrakContext>): string | undefined {
+    if (!context?.r) return;
+    try {
+        const bytes = hexToBytes(context.r);
+        return base64urlEncode(bytes);
+    } catch (e) {
+        console.error("Error compressing Frak context", { e, context });
+    }
+    return undefined;
+}
+
+/**
+ * Decompress the given Frak context
+ * @param context - The raw context to be decompressed into a `FrakContext`
+ * @returns The decompressed Frak context, or undefined if it fails
+ */
+function decompress(context?: string): FrakContext | undefined {
+    if (!context || context.length === 0) return;
+    try {
+        const bytes = base64urlDecode(context);
+        return { r: bytesToHex(bytes, { size: 20 }) as Address };
+    } catch (e) {
+        console.error("Error decompressing Frak context", { e, context });
+    }
+    return undefined;
+}
+
+/**
+ * Parse the current URL into a Frak Context
+ * @param args
+ * @param args.url - The url to parse
+ * @returns The parsed Frak context
+ */
+function parse({ url }: { url: string }) {
+    if (!url) return null;
+
+    // Check if the url contain the frak context key
+    const urlObj = new URL(url);
+    const frakContext = urlObj.searchParams.get(contextKey);
+    if (!frakContext) return null;
+
+    // Decompress and return it
+    return decompress(frakContext);
+}
+
+/**
+ * Populate the current url with the given Frak context
+ * @param args
+ * @param args.url - The url to update
+ * @param args.context - The context to update
+ * @returns The new url with the Frak context
+ */
+function update({
+    url,
+    context,
+}: { url?: string; context: Partial<FrakContext> }) {
+    if (!url) return null;
+
+    // Parse the current context
+    const currentContext = parse({ url });
+
+    // Merge the current context with the new context
+    const mergedContext = currentContext
+        ? { ...currentContext, ...context }
+        : context;
+
+    // If we don't have a referrer, early exit
+    if (!mergedContext.r) return null;
+
+    // Compress it
+    const compressedContext = compress(mergedContext);
+    if (!compressedContext) return null;
+
+    // Build the new url and return it
+    const urlObj = new URL(url);
+    urlObj.searchParams.set(contextKey, compressedContext);
+    return urlObj.toString();
+}
+
+/**
+ * Remove Frak context from current url
+ * @param url - The url to update
+ * @returns The new url without the Frak context
+ */
+function remove(url: string) {
+    const urlObj = new URL(url);
+    urlObj.searchParams.delete(contextKey);
+    return urlObj.toString();
+}
+
+/**
+ * Replace the current url with the given Frak context
+ * @param args
+ * @param args.url - The url to update
+ * @param args.context - The context to update
+ */
+function replaceUrl({
+    url: baseUrl,
+    context,
+}: { url?: string; context: Partial<FrakContext> | null }) {
+    // If no window here early exit
+    if (!window.location?.href || typeof window === "undefined") {
+        console.error("No window found, can't update context");
+        return;
+    }
+
+    // If no url, try to use the current one
+    const url = baseUrl ?? window.location.href;
+
+    // Get our new url with the frak context
+    let newUrl: string | null;
+    if (context !== null) {
+        newUrl = update({
+            url,
+            context,
+        });
+    } else {
+        newUrl = remove(url);
+    }
+
+    // If no new url, early exit
+    if (!newUrl) return;
+
+    // Update the url
+    window.history.replaceState(null, "", newUrl.toString());
+}
+
+/**
+ * Export our frak context
+ */
+export const FrakContextManager = {
+    compress,
+    decompress,
+    parse,
+    update,
+    remove,
+    replaceUrl,
+};

package/src/utils/compression/b64.ts

@@ -0,0 +1,29 @@
+/**
+ * Encode a buffer to a base64url encoded string
+ * @param buffer The buffer to encode
+ * @returns The encoded string
+ */
+export function base64urlEncode(buffer: Uint8Array): string {
+    return btoa(Array.from(buffer, (b) => String.fromCharCode(b)).join(""))
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+
+/**
+ * Decode a base64url encoded string
+ * @param value The value to decode
+ * @returns The decoded value
+ */
+export function base64urlDecode(value: string): Uint8Array {
+    const m = value.length % 4;
+    return Uint8Array.from(
+        atob(
+            value
+                .replace(/-/g, "+")
+                .replace(/_/g, "/")
+                .padEnd(value.length + (m === 0 ? 0 : 4 - m), "=")
+        ),
+        (c) => c.charCodeAt(0)
+    );
+}

package/src/utils/compression/compress.ts

@@ -0,0 +1,11 @@
+import { compressJson } from "@frak-labs/frame-connector";
+import { base64urlEncode } from "./b64";
+
+/**
+ * Compress json data
+ * @param data
+ * @ignore
+ */
+export function compressJsonToB64(data: unknown): string {
+    return base64urlEncode(compressJson(data));
+}