@xenterprises/fastify-xgeocode 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-12-29
+
+### ✅ Initial Release - Production Ready
+
+#### Features
+- ✅ Easy Geocodio API integration for Fastify
+- ✅ Get latitude/longitude from zip codes (5-digit and ZIP+4 formats)
+- ✅ Retrieve address components (city, county, state, country)
+- ✅ Optional plugin activation (can be disabled with `active: false`)
+- ✅ Comprehensive error handling with environment-aware messages
+- ✅ Input validation for zip code formats
+- ✅ Full test coverage (14 tests)
+- ✅ Production-safe error logging
+
+#### Security
+- ✅ Zero vulnerabilities (npm audit clean)
+- ✅ Environment-aware error messages (stack traces hidden in production)
+- ✅ URL encoding for API parameters to prevent injection
+- ✅ Input validation for all parameters
+- ✅ No hardcoded secrets
+
+#### Testing
+- ✅ 14 comprehensive tests covering:
+  - Plugin registration and configuration
+  - Input validation (zip code formats)
+  - Error handling (API errors, empty results)
+  - Response structure validation
+  - Edge cases (null values, whitespace trimming)
+  - API mocking for unit testing
+  - All tests passing (100%)
+
+#### Documentation
+- ✅ README.md with quick start and usage examples
+- ✅ QUICK_START.md for getting started
+- ✅ JSDoc comments in source code
+- ✅ This CHANGELOG
+
+#### Breaking Changes
+None - this is the initial release.
+
+### Configuration
+
+```javascript
+fastify.register(xGeocode, {
+  // Required: Geocodio API key
+  apiKey: process.env.GEOCODIO_API_KEY,
+
+  // Optional: Enable/disable plugin (default: true)
+  active: true
+});
+```
+
+### API Methods
+
+#### `fastify.geocode.getLatLongByZip(zipCode)`
+
+Gets geographic coordinates and address components for a zip code.
+
+**Parameters:**
+- `zipCode` (string) - The zip code to geocode
+  - Accepts 5-digit format: "10001"
+  - Accepts ZIP+4 format: "10001-1234"
+
+**Returns:**
+- Promise resolving to an object with:
+  - `zip` - Input zip code (trimmed)
+  - `lat` - Latitude
+  - `lng` - Longitude
+  - `city` - City name
+  - `county` - County name
+  - `state` - State code
+  - `country` - Country code
+  - `addressComponents` - Full address component object
+
+**Throws:**
+- Error if zip code format is invalid
+- Error if API call fails
+- Error if no results found
+
+### Validation
+
+- Zip codes must be 5 digits or 9 digits (ZIP+4)
+- Invalid formats will throw with descriptive error messages
+- Whitespace is automatically trimmed
+- Null/undefined values are rejected
+
+### Error Handling
+
+**Development Mode (`NODE_ENV !== 'production'):**
+- Detailed error messages logged to console
+- API status codes and error details included in error messages
+
+**Production Mode (`NODE_ENV === 'production'):**
+- Generic error messages returned to clients
+- Sensitive information hidden (API status codes, etc.)
+- Error details logged internally only
+
+### Example Usage
+
+```javascript
+import Fastify from 'fastify';
+import xGeocode from '@xenterprises/fastify-xgeocode';
+
+const fastify = Fastify();
+
+await fastify.register(xGeocode, {
+  apiKey: process.env.GEOCODIO_API_KEY
+});
+
+fastify.get('/location/:zip', async (request, reply) => {
+  try {
+    const location = await fastify.geocode.getLatLongByZip(request.params.zip);
+    return { success: true, data: location };
+  } catch (error) {
+    reply.status(400);
+    return { success: false, error: error.message };
+  }
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+### Dependencies
+- `fastify-plugin` - ^5.0.0
+- `fastify` (peer) - ^5.0.0
+
+### Known Limitations
+- Requires valid Geocodio API key
+- API rate limits apply based on your Geocodio account
+- Reverse geocoding (coordinates to address) not yet implemented
+
+### Future Enhancements
+- [ ] Reverse geocoding support
+- [ ] Caching for frequently geocoded zip codes
+- [ ] Batch geocoding support
+- [ ] Support for address-based geocoding
+
+### License
+
+ISC

package/QUICK_START.md

@@ -0,0 +1,126 @@
+# xGeocode Quick Start
+
+Get up and running with geocoding in 5 minutes.
+
+## 1. Install
+
+```bash
+npm install @xenterprises/fastify-xgeocode
+```
+
+## 2. Get API Key
+
+1. Sign up at [geocod.io](https://geocod.io)
+2. Get your free or paid API key from the dashboard
+3. Add to your `.env` file:
+
+```bash
+GEOCODIO_API_KEY=your_api_key_here
+```
+
+## 3. Register Plugin
+
+```javascript
+import Fastify from 'fastify';
+import xGeocode from '@xenterprises/fastify-xgeocode';
+
+const fastify = Fastify();
+
+// Register the plugin
+fastify.register(xGeocode, {
+  apiKey: process.env.GEOCODIO_API_KEY
+});
+
+export default fastify;
+```
+
+## 4. Use in Routes
+
+```javascript
+// Get coordinates from zip code
+fastify.get('/location/:zip', async (request, reply) => {
+  const location = await fastify.geocode.getLatLongByZip(request.params.zip);
+  return location;
+});
+
+// With error handling
+fastify.get('/geo/:zip', async (request, reply) => {
+  try {
+    const location = await fastify.geocode.getLatLongByZip(request.params.zip);
+    return {
+      success: true,
+      data: location
+    };
+  } catch (error) {
+    reply.status(400);
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+});
+```
+
+## 5. Test It
+
+```bash
+curl http://localhost:3000/location/10001
+```
+
+Expected response:
+```json
+{
+  "zip": "10001",
+  "lat": 40.7506,
+  "lng": -73.9972,
+  "city": "New York",
+  "county": "New York County",
+  "state": "NY",
+  "country": "US",
+  "addressComponents": {
+    "number": "",
+    "street": "",
+    "suffix": "",
+    "city": "New York",
+    "county": "New York County",
+    "state": "NY",
+    "zip": "10001",
+    "country": "US"
+  }
+}
+```
+
+## Configuration Options
+
+```javascript
+fastify.register(xGeocode, {
+  // Required
+  apiKey: process.env.GEOCODIO_API_KEY,
+
+  // Optional - disable the plugin if needed
+  active: process.env.ENABLE_GEOCODING !== 'false'
+});
+```
+
+## Error Handling
+
+```javascript
+fastify.get('/safe-geo/:zip', async (request, reply) => {
+  try {
+    const location = await fastify.geocode.getLatLongByZip(request.params.zip);
+    return location;
+  } catch (error) {
+    fastify.log.error(error);
+    reply.status(400);
+    return { error: 'Failed to geocode address' };
+  }
+});
+```
+
+## Next Steps
+
+- Check out the [README](./README.md) for more details
+- See [API Reference](./README.md#api-reference) for all available methods
+- Get an API key: https://geocod.io
+
+That's it! You're ready to geocode addresses in your Fastify app.

package/README.md

@@ -0,0 +1,126 @@
+# xGeocode
+
+A lightweight Fastify plugin for Geocodio API integration. Provides convenient methods for geocoding addresses and retrieving geographic coordinates.
+
+## Features
+
+- ✅ Easy Geocodio API integration
+- ✅ Get latitude/longitude from zip codes
+- ✅ Retrieve address components (city, county, state, country)
+- ✅ Optional plugin (can be disabled)
+- ✅ Error handling with detailed logging
+- ✅ Fastify 5.x compatible
+
+## Installation
+
+```bash
+npm install @xenterprises/fastify-xgeocode
+```
+
+## Quick Start
+
+### 1. Register the Plugin
+
+```javascript
+import Fastify from 'fastify';
+import xGeocode from '@xenterprises/fastify-xgeocode';
+
+const fastify = Fastify();
+
+fastify.register(xGeocode, {
+  apiKey: process.env.GEOCODIO_API_KEY
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+### 2. Use in Routes
+
+```javascript
+fastify.get('/location/:zip', async (request, reply) => {
+  const { zip } = request.params;
+  const location = await fastify.geocode.getLatLongByZip(zip);
+  return location;
+});
+```
+
+## Configuration
+
+### Options
+
+```javascript
+fastify.register(xGeocode, {
+  // Required: Geocodio API key
+  apiKey: process.env.GEOCODIO_API_KEY,
+
+  // Optional: Enable/disable plugin (default: true)
+  active: true
+});
+```
+
+## Usage Examples
+
+### Get Coordinates from Zip Code
+
+```javascript
+const location = await fastify.geocode.getLatLongByZip('10001');
+console.log(location);
+// {
+//   zip: '10001',
+//   lat: 40.7506,
+//   lng: -73.9972,
+//   city: 'New York',
+//   county: 'New York County',
+//   state: 'NY',
+//   country: 'US',
+//   addressComponents: { ... }
+// }
+```
+
+### In a Route
+
+```javascript
+fastify.get('/geo/:zip', async (request, reply) => {
+  try {
+    const data = await fastify.geocode.getLatLongByZip(request.params.zip);
+    return { success: true, data };
+  } catch (error) {
+    reply.status(400);
+    return { success: false, error: error.message };
+  }
+});
+```
+
+## Environment Variables
+
+```bash
+GEOCODIO_API_KEY=your_api_key_here
+```
+
+## API Reference
+
+### `fastify.geocode.getLatLongByZip(zipCode)`
+
+Gets geographic coordinates and address components for a zip code.
+
+**Parameters:**
+- `zipCode` (string) - The zip code to geocode
+
+**Returns:**
+- Promise resolving to an object with:
+  - `zip` - Input zip code
+  - `lat` - Latitude
+  - `lng` - Longitude
+  - `city` - City name
+  - `county` - County name
+  - `state` - State code
+  - `country` - Country code
+  - `addressComponents` - Full address component object
+
+**Throws:**
+- Error if no results found
+- Error if API call fails
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@xenterprises/fastify-xgeocode",
+  "type": "module",
+  "version": "1.0.1",
+  "description": "Fastify plugin for Geocodio API integration with address geocoding and reverse geocoding.",
+  "main": "src/xGeocode.js",
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/xGeocode.test.js"
+  },
+  "keywords": [
+    "fastify",
+    "geocoding",
+    "geocodio",
+    "geolocation",
+    "addresses",
+    "coordinates"
+  ],
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-geocode"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-geocode/-/issues"
+  },
+  "homepage": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-geocode#readme",
+  "dependencies": {
+    "fastify-plugin": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "fastify": "^5.1.0"
+  },
+  "peerDependencies": {
+    "fastify": "^5.0.0"
+  }
+}