@ton/appkit 0.0.1-alpha.1 → 0.0.1

package/src/types/query.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 * as Query from '@tanstack/query-core';
+
+import type { Compute, LooseOmit, RequiredBy, UnionLooseOmit } from './utils.js';
+
+export type MutationParameter<data = unknown, error = Error, variables = void, context = unknown> = {
+    mutation?:
+        | LooseOmit<
+              Query.MutationOptions<data, error, Compute<variables>, context>,
+              'mutationFn' | 'mutationKey' | 'throwOnError'
+          >
+        | undefined;
+};
+
+export type QueryParameter<
+    queryFnData = unknown,
+    error = Query.DefaultError,
+    data = queryFnData,
+    queryKey extends Query.QueryKey = Query.QueryKey,
+> = {
+    query?: UnionLooseOmit<QueryOptions<queryFnData, error, data, queryKey>, 'queryKey' | 'queryFn'> | undefined;
+};
+
+export type QueryOptions<
+    queryFnData = unknown,
+    error = Query.DefaultError,
+    data = queryFnData,
+    queryKey extends Query.QueryKey = Query.QueryKey,
+> = Omit<
+    RequiredBy<Query.QueryObserverOptions<queryFnData, error, data, queryFnData, queryKey>, 'queryKey'>,
+    'queryFn' | 'queryHash' | 'queryKeyHashFn' | 'throwOnError'
+> & {
+    queryFn: Exclude<
+        Query.QueryObserverOptions<queryFnData, error, data, queryFnData, queryKey>['queryFn'],
+        typeof Query.skipToken | undefined
+    >;
+};

package/src/types/signing.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 { Network } from './network';
+import type { Base64String } from './primitives';
+
+// SignData types for wallet adapter
+
+/**
+ * Data to be signed by the wallet, discriminated by type.
+ */
+export type SignData =
+    | { type: 'text'; value: SignDataText }
+    | { type: 'binary'; value: SignDataBinary }
+    | { type: 'cell'; value: SignDataCell };
+
+/**
+ * Binary data to be signed.
+ */
+export interface SignDataBinary {
+    /**
+     * Raw binary content encoded as bytes in Base64
+     */
+    content: Base64String;
+}
+
+/**
+ * TON Cell data to be signed with a schema definition.
+ */
+export interface SignDataCell {
+    /**
+     * Schema describing the cell structure for parsing
+     */
+    schema: string;
+    /**
+     * Cell content encoded in Base64
+     */
+    content: Base64String;
+}
+
+/**
+ * Plain text data to be signed.
+ */
+export interface SignDataText {
+    /**
+     * Text content to be signed
+     */
+    content: string;
+}
+
+/** SignData Request Payload - sent to wallet */
+export interface SignDataRequest {
+    /** Network */
+    network?: Network;
+    /** Sender address in raw format */
+    from?: string;
+    /** Data to sign */
+    data: SignData;
+}
+
+/** SignData Response - returned from wallet */
+export interface SignDataResponse {
+    /** Base64 encoded signature */
+    signature: string;
+    /** Wallet address that signed */
+    address: string;
+    /** Unix timestamp when signed */
+    timestamp: number;
+    /** Domain of the dApp */
+    domain: string;
+    /** Original payload that was signed */
+    payload: SignDataRequest;
+}

package/src/types/transaction.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 { ExtraCurrencies, TokenAmount } from '@ton/walletkit';
+
+import type { Network } from './network';
+
+export interface TransactionRequest {
+    /**
+     * List of messages to include in the transaction
+     */
+    messages: TransactionRequestMessage[];
+
+    /**
+     * Network to execute the transaction on
+     */
+    network?: Network;
+
+    /**
+     * Unix timestamp after which the transaction becomes invalid
+     */
+    validUntil?: number;
+
+    /**
+     * Sender wallet address in received format(raw, user friendly)
+     */
+    fromAddress?: string;
+}
+
+/**
+ * Individual message within a transaction request.
+ */
+export interface TransactionRequestMessage {
+    /**
+     * Recipient wallet address in format received from caller (raw, user friendly)
+     */
+    address: string;
+
+    /**
+     * Amount to transfer in nanos
+     */
+    amount: TokenAmount;
+
+    /**
+     * Additional currencies to include in the transfer
+     */
+    extraCurrency?: ExtraCurrencies;
+
+    /**
+     * Initial state for deploying a new contract, encoded in Base64
+     */
+    stateInit?: string;
+
+    /**
+     * Message payload data encoded in Base64
+     */
+    payload?: string;
+}

package/src/types/utils.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ *
+ */
+
+/** Combines members of an intersection into a readable type. */
+// https://twitter.com/mattpocockuk/status/1622730173446557697?s=20&t=NdpAcmEFXY01xkqU3KO0Mg
+export type Compute<type> = { [key in keyof type]: type[key] } & unknown;
+
+/**
+ * Makes all properties of an object optional.
+ *
+ * Compatible with [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes).
+ */
+export type ExactPartial<type> = {
+    [key in keyof type]?: type[key] | undefined;
+};
+
+/**
+ * Creates a fixed array of `count` elements of type `type`.
+ *
+ * @example
+ * ```ts
+ * type Result = FixedArray<string, 3>
+ * //   ^? type Result = readonly [string, string, string]
+ * ```
+ */
+export type FixedArray<type, count extends number, result extends readonly type[] = []> = result['length'] extends count
+    ? result
+    : FixedArray<type, count, readonly [...result, type]>;
+
+/** Checks if {@link type} can be narrowed further than {@link type2} */
+export type IsNarrowable<type, type2> =
+    IsUnknown<type> extends true
+        ? false
+        : undefined extends type
+          ? false
+          : IsNever<(type extends type2 ? true : false) & (type2 extends type ? false : true)> extends true
+            ? false
+            : true;
+
+/**
+ * @internal
+ * Checks if {@link type} is `never`
+ */
+export type IsNever<type> = [type] extends [never] ? true : false;
+
+/**
+ * @internal
+ * Checks if {@link type} is `unknown`
+ */
+export type IsUnknown<type> = unknown extends type ? true : false;
+
+/** Merges two object types into new type  */
+export type Merge<obj1, obj2> = Compute<
+    LooseOmit<obj1, keyof obj2 extends infer key extends string ? key : never> & obj2
+>;
+
+/** Removes `readonly` from all properties of an object. */
+export type Mutable<type extends object> = {
+    -readonly [key in keyof type]: type[key];
+};
+
+/** Strict version of built-in Omit type */
+export type StrictOmit<type, keys extends keyof type> = Pick<type, Exclude<keyof type, keys>>;
+
+/** Makes objects destructurable. */
+export type OneOf<
+    union extends object,
+    ///
+    keys extends KeyofUnion<union> = KeyofUnion<union>,
+> = union extends infer Item ? Compute<Item & { [K in Exclude<keys, keyof Item>]?: undefined }> : never;
+type KeyofUnion<type> = type extends type ? keyof type : never;
+
+/** Makes {@link key} optional in {@link type} while preserving type inference. */
+// s/o trpc (https://github.com/trpc/trpc/blob/main/packages/server/src/types.ts#L6)
+export type PartialBy<type, key extends keyof type> = ExactPartial<Pick<type, key>> & StrictOmit<type, key>;
+
+/* Removes `undefined` from object property */
+export type RemoveUndefined<type> = {
+    [key in keyof type]: NonNullable<type[key]>;
+};
+
+/**
+ * Creates a type that is {@link type} with the required keys {@link key}.
+ *
+ * @example
+ * ```ts
+ * RequiredBy<{ a?: string, b: number }, 'a'>
+ * // { a: string, b: number }
+ * ```
+ *
+ * @internal
+ */
+export type RequiredBy<type, key extends keyof type> = Omit<type, key> & ExactRequired<Pick<type, key>>;
+
+/** @internal */
+export type ExactRequired<type> = {
+    [key in keyof type]-?: Exclude<type[key], undefined>;
+};
+
+///////////////////////////////////////////////////////////////////////////
+// Loose types
+
+/** Loose version of {@link StrictOmit} */
+export type LooseOmit<type, keys extends string> = Pick<type, Exclude<keyof type, keys>>;
+
+///////////////////////////////////////////////////////////////////////////
+// Union types
+
+export type UnionCompute<type> = type extends object ? Compute<type> : type;
+
+export type UnionLooseOmit<type, keys extends string> = type extends unknown ? LooseOmit<type, keys> : never;
+
+export type UnionStrictOmit<type, keys extends keyof type> = type extends unknown ? StrictOmit<type, keys> : never;
+
+export type UnionExactPartial<type> = type extends object ? ExactPartial<type> : type;

package/src/types/wallet.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { Network, SendTransactionResponse, Hex, UserFriendlyAddress } from '@ton/walletkit';
+
+import type { TransactionRequest } from './transaction';
+import type { SignDataRequest, SignDataResponse } from './signing';
+
+/**
+ * Minimal wallet interface for appkit.
+ * Only includes methods that require wallet-specific logic (signing, identity).
+ * Data fetching (balance, jettons, nfts) is done via actions using networkManager.
+ */
+export interface WalletInterface {
+    /** Connector that created this wallet */
+    readonly connectorId: string;
+
+    // ==========================================
+    // Identity
+    // ==========================================
+
+    /** Get the wallet address */
+    getAddress(): UserFriendlyAddress;
+
+    /** Get the wallet public key */
+    getPublicKey(): Hex;
+
+    /** Get the network the wallet is connected to */
+    getNetwork(): Network;
+
+    /** Get unique wallet identifier */
+    getWalletId(): string;
+
+    // ==========================================
+    // Actions requiring wallet signature
+    // ==========================================
+
+    /** Send a transaction (wallet signs and submits) */
+    sendTransaction(request: TransactionRequest): Promise<SendTransactionResponse>;
+
+    /** Sign arbitrary data using TonConnect signData */
+    signData(payload: SignDataRequest): Promise<SignDataResponse>;
+}

package/src/utils/amount/validate-numeric-string.test.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 { describe, expect, it } from 'vitest';
+
+import { validateNumericString } from './validate-numeric-string';
+
+describe('validateNumericString', () => {
+    it('should validate integers', () => {
+        expect(validateNumericString('123')).toBe(true);
+        expect(validateNumericString('0')).toBe(true);
+    });
+
+    it('should validate floats with dot', () => {
+        expect(validateNumericString('1.23')).toBe(true);
+        expect(validateNumericString('0.1')).toBe(true);
+        expect(validateNumericString('1.')).toBe(true);
+        expect(validateNumericString('.1')).toBe(true);
+    });
+
+    it('should validate floats with comma', () => {
+        expect(validateNumericString('1,23')).toBe(true);
+        expect(validateNumericString('0,1')).toBe(true);
+    });
+
+    it('should reject invalid characters', () => {
+        expect(validateNumericString('1a')).toBe(false);
+        expect(validateNumericString('abc')).toBe(false);
+        expect(validateNumericString('1.2.3')).toBe(false);
+        expect(validateNumericString(' ')).toBe(false);
+    });
+
+    it('should validate max decimals', () => {
+        expect(validateNumericString('1.23', 2)).toBe(true);
+        expect(validateNumericString('1.234', 2)).toBe(false);
+        expect(validateNumericString('1.23', 1)).toBe(false);
+    });
+
+    it('should handle 0 max decimals', () => {
+        expect(validateNumericString('123', 0)).toBe(true);
+        expect(validateNumericString('1.2', 0)).toBe(false);
+    });
+
+    it('should reject pure dot regardless', () => {
+        expect(validateNumericString('.')).toBe(false);
+        expect(validateNumericString(',')).toBe(false);
+    });
+});

package/src/utils/amount/validate-numeric-string.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 DOT_NUM_REGEXP = /^\d*[.]?(\d*)$/;
+export const COMMA_NUM_REGEXP = /^\d*,?(\d*)$/;
+
+export const validateNumericString = (num: string, maxDecimals?: number): boolean => {
+    const isDotNum = num.includes('.');
+    const isValid = isDotNum ? DOT_NUM_REGEXP.test(num) : COMMA_NUM_REGEXP.test(num);
+    const match = isDotNum ? DOT_NUM_REGEXP.exec(num) : COMMA_NUM_REGEXP.exec(num);
+
+    // if the decimals is zero the dot is not needed
+    if (maxDecimals === 0 && num.includes('.')) return false;
+
+    if (num === '.' || num === ',') return false;
+
+    if (maxDecimals !== undefined && match?.[1]) return isValid && match?.[1].length <= maxDecimals;
+
+    return isValid;
+};

package/src/utils/arrays/key-by.test.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+
+import { keyBy } from './key-by';
+
+describe('keyBy', () => {
+    it('should key array by property', () => {
+        const array = [
+            { id: 1, name: 'a' },
+            { id: 2, name: 'b' },
+        ];
+        const result = keyBy(array, (item) => item.id);
+        expect(result).toEqual({
+            1: { id: 1, name: 'a' },
+            2: { id: 2, name: 'b' },
+        });
+    });
+
+    it('should handle property collision (last wins)', () => {
+        const array = [
+            { id: 1, name: 'a' },
+            { id: 1, name: 'b' },
+        ];
+        // Based on implementation: arr.forEach(...) which iterates in order
+        const result = keyBy(array, (item) => item.id);
+        expect(result).toEqual({
+            1: { id: 1, name: 'b' },
+        });
+    });
+
+    it('should handle empty array', () => {
+        const array: { id: number }[] = [];
+        const result = keyBy(array, (item) => item.id);
+        expect(result).toEqual({});
+    });
+
+    it('should work with string keys', () => {
+        const array = [
+            { id: 'a', val: 1 },
+            { id: 'b', val: 2 },
+        ];
+        const result = keyBy(array, (item) => item.id);
+        expect(result).toEqual({
+            a: { id: 'a', val: 1 },
+            b: { id: 'b', val: 2 },
+        });
+    });
+});

package/src/utils/arrays/key-by.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 function keyBy<T, K extends PropertyKey>(arr: readonly T[], getKeyFromItem: (item: T) => K): Record<K, T> {
+    const result = {} as Record<K, T>;
+
+    arr.forEach((item) => {
+        const key = getKeyFromItem(item);
+        result[key] = item;
+    });
+
+    return result;
+}

package/src/utils/arrays/random-from-array.test.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.
+ *
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { randomFromArray } from './random-from-array';
+
+describe('randomFromArray', () => {
+    it('should return an item from the array', () => {
+        const array = [1, 2, 3];
+        const item = randomFromArray(array);
+        expect(array).toContain(item);
+    });
+
+    it('should return undefined for empty array', () => {
+        const array: number[] = [];
+        const item = randomFromArray(array);
+        expect(item).toBeUndefined();
+    });
+
+    it('should work with single item', () => {
+        const array = [42];
+        expect(randomFromArray(array)).toBe(42);
+    });
+
+    it('should use Math.random', () => {
+        const randomSpy = vi.spyOn(Math, 'random');
+        randomFromArray([1, 2]);
+        expect(randomSpy).toHaveBeenCalled();
+        randomSpy.mockRestore();
+    });
+});

package/src/utils/arrays/random-from-array.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 const randomFromArray = <T>(items: T[]): T => items[Math.floor(Math.random() * items.length)]!;

package/src/utils/errors/get-error-message.test.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { describe, expect, it } from 'vitest';
+
+import { getErrorMessage } from './get-error-message';
+
+describe('getErrorMessage', () => {
+    it('should return error message from Error object', () => {
+        const error = new Error('Something went wrong');
+        expect(getErrorMessage(error)).toBe('Something went wrong');
+    });
+
+    it('should return string error directly', () => {
+        const error = 'Something went wrong';
+        expect(getErrorMessage(error)).toBe('Something went wrong');
+    });
+
+    it('should return message from object with message property', () => {
+        const error = { message: 'Something went wrong' };
+        expect(getErrorMessage(error)).toBe('Something went wrong');
+    });
+
+    it('should return default message if error is unknown object', () => {
+        const error = { foo: 'bar' };
+        expect(getErrorMessage(error, 'Default Message')).toBe('Default Message');
+        expect(getErrorMessage(error)).toBe('Error occurred');
+    });
+
+    it('should return default message if error is null/undefined', () => {
+        expect(getErrorMessage(null)).toBe('Error occurred');
+        expect(getErrorMessage(undefined)).toBe('Error occurred');
+    });
+});

package/src/utils/errors/get-error-message.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ *
+ */
+
+type ObjectWithMessage = { message: string } & { [key: string]: unknown };
+
+const isObjectWithMessage = (toBeDetermined: unknown): toBeDetermined is ObjectWithMessage =>
+    !!toBeDetermined && !!(toBeDetermined as ObjectWithMessage).message;
+
+export const getErrorMessage = (error: unknown, defaultMessage?: string): string => {
+    if (typeof error === 'string') {
+        return error;
+    }
+
+    if (error instanceof Error || isObjectWithMessage(error)) {
+        return error.message;
+    }
+
+    return defaultMessage || 'Error occurred';
+};

package/src/utils/functions/noop.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 noop = (): void => {
+    //
+};

package/src/utils/index.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.
+ *
+ */
+
+export { formatUnits, parseUnits } from '@ton/walletkit';
+
+export * from './amount/validate-numeric-string';
+export * from './arrays/key-by';
+export * from './arrays/random-from-array';
+export * from './errors/get-error-message';
+export * from './functions/noop';
+export * from './jetton/jetton-info';
+export * from './nft/nft-info';
+export * from './object/map-values';
+export * from './predicate/is-string';
+export * from './promise/cancel-promise';
+export * from './promise/sleep';
+export * from './query/filter-query-options';
+export * from './string/middle-ellipsis';