@tgsnake/skema 1.12.0 → 2.0.0-browser.0

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

@@ -0,0 +1,89 @@
+/**
+ * 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 { BaseError } from './Base.js';
+/**
+ * Base error class for all file and stream operations.
+ *
+ * @remarks
+ * Extends {@link BaseError} to provide additional context specifically for handling,
+ * transferring, and validating local or remote files.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new FileError('File not found', 'The specified file does not exist.');
+ * ```
+ */
+export declare class FileError extends BaseError {
+    /**
+     * Constructs a new FileError instance.
+     *
+     * @param message - A brief message describing the error.
+     * @param description - An optional detailed description or troubleshooting guide.
+     */
+    constructor(message: string, description?: string);
+}
+/**
+ * Error thrown when an attempt is made to upload or process a zero-byte file.
+ *
+ * @remarks
+ * Telegram MTProto uploads require files to have a non-zero byte size.
+ *
+ * @extends FileError
+ * @example
+ * ```typescript
+ * if (file.size === 0) {
+ *   throw new FileUploadZero();
+ * }
+ * ```
+ */
+export declare class FileUploadZero extends FileError {
+    /**
+     * Constructs a new FileUploadZero instance with predefined error messages.
+     */
+    constructor();
+}
+/**
+ * Error thrown when a file exceeds the maximum allowed file upload size.
+ *
+ * @extends FileError
+ * @example
+ * ```typescript
+ * if (file.size > LIMIT) {
+ *   throw new FileUploadBigger(LIMIT, file.size);
+ * }
+ * ```
+ */
+export declare class FileUploadBigger extends FileError {
+    /**
+     * Constructs a new FileUploadBigger instance.
+     *
+     * @param limit - The maximum allowed file size limit in bytes.
+     * @param size - The actual size of the provided file in bytes.
+     */
+    constructor(limit: number, size: number);
+}
+/**
+ * Error thrown when the provided argument is not a valid readable stream or buffer.
+ *
+ * @extends FileError
+ * @example
+ * ```typescript
+ * if (!isReadableStream(arg)) {
+ *   throw new FileIsNotReadable();
+ * }
+ * ```
+ */
+export declare class FileIsNotReadable extends FileError {
+    /**
+     * Constructs a new FileIsNotReadable instance with predefined error messages.
+     */
+    constructor();
+}

package/dist/src/errors/File.js

@@ -0,0 +1,99 @@
+/**
+ * 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 { BaseError } from './Base.js';
+/**
+ * Base error class for all file and stream operations.
+ *
+ * @remarks
+ * Extends {@link BaseError} to provide additional context specifically for handling,
+ * transferring, and validating local or remote files.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new FileError('File not found', 'The specified file does not exist.');
+ * ```
+ */
+export class FileError extends BaseError {
+    /**
+     * Constructs a new FileError instance.
+     *
+     * @param message - A brief message describing the error.
+     * @param description - An optional detailed description or troubleshooting guide.
+     */
+    constructor(message, description) {
+        super();
+        this.message = message;
+        this.description = description;
+    }
+}
+/**
+ * Error thrown when an attempt is made to upload or process a zero-byte file.
+ *
+ * @remarks
+ * Telegram MTProto uploads require files to have a non-zero byte size.
+ *
+ * @extends FileError
+ * @example
+ * ```typescript
+ * if (file.size === 0) {
+ *   throw new FileUploadZero();
+ * }
+ * ```
+ */
+export class FileUploadZero extends FileError {
+    /**
+     * Constructs a new FileUploadZero instance with predefined error messages.
+     */
+    constructor() {
+        super("Can't upload file when it zero bytes.", 'Provided file has zero bytes (0 B) file size.');
+    }
+}
+/**
+ * Error thrown when a file exceeds the maximum allowed file upload size.
+ *
+ * @extends FileError
+ * @example
+ * ```typescript
+ * if (file.size > LIMIT) {
+ *   throw new FileUploadBigger(LIMIT, file.size);
+ * }
+ * ```
+ */
+export class FileUploadBigger extends FileError {
+    /**
+     * Constructs a new FileUploadBigger instance.
+     *
+     * @param limit - The maximum allowed file size limit in bytes.
+     * @param size - The actual size of the provided file in bytes.
+     */
+    constructor(limit, size) {
+        super(`File greater than ${limit} B.`, `The provided file has ${size} B file size, it greater than ${limit} B`);
+    }
+}
+/**
+ * Error thrown when the provided argument is not a valid readable stream or buffer.
+ *
+ * @extends FileError
+ * @example
+ * ```typescript
+ * if (!isReadableStream(arg)) {
+ *   throw new FileIsNotReadable();
+ * }
+ * ```
+ */
+export class FileIsNotReadable extends FileError {
+    /**
+     * Constructs a new FileIsNotReadable instance with predefined error messages.
+     */
+    constructor() {
+        super('FILE_IS_NOT_READABLE', 'The argument provided is not a Readable stream.');
+    }
+}

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

@@ -0,0 +1,115 @@
+/**
+ * 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 { Raw, TLObject } from '../raw/index.js';
+/**
+ * Base error class for all Remote Procedure Call (RPC) errors returned by the Telegram API.
+ *
+ * @remarks
+ * Every failed API request returns an RPC error consisting of an error code (e.g. 400, 401, 403, 420, etc.)
+ * and an error identifier (e.g. `PHONE_NUMBER_INVALID`). This class dynamically maps, formats,
+ * and formats exceptions into descriptive structures that inherit from `Error`.
+ *
+ * @extends Error
+ */
+export declare class RPCError extends Error {
+    /**
+     * The Telegram-specific alphanumeric error code identifier. E.g. `FLOOD_WAIT_X`.
+     */
+    id: string;
+    /**
+     * The HTTP/MTProto status code returned. E.g. 400 or 420.
+     */
+    code: number;
+    /**
+     * The formatted, human-readable error message.
+     */
+    message: string;
+    /**
+     * The class name representing this error instance.
+     */
+    name: string;
+    /**
+     * The optional value parsed from the Telegram error string (such as the number of seconds to wait).
+     */
+    value?: number | string | Raw.RpcError;
+    /**
+     * Internal sign flag. True if the Telegram error code was negative.
+     *
+     * @internal
+     */
+    _isSigned?: boolean;
+    /**
+     * Internal flag indicating whether the error code or string was unrecognized.
+     *
+     * @internal
+     */
+    _isUnknown?: boolean;
+    /**
+     * The name of the specific RPC method that triggered this error.
+     *
+     * @internal
+     */
+    _rpcName?: string;
+    /**
+     * Constructs a new RPCError instance.
+     *
+     * @param value - The parsed variable value from the Telegram error string, if any.
+     * @param rpcName - The name of the causing RPC method.
+     * @param isUnknown - True if the error is unrecognized.
+     * @param isSigned - True if the error code is signed.
+     */
+    constructor(value?: number | string | Raw.RpcError, rpcName?: string, isUnknown?: boolean, isSigned?: boolean);
+    /**
+     * Formats the final exception message by embedding variables and the causing RPC method name.
+     *
+     * @protected
+     */
+    protected _format(): void;
+    /**
+     * Analyzes a raw Telegram `RpcError` object and raises a matching, highly-specialized RPC sub-exception.
+     *
+     * @remarks
+     * This static factory parses the Telegram response error string, extracts parameterized values (such as
+     * the cooldown duration in `FLOOD_WAIT_60`), matches the error code to the compiled exception dictionary,
+     * constructs the correct class dynamically, and throws the finalized instance.
+     *
+     * @param rpcError - The raw `RpcError` returned from the API deserializer.
+     * @param rpcType - The causing TL request object context.
+     * @throws {RPCError} The parsed, specialized subclass of `RPCError`.
+     */
+    static raise(rpcError: Raw.RpcError, rpcType: TLObject): Promise<void>;
+    /**
+     * Serializes the RPC error object to a clean JSON-compatible representation.
+     *
+     * @remarks
+     * Correctly stringifies extremely large fields (e.g. bigints) that are normally not
+     * serializable in standard `JSON.stringify` calls.
+     *
+     * @returns A plain object containing error properties and the stack trace.
+     */
+    toJSON(): {
+        [key: string]: unknown;
+    };
+    /**
+     * Formats the error into a structured string.
+     *
+     * @returns A string starting with the constructor name followed by a pretty JSON payload.
+     */
+    toString(): string;
+}
+/**
+ * Fallback error class used when the Telegram API returns an unrecognized error code or message.
+ *
+ * @extends RPCError
+ */
+export declare class UnknownError extends RPCError {
+    code: number;
+    name: string;
+}

package/dist/src/errors/RpcError.js

@@ -0,0 +1,226 @@
+/**
+ * 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 { Logger } from '../Logger.js';
+import { Exceptions } from './exceptions/All.js';
+import { inspect } from '../deps.js';
+import { Exceptions as AllExceptions } from './index.js';
+function getModule(name) {
+    const [namespace, mod] = name.split('.');
+    if (AllExceptions[namespace] &&
+        AllExceptions[namespace][mod]) {
+        return AllExceptions[namespace][mod];
+    }
+    return UnknownError;
+}
+/**
+ * Base error class for all Remote Procedure Call (RPC) errors returned by the Telegram API.
+ *
+ * @remarks
+ * Every failed API request returns an RPC error consisting of an error code (e.g. 400, 401, 403, 420, etc.)
+ * and an error identifier (e.g. `PHONE_NUMBER_INVALID`). This class dynamically maps, formats,
+ * and formats exceptions into descriptive structures that inherit from `Error`.
+ *
+ * @extends Error
+ */
+export class RPCError extends Error {
+    /**
+     * The Telegram-specific alphanumeric error code identifier. E.g. `FLOOD_WAIT_X`.
+     */
+    id;
+    /**
+     * The HTTP/MTProto status code returned. E.g. 400 or 420.
+     */
+    code;
+    /**
+     * The formatted, human-readable error message.
+     */
+    message;
+    /**
+     * The class name representing this error instance.
+     */
+    name;
+    /**
+     * The optional value parsed from the Telegram error string (such as the number of seconds to wait).
+     */
+    value;
+    /**
+     * Internal sign flag. True if the Telegram error code was negative.
+     *
+     * @internal
+     */
+    _isSigned;
+    /**
+     * Internal flag indicating whether the error code or string was unrecognized.
+     *
+     * @internal
+     */
+    _isUnknown;
+    /**
+     * The name of the specific RPC method that triggered this error.
+     *
+     * @internal
+     */
+    _rpcName;
+    /**
+     * Constructs a new RPCError instance.
+     *
+     * @param value - The parsed variable value from the Telegram error string, if any.
+     * @param rpcName - The name of the causing RPC method.
+     * @param isUnknown - True if the error is unrecognized.
+     * @param isSigned - True if the error code is signed.
+     */
+    constructor(value, rpcName, isUnknown, isSigned) {
+        super();
+        Logger.debug(`[8] Creating new instance RPCError(${rpcName ?? this.name})`);
+        this._isSigned = isSigned;
+        this._isUnknown = isUnknown;
+        this._rpcName = rpcName;
+        if (!Number.isNaN(value)) {
+            this.value = Number(value);
+        }
+        else {
+            this.value = value;
+        }
+        if (isUnknown) {
+            Logger.debug(`[9] UnknownError : ${this.name}`);
+            // TODO: write UnknownError.txt file
+        }
+    }
+    /**
+     * Formats the final exception message by embedding variables and the causing RPC method name.
+     *
+     * @protected
+     */
+    _format() {
+        this.message = `Telegram Says: [${this._isSigned ? '-' : ''}${this.code} ${this.id || this.name}] - ${(this.message || '').replace(/\{value\}/g, String(this.value))} ${this._rpcName ? `(caused by ${this._rpcName})` : ''}`;
+    }
+    /**
+     * Analyzes a raw Telegram `RpcError` object and raises a matching, highly-specialized RPC sub-exception.
+     *
+     * @remarks
+     * This static factory parses the Telegram response error string, extracts parameterized values (such as
+     * the cooldown duration in `FLOOD_WAIT_60`), matches the error code to the compiled exception dictionary,
+     * constructs the correct class dynamically, and throws the finalized instance.
+     *
+     * @param rpcError - The raw `RpcError` returned from the API deserializer.
+     * @param rpcType - The causing TL request object context.
+     * @throws {RPCError} The parsed, specialized subclass of `RPCError`.
+     */
+    static async raise(rpcError, rpcType) {
+        let code = rpcError.errorCode;
+        const message = rpcError.errorMessage;
+        const isSigned = code < 0;
+        const name = rpcType.className;
+        if (isSigned)
+            code = -code;
+        if (!(code in Exceptions)) {
+            throw new UnknownError(`[${code} ${message}]`, name, true, isSigned);
+        }
+        let id = message.replace(/\_\d+/gm, '_X');
+        const regexMatch = message.match(/\_(\d+)/gm);
+        let value = '';
+        if (regexMatch) {
+            value = regexMatch[0].replace(/\_/g, '');
+        }
+        if (!(id in Exceptions[code])) {
+            // try to replace the last word with asterisk (*)
+            // example: FILE_REFERENCE_*
+            id = id.split('_').splice(-1, 1, '*').join('_');
+            if (!(id in Exceptions[code])) {
+                const modules = getModule(Exceptions[code]['_']);
+                const _module = new modules(value, name, true, isSigned);
+                _module.message = `[${code} ${message}]`;
+                _module.id = message.replace(/\_\d+/gm, '_X');
+                _module._format();
+                throw _module;
+            }
+        }
+        const modules = await getModule(Exceptions[code][id]);
+        const _module = new modules(value, name, false, isSigned);
+        _module._format();
+        throw _module;
+    }
+    /**
+     * Custom inspect handler for Node.js console output (`util.inspect`).
+     * Omits private properties (prefixed with `_`) to keep debug prints clean.
+     *
+     * @ignore
+     * @returns An object containing enumerable public properties to display.
+     */
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        const toPrint = {
+            _: this.constructor.name,
+        };
+        for (const key in this) {
+            if (Object.prototype.hasOwnProperty.call(this, key)) {
+                const value = this[key];
+                if (!key.startsWith('_') && value !== undefined && value !== null) {
+                    toPrint[key] = value;
+                }
+            }
+        }
+        Object.setPrototypeOf(toPrint, {
+            stack: this.stack,
+        });
+        return toPrint;
+    }
+    /**
+     * Custom inspect handler for Deno runtime terminal output (`Deno.inspect`).
+     * Wraps the Node.js inspect output and enables terminal colors.
+     *
+     * @ignore
+     * @returns The colorized, formatted representation of the error.
+     */
+    [Symbol.for('Deno.customInspect')]() {
+        // @ts-ignore: deno compatibility
+        return String(inspect(this[Symbol.for('nodejs.util.inspect.custom')](), { colors: true }));
+    }
+    /**
+     * Serializes the RPC error object to a clean JSON-compatible representation.
+     *
+     * @remarks
+     * Correctly stringifies extremely large fields (e.g. bigints) that are normally not
+     * serializable in standard `JSON.stringify` calls.
+     *
+     * @returns A plain object containing error properties and the stack trace.
+     */
+    toJSON() {
+        const toPrint = {
+            _: this.constructor.name,
+            stack: this.stack,
+        };
+        for (const key in this) {
+            if (Object.prototype.hasOwnProperty.call(this, key)) {
+                const value = this[key];
+                if (!key.startsWith('_')) {
+                    toPrint[key] = typeof value === 'bigint' ? String(value) : value;
+                }
+            }
+        }
+        return toPrint;
+    }
+    /**
+     * Formats the error into a structured string.
+     *
+     * @returns A string starting with the constructor name followed by a pretty JSON payload.
+     */
+    toString() {
+        return `[constructor of ${this.constructor.name}] ${JSON.stringify(this, null, 2)}`;
+    }
+}
+/**
+ * Fallback error class used when the Telegram API returns an unrecognized error code or message.
+ *
+ * @extends RPCError
+ */
+export class UnknownError extends RPCError {
+    code = 520;
+    name = 'Unknown Error';
+}

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

@@ -0,0 +1,78 @@
+/**
+ * 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 { BaseError } from './Base.js';
+/**
+ * Base custom error class for all secret chat end-to-end encryption and session management issues.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new SecretChatError('Failed to decrypt message', 'The provided key is invalid.');
+ * ```
+ */
+export declare class SecretChatError extends BaseError {
+    /**
+     * Constructs a new SecretChatError instance.
+     *
+     * @param message - A brief message describing the error.
+     * @param description - An optional detailed description or troubleshooting context.
+     */
+    constructor(message: string, description?: string);
+}
+/**
+ * Error thrown when a security key fingerprint mismatch is detected during end-to-end secret chat encryption.
+ *
+ * @remarks
+ * This suggests that the encryption key exchanged does not match, indicating the session is not secure
+ * or has been tampered with. For security reasons, the secret chat must be closed immediately.
+ *
+ * @extends SecretChatError
+ */
+export declare class FingerprintMismatch extends SecretChatError {
+    /**
+     * Constructs a new FingerprintMismatch instance with predefined error messages.
+     */
+    constructor();
+}
+/**
+ * Error thrown when a secret chat session ID cannot be found in the client's local database or session file.
+ *
+ * @remarks
+ * Ensure that the `chatId` is valid, correct, and that the secret chat negotiation has already taken place
+ * and was stored successfully.
+ *
+ * @extends SecretChatError
+ * @example
+ * ```typescript
+ * throw new ChatNotFound(12345);
+ * ```
+ */
+export declare class ChatNotFound extends SecretChatError {
+    /**
+     * Constructs a new ChatNotFound instance.
+     *
+     * @param chatId - The target secret chat ID that was not found.
+     */
+    constructor(chatId: number);
+}
+/**
+ * Error thrown when an attempt is made to accept an end-to-end secret chat request that has already been accepted.
+ *
+ * @remarks
+ * Secret chats can only transition from pending to accepted once.
+ *
+ * @extends SecretChatError
+ */
+export declare class AlreadyAccepted extends SecretChatError {
+    /**
+     * Constructs a new AlreadyAccepted instance.
+     */
+    constructor();
+}

package/dist/src/errors/SecretChat.js

@@ -0,0 +1,88 @@
+/**
+ * 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 { BaseError } from './Base.js';
+/**
+ * Base custom error class for all secret chat end-to-end encryption and session management issues.
+ *
+ * @extends BaseError
+ * @example
+ * ```typescript
+ * throw new SecretChatError('Failed to decrypt message', 'The provided key is invalid.');
+ * ```
+ */
+export class SecretChatError extends BaseError {
+    /**
+     * Constructs a new SecretChatError instance.
+     *
+     * @param message - A brief message describing the error.
+     * @param description - An optional detailed description or troubleshooting context.
+     */
+    constructor(message, description) {
+        super();
+        this.message = message;
+        this.description = description;
+    }
+}
+/**
+ * Error thrown when a security key fingerprint mismatch is detected during end-to-end secret chat encryption.
+ *
+ * @remarks
+ * This suggests that the encryption key exchanged does not match, indicating the session is not secure
+ * or has been tampered with. For security reasons, the secret chat must be closed immediately.
+ *
+ * @extends SecretChatError
+ */
+export class FingerprintMismatch extends SecretChatError {
+    /**
+     * Constructs a new FingerprintMismatch instance with predefined error messages.
+     */
+    constructor() {
+        super('Fingerprint key mismatch', 'Given fingerprint key from message is mismatch. So the message is not secure and the secret chat should be closed.');
+    }
+}
+/**
+ * Error thrown when a secret chat session ID cannot be found in the client's local database or session file.
+ *
+ * @remarks
+ * Ensure that the `chatId` is valid, correct, and that the secret chat negotiation has already taken place
+ * and was stored successfully.
+ *
+ * @extends SecretChatError
+ * @example
+ * ```typescript
+ * throw new ChatNotFound(12345);
+ * ```
+ */
+export class ChatNotFound extends SecretChatError {
+    /**
+     * Constructs a new ChatNotFound instance.
+     *
+     * @param chatId - The target secret chat ID that was not found.
+     */
+    constructor(chatId) {
+        super('Secret chat not found', `Provided chatId (${chatId}) is not found in session. Make sure the chatId is correct and already saved in session.`);
+    }
+}
+/**
+ * Error thrown when an attempt is made to accept an end-to-end secret chat request that has already been accepted.
+ *
+ * @remarks
+ * Secret chats can only transition from pending to accepted once.
+ *
+ * @extends SecretChatError
+ */
+export class AlreadyAccepted extends SecretChatError {
+    /**
+     * Constructs a new AlreadyAccepted instance.
+     */
+    constructor() {
+        super('Secret chat already accepted');
+    }
+}