@ton/appkit 0.0.1-alpha.1 → 0.0.1

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,10 +1,97 @@
 {
   "name": "@ton/appkit",
-  "version": "0.0.1-alpha.1",
-  "description": "TON AppKit — SDK for building TON applications",
-  "main": "index.js",
-  "scripts": {},
-  "keywords": ["ton", "appkit", "blockchain", "sdk"],
-  "author": "TON Studio",
-  "license": "MIT"
-}
+  "version": "0.0.1",
+  "description": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ton-connect/kit"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./queries": {
+      "import": {
+        "types": "./dist/queries/index.d.ts",
+        "default": "./dist/queries/index.js"
+      },
+      "require": {
+        "types": "./dist/queries/index.d.ts",
+        "default": "./dist/queries/index.cjs"
+      }
+    },
+    "./swap/omniston": {
+      "import": {
+        "types": "./dist/swap/omniston/index.d.ts",
+        "default": "./dist/swap/omniston/index.js"
+      },
+      "require": {
+        "types": "./dist/swap/omniston/index.d.ts",
+        "default": "./dist/swap/omniston/index.cjs"
+      }
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "tonconnect": [
+        "./dist/connectors/tonconnect/index.d.ts"
+      ],
+      "queries": [
+        "./dist/queries/index.d.ts"
+      ],
+      "swap/omniston": [
+        "./dist/swap/omniston/index.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "@ton/walletkit": "0.0.8"
+  },
+  "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",
+    "tsup": "^8.5.0",
+    "typescript": "~5.8.3",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsup --onSuccess \"tsc --emitDeclarationOnly\"",
+    "dev": "pnpm run build --watch --no-clean",
+    "quality": "pnpm test",
+    "typecheck": "tsc --noEmit",
+    "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;
+};

package/src/actions/index.ts

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ *
+ */
+
+// Balances
+export {
+    getBalanceByAddress,
+    type GetBalanceByAddressOptions,
+    type GetBalanceByAddressReturnType,
+} from './balances/get-balance-by-address';
+export { getBalance, type GetBalanceOptions, type GetBalanceReturnType } from './balances/get-balance';
+
+// Connectors
+export { addConnector, type AddConnectorParameters, type AddConnectorReturnType } from './connectors/add-connector';
+export { connect, type ConnectParameters, type ConnectReturnType } from './connectors/connect';
+export { disconnect, type DisconnectReturnType, type DisconnectParameters } from './connectors/disconnect';
+export { getConnectors, type GetConnectorsReturnType } from './connectors/get-connectors';
+export {
+    watchConnectors,
+    type WatchConnectorsParameters,
+    type WatchConnectorsReturnType,
+} from './connectors/watch-connectors';
+export {
+    getConnectorById,
+    type GetConnectorByIdOptions,
+    type GetConnectorByIdReturnType,
+} from './connectors/get-connector-by-id';
+export {
+    watchConnectorById,
+    type WatchConnectorByIdParameters,
+    type WatchConnectorByIdReturnType,
+} from './connectors/watch-connector-by-id';
+
+// Jettons
+export { getJettonInfo, type GetJettonInfoOptions, type GetJettonInfoReturnType } from './jettons/get-jetton-info';
+export {
+    getJettonWalletAddress,
+    type GetJettonWalletAddressOptions,
+    type GetJettonWalletAddressReturnType,
+} from './jettons/get-jetton-wallet-address';
+export {
+    getJettonBalance,
+    type GetJettonBalanceOptions,
+    type GetJettonBalanceReturnType,
+} from './jettons/get-jetton-balance';
+export {
+    getJettonsByAddress,
+    type GetJettonsByAddressOptions,
+    type GetJettonsByAddressReturnType,
+} from './jettons/get-jettons-by-address';
+export { getJettons, type GetJettonsOptions, type GetJettonsReturnType } from './jettons/get-jettons';
+export {
+    createTransferJettonTransaction,
+    type CreateTransferJettonTransactionParameters,
+    type CreateTransferJettonTransactionReturnType,
+} from './jettons/create-transfer-jetton-transaction';
+export {
+    transferJetton,
+    type TransferJettonParameters,
+    type TransferJettonReturnType,
+} from './jettons/transfer-jetton';
+
+// Network
+export { getNetworks, type GetNetworksReturnType } from './network/get-networks';
+export { getNetwork, type GetNetworkReturnType } from './network/get-network';
+export { watchNetworks, type WatchNetworksParameters, type WatchNetworksReturnType } from './network/watch-networks';
+
+// NFT
+export {
+    getNftsByAddress,
+    type GetNftsByAddressOptions,
+    type GetNftsByAddressReturnType,
+} from './nft/get-nfts-by-address';
+export { getNfts, type GetNftsOptions, type GetNftsReturnType } from './nft/get-nfts';
+export { getNft, type GetNftOptions, type GetNftReturnType } from './nft/get-nft';
+export { transferNft, type TransferNftParameters, type TransferNftReturnType } from './nft/transfer-nft';
+
+// Providers
+export { registerProvider, type RegisterProviderOptions } from './providers/register-provider';
+
+// Signing
+export { signText, type SignTextParameters, type SignTextReturnType } from './signing/sign-text';
+export { signBinary, type SignBinaryParameters, type SignBinaryReturnType } from './signing/sign-binary';
+export { signCell, type SignCellParameters, type SignCellReturnType } from './signing/sign-cell';
+
+// Swap
+export { getSwapManager, type GetSwapManagerReturnType } from './swap/get-swap-manager';
+export { getSwapQuote, type GetSwapQuoteOptions, type GetSwapQuoteReturnType } from './swap/get-swap-quote';
+export {
+    buildSwapTransaction,
+    type BuildSwapTransactionOptions,
+    type BuildSwapTransactionReturnType,
+} from './swap/build-swap-transaction';
+
+// Transactions
+export {
+    sendTransaction,
+    type SendTransactionParameters,
+    type SendTransactionReturnType,
+} from './transaction/send-transaction';
+export { transferTon, type TransferTonParameters, type TransferTonReturnType } from './transaction/transfer-ton';
+export {
+    createTransferNftTransaction,
+    type CreateTransferNftTransactionParameters,
+    type CreateTransferNftTransactionReturnType,
+} from './nft/create-transfer-nft-transaction';
+export {
+    createTransferTonTransaction,
+    type CreateTransferTonTransactionParameters,
+    type CreateTransferTonTransactionReturnType,
+} from './transaction/create-transfer-ton-transaction';
+
+// Wallets
+export { getConnectedWallets, type GetConnectedWalletsReturnType } from './wallets/get-connected-wallets';
+export { getSelectedWallet, type GetSelectedWalletReturnType } from './wallets/get-selected-wallet';
+export {
+    setSelectedWalletId,
+    type SetSelectedWalletIdParameters,
+    type SetSelectedWalletIdReturnType,
+} from './wallets/set-selected-wallet-id';
+export {
+    watchSelectedWallet,
+    type WatchSelectedWalletParameters,
+    type WatchSelectedWalletReturnType,
+} from './wallets/watch-selected-wallet';
+export {
+    watchConnectedWallets,
+    type WatchConnectedWalletsParameters,
+    type WatchConnectedWalletsReturnType,
+} from './wallets/watch-connected-wallets';

package/src/actions/jettons/create-transfer-jetton-transaction.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 {
+    createJettonTransferPayload,
+    createTransferTransaction,
+    getJettonWalletAddressFromClient,
+    DEFAULT_JETTON_GAS_FEE,
+    parseUnits,
+} from '@ton/walletkit';
+
+import type { TransactionRequest } from '../../types/transaction';
+import type { AppKit } from '../../core/app-kit';
+import { getSelectedWallet } from '../wallets/get-selected-wallet';
+
+export interface CreateTransferJettonTransactionParameters {
+    jettonAddress: string;
+    recipientAddress: string;
+    amount: string;
+    jettonDecimals: number;
+    comment?: string;
+}
+
+export type CreateTransferJettonTransactionReturnType = TransactionRequest;
+
+/**
+ * Create a Jetton transfer transaction request
+ */
+export const createTransferJettonTransaction = async (
+    appKit: AppKit,
+    parameters: CreateTransferJettonTransactionParameters,
+): Promise<CreateTransferJettonTransactionReturnType> => {
+    const { jettonAddress, recipientAddress, amount, jettonDecimals, comment } = parameters;
+
+    const wallet = getSelectedWallet(appKit);
+
+    if (!wallet) {
+        throw new Error('Wallet not connected');
+    }
+
+    // Get client from network manager
+    const client = appKit.networkManager.getClient(wallet.getNetwork());
+
+    // Get jetton wallet address
+    const jettonWalletAddress = await getJettonWalletAddressFromClient(client, jettonAddress, wallet.getAddress());
+
+    // Create jetton transfer payload
+    const jettonPayload = createJettonTransferPayload({
+        amount: parseUnits(amount, jettonDecimals),
+        destination: recipientAddress,
+        responseDestination: wallet.getAddress(),
+        comment,
+    });
+
+    // Build transaction
+    return createTransferTransaction({
+        targetAddress: jettonWalletAddress,
+        amount: DEFAULT_JETTON_GAS_FEE,
+        payload: jettonPayload,
+        fromAddress: wallet.getAddress(),
+    });
+};

package/src/actions/jettons/get-jetton-balance.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { Network, getJettonBalanceFromClient, formatUnits } from '@ton/walletkit';
+import type { TokenAmount, UserFriendlyAddress } from '@ton/walletkit';
+
+import type { AppKit } from '../../core/app-kit';
+import { getJettonWalletAddress } from './get-jetton-wallet-address';
+
+export interface GetJettonBalanceOptions {
+    jettonAddress: UserFriendlyAddress;
+    ownerAddress: UserFriendlyAddress;
+    jettonDecimals: number;
+    network?: Network;
+}
+
+export type GetJettonBalanceReturnType = TokenAmount;
+
+export const getJettonBalance = async (
+    appKit: AppKit,
+    options: GetJettonBalanceOptions,
+): Promise<GetJettonBalanceReturnType> => {
+    const { jettonAddress, ownerAddress, jettonDecimals, network } = options;
+
+    const client = appKit.networkManager.getClient(network ?? Network.mainnet());
+
+    const jettonWalletAddress = await getJettonWalletAddress(appKit, {
+        jettonAddress,
+        ownerAddress,
+        network,
+    });
+    const balance = await getJettonBalanceFromClient(client, jettonWalletAddress);
+
+    return formatUnits(balance, jettonDecimals);
+};