@datadive-tools/mcp 0.11.0 → 0.13.0

package/README.md

@@ -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
@@ -197,6 +205,7 @@ specific HTTP status from the DataDive API.
 |---|---|
 | **Authentication failed: your DATADIVE_API_KEY is invalid or expired** | The key is wrong, deleted, or expired. Generate a new one at https://2.datadive.tools/api-key. |
 | **Subscription is inactive or paused** | Resume billing at https://2.datadive.tools — the API key is valid but the subscription isn't active. |
+| **Quota exceeded** / **… quota exceeded** | The subscription's quota for that billable feature (Dive tokens, Rank Radar tracked keywords, AI Copywriter prompts, …) is used up. The message names the feature, the usage, the next refresh date when there is one, and links to the subscription overview page where it can be raised. Don't retry until it has been. |
 | **Forbidden** | The key is valid but doesn't have access to that resource. Usually a niche/rank-radar that belongs to a different org. |
 | **Rate limit exceeded** | Wait a few seconds and retry. |
 | **Bad request** | Check the parameters — the message echoes the server's validation error (e.g., `pageSize must not exceed 50`). |

package/dist/index.js

@@ -31,6 +31,13 @@ import { z } from "zod";
 
 // src/http/errors.ts
 var KEY_HELP_URL2 = "https://2.datadive.tools/api-key";
+var FEATURE_LABELS = {
+  DIVED_ASINS: "Dive tokens",
+  RANK_RADAR_KEYWORDS: "Rank Radar tracked keywords",
+  PRODUCT_BRIEF_ASINS: "Product Brief ASINs",
+  AI_COPYWRITER_PROMPTS: "AI Copywriter prompts",
+  INDEXING_DIAGNOSIS: "Indexing Diagnosis checks"
+};
 var ApiError = class _ApiError extends Error {
   kind;
   status;
@@ -43,6 +50,9 @@ var ApiError = class _ApiError extends Error {
     this.body = body;
   }
   static fromHttp(status, body) {
+    if (isQuotaExceededBody(body)) {
+      return new _ApiError("quota", status, quotaExceededMessage(body), body);
+    }
     const serverMsg = extractMessage(body);
     if (status === 400) {
       return new _ApiError(
@@ -93,6 +103,35 @@ var ApiError = class _ApiError extends Error {
     return new _ApiError("http", status, serverMsg ?? `HTTP ${status}`, body);
   }
 };
+function isQuotaExceededBody(body) {
+  if (!body || typeof body !== "object") return false;
+  const b = body;
+  return b.error === "QUOTA_EXCEEDED" && typeof b.subscriptionUrl === "string";
+}
+function quotaExceededMessage(body) {
+  const lead = typeof body.message === "string" && body.message.length > 0 ? body.message : "Quota exceeded";
+  const feature = body.feature ? FEATURE_LABELS[body.feature] ?? body.feature : null;
+  const parts = [];
+  if (feature) {
+    parts.push(`This subscription has used up its ${feature} quota${usageSuffix(body)}.`);
+  } else {
+    parts.push(`This subscription has used up its quota for this action${usageSuffix(body)}.`);
+  }
+  if (body.nextRefreshDate) {
+    parts.push(`It refreshes on ${body.nextRefreshDate.slice(0, 10)}.`);
+  }
+  parts.push(
+    `Tell the user which quota ran out and that they can review or raise it on their subscription page: ${body.subscriptionUrl}`
+  );
+  parts.push("Do not retry this call until the quota has been raised.");
+  return `${lead}. ${parts.join(" ")}`;
+}
+function usageSuffix(body) {
+  if (typeof body.used === "number" && typeof body.capacity === "number") {
+    return ` (${body.used} of ${body.capacity} used)`;
+  }
+  return "";
+}
 function extractMessage(body) {
   if (!body || typeof body !== "object") return null;
   const b = body;
@@ -105,7 +144,7 @@ function extractMessage(body) {
 }
 
 // package.json
-var version = "0.11.0";
+var version = "0.13.0";
 
 // src/http/client.ts
 var PKG_VERSION = version;
@@ -241,20 +280,36 @@ function isObject(v) {
 // src/tools/list-niches.ts
 var LIST_NICHES_MAX_PAGE_SIZE = 50;
 var inputSchema = {
-  currentPage: z.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
-  pageSize: z.number().int().min(1).max(LIST_NICHES_MAX_PAGE_SIZE).optional().describe(`Items per page (max ${LIST_NICHES_MAX_PAGE_SIZE}). Defaults to 20.`)
+  currentPage: z.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1. Keep requesting the next page while `hasNext` is true."),
+  pageSize: z.number().int().min(1).max(LIST_NICHES_MAX_PAGE_SIZE).optional().describe(`Items per page (max ${LIST_NICHES_MAX_PAGE_SIZE}). Defaults to 20.`),
+  searchText: z.string().trim().min(1).max(200).optional().describe(
+    "Case-insensitive partial match on the niche label or hero keyword. Prefer this over paging through everything when the user names a niche."
+  ),
+  searchAsin: z.string().trim().regex(/^[A-Za-z0-9]{10}$/, "must be a 10-character ASIN").optional().describe("Only niches whose competitor set contains this ASIN (10 characters, e.g. B08N5WRWNW)."),
+  orderBy: z.enum(["lastDived", "name"]).optional().describe(
+    "Sort field: `lastDived` (by latestResearchDate, newest first by default) or `name` (by nicheLabel, A\u2192Z by default). Defaults to `lastDived`."
+  ),
+  sortOrder: z.enum(["ASC", "DESC"]).optional().describe("Sort direction. Defaults to DESC for `lastDived` and ASC for `name`.")
 };
 var listNichesTool = {
   name: "list_niches",
   title: "List DataDive Niches",
-  description: "Use this first when the user asks about their niches, or to find a `nicheId` for use with `get_niche_keywords`, `get_niche_competitors`, or `get_ranking_juice`. Retrieves the Niches of the account. Each Niche represents a market segment or product category being tracked. Returns nicheId, heroKeyword, nicheLabel, marketplace (com/uk/de/...), and latestResearchDate per niche, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). TEMPORARY LIMITATION: the API does not apply paging yet, so a single call returns every niche of the account whatever `currentPage` and `pageSize` say, and the pagination metadata describes a page that was not applied. Read the whole `data` array and filter it yourself; do not walk `currentPage` while `hasNext` is true, because every page repeats the same rows. Accounts with many niches therefore return a large response. There is no server-side search or sorting.",
+  description: `Use this first when the user asks about their niches, or to find a \`nicheId\` for use with \`get_niche_keywords\`, \`get_niche_competitors\`, or \`get_ranking_juice\`. Retrieves a paginated list of Niches, newest dive first. Each Niche represents a market segment or product category being tracked. Returns nicheId, heroKeyword, nicheLabel, marketplace (com/uk/de/...), and latestResearchDate per niche, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev). Narrow with \`searchText\` (label/keyword) or \`searchAsin\` (a competitor ASIN) instead of scanning pages; a page holds at most ${LIST_NICHES_MAX_PAGE_SIZE} niches, so the full list of a large account needs several calls.`,
   inputSchema,
   annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
-    return await httpGet({ config: ctx.config, toolName: "list_niches" }, "/v1/niches", {
-      currentPage: args.currentPage,
-      pageSize: args.pageSize
-    });
+    return await httpGet(
+      { config: ctx.config, toolName: "list_niches" },
+      "/v1/niches",
+      {
+        currentPage: args.currentPage,
+        pageSize: args.pageSize,
+        searchText: args.searchText,
+        searchAsin: args.searchAsin,
+        orderBy: args.orderBy,
+        sortOrder: args.sortOrder
+      }
+    );
   }
 };
 
@@ -431,16 +486,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."),
@@ -452,28 +515,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);
   }
 };