/**
 * Authentication error - thrown when API key is invalid or missing
 */
export declare class AuthenticationError extends WeatherError {
    constructor(provider: string, message?: string);
}

/**
 * Calculate distance between two coordinates using Haversine formula
 *
 * @param lat1 - First latitude
 * @param lon1 - First longitude
 * @param lat2 - Second latitude
 * @param lon2 - Second longitude
 * @returns Distance in kilometers
 */
export declare function calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;

/**
 * Ensure coordinates are valid, throw error if not
 *
 * @param provider - Provider name for error messages
 * @param latitude - Latitude to validate
 * @param longitude - Longitude to validate
 * @throws InvalidLocationError if coordinates are invalid
 */
export declare function ensureValidCoordinates(provider: string, latitude: number, longitude: number): void;

/**
 * Environment Canada provider options
 */
export declare interface EnvironmentCanadaOptions {
    provider: 'environment-canada';
    /** Request timeout in milliseconds (default: 10000) */
    timeout?: number;
}

/**
 * Convert temperature from Fahrenheit to Celsius
 *
 * @param fahrenheit - Temperature in Fahrenheit
 * @returns Temperature in Celsius
 */
export declare function fahrenheitToCelsius(fahrenheit: number): number;

/**
 * Fetch options for weather data
 */
export declare interface FetchOptions {
    /** Request timeout in milliseconds */
    timeout?: number;
    /** Maximum number of forecast periods to return */
    limit?: number;
    /** Force refresh even if cached data exists */
    forceRefresh?: boolean;
}

/**
 * Create a weather adapter instance
 *
 * @param options - Weather adapter options or undefined to use environment variables
 * @returns Weather adapter instance
 *
 * @example
 * ```typescript
 * // Use environment variables (HAVE_WEATHER_PROVIDER, OPENWEATHER_API_KEY)
 * const weather = await getWeatherAdapter();
 *
 * // Explicit configuration
 * const weather = await getWeatherAdapter({
 *   provider: 'openweathermap',
 *   apiKey: 'your-api-key'
 * });
 * ```
 */
declare function getWeatherAdapter(options?: PartialWeatherAdapterOptions): Promise<IWeatherAdapter>;
export default getWeatherAdapter;
export { getWeatherAdapter }

/**
 * Google Weather API provider options
 */
export declare interface GoogleWeatherOptions {
    provider: 'google-weather';
    /** Google API key (required) */
    apiKey: string;
    /** Request timeout in milliseconds (default: 10000) */
    timeout?: number;
}

/**
 * Fetch options for historical weather data.
 */
export declare interface HistoricalFetchOptions extends FetchOptions {
    /** Start of the requested historical window */
    start: Date | string;
    /** End of the requested historical window. Defaults to start. */
    end?: Date | string;
    /** Requested granularity. Providers may support only hourly data. */
    interval?: 'hourly';
}

/**
 * Invalid location error - thrown when location is invalid or unsupported
 */
export declare class InvalidLocationError extends WeatherError {
    constructor(provider: string, latitude: number, longitude: number, message?: string);
}

/**
 * Check if location is in Canada (very rough approximation)
 * Based on latitude/longitude bounding box
 *
 * @param latitude - Location latitude
 * @param longitude - Location longitude
 * @returns true if location appears to be in Canada
 */
export declare function isInCanada(latitude: number, longitude: number): boolean;

/**
 * Public weather adapter interface (identical to IWeatherProvider)
 * This is the interface returned by getWeatherAdapter()
 */
export declare type IWeatherAdapter = IWeatherProvider;

/**
 * Core weather provider interface
 * All weather providers must implement this interface
 */
export declare interface IWeatherProvider {
    /** Provider name for logging and identification */
    readonly name: string;
    /** Provider type */
    readonly providerType: 'government' | 'community' | 'commercial';
    /**
     * Fetch weather forecasts for a location
     *
     * @param latitude - Location latitude (-90 to 90)
     * @param longitude - Location longitude (-180 to 180)
     * @param options - Fetch options
     * @returns Array of weather forecasts
     */
    fetchForLocation(latitude: number, longitude: number, options?: FetchOptions): Promise<WeatherForecast[]>;
    /**
     * Fetch historical weather observations for a location.
     *
     * Providers that cannot serve historical data must reject with
     * UnsupportedWeatherCapabilityError instead of silently falling back.
     *
     * @param latitude - Location latitude (-90 to 90)
     * @param longitude - Location longitude (-180 to 180)
     * @param options - Historical fetch options
     * @returns Array of historical weather observations
     */
    fetchHistoricalForLocation(latitude: number, longitude: number, options: HistoricalFetchOptions): Promise<WeatherForecast[]>;
    /**
     * Test connection to the weather API
     *
     * @returns true if connection successful, false otherwise
     */
    testConnection(): Promise<boolean>;
    /**
     * Check if provider supports a specific location
     *
     * @param latitude - Location latitude
     * @param longitude - Location longitude
     * @returns true if location is supported
     */
    supportsLocation(latitude: number, longitude: number): Promise<boolean>;
}

/**
 * Convert temperature from Kelvin to Celsius
 *
 * @param kelvin - Temperature in Kelvin
 * @returns Temperature in Celsius
 */
export declare function kelvinToCelsius(kelvin: number): number;

/**
 * Convert wind speed from m/s to km/h
 *
 * @param metersPerSecond - Wind speed in m/s
 * @returns Wind speed in km/h
 */
export declare function metersPerSecondToKmPerHour(metersPerSecond: number): number;

/**
 * Convert visibility from meters to kilometers
 *
 * @param meters - Visibility in meters
 * @returns Visibility in kilometers
 */
export declare function metersToKilometers(meters: number): number;

/**
 * Convert wind speed from mph to km/h
 *
 * @param milesPerHour - Wind speed in mph
 * @returns Wind speed in km/h
 */
export declare function milesPerHourToKmPerHour(milesPerHour: number): number;

/**
 * Convert visibility from miles to kilometers
 *
 * @param miles - Visibility in miles
 * @returns Visibility in kilometers
 */
export declare function milesToKilometers(miles: number): number;

/**
 * No results error - thrown when provider returns no forecast data
 */
export declare class NoResultsError extends WeatherError {
    constructor(provider: string, latitude: number, longitude: number);
}

/**
 * Open-Meteo provider options
 */
export declare interface OpenMeteoOptions {
    provider: 'open-meteo';
    /** Request timeout in milliseconds (default: 10000) */
    timeout?: number;
}

/**
 * OpenWeatherMap One Call API provider options (paid tier)
 */
export declare interface OpenWeatherMapOneCallOptions {
    provider: 'openweathermap-onecall';
    /** OpenWeatherMap API key (required) */
    apiKey: string;
    /** Request timeout in milliseconds (default: 10000) */
    timeout?: number;
}

/**
 * OpenWeatherMap provider options (free tier)
 */
export declare interface OpenWeatherMapOptions {
    provider: 'openweathermap';
    /** OpenWeatherMap API key (required) */
    apiKey: string;
    /** Request timeout in milliseconds (default: 10000) */
    timeout?: number;
}

/* Excluded from this release type: PACKAGE_VERSION_INITIALIZED */

/**
 * Partial provider options for environment variable configuration
 */
export declare type PartialWeatherAdapterOptions = Partial<Omit<EnvironmentCanadaOptions, 'provider'>> & Partial<Omit<OpenWeatherMapOptions, 'provider'>> & Partial<Omit<OpenWeatherMapOneCallOptions, 'provider'>> & Partial<Omit<GoogleWeatherOptions, 'provider'>> & Partial<Omit<OpenMeteoOptions, 'provider'>> & {
    provider?: 'environment-canada' | 'openweathermap' | 'openweathermap-onecall' | 'google-weather' | 'open-meteo';
};

/**
 * Rate limit error - thrown when API rate limit is exceeded
 */
export declare class RateLimitError extends WeatherError {
    constructor(provider: string, retryAfter?: number);
}

/**
 * Unsupported capability error - thrown when a provider cannot serve an optional capability.
 */
export declare class UnsupportedWeatherCapabilityError extends WeatherError {
    constructor(provider: string, capability: string, message?: string);
}

/**
 * Shared utilities for weather providers
 */
/**
 * Validate coordinates
 *
 * @param latitude - Latitude to validate (-90 to 90)
 * @param longitude - Longitude to validate (-180 to 180)
 * @returns Validation result with optional error message
 */
export declare function validateCoordinates(latitude: number, longitude: number): {
    valid: boolean;
    error?: string;
};

/**
 * Discriminated union of all provider options
 */
export declare type WeatherAdapterOptions = EnvironmentCanadaOptions | OpenWeatherMapOptions | OpenWeatherMapOneCallOptions | GoogleWeatherOptions | OpenMeteoOptions;

/**
 * Weather alert from Google Weather API
 */
export declare interface WeatherAlert {
    /** Alert identifier */
    id: string;
    /** Alert headline */
    headline: string;
    /** Detailed description */
    description: string;
    /** Severity level */
    severity: string;
    /** Alert start time */
    startTime: Date;
    /** Alert end time */
    endTime: Date;
    /** Raw API response */
    raw: any;
}

/**
 * Weather error - base class for weather-related errors
 */
export declare class WeatherError extends Error {
    readonly provider: string;
    readonly code?: string | undefined;
    readonly details?: any | undefined;
    constructor(message: string, provider: string, code?: string | undefined, details?: any | undefined);
}

/**
 * Weather package type definitions
 *
 * Provides standardized interfaces for weather data providers
 */
/**
 * Standard weather forecast data structure
 * All providers must return this format
 */
export declare interface WeatherForecast {
    /** Forecast timestamp */
    timestamp: Date;
    /** Temperature in Celsius */
    temperature: number;
    /** Feels-like temperature in Celsius (optional) */
    feelsLike?: number;
    /** Minimum temperature in Celsius (optional) */
    temperatureMin?: number;
    /** Maximum temperature in Celsius (optional) */
    temperatureMax?: number;
    /** Human-readable conditions description */
    conditions: string;
    /** Humidity percentage (0-100) */
    humidity: number;
    /** Wind speed in km/h */
    windSpeed: number;
    /** Wind direction in degrees (0-360, optional) */
    windDirection?: number;
    /** Wind gust speed in km/h (optional) */
    windGust?: number;
    /** Atmospheric pressure in hPa (optional) */
    pressure?: number;
    /** Cloud cover percentage (0-100, optional) */
    cloudCover?: number;
    /** Visibility in kilometers (optional) */
    visibility?: number;
    /** Precipitation probability percentage (0-100, optional) */
    precipProbability?: number;
    /** Precipitation amount in mm (optional) */
    precipAmount?: number;
    /** Provider's confidence in forecast (0-100, optional) */
    confidence?: number;
    /** Raw provider-specific data */
    raw: any;
}

export { }