@jablum/weather-mcp 1.7.0

package/dist/utils/timezone.js

@@ -0,0 +1,167 @@
+/**
+ * Utility functions for timezone-aware time formatting
+ * Uses Luxon for timezone support with native Intl API
+ */
+import { DateTime } from 'luxon';
+/**
+ * Format an ISO 8601 datetime string in the specified timezone
+ * @param isoString - ISO 8601 datetime string (e.g., "2025-11-07T14:30:00+00:00")
+ * @param timezone - IANA timezone identifier (e.g., "America/New_York", "Asia/Tokyo")
+ * @param format - Optional format style ('full', 'long', 'medium', 'short')
+ * @returns Formatted datetime string in local timezone
+ */
+export function formatInTimezone(isoString, timezone, format = 'medium') {
+    try {
+        const dt = DateTime.fromISO(isoString, { setZone: false });
+        if (!dt.isValid) {
+            // Fallback to JavaScript Date if Luxon can't parse
+            return new Date(isoString).toLocaleString('en-US', { timeZone: timezone });
+        }
+        const zonedDt = dt.setZone(timezone);
+        // Format based on requested style
+        switch (format) {
+            case 'full':
+                return zonedDt.toLocaleString(DateTime.DATETIME_FULL);
+            case 'long':
+                return zonedDt.toLocaleString(DateTime.DATETIME_MED_WITH_SECONDS);
+            case 'short':
+                return zonedDt.toLocaleString(DateTime.DATETIME_SHORT);
+            case 'medium':
+            default:
+                return zonedDt.toLocaleString(DateTime.DATETIME_MED);
+        }
+    }
+    catch (error) {
+        // Fallback to standard Date formatting if anything goes wrong
+        return new Date(isoString).toLocaleString('en-US', { timeZone: timezone });
+    }
+}
+/**
+ * Format a date-only ISO string in the specified timezone
+ * @param isoString - ISO 8601 datetime string
+ * @param timezone - IANA timezone identifier
+ * @returns Formatted date string (e.g., "Nov 7, 2025")
+ */
+export function formatDateInTimezone(isoString, timezone) {
+    try {
+        const dt = DateTime.fromISO(isoString, { setZone: false });
+        if (!dt.isValid) {
+            return new Date(isoString).toLocaleDateString('en-US', { timeZone: timezone });
+        }
+        const zonedDt = dt.setZone(timezone);
+        return zonedDt.toLocaleString(DateTime.DATE_MED);
+    }
+    catch (error) {
+        return new Date(isoString).toLocaleDateString('en-US', { timeZone: timezone });
+    }
+}
+/**
+ * Format a time-only ISO string in the specified timezone
+ * @param isoString - ISO 8601 datetime string
+ * @param timezone - IANA timezone identifier
+ * @returns Formatted time string (e.g., "2:30 PM EST")
+ */
+export function formatTimeInTimezone(isoString, timezone) {
+    try {
+        const dt = DateTime.fromISO(isoString, { setZone: false });
+        if (!dt.isValid) {
+            return new Date(isoString).toLocaleTimeString('en-US', {
+                timeZone: timezone,
+                timeZoneName: 'short'
+            });
+        }
+        const zonedDt = dt.setZone(timezone);
+        return zonedDt.toLocaleString(DateTime.TIME_WITH_SHORT_OFFSET);
+    }
+    catch (error) {
+        return new Date(isoString).toLocaleTimeString('en-US', {
+            timeZone: timezone,
+            timeZoneName: 'short'
+        });
+    }
+}
+/**
+ * Get timezone abbreviation from IANA timezone identifier
+ * @param timezone - IANA timezone identifier (e.g., "America/New_York")
+ * @param datetime - Optional datetime to determine DST status
+ * @returns Timezone abbreviation (e.g., "EST" or "EDT")
+ */
+export function getTimezoneAbbreviation(timezone, datetime) {
+    try {
+        const dt = datetime
+            ? DateTime.fromJSDate(datetime).setZone(timezone)
+            : DateTime.now().setZone(timezone);
+        return dt.offsetNameShort || dt.toFormat('ZZZZ');
+    }
+    catch (error) {
+        return timezone;
+    }
+}
+/**
+ * Detect timezone from coordinates using a simple heuristic
+ * This is a fallback when timezone is not provided by APIs
+ * @param latitude - Latitude
+ * @param longitude - Longitude
+ * @returns Best-guess IANA timezone identifier
+ */
+export function guessTimezoneFromCoords(latitude, longitude) {
+    // This is a simplified heuristic - in practice, APIs usually provide timezone
+    // For production use, consider integrating a proper coordinate-to-timezone library
+    // like tz-lookup or @photostructure/tz-lookup for accurate global coverage
+    // Map to common US timezones for North America based on longitude
+    if (latitude >= 24 && latitude <= 50 && longitude >= -125 && longitude <= -66) {
+        if (longitude >= -75)
+            return 'America/New_York';
+        if (longitude >= -87)
+            return 'America/Chicago';
+        if (longitude >= -104)
+            return 'America/Denver';
+        if (longitude >= -125)
+            return 'America/Los_Angeles';
+    }
+    // For international locations, default to UTC instead of server timezone
+    // This provides predictable, unambiguous timestamps for all users
+    // Note: The previous fallback to Intl.DateTimeFormat().resolvedOptions().timeZone
+    // would return the server's local timezone, which is misleading for international queries
+    return 'UTC';
+}
+/**
+ * Format a time range with timezone context
+ * @param startTime - Start time ISO string
+ * @param endTime - End time ISO string
+ * @param timezone - IANA timezone identifier
+ * @returns Formatted range (e.g., "Nov 7, 2:00 PM - 5:00 PM EST")
+ */
+export function formatTimeRangeInTimezone(startTime, endTime, timezone) {
+    try {
+        const start = DateTime.fromISO(startTime, { setZone: false }).setZone(timezone);
+        const end = DateTime.fromISO(endTime, { setZone: false }).setZone(timezone);
+        if (!start.isValid || !end.isValid) {
+            return `${formatInTimezone(startTime, timezone, 'short')} - ${formatInTimezone(endTime, timezone, 'short')}`;
+        }
+        // If same day, show: "Nov 7, 2:00 PM - 5:00 PM EST"
+        if (start.hasSame(end, 'day')) {
+            return `${start.toLocaleString(DateTime.DATE_MED)}, ${start.toLocaleString(DateTime.TIME_SIMPLE)} - ${end.toLocaleString(DateTime.TIME_SIMPLE)} ${start.offsetNameShort}`;
+        }
+        // Different days: "Nov 7, 2:00 PM - Nov 8, 5:00 PM EST"
+        return `${start.toLocaleString(DateTime.DATETIME_MED)} - ${end.toLocaleString(DateTime.DATETIME_MED)}`;
+    }
+    catch (error) {
+        return `${formatInTimezone(startTime, timezone, 'short')} - ${formatInTimezone(endTime, timezone, 'short')}`;
+    }
+}
+/**
+ * Check if a timezone is valid IANA timezone identifier
+ * @param timezone - Timezone string to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidTimezone(timezone) {
+    try {
+        DateTime.now().setZone(timezone);
+        return DateTime.now().setZone(timezone).isValid;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=timezone.js.map

package/dist/utils/timezone.js.map

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

package/dist/utils/units.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Utility functions for unit conversion and formatting
+ */
+import { QuantitativeValue } from '../types/noaa.js';
+/**
+ * Extract numeric value from QuantitativeValue, handling null values
+ */
+export declare function extractValue(qv: QuantitativeValue | undefined): number | null;
+/**
+ * Convert Celsius to Fahrenheit
+ */
+export declare function celsiusToFahrenheit(celsius: number): number;
+/**
+ * Convert meters per second to miles per hour
+ */
+export declare function mpsToMph(mps: number): number;
+/**
+ * Convert kilometers per hour to miles per hour
+ */
+export declare function kphToMph(kph: number): number;
+/**
+ * Convert meters to miles
+ */
+export declare function metersToMiles(meters: number): number;
+/**
+ * Convert meters to feet
+ */
+export declare function metersToFeet(meters: number): number;
+/**
+ * Convert Pascals to inches of mercury
+ */
+export declare function pascalsToInHg(pa: number): number;
+/**
+ * Convert Pascals to millibars/hectopascals
+ */
+export declare function pascalsToMb(pa: number): number;
+/**
+ * Format temperature with unit
+ */
+export declare function formatTemperature(qv: QuantitativeValue | undefined, preferFahrenheit?: boolean): string;
+/**
+ * Format wind speed with unit
+ */
+export declare function formatWindSpeed(qv: QuantitativeValue | undefined): string;
+/**
+ * Format visibility with unit
+ */
+export declare function formatVisibility(qv: QuantitativeValue | undefined): string;
+/**
+ * Format pressure with unit
+ */
+export declare function formatPressure(qv: QuantitativeValue | undefined): string;
+/**
+ * Format a percentage value
+ */
+export declare function formatPercentage(qv: QuantitativeValue | undefined): string;
+/**
+ * Format wind direction from degrees to cardinal direction
+ */
+export declare function formatWindDirection(qv: QuantitativeValue | undefined): string;
+/**
+ * Format date/time in readable format
+ */
+export declare function formatDateTime(isoString: string): string;
+/**
+ * Format date only
+ */
+export declare function formatDate(isoString: string): string;
+//# sourceMappingURL=units.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/utils/units.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;;GAEG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAK7E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,iBAAiB,GAAG,SAAS,EAAE,gBAAgB,UAAO,GAAG,MAAM,CAcpG;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAazE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAO1E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAOxE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAK1E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAQ7E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAUxD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQpD"}

package/dist/utils/units.js

@@ -0,0 +1,158 @@
+/**
+ * Utility functions for unit conversion and formatting
+ */
+/**
+ * Extract numeric value from QuantitativeValue, handling null values
+ */
+export function extractValue(qv) {
+    if (!qv || qv.value === null || qv.value === undefined) {
+        return null;
+    }
+    return qv.value;
+}
+/**
+ * Convert Celsius to Fahrenheit
+ */
+export function celsiusToFahrenheit(celsius) {
+    return (celsius * 9 / 5) + 32;
+}
+/**
+ * Convert meters per second to miles per hour
+ */
+export function mpsToMph(mps) {
+    return mps * 2.23694;
+}
+/**
+ * Convert kilometers per hour to miles per hour
+ */
+export function kphToMph(kph) {
+    return kph * 0.621371;
+}
+/**
+ * Convert meters to miles
+ */
+export function metersToMiles(meters) {
+    return meters * 0.000621371;
+}
+/**
+ * Convert meters to feet
+ */
+export function metersToFeet(meters) {
+    return meters * 3.28084;
+}
+/**
+ * Convert Pascals to inches of mercury
+ */
+export function pascalsToInHg(pa) {
+    return pa * 0.0002953;
+}
+/**
+ * Convert Pascals to millibars/hectopascals
+ */
+export function pascalsToMb(pa) {
+    return pa / 100;
+}
+/**
+ * Format temperature with unit
+ */
+export function formatTemperature(qv, preferFahrenheit = true) {
+    const value = extractValue(qv);
+    if (value === null)
+        return 'N/A';
+    // NOAA returns temperature in Celsius in unitCode format "wmoUnit:degC"
+    if (qv?.unitCode?.includes('degC')) {
+        if (preferFahrenheit) {
+            return `${Math.round(celsiusToFahrenheit(value))}°F`;
+        }
+        return `${Math.round(value)}°C`;
+    }
+    // If already in Fahrenheit
+    return `${Math.round(value)}°F`;
+}
+/**
+ * Format wind speed with unit
+ */
+export function formatWindSpeed(qv) {
+    const value = extractValue(qv);
+    if (value === null)
+        return 'Calm';
+    // Convert to mph if needed
+    let mph = value;
+    if (qv?.unitCode?.includes('km_h')) {
+        mph = kphToMph(value);
+    }
+    else if (qv?.unitCode?.includes('m_s')) {
+        mph = mpsToMph(value);
+    }
+    return `${Math.round(mph)} mph`;
+}
+/**
+ * Format visibility with unit
+ */
+export function formatVisibility(qv) {
+    const value = extractValue(qv);
+    if (value === null)
+        return 'N/A';
+    // Convert meters to miles
+    const miles = metersToMiles(value);
+    return `${miles.toFixed(1)} miles`;
+}
+/**
+ * Format pressure with unit
+ */
+export function formatPressure(qv) {
+    const value = extractValue(qv);
+    if (value === null)
+        return 'N/A';
+    // Convert Pascals to inHg
+    const inHg = pascalsToInHg(value);
+    return `${inHg.toFixed(2)} inHg`;
+}
+/**
+ * Format a percentage value
+ */
+export function formatPercentage(qv) {
+    const value = extractValue(qv);
+    if (value === null)
+        return 'N/A';
+    return `${Math.round(value)}%`;
+}
+/**
+ * Format wind direction from degrees to cardinal direction
+ */
+export function formatWindDirection(qv) {
+    const degrees = extractValue(qv);
+    if (degrees === null)
+        return 'Variable';
+    const directions = ['N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE',
+        'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW'];
+    const index = Math.round(degrees / 22.5) % 16;
+    return directions[index];
+}
+/**
+ * Format date/time in readable format
+ */
+export function formatDateTime(isoString) {
+    const date = new Date(isoString);
+    return date.toLocaleString('en-US', {
+        weekday: 'short',
+        month: 'short',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: '2-digit',
+        timeZoneName: 'short'
+    });
+}
+/**
+ * Format date only
+ */
+export function formatDate(isoString) {
+    const date = new Date(isoString);
+    return date.toLocaleDateString('en-US', {
+        weekday: 'long',
+        month: 'long',
+        day: 'numeric',
+        year: 'numeric'
+    });
+}
+//# sourceMappingURL=units.js.map

package/dist/utils/units.js.map

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

package/dist/utils/validation.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Input validation utilities for API parameters
+ * Provides runtime type checking and sanitization
+ */
+/**
+ * Validate that latitude is a valid number within range
+ * @param lat - Latitude value to validate
+ * @throws {Error} If latitude is invalid
+ */
+export declare function validateLatitude(lat: unknown): asserts lat is number;
+/**
+ * Validate that longitude is a valid number within range
+ * @param lon - Longitude value to validate
+ * @throws {Error} If longitude is invalid
+ */
+export declare function validateLongitude(lon: unknown): asserts lon is number;
+/**
+ * Validate coordinate pair
+ * @param args - Arguments object potentially containing coordinates
+ * @returns Validated coordinates
+ * @throws {Error} If coordinates are invalid
+ */
+export declare function validateCoordinates(args: unknown): {
+    latitude: number;
+    longitude: number;
+};
+/**
+ * Validate a positive integer within optional range
+ * @param value - Value to validate
+ * @param name - Parameter name for error messages
+ * @param min - Minimum allowed value (inclusive)
+ * @param max - Maximum allowed value (inclusive)
+ * @returns Validated number
+ * @throws {Error} If value is invalid
+ */
+export declare function validatePositiveInteger(value: unknown, name: string, min?: number, max?: number): number;
+/**
+ * Validate a boolean value
+ * @param value - Value to validate
+ * @param name - Parameter name for error messages
+ * @returns Validated boolean
+ * @throws {Error} If value is invalid
+ */
+export declare function validateBoolean(value: unknown, name: string): boolean;
+/**
+ * Validate a date string in ISO format
+ * @param value - Value to validate
+ * @param name - Parameter name for error messages
+ * @returns Validated date string
+ * @throws {Error} If value is invalid
+ */
+export declare function validateDateString(value: unknown, name: string): string;
+/**
+ * Validate forecast days parameter
+ * @param args - Arguments object potentially containing days parameter
+ * @returns Validated days value (defaults to 7 if not provided)
+ * @throws {Error} If days parameter is invalid
+ */
+export declare function validateForecastDays(args: unknown): number;
+/**
+ * Validate granularity parameter
+ * @param value - Value to validate
+ * @returns Validated granularity ('daily' or 'hourly')
+ * @throws {Error} If value is invalid
+ */
+export declare function validateGranularity(value: unknown): 'daily' | 'hourly';
+/**
+ * Validate optional boolean with default
+ * @param value - Value to validate
+ * @param name - Parameter name for error messages
+ * @param defaultValue - Default value if undefined
+ * @returns Validated boolean
+ * @throws {Error} If value is invalid
+ */
+export declare function validateOptionalBoolean(value: unknown, name: string, defaultValue: boolean): boolean;
+/**
+ * Validate historical weather parameters
+ * @param args - Arguments object
+ * @returns Validated parameters
+ * @throws {Error} If parameters are invalid
+ */
+export declare function validateHistoricalWeatherParams(args: unknown): {
+    latitude: number;
+    longitude: number;
+    start_date: string;
+    end_date: string;
+    limit?: number;
+};
+//# sourceMappingURL=validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,MAAM,CAOpE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,MAAM,CAOrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAW1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,MAAU,EACf,GAAG,GAAE,MAAgC,GACpC,MAAM,CAWR;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAKrE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAY1D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CActE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,OAAO,GACpB,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,OAAO,GAAG;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAoCA"}