mcpscraper-sdk 0.12.2 → 0.12.4

package/README.md

@@ -62,6 +62,22 @@ Core operations are flat on the client: `searchSerp`, `harvestPaa`, `extractUrl`
 
 Everything else is namespaced by product area, matching the OpenAPI spec's tags: `client.youtube`, `client.screenshot`, `client.facebook`, `client.googleAds`, `client.instagram`, `client.reddit`, `client.video`, `client.maps`, `client.directory`, `client.serpIntelligence`, `client.workflows`.
 
+### Retry-safe SERP Intelligence captures
+
+Pass a stable idempotency key when a capture may be retried. The regular method continues to return the response body; `captureWithReceipt` also returns the key accepted or generated by the server so it can be reused after a timeout or uncertain response:
+
+```ts
+const result = await client.serpIntelligence.capture(
+  { query: 'roofers near me' },
+  { idempotencyKey: 'serp-run-2026-07-14-001' },
+)
+
+const receipt = await client.serpIntelligence.captureWithReceipt({ query: 'roofers near me' })
+console.log(receipt.data.billing.creditsUsed, receipt.idempotencyKey)
+```
+
+Reusing a key with the same body recovers the original debit and settlement. Reusing it with a different body throws `ScraperApiError` with status `409` and code `idempotency_conflict`.
+
 ## Scrape → memory vault
 
 `extractUrl` accepts `depositToVault: true` (optionally with `vaultName`) to embed the full scraped body server-side into your mcp-memory vault instead of returning it inline — the response's `memory` field reports `{ deposited, vault, noteId, path, chunks }` (or falls back to a temporary `fileUrl` download if the vault deposit itself fails):

package/dist/index.cjs

@@ -71,18 +71,22 @@ var Requester = class {
   apiKey;
   baseUrl;
   fetchImpl;
-  async call(method, path, body) {
+  async call(method, path, body, extraHeaders = {}) {
+    return (await this.callWithReceipt(method, path, body, extraHeaders)).data;
+  }
+  async callWithReceipt(method, path, body, extraHeaders = {}) {
     const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
       method,
       headers: {
         "x-api-key": this.apiKey,
-        ...body !== void 0 ? { "content-type": "application/json" } : {}
+        ...body !== void 0 ? { "content-type": "application/json" } : {},
+        ...extraHeaders
       },
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
     const data = await res.json().catch(() => void 0);
     if (!res.ok) throw new ScraperApiError(res.status, data);
-    return data;
+    return { data, headers: res.headers };
   }
   async callRaw(method, path) {
     const res = await this.fetchImpl(`${this.baseUrl}${path}`, { method, headers: { "x-api-key": this.apiKey } });
@@ -212,8 +216,25 @@ var SerpIntelligenceNamespace = class {
     this.r = r;
   }
   r;
-  capture(params) {
-    return this.r.call("POST", "/serp-intelligence/capture", params);
+  capture(params, options = {}) {
+    return this.r.call(
+      "POST",
+      "/serp-intelligence/capture",
+      params,
+      options.idempotencyKey === void 0 ? {} : { "Idempotency-Key": options.idempotencyKey }
+    );
+  }
+  async captureWithReceipt(params, options = {}) {
+    const result = await this.r.callWithReceipt(
+      "POST",
+      "/serp-intelligence/capture",
+      params,
+      options.idempotencyKey === void 0 ? {} : { "Idempotency-Key": options.idempotencyKey }
+    );
+    return {
+      data: result.data,
+      idempotencyKey: result.headers.get("Idempotency-Key")
+    };
   }
   pageSnapshots(params) {
     return this.r.call("POST", "/serp-intelligence/page-snapshots", params);

package/dist/index.d.cts

@@ -17,8 +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 (1 credit). Omit or
-         *     set `false` for a full People-Also-Ask harvest, which also returns SERP data
+         * @description Set `serpOnly: true` for a pure organic-results/SERP call (4 credits, headless —
+         *     14 credits if an anti-bot escalation forces a headful retry; overestimate refunded).
+         *     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
          *     refunded). Runs synchronously and returns the result inline.
          */
@@ -591,7 +592,11 @@ interface paths {
         put?: never;
         /**
          * Structured SERP capture with AI Overview/AI Mode detection, entity IDs, and location-match evidence
-         * @description Costs 1 credit. Rate-limited to 60 requests/minute per account.
+         * @description Holds 14 credits for the SERP and settles to 4 credits when the capture is served
+         *     headless, or retains 14 credits when anti-bot escalation requires headful mode.
+         *     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.
          */
         post: operations["serpIntelligenceCapture"];
         delete?: never;
@@ -1259,16 +1264,29 @@ interface components {
             pages: number;
             /** @default false */
             debug: boolean;
-            /** @default false */
+            /**
+             * @description Also attempt ranking-page snapshots at 1 credit per URL.
+             * @default false
+             */
             includePageSnapshots: boolean;
-            /** @default 0 */
+            /**
+             * @description Maximum snapshot attempts; capacity is held up front and unused capacity is refunded.
+             * @default 0
+             */
             pageSnapshotLimit: number;
         };
         SerpIntelligencePageSnapshotsRequest: {
             urls: string[];
-            targets?: {
+            /** @default 2 */
+            maxConcurrency: number;
+            /** @default 15000 */
+            timeoutMs: number;
+            /** @default false */
+            debug: boolean;
+        } | {
+            targets: {
                 /** Format: uri */
-                url?: string;
+                url: string;
                 /**
                  * @default configured_target
                  * @enum {string}
@@ -1399,10 +1417,8 @@ interface components {
                 [key: string]: unknown;
             } | null;
             pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
-            billing?: {
-                creditsUsed?: number;
-                requestId?: string;
-                jobId?: string;
+            billing: {
+                creditsUsed: number;
             };
         };
         SerpIntelligencePageSnapshotsResponse: {
@@ -2702,7 +2718,15 @@ interface operations {
     serpIntelligenceCapture: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /**
+                 * @description Stable retry key for this capture. Reusing the same key with the same
+                 *     request body recovers the original debit and settlement; reusing it with
+                 *     a different body returns `409 idempotency_conflict`. When omitted, the
+                 *     server generates a key and returns it in the response header.
+                 */
+                "Idempotency-Key"?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -2715,6 +2739,8 @@ interface operations {
             /** @description Structured SERP capture. */
             200: {
                 headers: {
+                    /** @description Retry key accepted from the request or generated by the server. */
+                    "Idempotency-Key"?: string;
                     [name: string]: unknown;
                 };
                 content: {
@@ -2723,6 +2749,17 @@ interface operations {
             };
             400: components["responses"]["StructuredBadRequest"];
             402: components["responses"]["InsufficientBalance"];
+            /** @description The Idempotency-Key was already used with a different request body. */
+            409: {
+                headers: {
+                    /** @description The conflicting retry key. */
+                    "Idempotency-Key"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StructuredError"];
+                };
+            };
             429: components["responses"]["StructuredRateLimited"];
             500: components["responses"]["StructuredCaptureFailed"];
         };
@@ -3156,12 +3193,25 @@ interface ScraperClientOptions {
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
 }
+type SerpIntelligenceCaptureDefaultedKey = 'gl' | 'hl' | 'device' | 'proxyMode' | 'pages' | 'debug' | 'includePageSnapshots' | 'pageSnapshotLimit';
+type SerpIntelligenceCaptureParams = Omit<RequestBodyOf<'serpIntelligenceCapture'>, SerpIntelligenceCaptureDefaultedKey> & Partial<Pick<RequestBodyOf<'serpIntelligenceCapture'>, SerpIntelligenceCaptureDefaultedKey>>;
+interface SerpIntelligenceCaptureOptions {
+    idempotencyKey?: string;
+}
+interface SerpIntelligenceCaptureReceipt {
+    data: SuccessBodyOf<'serpIntelligenceCapture'>;
+    idempotencyKey: string | null;
+}
 declare class Requester {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetchImpl;
     constructor(apiKey: string, baseUrl: string, fetchImpl: typeof globalThis.fetch);
-    call<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>): Promise<SuccessBodyOf<K>>;
+    call<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>, extraHeaders?: Record<string, string>): Promise<SuccessBodyOf<K>>;
+    callWithReceipt<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>, extraHeaders?: Record<string, string>): Promise<{
+        data: SuccessBodyOf<K>;
+        headers: Headers;
+    }>;
     callRaw(method: string, path: string): Promise<ArrayBuffer>;
 }
 declare class YoutubeNamespace {
@@ -3330,19 +3380,18 @@ declare class DirectoryNamespace {
 declare class SerpIntelligenceNamespace {
     private readonly r;
     constructor(r: Requester);
-    capture(params: RequestBodyOf<'serpIntelligenceCapture'>): Promise<{
+    capture(params: SerpIntelligenceCaptureParams, options?: SerpIntelligenceCaptureOptions): Promise<{
         harvestResult?: components["schemas"]["SerpIntelligenceHarvestResult"];
         attempts?: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
         locationEvidence?: {
             [key: string]: unknown;
         } | null;
         pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
-        billing?: {
-            creditsUsed?: number;
-            requestId?: string;
-            jobId?: string;
+        billing: {
+            creditsUsed: number;
         };
     }>;
+    captureWithReceipt(params: SerpIntelligenceCaptureParams, options?: SerpIntelligenceCaptureOptions): Promise<SerpIntelligenceCaptureReceipt>;
     pageSnapshots(params: RequestBodyOf<'serpIntelligencePageSnapshots'>): Promise<{
         pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
         attempts?: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
@@ -3749,4 +3798,4 @@ declare class ScraperApiError extends Error {
     };
 }
 
-export { type ConcurrencyLimitBody, type InsufficientBalanceBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type StructuredErrorBody, type components, type operations, type paths };
+export { type ConcurrencyLimitBody, type InsufficientBalanceBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };

package/dist/index.d.ts

@@ -17,8 +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 (1 credit). Omit or
-         *     set `false` for a full People-Also-Ask harvest, which also returns SERP data
+         * @description Set `serpOnly: true` for a pure organic-results/SERP call (4 credits, headless —
+         *     14 credits if an anti-bot escalation forces a headful retry; overestimate refunded).
+         *     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
          *     refunded). Runs synchronously and returns the result inline.
          */
@@ -591,7 +592,11 @@ interface paths {
         put?: never;
         /**
          * Structured SERP capture with AI Overview/AI Mode detection, entity IDs, and location-match evidence
-         * @description Costs 1 credit. Rate-limited to 60 requests/minute per account.
+         * @description Holds 14 credits for the SERP and settles to 4 credits when the capture is served
+         *     headless, or retains 14 credits when anti-bot escalation requires headful mode.
+         *     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.
          */
         post: operations["serpIntelligenceCapture"];
         delete?: never;
@@ -1259,16 +1264,29 @@ interface components {
             pages: number;
             /** @default false */
             debug: boolean;
-            /** @default false */
+            /**
+             * @description Also attempt ranking-page snapshots at 1 credit per URL.
+             * @default false
+             */
             includePageSnapshots: boolean;
-            /** @default 0 */
+            /**
+             * @description Maximum snapshot attempts; capacity is held up front and unused capacity is refunded.
+             * @default 0
+             */
             pageSnapshotLimit: number;
         };
         SerpIntelligencePageSnapshotsRequest: {
             urls: string[];
-            targets?: {
+            /** @default 2 */
+            maxConcurrency: number;
+            /** @default 15000 */
+            timeoutMs: number;
+            /** @default false */
+            debug: boolean;
+        } | {
+            targets: {
                 /** Format: uri */
-                url?: string;
+                url: string;
                 /**
                  * @default configured_target
                  * @enum {string}
@@ -1399,10 +1417,8 @@ interface components {
                 [key: string]: unknown;
             } | null;
             pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
-            billing?: {
-                creditsUsed?: number;
-                requestId?: string;
-                jobId?: string;
+            billing: {
+                creditsUsed: number;
             };
         };
         SerpIntelligencePageSnapshotsResponse: {
@@ -2702,7 +2718,15 @@ interface operations {
     serpIntelligenceCapture: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /**
+                 * @description Stable retry key for this capture. Reusing the same key with the same
+                 *     request body recovers the original debit and settlement; reusing it with
+                 *     a different body returns `409 idempotency_conflict`. When omitted, the
+                 *     server generates a key and returns it in the response header.
+                 */
+                "Idempotency-Key"?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -2715,6 +2739,8 @@ interface operations {
             /** @description Structured SERP capture. */
             200: {
                 headers: {
+                    /** @description Retry key accepted from the request or generated by the server. */
+                    "Idempotency-Key"?: string;
                     [name: string]: unknown;
                 };
                 content: {
@@ -2723,6 +2749,17 @@ interface operations {
             };
             400: components["responses"]["StructuredBadRequest"];
             402: components["responses"]["InsufficientBalance"];
+            /** @description The Idempotency-Key was already used with a different request body. */
+            409: {
+                headers: {
+                    /** @description The conflicting retry key. */
+                    "Idempotency-Key"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StructuredError"];
+                };
+            };
             429: components["responses"]["StructuredRateLimited"];
             500: components["responses"]["StructuredCaptureFailed"];
         };
@@ -3156,12 +3193,25 @@ interface ScraperClientOptions {
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
 }
+type SerpIntelligenceCaptureDefaultedKey = 'gl' | 'hl' | 'device' | 'proxyMode' | 'pages' | 'debug' | 'includePageSnapshots' | 'pageSnapshotLimit';
+type SerpIntelligenceCaptureParams = Omit<RequestBodyOf<'serpIntelligenceCapture'>, SerpIntelligenceCaptureDefaultedKey> & Partial<Pick<RequestBodyOf<'serpIntelligenceCapture'>, SerpIntelligenceCaptureDefaultedKey>>;
+interface SerpIntelligenceCaptureOptions {
+    idempotencyKey?: string;
+}
+interface SerpIntelligenceCaptureReceipt {
+    data: SuccessBodyOf<'serpIntelligenceCapture'>;
+    idempotencyKey: string | null;
+}
 declare class Requester {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetchImpl;
     constructor(apiKey: string, baseUrl: string, fetchImpl: typeof globalThis.fetch);
-    call<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>): Promise<SuccessBodyOf<K>>;
+    call<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>, extraHeaders?: Record<string, string>): Promise<SuccessBodyOf<K>>;
+    callWithReceipt<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>, extraHeaders?: Record<string, string>): Promise<{
+        data: SuccessBodyOf<K>;
+        headers: Headers;
+    }>;
     callRaw(method: string, path: string): Promise<ArrayBuffer>;
 }
 declare class YoutubeNamespace {
@@ -3330,19 +3380,18 @@ declare class DirectoryNamespace {
 declare class SerpIntelligenceNamespace {
     private readonly r;
     constructor(r: Requester);
-    capture(params: RequestBodyOf<'serpIntelligenceCapture'>): Promise<{
+    capture(params: SerpIntelligenceCaptureParams, options?: SerpIntelligenceCaptureOptions): Promise<{
         harvestResult?: components["schemas"]["SerpIntelligenceHarvestResult"];
         attempts?: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
         locationEvidence?: {
             [key: string]: unknown;
         } | null;
         pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
-        billing?: {
-            creditsUsed?: number;
-            requestId?: string;
-            jobId?: string;
+        billing: {
+            creditsUsed: number;
         };
     }>;
+    captureWithReceipt(params: SerpIntelligenceCaptureParams, options?: SerpIntelligenceCaptureOptions): Promise<SerpIntelligenceCaptureReceipt>;
     pageSnapshots(params: RequestBodyOf<'serpIntelligencePageSnapshots'>): Promise<{
         pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
         attempts?: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
@@ -3749,4 +3798,4 @@ declare class ScraperApiError extends Error {
     };
 }
 
-export { type ConcurrencyLimitBody, type InsufficientBalanceBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type StructuredErrorBody, type components, type operations, type paths };
+export { type ConcurrencyLimitBody, type InsufficientBalanceBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };

package/dist/index.js

@@ -56,18 +56,22 @@ var Requester = class {
   apiKey;
   baseUrl;
   fetchImpl;
-  async call(method, path, body) {
+  async call(method, path, body, extraHeaders = {}) {
+    return (await this.callWithReceipt(method, path, body, extraHeaders)).data;
+  }
+  async callWithReceipt(method, path, body, extraHeaders = {}) {
     const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
       method,
       headers: {
         "x-api-key": this.apiKey,
-        ...body !== void 0 ? { "content-type": "application/json" } : {}
+        ...body !== void 0 ? { "content-type": "application/json" } : {},
+        ...extraHeaders
       },
       body: body !== void 0 ? JSON.stringify(body) : void 0
     });
     const data = await res.json().catch(() => void 0);
     if (!res.ok) throw new ScraperApiError(res.status, data);
-    return data;
+    return { data, headers: res.headers };
   }
   async callRaw(method, path) {
     const res = await this.fetchImpl(`${this.baseUrl}${path}`, { method, headers: { "x-api-key": this.apiKey } });
@@ -197,8 +201,25 @@ var SerpIntelligenceNamespace = class {
     this.r = r;
   }
   r;
-  capture(params) {
-    return this.r.call("POST", "/serp-intelligence/capture", params);
+  capture(params, options = {}) {
+    return this.r.call(
+      "POST",
+      "/serp-intelligence/capture",
+      params,
+      options.idempotencyKey === void 0 ? {} : { "Idempotency-Key": options.idempotencyKey }
+    );
+  }
+  async captureWithReceipt(params, options = {}) {
+    const result = await this.r.callWithReceipt(
+      "POST",
+      "/serp-intelligence/capture",
+      params,
+      options.idempotencyKey === void 0 ? {} : { "Idempotency-Key": options.idempotencyKey }
+    );
+    return {
+      data: result.data,
+      idempotencyKey: result.headers.get("Idempotency-Key")
+    };
   }
   pageSnapshots(params) {
     return this.r.call("POST", "/serp-intelligence/page-snapshots", params);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpscraper-sdk",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "Official Node.js client for all 159 mcpscraper.dev MCP tools and the REST API",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "seo-api"
   ],
   "dependencies": {
-    "mcpscraper-memory-sdk": "^0.11.3"
+    "mcpscraper-memory-sdk": "^0.11.4"
   },
   "devDependencies": {
     "openapi-typescript": "^7.13.0"