mcpscraper-sdk 0.55.0 → 0.57.0

package/README.md

@@ -2,7 +2,7 @@
 
 Official TypeScript/JavaScript client for the [mcpscraper.dev](https://mcpscraper.dev) REST API — SERP search, People-Also-Ask harvesting, single-page and whole-site extraction, YouTube, Facebook/Google Ads Transparency, Instagram, Reddit, video breakdown, Google Maps, and directory/rank-tracking workflows.
 
-[Release history](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/main/CHANGELOG.md)
+[Release history](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.57.0)
 
 This is a thin HTTP client generated against [`../../contracts/scraper.openapi.generated.json`](../../contracts/scraper.openapi.generated.json), the complete public REST contract for the hosted API. It contains no scraping, proxy, or billing logic — only typed request/response plumbing.
 
@@ -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,27 @@ 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.
+
+## Bug Reporting
+
+Use `bug_reporting` to prepare a redacted draft from observed calls and errors. Review the returned report, then submit its exact `reportId` and `reviewToken` only when the user requests submission. Status returns the private receipt. The support team receives the report and verified account email. Drafts expire after one day; submitted reports after 365 days. See [the complete workflow](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/v0.57.0/examples/bug-reporting.mjs) and [release history](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.57.0).

package/dist/index.cjs

@@ -673,6 +673,17 @@ var ScraperClient = class {
       options
     );
   }
+  async bugReporting(params, options = {}) {
+    try {
+      return await this.r.call("POST", "/bugs/report", params, {}, options);
+    } catch (error) {
+      if (error instanceof ScraperApiError && error.code === "mcp_request_timeout") {
+        const message = params.action === "prepare" || params.action === void 0 ? "Draft preparation was not confirmed. An unreturned draft expires after one day; prepare never submits a report." : "Submission was not confirmed. Read status with the same reportId, then retry submit with the same reportId and reviewToken if needed. Bug Reporting is free.";
+        throw new ScraperApiError(408, { error_code: "mcp_request_timeout", error_type: "timeout", message, retryable: true, charge_status: "not_charged" }, { requestId: error.requestId });
+      }
+      throw error;
+    }
+  }
   searchSerp(params, options = {}) {
     return this.r.call("POST", "/harvest/sync", { ...params, serpOnly: true }, {}, options);
   }

package/dist/index.d.cts

@@ -6,6 +6,26 @@ export { ArtifactDelivery, ClientAttribution, ClientMetadataOptions, DeliveredNa
  * Do not make direct changes to the file.
  */
 interface paths {
+    "/bugs/report": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Prepare, submit or read a private bug report
+         * @description Prepare a redacted one-day draft from observed evidence. Submit its exact reportId and reviewToken only at the user’s request. Submitted reports and verified account email are shared with private support for 365 days. Free; status and repeated submit are safe.
+         */
+        post: operations["bugReporting"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/harvest": {
         parameters: {
             query?: never;
@@ -562,7 +582,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 +602,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 +2387,260 @@ 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";
+        BugReportingRequest: {
+            /**
+             * @description prepare saves a private one-day draft for review; submit sends that exact draft to support; status reads your report receipt.
+             * @default prepare
+             * @enum {string}
+             */
+            action: "prepare" | "submit" | "status";
+            /** @description Required for prepare. Collect known evidence from the conversation before asking the user for missing details. */
+            report?: {
+                /** @description Short description of the problem in plain language. */
+                title: string;
+                /** @description What the user was trying to accomplish, using their words. */
+                goal: string;
+                /** @description What should have happened. */
+                expected: string;
+                /** @description What actually happened. Separate observations from suspected causes. */
+                actual: string;
+                /** @description Ordered reproduction steps, including retries and what changed. */
+                steps: string[];
+                /** @description Calls in the order made. Include successful calls that explain the failure. */
+                attempts: {
+                    /** @description Exact tool name or REST method and path. */
+                    tool: string;
+                    /**
+                     * Format: date-time
+                     * @description Observed call time with timezone; omit if unknown.
+                     */
+                    submittedAt?: string;
+                    /** @description Exact submitted arguments as JSON or text. Remove credentials, cookies and unrelated private content first. Do not reconstruct unknown arguments. */
+                    arguments: string;
+                    /** @description Observed response or error text, including error codes and retry outcome. Remove secrets. */
+                    result: string;
+                    /** @description Returned request ID, when available. */
+                    requestId?: string;
+                    /** @description Returned job or run ID, when available. */
+                    jobId?: string;
+                }[];
+                /** @description Observed client environment; use unknown rather than guessing. */
+                client: {
+                    /** @description Observed application or SDK name. */
+                    name: string;
+                    /** @description Observed application or package version; omit if unknown. */
+                    version?: string;
+                    /**
+                     * @description Connection or install route used for the failed calls.
+                     * @enum {string}
+                     */
+                    transport: "oauth" | "api-key" | "npx" | "npm" | "sdk" | "mcpb" | "rest" | "unknown";
+                    /** @description Observed operating system; omit if unknown. */
+                    operatingSystem?: string;
+                    /** @description Observed AI model; omit if unknown. */
+                    model?: string;
+                };
+                /** @description Impact, frequency, useful prior context, and suspected cause clearly labeled as a guess. No full conversation dump. */
+                context?: string;
+                /**
+                 * @description Evidence that is unknown or unavailable; do not invent it.
+                 * @default []
+                 */
+                missing: string[];
+            };
+            /**
+             * Format: uuid
+             * @description ID returned by prepare; required for submit or status.
+             */
+            reportId?: string;
+            /** @description Exact token returned by prepare; required for submit. A changed report requires a new prepare. */
+            reviewToken?: string;
+            /** @description Set true only when the user has asked to submit this bug or approved the reviewed draft. Repeated errors alone do not authorize submission. */
+            userApproved?: boolean;
+        };
+        BugReportingResponse: {
+            /** @enum {boolean} */
+            ok: true;
+            accountEmail: string;
+            /** Format: uuid */
+            reportId: string;
+            /** @enum {string} */
+            status: "draft" | "submitted";
+            receivedAt: string;
+            submittedAt: string | null;
+            expiresAt: string;
+            report: {
+                /** @description Short description of the problem in plain language. */
+                title: string;
+                /** @description What the user was trying to accomplish, using their words. */
+                goal: string;
+                /** @description What should have happened. */
+                expected: string;
+                /** @description What actually happened. Separate observations from suspected causes. */
+                actual: string;
+                /** @description Ordered reproduction steps, including retries and what changed. */
+                steps: string[];
+                /** @description Calls in the order made. Include successful calls that explain the failure. */
+                attempts: {
+                    /** @description Exact tool name or REST method and path. */
+                    tool: string;
+                    /**
+                     * Format: date-time
+                     * @description Observed call time with timezone; omit if unknown.
+                     */
+                    submittedAt?: string;
+                    /** @description Exact submitted arguments as JSON or text. Remove credentials, cookies and unrelated private content first. Do not reconstruct unknown arguments. */
+                    arguments: string;
+                    /** @description Observed response or error text, including error codes and retry outcome. Remove secrets. */
+                    result: string;
+                    /** @description Returned request ID, when available. */
+                    requestId?: string;
+                    /** @description Returned job or run ID, when available. */
+                    jobId?: string;
+                }[];
+                /** @description Observed client environment; use unknown rather than guessing. */
+                client: {
+                    /** @description Observed application or SDK name. */
+                    name: string;
+                    /** @description Observed application or package version; omit if unknown. */
+                    version?: string;
+                    /**
+                     * @description Connection or install route used for the failed calls.
+                     * @enum {string}
+                     */
+                    transport: "oauth" | "api-key" | "npx" | "npm" | "sdk" | "mcpb" | "rest" | "unknown";
+                    /** @description Observed operating system; omit if unknown. */
+                    operatingSystem?: string;
+                    /** @description Observed AI model; omit if unknown. */
+                    model?: string;
+                };
+                /** @description Impact, frequency, useful prior context, and suspected cause clearly labeled as a guess. No full conversation dump. */
+                context?: string;
+                /**
+                 * @description Evidence that is unknown or unavailable; do not invent it.
+                 * @default []
+                 */
+                missing: string[];
+            };
+            reviewToken?: string;
+            redacted: boolean;
+            message: string;
+        };
+        BugReportingError: {
+            error?: string;
+            /** @enum {string} */
+            error_code: "request_aborted" | "captcha_exhausted" | "captcha_or_blocked" | "location_mismatch" | "proxy_tunnel_failed" | "proxy_unavailable" | "harvest_timeout" | "mcp_request_timeout" | "mcp_http_error" | "extraction_failed" | "concurrency_limit_exceeded" | "unauthorized" | "forbidden" | "invalid_request" | "rate_limited" | "upstream_rate_limited" | "insufficient_balance" | "service_unavailable" | "response_lost" | "vendor_unavailable" | "page_not_found" | "page_forbidden" | "page_rate_limited" | "page_server_error" | "page_http_error" | "bot_check_unresolved" | "page_too_large" | "page_unreachable" | "browser_session_interrupted" | "site_export_not_found" | "directory_job_not_found" | "site_export_format_unavailable" | "site_export_read_failed" | "site_export_image_not_found" | "image_url_invalid" | "image_url_not_https" | "image_host_unresolvable" | "image_host_blocked" | "image_redirect_invalid" | "image_source_unavailable" | "image_too_large" | "image_redirect_limit" | "image_base64_invalid" | "image_source_missing" | "image_source_ambiguous" | "image_source_type_invalid" | "image_artifact_not_found" | "image_page_too_large" | "page_image_not_found" | "page_image_candidates_unusable" | "image_format_unsupported" | "image_storage_unconfigured" | "featured_image_unhostable";
+            /** @enum {string} */
+            error_type: "request_aborted" | "captcha" | "location_mismatch" | "connection" | "timeout" | "extraction" | "concurrency_limit" | "unauthorized" | "forbidden" | "invalid_request" | "not_found" | "rate_limit" | "billing" | "service_unavailable";
+            message: string;
+            retryable: boolean;
+            /** @enum {string} */
+            charge_status: "not_charged";
+        } & {
+            [key: string]: unknown;
+        };
         MapsSearchRequest: {
             query: string;
             location?: string;
@@ -2645,6 +2920,102 @@ interface components {
     pathItems: never;
 }
 interface operations {
+    bugReporting: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BugReportingRequest"];
+            };
+        };
+        responses: {
+            /** @description Prepare, submit or read a private bug report */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingResponse"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+        };
+    };
     startHarvest: {
         parameters: {
             query?: never;
@@ -3591,11 +3962,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 +3972,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 +3997,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 +4007,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 +5203,7 @@ declare class RedditNamespace {
         author?: string | null;
         score?: string | null;
         postBody?: string;
+        publishedAt?: string | null;
         numComments?: number;
         comments?: {
             author?: string | null;
@@ -5415,6 +5714,42 @@ declare class ScraperClient {
         job_id: string;
         status: "pending";
     }>;
+    bugReporting(params: RequestBodyOf<'bugReporting'>, options?: ScraperRequestOptions): Promise<{
+        ok: true;
+        accountEmail: string;
+        reportId: string;
+        status: "draft" | "submitted";
+        receivedAt: string;
+        submittedAt: string | null;
+        expiresAt: string;
+        report: {
+            title: string;
+            goal: string;
+            expected: string;
+            actual: string;
+            steps: string[];
+            attempts: {
+                tool: string;
+                submittedAt?: string;
+                arguments: string;
+                result: string;
+                requestId?: string;
+                jobId?: string;
+            }[];
+            client: {
+                name: string;
+                version?: string;
+                transport: "oauth" | "api-key" | "npx" | "npm" | "sdk" | "mcpb" | "rest" | "unknown";
+                operatingSystem?: string;
+                model?: string;
+            };
+            context?: string;
+            missing: string[];
+        };
+        reviewToken?: string;
+        redacted: boolean;
+        message: string;
+    }>;
     searchSerp(params: SearchSerpParams, options?: ScraperRequestOptions): Promise<{
         job_id: string;
         status: "done" | "cancelled" | "failed";

package/dist/index.d.ts

@@ -6,6 +6,26 @@ export { ArtifactDelivery, ClientAttribution, ClientMetadataOptions, DeliveredNa
  * Do not make direct changes to the file.
  */
 interface paths {
+    "/bugs/report": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Prepare, submit or read a private bug report
+         * @description Prepare a redacted one-day draft from observed evidence. Submit its exact reportId and reviewToken only at the user’s request. Submitted reports and verified account email are shared with private support for 365 days. Free; status and repeated submit are safe.
+         */
+        post: operations["bugReporting"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/harvest": {
         parameters: {
             query?: never;
@@ -562,7 +582,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 +602,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 +2387,260 @@ 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";
+        BugReportingRequest: {
+            /**
+             * @description prepare saves a private one-day draft for review; submit sends that exact draft to support; status reads your report receipt.
+             * @default prepare
+             * @enum {string}
+             */
+            action: "prepare" | "submit" | "status";
+            /** @description Required for prepare. Collect known evidence from the conversation before asking the user for missing details. */
+            report?: {
+                /** @description Short description of the problem in plain language. */
+                title: string;
+                /** @description What the user was trying to accomplish, using their words. */
+                goal: string;
+                /** @description What should have happened. */
+                expected: string;
+                /** @description What actually happened. Separate observations from suspected causes. */
+                actual: string;
+                /** @description Ordered reproduction steps, including retries and what changed. */
+                steps: string[];
+                /** @description Calls in the order made. Include successful calls that explain the failure. */
+                attempts: {
+                    /** @description Exact tool name or REST method and path. */
+                    tool: string;
+                    /**
+                     * Format: date-time
+                     * @description Observed call time with timezone; omit if unknown.
+                     */
+                    submittedAt?: string;
+                    /** @description Exact submitted arguments as JSON or text. Remove credentials, cookies and unrelated private content first. Do not reconstruct unknown arguments. */
+                    arguments: string;
+                    /** @description Observed response or error text, including error codes and retry outcome. Remove secrets. */
+                    result: string;
+                    /** @description Returned request ID, when available. */
+                    requestId?: string;
+                    /** @description Returned job or run ID, when available. */
+                    jobId?: string;
+                }[];
+                /** @description Observed client environment; use unknown rather than guessing. */
+                client: {
+                    /** @description Observed application or SDK name. */
+                    name: string;
+                    /** @description Observed application or package version; omit if unknown. */
+                    version?: string;
+                    /**
+                     * @description Connection or install route used for the failed calls.
+                     * @enum {string}
+                     */
+                    transport: "oauth" | "api-key" | "npx" | "npm" | "sdk" | "mcpb" | "rest" | "unknown";
+                    /** @description Observed operating system; omit if unknown. */
+                    operatingSystem?: string;
+                    /** @description Observed AI model; omit if unknown. */
+                    model?: string;
+                };
+                /** @description Impact, frequency, useful prior context, and suspected cause clearly labeled as a guess. No full conversation dump. */
+                context?: string;
+                /**
+                 * @description Evidence that is unknown or unavailable; do not invent it.
+                 * @default []
+                 */
+                missing: string[];
+            };
+            /**
+             * Format: uuid
+             * @description ID returned by prepare; required for submit or status.
+             */
+            reportId?: string;
+            /** @description Exact token returned by prepare; required for submit. A changed report requires a new prepare. */
+            reviewToken?: string;
+            /** @description Set true only when the user has asked to submit this bug or approved the reviewed draft. Repeated errors alone do not authorize submission. */
+            userApproved?: boolean;
+        };
+        BugReportingResponse: {
+            /** @enum {boolean} */
+            ok: true;
+            accountEmail: string;
+            /** Format: uuid */
+            reportId: string;
+            /** @enum {string} */
+            status: "draft" | "submitted";
+            receivedAt: string;
+            submittedAt: string | null;
+            expiresAt: string;
+            report: {
+                /** @description Short description of the problem in plain language. */
+                title: string;
+                /** @description What the user was trying to accomplish, using their words. */
+                goal: string;
+                /** @description What should have happened. */
+                expected: string;
+                /** @description What actually happened. Separate observations from suspected causes. */
+                actual: string;
+                /** @description Ordered reproduction steps, including retries and what changed. */
+                steps: string[];
+                /** @description Calls in the order made. Include successful calls that explain the failure. */
+                attempts: {
+                    /** @description Exact tool name or REST method and path. */
+                    tool: string;
+                    /**
+                     * Format: date-time
+                     * @description Observed call time with timezone; omit if unknown.
+                     */
+                    submittedAt?: string;
+                    /** @description Exact submitted arguments as JSON or text. Remove credentials, cookies and unrelated private content first. Do not reconstruct unknown arguments. */
+                    arguments: string;
+                    /** @description Observed response or error text, including error codes and retry outcome. Remove secrets. */
+                    result: string;
+                    /** @description Returned request ID, when available. */
+                    requestId?: string;
+                    /** @description Returned job or run ID, when available. */
+                    jobId?: string;
+                }[];
+                /** @description Observed client environment; use unknown rather than guessing. */
+                client: {
+                    /** @description Observed application or SDK name. */
+                    name: string;
+                    /** @description Observed application or package version; omit if unknown. */
+                    version?: string;
+                    /**
+                     * @description Connection or install route used for the failed calls.
+                     * @enum {string}
+                     */
+                    transport: "oauth" | "api-key" | "npx" | "npm" | "sdk" | "mcpb" | "rest" | "unknown";
+                    /** @description Observed operating system; omit if unknown. */
+                    operatingSystem?: string;
+                    /** @description Observed AI model; omit if unknown. */
+                    model?: string;
+                };
+                /** @description Impact, frequency, useful prior context, and suspected cause clearly labeled as a guess. No full conversation dump. */
+                context?: string;
+                /**
+                 * @description Evidence that is unknown or unavailable; do not invent it.
+                 * @default []
+                 */
+                missing: string[];
+            };
+            reviewToken?: string;
+            redacted: boolean;
+            message: string;
+        };
+        BugReportingError: {
+            error?: string;
+            /** @enum {string} */
+            error_code: "request_aborted" | "captcha_exhausted" | "captcha_or_blocked" | "location_mismatch" | "proxy_tunnel_failed" | "proxy_unavailable" | "harvest_timeout" | "mcp_request_timeout" | "mcp_http_error" | "extraction_failed" | "concurrency_limit_exceeded" | "unauthorized" | "forbidden" | "invalid_request" | "rate_limited" | "upstream_rate_limited" | "insufficient_balance" | "service_unavailable" | "response_lost" | "vendor_unavailable" | "page_not_found" | "page_forbidden" | "page_rate_limited" | "page_server_error" | "page_http_error" | "bot_check_unresolved" | "page_too_large" | "page_unreachable" | "browser_session_interrupted" | "site_export_not_found" | "directory_job_not_found" | "site_export_format_unavailable" | "site_export_read_failed" | "site_export_image_not_found" | "image_url_invalid" | "image_url_not_https" | "image_host_unresolvable" | "image_host_blocked" | "image_redirect_invalid" | "image_source_unavailable" | "image_too_large" | "image_redirect_limit" | "image_base64_invalid" | "image_source_missing" | "image_source_ambiguous" | "image_source_type_invalid" | "image_artifact_not_found" | "image_page_too_large" | "page_image_not_found" | "page_image_candidates_unusable" | "image_format_unsupported" | "image_storage_unconfigured" | "featured_image_unhostable";
+            /** @enum {string} */
+            error_type: "request_aborted" | "captcha" | "location_mismatch" | "connection" | "timeout" | "extraction" | "concurrency_limit" | "unauthorized" | "forbidden" | "invalid_request" | "not_found" | "rate_limit" | "billing" | "service_unavailable";
+            message: string;
+            retryable: boolean;
+            /** @enum {string} */
+            charge_status: "not_charged";
+        } & {
+            [key: string]: unknown;
+        };
         MapsSearchRequest: {
             query: string;
             location?: string;
@@ -2645,6 +2920,102 @@ interface components {
     pathItems: never;
 }
 interface operations {
+    bugReporting: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BugReportingRequest"];
+            };
+        };
+        responses: {
+            /** @description Prepare, submit or read a private bug report */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingResponse"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            413: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+            /** @description Prepare, submit or read a private bug report */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BugReportingError"];
+                };
+            };
+        };
+    };
     startHarvest: {
         parameters: {
             query?: never;
@@ -3591,11 +3962,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 +3972,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 +3997,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 +4007,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 +5203,7 @@ declare class RedditNamespace {
         author?: string | null;
         score?: string | null;
         postBody?: string;
+        publishedAt?: string | null;
         numComments?: number;
         comments?: {
             author?: string | null;
@@ -5415,6 +5714,42 @@ declare class ScraperClient {
         job_id: string;
         status: "pending";
     }>;
+    bugReporting(params: RequestBodyOf<'bugReporting'>, options?: ScraperRequestOptions): Promise<{
+        ok: true;
+        accountEmail: string;
+        reportId: string;
+        status: "draft" | "submitted";
+        receivedAt: string;
+        submittedAt: string | null;
+        expiresAt: string;
+        report: {
+            title: string;
+            goal: string;
+            expected: string;
+            actual: string;
+            steps: string[];
+            attempts: {
+                tool: string;
+                submittedAt?: string;
+                arguments: string;
+                result: string;
+                requestId?: string;
+                jobId?: string;
+            }[];
+            client: {
+                name: string;
+                version?: string;
+                transport: "oauth" | "api-key" | "npx" | "npm" | "sdk" | "mcpb" | "rest" | "unknown";
+                operatingSystem?: string;
+                model?: string;
+            };
+            context?: string;
+            missing: string[];
+        };
+        reviewToken?: string;
+        redacted: boolean;
+        message: string;
+    }>;
     searchSerp(params: SearchSerpParams, options?: ScraperRequestOptions): Promise<{
         job_id: string;
         status: "done" | "cancelled" | "failed";

package/dist/index.js

@@ -662,6 +662,17 @@ var ScraperClient = class {
       options
     );
   }
+  async bugReporting(params, options = {}) {
+    try {
+      return await this.r.call("POST", "/bugs/report", params, {}, options);
+    } catch (error) {
+      if (error instanceof ScraperApiError && error.code === "mcp_request_timeout") {
+        const message = params.action === "prepare" || params.action === void 0 ? "Draft preparation was not confirmed. An unreturned draft expires after one day; prepare never submits a report." : "Submission was not confirmed. Read status with the same reportId, then retry submit with the same reportId and reviewToken if needed. Bug Reporting is free.";
+        throw new ScraperApiError(408, { error_code: "mcp_request_timeout", error_type: "timeout", message, retryable: true, charge_status: "not_charged" }, { requestId: error.requestId });
+      }
+      throw error;
+    }
+  }
   searchSerp(params, options = {}) {
     return this.r.call("POST", "/harvest/sync", { ...params, serpOnly: true }, {}, options);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcpscraper-sdk",
-  "version": "0.55.0",
-  "description": "Official Node.js client for all 347 mcpscraper.dev MCP tools and the REST API",
+  "version": "0.57.0",
+  "description": "Official Node.js client for all 348 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.54.0"
+    "mcpscraper-memory-sdk": "^0.56.0"
   },
   "devDependencies": {
     "openapi-typescript": "^7.13.0"