/**
 * API Documentation Page Discovery (D-002)
 *
 * Discovers and parses human-readable API documentation pages.
 * Finds API docs at common locations (/docs, /developers, /api-reference),
 * detects documentation frameworks (ReadMe, Slate, Docusaurus, Swagger UI, Redoc),
 * and extracts endpoint information from HTML documentation.
 */
import type { LearnedApiPattern } from '../types/api-patterns.js';
/**
 * A parameter documented in an API endpoint
 */
export interface DocumentedParam {
    name: string;
    type: string;
    required: boolean;
    description?: string;
    location: 'path' | 'query' | 'header' | 'body';
    defaultValue?: string;
}
/**
 * An API endpoint extracted from documentation
 */
export interface DocumentedEndpoint {
    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
    path: string;
    parameters: DocumentedParam[];
    exampleRequest?: string;
    exampleResponse?: string;
    description: string;
    authentication?: string;
    rateLimit?: string;
    /** Source of discovery (e.g., endpoint table, code block) */
    source: 'table' | 'code-block' | 'navigation' | 'heading';
    /** Confidence in the extraction (0-1) */
    confidence: number;
}
/**
 * Detected documentation framework
 */
export type DocFramework = 'readme' | 'slate' | 'docusaurus' | 'swagger-ui' | 'redoc' | 'gitbook' | 'mintlify' | 'stoplight' | 'unknown';
/**
 * Result of documentation page discovery
 */
export interface DocsDiscoveryResult {
    found: boolean;
    docsUrl?: string;
    framework?: DocFramework;
    endpoints: DocumentedEndpoint[];
    /** Navigation links found pointing to API docs */
    navigationLinks: string[];
    /** Title of the documentation */
    title?: string;
    /** Base URL for API calls if detected */
    apiBaseUrl?: string;
    /** Authentication instructions if found */
    authInstructions?: string;
    /** Time taken to discover in ms */
    discoveryTime: number;
    error?: string;
}
/**
 * Options for docs discovery
 */
export interface DocsDiscoveryOptions {
    /** Custom headers to send with requests */
    headers?: Record<string, string>;
    /** Custom fetch function for testing */
    fetchFn?: (url: string, init?: RequestInit) => Promise<Response>;
    /** Timeout in ms (default: 10000) */
    timeout?: number;
    /** Maximum pages to probe (default: 10) */
    maxProbes?: number;
    /** Whether to follow navigation links (default: true) */
    followNavigation?: boolean;
}
/**
 * Common locations for API documentation
 */
export declare const DOCS_PROBE_LOCATIONS: readonly ["/docs", "/documentation", "/api-docs", "/api/docs", "/developers", "/developer", "/dev", "/api", "/api/v1", "/api/v2", "/reference", "/api-reference", "/help/api", "/support/api", "/docs/api", "/docs/reference"];
/**
 * Detect which documentation framework a page uses
 */
export declare function detectDocFramework(html: string): DocFramework;
/**
 * Extract navigation links from common nav structures
 */
export declare function extractNavigationLinks(html: string, baseUrl: string): string[];
/**
 * Extract API endpoints from HTML tables
 */
export declare function extractEndpointsFromTables(html: string): DocumentedEndpoint[];
/**
 * Extract API endpoints from code blocks
 */
export declare function extractEndpointsFromCodeBlocks(html: string): DocumentedEndpoint[];
/**
 * Extract endpoints from headings (## GET /api/users style)
 */
export declare function extractEndpointsFromHeadings(html: string): DocumentedEndpoint[];
/**
 * Extract API base URL from documentation
 */
export declare function extractApiBaseUrl(html: string, pageUrl: string): string | undefined;
/**
 * Extract authentication instructions
 */
export declare function extractAuthInstructions(html: string): string | undefined;
/**
 * Parse documentation page and extract all information
 */
export declare function parseDocsPage(html: string, pageUrl: string): Omit<DocsDiscoveryResult, 'found' | 'discoveryTime' | 'docsUrl'>;
/**
 * Discover API documentation for a domain
 */
export declare function discoverDocs(domain: string, options?: DocsDiscoveryOptions): Promise<DocsDiscoveryResult>;
/**
 * Generate API patterns from discovered documentation
 */
export declare function generatePatternsFromDocs(result: DocsDiscoveryResult, domain: string): LearnedApiPattern[];
//# sourceMappingURL=docs-page-discovery.d.ts.map