mcpscraper-sdk 0.54.1 → 0.55.0

package/README.md

@@ -41,7 +41,7 @@ Every non-2xx response throws a `ScraperApiError` with `status`, `code`, and the
 - `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.
 
-Google Search light mode returns organic positions, URLs, titles, and descriptions for 20 Credits per delivered SERP page, or 35 Credits when the backup supplies the result. One-page full mode adds available same-page SERP features for 35 Credits. Both modes default to one page; an unfiltered two-page search costs 40 Credits when the normal provider returns both pages. Past-week and past-month searches use a managed browser for organic results at 35 Credits per delivered page. Unfiltered light searches try the primary path twice, then one API fallback; an unfiltered one-page full search uses the feature-capable API directly. If page 2 cannot be delivered, an available page 1 is returned as partial and billed at the one-page rate. A 35-Credit-per-requested-page hold is settled after delivery. PAA costs 400 Credits plus 10 Credits per returned question. One optional concurrency pack adds two browser slots for $5/month; quantity `n` adds `2n` slots for `$5n` without changing the base plan.
+Google Search light mode returns organic positions, URLs, titles, and descriptions for 20 Credits per delivered SERP page, or 35 Credits when the backup supplies the result. One-page full mode adds available same-page SERP features for 35 Credits. Both modes default to one page; an unfiltered two-page search costs 40 Credits when the normal provider returns both pages. Past-week and past-month searches return one page of organic results at 35 Credits; omit the date filter when requesting two pages. Unfiltered one-page light searches try the primary path twice, then one API fallback; an unfiltered one-page full search uses the feature-capable API directly. Date filters and saved search identities require one page. Combining either with two pages is rejected before acquisition or billing. Two-page searches return organic results without a backup provider. If page 2 cannot be delivered, an available page 1 is returned as partial and billed at the one-page rate. A 35-Credit-per-requested-page hold is settled after delivery. PAA costs 400 Credits plus 10 Credits per returned question. 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
 
@@ -193,10 +193,16 @@ npm run verify:rest-contract
 
 Durable PAA harvests should wait at least 20 seconds between status checks and honor a longer returned polling interval. Keep the same job ID and retry key while the original work is running.
 
-Release changes: [SDK 0.54.1 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.54.1).
+Release changes: [SDK 0.55.0 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.55.0).
 
 ## Client attribution and full results
 
 Clients accept `clientAttribution: { installChannel?, aiClient?, aiModel? }` and default to calling surface `sdk`. Set only known caller labels; unspecified labels stay unknown. `onResponse({ requestId, status })` receives per-response correlation without changing results, and errors keep their own `requestId`. These options also apply to `McpToolsClient` and `MemoryClient`; labels are reporting declarations, not authorization.
 
 Large tool outputs may be delivery envelopes instead of inline domain values. Preserve `delivery`, `scope` and `recovery`, then use `tools.artifacts.describe`, `readRetained` (follow `nextOffset` to null), or `download` with the returned artifact ID. The legacy `artifacts.read` method remains the report reader. `callToolResult` preserves native content/resource links. Download URL expiry differs from artifact retention; renew a URL through `download` without rerunning acquisition. Use the returned capability for binary files.
+
+Artifact delivery may include optional `delivery.availableExports` handles. Use the
+export artifact ID with `artifact_download`, `artifact_read` or `artifact_describe`
+to generate Markdown from retained JSON without repeating acquisition. The
+[on-demand export example](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/v0.55.0/examples/serp-on-demand-export.mjs)
+shows the complete flow and preserves a retry key for uncertain search responses.

package/dist/index.d.cts

@@ -46,7 +46,10 @@ interface paths {
          *     positions, URLs, titles, and descriptions for 20 Credits per delivered
          *     page, or 35 Credits when the backup supplies the result. Full mode adds
          *     available same-page SERP features for 35 Credits per delivered page.
-         *     Both modes default to one page; set `pages: 2` explicitly for two.
+         *     Both modes default to one page; set `pages: 2` explicitly for two unfiltered
+         *     organic pages without a backup provider. With `serpOnly: true`, `recency: week` or `month` returns
+         *     one page for 35 Credits. Combining recency with two pages is rejected
+         *     before acquisition or billing.
          *     A 35-Credit-per-requested-page hold is settled after delivery.
          *     Omit or set `false` for a full People-Also-Ask harvest, which also returns SERP data
          *     (400 Credit base + 10 Credits per question actually returned; unused estimate is
@@ -1257,7 +1260,7 @@ interface components {
             /** @description Optional US ZIP override. */
             proxyZip?: string;
             /**
-             * @description Google result pages to fetch. Full mode alone does not request page 2.
+             * @description Google result pages to fetch. Full mode alone does not request page 2. For serpOnly searches, two pages require an omitted recency filter.
              * @default 1
              */
             pages: number;
@@ -1273,7 +1276,7 @@ interface components {
              */
             serpOnly: boolean;
             /**
-             * @description Optional Google time filter. Ordinary search_serp accepts week or month and returns organic browser results; PAA harvest also accepts day and year. Omit for all-time results.
+             * @description Optional Google time filter. Ordinary search_serp accepts week or month for one page of organic results at 35 Credits; combining recency with pages 2 is rejected before acquisition or billing. PAA harvest also accepts day and year. Omit for all-time results.
              * @enum {string}
              */
             recency?: "day" | "week" | "month" | "year";

package/dist/index.d.ts

@@ -46,7 +46,10 @@ interface paths {
          *     positions, URLs, titles, and descriptions for 20 Credits per delivered
          *     page, or 35 Credits when the backup supplies the result. Full mode adds
          *     available same-page SERP features for 35 Credits per delivered page.
-         *     Both modes default to one page; set `pages: 2` explicitly for two.
+         *     Both modes default to one page; set `pages: 2` explicitly for two unfiltered
+         *     organic pages without a backup provider. With `serpOnly: true`, `recency: week` or `month` returns
+         *     one page for 35 Credits. Combining recency with two pages is rejected
+         *     before acquisition or billing.
          *     A 35-Credit-per-requested-page hold is settled after delivery.
          *     Omit or set `false` for a full People-Also-Ask harvest, which also returns SERP data
          *     (400 Credit base + 10 Credits per question actually returned; unused estimate is
@@ -1257,7 +1260,7 @@ interface components {
             /** @description Optional US ZIP override. */
             proxyZip?: string;
             /**
-             * @description Google result pages to fetch. Full mode alone does not request page 2.
+             * @description Google result pages to fetch. Full mode alone does not request page 2. For serpOnly searches, two pages require an omitted recency filter.
              * @default 1
              */
             pages: number;
@@ -1273,7 +1276,7 @@ interface components {
              */
             serpOnly: boolean;
             /**
-             * @description Optional Google time filter. Ordinary search_serp accepts week or month and returns organic browser results; PAA harvest also accepts day and year. Omit for all-time results.
+             * @description Optional Google time filter. Ordinary search_serp accepts week or month for one page of organic results at 35 Credits; combining recency with pages 2 is rejected before acquisition or billing. PAA harvest also accepts day and year. Omit for all-time results.
              * @enum {string}
              */
             recency?: "day" | "week" | "month" | "year";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpscraper-sdk",
-  "version": "0.54.1",
+  "version": "0.55.0",
   "description": "Official Node.js client for all 347 mcpscraper.dev MCP tools and the REST API",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
     "seo-api"
   ],
   "dependencies": {
-    "mcpscraper-memory-sdk": "^0.53.1"
+    "mcpscraper-memory-sdk": "^0.54.0"
   },
   "devDependencies": {
     "openapi-typescript": "^7.13.0"