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 JSR

console.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:

import type { ValueType } from '@grom.js/bot-api-spec/format' // '@grom/bot-api-spec/format' for JSR

function generateCode(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).