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

package/src/clients/transports/iframeLifecycleManager.ts

@@ -0,0 +1,88 @@
+import { Deferred } from "@frak-labs/frame-connector";
+import type { FrakLifecycleEvent } from "../../types";
+import { BACKUP_KEY } from "../../utils/constants";
+import { changeIframeVisibility } from "../../utils/iframeHelper";
+
+/** @ignore */
+export type IframeLifecycleManager = {
+    isConnected: Promise<boolean>;
+    handleEvent: (messageEvent: FrakLifecycleEvent) => Promise<void>;
+};
+
+/**
+ * Create a new iframe lifecycle handler
+ * @ignore
+ */
+export function createIFrameLifecycleManager({
+    iframe,
+}: { iframe: HTMLIFrameElement }): IframeLifecycleManager {
+    // Create the isConnected listener
+    const isConnectedDeferred = new Deferred<boolean>();
+
+    // Build the handler itself
+    const handler = async (messageEvent: FrakLifecycleEvent) => {
+        if (!("iframeLifecycle" in messageEvent)) return;
+
+        const { iframeLifecycle: event, data } = messageEvent;
+
+        switch (event) {
+            // Resolve the isConnected promise
+            case "connected":
+                isConnectedDeferred.resolve(true);
+                break;
+            // Perform a frak backup
+            case "do-backup":
+                if (data.backup) {
+                    localStorage.setItem(BACKUP_KEY, data.backup);
+                } else {
+                    localStorage.removeItem(BACKUP_KEY);
+                }
+                break;
+            // Remove frak backup
+            case "remove-backup":
+                localStorage.removeItem(BACKUP_KEY);
+                break;
+            // Change iframe visibility
+            case "show":
+            case "hide":
+                changeIframeVisibility({
+                    iframe,
+                    isVisible: event === "show",
+                });
+                break;
+            // Handshake handling
+            case "handshake": {
+                iframe.contentWindow?.postMessage(
+                    {
+                        clientLifecycle: "handshake-response",
+                        data: {
+                            token: data.token,
+                            currentUrl: window.location.href,
+                        },
+                    },
+                    "*"
+                );
+                break;
+            }
+            // Redirect handling
+            case "redirect": {
+                const redirectUrl = new URL(data.baseRedirectUrl);
+
+                // If we got a u append the current location dynamicly
+                if (redirectUrl.searchParams.has("u")) {
+                    redirectUrl.searchParams.delete("u");
+                    redirectUrl.searchParams.append("u", window.location.href);
+                    window.location.href = redirectUrl.toString();
+                } else {
+                    window.location.href = data.baseRedirectUrl;
+                }
+                break;
+            }
+        }
+    };
+
+    return {
+        handleEvent: handler,
+        isConnected: isConnectedDeferred.promise,
+    };
+}

package/src/constants/interactionTypes.ts

@@ -0,0 +1,44 @@
+/**
+ * The final keys for each interaction types (e.g. `openArticle`) -> interaction type
+ * @inline
+ */
+export type InteractionTypesKey = {
+    [K in keyof typeof interactionTypes]: keyof (typeof interactionTypes)[K];
+}[keyof typeof interactionTypes];
+
+/**
+ * The keys for each interaction types (e.g. `press.openArticle`) -> category_type.interaction_type
+ * @inline
+ */
+export type FullInteractionTypesKey = {
+    [Category in keyof typeof interactionTypes]: `${Category & string}.${keyof (typeof interactionTypes)[Category] & string}`;
+}[keyof typeof interactionTypes];
+
+/**
+ * Each interactions types according to the product types
+ */
+export const interactionTypes = {
+    press: {
+        openArticle: "0xc0a24ffb",
+        readArticle: "0xd5bd0fbe",
+    },
+    dapp: {
+        proofVerifiableStorageUpdate: "0x2ab2aeef",
+        callableVerifiableStorageUpdate: "0xa07da986",
+    },
+    webshop: {
+        open: "0xb311798f",
+    },
+    referral: {
+        referred: "0x010cc3b9",
+        createLink: "0xb2c0f17c",
+    },
+    purchase: {
+        started: "0xd87e90c3",
+        completed: "0x8403aeb4",
+        unsafeCompleted: "0x4d5b14e0",
+    },
+    retail: {
+        customerMeeting: "0x74489004",
+    },
+} as const;

package/src/constants/locales.ts

@@ -0,0 +1,14 @@
+/**
+ * The keys for each locales
+ * @inline
+ */
+export type LocalesKey = keyof typeof locales;
+
+/**
+ * Map the currency to the locale
+ */
+export const locales = {
+    eur: "fr-FR",
+    usd: "en-US",
+    gbp: "en-GB",
+} as const;

package/src/constants/productTypes.ts

@@ -0,0 +1,33 @@
+/**
+ * The keys for each product types
+ * @inline
+ */
+export type ProductTypesKey = keyof typeof productTypes;
+
+/**
+ * List of the product types per denominator
+ */
+export const productTypes = {
+    // content type
+    dapp: 1,
+    press: 2,
+    webshop: 3,
+    retail: 4,
+
+    // feature type
+    referral: 30,
+    purchase: 31,
+};
+
+/**
+ * Bitmask for each product types
+ */
+export const productTypesMask: Record<ProductTypesKey, bigint> = Object.entries(
+    productTypes
+).reduce(
+    (acc, [key, value]) => {
+        acc[key as ProductTypesKey] = BigInt(1) << BigInt(value);
+        return acc;
+    },
+    {} as Record<ProductTypesKey, bigint>
+);

package/src/index.ts

@@ -0,0 +1,103 @@
+// Clients
+export {
+    createIFrameFrakClient,
+    setupClient,
+    DebugInfoGatherer,
+} from "./clients";
+
+// Utils
+export {
+    compressJsonToB64,
+    decompressJsonFromB64,
+    createIframe,
+    FrakContextManager,
+    baseIframeProps,
+    findIframeInOpener,
+    getSupportedCurrency,
+    getSupportedLocale,
+    getCurrencyAmountKey,
+    formatAmount,
+    base64urlDecode,
+    base64urlEncode,
+    trackEvent,
+    generateSsoUrl,
+    type CompressedSsoData,
+    type FullSsoParams,
+    type AppSpecificSsoMetadata,
+} from "./utils";
+
+// Constants
+export {
+    type ProductTypesKey,
+    productTypes,
+    productTypesMask,
+} from "./constants/productTypes";
+export {
+    interactionTypes,
+    type InteractionTypesKey,
+    type FullInteractionTypesKey,
+} from "./constants/interactionTypes";
+export { locales, type LocalesKey } from "./constants/locales";
+export { ssoPopupFeatures, ssoPopupName } from "./actions/openSso";
+
+// Types
+export type {
+    // Rpc
+    WalletStatusReturnType,
+    IFrameRpcSchema,
+    PreparedInteraction,
+    SendInteractionParamsType,
+    SendInteractionReturnType,
+    SsoMetadata,
+    PrepareSsoParamsType,
+    PrepareSsoReturnType,
+    OpenSsoParamsType,
+    OpenSsoReturnType,
+    Currency,
+    Language,
+    I18nConfig,
+    LocalizedI18nConfig,
+    TokenAmountType,
+    GetProductInformationReturnType,
+    // RPC Embedded wallet
+    DisplayEmbeddedWalletParamsType,
+    DisplayEmbeddedWalletResultType,
+    LoggedOutEmbeddedView,
+    LoggedInEmbeddedView,
+    EmbeddedViewActionReferred,
+    EmbeddedViewActionSharing,
+    // RPC Modal generics
+    ModalStepTypes,
+    ModalRpcMetadata,
+    DisplayModalParamsType,
+    ModalRpcStepsInput,
+    ModalRpcStepsResultType,
+    // RPC Modal types
+    ModalStepMetadata,
+    LoginModalStepType,
+    SiweAuthenticateModalStepType,
+    SiweAuthenticationParams,
+    SiweAuthenticateReturnType,
+    SendTransactionTxType,
+    SendTransactionModalStepType,
+    SendTransactionReturnType,
+    OpenInteractionSessionReturnType,
+    OpenInteractionSessionModalStepType,
+    FinalModalStepType,
+    FinalActionType,
+    // Client
+    FrakClient,
+    // Transport
+    IFrameTransport,
+    IFrameLifecycleEvent,
+    ClientLifecycleEvent,
+    FrakLifecycleEvent,
+    // Config
+    FrakWalletSdkConfig,
+    // Compression
+    KeyProvider,
+    CompressedData,
+    HashProtectedData,
+    // Utils
+    FrakContext,
+} from "./types";

package/src/interactions/index.ts

@@ -0,0 +1,5 @@
+export { PressInteractionEncoder } from "./pressEncoder";
+export { ReferralInteractionEncoder } from "./referralEncoder";
+export { PurchaseInteractionEncoder } from "./purchaseEncoder";
+export { WebShopInteractionEncoder } from "./webshopEncoder";
+export { RetailInteractionEncoder } from "./retailEncoder";

package/src/interactions/pressEncoder.ts

@@ -0,0 +1,53 @@
+import { type Hex, concatHex, pad, toHex } from "viem";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import type { PreparedInteraction } from "../types";
+
+/**
+ * Press interactions allow you to track user engagement with articles or other press content on your platform.
+ * After setting up these interactions, you can create acquisition campaign based on the user engagement with your press content.
+ *
+ * :::info
+ *   To properly handle press interactions, ensure that the "Press" product type is enabled in your Business dashboard.
+ * :::
+ *
+ * @description Encode press related user interactions
+ *
+ * @group Interactions Encoder
+ *
+ * @see {@link PreparedInteraction} The prepared interaction object that can be sent
+ * @see {@link !actions.sendInteraction | `sendInteraction()`} Action used to send the prepared interaction to the Frak Wallet
+ */
+export const PressInteractionEncoder = {
+    /**
+     * Encode an open article interaction
+     * @param args
+     * @param args.articleId - The id of the article the user opened (32 bytes), could be a `keccak256` hash of the article slug, or your internal id
+     */
+    openArticle({ articleId }: { articleId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.press.openArticle,
+            pad(articleId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.press),
+            interactionData,
+        };
+    },
+
+    /**
+     * Encode a read article interaction
+     * @param args
+     * @param args.articleId - The id of the article the user opened (32 bytes), could be a `keccak256` hash of the article slug, or your internal id
+     */
+    readArticle({ articleId }: { articleId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.press.readArticle,
+            pad(articleId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.press),
+            interactionData,
+        };
+    },
+};

package/src/interactions/purchaseEncoder.ts

@@ -0,0 +1,94 @@
+import { type Hex, concatHex, encodeAbiParameters, pad, toHex } from "viem";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import type { PreparedInteraction } from "../types";
+
+/**
+ * Purchase interactions allow you to track user purchases on your platform.
+ * After setting up these interactions, you can create acquisition campaign based on the user purchase  (starting a new one, completed, or even purchase dropped).
+ *
+ * :::info
+ *   To properly handle purchase interactions, ensure that the "Purchase" product type is enabled in your Business dashboard, and that you have set up everything correctly in the `Purchasetracker` section.
+ * :::
+ *
+ * :::note
+ * The `purchaseId` is used on both interactions. It can be computed like this:
+ *
+ * ```ts
+ * const purchaseId = keccak256(concatHex([productId, toHex(externalPurchaseId)]));
+ * ```
+ *
+ * With:
+ * - `productId`: The id of your product, you can find it in the product dashboard.
+ * - `externalPurchaseId`: The id of the purchase in your system (e.g. the shopify `order_id`).
+ * :::
+ *
+ * @description Encode purchase related user interactions
+ *
+ * @group Interactions Encoder
+ *
+ * @see {@link !actions.sendInteraction | `sendInteraction()`} Action used to send the prepared interaction to the Frak Wallet
+ * @see {@link PreparedInteraction} The prepared interaction object that can be sent
+ * @see {@link !actions.trackPurchaseStatus | `trackPurchaseStatus()`} Action that will automatically send the purchase upon completion
+ * @see [Purchase Webhooks](/wallet-sdk/references-api/webhook) Webhooks to be implemented on your side to confirm a purchase
+ * @see [Purchase Proof](/wallet-sdk/references-api/purchaseProof) Get a merklee proof for the purchase
+ */
+export const PurchaseInteractionEncoder = {
+    /**
+     * Encode a start purchase interaction
+     * @param args
+     * @param args.purchaseId - The id of the purchase that is being started.
+     */
+    startPurchase({ purchaseId }: { purchaseId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.purchase.started,
+            pad(purchaseId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.purchase),
+            interactionData,
+        };
+    },
+
+    /**
+     * Encode a complete purchase interaction
+     * @param args
+     * @param args.purchaseId - The id of the purchase that is being completed.
+     * @param args.proof - The merkle proof that the user has completed the purchase (see [Purchase Webhooks](/wallet-sdk/references-api/webhook) for more details).
+     */
+    completedPurchase({
+        purchaseId,
+        proof,
+    }: { purchaseId: Hex; proof: Hex[] }): PreparedInteraction {
+        const innerData = encodeAbiParameters(
+            [{ type: "uint256" }, { type: "bytes32[]" }],
+            [BigInt(purchaseId), proof]
+        );
+        const interactionData = concatHex([
+            interactionTypes.purchase.completed,
+            innerData,
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.purchase),
+            interactionData,
+        };
+    },
+
+    /**
+     * Encode an unsafe complete purchase interaction (when we can't provide the proof)
+     * @param args
+     * @param args.purchaseId - The id of the purchase that is being completed.
+     */
+    unsafeCompletedPurchase({
+        purchaseId,
+    }: { purchaseId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.purchase.unsafeCompleted,
+            pad(purchaseId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.purchase),
+            interactionData,
+        };
+    },
+};

package/src/interactions/referralEncoder.ts

@@ -0,0 +1,47 @@
+import { type Address, concatHex, pad, toHex } from "viem";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import type { PreparedInteraction } from "../types";
+
+/**
+ * Referral interactions allow you to track user sharing activities.
+ * These interactions are essential for platforms looking to grow their user base through user-to-user referrals and reward systems.
+ *
+ * :::info
+ *   To properly handle referral interactions, ensure that the "Referral" product type is enabled in your Business dashboard.
+ * :::
+ *
+ * @description Encode referral related user interactions
+ *
+ * @group Interactions Encoder
+ *
+ * @see {@link PreparedInteraction} The prepared interaction object that can be sent
+ * @see {@link !actions.sendInteraction | `sendInteraction()`} Action used to send the prepared interaction to the Frak Wallet
+ */
+export const ReferralInteractionEncoder = {
+    /**
+     * Records the event of a user creating a referral link. Note that this interaction doesn't actually create the link itself; it only sends an event to track that a link was created.
+     */
+    createLink(): PreparedInteraction {
+        return {
+            handlerTypeDenominator: toHex(productTypes.referral),
+            interactionData: interactionTypes.referral.createLink,
+        };
+    },
+
+    /**
+     * Encode a referred interaction
+     * @param args
+     * @param args.referrer - The Ethereum address of the user who made the referral
+     */
+    referred({ referrer }: { referrer: Address }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.referral.referred,
+            pad(referrer, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.referral),
+            interactionData,
+        };
+    },
+};

package/src/interactions/retailEncoder.ts

@@ -0,0 +1,37 @@
+import { type Hex, concatHex, pad, toHex } from "viem";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import type { PreparedInteraction } from "../types";
+
+/**
+ * Retail interactions allow you to track user activities on your retails products.
+ *
+ * :::info
+ *   To properly handle retail interactions, ensure that the "Retail" product type is enabled in your Business dashboard.
+ * :::
+ *
+ * @description Encode retail related user interactions
+ *
+ * @group Interactions Encoder
+ *
+ * @see {@link PreparedInteraction} The prepared interaction object that can be sent
+ * @see {@link !actions.sendInteraction | `sendInteraction()`} Action used to send the prepared interaction to the Frak Wallet
+ */
+export const RetailInteractionEncoder = {
+    /**
+     * Encode a customer meeting retail interaction
+     * @param args
+     * @param args.agencyId - The id of the agency that the customer is meeting with
+     *
+     */
+    customerMeeting({ agencyId }: { agencyId: Hex }): PreparedInteraction {
+        const interactionData = concatHex([
+            interactionTypes.retail.customerMeeting,
+            pad(agencyId, { size: 32 }),
+        ]);
+        return {
+            handlerTypeDenominator: toHex(productTypes.retail),
+            interactionData,
+        };
+    },
+};

package/src/interactions/webshopEncoder.ts

@@ -0,0 +1,30 @@
+import { toHex } from "viem";
+import { interactionTypes } from "../constants/interactionTypes";
+import { productTypes } from "../constants/productTypes";
+import type { PreparedInteraction } from "../types";
+
+/**
+ * Webshop interactions allow you to track user activities on your webshop.
+ *
+ * :::info
+ *   To properly handle webshop interactions, ensure that the "WebShop" product type is enabled in your Business dashboard.
+ * :::
+ *
+ * @description Encode webshop related user interactions
+ *
+ * @group Interactions Encoder
+ *
+ * @see {@link PreparedInteraction} The prepared interaction object that can be sent
+ * @see {@link !actions.sendInteraction | `sendInteraction()`} Action used to send the prepared interaction to the Frak Wallet
+ */
+export const WebShopInteractionEncoder = {
+    /**
+     * Encode an open webshop interaction
+     */
+    open(): PreparedInteraction {
+        return {
+            handlerTypeDenominator: toHex(productTypes.webshop),
+            interactionData: interactionTypes.webshop.open,
+        };
+    },
+};

package/src/types/client.ts

@@ -0,0 +1,14 @@
+import type { OpenPanel } from "@openpanel/web";
+import type { FrakWalletSdkConfig } from "./config";
+import type { IFrameTransport } from "./transport";
+
+/**
+ * Representing a Frak client, used to interact with the Frak Wallet
+ */
+export type FrakClient = {
+    config: FrakWalletSdkConfig;
+    debugInfo: {
+        formatDebugInfo: (error: Error | unknown | string) => string;
+    };
+    openPanel?: OpenPanel;
+} & IFrameTransport;

package/src/types/compression.ts

@@ -0,0 +1,22 @@
+/**
+ * The received encoded data from a client
+ *  -> The encoded should contain a HashProtectedData once decoded
+ *  @ignore
+ */
+export type CompressedData = Uint8Array;
+
+/**
+ * The encoded data to send to a client / received by a client
+ *  @ignore
+ */
+export type HashProtectedData<DataType> = Readonly<
+    DataType & {
+        validationHash: string;
+    }
+>;
+
+/**
+ * Represent a key provider used for the hashed and secure compression
+ *  @ignore
+ */
+export type KeyProvider<DataType> = (value: DataType) => string[];