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

Motivation

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

Installation

# Using npm
npm install @grom.js/bot-api-spec
# Using JSR
deno add jsr:@grom/bot-api-spec

Usage

Root module exports two objects: types and methods, containing definitions of all Bot API types and methods respectively.

import{types,methods}from'@grom.js/bot-api-spec'// '@grom/bot-api-spec' for JSRconsole.log(types)// {// Update: {// name: 'Update',// description: { markdown: '...' },// fields: [// {// name: 'update_id',// type: { type: 'int32' },// description: { markdown: '...' },// required: true,// },// ...// ],// },// ...// }console.log(methods)// {// getUpdates: {// name: 'getUpdates',// description: { markdown: '...' },// parameters: [// {// name: 'offset',// type: { type: 'int32' },// description: { markdown: '...' },// required: false,// },// ...// ],// returnType: {// type: 'array',// of: {// type: 'api-type',// name: 'Update',// },// },// },// ...// }

Format

Refer to the ./src/format.ts module for reference.

You can also import types in your code:

importtype{ValueType}from'@grom.js/bot-api-spec/format'// '@grom/bot-api-spec/format' for JSRfunctiongenerateCode(valueType: ValueType): string{if(valueType.type==='str'){return'string'}// ...}

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

All definitions of types, methods, fields, and parameters include their descriptions.

Descriptions are copied verbatim from the official Bot API documentation, with the following modifications:

• Description HTML is parsed and converted to Markdown.
• The "Optional." prefix is omitted from field descriptions. Instead, the required property is set to false for such fields.
• "JSON-serialized..." portions are omitted from field/parameter descriptions.
• "...may have more than 32 significant bits...but it has at most 52 significant bits..." portions are omitted from Integer field/parameter descriptions. Instead, the type is set to int53 for such fields/parameters (as per TDLib).

Development

The spec is generated from the Bot API documentation into src/*.gen.ts, which are committed and never edited by hand.

pnpm gen:fetch # refresh spec/upstream/ from the documentation
pnpm gen:check # report what needs a decision
pnpm gen:build # spec/ -> src/*.gen.ts

spec/upstream/ is a verbatim snapshot of the documentation, so reviewing its diff is how upstream changes are reviewed. spec/overrides/ holds the hand-written corrections applied on top of it. See AGENTS.md.