mcp-scraper 0.92.1 → 0.93.1

package/dist/index.d.cts

@@ -1,5 +1,44 @@
 import { z } from 'zod';
 
+declare const SERP_FEATURE_COMPLETENESS_STATES: readonly ["observed_present", "observed_absent", "incomplete", "not_requested", "unknown", "unsupported"];
+type SerpFeatureCompletenessState = typeof SERP_FEATURE_COMPLETENESS_STATES[number];
+
+interface SerpPreviewQuestion {
+    question: string;
+    answer: string | null;
+    url: string | null;
+}
+interface SerpFeatureItem {
+    title: string | null;
+    url: string | null;
+    description: string | null;
+    position: number | null;
+}
+interface SerpFeatureGroup {
+    name: string;
+    attributes: Record<string, string | number | boolean | null>;
+    items: SerpFeatureItem[];
+}
+interface FullSerpPageFeatures {
+    page: 1 | 2;
+    status: Record<string, SerpFeatureCompletenessState>;
+    paaPreview: SerpPreviewQuestion[];
+    additional: SerpFeatureGroup[];
+    localPack: LocalPackBusiness[];
+    forums: ForumResult[];
+    videos: VideoResult[];
+    whatPeopleSaying: WhatPeopleSayingCard[];
+    aiOverview: AIOverviewResult;
+    aiMode: AIModeResult;
+    entityIds: EntityIds;
+}
+interface FullSerpFeatures {
+    status: Record<string, SerpFeatureCompletenessState>;
+    paaPreview: SerpPreviewQuestion[];
+    additional: SerpFeatureGroup[];
+    pages: FullSerpPageFeatures[];
+}
+
 declare const HarvestOptionsSchema: z.ZodObject<{
     query: z.ZodString;
     location: z.ZodOptional<z.ZodString>;
@@ -24,13 +63,13 @@ declare const HarvestOptionsSchema: z.ZodObject<{
     headless: z.ZodDefault<z.ZodBoolean>;
     profileDir: z.ZodOptional<z.ZodString>;
     proxy: z.ZodOptional<z.ZodString>;
-    kernelApiKey: z.ZodOptional<z.ZodString>;
-    kernelProxyId: z.ZodOptional<z.ZodString>;
-    kernelProfileName: z.ZodOptional<z.ZodString>;
-    kernelProfileSaveChanges: z.ZodOptional<z.ZodBoolean>;
-    kernelStealth: z.ZodOptional<z.ZodBoolean>;
+    \u006b\u0065\u0072\u006e\u0065\u006cApiKey: z.ZodOptional<z.ZodString>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProxyId: z.ZodOptional<z.ZodString>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProfileName: z.ZodOptional<z.ZodString>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProfileSaveChanges: z.ZodOptional<z.ZodBoolean>;
+    \u006b\u0065\u0072\u006e\u0065\u006cStealth: z.ZodOptional<z.ZodBoolean>;
     serpIdentity: z.ZodOptional<z.ZodString>;
-    kernelProxyResolution: z.ZodOptional<z.ZodUnknown>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProxyResolution: z.ZodOptional<z.ZodUnknown>;
     outputDir: z.ZodDefault<z.ZodString>;
     format: z.ZodDefault<z.ZodEnum<{
         json: "json";
@@ -57,75 +96,6 @@ declare const HarvestOptionsSchema: z.ZodObject<{
     softDeadlineMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 
-type CanonicalLocationName = string;
-type SerpDevice = 'desktop' | 'mobile';
-type ProxyMode = 'location' | 'configured' | 'none';
-interface KernelLocationProxyTarget {
-    canonicalLocation: CanonicalLocationName;
-    level: 'zip' | 'city' | 'state';
-    country: 'US';
-    state: string;
-    city: string;
-    zip?: string;
-    cityCandidates: string[];
-    proxyName: string;
-    config: {
-        country: 'US';
-        state: string;
-        city?: string;
-        zip?: string;
-    };
-}
-type KernelProxyResolutionSource = 'disabled' | 'location_reused' | 'location_created' | 'isp_created' | 'backup_custom' | 'configured_fallback' | 'unavailable';
-interface KernelProxyResolutionDebug {
-    source: KernelProxyResolutionSource;
-    proxyType: string;
-    proxyMode: ProxyMode;
-    proxyIdPresent: boolean;
-    proxyIdSuffix: string | null;
-    target: KernelLocationProxyTarget | null;
-    error: string | null;
-    disposable?: boolean;
-}
-interface HarvestStats {
-    seed: string;
-    totalQuestions: number;
-    maxDepthReached: number;
-    durationMs: number;
-    errorCount: number;
-}
-type HarvestCompletionStatus = 'paa_found' | 'no_paa' | 'serp_only';
-/**
- * A completed browser attempt can still be unsuitable for programmatic use.
- * This is deliberately separate from completionStatus so a valid no-PAA
- * response with organic results is not confused with an unreadable SERP.
- */
-type HarvestResultQuality = 'complete' | 'partial' | 'degraded';
-type HarvestDegradationReason = 'empty_primary_serp';
-type HarvestDiagnosticWarningCode = 'short_videos_captcha_skipped' | 'paa_partial';
-type HarvestDiagnosticWarningSurface = 'short_videos' | 'paa';
-interface HarvestDiagnosticWarning {
-    code: HarvestDiagnosticWarningCode;
-    surface: HarvestDiagnosticWarningSurface;
-    message: string;
-    retryable: boolean;
-}
-interface HarvestCompleteness {
-    paaWithoutAnswer: number;
-    paaWithoutSource: number;
-    paaAnswersRecovered: number;
-    aioShareCaptured: boolean | null;
-    paaRequested?: number;
-    paaReturned?: number;
-    paaUnique?: number;
-}
-type HarvestInterruptionCode = 'browser_session_interrupted' | 'request_aborted' | 'timeout';
-type HarvestInterruptionReasonSource = 'client_runtime' | 'extractor';
-interface HarvestInterruptionDiagnostic {
-    code: HarvestInterruptionCode;
-    reasonSource: HarvestInterruptionReasonSource;
-    message: string | null;
-}
 type PaaDiscoveryStatus = 'in_progress' | 'target_reached' | 'frontier_exhausted' | 'no_paa_observed' | 'interrupted' | 'recovery_exhausted';
 type PaaTargetStatus = 'met' | 'not_met';
 type PaaMaterialStatus = 'complete' | 'partial';
@@ -185,15 +155,6 @@ interface PaaInteractionObservation {
     errorCode: 'click_failed' | 'click_ack_timeout' | 'control_missing' | 'confirmation_timeout' | null;
 }
 type PaaProgressPhase = 'serp_captured' | 'discovered' | 'click_observed' | 'answer_captured' | 'fill_incomplete' | 'expansion_finished' | 'attempt_ending';
-/** Observed organic pagination outcome; page two never expands a separate PAA graph. */
-interface HarvestPaginationDiagnostics {
-    requestedPages: 1 | 2;
-    capturedPages: 1 | 2;
-    page2Status: 'not_requested' | 'not_attempted' | 'captured' | 'unavailable' | 'failed';
-    page1OrganicCount: number;
-    page2OrganicCount: number;
-    failureCode?: 'missing_next' | 'invalid_next' | 'empty_page' | 'captcha' | 'timeout' | 'navigation_error' | 'unsupported_driver';
-}
 /** Material already observed before PAA expansion completes. It is checkpointed
  * so a worker interruption cannot discard the SERP that led to the PAA graph. */
 interface PaaProgressMaterial {
@@ -218,6 +179,119 @@ interface PaaProgressSnapshot {
     material?: PaaProgressMaterial;
     interactions?: PaaInteractionObservation[];
 }
+interface PaaSource extends SerpOutboundLink {
+    title: string | null;
+    site: string | null;
+}
+interface PAANode {
+    questionId: string;
+    googleLinkId: string | null;
+    googleEvidenceId: string | null;
+    question: string;
+    answer: string | null;
+    sourceTitle: string | null;
+    sourceSite: string | null;
+    sourceCite: string | null;
+    sources: PaaSource[];
+    depth: number;
+    parentQuestion: string | null;
+    children: PAANode[];
+}
+interface FlatRow {
+    seed_query: string;
+    question_id: string;
+    google_link_id: string;
+    google_evidence_id: string;
+    question: string;
+    answer: string;
+    source_title: string;
+    source_site: string;
+    source_cite: string;
+    sources: PaaSource[];
+    depth: number;
+    parent_question: string;
+    extracted_at: string;
+}
+type HarvestOptions = z.infer<typeof HarvestOptionsSchema>;
+
+type CanonicalLocationName = string;
+type SerpDevice = 'desktop' | 'mobile';
+type ProxyMode = 'location' | 'configured' | 'none';
+interface \u004b\u0065\u0072\u006e\u0065\u006cLocationProxyTarget {
+    canonicalLocation: CanonicalLocationName;
+    level: 'zip' | 'city' | 'state';
+    country: 'US';
+    state: string;
+    city: string;
+    zip?: string;
+    cityCandidates: string[];
+    proxyName: string;
+    config: {
+        country: 'US';
+        state: string;
+        city?: string;
+        zip?: string;
+    };
+}
+type \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionSource = 'disabled' | 'location_reused' | 'location_created' | 'isp_created' | 'backup_custom' | 'configured_fallback' | 'unavailable';
+interface \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionDebug {
+    source: \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionSource;
+    proxyType: string;
+    proxyMode: ProxyMode;
+    proxyIdPresent: boolean;
+    proxyIdSuffix: string | null;
+    target: \u004b\u0065\u0072\u006e\u0065\u006cLocationProxyTarget | null;
+    error: string | null;
+    disposable?: boolean;
+}
+interface HarvestStats {
+    seed: string;
+    totalQuestions: number;
+    maxDepthReached: number;
+    durationMs: number;
+    errorCount: number;
+}
+type HarvestCompletionStatus = 'paa_found' | 'no_paa' | 'serp_only';
+/**
+ * A completed browser attempt can still be unsuitable for programmatic use.
+ * This is deliberately separate from completionStatus so a valid no-PAA
+ * response with organic results is not confused with an unreadable SERP.
+ */
+type HarvestResultQuality = 'complete' | 'partial' | 'degraded';
+type HarvestDegradationReason = 'empty_primary_serp' | 'page_two_missing';
+type HarvestDiagnosticWarningCode = 'short_videos_captcha_skipped' | 'paa_partial';
+type HarvestDiagnosticWarningSurface = 'short_videos' | 'paa';
+interface HarvestDiagnosticWarning {
+    code: HarvestDiagnosticWarningCode;
+    surface: HarvestDiagnosticWarningSurface;
+    message: string;
+    retryable: boolean;
+}
+interface HarvestCompleteness {
+    paaWithoutAnswer: number;
+    paaWithoutSource: number;
+    paaAnswersRecovered: number;
+    aioShareCaptured: boolean | null;
+    paaRequested?: number;
+    paaReturned?: number;
+    paaUnique?: number;
+}
+type HarvestInterruptionCode = 'browser_session_interrupted' | 'request_aborted' | 'timeout';
+type HarvestInterruptionReasonSource = 'client_runtime' | 'extractor';
+interface HarvestInterruptionDiagnostic {
+    code: HarvestInterruptionCode;
+    reasonSource: HarvestInterruptionReasonSource;
+    message: string | null;
+}
+/** Observed organic pagination outcome; page two never expands a separate PAA graph. */
+interface HarvestPaginationDiagnostics {
+    requestedPages: 1 | 2;
+    capturedPages: 1 | 2;
+    page2Status: 'not_requested' | 'not_attempted' | 'captured' | 'unavailable' | 'failed';
+    page1OrganicCount: number;
+    page2OrganicCount: number;
+    failureCode?: 'missing_next' | 'invalid_next' | 'empty_page' | 'captcha' | 'timeout' | 'navigation_error' | 'unsupported_driver';
+}
 interface HarvestDiagnostics {
     phaseTimings?: {
         providerConnectMs?: number;
@@ -265,7 +339,7 @@ interface BrowserNetworkLocationDebug {
     timezone: string | null;
     error: string | null;
 }
-interface KernelSessionDebug {
+interface \u004b\u0065\u0072\u006e\u0065\u006cSessionDebug {
     sessionId: string | null;
     proxyMode: ProxyMode;
     requestedProxyIdPresent: boolean;
@@ -277,7 +351,7 @@ interface KernelSessionDebug {
     retrievedProxyIdMatchesRequested: boolean | null;
     defaultProxyDisabled: boolean | null;
     defaultProxyDisableError: string | null;
-    proxyResolution: KernelProxyResolutionDebug | null;
+    proxyResolution: \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionDebug | null;
     timeoutSeconds: number | null;
     stealth: boolean | null;
     profilePresent: boolean | null;
@@ -307,7 +381,7 @@ interface SerpNavigationDebug {
     redirected: boolean | null;
 }
 interface BrowserDebugSnapshot {
-    kernel: KernelSessionDebug | null;
+    \u006b\u0065\u0072\u006e\u0065\u006c: \u004b\u0065\u0072\u006e\u0065\u006cSessionDebug | null;
     context: BrowserContextDebug | null;
     networkLocation: BrowserNetworkLocationDebug | null;
     serpNavigation: SerpNavigationDebug | null;
@@ -358,39 +432,6 @@ interface SerpOutboundLink {
     linkType: SerpLinkType;
     resolutionStatus: SerpLinkResolutionStatus;
 }
-interface PaaSource extends SerpOutboundLink {
-    title: string | null;
-    site: string | null;
-}
-interface PAANode {
-    questionId: string;
-    googleLinkId: string | null;
-    googleEvidenceId: string | null;
-    question: string;
-    answer: string | null;
-    sourceTitle: string | null;
-    sourceSite: string | null;
-    sourceCite: string | null;
-    sources: PaaSource[];
-    depth: number;
-    parentQuestion: string | null;
-    children: PAANode[];
-}
-interface FlatRow {
-    seed_query: string;
-    question_id: string;
-    google_link_id: string;
-    google_evidence_id: string;
-    question: string;
-    answer: string;
-    source_title: string;
-    source_site: string;
-    source_cite: string;
-    sources: PaaSource[];
-    depth: number;
-    parent_question: string;
-    extracted_at: string;
-}
 interface VideoResult {
     type: 'video' | 'short_video';
     title: string;
@@ -495,9 +536,9 @@ interface HarvestResult {
     organicResults: OrganicResult[];
     localPack: LocalPackBusiness[];
     entityIds: EntityIds;
+    fullSerpFeatures?: FullSerpFeatures;
     stats: HarvestStats;
 }
-type HarvestOptions = z.infer<typeof HarvestOptionsSchema>;
 
 declare function harvest(rawOptions: unknown): Promise<HarvestResult>;
 

package/dist/index.d.ts

@@ -1,5 +1,44 @@
 import { z } from 'zod';
 
+declare const SERP_FEATURE_COMPLETENESS_STATES: readonly ["observed_present", "observed_absent", "incomplete", "not_requested", "unknown", "unsupported"];
+type SerpFeatureCompletenessState = typeof SERP_FEATURE_COMPLETENESS_STATES[number];
+
+interface SerpPreviewQuestion {
+    question: string;
+    answer: string | null;
+    url: string | null;
+}
+interface SerpFeatureItem {
+    title: string | null;
+    url: string | null;
+    description: string | null;
+    position: number | null;
+}
+interface SerpFeatureGroup {
+    name: string;
+    attributes: Record<string, string | number | boolean | null>;
+    items: SerpFeatureItem[];
+}
+interface FullSerpPageFeatures {
+    page: 1 | 2;
+    status: Record<string, SerpFeatureCompletenessState>;
+    paaPreview: SerpPreviewQuestion[];
+    additional: SerpFeatureGroup[];
+    localPack: LocalPackBusiness[];
+    forums: ForumResult[];
+    videos: VideoResult[];
+    whatPeopleSaying: WhatPeopleSayingCard[];
+    aiOverview: AIOverviewResult;
+    aiMode: AIModeResult;
+    entityIds: EntityIds;
+}
+interface FullSerpFeatures {
+    status: Record<string, SerpFeatureCompletenessState>;
+    paaPreview: SerpPreviewQuestion[];
+    additional: SerpFeatureGroup[];
+    pages: FullSerpPageFeatures[];
+}
+
 declare const HarvestOptionsSchema: z.ZodObject<{
     query: z.ZodString;
     location: z.ZodOptional<z.ZodString>;
@@ -24,13 +63,13 @@ declare const HarvestOptionsSchema: z.ZodObject<{
     headless: z.ZodDefault<z.ZodBoolean>;
     profileDir: z.ZodOptional<z.ZodString>;
     proxy: z.ZodOptional<z.ZodString>;
-    kernelApiKey: z.ZodOptional<z.ZodString>;
-    kernelProxyId: z.ZodOptional<z.ZodString>;
-    kernelProfileName: z.ZodOptional<z.ZodString>;
-    kernelProfileSaveChanges: z.ZodOptional<z.ZodBoolean>;
-    kernelStealth: z.ZodOptional<z.ZodBoolean>;
+    \u006b\u0065\u0072\u006e\u0065\u006cApiKey: z.ZodOptional<z.ZodString>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProxyId: z.ZodOptional<z.ZodString>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProfileName: z.ZodOptional<z.ZodString>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProfileSaveChanges: z.ZodOptional<z.ZodBoolean>;
+    \u006b\u0065\u0072\u006e\u0065\u006cStealth: z.ZodOptional<z.ZodBoolean>;
     serpIdentity: z.ZodOptional<z.ZodString>;
-    kernelProxyResolution: z.ZodOptional<z.ZodUnknown>;
+    \u006b\u0065\u0072\u006e\u0065\u006cProxyResolution: z.ZodOptional<z.ZodUnknown>;
     outputDir: z.ZodDefault<z.ZodString>;
     format: z.ZodDefault<z.ZodEnum<{
         json: "json";
@@ -57,75 +96,6 @@ declare const HarvestOptionsSchema: z.ZodObject<{
     softDeadlineMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 
-type CanonicalLocationName = string;
-type SerpDevice = 'desktop' | 'mobile';
-type ProxyMode = 'location' | 'configured' | 'none';
-interface KernelLocationProxyTarget {
-    canonicalLocation: CanonicalLocationName;
-    level: 'zip' | 'city' | 'state';
-    country: 'US';
-    state: string;
-    city: string;
-    zip?: string;
-    cityCandidates: string[];
-    proxyName: string;
-    config: {
-        country: 'US';
-        state: string;
-        city?: string;
-        zip?: string;
-    };
-}
-type KernelProxyResolutionSource = 'disabled' | 'location_reused' | 'location_created' | 'isp_created' | 'backup_custom' | 'configured_fallback' | 'unavailable';
-interface KernelProxyResolutionDebug {
-    source: KernelProxyResolutionSource;
-    proxyType: string;
-    proxyMode: ProxyMode;
-    proxyIdPresent: boolean;
-    proxyIdSuffix: string | null;
-    target: KernelLocationProxyTarget | null;
-    error: string | null;
-    disposable?: boolean;
-}
-interface HarvestStats {
-    seed: string;
-    totalQuestions: number;
-    maxDepthReached: number;
-    durationMs: number;
-    errorCount: number;
-}
-type HarvestCompletionStatus = 'paa_found' | 'no_paa' | 'serp_only';
-/**
- * A completed browser attempt can still be unsuitable for programmatic use.
- * This is deliberately separate from completionStatus so a valid no-PAA
- * response with organic results is not confused with an unreadable SERP.
- */
-type HarvestResultQuality = 'complete' | 'partial' | 'degraded';
-type HarvestDegradationReason = 'empty_primary_serp';
-type HarvestDiagnosticWarningCode = 'short_videos_captcha_skipped' | 'paa_partial';
-type HarvestDiagnosticWarningSurface = 'short_videos' | 'paa';
-interface HarvestDiagnosticWarning {
-    code: HarvestDiagnosticWarningCode;
-    surface: HarvestDiagnosticWarningSurface;
-    message: string;
-    retryable: boolean;
-}
-interface HarvestCompleteness {
-    paaWithoutAnswer: number;
-    paaWithoutSource: number;
-    paaAnswersRecovered: number;
-    aioShareCaptured: boolean | null;
-    paaRequested?: number;
-    paaReturned?: number;
-    paaUnique?: number;
-}
-type HarvestInterruptionCode = 'browser_session_interrupted' | 'request_aborted' | 'timeout';
-type HarvestInterruptionReasonSource = 'client_runtime' | 'extractor';
-interface HarvestInterruptionDiagnostic {
-    code: HarvestInterruptionCode;
-    reasonSource: HarvestInterruptionReasonSource;
-    message: string | null;
-}
 type PaaDiscoveryStatus = 'in_progress' | 'target_reached' | 'frontier_exhausted' | 'no_paa_observed' | 'interrupted' | 'recovery_exhausted';
 type PaaTargetStatus = 'met' | 'not_met';
 type PaaMaterialStatus = 'complete' | 'partial';
@@ -185,15 +155,6 @@ interface PaaInteractionObservation {
     errorCode: 'click_failed' | 'click_ack_timeout' | 'control_missing' | 'confirmation_timeout' | null;
 }
 type PaaProgressPhase = 'serp_captured' | 'discovered' | 'click_observed' | 'answer_captured' | 'fill_incomplete' | 'expansion_finished' | 'attempt_ending';
-/** Observed organic pagination outcome; page two never expands a separate PAA graph. */
-interface HarvestPaginationDiagnostics {
-    requestedPages: 1 | 2;
-    capturedPages: 1 | 2;
-    page2Status: 'not_requested' | 'not_attempted' | 'captured' | 'unavailable' | 'failed';
-    page1OrganicCount: number;
-    page2OrganicCount: number;
-    failureCode?: 'missing_next' | 'invalid_next' | 'empty_page' | 'captcha' | 'timeout' | 'navigation_error' | 'unsupported_driver';
-}
 /** Material already observed before PAA expansion completes. It is checkpointed
  * so a worker interruption cannot discard the SERP that led to the PAA graph. */
 interface PaaProgressMaterial {
@@ -218,6 +179,119 @@ interface PaaProgressSnapshot {
     material?: PaaProgressMaterial;
     interactions?: PaaInteractionObservation[];
 }
+interface PaaSource extends SerpOutboundLink {
+    title: string | null;
+    site: string | null;
+}
+interface PAANode {
+    questionId: string;
+    googleLinkId: string | null;
+    googleEvidenceId: string | null;
+    question: string;
+    answer: string | null;
+    sourceTitle: string | null;
+    sourceSite: string | null;
+    sourceCite: string | null;
+    sources: PaaSource[];
+    depth: number;
+    parentQuestion: string | null;
+    children: PAANode[];
+}
+interface FlatRow {
+    seed_query: string;
+    question_id: string;
+    google_link_id: string;
+    google_evidence_id: string;
+    question: string;
+    answer: string;
+    source_title: string;
+    source_site: string;
+    source_cite: string;
+    sources: PaaSource[];
+    depth: number;
+    parent_question: string;
+    extracted_at: string;
+}
+type HarvestOptions = z.infer<typeof HarvestOptionsSchema>;
+
+type CanonicalLocationName = string;
+type SerpDevice = 'desktop' | 'mobile';
+type ProxyMode = 'location' | 'configured' | 'none';
+interface \u004b\u0065\u0072\u006e\u0065\u006cLocationProxyTarget {
+    canonicalLocation: CanonicalLocationName;
+    level: 'zip' | 'city' | 'state';
+    country: 'US';
+    state: string;
+    city: string;
+    zip?: string;
+    cityCandidates: string[];
+    proxyName: string;
+    config: {
+        country: 'US';
+        state: string;
+        city?: string;
+        zip?: string;
+    };
+}
+type \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionSource = 'disabled' | 'location_reused' | 'location_created' | 'isp_created' | 'backup_custom' | 'configured_fallback' | 'unavailable';
+interface \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionDebug {
+    source: \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionSource;
+    proxyType: string;
+    proxyMode: ProxyMode;
+    proxyIdPresent: boolean;
+    proxyIdSuffix: string | null;
+    target: \u004b\u0065\u0072\u006e\u0065\u006cLocationProxyTarget | null;
+    error: string | null;
+    disposable?: boolean;
+}
+interface HarvestStats {
+    seed: string;
+    totalQuestions: number;
+    maxDepthReached: number;
+    durationMs: number;
+    errorCount: number;
+}
+type HarvestCompletionStatus = 'paa_found' | 'no_paa' | 'serp_only';
+/**
+ * A completed browser attempt can still be unsuitable for programmatic use.
+ * This is deliberately separate from completionStatus so a valid no-PAA
+ * response with organic results is not confused with an unreadable SERP.
+ */
+type HarvestResultQuality = 'complete' | 'partial' | 'degraded';
+type HarvestDegradationReason = 'empty_primary_serp' | 'page_two_missing';
+type HarvestDiagnosticWarningCode = 'short_videos_captcha_skipped' | 'paa_partial';
+type HarvestDiagnosticWarningSurface = 'short_videos' | 'paa';
+interface HarvestDiagnosticWarning {
+    code: HarvestDiagnosticWarningCode;
+    surface: HarvestDiagnosticWarningSurface;
+    message: string;
+    retryable: boolean;
+}
+interface HarvestCompleteness {
+    paaWithoutAnswer: number;
+    paaWithoutSource: number;
+    paaAnswersRecovered: number;
+    aioShareCaptured: boolean | null;
+    paaRequested?: number;
+    paaReturned?: number;
+    paaUnique?: number;
+}
+type HarvestInterruptionCode = 'browser_session_interrupted' | 'request_aborted' | 'timeout';
+type HarvestInterruptionReasonSource = 'client_runtime' | 'extractor';
+interface HarvestInterruptionDiagnostic {
+    code: HarvestInterruptionCode;
+    reasonSource: HarvestInterruptionReasonSource;
+    message: string | null;
+}
+/** Observed organic pagination outcome; page two never expands a separate PAA graph. */
+interface HarvestPaginationDiagnostics {
+    requestedPages: 1 | 2;
+    capturedPages: 1 | 2;
+    page2Status: 'not_requested' | 'not_attempted' | 'captured' | 'unavailable' | 'failed';
+    page1OrganicCount: number;
+    page2OrganicCount: number;
+    failureCode?: 'missing_next' | 'invalid_next' | 'empty_page' | 'captcha' | 'timeout' | 'navigation_error' | 'unsupported_driver';
+}
 interface HarvestDiagnostics {
     phaseTimings?: {
         providerConnectMs?: number;
@@ -265,7 +339,7 @@ interface BrowserNetworkLocationDebug {
     timezone: string | null;
     error: string | null;
 }
-interface KernelSessionDebug {
+interface \u004b\u0065\u0072\u006e\u0065\u006cSessionDebug {
     sessionId: string | null;
     proxyMode: ProxyMode;
     requestedProxyIdPresent: boolean;
@@ -277,7 +351,7 @@ interface KernelSessionDebug {
     retrievedProxyIdMatchesRequested: boolean | null;
     defaultProxyDisabled: boolean | null;
     defaultProxyDisableError: string | null;
-    proxyResolution: KernelProxyResolutionDebug | null;
+    proxyResolution: \u004b\u0065\u0072\u006e\u0065\u006cProxyResolutionDebug | null;
     timeoutSeconds: number | null;
     stealth: boolean | null;
     profilePresent: boolean | null;
@@ -307,7 +381,7 @@ interface SerpNavigationDebug {
     redirected: boolean | null;
 }
 interface BrowserDebugSnapshot {
-    kernel: KernelSessionDebug | null;
+    \u006b\u0065\u0072\u006e\u0065\u006c: \u004b\u0065\u0072\u006e\u0065\u006cSessionDebug | null;
     context: BrowserContextDebug | null;
     networkLocation: BrowserNetworkLocationDebug | null;
     serpNavigation: SerpNavigationDebug | null;
@@ -358,39 +432,6 @@ interface SerpOutboundLink {
     linkType: SerpLinkType;
     resolutionStatus: SerpLinkResolutionStatus;
 }
-interface PaaSource extends SerpOutboundLink {
-    title: string | null;
-    site: string | null;
-}
-interface PAANode {
-    questionId: string;
-    googleLinkId: string | null;
-    googleEvidenceId: string | null;
-    question: string;
-    answer: string | null;
-    sourceTitle: string | null;
-    sourceSite: string | null;
-    sourceCite: string | null;
-    sources: PaaSource[];
-    depth: number;
-    parentQuestion: string | null;
-    children: PAANode[];
-}
-interface FlatRow {
-    seed_query: string;
-    question_id: string;
-    google_link_id: string;
-    google_evidence_id: string;
-    question: string;
-    answer: string;
-    source_title: string;
-    source_site: string;
-    source_cite: string;
-    sources: PaaSource[];
-    depth: number;
-    parent_question: string;
-    extracted_at: string;
-}
 interface VideoResult {
     type: 'video' | 'short_video';
     title: string;
@@ -495,9 +536,9 @@ interface HarvestResult {
     organicResults: OrganicResult[];
     localPack: LocalPackBusiness[];
     entityIds: EntityIds;
+    fullSerpFeatures?: FullSerpFeatures;
     stats: HarvestStats;
 }
-type HarvestOptions = z.infer<typeof HarvestOptionsSchema>;
 
 declare function harvest(rawOptions: unknown): Promise<HarvestResult>;