import { HttpRequestConfig } from './http';
/**
 * API version format
 */
export type ApiVersion = `v${number}` | `v${number}.${number}` | `v${number}.${number}.${number}`;
/**
 * Versioning strategies
 */
export declare enum VersioningStrategy {
    /** URL path versioning: /v1/users */
    URL_PATH = "url-path",
    /** Accept header versioning: Accept: application/vnd.api+json; version=1 */
    ACCEPT_HEADER = "accept-header",
    /** Query parameter: /users?version=1 */
    QUERY_PARAM = "query-param",
    /** Custom header: X-API-Version: 1 */
    CUSTOM_HEADER = "custom-header",
    /** Media type versioning: application/vnd.api.v1+json */
    MEDIA_TYPE = "media-type"
}
/**
 * Version deprecation info
 */
export interface VersionDeprecation {
    /** Sunset date (ISO 8601) */
    sunsetDate: string;
    /** Migration guide URL */
    migrationGuide?: string;
    /** Replacement version */
    replacementVersion?: ApiVersion;
    /** Additional warning message */
    message?: string;
}
/**
 * Version transformer for request/response adaptation
 */
export interface VersionTransformer {
    /** Transform request to target version format */
    transformRequest?: (config: HttpRequestConfig) => HttpRequestConfig;
    /** Transform response from target version format */
    transformResponse?: <T>(data: T, originalVersion: ApiVersion) => T;
    /** Map endpoint paths for version differences */
    mapEndpoint?: (path: string) => string;
    /** Transform request body */
    transformBody?: (body: unknown) => unknown;
    /** Transform response data shape */
    transformData?: <T>(data: T) => T;
}
/**
 * Version configuration
 */
export interface VersionConfig {
    /** Current/default version */
    current: ApiVersion;
    /** Minimum supported version */
    minimum: ApiVersion;
    /** Deprecated versions with sunset info */
    deprecated: Map<ApiVersion, VersionDeprecation>;
    /** Version-specific transformers */
    transformers: Map<ApiVersion, VersionTransformer>;
    /** Supported versions */
    supported: ApiVersion[];
}
/**
 * Version negotiation result
 */
export interface VersionNegotiationResult {
    /** Requested version */
    requestedVersion: ApiVersion;
    /** Actually negotiated version */
    negotiatedVersion: ApiVersion;
    /** Whether version is deprecated */
    isDeprecated: boolean;
    /** Deprecation info if applicable */
    deprecation?: VersionDeprecation | undefined;
    /** Whether version is supported */
    isSupported: boolean;
}
/**
 * Versioned API client configuration
 */
export interface VersionedApiClientConfig {
    /** Base URL for API */
    baseUrl: string;
    /** Versioning strategy */
    strategy: VersioningStrategy;
    /** Version configuration */
    versionConfig: VersionConfig;
    /** Custom header name for CUSTOM_HEADER strategy */
    headerName?: string;
    /** Media type template for MEDIA_TYPE strategy */
    mediaTypeTemplate?: string;
    /** Callback for deprecation warnings */
    onDeprecationWarning?: (info: VersionNegotiationResult) => void;
    /** Callback for version mismatch */
    onVersionMismatch?: (requested: ApiVersion, actual: ApiVersion) => void;
    /** Callback for unsupported version */
    onUnsupportedVersion?: (version: ApiVersion, minimum: ApiVersion) => void;
    /** Default request timeout */
    timeout?: number;
    /** Default headers */
    defaultHeaders?: Record<string, string>;
}
/**
 * Version not supported error
 */
export declare class VersionNotSupportedError extends Error {
    readonly isVersionError = true;
    readonly requestedVersion: ApiVersion;
    readonly minimumVersion: ApiVersion;
    readonly supportedVersions: ApiVersion[];
    constructor(requested: ApiVersion, minimum: ApiVersion, supported: ApiVersion[]);
}
/**
 * Version deprecated error (when using sunset version)
 */
export declare class VersionDeprecatedError extends Error {
    readonly isVersionError = true;
    readonly version: ApiVersion;
    readonly deprecation: VersionDeprecation;
    constructor(version: ApiVersion, deprecation: VersionDeprecation);
}
/**
 * Parse version string to comparable components
 */
export declare function parseVersion(version: ApiVersion): {
    major: number;
    minor: number;
    patch: number;
};
/**
 * Convert version to numeric value for comparison
 */
export declare function versionToNumber(version: ApiVersion): number;
/**
 * Compare two versions
 * Returns: negative if a < b, 0 if equal, positive if a > b
 */
export declare function compareVersions(a: ApiVersion, b: ApiVersion): number;
/**
 * Check if version is within range
 */
export declare function isVersionInRange(version: ApiVersion, min: ApiVersion, max?: ApiVersion): boolean;
/**
 * Get latest version from array
 */
export declare function getLatestVersion(versions: ApiVersion[]): ApiVersion | undefined;
/**
 * Versioned API client with full version management
 */
export declare class VersionedApiClient {
    private readonly config;
    private currentVersion;
    private deprecationWarned;
    constructor(config: VersionedApiClientConfig);
    /**
     * Get current version
     */
    getVersion(): ApiVersion;
    /**
     * Get all supported versions
     */
    getSupportedVersions(): ApiVersion[];
    /**
     * Check if version is supported
     */
    isVersionSupported(version: ApiVersion): boolean;
    /**
     * Set target version with validation
     */
    setVersion(version: ApiVersion): VersionNegotiationResult;
    /**
     * Execute versioned request using apiClient
     * @throws {ApiError} When the request fails
     */
    request<T>(config: HttpRequestConfig): Promise<T>;
    /**
     * GET request using apiClient
     * @throws {ApiError} When the request fails
     */
    get<T>(path: string, config?: Partial<HttpRequestConfig>): Promise<T>;
    /**
     * POST request using apiClient
     * @throws {ApiError} When the request fails
     */
    post<T>(path: string, body?: unknown, config?: Partial<HttpRequestConfig>): Promise<T>;
    /**
     * PUT request using apiClient
     * @throws {ApiError} When the request fails
     */
    put<T>(path: string, body?: unknown, config?: Partial<HttpRequestConfig>): Promise<T>;
    /**
     * PATCH request using apiClient
     * @throws {ApiError} When the request fails
     */
    patch<T>(path: string, body?: unknown, config?: Partial<HttpRequestConfig>): Promise<T>;
    /**
     * DELETE request using apiClient
     * @throws {ApiError} When the request fails
     */
    delete<T>(path: string, config?: Partial<HttpRequestConfig>): Promise<T>;
    /**
     * Create a version-specific client
     */
    withVersion(version: ApiVersion): VersionedApiClient;
    /**
     * Build versioned URL
     */
    private buildUrl;
    /**
     * Build versioned headers
     */
    private buildHeaders;
}
/**
 * Create a versioned API client with sensible defaults
 */
export declare function createVersionedApi(config: {
    baseUrl: string;
    currentVersion?: ApiVersion;
    minimumVersion?: ApiVersion;
    supportedVersions?: ApiVersion[];
    strategy?: VersioningStrategy;
    deprecated?: Record<ApiVersion, VersionDeprecation>;
    transformers?: Record<ApiVersion, VersionTransformer>;
    onDeprecationWarning?: (info: VersionNegotiationResult) => void;
}): VersionedApiClient;
/**
 * Create a field renaming transformer
 */
export declare function createFieldRenamingTransformer(requestMappings: Record<string, string>, responseMappings: Record<string, string>): VersionTransformer;
/**
 * Create an endpoint mapping transformer
 */
export declare function createEndpointMappingTransformer(mappings: Record<string, string>): VersionTransformer;
/**
 * Compose multiple transformers
 */
export declare function composeTransformers(...transformers: VersionTransformer[]): VersionTransformer;
/**
 * Example: Create versioned API with v1 to v2 migration
 */
export declare const exampleVersionedApi: VersionedApiClient;