@tgsnake/skema 1.12.0 → 2.0.0-browser.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 tgsnake
+Copyright (c) 2026 tgsnake
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,37 +1,146 @@
 # Skema 🚀
 
-**Skema** is a compiled Telegram TL Schema and Telegram errors Schema into usable JavaScript classes with full TypeScript support.  
-This project was originally based on the source code from [`@tgsnake/core`](https://github.com/tgsnake/core). 🐍
+[![JSR Badge](https://jsr.io/badges/@tgsnake/skema)](https://jsr.io/@tgsnake/skema) [![NPM Version](https://img.shields.io/npm/v/@tgsnake/skema?style=flat-down&color=blue)](https://www.npmjs.com/package/@tgsnake/skema) [![NPM Downloads](https://img.shields.io/npm/dm/@tgsnake/skema?style=flat-down)](https://www.npmjs.com/package/@tgsnake/skema) [![License](https://img.shields.io/github/license/tgsnake/skema?style=flat-down&color=green)](https://github.com/tgsnake/skema/blob/main/LICENSE)
+
+**Skema** compiles the Telegram TL (Type Language) Schema and Telegram RPC Errors Schema into highly usable JavaScript classes with first-class TypeScript support.
+
+This project was originally based on the source code from [`@tgsnake/core`](https://github.com/tgsnake/core) 🐍.
+
+---
 
 <center>  
-  <b>Layer 224</b>  
+  <b>Layer 225</b>  
 </center>
 
-## Features ✨
+---
+
+## ⚠️ Requirements & Compatibility in v2.0.0
+
+> [!IMPORTANT]  
+> Starting with the major release **v2.0.0**, `@tgsnake/skema` is compiled as a pure ECMAScript Module (ESM). Since Node.js 20 introduced native support for `require(ESM)` under experimental flags (and subsequent stabilizing in newer versions), we fully transitioned to ESM. So, the minimum Node.js version required for installation and execution is **Node.js 22**. Ensure your runtime matches or exceeds this version before installing the package.
+
+---
 
-- Converts Telegram TL Schema to JavaScript/TypeScript classes
-- Handles Telegram error types
-- Easy integration into your TypeScript or JavaScript projects
+## ✨ Features
 
-## Installation 📦
+- Up-to-date with Telegram's compiled TL Schema.
+- **Bi-directional Serialization**: Clean and efficient API to serialize TL schema classes into binary `Buffer` structures (`.write()`) and parse them back (`.read()`).
+- **Comprehensive Error Mapping**: Built-in classes for standard Telegram `RPCError` exceptions, custom security mismatches, websocket timeouts, and MTProto packet notifications.
+- **Out-of-the-box Type Safety**: Fully typed modules providing precise autocompletion for Telegram functions, requests, and constructors.
+- **Multi-Runtime Support**: Compatible with modern ESM environments across Node.js, Deno, Bun, and Browser.
+
+---
+
+## 📦 Installation
+
+Install `@tgsnake/skema` using your preferred package manager:
 
 ```bash
+# Using npm
 npm install @tgsnake/skema
+
+# Using yarn
+yarn add @tgsnake/skema
+
+# Using pnpm
+pnpm add @tgsnake/skema
+
+# Using Bun
+bun add @tgsnake/skema
+```
+
+## Deno / JSR (Native Deno Import)
+
+```bash
+# Add the dependency via JSR
+deno add jsr:@tgsnake/skema
 ```
 
-## Usage 🛠️
+---
+
+## 🛠️ Usage Guide
+
+### Constructing Schema Objects
+
+You can construct Telegram MTProto API requests and constructors using the `Raw` namespace.
 
 ```ts
 import { Raw } from '@tgsnake/skema';
 
-// Example usage
-const sendMessageApi = new Raw.messages.SendMessage({
-  // constructor parameter here
+// Create a SendMessage request parameters object
+const sendMessageRequest = new Raw.messages.SendMessage({
+  peer: new Raw.InputPeerSelf(),
+  message: 'Hello from Skema! 🐍',
+  randomId: 1234567890n, // BigInt support for long/int128/int256 types
 });
+
+console.log(sendMessageRequest.className); // "messages.SendMessage"
+```
+
+### Catching & Handling Errors
+
+Skema includes robust exceptions mapping Telegram errors to digestible error classes.
+
+```ts
+import { RPCError, Exceptions } from '@tgsnake/skema';
+
+try {
+  // E.g., MTProto request execution logic...
+} catch (error) {
+  if (error instanceof RPCError) {
+    console.error(`RPC Error [${error.code}]: ${error.message} (${error.description})`);
+
+    // Check for specific error types
+    if (error instanceof Exceptions.BadRequest.PeerIdInvalid) {
+      console.error('The provided peer ID is invalid.');
+    }
+  }
+}
 ```
 
-## Why Skema? 🤔
+---
+
+## 🗃️ Key Exports & Architecture
+
+Below is a breakdown of the primary entry points and structures exported by `@tgsnake/skema`:
+
+### 🌐 Namespaces & Schema Engines
+
+- **`Raw`**: Contains the entire Telegram TL Schema constructors and requests. All types conform to MTProto Layer 225.
+  - `Raw.Layer`: The active layer number.
+  - `Raw.HighestSCLayer`: The highest secret chat layer supported.
+
+### 🏗️ Core Classes
+
+- **`TLObject`**: The base class for all compiled types. Implements common helper functions (`read`, `write`, `toJSON`, `toString`).
+- **`Message`**: Represents an individual MTProto envelope message encapsulating a payload, `msg_id`, `seq_no`, and length.
+- **`MsgContainer`**: A container class handling transport multiplexing of multiple MTProto messages.
+- **`GzipPacked`**: Helper utility handling compression and decompression of zlib payloads inside MTProto communications.
+
+### 🧰 Math & Buffer Helpers
+
+- **`bufferToBigint(buffer: Buffer)`**: Parses a binary buffer into a BigInt.
+- **`bigintToBuffer(number: bigint, padding?: number)`**: Converts a BigInt to its equivalent binary buffer.
+- **`mod(n: number, m: number)`** / **`bigIntMod(n: bigint, m: bigint)`**: Standard modulus helpers.
+
+### 🚨 Exceptional Errors Mappings
+
+- **`RPCError`**: Base class representing standard Telegram RPC failures.
+- **`BadMsgNotification`**: Raised when the MTProto server rejects a message envelope structure (such as incorrect server salt or out-of-sync message ID).
+- **`SecurityError`** / **`SecurityCheckMismatch`**: Raised when cryptographic assertions, signature checks, or padding validations fail during keys derivation.
+- **`CDNFileHashMismatch`**: Raised if a file chunk downloaded from a Telegram CDN fails checksum verification.
+- **`TimeoutError`**: Raised when a task exceeds its execution time boundary.
+
+---
+
+## 🤔 Why Skema?
+
+1. **Eliminates Boilerplate**: Automates the tedious, error-prone manual serialization layout and serialization rules of MTProto schemas.
+2. **Type Safety**: Write codebase with confidence using fully generated TypeScript definition files that precisely mirror the official Telegram Type Language layers.
+3. **Optimized for Modern Environments**: Native ESM and modern Node.js features support, making it lightweight and highly performant.
+
+---
+
+## 📄 License
 
-- Simplifies working with Telegram's complex TL schema
-- Type-safe: full TypeScript support
-- Reduces boilerplate and manual schema handling
+This project is licensed under the [MIT License](https://github.com/tgsnake/skema/blob/main/LICENSE) - Copyright (C) 2026 tgsnake.

package/dist/mod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 * from './src/index.js';

package/dist/mod.js

@@ -0,0 +1,10 @@
+/**
+ * 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 * from './src/index.js';

package/dist/src/Logger.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 './deps.js';
+/**
+ * The internal logger instance for the `@tgsnake/skema` package.
+ * Configure with debug level by default to output internal protocol logs.
+ *
+ * @remarks
+ * This logger wraps the `@tgsnake/log` utility. It is configured to output debug
+ * and more severe messages for tracing MTProto serialization and deserialization.
+ */
+declare const log: Logger;
+export { log as Logger };

package/dist/src/Logger.js

@@ -0,0 +1,23 @@
+/**
+ * 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 './deps.js';
+/**
+ * The internal logger instance for the `@tgsnake/skema` package.
+ * Configure with debug level by default to output internal protocol logs.
+ *
+ * @remarks
+ * This logger wraps the `@tgsnake/log` utility. It is configured to output debug
+ * and more severe messages for tracing MTProto serialization and deserialization.
+ */
+const log = new Logger({
+    name: '@tgsnake/skema',
+    level: ['debug'],
+});
+export { log as Logger };

package/dist/src/deps.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 { BytesIO } from '@tgsnake/bytesio';
+export { Logger } from '@tgsnake/log';
+export { gzipSync, gunzipSync } from 'browserify-zlib';
+export { Buffer } from 'buffer';
+import { inspect as nodeInspect } from 'util';
+import bigInt from 'big-integer';
+/**
+ * Identifies the runtime platform environment.
+ * Can be 'Deno', 'Bun', 'Browser', or 'Node'.
+ * @type {'Deno' | 'Bun' | 'Browser' | 'Node'}
+ */
+export declare const platform: string;
+/**
+ * Platform-independent utility function to deeply inspect objects.
+ * Uses `Deno.inspect` in Deno environment, otherwise falls back to Node's `util.inspect`.
+ *
+ * @type {typeof nodeInspect}
+ */
+export declare const inspect: typeof nodeInspect;
+export { bigInt };

package/dist/src/deps.js

@@ -0,0 +1,34 @@
+/**
+ * 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 { BytesIO } from '@tgsnake/bytesio';
+export { Logger } from '@tgsnake/log';
+export { gzipSync, gunzipSync } from 'browserify-zlib';
+export { Buffer } from 'buffer';
+import { inspect as nodeInspect } from 'util';
+import bigInt from 'big-integer';
+// Other platform compatibility
+// After this line, we will provide some compatibility for Deno, Bun, and Browser so that the same code can run in both environments without modification.
+const isDeno = 'Deno' in globalThis;
+const isBun = 'Bun' in globalThis;
+const isBrowser = !isDeno && !isBun && typeof window !== 'undefined'; // browser compatibility
+/**
+ * Identifies the runtime platform environment.
+ * Can be 'Deno', 'Bun', 'Browser', or 'Node'.
+ * @type {'Deno' | 'Bun' | 'Browser' | 'Node'}
+ */
+export const platform = isDeno ? 'Deno' : isBun ? 'Bun' : isBrowser ? 'Browser' : 'Node';
+/**
+ * Platform-independent utility function to deeply inspect objects.
+ * Uses `Deno.inspect` in Deno environment, otherwise falls back to Node's `util.inspect`.
+ *
+ * @type {typeof nodeInspect}
+ */
+export const inspect = nodeInspect;
+export { bigInt };

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

@@ -0,0 +1,53 @@
+/**
+ * Base custom error class for the entire tgsnake library.
+ *
+ * @remarks
+ * This class inherits from the standard JavaScript `Error` object.
+ * It provides uniform JSON serialization (`toJSON`), string serialization (`toString`),
+ * and platform-agnostic runtime object inspector support for Node.js (`util.inspect`)
+ * and Deno console utilities.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomError extends BaseError {
+ *   constructor(msg: string) {
+ *     super(msg);
+ *     this.name = "MyCustomError";
+ *   }
+ * }
+ * ```
+ */
+export declare class BaseError extends Error {
+    /**
+     * The message string describing this error.
+     */
+    message: string;
+    /**
+     * Detailed human-readable description offering troubleshooting steps or context.
+     */
+    description?: string;
+    /**
+     * Constructs a new instance of the BaseError class.
+     *
+     * @param message - An optional brief message describing the error.
+     */
+    constructor(message?: string);
+    /**
+     * Serializes the 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;
+}

package/dist/src/errors/Base.js

@@ -0,0 +1,114 @@
+/**
+ * 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 { inspect } from '../deps.js';
+/**
+ * Base custom error class for the entire tgsnake library.
+ *
+ * @remarks
+ * This class inherits from the standard JavaScript `Error` object.
+ * It provides uniform JSON serialization (`toJSON`), string serialization (`toString`),
+ * and platform-agnostic runtime object inspector support for Node.js (`util.inspect`)
+ * and Deno console utilities.
+ *
+ * @example
+ * ```typescript
+ * class MyCustomError extends BaseError {
+ *   constructor(msg: string) {
+ *     super(msg);
+ *     this.name = "MyCustomError";
+ *   }
+ * }
+ * ```
+ */
+export class BaseError extends Error {
+    /**
+     * The message string describing this error.
+     */
+    message;
+    /**
+     * Detailed human-readable description offering troubleshooting steps or context.
+     */
+    description;
+    /**
+     * Constructs a new instance of the BaseError class.
+     *
+     * @param message - An optional brief message describing the error.
+     */
+    constructor(message) {
+        super(message);
+    }
+    /**
+     * 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('_')) {
+                    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 custom inspect
+        return String(inspect(this[Symbol.for('nodejs.util.inspect.custom')](), { colors: true }));
+    }
+    /**
+     * Serializes the 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)}`;
+    }
+}

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

@@ -0,0 +1,69 @@
+/**
+ * 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';
+/**
+ * Error thrown when a client request is attempted while the Telegram MTProto client is completely disconnected.
+ *
+ * @remarks
+ * To resolve this error, ensure that `client.connect()` or equivalent initialization routines are run
+ * and completed successfully before initiating requests to the Telegram API.
+ *
+ * @extends BaseError
+ */
+export declare class ClientDisconnected extends BaseError {
+    message: string;
+    description: string;
+}
+/**
+ * Error thrown when the Telegram client completely fails to establish a connection to the data center servers.
+ *
+ * @remarks
+ * This occurs when the network connection retries exceed the user-defined maximum attempt threshold.
+ *
+ * @extends BaseError
+ */
+export declare class ClientFailed extends BaseError {
+    message: string;
+    description: string;
+}
+/**
+ * Error thrown when an attempt is made to call connect or start on an already connected Telegram client.
+ *
+ * @remarks
+ * Re-initiating a connection while the socket/channel is already fully active is not permitted.
+ *
+ * @extends BaseError
+ */
+export declare class ClientReady extends BaseError {
+    message: string;
+    description: string;
+}
+/**
+ * Error thrown when an attempt is made to disconnect or stop an already disconnected Telegram client.
+ *
+ * @extends BaseError
+ */
+export declare class ClientNotReady extends BaseError {
+    message: string;
+    description: string;
+}
+/**
+ * Error thrown when the MTProto session authentication key is missing or not provided.
+ *
+ * @remarks
+ * This commonly happens if the client is run in an environment expecting an existing session file
+ * or session string, but no authorization parameters or credentials are supplied.
+ *
+ * @extends BaseError
+ */
+export declare class AuthKeyMissing extends BaseError {
+    message: string;
+    description: string;
+}

package/dist/src/errors/Client.js

@@ -0,0 +1,69 @@
+/**
+ * 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';
+/**
+ * Error thrown when a client request is attempted while the Telegram MTProto client is completely disconnected.
+ *
+ * @remarks
+ * To resolve this error, ensure that `client.connect()` or equivalent initialization routines are run
+ * and completed successfully before initiating requests to the Telegram API.
+ *
+ * @extends BaseError
+ */
+export class ClientDisconnected extends BaseError {
+    message = "Can't send request to telegram when client is unconnected.";
+    description = 'The provided telegram client is unconnected, make sure to start the telegram client first before sending request.';
+}
+/**
+ * Error thrown when the Telegram client completely fails to establish a connection to the data center servers.
+ *
+ * @remarks
+ * This occurs when the network connection retries exceed the user-defined maximum attempt threshold.
+ *
+ * @extends BaseError
+ */
+export class ClientFailed extends BaseError {
+    message = 'Client failed to connect to server.';
+    description = 'The provided telegram client failed to connect to the telegram data center server. Attempts to connect to the telegram server have exceeded the specified maximum limit.';
+}
+/**
+ * Error thrown when an attempt is made to call connect or start on an already connected Telegram client.
+ *
+ * @remarks
+ * Re-initiating a connection while the socket/channel is already fully active is not permitted.
+ *
+ * @extends BaseError
+ */
+export class ClientReady extends BaseError {
+    message = 'Client is already connected to server.';
+    description = 'The provided telegram client has been already connected to the telegram data center server.';
+}
+/**
+ * Error thrown when an attempt is made to disconnect or stop an already disconnected Telegram client.
+ *
+ * @extends BaseError
+ */
+export class ClientNotReady extends BaseError {
+    message = 'Client is already disconnected to server.';
+    description = 'The provided telegram client has been already disconnected to the telegram data center server.';
+}
+/**
+ * Error thrown when the MTProto session authentication key is missing or not provided.
+ *
+ * @remarks
+ * This commonly happens if the client is run in an environment expecting an existing session file
+ * or session string, but no authorization parameters or credentials are supplied.
+ *
+ * @extends BaseError
+ */
+export class AuthKeyMissing extends BaseError {
+    message = 'Auth key unavailable';
+    description = 'Auth key is unavailable, this can happen because at when the client is run, the user does not provide information to login.';
+}