@imtbl/checkout-sdk 2.0.0-alpha.0

package/dist/types/widgets/definitions/parameters/wallet.d.ts

@@ -0,0 +1,12 @@
+import { WalletProviderName } from '../../../types';
+import { WidgetLanguage } from '../configurations';
+/**
+ * Wallet Widget parameters
+ * @property {WalletProviderName | undefined} walletProviderName
+ */
+export type WalletWidgetParams = {
+    /** The wallet provider name to use for the wallet widget */
+    walletProviderName?: WalletProviderName;
+    /** The language to use for the wallet widget */
+    language?: WidgetLanguage;
+};

package/dist/types/widgets/definitions/types.d.ts

@@ -0,0 +1,282 @@
+import { Environment } from '@imtbl/config';
+import { BridgeClaimWithdrawalFailed, BridgeClaimWithdrawalSuccess, BridgeEventType, BridgeFailed, BridgeTransactionSent, ConnectEventType, ConnectionFailed, ConnectionSuccess, OnRampEventType, OnRampFailed, OnRampSuccess, OrchestrationEventType, ProviderEventType, ProviderUpdated, RequestBridgeEvent, RequestConnectEvent, RequestOnrampEvent, RequestSwapEvent, RequestWalletEvent, SaleEventType, SaleFailed, SalePaymentMethod, SalePaymentToken, SaleSuccess, SaleTransactionSuccess, SwapEventType, SwapFailed, SwapRejected, SwapSuccess, WalletConnectProviderChanged, WalletDisconnect, WalletEventType, WalletNetworkSwitch, CommerceEventType, CommerceProviderUpdatedEvent, CommerceSuccessEvent, CommerceFailureEvent, CommerceUserActionEvent, RequestAddTokensEvent, RequestGoBackEvent, AddTokensEventType, AddTokensConnectSuccess, AddTokensSuccess, AddTokensFailed, PurchaseConnectSuccess, PurchaseEventType, PurchaseFailed, PurchaseSuccess } from './events';
+import { BridgeWidgetParams, ConnectWidgetParams, SwapWidgetParams, WalletWidgetParams, OnRampWidgetParams, CommerceWidgetParams, AddTokensWidgetParams, SaleWidgetParams, PurchaseWidgetParams } from './parameters';
+import { BridgeWidgetConfiguration, ConnectWidgetConfiguration, OnrampWidgetConfiguration, SaleWidgetConfiguration, SwapWidgetConfiguration, WalletWidgetConfiguration, CommerceWidgetConfiguration, AddTokensWidgetConfiguration, WidgetTheme, PurchaseWidgetConfiguration } from './configurations';
+import { WrappedBrowserProvider } from '../../types';
+/**
+ * Enum representing the list of widget types.
+ */
+export declare enum WidgetType {
+    CONNECT = "connect",
+    WALLET = "wallet",
+    SWAP = "swap",
+    BRIDGE = "bridge",
+    ONRAMP = "onramp",
+    SALE = "sale",
+    IMMUTABLE_COMMERCE = "immutableCommerce",
+    ADD_TOKENS = "addTokens",
+    PURCHASE = "purchase"
+}
+/**
+ * Widget properties definition for each widget. Used for creating and updating widgets
+ */
+export type WidgetProperties<T extends WidgetType> = {
+    config?: WidgetConfigurations[T];
+    provider?: WrappedBrowserProvider;
+};
+export type WidgetConfigurations = {
+    [WidgetType.CONNECT]: ConnectWidgetConfiguration;
+    [WidgetType.WALLET]: WalletWidgetConfiguration;
+    [WidgetType.SWAP]: SwapWidgetConfiguration;
+    [WidgetType.BRIDGE]: BridgeWidgetConfiguration;
+    [WidgetType.ONRAMP]: OnrampWidgetConfiguration;
+    [WidgetType.SALE]: SaleWidgetConfiguration;
+    [WidgetType.ADD_TOKENS]: AddTokensWidgetConfiguration;
+    [WidgetType.PURCHASE]: PurchaseWidgetConfiguration;
+    [WidgetType.IMMUTABLE_COMMERCE]: CommerceWidgetConfiguration;
+};
+export type WidgetParameters = {
+    [WidgetType.CONNECT]: ConnectWidgetParams;
+    [WidgetType.WALLET]: WalletWidgetParams;
+    [WidgetType.SWAP]: SwapWidgetParams;
+    [WidgetType.BRIDGE]: BridgeWidgetParams;
+    [WidgetType.ONRAMP]: OnRampWidgetParams;
+    [WidgetType.SALE]: SaleWidgetParams;
+    [WidgetType.ADD_TOKENS]: AddTokensWidgetParams;
+    [WidgetType.PURCHASE]: PurchaseWidgetParams;
+    [WidgetType.IMMUTABLE_COMMERCE]: CommerceWidgetParams;
+};
+/**
+ * Represents all the possible event types that are emitted by the widgets.
+ */
+export type WidgetEventTypes = {
+    [WidgetType.CONNECT]: ConnectEventType | OrchestrationEventType;
+    [WidgetType.WALLET]: WalletEventType | OrchestrationEventType;
+    [WidgetType.SWAP]: SwapEventType | OrchestrationEventType;
+    [WidgetType.BRIDGE]: BridgeEventType | OrchestrationEventType;
+    [WidgetType.ONRAMP]: OnRampEventType | OrchestrationEventType;
+    [WidgetType.SALE]: SaleEventType | OrchestrationEventType;
+    [WidgetType.IMMUTABLE_COMMERCE]: CommerceEventType | OrchestrationEventType;
+    [WidgetType.ADD_TOKENS]: AddTokensEventType | OrchestrationEventType;
+    [WidgetType.PURCHASE]: PurchaseEventType | OrchestrationEventType;
+};
+type OrchestrationMapping = {
+    [OrchestrationEventType.REQUEST_CONNECT]: RequestConnectEvent;
+    [OrchestrationEventType.REQUEST_WALLET]: RequestWalletEvent;
+    [OrchestrationEventType.REQUEST_SWAP]: RequestSwapEvent;
+    [OrchestrationEventType.REQUEST_BRIDGE]: RequestBridgeEvent;
+    [OrchestrationEventType.REQUEST_ONRAMP]: RequestOnrampEvent;
+    [OrchestrationEventType.REQUEST_ADD_TOKENS]: RequestAddTokensEvent;
+    [OrchestrationEventType.REQUEST_GO_BACK]: RequestGoBackEvent;
+};
+type ProviderEventMapping = {
+    [ProviderEventType.PROVIDER_UPDATED]: ProviderUpdated;
+};
+/**
+ * Mapping of widget type, to each of its events and then each event's payload
+ * Update this whenever a new event is created and used by a widget
+ * Each widget also has all the orchestration events
+ */
+export type WidgetEventData = {
+    [WidgetType.CONNECT]: {
+        [ConnectEventType.SUCCESS]: ConnectionSuccess;
+        [ConnectEventType.FAILURE]: ConnectionFailed;
+        [ConnectEventType.CLOSE_WIDGET]: {};
+        [ConnectEventType.WALLETCONNECT_PROVIDER_UPDATED]: WalletConnectProviderChanged;
+    } & OrchestrationMapping & ProviderEventMapping;
+    [WidgetType.WALLET]: {
+        [WalletEventType.NETWORK_SWITCH]: WalletNetworkSwitch;
+        [WalletEventType.DISCONNECT_WALLET]: WalletDisconnect;
+        [WalletEventType.CLOSE_WIDGET]: {};
+    } & OrchestrationMapping & ProviderEventMapping;
+    [WidgetType.SWAP]: {
+        [SwapEventType.SUCCESS]: SwapSuccess;
+        [SwapEventType.FAILURE]: SwapFailed;
+        [SwapEventType.REJECTED]: SwapRejected;
+        [SwapEventType.CLOSE_WIDGET]: {};
+    } & OrchestrationMapping & ProviderEventMapping;
+    [WidgetType.BRIDGE]: {
+        [BridgeEventType.TRANSACTION_SENT]: BridgeTransactionSent;
+        [BridgeEventType.FAILURE]: BridgeFailed;
+        [BridgeEventType.CLOSE_WIDGET]: {};
+        [BridgeEventType.CLAIM_WITHDRAWAL_SUCCESS]: BridgeClaimWithdrawalSuccess;
+        [BridgeEventType.CLAIM_WITHDRAWAL_FAILURE]: BridgeClaimWithdrawalFailed;
+    } & OrchestrationMapping & ProviderEventMapping;
+    [WidgetType.ONRAMP]: {
+        [OnRampEventType.SUCCESS]: OnRampSuccess;
+        [OnRampEventType.FAILURE]: OnRampFailed;
+        [OnRampEventType.CLOSE_WIDGET]: {};
+    } & OrchestrationMapping & ProviderEventMapping;
+    [WidgetType.SALE]: {
+        [SaleEventType.SUCCESS]: SaleSuccess;
+        [SaleEventType.FAILURE]: SaleFailed;
+        [SaleEventType.REJECTED]: any;
+        [SaleEventType.CLOSE_WIDGET]: {};
+        [SaleEventType.TRANSACTION_SUCCESS]: SaleTransactionSuccess;
+        [SaleEventType.PAYMENT_METHOD]: SalePaymentMethod;
+        [SaleEventType.PAYMENT_TOKEN]: SalePaymentToken;
+        [SaleEventType.REQUEST_BRIDGE]: {};
+        [SaleEventType.REQUEST_SWAP]: {};
+        [SaleEventType.REQUEST_ONRAMP]: {};
+    } & OrchestrationMapping & ProviderEventMapping;
+    [WidgetType.IMMUTABLE_COMMERCE]: {
+        [CommerceEventType.INITIALISED]: CommerceWidgetParams;
+        [CommerceEventType.PROVIDER_UPDATED]: CommerceProviderUpdatedEvent;
+        [CommerceEventType.CLOSE]: {};
+        [CommerceEventType.SUCCESS]: CommerceSuccessEvent;
+        [CommerceEventType.FAILURE]: CommerceFailureEvent;
+        [CommerceEventType.DISCONNECTED]: {};
+        [CommerceEventType.USER_ACTION]: CommerceUserActionEvent;
+    };
+    [WidgetType.ADD_TOKENS]: {
+        [AddTokensEventType.CLOSE_WIDGET]: {};
+        [AddTokensEventType.CONNECT_SUCCESS]: AddTokensConnectSuccess;
+        [AddTokensEventType.SUCCESS]: AddTokensSuccess;
+        [AddTokensEventType.FAILURE]: AddTokensFailed;
+    } & OrchestrationMapping & ProviderEventMapping;
+    [WidgetType.PURCHASE]: {
+        [PurchaseEventType.CLOSE_WIDGET]: {};
+        [PurchaseEventType.CONNECT_SUCCESS]: PurchaseConnectSuccess;
+        [PurchaseEventType.SUCCESS]: PurchaseSuccess;
+        [PurchaseEventType.FAILURE]: PurchaseFailed;
+    } & OrchestrationMapping & ProviderEventMapping;
+};
+/**
+ * Represents an event emitted by a widget. The event type should match the event data
+ */
+/**
+ * Represents an event emitted by a widget.
+ * @template T - The widget type
+ * @template KEventName - The widget event name.
+ * @property {KEventName} type - The type of the event.
+ * @property {WidgetEventData[T][KEventName]} data - The data associated with the widget event.
+ */
+export type WidgetEvent<T extends WidgetType, KEventName extends keyof WidgetEventData[T]> = {
+    type: KEventName;
+    data: WidgetEventData[T][KEventName];
+};
+/**
+ * Represents an event emitted by a widget.
+ * @template KEventName - The orchestration event name.
+ * @property {KEventName} type
+ * @property {OrchestrationMapping[KEventName]} data
+ */
+export type OrchestrationEvent<KEventName extends keyof OrchestrationMapping> = {
+    /** The type of the event. */
+    type: KEventName;
+    /** The data associated with the event. */
+    data: OrchestrationMapping[KEventName];
+};
+/**
+ * Represents an event emitted by a widget.
+ * @template KEventName - The provider event name.
+ * @property {KEventName} type
+ * @property {ProviderEventMapping[KEventName]} data
+ */
+export type ProviderEvent<KEventName extends keyof ProviderEventMapping> = {
+    /** The type of the event. */
+    type: KEventName;
+    /** The data associated with the event. */
+    data: ProviderEventMapping[KEventName];
+};
+export interface IWidgetsFactory {
+    /**
+     * Create a new widget instance.
+     * @param type widget type to instantiate.
+     * @param props widget configurations and provider.
+     */
+    create: IWidgetsFactoryCreate;
+    /**
+     * Update the widgets provider instance.
+     * @param provider the provider instance to update all widgets.
+     */
+    updateProvider(provider: WrappedBrowserProvider): void;
+}
+export interface IWidgetsFactoryCreate {
+    (type: WidgetType.IMMUTABLE_COMMERCE, props?: WidgetProperties<WidgetType.IMMUTABLE_COMMERCE>): Widget<WidgetType.IMMUTABLE_COMMERCE>;
+    /** @deprecated
+     * Use WidgetType.IMMUTABLE_COMMERCE instead, see https://docs.immutable.com/products/zkEVM/checkout/commerce-widget
+     * */
+    <T extends Exclude<WidgetType, WidgetType.IMMUTABLE_COMMERCE>>(type: T, props?: WidgetProperties<T>): Widget<T>;
+}
+/**
+ * Widget interface. Every widget implements this interface.
+ */
+export interface Widget<T extends WidgetType> {
+    /**
+     * Mount a widget to a DOM ref element.
+     * @param id ID of the DOM element where the widget will be mounted.
+     * @param params widget parameters.
+     */
+    mount(id: string, params?: WidgetParameters[T]): void;
+    /**
+     * Unmount a widget and reset parameters
+     */
+    unmount(): void;
+    /**
+     * Update the widget properties
+     * @param props Widget specific properties including configuration
+     */
+    update(props: WidgetProperties<T>): void;
+    /**
+     * Add a listener for a widget event.
+     * @param event Widget specific event name.
+     * @param callback function to execute when the event is received.
+     */
+    addListener<KEventName extends keyof WidgetEventData[T]>(type: KEventName, callback: (data: WidgetEventData[T][KEventName]) => void): void;
+    /**
+     * Removes an event listener for a widget event.
+     * @param type Widget specific event name.
+     */
+    removeListener<KEventName extends keyof WidgetEventData[T]>(type: KEventName): void;
+}
+/**
+ * Represents the version of the Commerce Widgets to use defaults to (0.1.9-alpha)
+ * @property {number} major
+ * @property {number | undefined} minor
+ * @property {number | undefined} patch
+ * @property {'alpha' | undefined} prerelease
+ * @property {number | undefined} build
+ *
+ * @example
+ * { major: 0 } - use default version 0.1.9-alpha
+ * { major: 1 } - use version 1.x.x, pickup all new minor and patch versions released
+ * { major: 1, minor: 1 } - use version 1.1.x, pickup all new patch versions released
+ * { major: 1, minor: 2, patch: 3 } - use version 1.2.3 specifically
+ */
+export type SemanticVersion = {
+    /** The major version of the widgets, must specify a major version even if it is 0. */
+    major: number;
+    /** The minor version of the widgets, leaving this blank will use the latest minor based on major */
+    minor?: number;
+    /** The patch version of the widgets, leaving this blank will use the latest minor based on minor */
+    patch?: number;
+    /** The prerelease version of the widgets, can only be 'alpha'. Do not use in production. */
+    prerelease?: 'alpha';
+    /** The build version of the widgets. Do not use in production. */
+    build?: number;
+};
+/**
+ * Represents the global configuration options for the Commerce Widgets.
+ * @property {WidgetTheme | undefined} theme
+ * @property {Environment | undefined} environment
+ * @property {SemanticVersion | undefined} version
+ * @property {boolean | undefined} isOnRampEnabled
+ * @property {boolean | undefined} isSwapEnabled
+ * @property {boolean | undefined} isBridgeEnabled
+ */
+export type CheckoutWidgetsConfig = {
+    /** The theme of the Checkout Widget (default: "DARK") */
+    theme?: WidgetTheme;
+    /** The environment configuration (default: "SANDBOX") */
+    environment?: Environment;
+    /** The version of the Checkout Widgets js file to use (default: "0.1.x") */
+    version?: SemanticVersion;
+    /** Enable on-ramp top-up method (default: "true") */
+    isOnRampEnabled?: boolean;
+    /** Enable swap top-up method (default: "true") */
+    isSwapEnabled?: boolean;
+    /** Enable bridge top-up method (default: "true") */
+    isBridgeEnabled?: boolean;
+};
+export {};

package/dist/types/widgets/load.d.ts

@@ -0,0 +1,2 @@
+export declare function loadUnresolvedBundle(tag: HTMLScriptElement, scriptId: string, validVersion: string): void;
+export declare function getWidgetsEsmUrl(validVersion: string): string;

package/dist/types/widgets/load.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/widgets/version.d.ts

@@ -0,0 +1,23 @@
+import { SemanticVersion } from './definitions/types';
+import { CheckoutWidgetsVersionConfig } from '../types';
+/**
+ * Validates and builds a version string based on the given SemanticVersion object.
+ * If the version is undefined or has an invalid major version, it returns the default checkout version.
+ * If the version is all zeros, it also returns the default checkout version.
+ * Otherwise, it constructs a validated version string based on the major, minor, patch, and build numbers.
+ */
+export declare function validateAndBuildVersion(version: SemanticVersion | undefined): string;
+/**
+ * Fetches the latest version of the package from the NPM registry.
+ * Loads a specific latest version instead of relying on the latest tag helps with caching issues.
+ * Falls back to 'latest' if an error occurs or if the response is invalid.
+ * @returns {Promise<string>} A promise resolving to the latest version string or 'latest'.
+ */
+export declare function getLatestVersionFromNpm(): Promise<string>;
+/**
+ * Determines the version of the widgets to use based on the provided validated build version and checkout version config.
+ * If a version is provided in the widget init parameters, it uses that version.
+ * If the build version is an alpha, it uses that version.
+ * Defaults to 'latest' if no compatible version markers are found.
+ */
+export declare function determineWidgetsVersion(validatedBuildVersion: string, initVersionProvided: boolean, versionConfig?: CheckoutWidgetsVersionConfig): Promise<string>;

package/dist/types/widgets/version.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@imtbl/checkout-sdk",
+  "description": "Immutable Checkout SDK",
+  "version": "2.0.0-alpha.0",
+  "author": "immutable",
+  "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
+  "dependencies": {
+    "@imtbl/blockchain-data": "2.0.0-alpha.0",
+    "@imtbl/bridge-sdk": "2.0.0-alpha.0",
+    "@imtbl/config": "2.0.0-alpha.0",
+    "@imtbl/dex-sdk": "2.0.0-alpha.0",
+    "@imtbl/generated-clients": "2.0.0-alpha.0",
+    "@imtbl/metrics": "2.0.0-alpha.0",
+    "@imtbl/orderbook": "2.0.0-alpha.0",
+    "@imtbl/passport": "2.0.0-alpha.0",
+    "@metamask/detect-provider": "^2.0.0",
+    "axios": "^1.6.5",
+    "ethers": "^6.13.4",
+    "semver": "^7.4.0",
+    "uuid": "^8.3.2"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.3.36",
+    "@types/jest": "^29.4.3",
+    "@types/node": "^18.14.2",
+    "@types/semver": "^7.5.8",
+    "@types/uuid": "^8.3.4",
+    "esbuild-plugin-replace": "^1.4.0",
+    "eslint": "^8.40.0",
+    "jest": "^29.4.3",
+    "jest-environment-jsdom": "^29.4.3",
+    "text-encoding": "^0.7.0",
+    "tsup": "^8.3.5",
+    "typedoc": "^0.26.5",
+    "typedoc-plugin-markdown": "^4.2.3",
+    "typescript": "^5.6.2"
+  },
+  "exports": {
+    "development": {
+      "types": "./src/index.ts",
+      "browser": "./dist/browser/index.js",
+      "require": "./dist/node/index.cjs",
+      "default": "./dist/node/index.js"
+    },
+    "default": {
+      "types": "./dist/types/index.d.ts",
+      "browser": "./dist/browser/index.js",
+      "require": "./dist/node/index.cjs",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/immutable/ts-immutable-sdk",
+  "keywords": [
+    "immutablex"
+  ],
+  "license": "Apache-2.0",
+  "main": "dist/node/index.cjs",
+  "module": "dist/node/index.js",
+  "browser": "dist/browser/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "immutable/ts-immutable-sdk.git",
+  "source": "src/index.ts",
+  "type": "module",
+  "types": "./dist/types/index.d.ts",
+  "scripts": {
+    "build": "pnpm transpile && pnpm typegen",
+    "transpile": "tsup src/index.ts --config ./tsup.config.js",
+    "typegen": "tsc --customConditions default --emitDeclarationOnly --outDir dist/types",
+    "build:dev": "CHECKOUT_DEV_MODE=true pnpm build",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --skipErrorChecking --disableSources --out docs src/index.ts",
+    "lint": "eslint ./src --ext .ts,.jsx,.tsx --max-warnings=0",
+    "lint:fix": "eslint ./src --ext .ts,.jsx,.tsx --max-warnings=0 --fix",
+    "prepare:examplesdk": "pnpm --filter @examples/commerce-widget-nextjs exec mkdir -p tests/utils/local-widgets-js/ && cp ./dist/*.js $(pnpm --filter @examples/commerce-widget-nextjs exec pwd)/tests/utils/local-widgets-js/",
+    "prepare:testsdk": "pnpm --filter @tests/checkout-widgets-nextjs exec mkdir -p tests/utils/local-widgets-js/ && cp ./dist/*.js $(pnpm --filter @tests/checkout-widgets-nextjs exec pwd)/tests/utils/local-widgets-js/",
+    "start": "tsup --config ./tsup.config.js --watch",
+    "start:dev": "CHECKOUT_DEV_MODE=true pnpm start",
+    "start:local": "CHECKOUT_LOCAL_MODE=true pnpm start",
+    "test": "jest test",
+    "test:watch": "jest test --watch",
+    "typecheck": "tsc --customConditions default --noEmit"
+  }
+}