@ton/appkit 0.0.1-alpha.2 → 0.0.2

package/docs/connectors.md

@@ -0,0 +1,135 @@
+# Connectors
+
+AppKit supports wallet connections through connectors. The primary connector is `TonConnect`.
+
+## TonConnect
+
+To use TonConnect, you need to install `@tonconnect/ui` and `@ton/appkit`.
+
+### Installation
+
+```bash
+npm install @ton/appkit @tonconnect/ui
+```
+
+### Import
+
+`TonConnectConnector` is located in a separate entry point `@ton/appkit/tonconnect` to allow tree-shaking for users who don't need TonConnect functionality.
+
+```typescript
+import { TonConnectConnector } from '@ton/appkit/tonconnect';
+```
+
+### Setup
+
+You can set up `TonConnectConnector` by passing `tonConnectOptions`. The connector will create the `TonConnectUI` instance internally.
+
+```ts
+const appKit = new AppKit({
+    networks: {
+        [Network.mainnet().chainId]: {
+            apiClient: {
+                url: 'https://toncenter.com',
+                key: 'your-key',
+            },
+        },
+    },
+    connectors: [
+        new TonConnectConnector({
+            tonConnectOptions: {
+                manifestUrl: 'https://my-app.com/tonconnect-manifest.json',
+            },
+        }),
+    ],
+});
+```
+
+Alternatively, you can pass an existing `TonConnectUI` instance:
+
+```ts
+// 1. Create TonConnectUI instance
+const tonConnectUI = new TonConnectUI({
+    manifestUrl: 'https://my-app.com/tonconnect-manifest.json',
+});
+
+// 2. Initialize AppKit
+const appKit = new AppKit({
+    networks: {
+        [Network.mainnet().chainId]: {
+            apiClient: {
+                url: 'https://toncenter.com',
+                key: 'your-key',
+            },
+        },
+    },
+    connectors: [new TonConnectConnector({ tonConnectUI })],
+});
+```
+
+### Add Connector Dynamically
+
+In some cases, you may need to add a connector after initialization. You can use the `addConnector` method for this purpose.
+
+```ts
+// 1. Initialize AppKit
+const appKit = new AppKit({
+    networks: {
+        [Network.mainnet().chainId]: {
+            apiClient: {
+                url: 'https://toncenter.com',
+                key: 'your-key',
+            },
+        },
+    },
+});
+
+// 2. Initialize TonConnect connector
+const connector = new TonConnectConnector({
+    tonConnectOptions: {
+        manifestUrl: 'https://my-app.com/tonconnect-manifest.json',
+    },
+});
+
+// 3. Add connector dynamically
+appKit.addConnector(connector);
+```
+
+### Configuration
+
+`TonConnectConnector` takes a configuration object:
+
+```typescript
+interface TonConnectConnectorConfig {
+    /**
+     * TonConnectUI options or instance
+     */
+    tonConnectUI?: TonConnectUI;
+    tonConnectOptions?: TonConnectUiCreateOptions;
+    /**
+     * Connector ID
+     * @default 'tonconnect'
+     */
+    id?: string;
+    /**
+     * Connector metadata
+     */
+    metadata?: ConnectorMetadata;
+}
+```
+
+### Connector Metadata
+
+You can provide metadata for the connector, which can be used to display connector information in the UI.
+
+```typescript
+interface ConnectorMetadata {
+    /**
+     * Connector name
+     */
+    name: string;
+    /**
+     * Connector icon URL
+     */
+    iconUrl?: string;
+}
+```

package/docs/query.md

@@ -0,0 +1,30 @@
+# Query & Mutations
+
+AppKit provides a separate entry point `@ton/appkit/queries` that contains standardized options for [TanStack Query](https://tanstack.com/query/latest) (v5).
+
+These options are framework-agnostic and allow you to easily integrate AppKit with TanStack Query in any environment (React, Vue, Svelte, Solid, etc.) to handle caching, background refetching, and state management for blockchain data.
+
+## Features
+
+-   **Separate Entry Point**: logic is isolated in `@ton/appkit/queries` and is not included in the main bundle, keeping your application lightweight if you don't use it.
+-   **TanStack Query Integration**: provides `queryOptions` and mutation logic compatible with TanStack Query.
+-   **Reusability**: used internally by `@ton/appkit-react`, but can be used to build other wrappers like `appkit-vue` or `appkit-svelte`.
+
+## Usage
+
+You can import query and mutation options directly from the queries entry point:
+
+```typescript
+import { getBalanceQueryOptions } from '@ton/appkit/queries';
+```
+
+Since these are standard TanStack Query options, you can use them with any adapter. For example, in React:
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { getBalanceQueryOptions } from '@ton/appkit/queries';
+
+const { data } = useQuery(getBalanceQueryOptions(appKit, { address: '...' }));
+```
+
+For more examples of how to use these queries and mutations to build custom hooks, you can check the source code of the [`@ton/appkit-react`](../appkit-react) library.

package/docs/swap.md

@@ -0,0 +1,66 @@
+# Swap
+
+AppKit supports swapping assets through the `SwapProvider` interface. The primary provider is `OmnistonSwapProvider`, which integrates with the [STON.fi](https://ston.fi) DEX aggregator via the [Omniston SDK](https://docs.ston.org/docs/developer-section/sdk/omniston-sdk).
+
+## Installation
+
+To use `OmnistonSwapProvider`, you need to install `@ston-fi/omniston-sdk`:
+
+```bash
+npm install @ston-fi/omniston-sdk
+```
+
+## Setup
+
+You can set up `OmnistonSwapProvider` by passing it to the `AppKit` constructor.
+
+```ts
+// Initialize AppKit with swap provider
+const appKit = new AppKit({
+    networks: {
+        [Network.mainnet().chainId]: {
+            apiClient: {
+                url: 'https://toncenter.com',
+                key: 'your-key',
+            },
+        },
+    },
+    providers: [
+        new OmnistonSwapProvider({
+            // Optional configuration
+            apiUrl: 'https://api.ston.fi',
+            defaultSlippageBps: 100, // 1%
+        }),
+    ],
+});
+```
+
+### Register Dynamically
+
+Alternatively, you can register the provider dynamically using `registerProvider`:
+
+```ts
+// 1. Initialize AppKit
+const appKit = new AppKit({
+    networks: {
+        [Network.mainnet().chainId]: {
+            apiClient: {
+                url: 'https://toncenter.com',
+                key: 'your-key',
+            },
+        },
+    },
+});
+
+// 2. Register swap provider
+const provider = new OmnistonSwapProvider({
+    // Optional configuration
+    apiUrl: 'https://api.ston.fi',
+});
+
+registerProvider(appKit, provider);
+```
+
+## Configuration
+
+For detailed configuration options and usage of `OmnistonSwapProvider`, please refer to the [Omniston SDK documentation](https://docs.ston.org/docs/developer-section/sdk/omniston-sdk) and the [provider documentation](../src/swap/omniston/README.md).

package/package.json

@@ -1,16 +1,96 @@
 {
   "name": "@ton/appkit",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.2",
   "description": "",
-  "main": "index.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/ton-connect/kit"
   },
+  "sideEffects": false,
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./queries": {
+      "import": {
+        "types": "./dist/esm/queries/index.d.ts",
+        "default": "./dist/esm/queries/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/queries/index.d.ts",
+        "default": "./dist/cjs/queries/index.js"
+      }
+    },
+    "./swap/omniston": {
+      "import": {
+        "types": "./dist/esm/swap/omniston/index.d.ts",
+        "default": "./dist/esm/swap/omniston/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/swap/omniston/index.d.ts",
+        "default": "./dist/cjs/swap/omniston/index.js"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "queries": [
+        "./dist/cjs/queries/index.d.ts"
+      ],
+      "swap/omniston": [
+        "./dist/cjs/swap/omniston/index.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "@ton/walletkit": "0.0.9"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": ">=5.0.0",
+    "@ton/core": "^0.62.0 || ^0.63.0",
+    "@ton/crypto": "^3.3.0",
+    "@tonconnect/ui": ">=2.4.1"
+  },
+  "peerDependenciesMeta": {
+    "@tonconnect/ui": {
+      "optional": true
+    },
+    "@ston-fi/omniston-sdk": {
+      "optional": true
+    },
+    "@tanstack/query-core": {
+      "optional": true
+    }
+  },
   "keywords": [],
   "author": "",
   "license": "ISC",
+  "devDependencies": {
+    "@tanstack/query-core": "5.90.20",
+    "@ton/core": "^0.63.0",
+    "@tonconnect/ui": "2.4.1",
+    "typescript": "~5.8.3",
+    "vitest": "^4.0.17"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "pnpm build:clean && pnpm build:cjs && pnpm build:esm",
+    "build:clean": "git clean -xdf dist",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "quality": "pnpm test",
+    "typecheck": "tsc --noEmit",
+    "clean": "git clean -xdf .turbo dist node_modules",
+    "test": "vitest run"
   }
 }

package/src/actions/balances/get-balance-by-address.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import { Address } from '@ton/core';
+import type { TokenAmount } from '@ton/walletkit';
+import { Network, formatUnits } from '@ton/walletkit';
+
+import type { AppKit } from '../../core/app-kit';
+
+export interface GetBalanceByAddressOptions {
+    address: string | Address;
+    network?: Network;
+}
+
+export type GetBalanceByAddressReturnType = TokenAmount;
+
+export const getBalanceByAddress = async (
+    appKit: AppKit,
+    options: GetBalanceByAddressOptions,
+): Promise<GetBalanceByAddressReturnType> => {
+    const { address, network } = options;
+    const addressString = Address.isAddress(address) ? address.toString() : Address.parse(address).toString();
+
+    const client = appKit.networkManager.getClient(network ?? Network.mainnet());
+    const balance = await client.getBalance(addressString);
+
+    return formatUnits(balance, 9);
+};

package/src/actions/balances/get-balance.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { TokenAmount, Network } from '@ton/walletkit';
+
+import type { AppKit } from '../../core/app-kit';
+import { getSelectedWallet } from '../wallets/get-selected-wallet';
+import { getBalanceByAddress } from './get-balance-by-address';
+
+export interface GetBalanceOptions {
+    network?: Network;
+}
+
+export type GetBalanceReturnType = TokenAmount | null;
+
+export const getBalance = async (appKit: AppKit, options: GetBalanceOptions = {}): Promise<GetBalanceReturnType> => {
+    const selectedWallet = getSelectedWallet(appKit);
+
+    if (!selectedWallet) {
+        return null;
+    }
+
+    return getBalanceByAddress(appKit, {
+        address: selectedWallet.getAddress(),
+        network: options.network,
+    });
+};

package/src/actions/connectors/add-connector.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { AppKit } from '../../core/app-kit';
+import type { Connector } from '../../types/connector';
+
+export type AddConnectorParameters = Connector;
+
+export type AddConnectorReturnType = () => void;
+
+/**
+ * Add a wallet connector
+ */
+export const addConnector = (appKit: AppKit, connector: AddConnectorParameters): AddConnectorReturnType => {
+    return appKit.addConnector(connector);
+};

package/src/actions/connectors/connect.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { AppKit } from '../../core/app-kit';
+
+export type ConnectParameters = {
+    connectorId: string;
+};
+
+export type ConnectReturnType = void;
+
+/**
+ * Connect wallet using specific connector
+ */
+export const connect = async (appKit: AppKit, parameters: ConnectParameters): Promise<ConnectReturnType> => {
+    const { connectorId } = parameters;
+    const connector = appKit.connectors.find((c) => c.id === connectorId);
+
+    if (!connector) {
+        throw new Error(`Connector with id "${connectorId}" not found`);
+    }
+
+    await connector.connectWallet();
+};

package/src/actions/connectors/disconnect.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { AppKit } from '../../core/app-kit';
+
+export type DisconnectParameters = {
+    connectorId: string;
+};
+
+export type DisconnectReturnType = void;
+
+/**
+ * Disconnect wallet using specific connector
+ */
+export const disconnect = async (appKit: AppKit, parameters: DisconnectParameters): Promise<DisconnectReturnType> => {
+    const { connectorId } = parameters;
+    const connector = appKit.connectors.find((c) => c.id === connectorId);
+
+    if (!connector) {
+        throw new Error(`Connector with id "${connectorId}" not found`);
+    }
+
+    await connector.disconnectWallet();
+};

package/src/actions/connectors/get-connector-by-id.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { Connector } from '../../types/connector';
+import type { AppKit } from '../../core/app-kit';
+
+export interface GetConnectorByIdOptions {
+    id: string;
+}
+
+export type GetConnectorByIdReturnType = Connector | undefined;
+
+/**
+ * Get connector by id
+ */
+export const getConnectorById = (appKit: AppKit, options: GetConnectorByIdOptions): GetConnectorByIdReturnType => {
+    return appKit.connectors.find((connector) => connector.id === options.id);
+};

package/src/actions/connectors/get-connectors.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { Connector } from '../../types/connector';
+import type { AppKit } from '../../core/app-kit';
+
+export type GetConnectorsReturnType = readonly Connector[];
+
+/**
+ * Get connected wallets
+ */
+export const getConnectors = (appKit: AppKit): GetConnectorsReturnType => {
+    return appKit.connectors;
+};

package/src/actions/connectors/watch-connector-by-id.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { AppKit } from '../../core/app-kit';
+import { CONNECTOR_EVENTS } from '../../core/app-kit';
+import type { Connector } from '../../types/connector';
+import { getConnectorById } from './get-connector-by-id';
+
+export interface WatchConnectorByIdParameters {
+    id: string;
+    onChange: (connector: Connector | undefined) => void;
+}
+
+export type WatchConnectorByIdReturnType = () => void;
+
+/**
+ * Watch connector by id
+ */
+export const watchConnectorById = (
+    appKit: AppKit,
+    parameters: WatchConnectorByIdParameters,
+): WatchConnectorByIdReturnType => {
+    const { id, onChange } = parameters;
+
+    const unsubscribe = appKit.emitter.on(CONNECTOR_EVENTS.CONNECTED, () => {
+        onChange(getConnectorById(appKit, { id }));
+    });
+
+    return unsubscribe;
+};

package/src/actions/connectors/watch-connectors.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) TonTech.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+import type { AppKit } from '../../core/app-kit';
+import { CONNECTOR_EVENTS } from '../../core/app-kit';
+import type { Connector } from '../../types/connector';
+import { getConnectors } from './get-connectors';
+
+export type WatchConnectorsParameters = {
+    onChange: (connectors: readonly Connector[]) => void;
+};
+
+export type WatchConnectorsReturnType = () => void;
+
+/**
+ * Watch connectors
+ */
+export const watchConnectors = (appKit: AppKit, parameters: WatchConnectorsParameters): WatchConnectorsReturnType => {
+    const { onChange } = parameters;
+
+    const unsubscribe = appKit.emitter.on(CONNECTOR_EVENTS.CONNECTED, () => {
+        onChange(getConnectors(appKit));
+    });
+
+    return unsubscribe;
+};