zaytsv-bot-graph-mcp 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zaytsv-bot-graph-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server to build and publish Telegram bot funnels in the zaytsv /bots service. Zero dependencies.",
   "type": "module",
   "bin": { "zaytsv-bot-graph-mcp": "src/index.mjs" },

package/skills/build-bot-funnel/SKILL.md

@@ -20,7 +20,8 @@ description: Собрать воронку (сценарий) Telegram-бота
    - У каждого `SEND_MESSAGE` непустой `config.text` (и продублируй в `cards[0].text`).
    - id узлов и рёбер — валидные UUID, уникальные.
    - Есть хотя бы один корневой `TRIGGER_*`; все нелистовые узлы достижимы от триггера; синхронных циклов нет (цикл только через `ASK_QUESTION`/`DELAY`/`SCHEDULE`).
-   - Кнопки-выборы разведены по хэндлам `btn_N`; условия — `yes`/`no`; вопрос — `valid`/`invalid`.
+   - Кнопки-выборы разведены по хэндлам `btn_N`; условия `CONDITION` — `yes`/`no`; вопрос — `valid`/`invalid`.
+   - `CONDITION` умеет: теги, переменные, UTM-метки, имя/email/телефон из профиля, @username, подписку на канал (`SUBSCRIBED`), дату/время/день недели. Полная таблица `kind`/`op` — в schema.md.
 
 4. **Проверь локально** перед заливкой:
    ```bash

package/skills/build-bot-funnel/reference/schema.md

@@ -46,7 +46,7 @@
 - `SEND_PHOTO` — `{ "photoUrl": "https://...", "text": "подпись (необязательно)" }`
 
 ### Логика / ветвление
-- `CONDITION` — выходы `yes` / `no`. `{ "match":"ALL"|"ANY", "conditions":[ { "kind":"...", "op":"...", "key":"...", "value":"..." } ] }`
+- `CONDITION` — проверка условий, выходы `yes` / `no`. `{ "match":"ALL"|"ANY", "conditions":[ { "kind":"...", "op":"...", "key":"...", "value":"..." } ] }`. `match:"ALL"` — все условия истинны; `"ANY"` — хотя бы одно. Полный список `kind`/`op`/полей — в разделе [«Условия CONDITION»](#условия-condition).
 - `BRANCH` — `{ "cases":[ {"id":"c1","label":"...","expression":"var.x=='a'"} ], "hasDefault": false, "abTest": false }`. Выходы: `case_<id>` (+ `default`).
 - `ASK_QUESTION` — вопрос со сбором ответа. `{ "promptText":"...","saveTo":"name","validator":"ANY"|"PHONE"|"EMAIL"|"REGEX","regex":"...","retryText":"...","maxAttempts":3 }`. Выходы `valid` / `invalid`.
 - `END` — `{}` (конец ветки).
@@ -65,6 +65,28 @@
 - `CALL_WEBHOOK` — `{ "url":"https://...", "method":"POST", "bodyTemplate":"{...}", "timeoutMs":5000 }`. Выходы `ok` / `error`.
 - `AI_REPLY`, `PAYMENT_LINK`.
 
+## Условия CONDITION
+
+Каждый элемент `conditions[]` — `{ "kind", "op", ...поля }`. Любая внутренняя ошибка условия = `false` (узел уходит в `no`).
+
+| `kind` | `op` (допустимые) | Поля | Что проверяет |
+|---|---|---|---|
+| `TAG` | `HAS`, `NOT_HAS` | `value` — метка `[a-z0-9_-]{1,64}` | есть ли у пользователя тег |
+| `VARIABLE` | `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY`, `GT`, `LT` | `key` — имя переменной `[a-z_][a-z0-9_]{0,63}`, `value` | значение переменной (`GT`/`LT` — числовое сравнение) |
+| `UTM` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `key` ∈ `source`/`medium`/`campaign`/`content`/`term`, `value` | UTM-метку клика (`utm_<key>`), регистронезависимо |
+| `NAME` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `value` | имя из профиля, регистронезависимо |
+| `EMAIL` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `value` | email из профиля |
+| `PHONE` | `EQUALS`, `CONTAINS`, `NOT_EMPTY`, `EMPTY` | `value` | телефон из профиля |
+| `USERNAME` | `EQUALS`, `CONTAINS` | `value` | @username пользователя Telegram |
+| `SUBSCRIBED` | `SUBSCRIBED`, `NOT_SUBSCRIBED` | `key` — **числовой** id канала/группы (напр. `-1001234567890`) | подписан ли пользователь на канал бота |
+| `CURRENT_DATE` | `BEFORE`, `AFTER`, `EQUALS` | `value` — дата `YYYY-MM-DD` | сегодняшнюю дату (МСК) |
+| `CURRENT_TIME` | `BETWEEN` | `value`, `value2` — время `HH:mm` | текущее время в интервале (через полночь — если `value`>`value2`) |
+| `DAY_OF_WEEK` | `IN` | `days` — массив из `MON`,`TUE`,`WED`,`THU`,`FRI`,`SAT`,`SUN` | день недели (МСК) |
+
+Для `NOT_EMPTY`/`EMPTY` поле `value` не нужно. `UTM` без `key` всегда `false`.
+
+**`SUBSCRIBED`** работает только если бот **админ** в канале/группе и канал «привязан» (бот узнаёт о членстве через хук `my_chat_member` — добавь бота в канал админом). `key` должен парситься в число, иначе условие = `false`. Профильные поля (`NAME`/`EMAIL`/`PHONE`) и UTM заполняются по ходу воронки (`ASK_QUESTION`→`saveTo`, диплинк-клик с UTM).
+
 ## Выходные хэндлы (`sourceHandle`) — шпаргалка
 | Узел | Хэндлы |
 |---|---|

package/skills/build-bot-funnel/reference/validation.md

@@ -30,6 +30,7 @@
 - `TRIGGER_TEXT`: `matchMode` ∈ {ANY,EQUALS,CONTAINS,REGEX}; для не-ANY нужен `value`.
 - `ASK_QUESTION`: `promptText` обязателен; `saveTo` ∈ `[a-z_][a-z0-9_]{0,63}`.
 - `BRANCH`: ≥1 case; выражения валидны (или `abTest:true`).
+- `CONDITION`: `match` ∈ {ALL, ANY} (`CONDITION_BAD_MATCH`); ≥1 элемент в `conditions` (`CONDITION_EMPTY`). Для `kind:"TAG"` — `value` ∈ `[a-z0-9_-]{1,64}` (`CONDITION_BAD_TAG`); для `kind:"VARIABLE"` — `key` ∈ `[a-z_][a-z0-9_]{0,63}` (`CONDITION_BAD_KEY`). Остальные `kind` (UTM/NAME/EMAIL/PHONE/USERNAME/SUBSCRIBED/CURRENT_*/DAY_OF_WEEK) бэкенд проверяет в рантайме — некорректный `kind`/`op` или нечисловой `key` у `SUBSCRIBED` молча дают `false` (выход `no`), публикацию не блокируют. Список `kind`/`op` — в schema.md.
 - `CALL_WEBHOOK`: `url` обязателен, http(s)://.
 - `DELAY`: `FIXED` с `durationSec>0`, либо `UNTIL` с `isoDate`+`time`.
 - Метки: `[a-z0-9_-]{1,64}`. Переменные: `[a-z_][a-z0-9_]{0,63}`.

package/skills/build-bot-funnel/validate.mjs

@@ -19,6 +19,22 @@ const warns = [];
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const VAR_RE = /^[a-z_][a-z0-9_]{0,63}$/;
+const TAG_RE = /^[a-z0-9_-]{1,64}$/;
+
+// kind -> допустимые op (для подсказок; бэкенд блокирует только TAG/VARIABLE)
+const COND_OPS = {
+  TAG: ["HAS", "NOT_HAS"],
+  VARIABLE: ["EQUALS", "NOT_EQUALS", "CONTAINS", "NOT_EMPTY", "EMPTY", "GT", "LT"],
+  UTM: ["EQUALS", "CONTAINS", "NOT_EMPTY", "EMPTY"],
+  NAME: ["EQUALS", "CONTAINS", "NOT_EMPTY", "EMPTY"],
+  EMAIL: ["EQUALS", "CONTAINS", "NOT_EMPTY", "EMPTY"],
+  PHONE: ["EQUALS", "CONTAINS", "NOT_EMPTY", "EMPTY"],
+  USERNAME: ["EQUALS", "CONTAINS"],
+  SUBSCRIBED: ["SUBSCRIBED", "NOT_SUBSCRIBED"],
+  CURRENT_DATE: ["BEFORE", "AFTER", "EQUALS"],
+  CURRENT_TIME: ["BETWEEN"],
+  DAY_OF_WEEK: ["IN"],
+};
 
 // cardsToLegacy: текст = первая text-карточка с непустым text (или image.url -> photoUrl)
 function cardsToLegacy(cards) {
@@ -99,6 +115,26 @@ for (const n of nodes) {
     case "BRANCH":
       if (!Array.isArray(c.cases) || c.cases.length === 0) errors.push(`${who}: нужен хотя бы один case.`);
       break;
+    case "CONDITION": {
+      if (c.match !== "ALL" && c.match !== "ANY") errors.push(`CONDITION_BAD_MATCH: ${who} — match ∈ {ALL,ANY}.`);
+      if (!Array.isArray(c.conditions) || c.conditions.length === 0) {
+        errors.push(`CONDITION_EMPTY: ${who} — нужно хотя бы одно условие.`);
+        break;
+      }
+      c.conditions.forEach((cond, i) => {
+        if (!cond || typeof cond !== "object") { errors.push(`${who}: условие #${i + 1} — не объект.`); return; }
+        const kind = cond.kind;
+        // Бэкенд блокирует публикацию только для TAG.value и VARIABLE.key:
+        if (kind === "TAG" && !TAG_RE.test(String(cond.value || ""))) errors.push(`CONDITION_BAD_TAG: ${who} — TAG.value ∈ [a-z0-9_-]{1,64}.`);
+        if (kind === "VARIABLE" && !VAR_RE.test(String(cond.key || ""))) errors.push(`CONDITION_BAD_KEY: ${who} — VARIABLE.key ∈ [a-z_][a-z0-9_]{0,63}.`);
+        // Остальное — подсказки (рантайм бэкенда отдаст false, но публикацию не сорвёт):
+        if (!COND_OPS[kind]) warns.push(`${who}: неизвестный kind «${kind}» в условии #${i + 1} — рантайм даст false.`);
+        else if (cond.op && !COND_OPS[kind].includes(cond.op)) warns.push(`${who}: op «${cond.op}» не из {${COND_OPS[kind].join(",")}} для ${kind} — рантайм даст false.`);
+        if (kind === "SUBSCRIBED" && !/^-?\d+$/.test(String(cond.key || "").trim())) warns.push(`${who}: SUBSCRIBED.key должен быть числовым id канала — иначе false (и бот должен быть админом канала).`);
+        if (kind === "UTM" && !cond.key) warns.push(`${who}: UTM без key — рантайм даст false (ожидается source/medium/campaign/content/term).`);
+      });
+      break;
+    }
   }
 }
 

package/src/index.mjs

@@ -21,7 +21,7 @@ import os from "node:os";
 import fs from "node:fs";
 import path from "node:path";
 
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 const BASE = (process.env.ZAYTSV_BASE_URL || "https://zaytsv.ru").replace(/\/+$/, "");
 const CONFIG_DIR = path.join(os.homedir(), ".zaytsv-bot-graph");
 const TOKEN_FILE = path.join(CONFIG_DIR, "token");