@grom.js/bot-api-spec 0.4.1 → 0.6.0

package/README.md

@@ -1,21 +1,93 @@
+[![bot-api](https://img.shields.io/badge/v9.3-000?style=flat&logo=telegram&logoColor=%2325A3E1&label=Bot%20API&labelColor=%23000&color=%2325A3E1)][bot-api]
+[![npm](https://img.shields.io/npm/v/%40grom.js%2Fbot-api-spec?style=flat&logo=npm&logoColor=%23BB443E&logoSize=auto&label=%C2%A0&labelColor=%23fff&color=%23BB443E)](https://www.npmjs.com/package/@grom.js/tgx)
+[![jsr](https://img.shields.io/jsr/v/%40grom/bot-api-spec?style=flat&logo=jsr&logoColor=%231B3646&logoSize=auto&label=%C2%A0&labelColor=%23F3E051&color=%231B3646)](https://jsr.io/@grom/tgx)
+
 [Telegram Bot API](https://core.telegram.org/bots/api) specification as a collection of JavaScript objects in a [custom format](#format).
 
 ## Motivation
 
 Automatically generate tools, libraries, MCP servers, custom documentations, etc.
 
+## Installation
+
+```sh
+# Using npm
+npm install @grom.js/bot-api-spec
+
+# Using JSR
+deno add jsr:@grom/bot-api-spec
+```
+
 ## Usage
 
+Root module exports two objects:
+
+1. `types` — definition of all Bot API types
+2. `methods` — definition of all Bot API methods
+
 ```ts
-import { types, methods } from '@grom.js/bot-api-spec'
+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(types)   // { Update: <definition of Update>, ... }
-console.log(methods) // { getUpdates: <definition of getUpdates>, ... }
+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
 
-See [./src/types.ts](./src/types.ts)
+Refer to the [./src/format.ts](./src/format.ts) module for reference.
+
+You can also import types in your code:
+
+```ts
+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
 
@@ -36,9 +108,13 @@ Below are the rules how we map type of a field/parameter to the `ValueType`:
 
 ### Descriptions
 
-Objects also include descriptions of the API types, methods, fields, and parameters, with the following remarks:
+All definitions of types, methods, fields, and parameters include their descriptions.
+
+Descriptions are copied verbatim from the official [Bot API documentation][bot-api], 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](https://core.telegram.org/tdlib/docs/td__api_8h.html#a6f57ab89c6371535f0fb7fec2d770126)).
 
-- 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](https://core.telegram.org/tdlib/docs/td__api_8h.html#a6f57ab89c6371535f0fb7fec2d770126)).
+[bot-api]: https://core.telegram.org/bots/api

package/dist/format.d.ts

@@ -0,0 +1,149 @@
+import type { types } from './types.gen.ts';
+/**
+ * Type defined in the API. It can either be an {@link ApiTypeObject object}
+ * or a {@link ApiTypeOneOf union}.
+ */
+export type ApiType = ApiTypeObject | ApiTypeOneOf;
+export interface ApiTypeObject {
+    /**
+     * Name of the type.
+     */
+    name: string;
+    /**
+     * Description of the type.
+     */
+    description: Description;
+    /**
+     * Fields of the object representing this type.
+     */
+    fields: Array<FieldOrParam>;
+    oneOf?: never;
+}
+export interface ApiTypeOneOf {
+    /**
+     * Name of the type.
+     */
+    name: string;
+    /**
+     * Description of the type.
+     */
+    description: Description;
+    /**
+     * Array of possible types this type can be.
+     */
+    oneOf: Array<ValueTypeApiType>;
+    fields?: never;
+}
+export interface ApiMethod {
+    /**
+     * Name of the method.
+     */
+    name: string;
+    /**
+     * Description of the method.
+     */
+    description: Description;
+    /**
+     * Parameters this method takes.
+     */
+    parameters: Array<FieldOrParam>;
+    /**
+     * Type of the value this method returns.
+     */
+    returnType: ValueType;
+}
+export interface FieldOrParam {
+    /**
+     * Name of the field/parameter.
+     */
+    name: string;
+    /**
+     * Type of the value this field/parameter can be assigned.
+     */
+    type: ValueType;
+    /**
+     * Whether this is a required field/parameter.
+     */
+    required: boolean;
+    /**
+     * Description of the field/parameter.
+     */
+    description: Description;
+    /**
+     * Whether this field/parameter should be JSON-serialized.
+     */
+    jsonSerialized: boolean;
+}
+/**
+ * Description of a type/method/field/parameter.
+ */
+export interface Description {
+    markdown: string;
+}
+/**
+ * Type of a value.
+ */
+export type ValueType = ValueTypeString | ValueTypeBoolean | ValueTypeInteger32 | ValueTypeInteger53 | ValueTypeFloat | ValueTypeInputFile | ValueTypeApiType | ValueTypeArray | ValueTypeUnion;
+/**
+ * `String` value type.
+ */
+export interface ValueTypeString {
+    type: 'str';
+    literal?: string;
+}
+/**
+ * `Boolean` value type.
+ */
+export interface ValueTypeBoolean {
+    type: 'bool';
+    literal?: boolean;
+}
+/**
+ * `Integer` value type, which fits in a 32-bit integer.
+ */
+export interface ValueTypeInteger32 {
+    type: 'int32';
+    literal?: number;
+}
+/**
+ * `Integer` value type, which may have more than 32 significant bits, but has
+ * at most 52 significant bits, so a 64-bit integer or double-precision float
+ * type are safe for storing values of this type.
+ */
+export interface ValueTypeInteger53 {
+    type: 'int53';
+}
+/**
+ * `Float` value type.
+ */
+export interface ValueTypeFloat {
+    type: 'float';
+}
+/**
+ * [`InputFile`](https://core.telegram.org/bots/api#inputfile) value type.
+ */
+export interface ValueTypeInputFile {
+    type: 'input-file';
+}
+/**
+ * Any {@link ApiType} value type.
+ */
+export interface ValueTypeApiType {
+    type: 'api-type';
+    name: keyof typeof types;
+}
+/**
+ * Array of any value type.
+ */
+export interface ValueTypeArray {
+    type: 'array';
+    of: ValueType;
+}
+/**
+ * Union of any value types.
+ */
+export interface ValueTypeUnion {
+    type: 'union';
+    types: Array<ValueType>;
+}
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAE3C;;;GAGG;AACH,MAAM,MAAM,OAAO,GACb,aAAa,GACb,YAAY,CAAA;AAElB,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IAExB;;OAEG;IACH,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,CAAA;IAE3B,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAED,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IAExB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAA;IAE9B,MAAM,CAAC,EAAE,KAAK,CAAA;CACf;AAED,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IAExB;;OAEG;IACH,UAAU,EAAE,KAAK,CAAC,YAAY,CAAC,CAAA;IAE/B;;OAEG;IACH,UAAU,EAAE,SAAS,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,IAAI,EAAE,SAAS,CAAA;IAEf;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAA;IAEjB;;OAEG;IACH,WAAW,EAAE,WAAW,CAAA;IAExB;;OAEG;IACH,cAAc,EAAE,OAAO,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GACf,eAAe,GACf,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,cAAc,GACd,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,GACd,cAAc,CAAA;AAEpB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,YAAY,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,CAAA;IAChB,IAAI,EAAE,MAAM,OAAO,KAAK,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAA;IACb,EAAE,EAAE,SAAS,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;CACxB"}

package/dist/format.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":""}