mcpscraper-sdk 0.26.2 → 0.27.0

package/README.md

@@ -38,11 +38,14 @@ try {
 Every non-2xx response throws a `ScraperApiError` with `status`, `code`, and the raw response `body`. Two cases have typed narrowing helpers:
 
 - `err.isInsufficientBalance()` — narrows `err.body` to `{ balance_credits, required_credits, topup_url, ... }`.
-- `err.isConcurrencyLimitExceeded()` — narrows `err.body` to `{ active, limit, retryable, ... }`.
+- `err.isConcurrencyLimitExceeded()` — narrows `err.body` to `{ active, limit, retryable, upgrade, ... }`.
+- `err.isVerificationChallenge()` / `err.isTimeout()` — preserve actionable, vendor-neutral retry and charge details returned by the service.
+
+Current Google search pricing is 60 Credits per SERP search and 400 Credits plus 10 Credits per returned question for PAA. One optional concurrency pack adds two browser slots for $5/month; quantity `n` adds `2n` slots for `$5n` without changing the base plan.
 
 ## API surface
 
-`client.tools` is the generated, typed 246-tool MCP surface. It includes 145 MCP Scraper tools and all 101 mirrored Memory tools from `contracts/mcp.tools.json`.
+`client.tools` is the generated, typed 249-tool MCP surface. It includes 148 MCP Scraper tools and all 101 mirrored Memory tools from `contracts/mcp.tools.json`.
 
 For multimodal results such as `meta_ad_creative_media`, call `client.tools.callToolResult(...)` to preserve native MCP image/audio/resource blocks. `callTool(...)` remains backward-compatible and returns the parsed structured or text value.
 

package/dist/index.cjs

@@ -39,7 +39,78 @@ function readString(body, key) {
   return void 0;
 }
 var PUBLIC_SERVICE_UNAVAILABLE_MESSAGE = "This operation is temporarily unavailable. Please retry later.";
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "request_aborted",
+  "captcha_exhausted",
+  "captcha_or_blocked",
+  "location_mismatch",
+  "proxy_tunnel_failed",
+  "proxy_unavailable",
+  "harvest_timeout",
+  "mcp_request_timeout",
+  "extraction_failed",
+  "concurrency_limit_exceeded",
+  "unauthorized",
+  "forbidden",
+  "invalid_request",
+  "rate_limited",
+  "insufficient_balance",
+  "service_unavailable"
+]);
+var PUBLIC_ERROR_FIELDS = /* @__PURE__ */ new Set([
+  "error",
+  "error_code",
+  "error_type",
+  "message",
+  "retryable",
+  "retry_after_seconds",
+  "charge_status",
+  "details",
+  "active",
+  "limit",
+  "operation",
+  "upgrade",
+  "upgrade_url",
+  "upgrade_command",
+  "balance_credits",
+  "required_credits",
+  "topup_url"
+]);
+var PUBLIC_DETAIL_FIELDS = /* @__PURE__ */ new Set([
+  "active",
+  "limit",
+  "operation",
+  "upgrade_url",
+  "topup_url",
+  "upgrade_command",
+  "slots_per_pack",
+  "pack_price_usd",
+  "balance_credits",
+  "required_credits"
+]);
+function recognizedPublicDetails(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const details = Object.fromEntries(
+    Object.entries(value).filter(
+      ([key, child]) => PUBLIC_DETAIL_FIELDS.has(key) && (child === null || ["string", "number", "boolean"].includes(typeof child))
+    )
+  );
+  return Object.keys(details).length > 0 ? details : void 0;
+}
+function recognizedPublicErrorBody(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record = body;
+  const code = readString(record, "error_code");
+  if (!code || !PUBLIC_ERROR_CODES.has(code)) return void 0;
+  const safe = Object.fromEntries(Object.entries(record).filter(([key]) => PUBLIC_ERROR_FIELDS.has(key)));
+  const details = recognizedPublicDetails(record.details);
+  if (details) safe.details = details;
+  else delete safe.details;
+  return safe;
+}
 function publicErrorBody(status, body) {
+  const recognized = recognizedPublicErrorBody(body);
+  if (recognized) return recognized;
   if (status < 500) return body;
   return {
     error: "service_unavailable",
@@ -71,6 +142,12 @@ var ScraperApiError = class extends Error {
   isStructuredError() {
     return typeof readString(this.body, "error_type") === "string";
   }
+  isVerificationChallenge() {
+    return this.code === "captcha_exhausted" || this.code === "captcha_or_blocked";
+  }
+  isTimeout() {
+    return this.code === "harvest_timeout" || this.code === "mcp_request_timeout";
+  }
 };
 
 // src/client.ts

package/dist/index.d.cts

@@ -17,10 +17,9 @@ interface paths {
         put?: never;
         /**
          * Run a Google SERP search, or a full People-Also-Ask harvest
-         * @description Set `serpOnly: true` for a pure organic-results/SERP call (14 credits; runs headful so
-         *     Google serves a complete page).
+         * @description Set `serpOnly: true` for a pure organic-results/SERP call (60 Credits).
          *     Omit or set `false` for a full People-Also-Ask harvest, which also returns SERP data
-         *     (55 credit base + 3 credits per question actually returned; unused estimate is
+         *     (400 Credit base + 10 Credits per question actually returned; unused estimate is
          *     refunded). Runs synchronously and returns the result inline.
          */
         post: operations["harvestSync"];
@@ -618,8 +617,7 @@ interface paths {
         put?: never;
         /**
          * Structured SERP capture with AI Overview/AI Mode detection, entity IDs, and location-match evidence
-         * @description Holds 14 credits for the SERP and settles to 4 credits when the capture is served
-         *     headless, or retains 14 credits when it runs headful.
+         * @description Costs 60 Credits for the base SERP capture.
          *     When `includePageSnapshots` is true, also holds 1 credit per requested
          *     `pageSnapshotLimit` slot and settles to 1 credit per URL actually attempted.
          *     Rate-limited to 60 requests/minute per account.
@@ -838,15 +836,33 @@ interface components {
         Error: {
             error: string;
             error_code?: string;
+            error_type?: string;
             message?: string;
-        };
-        /** @description Shared structured error shape used by SERP Intelligence endpoints. */
-        StructuredError: {
-            error_code: string;
-            error_type: string;
+            retryable?: boolean;
+            retry_after_seconds?: number;
+            charge_status?: components["schemas"]["PublicChargeStatus"];
+            details?: components["schemas"]["PublicErrorDetails"];
+        };
+        /** @enum {string} */
+        PublicChargeStatus: "not_charged" | "refunded" | "charged";
+        /** @description Bounded, vendor-neutral recovery and account details safe for public clients. */
+        PublicErrorDetails: {
+            [key: string]: string | number | boolean | (string | null);
+        };
+        /** @description Stable public failure envelope shared across REST and MCP operations. */
+        PublicErrorEnvelope: {
+            /** @enum {string} */
+            error_code: "request_aborted" | "captcha_exhausted" | "captcha_or_blocked" | "location_mismatch" | "proxy_tunnel_failed" | "proxy_unavailable" | "harvest_timeout" | "mcp_request_timeout" | "extraction_failed" | "concurrency_limit_exceeded" | "unauthorized" | "forbidden" | "invalid_request" | "rate_limited" | "insufficient_balance" | "service_unavailable";
+            /** @enum {string} */
+            error_type: "request_aborted" | "captcha" | "location_mismatch" | "connection" | "timeout" | "extraction" | "concurrency_limit" | "unauthorized" | "forbidden" | "invalid_request" | "rate_limit" | "billing" | "service_unavailable";
             message: string;
             retryable: boolean;
+            retry_after_seconds?: number;
+            charge_status?: components["schemas"]["PublicChargeStatus"];
+            details?: components["schemas"]["PublicErrorDetails"];
         };
+        /** @description Shared structured error shape used by SERP Intelligence endpoints. */
+        StructuredError: components["schemas"]["PublicErrorEnvelope"];
         InsufficientBalanceError: {
             /** @enum {string} */
             error: "insufficient_balance";
@@ -858,22 +874,53 @@ interface components {
             /** Format: uri */
             topup_url: string;
         };
-        ConcurrencyLimitError: {
+        ConcurrencyLimitError: components["schemas"]["PublicErrorEnvelope"] & {
             error?: string;
-            message: string;
             /** @enum {string} */
             error_code: "concurrency_limit_exceeded";
             /** @enum {string} */
-            error_type?: "concurrency_limit";
-            retryable?: boolean;
+            error_type: "concurrency_limit";
             active: number;
             limit: number;
             operation: string;
+            upgrade: components["schemas"]["ConcurrencyPack"];
             /** Format: uri */
             upgrade_url?: string;
-            /** @description CLI command to buy an extra concurrency slot. */
+            /** @description CLI command to buy or update two-browser concurrency packs. */
             upgrade_command?: string;
         };
+        /** @description One $5 monthly pack adds exactly two concurrent browser slots. Quantity n adds 2n slots for $5n per month. */
+        ConcurrencyPack: {
+            product: string;
+            rate_policy_version: string;
+            price_label: string;
+            /** @enum {number} */
+            unit_amount_usd: 5;
+            /** @enum {string} */
+            currency: "usd";
+            /** @enum {string} */
+            interval: "month";
+            /** @enum {string} */
+            billing_unit: "pack";
+            pack_quantity: number;
+            /** @enum {integer} */
+            slots_per_pack: 2;
+            extra_slots: number;
+            /** Format: uri */
+            billing_url: string;
+            terminal_command: string;
+            terminal_command_with_api_key_env: string;
+        };
+        /** @description Quantity-based add-on entitlement projected by account and billing endpoints. */
+        ConcurrencyAccountView: {
+            pack_quantity: number;
+            /** @enum {integer} */
+            slots_per_pack: 2;
+            extra_concurrency_slots: number;
+            effective_limit: number;
+            monthly_amount_usd: number;
+            has_subscription?: boolean;
+        };
         HarvestSyncRequest: {
             /** @description Search query. */
             query: string;
@@ -3866,6 +3913,9 @@ declare class ScraperClient {
 type InsufficientBalanceBody = components['schemas']['InsufficientBalanceError'];
 type ConcurrencyLimitBody = components['schemas']['ConcurrencyLimitError'];
 type StructuredErrorBody = components['schemas']['StructuredError'];
+type PublicErrorEnvelopeBody = components['schemas']['PublicErrorEnvelope'];
+type ConcurrencyPackBody = components['schemas']['ConcurrencyPack'];
+type ConcurrencyAccountViewBody = components['schemas']['ConcurrencyAccountView'];
 declare class ScraperApiError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -3880,6 +3930,12 @@ declare class ScraperApiError extends Error {
     isStructuredError(): this is ScraperApiError & {
         body: StructuredErrorBody;
     };
+    isVerificationChallenge(): this is ScraperApiError & {
+        body: PublicErrorEnvelopeBody;
+    };
+    isTimeout(): this is ScraperApiError & {
+        body: PublicErrorEnvelopeBody;
+    };
 }
 
-export { type ConcurrencyLimitBody, type InsufficientBalanceBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };
+export { type ConcurrencyAccountViewBody, type ConcurrencyLimitBody, type ConcurrencyPackBody, type InsufficientBalanceBody, type PublicErrorEnvelopeBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };

package/dist/index.d.ts

@@ -17,10 +17,9 @@ interface paths {
         put?: never;
         /**
          * Run a Google SERP search, or a full People-Also-Ask harvest
-         * @description Set `serpOnly: true` for a pure organic-results/SERP call (14 credits; runs headful so
-         *     Google serves a complete page).
+         * @description Set `serpOnly: true` for a pure organic-results/SERP call (60 Credits).
          *     Omit or set `false` for a full People-Also-Ask harvest, which also returns SERP data
-         *     (55 credit base + 3 credits per question actually returned; unused estimate is
+         *     (400 Credit base + 10 Credits per question actually returned; unused estimate is
          *     refunded). Runs synchronously and returns the result inline.
          */
         post: operations["harvestSync"];
@@ -618,8 +617,7 @@ interface paths {
         put?: never;
         /**
          * Structured SERP capture with AI Overview/AI Mode detection, entity IDs, and location-match evidence
-         * @description Holds 14 credits for the SERP and settles to 4 credits when the capture is served
-         *     headless, or retains 14 credits when it runs headful.
+         * @description Costs 60 Credits for the base SERP capture.
          *     When `includePageSnapshots` is true, also holds 1 credit per requested
          *     `pageSnapshotLimit` slot and settles to 1 credit per URL actually attempted.
          *     Rate-limited to 60 requests/minute per account.
@@ -838,15 +836,33 @@ interface components {
         Error: {
             error: string;
             error_code?: string;
+            error_type?: string;
             message?: string;
-        };
-        /** @description Shared structured error shape used by SERP Intelligence endpoints. */
-        StructuredError: {
-            error_code: string;
-            error_type: string;
+            retryable?: boolean;
+            retry_after_seconds?: number;
+            charge_status?: components["schemas"]["PublicChargeStatus"];
+            details?: components["schemas"]["PublicErrorDetails"];
+        };
+        /** @enum {string} */
+        PublicChargeStatus: "not_charged" | "refunded" | "charged";
+        /** @description Bounded, vendor-neutral recovery and account details safe for public clients. */
+        PublicErrorDetails: {
+            [key: string]: string | number | boolean | (string | null);
+        };
+        /** @description Stable public failure envelope shared across REST and MCP operations. */
+        PublicErrorEnvelope: {
+            /** @enum {string} */
+            error_code: "request_aborted" | "captcha_exhausted" | "captcha_or_blocked" | "location_mismatch" | "proxy_tunnel_failed" | "proxy_unavailable" | "harvest_timeout" | "mcp_request_timeout" | "extraction_failed" | "concurrency_limit_exceeded" | "unauthorized" | "forbidden" | "invalid_request" | "rate_limited" | "insufficient_balance" | "service_unavailable";
+            /** @enum {string} */
+            error_type: "request_aborted" | "captcha" | "location_mismatch" | "connection" | "timeout" | "extraction" | "concurrency_limit" | "unauthorized" | "forbidden" | "invalid_request" | "rate_limit" | "billing" | "service_unavailable";
             message: string;
             retryable: boolean;
+            retry_after_seconds?: number;
+            charge_status?: components["schemas"]["PublicChargeStatus"];
+            details?: components["schemas"]["PublicErrorDetails"];
         };
+        /** @description Shared structured error shape used by SERP Intelligence endpoints. */
+        StructuredError: components["schemas"]["PublicErrorEnvelope"];
         InsufficientBalanceError: {
             /** @enum {string} */
             error: "insufficient_balance";
@@ -858,22 +874,53 @@ interface components {
             /** Format: uri */
             topup_url: string;
         };
-        ConcurrencyLimitError: {
+        ConcurrencyLimitError: components["schemas"]["PublicErrorEnvelope"] & {
             error?: string;
-            message: string;
             /** @enum {string} */
             error_code: "concurrency_limit_exceeded";
             /** @enum {string} */
-            error_type?: "concurrency_limit";
-            retryable?: boolean;
+            error_type: "concurrency_limit";
             active: number;
             limit: number;
             operation: string;
+            upgrade: components["schemas"]["ConcurrencyPack"];
             /** Format: uri */
             upgrade_url?: string;
-            /** @description CLI command to buy an extra concurrency slot. */
+            /** @description CLI command to buy or update two-browser concurrency packs. */
             upgrade_command?: string;
         };
+        /** @description One $5 monthly pack adds exactly two concurrent browser slots. Quantity n adds 2n slots for $5n per month. */
+        ConcurrencyPack: {
+            product: string;
+            rate_policy_version: string;
+            price_label: string;
+            /** @enum {number} */
+            unit_amount_usd: 5;
+            /** @enum {string} */
+            currency: "usd";
+            /** @enum {string} */
+            interval: "month";
+            /** @enum {string} */
+            billing_unit: "pack";
+            pack_quantity: number;
+            /** @enum {integer} */
+            slots_per_pack: 2;
+            extra_slots: number;
+            /** Format: uri */
+            billing_url: string;
+            terminal_command: string;
+            terminal_command_with_api_key_env: string;
+        };
+        /** @description Quantity-based add-on entitlement projected by account and billing endpoints. */
+        ConcurrencyAccountView: {
+            pack_quantity: number;
+            /** @enum {integer} */
+            slots_per_pack: 2;
+            extra_concurrency_slots: number;
+            effective_limit: number;
+            monthly_amount_usd: number;
+            has_subscription?: boolean;
+        };
         HarvestSyncRequest: {
             /** @description Search query. */
             query: string;
@@ -3866,6 +3913,9 @@ declare class ScraperClient {
 type InsufficientBalanceBody = components['schemas']['InsufficientBalanceError'];
 type ConcurrencyLimitBody = components['schemas']['ConcurrencyLimitError'];
 type StructuredErrorBody = components['schemas']['StructuredError'];
+type PublicErrorEnvelopeBody = components['schemas']['PublicErrorEnvelope'];
+type ConcurrencyPackBody = components['schemas']['ConcurrencyPack'];
+type ConcurrencyAccountViewBody = components['schemas']['ConcurrencyAccountView'];
 declare class ScraperApiError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -3880,6 +3930,12 @@ declare class ScraperApiError extends Error {
     isStructuredError(): this is ScraperApiError & {
         body: StructuredErrorBody;
     };
+    isVerificationChallenge(): this is ScraperApiError & {
+        body: PublicErrorEnvelopeBody;
+    };
+    isTimeout(): this is ScraperApiError & {
+        body: PublicErrorEnvelopeBody;
+    };
 }
 
-export { type ConcurrencyLimitBody, type InsufficientBalanceBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };
+export { type ConcurrencyAccountViewBody, type ConcurrencyLimitBody, type ConcurrencyPackBody, type InsufficientBalanceBody, type PublicErrorEnvelopeBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };

package/dist/index.js

@@ -7,7 +7,78 @@ function readString(body, key) {
   return void 0;
 }
 var PUBLIC_SERVICE_UNAVAILABLE_MESSAGE = "This operation is temporarily unavailable. Please retry later.";
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "request_aborted",
+  "captcha_exhausted",
+  "captcha_or_blocked",
+  "location_mismatch",
+  "proxy_tunnel_failed",
+  "proxy_unavailable",
+  "harvest_timeout",
+  "mcp_request_timeout",
+  "extraction_failed",
+  "concurrency_limit_exceeded",
+  "unauthorized",
+  "forbidden",
+  "invalid_request",
+  "rate_limited",
+  "insufficient_balance",
+  "service_unavailable"
+]);
+var PUBLIC_ERROR_FIELDS = /* @__PURE__ */ new Set([
+  "error",
+  "error_code",
+  "error_type",
+  "message",
+  "retryable",
+  "retry_after_seconds",
+  "charge_status",
+  "details",
+  "active",
+  "limit",
+  "operation",
+  "upgrade",
+  "upgrade_url",
+  "upgrade_command",
+  "balance_credits",
+  "required_credits",
+  "topup_url"
+]);
+var PUBLIC_DETAIL_FIELDS = /* @__PURE__ */ new Set([
+  "active",
+  "limit",
+  "operation",
+  "upgrade_url",
+  "topup_url",
+  "upgrade_command",
+  "slots_per_pack",
+  "pack_price_usd",
+  "balance_credits",
+  "required_credits"
+]);
+function recognizedPublicDetails(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const details = Object.fromEntries(
+    Object.entries(value).filter(
+      ([key, child]) => PUBLIC_DETAIL_FIELDS.has(key) && (child === null || ["string", "number", "boolean"].includes(typeof child))
+    )
+  );
+  return Object.keys(details).length > 0 ? details : void 0;
+}
+function recognizedPublicErrorBody(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record = body;
+  const code = readString(record, "error_code");
+  if (!code || !PUBLIC_ERROR_CODES.has(code)) return void 0;
+  const safe = Object.fromEntries(Object.entries(record).filter(([key]) => PUBLIC_ERROR_FIELDS.has(key)));
+  const details = recognizedPublicDetails(record.details);
+  if (details) safe.details = details;
+  else delete safe.details;
+  return safe;
+}
 function publicErrorBody(status, body) {
+  const recognized = recognizedPublicErrorBody(body);
+  if (recognized) return recognized;
   if (status < 500) return body;
   return {
     error: "service_unavailable",
@@ -39,6 +110,12 @@ var ScraperApiError = class extends Error {
   isStructuredError() {
     return typeof readString(this.body, "error_type") === "string";
   }
+  isVerificationChallenge() {
+    return this.code === "captcha_exhausted" || this.code === "captcha_or_blocked";
+  }
+  isTimeout() {
+    return this.code === "harvest_timeout" || this.code === "mcp_request_timeout";
+  }
 };
 
 // src/client.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcpscraper-sdk",
-  "version": "0.26.2",
-  "description": "Official Node.js client for all 246 mcpscraper.dev MCP tools and the REST API",
+  "version": "0.27.0",
+  "description": "Official Node.js client for all 249 mcpscraper.dev MCP tools and the REST API",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -32,7 +32,7 @@
     "seo-api"
   ],
   "dependencies": {
-    "mcpscraper-memory-sdk": "^0.27.2"
+    "mcpscraper-memory-sdk": "^0.28.0"
   },
   "devDependencies": {
     "openapi-typescript": "^7.13.0"