/**
 * API Documentation Discovery Orchestrator (D-008)
 *
 * Unified pipeline that orchestrates all API discovery methods:
 * - OpenAPI/Swagger specification discovery
 * - GraphQL introspection
 * - (Future) Link relation discovery (RFC 8288)
 * - (Future) Documentation page parsing
 * - (Future) AsyncAPI discovery
 *
 * Features:
 * - Parallel discovery across all methods
 * - Result caching with configurable TTL
 * - Pattern deduplication and merging
 * - Priority-based result ordering
 */
import { type GraphQLDiscoveryResult, type GraphQLQueryPattern } from './graphql-introspection.js';
import { type LinkDiscoveryResult } from './link-discovery.js';
import { type DocsDiscoveryResult } from './docs-page-discovery.js';
import { type AsyncAPIDiscoveryResult } from './asyncapi-discovery.js';
import { type AltSpecDiscoveryResult } from './alt-spec-discovery.js';
import { type RobotsSitemapDiscoveryResult } from './robots-sitemap-discovery.js';
import { type BackendFrameworkDiscoveryResult } from './backend-framework-fingerprinting.js';
import type { LearnedApiPattern, ParsedOpenAPISpec } from '../types/api-patterns.js';
/**
 * Source of the discovered API documentation
 */
export type DiscoverySource = 'openapi' | 'graphql' | 'docs-page' | 'links' | 'asyncapi' | 'alt-spec' | 'robots-sitemap' | 'backend-framework' | 'raml' | 'observed';
/**
 * Rate limit information extracted from API documentation
 */
export interface RateLimitInfo {
    /** Requests allowed per window */
    requests: number;
    /** Time window in seconds */
    windowSeconds: number;
    /** Header name for remaining requests */
    remainingHeader?: string;
    /** Header name for reset time */
    resetHeader?: string;
}
/**
 * Authentication information extracted from API documentation
 */
export interface AuthInfo {
    /** Authentication type */
    type: 'api_key' | 'bearer' | 'basic' | 'oauth2' | 'cookie';
    /** Where the credential goes */
    in?: 'header' | 'query' | 'cookie';
    /** Header/query param name */
    name?: string;
    /** OAuth2 flow type */
    oauthFlow?: 'authorization_code' | 'client_credentials' | 'implicit' | 'password';
    /** OAuth2 URLs */
    oauthUrls?: {
        authorizationUrl?: string;
        tokenUrl?: string;
        refreshUrl?: string;
        scopes?: Record<string, string>;
    };
}
/**
 * Metadata extracted from API documentation
 */
export interface DiscoveryMetadata {
    /** API version string */
    specVersion?: string;
    /** Rate limit information */
    rateLimit?: RateLimitInfo;
    /** Authentication requirements */
    authentication?: AuthInfo[];
    /** Base URL for the API */
    baseUrl?: string;
    /** API title/name */
    title?: string;
    /** API description */
    description?: string;
}
/**
 * Result from a single discovery source
 */
export interface DiscoveryResult {
    /** Source of this discovery */
    source: DiscoverySource;
    /** Confidence in this discovery (0-1) */
    confidence: number;
    /** Discovered patterns (empty if none found) */
    patterns: LearnedApiPattern[];
    /** Extracted metadata */
    metadata: DiscoveryMetadata;
    /** Time taken for discovery (ms) */
    discoveryTime: number;
    /** Whether this source found anything */
    found: boolean;
    /** Error message if discovery failed */
    error?: string;
    /** Raw source data for debugging */
    rawData?: {
        openapi?: ParsedOpenAPISpec;
        graphql?: GraphQLDiscoveryResult;
        links?: LinkDiscoveryResult;
        docs?: DocsDiscoveryResult;
        asyncapi?: AsyncAPIDiscoveryResult;
        altSpec?: AltSpecDiscoveryResult;
        robotsSitemap?: RobotsSitemapDiscoveryResult;
        backendFramework?: BackendFrameworkDiscoveryResult;
    };
}
/**
 * Aggregated results from all discovery sources
 */
export interface AggregatedDiscoveryResult {
    /** Domain that was discovered */
    domain: string;
    /** All discovery results, ordered by priority/confidence */
    results: DiscoveryResult[];
    /** Combined patterns from all sources (deduplicated) */
    allPatterns: LearnedApiPattern[];
    /** Best metadata (from highest confidence source) */
    metadata: DiscoveryMetadata;
    /** Total discovery time */
    totalTime: number;
    /** Whether any source found documentation */
    found: boolean;
    /** When this result was cached */
    cachedAt?: number;
}
/**
 * Options for discovery orchestration
 */
export interface DiscoveryOptions {
    /** Custom headers for requests */
    headers?: Record<string, string>;
    /** Timeout per source (ms) */
    timeout?: number;
    /** Skip specific sources */
    skipSources?: DiscoverySource[];
    /** Custom fetch function */
    fetchFn?: (url: string, init?: RequestInit) => Promise<Response>;
    /** Force fresh discovery (ignore cache) */
    forceRefresh?: boolean;
}
/** Default cache TTL: 1 hour */
export declare const DEFAULT_CACHE_TTL_MS: number;
/** Default timeout per discovery source */
export declare const DEFAULT_SOURCE_TIMEOUT_MS = 30000;
/** Confidence scores for different sources */
export declare const SOURCE_CONFIDENCE: Record<DiscoverySource, number>;
/** Priority order for sources (higher = tried first, results prioritized) */
export declare const SOURCE_PRIORITY: Record<DiscoverySource, number>;
import { type DiscoveryCacheStats } from '../utils/discovery-cache.js';
/**
 * Get cached discovery result if valid
 * Note: The orchestrator caches aggregated results, while individual modules cache their own results
 */
export declare function getCachedDiscovery(domain: string): Promise<AggregatedDiscoveryResult | null>;
/**
 * Cache a discovery result
 */
export declare function cacheDiscovery(domain: string, result: AggregatedDiscoveryResult, ttlMs?: number): Promise<void>;
/**
 * Clear cache for a specific domain or all domains
 */
export declare function clearDiscoveryCache(domain?: string): Promise<void>;
/**
 * Get cache statistics
 */
export declare function getDiscoveryCacheStats(): Promise<{
    size: number;
    domains: string[];
}>;
/**
 * Get unified cache statistics across all discovery sources
 */
export declare function getUnifiedCacheStats(): Promise<DiscoveryCacheStats>;
/**
 * Discover OpenAPI documentation for a domain
 */
declare function discoverOpenAPISource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Discover GraphQL API via introspection
 */
declare function discoverGraphQLSource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Convert a GraphQL pattern to LearnedApiPattern format
 */
declare function convertGraphQLPattern(gqlPattern: GraphQLQueryPattern, domain: string, endpoint: string): LearnedApiPattern;
/**
 * Discover API links via RFC 8288 Link headers, HTML links, and HATEOAS
 */
declare function discoverLinksSource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Discover API documentation pages (HTML docs at /docs, /developers, etc.)
 */
declare function discoverDocsSource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Discover AsyncAPI specification
 */
declare function discoverAsyncAPISource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Discover alternative API specifications (RAML, API Blueprint, WADL)
 */
declare function discoverAltSpecSource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Discover API hints from robots.txt and sitemap.xml
 *
 * This source provides low-confidence hints about potential API paths
 * rather than definitive patterns. Hints can guide further discovery.
 */
declare function discoverRobotsSitemapSource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Discover API patterns from backend framework fingerprinting
 *
 * This source detects backend frameworks (Rails, Django, Phoenix, FastAPI,
 * Spring Boot, Laravel, Express, ASP.NET Core) and suggests convention-based
 * API patterns for each framework.
 */
declare function discoverBackendFrameworkSource(domain: string, options: DiscoveryOptions): Promise<DiscoveryResult>;
/**
 * Run all discovery sources in parallel and aggregate results
 */
export declare function discoverApiDocumentation(domain: string, options?: DiscoveryOptions): Promise<AggregatedDiscoveryResult>;
/**
 * Quick check if a domain has any documented API
 * Returns cached result if available, otherwise runs discovery
 */
export declare function hasDocumentedApi(domain: string, options?: DiscoveryOptions): Promise<boolean>;
/**
 * Get all patterns for a domain from documented sources
 */
export declare function getDocumentedPatterns(domain: string, options?: DiscoveryOptions): Promise<LearnedApiPattern[]>;
/**
 * Get discovery results for a specific source
 */
export declare function getDiscoveryBySource(domain: string, source: DiscoverySource, options?: DiscoveryOptions): Promise<DiscoveryResult | null>;
export { discoverOpenAPISource, discoverGraphQLSource, discoverLinksSource, discoverDocsSource, discoverAsyncAPISource, discoverAltSpecSource, discoverRobotsSitemapSource, discoverBackendFrameworkSource, convertGraphQLPattern, };
export type { LinkDiscoveryResult, DiscoveredLink, } from './link-discovery.js';
export type { DocsDiscoveryResult, DocumentedEndpoint, DocFramework, } from './docs-page-discovery.js';
export type { AsyncAPIDiscoveryResult, ParsedAsyncAPISpec, AsyncAPIChannel, AsyncAPIServer, AsyncAPIProtocol, AsyncAPIPattern, } from './asyncapi-discovery.js';
export type { AltSpecDiscoveryResult, ParsedAltSpec, AltSpecFormat, AltSpecEndpoint, AltSpecDiscoveryOptions, } from './alt-spec-discovery.js';
export type { RobotsSitemapDiscoveryResult, ApiHint, ParsedRobotsTxt, ParsedSitemap, SitemapEntry, RobotsSitemapDiscoveryOptions, } from './robots-sitemap-discovery.js';
export type { BackendFrameworkDiscoveryResult, BackendFramework, FrameworkFingerprintResult, FrameworkEvidence, FrameworkApiPattern, FingerprintOptions, } from './backend-framework-fingerprinting.js';
//# sourceMappingURL=api-documentation-discovery.d.ts.map