/**
 * Link Relation Discovery (D-003)
 *
 * Discovers APIs through multiple link-based mechanisms:
 * - RFC 8288 Link response headers
 * - HTML <link> elements
 * - HATEOAS hypermedia formats (HAL, JSON:API, Siren)
 *
 * Common link relations for API discovery:
 * - describedby: Points to API documentation (OpenAPI, etc.)
 * - service: Points to API service endpoint
 * - api: Points to API endpoint
 * - alternate (type=application/json): JSON version of resource
 */
import type { LearnedApiPattern } from '../types/api-patterns.js';
/**
 * Standard link relations relevant for API discovery
 * Based on IANA Link Relations registry
 */
export type ApiLinkRelation = 'describedby' | 'service' | 'api' | 'alternate' | 'collection' | 'item' | 'self' | 'next' | 'prev' | 'first' | 'last' | 'search' | 'edit' | 'create-form' | 'edit-form';
/**
 * A discovered link from headers, HTML, or hypermedia
 */
export interface DiscoveredLink {
    /** The URL this link points to */
    href: string;
    /** Link relation type */
    rel: string;
    /** MIME type (if specified) */
    type?: string;
    /** Title (if specified) */
    title?: string;
    /** Language (if specified) */
    hreflang?: string;
    /** Media query (if specified) */
    media?: string;
    /** Source of this link */
    source: 'header' | 'html' | 'hateoas';
    /** Hypermedia format if from HATEOAS */
    hypermediaFormat?: HypermediaFormat;
    /** Whether this link likely points to an API */
    isApiLink: boolean;
    /** Confidence that this is a useful API link (0-1) */
    confidence: number;
}
/**
 * Hypermedia formats for HATEOAS detection
 */
export type HypermediaFormat = 'hal' | 'json-api' | 'siren' | 'collection+json' | 'hydra' | 'unknown';
/**
 * Result of link discovery
 */
export interface LinkDiscoveryResult {
    /** Whether any links were found */
    found: boolean;
    /** All discovered links */
    links: DiscoveredLink[];
    /** Links that are likely API endpoints */
    apiLinks: DiscoveredLink[];
    /** Links that point to API documentation */
    documentationLinks: DiscoveredLink[];
    /** Detected hypermedia format (if any) */
    hypermediaFormat?: HypermediaFormat;
    /** Pagination links (if found) */
    paginationLinks?: {
        next?: string;
        prev?: string;
        first?: string;
        last?: string;
    };
    /** Discovery time in ms */
    discoveryTime: number;
    /** Error message if discovery failed */
    error?: string;
}
/**
 * Options for link discovery
 */
export interface LinkDiscoveryOptions {
    /** Custom fetch function */
    fetchFn?: (url: string, init?: RequestInit) => Promise<Response>;
    /** Headers to send with requests */
    headers?: Record<string, string>;
    /** Follow links to discover more (depth limit) */
    maxDepth?: number;
    /** Timeout in ms */
    timeout?: number;
    /** Base URL for resolving relative links */
    baseUrl?: string;
    /** HTML content to parse (if already fetched) */
    htmlContent?: string;
    /** Response headers to parse (if already fetched) */
    responseHeaders?: Headers | Record<string, string>;
    /** JSON response to parse for HATEOAS (if already fetched) */
    jsonResponse?: unknown;
}
/**
 * Parse RFC 8288 Link header value
 *
 * Format: <url>; rel="relation"; type="mime/type"; title="title"
 * Multiple links separated by commas
 *
 * Example:
 *   Link: </api/openapi.json>; rel="describedby"; type="application/json"
 *   Link: </api/users?page=2>; rel="next", </api/users?page=1>; rel="prev"
 */
export declare function parseLinkHeader(headerValue: string, baseUrl?: string): DiscoveredLink[];
/**
 * Extract <link> elements from HTML
 *
 * Looks for:
 * - <link rel="api" href="/api">
 * - <link rel="alternate" type="application/json" href="/api/posts.json">
 * - <link rel="describedby" href="/swagger.json">
 */
export declare function extractHtmlLinks(html: string, baseUrl?: string): DiscoveredLink[];
/**
 * Detect hypermedia format from JSON response
 */
export declare function detectHypermediaFormat(json: unknown): HypermediaFormat | null;
/**
 * Extract links from HAL JSON response
 */
export declare function extractHalLinks(json: unknown, baseUrl?: string): DiscoveredLink[];
/**
 * Extract links from JSON:API response
 */
export declare function extractJsonApiLinks(json: unknown, baseUrl?: string): DiscoveredLink[];
/**
 * Extract links from Siren response
 */
export declare function extractSirenLinks(json: unknown, baseUrl?: string): DiscoveredLink[];
/**
 * Extract links from Collection+JSON response (RFC 6573)
 */
export declare function extractCollectionJsonLinks(json: unknown, baseUrl?: string): DiscoveredLink[];
/**
 * Extract links from Hydra (JSON-LD) response
 */
export declare function extractHydraLinks(json: unknown, baseUrl?: string): DiscoveredLink[];
/**
 * Extract links from any detected hypermedia format
 */
export declare function extractHateoasLinks(json: unknown, baseUrl?: string): DiscoveredLink[];
/**
 * Filter links to those most likely to be API-related
 */
export declare function filterApiLinks(links: DiscoveredLink[]): DiscoveredLink[];
/**
 * Filter links that point to API documentation
 */
export declare function filterDocumentationLinks(links: DiscoveredLink[]): DiscoveredLink[];
/**
 * Extract pagination links from a set of links
 */
export declare function extractPaginationLinks(links: DiscoveredLink[]): LinkDiscoveryResult['paginationLinks'];
/**
 * Discover links from a URL or pre-fetched content
 *
 * Can work with:
 * 1. A URL - fetches and parses headers, HTML, JSON
 * 2. Pre-fetched content - parses headers, HTML, JSON passed in options
 */
export declare function discoverLinks(url: string, options?: LinkDiscoveryOptions): Promise<LinkDiscoveryResult>;
/**
 * Convert discovered API links to LearnedApiPattern format
 */
export declare function generatePatternsFromLinks(links: DiscoveredLink[], domain: string): LearnedApiPattern[];
//# sourceMappingURL=link-discovery.d.ts.map