@tma.js/init-data 0.2.21 → 4.0.0-rc.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Vladislav Kibenko
+Copyright (c) 2025 Vladislav Kibenko
 
 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,28 +1,124 @@
 # @tma.js/init-data
 
-[code-link]: https://github.com/Telegram-Mini-Apps/tma.js/tree/master/packages/init-data
+Parse, validate and sign Telegram Mini Apps
+[init data](https://docs.telegram-mini-apps.com/platform/init-data) on the server. Built on
+Web Crypto, so it works in Node.js 20+, Bun, Deno, Cloudflare Workers and other modern runtimes.
 
-[code-badge]: https://img.shields.io/badge/source-black?logo=github
+```bash
+pnpm i @tma.js/init-data
+```
 
-[docs-link]: https://docs.telegram-mini-apps.com/packages/typescript/tma-js-init-data/about
+## Validating
 
-[docs-badge]: https://img.shields.io/badge/documentation-blue?logo=gitbook&logoColor=white
+`validate` checks the init data signature and expiration, and returns the parsed init data:
 
-[npm-link]: https://npmjs.com/package/@tma.js/init-data
+```ts
+import { validate } from '@tma.js/init-data';
 
-[npm-badge]: https://img.shields.io/npm/v/@tma.js/init-data?logo=npm
+// Raw init data sent by the client, e.g. in the Authorization header.
+const initData = await validate(rawInitData, botToken);
+console.log(initData.user?.id, initData.auth_date);
+```
 
-[size-badge]: https://img.shields.io/bundlephobia/minzip/@tma.js/init-data
+It throws `SignatureMissingError`, `AuthDateInvalidError`, `ExpiredError`,
+`SignatureInvalidError` or `InvalidInitDataError` if init data is invalid. Use `isValid` to get
+a boolean instead.
 
+### Handling errors
 
-[![npm-badge]][npm-link]
-![size-badge]
-[![docs-badge]][docs-link]
-[![code-badge]][code-link]
+Each throwing function has a `safe` counterpart returning the error instead of throwing it.
+The error type is a union of all possible errors, so the compiler knows what to handle:
 
-Package providing utilities connected with Telegram Mini Apps init data. It
-allows init data parsing, works in browser only.
+```ts
+import { matchError, safeValidate } from '@tma.js/init-data';
 
-This library is a part of TypeScript packages ecosystem around Telegram Web
-Apps. You can learn more about this package in this
-[documentation][docs-link].
+const result = await safeValidate(rawInitData, botToken);
+if (!result.ok) {
+  // Compilation fails if any error is left unhandled.
+  return matchError(result.error, {
+    SignatureMissingError: () => reply(401, 'Init data is not signed'),
+    AuthDateInvalidError: () => reply(401, 'Init data has no valid auth date'),
+    ExpiredError: () => reply(401, 'Init data has expired'),
+    SignatureInvalidError: () => reply(403, 'Init data signature is invalid'),
+    InvalidInitDataError: () => reply(400, 'Init data has an unexpected structure'),
+  });
+}
+const initData = result.data;
+```
+
+Each error class also has the `is` method to check a single error: `ExpiredError.is(result.error)`.
+The `ValidateError` type is the union of all validation errors.
+
+Safe functions return only expected errors. Unexpected ones, like a broken Web Crypto
+implementation, are still thrown.
+
+Init data expires in 1 day by default. Change it with the `expiresIn` option (in seconds), or
+pass `0` to skip the check:
+
+```ts
+await validate(rawInitData, botToken, { expiresIn: 3600 });
+```
+
+### Secret key
+
+Each call derives a key from the bot token. To do it once, create a secret key and pass it
+instead of the token:
+
+```ts
+import { createSecretKey, validate } from '@tma.js/init-data';
+
+const secretKey = await createSecretKey(botToken);
+await validate(rawInitData, secretKey);
+```
+
+If the server only validates init data, it doesn't need the bot token at all. Store its hash
+created with `hashToken` instead:
+
+```ts
+import { createSecretKey, hashToken } from '@tma.js/init-data';
+
+await hashToken(botToken); // Run once, store the result.
+const secretKey = await createSecretKey(process.env.BOT_TOKEN_HASH!, { hashed: true });
+```
+
+### Third-party validation
+
+Init data of another bot can be validated without its token, using the Telegram public key:
+
+```ts
+import { validate3rd } from '@tma.js/init-data';
+
+const initData = await validate3rd(rawInitData, botId);
+// Or safeValidate3rd to get the error instead of throwing it.
+// Init data from the Telegram test environment.
+await validate3rd(rawInitData, botId, { test: true });
+```
+
+## Parsing
+
+`parse` reads init data without checking its signature. It throws `InvalidInitDataError` if the
+value has an unexpected structure. `safeParse` returns this error instead.
+
+```ts
+import { parse, serialize } from '@tma.js/init-data';
+
+const initData = parse(rawInitData);
+serialize(initData); // Back to the query format.
+```
+
+## Signing
+
+`sign` creates init data signed with the bot token. It is useful to test the server or to mock
+the Telegram environment:
+
+```ts
+import { sign } from '@tma.js/init-data';
+
+const rawInitData = await sign({
+  user: { id: 1, first_name: 'Pavel' },
+  // Defaults to the current date.
+  auth_date: new Date(),
+}, botToken);
+```
+
+Use `signData` to sign an arbitrary data-check-string.

package/dist/dts/errors.d.ts

@@ -0,0 +1,41 @@
+declare const InvalidInitDataError_base: import('error-kid').ErrorClassWithData<[_value: string, cause?: unknown], {
+    value: string;
+}, "InvalidInitDataError">;
+/**
+ * Thrown when a value doesn't represent valid init data.
+ */
+export declare class InvalidInitDataError extends /* @__PURE__ */ InvalidInitDataError_base {
+}
+declare const SignatureMissingError_base: import('error-kid').ErrorClassWithData<[param: "hash" | "signature"], {
+    param: "hash" | "signature";
+}, "SignatureMissingError">;
+/**
+ * Thrown when init data has no parameter containing its signature.
+ */
+export declare class SignatureMissingError extends /* @__PURE__ */ SignatureMissingError_base {
+}
+declare const SignatureInvalidError_base: import('error-kid').ErrorClass<[], "SignatureInvalidError">;
+/**
+ * Thrown when init data signature doesn't match its content.
+ */
+export declare class SignatureInvalidError extends /* @__PURE__ */ SignatureInvalidError_base {
+}
+declare const AuthDateInvalidError_base: import('error-kid').ErrorClassWithData<[value?: string | undefined], {
+    value: string | undefined;
+}, "AuthDateInvalidError">;
+/**
+ * Thrown when the `auth_date` init data parameter is missing or isn't a Unix time.
+ */
+export declare class AuthDateInvalidError extends /* @__PURE__ */ AuthDateInvalidError_base {
+}
+declare const ExpiredError_base: import('error-kid').ErrorClassWithData<[issuedAt: Date, expiresAt: Date, now: Date], {
+    issuedAt: Date;
+    expiresAt: Date;
+    now: Date;
+}, "ExpiredError">;
+/**
+ * Thrown when init data has expired.
+ */
+export declare class ExpiredError extends /* @__PURE__ */ ExpiredError_base {
+}
+export {};

package/dist/dts/index.d.ts

@@ -1,6 +1,7 @@
-export * from './chat.js';
-export * from './initData.js';
-export * from './parse.js';
-export * from './serialize.js';
-export * from './types.js';
-export * from './user.js';
+export { matchError } from 'error-kid';
+export { AuthDateInvalidError, ExpiredError, InvalidInitDataError, SignatureInvalidError, SignatureMissingError, } from './errors.js';
+export { parse, safeParse, serialize } from './parsing.js';
+export type { Result } from './result.js';
+export { createSecretKey, hashToken, sign, signData, type Secret, type SignableInitData, } from './signing.js';
+export { isValid, isValid3rd, safeValidate, safeValidate3rd, validate, validate3rd, type Validate3rdOptions, type ValidateError, type ValidateOptions, } from './validation.js';
+export type * from './types.js';

package/dist/dts/parsing.d.ts

@@ -0,0 +1,25 @@
+import { InvalidInitDataError } from './errors.js';
+import { Result } from './result.js';
+import { InitData } from './types.js';
+/**
+ * Parses init data from its query representation. The function doesn't check the init data
+ * signature, use `safeValidate` for that.
+ * @param value - init data query.
+ * @returns Parsed init data, or `InvalidInitDataError` if the value doesn't represent valid
+ * init data.
+ */
+export declare function safeParse(value: string | URLSearchParams): Result<InvalidInitDataError, InitData>;
+/**
+ * Parses init data from its query representation. The function doesn't check the init data
+ * signature, use `validate` for that.
+ *
+ * Throwing version of `safeParse`.
+ * @param value - init data query.
+ * @throws {InvalidInitDataError} The value doesn't represent valid init data.
+ */
+export declare const parse: (value: string | URLSearchParams) => InitData;
+/**
+ * Converts init data to its query representation.
+ * @param value - init data.
+ */
+export declare function serialize(value: Partial<InitData>): string;

package/dist/dts/result.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Result of an operation which can fail with one of the known errors. Unlike a thrown error,
+ * the error type here is checked by the compiler.
+ */
+export type Result<E, T> = {
+    ok: false;
+    error: E;
+} | {
+    ok: true;
+    data: T;
+};
+/**
+ * @returns A successful result.
+ * @param data - result data.
+ */
+export declare function ok<T>(data: T): {
+    ok: true;
+    data: T;
+};
+/**
+ * @returns A failed result.
+ * @param error - result error.
+ */
+export declare function err<E>(error: E): {
+    ok: false;
+    error: E;
+};
+/**
+ * @returns Result data.
+ * @param result - result to unwrap.
+ * @throws The result error, if the result is failed.
+ */
+export declare function unwrap<E extends Error, T>(result: Result<E, T>): T;
+/**
+ * Creates a throwing version of a function returning a result. The created function accepts
+ * the same arguments and returns the result data, or throws the result error.
+ *
+ * Generic functions lose their type parameters when wrapped, so write their throwing versions
+ * manually using `unwrap`.
+ * @param fn - function returning a result, or a promise of it.
+ * @example
+ * export const createStartParam = throwing(safeCreateStartParam);
+ */
+export declare function throwing<A extends unknown[], E extends Error, T>(fn: (...args: A) => Promise<Result<E, T>>): (...args: A) => Promise<T>;
+export declare function throwing<A extends unknown[], E extends Error, T>(fn: (...args: A) => Result<E, T>): (...args: A) => T;

package/dist/dts/signing.d.ts

@@ -0,0 +1,54 @@
+import { InitData } from './types.js';
+/**
+ * Bot token, or a secret key created with `createSecretKey`.
+ */
+export type Secret = string | CryptoKey;
+/**
+ * Init data to sign. If `auth_date` is omitted, the current date is used.
+ */
+export type SignableInitData = Omit<InitData, 'auth_date' | 'hash'> & {
+    auth_date?: Date;
+};
+export declare function bytesToHex(bytes: ArrayBuffer): string;
+export declare function hexToBytes(hex: string): Uint8Array<ArrayBuffer>;
+/**
+ * @returns Data-check-string of the init data parameters: `key=value` pairs sorted
+ * alphabetically and separated by line feeds.
+ * @param pairs - init data parameters.
+ */
+export declare function createDataCheckString(pairs: [key: string, value: string][]): string;
+/**
+ * Hashes the bot token the way Telegram does to sign init data. Store the result instead of
+ * the bot token if the server only needs to validate init data, and pass it to
+ * `createSecretKey` with the `hashed` option.
+ * @param token - bot token.
+ * @returns HMAC-SHA-256 of the bot token keyed with `WebAppData`, in the hex format.
+ */
+export declare function hashToken(token: string): Promise<string>;
+/**
+ * Creates a key used to sign and validate init data. Create it once and reuse to avoid
+ * hashing the bot token on each call.
+ * @param token - bot token, or its hash created with `hashToken` if `hashed` is true.
+ * @param options - additional options.
+ * @throws {TypeError} The token is marked as hashed but isn't a SHA-256 hash in the hex format.
+ */
+export declare function createSecretKey(token: string, options?: {
+    hashed?: boolean;
+}): Promise<CryptoKey>;
+export declare function toSecretKey(secret: Secret): Promise<CryptoKey>;
+/**
+ * Signs data the way Telegram signs init data.
+ * @param data - data to sign, usually a data-check-string.
+ * @param secret - bot token or a secret key.
+ * @returns Signature in the hex format.
+ */
+export declare function signData(data: string, secret: Secret): Promise<string>;
+/**
+ * Signs init data. Useful to test the server or to mock the Telegram environment.
+ * @param data - init data to sign.
+ * @param secret - bot token or a secret key.
+ * @returns Signed init data in the query format.
+ * @example
+ * const initData = await sign({ user: { id: 1, first_name: 'Pavel' } }, botToken);
+ */
+export declare function sign(data: SignableInitData, secret: Secret): Promise<string>;

package/dist/dts/types.d.ts

@@ -1,133 +1,141 @@
 /**
- * Known type of chat.
+ * Type of the chat from which the mini app was opened.
  */
 export type ChatType = 'sender' | 'private' | 'group' | 'supergroup' | 'channel' | string;
 /**
- * Describes Telegram Mini Apps [User](https://docs.telegram-mini-apps.com/launch-parameters/init-data#user) type.
+ * @see https://core.telegram.org/bots/webapps#webappuser
  */
 export interface User {
     /**
-     * True, if this user added the bot to the attachment menu.
+     * True if the user added the bot to the attachment menu.
      */
-    addedToAttachmentMenu?: boolean;
+    added_to_attachment_menu?: boolean;
     /**
-     * True, if this user allowed the bot to message them.
+     * True if the user allowed the bot to message them.
      */
-    allowsWriteToPm?: boolean;
+    allows_write_to_pm?: boolean;
     /**
      * First name of the user or bot.
      */
-    firstName: string;
+    first_name: string;
     /**
-     * A unique identifier for the user or bot.
+     * Unique identifier of the user or bot.
      */
     id: number;
     /**
-     * True, if this user is a bot. Returned in the `receiver` field only.
-     * @see InitData.receiver
+     * True if the user is a bot. Returned in the `receiver` field only.
      */
-    isBot?: boolean;
+    is_bot?: boolean;
     /**
-     * True, if this user is a Telegram Premium user.
+     * True if the user has Telegram Premium.
      */
-    isPremium?: boolean;
+    is_premium?: boolean;
     /**
-     * Last name of the user or bot.
+     * [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) of the user's
+     * language. Returned in the `user` field only.
      */
-    lastName?: string;
+    language_code?: string;
     /**
-     * [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) of the user's language.
-     * Returns in user field only.
+     * Last name of the user or bot.
      */
-    languageCode?: string;
+    last_name?: string;
     /**
-     * URL of the user’s profile photo. The photo can be in .jpeg or .svg
-     * formats. Only returned for Mini Apps launched from the attachment menu.
+     * URL of the user's profile photo in the .jpeg or .svg format.
      */
-    photoUrl?: string;
+    photo_url?: string;
     /**
      * Username of the user or bot.
      */
     username?: string;
 }
 /**
- * Describes Telegram Mini Apps [Chat](https://docs.telegram-mini-apps.com/launch-parameters/init-data#chat) type.
+ * @see https://core.telegram.org/bots/webapps#webappchat
  */
 export interface Chat {
     /**
-     * Unique identifier for this chat.
+     * Unique identifier of the chat.
      */
     id: number;
     /**
-     * URL of the chat’s photo. The photo can be in .jpeg or .svg formats.
-     * Only returned for Mini Apps launched from the attachment menu.
-     */
-    photoUrl?: string;
-    /**
-     * Type of chat.
+     * URL of the chat's photo in the .jpeg or .svg format. Returned only for mini apps launched
+     * from the attachment menu.
      */
-    type: 'group' | 'supergroup' | 'channel' | string;
+    photo_url?: string;
     /**
      * Title of the chat.
      */
     title: string;
+    /**
+     * Type of the chat.
+     */
+    type: 'group' | 'supergroup' | 'channel' | string;
     /**
      * Username of the chat.
      */
     username?: string;
 }
 /**
- * Describes Telegram Mini Apps [InitData](https://docs.telegram-mini-apps.com/launch-parameters/init-data#parameters-list)
- * type.
+ * Init data passed by the Telegram client to the mini app.
+ * @see https://core.telegram.org/bots/webapps#webappinitdata
+ * @see https://docs.telegram-mini-apps.com/platform/init-data
  */
 export interface InitData {
     /**
-     * Init data generation date.
+     * Date when the init data was created.
      */
-    authDate: Date;
+    auth_date: Date;
     /**
-     * The number of seconds after which a message can be sent via the method [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery).
+     * Number of seconds after which a message can be sent via the
+     * [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
      */
-    canSendAfter?: number;
+    can_send_after?: number;
     /**
-     * An object containing data about the chat where the bot was launched via
-     * the attachment menu. Returned for supergroups, channels and group
-     * chats – only for Mini Apps launched via the attachment menu.
+     * Chat where the bot was launched via the attachment menu, or the chat of the processed join
+     * request. Returned for supergroups, channels and group chats.
      */
     chat?: Chat;
     /**
-     * The type of chat from which Mini App was opened.
+     * Global identifier of the chat from which the mini app was opened. Returned only for mini
+     * apps opened by a direct link.
+     */
+    chat_instance?: string;
+    /**
+     * Unique identifier for processing a chat join request via the
+     * [answerChatJoinRequestQuery](https://core.telegram.org/bots/api#answerchatjoinrequestquery)
+     * method.
      */
-    chatType?: ChatType;
+    chat_join_request_query_id?: string;
     /**
-     * A global identifier indicating the chat from which Mini App was
-     * opened. Returned only for applications opened by direct link.
+     * Type of the chat from which the mini app was opened. Returned only for mini apps opened by
+     * a direct link.
      */
-    chatInstance?: string;
+    chat_type?: ChatType;
     /**
-     * A hash of all passed parameters, which the bot server can use to
-     * check their [validity](https://core.telegram.org/bots/webapps#validating-data-received-via-the-web-app).
+     * Init data hash used to validate it with the bot token.
+     * @see https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
      */
     hash: string;
     /**
-     * A unique identifier for the Mini App session, required for sending
-     * messages via the [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
+     * Unique identifier of the mini app session, required for sending messages via the
+     * [answerWebAppQuery](https://core.telegram.org/bots/api#answerwebappquery) method.
      */
-    queryId?: string;
+    query_id?: string;
     /**
-     * An object containing data about the chat partner of the current user in
-     * the chat where the bot was launched via the attachment menu.
-     * Returned only for private chats and only for Mini Apps launched
-     * via the attachment menu.
+     * Chat partner of the current user in the chat where the bot was launched via the attachment
+     * menu. Returned only for private chats.
      */
     receiver?: User;
     /**
-     * The value of the `startattach` parameter, passed via link. Only returned for
-     * Mini Apps when launched from the attachment menu via link.
+     * Init data signature used to validate it without the bot token.
+     * @see https://core.telegram.org/bots/webapps#validating-data-for-third-party-use
+     */
+    signature?: string;
+    /**
+     * Value of the `startattach` or `startapp` parameter passed in the link.
      */
-    startParam?: string;
+    start_param?: string;
     /**
-     * An object containing data about the current user.
+     * Current user.
      */
     user?: User;
 }

package/dist/dts/validation.d.ts

@@ -0,0 +1,110 @@
+import { AuthDateInvalidError, ExpiredError, SignatureInvalidError, InvalidInitDataError, SignatureMissingError } from './errors.js';
+import { Result } from './result.js';
+import { Secret } from './signing.js';
+import { InitData } from './types.js';
+export interface ValidateOptions {
+    /**
+     * Time in seconds during which init data is considered valid after it was created. Pass `0`
+     * to skip the expiration check.
+     * @default 86400 (1 day)
+     */
+    expiresIn?: number;
+}
+export interface Validate3rdOptions extends ValidateOptions {
+    /**
+     * True if init data was created in the Telegram test environment.
+     * @default false
+     */
+    test?: boolean;
+}
+/**
+ * Error returned when init data is invalid.
+ */
+export type ValidateError = SignatureMissingError | AuthDateInvalidError | ExpiredError | SignatureInvalidError | InvalidInitDataError;
+/**
+ * Validates init data using the bot token and parses it.
+ * @param value - init data query.
+ * @param secret - bot token or a secret key created with `createSecretKey`.
+ * @param options - additional options.
+ * @returns Parsed init data, or one of the errors:
+ * - `SignatureMissingError`: the `hash` parameter is missing;
+ * - `AuthDateInvalidError`: the `auth_date` parameter is missing or invalid;
+ * - `ExpiredError`: init data has expired;
+ * - `SignatureInvalidError`: init data wasn't signed with the specified bot token;
+ * - `InvalidInitDataError`: init data is signed, but has an unexpected structure.
+ * @see https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
+ * @example
+ * const result = await safeValidate(rawInitData, botToken);
+ * if (!result.ok) {
+ *   return matchError(result.error, {
+ *     ExpiredError: () => reply(401, 'Init data has expired'),
+ *     ...
+ *   });
+ * }
+ * const initData = result.data;
+ */
+export declare function safeValidate(value: string | URLSearchParams, secret: Secret, options?: ValidateOptions): Promise<Result<ValidateError, InitData>>;
+/**
+ * Validates init data using the bot token and parses it.
+ *
+ * Throwing version of `safeValidate`.
+ * @param value - init data query.
+ * @param secret - bot token or a secret key created with `createSecretKey`.
+ * @param options - additional options.
+ * @returns Parsed init data.
+ * @throws {SignatureMissingError} The `hash` parameter is missing.
+ * @throws {AuthDateInvalidError} The `auth_date` parameter is missing or invalid.
+ * @throws {ExpiredError} Init data has expired.
+ * @throws {SignatureInvalidError} Init data wasn't signed with the specified bot token.
+ * @throws {InvalidInitDataError} Init data is signed, but has an unexpected structure.
+ * @see https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app
+ * @example
+ * const initData = await validate(rawInitData, botToken);
+ */
+export declare const validate: (value: string | URLSearchParams, secret: Secret, options?: ValidateOptions | undefined) => Promise<InitData>;
+/**
+ * @returns True if init data is signed with the bot token and hasn't expired.
+ * @param value - init data query.
+ * @param secret - bot token or a secret key created with `createSecretKey`.
+ * @param options - additional options.
+ */
+export declare function isValid(value: string | URLSearchParams, secret: Secret, options?: ValidateOptions): Promise<boolean>;
+/**
+ * Validates init data without the bot token, using the Telegram public key, and parses it.
+ * Useful for third parties receiving init data of another bot.
+ * @param value - init data query.
+ * @param botId - identifier of the bot the init data was issued for.
+ * @param options - additional options.
+ * @returns Parsed init data, or one of the errors:
+ * - `SignatureMissingError`: the `signature` parameter is missing;
+ * - `AuthDateInvalidError`: the `auth_date` parameter is missing or invalid;
+ * - `ExpiredError`: init data has expired;
+ * - `SignatureInvalidError`: init data wasn't signed by Telegram for the specified bot;
+ * - `InvalidInitDataError`: init data is signed, but has an unexpected structure.
+ * @see https://core.telegram.org/bots/webapps#validating-data-for-third-party-use
+ */
+export declare function safeValidate3rd(value: string | URLSearchParams, botId: number, options?: Validate3rdOptions): Promise<Result<ValidateError, InitData>>;
+/**
+ * Validates init data without the bot token, using the Telegram public key, and parses it.
+ * Useful for third parties receiving init data of another bot.
+ *
+ * Throwing version of `safeValidate3rd`.
+ * @param value - init data query.
+ * @param botId - identifier of the bot the init data was issued for.
+ * @param options - additional options.
+ * @returns Parsed init data.
+ * @throws {SignatureMissingError} The `signature` parameter is missing.
+ * @throws {AuthDateInvalidError} The `auth_date` parameter is missing or invalid.
+ * @throws {ExpiredError} Init data has expired.
+ * @throws {SignatureInvalidError} Init data wasn't signed by Telegram for the specified bot.
+ * @throws {InvalidInitDataError} Init data is signed, but has an unexpected structure.
+ * @see https://core.telegram.org/bots/webapps#validating-data-for-third-party-use
+ */
+export declare const validate3rd: (value: string | URLSearchParams, botId: number, options?: Validate3rdOptions | undefined) => Promise<InitData>;
+/**
+ * @returns True if init data is signed by Telegram for the specified bot and hasn't expired.
+ * @param value - init data query.
+ * @param botId - identifier of the bot the init data was issued for.
+ * @param options - additional options.
+ */
+export declare function isValid3rd(value: string | URLSearchParams, botId: number, options?: Validate3rdOptions): Promise<boolean>;