mcpscraper-sdk 0.55.0 → 0.56.0

package/README.md

@@ -193,7 +193,7 @@ 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.55.0 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.55.0).
+Release changes: [SDK 0.56.0 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.56.0).
 
 ## Client attribution and full results
 
@@ -206,3 +206,23 @@ export artifact ID with `artifact_download`, `artifact_read` or `artifact_descri
 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.
+
+## Reddit discovery and known threads
+
+Use `reddit_trending` with `window:"year"` to discover past-year search candidates and
+select relevant threads before collecting comments. Set `maxThreads` to bound the
+number selected and `maxCommentsPerThread:20` for a per-thread capture limit.
+Twenty is a request limit; inspect returned coverage because fewer accessible text
+comments can produce a partial result. Publication dates are optional when unknown.
+
+Pass a known Reddit thread URL directly to `reddit_thread` with `maxComments:20`;
+it does not require a discovery call first. Trending returns ranked summaries and
+questions; the thread tool returns full comment bodies. Preserve each operation's
+retry key and exact inputs after an uncertain response.
+
+The [past-year and direct-thread example](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/v0.56.0/examples/reddit-past-year.mjs)
+shows both paths.
+
+## Saved Maps reviews
+
+Server 0.100.1 improves Maps discovery, review text and list collection through the existing interfaces. Use the exact name and location returned by discovery. Read the saved run and its review pages before considering a new acquisition. An explicit resume uses a fresh browser and reopens the profile and reviews; it retains saved review IDs. A new resume key authorizes a separately billed attempt, while repeating that key reads the same run.

package/dist/index.d.cts

@@ -562,7 +562,7 @@ interface paths {
         put?: never;
         /**
          * Capture a Reddit post and its comment tree
-         * @description Costs 30 credits for the thread plus 2 credits per comment actually returned. Refunded automatically if Reddit blocks the request after retries.
+         * @description Opens a known Reddit thread directly without a discovery search. Costs 30 credits for the thread plus 2 credits per comment actually returned. Refunded automatically if Reddit blocks the request after retries.
          */
         post: operations["redditThread"];
         delete?: never;
@@ -582,13 +582,14 @@ interface paths {
         put?: never;
         /**
          * Discover and rank the top recent Reddit threads for a topic
-         * @description Finds relevant recent Reddit threads via a Google site:reddit.com search over a week/month window,
-         *     then (by default) scrapes them all in parallel for real upvotes, comments, and the questions people
-         *     asked, and ranks by engagement (upvotes + 2x comments). Billing: one discovery debit plus, when
-         *     includeComments is true, 30 credits per scraped thread and 2 credits per captured comment, each
-         *     refunded on failure. Set includeComments:false for a cheap discovery-only sweep (thread list, no
-         *     engagement stats, no per-thread billing). Scraping respects a soft deadline and returns partial:true
-         *     if it stops early rather than exceeding the request limit.
+         * @description Discovers Reddit threads through a Google site:reddit.com search and selects relevant candidates
+         *     before scraping. Supports week, month, year and all-time windows. Scraped post dates are checked
+         *     against the requested publication window; discovery-only candidate dates remain unverified.
+         *     With includeComments:true, collects selected threads and ranks by engagement (upvotes + 2x
+         *     reported comments). Billing: one discovery debit plus 30 credits per scraped thread and 2 credits
+         *     per captured comment, each refunded on failure. Set includeComments:false for a candidate list
+         *     without per-thread billing. Comment coverage distinguishes the requested limit, returned text
+         *     comments and reported comment count. A bounded capture can return partial:true.
          */
         post: operations["redditTrending"];
         delete?: never;
@@ -2366,6 +2367,108 @@ interface components {
         } & {
             [key: string]: unknown;
         };
+        RedditThreadRequest: {
+            /** @description A known Reddit thread URL to open directly without searching; legacy Reddit hostnames are normalized to the current page. */
+            url: string;
+            maxComments?: number;
+        };
+        RedditThreadResponse: {
+            title?: string;
+            author?: string | null;
+            score?: string | null;
+            postBody?: string;
+            /**
+             * Format: date-time
+             * @description Observed publication timestamp when available.
+             */
+            publishedAt?: string | null;
+            numComments?: number;
+            comments?: {
+                author?: string | null;
+                score?: string;
+                depth?: number;
+                body?: string;
+            }[];
+            sourceUrl?: string;
+        };
+        RedditTrendingRequest: {
+            /** @description Topic in plain words, e.g. "crm for small business". Not a URL. */
+            topic: string;
+            /** @description Bare subreddit name to scope the scan, e.g. "SEO" (no r/ prefix). Omit to scan all of Reddit. */
+            subreddit?: string;
+            /**
+             * @description Publication window; scraped threads are checked against their actual post dates, while discovery-only dates remain unverified.
+             * @default month
+             * @enum {string}
+             */
+            window: "week" | "month" | "year" | "all";
+            /**
+             * @description Cap on relevant threads selected before scraping; one search page can yield fewer. Each scraped thread and its returned comments are billed separately.
+             * @default 20
+             */
+            maxThreads: number;
+            /**
+             * @description Open selected threads to verify post dates and collect comments; false returns search candidates for your own selection, without per-thread charges or verified post dates.
+             * @default true
+             */
+            includeComments: boolean;
+            /**
+             * @description Comments captured (and billed) per scraped thread when includeComments is true.
+             * @default 50
+             */
+            maxCommentsPerThread: number;
+        };
+        RedditTrendingResponse: {
+            topic?: string;
+            subreddit?: string | null;
+            /** @description Resolved publication window: "7d", "30d", "365d" or "all". */
+            window?: string;
+            totals?: {
+                threads?: number;
+                upvotes?: number;
+                comments?: number;
+            };
+            rankedThreads?: {
+                title?: string;
+                url?: string;
+                subreddit?: string;
+                score?: number;
+                commentCount?: number;
+                engagementScore?: number;
+                ageText?: string;
+                /**
+                 * Format: date-time
+                 * @description Observed publication timestamp when available.
+                 */
+                publishedAt?: string | null;
+                /** @description Text comments actually returned for this thread. */
+                capturedCommentCount?: number;
+                /** @description Requested per-thread comment cap. */
+                requestedCommentLimit?: number;
+                commentCoverage?: {
+                    requestedLimit: number;
+                    returnedCount: number;
+                    declaredCount: number;
+                    status: components["schemas"]["RedditCommentCoverageStatus"];
+                    reason: components["schemas"]["RedditCommentCoverageReason"];
+                };
+                topQuestions?: string[];
+            }[];
+            questions?: {
+                question?: string;
+                threadUrl?: string;
+            }[];
+            threadsScraped?: number;
+            candidatesFound?: number;
+            /** @description true if scraping stopped early at the time limit. */
+            partial?: boolean;
+            /** @description The Google site:reddit.com query used for discovery. */
+            searchQuery?: string;
+        };
+        /** @enum {string} */
+        RedditCommentCoverageStatus: "complete" | "partial";
+        /** @enum {string} */
+        RedditCommentCoverageReason: "requested_limit_reached" | "declared_count_reached" | "stable_visible_shortfall" | "capture_shortfall" | "funding_limited";
         MapsSearchRequest: {
             query: string;
             location?: string;
@@ -3591,11 +3694,7 @@ interface operations {
         };
         requestBody: {
             content: {
-                "application/json": {
-                    /** @description A reddit.com or redd.it thread URL. */
-                    url: string;
-                    maxComments?: number;
-                };
+                "application/json": components["schemas"]["RedditThreadRequest"];
             };
         };
         responses: {
@@ -3605,20 +3704,7 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        title?: string;
-                        author?: string | null;
-                        score?: string | null;
-                        postBody?: string;
-                        numComments?: number;
-                        comments?: {
-                            author?: string | null;
-                            score?: string;
-                            depth?: number;
-                            body?: string;
-                        }[];
-                        sourceUrl?: string;
-                    };
+                    "application/json": components["schemas"]["RedditThreadResponse"];
                 };
             };
             400: components["responses"]["BadRequest"];
@@ -3643,33 +3729,7 @@ interface operations {
         };
         requestBody: {
             content: {
-                "application/json": {
-                    /** @description Topic in plain words, e.g. "crm for small business". Not a URL. */
-                    topic: string;
-                    /** @description Bare subreddit name to scope the scan, e.g. "SEO" (no r/ prefix). Omit to scan all of Reddit. */
-                    subreddit?: string;
-                    /**
-                     * @description How recent the threads must be.
-                     * @default month
-                     * @enum {string}
-                     */
-                    window?: "week" | "month";
-                    /**
-                     * @description How many discovered threads to scrape and rank (scrape-all default). Lower to cap cost.
-                     * @default 20
-                     */
-                    maxThreads?: number;
-                    /**
-                     * @description true = scrape each thread for engagement + questions and rank; false = cheap discovery-only list.
-                     * @default true
-                     */
-                    includeComments?: boolean;
-                    /**
-                     * @description Comments captured (and billed) per scraped thread when includeComments is true.
-                     * @default 50
-                     */
-                    maxCommentsPerThread?: number;
-                };
+                "application/json": components["schemas"]["RedditTrendingRequest"];
             };
         };
         responses: {
@@ -3679,37 +3739,7 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        topic?: string;
-                        subreddit?: string | null;
-                        /** @description Resolved window, e.g. "7d" or "30d". */
-                        window?: string;
-                        totals?: {
-                            threads?: number;
-                            upvotes?: number;
-                            comments?: number;
-                        };
-                        rankedThreads?: {
-                            title?: string;
-                            url?: string;
-                            subreddit?: string;
-                            score?: number;
-                            commentCount?: number;
-                            engagementScore?: number;
-                            ageText?: string;
-                            topQuestions?: string[];
-                        }[];
-                        questions?: {
-                            question?: string;
-                            threadUrl?: string;
-                        }[];
-                        threadsScraped?: number;
-                        candidatesFound?: number;
-                        /** @description true if scraping stopped early at the time limit. */
-                        partial?: boolean;
-                        /** @description The Google site:reddit.com query used for discovery. */
-                        searchQuery?: string;
-                    };
+                    "application/json": components["schemas"]["RedditTrendingResponse"];
                 };
             };
             400: components["responses"]["BadRequest"];
@@ -4905,6 +4935,7 @@ declare class RedditNamespace {
         author?: string | null;
         score?: string | null;
         postBody?: string;
+        publishedAt?: string | null;
         numComments?: number;
         comments?: {
             author?: string | null;

package/dist/index.d.ts

@@ -562,7 +562,7 @@ interface paths {
         put?: never;
         /**
          * Capture a Reddit post and its comment tree
-         * @description Costs 30 credits for the thread plus 2 credits per comment actually returned. Refunded automatically if Reddit blocks the request after retries.
+         * @description Opens a known Reddit thread directly without a discovery search. Costs 30 credits for the thread plus 2 credits per comment actually returned. Refunded automatically if Reddit blocks the request after retries.
          */
         post: operations["redditThread"];
         delete?: never;
@@ -582,13 +582,14 @@ interface paths {
         put?: never;
         /**
          * Discover and rank the top recent Reddit threads for a topic
-         * @description Finds relevant recent Reddit threads via a Google site:reddit.com search over a week/month window,
-         *     then (by default) scrapes them all in parallel for real upvotes, comments, and the questions people
-         *     asked, and ranks by engagement (upvotes + 2x comments). Billing: one discovery debit plus, when
-         *     includeComments is true, 30 credits per scraped thread and 2 credits per captured comment, each
-         *     refunded on failure. Set includeComments:false for a cheap discovery-only sweep (thread list, no
-         *     engagement stats, no per-thread billing). Scraping respects a soft deadline and returns partial:true
-         *     if it stops early rather than exceeding the request limit.
+         * @description Discovers Reddit threads through a Google site:reddit.com search and selects relevant candidates
+         *     before scraping. Supports week, month, year and all-time windows. Scraped post dates are checked
+         *     against the requested publication window; discovery-only candidate dates remain unverified.
+         *     With includeComments:true, collects selected threads and ranks by engagement (upvotes + 2x
+         *     reported comments). Billing: one discovery debit plus 30 credits per scraped thread and 2 credits
+         *     per captured comment, each refunded on failure. Set includeComments:false for a candidate list
+         *     without per-thread billing. Comment coverage distinguishes the requested limit, returned text
+         *     comments and reported comment count. A bounded capture can return partial:true.
          */
         post: operations["redditTrending"];
         delete?: never;
@@ -2366,6 +2367,108 @@ interface components {
         } & {
             [key: string]: unknown;
         };
+        RedditThreadRequest: {
+            /** @description A known Reddit thread URL to open directly without searching; legacy Reddit hostnames are normalized to the current page. */
+            url: string;
+            maxComments?: number;
+        };
+        RedditThreadResponse: {
+            title?: string;
+            author?: string | null;
+            score?: string | null;
+            postBody?: string;
+            /**
+             * Format: date-time
+             * @description Observed publication timestamp when available.
+             */
+            publishedAt?: string | null;
+            numComments?: number;
+            comments?: {
+                author?: string | null;
+                score?: string;
+                depth?: number;
+                body?: string;
+            }[];
+            sourceUrl?: string;
+        };
+        RedditTrendingRequest: {
+            /** @description Topic in plain words, e.g. "crm for small business". Not a URL. */
+            topic: string;
+            /** @description Bare subreddit name to scope the scan, e.g. "SEO" (no r/ prefix). Omit to scan all of Reddit. */
+            subreddit?: string;
+            /**
+             * @description Publication window; scraped threads are checked against their actual post dates, while discovery-only dates remain unverified.
+             * @default month
+             * @enum {string}
+             */
+            window: "week" | "month" | "year" | "all";
+            /**
+             * @description Cap on relevant threads selected before scraping; one search page can yield fewer. Each scraped thread and its returned comments are billed separately.
+             * @default 20
+             */
+            maxThreads: number;
+            /**
+             * @description Open selected threads to verify post dates and collect comments; false returns search candidates for your own selection, without per-thread charges or verified post dates.
+             * @default true
+             */
+            includeComments: boolean;
+            /**
+             * @description Comments captured (and billed) per scraped thread when includeComments is true.
+             * @default 50
+             */
+            maxCommentsPerThread: number;
+        };
+        RedditTrendingResponse: {
+            topic?: string;
+            subreddit?: string | null;
+            /** @description Resolved publication window: "7d", "30d", "365d" or "all". */
+            window?: string;
+            totals?: {
+                threads?: number;
+                upvotes?: number;
+                comments?: number;
+            };
+            rankedThreads?: {
+                title?: string;
+                url?: string;
+                subreddit?: string;
+                score?: number;
+                commentCount?: number;
+                engagementScore?: number;
+                ageText?: string;
+                /**
+                 * Format: date-time
+                 * @description Observed publication timestamp when available.
+                 */
+                publishedAt?: string | null;
+                /** @description Text comments actually returned for this thread. */
+                capturedCommentCount?: number;
+                /** @description Requested per-thread comment cap. */
+                requestedCommentLimit?: number;
+                commentCoverage?: {
+                    requestedLimit: number;
+                    returnedCount: number;
+                    declaredCount: number;
+                    status: components["schemas"]["RedditCommentCoverageStatus"];
+                    reason: components["schemas"]["RedditCommentCoverageReason"];
+                };
+                topQuestions?: string[];
+            }[];
+            questions?: {
+                question?: string;
+                threadUrl?: string;
+            }[];
+            threadsScraped?: number;
+            candidatesFound?: number;
+            /** @description true if scraping stopped early at the time limit. */
+            partial?: boolean;
+            /** @description The Google site:reddit.com query used for discovery. */
+            searchQuery?: string;
+        };
+        /** @enum {string} */
+        RedditCommentCoverageStatus: "complete" | "partial";
+        /** @enum {string} */
+        RedditCommentCoverageReason: "requested_limit_reached" | "declared_count_reached" | "stable_visible_shortfall" | "capture_shortfall" | "funding_limited";
         MapsSearchRequest: {
             query: string;
             location?: string;
@@ -3591,11 +3694,7 @@ interface operations {
         };
         requestBody: {
             content: {
-                "application/json": {
-                    /** @description A reddit.com or redd.it thread URL. */
-                    url: string;
-                    maxComments?: number;
-                };
+                "application/json": components["schemas"]["RedditThreadRequest"];
             };
         };
         responses: {
@@ -3605,20 +3704,7 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        title?: string;
-                        author?: string | null;
-                        score?: string | null;
-                        postBody?: string;
-                        numComments?: number;
-                        comments?: {
-                            author?: string | null;
-                            score?: string;
-                            depth?: number;
-                            body?: string;
-                        }[];
-                        sourceUrl?: string;
-                    };
+                    "application/json": components["schemas"]["RedditThreadResponse"];
                 };
             };
             400: components["responses"]["BadRequest"];
@@ -3643,33 +3729,7 @@ interface operations {
         };
         requestBody: {
             content: {
-                "application/json": {
-                    /** @description Topic in plain words, e.g. "crm for small business". Not a URL. */
-                    topic: string;
-                    /** @description Bare subreddit name to scope the scan, e.g. "SEO" (no r/ prefix). Omit to scan all of Reddit. */
-                    subreddit?: string;
-                    /**
-                     * @description How recent the threads must be.
-                     * @default month
-                     * @enum {string}
-                     */
-                    window?: "week" | "month";
-                    /**
-                     * @description How many discovered threads to scrape and rank (scrape-all default). Lower to cap cost.
-                     * @default 20
-                     */
-                    maxThreads?: number;
-                    /**
-                     * @description true = scrape each thread for engagement + questions and rank; false = cheap discovery-only list.
-                     * @default true
-                     */
-                    includeComments?: boolean;
-                    /**
-                     * @description Comments captured (and billed) per scraped thread when includeComments is true.
-                     * @default 50
-                     */
-                    maxCommentsPerThread?: number;
-                };
+                "application/json": components["schemas"]["RedditTrendingRequest"];
             };
         };
         responses: {
@@ -3679,37 +3739,7 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        topic?: string;
-                        subreddit?: string | null;
-                        /** @description Resolved window, e.g. "7d" or "30d". */
-                        window?: string;
-                        totals?: {
-                            threads?: number;
-                            upvotes?: number;
-                            comments?: number;
-                        };
-                        rankedThreads?: {
-                            title?: string;
-                            url?: string;
-                            subreddit?: string;
-                            score?: number;
-                            commentCount?: number;
-                            engagementScore?: number;
-                            ageText?: string;
-                            topQuestions?: string[];
-                        }[];
-                        questions?: {
-                            question?: string;
-                            threadUrl?: string;
-                        }[];
-                        threadsScraped?: number;
-                        candidatesFound?: number;
-                        /** @description true if scraping stopped early at the time limit. */
-                        partial?: boolean;
-                        /** @description The Google site:reddit.com query used for discovery. */
-                        searchQuery?: string;
-                    };
+                    "application/json": components["schemas"]["RedditTrendingResponse"];
                 };
             };
             400: components["responses"]["BadRequest"];
@@ -4905,6 +4935,7 @@ declare class RedditNamespace {
         author?: string | null;
         score?: string | null;
         postBody?: string;
+        publishedAt?: string | null;
         numComments?: number;
         comments?: {
             author?: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpscraper-sdk",
-  "version": "0.55.0",
+  "version": "0.56.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.54.0"
+    "mcpscraper-memory-sdk": "^0.55.0"
   },
   "devDependencies": {
     "openapi-typescript": "^7.13.0"