/**
 * API Versioning
 *
 * Comprehensive API version management with support for multiple
 * versioning strategies and migration helpers.
 *
 * @module api/advanced/api-versioning
 */
/**
 * API versioning strategy.
 */
export type VersioningStrategy = 'url' | 'header' | 'query' | 'accept';
/**
 * Version format configuration.
 */
export interface VersionFormat {
    /** Version prefix (e.g., 'v') */
    prefix?: string;
    /** Version separator for header-based (e.g., '.') */
    separator?: string;
    /** Date format for date-based versioning */
    dateFormat?: string;
}
/**
 * Version compatibility status.
 */
export type VersionStatus = 'current' | 'supported' | 'deprecated' | 'unsupported';
/**
 * API version definition.
 */
export interface APIVersion {
    /** Version identifier */
    version: string;
    /** Semantic version number */
    semver?: string;
    /** Version status */
    status: VersionStatus;
    /** Release date */
    releasedAt?: string;
    /** Deprecation date */
    deprecatedAt?: string;
    /** Sunset date (when version will be removed) */
    sunsetAt?: string;
    /** Breaking changes in this version */
    breakingChanges?: string[];
    /** New features in this version */
    features?: string[];
    /** Migration notes */
    migrationNotes?: string;
    /** Changelog URL */
    changelogUrl?: string;
}
/**
 * Version manager configuration.
 */
export interface VersionManagerConfig {
    /** Versioning strategy */
    strategy: VersioningStrategy;
    /** Current/default version */
    currentVersion: string;
    /** Supported versions */
    supportedVersions: APIVersion[];
    /** Header name for header-based versioning */
    headerName?: string;
    /** Query parameter name for query-based versioning */
    queryParam?: string;
    /** Accept header media type prefix */
    acceptPrefix?: string;
    /** Version format configuration */
    format?: VersionFormat;
    /** Callback when using deprecated version */
    onDeprecatedVersion?: (version: string, info: APIVersion) => void;
    /** Callback when using unsupported version */
    onUnsupportedVersion?: (version: string) => void;
}
/**
 * Version transform function for request migration.
 */
export type VersionTransform<T = unknown> = (data: T, fromVersion: string, toVersion: string) => T;
/**
 * Response migration configuration.
 */
export interface ResponseMigration<T = unknown> {
    /** Source version */
    fromVersion: string;
    /** Target version */
    toVersion: string;
    /** Transform function */
    transform: VersionTransform<T>;
}
/**
 * API Version Manager for handling API versioning.
 *
 * @example
 * ```typescript
 * const versionManager = new VersionManager({
 *   strategy: 'header',
 *   currentVersion: 'v2',
 *   supportedVersions: [
 *     { version: 'v2', status: 'current' },
 *     { version: 'v1', status: 'deprecated', sunsetAt: '2024-12-31' },
 *   ],
 * });
 *
 * // Apply version to request
 * const headers = versionManager.getVersionHeaders('v2');
 * const url = versionManager.getVersionedUrl('/users', 'v2');
 *
 * // Check version status
 * if (versionManager.isDeprecated('v1')) {
 *   console.warn('Please upgrade to v2');
 * }
 * ```
 */
export declare class VersionManager {
    private config;
    private migrations;
    /**
     * Create a new version manager.
     *
     * @param config - Version manager configuration
     */
    constructor(config: VersionManagerConfig);
    /**
     * Get headers for the specified version.
     *
     * @param version - API version
     * @returns Headers object
     */
    getVersionHeaders(version?: string): Record<string, string>;
    /**
     * Get versioned URL.
     *
     * @param path - API path
     * @param version - API version
     * @param baseUrl - Base URL
     * @returns Versioned URL
     */
    getVersionedUrl(path: string, version?: string, baseUrl?: string): string;
    /**
     * Extract version from request/response.
     *
     * @param headers - Response headers
     * @param url - Request URL
     * @returns Detected version or null
     */
    extractVersion(headers?: Record<string, string>, url?: string): string | null;
    /**
     * Get version information.
     *
     * @param version - Version to check
     * @returns Version info or undefined
     */
    getVersionInfo(version: string): APIVersion | undefined;
    /**
     * Check if version is supported.
     *
     * @param version - Version to check
     * @returns Whether version is supported
     */
    isSupported(version: string): boolean;
    /**
     * Check if version is deprecated.
     *
     * @param version - Version to check
     * @returns Whether version is deprecated
     */
    isDeprecated(version: string): boolean;
    /**
     * Check if version is current.
     *
     * @param version - Version to check
     * @returns Whether version is current
     */
    isCurrent(version: string): boolean;
    /**
     * Get the current version.
     */
    getCurrentVersion(): string;
    /**
     * Get all supported versions.
     */
    getSupportedVersions(): APIVersion[];
    /**
     * Get deprecated versions.
     */
    getDeprecatedVersions(): APIVersion[];
    /**
     * Compare two versions.
     *
     * @param a - First version
     * @param b - Second version
     * @returns Negative if a < b, positive if a > b, 0 if equal
     */
    compareVersions(a: string, b: string): number;
    /**
     * Check if version is newer than another.
     */
    isNewerThan(version: string, other: string): boolean;
    /**
     * Check if version is older than another.
     */
    isOlderThan(version: string, other: string): boolean;
    /**
     * Get the latest version.
     */
    getLatestVersion(): string;
    /**
     * Register a response migration.
     *
     * @param migration - Migration configuration
     */
    registerMigration<T = unknown>(migration: ResponseMigration<T>): void;
    /**
     * Migrate response data from one version to another.
     *
     * @param data - Response data
     * @param fromVersion - Source version
     * @param toVersion - Target version
     * @returns Migrated data
     */
    migrateResponse<T>(data: T, fromVersion: string, toVersion: string): T;
    /**
     * Get days until version sunset.
     *
     * @param version - Version to check
     * @returns Days until sunset, -1 if no sunset date, Infinity if already past
     */
    getDaysUntilSunset(version: string): number;
    /**
     * Check if version has sunset.
     */
    hasSunset(version: string): boolean;
    /**
     * Get versions approaching sunset.
     *
     * @param daysThreshold - Days before sunset to warn
     * @returns Versions within threshold
     */
    getVersionsApproachingSunset(daysThreshold?: number): APIVersion[];
    /**
     * Add a new version.
     */
    addVersion(version: APIVersion): void;
    /**
     * Update version status.
     */
    updateVersionStatus(version: string, status: VersionStatus): void;
    /**
     * Set current version.
     */
    setCurrentVersion(version: string): void;
    /**
     * Check version status and trigger callbacks.
     */
    private checkVersion;
    /**
     * Find migration path between versions.
     */
    private findMigrationPath;
}
/**
 * Create a new version manager.
 *
 * @param config - Configuration options
 * @returns VersionManager instance
 */
export declare function createVersionManager(config: VersionManagerConfig): VersionManager;
/**
 * Parse semantic version string.
 */
export declare function parseSemver(version: string): {
    major: number;
    minor: number;
    patch: number;
    prerelease?: string;
} | null;
/**
 * Format version string.
 */
export declare function formatVersion(major: number, minor?: number, patch?: number, options?: {
    prefix?: string;
}): string;