@ton/appkit 0.0.1-alpha.2 → 0.0.2

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';

package/src/utils/jetton/jetton-info.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 { Jetton } from '@ton/walletkit';
+
+export const getJettonsSymbol = (jetton: Jetton): string | undefined => {
+    if (!jetton?.info?.symbol) {
+        return;
+    }
+
+    return jetton.info.symbol;
+};
+
+export const getJettonsName = (jetton: Jetton): string | undefined => {
+    if (!jetton?.info?.name && !jetton?.info?.symbol) {
+        return;
+    }
+
+    return jetton.info?.name || jetton.info?.symbol || '';
+};
+
+export const getJettonsImage = (jetton: Jetton): string | undefined => {
+    if (!jetton?.info?.image) {
+        return;
+    }
+
+    return (
+        jetton.info.image.url ||
+        (jetton.info.image.data ? atob(jetton.info.image.data) : undefined) ||
+        jetton.info.image.mediumUrl ||
+        jetton.info.image.largeUrl ||
+        jetton.info.image.smallUrl ||
+        ''
+    );
+};
+
+export const getFormattedJettonInfo = (jetton: Jetton) => {
+    const jettonName = getJettonsName(jetton);
+    const jettonSymbol = getJettonsSymbol(jetton);
+    const jettonImage = getJettonsImage(jetton);
+    const jettonBalance = jetton.balance || '0';
+    const jettonDecimals = jetton.decimalsNumber;
+
+    return {
+        address: jetton.address,
+        walletAddress: jetton.walletAddress,
+        description: jetton.info?.description,
+        name: jettonName,
+        symbol: jettonSymbol,
+        image: jettonImage,
+        imageData: jetton.info?.image?.data,
+        balance: jettonBalance,
+        decimals: jettonDecimals,
+    };
+};

package/src/utils/nft/nft-info.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { NFT } from '@ton/walletkit';
+
+import { middleEllipsis } from '../string/middle-ellipsis';
+
+export const getNftImage = (nft: NFT): string | null => {
+    if (!nft.info?.image) return null;
+
+    const { url, data, mediumUrl, smallUrl, largeUrl } = nft.info.image;
+
+    if (url) return url;
+    if (mediumUrl) return mediumUrl;
+    if (largeUrl) return largeUrl;
+    if (smallUrl) return smallUrl;
+
+    if (data) {
+        try {
+            return atob(data);
+        } catch {
+            return null;
+        }
+    }
+
+    return null;
+};
+
+export const getNftName = (nft: NFT): string => {
+    if (nft.info?.name) return nft.info.name;
+    if (nft.index) return `NFT #${nft.index}`;
+    return middleEllipsis(nft.address);
+};
+
+export const getCollectionName = (nft: NFT): string => {
+    return nft.collection?.name || 'Unknown Collection';
+};
+
+export const getNftDescription = (nft: NFT): string | null => {
+    return nft.info?.description || null;
+};
+
+export const getFormattedNftInfo = (nft: NFT) => {
+    const nftName = getNftName(nft);
+    const nftImage = getNftImage(nft);
+    const collectionName = getCollectionName(nft);
+    const nftDescription = getNftDescription(nft);
+
+    return {
+        address: nft.address,
+        collectionName,
+        name: nftName,
+        image: nftImage,
+        description: nftDescription,
+        isOnSale: nft.isOnSale,
+    };
+};

package/src/utils/object/map-values.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 } from 'vitest';
+
+import { mapValues } from './map-values';
+
+describe('mapValues', () => {
+    it('should map values of object', () => {
+        const obj = { a: 1, b: 2 };
+        const result = mapValues(obj, (value) => value * 2);
+        expect(result).toEqual({ a: 2, b: 4 });
+    });
+
+    it('should provide key in callback', () => {
+        const obj = { a: 1, b: 2 };
+        const result = mapValues(obj, (value, key) => `${key}:${value}`);
+        expect(result).toEqual({ a: 'a:1', b: 'b:2' });
+    });
+
+    it('should handle empty object', () => {
+        const obj = {};
+        const result = mapValues(obj, (value) => value);
+        expect(result).toEqual({});
+    });
+
+    it('should not mutate original object', () => {
+        const obj = { a: 1 };
+        mapValues(obj, (val) => val + 1);
+        expect(obj).toEqual({ a: 1 });
+    });
+});

package/src/utils/object/map-values.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 function mapValues<T extends object, K extends keyof T, V>(
+    object: T,
+    getNewValue: (value: T[K], key: K, obj: T) => V,
+): Record<K, V> {
+    const result = {} as Record<K, V>;
+    const keys = Object.keys(object) as K[];
+
+    for (const key of keys) {
+        const value = object[key];
+
+        result[key] = getNewValue(value, key, object);
+    }
+
+    return result;
+}