Telegram Bot API specification as a collection of JavaScript objects in a custom format.

Motivation

Automatically generate tools, libraries, MCP servers, custom documentations, etc.

Usage

import { types, methods } from '@grom.js/bot-api-spec'

console.log(types)   // { Update: <definition of Update>, ... }
console.log(methods) // { getUpdates: <definition of getUpdates>, ... }

Format

See ./src/types.ts

Value Types

We define custom value types to represent types of the fields and parameters, to allow generating more flexible and user-friendly code.

Below are the rules how we map type of a field/parameter to the ValueType:

• Type is String — { type: 'str' }
• Type is Integer — { type: 'int32' }
• Type is Integer and Description says "...may have more than 32 significant bits...but it has at most 52 significant bits..." — { type: 'int53' }
• Type is Boolean — { type: 'bool' }
• Type is True — { type: 'bool', literal: true }
• Type is Float — { type: 'float' }
• Type is InputFile — { type: 'input-file' }
• Type is X, where X is any API type — { type: 'api-type', name: X }
• Type is Array of X — { type: 'array', of: X }
• Type is X or Y or ... — { type: 'union', types: [X, Y, ...] }

Descriptions

Objects also include descriptions of the API types, methods, fields, and parameters, with the following remarks:

• Description is an object with a single markdown property, a string containing the description in Markdown format with formatting (bold, italic, etc.) and links preserved.
• "Optional." prefix in field descriptions is omitted; instead, the required property is set to false for such fields.
• "JSON-serialized..." in field/parameter descriptions is omitted; instead, the jsonSerialized property is set to true for such fields/parameters.
• "...may have more than 32 significant bits...but it has at most 52 significant bits..." in Integer field/parameter descriptions is omitted; instead, type is set to int53 for such fields/parameters (as per TDLib).