yandex-direct-mcp-plus 1.3.0

package/dist/tools/dynamic-targets/schema.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { AUDIENCE_TARGET_STATES, DYNAMIC_TARGET_ACTIONS, STRATEGY_PRIORITIES, WEBPAGE_CONDITION_OPERANDS, WEBPAGE_CONDITION_OPERATORS } from "#shared/config/enums";
+import { MAX_AD_GROUPS_PER_CALL, MAX_CAMPAIGNS_PER_AUDIENCE_CALL, MAX_IDS_PER_CALL } from "#shared/config/limits";
+import { idField } from "#shared/lib/id";
+import { rublesField } from "#shared/lib/money";
+import { pageFields } from "#shared/lib/pagination";
+export const listDynamicTargetsSchema = z.object({
+    dynamic_target_ids: z
+        .array(idField("ID динамической цели"))
+        .check(z.maxLength(MAX_IDS_PER_CALL, { error: `Не больше ${MAX_IDS_PER_CALL} целей за вызов` }))
+        .optional()
+        .meta({ description: "Конкретные динамические цели" }),
+    ad_group_ids: z
+        .array(idField("ID группы объявлений"))
+        .check(z.maxLength(MAX_AD_GROUPS_PER_CALL, { error: `Не больше ${MAX_AD_GROUPS_PER_CALL} групп за вызов` }))
+        .optional()
+        .meta({ description: "Цели выбранных групп" }),
+    campaign_ids: z
+        .array(idField("ID кампании"))
+        .check(z.maxLength(MAX_CAMPAIGNS_PER_AUDIENCE_CALL, {
+        error: `Не больше ${MAX_CAMPAIGNS_PER_AUDIENCE_CALL} кампаний за вызов`
+    }))
+        .optional()
+        .meta({ description: "Цели выбранных кампаний" }),
+    states: z
+        .array(z.literal(AUDIENCE_TARGET_STATES))
+        .optional()
+        .meta({ description: "Фильтр по состоянию: ON или SUSPENDED" }),
+    ...pageFields
+});
+// Условие нацеливания: по какому свойству страницы отбирать и с каким оператором.
+const webpageCondition = z.object({
+    operand: z.literal(WEBPAGE_CONDITION_OPERANDS).meta({
+        description: "Свойство страницы: URL, DOMAIN, PAGE_TITLE, PAGE_CONTENT или OFFERS_LIST_URL"
+    }),
+    operator: z.literal(WEBPAGE_CONDITION_OPERATORS).meta({
+        description: "Как сравнивать: EQUALS_ANY, NOT_EQUALS_ALL, CONTAINS_ANY или NOT_CONTAINS_ALL"
+    }),
+    arguments: z
+        .array(z.string().check(z.minLength(1, { error: "Аргумент условия не может быть пустым" })))
+        .check(z.minLength(1, { error: "Условие без аргументов" }))
+        .meta({ description: "Значения, с которыми сравнивается свойство страницы" })
+});
+const dynamicTarget = z.object({
+    ad_group_id: idField("ID группы динамических объявлений"),
+    name: z
+        .string()
+        .check(z.minLength(1, { error: "Название не может быть пустым" }))
+        .meta({ description: "Название цели" }),
+    conditions: z
+        .array(webpageCondition)
+        .check(z.minLength(1, { error: "Цель без условий" }))
+        .meta({ description: "Условия отбора страниц; между собой соединяются логическим И" }),
+    bid: rublesField("Ставка на поиске в рублях; 0 — снять ставку", { allowZero: true }).optional(),
+    context_bid: rublesField("Ставка в сетях в рублях; 0 — снять ставку", { allowZero: true }).optional(),
+    strategy_priority: z
+        .literal(STRATEGY_PRIORITIES)
+        .optional()
+        .meta({ description: "Приоритет для автоматических стратегий" })
+});
+const dynamicBid = z.object({
+    dynamic_target_id: idField("ID динамической цели").optional(),
+    ad_group_id: idField("ID группы: ставка применится ко всем её целям").optional(),
+    campaign_id: idField("ID кампании: ставка применится ко всем её целям").optional(),
+    bid: rublesField("Ставка на поиске в рублях; 0 — снять ставку", { allowZero: true }).optional(),
+    context_bid: rublesField("Ставка в сетях в рублях; 0 — снять ставку", { allowZero: true }).optional(),
+    strategy_priority: z
+        .literal(STRATEGY_PRIORITIES)
+        .optional()
+        .meta({ description: "Приоритет для автоматических стратегий" })
+});
+export const manageDynamicTargetsSchema = z.object({
+    action: z.literal(DYNAMIC_TARGET_ACTIONS).meta({
+        description: "Что сделать: add, set_bids, suspend, resume или delete (необратимо)"
+    }),
+    targets: z
+        .array(dynamicTarget)
+        .check(z.minLength(1, { error: "Список целей пуст" }), z.maxLength(MAX_AD_GROUPS_PER_CALL, { error: `Не больше ${MAX_AD_GROUPS_PER_CALL} целей за вызов` }))
+        .optional()
+        .meta({ description: "Цели для добавления; обязателен при action=add" }),
+    bids: z
+        .array(dynamicBid)
+        .check(z.minLength(1, { error: "Список ставок пуст" }), z.maxLength(MAX_IDS_PER_CALL, { error: `Не больше ${MAX_IDS_PER_CALL} ставок за вызов` }))
+        .optional()
+        .meta({ description: "Новые ставки и приоритеты; обязателен при action=set_bids" }),
+    dynamic_target_ids: z
+        .array(idField("ID динамической цели"))
+        .check(z.minLength(1, { error: "Список целей пуст" }), z.maxLength(MAX_IDS_PER_CALL, { error: `Не больше ${MAX_IDS_PER_CALL} целей за вызов` }))
+        .optional()
+        .meta({ description: "Цели для suspend, resume или delete" })
+});

package/dist/tools/dynamic-targets/tool.d.ts

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

package/dist/tools/dynamic-targets/tool.js

@@ -0,0 +1,19 @@
+import { DESTRUCTIVE, defineTool, READ } from "#shared/lib/tool";
+import { handleListDynamicTargets, handleManageDynamicTargets } from "./handler.js";
+import { listDynamicTargetsSchema, manageDynamicTargetsSchema } from "./schema.js";
+export const listDynamicTargetsTool = defineTool({
+    name: "list_dynamic_targets",
+    title: "Динамические цели",
+    description: "Получить условия нацеливания динамических текстовых объявлений.",
+    annotations: READ,
+    schema: listDynamicTargetsSchema,
+    handler: handleListDynamicTargets
+});
+export const manageDynamicTargetsTool = defineTool({
+    name: "manage_dynamic_targets",
+    title: "Управление динамическими целями",
+    description: "Создать, изменить ставки, остановить, возобновить или удалить динамические цели.",
+    annotations: DESTRUCTIVE,
+    schema: manageDynamicTargetsSchema,
+    handler: handleManageDynamicTargets
+});

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

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

package/dist/tools/feeds/handler.js

@@ -0,0 +1,29 @@
+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 LIST_FIELDS = [
+    "Id",
+    "Name",
+    "BusinessType",
+    "SourceType",
+    "FilterSchema",
+    "UpdatedAt",
+    "CampaignIds",
+    "NumberOfItems",
+    "Status",
+    "TitleAndTextSources"
+];
+export async function handleListFeeds(params) {
+    const request = {
+        FieldNames: LIST_FIELDS,
+        FileFeedFieldNames: ["Filename"],
+        UrlFeedFieldNames: ["Login", "Url", "RemoveUtmTags"]
+    };
+    if (params.feed_ids?.length)
+        request.SelectionCriteria = { Ids: apiIds(params.feed_ids) };
+    const page = buildPage(params);
+    if (page)
+        request.Page = page;
+    return formatResult(await apiPost("feeds", "get", request), { money: false });
+}

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

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare const listFeedsSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodInt>;
+    offset: z.ZodOptional<z.ZodInt>;
+    feed_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;

package/dist/tools/feeds/schema.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { MAX_IDS_PER_CALL } from "#shared/config/limits";
+import { idField } from "#shared/lib/id";
+import { pageFields } from "#shared/lib/pagination";
+export const listFeedsSchema = z.object({
+    feed_ids: z
+        .array(idField("ID фида"))
+        .check(z.maxLength(MAX_IDS_PER_CALL, { error: `За один вызов допустимо не больше ${MAX_IDS_PER_CALL} фидов` }))
+        .optional()
+        .meta({ description: "Конкретные фиды; без них возвращаются все фиды аккаунта" }),
+    ...pageFields
+});

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

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

package/dist/tools/feeds/tool.js

@@ -0,0 +1,11 @@
+import { defineTool, READ } from "#shared/lib/tool";
+import { handleListFeeds } from "./handler.js";
+import { listFeedsSchema } from "./schema.js";
+export const listFeedsTool = defineTool({
+    name: "list_feeds",
+    title: "Список фидов",
+    description: "Получить товарные фиды, их источники, статусы обработки и связанные кампании.",
+    annotations: READ,
+    schema: listFeedsSchema,
+    handler: handleListFeeds
+});

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

@@ -0,0 +1,6 @@
+import type { z } from "zod";
+import type { addKeywordsSchema, listKeywordsSchema, manageKeywordsSchema, setKeywordBidsSchema } from "./schema.js";
+export declare function handleListKeywords(params: z.infer<typeof listKeywordsSchema>): Promise<string>;
+export declare function handleAddKeywords(params: z.infer<typeof addKeywordsSchema>): Promise<string>;
+export declare function handleManageKeywords(params: z.infer<typeof manageKeywordsSchema>): Promise<string>;
+export declare function handleSetKeywordBids(params: z.infer<typeof setKeywordBidsSchema>): Promise<string>;

package/dist/tools/keywords/handler.js

@@ -0,0 +1,53 @@
+import { apiPost } from "#shared/api/client";
+import { formatResult } from "#shared/lib/format";
+import { apiId, apiIds } from "#shared/lib/id";
+import { buildPage } from "#shared/lib/pagination";
+const LIST_FIELDS = ["Id", "Keyword", "CampaignId", "AdGroupId", "Status", "State", "Bid", "ContextBid"];
+function selectBidTarget(params) {
+    const targets = [];
+    if (params.keyword_ids?.length)
+        targets.push({ field: "KeywordId", ids: params.keyword_ids });
+    if (params.ad_group_ids?.length)
+        targets.push({ field: "AdGroupId", ids: params.ad_group_ids });
+    if (params.campaign_ids?.length)
+        targets.push({ field: "CampaignId", ids: params.campaign_ids });
+    if (targets.length !== 1) {
+        throw new Error("Укажите ровно один уровень целей: keyword_ids ИЛИ ad_group_ids ИЛИ campaign_ids.");
+    }
+    return targets[0];
+}
+export async function handleListKeywords(params) {
+    const requestParams = {
+        SelectionCriteria: { AdGroupIds: apiIds(params.ad_group_ids) },
+        FieldNames: LIST_FIELDS
+    };
+    const page = buildPage(params);
+    if (page)
+        requestParams.Page = page;
+    return formatResult(await apiPost("keywords", "get", requestParams));
+}
+export async function handleAddKeywords(params) {
+    const data = await apiPost("keywords", "add", {
+        Keywords: params.keywords.map((keyword) => ({ AdGroupId: apiId(params.ad_group_id), Keyword: keyword }))
+    });
+    return formatResult(data);
+}
+export async function handleManageKeywords(params) {
+    const data = await apiPost("keywords", params.action, {
+        SelectionCriteria: { Ids: apiIds(params.keyword_ids) }
+    });
+    return formatResult(data);
+}
+export async function handleSetKeywordBids(params) {
+    const target = selectBidTarget(params);
+    if (params.bid === undefined && params.context_bid === undefined) {
+        throw new Error("Укажите bid и/или context_bid (в рублях).");
+    }
+    const amounts = {};
+    if (params.bid !== undefined)
+        amounts.Bid = params.bid;
+    if (params.context_bid !== undefined)
+        amounts.ContextBid = params.context_bid;
+    const bids = target.ids.map((id) => ({ [target.field]: apiId(id), ...amounts }));
+    return formatResult(await apiPost("bids", "set", { Bids: bids }));
+}

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

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const listKeywordsSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodInt>;
+    offset: z.ZodOptional<z.ZodInt>;
+    ad_group_ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const addKeywordsSchema: z.ZodObject<{
+    ad_group_id: z.ZodString;
+    keywords: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const manageKeywordsSchema: z.ZodObject<{
+    keyword_ids: z.ZodArray<z.ZodString>;
+    action: z.ZodLiteral<"delete" | "resume" | "suspend">;
+}, z.core.$strip>;
+export declare const setKeywordBidsSchema: z.ZodObject<{
+    keyword_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ad_group_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    campaign_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    bid: z.ZodOptional<z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>>;
+    context_bid: z.ZodOptional<z.ZodPipe<z.ZodNumber, z.ZodTransform<number, number>>>;
+}, z.core.$strip>;

package/dist/tools/keywords/schema.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { KEYWORD_ACTIONS } from "#shared/config/enums";
+import { idField } from "#shared/lib/id";
+import { rublesField } from "#shared/lib/money";
+import { pageFields } from "#shared/lib/pagination";
+export const listKeywordsSchema = z.object({
+    ad_group_ids: z
+        .array(idField("ID группы объявлений"))
+        .check(z.minLength(1, { error: "Укажите хотя бы одну группу" }))
+        .meta({ description: "Группы, ключевые фразы которых нужно выбрать" }),
+    ...pageFields
+});
+export const addKeywordsSchema = z.object({
+    ad_group_id: idField("ID группы, в которую добавляются фразы"),
+    keywords: z
+        .array(z.string().check(z.minLength(1, { error: "Ключевая фраза не может быть пустой" })))
+        .check(z.minLength(1, { error: "Список фраз пуст" }))
+        .meta({ description: "Ключевые фразы; минус-слова внутри фразы записываются через дефис" })
+});
+export const manageKeywordsSchema = z.object({
+    keyword_ids: z
+        .array(idField("ID ключевой фразы"))
+        .check(z.minLength(1, { error: "Список фраз пуст" }))
+        .meta({ description: "Фразы, над которыми выполняется действие" }),
+    action: z.literal(KEYWORD_ACTIONS).meta({ description: "Действие: suspend, resume или delete (необратимо)" })
+});
+// Ставка ставится ровно на один уровень целей: фразы, группы или кампании.
+// Проверку «ровно один» делает хендлер — она про сочетание полей, а не про поле.
+export const setKeywordBidsSchema = z.object({
+    keyword_ids: z.array(idField("ID ключевой фразы")).optional().meta({ description: "Ставки на уровне фраз" }),
+    ad_group_ids: z
+        .array(idField("ID группы объявлений"))
+        .optional()
+        .meta({ description: "Ставки на все фразы указанных групп" }),
+    campaign_ids: z
+        .array(idField("ID кампании"))
+        .optional()
+        .meta({ description: "Ставки на все фразы указанных кампаний" }),
+    bid: rublesField("Ставка на поиске в рублях").optional(),
+    context_bid: rublesField("Ставка в сетях (РСЯ) в рублях").optional()
+});

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

@@ -0,0 +1,4 @@
+export declare const listKeywordsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const addKeywordsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const manageKeywordsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const setKeywordBidsTool: import("#shared/lib/tool").ToolDescriptor;

package/dist/tools/keywords/tool.js

@@ -0,0 +1,35 @@
+import { DESTRUCTIVE, defineTool, IDEMPOTENT, READ, WRITE } from "#shared/lib/tool";
+import { handleAddKeywords, handleListKeywords, handleManageKeywords, handleSetKeywordBids } from "./handler.js";
+import { addKeywordsSchema, listKeywordsSchema, manageKeywordsSchema, setKeywordBidsSchema } from "./schema.js";
+export const listKeywordsTool = defineTool({
+    name: "list_keywords",
+    title: "Список ключевых слов",
+    description: "Ключевые фразы в группах объявлений: фразы, ставки (руб), статусы.",
+    annotations: READ,
+    schema: listKeywordsSchema,
+    handler: handleListKeywords
+});
+export const addKeywordsTool = defineTool({
+    name: "add_keywords",
+    title: "Добавить ключевые слова",
+    description: "Добавить ключевые фразы в группу объявлений.",
+    annotations: WRITE,
+    schema: addKeywordsSchema,
+    handler: handleAddKeywords
+});
+export const manageKeywordsTool = defineTool({
+    name: "manage_keywords",
+    title: "Управление ключевыми словами",
+    description: "Действие над ключевыми фразами: suspend/resume/delete. ⚠️ delete необратимо.",
+    annotations: DESTRUCTIVE,
+    schema: manageKeywordsSchema,
+    handler: handleManageKeywords
+});
+export const setKeywordBidsTool = defineTool({
+    name: "set_keyword_bids",
+    title: "Установить ставки",
+    description: "Установить ставки (поиск/сети, в рублях) на уровне фраз, групп или кампаний (сервис Bids).",
+    annotations: IDEMPOTENT,
+    schema: setKeywordBidsSchema,
+    handler: handleSetKeywordBids
+});

package/dist/tools/negative-keywords/handler.d.ts

@@ -0,0 +1,8 @@
+import type { z } from "zod";
+import type { getCampaignNegativeKeywordsSchema, linkNegativeKeywordSetsSchema, listNegativeKeywordSharedSetsSchema, manageNegativeKeywordSharedSetsSchema, setAdGroupNegativeKeywordsSchema, setCampaignNegativeKeywordsSchema } from "./schema.js";
+export declare function handleGetCampaignNegativeKeywords(params: z.infer<typeof getCampaignNegativeKeywordsSchema>): Promise<string>;
+export declare function handleSetCampaignNegativeKeywords(params: z.infer<typeof setCampaignNegativeKeywordsSchema>): Promise<string>;
+export declare function handleSetAdGroupNegativeKeywords(params: z.infer<typeof setAdGroupNegativeKeywordsSchema>): Promise<string>;
+export declare function handleListNegativeKeywordSharedSets(params: z.infer<typeof listNegativeKeywordSharedSetsSchema>): Promise<string>;
+export declare function handleManageNegativeKeywordSharedSets(params: z.infer<typeof manageNegativeKeywordSharedSetsSchema>): Promise<string>;
+export declare function handleLinkNegativeKeywordSets(params: z.infer<typeof linkNegativeKeywordSetsSchema>): Promise<string>;

package/dist/tools/negative-keywords/handler.js

@@ -0,0 +1,135 @@
+import { apiPost } from "#shared/api/client";
+import { formatResult } from "#shared/lib/format";
+import { apiId, apiIds } from "#shared/lib/id";
+import { buildPage } from "#shared/lib/pagination";
+import { mergeNegativeKeywords } from "./merge.js";
+import { buildCampaignLink } from "./shared-set-link.js";
+// В домене нет денег: money: false бережёт от конвертации полей, которые ими не являются.
+const NO_MONEY = { money: false };
+export async function handleGetCampaignNegativeKeywords(params) {
+    const data = await apiPost("campaigns", "get", {
+        SelectionCriteria: { Ids: apiIds(params.campaign_ids) },
+        FieldNames: ["Id", "Name", "NegativeKeywords"]
+    });
+    return formatResult(data, NO_MONEY);
+}
+// NegativeKeywords обязано быть в FieldNames: без него Директ вернёт существующую
+// кампанию вообще без этого поля, слияние даст один входящий список, а update пройдёт
+// успешно — прежние минус-фразы исчезнут молча. Отсутствие сущности в ответе — ошибка,
+// а не пустой список: сливать не с чем.
+async function readExistingKeywords(service, collection, label, id) {
+    const data = await apiPost(service, "get", {
+        SelectionCriteria: { Ids: apiIds([id]) },
+        FieldNames: ["Id", "NegativeKeywords"]
+    });
+    const found = data?.result?.[collection];
+    const entity = Array.isArray(found) ? found[0] : undefined;
+    if (!entity)
+        throw new Error(`${label} ${id} не найдена или недоступна — объединять минус-фразы не с чем.`);
+    // У сущности без минус-фраз поле приходит как null, а не пропущенным ключом и не пустым
+    // Items (пробой 05.09.2026) — тип обязан это допускать, иначе `?.` выглядит перестраховкой.
+    return entity.NegativeKeywords?.Items ?? [];
+}
+// Коллекция очищается значением null, а не пустым Items: { Items: [] } Директ отклоняет
+// ошибкой 8000 «Количество элементов в массиве … должно быть не менее 1», { Items: null } —
+// «Items не может иметь значение null». В WSDL это видно как nillable="true" на самом поле;
+// подтверждено сетевым тестом и для NegativeKeywords, и для NegativeKeywordSharedSetIds.
+// Правило одно на домен и живёт здесь одним местом: «очистить» — это null, всегда.
+const itemsOrNull = (items) => (items.length > 0 ? { Items: items } : null);
+// replace остаётся одним вызовом: читать нечего, прежний список и так затирается.
+async function resolveItems(params, readExisting) {
+    if (params.mode === "replace")
+        return params.negative_keywords;
+    return mergeNegativeKeywords(await readExisting(), params.negative_keywords, params.mode);
+}
+export async function handleSetCampaignNegativeKeywords(params) {
+    const items = await resolveItems(params, () => readExistingKeywords("campaigns", "Campaigns", "Кампания", params.campaign_id));
+    const data = await apiPost("campaigns", "update", {
+        Campaigns: [{ Id: apiId(params.campaign_id), NegativeKeywords: itemsOrNull(items) }]
+    });
+    return formatResult(data);
+}
+export async function handleSetAdGroupNegativeKeywords(params) {
+    const items = await resolveItems(params, () => readExistingKeywords("adgroups", "AdGroups", "Группа объявлений", params.ad_group_id));
+    const data = await apiPost("adgroups", "update", {
+        AdGroups: [{ Id: apiId(params.ad_group_id), NegativeKeywords: itemsOrNull(items) }]
+    });
+    return formatResult(data);
+}
+export async function handleListNegativeKeywordSharedSets(params) {
+    const request = { FieldNames: ["Id", "Name", "NegativeKeywords", "Associated"] };
+    if (params.set_ids?.length)
+        request.SelectionCriteria = { Ids: apiIds(params.set_ids) };
+    const page = buildPage(params);
+    if (page)
+        request.Page = page;
+    return formatResult(await apiPost("negativekeywordsharedsets", "get", request), NO_MONEY);
+}
+function buildUpdateItem(set) {
+    if (set.name === undefined && set.negative_keywords === undefined) {
+        throw new Error("Для каждого update_sets укажите name и/или negative_keywords.");
+    }
+    const item = { Id: apiId(set.set_id) };
+    if (set.name !== undefined)
+        item.Name = set.name;
+    if (set.negative_keywords !== undefined)
+        item.NegativeKeywords = set.negative_keywords;
+    return item;
+}
+export async function handleManageNegativeKeywordSharedSets(params) {
+    if (params.action === "add") {
+        if (!params.add_sets?.length)
+            throw new Error("Для action=add передайте add_sets.");
+        const data = await apiPost("negativekeywordsharedsets", "add", {
+            NegativeKeywordSharedSets: params.add_sets.map((set) => ({
+                Name: set.name,
+                NegativeKeywords: set.negative_keywords
+            }))
+        });
+        return formatResult(data, NO_MONEY);
+    }
+    if (params.action === "update") {
+        if (!params.update_sets?.length)
+            throw new Error("Для action=update передайте update_sets.");
+        const data = await apiPost("negativekeywordsharedsets", "update", {
+            NegativeKeywordSharedSets: params.update_sets.map(buildUpdateItem)
+        });
+        return formatResult(data, NO_MONEY);
+    }
+    if (!params.set_ids?.length)
+        throw new Error("Для action=delete передайте set_ids.");
+    const data = await apiPost("negativekeywordsharedsets", "delete", {
+        SelectionCriteria: { Ids: apiIds(params.set_ids) }
+    });
+    return formatResult(data, NO_MONEY);
+}
+// Типы читаются одним вызовом на все кампании сразу, а не по одной: имя объекта настроек
+// зависит от типа, но сам запрос от этого не дробится.
+async function readCampaignTypes(campaignIds) {
+    const data = await apiPost("campaigns", "get", {
+        SelectionCriteria: { Ids: apiIds(campaignIds) },
+        FieldNames: ["Id", "Type"]
+    });
+    const campaigns = data.result?.Campaigns ?? [];
+    return new Map(campaigns.map((campaign) => [String(campaign.Id), campaign.Type]));
+}
+// Привязка наборов перезаписывается целиком: список, отправленный здесь, становится
+// единственным для объекта. Кампании и группы — два разных вызова API, и оба выполняются,
+// если заданы оба: ответы форматируются отдельно, чтобы per-item ошибки не потерялись.
+export async function handleLinkNegativeKeywordSets(params) {
+    const sharedSetIds = itemsOrNull(apiIds(params.set_ids));
+    const sections = [];
+    if (params.campaign_ids?.length) {
+        const types = await readCampaignTypes(params.campaign_ids);
+        const campaigns = params.campaign_ids.map((campaignId) => buildCampaignLink(campaignId, types.get(campaignId), sharedSetIds));
+        sections.push(formatResult(await apiPost("campaigns", "update", { Campaigns: campaigns }), NO_MONEY));
+    }
+    if (params.ad_group_ids?.length) {
+        const adGroups = params.ad_group_ids.map((adGroupId) => ({
+            Id: apiId(adGroupId),
+            NegativeKeywordSharedSetIds: sharedSetIds
+        }));
+        sections.push(formatResult(await apiPost("adgroups", "update", { AdGroups: adGroups }), NO_MONEY));
+    }
+    return sections.join("\n\n");
+}

package/dist/tools/negative-keywords/merge.d.ts

@@ -0,0 +1,2 @@
+export type NegativeKeywordsMode = "replace" | "add" | "remove";
+export declare function mergeNegativeKeywords(existing: string[], incoming: string[], mode: NegativeKeywordsMode): string[];

package/dist/tools/negative-keywords/merge.js

@@ -0,0 +1,36 @@
+// Слияние минус-фраз для режимов add и remove. Директ перезаписывает
+// NegativeKeywords.Items целиком, поэтому объединять обязан сценарий — а здесь это
+// чистая функция, чтобы правило сравнения проверялось обычным тестом, а не двумя
+// подменами fetch подряд.
+// Сравнивать надо ровно так, как сравнивает Директ: строже — remove не найдёт фразу и
+// вернёт успех, ничего не удалив; слабее — add допишет дубль, который Директ отбросит.
+// Тождественны для него: регистр («СКИДКА» ≡ «скидка»), ё и е («дёшево» ≡ «дешево»),
+// краевые и повторные пробелы («весло  двойное» ≡ «весло двойное»), операторы
+// закрепления «!» и «+» («!стекло» ≡ «стекло», «+ремонт» ≡ «ремонт»).
+//
+// Смысл операторов описан в справке (keywords/symbols-and-operators): «+» и «!» фиксируют
+// стоп-слова и словоформу. Чего в справке нет — что Директ приписывает «!» сам: присланное
+// «своими руками» хранится как «!своими руками». Не игнорируй мы оператор, пользователь не
+// смог бы удалить фразу, которую сам же и написал. Это и равенство пар выше подтверждены
+// пробоем 05.09.2026 на кампании-полигоне; сетевой тест рядом держит их проверенными.
+const normalize = (keyword) => keyword.toLowerCase().replaceAll("ё", "е").replaceAll(/[!+]/g, "").replaceAll(/\s+/g, " ").trim();
+export function mergeNegativeKeywords(existing, incoming, mode) {
+    if (mode === "replace")
+        return incoming;
+    const incomingKeys = new Set(incoming.map(normalize));
+    if (mode === "remove")
+        return existing.filter((keyword) => !incomingKeys.has(normalize(keyword)));
+    // add: написание уже сохранённых фраз не трогаем, новые дописываем в конец. Порядок —
+    // наш внутренний, наружу он не доживает: Директ хранит список отсортированным по
+    // кодовым точкам и при схлопывании дубля оставляет написание первого вхождения.
+    const merged = [...existing];
+    const seen = new Set(existing.map(normalize));
+    for (const keyword of incoming) {
+        const key = normalize(keyword);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push(keyword.trim());
+    }
+    return merged;
+}

package/dist/tools/negative-keywords/schema.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export declare const getCampaignNegativeKeywordsSchema: z.ZodObject<{
+    campaign_ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const setCampaignNegativeKeywordsSchema: z.ZodObject<{
+    campaign_id: z.ZodString;
+    negative_keywords: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"add" | "remove" | "replace">;
+}, z.core.$strip>;
+export declare const setAdGroupNegativeKeywordsSchema: z.ZodObject<{
+    ad_group_id: z.ZodString;
+    negative_keywords: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"add" | "remove" | "replace">;
+}, z.core.$strip>;
+export declare const listNegativeKeywordSharedSetsSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodInt>;
+    offset: z.ZodOptional<z.ZodInt>;
+    set_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const manageNegativeKeywordSharedSetsSchema: z.ZodObject<{
+    action: z.ZodLiteral<"add" | "delete" | "update">;
+    add_sets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        negative_keywords: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    update_sets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        set_id: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        negative_keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    set_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const linkNegativeKeywordSetsSchema: z.ZodObject<{
+    ad_group_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    campaign_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    set_ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;