@datadive-tools/mcp 0.11.0 → 0.13.0

package/dist/lib.d.ts

@@ -157,8 +157,9 @@ declare const allTools: ReadonlyArray<AnyTool>;
  * Source of truth for status semantics:
  *   datadive-backend/src/external-api/auth/api-key.guard.ts (401/402 logic)
  *   datadive-backend/src/external-api/external-api-v1.controller.ts (per-route docs)
+ *   datadive-backend/src/microservices/token/quota-exceeded.error.ts (QUOTA_EXCEEDED body)
  */
-type ApiErrorKind = "auth" | "payment" | "forbidden" | "not_found" | "bad_request" | "rate_limit" | "server" | "network" | "http";
+type ApiErrorKind = "auth" | "payment" | "quota" | "forbidden" | "not_found" | "bad_request" | "rate_limit" | "server" | "network" | "http";
 declare class ApiError extends Error {
     readonly kind: ApiErrorKind;
     readonly status: number;

package/dist/lib.js

@@ -26,6 +26,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;
@@ -38,6 +45,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(
@@ -88,6 +98,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;
@@ -100,7 +139,7 @@ function extractMessage(body) {
 }
 
 // package.json
-var version = "0.11.0";
+var version = "0.13.0";
 
 // src/http/client.ts
 var PKG_VERSION = version;
@@ -236,20 +275,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
+      }
+    );
   }
 };
 
@@ -426,16 +481,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."),
@@ -447,28 +510,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);
   }
 };