@kaminari-ad/mcp 0.9.1 → 0.11.0

package/dist/{chunk-R56UDCOA.js → chunk-XCAKB2QW.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { err, ok } from './chunk-JEGBPX3R.js';
+import { err, ok } from './chunk-XSI6SZTX.js';
 import { createHash, randomUUID } from 'crypto';
 import createClient from 'openapi-fetch';
 import { fetch } from 'undici';
@@ -240,17 +240,22 @@ var ProxyTargetRequest = z.object({
   city: z.string().default(""),
   isp: z.string().default("")
 }).partial().passthrough();
+var RepeatModeType = z.enum(["isolated", "shared"]);
 z.object({
   url: z.union([z.string(), z.null()]).optional(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_code: z.string().min(2).max(2),
   emulator_id: z.string().min(1).max(100),
   proxy: ProxyTargetRequest.optional(),
   labels: z.record(z.string()).optional(),
   campaign_id: z.union([z.string(), z.null()]).optional(),
   run_id: z.union([z.string(), z.null()]).optional(),
-  ad_discovery: z.boolean().optional().default(false)
+  ad_discovery: z.boolean().optional().default(false),
+  repeat_count: z.number().int().gte(1).optional().default(1),
+  repeat_mode: RepeatModeType.optional(),
+  retry_max_attempts: z.number().int().gte(0).optional().default(0)
 }).passthrough();
 var ScanStatus = z.enum([
   "pending",
@@ -290,7 +295,8 @@ var VideoMetaResponse = z.object({
   vast_version: z.string().default(""),
   ad_system: z.string().default(""),
   is_vpaid: z.boolean().default(false),
-  wrapper_depth: z.number().int().default(0)
+  wrapper_depth: z.number().int().default(0),
+  click_through: z.string().default("")
 }).partial().passthrough();
 var ProxyTargetResponse = z.object({
   proxy_type: z.string(),
@@ -357,8 +363,12 @@ var ScanResponse = z.object({
   public_report_url: z.string().optional().default(""),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
-  creative_kind: z.string().optional().default("banner"),
+  referrer: z.union([z.string(), z.null()]).optional(),
+  creative_kind: z.enum(["banner", "video"]).optional().default("banner"),
   creative_screenshot_url: z.string().optional().default(""),
+  creative_video_url: z.string().optional().default(""),
+  vast_xml_url: z.string().optional().default(""),
+  creative_html_url: z.string().optional().default(""),
   creative_width: z.number().int().optional().default(0),
   creative_height: z.number().int().optional().default(0),
   video: z.union([VideoMetaResponse, z.null()]).optional(),
@@ -374,7 +384,13 @@ var ScanResponse = z.object({
   campaign_group_name: z.union([z.string(), z.null()]).optional(),
   created_at: z.string().datetime({ offset: true }),
   completed_at: z.union([z.string(), z.null()]),
-  landings: z.array(LandingResponse).optional()
+  landings: z.array(LandingResponse).optional(),
+  repeat_index: z.number().int().optional().default(0),
+  repeat_total: z.number().int().optional().default(1),
+  repeat_session_id: z.union([z.string(), z.null()]).optional(),
+  repeat_scan_ids: z.array(z.string().uuid()).optional(),
+  retry_attempt: z.number().int().optional().default(0),
+  retry_max_attempts: z.number().int().optional().default(0)
 }).passthrough();
 z.union([z.string(), z.null()]).optional();
 var ScanBriefResponse = z.object({
@@ -401,7 +417,12 @@ var ScanBriefResponse = z.object({
   ad_kind: z.union([z.string(), z.null()]).optional(),
   network: z.string().optional().default(""),
   emulator_display_name: z.string().optional().default(""),
-  emulator_category: z.string().optional().default("")
+  emulator_category: z.string().optional().default(""),
+  repeat_index: z.number().int().optional().default(0),
+  repeat_total: z.number().int().optional().default(1),
+  repeat_session_id: z.union([z.string(), z.null()]).optional(),
+  retry_attempt: z.number().int().optional().default(0),
+  retry_max_attempts: z.number().int().optional().default(0)
 }).passthrough();
 z.object({
   items: z.array(ScanBriefResponse),
@@ -414,10 +435,14 @@ z.object({
   url: z.union([z.string(), z.null()]).optional(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_codes: z.array(z.string()).min(1),
   emulator_id: z.string().min(1).max(100),
   proxy: ProxyTargetRequest.optional(),
-  labels: z.record(z.string()).optional()
+  labels: z.record(z.string()).optional(),
+  repeat_count: z.number().int().gte(1).optional().default(1),
+  repeat_mode: RepeatModeType.optional(),
+  retry_max_attempts: z.number().int().gte(0).optional().default(0)
 }).passthrough();
 z.object({
   scope_type: z.enum(["last_n", "hours"]),
@@ -461,12 +486,14 @@ var GroupActionResponse = z.object({
   run_ids: z.array(z.string().uuid()).optional(),
   failures: z.array(BulkCampaignFailure).optional()
 }).passthrough();
+var RepeatMode = z.enum(["isolated", "shared"]);
 z.object({
   name: z.string().min(1).max(200),
   campaign_type: z.string().optional().default("url"),
   url: z.union([z.string(), z.null()]).optional(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_codes: z.array(z.string()).min(1),
   group_id: z.union([z.string(), z.null()]).optional(),
   emulator_categories: z.array(z.string()).optional(),
@@ -476,6 +503,9 @@ z.object({
   proxy_region: z.string().optional().default(""),
   proxy_city: z.string().optional().default(""),
   proxy_isp: z.string().optional().default(""),
+  repeat_count: z.number().int().gte(1).optional().default(1),
+  repeat_mode: RepeatMode.optional(),
+  retry_max_attempts: z.number().int().gte(0).optional().default(0),
   labels: z.record(z.string()).optional(),
   policy_set_id: z.union([z.string(), z.null()]).optional(),
   schedule_type: z.union([z.string(), z.null()]).optional(),
@@ -496,6 +526,7 @@ var CampaignResponse = z.object({
   url: z.string(),
   ad_tag: z.union([z.string(), z.null()]).optional(),
   vast_tag: z.union([z.string(), z.null()]).optional(),
+  referrer: z.union([z.string(), z.null()]).optional(),
   country_codes: z.array(z.string()),
   group_id: z.string().uuid(),
   emulator_selection: EmulatorSelectionResponse,
@@ -503,6 +534,9 @@ var CampaignResponse = z.object({
   proxy_region: z.string().optional().default(""),
   proxy_city: z.string().optional().default(""),
   proxy_isp: z.string().optional().default(""),
+  repeat_count: z.number().int().optional().default(1),
+  repeat_mode: RepeatMode.optional(),
+  retry_max_attempts: z.number().int().optional().default(0),
   schedule_type: z.union([z.string(), z.null()]).optional(),
   schedule_weekly: z.union([z.record(z.array(z.number().int())), z.null()]).optional(),
   schedule_interval_seconds: z.union([z.number(), z.null()]).optional(),
@@ -533,6 +567,7 @@ z.object({
   url: z.union([z.string(), z.null()]),
   ad_tag: z.union([z.string(), z.null()]),
   vast_tag: z.union([z.string(), z.null()]),
+  referrer: z.union([z.string(), z.null()]),
   country_codes: z.union([z.array(z.string()), z.null()]),
   group_id: z.union([z.string(), z.null()]),
   emulator_categories: z.union([z.array(z.string()), z.null()]),
@@ -542,6 +577,9 @@ z.object({
   proxy_region: z.union([z.string(), z.null()]),
   proxy_city: z.union([z.string(), z.null()]),
   proxy_isp: z.union([z.string(), z.null()]),
+  repeat_count: z.union([z.number(), z.null()]),
+  repeat_mode: z.union([RepeatMode, z.null()]),
+  retry_max_attempts: z.union([z.number(), z.null()]),
   labels: z.union([z.record(z.string()), z.null()]),
   policy_set_id: z.union([z.string(), z.null()]),
   schedule_type: z.union([z.string(), z.null()]),
@@ -649,7 +687,8 @@ z.object({
   tag_slug: z.string().max(100).optional().default(""),
   rule_type: z.string().max(50),
   config: z.object({}).partial().passthrough(),
-  target: z.string().max(30).optional().default("page")
+  target: z.string().max(30).optional().default("page"),
+  tag_visibility: z.union([z.record(TagVisibility), z.null()]).optional()
 }).passthrough();
 var CustomRuleResponse = z.object({
   id: z.string().uuid(),
@@ -661,7 +700,8 @@ var CustomRuleResponse = z.object({
   target: z.string(),
   is_active: z.boolean(),
   created_at: z.string().datetime({ offset: true }),
-  scope: z.string().optional().default("personal")
+  scope: z.string().optional().default("personal"),
+  tag_visibility: z.record(z.string()).optional()
 }).passthrough();
 z.object({
   items: z.array(CustomRuleResponse),
@@ -675,7 +715,8 @@ z.object({
   tag_slug: z.union([z.string(), z.null()]),
   config: z.union([z.object({}).partial().passthrough(), z.null()]),
   target: z.union([z.string(), z.null()]),
-  is_active: z.union([z.boolean(), z.null()])
+  is_active: z.union([z.boolean(), z.null()]),
+  tag_visibility: z.union([z.record(TagVisibility), z.null()])
 }).partial().passthrough();
 z.object({
   scan_id: z.string().uuid(),
@@ -906,7 +947,8 @@ var BalanceTransactionType = z.enum([
   "admin_adjustment",
   "refund",
   "invoice_settlement",
-  "crypto_top_up"
+  "crypto_top_up",
+  "card_top_up"
 ]);
 z.union([z.array(BalanceTransactionType), z.null()]).optional();
 var BalanceTransactionResponse = z.object({
@@ -1153,6 +1195,7 @@ z.object({
   description: z.string().max(500).optional().default(""),
   nodes: z.array(TaxonomyNodeRequest).optional().default([])
 });
+z.enum(["any", "all"]);
 var schemas = {
   OrgResponse,
   LabelDefinitionResponse,
@@ -1166,6 +1209,7 @@ var schemas = {
   EmulatorResponse,
   CampaignGroupResponse,
   GroupActionResponse,
+  RepeatMode,
   CampaignResponse,
   CampaignPickerItem,
   RunResponse,
@@ -1301,6 +1345,7 @@ var CampaignSchema = schemas.CampaignResponse.pick({
   url: true,
   ad_tag: true,
   vast_tag: true,
+  referrer: true,
   country_codes: true,
   group_id: true,
   emulator_selection: true,
@@ -1308,6 +1353,9 @@ var CampaignSchema = schemas.CampaignResponse.pick({
   proxy_region: true,
   proxy_city: true,
   proxy_isp: true,
+  repeat_count: true,
+  repeat_mode: true,
+  retry_max_attempts: true,
   labels: true,
   policy_set_id: true,
   schedule_enabled: true,
@@ -1318,7 +1366,7 @@ var CampaignSchema = schemas.CampaignResponse.pick({
   is_archived: true,
   created_at: true,
   last_run_at: true
-}).strip();
+}).extend({ repeat_mode: schemas.RepeatMode.default("isolated") }).strip();
 var parseCampaign = (raw) => parseWithSchema(CampaignSchema, raw, "campaign");
 var parseCampaignPage = (raw) => parsePagedWithItemSchema(CampaignSchema, raw, "campaigns");
 
@@ -1731,6 +1779,7 @@ var ScanSchema = schemas.ScanResponse.pick({
   public_report_url: true,
   ad_tag: true,
   vast_tag: true,
+  referrer: true,
   creative_kind: true,
   video: true,
   creative_screenshot_url: true,
@@ -1746,8 +1795,14 @@ var ScanSchema = schemas.ScanResponse.pick({
   ad_kind: true,
   network: true,
   created_at: true,
-  completed_at: true
-}).strip();
+  completed_at: true,
+  repeat_index: true,
+  repeat_total: true,
+  repeat_session_id: true,
+  repeat_scan_ids: true,
+  retry_attempt: true,
+  retry_max_attempts: true
+}).extend({ creative_kind: z.string().default("banner") }).strip();
 var ScanArraySchema = z.array(ScanSchema);
 var parseScan = (raw) => parseWithSchema(ScanSchema, raw, "scan");
 var parseScanArray = (raw) => parseWithSchema(ScanArraySchema, raw, "scans");
@@ -1773,7 +1828,12 @@ var ScanBriefSchema = schemas.ScanBriefResponse.pick({
   slot_index: true,
   ad_kind: true,
   network: true,
-  created_at: true
+  created_at: true,
+  repeat_index: true,
+  repeat_total: true,
+  repeat_session_id: true,
+  retry_attempt: true,
+  retry_max_attempts: true
 }).strip();
 var parseScanPage = (raw) => parsePagedWithItemSchema(ScanBriefSchema, raw, "scans");
 var TagDefinitionSchema = schemas.TagDefinitionWithStatsResponse.pick({
@@ -1865,10 +1925,7 @@ function createHttpApiGateway(config) {
     if (dispatcher !== void 0) {
       baseInit["dispatcher"] = dispatcher;
     }
-    return fetch(
-      input.url,
-      baseInit
-    );
+    return fetch(input.url, baseInit);
   };
   const client = createClient({
     baseUrl,
@@ -1933,10 +1990,7 @@ function createHttpApiGateway(config) {
         }
       };
       if (dispatcher !== void 0) init["dispatcher"] = dispatcher;
-      response = await fetch(
-        url,
-        init
-      );
+      response = await fetch(url, init);
     } catch (cause) {
       logger.warn({ api_path: path, elapsed_ms: Date.now() - startedAtMs }, "api.network_error");
       const inner = cause instanceof Error && cause.cause instanceof Error ? cause.cause : cause instanceof Error ? cause : null;
@@ -3245,13 +3299,14 @@ var TransactionTypeEnum = z.enum([
   "admin_adjustment",
   "refund",
   "invoice_settlement",
-  "crypto_top_up"
+  "crypto_top_up",
+  "card_top_up"
 ]);
 var ListBalanceHistoryInputShape = {
   date_from: z.string().date().optional().describe("ISO date, inclusive."),
   date_to: z.string().date().optional().describe("ISO date, inclusive."),
-  type: z.array(TransactionTypeEnum).max(9).optional().describe(
-    "Filter by transaction kind. Pass several values to OR them (e.g. ['top_up_manual','crypto_top_up'] for credits-only)."
+  type: z.array(TransactionTypeEnum).max(TransactionTypeEnum.options.length).optional().describe(
+    "Filter by transaction kind. Pass several values to OR them (e.g. ['top_up_manual','crypto_top_up','card_top_up'] for credits-only)."
   ),
   page: z.number().int().min(1).max(500).default(1).describe("1-indexed page."),
   limit: z.number().int().min(1).max(200).default(50).describe("Page size.")
@@ -3558,6 +3613,28 @@ var cancelCampaignTool = {
     return ok(result.value);
   }
 };
+var repeatRetryFields = {
+  repeat_count: z.number().int().min(1).max(20).optional().describe(
+    "How many times to repeat every scan this call already produces (1-20). It is a multiplier on top of the tool's own fan-out \u2014 see that tool's description for the exact formula \u2014 and each resulting repeat is a full scan with its own report and its own billing. 1-20 is the API's default ceiling; an operator can lower it during an incident, and then a value accepted here still comes back as a 422 from the API. Default: 1."
+  ),
+  repeat_mode: z.enum(["isolated", "shared"]).optional().describe(
+    "How the repeats of one combination relate to each other. 'isolated' gives every repeat a fresh browser and a new IP, so the repeats are statistically independent. 'shared' runs all repeats of one combination in a single browser behind one IP, carrying cookies and localStorage from one repeat to the next \u2014 use it to reproduce a cloaker or a frequency cap that only misbehaves on the second or third visit. 'shared' is rejected with 422 on an ad-discovery target: when creating, that is `ad_discovery: true` on a scan or `campaign_type: \"ad_discovery\"` on a campaign; when updating a campaign, it is a campaign whose existing type is already ad_discovery, since campaign_type itself cannot be changed. Default: isolated."
+  ),
+  retry_max_attempts: z.number().int().min(0).max(5).optional().describe(
+    "Extra crawl attempts when a scan fails for a technical reason \u2014 dead proxy, navigation timeout, browser crash (0-5). Permanent failures are never retried. The same scan is reused and only a completed scan is billed, so a retry never double-charges. 0-5 is the API's default ceiling; an operator can lower it, and then a value accepted here still comes back as a 422 from the API. Default: 0."
+  )
+};
+function pickRepeatRetryBody(input) {
+  const body = {};
+  if (input.repeat_count !== void 0) body.repeat_count = input.repeat_count;
+  if (input.repeat_mode !== void 0) body.repeat_mode = input.repeat_mode;
+  if (input.retry_max_attempts !== void 0) {
+    body.retry_max_attempts = input.retry_max_attempts;
+  }
+  return body;
+}
+
+// src/application/tools/campaigns/_campaign-config-fields.ts
 var campaignConfigFields = {
   emulator_categories: z.array(z.string()).optional().describe(
     "Device categories to rotate through, e.g. ['android_phone']. Valid: android_phone, android_tablet, iphone, ipad, windows_desktop, macos_desktop. On create, omitting this defaults to ['android_phone']; pass [] together with emulator_specific_ids to target ONLY specific devices."
@@ -3572,6 +3649,7 @@ var campaignConfigFields = {
   proxy_region: z.string().optional().describe("Proxy region/state targeting (free-text; only honoured for a single country)."),
   proxy_city: z.string().optional().describe("Proxy city targeting."),
   proxy_isp: z.string().optional().describe("Proxy ISP targeting."),
+  ...repeatRetryFields,
   schedule_type: z.enum(["weekly", "interval"]).optional().describe(
     "Scheduling mode: 'weekly' (run on a weekday/hour grid via schedule_weekly) or 'interval' (run every schedule_interval_seconds). Omit for a manual (run-on-demand) campaign."
   ),
@@ -3584,7 +3662,7 @@ var campaignConfigFields = {
   schedule_timezone: z.string().optional().describe("IANA timezone for the weekly grid, e.g. 'Europe/Berlin'. Default: UTC.")
 };
 function pickCampaignConfigBody(input) {
-  const body = {};
+  const body = { ...pickRepeatRetryBody(input) };
   if (input.emulator_categories !== void 0) body.emulator_categories = input.emulator_categories;
   if (input.emulator_specific_ids !== void 0) {
     body.emulator_specific_ids = input.emulator_specific_ids;
@@ -3602,6 +3680,10 @@ function pickCampaignConfigBody(input) {
   if (input.schedule_timezone !== void 0) body.schedule_timezone = input.schedule_timezone;
   return body;
 }
+var campaignReferrerUrl = z.string().url().regex(/^https?:\/\//i, "Must be an http(s) URL.").max(2048);
+var CAMPAIGN_REFERRER_DESCRIPTION = "Optional http(s) page URL every scan of this campaign is checked from. For `ad_tag` and `vast` campaigns this is the publisher page the tag is embedded in \u2014 NOT the creative and NOT its landing page; the browser commits the page document on this URL without fetching the publisher, so the creative renders as if embedded there, and its cross-origin subrequests receive the origin only (https://publisher.example/, no path). For `url` and `ad_discovery` campaigns this is where the visitor came from, sent in full as the Referer of the page request.";
+var campaignReferrerField = campaignReferrerUrl.optional().describe(CAMPAIGN_REFERRER_DESCRIPTION);
+var campaignReferrerUpdateField = campaignReferrerUrl.nullable().optional().describe(`${CAMPAIGN_REFERRER_DESCRIPTION} Pass null to clear it.`);
 
 // src/application/tools/campaigns/create-campaign.tool.ts
 var CreateCampaignInputShape = {
@@ -3616,6 +3698,7 @@ var CreateCampaignInputShape = {
   vast_tag: z.string().optional().describe(
     "VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML (required if campaign_type=vast)."
   ),
+  referrer: campaignReferrerField,
   country_codes: z.array(z.string().length(2)).min(1).describe("ISO 3166-1 alpha-2 codes \u2014 one scan per country per run."),
   group_id: z.string().uuid().optional().describe("Parent group UUID; defaults to the org's default group."),
   ...campaignConfigFields,
@@ -3625,7 +3708,7 @@ var CreateCampaignInputShape = {
 };
 var createCampaignTool = {
   name: "create_campaign",
-  description: "Create a recurring scan campaign (template). The schedule produces N scans per run where N = number of countries times number of device profiles. Scans cost credits when they run, not when the campaign is created.",
+  description: "Create a recurring scan campaign (template). The schedule produces N scans per run where N = number of countries times number of device profiles times `repeat_count`. Scans cost credits when they run, not when the campaign is created, so a high `repeat_count` multiplies the bill on every run. The returned campaign echoes `repeat_count`, `repeat_mode`, and `retry_max_attempts`, so read it back to confirm what the campaign will do.",
   annotations: {
     title: "Create Campaign",
     readOnlyHint: false,
@@ -3642,6 +3725,7 @@ var createCampaignTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.group_id !== void 0 ? { group_id: input.group_id } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
       ...input.policy_set_id !== void 0 ? { policy_set_id: input.policy_set_id } : {},
@@ -3658,7 +3742,7 @@ var GetCampaignInputShape = {
 };
 var getCampaignTool = {
   name: "get_campaign",
-  description: "Get one campaign by UUID: name, type (url|ad_tag|vast|ad_discovery), target URL / ad-tag / VAST tag (vast_tag), countries, schedule status, archive status, parent group. `ad_discovery` campaigns store the publisher page in the URL field.",
+  description: "Get one campaign by UUID: name, type (url|ad_tag|vast|ad_discovery), target URL / ad-tag / VAST tag (vast_tag), countries, emulator selection, proxy targeting, schedule status, archive status, parent group. Also echoes the repeat / retry settings \u2014 `repeat_count`, `repeat_mode`, `retry_max_attempts` \u2014 so this is how you confirm what `create_campaign` or `update_campaign` actually saved, and how many scans a run will produce (countries x device profiles x `repeat_count`). `ad_discovery` campaigns store the publisher page in the URL field.",
   annotations: {
     title: "Get Campaign",
     readOnlyHint: true,
@@ -3709,7 +3793,7 @@ var ListCampaignsInputShape = {
 };
 var listCampaignsTool = {
   name: "list_campaigns",
-  description: "List campaigns for the caller's organization, optionally filtered by group, archived flag, or name substring. Paginated.",
+  description: "List campaigns for the caller's organization, optionally filtered by group, archived flag, or name substring. Paginated. Each row carries the same fields as `get_campaign`, including the repeat / retry settings (`repeat_count`, `repeat_mode`, `retry_max_attempts`) \u2014 use them to spot the campaigns that multiply their per-run scan count.",
   annotations: {
     title: "List Campaigns",
     readOnlyHint: true,
@@ -3812,6 +3896,7 @@ var UpdateCampaignInputShape = {
   vast_tag: z.string().optional().describe(
     "New VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML (vast-type campaigns)."
   ),
+  referrer: campaignReferrerUpdateField,
   country_codes: z.array(z.string().length(2)).optional().describe("Replace the country list."),
   group_id: z.string().uuid().optional().describe("Move the campaign to another group."),
   ...campaignConfigFields,
@@ -3821,7 +3906,7 @@ var UpdateCampaignInputShape = {
 };
 var updateCampaignTool = {
   name: "update_campaign",
-  description: "Update one or more fields of a campaign. Fields not supplied are left unchanged. `policy_set_id` accepts null to clear the binding.",
+  description: "Update one or more fields of a campaign. Fields not supplied are left unchanged. `policy_set_id` accepts null to clear the binding, and `referrer` accepts null to clear the publisher page scans are checked from.",
   annotations: {
     title: "Update Campaign",
     readOnlyHint: false,
@@ -3836,6 +3921,7 @@ var updateCampaignTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.country_codes !== void 0 ? { country_codes: input.country_codes } : {},
       ...input.group_id !== void 0 ? { group_id: input.group_id } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
@@ -3848,6 +3934,21 @@ var updateCampaignTool = {
     return ok(result.value);
   }
 };
+var COMBO_MATCH_SCOPE_DOC = 'For `rule_type=\'combo\'` the optional rule-level key `match_scope` decides where conditions are counted. `"scan"` (the default, and the behaviour when the key is absent) checks them against the union of all tags on the scan. With `"url"`, every condition must be satisfied by tags on the same link, and the tag is assigned to that link \u2014 so a rule built only from link-less tags (AI verdicts, crawler behaviour) has no link to attach to and will never match; keep those on the whole scan. Mixing the two kinds does not help either: AI verdicts and per-link detections reach the engine in different scan parts and are not evaluated together today, so such a combo fires under neither scope. Give a `"url"` rule at least one positive condition (`all_of` / `any_of` / `tag_category` + `count_gte`) \u2014 a config carrying only `none_of` matches every link that merely lacks those tags, and the API does not reject that on this path. Thresholds stay "N or more" (`count_gte` / `any_of_min`) in both scopes; no other `match_scope` value is accepted.';
+var COMBO_MATCH_SCOPE_READ_DOC = 'For `rule_type=\'combo\'` the returned `config` may carry the rule-level key `match_scope` ("scan" = count conditions across the whole scan, "url" = every condition must be satisfied by tags on the same link). Resend it verbatim when updating: `update_custom_rule` replaces `config` wholesale, so dropping the key reverts the rule to whole-scan matching.';
+var ruleConfigField = z.record(z.unknown()).superRefine((config, ctx) => {
+  const scope = config["match_scope"];
+  if (scope === void 0 || scope === "scan" || scope === "url") {
+    return;
+  }
+  ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    path: ["match_scope"],
+    message: 'config.match_scope must be "scan" or "url". Omit the key for scan-wide matching (the default).'
+  });
+});
+
+// src/application/tools/custom-rules/create-custom-rule.tool.ts
 var CreateCustomRuleInputShape = {
   name: z.string().min(1).max(200).describe(
     "Display name. For non-LLM rules this also becomes the `display_name` of the auto-registered tag definition (see `tag_slug`)."
@@ -3858,8 +3959,8 @@ var CreateCustomRuleInputShape = {
   rule_type: z.string().max(50).describe(
     "Rule engine. One of: `stopword_content`, `stopword_url`, `regexp_content`, `regexp_url`, `blacklist_domain`, `combo`, `llm`. The API validates."
   ),
-  config: z.record(z.unknown()).describe(
-    "Rule-type-specific configuration object. Shape depends on `rule_type`. For `rule_type='llm'` the shape is `{ prompt: string, tags: { <tag_slug>: <description>, ... } }`; each key in `config.tags` is auto-registered as a custom tag definition AND must not collide with a system slug (same 422 contract as `tag_slug`)."
+  config: ruleConfigField.describe(
+    "Rule-type-specific configuration object. Shape depends on `rule_type`. For `rule_type='llm'` the shape is `{ prompt: string, tags: { <tag_slug>: <description>, ... } }`; each key in `config.tags` is auto-registered as a custom tag definition AND must not collide with a system slug (same 422 contract as `tag_slug`). " + COMBO_MATCH_SCOPE_DOC
   ),
   target: z.string().max(30).optional().describe(
     "Where to apply the rule (e.g. 'page' for landing HTML). Default: page. See API docs for the full set of valid values."
@@ -3867,7 +3968,7 @@ var CreateCustomRuleInputShape = {
 };
 var createCustomRuleTool = {
   name: "create_custom_rule",
-  description: "Define a custom tag-detection rule. The API auto-registers a tag definition for each slug the rule emits (`tag_slug` for non-LLM rules; `config.tags` keys for `rule_type='llm'`); slugs that collide with a built-in system tag are rejected with HTTP 422 / code `checking.system_slug_reserved`. Matches tag every future scan; existing scans are untouched until you call `recheck_scans`.",
+  description: "Define a custom tag-detection rule. The API auto-registers a tag definition for each slug the rule emits (`tag_slug` for non-LLM rules; `config.tags` keys for `rule_type='llm'`); slugs that collide with a built-in system tag are rejected with HTTP 422 / code `checking.system_slug_reserved`. For `rule_type='combo'` set `config.match_scope='url'` when the thresholds must be met inside one link instead of anywhere on the scan (default `'scan'`). Matches tag every future scan; existing scans are untouched until you call `recheck_scans`.",
   annotations: {
     title: "Create Custom Rule",
     readOnlyHint: false,
@@ -3912,7 +4013,7 @@ var deleteCustomRuleTool = {
 var GetCustomRuleInputShape = { rule_id: z.string().uuid().describe("Rule UUID.") };
 var getCustomRuleTool = {
   name: "get_custom_rule",
-  description: "Get one custom rule by UUID with name, tag-slug, type, config object, target, active flag.",
+  description: "Get one custom rule by UUID with name, tag-slug, type, config object, target, active flag. " + COMBO_MATCH_SCOPE_READ_DOC,
   annotations: {
     title: "Get Custom Rule",
     readOnlyHint: true,
@@ -3933,7 +4034,7 @@ var ListCustomRulesInputShape = {
 };
 var listCustomRulesTool = {
   name: "list_custom_rules",
-  description: "Paginated list of the organization's custom tag-detection rules (regex / heuristics) with their config, target, and active flag. Returns `{items, total, page, limit}`. To iterate: there is a next page iff `page * limit < total` (or equivalently `items.length === limit` until the last page). `page` is 1-indexed.",
+  description: "Paginated list of the organization's custom tag-detection rules (regex / heuristics) with their config, target, and active flag. Returns `{items, total, page, limit}`. To iterate: there is a next page iff `page * limit < total` (or equivalently `items.length === limit` until the last page). `page` is 1-indexed. " + COMBO_MATCH_SCOPE_READ_DOC,
   annotations: {
     title: "List Custom Rules",
     readOnlyHint: true,
@@ -3952,8 +4053,8 @@ var TestCustomRuleInputShape = {
   rule_type: z.string().max(50).describe(
     "Rule engine type. One of: `stopword_content`, `stopword_url`, `regexp_content`, `regexp_url`, `blacklist_domain`, `combo`, `llm`."
   ),
-  config: z.record(z.unknown()).describe(
-    "Rule-type-specific config to test. Same shape as `create_custom_rule`'s `config`. NOTE: `test_custom_rule` evaluates the rule against a scan WITHOUT persisting it, so slug-collision validation does NOT run here \u2014 verify slugs against `list_tags` (`scope=system`) before promoting to `create_custom_rule`."
+  config: ruleConfigField.describe(
+    "Rule-type-specific config to test. Same shape as `create_custom_rule`'s `config`. NOTE: `test_custom_rule` evaluates the rule against a scan WITHOUT persisting it, so slug-collision validation does NOT run here \u2014 verify slugs against `list_tags` (`scope=system`) before promoting to `create_custom_rule`. " + COMBO_MATCH_SCOPE_DOC
   ),
   target: z.string().max(30).describe(
     "Where to apply the rule (e.g. 'page' for landing HTML). See API docs for the full set of valid values."
@@ -3962,7 +4063,7 @@ var TestCustomRuleInputShape = {
 };
 var testCustomRuleTool = {
   name: "test_custom_rule",
-  description: "Preview-test a rule definition against an existing scan WITHOUT persisting the rule. Returns `matched: bool`, evaluation time, and per-tag-slug details. Use to validate config before `create_custom_rule`. NOTE: slug-collision validation does NOT run in preview mode \u2014 verify any `tag_slug` (or LLM `config.tags` keys) against `list_tags` (`scope=system`) before promoting to `create_custom_rule`, which would otherwise reject the same payload with HTTP 422 / code `checking.system_slug_reserved`.",
+  description: "Preview-test a rule definition against an existing scan WITHOUT persisting the rule. Returns `matched: bool`, evaluation time, and per-tag-slug details. Use to validate config before `create_custom_rule`. Combo rules are evaluated against the scan's existing tags, so `config.match_scope` is honoured \u2014 but per-URL hits are collapsed to one row per tag slug, so the result says whether the rule fires, not which URLs it would tag. NOTE: slug-collision validation does NOT run in preview mode \u2014 verify any `tag_slug` (or LLM `config.tags` keys) against `list_tags` (`scope=system`) before promoting to `create_custom_rule`, which would otherwise reject the same payload with HTTP 422 / code `checking.system_slug_reserved`.",
   annotations: {
     title: "Test Custom Rule",
     readOnlyHint: true,
@@ -3990,8 +4091,8 @@ var UpdateCustomRuleInputShape = {
   tag_slug: z.string().max(100).optional().describe(
     "New tag slug to assign on match. **MUST NOT collide with a built-in system tag slug** (see `list_tags` where `scope=system`); colliding requests return 422 with code `checking.system_slug_reserved`. Re-registering an existing custom slug refreshes its tag definition's `display_name` / `description`."
   ),
-  config: z.record(z.unknown()).optional().describe(
-    "New rule-type-specific config object. For `rule_type='llm'` the keys of `config.tags` are auto-registered as tag definitions; any key that collides with a system slug returns the same 422 contract."
+  config: ruleConfigField.optional().describe(
+    "New rule-type-specific config object. Replaces the stored config wholesale \u2014 resend every key you want to keep, including a combo rule's `match_scope`. For `rule_type='llm'` the keys of `config.tags` are auto-registered as tag definitions; any key that collides with a system slug returns the same 422 contract. " + COMBO_MATCH_SCOPE_DOC
   ),
   target: z.string().max(30).optional().describe(
     "Where to apply the rule (e.g. 'page' for landing HTML). See API docs for the full set of valid values."
@@ -4000,7 +4101,7 @@ var UpdateCustomRuleInputShape = {
 };
 var updateCustomRuleTool = {
   name: "update_custom_rule",
-  description: "Update a custom tag-detection rule. Only supplied fields are sent. Changing `tag_slug` (or `config.tags` keys for `rule_type='llm'`) onto a built-in system slug returns HTTP 422 / code `checking.system_slug_reserved`. To toggle activation, pass `is_active`. Existing tagged scans are NOT re-evaluated \u2014 call `recheck_scans` for that. (Rule engine `rule_type` cannot be changed after creation; create a new rule instead.)",
+  description: "Update a custom tag-detection rule. Only supplied fields are sent, but a supplied `config` replaces the stored one wholesale (omitting a combo rule's `match_scope` reverts it to the scan-wide default). Changing `tag_slug` (or `config.tags` keys for `rule_type='llm'`) onto a built-in system slug returns HTTP 422 / code `checking.system_slug_reserved`. To toggle activation, pass `is_active`. Existing tagged scans are NOT re-evaluated \u2014 call `recheck_scans` for that. (Rule engine `rule_type` cannot be changed after creation; create a new rule instead.)",
   annotations: {
     title: "Update Custom Rule",
     readOnlyHint: false,
@@ -4663,6 +4764,9 @@ var scanProxyField = z.object({
   city: z.string().optional().describe("Proxy city targeting."),
   isp: z.string().optional().describe("Proxy ISP targeting.")
 }).optional().describe("Optional proxy geo targeting for the crawl. Omit to use the org default.");
+var scanReferrerField = z.string().url().regex(/^https?:\/\//i, "Must be an http(s) URL.").max(2048).optional().describe(
+  "Optional http(s) page URL the check is performed from. With `ad_tag` or `vast_tag` this is the publisher page the tag is embedded in \u2014 NOT the creative and NOT its landing page; the browser commits the page document on this URL without fetching the publisher, so the creative renders as if embedded there, and its cross-origin subrequests receive the origin only (https://publisher.example/, no path). With a `url` target this is where the visitor came from, sent in full as the Referer of the page request."
+);
 
 // src/application/tools/scans/create-bulk-scans.tool.ts
 var CreateBulkScansInputShape = {
@@ -4673,14 +4777,16 @@ var CreateBulkScansInputShape = {
   vast_tag: z.string().optional().describe(
     "VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML. Provide exactly one of `url`, `ad_tag`, or `vast_tag`."
   ),
+  referrer: scanReferrerField,
   country_codes: z.array(z.string().length(2)).min(1).max(50).describe("List of ISO 3166-1 alpha-2 country codes; one scan per country is created."),
   emulator_id: z.string().min(1).max(100).describe("Device/OS profile slug; same for every country in the batch."),
   proxy: scanProxyField,
-  labels: z.record(z.string()).optional().describe("Arbitrary metadata copied onto every created scan.")
+  labels: z.record(z.string()).optional().describe("Arbitrary metadata copied onto every created scan."),
+  ...repeatRetryFields
 };
 var createBulkScansTool = {
   name: "create_bulk_scans",
-  description: "Queue one new scan per country in a single call (e.g. test the same URL, ad-tag, or VAST video tag from US + DE + JP). COSTS N CREDITS where N = number of countries. Returns the list of created scans.",
+  description: "Queue one new scan per country in a single call (e.g. test the same URL, ad-tag, or VAST video tag from US + DE + JP). COSTS N CREDITS where N = number of countries times `repeat_count`. Returns one entry per country; each entry's `repeat_scan_ids` lists that country's extra repeats.",
   annotations: {
     title: "Create Bulk Scans",
     readOnlyHint: false,
@@ -4696,8 +4802,10 @@ var createBulkScansTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.proxy !== void 0 ? { proxy: input.proxy } : {},
-      ...input.labels !== void 0 ? { labels: input.labels } : {}
+      ...input.labels !== void 0 ? { labels: input.labels } : {},
+      ...pickRepeatRetryBody(input)
     };
     const result = await ctx.api.createBulkScans(body);
     if (result.isErr()) return err(mapApiError(result.error));
@@ -4714,6 +4822,7 @@ var CreateScanInputShape = {
   vast_tag: z.string().optional().describe(
     "VAST video ad tag: an http(s) URL of a VAST endpoint OR raw VAST XML (a document containing a <VAST> element). Fetched and played in a real browser. Provide exactly one of `url`, `ad_tag`, or `vast_tag`."
   ),
+  referrer: scanReferrerField,
   country_code: z.string().length(2).describe("ISO 3166-1 alpha-2 country code, e.g. US, DE, JP. Determines proxy geo."),
   emulator_id: z.string().min(1).max(100).describe("Device/OS profile slug; use `list_emulators` to discover valid values."),
   proxy: scanProxyField,
@@ -4722,11 +4831,12 @@ var CreateScanInputShape = {
   run_id: z.string().uuid().optional().describe("Optional run UUID inside the campaign."),
   ad_discovery: z.boolean().optional().describe(
     "Publisher ad discovery: detect ad blocks on the page and spawn one child scan per detected ad (banner/pop). Only valid with `url`. Each child is a separate billed scan; list them with `list_scan_children`."
-  )
+  ),
+  ...repeatRetryFields
 };
 var createScanTool = {
   name: "create_scan",
-  description: "Queue a single new scan for a URL, ad-tag, or VAST video tag against one country. COSTS CREDITS and bills the caller's organization. Returns the newly-created scan record.",
+  description: "Queue a single new scan for a URL, ad-tag, or VAST video tag against one country. Takes one target and one country \u2014 there is no multi-URL form; call it once per URL. COSTS CREDITS and bills the caller's organization: this call creates exactly `repeat_count` scans (default 1) and bills every one of them. Returns the newly-created scan record; when `repeat_count` > 1 the response's `repeat_scan_ids` lists the sibling scans this call also created.",
   annotations: {
     title: "Create Scan",
     readOnlyHint: false,
@@ -4742,11 +4852,13 @@ var createScanTool = {
       ...input.url !== void 0 ? { url: input.url } : {},
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
+      ...input.referrer !== void 0 ? { referrer: input.referrer } : {},
       ...input.proxy !== void 0 ? { proxy: input.proxy } : {},
       ...input.labels !== void 0 ? { labels: input.labels } : {},
       ...input.campaign_id !== void 0 ? { campaign_id: input.campaign_id } : {},
       ...input.run_id !== void 0 ? { run_id: input.run_id } : {},
-      ...input.ad_discovery !== void 0 ? { ad_discovery: input.ad_discovery } : {}
+      ...input.ad_discovery !== void 0 ? { ad_discovery: input.ad_discovery } : {},
+      ...pickRepeatRetryBody(input)
     };
     const result = await ctx.api.createScan(body);
     if (result.isErr()) return err(mapApiError(result.error));
@@ -4758,7 +4870,7 @@ var GetScanInputShape = {
 };
 var getScanTool = {
   name: "get_scan",
-  description: "Get full detail for one scan by UUID: status, offer URL, absolute screenshot URL, report_url + public_report_url deep-links, timing, labels, and the parent campaign if any. VAST video scans also carry `vast_tag`, `creative_kind` (banner|video), and a `video` block (duration, media-file URL, VAST version, ad system, VPAID flag, wrapper depth). Link users with the returned `report_url` / `public_report_url` \u2014 never construct URLs yourself.",
+  description: "Get full detail for one scan by UUID: status, offer URL, absolute screenshot URL, report_url + public_report_url deep-links, timing, labels, and the parent campaign if any. VAST video scans also carry `vast_tag`, `creative_kind` (`banner` or `video` today; treat it as an open string), and a `video` block (duration, media-file URL, the creative's `click_through` destination, VAST version, ad system, VPAID flag, wrapper depth). Repeats and retries: `repeat_index` / `repeat_total` place this scan inside its repeat group (0-based, so 2 of 5 reads as repeat_index 1), a non-null `repeat_session_id` means the group ran in `shared` mode (same browser, same IP, cookies carried over) and is the key to correlate its members \u2014 a shared group of one has nothing to carry over, so it stays null \u2014 `repeat_scan_ids` is filled only on the create response, and `retry_attempt` / `retry_max_attempts` show how many technical re-crawls this scan already consumed. Link users with the returned `report_url` / `public_report_url` \u2014 never construct URLs yourself.",
   annotations: {
     title: "Get Scan",
     readOnlyHint: true,
@@ -4797,7 +4909,9 @@ var getScanCreativeScreenshotTool = {
 var GetScanLandingScreenshotInputShape = {
   scan_id: z.string().uuid().describe("Scan UUID (ad-tag scan)."),
   landing_ord: z.number().int().min(0).max(50).describe("0-indexed landing slot (see `get_scan(...).landings[*].ord`)."),
-  width: z.number().int().min(50).max(2e3).optional().describe("Optional resize width in pixels.")
+  width: z.number().int().min(50).max(2e3).optional().describe(
+    "Optional resize width in pixels. The API top-crops a resized landing screenshot whose height exceeds 2.5x its width, so a long landing page comes back as its top region only \u2014 never conclude that something is absent from the page from a resized capture. Fetch without `width` when you need the whole page."
+  )
 };
 var getScanLandingScreenshotTool = {
   name: "get_scan_landing_screenshot",
@@ -4823,7 +4937,7 @@ var getScanLandingScreenshotTool = {
 var GetScanScreenshotInputShape = {
   scan_id: z.string().uuid().describe("Scan UUID."),
   width: z.number().int().min(50).max(2e3).optional().describe(
-    "Optional resize width in pixels. The API resizes server-side to keep the image small for the agent's context window."
+    "Optional resize width in pixels. The API resizes server-side to keep the image small for the agent's context window. It also top-crops a resized page screenshot whose height exceeds 2.5x its width, so a long page comes back as its top region only \u2014 never conclude that something is absent from the page from a resized capture. Fetch without `width` when you need the whole page."
   )
 };
 var getScanScreenshotTool = {
@@ -4850,7 +4964,7 @@ var ListScanChildrenInputShape = {
 };
 var listScanChildrenTool = {
   name: "list_scan_children",
-  description: "List the discovered-ad child scans of a publisher ad-discovery scan \u2014 one per detected ad block on the page. Each child brief carries ad_kind (banner|pop), the attributed ad network, and slot_index. Returns a paginated envelope with screenshot + report deep-links; link users with those, never hand-build URLs.",
+  description: "List the discovered-ad child scans of a publisher ad-discovery scan \u2014 one per detected ad block on the page. Each child brief carries ad_kind (banner|pop), the attributed ad network, and slot_index. The repeat / retry fields are present but never meaningful here: a child is always its own group of one (`repeat_index` 0, `repeat_total` 1, `repeat_session_id` null) and is never re-crawled, because repeats and retries apply to the publisher scan \u2014 repeating an ad-discovery scan gives you several parents, each with its own children. Returns a paginated envelope with screenshot + report deep-links; link users with those, never hand-build URLs.",
   annotations: {
     title: "List Scan Children",
     readOnlyHint: true,
@@ -4901,7 +5015,7 @@ var ListScansInputShape = {
 };
 var listScansTool = {
   name: "list_scans",
-  description: "List scans for the caller's organization with optional filters (status, country, URL substring, date range, run/campaign/group, tag, AI/IAB/brand category, dynamic labels). Returns a paginated envelope; each brief carries `is_ad_tag` and `is_vast` flags, an absolute screenshot URL plus report_url (auth dashboard) and public_report_url (shareable) deep-links \u2014 link users with those, never hand-build URLs.",
+  description: "List scans for the caller's organization with optional filters (status, country, URL substring, date range, run/campaign/group, tag, AI/IAB/brand category, dynamic labels). Returns a paginated envelope; each brief carries `is_ad_tag` and `is_vast` flags, an absolute screenshot URL plus report_url (auth dashboard) and public_report_url (shareable) deep-links \u2014 link users with those, never hand-build URLs. Repeated scans look like near-duplicate rows: `repeat_index` / `repeat_total` place each one inside its repeat group (0-based) and a non-null `repeat_session_id` means the group ran in `shared` mode (one browser, one IP, cookies carried across repeats) \u2014 group by it to compare the repeats of one combination. `retry_attempt` / `retry_max_attempts` count technical re-crawls of that same scan, not extra scans. `repeat_scan_ids` is not part of this response; use `get_scan` for a single scan's full detail.",
   annotations: {
     title: "List Scans",
     readOnlyHint: true,
@@ -5535,5 +5649,5 @@ function formatToolError(error) {
 }
 
 export { BearerToken, SERVER_INSTRUCTIONS, createHttpApiGateway, createPinoLogger, declareEmptyResourcesAndPrompts, newRequestId, wireToolsIntoMcpServer };
-//# sourceMappingURL=chunk-R56UDCOA.js.map
-//# sourceMappingURL=chunk-R56UDCOA.js.map
+//# sourceMappingURL=chunk-XCAKB2QW.js.map
+//# sourceMappingURL=chunk-XCAKB2QW.js.map