@ton/appkit 0.0.5-alpha.3 → 1.0.0-alpha.1

package/dist/esm/utils/predicate/is-number.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ *
+ */
+export const isNumber = (value) => {
+    if (typeof value !== 'number') {
+        return false;
+    }
+    if (Number.isNaN(value)) {
+        return false;
+    }
+    return Number.isFinite(value);
+};

package/dist/esm/utils/predicate/is-string.d.ts

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-export declare function isString(value: unknown): value is string;
+export declare const isString: (value: unknown) => value is string;
 //# sourceMappingURL=is-string.d.ts.map

package/dist/esm/utils/predicate/is-string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-string.d.ts","sourceRoot":"","sources":["../../../../src/utils/predicate/is-string.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD"}
+{"version":3,"file":"is-string.d.ts","sourceRoot":"","sources":["../../../../src/utils/predicate/is-string.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAElD,CAAC"}

package/dist/esm/utils/predicate/is-string.js

@@ -5,6 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  *
  */
-export function isString(value) {
+export const isString = (value) => {
     return typeof value === 'string';
-}
+};

package/docs/actions.md

@@ -1,9 +1,3 @@
-<!--
-This file is auto-generated. Do not edit manually.
-Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/actions.md
--->
-
 # Actions
 
 AppKit provides a set of actions to interact with the blockchain and wallets.
@@ -202,7 +196,6 @@ if (!selectedWallet) {
 const balance = await getJettonBalance(appKit, {
     jettonAddress: 'EQDBE420tTQIkoWcZ9pEOTKY63WVmwyIl3hH6yWl0r_h51Tl',
     ownerAddress: selectedWallet.getAddress(),
-    jettonDecimals: 6,
 });
 console.log('Jetton Balance:', balance.toString());
 ```
@@ -246,7 +239,6 @@ const tx = await createTransferJettonTransaction(appKit, {
     recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
     amount: '100', // 100 USDT
     comment: 'Hello Jetton',
-    jettonDecimals: 6,
 });
 console.log('Transfer Transaction:', tx);
 ```
@@ -260,7 +252,6 @@ const result = await transferJetton(appKit, {
     jettonAddress: 'EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs',
     recipientAddress: 'EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c',
     amount: '100',
-    jettonDecimals: 6,
 });
 console.log('Transfer Result:', result);
 ```
@@ -445,11 +436,12 @@ console.log('NFT Transfer Result:', result);
 Register a custom provider in AppKit (e.g., Swap or Streaming).
 
 ```ts
-const omnistonProvider = new OmnistonSwapProvider({
-    defaultSlippageBps: 100, // 1%
-});
-
-registerProvider(appKit, omnistonProvider);
+registerProvider(
+    appKit,
+    createOmnistonProvider({
+        defaultSlippageBps: 100, // 1%
+    }),
+);
 ```
 
 ## Signing
@@ -502,6 +494,45 @@ Get the `SwapManager` instance to interact with swap providers directly.
 const swapManager = getSwapManager(appKit);
 ```
 
+### `getSwapProvider`
+
+Get a specific swap provider by its ID.
+
+```ts
+const swapProvider = getSwapProvider(appKit, { id: 'stonfi' });
+```
+
+### `getSwapProviders`
+
+Get all registered swap providers. The returned array keeps a stable reference until the provider list changes.
+
+```ts
+const swapProviders = getSwapProviders(appKit);
+console.log(
+    'Registered providers:',
+    swapProviders.map((p) => p.providerId),
+);
+```
+
+### `setDefaultSwapProvider`
+
+Set the default swap provider. Subsequent quote and swap-transaction calls will use this provider when none is specified.
+
+```ts
+setDefaultSwapProvider(appKit, { providerId: 'stonfi' });
+```
+
+### `watchSwapProviders`
+
+Watch for new swap providers registration.
+
+```ts
+const unsubscribe = watchSwapProviders(appKit, {
+    onChange: () => console.log('Swap providers updated'),
+});
+unsubscribe();
+```
+
 ### `getSwapQuote`
 
 Get a swap quote from registered providers.
@@ -546,7 +577,7 @@ console.log('Available Staking Providers:', providers);
 
 ### `getStakingProviderInfo`
 
-Get information about a specific staking provider.
+Get dynamic information about a specific staking provider (e.g. APY, rate).
 
 ```ts
 const providerInfo = await getStakingProviderInfo(appKit, {
@@ -555,6 +586,17 @@ const providerInfo = await getStakingProviderInfo(appKit, {
 console.log('Provider Info:', providerInfo);
 ```
 
+### `getStakingProviderMetadata`
+
+Get static metadata about a specific staking provider.
+
+```ts
+const providerMetadata = getStakingProviderMetadata(appKit, {
+    providerId: 'tonstakers',
+});
+console.log('Provider Metadata:', providerMetadata);
+```
+
 ### `getStakingQuote`
 
 Get a staking or unstaking quote.
@@ -703,3 +745,10 @@ const unsubscribe = watchSelectedWallet(appKit, {
 
 // Later: unsubscribe();
 ```
+
+<!--
+This file is auto-generated. Do not edit manually.
+Changes will be overwritten when running the docs update script.
+Source template: template/packages/appkit/docs/actions.md
+-->
+

package/docs/connectors.md

@@ -1,9 +1,3 @@
-<!--
-This file is auto-generated. Do not edit manually.
-Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/connectors.md
--->
-
 # Connectors
 
 AppKit supports wallet connections through connectors. The primary connector is `TonConnect`.
@@ -116,26 +110,12 @@ interface TonConnectConnectorConfig {
      * @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.
+<!--
+This file is auto-generated. Do not edit manually.
+Changes will be overwritten when running the docs update script.
+Source template: template/packages/appkit/docs/connectors.md
+-->
 
-```typescript
-interface ConnectorMetadata {
-    /**
-     * Connector name
-     */
-    name: string;
-    /**
-     * Connector icon URL
-     */
-    iconUrl?: string;
-}
-```

package/docs/staking.md

@@ -1,9 +1,3 @@
-<!--
-This file is auto-generated. Do not edit manually.
-Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/staking.md
--->
-
 # Staking
 
 AppKit supports staking through various providers. Available providers:
@@ -56,3 +50,10 @@ registerProvider(appKit, createTonstakersProvider());
 ## Configuration
 
 - **Tonstakers**: [Tonstakers documentation](https://docs.tonstakers.com) and [provider README](https://github.com/ton-connect/kit/blob/main/packages/walletkit/src/defi/staking/tonstakers/README.md)
+
+<!--
+This file is auto-generated. Do not edit manually.
+Changes will be overwritten when running the docs update script.
+Source template: template/packages/appkit/docs/staking.md
+-->
+

package/docs/swap.md

@@ -1,9 +1,3 @@
-<!--
-This file is auto-generated. Do not edit manually.
-Changes will be overwritten when running the docs update script.
-Source template: template/packages/appkit/docs/swap.md
--->
-
 # Swap
 
 AppKit supports swapping assets through the `SwapProvider` interface. Available providers:
@@ -37,11 +31,11 @@ const appKit = new AppKit({
         },
     },
     providers: [
-        new OmnistonSwapProvider({
+        createOmnistonProvider({
             apiUrl: 'https://api.ston.fi',
             defaultSlippageBps: 100, // 1%
         }),
-        new DeDustSwapProvider({
+        createDeDustProvider({
             defaultSlippageBps: 100,
             referralAddress: 'EQ...', // Optional
         }),
@@ -67,11 +61,18 @@ const appKit = new AppKit({
 });
 
 // 2. Register swap providers
-registerProvider(appKit, new OmnistonSwapProvider({ defaultSlippageBps: 100 }));
-registerProvider(appKit, new DeDustSwapProvider({ defaultSlippageBps: 100 }));
+registerProvider(appKit, createOmnistonProvider({ defaultSlippageBps: 100 }));
+registerProvider(appKit, createDeDustProvider({ defaultSlippageBps: 100 }));
 ```
 
 ## Configuration
 
 - **Omniston**: [Omniston SDK documentation](https://docs.ston.org/docs/developer-section/sdk/omniston-sdk) and [provider README](https://github.com/ton-connect/kit/blob/main/packages/walletkit/src/defi/swap/omniston/README.md)
 - **DeDust**: [provider README](https://github.com/ton-connect/kit/blob/main/packages/walletkit/src/defi/swap/dedust/README.md)
+
+<!--
+This file is auto-generated. Do not edit manually.
+Changes will be overwritten when running the docs update script.
+Source template: template/packages/appkit/docs/swap.md
+-->
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ton/appkit",
-  "version": "0.0.5-alpha.3",
+  "version": "1.0.0-alpha.1",
   "description": "",
   "repository": {
     "type": "git",
@@ -79,7 +79,8 @@
     }
   },
   "dependencies": {
-    "@ton/walletkit": "0.0.12-alpha.3"
+    "lru-cache": "11.3.5",
+    "@ton/walletkit": "1.0.0-alpha.1"
   },
   "peerDependencies": {
     "@tanstack/query-core": ">=5.0.0",
@@ -104,7 +105,7 @@
   "devDependencies": {
     "@tanstack/query-core": "5.99.0",
     "@ton/core": "0.63.1",
-    "@tonconnect/ui": "2.4.4",
+    "@tonconnect/ui": "2.5.0-alpha.0",
     "typescript": "~5.9.3",
     "vitest": "^4.1.4"
   },

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

@@ -27,9 +27,15 @@ export const watchConnectorById = (
 ): WatchConnectorByIdReturnType => {
     const { id, onChange } = parameters;
 
-    const unsubscribe = appKit.emitter.on(CONNECTOR_EVENTS.CONNECTED, () => {
+    const handler = (): void => {
         onChange(getConnectorById(appKit, { id }));
-    });
+    };
 
-    return unsubscribe;
+    const unsubscribeAdded = appKit.emitter.on(CONNECTOR_EVENTS.ADDED, handler);
+    const unsubscribeRemoved = appKit.emitter.on(CONNECTOR_EVENTS.REMOVED, handler);
+
+    return () => {
+        unsubscribeAdded();
+        unsubscribeRemoved();
+    };
 };

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

@@ -23,9 +23,15 @@ export type WatchConnectorsReturnType = () => void;
 export const watchConnectors = (appKit: AppKit, parameters: WatchConnectorsParameters): WatchConnectorsReturnType => {
     const { onChange } = parameters;
 
-    const unsubscribe = appKit.emitter.on(CONNECTOR_EVENTS.CONNECTED, () => {
+    const handler = (): void => {
         onChange(getConnectors(appKit));
-    });
+    };
 
-    return unsubscribe;
+    const unsubscribeAdded = appKit.emitter.on(CONNECTOR_EVENTS.ADDED, handler);
+    const unsubscribeRemoved = appKit.emitter.on(CONNECTOR_EVENTS.REMOVED, handler);
+
+    return () => {
+        unsubscribeAdded();
+        unsubscribeRemoved();
+    };
 };

package/src/actions/index.ts

@@ -115,7 +115,19 @@ export { signCell, type SignCellParameters, type SignCellReturnType } from './si
 
 // Swap
 export { getSwapManager, type GetSwapManagerReturnType } from './swap/get-swap-manager';
+export { getSwapProvider, type GetSwapProviderOptions, type GetSwapProviderReturnType } from './swap/get-swap-provider';
+export { getSwapProviders, type GetSwapProvidersReturnType } from './swap/get-swap-providers';
+export {
+    setDefaultSwapProvider,
+    type SetDefaultSwapProviderParameters,
+    type SetDefaultSwapProviderReturnType,
+} from './swap/set-default-swap-provider';
 export { getSwapQuote, type GetSwapQuoteOptions, type GetSwapQuoteReturnType } from './swap/get-swap-quote';
+export {
+    watchSwapProviders,
+    type WatchSwapProvidersParameters,
+    type WatchSwapProvidersReturnType,
+} from './swap/watch-swap-providers';
 export {
     buildSwapTransaction,
     type BuildSwapTransactionOptions,
@@ -125,6 +137,21 @@ export {
 // Staking
 export { getStakingManager, type GetStakingManagerReturnType } from './staking/get-staking-manager';
 export { getStakingProviders, type GetStakingProvidersReturnType } from './staking/get-staking-providers';
+export {
+    getStakingProvider,
+    type GetStakingProviderOptions,
+    type GetStakingProviderReturnType,
+} from './staking/get-staking-provider';
+export {
+    setDefaultStakingProvider,
+    type SetDefaultStakingProviderParameters,
+    type SetDefaultStakingProviderReturnType,
+} from './staking/set-default-staking-provider';
+export {
+    watchStakingProviders,
+    type WatchStakingProvidersParameters,
+    type WatchStakingProvidersReturnType,
+} from './staking/watch-staking-providers';
 export {
     getStakingQuote,
     type GetStakingQuoteOptions,
@@ -145,6 +172,11 @@ export {
     type GetStakingProviderInfoOptions,
     type GetStakingProviderInfoReturnType,
 } from './staking/get-staking-provider-info';
+export {
+    getStakingProviderMetadata,
+    type GetStakingProviderMetadataOptions,
+    type GetStakingProviderMetadataReturnType,
+} from './staking/get-staking-provider-metadata';
 
 // Transactions
 export {

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

@@ -17,12 +17,14 @@ import {
 import type { TransactionRequest } from '../../types/transaction';
 import type { AppKit } from '../../core/app-kit';
 import { getSelectedWallet } from '../wallets/get-selected-wallet';
+import { getJettonInfo } from './get-jetton-info';
+import { isNumber } from '../../utils';
 
 export interface CreateTransferJettonTransactionParameters {
     jettonAddress: string;
     recipientAddress: string;
     amount: string;
-    jettonDecimals: number;
+    jettonDecimals?: number;
     comment?: string;
 }
 
@@ -44,16 +46,30 @@ export const createTransferJettonTransaction = async (
     }
 
     // Get client from network manager
-    const client = appKit.networkManager.getClient(wallet.getNetwork());
+    const network = wallet.getNetwork();
+    const client = appKit.networkManager.getClient(network);
 
     // Get jetton wallet address
-    const jettonWalletAddress = await getJettonWalletAddressFromClient(client, jettonAddress, wallet.getAddress());
+    const ownerAddress = wallet.getAddress();
+    const jettonWalletAddress = await getJettonWalletAddressFromClient(client, jettonAddress, ownerAddress);
+
+    let decimals = jettonDecimals;
+
+    if (!isNumber(decimals)) {
+        const jettonInfo = await getJettonInfo(appKit, { address: jettonAddress, network });
+
+        if (!isNumber(jettonInfo?.decimals)) {
+            throw new Error(`Jetton decimals not found for address ${jettonAddress}`);
+        }
+
+        decimals = jettonInfo.decimals;
+    }
 
     // Create jetton transfer payload
     const jettonPayload = createJettonTransferPayload({
-        amount: parseUnits(amount, jettonDecimals),
+        amount: parseUnits(amount, decimals),
         destination: recipientAddress,
-        responseDestination: wallet.getAddress(),
+        responseDestination: ownerAddress,
         comment,
     });
 
@@ -62,6 +78,6 @@ export const createTransferJettonTransaction = async (
         targetAddress: jettonWalletAddress,
         amount: DEFAULT_JETTON_GAS_FEE,
         payload: jettonPayload,
-        fromAddress: wallet.getAddress(),
+        fromAddress: ownerAddress,
     });
 };

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

@@ -11,13 +11,14 @@ import type { TokenAmount, UserFriendlyAddress } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
 import { getJettonWalletAddress } from './get-jetton-wallet-address';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import { getJettonInfo } from './get-jetton-info';
+import { isNumber, resolveNetwork } from '../../utils';
 import type { Network } from '../../types/network';
 
 export interface GetJettonBalanceOptions {
     jettonAddress: UserFriendlyAddress;
     ownerAddress: UserFriendlyAddress;
-    jettonDecimals: number;
+    jettonDecimals?: number;
     network?: Network;
 }
 
@@ -38,5 +39,11 @@ export const getJettonBalance = async (
     });
     const balance = await getJettonBalanceFromClient(client, jettonWalletAddress);
 
-    return formatUnits(balance, jettonDecimals);
+    if (isNumber(jettonDecimals)) {
+        return formatUnits(balance, jettonDecimals);
+    }
+
+    const jettonInfo = await getJettonInfo(appKit, { address: jettonAddress, network });
+
+    return formatUnits(balance, jettonInfo?.decimals ?? 0);
 };

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

@@ -9,8 +9,9 @@
 import type { JettonInfo } from '@ton/walletkit';
 
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
+import { toBounceableAddress, resolveNetwork, isJettonInfo } from '../../utils';
 import type { Network } from '../../types/network';
+import { getCacheKey } from '../../core/cache';
 
 export interface GetJettonInfoOptions {
     address: string;
@@ -19,16 +20,23 @@ export interface GetJettonInfoOptions {
 
 export type GetJettonInfoReturnType = JettonInfo | null;
 
+const getJettonInfoCacheKey = getCacheKey('jetton-info');
+
 export const getJettonInfo = async (
     appKit: AppKit,
     options: GetJettonInfoOptions,
 ): Promise<GetJettonInfoReturnType> => {
-    const { address, network } = options;
+    const address = toBounceableAddress(options.address);
+    const network = resolveNetwork(appKit, options.network);
+    const cacheKey = getJettonInfoCacheKey(address, network.chainId);
+
+    const cached = await appKit.cache.get(cacheKey);
+    if (cached && isJettonInfo(cached)) return cached;
 
-    const client = appKit.networkManager.getClient(resolveNetwork(appKit, network));
+    const client = appKit.networkManager.getClient(network);
 
     const response = await client.jettonsByAddress({
-        address: address,
+        address,
         offset: 0,
         limit: 1,
     });
@@ -61,13 +69,17 @@ export const getJettonInfo = async (
         }
     }
 
-    return {
+    const result: GetJettonInfoReturnType = {
+        address,
         decimals,
-        address: jetton.jetton,
         name: tokenInfo?.name ?? '',
         symbol: tokenInfo?.symbol ?? '',
         description: tokenInfo?.description ?? '',
         image: tokenInfo?.image,
         uri: tokenInfo?.extra?.uri,
     };
+
+    await appKit.cache.set(cacheKey, result);
+
+    return result;
 };

package/src/actions/jettons/get-jetton-wallet-address.ts

@@ -7,11 +7,12 @@
  */
 
 import { getJettonWalletAddressFromClient } from '@ton/walletkit';
-import type { UserFriendlyAddress } from '@ton/walletkit';
 
+import type { UserFriendlyAddress } from '../../types/primitives';
 import type { AppKit } from '../../core/app-kit';
-import { resolveNetwork } from '../../utils/network/resolve-network';
 import type { Network } from '../../types/network';
+import { getCacheKey } from '../../core/cache';
+import { isFriendlyTonAddress, resolveNetwork, toBounceableAddress } from '../../utils';
 
 export interface GetJettonWalletAddressOptions {
     jettonAddress: UserFriendlyAddress;
@@ -21,13 +22,26 @@ export interface GetJettonWalletAddressOptions {
 
 export type GetJettonWalletAddressReturnType = UserFriendlyAddress;
 
+const getJettonWalletCacheKey = getCacheKey('jetton-wallet-address');
+
 export const getJettonWalletAddress = async (
     appKit: AppKit,
     options: GetJettonWalletAddressOptions,
 ): Promise<GetJettonWalletAddressReturnType> => {
-    const { jettonAddress, ownerAddress, network } = options;
+    const ownerAddress = toBounceableAddress(options.ownerAddress);
+    const jettonAddress = toBounceableAddress(options.jettonAddress);
+    const network = resolveNetwork(appKit, options.network);
+
+    const cacheKey = getJettonWalletCacheKey(network.chainId, ownerAddress, jettonAddress);
+
+    const cached = await appKit.cache.get(cacheKey);
+    if (cached && isFriendlyTonAddress(cached)) {
+        return cached;
+    }
 
-    const client = appKit.networkManager.getClient(resolveNetwork(appKit, network));
+    const client = appKit.networkManager.getClient(network);
+    const jettonWalletAddress = await getJettonWalletAddressFromClient(client, jettonAddress, ownerAddress);
+    await appKit.cache.set(cacheKey, jettonWalletAddress);
 
-    return getJettonWalletAddressFromClient(client, jettonAddress, ownerAddress);
+    return jettonWalletAddress;
 };

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

@@ -19,7 +19,7 @@ export interface GetNftOptions {
     network?: Network;
 }
 
-export type GetNftReturnType = NFT | null;
+export type GetNftReturnType = NFT | undefined;
 
 export const getNft = async (appKit: AppKit, options: GetNftOptions): Promise<GetNftReturnType> => {
     const { address, network } = options;

package/src/actions/providers/register-provider.ts

@@ -8,9 +8,10 @@
 
 import type { ProviderInput } from '@ton/walletkit';
 
+import type { AppKitProvider } from '../../types/provider';
 import type { AppKit } from '../../core/app-kit';
 
-export type RegisterProviderOptions = ProviderInput;
+export type RegisterProviderOptions = ProviderInput<AppKitProvider>;
 
 /**
  * Register provider

package/src/actions/staking/get-staking-provider-metadata.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 { StakingProviderMetadata, Network } from '@ton/walletkit';
+
+import { resolveNetwork } from '../../utils';
+import type { AppKit } from '../../core/app-kit';
+
+export type GetStakingProviderMetadataOptions = {
+    network?: Network;
+    providerId?: string;
+};
+
+export type GetStakingProviderMetadataReturnType = StakingProviderMetadata;
+
+/**
+ * Get staking provider static metadata
+ */
+export const getStakingProviderMetadata = (
+    appKit: AppKit,
+    options: GetStakingProviderMetadataOptions = {},
+): GetStakingProviderMetadataReturnType => {
+    return appKit.stakingManager.getStakingProviderMetadata(
+        resolveNetwork(appKit, options.network),
+        options.providerId,
+    );
+};