feat: update docs for @gramio/init-data

Author: kravetsone

.cursor/rules/translation-sync.mdc

@@ -13,6 +13,7 @@ alwaysApply: true
 - Exclude double translation (do not translate docs/ru/ back into docs/ru/).
 - You can check updates via `Recent changes`
 - Correct grammatical punctuation and other errors in both: original and other language modified files.
+- Please dont delete `// ^?` it used internally 
 
 Examples:
 - docs/plugins/official/scenes.md <=> docs/ru/plugins/official/scenes.md

docs/ru/tma/init-data.md

@@ -13,7 +13,16 @@ head:
 
 # Валидация WebAppInitData
 
-Библиотека `@gramio/init-data` позволяет проверять подлинность данных, передаваемых из Telegram Mini Apps на ваш сервер, обеспечивая безопасное взаимодействие между веб-приложением и ботом.
+`@gramio/init-data` — это библиотека на TypeScript для безопасной проверки, разбора и генерации строк инициализации (init data) Telegram Web App. Она предоставляет набор утилит для работы с init data Telegram Mini App, обеспечивая целостность и подлинность пользовательских данных, передаваемых из Telegram-клиента на ваш сервер. Библиотека не зависит от фреймворка.
+
+Основные возможности:
+
+-   Проверка подлинности init data Telegram Web App с помощью токена бота
+-   Разбор и получение структурированных данных пользователя и чата из строки init data
+-   Генерация валидных строк init data для тестирования и документации
+-   Строгие типы TypeScript для всех структур и методов
+
+[Документация и справочник](https://jsr.io/@gramio/init-data@latest/doc)
 
 ## Установка
 
@@ -32,70 +41,114 @@ pnpm add @gramio/init-data
 ```
 
 ```bash [bun]
-bun add @gramio/init-data
+bun install @gramio/init-data
 ```
 
 :::
 
-### validateAndParseInitData
+# getBotTokenSecretKey
+
+Получает секретный ключ из токена вашего Telegram-бота. Этот ключ необходим для проверки хэша строки init data, отправленной из Telegram Web App. Всегда используйте этот метод для генерации ключа перед валидацией или подписью init data, если хотите максимальную производительность. Если не передавать ключ в методы проверки, он будет вычисляться **при каждом вызове**.
+
+```ts
+import { getBotTokenSecretKey } from "@gramio/init-data";
+
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
+// используйте secretKey далее
+```
+
+# validateAndParseInitData
+
+Проверяет подлинность строки init data Telegram Web App с помощью секретного ключа или токена бота. Если данные валидны, возвращает объект [WebAppInitData](https://core.telegram.org/bots/webapps#webappinitdata). Если данные некорректны — возвращает `false`.
 
 ```ts
-import { validateAndParseInitData } from "@gramio/init-data";
+import {
+    validateAndParseInitData,
+    getBotTokenSecretKey,
+} from "@gramio/init-data";
 
-const initData = validateAndParseInitData(initDataString, "BOT_TOKEN");
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
 
-if (!initData) {
-    throw new Error("Invalid init data");
+const initData = req.headers["x-init-data"] as string;
+const result = validateAndParseInitData(initData, secretKey);
+
+if (!result) {
+    // Данные невалидны или подделаны
 }
 
-console.log(initData.user);
+// Доступ к данным пользователя и чата
+const userId = result.user?.id;
+const chatId = result.chat?.id;
 ```
 
-## Проверка init-data
+# validateInitData
+
+Проверяет подлинность строки init data Telegram Web App с помощью секретного ключа или токена бота. Возвращает `true`, если данные валидны, иначе — `false`. Этот метод только проверяет данные и **не разбирает** их. Используйте, если нужно только проверить подлинность без извлечения информации о пользователе или чате.
 
 ```ts
-import { validateInitData } from "@gramio/init-data";
+import { validateInitData, getBotTokenSecretKey } from "@gramio/init-data";
 
-// Получаем init-data из запроса
-const initDataString = req.query.initData;
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
 
-// Валидируем с использованием токена бота
-const isValid = validateInitData(initDataString, "BOT_TOKEN");
+const initData = req.headers["x-init-data"] as string;
+const isValid = validateInitData(initData, secretKey);
 
-if (isValid) {
-    // Данные действительно пришли из Telegram
-    console.log("Данные прошли проверку");
-} else {
-    // Данные не прошли проверку или были подделаны
-    console.log("Внимание: Данные не прошли проверку!");
+if (!isValid) {
+    // Данные невалидны или подделаны
 }
+// Если true — строке init data можно доверять
 ```
 
-## Получение данных пользователя
+# parseInitData
+
+Разбирает строку init data Telegram Web App и возвращает объект [WebAppInitData](https://core.telegram.org/bots/webapps#webappinitdata). Этот метод **не выполняет проверку** подлинности или целостности — используйте его только после проверки через `validateInitData` или `validateAndParseInitData`.
 
 ```ts
 import { parseInitData } from "@gramio/init-data";
 
-// Разбор строки init-data
-const initData = parseInitData(initDataString);
+const initData = req.headers["x-init-data"] as string;
+const parsed = parseInitData(initData);
 
-// Теперь можно получить доступ к данным
-console.log(initData.user); // Информация о пользователе
-console.log(initData.auth_date); // Дата аутентификации
-console.log(initData.hash); // Хэш для проверки
+// Доступ к данным пользователя и чата
+const userId = parsed.user?.id;
+const chatId = parsed.chat?.id;
 ```
 
-## Безопасность
+# signInitData
 
-Всегда проверяйте данные init-data перед использованием, чтобы гарантировать, что запрос действительно поступил из Telegram и данные не были подделаны.
+Генерирует валидную строку init data из объекта данных и секретного ключа или токена бота. Полезно для тестирования, документации или генерации примеров для клиентов API.
 
-## Пример интеграции с Elysia
+```ts
+import {
+    signInitData,
+    getBotTokenSecretKey,
+    type WebAppUser,
+} from "@gramio/init-data";
+
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
+
+const data = {
+    user: {
+        id: 1,
+        first_name: "durov",
+        username: "durov",
+    },
+} satisfies WebAppUser;
 
-Этот пример демонстрирует, как интегрировать `@gramio/init-data` с Elysia с помощью удобного плагина с типо-безопасностью.
+const signedInitData = signInitData(data, secretKey);
+// Используйте signedInitData как валидную строку init data для тестов
+```
+
+# Пример: интеграция с Elysia
 
-`examples` в `x-init-data` заголовке являются валидными сгенерированными `init-data`, которые позволяют легче тестировать ваш API в OpenAPI клиентах.
+Вы можете использовать `@gramio/init-data` с любым backend-фреймворком. Ниже — бонус: пример интеграции с Elysia для типобезопасной аутентификации.
 
-```ts twoslash
+```ts
+twoslash;
 import {
     validateAndParseInitData,
     signInitData,

docs/tma/init-data.md

@@ -1,6 +1,15 @@
 # Init data
 
-WIP
+`@gramio/init-data` is a TypeScript library for securely validating, parsing, and generating Telegram Web App init data strings. It provides a set of utilities to help you work with the Telegram Mini App authentication init data, ensuring the integrity and authenticity of user data passed from the Telegram client to your backend. The library is framework-agnostic.
+
+Key features:
+
+-   Validates the authenticity of Telegram Web App init data using your bot token
+-   Parses and exposes structured user and chat data from the init data string
+-   Generates valid init data strings for testing and documentation
+-   Provides strong TypeScript types for all data structures and methods
+
+[Reference](https://jsr.io/@gramio/[email protected]/doc)
 
 ### Installation
 
@@ -24,13 +33,109 @@ bun install @gramio/init-data
 
 :::
 
-## Elysia integration example
+# getBotTokenSecretKey
+
+Get a secret key from your Telegram bot token. This secret key is required to validate the hash of the init data string sent by the Telegram Web App. Always use this method to generate the secret key before validating or signing init data if you wants reach maximum performance. If you don't provide it to validate init data methods it will execute it on **every call**.
+
+```ts
+import { getBotTokenSecretKey } from "@gramio/init-data";
+
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
+// use it later
+```
+
+# validateAndParseInitData
+
+Verifies the authenticity of the Telegram Web App init data string using the secret key or bot token. If the data is valid, it parses and returns the [WebAppInitData](https://core.telegram.org/bots/webapps#webappinitdata) object. If the data is invalid, it returns `false`.
+
+```ts
+import {
+    validateAndParseInitData,
+    getBotTokenSecretKey,
+} from "@gramio/init-data";
+
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
+
+const initData = req.headers["x-init-data"] as string;
+const result = validateAndParseInitData(initData, secretKey);
+
+if (!result) {
+    // Handle invalid or tampered data
+}
+
+// Access user and chat data
+const userId = result.user?.id;
+const chatId = result.chat?.id;
+```
+
+# validateInitData
+
+Checks the authenticity of the Telegram Web App init data string using the secret key or bot token. Returns `true` if the data is valid, otherwise returns `false`. This method only validates the data and does **not parse** it. Use this when you only need to check authenticity without extracting user or chat information.
+
+```ts
+import { validateInitData, getBotTokenSecretKey } from "@gramio/init-data";
+
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
+
+const initData = req.headers["x-init-data"] as string;
+const isValid = validateInitData(initData, secretKey);
+
+if (!isValid) {
+    // Handle invalid or tampered data
+}
+// If valid, you can safely trust the init data string
+```
+
+# parseInitData
+
+Parses the Telegram Web App init data string and returns the [WebAppInitData](https://core.telegram.org/bots/webapps#webappinitdata) object. This method does not perform any validation or authenticity checks. Use it only if you have already verified the data with `validateInitData` or `validateAndParseInitData`.
+
+```ts
+import { parseInitData } from "@gramio/init-data";
+
+const initData = req.headers["x-init-data"] as string;
+const parsed = parseInitData(initData);
+
+// Access user and chat data
+const userId = parsed.user?.id;
+const chatId = parsed.chat?.id;
+```
+
+# signInitData
+
+Generates a valid init data string from a data object and a secret key or bot token. This is useful for testing, documentation, or generating example values for API clients.
+
+```ts
+import {
+    signInitData,
+    getBotTokenSecretKey,
+    type WebAppUser,
+} from "@gramio/init-data";
+
+const botToken = process.env.BOT_TOKEN as string;
+const secretKey = getBotTokenSecretKey(botToken);
+
+const data = {
+    user: {
+        id: 1,
+        first_name: "durov",
+        username: "durov",
+    },
+} satisfies WebAppUser;
+
+const signedInitData = signInitData(data, secretKey);
+// Use signedInitData as a valid init data string for testing
+```
 
-This example shows how to integrate `@gramio/init-data` with Elysia via convenient plugin with type safety.
+# Example: Elysia integration
 
-`examples` at `x-init-data` header is valid generated init-data which allows you to more easily test your API in OpenAPI Client.
+You can use `@gramio/init-data` in any backend framework. Here is a bonus example of integrating it with Elysia for type-safe authentication:
 
-```ts twoslash
+```ts
+twoslash;
 import {
     validateAndParseInitData,
     signInitData,
@@ -84,6 +189,6 @@ const app = new Elysia()
     .use(authElysia)
     .get("/user", ({ user }) => {
         user;
-        // ^?
+        //  ^?
     });
 ```