mcpscraper-sdk 0.52.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.
@@ -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;
+                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?: {
-                [key: string]: unknown;
+            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;
@@ -4701,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;
@@ -4740,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<{
@@ -4849,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;
@@ -5185,18 +5470,21 @@ 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 {
@@ -5708,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;
     };
@@ -5730,4 +6022,4 @@ declare class ScraperApiError extends Error {
     };
 }
 
-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, 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 };