@tgsnake/skema 1.12.0 → 2.0.0-browser.0

package/dist/src/errors/index.d.ts

@@ -0,0 +1,142 @@
+/**
+ * tgsnake - Telegram MTProto library for javascript or typescript.
+ * Copyright (C) 2026 tgsnake <https://github.com/tgsnake>
+ *
+ * THIS FILE IS PART OF TGSNAKE
+ *
+ * tgsnake is a free software : you can redistribute it and/or modify
+ * it under the terms of the MIT License as published.
+ */
+export * as Exceptions from './exceptions/index.js';
+export * as ClientError from './Client.js';
+export * as WSError from './WebSocket.js';
+export * as SecretChatError from './SecretChat.js';
+export * as FileErrors from './File.js';
+export { RPCError, UnknownError } from './RpcError.js';
+import { BaseError } from './Base.js';
+/**
+ * Error thrown when a promise or task execution exceeds a specified timeout threshold.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new TimeoutError(5000);
+ * ```
+ */
+export declare class TimeoutError extends BaseError {
+    /**
+     * The duration in milliseconds that was allowed before the timeout triggered.
+     */
+    timeout: number;
+    /**
+     * Constructs a new TimeoutError instance.
+     *
+     * @param timeout - The timeout limit in milliseconds.
+     */
+    constructor(timeout: number);
+}
+/**
+ * Error thrown when the client encounters a class constructor where it was expecting an executable function.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new NotAFunctionClass('MyClass');
+ * ```
+ */
+export declare class NotAFunctionClass extends BaseError {
+    message: string;
+    description: string;
+    /**
+     * Constructs a new NotAFunctionClass instance.
+     *
+     * @param className - The name of the invalid class.
+     */
+    constructor(className: string);
+}
+/**
+ * Error raised when the server responds with a bad message notification.
+ *
+ * @remarks
+ * Bad message notifications indicate structural, sequence, or time-sync errors in client messages.
+ * Common errors include out-of-sync system time, invalid sequence numbers (`seq_no`), or salt expiration.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new BadMsgNotification(16);
+ * ```
+ */
+export declare class BadMsgNotification extends BaseError {
+    /**
+     * Constructs a new BadMsgNotification instance.
+     *
+     * @param code - The bad message error code returned by the Telegram MTProto server.
+     */
+    constructor(code: number);
+}
+/**
+ * Custom error thrown when a security check, hash mismatch, or signature verification fails.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * SecurityError.check(user.isAuthenticated, "User must be authenticated");
+ * ```
+ */
+export declare class SecurityError extends BaseError {
+    /**
+     * Constructs a new SecurityError instance.
+     *
+     * @param description - Detailed context of the security violation.
+     */
+    constructor(description?: string);
+    /**
+     * Asserts that a condition is true, throwing a SecurityError if it is not.
+     *
+     * @param cond - The boolean condition to evaluate.
+     * @param description - Detailed error message if assertion fails.
+     * @throws {SecurityError} If the condition is false.
+     */
+    static check(cond: boolean, description?: string): void;
+}
+/**
+ * Error raised when an assertion check for key, signature, or padding lengths fails.
+ *
+ * @extends SecurityError
+ * @example
+ * ```typescript
+ * SecurityCheckMismatch.check(serverNonce === expectedNonce, 'Nonce mismatch');
+ * ```
+ */
+export declare class SecurityCheckMismatch extends SecurityError {
+    message: string;
+    /**
+     * Asserts that a condition is true, throwing a SecurityCheckMismatch if it is not.
+     *
+     * @param cond - The boolean condition to evaluate.
+     * @param description - Detailed error message if assertion fails.
+     * @throws {SecurityCheckMismatch} If the condition is false.
+     */
+    static check(cond: boolean, description?: string): void;
+}
+/**
+ * Error raised when the checksum or hash verification of a file downloaded from a Telegram CDN fails.
+ *
+ * @extends SecurityError
+ * @example
+ * ```typescript
+ * CDNFileHashMismatch.check(downloadedHash === correctHash, 'CDN file hash is corrupted');
+ * ```
+ */
+export declare class CDNFileHashMismatch extends SecurityError {
+    message: string;
+    /**
+     * Asserts that a condition is true, throwing a CDNFileHashMismatch if it is not.
+     *
+     * @param cond - The boolean condition to evaluate.
+     * @param description - Detailed error message if assertion fails.
+     * @throws {CDNFileHashMismatch} If the condition is false.
+     */
+    static check(cond: boolean, description?: string): void;
+}

package/dist/src/errors/index.js

@@ -0,0 +1,178 @@
+/**
+ * tgsnake - Telegram MTProto library for javascript or typescript.
+ * Copyright (C) 2026 tgsnake <https://github.com/tgsnake>
+ *
+ * THIS FILE IS PART OF TGSNAKE
+ *
+ * tgsnake is a free software : you can redistribute it and/or modify
+ * it under the terms of the MIT License as published.
+ */
+export * as Exceptions from './exceptions/index.js';
+export * as ClientError from './Client.js';
+export * as WSError from './WebSocket.js';
+export * as SecretChatError from './SecretChat.js';
+export * as FileErrors from './File.js';
+export { RPCError, UnknownError } from './RpcError.js';
+import { BaseError } from './Base.js';
+/**
+ * Error thrown when a promise or task execution exceeds a specified timeout threshold.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new TimeoutError(5000);
+ * ```
+ */
+export class TimeoutError extends BaseError {
+    /**
+     * The duration in milliseconds that was allowed before the timeout triggered.
+     */
+    timeout;
+    /**
+     * Constructs a new TimeoutError instance.
+     *
+     * @param timeout - The timeout limit in milliseconds.
+     */
+    constructor(timeout) {
+        super();
+        this.message = `Running timeout after ${timeout} ms`;
+        this.timeout = timeout;
+        this.description = `The function is running too long, until it reaches the time limit that has been given.`;
+    }
+}
+/**
+ * Error thrown when the client encounters a class constructor where it was expecting an executable function.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new NotAFunctionClass('MyClass');
+ * ```
+ */
+export class NotAFunctionClass extends BaseError {
+    message = '{value} is not a function.';
+    description = "The provided class {value} is not a function constructor, can't sending request with that class.";
+    /**
+     * Constructs a new NotAFunctionClass instance.
+     *
+     * @param className - The name of the invalid class.
+     */
+    constructor(className) {
+        super();
+        this.message = this.message.replace('{value}', className);
+        this.description = this.description.replace('{value}', className);
+    }
+}
+/**
+ * Error raised when the server responds with a bad message notification.
+ *
+ * @remarks
+ * Bad message notifications indicate structural, sequence, or time-sync errors in client messages.
+ * Common errors include out-of-sync system time, invalid sequence numbers (`seq_no`), or salt expiration.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new BadMsgNotification(16);
+ * ```
+ */
+export class BadMsgNotification extends BaseError {
+    /**
+     * Constructs a new BadMsgNotification instance.
+     *
+     * @param code - The bad message error code returned by the Telegram MTProto server.
+     */
+    constructor(code) {
+        const description = {
+            16: 'The msg_id is too low, the client time has to be synchronized.',
+            17: 'The msg_id is too high, the client time has to be synchronized.',
+            18: 'Incorrect two lower order of the msg_id bits, the server expects the client message\nmsg_id to be divisible by 4.',
+            19: 'The container msg_id is the same as the msg_id of a previously received message.',
+            20: 'The message is too old, it cannot be verified by the server.',
+            32: 'The msg_seqno is too low.',
+            33: 'The msg_seqno is too high.',
+            34: 'An even msg_seqno was expected, but an odd one was received.',
+            35: 'An odd msg_seqno was expected, but an even one was received.',
+            48: 'Incorrect server salt.',
+            64: 'Invalid container.',
+        };
+        super(`[${code}] ${description[code] ?? 'Unknown Error'}`);
+    }
+}
+/**
+ * Custom error thrown when a security check, hash mismatch, or signature verification fails.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * SecurityError.check(user.isAuthenticated, "User must be authenticated");
+ * ```
+ */
+export class SecurityError extends BaseError {
+    /**
+     * Constructs a new SecurityError instance.
+     *
+     * @param description - Detailed context of the security violation.
+     */
+    constructor(description) {
+        super();
+        this.description = description;
+    }
+    /**
+     * Asserts that a condition is true, throwing a SecurityError if it is not.
+     *
+     * @param cond - The boolean condition to evaluate.
+     * @param description - Detailed error message if assertion fails.
+     * @throws {SecurityError} If the condition is false.
+     */
+    static check(cond, description) {
+        if (!cond)
+            throw new SecurityError(description);
+    }
+}
+/**
+ * Error raised when an assertion check for key, signature, or padding lengths fails.
+ *
+ * @extends SecurityError
+ * @example
+ * ```typescript
+ * SecurityCheckMismatch.check(serverNonce === expectedNonce, 'Nonce mismatch');
+ * ```
+ */
+export class SecurityCheckMismatch extends SecurityError {
+    message = 'A security check mismatch has occurred.';
+    /**
+     * Asserts that a condition is true, throwing a SecurityCheckMismatch if it is not.
+     *
+     * @param cond - The boolean condition to evaluate.
+     * @param description - Detailed error message if assertion fails.
+     * @throws {SecurityCheckMismatch} If the condition is false.
+     */
+    static check(cond, description) {
+        if (!cond)
+            throw new SecurityCheckMismatch(description);
+    }
+}
+/**
+ * Error raised when the checksum or hash verification of a file downloaded from a Telegram CDN fails.
+ *
+ * @extends SecurityError
+ * @example
+ * ```typescript
+ * CDNFileHashMismatch.check(downloadedHash === correctHash, 'CDN file hash is corrupted');
+ * ```
+ */
+export class CDNFileHashMismatch extends SecurityError {
+    message = 'A CDN file hash mismatch has occurred.';
+    /**
+     * Asserts that a condition is true, throwing a CDNFileHashMismatch if it is not.
+     *
+     * @param cond - The boolean condition to evaluate.
+     * @param description - Detailed error message if assertion fails.
+     * @throws {CDNFileHashMismatch} If the condition is false.
+     */
+    static check(cond, description) {
+        if (!cond)
+            throw new CDNFileHashMismatch(description);
+    }
+}

package/dist/src/helpers.d.ts

@@ -0,0 +1,102 @@
+/**
+ * tgsnake - Telegram MTProto library for javascript or typescript.
+ * Copyright (C) 2026 tgsnake <https://github.com/tgsnake>
+ *
+ * THIS FILE IS PART OF TGSNAKE
+ *
+ * tgsnake is a free software: you can redistribute it and/or modify
+ * it under the terms of the MIT License as published.
+ */
+import { Buffer } from './deps.js';
+/**
+ * Converts a JS native `bigint` value into a Node.js `Buffer` with custom byte-padding, endianness, and sign representation.
+ *
+ * @remarks
+ * This utility handles both signed and unsigned numeric translations.
+ * For signed negative bigints, it computes the manual two's complement transformation
+ * in either little-endian or big-endian formats to match Telegram MTProto specifications.
+ *
+ * @param int - The bigint value to serialize into the buffer.
+ * @param padding - The absolute target size of the output buffer in bytes.
+ * @param litte - Set to `true` for little-endian encoding; set to `false` for big-endian. Defaults to `true`.
+ * @param signed - Set to `true` to allow signed integers and two's complement representation. Defaults to `false`.
+ * @returns A new `Buffer` representation of the bigint value.
+ *
+ * @throws {Error} If the bigint requires more bytes to represent than the specified padding size.
+ * @throws {Error} If the bigint is negative and `signed` is set to `false`.
+ *
+ * @example
+ * ```typescript
+ * // Unsigned little-endian 4-byte padding
+ * const buf = bigintToBuffer(BigInt(42), 4, true, false);
+ * ```
+ */
+export declare function bigintToBuffer(int: bigint, padding: number, litte?: boolean, signed?: boolean): Buffer;
+/**
+ * Computes base-`x` raised to exponent-`y`, with an optional modular reduction `z`.
+ *
+ * @remarks
+ * Uses an efficient binary exponentiation algorithm (square-and-multiply) to handle
+ * extremely large values of `x`, `y`, and `z` securely without precision loss.
+ *
+ * @param x - The base bigint value.
+ * @param y - The exponent bigint value (must be non-negative if modulus is specified).
+ * @param z - Optional modulus bigint value.
+ * @returns If `z` is not defined: `x ** y`. If `z` is defined: `(x ** y) % z`.
+ *
+ * @example
+ * ```typescript
+ * const result = bigIntPow(BigInt(5), BigInt(3), BigInt(7)); // (5 ** 3) % 7 = 6
+ * ```
+ */
+export declare function bigIntPow(x: bigint, y: bigint, z?: bigint): bigint;
+/**
+ * Computes the true mathematical modulo of two JS standard `number`s, ensuring a non-negative result.
+ *
+ * @remarks
+ * In standard JavaScript, the `%` operator computes the remainder, which can result in a negative
+ * number if the dividend `n` is negative. This helper function corrects that behavior to return
+ * a mathematically sound positive modulo in the range `[0, m)`.
+ *
+ * @param n - The dividend.
+ * @param m - The divisor (must be a positive, non-zero number).
+ * @returns The positive remainder representing `n mod m`.
+ *
+ * @example
+ * ```typescript
+ * mod(5, 3);   // returns 2
+ * mod(-1, 3);  // returns 2 (whereas -1 % 3 returns -1)
+ * ```
+ */
+export declare function mod(n: number, m: number): number;
+/**
+ * Computes the true mathematical modulo of two `bigint` values, ensuring a non-negative result.
+ *
+ * @remarks
+ * Similar to {@link mod}, this function implements correct mathematical modulo for large bigints
+ * so that any negative dividend `n` resolves into a positive remainder modulo `m`.
+ *
+ * @param n - The bigint dividend.
+ * @param m - The bigint divisor.
+ * @returns The positive bigint remainder representing `n mod m`.
+ *
+ * @example
+ * ```typescript
+ * bigIntMod(BigInt(-5), BigInt(3)); // returns 1n
+ * ```
+ */
+export declare function bigIntMod(n: bigint, m: bigint): bigint;
+/**
+ * Decodes a Node.js `Buffer` back into a JS native `BigInt` value.
+ *
+ * @param buffer - The source Buffer containing binary representation of the integer.
+ * @param little - Set to `true` if the buffer is encoded in little-endian format; set to `false` if big-endian. Defaults to `true`.
+ * @param signed - Set to `true` if the buffer contains a signed two's complement integer. Defaults to `false`.
+ * @returns A standard native `bigint` value decoded from the bytes.
+ *
+ * @example
+ * ```typescript
+ * const val = bufferToBigint(Buffer.from([0x2a, 0x00]), true, false); // 42n
+ * ```
+ */
+export declare function bufferToBigint(buffer: Buffer, little?: boolean, signed?: boolean): bigint;

package/dist/src/helpers.js

@@ -0,0 +1,176 @@
+/**
+ * tgsnake - Telegram MTProto library for javascript or typescript.
+ * Copyright (C) 2026 tgsnake <https://github.com/tgsnake>
+ *
+ * THIS FILE IS PART OF TGSNAKE
+ *
+ * tgsnake is a free software: you can redistribute it and/or modify
+ * it under the terms of the MIT License as published.
+ */
+import { bigInt, Buffer } from './deps.js';
+// https://github.com/gram-js/gramjs/blob/b99879464cd1114d89b333c5d929610780c4b003/gramjs/Helpers.ts#L13
+/**
+ * Converts a JS native `bigint` value into a Node.js `Buffer` with custom byte-padding, endianness, and sign representation.
+ *
+ * @remarks
+ * This utility handles both signed and unsigned numeric translations.
+ * For signed negative bigints, it computes the manual two's complement transformation
+ * in either little-endian or big-endian formats to match Telegram MTProto specifications.
+ *
+ * @param int - The bigint value to serialize into the buffer.
+ * @param padding - The absolute target size of the output buffer in bytes.
+ * @param litte - Set to `true` for little-endian encoding; set to `false` for big-endian. Defaults to `true`.
+ * @param signed - Set to `true` to allow signed integers and two's complement representation. Defaults to `false`.
+ * @returns A new `Buffer` representation of the bigint value.
+ *
+ * @throws {Error} If the bigint requires more bytes to represent than the specified padding size.
+ * @throws {Error} If the bigint is negative and `signed` is set to `false`.
+ *
+ * @example
+ * ```typescript
+ * // Unsigned little-endian 4-byte padding
+ * const buf = bigintToBuffer(BigInt(42), 4, true, false);
+ * ```
+ */
+export function bigintToBuffer(int, padding, litte = true, signed = false) {
+    const bigintLength = int.toString(2).length;
+    const bytes = Math.ceil(bigintLength / 8);
+    if (padding < bytes) {
+        throw new Error("Too big, Can't convert it to buffer with that padding.");
+    }
+    if (!signed && int < BigInt(0)) {
+        throw new Error('Too small, can convert it when unsigned.');
+    }
+    let isBellow = false;
+    if (int < BigInt(0)) {
+        isBellow = true;
+        int = int * BigInt(-1);
+    }
+    const hex = int.toString(16).padStart(padding * 2, '0');
+    let buffer = Buffer.from(hex, 'hex');
+    if (litte)
+        buffer = buffer.reverse();
+    if (isBellow && signed) {
+        if (litte) {
+            let isReminder = false;
+            if (buffer[0])
+                buffer[0] -= 1;
+            for (let b = 0; b < Buffer.byteLength(buffer); b++) {
+                if (!buffer[b]) {
+                    isReminder = true;
+                    continue;
+                }
+                if (isReminder) {
+                    buffer[b] -= 1;
+                    isReminder = false;
+                }
+                buffer[b] = 255 - buffer[b];
+            }
+        }
+        else {
+            buffer[Buffer.byteLength(buffer) - 1] =
+                256 - buffer[Buffer.byteLength(buffer) - 1];
+            for (let b = 0; b < Buffer.byteLength(buffer); b++) {
+                buffer[b] = 255 - buffer[b];
+            }
+        }
+    }
+    return buffer;
+}
+/**
+ * Computes base-`x` raised to exponent-`y`, with an optional modular reduction `z`.
+ *
+ * @remarks
+ * Uses an efficient binary exponentiation algorithm (square-and-multiply) to handle
+ * extremely large values of `x`, `y`, and `z` securely without precision loss.
+ *
+ * @param x - The base bigint value.
+ * @param y - The exponent bigint value (must be non-negative if modulus is specified).
+ * @param z - Optional modulus bigint value.
+ * @returns If `z` is not defined: `x ** y`. If `z` is defined: `(x ** y) % z`.
+ *
+ * @example
+ * ```typescript
+ * const result = bigIntPow(BigInt(5), BigInt(3), BigInt(7)); // (5 ** 3) % 7 = 6
+ * ```
+ */
+export function bigIntPow(x, y, z) {
+    if (z === undefined) {
+        return x ** y;
+    }
+    else {
+        let result = BigInt(1);
+        while (y > BigInt(0)) {
+            if (bigIntMod(y, BigInt(2)) === BigInt(1)) {
+                result = bigIntMod(result * x, z);
+            }
+            y = y >> BigInt(1);
+            x = bigIntMod(x * x, z);
+        }
+        return result;
+    }
+}
+// https://stackoverflow.com/questions/4467539/javascript-modulo-gives-a-negative-result-for-negative-numbers
+/**
+ * Computes the true mathematical modulo of two JS standard `number`s, ensuring a non-negative result.
+ *
+ * @remarks
+ * In standard JavaScript, the `%` operator computes the remainder, which can result in a negative
+ * number if the dividend `n` is negative. This helper function corrects that behavior to return
+ * a mathematically sound positive modulo in the range `[0, m)`.
+ *
+ * @param n - The dividend.
+ * @param m - The divisor (must be a positive, non-zero number).
+ * @returns The positive remainder representing `n mod m`.
+ *
+ * @example
+ * ```typescript
+ * mod(5, 3);   // returns 2
+ * mod(-1, 3);  // returns 2 (whereas -1 % 3 returns -1)
+ * ```
+ */
+export function mod(n, m) {
+    return ((n % m) + m) % m;
+}
+/**
+ * Computes the true mathematical modulo of two `bigint` values, ensuring a non-negative result.
+ *
+ * @remarks
+ * Similar to {@link mod}, this function implements correct mathematical modulo for large bigints
+ * so that any negative dividend `n` resolves into a positive remainder modulo `m`.
+ *
+ * @param n - The bigint dividend.
+ * @param m - The bigint divisor.
+ * @returns The positive bigint remainder representing `n mod m`.
+ *
+ * @example
+ * ```typescript
+ * bigIntMod(BigInt(-5), BigInt(3)); // returns 1n
+ * ```
+ */
+export function bigIntMod(n, m) {
+    return ((n % m) + m) % m;
+}
+/**
+ * Decodes a Node.js `Buffer` back into a JS native `BigInt` value.
+ *
+ * @param buffer - The source Buffer containing binary representation of the integer.
+ * @param little - Set to `true` if the buffer is encoded in little-endian format; set to `false` if big-endian. Defaults to `true`.
+ * @param signed - Set to `true` if the buffer contains a signed two's complement integer. Defaults to `false`.
+ * @returns A standard native `bigint` value decoded from the bytes.
+ *
+ * @example
+ * ```typescript
+ * const val = bufferToBigint(Buffer.from([0x2a, 0x00]), true, false); // 42n
+ * ```
+ */
+export function bufferToBigint(buffer, little = true, signed = false) {
+    const length = Buffer.byteLength(buffer);
+    const value = little ? buffer.reverse().toString('hex') : buffer.toString('hex');
+    const _bigint = bigInt(value, 16);
+    let bigint = BigInt(String(_bigint));
+    if (signed && Math.floor(bigint.toString(2).length / 8) >= length) {
+        bigint = bigint - bigIntPow(BigInt(2), BigInt(length * 8));
+    }
+    return BigInt(bigint);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * tgsnake - Telegram MTProto library for javascript or typescript.
+ * Copyright (C) 2026 tgsnake <https://github.com/tgsnake>
+ *
+ * THIS FILE IS PART OF TGSNAKE
+ *
+ * tgsnake is a free software: you can redistribute it and/or modify
+ * it under the terms of the MIT License as published.
+ */
+export { Raw, AllTLObject, Primitive, TLObject, GzipPacked, Message, MsgContainer, SecretChatMessage, SecretChatMessageService, UpdateSecretChatMessage, TypeTGenerate, } from './raw/index.js';
+export { bufferToBigint, bigIntMod, bigIntPow, bigintToBuffer, mod } from './helpers.js';
+export { BadMsgNotification, CDNFileHashMismatch, ClientError, Exceptions, FileErrors, NotAFunctionClass, RPCError, SecretChatError, SecurityCheckMismatch, SecurityError, TimeoutError, UnknownError, WSError, } from './errors/index.js';

package/dist/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * tgsnake - Telegram MTProto library for javascript or typescript.
+ * Copyright (C) 2026 tgsnake <https://github.com/tgsnake>
+ *
+ * THIS FILE IS PART OF TGSNAKE
+ *
+ * tgsnake is a free software: you can redistribute it and/or modify
+ * it under the terms of the MIT License as published.
+ */
+export { Raw, AllTLObject, Primitive, TLObject, GzipPacked, Message, MsgContainer, SecretChatMessage, SecretChatMessageService, UpdateSecretChatMessage, } from './raw/index.js';
+export { bufferToBigint, bigIntMod, bigIntPow, bigintToBuffer, mod } from './helpers.js';
+export { BadMsgNotification, CDNFileHashMismatch, ClientError, Exceptions, FileErrors, NotAFunctionClass, RPCError, SecretChatError, SecurityCheckMismatch, SecurityError, TimeoutError, UnknownError, WSError, } from './errors/index.js';