@ton/appkit 0.0.1-alpha.1 → 0.0.1

package/src/connectors/tonconnect/utils/transaction.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 { SendTransactionRequest } from '@tonconnect/sdk';
+
+import type { TransactionRequest, TransactionRequestMessage } from '../../../types/transaction';
+
+/**
+ * Default transaction validity duration in seconds (5 minutes)
+ */
+export const DEFAULT_TRANSACTION_VALIDITY_SECONDS = 300;
+
+/**
+ * Convert TonWalletKit TransactionRequest to TonConnect SendTransactionRequest format
+ */
+export function toTonConnectTransaction(request: TransactionRequest): SendTransactionRequest {
+    return {
+        validUntil: request.validUntil ?? Math.floor(Date.now() / 1000) + DEFAULT_TRANSACTION_VALIDITY_SECONDS,
+        messages: request.messages.map(toTonConnectMessage),
+    };
+}
+
+/**
+ * Convert a single TransactionRequestMessage to TonConnect message format
+ */
+export function toTonConnectMessage(msg: TransactionRequestMessage): {
+    address: string;
+    amount: string;
+    payload?: string;
+    stateInit?: string;
+} {
+    return {
+        address: msg.address,
+        amount: String(msg.amount),
+        payload: msg.payload,
+        stateInit: msg.stateInit,
+    };
+}
+
+/**
+ * Get current timestamp plus validity duration
+ */
+export function getValidUntil(validitySeconds = DEFAULT_TRANSACTION_VALIDITY_SECONDS): number {
+    return Math.floor(Date.now() / 1000) + validitySeconds;
+}

package/src/core/app-kit/constants/events.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ *
+ */
+
+/**
+ * Connector events
+ */
+export const CONNECTOR_EVENTS = {
+    CONNECTED: 'connector:connected',
+    DISCONNECTED: 'connector:disconnected',
+} as const;
+
+/**
+ * Wallet events
+ */
+export const WALLETS_EVENTS = {
+    UPDATED: 'wallets:updated',
+    SELECTION_CHANGED: 'wallets:selection-changed',
+} as const;
+
+/**
+ * Networks events
+ */
+export const NETWORKS_EVENTS = {
+    UPDATED: 'networks:updated',
+} as const;
+
+/**
+ * Plugin events
+ */
+export const PLUGIN_EVENTS = {
+    REGISTERED: 'plugin:registered',
+} as const;

package/src/core/app-kit/index.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.
+ *
+ */
+
+export { AppKit } from './services/app-kit';
+export { CONNECTOR_EVENTS, WALLETS_EVENTS, PLUGIN_EVENTS, NETWORKS_EVENTS } from './constants/events';
+
+export type { AppKitConfig } from './types/config';
+export type {
+    AppKitEmitter,
+    AppKitEvents,
+    WalletConnectedPayload,
+    WalletDisconnectedPayload,
+    PluginRegisteredPayload,
+} from './types/events';

package/src/core/app-kit/services/app-kit-network-manager.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { ApiClient, Network } from '@ton/walletkit';
+import { KitNetworkManager } from '@ton/walletkit';
+
+import { NETWORKS_EVENTS } from '../constants/events';
+import type { AppKitEmitter } from '../types/events';
+
+export class AppKitNetworkManager extends KitNetworkManager {
+    private emitter: AppKitEmitter;
+
+    constructor(options: ConstructorParameters<typeof KitNetworkManager>[0], emitter: AppKitEmitter) {
+        super(options);
+        this.emitter = emitter;
+    }
+
+    override setClient(network: Network, client: ApiClient): void {
+        super.setClient(network, client);
+        this.emitter.emit(NETWORKS_EVENTS.UPDATED, {}, 'network-manager');
+    }
+}

package/src/core/app-kit/services/app-kit.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 { NetworkManager } from '@ton/walletkit';
+import { Network, SwapManager } from '@ton/walletkit';
+import type { Provider } from 'src/types/provider';
+
+import type { AppKitConfig } from '../types/config';
+import type { Connector } from '../../../types/connector';
+import { Emitter } from '../../emitter';
+import { CONNECTOR_EVENTS, WALLETS_EVENTS } from '../constants/events';
+import type { AppKitEmitter, AppKitEvents } from '../types/events';
+import type { WalletInterface } from '../../../types/wallet';
+import { WalletsManager } from '../../wallets-manager';
+import { AppKitNetworkManager } from './app-kit-network-manager';
+
+/**
+ * Central hub for wallet management.
+ * Stores emitter, providers, and manages wallet connections.
+ */
+export class AppKit {
+    readonly emitter: AppKitEmitter;
+    readonly connectors: Connector[] = [];
+    readonly walletsManager: WalletsManager;
+    readonly swapManager: SwapManager;
+
+    readonly networkManager: NetworkManager;
+    readonly config: AppKitConfig;
+
+    constructor(config: AppKitConfig) {
+        this.config = config;
+
+        this.emitter = new Emitter<AppKitEvents>();
+        this.emitter.on(CONNECTOR_EVENTS.CONNECTED, this.updateWalletsFromConnectors.bind(this));
+        this.emitter.on(CONNECTOR_EVENTS.DISCONNECTED, this.updateWalletsFromConnectors.bind(this));
+
+        // Use provided networks config or default to mainnet
+        const networks = config.networks ?? {
+            [Network.mainnet().chainId]: {},
+        };
+
+        this.networkManager = new AppKitNetworkManager({ networks }, this.emitter);
+        this.walletsManager = new WalletsManager(this.emitter);
+        this.swapManager = new SwapManager();
+
+        if (config.connectors) {
+            config.connectors.forEach((connector) => {
+                this.addConnector(connector);
+            });
+        }
+
+        if (config.providers) {
+            config.providers.forEach((provider) => {
+                this.registerProvider(provider);
+            });
+        }
+    }
+
+    /**
+     * Add a wallet connector
+     */
+    addConnector(connector: Connector): () => void {
+        const id = connector.id;
+        const oldConnector = this.connectors.find((c) => c.id === id);
+
+        if (oldConnector) {
+            this.removeConnector(oldConnector);
+        }
+
+        this.connectors.push(connector);
+        connector.initialize(this.emitter, this.networkManager);
+
+        return () => {
+            this.removeConnector(connector);
+        };
+    }
+
+    /**
+     * Remove a wallet connector
+     */
+    removeConnector(connector: Connector): void {
+        const id = connector.id;
+        const oldConnector = this.connectors.find((c) => c.id === id);
+
+        if (oldConnector) {
+            oldConnector.destroy();
+            this.connectors.splice(this.connectors.indexOf(oldConnector), 1);
+        }
+    }
+
+    /**
+     * Add a provider
+     */
+    registerProvider(provider: Provider): void {
+        switch (provider.type) {
+            case 'swap':
+                this.swapManager.registerProvider(provider);
+                break;
+            default:
+                throw new Error('Unknown provider type');
+        }
+    }
+
+    /**
+     * Get all connected wallets from all connectors
+     */
+    private updateWalletsFromConnectors(): void {
+        const allWallets: WalletInterface[] = [];
+
+        for (const connector of this.connectors.values()) {
+            const wallets = connector.getConnectedWallets();
+            allWallets.push(...wallets);
+        }
+
+        this.walletsManager.setWallets(allWallets);
+        this.emitter.emit(WALLETS_EVENTS.UPDATED, { wallets: allWallets }, 'appkit');
+    }
+}

package/src/core/app-kit/types/config.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { NetworkAdapters } from '@ton/walletkit';
+
+import type { Connector } from '../../../types/connector';
+import type { Provider } from '../../../types/provider';
+
+/**
+ * Configuration for AppKit
+ */
+export interface AppKitConfig {
+    /**
+     * Network configuration
+     * At least one network must be configured.
+     *
+     * Keys are chain IDs (use `Network.mainnet().chainId` or `Network.testnet().chainId`)
+     * Values contain apiClient configuration (url and optional API key)
+     */
+    networks?: NetworkAdapters;
+    connectors?: Connector[];
+    providers?: Provider[];
+}

package/src/core/app-kit/types/events.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 { Emitter } from '../../emitter';
+import type { CONNECTOR_EVENTS, WALLETS_EVENTS, PLUGIN_EVENTS, NETWORKS_EVENTS } from '../constants/events';
+import type { WalletInterface } from '../../../types/wallet';
+
+export interface WalletConnectedPayload {
+    wallets: WalletInterface[];
+    connectorId: string;
+}
+
+export interface WalletDisconnectedPayload {
+    connectorId: string;
+}
+
+export interface PluginRegisteredPayload {
+    pluginId: string;
+    pluginType: string;
+}
+
+export interface AppKitEvents {
+    // Connector events
+    [CONNECTOR_EVENTS.CONNECTED]: WalletConnectedPayload;
+    [CONNECTOR_EVENTS.DISCONNECTED]: WalletDisconnectedPayload;
+
+    // Wallets events
+    [WALLETS_EVENTS.UPDATED]: { wallets: WalletInterface[] };
+    [WALLETS_EVENTS.SELECTION_CHANGED]: { walletId: string | null };
+
+    // Networks events
+    [NETWORKS_EVENTS.UPDATED]: Record<string, never>;
+
+    // Plugin events
+    [PLUGIN_EVENTS.REGISTERED]: PluginRegisteredPayload;
+}
+
+export type AppKitEmitter = Emitter<AppKitEvents>;

package/src/core/emitter/index.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ *
+ */
+
+/**
+ * Events Feature
+ * Provides Emitter implementation
+ */
+export { Emitter } from './services/emitter';
+
+export type { EventPayload, AppKitEvent, EventListener } from './types/events';

package/src/core/emitter/services/emitter.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { EventListener, AppKitEvent, EventPayload } from '../types/events';
+
+export class Emitter<Events extends { [K in keyof Events]: EventPayload }> {
+    private listeners = new Map<keyof Events, Set<unknown>>();
+
+    emit<K extends keyof Events>(type: K, payload: Events[K], source: string): void {
+        const event: AppKitEvent<Events[K]> = {
+            type: type as string,
+            payload,
+            source,
+            timestamp: Date.now(),
+        };
+
+        const listeners = this.listeners.get(type);
+
+        if (listeners) {
+            listeners.forEach((listener) => {
+                (listener as EventListener<Events[K]>)(event);
+            });
+        }
+    }
+
+    on<K extends keyof Events>(type: K, listener: EventListener<Events[K]>): () => void {
+        if (!this.listeners.has(type)) {
+            this.listeners.set(type, new Set());
+        }
+
+        this.listeners.get(type)!.add(listener as unknown);
+
+        return () => this.off(type, listener);
+    }
+
+    off<K extends keyof Events>(type: K, listener: EventListener<Events[K]>): void {
+        this.listeners.get(type)?.delete(listener as unknown);
+    }
+
+    once<K extends keyof Events>(type: K, listener: EventListener<Events[K]>): () => void {
+        const wrapper = (event: AppKitEvent<Events[K]>) => {
+            this.off(type, wrapper);
+            listener(event);
+        };
+
+        return this.on(type, wrapper);
+    }
+}

package/src/core/emitter/types/events.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type EventPayload = object;
+
+export interface AppKitEvent<T extends EventPayload = EventPayload> {
+    type: string;
+    payload: T;
+    source: string;
+    timestamp: number;
+}
+
+export type EventListener<T extends EventPayload = EventPayload> = (event: AppKitEvent<T>) => void;

package/src/core/wallets-manager/index.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { WalletsManager } from './services/wallets-manager';

package/src/core/wallets-manager/services/wallets-manager.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 { AppKitEmitter } from '../../../core/app-kit';
+import { WALLETS_EVENTS } from '../../../core/app-kit';
+import type { WalletInterface } from '../../../types/wallet';
+
+/**
+ * Manages connected wallets.
+ */
+export class WalletsManager {
+    private _wallets: WalletInterface[];
+    private _selectedWalletId: string | null;
+    private emitter: AppKitEmitter;
+
+    constructor(emitter: AppKitEmitter) {
+        this._wallets = [];
+        this._selectedWalletId = null;
+        this.emitter = emitter;
+    }
+
+    /**
+     * All connected wallets
+     */
+    get wallets(): WalletInterface[] {
+        return this._wallets;
+    }
+
+    /**
+     * Selected wallet id
+     */
+    get selectedWalletId(): string | null {
+        return this._selectedWalletId;
+    }
+
+    /**
+     * Selected wallet
+     */
+    get selectedWallet(): WalletInterface | null {
+        if (!this._selectedWalletId) {
+            return null;
+        }
+
+        return this._wallets.find((wallet) => wallet.getWalletId() === this._selectedWalletId) ?? null;
+    }
+
+    /**
+     * Set selected wallet id
+     */
+    setSelectedWalletId(id: string | null): void {
+        this._selectedWalletId = id;
+    }
+
+    /**
+     * Set connected wallets
+     * Automatically handles selected wallet state
+     */
+    setWallets(wallets: WalletInterface[]): void {
+        this._wallets = wallets;
+
+        // If currently selected wallet is still in the new list, keep it
+        if (this._selectedWalletId && wallets.some((w) => w.getWalletId() === this._selectedWalletId)) {
+            return;
+        }
+
+        // If list is not empty, auto-select the first one
+        if (wallets.length > 0) {
+            this._selectedWalletId = wallets[0].getWalletId();
+            this.emitter.emit(
+                WALLETS_EVENTS.SELECTION_CHANGED,
+                { walletId: this._selectedWalletId },
+                'wallets-manager',
+            );
+
+            return;
+        }
+
+        // Otherwise clear selection
+        this._selectedWalletId = null;
+        this.emitter.emit(WALLETS_EVENTS.SELECTION_CHANGED, { walletId: null }, 'wallets-manager');
+    }
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ *
+ */
+
+/**
+ * AppKit - Core wallet management for TON dApps
+ *
+ * This is the main entry point for AppKit. It provides provider-agnostic
+ * wallet management functionality.
+ *
+ * For TonConnect support, import from '@ton/appkit/tonconnect' separately.
+ * This allows tree-shaking for users who don't need TonConnect.
+ *
+ * @example
+ * ```ts
+ * // Core AppKit (provider-agnostic)
+ * import { AppKit } from '@ton/appkit';
+ *
+ * // TonConnect feature (optional, for tree-shaking)
+ * import { TonConnectConnector } from '@ton/appkit/tonconnect';
+ * ```
+ */
+
+// Core
+export * from './core/app-kit';
+export * from './core/emitter';
+export * from './connectors/tonconnect';
+
+export * from './swap';
+
+// Actions
+export * from './actions';
+
+// Types
+export * from './types/connector';
+export * from './types/balance';
+export * from './types/wallet';
+export * from './types/query';
+export * from './types/utils';
+export * from './types/network';
+export * from './types/jetton';
+export * from './types/nft';
+export * from './types/transaction';
+export * from './types/primitives';
+export * from './types/signing';
+
+// Utils
+export * from './utils';

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

@@ -0,0 +1,58 @@
+/**
+ * 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 { getBalanceByAddress } from '../../actions/balances/get-balance-by-address';
+import type { GetBalanceByAddressOptions } from '../../actions/balances/get-balance-by-address';
+import type { QueryOptions, QueryParameter } from '../../types/query';
+import type { Compute, ExactPartial } from '../../types/utils';
+import { filterQueryOptions } from '../../utils';
+import type { GetBalanceByAddressReturnType } from '../../actions/balances/get-balance-by-address';
+
+export type GetBalanceErrorType = Error;
+
+export type GetBalanceByAddressData = GetBalanceQueryFnData;
+
+export type GetBalanceByAddressQueryConfig<selectData = GetBalanceByAddressData> = Compute<
+    ExactPartial<GetBalanceByAddressOptions>
+> &
+    QueryParameter<GetBalanceQueryFnData, GetBalanceErrorType, selectData, GetBalanceByAddressQueryKey>;
+
+export const getBalanceByAddressQueryOptions = <selectData = GetBalanceByAddressData>(
+    appKit: AppKit,
+    options: GetBalanceByAddressQueryConfig<selectData> = {},
+): GetBalanceByAddressQueryOptions<selectData> => {
+    return {
+        ...options.query,
+        enabled: Boolean(options.address && (options.query?.enabled ?? true)),
+        queryFn: async (context) => {
+            const [, parameters] = context.queryKey as [string, GetBalanceByAddressOptions];
+            if (!parameters.address) throw new Error('address is required');
+            const balance = await getBalanceByAddress(appKit, parameters);
+            return balance ?? null;
+        },
+        queryKey: getBalanceByAddressQueryKey(options),
+    };
+};
+
+export type GetBalanceQueryFnData = Compute<Awaited<GetBalanceByAddressReturnType>>;
+
+export const getBalanceByAddressQueryKey = (
+    options: Compute<ExactPartial<GetBalanceByAddressOptions>> = {},
+): GetBalanceByAddressQueryKey => {
+    return ['balance', filterQueryOptions(options)] as const;
+};
+
+export type GetBalanceByAddressQueryKey = readonly ['balance', Compute<ExactPartial<GetBalanceByAddressOptions>>];
+
+export type GetBalanceByAddressQueryOptions<selectData = GetBalanceByAddressData> = QueryOptions<
+    GetBalanceQueryFnData,
+    GetBalanceErrorType,
+    selectData,
+    GetBalanceByAddressQueryKey
+>;

package/src/queries/connectors/connect.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 { MutateOptions, MutationOptions } from '@tanstack/query-core';
+
+import type { AppKit } from '../../core/app-kit';
+import { connect } from '../../actions/connectors/connect';
+import type { ConnectParameters, ConnectReturnType } from '../../actions/connectors/connect';
+import type { MutationParameter } from '../../types/query';
+import type { Compute } from '../../types/utils';
+
+export type { ConnectParameters, ConnectReturnType };
+
+export type ConnectErrorType = Error;
+
+export type ConnectOptions<context = unknown> = MutationParameter<
+    ConnectData,
+    ConnectErrorType,
+    ConnectVariables,
+    context
+>;
+
+export const connectMutationOptions = <context = unknown>(
+    appKit: AppKit,
+    options: ConnectOptions<context> = {},
+): ConnectMutationOptions<context> => {
+    return {
+        ...options.mutation,
+        mutationFn(variables) {
+            return connect(appKit, variables);
+        },
+        mutationKey: ['connect'],
+    };
+};
+
+export type ConnectMutationOptions<context = unknown> = MutationOptions<
+    ConnectData,
+    ConnectErrorType,
+    ConnectVariables,
+    context
+>;
+
+export type ConnectData = Compute<ConnectReturnType>;
+
+export type ConnectVariables = ConnectParameters;
+
+export type ConnectMutate<context = unknown> = (
+    variables: ConnectVariables,
+    options?: Compute<MutateOptions<ConnectData, ConnectErrorType, Compute<ConnectVariables>, context>> | undefined,
+) => void;
+
+export type ConnectMutateAsync<context = unknown> = (
+    variables: ConnectVariables,
+    options?: Compute<MutateOptions<ConnectData, ConnectErrorType, Compute<ConnectVariables>, context>> | undefined,
+) => Promise<ConnectData>;