@besales/mcp 0.48.0 → 1.0.0-beta.2

package/scripts/sync-trigger-argument-schema.mjs

@@ -0,0 +1,121 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import openapiTS from 'openapi-typescript';
+import { z } from 'zod';
+import { linkTrackingTools } from '../dist/tools/definitions/link-tracking.js';
+import { triggerActionArgumentSchema } from '../dist/tools/definitions/trigger-argument.schema.js';
+import { toolDefinitions } from '../dist/tools/definitions.js';
+import { triggerActionItemSchema } from '../dist/tools/definitions/platform-setup.js';
+import { canonicalCallOperatorTaskSchema } from '../dist/tools/definitions/call-operator-task.schema.js';
+
+// Границы опубликованных полей — из контракта выбранного API checkout, не из ручного JSON.
+const contractsDir = process.env.BESALES_API_CONTRACTS_DIR?.trim() || '../besales-api/contracts';
+let callOperator;
+await openapiTS(pathToFileURL(resolve(contractsDir, 'openapi-besales-api.yaml')), {
+  transform(schema) {
+    if (schema.properties?.step_type?.enum?.includes('CALL_OPERATOR') && schema.properties.task_text && schema.properties.task_due_hours) callOperator = schema;
+  },
+});
+if (!callOperator?.properties?.task_text || !callOperator.properties.task_due_hours) {
+  throw new Error('CALL_OPERATOR_TASK_CONTRACT_MISSING');
+}
+const action = z.toJSONSchema(triggerActionItemSchema, {
+  target: 'draft-7',
+  io: 'input',
+});
+delete action.$schema;
+const canonical = z.toJSONSchema(canonicalCallOperatorTaskSchema, {
+  target: 'draft-7',
+  io: 'input',
+});
+for (const [name, alias] of [
+  ['task_text', 'taskText'],
+  ['task_due_hours', 'taskDueHours'],
+]) {
+  const property = callOperator.properties[name];
+  const nullable = property.anyOf?.some((branch) => branch.type === 'null');
+  const value = property.anyOf?.find((branch) => branch.type !== 'null');
+  const runtime = canonical.properties[name].anyOf.find((branch) => branch.type !== 'null');
+  // refine считает Unicode; JSON Schema maxLength считает те же кодовые точки.
+  if (
+    !nullable ||
+    (name === 'task_text'
+      ? value?.type !== 'string' || value.maxLength !== 500
+      : value?.type !== runtime.type ||
+        value.minimum !== runtime.minimum ||
+        value.maximum !== runtime.maximum)
+  ) {
+    throw new Error(`CALL_OPERATOR_TASK_CONTRACT_DRIFT:${name}`);
+  }
+  canonical.properties[name] = {
+    ...property,
+    description: canonical.properties[name].description,
+  };
+  action.properties.callOperatorConfig.properties[alias] = {
+    ...property,
+    description: action.properties.callOperatorConfig.properties[alias].description,
+  };
+}
+action.properties.config = {
+  ...action.properties.config,
+  properties: canonical.properties,
+};
+
+// Публикуемые объявления берутся из исполняемой схемы: refine не обещает maxLength в JSON Schema.
+const target = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const registry = JSON.parse(readFileSync(target, 'utf8'));
+// Assigned Instagram branches follow their executable schemas, including omission/null.
+for (const [name, field] of [
+  ['besales_platform_settings_update', 'instagram_comment_behavior'],
+  ['besales_trigger_upsert', 'instagram_comment_kind'],
+]) {
+  const definition = toolDefinitions.find((entry) => entry.name === name);
+  const schema = definition?.schema.shape?.[field];
+  const tool = registry.tools.find((entry) => entry.name === name);
+  if (!schema || !tool?.inputSchema?.properties) throw new Error(`INSTAGRAM_SCHEMA_MISSING:${name}`);
+  const published = z.toJSONSchema(schema, { target: 'draft-7', io: 'input' });
+  delete published.$schema;
+  tool.inputSchema.properties[field] = published;
+}
+const argument = z.toJSONSchema(triggerActionArgumentSchema, { target: 'draft-7', io: 'input' });
+delete argument.$schema;
+for (const name of ['besales_trigger_upsert']) {
+  const tool = registry.tools.find((entry) => entry.name === name);
+  if (!tool?.inputSchema?.properties?.arguments)
+    throw new Error(`TRIGGER_ARGUMENT_SCHEMA_MISSING:${name}`);
+  tool.inputSchema.properties.arguments.items = argument;
+  if (!tool.inputSchema.properties.actions)
+    throw new Error(`TRIGGER_ACTION_SCHEMA_MISSING:${name}`);
+  const publishedAction = tool.inputSchema.properties.actions.items;
+  publishedAction.properties.callOperatorConfig = action.properties.callOperatorConfig;
+  publishedAction.properties.config = action.properties.config;
+}
+// Поля каталога публикуются из исполняемой схемы: null очистки и refine входят в носитель.
+for (const name of ['besales_tracked_link_create', 'besales_tracked_link_update']) {
+  const definition = linkTrackingTools.find((entry) => entry.name === name);
+  const tool = registry.tools.find((entry) => entry.name === name);
+  if (!definition || !tool) throw new Error(`LINK_CATALOG_SCHEMA_MISSING:${name}`);
+  const derived = z.toJSONSchema(definition.schema, { target: 'draft-7', io: 'input' });
+  delete derived.$schema;
+  if (!derived.properties?.personal_url_variable)
+    throw new Error(`PERSONAL_URL_SCHEMA_MISSING:${name}`);
+  if (!derived.properties.personal_url_variable.description)
+    throw new Error(`PERSONAL_URL_DESCRIPTION_MISSING:${name}`);
+  // Остальные поля сохраняют принятые описания lpv; добавляется только новый контракт.
+  let personalUrlVariable = derived.properties.personal_url_variable;
+  if (name === 'besales_tracked_link_update') {
+    const { anyOf, ...metadata } = personalUrlVariable;
+    if (anyOf?.length !== 2 || anyOf[0].type !== 'string' || anyOf[1].type !== 'null') {
+      throw new Error(`PERSONAL_URL_NULLABLE_SCHEMA_UNEXPECTED:${name}`);
+    }
+    // Отгруженная форма сохраняет ограничения строки и отдельное разрешение очистки через null.
+    personalUrlVariable = { ...anyOf[0], ...metadata, type: ['string', 'null'] };
+  }
+  tool.inputSchema.properties.personal_url_variable = personalUrlVariable;
+}
+const serialized = `${JSON.stringify(registry, null, 2)}\n`;
+writeFileSync(target, serialized);
+// Уже собранный пакет и публикуемый исходник обязаны рекламировать одинаковые ограничения.
+mkdirSync(new URL('../dist/schemas/', import.meta.url), { recursive: true });
+writeFileSync(new URL('../dist/schemas/mcp-tools.json', import.meta.url), serialized);

package/scripts/sync-trigger-repeat-mapping.mjs

@@ -0,0 +1,12 @@
+import { copyFileSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+// Межрепозиторный маппер переносится из явного канонического входа, без второй копии правила.
+const source = process.env.BESALES_TRIGGER_REPEAT_MAPPING_SOURCE;
+if (!source) throw new Error('BESALES_TRIGGER_REPEAT_MAPPING_SOURCE обязателен');
+const destination = new URL('../src/shared/utils/trigger-repeat-mapping.ts', import.meta.url);
+if (process.argv.includes('--check')) {
+  if (!readFileSync(resolve(source)).equals(readFileSync(destination))) {
+    throw new Error('Маппер повторов моста разошёлся с каноническим маппером переноса');
+  }
+} else copyFileSync(resolve(source), destination);

package/scripts/sync-voice-actions-contract.mjs

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { load } from 'js-yaml';
+import ts from 'typescript';
+
+// Узкий срез принятого API: не обновляет соседние устаревшие контракты моста.
+const apiFile = resolve(
+  process.env.BESALES_API_CONTRACTS_DIR || '../besales-api/contracts',
+  'openapi-besales-api.yaml',
+);
+const schemas = load(readFileSync(apiFile, 'utf8')).components.schemas;
+const voiceConfigs = Object.fromEntries(
+  schemas.AgentActionStepViewDto.properties.config.oneOf
+    .filter((schema) =>
+      ['VOICE_INITIATE_OUTBOUND_CALL', 'VOICE_TRANSFER_CALL'].includes(
+        schema.properties?.step_type?.enum?.[0],
+      ),
+    )
+    .map((schema) => [schema.properties.step_type.enum[0], schema]),
+);
+const purchased = schemas.ListConversationsQueryDto.properties.purchased;
+const hasPurchase = schemas.ConversationListRowDto.properties.hasPurchase;
+const mapperFile = resolve(apiFile, '../../src/control/agent-config/trigger-action.mapper.ts');
+const mapperText = readFileSync(mapperFile, 'utf8');
+const mapper = ts.createSourceFile(mapperFile, mapperText, ts.ScriptTarget.Latest, true);
+const relationNames = [];
+function visit(node) {
+  if (
+    ts.isVariableDeclaration(node) &&
+    node.name.getText(mapper) === 'LEGACY_STEP_MAPPINGS' &&
+    node.initializer &&
+    ts.isObjectLiteralExpression(node.initializer)
+  ) {
+    for (const property of node.initializer.properties) {
+      if (!ts.isPropertyAssignment(property)) throw new Error('VOICE_RELATION_MAPPING_UNREADABLE');
+      relationNames.push(property.name.getText(mapper).replace(/^['"]|['"]$/gu, ''));
+    }
+  }
+  ts.forEachChild(node, visit);
+}
+visit(mapper);
+if (
+  Object.keys(voiceConfigs).length !== 2 ||
+  purchased?.type !== 'boolean' ||
+  hasPurchase?.type !== 'boolean' ||
+  relationNames.length < 30
+)
+  throw new Error('VOICE_PURCHASE_API_CONTRACT_MISSING');
+writeFileSync(
+  new URL('../src/schemas/voice-actions-api.contract.json', import.meta.url),
+  JSON.stringify(
+    {
+      source: {
+        file: 'besales-api/contracts/openapi-besales-api.yaml',
+        sha256: createHash('sha256').update(readFileSync(apiFile)).digest('hex'),
+        relationMapperSha256: createHash('sha256').update(mapperText).digest('hex'),
+      },
+      voiceConfigs,
+      purchased,
+      hasPurchase,
+      relationNames,
+    },
+    null,
+    2,
+  ) + '\n',
+);

package/scripts/sync-voice-actions-tools.mjs

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+const registryFile = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const registry = JSON.parse(readFileSync(registryFile, 'utf8'));
+const contract = JSON.parse(
+  readFileSync(new URL('../src/schemas/voice-actions-api.contract.json', import.meta.url), 'utf8'),
+);
+const trigger = registry.tools.find((tool) => tool.name === 'besales_trigger_upsert');
+const item = trigger.inputSchema.properties.actions.items;
+delete item.required;
+item.anyOf = ['actionType', 'stepType', 'type'].map((field) => ({ required: [field] }));
+item.properties.stepType = {
+  type: 'string',
+  description:
+    'Канонический тип шага v2; для звонков VOICE_INITIATE_OUTBOUND_CALL / VOICE_TRANSFER_CALL.',
+};
+item.properties.type = { type: 'string', description: 'Совместимое имя типа действия.' };
+for (const [type, keys] of Object.entries({
+  VOICE_INITIATE_OUTBOUND_CALL: ['initiateOutboundCall', 'initiateOutboundCallConfig'],
+  VOICE_TRANSFER_CALL: ['transferCall', 'transferCallConfig'],
+})) {
+  for (const key of keys) {
+    const schema = structuredClone(contract.voiceConfigs[type]);
+    delete schema.required;
+    schema.additionalProperties = true;
+    item.properties[key] = {
+      anyOf: [{}, schema],
+      description:
+        'Совместимый ввод голосового конфига. Используй один config или одно прежнее имя; relation вместе с input, даже null, отклоняется до HTTP.',
+    };
+  }
+}
+const hint =
+  ' Голосовые шаги: канон stepType=VOICE_INITIATE_OUTBOUND_CALL / VOICE_TRANSFER_CALL и config. Старые initiateOutboundCall/initiateOutboundCallConfig и transferCall/transferCallConfig принимаются как ввод. Конфликты и непустой чужой конфиг отклоняются до HTTP; снимается только служебное эхо верхнего уровня, вложенные поля сохраняются. Редактирование не выполняет звонок или перевод.';
+if (!trigger.description.includes('Голосовые шаги: канон')) trigger.description += hint;
+const query = registry.tools.find((tool) => tool.name === 'besales_dialogues_query');
+Object.assign(query.inputSchema.properties, {
+  source: {
+    type: 'string',
+    enum: ['export', 'inbox'],
+    description:
+      'По умолчанию export — прежняя выгрузка. inbox — список Входящих с серверным признаком покупки, отдельный маршрут и набор фильтров.',
+  },
+  channel_id: {
+    type: 'string',
+    format: 'uuid',
+    description: 'Только source=inbox: ограничить область покупки каналом.',
+  },
+  contact_id: { type: 'string', format: 'uuid' },
+  purchased: contract.purchased,
+  has_payment: {
+    type: 'boolean',
+    description: 'Только source=inbox: оплата независимо от покупки.',
+  },
+  with_totals: {
+    type: 'boolean',
+    description: 'Только source=inbox: ограниченные итоги первой страницы.',
+  },
+});
+const queryHint =
+  ' source=inbox читает Входящие через POST /workspaces/:workspaceId/conversations/search (scope read:conversations): purchased=true — заказ агента ИЛИ продажная стадия, false — нет обоих признаков. Это не оплата; has_payment независим. channel_id ограничивает область каналом, без него — видимыми каналами человека. hasPurchase, отбор и итоги считает API до пагинации. Продолжай с source=inbox, теми же фильтрами и cursor; with_totals только на первой странице, capped=true означает 999+. Фильтры выгрузки (action_type, даты, platform_ids и прочие) с inbox не смешиваются: отказ до HTTP.';
+if (!query.description.includes('source=inbox читает')) query.description += queryHint;
+writeFileSync(registryFile, JSON.stringify(registry, null, 2) + '\n');
+const mapFile = new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url);
+const rows = JSON.parse(readFileSync(mapFile, 'utf8')).filter(
+  (row) => row.tool !== 'besales_dialogues_query@inbox',
+);
+const id = '00000000-0000-4000-8000-000000000001';
+rows.push({
+  tool: 'besales_dialogues_query@inbox',
+  backendTarget: 'besales-api',
+  canonicalArgs: {
+    source: 'inbox',
+    workspace_id: id,
+    channel_id: id,
+    contact_id: id,
+    purchased: false,
+    has_payment: false,
+    with_totals: true,
+    limit: 2,
+    cursor: 'next',
+  },
+  expected: {
+    method: 'POST',
+    pathTemplate: '/workspaces/:workspaceId/conversations/search',
+    path: `/workspaces/${id}/conversations/search`,
+    body: {
+      channelId: id,
+      contactId: id,
+      purchased: false,
+      hasPayment: false,
+      withTotals: true,
+      limit: 2,
+      cursor: 'next',
+    },
+  },
+});
+writeFileSync(mapFile, JSON.stringify(rows, null, 2) + '\n');

package/scripts/sync-wave-id-schemas.mjs

@@ -0,0 +1,55 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+
+import { platformSetupWaveTools } from '../dist/tools/definitions/platform-setup-wave.js';
+
+// Ограничения берутся из исполняемых схем; подписи объясняют номера без имён таблиц.
+const numericPaths = {
+  besales_getcourse_wave_import: [
+    ['pipeline_id'],
+    ['status_id'],
+    ['group_id'],
+    ['preflight', 'offer_id'],
+  ],
+  besales_getcourse_wave_run_start: [['preflight', 'offer_id']],
+  besales_getcourse_wave_run_batch_start: [['segments', '[]', 'preflight', 'offer_id']],
+};
+const descriptions = {
+  pipeline_id: 'Номер воронки GetCourse: безопасное целое от нуля.',
+  status_id: 'Номер стадии GetCourse: безопасное целое от нуля.',
+  group_id: 'Номер группы GetCourse: безопасное целое от нуля.',
+  offer_id:
+    'Номер предложения GetCourse: безопасное целое от нуля. Сам по себе не выбирает сделки для отправки.',
+};
+
+function atPath(schema, path) {
+  return path.reduce(
+    (node, field) => (field === '[]' ? node?.items : node?.properties?.[field]),
+    schema,
+  );
+}
+
+const target = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const registry = JSON.parse(readFileSync(target, 'utf8'));
+for (const [name, paths] of Object.entries(numericPaths)) {
+  const definition = platformSetupWaveTools.find((tool) => tool.name === name);
+  const contract = registry.tools.find((tool) => tool.name === name);
+  if (!definition || !contract) throw new Error(`WAVE_TOOL_MISSING:${name}`);
+  const generated = z.toJSONSchema(definition.schema, {
+    target: 'draft-7',
+    io: 'input',
+  });
+  for (const path of paths) {
+    const published = atPath(contract.inputSchema, path);
+    const executable = atPath(generated, path);
+    if (!published || executable?.type !== 'integer') {
+      throw new Error(`WAVE_ID_SCHEMA_MISSING:${name}:${path.join('.')}`);
+    }
+    for (const key of Object.keys(published)) delete published[key];
+    Object.assign(published, executable, { description: descriptions[path.at(-1)] });
+  }
+}
+const serialized = `${JSON.stringify(registry, null, 2)}\n`;
+writeFileSync(target, serialized);
+mkdirSync(new URL('../dist/schemas/', import.meta.url), { recursive: true });
+writeFileSync(new URL('../dist/schemas/mcp-tools.json', import.meta.url), serialized);

package/scripts/tool-input-schemas.mjs

@@ -0,0 +1,46 @@
+// Схемы входа инструментов для выгрузки в besales-api: отгруженного реестра и ветки v2 — отдельными картами «имя →
+// схема».
+//
+// ⭐ Зачем серверу схемы. Навигация рабочей области называет ассистенту следующий инструмент и аргументы к нему.
+// Аргумент мимо схемы мост отвергнет или молча срежет, и шаг выполнится не тем, что обещано, — а сервер без схем
+// этого не видит. Какие инструменты назовёт навигация, эмиттер знать не может (файлов API у него нет), поэтому
+// выгружаются схемы ВСЕХ инструментов обоих реестров.
+//
+// ⛔ Схемы едут отдельными ключами верхнего уровня, а не полем записей `tools`: иначе меняются все записи и ломается
+// обещание «записи побайтово прежние».
+
+/**
+ * Карта «имя → схема входа», упорядоченная по имени: порядок реестра не должен шевелить выгрузку.
+ *
+ * @param {ReadonlyArray<{ name: string; inputSchema?: unknown }>} tools инструменты реестра
+ * @param {string} label название реестра для сообщения об отказе
+ * @returns {Record<string, unknown>}
+ */
+export function collectInputSchemas(tools, label) {
+  const schemas = new Map();
+  for (const tool of tools) {
+    if (typeof tool.name !== 'string' || tool.name.length === 0) {
+      throw new Error(`${label}: инструмент без имени`);
+    }
+    if (schemas.has(tool.name)) {
+      throw new Error(`${label}: инструмент ${tool.name} объявлен дважды`);
+    }
+    if (tool.inputSchema === null || typeof tool.inputSchema !== 'object') {
+      throw new Error(`${label}: у инструмента ${tool.name} нет схемы входа`);
+    }
+    schemas.set(tool.name, tool.inputSchema);
+  }
+  return Object.fromEntries([...schemas].sort(([left], [right]) => left.localeCompare(right)));
+}
+
+/**
+ * Имена выгруженных инструментов без схемы ветки v2. Непустой список — отказ выгрузки сразу, для всех инструментов:
+ * сторож навигации на сервере покраснел бы позже и только на своём инструменте.
+ *
+ * @param {ReadonlyArray<string>} names имена записей `tools`
+ * @param {Record<string, unknown>} v2Schemas карта схем ветки v2
+ * @returns {string[]}
+ */
+export function namesWithoutSchema(names, v2Schemas) {
+  return [...new Set(names)].filter((name) => !Object.hasOwn(v2Schemas, name)).sort();
+}

package/scripts/tool-input-schemas.spec.mjs

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { collectInputSchemas, namesWithoutSchema } from './tool-input-schemas.mjs';
+
+describe('collectInputSchemas — карта «имя → схема входа» для выгрузки', () => {
+  it('отдаёт схему каждого инструмента по имени, упорядоченно по имени', () => {
+    const actual = collectInputSchemas(
+      [
+        { name: 'besales_b', inputSchema: { type: 'object', properties: { b: { type: 'string' } } } },
+        { name: 'besales_a', inputSchema: { type: 'object', properties: {} } },
+      ],
+      'ветка v2',
+    );
+
+    expect(Object.keys(actual)).toEqual(['besales_a', 'besales_b']);
+    expect(actual.besales_b).toEqual({ type: 'object', properties: { b: { type: 'string' } } });
+  });
+
+  it('⛔ повтор имени — отказ, а не молча последняя схема', () => {
+    expect(() =>
+      collectInputSchemas(
+        [
+          { name: 'besales_a', inputSchema: { type: 'object' } },
+          { name: 'besales_a', inputSchema: { type: 'object', required: ['x'] } },
+        ],
+        'ветка v2',
+      ),
+    ).toThrow('besales_a объявлен дважды');
+  });
+
+  it('⛔ инструмент без схемы входа — отказ с именем реестра', () => {
+    expect(() => collectInputSchemas([{ name: 'besales_a' }], 'отгруженный реестр')).toThrow(
+      'отгруженный реестр: у инструмента besales_a нет схемы входа',
+    );
+  });
+});
+
+describe('namesWithoutSchema — выгруженные инструменты без схемы ветки v2', () => {
+  it('⛔ называет каждое имя без схемы один раз', () => {
+    expect(
+      namesWithoutSchema(['besales_a', 'besales_b', 'besales_b', 'besales_c'], {
+        besales_a: { type: 'object' },
+      }),
+    ).toEqual(['besales_b', 'besales_c']);
+  });
+
+  it('все имена со схемой — пусто', () => {
+    expect(namesWithoutSchema(['besales_a'], { besales_a: { type: 'object' } })).toEqual([]);
+  });
+});