@dangahagan/weather-mcp 0.1.0

package/dist/services/noaa.js

@@ -0,0 +1,296 @@
+/**
+ * Service for interacting with the NOAA Weather API
+ */
+import axios from 'axios';
+export class NOAAService {
+    client;
+    maxRetries;
+    constructor(config = {}) {
+        const { userAgent = '(weather-mcp, contact@example.com)', baseURL = 'https://api.weather.gov', timeout = 30000, maxRetries = 3 } = config;
+        this.maxRetries = maxRetries;
+        this.client = axios.create({
+            baseURL,
+            timeout,
+            headers: {
+                'User-Agent': userAgent,
+                'Accept': 'application/geo+json'
+            }
+        });
+        // Add response interceptor for error handling
+        this.client.interceptors.response.use(response => response, error => this.handleError(error));
+    }
+    /**
+     * Handle API errors with retry logic and helpful status information
+     */
+    async handleError(error) {
+        if (error.response) {
+            const status = error.response.status;
+            const data = error.response.data;
+            // Rate limit error - suggest retry
+            if (status === 429) {
+                throw new Error(`NOAA API rate limit exceeded. Please retry in a few seconds.\n\n` +
+                    `Details: ${data.detail || 'Too many requests'}\n\n` +
+                    `For more information about rate limits, visit:\n` +
+                    `https://weather-gov.github.io/api/`);
+            }
+            // Other client errors
+            if (status >= 400 && status < 500) {
+                let errorMsg = `NOAA API error: ${data.detail || data.title || 'Invalid request'}\n\n`;
+                // Add contextual help based on error type
+                if (status === 404) {
+                    errorMsg += `This location may be outside NOAA's coverage area (US only).\n\n`;
+                }
+                errorMsg += `If this persists, check:\n` +
+                    `- Planned outages: https://weather-gov.github.io/api/planned-outages\n` +
+                    `- Service notices: https://www.weather.gov/notification\n` +
+                    `- Report issues: https://weather-gov.github.io/api/reporting-issues`;
+                throw new Error(errorMsg);
+            }
+            // Server errors
+            if (status >= 500) {
+                throw new Error(`NOAA API server error: ${data.detail || 'Service temporarily unavailable'}\n\n` +
+                    `The NOAA Weather API may be experiencing an outage.\n\n` +
+                    `Check service status:\n` +
+                    `- Planned outages: https://weather-gov.github.io/api/planned-outages\n` +
+                    `- Service notices: https://www.weather.gov/notification\n` +
+                    `- Report issues: nco.ops@noaa.gov or (301) 683-1518`);
+            }
+        }
+        // Network errors
+        if (error.code === 'ECONNABORTED') {
+            throw new Error(`Request to NOAA API timed out. Please try again.\n\n` +
+                `If timeouts persist, the service may be experiencing issues:\n` +
+                `https://weather-gov.github.io/api/planned-outages`);
+        }
+        if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
+            throw new Error(`Unable to connect to NOAA API.\n\n` +
+                `Possible causes:\n` +
+                `- Internet connection issues\n` +
+                `- NOAA API service outage\n` +
+                `- DNS resolution problems\n\n` +
+                `Check:\n` +
+                `- Your internet connection\n` +
+                `- Service status: https://weather-gov.github.io/api/planned-outages`);
+        }
+        // Generic error
+        throw new Error(`NOAA API request failed: ${error.message}\n\n` +
+            `For assistance, visit:\n` +
+            `https://weather-gov.github.io/api/reporting-issues`);
+    }
+    /**
+     * Make request with retry logic
+     */
+    async makeRequest(url, retries = 0) {
+        try {
+            const response = await this.client.get(url);
+            return response.data;
+        }
+        catch (error) {
+            // Retry on rate limit or server errors
+            if (retries < this.maxRetries) {
+                const shouldRetry = error.message.includes('rate limit') ||
+                    error.message.includes('server error') ||
+                    error.message.includes('timed out');
+                if (shouldRetry) {
+                    const delay = Math.pow(2, retries) * 1000; // Exponential backoff
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return this.makeRequest(url, retries + 1);
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if the NOAA API is operational
+     * Performs a lightweight health check by requesting a well-known endpoint
+     * @returns Object with status information
+     */
+    async checkServiceStatus() {
+        try {
+            // Use a simple, well-known location (US mainland center) for health check
+            const response = await this.client.get('/points/39.8283,-98.5795', {
+                timeout: 10000 // Shorter timeout for health check
+            });
+            if (response.status === 200) {
+                return {
+                    operational: true,
+                    message: 'NOAA Weather API is operational',
+                    statusPage: 'https://weather-gov.github.io/api/planned-outages',
+                    timestamp: new Date().toISOString()
+                };
+            }
+            return {
+                operational: false,
+                message: `NOAA API returned unexpected status: ${response.status}`,
+                statusPage: 'https://weather-gov.github.io/api/planned-outages',
+                timestamp: new Date().toISOString()
+            };
+        }
+        catch (error) {
+            const axiosError = error;
+            let message = 'NOAA Weather API may be experiencing issues';
+            let operational = false;
+            if (axiosError.response) {
+                const status = axiosError.response.status;
+                if (status === 429) {
+                    operational = true; // API is up, just rate limited
+                    message = 'NOAA API is operational but rate limited';
+                }
+                else if (status >= 500) {
+                    message = 'NOAA API is experiencing server errors (possible outage)';
+                }
+                else if (status === 404) {
+                    operational = true; // 404 on this endpoint might just mean API change
+                    message = 'NOAA API is responding (health check endpoint may have changed)';
+                }
+            }
+            else if (axiosError.code === 'ECONNABORTED') {
+                message = 'NOAA API is not responding (timeout)';
+            }
+            else if (axiosError.code === 'ENOTFOUND' || axiosError.code === 'ECONNREFUSED') {
+                message = 'Cannot connect to NOAA API (DNS or connection failure)';
+            }
+            return {
+                operational,
+                message,
+                statusPage: 'https://weather-gov.github.io/api/planned-outages',
+                timestamp: new Date().toISOString()
+            };
+        }
+    }
+    /**
+     * Convert lat/lon coordinates to NWS grid information
+     * This is the first step for getting forecast or observation data
+     */
+    async getPointData(latitude, longitude) {
+        // Validate coordinates
+        if (latitude < -90 || latitude > 90) {
+            throw new Error(`Invalid latitude: ${latitude}. Must be between -90 and 90.`);
+        }
+        if (longitude < -180 || longitude > 180) {
+            throw new Error(`Invalid longitude: ${longitude}. Must be between -180 and 180.`);
+        }
+        const url = `/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
+        return this.makeRequest(url);
+    }
+    /**
+     * Get forecast for a location using grid coordinates
+     */
+    async getForecast(office, gridX, gridY) {
+        const url = `/gridpoints/${office}/${gridX},${gridY}/forecast`;
+        return this.makeRequest(url);
+    }
+    /**
+     * Get hourly forecast for a location using grid coordinates
+     */
+    async getHourlyForecast(office, gridX, gridY) {
+        const url = `/gridpoints/${office}/${gridX},${gridY}/forecast/hourly`;
+        return this.makeRequest(url);
+    }
+    /**
+     * Get forecast for a location using lat/lon (convenience method)
+     * This combines getPointData and getForecast
+     */
+    async getForecastByCoordinates(latitude, longitude) {
+        const pointData = await this.getPointData(latitude, longitude);
+        const { gridId, gridX, gridY } = pointData.properties;
+        return this.getForecast(gridId, gridX, gridY);
+    }
+    /**
+     * Get nearest observation stations for a location
+     */
+    async getStations(latitude, longitude) {
+        const url = `/points/${latitude.toFixed(4)},${longitude.toFixed(4)}/stations`;
+        return this.makeRequest(url);
+    }
+    /**
+     * Get the latest observation from a station
+     */
+    async getLatestObservation(stationId) {
+        const url = `/stations/${stationId}/observations/latest`;
+        return this.makeRequest(url);
+    }
+    /**
+     * Get observations from a station within a time range
+     */
+    async getObservations(stationId, startTime, endTime, limit) {
+        // Validate date range if both dates are provided
+        if (startTime && endTime) {
+            if (startTime > endTime) {
+                throw new Error(`Invalid date range: start date (${startTime.toISOString()}) must be before end date (${endTime.toISOString()})`);
+            }
+        }
+        // Validate dates are not in the future
+        const now = new Date();
+        if (startTime && startTime > now) {
+            throw new Error(`Start date (${startTime.toISOString()}) cannot be in the future`);
+        }
+        if (endTime && endTime > now) {
+            throw new Error(`End date (${endTime.toISOString()}) cannot be in the future`);
+        }
+        let url = `/stations/${stationId}/observations`;
+        const params = new URLSearchParams();
+        if (startTime) {
+            params.append('start', startTime.toISOString());
+        }
+        if (endTime) {
+            params.append('end', endTime.toISOString());
+        }
+        if (limit) {
+            // Ensure limit is between 1 and 500
+            const validLimit = Math.max(1, Math.min(limit, 500));
+            params.append('limit', validLimit.toString());
+        }
+        if (params.toString()) {
+            url += `?${params.toString()}`;
+        }
+        return this.makeRequest(url);
+    }
+    /**
+     * Get current conditions for a location (convenience method)
+     * This combines getStations and getLatestObservation
+     */
+    async getCurrentConditions(latitude, longitude) {
+        const stations = await this.getStations(latitude, longitude);
+        if (!stations.features || stations.features.length === 0) {
+            throw new Error('No weather stations found near the specified location.');
+        }
+        // Try the first station, fallback to others if it fails
+        for (const station of stations.features) {
+            try {
+                const stationId = station.properties.stationIdentifier;
+                return await this.getLatestObservation(stationId);
+            }
+            catch (error) {
+                // Try next station
+                continue;
+            }
+        }
+        throw new Error('Unable to retrieve current conditions from nearby stations.');
+    }
+    /**
+     * Get historical observations for a location (convenience method)
+     */
+    async getHistoricalObservations(latitude, longitude, startTime, endTime, limit) {
+        // Validate date range
+        if (startTime > endTime) {
+            throw new Error(`Invalid date range: start date (${startTime.toISOString()}) must be before end date (${endTime.toISOString()})`);
+        }
+        // Validate dates are not in the future
+        const now = new Date();
+        if (startTime > now) {
+            throw new Error(`Start date (${startTime.toISOString()}) cannot be in the future`);
+        }
+        if (endTime > now) {
+            throw new Error(`End date (${endTime.toISOString()}) cannot be in the future`);
+        }
+        const stations = await this.getStations(latitude, longitude);
+        if (!stations.features || stations.features.length === 0) {
+            throw new Error('No weather stations found near the specified location.');
+        }
+        // Get observations from the nearest station
+        const stationId = stations.features[0].properties.stationIdentifier;
+        return this.getObservations(stationId, startTime, endTime, limit);
+    }
+}
+//# sourceMappingURL=noaa.js.map

package/dist/services/noaa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noaa.js","sourceRoot":"","sources":["../../src/services/noaa.ts"],"names":[],"mappings":"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"}

package/dist/services/openmeteo.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Service for interacting with the Open-Meteo Historical Weather API
+ * Documentation: https://open-meteo.com/en/docs/historical-weather-api
+ */
+import type { OpenMeteoHistoricalResponse } from '../types/openmeteo.js';
+export interface OpenMeteoServiceConfig {
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+export declare class OpenMeteoService {
+    private client;
+    private maxRetries;
+    constructor(config?: OpenMeteoServiceConfig);
+    /**
+     * Handle API errors with helpful status information
+     */
+    private handleError;
+    /**
+     * Make request with retry logic
+     */
+    private makeRequest;
+    /**
+     * Check if the Open-Meteo API is operational
+     * Performs a lightweight health check by requesting a simple query
+     * @returns Object with status information
+     */
+    checkServiceStatus(): Promise<{
+        operational: boolean;
+        message: string;
+        statusPage: string;
+        timestamp: string;
+    }>;
+    /**
+     * Get historical weather data for a location
+     *
+     * @param latitude - Latitude coordinate (-90 to 90)
+     * @param longitude - Longitude coordinate (-180 to 180)
+     * @param startDate - Start date in ISO format (YYYY-MM-DD)
+     * @param endDate - End date in ISO format (YYYY-MM-DD)
+     * @param useHourly - Whether to request hourly data (default: true)
+     * @returns Historical weather data
+     */
+    getHistoricalWeather(latitude: number, longitude: number, startDate: string, endDate: string, useHourly?: boolean): Promise<OpenMeteoHistoricalResponse>;
+    /**
+     * Get weather description from WMO weather code
+     * WMO Weather interpretation codes (WW): https://open-meteo.com/en/docs
+     */
+    getWeatherDescription(code: number): string;
+}
+//# sourceMappingURL=openmeteo.d.ts.map

package/dist/services/openmeteo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openmeteo.d.ts","sourceRoot":"","sources":["../../src/services/openmeteo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,2BAA2B,EAE5B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,GAAE,sBAA2B;IAyB/C;;OAEG;YACW,WAAW;IAkFzB;;OAEG;YACW,WAAW;IA0BzB;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAClC,WAAW,EAAE,OAAO,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAkEF;;;;;;;;;OASG;IACG,oBAAoB,CACxB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAAc,GACxB,OAAO,CAAC,2BAA2B,CAAC;IAoFvC;;;OAGG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAkC5C"}

package/dist/services/openmeteo.js

@@ -0,0 +1,298 @@
+/**
+ * Service for interacting with the Open-Meteo Historical Weather API
+ * Documentation: https://open-meteo.com/en/docs/historical-weather-api
+ */
+import axios from 'axios';
+export class OpenMeteoService {
+    client;
+    maxRetries;
+    constructor(config = {}) {
+        const { baseURL = 'https://archive-api.open-meteo.com/v1', timeout = 30000, maxRetries = 3 } = config;
+        this.maxRetries = maxRetries;
+        this.client = axios.create({
+            baseURL,
+            timeout,
+            headers: {
+                'Accept': 'application/json',
+                'User-Agent': 'weather-mcp/0.1.0'
+            }
+        });
+        // Add response interceptor for error handling
+        this.client.interceptors.response.use(response => response, error => this.handleError(error));
+    }
+    /**
+     * Handle API errors with helpful status information
+     */
+    async handleError(error) {
+        if (error.response) {
+            const status = error.response.status;
+            const data = error.response.data;
+            // Bad request
+            if (status === 400) {
+                const reason = data.reason || 'Invalid request parameters';
+                throw new Error(`Open-Meteo API error: ${reason}\n\n` +
+                    `Please verify:\n` +
+                    `- Coordinates are valid (latitude: -90 to 90, longitude: -180 to 180)\n` +
+                    `- Date range is valid (1940 to 5 days ago)\n` +
+                    `- Parameters are correctly formatted\n\n` +
+                    `API documentation: https://open-meteo.com/en/docs/historical-weather-api`);
+            }
+            // Rate limit error
+            if (status === 429) {
+                throw new Error(`Open-Meteo API rate limit exceeded (10,000 requests/day for non-commercial use).\n\n` +
+                    `Please retry later or consider:\n` +
+                    `- Reducing request frequency\n` +
+                    `- Using daily instead of hourly data for longer periods\n` +
+                    `- Upgrading to a commercial plan for higher limits\n\n` +
+                    `More info: https://open-meteo.com/en/pricing`);
+            }
+            // Server errors
+            if (status >= 500) {
+                throw new Error(`Open-Meteo API server error: Service temporarily unavailable\n\n` +
+                    `The Open-Meteo API may be experiencing an outage.\n\n` +
+                    `Check service status:\n` +
+                    `- Production status: https://open-meteo.com/en/docs/model-updates\n` +
+                    `- GitHub issues: https://github.com/open-meteo/open-meteo/issues`);
+            }
+            // Other errors
+            throw new Error(`Open-Meteo API error (${status}): ${data.reason || 'Request failed'}\n\n` +
+                `For assistance, visit:\n` +
+                `- API documentation: https://open-meteo.com/en/docs\n` +
+                `- GitHub issues: https://github.com/open-meteo/open-meteo/issues`);
+        }
+        // Network errors
+        if (error.code === 'ECONNABORTED') {
+            throw new Error(`Request to Open-Meteo API timed out. Please try again.\n\n` +
+                `If timeouts persist, check:\n` +
+                `- Your internet connection\n` +
+                `- Service status: https://open-meteo.com/en/docs/model-updates`);
+        }
+        if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
+            throw new Error(`Unable to connect to Open-Meteo API.\n\n` +
+                `Possible causes:\n` +
+                `- Internet connection issues\n` +
+                `- Open-Meteo API service outage\n` +
+                `- DNS resolution problems\n\n` +
+                `Check:\n` +
+                `- Your internet connection\n` +
+                `- Service status: https://open-meteo.com/en/docs/model-updates`);
+        }
+        // Generic error
+        throw new Error(`Open-Meteo API request failed: ${error.message}\n\n` +
+            `For assistance, visit:\n` +
+            `- GitHub issues: https://github.com/open-meteo/open-meteo/issues\n` +
+            `- Documentation: https://open-meteo.com/en/docs`);
+    }
+    /**
+     * Make request with retry logic
+     */
+    async makeRequest(url, params, retries = 0) {
+        try {
+            const response = await this.client.get(url, { params });
+            return response.data;
+        }
+        catch (error) {
+            // Retry on rate limit or server errors
+            if (retries < this.maxRetries) {
+                const shouldRetry = error.message.includes('rate limit') ||
+                    error.message.includes('server error') ||
+                    error.message.includes('timed out');
+                if (shouldRetry) {
+                    const delay = Math.pow(2, retries) * 1000; // Exponential backoff
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return this.makeRequest(url, params, retries + 1);
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if the Open-Meteo API is operational
+     * Performs a lightweight health check by requesting a simple query
+     * @returns Object with status information
+     */
+    async checkServiceStatus() {
+        try {
+            // Use a simple request for a recent date at a known location (London, UK)
+            // Using a 1-day range from 30 days ago to avoid the 5-day delay issue
+            const testDate = new Date();
+            testDate.setDate(testDate.getDate() - 30);
+            const dateStr = testDate.toISOString().split('T')[0];
+            const response = await this.client.get('/archive', {
+                params: {
+                    latitude: 51.5074,
+                    longitude: -0.1278,
+                    start_date: dateStr,
+                    end_date: dateStr,
+                    daily: 'temperature_2m_max',
+                    timezone: 'UTC'
+                },
+                timeout: 10000 // Shorter timeout for health check
+            });
+            if (response.status === 200 && response.data) {
+                return {
+                    operational: true,
+                    message: 'Open-Meteo API is operational',
+                    statusPage: 'https://open-meteo.com/en/docs/model-updates',
+                    timestamp: new Date().toISOString()
+                };
+            }
+            return {
+                operational: false,
+                message: `Open-Meteo API returned unexpected status: ${response.status}`,
+                statusPage: 'https://open-meteo.com/en/docs/model-updates',
+                timestamp: new Date().toISOString()
+            };
+        }
+        catch (error) {
+            const axiosError = error;
+            let message = 'Open-Meteo API may be experiencing issues';
+            let operational = false;
+            if (axiosError.response) {
+                const status = axiosError.response.status;
+                if (status === 429) {
+                    operational = true; // API is up, just rate limited
+                    message = 'Open-Meteo API is operational but rate limited';
+                }
+                else if (status >= 500) {
+                    message = 'Open-Meteo API is experiencing server errors (possible outage)';
+                }
+                else if (status === 400) {
+                    operational = true; // Bad request might indicate API is up but our test is wrong
+                    message = 'Open-Meteo API is responding (health check may need adjustment)';
+                }
+            }
+            else if (axiosError.code === 'ECONNABORTED') {
+                message = 'Open-Meteo API is not responding (timeout)';
+            }
+            else if (axiosError.code === 'ENOTFOUND' || axiosError.code === 'ECONNREFUSED') {
+                message = 'Cannot connect to Open-Meteo API (DNS or connection failure)';
+            }
+            return {
+                operational,
+                message,
+                statusPage: 'https://open-meteo.com/en/docs/model-updates',
+                timestamp: new Date().toISOString()
+            };
+        }
+    }
+    /**
+     * Get historical weather data for a location
+     *
+     * @param latitude - Latitude coordinate (-90 to 90)
+     * @param longitude - Longitude coordinate (-180 to 180)
+     * @param startDate - Start date in ISO format (YYYY-MM-DD)
+     * @param endDate - End date in ISO format (YYYY-MM-DD)
+     * @param useHourly - Whether to request hourly data (default: true)
+     * @returns Historical weather data
+     */
+    async getHistoricalWeather(latitude, longitude, startDate, endDate, useHourly = true) {
+        // Validate coordinates
+        if (latitude < -90 || latitude > 90) {
+            throw new Error(`Invalid latitude: ${latitude}. Must be between -90 and 90.`);
+        }
+        if (longitude < -180 || longitude > 180) {
+            throw new Error(`Invalid longitude: ${longitude}. Must be between -180 and 180.`);
+        }
+        // Build request parameters
+        const params = {
+            latitude,
+            longitude,
+            start_date: startDate,
+            end_date: endDate,
+            temperature_unit: 'fahrenheit',
+            wind_speed_unit: 'mph',
+            precipitation_unit: 'inch',
+            timezone: 'auto'
+        };
+        // Request appropriate data granularity
+        if (useHourly) {
+            // Hourly data for detailed observations
+            params.hourly = [
+                'temperature_2m',
+                'relative_humidity_2m',
+                'dewpoint_2m',
+                'apparent_temperature',
+                'precipitation',
+                'rain',
+                'snowfall',
+                'weather_code',
+                'pressure_msl',
+                'cloud_cover',
+                'wind_speed_10m',
+                'wind_direction_10m',
+                'wind_gusts_10m'
+            ].join(',');
+        }
+        else {
+            // Daily summaries for longer time periods
+            params.daily = [
+                'temperature_2m_max',
+                'temperature_2m_min',
+                'temperature_2m_mean',
+                'apparent_temperature_max',
+                'apparent_temperature_min',
+                'precipitation_sum',
+                'rain_sum',
+                'snowfall_sum',
+                'precipitation_hours',
+                'weather_code',
+                'wind_speed_10m_max',
+                'wind_gusts_10m_max',
+                'wind_direction_10m_dominant'
+            ].join(',');
+        }
+        const response = await this.makeRequest('/archive', params);
+        // Validate response has data
+        if (useHourly && (!response.hourly || !response.hourly.time || response.hourly.time.length === 0)) {
+            throw new Error(`No historical weather data available for the specified date range (${startDate} to ${endDate}).\n\n` +
+                'This may occur because:\n' +
+                '- The dates are too recent (data has a 5-day delay for most models)\n' +
+                '- The dates are before 1940 (earliest available data)\n\n' +
+                'Please try adjusting your date range.');
+        }
+        if (!useHourly && (!response.daily || !response.daily.time || response.daily.time.length === 0)) {
+            throw new Error(`No historical weather data available for the specified date range (${startDate} to ${endDate}).\n\n` +
+                'Please try adjusting your date range.');
+        }
+        return response;
+    }
+    /**
+     * Get weather description from WMO weather code
+     * WMO Weather interpretation codes (WW): https://open-meteo.com/en/docs
+     */
+    getWeatherDescription(code) {
+        const weatherCodes = {
+            0: 'Clear sky',
+            1: 'Mainly clear',
+            2: 'Partly cloudy',
+            3: 'Overcast',
+            45: 'Foggy',
+            48: 'Depositing rime fog',
+            51: 'Light drizzle',
+            53: 'Moderate drizzle',
+            55: 'Dense drizzle',
+            56: 'Light freezing drizzle',
+            57: 'Dense freezing drizzle',
+            61: 'Slight rain',
+            63: 'Moderate rain',
+            65: 'Heavy rain',
+            66: 'Light freezing rain',
+            67: 'Heavy freezing rain',
+            71: 'Slight snow',
+            73: 'Moderate snow',
+            75: 'Heavy snow',
+            77: 'Snow grains',
+            80: 'Slight rain showers',
+            81: 'Moderate rain showers',
+            82: 'Violent rain showers',
+            85: 'Slight snow showers',
+            86: 'Heavy snow showers',
+            95: 'Thunderstorm',
+            96: 'Thunderstorm with slight hail',
+            99: 'Thunderstorm with heavy hail'
+        };
+        return weatherCodes[code] || `Unknown (code: ${code})`;
+    }
+}
+//# sourceMappingURL=openmeteo.js.map