@frak-labs/core-sdk 0.1.0-beta.afa252b0 → 0.1.0-beta.dd44738a

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));
+}

package/src/utils/compression/decompress.ts

@@ -0,0 +1,11 @@
+import { decompressJson } from "@frak-labs/frame-connector";
+import { base64urlDecode } from "./b64";
+
+/**
+ * Decompress json data
+ * @param data
+ * @ignore
+ */
+export function decompressJsonFromB64<T>(data: string): T | null {
+    return decompressJson(base64urlDecode(data));
+}

package/src/utils/compression/index.ts

@@ -0,0 +1,3 @@
+export { compressJsonToB64 } from "./compress";
+export { decompressJsonFromB64 } from "./decompress";
+export { base64urlDecode, base64urlEncode } from "./b64";

package/src/utils/computeProductId.ts

@@ -0,0 +1,11 @@
+import { keccak256, toHex } from "viem";
+
+/**
+ * Compute the product id from a domain
+ * @ignore
+ */
+export function computeProductId({ domain }: { domain?: string } = {}) {
+    const effectiveDomain = domain ?? window.location.host;
+    const normalizedDomain = effectiveDomain.replace("www.", "");
+    return keccak256(toHex(normalizedDomain));
+}

package/src/utils/constants.ts

@@ -0,0 +1,4 @@
+/**
+ * The backup key for client side backup if needed
+ */
+export const BACKUP_KEY = "nexus-wallet-backup";

package/src/utils/formatAmount.ts

@@ -0,0 +1,18 @@
+import type { Currency } from "../types";
+import { getSupportedCurrency } from "./getSupportedCurrency";
+import { getSupportedLocale } from "./getSupportedLocale";
+
+export function formatAmount(amount: number, currency?: Currency) {
+    // Get the supported locale (e.g. "fr-FR")
+    const supportedLocale = getSupportedLocale(currency);
+
+    // Get the supported currency (e.g. "eur")
+    const supportedCurrency = getSupportedCurrency(currency);
+
+    return amount.toLocaleString(supportedLocale, {
+        style: "currency",
+        currency: supportedCurrency,
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 2,
+    });
+}

package/src/utils/getCurrencyAmountKey.ts

@@ -0,0 +1,15 @@
+import type { Currency, TokenAmountType } from "../types";
+
+/**
+ * Get the currency amount key for a given currency
+ * @param currency - The currency to use
+ * @returns The currency amount key
+ */
+export function getCurrencyAmountKey(
+    currency?: Currency
+): keyof TokenAmountType {
+    if (!currency) {
+        return "eurAmount";
+    }
+    return `${currency}Amount` as keyof TokenAmountType;
+}

package/src/utils/getSupportedCurrency.ts

@@ -0,0 +1,14 @@
+import { locales } from "../constants/locales";
+import type { Currency } from "../types";
+
+/**
+ * Get the supported currency for a given currency
+ * @param currency - The currency to use
+ * @returns The supported currency
+ */
+export function getSupportedCurrency(currency?: Currency): Currency {
+    if (!currency) {
+        return "eur";
+    }
+    return currency in locales ? currency : "eur";
+}

package/src/utils/getSupportedLocale.ts

@@ -0,0 +1,16 @@
+import { type LocalesKey, locales } from "../constants/locales";
+import type { Currency } from "../types";
+
+/**
+ * Get the supported locale for a given currency
+ * @param currency - The currency to use
+ * @returns The supported locale
+ */
+export function getSupportedLocale(
+    currency?: Currency
+): (typeof locales)[LocalesKey] {
+    if (!currency) {
+        return locales.eur;
+    }
+    return locales[currency] ?? locales.eur;
+}

package/src/utils/iframeHelper.ts

@@ -0,0 +1,142 @@
+import type { FrakWalletSdkConfig } from "../types";
+
+/**
+ * Base props for the iframe
+ * @ignore
+ */
+export const baseIframeProps = {
+    id: "frak-wallet",
+    name: "frak-wallet",
+    title: "Frak Wallet",
+    allow: "publickey-credentials-get *; clipboard-write; web-share *",
+    style: {
+        width: "0",
+        height: "0",
+        border: "0",
+        position: "absolute",
+        zIndex: 2000001,
+        top: "-1000px",
+        left: "-1000px",
+        colorScheme: "auto",
+    },
+};
+
+/**
+ * Create the Frak iframe
+ * @param args
+ * @param args.walletBaseUrl - Use `config.walletUrl` instead. Will be removed in future versions.
+ * @param args.config - The configuration object containing iframe options, including the replacement for `walletBaseUrl`.
+ */
+export function createIframe({
+    walletBaseUrl,
+    config,
+}: { walletBaseUrl?: string; config?: FrakWalletSdkConfig }): Promise<
+    HTMLIFrameElement | undefined
+> {
+    // Check if the iframe is already created
+    const alreadyCreatedIFrame = document.querySelector("#frak-wallet");
+
+    // If the iframe is already created, remove it
+    if (alreadyCreatedIFrame) {
+        alreadyCreatedIFrame.remove();
+    }
+
+    const iframe = document.createElement("iframe");
+
+    // Set the base iframe props
+    iframe.id = baseIframeProps.id;
+    iframe.name = baseIframeProps.name;
+    iframe.allow = baseIframeProps.allow;
+    iframe.style.zIndex = baseIframeProps.style.zIndex.toString();
+
+    changeIframeVisibility({ iframe, isVisible: false });
+    document.body.appendChild(iframe);
+
+    return new Promise((resolve) => {
+        iframe?.addEventListener("load", () => resolve(iframe));
+        iframe.src = `${config?.walletUrl ?? walletBaseUrl ?? "https://wallet.frak.id"}/listener`;
+    });
+}
+/**
+ * Change the visibility of the given iframe
+ * @ignore
+ */
+export function changeIframeVisibility({
+    iframe,
+    isVisible,
+}: {
+    iframe: HTMLIFrameElement;
+    isVisible: boolean;
+}) {
+    if (!isVisible) {
+        iframe.style.width = "0";
+        iframe.style.height = "0";
+        iframe.style.border = "0";
+        iframe.style.position = "fixed";
+        iframe.style.top = "-1000px";
+        iframe.style.left = "-1000px";
+        return;
+    }
+
+    iframe.style.position = "fixed";
+    iframe.style.top = "0";
+    iframe.style.left = "0";
+    iframe.style.width = "100%";
+    iframe.style.height = "100%";
+    iframe.style.pointerEvents = "auto";
+}
+
+/**
+ * Find an iframe within window.opener by pathname
+ *
+ * When a popup is opened via window.open from an iframe, window.opener points to
+ * the parent window, not the iframe itself. This utility searches through all frames
+ * in window.opener to find an iframe matching the specified pathname.
+ *
+ * @param pathname - The pathname to search for (default: "/listener")
+ * @returns The matching iframe window, or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Find the default /listener iframe
+ * const listenerIframe = findIframeInOpener();
+ *
+ * // Find a custom iframe
+ * const customIframe = findIframeInOpener("/my-custom-iframe");
+ * ```
+ */
+export function findIframeInOpener(pathname = "/listener"): Window | null {
+    if (!window.opener) return null;
+
+    const frameCheck = (frame: Window) => {
+        try {
+            return (
+                frame.location.origin === window.location.origin &&
+                frame.location.pathname === pathname
+            );
+        } catch {
+            // Cross-origin frame, skip
+            return false;
+        }
+    };
+
+    // Check if the openner window is the right one
+    if (frameCheck(window.opener)) return window.opener;
+
+    // Search through frames in window.opener
+    try {
+        const frames = window.opener.frames;
+        for (let i = 0; i < frames.length; i++) {
+            if (frameCheck(frames[i])) {
+                return frames[i];
+            }
+        }
+        return null;
+    } catch (error) {
+        console.error(
+            `[findIframeInOpener] Error finding iframe with pathname ${pathname}:`,
+            error
+        );
+        return null;
+    }
+}

package/src/utils/index.ts

@@ -0,0 +1,21 @@
+export {
+    createIframe,
+    baseIframeProps,
+    findIframeInOpener,
+} from "./iframeHelper";
+export { compressJsonToB64 } from "./compression/compress";
+export { decompressJsonFromB64 } from "./compression/decompress";
+export { base64urlDecode, base64urlEncode } from "./compression/b64";
+export { FrakContextManager } from "./FrakContext";
+export { getSupportedCurrency } from "./getSupportedCurrency";
+export { getSupportedLocale } from "./getSupportedLocale";
+export { getCurrencyAmountKey } from "./getCurrencyAmountKey";
+export { formatAmount } from "./formatAmount";
+export { trackEvent } from "./trackEvent";
+export { Deferred } from "@frak-labs/frame-connector";
+export {
+    generateSsoUrl,
+    type CompressedSsoData,
+    type FullSsoParams,
+    type AppSpecificSsoMetadata,
+} from "./sso";