@jablum/weather-mcp 1.7.0

package/dist/utils/logger.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Structured logging utility for MCP server
+ *
+ * IMPORTANT: MCP servers use stdio for communication, so all logging MUST go to stderr
+ * (console.error) to avoid interfering with the MCP protocol on stdout.
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+export declare class Logger {
+    private level;
+    private context?;
+    constructor(level?: LogLevel, context?: string);
+    /**
+     * Create a child logger with a specific context
+     */
+    child(context: string): Logger;
+    /**
+     * Set the logging level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Internal logging method
+     */
+    private log;
+    /**
+     * Log debug message (detailed information for diagnosing problems)
+     */
+    debug(message: string, metadata?: Record<string, any>): void;
+    /**
+     * Log info message (general informational messages)
+     */
+    info(message: string, metadata?: Record<string, any>): void;
+    /**
+     * Log warning message (warning messages for potentially harmful situations)
+     */
+    warn(message: string, metadata?: Record<string, any>): void;
+    /**
+     * Log error message (error events that might still allow the application to continue)
+     */
+    error(message: string, error?: Error, metadata?: Record<string, any>): void;
+    /**
+     * Log API request
+     */
+    logApiRequest(service: string, endpoint: string, metadata?: Record<string, any>): void;
+    /**
+     * Log API response
+     */
+    logApiResponse(service: string, endpoint: string, success: boolean, duration?: number): void;
+    /**
+     * Log cache operation
+     */
+    logCacheOperation(operation: 'hit' | 'miss' | 'set' | 'evict', key: string): void;
+}
+export declare const logger: Logger;
+/**
+ * Round coordinates for logging to protect user privacy
+ * Reduces precision to ~1.1km accuracy (2 decimal places)
+ * Set LOG_PII=true environment variable to log full precision (not recommended for production)
+ *
+ * Privacy rationale: Precise coordinates can reveal sensitive locations (homes, workplaces).
+ * Rounded coordinates provide sufficient context for debugging while protecting user privacy.
+ *
+ * @param latitude - Original latitude
+ * @param longitude - Original longitude
+ * @returns Rounded coordinates object
+ */
+export declare function redactCoordinatesForLogging(latitude: number, longitude: number): {
+    lat: number;
+    lon: number;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oBAAY,QAAQ;IAClB,KAAK,IAAI;IACT,IAAI,IAAI;IACR,IAAI,IAAI;IACR,KAAK,IAAI;CACV;AAeD,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAAC,CAAS;gBAEb,KAAK,GAAE,QAAwB,EAAE,OAAO,CAAC,EAAE,MAAM;IAK7D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI9B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;OAEG;IACH,OAAO,CAAC,GAAG;IA8BX;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAI5D;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAI3D;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAI3D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAI3E;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAQtF;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAU5F;;OAEG;IACH,iBAAiB,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;CAGlF;AAkBD,eAAO,MAAM,MAAM,QAAwB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAc7G"}

package/dist/utils/logger.js

@@ -0,0 +1,153 @@
+/**
+ * Structured logging utility for MCP server
+ *
+ * IMPORTANT: MCP servers use stdio for communication, so all logging MUST go to stderr
+ * (console.error) to avoid interfering with the MCP protocol on stdout.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+export class Logger {
+    level;
+    context;
+    constructor(level = LogLevel.INFO, context) {
+        this.level = level;
+        this.context = context;
+    }
+    /**
+     * Create a child logger with a specific context
+     */
+    child(context) {
+        return new Logger(this.level, context);
+    }
+    /**
+     * Set the logging level
+     */
+    setLevel(level) {
+        this.level = level;
+    }
+    /**
+     * Internal logging method
+     */
+    log(level, message, metadata, error) {
+        // Skip if below current log level
+        if (level < this.level)
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: LogLevel[level],
+            message,
+        };
+        if (this.context) {
+            entry.context = this.context;
+        }
+        if (error) {
+            entry.error = {
+                message: error.message,
+                stack: error.stack,
+                code: error.code,
+            };
+        }
+        if (metadata) {
+            entry.metadata = metadata;
+        }
+        // Output to stderr for MCP compatibility
+        console.error(JSON.stringify(entry));
+    }
+    /**
+     * Log debug message (detailed information for diagnosing problems)
+     */
+    debug(message, metadata) {
+        this.log(LogLevel.DEBUG, message, metadata);
+    }
+    /**
+     * Log info message (general informational messages)
+     */
+    info(message, metadata) {
+        this.log(LogLevel.INFO, message, metadata);
+    }
+    /**
+     * Log warning message (warning messages for potentially harmful situations)
+     */
+    warn(message, metadata) {
+        this.log(LogLevel.WARN, message, metadata);
+    }
+    /**
+     * Log error message (error events that might still allow the application to continue)
+     */
+    error(message, error, metadata) {
+        this.log(LogLevel.ERROR, message, metadata, error);
+    }
+    /**
+     * Log API request
+     */
+    logApiRequest(service, endpoint, metadata) {
+        this.debug(`API request to ${service}`, {
+            service,
+            endpoint,
+            ...metadata,
+        });
+    }
+    /**
+     * Log API response
+     */
+    logApiResponse(service, endpoint, success, duration) {
+        const level = success ? LogLevel.DEBUG : LogLevel.WARN;
+        this.log(level, `API response from ${service}`, {
+            service,
+            endpoint,
+            success,
+            duration,
+        });
+    }
+    /**
+     * Log cache operation
+     */
+    logCacheOperation(operation, key) {
+        this.debug(`Cache ${operation}`, { operation, key });
+    }
+}
+/**
+ * Create the default logger instance
+ * Level is controlled by LOG_LEVEL environment variable
+ */
+function createDefaultLogger() {
+    const levelStr = process.env.LOG_LEVEL?.toUpperCase();
+    let level = LogLevel.INFO; // Default to INFO
+    if (levelStr && levelStr in LogLevel) {
+        level = LogLevel[levelStr];
+    }
+    return new Logger(level);
+}
+// Export singleton instance
+export const logger = createDefaultLogger();
+/**
+ * Round coordinates for logging to protect user privacy
+ * Reduces precision to ~1.1km accuracy (2 decimal places)
+ * Set LOG_PII=true environment variable to log full precision (not recommended for production)
+ *
+ * Privacy rationale: Precise coordinates can reveal sensitive locations (homes, workplaces).
+ * Rounded coordinates provide sufficient context for debugging while protecting user privacy.
+ *
+ * @param latitude - Original latitude
+ * @param longitude - Original longitude
+ * @returns Rounded coordinates object
+ */
+export function redactCoordinatesForLogging(latitude, longitude) {
+    // Check if PII logging is explicitly enabled (not recommended)
+    const logPII = process.env.LOG_PII === 'true';
+    if (logPII) {
+        return { lat: latitude, lon: longitude };
+    }
+    // Round to 2 decimal places (~1.1km precision at equator)
+    // This balances GDPR/CPRA data minimization with operational observability
+    return {
+        lat: Math.round(latitude * 100) / 100,
+        lon: Math.round(longitude * 100) / 100
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/dist/utils/marine.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Utility functions for marine conditions data formatting and interpretation
+ */
+import type { GridpointResponse } from '../types/noaa.js';
+/**
+ * NOAA Marine Conditions extracted from gridpoint data
+ */
+export interface NOAAMarineConditions {
+    waveHeight?: number;
+    wavePeriod?: number;
+    waveDirection?: number;
+    windSpeed?: number;
+    windDirection?: number;
+    windGust?: number;
+    timestamp: string;
+}
+/**
+ * Extract marine conditions from NOAA gridpoint response
+ */
+export declare function extractNOAAMarineConditions(gridpoint: GridpointResponse): NOAAMarineConditions | null;
+/**
+ * Format wave height with appropriate units and precision
+ */
+export declare function formatWaveHeight(meters: number | undefined): string;
+/**
+ * Format wave period with units
+ */
+export declare function formatWavePeriod(seconds: number | undefined): string;
+/**
+ * Format wind speed with units (converts km/h to knots for marine)
+ */
+export declare function formatWindSpeed(kmh: number | undefined): string;
+/**
+ * Format ocean current velocity
+ */
+export declare function formatCurrentVelocity(metersPerSecond: number | undefined): string;
+/**
+ * Convert degrees to cardinal/ordinal direction
+ */
+export declare function formatDirection(degrees: number | undefined): string;
+/**
+ * Categorize wave height
+ */
+export interface WaveHeightCategory {
+    description: string;
+    level: string;
+    recommendation: string;
+}
+export declare function getWaveHeightCategory(meters: number | undefined): WaveHeightCategory;
+/**
+ * Overall safety assessment based on multiple factors
+ */
+export interface SafetyAssessment {
+    level: string;
+    description: string;
+    recommendation: string;
+}
+export declare function getSafetyAssessment(totalWaveHeight: number | undefined, windWaveHeight: number | undefined, swellHeight: number | undefined, wavePeriod: number | undefined): SafetyAssessment;
+//# sourceMappingURL=marine.d.ts.map

package/dist/utils/marine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marine.d.ts","sourceRoot":"","sources":["../../src/utils/marine.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAuB,MAAM,kBAAkB,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAqBD;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,IAAI,CAyBrG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAOnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMpE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQ/D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQjF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAmBnE;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CAiEpF;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CACjC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,gBAAgB,CAoClB"}

package/dist/utils/marine.js

@@ -0,0 +1,215 @@
+/**
+ * Utility functions for marine conditions data formatting and interpretation
+ */
+/**
+ * Extract current value from a gridpoint data series
+ */
+function extractCurrentValue(series) {
+    if (!series || !series.values || series.values.length === 0) {
+        return undefined;
+    }
+    // Find the first valid value (gridpoint data is time-ordered)
+    for (const entry of series.values) {
+        const value = entry.value;
+        if (value !== null && value !== undefined) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract marine conditions from NOAA gridpoint response
+ */
+export function extractNOAAMarineConditions(gridpoint) {
+    const props = gridpoint.properties;
+    // Extract marine data
+    const waveHeight = extractCurrentValue(props.waveHeight);
+    const wavePeriod = extractCurrentValue(props.wavePeriod);
+    const waveDirection = extractCurrentValue(props.waveDirection);
+    const windSpeed = extractCurrentValue(props.windSpeed);
+    const windDirection = extractCurrentValue(props.windDirection);
+    const windGust = extractCurrentValue(props.windGust);
+    // Check if we have any marine data
+    if (waveHeight === undefined && wavePeriod === undefined && waveDirection === undefined) {
+        return null;
+    }
+    return {
+        waveHeight,
+        wavePeriod,
+        waveDirection,
+        windSpeed,
+        windDirection,
+        windGust,
+        timestamp: props.updateTime
+    };
+}
+/**
+ * Format wave height with appropriate units and precision
+ */
+export function formatWaveHeight(meters) {
+    if (meters === undefined || meters === null) {
+        return 'N/A';
+    }
+    const feet = meters * 3.28084;
+    return `${meters.toFixed(1)}m (${feet.toFixed(1)}ft)`;
+}
+/**
+ * Format wave period with units
+ */
+export function formatWavePeriod(seconds) {
+    if (seconds === undefined || seconds === null) {
+        return 'N/A';
+    }
+    return `${seconds.toFixed(1)}s`;
+}
+/**
+ * Format wind speed with units (converts km/h to knots for marine)
+ */
+export function formatWindSpeed(kmh) {
+    if (kmh === undefined || kmh === null) {
+        return 'N/A';
+    }
+    // Convert km/h to knots (1 km/h = 0.539957 knots)
+    const knots = kmh * 0.539957;
+    return `${knots.toFixed(1)} knots (${kmh.toFixed(1)} km/h)`;
+}
+/**
+ * Format ocean current velocity
+ */
+export function formatCurrentVelocity(metersPerSecond) {
+    if (metersPerSecond === undefined || metersPerSecond === null) {
+        return 'N/A';
+    }
+    // Convert m/s to knots (1 m/s = 1.94384 knots)
+    const knots = metersPerSecond * 1.94384;
+    return `${metersPerSecond.toFixed(2)} m/s (${knots.toFixed(2)} knots)`;
+}
+/**
+ * Convert degrees to cardinal/ordinal direction
+ */
+export function formatDirection(degrees) {
+    if (degrees === undefined || degrees === null) {
+        return 'N/A';
+    }
+    const directions = [
+        'N', 'NNE', 'NE', 'ENE',
+        'E', 'ESE', 'SE', 'SSE',
+        'S', 'SSW', 'SW', 'WSW',
+        'W', 'WNW', 'NW', 'NNW'
+    ];
+    // Normalize to 0-360
+    const normalized = ((degrees % 360) + 360) % 360;
+    // Calculate index (16 directions, each 22.5 degrees)
+    const index = Math.round(normalized / 22.5) % 16;
+    return `${directions[index]} (${Math.round(normalized)}°)`;
+}
+export function getWaveHeightCategory(meters) {
+    if (meters === undefined || meters === null) {
+        return {
+            description: 'Unknown',
+            level: 'Unknown',
+            recommendation: 'No data available'
+        };
+    }
+    // Based on WMO Sea State Code and Douglas Sea Scale
+    if (meters < 0.1) {
+        return {
+            description: 'Calm (glassy)',
+            level: 'Calm',
+            recommendation: 'Ideal for all water activities'
+        };
+    }
+    else if (meters < 0.5) {
+        return {
+            description: 'Calm (rippled)',
+            level: 'Calm',
+            recommendation: 'Excellent conditions for all vessels'
+        };
+    }
+    else if (meters < 1.25) {
+        return {
+            description: 'Smooth',
+            level: 'Slight',
+            recommendation: 'Good conditions for most activities'
+        };
+    }
+    else if (meters < 2.5) {
+        return {
+            description: 'Slight',
+            level: 'Moderate',
+            recommendation: 'Safe for experienced boaters'
+        };
+    }
+    else if (meters < 4.0) {
+        return {
+            description: 'Moderate',
+            level: 'Moderate',
+            recommendation: 'Use caution, especially for small craft'
+        };
+    }
+    else if (meters < 6.0) {
+        return {
+            description: 'Rough',
+            level: 'Rough',
+            recommendation: 'Hazardous for small vessels, secure all gear'
+        };
+    }
+    else if (meters < 9.0) {
+        return {
+            description: 'Very Rough',
+            level: 'Very Rough',
+            recommendation: 'Dangerous conditions, avoid non-essential travel'
+        };
+    }
+    else if (meters < 14.0) {
+        return {
+            description: 'High',
+            level: 'High',
+            recommendation: 'Very dangerous, only experienced vessels should be out'
+        };
+    }
+    else {
+        return {
+            description: 'Very High',
+            level: 'Extreme',
+            recommendation: 'Extremely dangerous, all vessels should seek shelter'
+        };
+    }
+}
+export function getSafetyAssessment(totalWaveHeight, windWaveHeight, swellHeight, wavePeriod) {
+    if (totalWaveHeight === undefined || totalWaveHeight === null) {
+        return {
+            level: 'Unknown',
+            description: 'Marine conditions data not available',
+            recommendation: 'Consult local marine forecast'
+        };
+    }
+    const waveCategory = getWaveHeightCategory(totalWaveHeight);
+    // Adjust based on wave period (short period = choppy/uncomfortable)
+    let adjustedDescription = waveCategory.description;
+    if (wavePeriod !== undefined && wavePeriod < 6 && totalWaveHeight > 1.0) {
+        adjustedDescription += ' and choppy (short period)';
+    }
+    else if (wavePeriod !== undefined && wavePeriod > 12 && totalWaveHeight > 2.0) {
+        adjustedDescription += ' with long-period swell (powerful)';
+    }
+    // Add context about wind vs swell
+    let context = '';
+    if (windWaveHeight !== undefined && swellHeight !== undefined) {
+        if (windWaveHeight > swellHeight * 1.5) {
+            context = ' Conditions dominated by local wind waves.';
+        }
+        else if (swellHeight > windWaveHeight * 1.5) {
+            context = ' Conditions dominated by swell from distant systems.';
+        }
+        else {
+            context = ' Mixed wind and swell conditions.';
+        }
+    }
+    return {
+        level: waveCategory.level,
+        description: adjustedDescription + context,
+        recommendation: waveCategory.recommendation
+    };
+}
+//# sourceMappingURL=marine.js.map

package/dist/utils/marine.js.map

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

package/dist/utils/normals.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Utility functions for computing climate normals from historical data
+ *
+ * Climate normals are 30-year averages (1991-2020) used to provide
+ * context for current weather conditions.
+ *
+ * Hybrid Strategy:
+ * 1. Try NCEI (US only, requires token) for official normals
+ * 2. Fall back to Open-Meteo (global, no token) computed normals
+ */
+import type { OpenMeteoHistoricalResponse, ClimateNormals } from '../types/openmeteo.js';
+import type { OpenMeteoService } from '../services/openmeteo.js';
+import type { NCEIService } from '../services/ncei.js';
+/**
+ * Compute climate normals from 30 years of historical data
+ *
+ * @param historicalData - 30 years of daily historical weather data from Open-Meteo
+ * @param targetMonth - Month (1-12) to compute normals for
+ * @param targetDay - Day of month (1-31) to compute normals for
+ * @returns Climate normals (30-year averages) for the specified date
+ */
+export declare function computeNormalsFrom30YearData(historicalData: OpenMeteoHistoricalResponse, targetMonth: number, targetDay: number): ClimateNormals;
+/**
+ * Generate a cache key for climate normals
+ *
+ * @param latitude - Latitude (rounded to 2 decimals)
+ * @param longitude - Longitude (rounded to 2 decimals)
+ * @param month - Month (1-12)
+ * @param day - Day of month (1-31)
+ * @returns Cache key string
+ */
+export declare function getNormalsCacheKey(latitude: number, longitude: number, month: number, day: number): string;
+/**
+ * Calculate departure from normal
+ *
+ * @param actual - Actual temperature value
+ * @param normal - Normal (average) temperature value
+ * @returns Departure with sign (e.g., +10, -5)
+ */
+export declare function calculateDeparture(actual: number, normal: number): string;
+/**
+ * Format climate normals for display
+ *
+ * @param normals - Climate normals data
+ * @param currentTemp - Optional current temperature for comparison
+ * @returns Formatted markdown string
+ */
+export declare function formatNormals(normals: ClimateNormals, currentTemp?: {
+    high?: number;
+    low?: number;
+}): string;
+/**
+ * Get date components from Date object or ISO string
+ *
+ * @param date - Date object or ISO string
+ * @returns Object with month (1-12) and day (1-31)
+ */
+export declare function getDateComponents(date: Date | string): {
+    month: number;
+    day: number;
+};
+/**
+ * Check if coordinates are within the contiguous United States
+ *
+ * @param latitude - Latitude
+ * @param longitude - Longitude
+ * @returns true if location is in contiguous US
+ */
+export declare function isLocationInUS(latitude: number, longitude: number): boolean;
+/**
+ * Get climate normals using hybrid strategy
+ *
+ * Strategy:
+ * 1. If location is in US and NCEI token available, try NCEI first
+ * 2. Fall back to Open-Meteo computed normals (always works)
+ *
+ * @param openMeteoService - Open-Meteo service instance
+ * @param nceiService - NCEI service instance (optional)
+ * @param latitude - Latitude
+ * @param longitude - Longitude
+ * @param month - Month (1-12)
+ * @param day - Day of month (1-31)
+ * @returns Climate normals with source indication
+ */
+export declare function getClimateNormals(openMeteoService: OpenMeteoService, nceiService: NCEIService | undefined, latitude: number, longitude: number, month: number, day: number): Promise<ClimateNormals>;
+//# sourceMappingURL=normals.d.ts.map

package/dist/utils/normals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normals.d.ts","sourceRoot":"","sources":["../../src/utils/normals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAUvD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,2BAA2B,EAC3C,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,cAAc,CAsDhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,MAAM,CAKR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,WAAW,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,MAAM,CAkCR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAMrF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAU3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,gBAAgB,EAAE,gBAAgB,EAClC,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,CAAC,CA8CzB"}