Max IO

https://github.com/xtcry/max-io
Admin
TypeScript framework for developing bots in the Max messenger with middleware runtime, typed...
Tokens:13,434
Snippets:157
Trust Score:9.3
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Copy Example

Source: https://github.com/xtcry/max-io/blob/main/examples/02-chat-admin-management/README.md

Install project dependencies and copy the environment example file. This is a prerequisite for running the provided commands.

```bash
yarn install
cp .env.example .env
```

--------------------------------

### Project Setup and Execution Commands

Source: https://github.com/xtcry/max-io/blob/main/examples/04-sessions-scenes-i18n/README.md

Install dependencies, run type checking, and start the bot using these commands.

```bash
yarn install
yarn typecheck
yarn start
```

--------------------------------

### Create a Basic Bot

Source: https://github.com/xtcry/max-io/blob/main/README.md

Set up a basic bot using Max IO. Ensure the MAX_BOT_TOKEN environment variable is set. This example demonstrates handling 'start' and 'echo' commands, and inline keyboard callbacks.

```typescript
import 'dotenv/config';

import { Bot, Keyboard } from 'max-io';

const bot = new Bot(process.env.MAX_BOT_TOKEN!);

bot.command('start', async (ctx) => {
  await ctx.reply('Привет! Я бот на Max IO.', {
    attachments: [
      Keyboard.inlineKeyboard([
        [Keyboard.button.callback('Проверить callback', 'demo:callback')],
      ]),
    ],
  });
});

bot.command('echo', async (ctx) => {
  const text = ctx.payload || 'Напиши /echo любой текст';
  await ctx.reply(text);
});

bot.action('demo:callback', async (ctx) => {
  await ctx.answerOnCallback({ notification: 'Callback получен' });
});

bot.start().then();
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/xtcry/max-io/blob/main/CONTRIBUTING.md

Run this command to install all necessary dependencies for the project.

```bash
yarn install
```

--------------------------------

### Built-in Webhook Server

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

This example demonstrates how to start the max-io bot with a built-in webhook server. The `webhook` object configures the domain, port, and optionally a secret for security. If `path` is not specified, a secure path is automatically generated.

```APIDOC
## Built-in Webhook Server

### Description
Starts the max-io bot with a built-in webhook server to receive events.

### Method
`bot.start(options)`

### Parameters
#### `options` (object)
- **allowedUpdates** (array) - Optional - List of update types to listen for.
- **webhook** (object) - Required - Configuration for the webhook server.
  - **domain** (string) - Required - The public domain for the webhook.
  - **port** (number) - Required - The port the webhook server will listen on.
  - **secret** (string) - Optional - A secret key for webhook security.
  - **path** (string) - Optional - A custom path for the webhook endpoint. If not provided, a secure path is generated.

### Request Example
```ts
await bot.start({
  allowedUpdates: ['message_created', 'message_callback'],
  webhook: {
    domain: 'https://example.com',
    port: 3000,
    secret: process.env.MAX_WEBHOOK_SECRET,
  },
});
```

### Request Example with Custom Path
```ts
await bot.start({
  webhook: {
    domain: 'https://example.com',
    path: '/max-webhook',
    port: 3000,
  },
});
```
```

--------------------------------

### Install Max IO

Source: https://github.com/xtcry/max-io/blob/main/README.md

Install the max-io package using npm or yarn. Node.js version 14.13.1 or higher is required.

```bash
npm i max-io
```

```bash
yarn add max-io
```

--------------------------------

### Start Local Webhook Receiver

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Starts the local webhook receiver. By default, it uses the built-in runtime of the library. This command also prints current subscriptions, creates/updates a subscription if AUTO_SUBSCRIBE is true, and opens an interactive console.

```bash
yarn server
```

--------------------------------

### Set Up Webhook

Source: https://github.com/xtcry/max-io/blob/main/README.md

Configure a Max IO bot to use webhooks for receiving updates. This example sets up a webhook with a specified domain and port. Ensure MAX_WEBHOOK_SECRET is set.

```typescript
import 'dotenv/config';

import { Bot } from 'max-io';

const bot = new Bot(process.env.MAX_BOT_TOKEN!);

bot.command('ping', async (ctx) => {
  await ctx.reply('pong from webhook');
});

await bot.start({
  webhook: {
    domain: 'https://example.com',
    port: 3000,
    secret: process.env.MAX_WEBHOOK_SECRET,
  },
});
```

--------------------------------

### Start Built-in Webhook Server

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Starts the max-io bot with a built-in webhook server. Ensure the domain is publicly accessible and the port is open. The `allowedUpdates` parameter specifies which event types to listen for.

```typescript
import 'dotenv/config';

import { Bot } from 'max-io';

const token = process.env.MAX_BOT_TOKEN;
if (!token) throw new Error('MAX_BOT_TOKEN is not set');

const bot = new Bot(token);

bot.command('ping', async (ctx) => {
  await ctx.reply('pong');
});

await bot.start({
  allowedUpdates: ['message_created', 'message_callback'],
  webhook: {
    domain: 'https://example.com',
    port: 3000,
    secret: process.env.MAX_WEBHOOK_SECRET,
  },
});
```

--------------------------------

### Start Local Webhook Receiver with Custom Server Mode

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Starts the local webhook receiver using a custom Node.js HTTP server. This is useful for testing manual integration with your own HTTP server.

```bash
MAX_WEBHOOK_SERVER_MODE=custom
yarn server
```

--------------------------------

### Custom HTTP Server with Webhook Callback

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

This example shows how to integrate max-io webhooks with an existing HTTP server using `webhookCallback`. This method handles incoming POST requests, verifies the path and secret, and processes updates.

```APIDOC
## Custom HTTP Server

### Description
Integrates max-io webhooks with an existing Node.js HTTP server using `webhookCallback`.

### Method
`bot.webhookCallback(path, options)`

### Parameters
#### `path` (string)
- The expected path for the webhook endpoint.

#### `options` (object)
- **secret** (string) - Optional - A secret key for webhook security verification.

### Request Example
```ts
import { Bot } from 'max-io';
import { createServer } from 'node:http';

const bot = new Bot(process.env.MAX_BOT_TOKEN!);

bot.command('ping', async (ctx) => {
  await ctx.reply('pong');
});

bot.botInfo ??= await bot.api.getMyInfo();

const server = createServer(
  bot.webhookCallback('/max-webhook', {
    secret: process.env.MAX_WEBHOOK_SECRET,
  }),
);

server.listen(3000);
```

### Verification
The `webhookCallback` function verifies:
- HTTP method is `POST`.
- Request path matches the provided path.
- `x-max-bot-api-secret` header matches the provided `secret` (if configured).
- Request body is a valid JSON update.
- Update is passed to `bot.handleUpdate(...)`.
```

--------------------------------

### Start Built-in Webhook Server with Custom Path

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Configures the built-in webhook server to use a custom path. If no path is specified, the library generates a secure, stable path based on the bot token.

```typescript
await bot.start({
  webhook: {
    domain: 'https://example.com',
    path: '/max-webhook',
    port: 3000,
  },
});
```

--------------------------------

### Standalone API Commands

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Individual commands to test the webhook API functions separately. These can be run without starting the interactive server.

```bash
yarn subscribe
yarn get-subs
yarn unsubscribe
```

--------------------------------

### Get Subscriptions

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Retrieves a list of all configured webhook subscriptions for the bot.

```APIDOC
## GET /getSubscriptions

### Description
Retrieves a list of all configured webhook subscriptions for the bot.

### Method
GET

### Endpoint
/getSubscriptions

### Response
#### Success Response (200)
- **subscriptions** (array) - A list of webhook subscription objects.
  - **url** (string) - The URL of the webhook.
  - **update_types** (array) - A list of update types the webhook is subscribed to.

### Response Example
{
  "subscriptions": [
    {
      "url": "https://example.com/webhook",
      "update_types": ["message", "callback_query"]
    }
  ]
}
```

--------------------------------

### Webhook Subscriptions Management

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Provides methods for managing webhook subscriptions, including getting existing subscriptions, subscribing to updates, and unsubscribing.

```APIDOC
## Subscriptions

### Description
Manages webhook subscriptions using low-level API methods.

### Methods
#### `bot.api.getSubscriptions()`
- **Description**: Retrieves a list of current webhook subscriptions.
- **Returns**: A promise that resolves to an array of subscription objects.

#### `bot.api.subscribe(options)`
- **Description**: Subscribes to receive specific types of updates at a given URL.
- **Parameters**:
  - **options** (object)
    - **url** (string) - Required - The webhook URL to send updates to.
    - **update_types** (array) - Required - A list of update types to subscribe to (e.g., ['message_created']).
    - **secret** (string) - Optional - A secret key for webhook security.
- **Returns**: A promise that resolves when the subscription is created.

#### `bot.api.unsubscribe(url)`
- **Description**: Unsubscribes from receiving updates at a specific URL.
- **Parameters**:
  - **url** (string) - Required - The webhook URL to unsubscribe from.
- **Returns**: A promise that resolves when the subscription is removed.

### Request Example (Subscribe)
```ts
await bot.api.subscribe({
  url: 'https://example.com/max-webhook',
  update_types: ['message_created'],
  secret: process.env.MAX_WEBHOOK_SECRET,
});
```

### Request Example (Get Subscriptions)
```ts
const subscriptions = await bot.api.getSubscriptions();
```

### Request Example (Unsubscribe)
```ts
await bot.api.unsubscribe('https://example.com/max-webhook');
```
```

--------------------------------

### Controlling Previous Webhook Deletion

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Explains how to control the automatic deletion of previous webhook subscriptions when starting the bot or creating new webhooks.

```APIDOC
## Controlling Old Webhook Subscriptions

### Description
Manages the behavior of deleting previous webhook subscriptions to prevent conflicts.

### Behavior
By default, `max-io` prevents delivery mode conflicts by deleting existing webhook subscriptions in certain scenarios:
- `bot.start()` deletes all webhook subscriptions before starting long polling.
- `bot.start({ webhook })` deletes webhook subscriptions pointing to different URLs.
- `bot.createWebhook(...)` deletes webhook subscriptions pointing to different URLs.

### Overriding Default Behavior
To keep existing webhook subscriptions, set `deletePreviousWebhooks` to `false`.

### Request Example (Keep Previous Webhooks on Start)
```ts
await bot.start({ deletePreviousWebhooks: false });
```

### Request Example (Keep Previous Webhooks with Webhook Config)
```ts
await bot.start({
  webhook: {
    domain: 'https://example.com',
    deletePreviousWebhooks: false,
  },
});
```
```

--------------------------------

### Prevent Deleting Previous Webhooks

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Configure the bot to not delete existing webhook subscriptions when starting. This is useful if you need to maintain multiple webhook endpoints or want to avoid disrupting existing integrations.

```typescript
await bot.start({ deletePreviousWebhooks: false });

await bot.start({
  webhook: {
    domain: 'https://example.com',
    deletePreviousWebhooks: false,
  },
});
```

--------------------------------

### Download Demo Files with Curl

Source: https://github.com/xtcry/max-io/blob/main/examples/pr-scenarios/README.md

Use these curl commands to download sample media files for testing. Ensure you have a 'public' directory in your 'examples/pr-scenarios' directory.

```bash
curl -L https://samplelib.com/mp4/sample-30s.mp4 -o public/video.mp4
curl -L https://samplelib.com/mp3/sample-speech-20m.mp3 -o public/audio.mp3
curl -L https://samplelib.com/png/sample-boat-400x300.png -o public/image.png
```

--------------------------------

### Create Inline Keyboards with Max IO

Source: https://github.com/xtcry/max-io/blob/main/README.md

Demonstrates how to create inline keyboards with different button types like callback, openApp, and clipboard. Ensure the Keyboard module is imported.

```typescript
const keyboard = Keyboard.inlineKeyboard([
  [Keyboard.button.callback('Callback', 'payload')],
  [Keyboard.button.openApp('Открыть mini app', 'my_bot', 'demo')],
  [Keyboard.button.clipboard('Скопировать', 'promo-code')],
]);
```

--------------------------------

### Build and Copy Local Max-IO Changes

Source: https://github.com/xtcry/max-io/blob/main/examples/02-chat-admin-management/README.md

Build local changes in the `max-io` library and copy them to the sample project. This is necessary if you are working with unpublished changes.

```bash
yarn build
node scripts/copy-to-sample.js
```

--------------------------------

### Handle Callback Action

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Listen for a specific callback action ('profile:open') and respond with a notification to the user.

```typescript
bot.action('profile:open', async (ctx) => {
  await ctx.answerOnCallback({ notification: 'Открываем профиль' });
});
```

--------------------------------

### Run Project Checks

Source: https://github.com/xtcry/max-io/blob/main/CONTRIBUTING.md

Execute these commands to ensure the project builds correctly, passes type checking, linting, and formatting standards.

```bash
yarn build
yarn typecheck
yarn lint
yarn format
```

--------------------------------

### Import Max IO Additional Modules

Source: https://github.com/xtcry/max-io/blob/main/README.md

Shows how to import essential modules for session management, scene management, and internationalization (i18n) from the max-io library. These modules provide middleware for enhanced bot functionality.

```typescript
import { I18n } from 'max-io/lib/i18n';
import { SceneManager, StepScene } from 'max-io/lib/scene';
import { SessionManager } from 'max-io/lib/session';
```

--------------------------------

### Creating Attachments with Existing Tokens

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Demonstrates how to create attachment objects when you already have a token for the file. This is useful for replying with pre-uploaded content.

```APIDOC
## Creating Attachments with Existing Tokens

If a token already exists, an attachment can be created directly.

```ts
import {
  AudioAttachment,
  FileAttachment,
  ImageAttachment,
  VideoAttachment,
} from 'max-io';

await ctx.reply('Image', {
  attachments: [new ImageAttachment({ token: 'image-token' }).toJson()],
});

await ctx.reply('Video', {
  attachments: [new VideoAttachment({ token: 'video-token' }).toJson()],
});

await ctx.reply('Audio', {
  attachments: [new AudioAttachment({ token: 'audio-token' }).toJson()],
});

await ctx.reply('File', {
  attachments: [new FileAttachment({ token: 'file-token' }).toJson()],
});
```
```

--------------------------------

### Uploading New Files via ctx.api

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Shows how to upload new files (images, videos, audio, general files) using the `ctx.api.upload*` methods. The `source` can be a file path, Buffer, or ReadStream.

```APIDOC
## Upload via `ctx.api`

For new files, use upload helpers:

```ts
const image = await ctx.api.uploadImage({ source: './public/image.png' });
const video = await ctx.api.uploadVideo({ source: './public/video.mp4' });
const audio = await ctx.api.uploadAudio({ source: './public/audio.mp3' });
const file = await ctx.api.uploadFile({ source: './public/report.pdf' });

await ctx.reply('Done', {
  attachments: [image.toJson(), video.toJson(), audio.toJson(), file.toJson()],
});
```

`source` can be a file path, `Buffer`, or `ReadStream`.
```

--------------------------------

### Create Attachments with Existing Tokens

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Use helper classes like `ImageAttachment`, `VideoAttachment`, `AudioAttachment`, and `FileAttachment` to create attachments when you already have a token.

```typescript
import {
  AudioAttachment,
  FileAttachment,
  ImageAttachment,
  VideoAttachment,
} from 'max-io';

await ctx.reply('Изображение', {
  attachments: [new ImageAttachment({ token: 'image-token' }).toJson()],
});

await ctx.reply('Видео', {
  attachments: [new VideoAttachment({ token: 'video-token' }).toJson()],
});

await ctx.reply('Аудио', {
  attachments: [new AudioAttachment({ token: 'audio-token' }).toJson()],
});

await ctx.reply('Файл', {
  attachments: [new FileAttachment({ token: 'file-token' }).toJson()],
});
```

--------------------------------

### Webhook Creation and Deletion Helpers

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Helper methods for creating and deleting webhook configurations, which abstract the underlying API calls for managing subscriptions.

```APIDOC
## Webhook Creation/Deletion Helpers

### Description
Provides helper methods to create and delete webhook configurations, simplifying subscription management.

### Methods
#### `bot.createWebhook(options)`
- **Description**: Creates a webhook subscription using provided configuration.
- **Parameters**:
  - **options** (object)
    - **domain** (string) - Required - The public domain for the webhook.
    - **path** (string) - Required - The path for the webhook endpoint.
    - **secret** (string) - Optional - A secret key for webhook security.
- **Returns**: A promise that resolves with webhook information.

#### `bot.deleteWebhook(options)`
- **Description**: Deletes a webhook subscription.
- **Parameters**:
  - **options** (object)
    - **domain** (string) - Required - The public domain of the webhook to delete.
    - **path** (string) - Required - The path of the webhook to delete.
- **Returns**: A promise that resolves when the webhook is deleted.

### Request Example (Create Webhook)
```ts
const callback = await bot.createWebhook({
  domain: 'https://example.com',
  path: '/max-webhook',
  secret: process.env.MAX_WEBHOOK_SECRET,
});
```

### Request Example (Delete Webhook)
```ts
await bot.deleteWebhook({
  domain: 'https://example.com',
  path: '/max-webhook',
});
```
```

--------------------------------

### Create Open App Button

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Generate a button to open a mini app. It requires the button text, the web app identifier (bot name or URL), and an optional payload and contact ID.

```typescript
Keyboard.button.openApp('Открыть mini app', 'my_bot', 'payload');
```

--------------------------------

### Set up Cloudflared Tunnel for Public URL

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Demonstrates how to use cloudflared to create a public HTTPS endpoint for local testing. The tunnel forwards requests to the local server running on port 3000.

```bash
cloudflared tunnel --url http://localhost:3000
```

--------------------------------

### Upload New Files via ctx.api

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Utilize `ctx.api.uploadImage`, `ctx.api.uploadVideo`, `ctx.api.uploadAudio`, and `ctx.api.uploadFile` for new files. The `source` can be a file path, Buffer, or ReadStream.

```typescript
const image = await ctx.api.uploadImage({ source: './public/image.png' });
const video = await ctx.api.uploadVideo({ source: './public/video.mp4' });
const audio = await ctx.api.uploadAudio({ source: './public/audio.mp3' });
const file = await ctx.api.uploadFile({ source: './public/report.pdf' });

await ctx.reply('Готово', {
  attachments: [image.toJson(), video.toJson(), audio.toJson(), file.toJson()],
});
```

--------------------------------

### Middleware Order for Scene Control Commands

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Illustrates the recommended order for middleware and command registration. Scene control commands like `/cancel` should be registered before `sceneManager.middlewareIntercept` to ensure they are processed correctly by the active scene.

```typescript
bot.use(sessionManager.middleware);
bot.use(i18n.middleware);
bot.use(sceneManager.middleware);

bot.command('cancel', async (ctx) => {
  await ctx.scene.leave({ silent: true, canceled: true });
  await ctx.reply(ctx.i18n.t('scene.cancelled'));
});

bot.use(sceneManager.middlewareIntercept);
```

--------------------------------

### Progress Tracking during Upload

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Illustrates how to monitor the upload progress using the `onProgress` callback, which provides details about the upload phase, mode, filename, loaded bytes, and total size.

```APIDOC
## Progress

`onProgress` receives the phase, upload mode, file name, loaded bytes, and total size if known.

```ts
const video = await ctx.api.uploadVideo({
  source: './public/video.mp4',
  timeout: 60_000,
  onProgress: ({ phase, mode, fileName, loaded, total }) => {
    const percent = total ? Math.round((loaded / total) * 100) : undefined;
    console.log({ phase, mode, fileName, percent });
  },
});

await ctx.reply('Video uploaded', {
  attachments: [video.toJson()],
});
```
```

--------------------------------

### Scene Management with Step-based Scenes

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Implement multi-step interactions using `StepScene`. Ensure session middleware is loaded before scene middleware. Register scene control commands after `sceneManager.middleware` but before `sceneManager.middlewareIntercept`.

```typescript
import { SceneManager, StepScene } from 'max-io/lib/scene';

const introScene = new StepScene('intro', [
  async (ctx) => {
    await ctx.reply('Как тебя зовут?');
    await ctx.scene.step.next();
  },
  async (ctx) => {
    await ctx.reply(`Приятно познакомиться: ${ctx.message?.body?.text}`);
    await ctx.scene.leave();
  },
]);

const scenes = new SceneManager({ scenes: [introScene] });

bot.use(scenes.middleware);
bot.use(scenes.middlewareIntercept);

bot.command('intro', async (ctx) => {
  await ctx.scene.enter('intro');
});
```

--------------------------------

### Environment Variables for Max.io Bot

Source: https://github.com/xtcry/max-io/blob/main/examples/04-sessions-scenes-i18n/README.md

Configure your Max.io bot using these environment variables.

```env
MAX_BOT_TOKEN=<token>
ADMIN_ID=<optional-user-id>
DEBUG=max-io:main
```

--------------------------------

### Import Keyboard Namespace

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Import the Keyboard namespace from max-io to use keyboard functionalities.

```typescript
import { Keyboard } from 'max-io';
```

--------------------------------

### Redis Storage for Session Management

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Integrate Redis for persistent session storage. Requires the `ioredis` package. Configure TTL for session expiration.

```bash
yarn add ioredis
```

```typescript
import { RedisStorage, SessionManager } from 'max-io/lib/session';

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

const sessions = new SessionManager({
  storage: new RedisStorage({
    redis,
    ttl: 7 * 24 * 3600,
  }),
});
```

--------------------------------

### I18n Integration with YAML Files

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Set up internationalization using YAML files for translations. Requires the `js-yaml` package. Specify the default language and the directory containing locale files.

```bash
yarn add js-yaml
```

```typescript
import { I18n } from 'max-io/lib/i18n';

import { resolve } from 'node:path';

const i18n = new I18n({
  defaultLanguage: 'ru',
  directory: resolve(process.cwd(), 'locales'),
  useSession: true,
});

bot.use(i18n.middleware);
```

```yaml
# locales/ru.yml
start:
  hello: 'Привет, {name}!'

```

```typescript
bot.command('start', async (ctx) => {
  await ctx.reply(
    ctx.i18n.t('start.hello', { name: ctx.message?.sender?.name }),
  );
});
```

--------------------------------

### Create Link Button

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Create a button that opens a specified URL in the client's browser.

```typescript
Keyboard.button.link('Документация', 'https://dev.max.ru');
```

--------------------------------

### Interactive Commands for Webhook Server

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Commands available within the running 'yarn server' interactive console for managing webhook subscriptions.

```text
help
list
subscribe
unsubscribe
exit
```

--------------------------------

### Upload Video with Progress

Source: https://github.com/xtcry/max-io/blob/main/README.md

Upload a video file using the Max IO API. The `uploadVideo` method supports progress tracking via the `onProgress` callback and returns attachment information.

```typescript
bot.command('video', async (ctx) => {
  const video = await ctx.api.uploadVideo({
    source: './public/video.mp4',
    onProgress: ({ loaded, total }) => {
      if (total) console.log(`upload ${Math.round((loaded / total) * 100)}%`);
    },
  });

  await ctx.reply('Видео загружено', {
    attachments: [video.toJson()],
  });
});
```

--------------------------------

### Create Reply Keyboard

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Build a reply keyboard with buttons for sending messages, contacts, or geolocation. Visual support for reply keyboards depends on the specific Max client.

```typescript
const keyboard = Keyboard.replyKeyboard([
  [Keyboard.button.sendMessage('Да', 'answer:yes')],
  [Keyboard.button.sendContact('Отправить контакт')],
  [
    Keyboard.button.sendGeoLocation('Отправить геолокацию', null, {
      quick: true,
    }),
  ],
]);

await ctx.reply('Быстрый ответ', {
  attachments: [keyboard],
});
```

--------------------------------

### Configure Public URL and Webhook Path

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Sets the public webhook URL and a specific path for the webhook endpoint. This is used in conjunction with a tunneling service like cloudflared.

```bash
MAX_WEBHOOK_URL=https://example.trycloudflare.com
MAX_WEBHOOK_PATH=/max-webhook
```

--------------------------------

### Basic Session Management with Memory Storage

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Set up session middleware to store state between updates. Uses memory storage by default, suitable for development. For production, consider external storage.

```typescript
import { Bot, type Context } from 'max-io';
import { type ISessionContext, SessionManager } from 'max-io/lib/session';

type SessionState = ISessionContext & {
  visits?: number;
};

type MyContext = Context & {
  session: SessionState;
};

const bot = new Bot<MyContext>(process.env.MAX_BOT_TOKEN!);
const sessions = new SessionManager<SessionState, MyContext>({});

bot.use(sessions.middleware);

bot.command('start', async (ctx) => {
  ctx.session.visits = (ctx.session.visits ?? 0) + 1;
  await ctx.reply(`Визитов: ${ctx.session.visits}`);
});
```

--------------------------------

### Create Inline Keyboard

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Construct an inline keyboard with multiple rows and buttons, including callback and link buttons. This keyboard is then sent as an attachment in a reply.

```typescript
const keyboard = Keyboard.inlineKeyboard([
  [
    Keyboard.button.callback('Обычная', 'intent:default'),
    Keyboard.button.callback('Да', 'intent:yes', { intent: 'positive' }),
    Keyboard.button.callback('Нет', 'intent:no', { intent: 'negative' }),
  ],
  [Keyboard.button.link('Открыть Max', 'https://max.ru')],
]);

await ctx.reply('Выбери действие', {
  attachments: [keyboard],
});
```

--------------------------------

### Use Webhook Callback with Custom HTTP Server

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Integrates max-io's webhook handling into an existing Node.js HTTP server. This is useful when you already have a server running and want to process incoming webhook events.

```typescript
import { Bot } from 'max-io';

import { createServer } from 'node:http';

const bot = new Bot(process.env.MAX_BOT_TOKEN!);

bot.command('ping', async (ctx) => {
  await ctx.reply('pong');
});

bot.botInfo ??= await bot.api.getMyInfo();

const server = createServer(
  bot.webhookCallback('/max-webhook', {
    secret: process.env.MAX_WEBHOOK_SECRET,
  }),
);

server.listen(3000);
```

--------------------------------

### Create Message and Clipboard Buttons

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Create buttons for sending predefined text messages or copying text to the clipboard. The clipboard button requires client support.

```typescript
Keyboard.button.message('Отправить этот текст');
Keyboard.button.clipboard('Скопировать промокод', 'PROMO-2026');
```

--------------------------------

### Cancelling Uploads

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Explains how to cancel an ongoing upload using `AbortController`. It also provides guidance on handling cancellation requests from users by managing upload jobs in the background.

```APIDOC
## Cancel upload

```ts
const controller = new AbortController();

setTimeout(() => controller.abort(), 30_000);

await ctx.api.uploadFile({
  source: './public/archive.zip',
  signal: controller.signal,
});
```

If you need to cancel an upload via a user command, do not block the middleware by waiting for the upload: start the upload job in the background, save the `AbortController`, and handle the cancel command separately.
```

--------------------------------

### Handle Command Arguments and Payload

Source: https://github.com/xtcry/max-io/blob/main/README.md

Commands in Max IO support payload and arguments. This snippet shows how to parse user IDs and reasons from command arguments.

```typescript
bot.command('ban', async (ctx) => {
  const [userId, ...reasonParts] = ctx.args ?? [];
  const reason = reasonParts.join(' ');

  await ctx.reply(`userId=${userId}; reason=${reason || 'не указана'}`);
});
```

--------------------------------

### Handling `attachment.not.ready`

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Describes the `attachment.not.ready` status that the Max server might return temporarily after an upload while it processes the file. The max-io library automatically retries sending messages with this status and respects `AbortSignal`.

```APIDOC
## `attachment.not.ready`

After an upload, the Max server might temporarily return `attachment.not.ready` when sending a message. `max-io` retries sending with backoff and considers `AbortSignal`.

```ts
const controller = new AbortController();

await ctx.api.sendMessageToChat(ctx.chatId!, 'Video', {
  attachments: [video.toJson()],
  signal: controller.signal,
});
```
```

--------------------------------

### Monitor Upload Progress

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Use the `onProgress` callback to track the upload status, including phase, mode, filename, loaded bytes, and total size. The percentage is calculated if the total size is known.

```typescript
const video = await ctx.api.uploadVideo({
  source: './public/video.mp4',
  timeout: 60_000,
  onProgress: ({ phase, mode, fileName, loaded, total }) => {
    const percent = total ? Math.round((loaded / total) * 100) : undefined;
    console.log({ phase, mode, fileName, percent });
  },
});

await ctx.reply('Видео загружено', {
  attachments: [video.toJson()],
});
```

--------------------------------

### Other Attachment Types

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Demonstrates how to create and send other types of attachments like stickers, geolocation, and shared links.

```APIDOC
## Other attachments

```ts
import { LocationAttachment, ShareAttachment, StickerAttachment } from 'max-io';

await ctx.reply('', {
  attachments: [new StickerAttachment({ code: 'sticker-code' }).toJson()],
});

await ctx.reply('Geolocation', {
  attachments: [
    new LocationAttachment({ lon: 37.6173, lat: 55.7558 }).toJson(),
  ],
});

await ctx.reply('Link', {
  attachments: [new ShareAttachment({ url: 'https://example.com' }).toJson()],
});
```
```

--------------------------------

### Run Chat Admin Management Commands

Source: https://github.com/xtcry/max-io/blob/main/examples/02-chat-admin-management/README.md

Execute commands to manage chat administrators and chats. Ensure the `delete-chat` command is used only on test chats as it permanently removes them.

```bash
yarn get-admins
yarn set-admin
yarn delete-admin
yarn delete-chat
```

--------------------------------

### Create Callback Button

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Define a callback button with text and a payload. When pressed, the bot receives a message_callback update. The payload is limited, so use short keys or IDs.

```typescript
Keyboard.button.callback('Профиль', 'profile:open');
```

--------------------------------

### Manage Webhook Subscriptions

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

API methods for managing webhook subscriptions. Use `getSubscriptions` to view current subscriptions, `subscribe` to create a new one, and `unsubscribe` to remove an existing one.

```typescript
const subscriptions = await bot.api.getSubscriptions();

await bot.api.subscribe({
  url: 'https://example.com/max-webhook',
  update_types: ['message_created'],
  secret: process.env.MAX_WEBHOOK_SECRET,
});

await bot.api.unsubscribe('https://example.com/max-webhook');
```

--------------------------------

### Subscribe to Webhooks

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Configures a new webhook subscription for receiving updates at a specified URL.

```APIDOC
## POST /subscribe

### Description
Configures a new webhook subscription for receiving updates at a specified URL. If a subscription with the same URL already exists, it will be updated.

### Method
POST

### Endpoint
/subscribe

### Parameters
#### Request Body
- **url** (string) - Required - The public HTTPS URL where updates should be delivered.
- **update_types** (array) - Optional - A list of update types to subscribe to. If empty, subscribes to all available types.
- **secret** (string) - Optional - A secret string used for the `X-Max-Bot-Api-Secret` header for authentication.

### Request Example
{
  "url": "https://your-webhook-url.com/path",
  "update_types": ["message", "edited_message"],
  "secret": "your-secure-secret"
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the result of the subscription operation (e.g., 'subscribed', 'updated').

### Response Example
{
  "status": "subscribed"
}
```

--------------------------------

### Override Max Upload Paths

Source: https://github.com/xtcry/max-io/blob/main/examples/pr-scenarios/README.md

When testing upload scenarios that require larger files than the default samples, override the MAX_UPLOAD_PROGRESS_IMAGE_PATH and MAX_UPLOAD_PROGRESS_FILE_PATH environment variables with the absolute paths to your local files.

```bash
MAX_UPLOAD_PROGRESS_IMAGE_PATH=/abs/path/to/your-image.png \
MAX_UPLOAD_PROGRESS_FILE_PATH=/abs/path/to/your-file.bin \
yarn start:10-pr-227-upload-progress
```

--------------------------------

### Uploading Image by URL

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Allows uploading an image directly from a URL without needing to download and then upload the file.

```APIDOC
## Image by URL

For an image, you can provide a URL without uploading the file via the upload endpoint:

```ts
const image = await ctx.api.uploadImage({
  url: 'https://example.com/image.png',
});

await ctx.reply('Image from URL', {
  attachments: [image.toJson()],
});
```
```

--------------------------------

### Create Request Contact and Geolocation Buttons

Source: https://github.com/xtcry/max-io/blob/main/docs/04-keyboards.md

Buttons that prompt the user to share their contact information or geolocation. The bot receives this data as an attachment if the user confirms and the client supports it.

```typescript
Keyboard.button.requestContact('Отправить контакт');
Keyboard.button.requestGeoLocation('Отправить геолокацию', { quick: true });
```

--------------------------------

### Upload Image by URL

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Upload an image directly using its URL without needing to download and re-upload the file.

```typescript
const image = await ctx.api.uploadImage({
  url: 'https://example.com/image.png',
});

await ctx.reply('Картинка по URL', {
  attachments: [image.toJson()],
});
```

--------------------------------

### Create and Delete Webhook Endpoints

Source: https://github.com/xtcry/max-io/blob/main/docs/webhook.md

Helper methods to create and delete webhook endpoints. These methods abstract the underlying API calls for managing subscriptions.

```typescript
const callback = await bot.createWebhook({
  domain: 'https://example.com',
  path: '/max-webhook',
  secret: process.env.MAX_WEBHOOK_SECRET,
});

await bot.deleteWebhook({
  domain: 'https://example.com',
  path: '/max-webhook',
});
```

--------------------------------

### Cancel Upload with AbortController

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Implement upload cancellation using `AbortController`. This is useful for user-initiated cancellations or to manage long-running uploads.

```typescript
const controller = new AbortController();

setTimeout(() => controller.abort(), 30_000);

await ctx.api.uploadFile({
  source: './public/archive.zip',
  signal: controller.signal,
});
```

--------------------------------

### Render Scene Messages with Callbacks

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Use `answerOnCallback` to edit the current message for inline scenes, which is more efficient than sending a new message. Store temporary message IDs in `session.tempMids` to manage and clean them up later.

```typescript
async function renderSceneMessage(
  ctx: IStepContext<ExtraSceneState>,
  text: string,
  keyboard?: InlineKeyboardAttachmentRequest,
) {
  const attachments = keyboard ? [keyboard] : [];

  if (ctx.updateType === 'message_callback') {
    await ctx.answerOnCallback({ message: { text, attachments } });
    return;
  }

  const message = await ctx.reply(text, { attachments });
  ctx.session.tempMids ??= [];
  ctx.session.tempMids.push(message.body.mid);
}
```

--------------------------------

### Save User Message with Reply-Link Mid

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Store the user's message text and its message ID (`mid`) in the scene state. This allows the final message to reference the original user input using a reply-link.

```typescript
noteStep.on('message_created', async (ctx, next) => {
  const text = ctx.message?.body?.text?.trim();
  if (!text || text.startsWith('/')) return next();

  ctx.scene.state.note = text;
  ctx.scene.state.noteMid = ctx.message.body.mid;
  await ctx.scene.step.next();
});

await ctx.answerOnCallback({
  message: {
    text: ctx.i18n.t('scene.extra.saved'),
    link: { type: 'reply', mid: ctx.scene.state.noteMid! },
  },
});
```

--------------------------------

### Send Other Attachment Types

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

Create and send various other attachment types including stickers, geolocation, and shared links using their respective helper classes.

```typescript
import { LocationAttachment, ShareAttachment, StickerAttachment } from 'max-io';

await ctx.reply('', {
  attachments: [new StickerAttachment({ code: 'sticker-code' }).toJson()],
});

await ctx.reply('Геолокация', {
  attachments: [
    new LocationAttachment({ lon: 37.6173, lat: 55.7558 }).toJson(),
  ],
});

await ctx.reply('Ссылка', {
  attachments: [new ShareAttachment({ url: 'https://example.com' }).toJson()],
});
```

--------------------------------

### Define Scene State Types

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Define distinct types for temporary scene states (e.g., IntroSceneState) and additional states (e.g., ExtraSceneState) to avoid conflicts with persistent session data. Use IStepContext to strongly type the scene's context.

```typescript
export type IntroSceneState = {
  name?: string;
  age?: number;
};

export type ExtraSceneState = {
  language?: 'ru' | 'en';
  frequency?: 'daily' | 'weekly';
  note?: string;
  noteMid?: string;
};

export type IStepContext<S extends Record<string, unknown> = {}> =
  WithStepScene<AppContext<max.Update, S>, 'session'>;

const introScene = new StepScene<IStepContext<IntroSceneState>>(
  SceneType.Intro,
  steps,
);
```

--------------------------------

### Typed Context for Unified Bot Features

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Define a custom `MyContext` type that merges `Context`, `I18nContext`, and `ISessionContext` for a unified type definition. This improves type safety when working with session and i18n features.

```typescript
import type { Context } from 'max-io';
import type { I18nContext } from 'max-io/lib/i18n';
import type { ISessionContext } from 'max-io/lib/session';

type SessionState = ISessionContext & {
  locale?: string;
};

type MyContext = Context & {
  session: SessionState;
  i18n: I18nContext<Record<string, Record<string, unknown>>>;
};
```

--------------------------------

### Handle `attachment.not.ready` State

Source: https://github.com/xtcry/max-io/blob/main/docs/03-attachments-and-uploads.md

When Max is still processing an uploaded file, it may temporarily respond with `attachment.not.ready`. `max-io` automatically retries sending messages with backoff and respects `AbortSignal`.

```typescript
const controller = new AbortController();

await ctx.api.sendMessageToChat(ctx.chatId!, 'Видео', {
  attachments: [video.toJson()],
  signal: controller.signal,
});
```

--------------------------------

### Configure Long Polling Marker

Source: https://github.com/xtcry/max-io/blob/main/README.md

Customize long polling behavior by setting a marker to resume from a specific position. This is useful for development and manual testing. For production, Webhook is recommended.

```typescript
const bot = new Bot(process.env.MAX_BOT_TOKEN!, {
  polling: { marker: Number(process.env.MAX_POLLING_MARKER) || undefined },
});
// или
bot.polling.setMarker(123456);
console.log(bot.polling.marker);
// или
await bot.start({ marker: bot.polling.marker });
```

--------------------------------

### Clean Up Temporary Messages

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Implement a function to clean up temporary messages stored in `session.tempMids`. Exclude the message currently being edited via `answerOnCallback` to avoid issues.

```typescript
async function cleanupTempMessages(
  ctx: IStepContext<ExtraSceneState>,
  keepMid?: string,
) {
  const mids = ctx.session.tempMids ?? [];
  ctx.session.tempMids = [];

  await Promise.allSettled(
    mids.filter((mid) => mid !== keepMid).map((mid) => ctx.deleteMessage(mid)),
  );
}
```

--------------------------------

### Unsubscribe from Webhooks

Source: https://github.com/xtcry/max-io/blob/main/examples/03-webhook-subscriptions/README.md

Removes an existing webhook subscription identified by its URL.

```APIDOC
## POST /unsubscribe

### Description
Removes an existing webhook subscription identified by its URL.

### Method
POST

### Endpoint
/unsubscribe

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the webhook subscription to remove.

### Request Example
{
  "url": "https://your-webhook-url.com/path"
}

### Response
#### Success Response (200)
- **status** (string) - Indicates the result of the unsubscription operation (e.g., 'unsubscribed', 'not_found').

### Response Example
{
  "status": "unsubscribed"
}
```

--------------------------------

### Change Language Within a Scene

Source: https://github.com/xtcry/max-io/blob/main/docs/05-sessions-scenes-i18n.md

Update the scene state and i18n locale when a language change action is triggered. Re-render the scene message to reflect the new language immediately.

```typescript
languageStep.action(/extra:lang:(ru|en)/, async (ctx) => {
  const language = ctx.match![1] as 'ru' | 'en';

  ctx.scene.state.language = language;
  ctx.i18n.locale(language);

  await renderSceneMessage(
    ctx,
    ctx.i18n.t('scene.extra.chooseLanguage'),
    languageKeyboard(ctx),
  );
});
```
Tokens:
Raw