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

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[];

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