Кукбук: serverless-бот с мини-аппом за вечер#

Рассказ в этом файле на русском. Команды CLI и имена инструментов от языка не зависят. English, 中文, العربية, Deutsch and Français overviews: docs/cookbook.<lang>.mdx.

Пошаговый рецепт по платформе Telegram serverless (@tgcloud) на примере реального бота «Дневник обучения» (srl_assistant_bot): хранит заметки в базе, отвечает кнопками, показывает записи в Mini App.

Всё проверено на живом боте; форматы вывода CLI — самоснятые.

0. Подготовка (5 минут)#

Нужны: Node.js 18+, npm, Telegram.

Создайте бота у @BotFather → /newbot → получите API-токен (он пригодится только для проверок через Bot API, платформе нужен другой токен).
Там же: ваш бот → Serverless → CLI Access → Access token → получите CLI access token формата app<id>:<secret>.

⚠️ Это два разных токена. CLI отвергнет API-токен с ошибкой Token format looks wrong. Expected "app<id>:<secret>".

1. Скаффолд и логин (5 минут)#

npm create @tgcloud/bot my_diarycd my_diarynpx tgcloud login   # вставьте CLI access token (ввод скрыт)

Для CI/неинтерактива:

printf 'app...\n' | TGCLOUD_ASSUME_TTY=1 npx tgcloud login# или export TGCLOUD_TOKEN='app...' — тогда login вообще не нужен

Структура проекта — весь платформенный код в tgcloud/:

tgcloud/schema.js         # схема БД, один файлtgcloud/handlers/         # хендлеры апдейтов, плоско: message.js, callback_query.js, …tgcloud/endpoints/        # серверные функции для Mini App (POST /api/<name>)tgcloud/lib/              # общие модули (можно вложенно)tgcloud.jsonc             # конфиг: static-блок мини-аппаdocs/tgcloud-sdk.md       # полный SDK-референс — читайте его!

⚠️ Импорты проектных модулей — относительные пути С расширением .js: import { notes } from '../schema.js'. Без .js не компилируется. SDK — по имени: import { db, api, fetch, EndpointError, BotApiError } from 'sdk'.

2. Хендлер сообщений + база (20 минут)#

tgcloud/schema.js — таблица заметок:

import { table, integer, text, sql } from 'sdk/db';export const notes = table('notes', {  id:      integer('id').primaryKey({ autoIncrement: true }),  chatId:  integer('chat_id').notNull(),  text:    text('text').notNull(),  created: integer('created_at', { mode: 'timestamp' }).default(sql`(unixepoch())`),});

tgcloud/handlers/message.js — имя файла = тип апдейта, export default получает payload (для message — сам Message):

import { api, db } from 'sdk';import { notes } from '../schema.js';import { eq } from 'sdk/db';export default async function (message) {  const chatId = message.chat.id;  const text = (message.text ?? '').trim();  if (text.startsWith('/start')) {    await api.sendMessage({ chat_id: chatId, text: 'Пиши заметки — сохраню.' });    return;  }  // любая другая строка — заметка  const [row] = await db.insert(notes).values({ chatId, text }).returning().run();  await api.sendMessage({ chat_id: chatId, text: `Записал (#${row.id}) 📝` });}

Правила БД, о которых не скажет компилятор:

всё async — всегда await;
нет foreign keys (.references() бросит при декларации);
удаление колонок/таблиц — только .deprecated('reason'), удаление декларации ничего не дропает;
push никогда не трогает базу — миграции отдельным шагом.

3. Деплой и миграция (5 минут)#

npx tgcloud push# Deploying 2 changes...#   ✓ tgcloud/schema.js#   ✓ tgcloud/handlers/message.js# Schema out of sync — 1 change:#   +  notes    new table

Сначала предпросмотр миграции:

npx tgcloud migrate --dry-run# @@ notes: new table @@#  CREATE TABLE notes ( ... )# (dry-run — nothing was applied)

Применение. В терминале — интерактив (Proceed? → [1/1] Apply? [y]es/[n]o/[q]uit). В CI/скриптах интерактив не сработает:

npx tgcloud migrate --yes     # или --safe (только безопасные изменения)# ✓ notes# Migration complete. Applied: 1, skipped: 0.

Быстрая проверка без живого чата (payload — JSON5):

npx tgcloud run handlers/message '{ chat: { id: 1 }, text: "выучил serverless" }'# ✗ Uncaught exception: BotApiError: api.sendMessage failed [400]: chat not found

chat not found при фейковом chat id — нормально: значит, запись в БД прошла, упала только отправка ответа несуществующему чату.

При первом push на бота с уже задеплоенным скаффолдом увидите конфликт ревизий: This bot already has 2 deployed modules (revision 1). Лечение — npx tgcloud fetch, затем повторный push (или осознанный push --force).

Вебхук платформа ведёт сама по handlers/*:

npx tgcloud webhook# url: https://cloud.telegram.org/app5888700151/webhook# allowed updates: message# ✓ in sync with your deployed handlers

4. Inline-кнопки (callback_query) (15 минут)#

Добавляем кнопки к ответу о сохранении (message.js):

await api.sendMessage({  chat_id: chatId,  text: `Записал (#${row.id}).\n\n${text}`,  reply_markup: {    inline_keyboard: [[      { text: '👍 Полезно', callback_data: `like:${row.id}` },      { text: '🗑 Удалить', callback_data: `del:${row.id}` },    ]],  },});

Скаффолд и хендлер:

npx tgcloud add handlers/callback_query

import { api, db } from 'sdk';import { notes } from '../schema.js';import { eq, and } from 'sdk/db';export default async function (cb) {  const chatId = cb.message?.chat?.id;  const [action, idRaw] = (cb.data ?? '').split(':');  const noteId = Number(idRaw);  const answer = (text) =>    api.answerCallbackQuery({ callback_query_id: cb.id, text }).catch(() => {});  // чужие заметки не трогаем  const note = await db.select().from(notes)    .where(and(eq(notes.id, noteId), eq(notes.chatId, chatId))).get();  if (!note) return answer('Запись не найдена');  if (action === 'del') {    await db.delete(notes).where(and(eq(notes.id, noteId), eq(notes.chatId, chatId))).run();    await api.editMessageText({      chat_id: chatId, message_id: cb.message.message_id,      text: `🗑 Запись #${noteId} удалена.`,    }).catch(() => {});    return answer('Удалено');  }  return answer('👍');}

push — и платформа сама добавит callback_query в allowed_updates вебхука.

5. Mini App (30 минут)#

Три части: endpoint (сервер), статика (фронт), конфиг.

Endpoint tgcloud/endpoints/listNotes.js — вызывается из мини-аппа как POST /api/listNotes, платформа проверяет init data до запуска вашего кода:

import { db, EndpointError } from 'sdk';import { notes } from '../schema.js';import { eq, desc } from 'sdk/db';export default async function (input, ctx) {  const user = ctx.initData?.user;      // уже проверен платформой  if (!user) throw new EndpointError('No user', { code: 'AUTH' });  const rows = await db.select().from(notes)    .where(eq(notes.chatId, user.id))   # в личке chat id == user id    .orderBy(desc(notes.id)).limit(50).all();  return { notes: rows };               // вернётся как JSON}

Статика web/index.html — без сборки, обычный HTML + официальный telegram-web-app.js:

<script src="https://telegram.org/js/telegram-web-app.js"></script><script>  Telegram.WebApp.ready();  Telegram.WebApp.expand();  Telegram.WebApp.Serverless.call('listNotes', {}, (err, result) => {    // err.type === 'ENDPOINT_ERROR' для EndpointError; result — ваш JSON    document.body.textContent = JSON.stringify(result.notes, null, 2);  });</script>

Конфиг tgcloud.jsonc:

{  "static": { "source": "web", "spa": true }}

npx tgcloud push# Deploying 3 changes...#   ✓ web/ — 1 file uploaded (2.1 KB)# Static: https://app5888700151.tgcloud.ai/

Чтобы бот открывал мини-апп, добавьте /app-команду с web_app-кнопкой (https://app<id_бота>.tgcloud.ai/) или Menu Button в @BotFather (/setmenubutton).

Не ставьте X-Frame-Options/строгий frame-ancestors на статику — Telegram Web открывает мини-аппы в iframe.

6. Если что-то молчит#

npx tgcloud webhook        # нет ли ошибок доставки, совпадает ли allowed_updatesnpx tgcloud webhook sync   # перепривязать (--drop-pending отбросит очередь — деструктивно)npx tgcloud status/diff    # что не задеплоеноnpx tgcloud run <module> '<json5>'   # прогон server-side с локальными файлами

Шпаргалка по токенам и CLI#

Что	Значение
API-токен (`123:AA…`)	Bot API вручную; платформе не нужен
CLI access token (`app<id>:<secret>`)	@BotFather → Serverless → CLI Access; для `tgcloud login` / `TGCLOUD_TOKEN`
`login` неинтерактивно	`TGCLOUD_ASSUME_TTY=1` + stdin, или только env `TGCLOUD_TOKEN` (CI)
`migrate` неинтерактивно	`--dry-run` / `--yes` / `--safe`

Полный SDK-референс — в docs/tgcloud-sdk.md вашего скаффолда. Управлять всем этим из AI-агента — MCP-сервер tgcloud-mcp.