@pachca/cli 2026.11.0 → 2026.11.2

package/dist/commands/bots/listen-events.js

@@ -0,0 +1,248 @@
+import { createHmac } from 'node:crypto';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base-command.js';
+import { ApiError, resolveTimeoutSeconds } from '../../client.js';
+import { listenWebhookEvents } from '../../webhook-listener.js';
+/** A `view_submit` payload carries what the answer to the form needs. */
+function formSubmit(payload) {
+    const p = payload;
+    if (!p || p.type !== 'view' || p.event !== 'submit')
+        return undefined;
+    if (typeof p.view_id !== 'string' || typeof p.submit_id !== 'string')
+        return undefined;
+    return { view_id: p.view_id, submit_id: p.submit_id };
+}
+/** Pachca stamps every delivery attempt anew, so a record replayed from the history gets the time of forwarding. */
+function withFreshTimestamp(payload) {
+    const p = payload;
+    if (!p || typeof p !== 'object' || Array.isArray(p) || typeof p.webhook_timestamp !== 'number')
+        return payload;
+    return { ...p, webhook_timestamp: Math.floor(Date.now() / 1000) };
+}
+// Pachca takes the answer to a form for 5 seconds and then shows the employee a sending error.
+// A submission older than this is one the employee saw fail. The age is measured on Pachca's clock,
+// from the Date header of the last API response: 10 s leave room for its whole seconds and transit.
+const FORM_STALE_MS = 10_000;
+// With no Date header the local clock may differ from Pachca's, so the margin is wider.
+const FORM_STALE_LOCAL_MS = 60_000;
+export default class BotsListenEvents extends BaseCommand {
+    static summary = 'Слушать события бота в реальном времени';
+    static description = `Слушать события бота: JSONL в stdout или пересылка на локальный HTTP-обработчик.
+
+Нужен токен бота с webhooks:events:read и включённая история событий.
+Без --forward-to записи остаются в истории. С --forward-to запись удаляется из истории после ответа 2xx.
+Для этого нужно право webhooks:events:delete. Если задан PACHCA_SIGNING_SECRET, запрос подписан им, как вебхук.
+Ответ обработчика на отправку формы CLI передаёт в Пачку, для этого нужно право views:write.
+Ошибка обработчика останавливает команду. После перезапуска событие может прийти снова.`;
+    static scope = 'webhooks:events:read';
+    static examples = [
+        'PACHCA_TOKEN=$PACHCA_BOT_TOKEN <%= config.bin %> bots listen-events',
+        'PACHCA_TOKEN=$PACHCA_BOT_TOKEN PACHCA_SIGNING_SECRET=$PACHCA_SIGNING_SECRET <%= config.bin %> bots listen-events --forward-to http://localhost:3000/webhook',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        'forward-to': Flags.string({ description: 'HTTP(S)-адрес обработчика: событие уходит POST, запись удаляется из истории после 2xx' }),
+        'no-retry': Flags.boolean({
+            description: 'Не переподключаться к потоку после обрыва. Запросы к API по-прежнему повторяются при 429 и 5xx',
+            default: false,
+        }),
+    };
+    /** Without views:write the answer to a form cannot reach Pachca, and trying would fail the record. */
+    answerForms = true;
+    /** Pachca's clock minus the local one, from the Date header of the last API response, with the local stamps it was taken at. */
+    serverClock;
+    // The stream response contains a capability URL: suppress HTTP body diagnostics for this command.
+    // --no-retry here means «do not reconnect»: single API calls keep their retries on 429 and 5xx.
+    getClientFlags() {
+        return { ...super.getClientFlags(), verbose: false, quiet: true, 'no-retry': false };
+    }
+    async run() {
+        const { flags } = await this.parse(BotsListenEvents);
+        this.parsedFlags = flags;
+        let target;
+        if (flags['forward-to']) {
+            try {
+                target = new URL(flags['forward-to']);
+            }
+            catch { /* validation below */ }
+            if (!target || !['http:', 'https:'].includes(target.protocol) || target.username || target.password) {
+                this.validationError([{ message: 'Нужен HTTP(S)-адрес без логина и пароля', flag: 'forward-to' }]);
+            }
+        }
+        if ((flags.output && flags.output !== 'json') || flags.plain || flags.columns || flags.quiet) {
+            this.validationError([{ message: 'События выводятся в JSONL; форматирование и --quiet не поддерживаются' }]);
+        }
+        if (flags['dry-run']) {
+            await this.apiRequest({ method: 'GET', path: '/webhooks/events/stream' });
+            return;
+        }
+        if (target)
+            await this.checkForwardingScopes();
+        // The same rule as API calls: --timeout, defaults.timeout, PACHCA_TIMEOUT, 30 seconds.
+        const timeoutMs = Math.ceil(resolveTimeoutSeconds(this.getClientFlags().timeout) * 1_000);
+        const secret = process.env.PACHCA_SIGNING_SECRET || undefined;
+        if (target && !secret) {
+            process.stderr.write('PACHCA_SIGNING_SECRET не задан: события уходят без заголовка Pachca-Signature\n');
+        }
+        const controller = new AbortController();
+        let interrupted = false;
+        const stop = () => { interrupted = true; controller.abort(); };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            await listenWebhookEvents({
+                signal: controller.signal,
+                retry: !flags['no-retry'],
+                timeoutMs,
+                acknowledge: !!target,
+                request: async (opts) => {
+                    const response = await this.apiRequest(opts);
+                    const date = Date.parse(response.headers?.get('date') ?? '');
+                    if (Number.isFinite(date)) {
+                        const wall = Date.now();
+                        this.serverClock = { offset: date - wall, wall, mono: performance.now() };
+                    }
+                    return response.data;
+                },
+                onReconnect: () => { process.stderr.write('Переподключение к потоку событий…\n'); },
+                onEvent: async (event) => {
+                    if (!target) {
+                        await new Promise((resolve, reject) => {
+                            process.stdout.write(JSON.stringify(event) + '\n', (error) => error ? reject(error) : resolve());
+                        });
+                        return;
+                    }
+                    await this.forward(event, target, secret, controller.signal, timeoutMs);
+                },
+            });
+        }
+        finally {
+            controller.abort();
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        }
+        if (interrupted) {
+            // An API call in flight would keep the process alive until its timeout and retries end.
+            // A JSONL line may still wait in the pipe: let it out, but do not wait on a stuck reader.
+            await Promise.race([
+                new Promise((resolve) => { process.stdout.write('', () => resolve()); }),
+                new Promise((resolve) => { setTimeout(resolve, 1_000); }),
+            ]);
+            process.exit(0);
+        }
+    }
+    /** Without webhooks:events:delete every forwarded event would come again on the next run. */
+    async checkForwardingScopes() {
+        const body = (await this.apiRequest({ method: 'GET', path: '/oauth/token/info' })).data;
+        const scopes = body?.data?.scopes ?? [];
+        const has = (scope) => scopes.includes(scope) || scopes.includes('all');
+        if (!has('webhooks:events:delete')) {
+            throw new ApiError({
+                error: 'Для --forward-to токену нужно право webhooks:events:delete: без него события придут снова при каждом запуске',
+                code: null,
+                type: 'PACHCA_SCOPE_ERROR',
+                scope: 'webhooks:events:delete',
+            });
+        }
+        this.answerForms = has('views:write');
+        if (!this.answerForms) {
+            process.stderr.write('У токена нет права views:write: ответ обработчика на отправку формы не дойдёт до Пачки, и сотрудник увидит ошибку отправки\n');
+        }
+    }
+    async forward(event, target, secret, signal, timeoutMs) {
+        const name = `${event.id} (${event.event_type})`;
+        const form = formSubmit(event.payload);
+        const clock = this.serverClock;
+        // A local clock that jumped (time sync, a virtual machine catching up, a manual change) or a machine
+        // that slept since the stamp breaks the offset: the wider margin on the local clock applies then.
+        const offset = clock && Math.abs((Date.now() - clock.wall) - (performance.now() - clock.mono)) <= 1_000
+            ? clock.offset : undefined;
+        const age = Date.now() + (offset ?? 0) - Date.parse(event.created_at);
+        if (form && age > (offset === undefined ? FORM_STALE_LOCAL_MS : FORM_STALE_MS)) {
+            // The record is acknowledged: no answer reaches Pachca now, and the employee may have sent the form again.
+            process.stderr.write(`Отправка формы ${name} пропущена: срок ответа вышел, сотрудник уже видел ошибку отправки\n`);
+            return;
+        }
+        const payload = withFreshTimestamp(event.payload);
+        const body = JSON.stringify(payload);
+        // The record id stays the same for every attempt and every run, like the key of one webhook delivery.
+        const headers = { 'content-type': 'application/json', 'idempotency-key': event.id };
+        if (secret)
+            headers['pachca-signature'] = createHmac('sha256', secret).update(body).digest('hex');
+        let response;
+        try {
+            response = await fetch(target, {
+                method: 'POST', headers, body, redirect: 'manual',
+                signal: AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]),
+            });
+        }
+        catch {
+            if (signal.aborted)
+                return;
+            throw new Error(`Не удалось переслать событие ${name}, запись сохранена в истории`);
+        }
+        if (form && (response.status === 400 || response.status === 422)) {
+            const errors = await this.formErrors(response);
+            if (!errors)
+                throw new Error(`Обработчик ответил HTTP ${response.status} на форму ${name} без объекта errors, запись сохранена в истории`);
+            await this.answerForm(form, errors);
+            return;
+        }
+        await response.body?.cancel();
+        if (!response.ok)
+            throw new Error(`Обработчик ответил HTTP ${response.status} на событие ${name}, запись сохранена в истории`);
+        if (form)
+            await this.answerForm(form);
+    }
+    /** `errors` from a 400 or 422 reply: field name to the text shown under that field. */
+    async formErrors(response) {
+        try {
+            const body = await response.json();
+            const errors = body?.errors;
+            if (!errors || typeof errors !== 'object' || Array.isArray(errors))
+                return undefined;
+            const entries = Object.entries(errors);
+            if (!entries.length || !entries.every(([, value]) => typeof value === 'string'))
+                return undefined;
+            return Object.fromEntries(entries);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * A bot without a webhook URL closes the form with a method: the reply a handler gives to a
+     * webhook goes on to Pachca the same way, closing the form or showing errors under its fields.
+     * The handler has already acted on the submission, and the 5 seconds for an answer do not come
+     * back, so a refused answer is reported and the record is still acknowledged.
+     */
+    async answerForm(form, errors) {
+        if (!this.answerForms)
+            return;
+        // 503: Pachca kept the submission open, so the same call a moment later can still close the form.
+        // Repeating is safe: an answer already taken, or one past the 5 seconds, gets 410.
+        for (let attempt = 0;; attempt++) {
+            try {
+                await this.apiRequest({
+                    method: 'POST',
+                    path: `/views/${encodeURIComponent(form.view_id)}/submit_response`,
+                    body: { submit_id: form.submit_id, ...(errors ? { errors } : {}) },
+                });
+                return;
+            }
+            catch (error) {
+                if (!(error instanceof ApiError))
+                    throw error;
+                if (error.details.code === 503 && attempt < 2) {
+                    await new Promise((resolve) => setTimeout(resolve, 500));
+                    continue;
+                }
+                const reason = error.details.code === 410
+                    ? 'время вышло или ответ уже отправлен'
+                    : `HTTP ${error.details.code ?? 'без ответа'}: ${error.details.error}`;
+                process.stderr.write(`Ответ на форму ${form.submit_id} не передан в Пачку: ${reason}\n`);
+                return;
+            }
+        }
+    }
+}

package/dist/commands/bots/update-webhook.js

@@ -13,14 +13,14 @@ export default class BotsUpdateWebhook extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         'outgoing-url': Flags.string({
-            description: "URL исходящего вебхука. Пустая строка отключает вебхук. (макс. 255 символов)",
+            description: "URL исходящего вебхука: публичный адрес с протоколом `http` или `https`. Иначе ответ `400` на поле `webhook.outgoing_url` с кодом `webhook_url_invalid`, `webhook_url_unresolved` или `webhook_url_forbidden`. Пустая строка отключает вебхук. (макс. 255 символов)",
         }),
     };
     async run() {
         const { args, flags } = await this.parse(BotsUpdateWebhook);
         this.parsedFlags = flags;
         const missingRequired = [
-            { flag: 'outgoing-url', label: "URL исходящего вебхука. Пустая строка отключает вебхук.", type: 'string' },
+            { flag: 'outgoing-url', label: "URL исходящего вебхука: публичный адрес с протоколом `http` или `https`. Иначе ответ `400` на поле `webhook.outgoing_url` с кодом `webhook_url_invalid`, `webhook_url_unresolved` или `webhook_url_forbidden`. Пустая строка отключает вебхук.", type: 'string' },
         ].filter((f) => flags[f.flag] === undefined || flags[f.flag] === null);
         if (missingRequired.length > 0) {
             if (this.isInteractive()) {

package/dist/commands/bots/update.js

@@ -23,7 +23,7 @@ export default class BotsUpdate extends BaseCommand {
             description: "Никнейм бота: латинские буквы, цифры и `_`, в конце `_bot`, свободный в пространстве. Ник не по формату отвечает `400` на поле `bot.nickname` с кодом `invalid`, а занятый ник — с кодом `taken`. (макс. 255 символов)",
         }),
         'outgoing-url': Flags.string({
-            description: "URL исходящего вебхука (макс. 255 символов)",
+            description: "URL исходящего вебхука: публичный адрес с протоколом `http` или `https`. Иначе ответ `400` на поле `webhook.outgoing_url` с кодом `webhook_url_invalid`, `webhook_url_unresolved` или `webhook_url_forbidden`. (макс. 255 символов)",
         }),
         'events': Flags.string({
             description: "События, на которые подписан бот. Список заменяется целиком.",
@@ -38,7 +38,7 @@ export default class BotsUpdate extends BaseCommand {
             description: "Скоупы (права доступа) токена бота. Если не указано, бот получает набор по умолчанию. Боту доступны не все скоупы: часть из них разрешена только пользовательским ролям, и попытка назначить такой скоуп возвращает `400`. Служебные значения `bot` и `all` назначать нельзя.",
         }),
         'template': Flags.string({
-            description: "Шаблон форматирования входящего вебхука",
+            description: "Шаблон форматирования входящего вебхука. Шаблон проверяется, когда в запросе меняются `template`, `template_engine` или `kind`, поэтому смена одного шаблонизатора или включение `kind: simple` проверяет и уже сохранённый шаблон. Шаблон с синтаксической ошибкой у источника `simple` даёт ответ `400` на этом поле с кодом `invalid`, и запрос не применяется. Причина приходит в `message`.",
         }),
         'template-engine': Flags.string({
             description: "Шаблонизатор для обработки шаблона входящего вебхука",

package/dist/commands/chats/list.js

@@ -16,7 +16,7 @@ export default class ChatsList extends BaseCommand {
             default: "id",
         }),
         'order': Flags.string({
-            description: "Направление сортировки. Применяется вместе с `sort`, например `sort=last_message_at&order=desc`. Без `sort` чаты идут по убыванию `id` при любом `order`.",
+            description: "Направление сортировки по полю `sort`, например `sort=last_message_at&order=desc`. Без `sort` направление применяется к `id`.",
             options: ["asc", "desc"],
             default: "desc",
         }),

package/dist/commands/doctor.js

@@ -22,14 +22,14 @@ export default class Doctor extends BaseCommand {
         let networkOk = false;
         // 1. Node.js version
         const nodeVersion = process.version.replace('v', '');
-        const nodeMajor = Number.parseInt(nodeVersion.split('.')[0], 10);
-        if (nodeMajor >= 20) {
-            checks.push({ name: 'node', status: 'ok', version: nodeVersion, required: '>=20' });
-            this.printCheck('ok', `Node.js        v${nodeVersion} (требуется >=20)`, format);
+        // AbortSignal.any (bots listen-events --forward-to) arrived in Node 20.3.0.
+        if (semver.satisfies(nodeVersion, '>=20.3.0')) {
+            checks.push({ name: 'node', status: 'ok', version: nodeVersion, required: '>=20.3.0' });
+            this.printCheck('ok', `Node.js        v${nodeVersion} (требуется >=20.3.0)`, format);
         }
         else {
-            checks.push({ name: 'node', status: 'error', version: nodeVersion, required: '>=20' });
-            this.printCheck('error', `Node.js        v${nodeVersion} — требуется >=20`, format);
+            checks.push({ name: 'node', status: 'error', version: nodeVersion, required: '>=20.3.0' });
+            this.printCheck('error', `Node.js        v${nodeVersion} — требуется >=20.3.0`, format);
         }
         // 2. Network. Check the host the CLI actually talks to: on-premise installs
         // point elsewhere, and probing the cloud there reports a healthy network

package/dist/commands/messages/list.js

@@ -26,7 +26,7 @@ export default class MessagesList extends BaseCommand {
             default: "id",
         }),
         'order': Flags.string({
-            description: "Направление сортировки. Применяется вместе с `sort`: сообщения от старых к новым дают `sort=id` и `order=asc`. Без `sort` сообщения идут от новых к старым при любом `order`.",
+            description: "Направление сортировки по `id`: `asc` отдаёт сообщения от старых к новым, `desc` от новых к старым.",
             options: ["asc", "desc"],
             default: "desc",
         }),

package/dist/commands/users/update.js

@@ -40,7 +40,7 @@ export default class UsersUpdate extends BaseCommand {
             description: "Уровень доступа",
         }),
         'chat-ids': Flags.string({
-            description: "Чат, в котором останется сотрудник при переводе в гости (`role: \"guest\"`): ровно одна активная беседа или канал, куда у токена есть право добавлять участников. Без такого чата ответ `400` по этому полю, и не меняется ничего. При других ролях и у того, кто уже гость, поле не учитывается.",
+            description: "Чат, в котором останется сотрудник при переводе в гости (`role: \"guest\"`): ровно одна активная беседа или канал, куда у токена есть право добавлять участников. Без такого чата ответ `400` по этому полю, и не меняется ничего. При других ролях и у того, кто уже гость, поле не учитывается. При переводе в гости сотруднику с указанной почтой уходит письмо о смене роли со ссылкой на этот чат, даже если он ещё не входил в Пачку или приостановлен. В суточный лимит писем-приглашений оно не идёт.",
         }),
         'suspended': Flags.boolean({
             description: "Деактивация пользователя. Владельца пространства приостановить нельзя никому, в том числе ему самому: ответ `403`.",

package/dist/data/changelog.json

@@ -1,4 +1,59 @@
 [
+    {
+        "version": "2026.11.2",
+        "date": "10 ноября 2026",
+        "changes": [
+            {
+                "type": "+",
+                "command": "bots listen-events",
+                "description": "События бота в реальном времени без публичного адреса: JSONL в терминале или пересылка на локальный обработчик, как исходящий вебхук, с подписью, свежим `webhook_timestamp` и ответом на отправку формы. Запись удаляется из истории после ответа 2xx."
+            },
+            {
+                "type": "~",
+                "description": "Для запуска CLI требуется Node.js 20.3.0 или новее"
+            }
+        ]
+    },
+    {
+        "version": "2026.11.1",
+        "date": "9 ноября 2026",
+        "changes": [
+            {
+                "type": "~",
+                "command": "auth status",
+                "description": "Показывает токен, с которым работают команды, в том числе из `--token` и `PACHCA_TOKEN`. Владельца, права и срок жизни такого токена команда спрашивает у сервера и называет сохранённый профиль, который не используется, пока задан `PACHCA_TOKEN`."
+            },
+            {
+                "type": "~",
+                "description": "Подсказки к отказу `insufficient_scope` ведут к `pachca auth status` с тем же `--token` или `--profile`, что у команды, а для сохранённого профиля в `-o json` ещё и с `--remote`"
+            },
+            {
+                "type": "~",
+                "command": "auth login",
+                "description": "Подсказка `pachca auth status` после входа называет профиль, если без него команда покажет другой токен, а при заданном `PACHCA_TOKEN` вход предупреждает, что команды используют переменную"
+            },
+            {
+                "type": "+",
+                "command": "messages get, messages list, messages create, messages update, search list-messages",
+                "description": "В ответах с сообщениями есть поля `source` и `application`: через что сотрудник отправил сообщение и какая программа"
+            },
+            {
+                "type": "~",
+                "command": "chats list, messages list",
+                "description": "`--order` без `--sort` задаёт направление по `id`"
+            },
+            {
+                "type": "~",
+                "command": "bots create, bots update, bots update-webhook",
+                "description": "В описании адреса вебхука коды отказа, а в описании шаблона проверка синтаксиса"
+            },
+            {
+                "type": "~",
+                "command": "users update",
+                "description": "В описании чата для перевода в гости письмо о смене роли"
+            }
+        ]
+    },
     {
         "version": "2026.11.0",
         "date": "4 ноября 2026",