@xenterprises/fastify-xgeocode 1.0.1

package/src/xGeocode.js

@@ -0,0 +1,363 @@
+import fp from "fastify-plugin";
+
+async function xGeocode(fastify, options) {
+  const { active = true, apiKey } = options;
+
+  if (active === false) {
+    return;
+  }
+
+  if (!apiKey) {
+    throw new Error("xGeocode: apiKey is required in options");
+  }
+
+  const geocodioEndpoint = 'https://api.geocod.io/v1.7/geocode';
+  const reverseEndpoint = 'https://api.geocod.io/v1.7/reverse';
+
+  // Helper to validate zip code format
+  function validateZipCode(zipCode) {
+    if (!zipCode || typeof zipCode !== 'string') {
+      throw new Error('xGeocode: Invalid input - zipCode must be a non-empty string');
+    }
+
+    // Match 5-digit or 9-digit (ZIP+4) format
+    if (!/^\d{5}(-\d{4})?$/.test(zipCode.trim())) {
+      throw new Error('xGeocode: Invalid zip code format - must be 5 digits or 9 digits (ZIP+4)');
+    }
+
+    return zipCode.trim();
+  }
+
+  // Helper to validate address string
+  function validateAddress(address) {
+    if (!address || typeof address !== 'string') {
+      throw new Error('xGeocode: Invalid input - address must be a non-empty string');
+    }
+
+    if (address.trim().length < 3) {
+      throw new Error('xGeocode: Invalid address - minimum 3 characters required');
+    }
+
+    return address.trim();
+  }
+
+  // Helper to validate coordinates
+  function validateCoordinates(lat, lng) {
+    const latitude = parseFloat(lat);
+    const longitude = parseFloat(lng);
+
+    if (isNaN(latitude) || isNaN(longitude)) {
+      throw new Error('xGeocode: Invalid coordinates - latitude and longitude must be numbers');
+    }
+
+    if (latitude < -90 || latitude > 90) {
+      throw new Error('xGeocode: Invalid latitude - must be between -90 and 90');
+    }
+
+    if (longitude < -180 || longitude > 180) {
+      throw new Error('xGeocode: Invalid longitude - must be between -180 and 180');
+    }
+
+    return { latitude, longitude };
+  }
+
+  // Helper to parse API response
+  function parseGeocodeResult(result) {
+    if (!result.results || result.results.length === 0) {
+      throw new Error('xGeocode: No results found');
+    }
+
+    const location = result.results[0].location;
+    const addressComponents = result.results[0].address_components;
+
+    return {
+      lat: location.lat,
+      lng: location.lng,
+      formatted_address: result.results[0].formatted_address || null,
+      city: addressComponents.city || null,
+      county: addressComponents.county || null,
+      country: addressComponents.country || null,
+      state: addressComponents.state || null,
+      zip: addressComponents.zip || null,
+      addressComponents
+    };
+  }
+
+  // Haversine formula to calculate distance between two points
+  function calculateHaversineDistance(lat1, lng1, lat2, lng2) {
+    const R = 6371; // Earth's radius in kilometers
+    const dLat = (lat2 - lat1) * (Math.PI / 180);
+    const dLng = (lng2 - lng1) * (Math.PI / 180);
+
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+              Math.cos(lat1 * (Math.PI / 180)) * Math.cos(lat2 * (Math.PI / 180)) *
+              Math.sin(dLng / 2) * Math.sin(dLng / 2);
+
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    const km = R * c;
+
+    return {
+      kilometers: Math.round(km * 100) / 100,
+      miles: Math.round((km * 0.621371) * 100) / 100,
+      meters: Math.round(km * 1000)
+    };
+  }
+
+  fastify.decorate('xGeocode', {
+    /**
+     * Get latitude, longitude, and address components from a zip code
+     * @param {string} zipCode - The zip code to geocode (5 or 9 digits)
+     * @returns {Promise<Object>} Object with zip, lat, lng, city, county, country, state, and addressComponents
+     */
+    async getLatLongByZip(zipCode) {
+      try {
+        const validZip = validateZipCode(zipCode);
+        const url = `${geocodioEndpoint}?q=${encodeURIComponent(validZip)}&fields=cd,stateleg&api_key=${apiKey}`;
+        const response = await fetch(url);
+
+        if (!response.ok) {
+          const error = process.env.NODE_ENV === 'production'
+            ? 'Geocoding service unavailable'
+            : `Geocoding API returned ${response.status}`;
+          throw new Error(error);
+        }
+
+        const result = await response.json();
+        const parsed = parseGeocodeResult(result);
+
+        return {
+          zip: validZip,
+          ...parsed
+        };
+      } catch (error) {
+        const message = error.message || 'Unknown error in geocoding';
+        const sanitizedMessage = process.env.NODE_ENV === 'production'
+          ? 'Failed to geocode address'
+          : message;
+
+        if (process.env.NODE_ENV !== 'production') {
+          console.error('xGeocode error:', message);
+        }
+
+        throw new Error(sanitizedMessage);
+      }
+    },
+
+    /**
+     * Get latitude, longitude, and address components from a street address
+     * @param {string} address - The street address to geocode (e.g., "123 Main St, New York, NY")
+     * @returns {Promise<Object>} Object with lat, lng, formatted_address, city, state, etc.
+     */
+    async getLatLongByAddress(address) {
+      try {
+        const validAddress = validateAddress(address);
+        const url = `${geocodioEndpoint}?q=${encodeURIComponent(validAddress)}&fields=cd,stateleg&api_key=${apiKey}`;
+        const response = await fetch(url);
+
+        if (!response.ok) {
+          const error = process.env.NODE_ENV === 'production'
+            ? 'Geocoding service unavailable'
+            : `Geocoding API returned ${response.status}`;
+          throw new Error(error);
+        }
+
+        const result = await response.json();
+        return parseGeocodeResult(result);
+      } catch (error) {
+        const message = error.message || 'Unknown error in geocoding';
+        const sanitizedMessage = process.env.NODE_ENV === 'production'
+          ? 'Failed to geocode address'
+          : message;
+
+        if (process.env.NODE_ENV !== 'production') {
+          console.error('xGeocode error:', message);
+        }
+
+        throw new Error(sanitizedMessage);
+      }
+    },
+
+    /**
+     * Get address from latitude and longitude (reverse geocoding)
+     * @param {number} lat - Latitude coordinate
+     * @param {number} lng - Longitude coordinate
+     * @returns {Promise<Object>} Object with formatted_address, city, state, zip, etc.
+     */
+    async getReverseGeocode(lat, lng) {
+      try {
+        const { latitude, longitude } = validateCoordinates(lat, lng);
+        const url = `${reverseEndpoint}?q=${latitude},${longitude}&fields=cd,stateleg&api_key=${apiKey}`;
+        const response = await fetch(url);
+
+        if (!response.ok) {
+          const error = process.env.NODE_ENV === 'production'
+            ? 'Reverse geocoding service unavailable'
+            : `Reverse geocoding API returned ${response.status}`;
+          throw new Error(error);
+        }
+
+        const result = await response.json();
+        return parseGeocodeResult(result);
+      } catch (error) {
+        const message = error.message || 'Unknown error in reverse geocoding';
+        const sanitizedMessage = process.env.NODE_ENV === 'production'
+          ? 'Failed to reverse geocode coordinates'
+          : message;
+
+        if (process.env.NODE_ENV !== 'production') {
+          console.error('xGeocode error:', message);
+        }
+
+        throw new Error(sanitizedMessage);
+      }
+    },
+
+    /**
+     * Calculate distance between two geographic points
+     * @param {number} lat1 - Origin latitude
+     * @param {number} lng1 - Origin longitude
+     * @param {number} lat2 - Destination latitude
+     * @param {number} lng2 - Destination longitude
+     * @returns {Object} Distance in kilometers, miles, and meters
+     */
+    getDistance(lat1, lng1, lat2, lng2) {
+      try {
+        const origin = validateCoordinates(lat1, lng1);
+        const destination = validateCoordinates(lat2, lng2);
+
+        return calculateHaversineDistance(
+          origin.latitude,
+          origin.longitude,
+          destination.latitude,
+          destination.longitude
+        );
+      } catch (error) {
+        const message = error.message || 'Unknown error calculating distance';
+        const sanitizedMessage = process.env.NODE_ENV === 'production'
+          ? 'Failed to calculate distance'
+          : message;
+
+        if (process.env.NODE_ENV !== 'production') {
+          console.error('xGeocode error:', message);
+        }
+
+        throw new Error(sanitizedMessage);
+      }
+    },
+
+    /**
+     * Geocode multiple addresses or ZIP codes in a single operation
+     * @param {Array<string>} locations - Array of addresses or ZIP codes
+     * @returns {Promise<Array>} Array of geocoded results
+     */
+    async batchGeocode(locations) {
+      try {
+        if (!Array.isArray(locations)) {
+          throw new Error('xGeocode: locations must be an array');
+        }
+
+        if (locations.length === 0) {
+          throw new Error('xGeocode: locations array cannot be empty');
+        }
+
+        if (locations.length > 100) {
+          throw new Error('xGeocode: batch size cannot exceed 100 locations');
+        }
+
+        const results = await Promise.all(
+          locations.map(async (location) => {
+            try {
+              // Try as ZIP code first, fall back to address
+              if (/^\d{5}(-\d{4})?$/.test(location.trim())) {
+                return await this.getLatLongByZip(location);
+              } else {
+                const result = await this.getLatLongByAddress(location);
+                return { original: location, ...result };
+              }
+            } catch (error) {
+              return {
+                original: location,
+                error: error.message,
+                success: false
+              };
+            }
+          })
+        );
+
+        return results;
+      } catch (error) {
+        const message = error.message || 'Unknown error in batch geocoding';
+        const sanitizedMessage = process.env.NODE_ENV === 'production'
+          ? 'Failed to batch geocode addresses'
+          : message;
+
+        if (process.env.NODE_ENV !== 'production') {
+          console.error('xGeocode error:', message);
+        }
+
+        throw new Error(sanitizedMessage);
+      }
+    },
+
+    /**
+     * Validate and get standardized format for an address
+     * @param {string} address - The address to validate
+     * @returns {Promise<Object>} Object with validity, formatted address, and components
+     */
+    async validateAddress(address) {
+      try {
+        const validAddress = validateAddress(address);
+
+        // Use geocoding to validate the address
+        const url = `${geocodioEndpoint}?q=${encodeURIComponent(validAddress)}&fields=cd,stateleg&api_key=${apiKey}`;
+        const response = await fetch(url);
+
+        if (!response.ok) {
+          return {
+            valid: false,
+            input: address,
+            error: process.env.NODE_ENV === 'production'
+              ? 'Validation service unavailable'
+              : `API returned ${response.status}`
+          };
+        }
+
+        const result = await response.json();
+
+        if (!result.results || result.results.length === 0) {
+          return {
+            valid: false,
+            input: address,
+            error: 'Address not recognized'
+          };
+        }
+
+        const parsed = parseGeocodeResult(result);
+        return {
+          valid: true,
+          input: address,
+          formatted: result.results[0].formatted_address,
+          confidence: result.results[0].accuracy || 'unknown',
+          ...parsed
+        };
+      } catch (error) {
+        const message = error.message || 'Unknown error validating address';
+        const sanitizedMessage = process.env.NODE_ENV === 'production'
+          ? 'Failed to validate address'
+          : message;
+
+        if (process.env.NODE_ENV !== 'production') {
+          console.error('xGeocode error:', message);
+        }
+
+        throw new Error(sanitizedMessage);
+      }
+    }
+  });
+
+  console.info("   ✅ Geocoding Enabled");
+}
+
+export default fp(xGeocode, {
+  name: "xGeocode",
+});