@xenterprises/fastify-xconfig 2.1.0 → 2.1.2

package/.env

@@ -0,0 +1,33 @@
+# Environment variables for xConfig Plugin
+# Prisma supports the native connection string format for PostgreSQL, MySQL, SQLite, SQL Server, MongoDB and CockroachDB.
+# See the documentation for all the connection string options: https://pris.ly/d/connection-strings
+
+# Database Configuration (Required)
+DATABASE_URL="postgresql://user:password@localhost:5432/dbname?sslmode=require"
+
+# Server Configuration
+NODE_ENV=development
+PORT=3002
+FASTIFY_ADDRESS=0.0.0.0
+
+# Error Tracking (optional)
+BUGSNAG_API_KEY="your-bugsnag-api-key"
+
+# CORS Configuration (optional)
+CORS_ORIGIN="http://localhost:3000,https://example.com"
+RATE_LIMIT_MAX=100
+RATE_LIMIT_TIME_WINDOW="1 minute"
+
+# ========================================
+# DEPRECATED / NO LONGER USED BY XCONFIG
+# ========================================
+# The following services have been extracted to separate plugins:
+#
+# Authentication → Use @xenterprises/fastify-xauth-jwks
+# Geolocation → Use @xenterprises/fastify-xgeocode
+# SMS Services → Use xTwilio plugin (separate module)
+# Email Services → Use separate email plugin
+# Image/File Storage → Use xStorage plugin (separate module)
+# Payment Processing → Use xStripe plugin (separate module)
+#
+# Old Stack Auth variables are deprecated - use xAuthJWSK instead

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/fastify-xconfig",
   "type": "module",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Fastify configuration plugin for setting up middleware, services, and route handling.",
   "main": "src/xConfig.js",
   "scripts": {

package/CHANGELOG.md

@@ -1,189 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [2.0.0] - 2025-12-28
-
-### BREAKING CHANGES
-
-This is a major version release with significant architectural changes.
-
-#### Removed Services
-
-The following services have been extracted to dedicated plugins and are **no longer** available in xConfig:
-
-- **SendGrid Integration** - Use `@xenterprises/fastify-xsendgrid` (planned) or implement separately
-- **Twilio Integration** - Use `@xenterprises/fastify-xtwilio` (planned) or implement separately
-- **Cloudinary Integration** - Use `@xenterprises/fastify-xstorage` (planned) or implement separately
-- **Stripe Integration** - Use `@xenterprises/fastify-xstripe` (planned) or implement separately
-- **Stack Auth Integration** - Use `@xenterprises/fastify-xauth-jwks` instead
-
-#### Configuration Changes
-
-The following options are **no longer supported** in xConfig registration:
-
-```javascript
-// ❌ These options are now REMOVED
-fastify.register(xConfig, {
-  sendGrid: { ... },      // REMOVED - use separate plugin
-  twilio: { ... },        // REMOVED - use separate plugin
-  cloudinary: { ... },    // REMOVED - use separate plugin
-  stripe: { ... },        // REMOVED - use separate plugin
-  auth: { ... },          // REMOVED - use xAuthJWSK plugin
-  geocode: { ... },       // REMOVED - use xGeocode plugin
-});
-```
-
-#### New Plugin-Based Architecture
-
-xConfig now focuses on core middleware only. Use these dedicated plugins for removed services:
-
-```javascript
-import Fastify from 'fastify';
-import xConfig from '@xenterprises/fastify-xconfig';
-import xAuthJWSK from '@xenterprises/fastify-xauth-jwks';
-import xGeocode from '@xenterprises/fastify-xgeocode';
-
-const fastify = Fastify();
-
-// Core config (middleware & database)
-await fastify.register(xConfig, {
-  prisma: {},
-  cors: { origin: ['https://example.com'] },
-  rateLimit: { max: 100, timeWindow: '1 minute' },
-});
-
-// Dedicated plugins for other services
-await fastify.register(xAuthJWSK, { /* config */ });
-await fastify.register(xGeocode, { /* config */ });
-```
-
-### Added
-
-- ✅ Enhanced CORS security - Environment-aware origin defaults
-  - Production: Only allows configured domain
-  - Development: Allows localhost:3000 and localhost:3001
-- ✅ Improved health check endpoint - Better environment validation
-- ✅ Test suite - 8 comprehensive tests covering core functionality
-- ✅ Production hardening - Security audit and best practices applied
-
-### Changed
-
-- **Core Focus**: xConfig now provides only essential middleware and configuration
-- **Plugin Architecture**: Services moved to dedicated, focused plugins
-- **Dependencies**: Reduced from 22 to 11 (50% reduction)
-- **Bundle Size**: ~42% smaller with removed integrations
-- **Code Quality**: Improved maintainability and single responsibility
-
-### Fixed
-
-- ⚠️ Prisma disconnect hook - Now properly called only once on shutdown
-- ✅ Health endpoint - No longer fails when Prisma is disabled
-- ✅ Lifecycle hooks - Fixed "already listening" errors in test scenarios
-
-### Security
-
-- **npm audit**: 0 vulnerabilities
-- **CORS**: Secure defaults based on environment
-- **Error Handling**: Stack traces hidden in production
-- **Error Reporting**: Optional Bugsnag integration
-
-### Migration Guide
-
-#### Before (v1.x)
-
-```javascript
-fastify.register(xConfig, {
-  sendGrid: { apiKey: '...' },
-  twilio: { accountSid: '...', authToken: '...', phoneNumber: '...' },
-  cloudinary: { cloudName: '...' },
-  auth: { admin: { ... }, user: { ... } },
-  geocode: { apiKey: '...' },
-});
-```
-
-#### After (v2.0)
-
-```javascript
-// Step 1: Core config only
-fastify.register(xConfig, {
-  prisma: {},
-  cors: { active: true, origin: ['https://yourdomain.com'] },
-  rateLimit: { max: 100, timeWindow: '1 minute' },
-});
-
-// Step 2: Add service plugins
-fastify.register(xAuthJWSK, {
-  paths: { 
-    admin: { pathPattern: '/admin', jwksUrl: '...' },
-    api: { pathPattern: '/api', jwksUrl: '...' }
-  }
-});
-
-fastify.register(xGeocode, {
-  apiKey: process.env.GEOCODIO_API_KEY
-});
-
-// Step 3: Implement other services separately or wait for dedicated plugins
-// - Email: Use SendGrid SDK directly or wait for @xenterprises/fastify-xsendgrid
-// - SMS: Use Twilio SDK directly or wait for @xenterprises/fastify-xtwilio
-// - Storage: Use AWS S3 SDK directly or wait for @xenterprises/fastify-xstorage
-// - Payments: Use Stripe SDK directly or wait for @xenterprises/fastify-xstripe
-```
-
-### Deprecation Notes
-
-- The `auth` option is deprecated. Use `@xenterprises/fastify-xauth-jwks` instead
-- The `geocode` option is deprecated. Use `@xenterprises/fastify-xgeocode` instead
-- Stack Auth integration is deprecated. Use `@xenterprises/fastify-xauth-jwks` instead
-
-### Environment Variables
-
-**Removed** (no longer supported):
-- `ADMIN_STACK_PROJECT_ID`
-- `ADMIN_STACK_PUBLISHABLE_CLIENT_KEY`
-- `ADMIN_STACK_SECRET_SERVER_KEY`
-- `USER_STACK_PROJECT_ID`
-- `USER_STACK_PUBLISHABLE_CLIENT_KEY`
-- `USER_STACK_SECRET_SERVER_KEY`
-- `SENDGRID_API_KEY`
-- `SENDGRID_API_EMAIL_VALIDATION_KEY`
-- `SENDGRID_FROM_EMAIL`
-- `TWILIO_ACCOUNT_SID`
-- `TWILIO_AUTH_TOKEN`
-- `TWILIO_PHONE_NUMBER`
-- `CLOUDINARY_CLOUD_NAME`
-- `CLOUDINARY_API_KEY`
-- `CLOUDINARY_API_SECRET`
-- `CLOUDINARY_BASE_PATH`
-- `STRIPE_API_KEY`
-
-**Still Supported**:
-- `DATABASE_URL` - PostgreSQL connection string (if Prisma enabled)
-- `NODE_ENV` - Application environment
-- `PORT` - Server port
-- `FASTIFY_ADDRESS` - Server address
-- `BUGSNAG_API_KEY` - Error tracking (optional)
-- `CORS_ORIGIN` - Allowed CORS origins
-- `RATE_LIMIT_MAX` - Rate limit threshold
-- `RATE_LIMIT_TIME_WINDOW` - Rate limit window
-
-### Testing
-
-- ✅ All tests passing (8/8)
-- ✅ npm audit clean (0 vulnerabilities)
-- ✅ Production hardening complete
-- ✅ Graceful shutdown verified
-- ✅ Health endpoint validated
-
-### Dependencies Updated
-
-- Updated `@prisma/client` to ^7.2.0
-- All @fastify packages verified and up-to-date
-- Removed: @sendgrid/mail, @sendgrid/client, twilio, cloudinary, jose, stripe
-
----
-
-## [1.x] - Previous Versions
-
-See git history for previous releases.

package/server/app.js

@@ -1,43 +0,0 @@
-// server/app.js
-import Fastify from 'fastify';
-import xConfig from '../src/xConfig.js';  // Import your plugin correctly
-
-const fastify = Fastify();
-
-
-export default async function (fastify, opts) {
-  fastify.register(xConfig, {
-    professional: false,
-    fancyErrors: true,
-    prisma: {
-      active: false,
-    },
-    bugsnag: {
-      apiKey: process.env.BUGSNAG_API_KEY
-    },
-    rateLimit: {
-      max: process.env.RATE_LIMIT_MAX || 100,
-      timeWindow: process.env.RATE_LIMIT_TIME_WINDOW || '1 minute'
-    },
-    cors: {
-      active: true,
-      origin: process.env.CORS_ORIGIN || ['http://localhost:3000'],
-      credentials: true
-    },
-    multipart: {
-      limits: {
-        fileSize: 52428800 // 50MB
-      }
-    },
-    underPressure: {
-      maxEventLoopDelay: 1000,
-      maxHeapUsedBytes: 1000000000,
-      maxRssBytes: 1000000000
-    }
-  });  // Register the default export, which should be a function
-  fastify.get('/', async (request, reply) => {
-    console.log(fastify.xEcho())
-    return { status: fastify.xEcho() }
-  })
-
-};

package/test/index.js

@@ -1,17 +0,0 @@
-// test.js
-const fastify = require('fastify')();
-const myPlugin = require('../src/xConfig');
-
-fastify.register(myPlugin);
-
-fastify.get('/', async (request, reply) => {
-  return { message: fastify.myPluginMethod() };
-});
-
-try {
-  const address = await fastify.listen({ port: 3000 });
-  console.log(`Server running at ${address}`);
-} catch (err) {
-  console.error(err);
-  process.exit(1);
-}

package/test/xConfig.test.js

@@ -1,278 +0,0 @@
-// test/xConfig.test.js
-import { test } from "node:test";
-import assert from "node:assert";
-import Fastify from "fastify";
-import xConfig from "../src/xConfig.js";
-
-// Minimal config for testing
-const minimalConfig = {
-  prisma: { active: false },
-  bugsnag: { active: false },
-};
-
-test("xConfig Plugin - registers successfully", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(xConfig, minimalConfig);
-    assert.ok(true, "Plugin registered successfully");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Plugin - provides utility decorators", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(xConfig, minimalConfig);
-    // At least one utility decorator should be available
-    const hasUtilityDecorators =
-      fastify.xEcho !== undefined ||
-      fastify.xUUID !== undefined;
-    assert.ok(hasUtilityDecorators, "At least one utility decorator is available");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Plugin - has health route registered", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    const routes = [];
-    fastify.addHook("onRoute", (r) => routes.push(r));
-    await fastify.register(xConfig, minimalConfig);
-
-    // Check that health route is present
-    const hasHealthRoute = routes.some((r) => r.url === "/health");
-    assert.ok(hasHealthRoute, "Health endpoint route is registered");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Plugin - accepts custom CORS config", async () => {
-  const fastify = Fastify({ logger: false });
-  const customConfig = {
-    ...minimalConfig,
-    cors: { origin: "http://example.com" },
-  };
-  try {
-    await fastify.register(xConfig, customConfig);
-    assert.ok(true, "Custom CORS config accepted");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Plugin - accepts custom rate limit config", async () => {
-  const fastify = Fastify({ logger: false });
-  const customConfig = {
-    ...minimalConfig,
-    rateLimit: { max: 50, timeWindow: "1 minute" },
-  };
-  try {
-    await fastify.register(xConfig, customConfig);
-    assert.ok(true, "Custom rate limit config accepted");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Plugin - under pressure monitoring available", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    const customConfig = {
-      ...minimalConfig,
-      underPressure: {
-        maxEventLoopDelay: 1000,
-        maxHeapUsedBytes: 1000000000,
-        maxRssBytes: 1000000000
-      }
-    };
-    await fastify.register(xConfig, customConfig);
-    assert.ok(true, "Under pressure config accepted");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Plugin - multipart handling available", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    const customConfig = {
-      ...minimalConfig,
-      multipart: { limits: { fileSize: 52428800 } }
-    };
-    await fastify.register(xConfig, customConfig);
-    assert.ok(true, "Multipart config accepted");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Plugin - health check endpoint responds", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    const routes = [];
-    fastify.addHook("onRoute", (r) => routes.push(r));
-    await fastify.register(xConfig, minimalConfig);
-
-    const response = await fastify.inject({
-      method: "GET",
-      url: "/health"
-    });
-    assert.equal(response.statusCode, 200, "Health endpoint returns 200");
-    const body = JSON.parse(response.body);
-    assert.ok(body.status, "Health response includes status field");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Utilities - xUUID generates valid UUIDs", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(xConfig, minimalConfig);
-
-    const uuid1 = fastify.xRandomUUID();
-    const uuid2 = fastify.xRandomUUID();
-
-    // Check that randomUUID is a function
-    assert.equal(typeof fastify.xRandomUUID, "function", "randomUUID is a function");
-
-    // Check that UUIDs are generated
-    assert.ok(uuid1, "UUID is generated");
-    assert.ok(uuid2, "Second UUID is generated");
-
-    // Check that UUIDs are different
-    assert.notEqual(uuid1, uuid2, "UUIDs are unique");
-
-    // Check UUID format (36 chars, with dashes at positions 8, 13, 18, 23)
-    assert.match(uuid1, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i, "UUID matches format");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Utilities - xSlugify handles various inputs", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(xConfig, minimalConfig);
-
-    // Test basic slugification
-    assert.equal(fastify.xSlugify("Hello World"), "hello-world", "Converts to lowercase and replaces spaces");
-    assert.equal(fastify.xSlugify("UPPERCASE"), "uppercase", "Converts uppercase to lowercase");
-    assert.equal(fastify.xSlugify("Multiple   Spaces"), "multiple-spaces", "Collapses multiple spaces");
-
-    // Test special character removal
-    assert.equal(fastify.xSlugify("Hello@World!"), "helloworld", "Removes special characters");
-    assert.equal(fastify.xSlugify("Test-String"), "test-string", "Preserves dashes");
-
-    // Test edge cases
-    assert.equal(fastify.xSlugify("  Trim  "), "trim", "Trims leading and trailing spaces");
-    assert.equal(fastify.xSlugify("---multiple-dashes---"), "multiple-dashes", "Collapses multiple dashes");
-    assert.equal(fastify.xSlugify(""), "", "Handles empty string");
-
-    // Test with numbers
-    assert.equal(fastify.xSlugify("Test123"), "test123", "Preserves numbers");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Utilities - xEcho returns status message", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(xConfig, minimalConfig);
-
-    const echo = fastify.xEcho();
-    assert.ok(echo, "xEcho returns a value");
-    assert.equal(typeof echo, "string", "xEcho returns a string");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Health Endpoint - response structure validation", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(xConfig, minimalConfig);
-
-    const response = await fastify.inject({
-      method: "GET",
-      url: "/health"
-    });
-
-    assert.equal(response.statusCode, 200, "Returns 200 status");
-
-    const body = JSON.parse(response.body);
-    assert.ok(body.status, "Has status field");
-    assert.ok(body.timestamp, "Has timestamp field");
-    assert.ok(body.details, "Has details object");
-    assert.ok(typeof body.details === "object", "Details is an object");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Configuration - CORS disabled when active is false", async () => {
-  const fastify = Fastify({ logger: false });
-  const customConfig = {
-    ...minimalConfig,
-    cors: { active: false },
-  };
-  try {
-    await fastify.register(xConfig, customConfig);
-    assert.ok(true, "Plugin accepts cors.active: false");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Configuration - rate limit disabled when active is false", async () => {
-  const fastify = Fastify({ logger: false });
-  const customConfig = {
-    ...minimalConfig,
-    rateLimit: { active: false },
-  };
-  try {
-    await fastify.register(xConfig, customConfig);
-    assert.ok(true, "Plugin accepts rateLimit.active: false");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Configuration - fancy errors can be disabled", async () => {
-  const fastify = Fastify({ logger: false });
-  const customConfig = {
-    ...minimalConfig,
-    fancyErrors: false,
-  };
-  try {
-    await fastify.register(xConfig, customConfig);
-    assert.ok(true, "Plugin accepts fancyErrors: false");
-  } finally {
-    await fastify.close();
-  }
-});
-
-test("xConfig Integration - all decorators available together", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(xConfig, minimalConfig);
-
-    // Verify all expected decorators exist
-    assert.ok(fastify.xEcho, "xEcho decorator available");
-    assert.ok(fastify.xRandomUUID, "randomUUID decorator available");
-    assert.ok(fastify.xGenerateUUID, "generateUUID decorator available");
-    assert.ok(fastify.xSlugify, "slugify decorator available");
-
-    // Verify they're functions
-    assert.equal(typeof fastify.xEcho, "function", "xEcho is a function");
-    assert.equal(typeof fastify.xRandomUUID, "function", "randomUUID is a function");
-    assert.equal(typeof fastify.xGenerateUUID, "function", "generateUUID is a function");
-    assert.equal(typeof fastify.xSlugify, "function", "slugify is a function");
-  } finally {
-    await fastify.close();
-  }
-});