@datadive-tools/mcp 0.11.0 → 0.12.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.12.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
+      }
+    );
   }
 };