@kaminari-ad/mcp 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-28
+
+### Added
+
+- **Repeats and retries.** `create_scan`, `create_bulk_scans`,
+  `create_campaign`, and `update_campaign` accept `repeat_count` (1-20),
+  `repeat_mode` (`isolated` | `shared`), and `retry_max_attempts` (0-5).
+  `repeat_count` multiplies the scans created — and billed — per
+  `url x country x device` combination; `shared` runs a combination's repeats
+  in one browser behind one IP with cookies carried over (rejected with 422
+  together with ad discovery); `retry_max_attempts` re-crawls the same scan
+  after a transient failure without billing twice.
+- **Repeat / retry fields on the read side.** Scan detail surfaces
+  `repeat_index`, `repeat_total`, `repeat_session_id`, `repeat_scan_ids`,
+  `retry_attempt`, and `retry_max_attempts`; the scan-list brief carries all of
+  those except `repeat_scan_ids`; campaign responses echo `repeat_count`,
+  `repeat_mode`, and `retry_max_attempts`.
+
+### Fixed
+
+- **`list_balance_history` can filter on `card_top_up`.** The API has emitted
+  that transaction type for a while — an unfiltered call already returned the
+  rows — but the tool's own enum stopped at `crypto_top_up`, so
+  `type: ["card_top_up"]` was rejected locally and never reached the API. The
+  filter's length cap was one short for the same reason.
+  `BalanceTransactionType` is now aliased off the generated schema instead of
+  hand-mirrored, so the next regen turns a new value into a compile error.
+
+### Changed
+
+- Regenerated the OpenAPI type + zod-schema snapshots against `/api/v1`
+  v1.27.0. Besides the repeat / retry fields this picks up the
+  `creative-html` / `creative-video` / `vast-xml` artifact endpoints,
+  `video.click_through`, `creative_kind` as an enum, `tag_visibility` on custom
+  rules, the `card_top_up` balance-transaction type, and the `tag_match` scan
+  filter.
+- `creative_kind` is surfaced as an open string rather than the regenerated
+  `banner | video` enum, following the same forward-compat policy as
+  `block_reason`. A creative kind added on the API side now degrades that one
+  field instead of failing the entire `get_scan` / `create_scan` /
+  `create_bulk_scans` response until an MCP release ships.
+- `get_scan_screenshot` and `get_scan_landing_screenshot` warn that a resized
+  capture is top-cropped past 2.5x its width, and to omit `width` when the
+  whole page matters. `get_scan_creative_screenshot` never crops and is
+  unchanged.
+- `get_campaign` and `list_campaigns` describe the repeat / retry settings they
+  echo, `list_scan_children` explains why those fields are always neutral on a
+  discovered-ad child, and `get_scan` documents the creative's `click_through`
+  destination.
+
 ## [0.8.0] - 2026-07-10
 
 ### Added

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { NAME, VERSION, err, ok } from './chunk-SWFPWJ74.js';
+import { NAME, VERSION, err, ok } from './chunk-KFVVS55N.js';
 import process from 'process';
 import { z } from 'zod';
 
@@ -160,10 +160,10 @@ async function main() {
   }
   const config = configResult.value;
   if (config.transport === "stdio") {
-    const { bootstrapStdio } = await import('./stdio-bootstrap-6DXIUJTV.js');
+    const { bootstrapStdio } = await import('./stdio-bootstrap-7EXISZ66.js');
     return bootstrapStdio(config);
   }
-  const { bootstrapHttp } = await import('./http-bootstrap-ZXECSCYN.js');
+  const { bootstrapHttp } = await import('./http-bootstrap-3MGAQHND.js');
   return bootstrapHttp(config);
 }
 main().then(

package/dist/{chunk-E66U4JXR.js → chunk-5UVZYMC3.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { err, ok } from './chunk-SWFPWJ74.js';
+import { err, ok } from './chunk-KFVVS55N.js';
 import { createHash, randomUUID } from 'crypto';
 import createClient from 'openapi-fetch';
 import { fetch } from 'undici';
@@ -240,6 +240,7 @@ 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(),
@@ -250,7 +251,10 @@ z.object({
   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 +294,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 +362,11 @@ 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"),
+  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 +382,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 +415,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),
@@ -417,7 +436,10 @@ z.object({
   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,6 +483,7 @@ 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"),
@@ -476,6 +499,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(),
@@ -503,6 +529,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(),
@@ -542,6 +571,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 +681,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 +694,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 +709,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 +941,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 +1189,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 +1203,7 @@ var schemas = {
   EmulatorResponse,
   CampaignGroupResponse,
   GroupActionResponse,
+  RepeatMode,
   CampaignResponse,
   CampaignPickerItem,
   RunResponse,
@@ -1308,6 +1346,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 +1359,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");
 
@@ -1746,8 +1787,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 +1820,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 +1917,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 +1982,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 +3291,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 +3605,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 +3641,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 +3654,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;
@@ -3606,8 +3676,10 @@ function pickCampaignConfigBody(input) {
 // src/application/tools/campaigns/create-campaign.tool.ts
 var CreateCampaignInputShape = {
   name: z.string().min(1).max(200).describe("Display name (1-200 chars)."),
-  campaign_type: z.enum(["url", "ad_tag", "vast"]).describe("`url`, `ad_tag`, or `vast` \u2014 must match the target field below."),
-  url: z.string().url().optional().describe("Target URL (required if campaign_type=url)."),
+  campaign_type: z.enum(["url", "ad_tag", "vast", "ad_discovery"]).describe(
+    "`url`, `ad_tag`, `vast`, or `ad_discovery` \u2014 must match the target field below. `ad_discovery` is a publisher-page scan: set `url`; each run detects the page's ad blocks and opens a child scan per detected ad."
+  ),
+  url: z.string().url().optional().describe("Target URL (required if campaign_type=url or ad_discovery)."),
   ad_tag: z.string().optional().describe(
     "Ad-tag HTML/JS or an http(s) URL of a page with the rendered creative (required if campaign_type=ad_tag)."
   ),
@@ -3623,7 +3695,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,
@@ -3656,7 +3728,7 @@ var GetCampaignInputShape = {
 };
 var getCampaignTool = {
   name: "get_campaign",
-  description: "Get one campaign by UUID: name, type (url|ad_tag|vast), target URL / ad-tag / VAST tag (vast_tag), countries, schedule status, archive status, parent group.",
+  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,
@@ -3707,7 +3779,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,
@@ -3803,7 +3875,7 @@ var unarchiveCampaignTool = {
 var UpdateCampaignInputShape = {
   campaign_id: z.string().uuid().describe("Campaign UUID to update."),
   name: z.string().min(1).max(200).optional().describe("New display name."),
-  url: z.string().url().optional().describe("New target URL (url-type campaigns)."),
+  url: z.string().url().optional().describe("New target URL (url-type and ad_discovery campaigns)."),
   ad_tag: z.string().optional().describe(
     "New ad-tag HTML/JS or an http(s) URL of a page with the rendered creative (ad_tag-type campaigns)."
   ),
@@ -4674,11 +4746,12 @@ var CreateBulkScansInputShape = {
   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,
@@ -4695,7 +4768,8 @@ var createBulkScansTool = {
       ...input.ad_tag !== void 0 ? { ad_tag: input.ad_tag } : {},
       ...input.vast_tag !== void 0 ? { vast_tag: input.vast_tag } : {},
       ...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));
@@ -4720,11 +4794,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,
@@ -4744,7 +4819,8 @@ var createScanTool = {
       ...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));
@@ -4756,7 +4832,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,
@@ -4795,7 +4871,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",
@@ -4821,7 +4899,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 = {
@@ -4848,7 +4926,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,
@@ -4899,7 +4977,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,
@@ -5533,5 +5611,5 @@ function formatToolError(error) {
 }
 
 export { BearerToken, SERVER_INSTRUCTIONS, createHttpApiGateway, createPinoLogger, declareEmptyResourcesAndPrompts, newRequestId, wireToolsIntoMcpServer };
-//# sourceMappingURL=chunk-E66U4JXR.js.map
-//# sourceMappingURL=chunk-E66U4JXR.js.map
+//# sourceMappingURL=chunk-5UVZYMC3.js.map
+//# sourceMappingURL=chunk-5UVZYMC3.js.map