@dangahagan/weather-mcp 0.1.2 → 0.4.0

package/README.md

@@ -4,21 +4,86 @@
 [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-An MCP (Model Context Protocol) server that provides weather data to AI systems like Claude Code. Uses NOAA's API for US weather forecasts and current conditions, plus Open-Meteo for global historical weather data.
+An MCP (Model Context Protocol) server that provides **global weather data** to AI systems like Claude Code. Uses NOAA's API for detailed US weather, plus Open-Meteo for international forecasts and historical weather data worldwide.
 
 **📦 Available in the [Official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.dgahagan/weather-mcp)** as `io.github.dgahagan/weather-mcp`
 
-**No API keys required!** Both NOAA and Open-Meteo APIs are free to use with no authentication needed.
+**No API keys required!** All APIs (NOAA, Open-Meteo) are free to use with no authentication needed.
 
 ## Features
 
-- **Get Forecast**: Retrieve weather forecasts for any US location (7-day forecast)
-- **Current Conditions**: Get real-time weather observations for US locations
+- **Location Search**: Find coordinates for any location worldwide (NEW in 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
 - **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)
 - **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
+
+## Caching
+
+The Weather MCP server includes an intelligent in-memory caching system that significantly improves performance for AI-driven weather queries.
+
+### Benefits
+
+- **Faster Responses**: Cached queries return in <10ms vs 200-1000ms for API calls
+- **Reduced API Load**: 50-80% fewer API calls for typical AI conversation patterns
+- **Rate Limit Protection**: Prevents hitting API rate limits during heavy usage
+- **Automatic Management**: Smart TTL-based expiration with LRU eviction
+
+### How It Works
+
+The cache automatically stores and retrieves weather data with intelligent expiration:
+
+- **Location Searches**: Cached for 30 days (locations don't move) - NEW in v0.4.0
+- **Weather Alerts**: Cached for 5 minutes (alerts can change rapidly)
+- **Forecasts**: Cached for 2 hours (updated approximately hourly)
+- **Current Conditions**: Cached for 15 minutes (observations update every 20-60 minutes)
+- **Historical Data (>1 day old)**: Cached indefinitely (finalized data never changes)
+- **Recent Historical (<1 day)**: Cached for 1 hour (may still be updated)
+- **Grid Coordinates**: Cached indefinitely (geographic mappings are static)
+
+### Configuration
+
+Caching is **enabled by default** with sensible settings. To customize:
+
+```bash
+# Disable caching (not recommended)
+export CACHE_ENABLED=false
+
+# Adjust maximum cache size (default: 1000 entries)
+export CACHE_MAX_SIZE=1500
+```
+
+### Monitoring
+
+Use the `check_service_status` tool to view cache statistics including:
+- Hit rate percentage
+- Cache size and utilization
+- API call reduction metrics
+
+For detailed information about caching architecture and configuration, see [.github/CACHING.md](./.github/CACHING.md).
 
 ## Installation
 
@@ -107,59 +172,109 @@ Restart Claude Code and the weather tools will be available.
 
 ## Finding Coordinates
 
-All tools require latitude and longitude coordinates. You can find coordinates for any location by:
-- Asking Claude Code: "What are the coordinates for [city name]?"
+**NEW in v0.4.0**: Use the built-in `search_location` tool to find coordinates automatically!
+
+```
+"What's the weather in Paris?"
+→ Uses search_location to find Paris coordinates (48.8534°, 2.3488°)
+→ Then gets the forecast for those coordinates
+```
+
+You can also find coordinates manually:
 - Using Google Maps: Right-click a location and select the coordinates
 - Using a geocoding service like geocode.maps.co or nominatim.org
 
-### Common US City Coordinates
+### Common City Coordinates (For Reference)
 
 | City | Latitude | Longitude |
 |------|----------|-----------|
-| San Francisco, CA | 37.7749 | -122.4194 |
+| Paris, France | 48.8534 | 2.3488 |
+| Tokyo, Japan | 35.6895 | 139.6917 |
+| London, UK | 51.5085 | -0.1257 |
 | New York, NY | 40.7128 | -74.0060 |
-| Chicago, IL | 41.8781 | -87.6298 |
-| Los Angeles, CA | 34.0522 | -118.2437 |
-| Denver, CO | 39.7392 | -104.9903 |
-| Miami, FL | 25.7617 | -80.1918 |
-| Seattle, WA | 47.6062 | -122.3321 |
-| Austin, TX | 30.2672 | -97.7431 |
+| San Francisco, CA | 37.7749 | -122.4194 |
+| Sydney, Australia | -33.8688 | 151.2093 |
+| Berlin, Germany | 52.5200 | 13.4050 |
+| Dubai, UAE | 25.2048 | 55.2708 |
 
 ## Available Tools
 
-### 1. check_service_status
-Check the operational status of weather APIs.
+### 1. search_location (NEW in v0.4.0)
+Find coordinates for any location worldwide by name.
 
-**Parameters:** None
+**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, and links to official status pages.
+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)
-- 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.)
 
-### 2. get_forecast
-Get weather forecast for a location.
+### 2. get_forecast (ENHANCED in v0.4.0)
+Get weather forecast for any location worldwide.
 
 **Parameters:**
 - `latitude` (required): Latitude coordinate (-90 to 90)
 - `longitude` (required): Longitude coordinate (-180 to 180)
-- `days` (optional): Number of days in forecast (1-7, default: 7)
+- `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)
+- `source` (optional): "auto" (default), "noaa" (US only), or "openmeteo" (global)
+
+**Description:**
+Automatically selects the best data source: NOAA for US locations (more detailed) or Open-Meteo for international locations. Supports extended forecasts up to 16 days. Includes sunrise/sunset times, daylight duration, temperature, precipitation, wind, and UV index.
+
+**Examples:**
+```
+"Get a 7-day forecast for Paris (48.8534, 2.3488)"
+"Hourly forecast for Tokyo for the next 3 days"
+"16-day extended forecast for Sydney, Australia"
+```
+
+**Returns:**
+- Temperature (high/low, feels like)
+- Sunrise and sunset times with daylight duration (NEW in v0.4.0)
+- Precipitation chances and amounts
+- Wind speed, direction, and gusts
+- Weather conditions and descriptions
+- UV index (for international locations)
+- Humidity and atmospheric conditions
+
+### 3. 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:**
 ```
-Get the weather forecast for San Francisco (latitude: 37.7749, longitude: -122.4194)
+Check if the weather services are operational
 ```
 
-### 3. get_current_conditions
+**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
+
+### 4. get_current_conditions
 Get current weather conditions for a location.
 
 **Parameters:**
@@ -171,7 +286,7 @@ Get current weather conditions for a location.
 What are the current weather conditions in New York? (latitude: 40.7128, longitude: -74.0060)
 ```
 
-### 4. get_historical_weather
+### 5. get_historical_weather
 Get historical weather observations for a location.
 
 **Parameters:**
@@ -302,19 +417,45 @@ Use the `check_service_status` tool to proactively verify API availability:
 
 ## Testing
 
-### Quick Test
+### Automated Test Suite
+
+This project includes a comprehensive test suite with 247 automated tests:
 
-Verify NOAA API connectivity:
 ```bash
-npx tsx tests/test_noaa_api.ts
+# Run all tests
+npm test
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests in watch mode (during development)
+npm run test:watch
+
+# Run tests with interactive UI
+npm run test:ui
 ```
 
-This runs 5 tests covering all major functionality with real NOAA API calls.
+**Test Coverage:**
+- **247 tests** across unit and integration test suites
+- **100% coverage** on critical utilities (cache, validation, units, errors)
+- **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
+- **Integration Tests** (19 tests) - Error recovery scenarios, service status checks
+
+### Quick API Connectivity Test
+
+Verify NOAA API connectivity with a quick integration test:
+```bash
+npx tsx tests/test_noaa_api.ts
+```
 
 ### Manual Testing with Claude Code
 
-See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive testing instructions including:
-- Setup steps
+See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive manual testing instructions including:
+- Setup steps for MCP clients
 - Test cases for all tools
 - Error handling verification
 - Performance testing
@@ -324,43 +465,89 @@ See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive testing instru
 
 ### Available Scripts
 
+**Build & Run:**
 - `npm run build` - Compile TypeScript to JavaScript
 - `npm run dev` - Run the server in development mode with tsx
 - `npm start` - Run the compiled server
-- `npx tsx tests/test_noaa_api.ts` - Run API connectivity tests
+
+**Testing:**
+- `npm test` - Run all automated tests
+- `npm run test:coverage` - Run tests with coverage report
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:ui` - Run tests with interactive UI
+- `npx tsx tests/test_noaa_api.ts` - Quick API connectivity test
+
+**Security & Maintenance:**
+- `npm run audit` - Check for dependency vulnerabilities
+- `npm run audit:fix` - Automatically fix dependency vulnerabilities
 
 ### Project Structure
 
 ```
 weather-mcp/
 ├── src/
-│   ├── index.ts           # Main MCP server
+│   ├── index.ts                 # Main MCP server
+│   ├── config/
+│   │   ├── cache.ts             # Cache configuration and TTL strategies
+│   │   └── displayThresholds.ts # Display thresholds for weather conditions
+│   ├── errors/
+│   │   └── ApiError.ts          # Custom error class hierarchy
+│   ├── handlers/
+│   │   ├── alertsHandler.ts     # Weather alerts tool handler
+│   │   ├── currentConditionsHandler.ts  # Current conditions handler
+│   │   ├── forecastHandler.ts   # Forecast tool handler
+│   │   ├── historicalWeatherHandler.ts  # Historical weather handler
+│   │   └── statusHandler.ts     # Service status handler
 │   ├── services/
-│   │   ├── noaa.ts        # NOAA real-time API service
-│   │   └── openmeteo.ts   # Open-Meteo historical weather API service
+│   │   ├── noaa.ts              # NOAA API service
+│   │   └── openmeteo.ts         # Open-Meteo API service
 │   ├── types/
-│   │   ├── noaa.ts        # NOAA TypeScript type definitions
-│   │   └── openmeteo.ts   # Open-Meteo TypeScript type definitions
+│   │   ├── noaa.ts              # NOAA TypeScript type definitions
+│   │   └── openmeteo.ts         # Open-Meteo TypeScript type definitions
 │   └── utils/
-│       └── units.ts       # Unit conversion utilities
-├── dist/                  # Compiled JavaScript (generated)
-├── tests/                 # Test files
+│       ├── cache.ts             # LRU cache implementation
+│       ├── logger.ts            # Structured logging utilities
+│       ├── temperatureConversion.ts  # Temperature conversion helpers
+│       ├── units.ts             # Unit conversion utilities
+│       └── validation.ts        # Input validation functions
+├── tests/
+│   ├── unit/                    # Unit tests (228 tests)
+│   └── integration/             # Integration tests (19 tests)
+├── dist/                        # Compiled JavaScript (generated)
+├── docs/                        # Documentation
 └── package.json
 ```
 
 ## API Information
 
-This server uses two weather APIs:
+This server uses three weather APIs:
 
-### NOAA Weather API (Real-time)
+### NOAA Weather API (Real-time, US)
 - **Base URL**: https://api.weather.gov
 - **Authentication**: None required (User-Agent header only)
 - **Rate Limits**: Enforced with 5-second retry window
 - **Coverage**: United States locations only
-- **Use cases**: Forecasts, current conditions, recent observations (last 7 days)
+- **Use cases**: US forecasts (detailed), current conditions, recent observations (last 7 days)
 - **Data**: Detailed hourly observations from weather stations
 
-### Open-Meteo Historical Weather API (Archival)
+### Open-Meteo Forecast API (Global) - NEW in v0.4.0
+- **Base URL**: https://api.open-meteo.com/v1
+- **Authentication**: None required (no API token needed)
+- **Rate Limits**: 10,000 requests/day for non-commercial use
+- **Coverage**: Global (worldwide locations)
+- **Use cases**: International forecasts, extended forecasts (up to 16 days)
+- **Data**: Temperature, precipitation, wind, humidity, UV index, sunrise/sunset
+- **Resolution**: 11km global grid resolution
+
+### Open-Meteo Geocoding API (Global) - NEW in v0.4.0
+- **Base URL**: https://geocoding-api.open-meteo.com/v1
+- **Authentication**: None required (no API token needed)
+- **Coverage**: Global (worldwide locations)
+- **Use cases**: Location name to coordinates conversion
+- **Data**: Coordinates, timezone, elevation, population, administrative regions
+- **Cache**: 30-day TTL (locations don't move)
+
+### Open-Meteo Historical Weather API (Global, Archival)
 - **Base URL**: https://archive-api.open-meteo.com/v1
 - **Authentication**: None required (no API token needed)
 - **Rate Limits**: 10,000 requests/day for non-commercial use
@@ -376,9 +563,15 @@ For more details on NOAA APIs, see [NOAA_API_RESEARCH.md](./docs/NOAA_API_RESEAR
 
 ### Geographic Coverage
 
-**Forecasts and Current Conditions:**
-- NOAA APIs only cover **United States locations**
-- International locations are not supported for forecasts and current conditions
+**Forecasts:** (UPDATED in v0.4.0)
+- **Global coverage** via automatic source selection
+- US locations: Uses NOAA API (more detailed, includes narratives)
+- International locations: Uses Open-Meteo API (reliable global forecasts)
+- Extended forecasts (>7 days, up to 16 days): Open-Meteo only
+
+**Current Conditions:**
+- **US locations only** (NOAA API)
+- International real-time conditions not yet supported
 
 **Historical Data:**
 - Recent data (last 7 days): **US locations only** (NOAA API)
@@ -411,6 +604,51 @@ For more details on NOAA APIs, see [NOAA_API_RESEARCH.md](./docs/NOAA_API_RESEAR
 - **For historical analysis**: Open-Meteo provides reliable global coverage back to 1940
 - **For international locations**: Only historical data (>7 days old) is supported
 
+## Security
+
+This project takes security seriously and implements multiple layers of protection:
+
+### Security Features
+
+**Input Validation:**
+- Comprehensive runtime validation for all user inputs
+- NaN and Infinity checks for numeric coordinates
+- Range validation for latitude (-90 to 90) and longitude (-180 to 180)
+- Type checking with TypeScript strict mode
+
+**Error Handling:**
+- Custom error class hierarchy with typed errors
+- Error message sanitization to prevent information leakage
+- Retryable errors clearly identified for graceful recovery
+- Network errors sanitized before display
+
+**Dependency Security:**
+- Automated dependency scanning via `npm audit`
+- GitHub Dependabot configured for weekly security updates
+- Minimal dependency footprint (3 runtime dependencies)
+- Zero known vulnerabilities in current dependencies
+
+**Reliability:**
+- Exponential backoff with jitter prevents thundering herd problems
+- Comprehensive test suite (247 tests) with 100% coverage on critical utilities
+- Memory-safe cache with automatic cleanup
+- Graceful shutdown handling
+
+### Security Audit
+
+The project has undergone a comprehensive security audit:
+- **Overall Security Posture:** B+ (Good)
+- **Risk Level:** LOW
+- **Vulnerabilities:** Zero critical or high-severity issues
+- See [SECURITY_AUDIT.md](./docs/development/SECURITY_AUDIT.md) for full audit report
+
+### Reporting Security Issues
+
+To report a security vulnerability, please see our [Security Policy](./SECURITY.md) which includes:
+- Vulnerability reporting procedures
+- Response timeline commitments (48hr acknowledgment, 7-day assessment)
+- Security best practices for users and developers
+
 ## License
 
 MIT
@@ -418,3 +656,8 @@ MIT
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
+
+For information about code quality, security considerations, and development best practices, see:
+- [CODE_REVIEW.md](./docs/development/CODE_REVIEW.md) - Comprehensive code quality analysis
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Contribution guidelines
+- [SECURITY.md](./SECURITY.md) - Security policy and vulnerability reporting

package/dist/config/cache.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cache configuration for weather data
+ *
+ * TTL (Time To Live) values are set based on data volatility:
+ * - Historical data: Never changes once recorded
+ * - Geographic data: Static (grid coordinates, station locations)
+ * - Forecasts: Updated approximately hourly
+ * - Current conditions: Observations typically update every 20-60 minutes
+ */
+export declare const CacheConfig: {
+    readonly enabled: boolean;
+    readonly maxSize: number;
+    readonly ttl: {
+        readonly gridCoordinates: number;
+        readonly stations: number;
+        readonly forecast: number;
+        readonly currentConditions: number;
+        readonly alerts: number;
+        readonly recentHistorical: number;
+        readonly historicalData: number;
+        readonly serviceStatus: number;
+    };
+};
+/**
+ * Determine appropriate TTL for historical weather data based on date
+ * @param startDate Start date of the historical query
+ * @returns TTL in milliseconds
+ */
+export declare function getHistoricalDataTTL(startDate: string | Date): number;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/config/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkDH,eAAO,MAAM,WAAW;;;;;;;;;;;;;CA0Cd,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAYrE"}

package/dist/config/cache.js

@@ -0,0 +1,105 @@
+/**
+ * Cache configuration for weather data
+ *
+ * TTL (Time To Live) values are set based on data volatility:
+ * - Historical data: Never changes once recorded
+ * - Geographic data: Static (grid coordinates, station locations)
+ * - Forecasts: Updated approximately hourly
+ * - Current conditions: Observations typically update every 20-60 minutes
+ */
+// Time constants in milliseconds
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/**
+ * Parse a boolean environment variable
+ * @param key Environment variable key
+ * @param defaultValue Default value if not set
+ * @returns Boolean value
+ */
+function getEnvBoolean(key, defaultValue) {
+    const value = process.env[key];
+    if (value === undefined)
+        return defaultValue;
+    return value !== 'false' && value !== '0';
+}
+/**
+ * Parse a number environment variable with validation
+ * @param key Environment variable key
+ * @param defaultValue Default value if not set or invalid
+ * @param min Minimum allowed value (optional)
+ * @param max Maximum allowed value (optional)
+ * @returns Validated number value
+ */
+function getEnvNumber(key, defaultValue, min, max) {
+    const value = process.env[key];
+    if (value === undefined)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+        console.warn(`Invalid ${key}: "${value}". Using default: ${defaultValue}`);
+        return defaultValue;
+    }
+    if (min !== undefined && parsed < min) {
+        console.warn(`${key} too low: ${parsed}. Using minimum: ${min}`);
+        return min;
+    }
+    if (max !== undefined && parsed > max) {
+        console.warn(`${key} too high: ${parsed}. Using maximum: ${max}`);
+        return max;
+    }
+    return parsed;
+}
+export const CacheConfig = {
+    // Enable/disable caching globally
+    enabled: getEnvBoolean('CACHE_ENABLED', true),
+    // Maximum number of entries in cache before LRU eviction
+    // Min: 100, Max: 10000, Default: 1000
+    maxSize: getEnvNumber('CACHE_MAX_SIZE', 1000, 100, 10000),
+    // TTL values for different data types
+    ttl: {
+        // Grid coordinate lookups (lat/lon -> grid mapping)
+        // These are geographic and never change
+        gridCoordinates: Infinity,
+        // Weather station lists
+        // Stations rarely change
+        stations: 24 * HOUR,
+        // 7-day forecasts
+        // NOAA updates forecasts approximately hourly
+        forecast: 2 * HOUR,
+        // Current weather conditions
+        // Observations typically update every 20-60 minutes
+        currentConditions: 15 * MINUTE,
+        // Weather alerts
+        // Alerts can change rapidly, cache for shorter period
+        alerts: 5 * MINUTE,
+        // Recent historical data (< 7 days old)
+        // Recent data may still be updated/corrected
+        recentHistorical: 1 * HOUR,
+        // Historical data (> 1 day old from current time)
+        // Historical data beyond 1 day is finalized and won't change
+        historicalData: Infinity,
+        // Service health check status
+        // Check freshness periodically
+        serviceStatus: 5 * MINUTE,
+    },
+};
+/**
+ * Determine appropriate TTL for historical weather data based on date
+ * @param startDate Start date of the historical query
+ * @returns TTL in milliseconds
+ */
+export function getHistoricalDataTTL(startDate) {
+    const start = typeof startDate === 'string' ? new Date(startDate) : startDate;
+    const now = new Date();
+    const daysDiff = (now.getTime() - start.getTime()) / DAY;
+    if (daysDiff > 1) {
+        // Data is more than 1 day old - it's finalized and won't change
+        return CacheConfig.ttl.historicalData;
+    }
+    else {
+        // Recent data may still be updated
+        return CacheConfig.ttl.recentHistorical;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/config/cache.js.map

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