mcpscraper-sdk 0.51.0 → 0.53.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AccessNamespace, CaptureNamespace, ChannelsNamespace, FactsNamespace, FilesNamespace, GraphNamespace, LibraryNamespace, MemoryNamespace, RecallNamespace, ScheduleNamespace, StorageNamespace, TablesNamespace, TagsNamespace, VaultsNamespace, VideoNamespace as VideoNamespace$1, WebhooksNamespace, CallToolFn, McpToolsClient } from 'mcpscraper-memory-sdk';
-export { GeneratedMcpToolsClient, MCP_TOOL_BINDINGS, MCP_TOOL_COUNT, McpContentBlock, McpToolCallResult, McpToolDescriptor, McpToolError, McpToolErrorDetails, McpToolsClient, McpToolsClientOptions } from 'mcpscraper-memory-sdk';
+import { ClientMetadataOptions, AccessNamespace, CaptureNamespace, ChannelsNamespace, FactsNamespace, FilesNamespace, GraphNamespace, LibraryNamespace, MemoryNamespace, RecallNamespace, ScheduleNamespace, StorageNamespace, TablesNamespace, TagsNamespace, VaultsNamespace, VideoNamespace as VideoNamespace$1, WebhooksNamespace, CallToolFn, McpToolsClient } from 'mcpscraper-memory-sdk';
+export { ArtifactDelivery, ClientAttribution, ClientMetadataOptions, DeliveredNamespace, GeneratedMcpToolsClient, MCP_TOOL_BINDINGS, MCP_TOOL_COUNT, McpContentBlock, McpToolCallResult, McpToolDescriptor, McpToolError, McpToolErrorDetails, McpToolsClient, McpToolsClientOptions, ResponseMetadata } from 'mcpscraper-memory-sdk';
 
 /**
  * This file was auto-generated by openapi-typescript.
@@ -646,8 +646,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Search Google Maps for businesses matching a query and location
-         * @description Costs 5 credits. Returns up to 50 business/profile candidates.
+         * Search Google Maps for business candidates
+         * @description Costs 5 Credits. Returns up to 50 candidates. websiteUrl can be null and ordinary search does not open every profile; use /maps/place selectively for complete profile fields.
          */
         post: operations["mapsSearch"];
         delete?: never;
@@ -754,8 +754,8 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Run Google Maps business search across many cities in a state/region at once
-         * @description Cost is `5 credits × number of markets resolved` for the query — see `GET /workflows/definitions` for related workflow shapes. Failed cities are refunded individually.
+         * Start a directory search across selected US cities
+         * @description Defaults to a durable background job. Poll its statusUrl without starting another search. background:false runs synchronously. Each failed city is refunded.
          */
         post: operations["directoryWorkflow"];
         delete?: never;
@@ -764,6 +764,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/directory/jobs/{jobId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Poll an owner-scoped directory job
+         * @description Returns progress, terminal city results, billing settlement, and any CSV artifact without starting or billing another search.
+         */
+        get: operations["directoryJobStatus"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/serp-intelligence/capture": {
         parameters: {
             query?: never;
@@ -1183,9 +1203,9 @@ interface components {
         /** @description Stable public failure envelope shared across REST and MCP operations. */
         PublicErrorEnvelope: {
             /** @enum {string} */
-            error_code: "request_aborted" | "captcha_exhausted" | "captcha_or_blocked" | "location_mismatch" | "proxy_tunnel_failed" | "proxy_unavailable" | "harvest_timeout" | "mcp_request_timeout" | "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" | "site_export_format_unavailable" | "site_export_read_failed" | "site_export_image_not_found";
+            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" | "rate_limit" | "billing" | "service_unavailable";
+            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;
             retry_after_seconds?: number;
@@ -1743,26 +1763,6 @@ interface components {
             markdown?: string;
             html?: string;
         };
-        MapsSearchRequest: {
-            query: string;
-            location?: string;
-            /** @default us */
-            gl: string;
-            /** @default en */
-            hl: string;
-            /** @default 10 */
-            maxResults: number;
-            /** @default false */
-            includeServices: boolean;
-            /**
-             * @default none
-             * @enum {string}
-             */
-            proxyMode: "configured" | "none";
-            proxyZip?: string;
-            /** @default false */
-            debug: boolean;
-        };
         MapsPlaceRequest: {
             businessName: string;
             location: string;
@@ -1877,115 +1877,396 @@ interface components {
             debug: boolean;
         };
         SerpIntelligenceOrganicResult: {
-            position?: number;
-            title?: string;
-            url?: string;
-            domain?: string;
-            cite?: string | null;
-            snippet?: string | null;
-            isRedditStyle?: boolean;
-            inlineRating?: {
-                value?: string;
-                count?: string;
+            position: number;
+            title: string;
+            url: string;
+            rawUrl?: string;
+            resolvedUrl?: string | null;
+            /** @enum {string} */
+            linkType?: "plain" | "google_url_redirect" | "google_goto_redirect";
+            /** @enum {string} */
+            resolutionStatus?: "not_needed" | "resolved" | "unresolved" | "rejected";
+            sourcePage?: 1 | 2;
+            domain: string;
+            cite: string | null;
+            snippet: string | null;
+            isRedditStyle: boolean;
+            inlineRating: {
+                value: string;
+                count: string;
             } | null;
         };
         SerpIntelligenceHarvestResult: {
-            seed?: string;
-            location?: string | null;
-            extractedAt?: string;
-            totalQuestions?: number;
+            seed: string;
+            location: string | null;
+            extractedAt: string;
+            totalQuestions: number;
             /** @enum {string} */
-            surface?: "web" | "aim" | "unknown";
-            aiOverview?: {
-                detected?: boolean;
-                text?: string | null;
-                citations?: {
-                    text?: string;
-                    href?: string;
+            surface: "web" | "aim" | "unknown";
+            aiOverview: {
+                detected: boolean;
+                text: string | null;
+                citations: {
+                    text: string;
+                    href: string;
+                    rawUrl?: string;
+                    resolvedUrl?: string | null;
+                    /** @enum {string} */
+                    linkType?: "plain" | "google_url_redirect" | "google_goto_redirect";
+                    /** @enum {string} */
+                    resolutionStatus?: "not_needed" | "resolved" | "unresolved" | "rejected";
                 }[];
-            };
-            aiMode?: {
-                detected?: boolean;
-                text?: string | null;
-                citations?: {
-                    text?: string;
-                    href?: string;
+                expanded?: boolean;
+                fullyExpanded?: boolean;
+                sections?: string[];
+                shareUrl?: string | null;
+            };
+            aiMode: {
+                detected: boolean;
+                text: string | null;
+                citations: {
+                    text: string;
+                    href: string;
+                    rawUrl?: string;
+                    resolvedUrl?: string | null;
+                    /** @enum {string} */
+                    linkType?: "plain" | "google_url_redirect" | "google_goto_redirect";
+                    /** @enum {string} */
+                    resolutionStatus?: "not_needed" | "resolved" | "unresolved" | "rejected";
                 }[];
             };
-            tree?: unknown[];
-            flat?: unknown[];
-            videos?: unknown[];
-            forums?: unknown[];
-            organicResults?: components["schemas"]["SerpIntelligenceOrganicResult"][];
-            localPack?: unknown[];
-            entityIds?: {
-                entities?: {
-                    name?: string;
-                    kgId?: string | null;
-                    cid?: string | null;
-                    gcid?: string | null;
+            tree: components["schemas"]["SerpIntelligencePaaNode"][];
+            flat: {
+                seed_query: string;
+                question_id: string;
+                google_link_id: string;
+                google_evidence_id: string;
+                question: string;
+                answer: string;
+                answerExpansionIncomplete?: boolean;
+                source_title: string;
+                source_site: string;
+                source_cite: string;
+                sources: {
+                    url: string;
+                    rawUrl?: string;
+                    resolvedUrl?: string | null;
+                    /** @enum {string} */
+                    linkType?: "plain" | "google_url_redirect" | "google_goto_redirect";
+                    /** @enum {string} */
+                    resolutionStatus?: "not_needed" | "resolved" | "unresolved" | "rejected";
+                    title: string | null;
+                    site: string | null;
+                    description?: string | null;
                 }[];
-                kgIds?: string[];
-                cids?: string[];
-                gcids?: string[];
-            };
-            stats?: {
-                seed?: string;
-                totalQuestions?: number;
-                maxDepthReached?: number;
-                durationMs?: number;
-                errorCount?: number;
-            };
-            diagnostics?: {
-                [key: string]: unknown;
+                depth: number;
+                parent_question: string;
+                extracted_at: string;
+            }[];
+            videos: {
+                /** @enum {string} */
+                type: "video" | "short_video";
+                title: string;
+                channel: string;
+                platform: string;
+                duration: string;
+                url: string;
+            }[];
+            forums: {
+                title: string;
+                source: string;
+                url: string;
+            }[];
+            organicResults: components["schemas"]["SerpIntelligenceOrganicResult"][];
+            localPack: {
+                position: number;
+                name: string;
+                cid?: string | null;
+                rating?: string | null;
+                reviewCount?: string | null;
+                metadata?: string[];
+                websiteUrl?: string | null;
+                directionsUrl?: string | null;
+            }[];
+            entityIds: {
+                entities: {
+                    name: string;
+                    kgId: string | null;
+                    cid: string | null;
+                    gcid: string | null;
+                }[];
+                kgIds: string[];
+                cids: string[];
+                gcids: string[];
+            };
+            stats: {
+                seed: string;
+                totalQuestions: number;
+                maxDepthReached: number;
+                durationMs: number;
+                errorCount: number;
+            };
+            diagnostics: components["schemas"]["SerpIntelligenceHarvestDiagnostics"];
+            whatPeopleSaying: {
+                /** @enum {string} */
+                type: "reddit" | "facebook" | "instagram" | "tiktok" | "youtube" | "news" | "unknown";
+                title: string;
+                url: string;
+                source: string;
+                platform: string;
+                popularComment: string | null;
+                engagement: string;
+                date: string;
+                duration: string | null;
+                authorNote: string | null;
+            }[];
+        };
+        SerpIntelligenceHarvestDiagnostics: {
+            /** @enum {string} */
+            completionStatus: "paa_found" | "no_paa" | "serp_only";
+            /** @enum {string|null} */
+            problem?: null;
+            /** @enum {string} */
+            resultQuality?: "complete" | "partial" | "degraded";
+            degradedResult?: boolean;
+            degradationReasons?: ("empty_primary_serp" | "page_two_missing")[];
+            retryRecommended?: boolean;
+            noPaaObserved?: boolean;
+            phaseTimings?: {
+                providerConnectMs?: number;
+                navigationMs?: number;
+                serpParseMs?: number;
+                paaExpansionMs?: number;
+                linkResolutionMs?: number;
+                totalServerMs: number;
+            };
+            pagination?: {
+                requestedPages: 1 | 2;
+                capturedPages: 1 | 2;
+                /** @enum {string} */
+                page2Status: "not_requested" | "not_attempted" | "captured" | "unavailable" | "failed";
+                page1OrganicCount: number;
+                page2OrganicCount: number;
+                /** @enum {string} */
+                failureCode?: "missing_next" | "invalid_next" | "empty_page" | "captcha" | "timeout" | "navigation_error" | "unsupported_driver";
+            };
+            completeness?: {
+                paaWithoutAnswer: number;
+                paaWithoutSource: number;
+                paaIncompleteAnswers?: number;
+                paaAnswersRecovered: number;
+                aioShareCaptured: boolean | null;
+                paaRequested?: number;
+                paaReturned?: number;
+                paaUnique?: number;
+            };
+            interruption?: {
+                /** @enum {string} */
+                code: "browser_session_interrupted" | "request_aborted" | "timeout";
             };
-            whatPeopleSaying?: unknown[];
+            warnings?: {
+                /** @enum {string} */
+                code: "short_videos_captcha_skipped" | "paa_partial";
+                /** @enum {string} */
+                surface: "short_videos" | "paa";
+                retryable: boolean;
+            }[];
+            links?: {
+                linkCandidatesObserved: number;
+                plainLinksObserved: number;
+                googleUrlRedirectsObserved: number;
+                googleGotoRedirectsObserved: number;
+                redirectsResolved: number;
+                redirectsUnresolved: number;
+                redirectsRejected: number;
+                resolverNonGoogleRequestsObserved: number;
+                paaSourcesPreserved: number;
+                aiOverviewLabelValidated: boolean;
+            };
+            paaLifecycle?: {
+                requestedQuestions: number;
+                questionsFound: number;
+                /** @enum {string} */
+                targetStatus: "met" | "not_met";
+                /** @enum {string} */
+                discoveryStatus: "in_progress" | "target_reached" | "frontier_exhausted" | "no_paa_observed" | "interrupted" | "recovery_exhausted";
+                /** @enum {string} */
+                materialStatus: "complete" | "partial";
+                automaticRetries: number;
+                retryBreakdown: {
+                    controlRetries: number;
+                    browserRetries: number;
+                    providerFallbacks: number;
+                    runtimeRecoveries: number;
+                    idempotentReplays: number;
+                };
+                knownQuestions: number;
+                processedQuestions: number;
+                failedInteractions: number;
+                noGrowthConfirmations: number;
+                visibleControls?: number;
+                eligibleControls?: number;
+                dispatchedInteractions?: number;
+                confirmedInteractions?: number;
+                unconfirmedInteractions?: number;
+            };
+        };
+        SerpIntelligenceLocationEvidence: {
+            /** @enum {string} */
+            status: "not_requested" | "matched" | "mismatch" | "unknown";
+            expected: {
+                city: string;
+                regionCode: string | null;
+                canonicalLocation: string;
+            } | null;
+            candidates: {
+                city: string;
+                regionCode: string;
+                count: number;
+                examples: string[];
+            }[];
+        };
+        SerpIntelligenceCaptureAttempt: {
+            attemptNumber: number;
+            /** @enum {string} */
+            outcome: "paa_found" | "paa_partial" | "no_paa" | "serp_only" | "degraded_result" | "captcha" | "request_aborted" | "timeout" | "location_mismatch" | "proxy_tunnel_failed" | "proxy_unavailable" | "browser_session_interrupted" | "mcp_unavailable" | "error" | "page_captured" | "page_failed";
+            startedAt?: string;
+            completedAt?: string;
+            durationMs?: number;
+            /** @enum {string} */
+            problemCode?: "paa_found" | "paa_partial" | "no_paa" | "serp_only" | "degraded_result" | "captcha" | "request_aborted" | "timeout" | "location_mismatch" | "proxy_tunnel_failed" | "proxy_unavailable" | "browser_session_interrupted" | "mcp_unavailable" | "error" | "captcha_exhausted" | "harvest_timeout" | "service_unavailable" | "vendor_unavailable" | "extraction_failed" | "invalid_url" | "capture_failed";
+            cleanupSucceeded?: boolean | null;
         };
         SerpPageSnapshotCapture: {
-            url?: string;
-            requestedUrl?: string;
-            finalUrl?: string | null;
+            /** Format: uri */
+            url: string;
+            /** Format: uri */
+            requestedUrl: string;
+            /** Format: uri */
+            finalUrl: string | null;
             /** @enum {string} */
-            sourceKind?: "organic" | "ai_citation" | "local_pack_website" | "configured_target" | "site_subject";
-            sourcePosition?: number | null;
+            sourceKind: "organic" | "ai_citation" | "local_pack_website" | "configured_target" | "site_subject";
+            sourcePosition: number | null;
             /** @enum {string} */
-            status?: "captured" | "skipped" | "failed";
+            status: "captured" | "skipped" | "failed";
             /** @enum {string|null} */
-            fetchedVia?: "fetch" | "headless" | "browser" | "mcp" | null;
-            httpStatus?: number | null;
-            contentType?: string | null;
-            title?: string | null;
-            canonicalUrl?: string | null;
-            metaDescription?: string | null;
-            headings?: {
-                level?: number;
-                text?: string;
+            fetchedVia: "fetch" | "headless" | "browser" | "mcp" | null;
+            httpStatus: number | null;
+            contentType: string | null;
+            title: string | null;
+            /** Format: uri */
+            canonicalUrl: string | null;
+            metaDescription: string | null;
+            /** @default [] */
+            headings: {
+                level: number;
+                text: string;
             }[];
-            artifact?: {
-                htmlBlobUrl?: string | null;
-                textBlobUrl?: string | null;
-                markdownBlobUrl?: string | null;
-                screenshotBlobUrl?: string | null;
-                contentSha256?: string | null;
-                capturedAt?: string | null;
-            };
-            error?: {
-                code?: string;
-                message?: string;
+            artifact: {
+                /** Format: uri */
+                htmlBlobUrl: string | null;
+                /** Format: uri */
+                textBlobUrl: string | null;
+                /** Format: uri */
+                markdownBlobUrl: string | null;
+                /** Format: uri */
+                screenshotBlobUrl: string | null;
+                contentSha256: string | null;
+                capturedAt: string | null;
+            };
+            error: {
+                /** @enum {string} */
+                code: "invalid_url" | "timeout" | "capture_failed";
+                message: string;
             } | null;
+            schemaTypes?: string[];
+            wordCount?: number;
+            linkCounts?: {
+                wordCount: number;
+                internalLinkCount: number;
+                externalLinkCount: number;
+                totalLinkCount: number;
+            };
+            hashes?: {
+                htmlSha256: string | null;
+                markdownSha256: string | null;
+                textSha256: string | null;
+            };
+            content?: {
+                html: string | null;
+                markdown: string | null;
+                text: string | null;
+            };
+            diagnostics?: {
+                requestedAt: string;
+                completedAt: string;
+                durationMs: number;
+                urlValidation: {
+                    passed: boolean;
+                };
+                browserFallback: {
+                    configured: boolean;
+                    used: boolean;
+                    boundedByTimeoutMs: number;
+                };
+                content: {
+                    htmlIncluded: boolean;
+                    markdownIncluded: boolean;
+                    textIncluded: boolean;
+                    maxContentChars: number;
+                    truncated: boolean;
+                };
+            };
+        };
+        SerpIntelligencePageSnapshotDiagnostics: {
+            requestedCount?: number;
+            capturedCount?: number;
+            failedCount?: number;
+            maxConcurrency?: number;
+            timeoutMs?: number;
         };
         SerpIntelligenceCaptureResponse: {
-            harvestResult?: components["schemas"]["SerpIntelligenceHarvestResult"];
-            locationEvidence?: {
-                [key: string]: unknown;
-            } | null;
-            pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
+            harvestResult: components["schemas"]["SerpIntelligenceHarvestResult"];
+            attempts: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
+            locationEvidence: components["schemas"]["SerpIntelligenceLocationEvidence"] | null;
+            pageSnapshotArtifacts: components["schemas"]["SerpPageSnapshotCapture"][];
             billing: {
                 creditsUsed: number;
+                requestId?: string;
+                jobId?: string;
             };
         };
         SerpIntelligencePageSnapshotsResponse: {
-            pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
+            pageSnapshotArtifacts: components["schemas"]["SerpPageSnapshotCapture"][];
+            /** @default [] */
+            attempts: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
+            diagnostics?: components["schemas"]["SerpIntelligencePageSnapshotDiagnostics"];
+        };
+        SerpIntelligencePaaNode: {
+            questionId: string;
+            googleLinkId: string | null;
+            googleEvidenceId: string | null;
+            question: string;
+            answer: string | null;
+            answerExpansionIncomplete?: boolean;
+            sourceTitle: string | null;
+            sourceSite: string | null;
+            sourceCite: string | null;
+            sources: {
+                url: string;
+                rawUrl?: string;
+                resolvedUrl?: string | null;
+                /** @enum {string} */
+                linkType?: "plain" | "google_url_redirect" | "google_goto_redirect";
+                /** @enum {string} */
+                resolutionStatus?: "not_needed" | "resolved" | "unresolved" | "rejected";
+                title: string | null;
+                site: string | null;
+                description?: string | null;
+            }[];
+            depth: number;
+            parentQuestion: string | null;
+            children: components["schemas"]["SerpIntelligencePaaNode"][];
         };
         WorkflowRun: {
             id?: string;
@@ -2150,6 +2431,198 @@ interface components {
         } & {
             [key: string]: unknown;
         };
+        MapsSearchRequest: {
+            query: string;
+            location?: string;
+            /** @default us */
+            gl: string;
+            /** @default en */
+            hl: string;
+            /** @default 10 */
+            maxResults: number;
+            /** @default false */
+            includeServices: boolean;
+            /**
+             * @default none
+             * @enum {string}
+             */
+            proxyMode: "location" | "configured" | "none";
+            proxyZip?: string;
+            /** @default false */
+            debug: boolean;
+        };
+        MapsSearchResponse: {
+            provider?: string;
+            fallbackFrom?: string;
+            acquisitionProvider?: string;
+            query: string;
+            location: string | null;
+            searchQuery: string;
+            /** Format: uri */
+            searchUrl: string;
+            extractedAt: string;
+            requestedMaxResults: number;
+            resultCount: number;
+            results: {
+                position: number;
+                name: string;
+                /** Format: uri */
+                placeUrl: string;
+                cid: string | null;
+                cidDecimal: string | null;
+                rating: string | null;
+                reviewCount: string | null;
+                category: string | null;
+                address: string | null;
+                phone: string | null;
+                hoursStatus: string | null;
+                websiteUrl: string | null;
+                directionsUrl: string | null;
+                metadata: string[];
+                /** @default [] */
+                services: string[];
+                /** @default [] */
+                areasServed: string[];
+                /**
+                 * @default unavailable
+                 * @enum {string}
+                 */
+                profileDetailsStatus: "collected" | "none_exist" | "unavailable" | "not_requested";
+            }[];
+            durationMs: number;
+        } & {
+            [key: string]: unknown;
+        };
+        DirectoryRunRequest: {
+            query: string;
+            /** @default TN */
+            state: string;
+            /** @default 100000 */
+            minPopulation: number;
+            /** @default 2025 */
+            populationYear: 2020 | 2021 | 2022 | 2023 | 2024 | 2025;
+            /** @default 25 */
+            maxCities: number;
+            /** @default 50 */
+            maxResultsPerCity: number;
+            /** @default 5 */
+            concurrency: number;
+            /** @default true */
+            includeZipGroups: boolean;
+            /** @default true */
+            saveCsv: boolean;
+            /** @default true */
+            background: boolean;
+            /** @default us */
+            gl: string;
+            /** @default en */
+            hl: string;
+            /**
+             * @default none
+             * @enum {string}
+             */
+            proxyMode: "configured" | "none";
+            proxyZip?: string;
+            /** @default false */
+            debug: boolean;
+        };
+        DirectoryJobResponse: {
+            jobId: string | null;
+            /** @enum {string} */
+            status: "queued" | "running" | "complete" | "partial" | "empty" | "failed";
+            statusUrl: string | null;
+            query: string;
+            state: string;
+            minPopulation: number;
+            populationYear: number;
+            maxResultsPerCity: number;
+            concurrency: number;
+            /** Format: uri */
+            censusSourceUrl: string;
+            usZipsSourcePath: string | null;
+            warnings: string[];
+            extractedAt: string;
+            selectedCityCount: number;
+            totalResultCount: number;
+            csvPath: string | null;
+            csvArtifact: {
+                artifactId: string;
+                filename: string;
+                contentType: string;
+                bytes: number;
+                rowCount: number;
+                sha256: string;
+                expiresAt: string;
+                downloadUrl: string | null;
+                downloadUrlExpiresAt: string | null;
+            } | null;
+            progress: {
+                completedCities: number;
+                totalCities: number;
+                failedCities: number;
+            };
+            billing: {
+                heldMc: number;
+                finalMc: number | null;
+                refundMc: number | null;
+            };
+            errorCode: string | null;
+            error: string | null;
+            retryable: boolean | null;
+            cities: {
+                city: string;
+                state: string;
+                location: string;
+                cityKey: string;
+                censusName: string;
+                population: number;
+                populationYear: number;
+                zips: string[];
+                counties: string[];
+                /** @enum {string} */
+                status: "ok" | "empty" | "failed";
+                error: string | null;
+                errorCode?: string | null;
+                retryable?: boolean;
+                resultCount: number;
+                durationMs: number;
+                results: {
+                    position: number;
+                    name: string;
+                    /** Format: uri */
+                    placeUrl: string;
+                    cid: string | null;
+                    cidDecimal: string | null;
+                    rating: string | null;
+                    reviewCount: string | null;
+                    category: string | null;
+                    address: string | null;
+                    phone: string | null;
+                    hoursStatus: string | null;
+                    websiteUrl: string | null;
+                    directionsUrl: string | null;
+                    metadata: string[];
+                }[];
+            }[];
+            durationMs: number;
+            truncatedCount?: number;
+            artifact?: {
+                artifactId: string;
+                bytes: number;
+                expiresAt: string;
+                preview: string;
+            };
+        } & {
+            [key: string]: unknown;
+        };
+        DirectoryJobNotFound: {
+            /** @enum {string} */
+            error: "Directory workflow job not found.";
+            /** @enum {string} */
+            error_code: "directory_job_not_found";
+            /** @enum {boolean} */
+            retryable: false;
+        };
     };
     responses: {
         /** @description Missing or invalid `x-api-key`. */
@@ -3442,7 +3915,10 @@ interface operations {
     mapsSearch: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description Reuse only for an identical retry after an uncertain response. */
+                "Idempotency-Key"?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -3452,22 +3928,20 @@ interface operations {
             };
         };
         responses: {
-            /** @description Search results. */
+            /** @description Search Google Maps for business candidates */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        [key: string]: unknown;
-                    };
+                    "application/json": components["schemas"]["MapsSearchResponse"];
                 };
             };
             400: components["responses"]["BadRequest"];
             402: components["responses"]["InsufficientBalance"];
             429: components["responses"]["ConcurrencyLimitExceeded"];
             500: components["responses"]["ServerError"];
-            /** @description Temporarily blocked — retryable. */
+            /** @description Temporarily blocked. */
             503: {
                 headers: {
                     [name: string]: unknown;
@@ -3676,48 +4150,46 @@ interface operations {
     directoryWorkflow: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description Reuse only for the same intended directory job. */
+                "Idempotency-Key"?: string;
+            };
             path?: never;
             cookie?: never;
         };
         requestBody: {
             content: {
-                "application/json": {
-                    /** @description Business category to search, e.g. "roofers". */
-                    query: string;
-                    /** @description US state code or name. */
-                    state: string;
-                    /** @description Minimum city population to include as a market. */
-                    minPop?: number;
-                    /** @description Max results per city. */
-                    perCity?: number;
-                };
+                "application/json": components["schemas"]["DirectoryRunRequest"];
             };
         };
         responses: {
-            /** @description Per-city results. */
+            /** @description Start a directory search across selected US cities */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        query?: string;
-                        state?: string;
-                        totalResultCount?: number;
-                        cities?: {
-                            city?: string;
-                            /** @enum {string} */
-                            status?: "done" | "failed";
-                            results?: {
-                                [key: string]: unknown;
-                            }[];
-                        }[];
-                    };
+                    "application/json": components["schemas"]["DirectoryJobResponse"];
+                };
+            };
+            /** @description Start a directory search across selected US cities */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DirectoryJobResponse"];
                 };
             };
             400: components["responses"]["BadRequest"];
             402: components["responses"]["InsufficientBalance"];
+            /** @description Idempotency-Key already used with different input. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
             429: components["responses"]["ConcurrencyLimitExceeded"];
             /** @description Directory workflow failed. */
             500: {
@@ -3728,6 +4200,37 @@ interface operations {
             };
         };
     };
+    directoryJobStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                jobId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Poll an owner-scoped directory job */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DirectoryJobResponse"];
+                };
+            };
+            /** @description Poll an owner-scoped directory job */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DirectoryJobNotFound"];
+                };
+            };
+        };
+    };
     serpIntelligenceCapture: {
         parameters: {
             query?: never;
@@ -4479,7 +4982,7 @@ type SuccessBodyOf<K extends OperationId> = operations[K]['responses'] extends {
         };
     };
 } ? B : unknown;
-interface ScraperClientOptions {
+interface ScraperClientOptions extends ClientMetadataOptions {
     apiKey: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
@@ -4496,6 +4999,10 @@ interface ScraperRequestOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
 }
+type MapsSearchDefaultedKey = 'gl' | 'hl' | 'maxResults' | 'includeServices' | 'proxyMode' | 'debug';
+type MapsSearchParams = Omit<RequestBodyOf<'mapsSearch'>, MapsSearchDefaultedKey> & Partial<Pick<RequestBodyOf<'mapsSearch'>, MapsSearchDefaultedKey>>;
+type DirectoryDefaultedKey = 'state' | 'minPopulation' | 'populationYear' | 'maxCities' | 'maxResultsPerCity' | 'concurrency' | 'includeZipGroups' | 'saveCsv' | 'background' | 'gl' | 'hl' | 'proxyMode' | 'debug';
+type DirectoryRunParams = Omit<RequestBodyOf<'directoryWorkflow'>, DirectoryDefaultedKey> & Partial<Pick<RequestBodyOf<'directoryWorkflow'>, DirectoryDefaultedKey>>;
 interface ExtractSiteOptions extends ScraperRequestOptions {
     idempotencyKey?: string;
 }
@@ -4514,13 +5021,17 @@ interface SerpIntelligenceCaptureOptions {
 interface SerpIntelligenceCaptureReceipt {
     data: SuccessBodyOf<'serpIntelligenceCapture'>;
     idempotencyKey: string | null;
+    requestId?: string;
 }
 declare class Requester {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetchImpl;
     private readonly timeoutMs;
-    constructor(apiKey: string, baseUrl: string, fetchImpl: typeof globalThis.fetch, timeoutMs: number);
+    private readonly metadataOptions;
+    constructor(apiKey: string, baseUrl: string, fetchImpl: typeof globalThis.fetch, timeoutMs: number, metadataOptions?: ClientMetadataOptions);
+    private headers;
+    private received;
     private request;
     call<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>, extraHeaders?: Record<string, string>, options?: ScraperRequestOptions): Promise<SuccessBodyOf<K>>;
     callWithReceipt<K extends OperationId>(method: string, path: string, body?: RequestBodyOf<K>, extraHeaders?: Record<string, string>, options?: ScraperRequestOptions): Promise<{
@@ -4623,7 +5134,7 @@ declare class InstagramNamespace {
 declare class RedditNamespace {
     private readonly r;
     constructor(r: Requester);
-    thread(params: RequestBodyOf<'redditThread'>): Promise<{
+    thread(params: RequestBodyOf<'redditThread'>, options?: ScraperRequestOptions & IdempotentRequestOptions): Promise<{
         title?: string;
         author?: string | null;
         score?: string | null;
@@ -4669,7 +5180,38 @@ declare class VideoNamespace {
 declare class MapsNamespace {
     private readonly r;
     constructor(r: Requester);
-    search(params: RequestBodyOf<'mapsSearch'>, options?: ScraperRequestOptions): Promise<{
+    search(params: MapsSearchParams, options?: ScraperRequestOptions & IdempotentRequestOptions): Promise<{
+        provider?: string;
+        fallbackFrom?: string;
+        acquisitionProvider?: string;
+        query: string;
+        location: string | null;
+        searchQuery: string;
+        searchUrl: string;
+        extractedAt: string;
+        requestedMaxResults: number;
+        resultCount: number;
+        results: {
+            position: number;
+            name: string;
+            placeUrl: string;
+            cid: string | null;
+            cidDecimal: string | null;
+            rating: string | null;
+            reviewCount: string | null;
+            category: string | null;
+            address: string | null;
+            phone: string | null;
+            hoursStatus: string | null;
+            websiteUrl: string | null;
+            directionsUrl: string | null;
+            metadata: string[];
+            services: string[];
+            areasServed: string[];
+            profileDetailsStatus: "collected" | "none_exist" | "unavailable" | "not_requested";
+        }[];
+        durationMs: number;
+    } & {
         [key: string]: unknown;
     }>;
     place(params: RequestBodyOf<'mapsPlaceIntel'>, options?: ScraperRequestOptions & {
@@ -4751,35 +5293,198 @@ declare class MapsNamespace {
 declare class DirectoryNamespace {
     private readonly r;
     constructor(r: Requester);
-    run(params: RequestBodyOf<'directoryWorkflow'>): Promise<{
-        query?: string;
-        state?: string;
-        totalResultCount?: number;
-        cities?: {
-            city?: string;
-            status?: "done" | "failed";
-            results?: {
-                [key: string]: unknown;
+    run(params: DirectoryRunParams, options?: ScraperRequestOptions & {
+        idempotencyKey?: string;
+    }): Promise<{
+        jobId: string | null;
+        status: "queued" | "running" | "complete" | "partial" | "empty" | "failed";
+        statusUrl: string | null;
+        query: string;
+        state: string;
+        minPopulation: number;
+        populationYear: number;
+        maxResultsPerCity: number;
+        concurrency: number;
+        censusSourceUrl: string;
+        usZipsSourcePath: string | null;
+        warnings: string[];
+        extractedAt: string;
+        selectedCityCount: number;
+        totalResultCount: number;
+        csvPath: string | null;
+        csvArtifact: {
+            artifactId: string;
+            filename: string;
+            contentType: string;
+            bytes: number;
+            rowCount: number;
+            sha256: string;
+            expiresAt: string;
+            downloadUrl: string | null;
+            downloadUrlExpiresAt: string | null;
+        } | null;
+        progress: {
+            completedCities: number;
+            totalCities: number;
+            failedCities: number;
+        };
+        billing: {
+            heldMc: number;
+            finalMc: number | null;
+            refundMc: number | null;
+        };
+        errorCode: string | null;
+        error: string | null;
+        retryable: boolean | null;
+        cities: {
+            city: string;
+            state: string;
+            location: string;
+            cityKey: string;
+            censusName: string;
+            population: number;
+            populationYear: number;
+            zips: string[];
+            counties: string[];
+            status: "ok" | "empty" | "failed";
+            error: string | null;
+            errorCode?: string | null;
+            retryable?: boolean;
+            resultCount: number;
+            durationMs: number;
+            results: {
+                position: number;
+                name: string;
+                placeUrl: string;
+                cid: string | null;
+                cidDecimal: string | null;
+                rating: string | null;
+                reviewCount: string | null;
+                category: string | null;
+                address: string | null;
+                phone: string | null;
+                hoursStatus: string | null;
+                websiteUrl: string | null;
+                directionsUrl: string | null;
+                metadata: string[];
             }[];
         }[];
+        durationMs: number;
+        truncatedCount?: number;
+        artifact?: {
+            artifactId: string;
+            bytes: number;
+            expiresAt: string;
+            preview: string;
+        };
+    } & {
+        [key: string]: unknown;
+    }>;
+    status(jobId: string, options?: ScraperRequestOptions): Promise<{
+        jobId: string | null;
+        status: "queued" | "running" | "complete" | "partial" | "empty" | "failed";
+        statusUrl: string | null;
+        query: string;
+        state: string;
+        minPopulation: number;
+        populationYear: number;
+        maxResultsPerCity: number;
+        concurrency: number;
+        censusSourceUrl: string;
+        usZipsSourcePath: string | null;
+        warnings: string[];
+        extractedAt: string;
+        selectedCityCount: number;
+        totalResultCount: number;
+        csvPath: string | null;
+        csvArtifact: {
+            artifactId: string;
+            filename: string;
+            contentType: string;
+            bytes: number;
+            rowCount: number;
+            sha256: string;
+            expiresAt: string;
+            downloadUrl: string | null;
+            downloadUrlExpiresAt: string | null;
+        } | null;
+        progress: {
+            completedCities: number;
+            totalCities: number;
+            failedCities: number;
+        };
+        billing: {
+            heldMc: number;
+            finalMc: number | null;
+            refundMc: number | null;
+        };
+        errorCode: string | null;
+        error: string | null;
+        retryable: boolean | null;
+        cities: {
+            city: string;
+            state: string;
+            location: string;
+            cityKey: string;
+            censusName: string;
+            population: number;
+            populationYear: number;
+            zips: string[];
+            counties: string[];
+            status: "ok" | "empty" | "failed";
+            error: string | null;
+            errorCode?: string | null;
+            retryable?: boolean;
+            resultCount: number;
+            durationMs: number;
+            results: {
+                position: number;
+                name: string;
+                placeUrl: string;
+                cid: string | null;
+                cidDecimal: string | null;
+                rating: string | null;
+                reviewCount: string | null;
+                category: string | null;
+                address: string | null;
+                phone: string | null;
+                hoursStatus: string | null;
+                websiteUrl: string | null;
+                directionsUrl: string | null;
+                metadata: string[];
+            }[];
+        }[];
+        durationMs: number;
+        truncatedCount?: number;
+        artifact?: {
+            artifactId: string;
+            bytes: number;
+            expiresAt: string;
+            preview: string;
+        };
+    } & {
+        [key: string]: unknown;
     }>;
 }
 declare class SerpIntelligenceNamespace {
     private readonly r;
     constructor(r: Requester);
     capture(params: SerpIntelligenceCaptureParams, options?: SerpIntelligenceCaptureOptions): Promise<{
-        harvestResult?: components["schemas"]["SerpIntelligenceHarvestResult"];
-        locationEvidence?: {
-            [key: string]: unknown;
-        } | null;
-        pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
+        harvestResult: components["schemas"]["SerpIntelligenceHarvestResult"];
+        attempts: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
+        locationEvidence: components["schemas"]["SerpIntelligenceLocationEvidence"] | null;
+        pageSnapshotArtifacts: components["schemas"]["SerpPageSnapshotCapture"][];
         billing: {
             creditsUsed: number;
+            requestId?: string;
+            jobId?: string;
         };
     }>;
     captureWithReceipt(params: SerpIntelligenceCaptureParams, options?: SerpIntelligenceCaptureOptions): Promise<SerpIntelligenceCaptureReceipt>;
     pageSnapshots(params: RequestBodyOf<'serpIntelligencePageSnapshots'>): Promise<{
-        pageSnapshotArtifacts?: components["schemas"]["SerpPageSnapshotCapture"][];
+        pageSnapshotArtifacts: components["schemas"]["SerpPageSnapshotCapture"][];
+        attempts: components["schemas"]["SerpIntelligenceCaptureAttempt"][];
+        diagnostics?: components["schemas"]["SerpIntelligencePageSnapshotDiagnostics"];
     }>;
 }
 declare class WorkflowsNamespace {
@@ -5291,11 +5996,15 @@ type StructuredErrorBody = components['schemas']['StructuredError'];
 type PublicErrorEnvelopeBody = components['schemas']['PublicErrorEnvelope'];
 type ConcurrencyPackBody = components['schemas']['ConcurrencyPack'];
 type ConcurrencyAccountViewBody = components['schemas']['ConcurrencyAccountView'];
+interface ScraperApiErrorDetails {
+    requestId?: string;
+}
 declare class ScraperApiError extends Error {
     readonly status: number;
     readonly code?: string;
     readonly body: unknown;
-    constructor(status: number, body: unknown);
+    readonly requestId?: string;
+    constructor(status: number, body: unknown, details?: ScraperApiErrorDetails);
     isInsufficientBalance(): this is ScraperApiError & {
         body: InsufficientBalanceBody;
     };
@@ -5313,4 +6022,4 @@ declare class ScraperApiError extends Error {
     };
 }
 
-export { type ArchiveReadParams, type ConcurrencyAccountViewBody, type ConcurrencyLimitBody, type ConcurrencyPackBody, type ExtractSiteOptions, type GmailMutationOptions, type HarvestParams, type IdempotentRequestOptions, type InsufficientBalanceBody, type PublicErrorEnvelopeBody, ScraperApiError, ScraperClient, type ScraperClientOptions, type ScraperRequestOptions, type SearchSerpParams, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };
+export { type ArchiveReadParams, type ConcurrencyAccountViewBody, type ConcurrencyLimitBody, type ConcurrencyPackBody, type DirectoryRunParams, type ExtractSiteOptions, type GmailMutationOptions, type HarvestParams, type IdempotentRequestOptions, type InsufficientBalanceBody, type MapsSearchParams, type PublicErrorEnvelopeBody, ScraperApiError, type ScraperApiErrorDetails, ScraperClient, type ScraperClientOptions, type ScraperRequestOptions, type SearchSerpParams, type SerpIntelligenceCaptureOptions, type SerpIntelligenceCaptureParams, type SerpIntelligenceCaptureReceipt, type StructuredErrorBody, type components, type operations, type paths };