@datadive-tools/mcp 0.12.0 → 0.14.0

package/README.md

@@ -103,7 +103,7 @@ niches, plus pagination metadata. If you don't, see Troubleshooting below.
 | `get_niche_competitors` | Competitor ASINs, titles, BSR, category and niche statistics (sales, revenue, ratings, opportunity score). |
 | `get_ranking_juice` | DataDive proprietary ranking-juice metric per competitor (current vs optimized listing). |
 | `list_rank_radars` | Paginated list of rank radars. Filter by `nicheId`, `searchText` or `status` (`ACTIVE` by default, plus `PAUSED`, `ARCHIVED`, `ALL`). |
-| `get_rank_radar_data` | Historical keyword rankings for a rank radar within a `startDate`/`endDate` range. |
+| `get_rank_radar_data` | Historical keyword rankings for a rank radar within a `startDate`/`endDate` range (max 90 days). Paged by keyword: walk `currentPage` while `hasNext` is true, `pageSize` up to 100. |
 | `create_niche_dive` | **Spends dive tokens.** Starts new niche research from a seed ASIN. Async — returns a `diveId` to poll with `get_dive_status`. Requires `confirm: true`. |
 | `redive_niche` | **Spends dive tokens.** Refreshes an existing niche with current data — either the same competitors or a newly discovered set. Async — returns a `diveId` to poll with `get_dive_status`. Requires `confirm: true`. |
 | `get_dive_status` | Poll a dive started by `create_niche_dive` or `redive_niche`: `in_progress`, `success` (carries the `nicheId`), or `error`. |
@@ -146,6 +146,14 @@ assistant to confirm the cost with you first:
 
 Check your remaining balance any time with `get_quota`.
 
+`create_rank_radar` uses that first, unconfirmed call to preview the creation
+against the API, so the note it comes back with can tell you something specific
+rather than only the token cost — for instance that the product family you asked
+for is already tracked by another of your Rank Radars, which would spend Tracked
+Search Terms on it twice. The preview creates nothing and spends nothing, and a
+warning never blocks the creation: two Rank Radars on one family is how you
+track two different sets of search terms and keep separate statistics.
+
 The other write tools — `pause_rank_radar`, `resume_rank_radar` and the three
 `*_rank_radar_search_terms` tools — need no confirmation. They only move Daily
 Tracked Keywords capacity, which is freed again when you pause, and each is

package/dist/index.js

@@ -144,7 +144,7 @@ function extractMessage(body) {
 }
 
 // package.json
-var version = "0.12.0";
+var version = "0.14.0";
 
 // src/http/client.ts
 var PKG_VERSION = version;
@@ -462,22 +462,33 @@ var listRankRadarsTool = {
 // src/tools/get-rank-radar-data.ts
 import { z as z7 } from "zod";
 var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+var RANK_RADAR_KEYWORDS_MAX_PAGE_SIZE = 100;
+var RANK_RADAR_MAX_DATE_RANGE_DAYS = 90;
 var inputSchema7 = {
   rankRadarId: z7.string().uuid().describe("The Rank Radar UUID (from `list_rank_radars`)."),
   startDate: z7.string().regex(ISO_DATE, "startDate must be in yyyy-mm-dd format").describe("Start date for the ranking data range, yyyy-mm-dd (e.g. 2024-03-26)."),
-  endDate: z7.string().regex(ISO_DATE, "endDate must be in yyyy-mm-dd format").describe("End date for the ranking data range, yyyy-mm-dd (e.g. 2024-04-26). Must be on or after startDate.")
+  endDate: z7.string().regex(ISO_DATE, "endDate must be in yyyy-mm-dd format").describe(
+    `End date for the ranking data range, yyyy-mm-dd (e.g. 2024-04-26). Must be on or after startDate, and at most ${RANK_RADAR_MAX_DATE_RANGE_DAYS} days after it.`
+  ),
+  currentPage: z7.number().int().min(1).optional().describe("Page of keywords, 1-indexed. Defaults to 1."),
+  pageSize: z7.number().int().min(1).max(RANK_RADAR_KEYWORDS_MAX_PAGE_SIZE).optional().describe(`Keywords per page (max ${RANK_RADAR_KEYWORDS_MAX_PAGE_SIZE}). Defaults to 20.`)
 };
 var getRankRadarDataTool = {
   name: "get_rank_radar_data",
   title: "Get Keyword Rankings for a Rank Radar",
-  description: "Use this to analyze keyword ranking trends over time. Requires startDate and endDate (yyyy-mm-dd). Retrieves historical keyword ranking data for the specified Rank Radar within the date range. Returns an array of tracked keywords; each has id, keyword, searchVolume, ranks (per-day { date, organicRank, impressionRank }), and any highlight annotations. Use after `list_rank_radars` to discover a `rankRadarId`.",
+  description: `Use this to analyze keyword ranking trends over time. Requires startDate and endDate (yyyy-mm-dd), at most ${RANK_RADAR_MAX_DATE_RANGE_DAYS} days apart. Retrieves historical keyword ranking data for the specified Rank Radar within the date range. Results are paged by keyword: \`data\` holds one page of tracked keywords, and the response carries currentPage, pageSize, total, lastPage, hasNext and hasPrev. \`total\` is the Rank Radar's keyword count; to read every keyword, call again with \`currentPage\` + 1 while \`hasNext\` is true, using \`pageSize\` ${RANK_RADAR_KEYWORDS_MAX_PAGE_SIZE} for large Rank Radars. Each keyword has id, keyword, searchVolume, relevancy, ranks (per-day { date, organicRank, sponsoredRank, impressionRank }), and any highlight annotations. Paused keywords are not included. Use after \`list_rank_radars\` to discover a \`rankRadarId\`.`,
   inputSchema: inputSchema7,
   annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
     return await httpGet(
       { config: ctx.config, toolName: "get_rank_radar_data" },
       `/v1/niches/rank-radars/${encodeURIComponent(args.rankRadarId)}`,
-      { startDate: args.startDate, endDate: args.endDate }
+      {
+        startDate: args.startDate,
+        endDate: args.endDate,
+        currentPage: args.currentPage,
+        pageSize: args.pageSize
+      }
     );
   }
 };
@@ -486,16 +497,24 @@ var getRankRadarDataTool = {
 import { z as z8 } from "zod";
 
 // src/tools/confirm.ts
-function requireConfirmation(confirm, ctx, costNote) {
-  if (confirm === true || ctx.config.autoConfirmWrites) return null;
+function needsConfirmation(confirm, ctx) {
+  return !(confirm === true || ctx.config.autoConfirmWrites);
+}
+function confirmationRequired(costNote, warnings) {
   return {
     status: "confirmation_required",
     message: "This action spends billable tokens and cannot be undone. Confirm the cost with the user, then call again with `confirm: true` to proceed.",
-    costNote
+    costNote,
+    ...warnings && warnings.length > 0 ? { warnings } : {}
   };
 }
+function requireConfirmation(confirm, ctx, costNote) {
+  if (!needsConfirmation(confirm, ctx)) return null;
+  return confirmationRequired(costNote);
+}
 
 // src/tools/create-rank-radar.ts
+var PATH = "/v1/niches/rank-radars";
 var inputSchema8 = {
   asin: z8.string().min(1).describe("The ASIN to track keyword rankings for."),
   numberOfKeywords: z8.number().int().min(1).describe("How many keywords to track (minimum 1). More keywords = broader tracking but more Search Term tokens."),
@@ -507,28 +526,28 @@ var inputSchema8 = {
 var createRankRadarTool = {
   name: "create_rank_radar",
   title: "Create a Rank Radar",
-  description: "Use this to start tracking organic and sponsored keyword rankings for an ASIN within a niche. \u26A0\uFE0F Spends Search Term tokens (cost scales with `numberOfKeywords`) and cannot be undone \u2014 set `confirm: true` only after the user approves the cost. Not safe to retry: each call spends tokens again and creates a separate Rank Radar \u2014 if a call errors or times out, check `list_rank_radars` instead of re-calling. Returns the new `rankRadarId`; read its data later with `get_rank_radar_data`. Requires `asin`, `numberOfKeywords` (min 1), and a `nicheId` from `list_niches`.",
+  description: "Use this to start tracking organic and sponsored keyword rankings for an ASIN within a niche. \u26A0\uFE0F Spends Search Term tokens (cost scales with `numberOfKeywords`) and cannot be undone \u2014 set `confirm: true` only after the user approves the cost. Not safe to retry: each call spends tokens again and creates a separate Rank Radar \u2014 if a call errors or times out, check `list_rank_radars` instead of re-calling. The first call previews the creation and may return `warnings` alongside the cost note \u2014 for example that this product family is already tracked by another Rank Radar. Show every warning `message` to the user verbatim, before asking them to confirm; do not summarise it or decide on their behalf. A warning never blocks creation. Returns the new `rankRadarId`; read its data later with `get_rank_radar_data`. Requires `asin`, `numberOfKeywords` (min 1), and a `nicheId` from `list_niches`.",
   inputSchema: inputSchema8,
   // destructiveHint is technically "additive" here (this creates a new Rank Radar, it
   // doesn't destroy data), but we flag it destructive so clients prompt before the
   // irreversible token spend. The confirm gate enforces this server-side regardless.
   annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
   handler: async (args, ctx) => {
-    const pending = requireConfirmation(
-      args.confirm,
-      ctx,
-      `Creating this Rank Radar consumes Search Term tokens \u2014 one per keyword tracked (${args.numberOfKeywords} requested).`
-    );
-    if (pending) return pending;
-    return await httpPost(
-      { config: ctx.config, toolName: "create_rank_radar" },
-      "/v1/niches/rank-radars",
-      {
-        asin: args.asin,
-        numberOfKeywords: args.numberOfKeywords,
-        nicheId: args.nicheId
-      }
-    );
+    const request = { config: ctx.config, toolName: "create_rank_radar" };
+    const body = {
+      asin: args.asin,
+      numberOfKeywords: args.numberOfKeywords,
+      nicheId: args.nicheId
+    };
+    if (needsConfirmation(args.confirm, ctx)) {
+      const preview = await httpPost(request, PATH, { ...body, dryRun: true });
+      if (preview.rankRadarId != null) return preview;
+      return confirmationRequired(
+        `Creating this Rank Radar consumes Search Term tokens \u2014 one per keyword tracked (${args.numberOfKeywords} requested).`,
+        preview.warnings
+      );
+    }
+    return await httpPost(request, PATH, body);
   }
 };