@dangahagan/weather-mcp 1.0.1 → 1.2.0

package/README.md

@@ -12,16 +12,59 @@ An MCP (Model Context Protocol) server that provides **global weather data** to
 
 ## Features
 
-- **Marine Conditions**: Comprehensive marine weather for coastal and ocean areas (NEW in v0.6.0)
-  - Global coverage for waves, swell, and ocean currents
-  - Significant wave height with safety categorization (Calm to Extreme)
-  - Wind waves (locally generated) and swell (distant systems) separation
-  - Wave period and direction for planning
-  - Ocean current velocity and direction
-  - Optional 5-day marine forecast with daily summaries
-  - Safety assessment for maritime activities (sailing, boating, surfing)
-  - Wave interpretation guide based on Douglas Sea Scale
-  - Important: Data has limited coastal accuracy - NOT for navigation
+- **Global Weather Forecasts**: Get forecasts for any location worldwide (ENHANCED in v0.4.0)
+  - Automatic source selection: NOAA (US, more detailed) or Open-Meteo (international)
+  - Extended forecasts up to 16 days (was 7)
+  - Sunrise/sunset times with daylight duration
+  - Daily or hourly granularity
+  - Precipitation probability display
+  - Temperature trends, humidity, wind, and UV index
+- **Current Conditions**: Get enhanced real-time weather observations for US locations
+  - Heat index and wind chill when relevant
+  - 24-hour temperature range
+  - Wind gusts and detailed cloud cover
+  - Recent precipitation history
+  - Optional fire weather indices (see below)
+- **Location Search**: Find coordinates for any location worldwide (v0.4.0)
+  - Convert location names to coordinates ("Paris" → 48.8534°, 2.3488°)
+  - Support for cities, airports, landmarks, and regions globally
+  - Detailed metadata: timezone, elevation, population, country
+  - Enables natural language queries: "What's the weather in Tokyo?"
+- **Climate Normals - Historical Context**: Compare weather to 30-year averages (NEW in v1.2.0)
+  - **Optional enhancement** for current conditions and forecasts (`include_normals=true`)
+  - Shows normal high/low temperatures and precipitation for comparison
+  - Displays departure from normal ("10°F warmer than normal")
+  - **Hybrid data strategy**: Open-Meteo computed normals (global, free) or optional NOAA NCEI official normals (US only, requires free API token)
+  - Based on 1991-2020 climate normals period
+  - Helps understand if weather is unusual for the time of year
+- **Snow and Ice Data**: Enhanced winter weather information (NEW in v1.2.0)
+  - Snow depth on ground (current conditions, US only)
+  - Snowfall accumulation forecasts with time periods
+  - Ice accumulation forecasts for freezing rain events
+  - Smart threshold-based display (filters trace amounts)
+  - Unit conversions from metric to imperial
+- **Timezone-Aware Display**: All timestamps in local time (NEW in v1.2.0)
+  - Automatic timezone detection from coordinates
+  - All times displayed in location's local timezone
+  - Includes timezone abbreviations (EST, PDT, etc.)
+  - Handles daylight saving time transitions
+  - Formatted time ranges for forecast periods
+- **Weather Alerts**: Get active weather watches, warnings, and advisories for US locations
+  - Severity levels (Extreme, Severe, Moderate, Minor)
+  - Urgency and certainty indicators
+  - Effective and expiration times
+  - Instructions and recommended responses
+- **Historical Data**: Access historical weather observations for any location worldwide
+  - Recent data (last 7 days): Detailed hourly observations from NOAA real-time API (US only)
+  - Archival data (>7 days old): Hourly/daily weather data from 1940-present via Open-Meteo (global coverage)
+- **Air Quality Monitoring**: Comprehensive air quality data for any location worldwide (v0.5.0)
+  - Air Quality Index (AQI) with automatic region detection (US AQI or European EAQI)
+  - Health recommendations based on AQI levels
+  - Pollutant concentrations (PM2.5, PM10, O₃, NO₂, SO₂, CO, NH₃)
+  - UV Index with sun protection recommendations
+  - Optional hourly air quality forecasts (5-day outlook)
+  - Categorized health risk levels (Good, Moderate, Unhealthy, etc.)
+  - Activity recommendations for sensitive populations
 - **Severe Weather Probabilities**: Probabilistic severe weather forecasting (NEW in v0.6.0)
   - US locations only (NOAA gridpoint data)
   - Optional enhancement to forecasts (`include_severe_weather` parameter)
@@ -31,14 +74,6 @@ An MCP (Model Context Protocol) server that provides **global weather data** to
   - Lightning activity levels
   - Smart display showing only significant threats
   - Works with both daily and hourly forecasts
-- **Air Quality Monitoring**: Comprehensive air quality data for any location worldwide (v0.5.0)
-  - Air Quality Index (AQI) with automatic region detection (US AQI or European EAQI)
-  - Health recommendations based on AQI levels
-  - Pollutant concentrations (PM2.5, PM10, O₃, NO₂, SO₂, CO, NH₃)
-  - UV Index with sun protection recommendations
-  - Optional hourly air quality forecasts (5-day outlook)
-  - Categorized health risk levels (Good, Moderate, Unhealthy, etc.)
-  - Activity recommendations for sensitive populations
 - **Fire Weather Data**: Fire danger indices for US locations (v0.5.0)
   - Haines Index (atmospheric fire growth potential)
   - Grassland Fire Danger Index
@@ -46,32 +81,16 @@ An MCP (Model Context Protocol) server that provides **global weather data** to
   - Mixing Height (smoke dispersion indicator)
   - Transport Wind Speed (smoke transport)
   - Optional enhancement to current conditions
-- **Location Search**: Find coordinates for any location worldwide (v0.4.0)
-  - Convert location names to coordinates ("Paris" → 48.8534°, 2.3488°)
-  - Support for cities, airports, landmarks, and regions globally
-  - Detailed metadata: timezone, elevation, population, country
-  - Enables natural language queries: "What's the weather in Tokyo?"
-- **Global Weather Forecasts**: Get forecasts for any location worldwide (ENHANCED in v0.4.0)
-  - Automatic source selection: NOAA (US, more detailed) or Open-Meteo (international)
-  - Extended forecasts up to 16 days (was 7)
-  - Sunrise/sunset times with daylight duration
-  - Daily or hourly granularity
-  - Precipitation probability display
-  - Temperature trends, humidity, wind, and UV index
-- **Weather Alerts**: Get active weather watches, warnings, and advisories for US locations
-  - Severity levels (Extreme, Severe, Moderate, Minor)
-  - Urgency and certainty indicators
-  - Effective and expiration times
-  - Instructions and recommended responses
-- **Current Conditions**: Get enhanced real-time weather observations for US locations
-  - Heat index and wind chill when relevant
-  - 24-hour temperature range
-  - Wind gusts and detailed cloud cover
-  - Recent precipitation history
-  - Optional fire weather indices (see above)
-- **Historical Data**: Access historical weather observations for any location worldwide
-  - Recent data (last 7 days): Detailed hourly observations from NOAA real-time API (US only)
-  - Archival data (>7 days old): Hourly/daily weather data from 1940-present via Open-Meteo (global coverage)
+- **Marine Conditions**: Comprehensive marine weather for coastal and ocean areas (NEW in v0.6.0)
+  - Global coverage for waves, swell, and ocean currents
+  - Significant wave height with safety categorization (Calm to Extreme)
+  - Wind waves (locally generated) and swell (distant systems) separation
+  - Wave period and direction for planning
+  - Ocean current velocity and direction
+  - Optional 5-day marine forecast with daily summaries
+  - Safety assessment for maritime activities (sailing, boating, surfing)
+  - Wave interpretation guide based on Douglas Sea Scale
+  - Important: Data has limited coastal accuracy - NOT for navigation
 - **Service Status Checking**: Proactively verify API availability with health checks
 - **Enhanced Error Handling**: Detailed, actionable error messages with status page links
 - **Intelligent Caching**: Built-in in-memory cache reduces API calls and improves performance
@@ -92,6 +111,7 @@ The Weather MCP server includes an intelligent in-memory caching system that sig
 The cache automatically stores and retrieves weather data with intelligent expiration:
 
 - **Location Searches**: Cached for 30 days (locations don't move)
+- **Climate Normals**: Cached indefinitely (30-year averages are static) - NEW in v1.2.0
 - **Marine Conditions**: Cached for 1 hour (marine data updates hourly) - NEW in v0.6.0
 - **Air Quality Data**: Cached for 1 hour (air quality updates hourly) - v0.5.0
 - **Fire Weather Data**: Cached for 2 hours (gridpoint data updates ~hourly) - v0.5.0
@@ -112,8 +132,18 @@ export CACHE_ENABLED=false
 
 # Adjust maximum cache size (default: 1000 entries)
 export CACHE_MAX_SIZE=1500
+
+# Optional: NOAA NCEI API token for official climate normals (US only, NEW in v1.2.0)
+# Falls back to Open-Meteo computed normals if not configured
+export NCEI_API_TOKEN=your_token_here
 ```
 
+**Note on Climate Normals (v1.2.0):**
+- By default, climate normals use Open-Meteo's computed 30-year averages (completely free, global coverage, zero setup)
+- Optionally, you can configure a free NCEI API token to use official NOAA climate normals for US locations
+- Get a free token at: https://www.ncdc.noaa.gov/cdo-web/token
+- If NCEI token is configured but unavailable, the system automatically falls back to Open-Meteo
+
 ### Monitoring
 
 Use the `check_service_status` tool to view cache statistics including:
@@ -237,32 +267,7 @@ You can also find coordinates manually:
 
 ## Available Tools
 
-### 1. search_location (NEW in v0.4.0)
-Find coordinates for any location worldwide by name.
-
-**Parameters:**
-- `query` (required): Location name to search for (e.g., "Paris", "New York, NY", "Tokyo")
-- `limit` (optional): Maximum number of results to return (1-100, default: 5)
-
-**Description:**
-Converts location names to coordinates using the Open-Meteo Geocoding API. Returns multiple matches with detailed metadata including coordinates, timezone, elevation, population, and administrative regions. Enables natural language weather queries by finding coordinates automatically.
-
-**Examples:**
-```
-"Find coordinates for Paris"
-"Search for Tokyo, Japan"
-"Where is San Francisco, CA?"
-```
-
-**Returns:**
-- Location name and full administrative hierarchy
-- Latitude and longitude coordinates
-- Timezone and elevation
-- Population (when available)
-- Country and region information
-- Feature type (capital, city, airport, etc.)
-
-### 2. get_forecast (ENHANCED in v0.4.0)
+### 1. get_forecast (ENHANCED in v0.4.0, v1.2.0)
 Get weather forecast for any location worldwide.
 
 **Parameters:**
@@ -271,6 +276,7 @@ Get weather forecast for any location worldwide.
 - `days` (optional): Number of days in forecast (1-16, default: 7)
 - `granularity` (optional): "daily" or "hourly" (default: "daily")
 - `include_precipitation_probability` (optional): Include rain chances (default: true)
+- `include_normals` (optional): Include climate normals for comparison (default: false, NEW in v1.2.0)
 - `source` (optional): "auto" (default), "noaa" (US only), or "openmeteo" (global)
 
 **Description:**
@@ -291,39 +297,86 @@ Automatically selects the best data source: NOAA for US locations (more detailed
 - Weather conditions and descriptions
 - UV index (for international locations)
 - Humidity and atmospheric conditions
+- Climate normals comparison (when `include_normals=true`, NEW in v1.2.0)
+- Snow and ice accumulation forecasts (when available, NEW in v1.2.0)
+- All timestamps in local timezone (NEW in v1.2.0)
 
-### 3. check_service_status
-Check the operational status of weather APIs and cache performance.
+### 2. get_current_conditions (ENHANCED in v1.2.0)
+Get current weather conditions for a location (US only).
 
-**Parameters:** None
+**Parameters:**
+- `latitude` (required): Latitude coordinate (-90 to 90)
+- `longitude` (required): Longitude coordinate (-180 to 180)
+- `include_fire_weather` (optional): Include fire weather indices (default: false)
+- `include_normals` (optional): Include climate normals for comparison (default: false, NEW in v1.2.0)
+
+**Example:**
+```
+What are the current weather conditions in New York? (latitude: 40.7128, longitude: -74.0060)
+```
+
+**Returns:**
+- Current temperature, humidity, wind, pressure
+- Heat index or wind chill (when applicable)
+- 24-hour temperature range
+- Recent precipitation
+- Cloud cover and visibility
+- Snow depth on ground (when available, NEW in v1.2.0)
+- Climate normals comparison (when `include_normals=true`, NEW in v1.2.0)
+- Fire weather indices (when `include_fire_weather=true`)
+- All timestamps in local timezone (NEW in v1.2.0)
+
+### 3. search_location (NEW in v0.4.0)
+Find coordinates for any location worldwide by name.
+
+**Parameters:**
+- `query` (required): Location name to search for (e.g., "Paris", "New York, NY", "Tokyo")
+- `limit` (optional): Maximum number of results to return (1-100, default: 5)
 
 **Description:**
-Performs health checks on both NOAA and Open-Meteo APIs to verify they are operational. Use this tool when experiencing errors or to proactively verify service availability before making weather data requests. Returns current status, helpful messages, links to official status pages, and cache statistics.
+Converts location names to coordinates using the Open-Meteo Geocoding API. Returns multiple matches with detailed metadata including coordinates, timezone, elevation, population, and administrative regions. Enables natural language weather queries by finding coordinates automatically.
 
-**Example:**
+**Examples:**
 ```
-Check if the weather services are operational
+"Find coordinates for Paris"
+"Search for Tokyo, Japan"
+"Where is San Francisco, CA?"
 ```
 
 **Returns:**
-- Operational status for NOAA API (forecasts & current conditions)
-- Operational status for Open-Meteo API (historical data & forecasts)
-- Cache statistics (hit rate, size, API call reduction)
-- Status page links and recommended actions if issues are detected
-- Overall service availability summary
+- Location name and full administrative hierarchy
+- Latitude and longitude coordinates
+- Timezone and elevation
+- Population (when available)
+- Country and region information
+- Feature type (capital, city, airport, etc.)
 
-### 4. get_current_conditions
-Get current weather conditions for a location.
+### 4. get_alerts
+Get active weather alerts, watches, warnings, and advisories for US locations.
 
 **Parameters:**
 - `latitude` (required): Latitude coordinate (-90 to 90)
 - `longitude` (required): Longitude coordinate (-180 to 180)
+- `active_only` (optional): Show only active alerts (default: true)
 
-**Example:**
+**Description:**
+Retrieves current weather alerts from the NOAA API for safety-critical weather information. Returns severity levels (Extreme, Severe, Moderate, Minor), urgency indicators, effective/expiration times, and affected areas. Alerts are automatically sorted by severity with the most critical first.
+
+**Examples:**
 ```
-What are the current weather conditions in New York? (latitude: 40.7128, longitude: -74.0060)
+"Are there any weather alerts for Miami, Florida?"
+"Check for severe weather warnings in Oklahoma City"
+"What weather watches are active in my area?" (latitude: 40.7128, longitude: -74.0060)
 ```
 
+**Returns:**
+- Alert type and severity (Extreme → Severe → Moderate → Minor)
+- Urgency, certainty, and response type
+- Event description and instructions
+- Effective and expiration times
+- Affected geographic areas
+- Recommended actions and safety information
+
 ### 5. get_historical_weather
 Get historical weather observations for a location.
 
@@ -383,33 +436,7 @@ If you get "No historical data available":
 - Note: Most recent data has a 5-day delay
 - Very recent dates (last 5 days) may not be available in archival data yet
 
-### 6. get_alerts
-Get active weather alerts, watches, warnings, and advisories for US locations.
-
-**Parameters:**
-- `latitude` (required): Latitude coordinate (-90 to 90)
-- `longitude` (required): Longitude coordinate (-180 to 180)
-- `active_only` (optional): Show only active alerts (default: true)
-
-**Description:**
-Retrieves current weather alerts from the NOAA API for safety-critical weather information. Returns severity levels (Extreme, Severe, Moderate, Minor), urgency indicators, effective/expiration times, and affected areas. Alerts are automatically sorted by severity with the most critical first.
-
-**Examples:**
-```
-"Are there any weather alerts for Miami, Florida?"
-"Check for severe weather warnings in Oklahoma City"
-"What weather watches are active in my area?" (latitude: 40.7128, longitude: -74.0060)
-```
-
-**Returns:**
-- Alert type and severity (Extreme → Severe → Moderate → Minor)
-- Urgency, certainty, and response type
-- Event description and instructions
-- Effective and expiration times
-- Affected geographic areas
-- Recommended actions and safety information
-
-### 7. get_air_quality (NEW in v0.5.0)
+### 6. get_air_quality (NEW in v0.5.0)
 Get comprehensive air quality data for any location worldwide.
 
 **Parameters:**
@@ -435,8 +462,28 @@ Provides current air quality conditions using the Open-Meteo Air Quality API wit
 - Activity recommendations for sensitive groups
 - Optional 5-day hourly forecast
 
-### 8. get_marine_conditions (NEW in v0.6.0)
-Get marine weather conditions including wave height, swell, ocean currents, and sea state.
+### 7. check_service_status
+Check the operational status of weather APIs and cache performance.
+
+**Parameters:** None
+
+**Description:**
+Performs health checks on both NOAA and Open-Meteo APIs to verify they are operational. Use this tool when experiencing errors or to proactively verify service availability before making weather data requests. Returns current status, helpful messages, links to official status pages, and cache statistics.
+
+**Example:**
+```
+Check if the weather services are operational
+```
+
+**Returns:**
+- Operational status for NOAA API (forecasts & current conditions)
+- Operational status for Open-Meteo API (historical data & forecasts)
+- Cache statistics (hit rate, size, API call reduction)
+- Status page links and recommended actions if issues are detected
+- Overall service availability summary
+
+### 8. get_marine_conditions (NEW in v0.6.0, Enhanced in v1.1.0)
+Get marine weather conditions including wave height, swell, ocean currents, and sea state with automatic source selection for Great Lakes and coastal bays.
 
 **Parameters:**
 - `latitude` (required): Latitude coordinate (-90 to 90)
@@ -444,7 +491,10 @@ Get marine weather conditions including wave height, swell, ocean currents, and
 - `forecast` (optional): Include 5-day marine forecast (default: false)
 
 **Description:**
-Provides comprehensive marine weather data using the Open-Meteo Marine API with global ocean coverage. Includes significant wave height with Douglas Sea Scale categorization, wind waves vs swell separation, wave period/direction, ocean currents, and safety assessment for maritime activities.
+Provides comprehensive marine weather data with intelligent dual-source support:
+- **Great Lakes & Coastal Bays (NEW in v1.1.0)**: Automatically uses NOAA gridpoint data for all 5 Great Lakes (Superior, Michigan, Huron, Erie, Ontario) and major US coastal bays (Chesapeake Bay, San Francisco Bay, Tampa Bay, Puget Sound, Lake Okeechobee). Provides wave height, wave period, wave direction, and wind conditions.
+- **Ocean Coverage**: Uses Open-Meteo Marine API for global ocean coverage, including significant wave height with Douglas Sea Scale categorization, wind waves vs swell separation, wave period/direction, ocean currents, and safety assessment for maritime activities.
+- **Automatic Selection**: Intelligent geographic detection automatically selects the best data source with zero configuration required.
 
 **Important:** Data has limited accuracy in coastal areas and is NOT suitable for coastal navigation - always consult official marine forecasts.
 
@@ -539,7 +589,7 @@ Use the `check_service_status` tool to proactively verify API availability:
 
 ### Automated Test Suite
 
-This project includes a comprehensive test suite with 247 automated tests:
+This project includes a comprehensive test suite with 693 automated tests:
 
 ```bash
 # Run all tests
@@ -556,13 +606,13 @@ npm run test:ui
 ```
 
 **Test Coverage:**
-- **247 tests** across unit and integration test suites
-- **100% coverage** on critical utilities (cache, validation, units, errors)
+- **693 tests** across unit and integration test suites (340 new tests in v1.2.0)
+- **100% coverage** on critical utilities (cache, validation, units, errors, normals, snow, timezone)
 - **54% overall coverage** with focus on reliability and security
 - All tests execute in ~1 second
 
 **Test Categories:**
-- **Unit Tests** (228 tests) - Cache, validation, units, errors, config, retry logic
+- **Unit Tests** (427 tests) - Cache, validation, units, errors, config, retry logic, normals, snow, timezone
 - **Integration Tests** (19 tests) - Error recovery scenarios, service status checks
 
 ### Quick API Connectivity Test
@@ -608,6 +658,7 @@ weather-mcp/
 ├── src/
 │   ├── index.ts                 # Main MCP server
 │   ├── config/
+│   │   ├── api.ts               # API configuration (NCEI token) - NEW in v1.2.0
 │   │   ├── cache.ts             # Cache configuration and TTL strategies
 │   │   └── displayThresholds.ts # Display thresholds for weather conditions
 │   ├── errors/
@@ -617,10 +668,14 @@ weather-mcp/
 │   │   ├── currentConditionsHandler.ts  # Current conditions handler
 │   │   ├── forecastHandler.ts   # Forecast tool handler
 │   │   ├── historicalWeatherHandler.ts  # Historical weather handler
+│   │   ├── airQualityHandler.ts # Air quality handler
+│   │   ├── marineConditionsHandler.ts   # Marine conditions handler
+│   │   ├── locationHandler.ts   # Location search handler
 │   │   └── statusHandler.ts     # Service status handler
 │   ├── services/
 │   │   ├── noaa.ts              # NOAA API service
-│   │   └── openmeteo.ts         # Open-Meteo API service
+│   │   ├── openmeteo.ts         # Open-Meteo API service
+│   │   └── ncei.ts              # NCEI climate normals service - NEW in v1.2.0
 │   ├── types/
 │   │   ├── noaa.ts              # NOAA TypeScript type definitions
 │   │   └── openmeteo.ts         # Open-Meteo TypeScript type definitions
@@ -629,9 +684,12 @@ weather-mcp/
 │       ├── logger.ts            # Structured logging utilities
 │       ├── temperatureConversion.ts  # Temperature conversion helpers
 │       ├── units.ts             # Unit conversion utilities
-│       └── validation.ts        # Input validation functions
+│       ├── validation.ts        # Input validation functions
+│       ├── normals.ts           # Climate normals utilities - NEW in v1.2.0
+│       ├── snow.ts              # Snow and ice data utilities - NEW in v1.2.0
+│       └── timezone.ts          # Timezone-aware formatting - NEW in v1.2.0
 ├── tests/
-│   ├── unit/                    # Unit tests (228 tests)
+│   ├── unit/                    # Unit tests (427 tests) - 93 new tests in v1.2.0
 │   └── integration/             # Integration tests (19 tests)
 ├── dist/                        # Compiled JavaScript (generated)
 ├── docs/                        # Documentation

package/dist/config/api.d.ts

@@ -0,0 +1,30 @@
+/**
+ * API configuration for external weather services
+ *
+ * Most APIs used by this server are free and require no authentication.
+ * Optional API tokens can be configured for enhanced features.
+ */
+/**
+ * NCEI (National Centers for Environmental Information) API token
+ *
+ * OPTIONAL: Get a free token at https://www.ncdc.noaa.gov/cdo-web/token
+ *
+ * Benefits of providing a token:
+ * - Access to official NOAA climate normals for US locations
+ * - More accurate than computed normals from reanalysis data
+ *
+ * If not provided:
+ * - Climate normals will be computed from Open-Meteo historical data
+ * - Works globally (not just US)
+ * - No setup required
+ *
+ * Rate limits with token:
+ * - 5 requests per second
+ * - 10,000 requests per day
+ */
+export declare const NCEI_API_TOKEN: string | undefined;
+/**
+ * Check if NCEI API is available (token configured)
+ */
+export declare function isNCEIAvailable(): boolean;
+//# sourceMappingURL=api.d.ts.map

package/dist/config/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/config/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,oBAA6B,CAAC;AAEzD;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC"}

package/dist/config/api.js

@@ -0,0 +1,32 @@
+/**
+ * API configuration for external weather services
+ *
+ * Most APIs used by this server are free and require no authentication.
+ * Optional API tokens can be configured for enhanced features.
+ */
+/**
+ * NCEI (National Centers for Environmental Information) API token
+ *
+ * OPTIONAL: Get a free token at https://www.ncdc.noaa.gov/cdo-web/token
+ *
+ * Benefits of providing a token:
+ * - Access to official NOAA climate normals for US locations
+ * - More accurate than computed normals from reanalysis data
+ *
+ * If not provided:
+ * - Climate normals will be computed from Open-Meteo historical data
+ * - Works globally (not just US)
+ * - No setup required
+ *
+ * Rate limits with token:
+ * - 5 requests per second
+ * - 10,000 requests per day
+ */
+export const NCEI_API_TOKEN = process.env.NCEI_API_TOKEN;
+/**
+ * Check if NCEI API is available (token configured)
+ */
+export function isNCEIAvailable() {
+    return !!NCEI_API_TOKEN && NCEI_API_TOKEN.trim().length > 0;
+}
+//# sourceMappingURL=api.js.map

package/dist/config/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/config/api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAEzD;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,CAAC,cAAc,IAAI,cAAc,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC"}

package/dist/errors/ApiError.d.ts

@@ -6,11 +6,11 @@
  */
 export declare class ApiError extends Error {
     readonly statusCode: number;
-    readonly service: 'NOAA' | 'OpenMeteo';
+    readonly service: 'NOAA' | 'OpenMeteo' | 'NCEI';
     readonly userMessage: string;
     readonly helpLinks: string[];
     readonly isRetryable: boolean;
-    constructor(message: string, statusCode: number, service: 'NOAA' | 'OpenMeteo', userMessage: string, helpLinks?: string[], isRetryable?: boolean);
+    constructor(message: string, statusCode: number, service: 'NOAA' | 'OpenMeteo' | 'NCEI', userMessage: string, helpLinks?: string[], isRetryable?: boolean);
     /**
      * Format error for display to user
      */
@@ -21,13 +21,13 @@ export declare class ApiError extends Error {
  */
 export declare class RateLimitError extends ApiError {
     readonly retryAfter?: number;
-    constructor(service: 'NOAA' | 'OpenMeteo', retryAfter?: number);
+    constructor(service: 'NOAA' | 'OpenMeteo' | 'NCEI', messageOrRetryAfter?: string | number, retryAfter?: number);
 }
 /**
  * Service unavailable error - API is down or timing out
  */
 export declare class ServiceUnavailableError extends ApiError {
-    constructor(service: 'NOAA' | 'OpenMeteo', originalError?: Error);
+    constructor(service: 'NOAA' | 'OpenMeteo' | 'NCEI', messageOrError?: string | Error, originalError?: Error);
 }
 /**
  * Invalid location error - coordinates not supported or out of range
@@ -35,13 +35,13 @@ export declare class ServiceUnavailableError extends ApiError {
 export declare class InvalidLocationError extends ApiError {
     readonly latitude?: number;
     readonly longitude?: number;
-    constructor(service: 'NOAA' | 'OpenMeteo', message: string, latitude?: number, longitude?: number);
+    constructor(service: 'NOAA' | 'OpenMeteo' | 'NCEI', message: string, latitude?: number, longitude?: number);
 }
 /**
  * Data not found error - requested data doesn't exist
  */
 export declare class DataNotFoundError extends ApiError {
-    constructor(service: 'NOAA' | 'OpenMeteo', message: string);
+    constructor(service: 'NOAA' | 'OpenMeteo' | 'NCEI', message: string);
 }
 /**
  * Validation error - invalid input parameters

package/dist/errors/ApiError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiError.d.ts","sourceRoot":"","sources":["../../src/errors/ApiError.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9C,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpC,SAAgB,WAAW,EAAE,OAAO,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,WAAW,EAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAAM,EAAO,EACxB,WAAW,GAAE,OAAe;IAgB9B;;OAEG;IACH,aAAa,IAAI,MAAM;CAYxB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,UAAU,CAAC,EAAE,MAAM;CAoB/D;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,aAAa,CAAC,EAAE,KAAK;CAoBjE;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;gBAGjC,OAAO,EAAE,MAAM,GAAG,WAAW,EAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM;CAerB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,OAAO,EAAE,MAAM;CAY3D;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,CAAC,EAAE,GAAG,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG;CAUzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAetD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAgBvD"}
+{"version":3,"file":"ApiError.d.ts","sourceRoot":"","sources":["../../src/errors/ApiError.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACvD,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpC,SAAgB,WAAW,EAAE,OAAO,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,EACtC,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,MAAM,EAAO,EACxB,WAAW,GAAE,OAAe;IAgB9B;;OAEG;IACH,aAAa,IAAI,MAAM;CAYxB;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,EAAE,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAiC/G;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;gBACvC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE,aAAa,CAAC,EAAE,KAAK;CAiC3G;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,QAAQ;IAChD,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClC,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;gBAGjC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,EACtC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM;CAerB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM;CAYpE;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAgB,KAAK,CAAC,EAAE,GAAG,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG;CAUzD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAetD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAgBvD"}

package/dist/errors/ApiError.js

@@ -42,33 +42,56 @@ export class ApiError extends Error {
  */
 export class RateLimitError extends ApiError {
     retryAfter;
-    constructor(service, retryAfter) {
-        const userMessage = retryAfter
-            ? `Rate limit exceeded. Please retry after ${retryAfter} seconds.`
-            : 'Rate limit exceeded. Please retry in a few seconds.';
+    constructor(service, messageOrRetryAfter, retryAfter) {
+        // Handle backwards compatibility: if second param is number, treat it as retryAfter
+        let message;
+        let retry;
+        if (typeof messageOrRetryAfter === 'number') {
+            message = undefined;
+            retry = messageOrRetryAfter;
+        }
+        else if (typeof messageOrRetryAfter === 'string') {
+            message = messageOrRetryAfter;
+            retry = retryAfter;
+        }
+        const userMessage = message || (retry
+            ? `Rate limit exceeded. Please retry after ${retry} seconds.`
+            : 'Rate limit exceeded. Please retry in a few seconds.');
         super(`Rate limit exceeded for ${service}`, 429, service, userMessage, [
             'https://weather.gov/documentation/services-web-api',
             'https://open-meteo.com/en/features#api-documentation',
+            'https://www.ncdc.noaa.gov/cdo-web/webservices'
         ], true // Retryable after waiting
         );
         this.name = 'RateLimitError';
-        this.retryAfter = retryAfter;
+        this.retryAfter = retry;
     }
 }
 /**
  * Service unavailable error - API is down or timing out
  */
 export class ServiceUnavailableError extends ApiError {
-    constructor(service, originalError) {
-        super(`${service} API is currently unavailable`, 503, service, `The ${service} weather service is temporarily unavailable. Please try again in a few minutes.`, [
-            service === 'NOAA'
-                ? 'https://www.weather.gov/'
-                : 'https://open-meteo.com/',
-        ], true // Retryable
+    constructor(service, messageOrError, originalError) {
+        // Handle backwards compatibility: if second param is Error, treat it as originalError
+        let message;
+        let error;
+        if (typeof messageOrError === 'string') {
+            message = messageOrError;
+            error = originalError;
+        }
+        else if (messageOrError instanceof Error) {
+            message = undefined;
+            error = messageOrError;
+        }
+        const userMessage = message || `The ${service} weather service is temporarily unavailable. Please try again in a few minutes.`;
+        const helpLink = service === 'NOAA' ? 'https://www.weather.gov/'
+            : service === 'NCEI' ? 'https://www.ncei.noaa.gov/'
+                : 'https://open-meteo.com/';
+        super(`${service} API is currently unavailable`, 503, service, userMessage, [helpLink], true // Retryable
         );
         this.name = 'ServiceUnavailableError';
-        if (originalError && originalError.stack) {
-            this.stack = `${this.stack}\nCaused by: ${originalError.stack}`;
+        if (error && error.stack) {
+            this.stack = `${this.stack}\nCaused by: ${error.stack}`;
         }
     }
 }