@datadive-tools/mcp 0.11.0 → 0.12.0

package/README.md

@@ -197,6 +197,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.12.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
+      }
+    );
   }
 };