yandex-direct-mcp-plus 1.3.0

package/dist/shared/config/enums.js

@@ -0,0 +1,137 @@
+// Перечисления Директа, по набору на предметную область. Схема — единственная
+// документация, которую видит модель: допустимые значения обязаны быть типом.
+//
+// Список фиксируется здесь ТОЛЬКО когда он закрыт — подтверждён справочником API
+// (сверка 03.09.2026) или ограничен нашей же реализацией. Директ пополняет
+// перечисления без предупреждения, и неполный литерал отклонял бы валидный вызов,
+// поэтому неподтверждённое остаётся строкой с перечислением в описании.
+// CampaignsService.get, SelectionCriteria.Statuses. UNKNOWN — только в ответе.
+export const CAMPAIGN_STATUSES = ["ACCEPTED", "DRAFT", "MODERATION", "REJECTED"];
+// Действия над ключевыми фразами: имя действия и есть метод сервиса keywords.
+export const KEYWORD_ACTIONS = ["suspend", "resume", "delete"];
+// Действия над объявлениями: тоже методы сервиса ads.
+export const AD_ACTIONS = ["suspend", "resume", "archive", "unarchive", "moderate", "delete"];
+// Действия над кампанией: отдельные методы API, набор закрыт.
+export const CAMPAIGN_ACTIONS = ["suspend", "resume", "archive", "unarchive"];
+// То же действие в update_campaign исторически принимается в верхнем регистре.
+// Регистр — часть внешнего контракта, менять его нельзя: он зашит в чужие сценарии.
+export const CAMPAIGN_STATUS_ACTIONS = ["SUSPEND", "RESUME", "ARCHIVE", "UNARCHIVE"];
+// Типы, которые умеет создавать create_campaign. Список ограничен нашей реализацией,
+// а не API: хендлер собирает только TextCampaign и DynamicTextCampaign.
+export const CAMPAIGN_TYPES_CREATABLE = ["TEXT_CAMPAIGN", "DYNAMIC_TEXT_CAMPAIGN"];
+// Типы кампаний для фильтра list_campaigns: CampaignTypeGetEnum без UNKNOWN —
+// это значение приходит в ответе для неизвестного клиенту типа, фильтровать по нему нечего.
+export const CAMPAIGN_TYPES = [
+    "TEXT_CAMPAIGN",
+    "MOBILE_APP_CAMPAIGN",
+    "DYNAMIC_TEXT_CAMPAIGN",
+    "CPM_BANNER_CAMPAIGN",
+    "SMART_CAMPAIGN",
+    "UNIFIED_CAMPAIGN"
+];
+// TextCampaignSearchStrategyTypeEnum без UNKNOWN. Набор шире, чем перечисляет
+// страница add: схема допускает и AVERAGE_ROI, и MAX_PROFIT, и *_MULTIPLE_GOALS.
+// Стратегии динамических кампаний — подмножество этого набора.
+export const SEARCH_STRATEGIES = [
+    "HIGHEST_POSITION",
+    "IMPRESSIONS_BELOW_SEARCH",
+    "WB_MAXIMUM_CLICKS",
+    "WB_MAXIMUM_CONVERSION_RATE",
+    "WEEKLY_CLICK_PACKAGE",
+    "AVERAGE_CPC",
+    "AVERAGE_CPA",
+    "AVERAGE_CPA_MULTIPLE_GOALS",
+    "AVERAGE_ROI",
+    "AVERAGE_CRR",
+    "PAY_FOR_CONVERSION",
+    "PAY_FOR_CONVERSION_CRR",
+    "PAY_FOR_CONVERSION_MULTIPLE_GOALS",
+    "MAX_PROFIT",
+    "SERVING_OFF"
+];
+// TextCampaignNetworkStrategyTypeEnum без UNKNOWN. От поисковой отличается началом:
+// вместо HIGHEST_POSITION — NETWORK_DEFAULT и MAXIMUM_COVERAGE.
+export const NETWORK_STRATEGIES = [
+    "NETWORK_DEFAULT",
+    "MAXIMUM_COVERAGE",
+    "WB_MAXIMUM_CLICKS",
+    "WB_MAXIMUM_CONVERSION_RATE",
+    "WEEKLY_CLICK_PACKAGE",
+    "AVERAGE_CPC",
+    "AVERAGE_CPA",
+    "AVERAGE_CPA_MULTIPLE_GOALS",
+    "AVERAGE_ROI",
+    "AVERAGE_CRR",
+    "PAY_FOR_CONVERSION",
+    "PAY_FOR_CONVERSION_CRR",
+    "PAY_FOR_CONVERSION_MULTIPLE_GOALS",
+    "MAX_PROFIT",
+    "SERVING_OFF"
+];
+// Действия над общими наборами минус-фраз: методы сервиса negativekeywordsharedsets.
+export const NEGATIVE_KEYWORD_SET_ACTIONS = ["add", "update", "delete"];
+// Состояния и статусы уточнений (AdExtensions.get, SelectionCriteria).
+export const AD_EXTENSION_STATES = ["ON", "DELETED"];
+export const AD_EXTENSION_STATUSES = ["ACCEPTED", "DRAFT", "MODERATION", "REJECTED"];
+// AdImageAddTypeEnum: AUTO просит Директ определить тип по размеру картинки.
+export const AD_IMAGE_TYPES = ["REGULAR", "WIDE", "FIXED_IMAGE", "AUTO"];
+// Что делает manage_ad_images: методы сервиса adimages.
+export const AD_IMAGE_ACTIONS = ["add", "get", "delete"];
+// Признак «привязан к объявлению» в SelectionCriteria ряда сервисов.
+export const ASSOCIATED_FLAGS = ["YES", "NO"];
+// RetargetingListTypeEnum и RetargetingListRuleOperatorEnum.
+export const RETARGETING_TYPES = ["RETARGETING", "AUDIENCE"];
+export const RETARGETING_RULE_OPERATORS = ["ALL", "ANY", "NONE"];
+// Типы корректировок, которые читает get_bid_adjustments. BidModifierTypeEnum шире
+// (регионы, видео, доход, SERP-раскладка) — эти сервер пока не покрывает, см. roadmap.
+export const BID_ADJUSTMENT_TYPES = [
+    "MOBILE_ADJUSTMENT",
+    "TABLET_ADJUSTMENT",
+    "DESKTOP_ADJUSTMENT",
+    "DESKTOP_ONLY_ADJUSTMENT",
+    "DEMOGRAPHICS_ADJUSTMENT"
+];
+// BidModifierLevelEnum.
+export const BID_ADJUSTMENT_LEVELS = ["CAMPAIGN", "AD_GROUP"];
+// AudienceTargetStateEnum и действия сервиса audiencetargets (setBids — наш set_bids).
+export const AUDIENCE_TARGET_STATES = ["ON", "SUSPENDED"];
+export const AUDIENCE_TARGET_ACTIONS = ["add", "set_bids", "suspend", "resume", "delete"];
+// Приоритет цели для автоматических стратегий.
+export const STRATEGY_PRIORITIES = ["LOW", "NORMAL", "HIGH"];
+// Динамические цели: действия сервиса dynamictextadtargets и условия отбора страниц
+// (WebpageConditionOperandEnum, StringConditionOperatorEnum).
+export const DYNAMIC_TARGET_ACTIONS = ["add", "set_bids", "suspend", "resume", "delete"];
+export const WEBPAGE_CONDITION_OPERANDS = ["URL", "DOMAIN", "PAGE_TITLE", "PAGE_CONTENT", "OFFERS_LIST_URL"];
+export const WEBPAGE_CONDITION_OPERATORS = ["EQUALS_ANY", "NOT_EQUALS_ALL", "CONTAINS_ANY", "NOT_CONTAINS_ALL"];
+// Режимы get_changes (наши имена методов checkCampaigns/check) и CheckFieldEnum.
+export const CHANGES_MODES = ["campaigns", "objects"];
+export const CHANGES_FIELD_NAMES = ["CampaignIds", "AdGroupIds", "AdIds", "CampaignsStat"];
+// Стратегии, которые умеет выставлять set_strategy. Список по-прежнему уже полного
+// (в TextCampaignStrategyBase двенадцать структур настроек), но покрывает переход
+// «клики → конверсии»: ручная, максимум кликов, средняя цена клика, средняя цена
+// конверсии и оплата за конверсию. Ограничение наше, не Директа — хендлер собирает
+// настройки только для этих типов.
+//
+// Сочетание сторон схемой не проверяется: таблица совместимости живёт у Директа
+// и меняется без нас, а лишний запрет здесь отклонял бы валидный вызов.
+export const SETTABLE_SEARCH_STRATEGIES = [
+    "HIGHEST_POSITION",
+    "WB_MAXIMUM_CLICKS",
+    "AVERAGE_CPC",
+    "AVERAGE_CPA",
+    "PAY_FOR_CONVERSION",
+    "SERVING_OFF"
+];
+export const SETTABLE_NETWORK_STRATEGIES = [
+    "NETWORK_DEFAULT",
+    "MAXIMUM_COVERAGE",
+    "WB_MAXIMUM_CLICKS",
+    "AVERAGE_CPC",
+    "AVERAGE_CPA",
+    "PAY_FOR_CONVERSION",
+    "SERVING_OFF"
+];
+// Дни недели расписания показов. В API день — первое число строки Schedule
+// (1 — понедельник … 7 — воскресенье); наружу отдаются буквенные коды: число
+// модель путает с часом, а порядок дней в неделе Директа не совпадает с ISO-датой.
+export const WEEKDAYS = ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"];

package/dist/shared/config/env.d.ts

@@ -0,0 +1,2 @@
+export declare function getToken(): string;
+export declare function getClientLogin(): string | undefined;

package/dist/shared/config/env.js

@@ -0,0 +1,14 @@
+// Чтение окружения. Токен читается на каждый запрос, а не при импорте модуля:
+// иначе тест не смог бы подменить его между кейсами, а сервер — стартовать без него.
+export function getToken() {
+    const token = process.env.YANDEX_DIRECT_TOKEN;
+    if (!token) {
+        throw new Error("Переменная окружения YANDEX_DIRECT_TOKEN не задана");
+    }
+    return token;
+}
+// Client-Login обязателен для агентских токенов.
+// Док: https://yandex.ru/dev/direct/doc/en/concepts/headers
+export function getClientLogin() {
+    return process.env.YANDEX_DIRECT_LOGIN;
+}

package/dist/shared/config/limits.d.ts

@@ -0,0 +1,58 @@
+export declare const REQUEST_TIMEOUT_MS = 15000;
+export declare const MAX_RETRIES = 3;
+export declare const MAX_RETRY_DELAY_MS = 8000;
+export declare const REPORT_MAX_POLLS = 6;
+export declare const REPORT_DEFAULT_RETRY_IN_SEC = 5;
+export declare const REPORT_MAX_RETRY_IN_SEC = 15;
+export declare const PAGE_MAX_LIMIT = 10000;
+export declare const MAX_CAMPAIGNS_PER_CALL = 1000;
+export declare const MAX_AD_GROUPS_PER_CALL = 1000;
+export declare const MAX_ADS_PER_MODERATION = 10000;
+export declare const MAX_SHARED_SETS_PER_CALL = 30;
+export declare const MAX_SHARED_SETS_PER_AD_GROUP = 3;
+export declare const SHARED_SET_NAME_MAX = 255;
+export declare const MAX_IDS_PER_CALL = 10000;
+export declare const AD_TEXT_LIMITS: {
+    readonly title: 56;
+    readonly title2: 30;
+    readonly text: 81;
+};
+export declare const SITELINK_LIMITS: {
+    readonly title: 30;
+    readonly href: 1024;
+    readonly description: 60;
+    readonly perSet: 8;
+};
+export declare const CALLOUT_TEXT_MAX = 25;
+export declare const MAX_CALLOUTS_PER_CALL = 1000;
+export declare const AD_IMAGE_NAME_MAX = 255;
+export declare const MAX_IMAGES_PER_CALL = 100;
+export declare const RETARGETING_LIMITS: {
+    readonly name: 250;
+    readonly description: 4096;
+    readonly membershipDays: 540;
+};
+export declare const BID_MODIFIER_RANGE: {
+    readonly min: 0;
+    readonly max: 1300;
+};
+export declare const MAX_CAMPAIGNS_PER_ADJUSTMENT_CALL = 10;
+export declare const MAX_CAMPAIGNS_PER_AUDIENCE_CALL = 100;
+export declare const MAX_CAMPAIGNS_PER_CHANGES_CALL = 3000;
+export declare const MAX_AD_GROUPS_PER_CHANGES_CALL = 10000;
+export declare const MAX_ADS_PER_CHANGES_CALL = 50000;
+export declare const REGIONS_DEFAULT_LIMIT = 50;
+export declare const REGIONS_MAX_LIMIT = 500;
+export declare const HOURS_IN_DAY = 24;
+export declare const HOURLY_BID_RANGE: {
+    readonly min: 0;
+    readonly max: 200;
+    readonly step: 10;
+};
+export declare const HOLIDAY_BID_RANGE: {
+    readonly min: 10;
+    readonly max: 200;
+    readonly step: 10;
+};
+export declare const TIME_ZONES_DEFAULT_LIMIT = 50;
+export declare const TIME_ZONES_MAX_LIMIT = 500;

package/dist/shared/config/limits.js

@@ -0,0 +1,54 @@
+// Настройки транспорта и выборок: крутилки живут здесь. Структурные константы
+// (вроде «список не пуст») остаются на месте объявления, в схеме инструмента.
+export const REQUEST_TIMEOUT_MS = 15_000;
+export const MAX_RETRIES = 3;
+export const MAX_RETRY_DELAY_MS = 8_000;
+// Отчёт формируется офлайн: сервер отвечает 201/202 и просит повторить позже.
+export const REPORT_MAX_POLLS = 6;
+export const REPORT_DEFAULT_RETRY_IN_SEC = 5;
+export const REPORT_MAX_RETRY_IN_SEC = 15;
+// Page.Limit в v5 ограничен десятью тысячами.
+export const PAGE_MAX_LIMIT = 10_000;
+// Ограничения самого Директа на размер выборки в одном вызове.
+export const MAX_CAMPAIGNS_PER_CALL = 1_000;
+export const MAX_AD_GROUPS_PER_CALL = 1_000;
+export const MAX_ADS_PER_MODERATION = 10_000;
+export const MAX_SHARED_SETS_PER_CALL = 30;
+export const MAX_SHARED_SETS_PER_AD_GROUP = 3;
+export const SHARED_SET_NAME_MAX = 255;
+// Универсальный потолок на список ID в SelectionCriteria большинства сервисов.
+export const MAX_IDS_PER_CALL = 10_000;
+// Длины текстов объявления, справочник TextAd.
+export const AD_TEXT_LIMITS = { title: 56, title2: 30, text: 81 };
+// Быстрые ссылки: длины полей и размер набора.
+export const SITELINK_LIMITS = { title: 30, href: 1024, description: 60, perSet: 8 };
+// Уточнения (Callout).
+export const CALLOUT_TEXT_MAX = 25;
+export const MAX_CALLOUTS_PER_CALL = 1_000;
+// Изображения объявлений.
+export const AD_IMAGE_NAME_MAX = 255;
+export const MAX_IMAGES_PER_CALL = 100;
+// Ретаргетинг: длины полей и срок учёта цели.
+export const RETARGETING_LIMITS = { name: 250, description: 4096, membershipDays: 540 };
+// Коэффициент корректировки ставки, в процентах.
+export const BID_MODIFIER_RANGE = { min: 0, max: 1300 };
+// Корректировки читаются не больше чем по десяти кампаниям за вызов.
+export const MAX_CAMPAIGNS_PER_ADJUSTMENT_CALL = 10;
+// Аудиторные цели читаются не больше чем по сотне кампаний за вызов.
+export const MAX_CAMPAIGNS_PER_AUDIENCE_CALL = 100;
+// Ограничения ChangesService на размер выборки.
+export const MAX_CAMPAIGNS_PER_CHANGES_CALL = 3_000;
+export const MAX_AD_GROUPS_PER_CHANGES_CALL = 10_000;
+export const MAX_ADS_PER_CHANGES_CALL = 50_000;
+// Выдача справочника регионов: сколько строк отдавать модели за раз.
+export const REGIONS_DEFAULT_LIMIT = 50;
+export const REGIONS_MAX_LIMIT = 500;
+// Временной таргетинг: почасовой коэффициент задаётся в процентах от текущей ставки,
+// шаг 10, ноль — показов в этот час нет. Праздничный коэффициент начинается с 10:
+// ноль там запрещён, показы в праздники отключает отдельный флаг.
+export const HOURS_IN_DAY = 24;
+export const HOURLY_BID_RANGE = { min: 0, max: 200, step: 10 };
+export const HOLIDAY_BID_RANGE = { min: 10, max: 200, step: 10 };
+// Выдача справочника часовых поясов: сколько строк отдавать модели за раз.
+export const TIME_ZONES_DEFAULT_LIMIT = 50;
+export const TIME_ZONES_MAX_LIMIT = 500;

package/dist/shared/lib/campaign-type.d.ts

@@ -0,0 +1,12 @@
+declare const CAMPAIGN_SETTINGS_KEYS: {
+    readonly TEXT_CAMPAIGN: "TextCampaign";
+    readonly DYNAMIC_TEXT_CAMPAIGN: "DynamicTextCampaign";
+    readonly MOBILE_APP_CAMPAIGN: "MobileAppCampaign";
+    readonly SMART_CAMPAIGN: "SmartCampaign";
+    readonly UNIFIED_CAMPAIGN: "UnifiedCampaign";
+    readonly CPM_BANNER_CAMPAIGN: "CpmBannerCampaign";
+};
+export type CampaignSettingsKey = (typeof CAMPAIGN_SETTINGS_KEYS)[keyof typeof CAMPAIGN_SETTINGS_KEYS];
+/** Имя объекта настроек кампании; у типа, которого нет в таблице, — `undefined`. */
+export declare const getCampaignSettingsKey: (type?: string) => CampaignSettingsKey | undefined;
+export {};

package/dist/shared/lib/campaign-type.js

@@ -0,0 +1,20 @@
+// Часть полей кампании лежит не на верхнем уровне, а внутри объекта настроек, имя
+// которого зависит от типа кампании: TrackingParams, BiddingStrategy,
+// NegativeKeywordSharedSetIds и прочие. Тип в запросе на изменение не передаётся, поэтому
+// сценарий читает его через campaigns.get и приводит сюда.
+//
+// Таблица отвечает только на вопрос «как называется объект настроек», и ответ этот общий
+// для всех полей. А вот какие типы поддерживают конкретное поле — знание не общее:
+// TrackingParams есть у SMART_CAMPAIGN, но нет у MOBILE_APP_CAMPAIGN, у
+// NegativeKeywordSharedSetIds ровно наоборот. Поэтому список поддерживаемых типов
+// остаётся у того, кто это поле пишет, а сюда не переезжает.
+const CAMPAIGN_SETTINGS_KEYS = {
+    TEXT_CAMPAIGN: "TextCampaign",
+    DYNAMIC_TEXT_CAMPAIGN: "DynamicTextCampaign",
+    MOBILE_APP_CAMPAIGN: "MobileAppCampaign",
+    SMART_CAMPAIGN: "SmartCampaign",
+    UNIFIED_CAMPAIGN: "UnifiedCampaign",
+    CPM_BANNER_CAMPAIGN: "CpmBannerCampaign"
+};
+/** Имя объекта настроек кампании; у типа, которого нет в таблице, — `undefined`. */
+export const getCampaignSettingsKey = (type) => CAMPAIGN_SETTINGS_KEYS[type];

package/dist/shared/lib/date.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+export declare function dateField(description: string): z.ZodString;
+export declare function timestampField(description: string): z.ZodString;

package/dist/shared/lib/date.js

@@ -0,0 +1,17 @@
+// Даты Директа: календарный день YYYY-MM-DD и момент времени ISO 8601.
+import { z } from "zod";
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+export function dateField(description) {
+    return z
+        .string()
+        .check(z.regex(DATE, { error: "Дата указывается в формате YYYY-MM-DD" }))
+        .meta({ description });
+}
+export function timestampField(description) {
+    return z
+        .string()
+        .check(z.regex(TIMESTAMP, { error: "Момент времени указывается в формате YYYY-MM-DDThh:mm:ssZ" }))
+        .refine((value) => !Number.isNaN(Date.parse(value)), { error: "Такой даты не существует" })
+        .meta({ description });
+}

package/dist/shared/lib/format.d.ts

@@ -0,0 +1,3 @@
+export declare function formatResult(data: unknown, opts?: {
+    money?: boolean;
+}): string;

package/dist/shared/lib/format.js

@@ -0,0 +1,51 @@
+// biome-ignore-all lint/plugin: слой вывода — ID сюда приходят уже строками из shared/api
+// Единый формат ответа инструментов: деньги в рублях, сверху — уведомления Директа.
+import { microsToRubles } from "#shared/lib/money";
+// Поля v5, приезжающие в микроединицах. Набор консервативный: только заведомо
+// денежные ключи, иначе под конвертацию попали бы счётчики и ID.
+const MONEY_KEYS = new Set(["Amount", "Bid", "ContextBid", "WeeklySpendLimit", "BidCeiling"]);
+function convertMoney(value) {
+    if (Array.isArray(value))
+        return value.map(convertMoney);
+    if (value && typeof value === "object") {
+        const converted = {};
+        for (const [key, nested] of Object.entries(value)) {
+            converted[key] = MONEY_KEYS.has(key) && typeof nested === "number" ? microsToRubles(nested) : convertMoney(nested);
+        }
+        return converted;
+    }
+    return value;
+}
+function formatNotice(prefix, key, index, notification) {
+    const detail = notification.Details ? ` — ${notification.Details}` : "";
+    return `${prefix} ${key}[${index}] [${notification.Code ?? "?"}] ${notification.Message ?? ""}${detail}`;
+}
+// Частичный успех Директ хранит в теле: per-item ошибки и предупреждения лежат
+// в массивах *Results, обрезанная выборка — в LimitedBy. Без этой шапки модель
+// увидела бы «успех» там, где половина элементов не прошла.
+function collectNotices(data) {
+    const lines = [];
+    const result = data?.result;
+    if (!result || typeof result !== "object")
+        return "";
+    if (typeof result.LimitedBy === "number") {
+        lines.push(`ℹ️ Результат обрезан (LimitedBy=${result.LimitedBy}). Для следующей страницы передайте offset=${result.LimitedBy}.`);
+    }
+    for (const [key, value] of Object.entries(result)) {
+        if (!/Results$/.test(key) || !Array.isArray(value))
+            continue;
+        value.forEach((item, index) => {
+            for (const error of (item?.Errors ?? []))
+                lines.push(formatNotice("❌", key, index, error));
+            for (const warning of (item?.Warnings ?? []))
+                lines.push(formatNotice("⚠️", key, index, warning));
+        });
+    }
+    return lines.join("\n");
+}
+export function formatResult(data, opts = {}) {
+    const payload = opts.money === false ? data : convertMoney(data);
+    const notices = collectNotices(data);
+    const body = JSON.stringify(payload, null, 2);
+    return notices ? `${notices}\n\n${body}` : body;
+}

package/dist/shared/lib/id.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare function idField(description: string): z.ZodString;
+export declare function apiId(id: string): bigint;
+export declare function apiIds(ids: string[]): bigint[];

package/dist/shared/lib/id.js

@@ -0,0 +1,21 @@
+// ID Директа наружу — десятичные строки, внутрь API — BigInt.
+// z.coerce здесь запрещён: он принял бы уже округлённое число и превратил его
+// в правдоподобную строку, заменив явную ошибку валидации тихо неверным ID.
+import { z } from "zod";
+const DECIMAL_ID = /^[1-9]\d*$/;
+export function idField(description) {
+    return z
+        .string({
+        error: (issue) => issue.input === undefined
+            ? "ID обязателен"
+            : "ID пришёл числом и уже потерял точность: 19-значные ID Директа не помещаются в число JavaScript. Передавайте строкой."
+    })
+        .check(z.regex(DECIMAL_ID, { error: "ID должен быть положительным целым числом в виде строки" }))
+        .meta({ description });
+}
+export function apiId(id) {
+    return BigInt(id);
+}
+export function apiIds(ids) {
+    return ids.map(apiId);
+}

package/dist/shared/lib/money.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare function rublesToMicros(rubles: number): number;
+export declare function microsToRubles(micros: number): number;
+export declare function rublesField(description: string, opts?: {
+    allowZero?: boolean;
+}): z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>;

package/dist/shared/lib/money.js

@@ -0,0 +1,21 @@
+// API Директа оперирует микроединицами (сумма в валюте × 1 000 000).
+// Наружу сервер отдаёт и принимает рубли: вход конвертирует схема, выход — format.
+import { z } from "zod";
+export function rublesToMicros(rubles) {
+    return Math.round(rubles * 1_000_000);
+}
+export function microsToRubles(micros) {
+    return micros / 1_000_000;
+}
+// Денежное поле схемы: наружу рубли, в хендлер приезжают уже микроединицы.
+// Все суммы объявляются через него — иначе конвертация расползётся по хендлерам
+// и рано или поздно случится дважды.
+// allowZero нужен ставкам, где ноль — осмысленное значение «не задана».
+export function rublesField(description, opts = {}) {
+    const amount = z
+        .number({ error: "Сумма указывается числом в рублях" })
+        .check(opts.allowZero
+        ? z.nonnegative({ error: "Сумма не может быть отрицательной" })
+        : z.positive({ error: "Сумма должна быть больше нуля" }));
+    return amount.transform(rublesToMicros).meta({ description });
+}

package/dist/shared/lib/pagination.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export declare const pageFields: {
+    limit: z.ZodOptional<z.ZodInt>;
+    offset: z.ZodOptional<z.ZodInt>;
+};
+export declare function buildPage(params: {
+    limit?: number;
+    offset?: number;
+}): Record<string, number> | undefined;

package/dist/shared/lib/pagination.js

@@ -0,0 +1,26 @@
+// Общие поля пагинации для list-инструментов: Page.Limit / Page.Offset.
+// Обрезанную выборку сервер помечает LimitedBy — его подсказывает format.
+import { z } from "zod";
+import { PAGE_MAX_LIMIT } from "#shared/config/limits";
+export const pageFields = {
+    limit: z
+        .int()
+        .check(z.positive(), z.lte(PAGE_MAX_LIMIT))
+        .optional()
+        .meta({ description: `Сколько объектов вернуть (максимум ${PAGE_MAX_LIMIT})` }),
+    offset: z
+        .int()
+        .check(z.nonnegative())
+        .optional()
+        .meta({ description: "Смещение выборки: сюда передаётся LimitedBy предыдущей страницы" })
+};
+export function buildPage(params) {
+    if (params.limit === undefined && params.offset === undefined)
+        return undefined;
+    const page = {};
+    if (params.limit !== undefined)
+        page.Limit = params.limit;
+    if (params.offset !== undefined)
+        page.Offset = params.offset;
+    return page;
+}

package/dist/shared/lib/report.d.ts

@@ -0,0 +1 @@
+export declare function reportName(prefix: string, now?: () => number): string;

package/dist/shared/lib/report.js

@@ -0,0 +1,5 @@
+// ReportName обязан быть уникальным в пределах аккаунта, поэтому в него идёт время.
+// Часы вынесены параметром: Date.now() внутри хендлера сделал бы его непроверяемым.
+export function reportName(prefix, now = Date.now) {
+    return `${prefix}_${now()}`;
+}

package/dist/shared/lib/tool.d.ts

@@ -0,0 +1,24 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+export declare const READ: ToolAnnotations;
+export declare const WRITE: ToolAnnotations;
+export declare const IDEMPOTENT: ToolAnnotations;
+export declare const DESTRUCTIVE: ToolAnnotations;
+export type ToolDescriptor = {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly annotations: ToolAnnotations;
+    readonly schema: z.ZodObject;
+    readonly run: (params: unknown) => Promise<string>;
+};
+type ToolInput<Schema extends z.ZodObject> = {
+    name: string;
+    title: string;
+    description: string;
+    annotations: ToolAnnotations;
+    schema: Schema;
+    handler: (params: z.infer<Schema>) => Promise<string>;
+};
+export declare function defineTool<Schema extends z.ZodObject>(tool: ToolInput<Schema>): ToolDescriptor;
+export {};

package/dist/shared/lib/tool.js

@@ -0,0 +1,20 @@
+// Подсказки клиенту о природе операции: по ним он решает, спрашивать ли пользователя.
+// Выбираются по реальному действию, а не по имени метода: manage_*, умеющий удалять, —
+// DESTRUCTIVE, даже если обычно только обновляет.
+export const READ = { readOnlyHint: true, openWorldHint: true };
+export const WRITE = { readOnlyHint: false, openWorldHint: true };
+export const IDEMPOTENT = { readOnlyHint: false, idempotentHint: true, openWorldHint: true };
+export const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+export function defineTool(tool) {
+    return {
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        annotations: tool.annotations,
+        schema: tool.schema,
+        // Единственное приведение типа на весь реестр, и оно обосновано: SDK валидирует
+        // аргументы этой же схемой до вызова. Повторный parse здесь был бы не просто
+        // лишним — он второй раз применил бы .transform, умножив рубли на миллион дважды.
+        run: (params) => tool.handler(params)
+    };
+}

package/dist/tools/account/handler.d.ts

@@ -0,0 +1,3 @@
+import type { z } from "zod";
+import type { getAccountBalanceSchema } from "./schema.js";
+export declare function handleGetAccountBalance(params: z.infer<typeof getAccountBalanceSchema>): Promise<string>;

package/dist/tools/account/handler.js

@@ -0,0 +1,12 @@
+import { apiV4 } from "#shared/api/v4";
+import { getClientLogin } from "#shared/config/env";
+import { formatResult } from "#shared/lib/format";
+export async function handleGetAccountBalance(params) {
+    const param = { Action: "Get" };
+    const clientLogin = getClientLogin();
+    const logins = params.logins ?? (clientLogin ? [clientLogin] : undefined);
+    if (logins?.length)
+        param.SelectionCriteria = { Logins: logins };
+    // money: false — v4 отдаёт Amount уже в валюте аккаунта, микроединиц здесь нет.
+    return formatResult(await apiV4("AccountManagement", param), { money: false });
+}

package/dist/tools/account/schema.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare const getAccountBalanceSchema: z.ZodObject<{
+    logins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;

package/dist/tools/account/schema.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export const getAccountBalanceSchema = z.object({
+    logins: z
+        .array(z.string().check(z.minLength(1, { error: "Логин не может быть пустым" })))
+        .optional()
+        .meta({ description: "Логины аккаунтов для агентского токена; по умолчанию — аккаунт самого токена" })
+});

package/dist/tools/account/tool.d.ts

@@ -0,0 +1 @@
+export declare const getAccountBalanceTool: import("#shared/lib/tool").ToolDescriptor;

package/dist/tools/account/tool.js

@@ -0,0 +1,11 @@
+import { defineTool, READ } from "#shared/lib/tool";
+import { handleGetAccountBalance } from "./handler.js";
+import { getAccountBalanceSchema } from "./schema.js";
+export const getAccountBalanceTool = defineTool({
+    name: "get_account_balance",
+    title: "Баланс аккаунта",
+    description: "Баланс и финансовая информация аккаунта (Amount, Currency) через Live API v4.",
+    annotations: READ,
+    schema: getAccountBalanceSchema,
+    handler: handleGetAccountBalance
+});

package/dist/tools/ad-extensions/handler.d.ts

@@ -0,0 +1,5 @@
+import type { z } from "zod";
+import type { addAdExtensionsSchema, deleteAdExtensionsSchema, listAdExtensionsSchema } from "./schema.js";
+export declare function handleListAdExtensions(params: z.infer<typeof listAdExtensionsSchema>): Promise<string>;
+export declare function handleAddAdExtensions(params: z.infer<typeof addAdExtensionsSchema>): Promise<string>;
+export declare function handleDeleteAdExtensions(params: z.infer<typeof deleteAdExtensionsSchema>): Promise<string>;

package/dist/tools/ad-extensions/handler.js

@@ -0,0 +1,35 @@
+import { apiPost } from "#shared/api/client";
+import { formatResult } from "#shared/lib/format";
+import { apiIds } from "#shared/lib/id";
+import { buildPage } from "#shared/lib/pagination";
+const NO_MONEY = { money: false };
+export async function handleListAdExtensions(params) {
+    const selection = { Types: ["CALLOUT"] };
+    if (params.ad_extension_ids?.length)
+        selection.Ids = apiIds(params.ad_extension_ids);
+    if (params.states?.length)
+        selection.States = params.states;
+    if (params.statuses?.length)
+        selection.Statuses = params.statuses;
+    const request = {
+        SelectionCriteria: selection,
+        FieldNames: ["Id", "Type", "Status", "StatusClarification", "Associated"],
+        CalloutFieldNames: ["CalloutText"]
+    };
+    const page = buildPage(params);
+    if (page)
+        request.Page = page;
+    return formatResult(await apiPost("adextensions", "get", request), NO_MONEY);
+}
+export async function handleAddAdExtensions(params) {
+    const data = await apiPost("adextensions", "add", {
+        AdExtensions: params.callouts.map((calloutText) => ({ Callout: { CalloutText: calloutText } }))
+    });
+    return formatResult(data, NO_MONEY);
+}
+export async function handleDeleteAdExtensions(params) {
+    const data = await apiPost("adextensions", "delete", {
+        SelectionCriteria: { Ids: apiIds(params.ad_extension_ids) }
+    });
+    return formatResult(data, NO_MONEY);
+}