yandex-direct-mcp-plus 1.3.0

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

@@ -0,0 +1,139 @@
+// В домене две разные сущности, отсюда и два набора инструментов. Собственные минус-фразы
+// кампании или группы — список, живущий внутри неё. Общий набор — именованный список
+// уровня аккаунта: он заводится один раз и переиспользуется, поэтому у него свой сервис,
+// своя форма поля (голый массив, не { Items: [...] }) и отдельная привязка к объекту.
+//
+// Минус-фразы Директа перезаписываются целиком: и NegativeKeywords.Items, и привязки
+// наборов. Инструменты этого домена названы set_*/link_* именно поэтому — они задают
+// новое значение, а не дополняют старое. Режимы add и remove у set_*_negative_keywords
+// прячут чтение и слияние внутрь сервера, чтобы «добавить одну фразу» не оборачивалось
+// стёртым списком; link_* и наборы по-прежнему только заменяют.
+import { z } from "zod";
+import { NEGATIVE_KEYWORD_SET_ACTIONS } from "#shared/config/enums";
+import { MAX_AD_GROUPS_PER_CALL, MAX_CAMPAIGNS_PER_CALL, MAX_SHARED_SETS_PER_AD_GROUP, MAX_SHARED_SETS_PER_CALL, SHARED_SET_NAME_MAX } from "#shared/config/limits";
+import { idField } from "#shared/lib/id";
+import { pageFields } from "#shared/lib/pagination";
+const negativeKeyword = z
+    .string()
+    .check(z.minLength(1, { error: "Минус-фраза не может быть пустой" }), z.regex(/\S/, { error: "Минус-фраза не может состоять из одних пробелов" }));
+// Режим общий для кампании и группы: снаружи это один и тот же вопрос «заменить,
+// дописать или убрать». Значения по умолчанию нет намеренно: replace затирает список
+// целиком, и пропуск поля на просьбе «добавь одну фразу» стёр бы всё остальное молча —
+// Директ ответил бы успехом. Обязательное поле превращает пропуск в ошибку валидации
+// до записи, то есть требует назвать намерение вслух.
+const negativeKeywordsMode = () => z.literal(["replace", "add", "remove"]).meta({
+    description: "Обязателен. replace — заменить список целиком (пустой массив очищает, прежние фразы теряются), add — дописать к текущим, remove — убрать перечисленные. add и remove сначала читают текущий список, это дополнительный вызов API. Фразы сравниваются так же, как их сравнивает Директ: без учёта регистра, буквы ё и е равны, краевые и повторные пробелы не учитываются, операторы закрепления ! и + игнорируются"
+});
+export const getCampaignNegativeKeywordsSchema = z.object({
+    campaign_ids: z
+        .array(idField("ID кампании"))
+        .check(z.minLength(1, { error: "Список кампаний пуст" }), z.maxLength(MAX_CAMPAIGNS_PER_CALL, {
+        error: `За один вызов допустимо не больше ${MAX_CAMPAIGNS_PER_CALL} кампаний`
+    }))
+        .meta({ description: "Кампании, минус-фразы которых нужно прочитать" })
+});
+export const setCampaignNegativeKeywordsSchema = z.object({
+    campaign_id: idField("ID кампании"),
+    negative_keywords: z.array(negativeKeyword).meta({
+        description: "Минус-фразы кампании: при mode=replace — полный новый список взамен прежнего, при add — что дописать, при remove — что убрать"
+    }),
+    mode: negativeKeywordsMode()
+});
+export const setAdGroupNegativeKeywordsSchema = z.object({
+    ad_group_id: idField("ID группы объявлений"),
+    negative_keywords: z.array(negativeKeyword).meta({
+        description: "Минус-фразы группы: при mode=replace — полный новый список взамен прежнего, при add — что дописать, при remove — что убрать"
+    }),
+    mode: negativeKeywordsMode()
+});
+export const listNegativeKeywordSharedSetsSchema = z.object({
+    set_ids: z
+        .array(idField("ID общего набора минус-фраз"))
+        .check(z.maxLength(MAX_SHARED_SETS_PER_CALL, {
+        error: `За один вызов допустимо не больше ${MAX_SHARED_SETS_PER_CALL} наборов`
+    }))
+        .optional()
+        .meta({ description: "Конкретные наборы; без них возвращаются все наборы аккаунта" }),
+    ...pageFields
+});
+const sharedSetName = z
+    .string()
+    .check(z.minLength(1, { error: "Название не может быть пустым" }), z.maxLength(SHARED_SET_NAME_MAX, { error: `Название длиннее ${SHARED_SET_NAME_MAX} символов` }));
+const addSharedSet = z.object({
+    name: sharedSetName.meta({ description: "Название набора" }),
+    negative_keywords: z
+        .array(negativeKeyword)
+        .check(z.minLength(1, { error: "Набор не может быть пустым" }))
+        .meta({ description: "Минус-фразы набора" })
+});
+const updateSharedSet = z.object({
+    set_id: idField("ID изменяемого набора"),
+    name: sharedSetName.optional().meta({ description: "Новое название набора" }),
+    negative_keywords: z
+        .array(negativeKeyword)
+        .optional()
+        .meta({ description: "Полный новый список минус-фраз набора — прежний затирается целиком" })
+});
+// Функция, а не готовая проверка: один и тот же объект проверки не переиспользуется
+// тремя схемами — каждая получает свой.
+const sharedSetsPerCall = () => z.maxLength(MAX_SHARED_SETS_PER_CALL, { error: `Не больше ${MAX_SHARED_SETS_PER_CALL} наборов за вызов` });
+export const manageNegativeKeywordSharedSetsSchema = z.object({
+    action: z.literal(NEGATIVE_KEYWORD_SET_ACTIONS).meta({
+        description: "Что сделать с наборами: add, update или delete (необратимо)"
+    }),
+    add_sets: z
+        .array(addSharedSet)
+        .check(z.minLength(1, { error: "Список наборов пуст" }), sharedSetsPerCall())
+        .optional()
+        .meta({ description: "Наборы для создания; обязателен при action=add" }),
+    update_sets: z
+        .array(updateSharedSet)
+        .check(z.minLength(1, { error: "Список наборов пуст" }), sharedSetsPerCall())
+        .optional()
+        .meta({ description: "Наборы для изменения; обязателен при action=update" }),
+    set_ids: z
+        .array(idField("ID общего набора минус-фраз"))
+        .check(z.minLength(1, { error: "Список наборов пуст" }), sharedSetsPerCall())
+        .optional()
+        .meta({ description: "Наборы для удаления; обязателен при action=delete" })
+});
+// Набор привязывается и к группе, и к кампании — это одно и то же действие над разными
+// объектами, поэтому инструмент один. Оба списка необязательны по отдельности, но пустым
+// вызов быть не может: проверку несёт сам объект, иначе «ничего не сделал» вернулось бы
+// успехом.
+export const linkNegativeKeywordSetsSchema = z
+    .object({
+    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_CALL, {
+        error: `За один вызов допустимо не больше ${MAX_CAMPAIGNS_PER_CALL} кампаний`
+    }))
+        .optional()
+        .meta({
+        description: "Кампании, которым назначаются наборы. Привязка на уровне кампании действует на все её группы. Тип кампании сервер читает сам — это дополнительный вызов API; общие наборы поддерживают TEXT_CAMPAIGN, DYNAMIC_TEXT_CAMPAIGN, MOBILE_APP_CAMPAIGN и UNIFIED_CAMPAIGN"
+    }),
+    set_ids: z
+        .array(idField("ID общего набора минус-фраз"))
+        .check(z.maxLength(MAX_SHARED_SETS_PER_AD_GROUP, {
+        error: `К объекту привязывается не больше ${MAX_SHARED_SETS_PER_AD_GROUP} наборов`
+    }))
+        .meta({
+        description: "Полный новый список наборов объекта — прежние привязки затираются. Пустой массив снимает все"
+    })
+})
+    .check((ctx) => {
+    if (ctx.value.ad_group_ids?.length || ctx.value.campaign_ids?.length)
+        return;
+    ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        message: "Укажите ad_group_ids и/или campaign_ids — кому назначаются наборы"
+    });
+});

package/dist/tools/negative-keywords/shared-set-link.d.ts

@@ -0,0 +1,3 @@
+export declare function buildCampaignLink(campaignId: string, campaignType: string | undefined, sharedSetIds: {
+    Items: bigint[];
+} | null): Record<string, unknown>;

package/dist/tools/negative-keywords/shared-set-link.js

@@ -0,0 +1,21 @@
+// Привязка общих наборов к кампании устроена не так, как к группе. У группы
+// NegativeKeywordSharedSetIds — поле верхнего уровня; у кампании оно спрятано внутрь
+// объекта настроек, а имя этого объекта зависит от типа кампании и берётся из
+// #shared/lib/campaign-type. Тип в запросе на привязку не передаётся, поэтому сценарий
+// читает его перед записью, а здесь лежит чистая часть — проверка типа и сборка элемента.
+import { getCampaignSettingsKey } from "#shared/lib/campaign-type";
+import { apiId } from "#shared/lib/id";
+// Свой список, а не общий: набор поддерживающих типов у каждого поля свой. Сверено с WSDL
+// campaigns 05.09.2026 — NegativeKeywordSharedSetIds объявлен в TextCampaignBase,
+// DynamicTextCampaignBase, UnifiedCampaignBase и MobileAppCampaignUpdateItem, но не в
+// SmartCampaign и не в CpmBannerCampaign.
+const SUPPORTED_TYPES = ["TEXT_CAMPAIGN", "DYNAMIC_TEXT_CAMPAIGN", "MOBILE_APP_CAMPAIGN", "UNIFIED_CAMPAIGN"];
+// Тип, которого нет в списке, молча пропустить нельзя: вызов вернул бы успех, а набор
+// остался бы непривязанным.
+export function buildCampaignLink(campaignId, campaignType, sharedSetIds) {
+    const settingsKey = campaignType && SUPPORTED_TYPES.includes(campaignType) ? getCampaignSettingsKey(campaignType) : undefined;
+    if (!settingsKey) {
+        throw new Error(`Кампания ${campaignId} имеет тип ${campaignType ?? "неизвестный"}, а общие наборы минус-фраз поддерживают только ${SUPPORTED_TYPES.join(", ")}.`);
+    }
+    return { Id: apiId(campaignId), [settingsKey]: { NegativeKeywordSharedSetIds: sharedSetIds } };
+}

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

@@ -0,0 +1,6 @@
+export declare const getCampaignNegativeKeywordsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const setCampaignNegativeKeywordsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const setAdGroupNegativeKeywordsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const listNegativeKeywordSharedSetsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const manageNegativeKeywordSharedSetsTool: import("#shared/lib/tool").ToolDescriptor;
+export declare const linkNegativeKeywordSetsTool: import("#shared/lib/tool").ToolDescriptor;

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

@@ -0,0 +1,51 @@
+import { DESTRUCTIVE, defineTool, IDEMPOTENT, READ } from "#shared/lib/tool";
+import { handleGetCampaignNegativeKeywords, handleLinkNegativeKeywordSets, handleListNegativeKeywordSharedSets, handleManageNegativeKeywordSharedSets, handleSetAdGroupNegativeKeywords, handleSetCampaignNegativeKeywords } from "./handler.js";
+import { getCampaignNegativeKeywordsSchema, linkNegativeKeywordSetsSchema, listNegativeKeywordSharedSetsSchema, manageNegativeKeywordSharedSetsSchema, setAdGroupNegativeKeywordsSchema, setCampaignNegativeKeywordsSchema } from "./schema.js";
+export const getCampaignNegativeKeywordsTool = defineTool({
+    name: "get_campaign_negative_keywords",
+    title: "Получить минус-фразы кампаний",
+    description: "Получить текущие минус-фразы кампаний по их ID.",
+    annotations: READ,
+    schema: getCampaignNegativeKeywordsSchema,
+    handler: handleGetCampaignNegativeKeywords
+});
+export const setCampaignNegativeKeywordsTool = defineTool({
+    name: "set_campaign_negative_keywords",
+    title: "Минус-фразы кампании",
+    description: "Минус-фразы на уровне кампании. Режим mode обязателен: replace заменяет список целиком (прежние фразы теряются, пустой массив очищает), add дописывает к текущим, remove убирает названные — читать список перед этим не нужно, add и remove делают это сами. Чтобы добавить фразу к существующим, нужен add: replace с одной фразой сотрёт остальные.",
+    annotations: DESTRUCTIVE,
+    schema: setCampaignNegativeKeywordsSchema,
+    handler: handleSetCampaignNegativeKeywords
+});
+export const setAdGroupNegativeKeywordsTool = defineTool({
+    name: "set_ad_group_negative_keywords",
+    title: "Минус-фразы группы",
+    description: "Минус-фразы на уровне группы объявлений. Режим mode обязателен: replace заменяет список целиком (прежние фразы теряются, пустой массив очищает), add дописывает к текущим, remove убирает названные — читать список перед этим не нужно, add и remove делают это сами. Чтобы добавить фразу к существующим, нужен add: replace с одной фразой сотрёт остальные.",
+    annotations: DESTRUCTIVE,
+    schema: setAdGroupNegativeKeywordsSchema,
+    handler: handleSetAdGroupNegativeKeywords
+});
+export const listNegativeKeywordSharedSetsTool = defineTool({
+    name: "list_negative_keyword_shared_sets",
+    title: "Общие наборы минус-фраз",
+    description: "Получить общие наборы минус-фраз аккаунта.",
+    annotations: READ,
+    schema: listNegativeKeywordSharedSetsSchema,
+    handler: handleListNegativeKeywordSharedSets
+});
+export const manageNegativeKeywordSharedSetsTool = defineTool({
+    name: "manage_negative_keyword_shared_sets",
+    title: "Управление общими минус-фразами",
+    description: "Создать, изменить или удалить общие наборы минус-фраз аккаунта.",
+    annotations: DESTRUCTIVE,
+    schema: manageNegativeKeywordSharedSetsSchema,
+    handler: handleManageNegativeKeywordSharedSets
+});
+export const linkNegativeKeywordSetsTool = defineTool({
+    name: "link_negative_keyword_sets",
+    title: "Привязать общие минус-фразы",
+    description: "Заменить привязки общих наборов минус-фраз у кампаний и/или групп объявлений. Привязка к кампании действует на все её группы. Пустой set_ids очищает привязки.",
+    annotations: IDEMPOTENT,
+    schema: linkNegativeKeywordSetsSchema,
+    handler: handleLinkNegativeKeywordSets
+});

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

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

package/dist/tools/retargeting/handler.js

@@ -0,0 +1,47 @@
+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 NO_MONEY = { money: false };
+const LIST_FIELDS = [
+    "Type",
+    "Id",
+    "Name",
+    "Description",
+    "Rules",
+    "IsAvailable",
+    "Scope",
+    "AvailableForTargetsInAdGroupTypes"
+];
+export async function handleListRetargetingLists(params) {
+    const selection = {};
+    if (params.retargeting_list_ids?.length)
+        selection.Ids = apiIds(params.retargeting_list_ids);
+    if (params.types?.length)
+        selection.Types = params.types;
+    const request = { FieldNames: LIST_FIELDS };
+    if (Object.keys(selection).length > 0)
+        request.SelectionCriteria = selection;
+    const page = buildPage(params);
+    if (page)
+        request.Page = page;
+    return formatResult(await apiPost("retargetinglists", "get", request), NO_MONEY);
+}
+export async function handleAddRetargetingList(params) {
+    const retargetingList = {
+        Name: params.name,
+        Type: params.type,
+        Rules: params.rules.map((rule) => ({
+            Operator: rule.operator,
+            Arguments: rule.arguments.map((argument) => {
+                const item = { ExternalId: apiId(argument.external_id) };
+                if (argument.membership_life_span !== undefined)
+                    item.MembershipLifeSpan = argument.membership_life_span;
+                return item;
+            })
+        }))
+    };
+    if (params.description !== undefined)
+        retargetingList.Description = params.description;
+    return formatResult(await apiPost("retargetinglists", "add", { RetargetingLists: [retargetingList] }), NO_MONEY);
+}

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

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export declare const listRetargetingListsSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodInt>;
+    offset: z.ZodOptional<z.ZodInt>;
+    retargeting_list_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    types: z.ZodOptional<z.ZodArray<z.ZodLiteral<"AUDIENCE" | "RETARGETING">>>;
+}, z.core.$strip>;
+export declare const addRetargetingListSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodDefault<z.ZodLiteral<"AUDIENCE" | "RETARGETING">>;
+    description: z.ZodOptional<z.ZodString>;
+    rules: z.ZodArray<z.ZodObject<{
+        operator: z.ZodLiteral<"ALL" | "ANY" | "NONE">;
+        arguments: z.ZodArray<z.ZodObject<{
+            external_id: z.ZodString;
+            membership_life_span: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/tools/retargeting/schema.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { RETARGETING_RULE_OPERATORS, RETARGETING_TYPES } from "#shared/config/enums";
+import { MAX_IDS_PER_CALL, RETARGETING_LIMITS } from "#shared/config/limits";
+import { idField } from "#shared/lib/id";
+import { pageFields } from "#shared/lib/pagination";
+export const listRetargetingListsSchema = z.object({
+    retargeting_list_ids: z
+        .array(idField("ID условия ретаргетинга"))
+        .check(z.maxLength(MAX_IDS_PER_CALL, { error: `За один вызов допустимо не больше ${MAX_IDS_PER_CALL} условий` }))
+        .optional()
+        .meta({ description: "Конкретные условия; без них возвращаются все" }),
+    types: z
+        .array(z.literal(RETARGETING_TYPES))
+        .optional()
+        .meta({ description: "Фильтр по типу: RETARGETING — цели Метрики, AUDIENCE — сегменты Аудиторий" }),
+    ...pageFields
+});
+const ruleArgument = z.object({
+    external_id: idField("ID цели Метрики или сегмента Аудиторий"),
+    membership_life_span: z
+        .int()
+        .check(z.gte(1, { error: "Срок не меньше одного дня" }), z.lte(RETARGETING_LIMITS.membershipDays, { error: `Срок не больше ${RETARGETING_LIMITS.membershipDays} дней` }))
+        .optional()
+        .meta({
+        description: `За сколько последних дней учитывать выполнение цели, 1–${RETARGETING_LIMITS.membershipDays}`
+    })
+});
+const rule = z.object({
+    operator: z.literal(RETARGETING_RULE_OPERATORS).meta({
+        description: "Как соединять условия: ALL — выполнены все, ANY — хотя бы одно, NONE — ни одного"
+    }),
+    arguments: z
+        .array(ruleArgument)
+        .check(z.minLength(1, { error: "Правило без условий" }))
+        .meta({ description: "Цели и сегменты, на которых строится правило" })
+});
+export const addRetargetingListSchema = z.object({
+    name: z
+        .string()
+        .check(z.minLength(1, { error: "Название не может быть пустым" }), z.maxLength(RETARGETING_LIMITS.name, { error: `Название длиннее ${RETARGETING_LIMITS.name} символов` }))
+        .meta({ description: "Название условия ретаргетинга" }),
+    type: z
+        .literal(RETARGETING_TYPES)
+        .default("RETARGETING")
+        .meta({ description: "RETARGETING — по целям Метрики, AUDIENCE — по сегментам Яндекс.Аудиторий" }),
+    description: z
+        .string()
+        .check(z.maxLength(RETARGETING_LIMITS.description, {
+        error: `Описание длиннее ${RETARGETING_LIMITS.description} символов`
+    }))
+        .optional()
+        .meta({ description: "Описание условия — видно только в интерфейсе, на показы не влияет" }),
+    rules: z
+        .array(rule)
+        .check(z.minLength(1, { error: "Условие без правил" }))
+        .meta({ description: "Правила условия; между собой они соединяются логическим И" })
+});

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

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

package/dist/tools/retargeting/tool.js

@@ -0,0 +1,19 @@
+import { defineTool, READ, WRITE } from "#shared/lib/tool";
+import { handleAddRetargetingList, handleListRetargetingLists } from "./handler.js";
+import { addRetargetingListSchema, listRetargetingListsSchema } from "./schema.js";
+export const listRetargetingListsTool = defineTool({
+    name: "list_retargeting_lists",
+    title: "Списки ретаргетинга",
+    description: "Получить условия ретаргетинга и подбора аудитории с правилами и областью применения.",
+    annotations: READ,
+    schema: listRetargetingListsSchema,
+    handler: handleListRetargetingLists
+});
+export const addRetargetingListTool = defineTool({
+    name: "add_retargeting_list",
+    title: "Создать список ретаргетинга",
+    description: "Создать условие ретаргетинга из целей Метрики, сегментов или интересов.",
+    annotations: WRITE,
+    schema: addRetargetingListSchema,
+    handler: handleAddRetargetingList
+});

package/dist/tools/search-queries/handler.d.ts

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

package/dist/tools/search-queries/handler.js

@@ -0,0 +1,28 @@
+import { apiReport } from "#shared/api/reports";
+import { reportName } from "#shared/lib/report";
+const DEFAULT_FIELDS = [
+    "Query",
+    "CampaignId",
+    "CampaignName",
+    "AdGroupId",
+    "AdGroupName",
+    "Criterion",
+    "Impressions",
+    "Clicks",
+    "Cost"
+];
+export async function handleGetSearchQueries(params) {
+    return apiReport({
+        SelectionCriteria: {
+            DateFrom: params.date_from,
+            DateTo: params.date_to,
+            Filter: [{ Field: "CampaignId", Operator: "IN", Values: params.campaign_ids }]
+        },
+        FieldNames: params.fields ?? DEFAULT_FIELDS,
+        ReportName: reportName("search_queries"),
+        ReportType: "SEARCH_QUERY_PERFORMANCE_REPORT",
+        DateRangeType: "CUSTOM_DATE",
+        Format: "TSV",
+        IncludeVAT: "YES"
+    });
+}

package/dist/tools/search-queries/schema.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const getSearchQueriesSchema: z.ZodObject<{
+    campaign_ids: z.ZodArray<z.ZodString>;
+    date_from: z.ZodString;
+    date_to: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;

package/dist/tools/search-queries/schema.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { dateField } from "#shared/lib/date";
+import { idField } from "#shared/lib/id";
+export const getSearchQueriesSchema = z.object({
+    campaign_ids: z
+        .array(idField("ID кампании"))
+        .check(z.minLength(1, { error: "Укажите хотя бы одну кампанию" }))
+        .meta({ description: "Кампании, по которым нужен отчёт о поисковых запросах" }),
+    date_from: dateField("Первый день периода, YYYY-MM-DD"),
+    date_to: dateField("Последний день периода включительно, YYYY-MM-DD"),
+    fields: z
+        .array(z.string().check(z.minLength(1, { error: "Имя поля не может быть пустым" })))
+        .optional()
+        .meta({
+        description: "Поля отчёта; по умолчанию Query, CampaignId, CampaignName, AdGroupId, AdGroupName, Criterion, Impressions, Clicks, Cost"
+    })
+});

package/dist/tools/search-queries/tool.d.ts

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

package/dist/tools/search-queries/tool.js

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

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

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

package/dist/tools/sitelinks/handler.js

@@ -0,0 +1,28 @@
+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 handleListSitelinks(params) {
+    const request = {
+        FieldNames: ["Id"],
+        SitelinkFieldNames: ["Title", "Href", "Description", "TurboPageId"]
+    };
+    if (params.sitelink_set_ids?.length)
+        request.SelectionCriteria = { Ids: apiIds(params.sitelink_set_ids) };
+    const page = buildPage(params);
+    if (page)
+        request.Page = page;
+    return formatResult(await apiPost("sitelinks", "get", request), NO_MONEY);
+}
+export async function handleSetSitelinks(params) {
+    const sitelinks = params.sitelinks.map((link) => {
+        const item = { Title: link.title };
+        if (link.href !== undefined)
+            item.Href = link.href;
+        if (link.description !== undefined)
+            item.Description = link.description;
+        return item;
+    });
+    return formatResult(await apiPost("sitelinks", "add", { SitelinksSets: [{ Sitelinks: sitelinks }] }), NO_MONEY);
+}

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

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const listSitelinksSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodInt>;
+    offset: z.ZodOptional<z.ZodInt>;
+    sitelink_set_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const setSitelinksSchema: z.ZodObject<{
+    sitelinks: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        href: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/tools/sitelinks/schema.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { MAX_IDS_PER_CALL, SITELINK_LIMITS } from "#shared/config/limits";
+import { idField } from "#shared/lib/id";
+import { pageFields } from "#shared/lib/pagination";
+export const listSitelinksSchema = z.object({
+    sitelink_set_ids: z
+        .array(idField("ID набора быстрых ссылок"))
+        .check(z.maxLength(MAX_IDS_PER_CALL, { error: `За один вызов допустимо не больше ${MAX_IDS_PER_CALL} наборов` }))
+        .optional()
+        .meta({ description: "Конкретные наборы; без них возвращаются все наборы аккаунта" }),
+    ...pageFields
+});
+const sitelink = z.object({
+    title: z
+        .string()
+        .check(z.minLength(1, { error: "Текст ссылки не может быть пустым" }), z.maxLength(SITELINK_LIMITS.title, { error: `Текст ссылки длиннее ${SITELINK_LIMITS.title} символов` }))
+        .meta({ description: `Текст быстрой ссылки, до ${SITELINK_LIMITS.title} символов` }),
+    href: z
+        .string()
+        .check(z.maxLength(SITELINK_LIMITS.href, { error: `Ссылка длиннее ${SITELINK_LIMITS.href} символов` }))
+        .optional()
+        .meta({ description: "URL с протоколом и доменом" }),
+    description: z
+        .string()
+        .check(z.maxLength(SITELINK_LIMITS.description, { error: `Описание длиннее ${SITELINK_LIMITS.description} символов` }))
+        .optional()
+        .meta({ description: `Описание ссылки, до ${SITELINK_LIMITS.description} символов` })
+});
+// Набор создаётся целиком: Директ не умеет дописать ссылку в существующий набор.
+export const setSitelinksSchema = z.object({
+    sitelinks: z
+        .array(sitelink)
+        .check(z.minLength(1, { error: "Набор не может быть пустым" }), z.maxLength(SITELINK_LIMITS.perSet, { error: `В наборе не больше ${SITELINK_LIMITS.perSet} ссылок` }))
+        .meta({ description: `Новый набор из 1–${SITELINK_LIMITS.perSet} быстрых ссылок` })
+});

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

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

package/dist/tools/sitelinks/tool.js

@@ -0,0 +1,19 @@
+import { defineTool, READ, WRITE } from "#shared/lib/tool";
+import { handleListSitelinks, handleSetSitelinks } from "./handler.js";
+import { listSitelinksSchema, setSitelinksSchema } from "./schema.js";
+export const listSitelinksTool = defineTool({
+    name: "list_sitelinks",
+    title: "Список быстрых ссылок",
+    description: "Получить все или выбранные наборы быстрых ссылок.",
+    annotations: READ,
+    schema: listSitelinksSchema,
+    handler: handleListSitelinks
+});
+export const setSitelinksTool = defineTool({
+    name: "set_sitelinks",
+    title: "Создать быстрые ссылки",
+    description: "Создать новый набор из 1–8 быстрых ссылок. Возвращает ID набора для привязки к объявлению.",
+    annotations: WRITE,
+    schema: setSitelinksSchema,
+    handler: handleSetSitelinks
+});

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

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

package/dist/tools/statistics/handler.js

@@ -0,0 +1,20 @@
+import { apiReport } from "#shared/api/reports";
+import { reportName } from "#shared/lib/report";
+const DEFAULT_FIELDS = ["Date", "CampaignName", "Impressions", "Clicks", "Cost", "Ctr", "AvgCpc"];
+// Отчёт приходит готовым TSV: ReportService форматирует его сам, деньги отдаёт
+// в рублях (returnMoneyInMicros=false), поэтому formatResult здесь не участвует.
+export async function handleGetStatistics(params) {
+    return apiReport({
+        SelectionCriteria: {
+            DateFrom: params.date_from,
+            DateTo: params.date_to,
+            Filter: [{ Field: "CampaignId", Operator: "IN", Values: params.campaign_ids }]
+        },
+        FieldNames: params.fields ?? DEFAULT_FIELDS,
+        ReportName: reportName("report"),
+        ReportType: "CAMPAIGN_PERFORMANCE_REPORT",
+        DateRangeType: "CUSTOM_DATE",
+        Format: "TSV",
+        IncludeVAT: "YES"
+    });
+}

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

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const getStatisticsSchema: z.ZodObject<{
+    campaign_ids: z.ZodArray<z.ZodString>;
+    date_from: z.ZodString;
+    date_to: z.ZodString;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;

package/dist/tools/statistics/schema.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { dateField } from "#shared/lib/date";
+import { idField } from "#shared/lib/id";
+export const getStatisticsSchema = z.object({
+    campaign_ids: z
+        .array(idField("ID кампании"))
+        .check(z.minLength(1, { error: "Укажите хотя бы одну кампанию" }))
+        .meta({ description: "Кампании, по которым строится отчёт" }),
+    date_from: dateField("Первый день периода, YYYY-MM-DD"),
+    date_to: dateField("Последний день периода включительно, YYYY-MM-DD"),
+    fields: z
+        .array(z.string().check(z.minLength(1, { error: "Имя поля не может быть пустым" })))
+        .optional()
+        .meta({
+        description: "Поля отчёта; по умолчанию Date, CampaignName, Impressions, Clicks, Cost, Ctr, AvgCpc. Деньги приходят в рублях"
+    })
+});

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

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