@tumbaland/backend-core 1.16.0

package/.versionrc.json

@@ -0,0 +1,7 @@
+{
+  "skip": {
+    "changelog": true,
+    "commit": true,
+    "tag": true
+  }
+}

package/README.md

@@ -0,0 +1,179 @@
+# @tumbaland/backend-core
+
+Core shared functionality for Tumbaland backend services.
+
+## Installation
+
+```bash
+npm install @tumbaland/backend-core
+```
+
+## Usage
+
+### Basic Service Setup
+
+```typescript
+import express from 'express';
+import {
+  logger,
+  healthCheck,
+  connectDB,
+  requestLogger,
+  errorHandler,
+  correlationMiddleware
+} from '@tumbaland/backend-core';
+
+const app = express();
+
+// Environment variables
+process.env.SERVICE_NAME = 'my-service';
+process.env.SERVICE_DESCRIPTION = 'My awesome service';
+
+// Middleware
+app.use(correlationMiddleware);
+app.use(requestLogger);
+
+// Routes
+app.get('/health', healthCheck);
+
+// Error handling (must be last)
+app.use(errorHandler);
+
+// Start server
+connectDB()
+  .then(() => {
+    const PORT = process.env.PORT || 3000;
+    app.listen(PORT, () => {
+      logger.info(`🚀 Service running on port ${PORT}`);
+    });
+  })
+  .catch((error) => {
+    logger.error('Failed to start service:', error);
+    process.exit(1);
+  });
+```
+
+### Using Authentication
+
+```typescript
+import { authenticateToken } from '@tumbaland/backend-core';
+
+app.get('/protected', authenticateToken, (req, res) => {
+  const user = (req as any).user;
+  res.json({ message: `Hello ${user.name}!` });
+});
+```
+
+### Structured Logging
+
+```typescript
+import { logger } from '@tumbaland/backend-core';
+
+// Different log levels
+logger.error('Database connection failed', { error: err.message });
+logger.warn('High memory usage detected', { usage: '85%' });
+logger.info('User logged in', { userId: '123', ip: '192.168.1.1' });
+logger.debug('Processing request', { correlationId: req.correlationId });
+```
+
+### API Responses
+
+```typescript
+import { sendSuccess, sendError } from '@tumbaland/backend-core';
+
+app.get('/api/users', (req, res) => {
+  // Success response
+  sendSuccess(res, users, 'Users retrieved successfully');
+
+  // Error response
+  sendError(res, 'Failed to retrieve users', 500, 'Database error');
+});
+```
+
+## Environment Variables
+
+- `NODE_ENV`: `development` or `production`
+- `SERVICE_NAME`: Name of your service
+- `SERVICE_DESCRIPTION`: Description of your service
+- `LOG_TO_FILE`: Set to `true` to also log to files (development only)
+
+## Docker Logging
+
+This library is optimized for Docker deployments:
+
+- Logs to stdout/stderr by default
+- Use structured JSON in production
+- Integrates with Docker logging drivers
+- Compatible with log aggregation tools (ELK, Loki, etc.)
+
+## Development vs Production
+
+### Development
+- Colored console output
+- Debug level logging
+- Human-readable format
+
+### Production
+- JSON structured logging
+- Info level and above
+- Optimized for log aggregation
+
+## 📦 Releases & Versioning
+
+This library uses [standard-version](https://github.com/conventional-changelog/standard-version) for automated versioning and follows [Conventional Commits](https://conventionalcommits.org/) specification.
+
+### Release Types
+
+- **PATCH** (`1.0.0` → `1.0.1`): Bug fixes
+- **MINOR** (`1.0.0` → `1.1.0`): New features (backward compatible)
+- **MAJOR** (`1.0.0` → `2.0.0`): Breaking changes
+
+### Commit Message Format
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation
+- `style`: Code style changes
+- `refactor`: Code refactoring
+- `test`: Testing
+- `chore`: Maintenance
+
+**Examples:**
+```
+feat(auth): add JWT token refresh
+fix(logging): resolve memory leak in Winston transport
+docs(api): update health check endpoint documentation
+```
+
+### Release Process
+
+1. **Make changes** with conventional commit messages
+2. **Run release script**: `./release.sh`
+3. **Push changes**: `git push origin main`
+4. **Publish**: Automated via GitHub Actions
+
+### Changelog
+
+Changelogs are maintained at the project level in the root `CHANGELOG.md` file. Individual library changelogs are not generated to maintain consistency across the monorepo.
+
+### Beta Releases
+
+For beta releases: `npm run release:beta`
+
+---
+
+## Contributing
+
+1. Make changes to source files in `src/`
+2. Run `npm run build` to compile TypeScript
+3. Test your changes
+4. Submit a pull request

package/__mocks__/uuid.js

@@ -0,0 +1,8 @@
+// Jest's CJS module loader can't require the real `uuid` package (ESM-only
+// since v9) — Node itself supports require(esm) at runtime, but Jest doesn't.
+// Swap in Node's built-in UUID generator for tests only.
+const crypto = require('crypto');
+
+module.exports = {
+  v4: () => crypto.randomUUID()
+};

package/dist/app/createBaseApp.d.ts

@@ -0,0 +1,44 @@
+import { Express, RequestHandler } from 'express';
+import { CorsMiddlewareOptions } from '../middleware/corsMiddleware';
+export interface CreateBaseAppOptions {
+    /** Passed through to createCorsMiddleware. */
+    corsOptions?: CorsMiddlewareOptions;
+    /**
+     * Defaults to standardRateLimiter; pass strictRateLimiter or a custom one
+     * to override. Pass `false` to skip mounting one here entirely — e.g. when
+     * a route (like a webhook) must be registered, and therefore exempted,
+     * before the limiter, and the service applies it itself afterward.
+     */
+    rateLimiter?: RequestHandler | false;
+    /** Mount express.json() here. Set false when a route needs the raw body first (e.g. a webhook) or handles its own parsing. Default true. */
+    parseJson?: boolean;
+    /** Mount cookie-parser here. Set false for services that don't use cookies. Default true. */
+    parseCookies?: boolean;
+    /** Mount tracingMiddleware. Default true. */
+    tracing?: boolean;
+    /** Use requestLoggerWithMetrics (adds Prometheus histograms) instead of the plain requestLogger. Default true. */
+    metrics?: boolean;
+}
+/**
+ * Assembles the middleware stack every service was hand-rolling in its own
+ * index.ts (correlation → tracing → request logging → security → rate
+ * limiting → CORS → cookies → JSON body). Services still mount their own
+ * routes, `/health` (DB-aware readiness), `/metrics`, and
+ * `app.use(errorHandler)` last — this only owns the common prefix, not the
+ * whole app lifecycle.
+ *
+ * `/health/live` is the one exception: it's mounted here, first, ahead of
+ * every other middleware. It has zero per-service variation (it never
+ * touches a dependency, just confirms the process is up), so — unlike
+ * `/health` — there's nothing for a service to customize. Mounting it
+ * before the rate limiter also matters operationally: a service under
+ * heavy legitimate traffic shouldn't have its own liveness probe start
+ * getting 429s and get killed for being "unhealthy" at the exact moment
+ * it's just busy.
+ *
+ * Services with non-standard body parsing (a webhook needing the raw body,
+ * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
+ * false` and mount those themselves at the exact point they need to.
+ */
+export declare function createBaseApp(options?: CreateBaseAppOptions): Express;
+//# sourceMappingURL=createBaseApp.d.ts.map

package/dist/app/createBaseApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBaseApp.d.ts","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAK3D,OAAO,EAAwB,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAI3F,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,cAAc,GAAG,KAAK,CAAC;IACrC,4IAA4I;IAC5I,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6FAA6F;IAC7F,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kHAAkH;IAClH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAwBzE"}

package/dist/app/createBaseApp.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBaseApp = createBaseApp;
+const express_1 = __importDefault(require("express"));
+const cookie_parser_1 = __importDefault(require("cookie-parser"));
+const correlation_1 = require("../utils/correlation");
+const tracing_1 = require("../tracing");
+const requestLogger_1 = require("../middleware/requestLogger");
+const corsMiddleware_1 = require("../middleware/corsMiddleware");
+const security_1 = require("../middleware/security");
+const healthController_1 = require("../health/healthController");
+/**
+ * Assembles the middleware stack every service was hand-rolling in its own
+ * index.ts (correlation → tracing → request logging → security → rate
+ * limiting → CORS → cookies → JSON body). Services still mount their own
+ * routes, `/health` (DB-aware readiness), `/metrics`, and
+ * `app.use(errorHandler)` last — this only owns the common prefix, not the
+ * whole app lifecycle.
+ *
+ * `/health/live` is the one exception: it's mounted here, first, ahead of
+ * every other middleware. It has zero per-service variation (it never
+ * touches a dependency, just confirms the process is up), so — unlike
+ * `/health` — there's nothing for a service to customize. Mounting it
+ * before the rate limiter also matters operationally: a service under
+ * heavy legitimate traffic shouldn't have its own liveness probe start
+ * getting 429s and get killed for being "unhealthy" at the exact moment
+ * it's just busy.
+ *
+ * Services with non-standard body parsing (a webhook needing the raw body,
+ * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
+ * false` and mount those themselves at the exact point they need to.
+ */
+function createBaseApp(options = {}) {
+    const { corsOptions, rateLimiter = security_1.standardRateLimiter, parseJson = true, parseCookies = true, tracing = true, metrics = true } = options;
+    const app = (0, express_1.default)();
+    app.get('/health/live', healthController_1.healthLive);
+    app.use(security_1.securityHeaders);
+    if (rateLimiter)
+        app.use(rateLimiter);
+    app.use(correlation_1.correlationMiddleware);
+    if (tracing)
+        app.use(tracing_1.tracingMiddleware);
+    app.use(metrics ? requestLogger_1.requestLoggerWithMetrics : requestLogger_1.requestLogger);
+    app.use((0, corsMiddleware_1.createCorsMiddleware)(corsOptions));
+    if (parseCookies)
+        app.use((0, cookie_parser_1.default)());
+    if (parseJson)
+        app.use(express_1.default.json());
+    return app;
+}
+//# sourceMappingURL=createBaseApp.js.map

package/dist/app/createBaseApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createBaseApp.js","sourceRoot":"","sources":["../../src/app/createBaseApp.ts"],"names":[],"mappings":";;;;;AAkDA,sCAwBC;AA1ED,sDAA2D;AAC3D,kEAAyC;AACzC,sDAA6D;AAC7D,wCAA+C;AAC/C,+DAAsF;AACtF,iEAA2F;AAC3F,qDAA8E;AAC9E,iEAAwD;AAsBxD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,aAAa,CAAC,UAAgC,EAAE;IAC9D,MAAM,EACJ,WAAW,EACX,WAAW,GAAG,8BAAmB,EACjC,SAAS,GAAG,IAAI,EAChB,YAAY,GAAG,IAAI,EACnB,OAAO,GAAG,IAAI,EACd,OAAO,GAAG,IAAI,EACf,GAAG,OAAO,CAAC;IAEZ,MAAM,GAAG,GAAG,IAAA,iBAAO,GAAE,CAAC;IAEtB,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,6BAAU,CAAC,CAAC;IAEpC,GAAG,CAAC,GAAG,CAAC,0BAAe,CAAC,CAAC;IACzB,IAAI,WAAW;QAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACtC,GAAG,CAAC,GAAG,CAAC,mCAAqB,CAAC,CAAC;IAC/B,IAAI,OAAO;QAAE,GAAG,CAAC,GAAG,CAAC,2BAAiB,CAAC,CAAC;IACxC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,wCAAwB,CAAC,CAAC,CAAC,6BAAa,CAAC,CAAC;IAC5D,GAAG,CAAC,GAAG,CAAC,IAAA,qCAAoB,EAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,IAAI,YAAY;QAAE,GAAG,CAAC,GAAG,CAAC,IAAA,uBAAY,GAAE,CAAC,CAAC;IAC1C,IAAI,SAAS;QAAE,GAAG,CAAC,GAAG,CAAC,iBAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAEvC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/config/env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns the value of a required environment variable.
+ * Throws if the variable is missing or empty — call at service startup
+ * (after dotenv.config()) so misconfigured services fail fast instead of
+ * running with insecure defaults.
+ */
+export declare function requireEnv(name: string): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/C"}

package/dist/config/env.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireEnv = requireEnv;
+/**
+ * Returns the value of a required environment variable.
+ * Throws if the variable is missing or empty — call at service startup
+ * (after dotenv.config()) so misconfigured services fail fast instead of
+ * running with insecure defaults.
+ */
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":";;AAMA,gCAMC;AAZD;;;;;GAKG;AACH,SAAgB,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,0CAA0C,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/database/connection.d.ts

@@ -0,0 +1,3 @@
+export declare const connectDB: (serviceName?: string, uri?: string) => Promise<void>;
+export declare const disconnectDB: (serviceName?: string) => Promise<void>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/database/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,SAAS,GAAU,cAAc,MAAM,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,IAAI,CA6BhF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,cAAc,MAAM,KAAG,OAAO,CAAC,IAAI,CASrE,CAAC"}

package/dist/database/connection.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.disconnectDB = exports.connectDB = void 0;
+const mongoose_1 = __importDefault(require("mongoose"));
+const logger_1 = __importDefault(require("../logging/logger"));
+let connected = false;
+const connectDB = async (serviceName, uri) => {
+    if (connected)
+        return;
+    const mongoUri = uri || process.env.MONGODB_URI;
+    if (!mongoUri) {
+        throw new Error('MONGODB_URI environment variable is not set');
+    }
+    try {
+        await mongoose_1.default.connect(mongoUri);
+        connected = true;
+        logger_1.default.info('MongoDB connected', { service: serviceName });
+        mongoose_1.default.connection.on('error', (err) => {
+            logger_1.default.error('MongoDB connection error', { service: serviceName, error: err.message });
+        });
+        mongoose_1.default.connection.on('disconnected', () => {
+            logger_1.default.warn('MongoDB disconnected', { service: serviceName });
+        });
+        mongoose_1.default.connection.on('reconnected', () => {
+            logger_1.default.info('MongoDB reconnected', { service: serviceName });
+        });
+    }
+    catch (error) {
+        logger_1.default.error('Failed to connect to MongoDB', { service: serviceName, error: error.message });
+        throw error;
+    }
+};
+exports.connectDB = connectDB;
+const disconnectDB = async (serviceName) => {
+    try {
+        await mongoose_1.default.connection.close();
+        connected = false;
+        logger_1.default.info('MongoDB connection closed', { service: serviceName });
+    }
+    catch (error) {
+        logger_1.default.error('Error closing MongoDB connection', { service: serviceName, error: error.message });
+        throw error;
+    }
+};
+exports.disconnectDB = disconnectDB;
+//# sourceMappingURL=connection.js.map

package/dist/database/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/database/connection.ts"],"names":[],"mappings":";;;;;;AAAA,wDAAgC;AAChC,+DAAuC;AAEvC,IAAI,SAAS,GAAG,KAAK,CAAC;AAEf,MAAM,SAAS,GAAG,KAAK,EAAE,WAAoB,EAAE,GAAY,EAAiB,EAAE;IACnF,IAAI,SAAS;QAAE,OAAO;IAEtB,MAAM,QAAQ,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,kBAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjC,SAAS,GAAG,IAAI,CAAC;QAEjB,gBAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAE3D,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAC7C,gBAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACzF,CAAC,CAAC,CAAC;QAEH,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,cAAc,EAAE,GAAG,EAAE;YAC1C,gBAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,kBAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,aAAa,EAAE,GAAG,EAAE;YACzC,gBAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACxG,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AA7BW,QAAA,SAAS,aA6BpB;AAEK,MAAM,YAAY,GAAG,KAAK,EAAE,WAAoB,EAAiB,EAAE;IACxE,IAAI,CAAC;QACH,MAAM,kBAAQ,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAClC,SAAS,GAAG,KAAK,CAAC;QAClB,gBAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gBAAM,CAAC,KAAK,CAAC,kCAAkC,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAG,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5G,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AATW,QAAA,YAAY,gBASvB"}

package/dist/errors/HttpError.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Base class for errors that should be turned into a specific HTTP response
+ * by the shared errorHandler, instead of every controller hand-rolling
+ * try/catch + string-matching on error.message to pick a status code.
+ *
+ * Express 5 forwards rejected promises from async route handlers to the
+ * mounted error handler automatically, so controllers can just
+ * `throw new NotFoundError(...)` and stop wrapping in try/catch.
+ */
+export declare class HttpError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare class BadRequestError extends HttpError {
+    constructor(message?: string);
+}
+export declare class UnauthorizedError extends HttpError {
+    constructor(message?: string);
+}
+export declare class ForbiddenError extends HttpError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends HttpError {
+    constructor(message?: string);
+}
+export declare class ConflictError extends HttpError {
+    constructor(message?: string);
+}
+export declare class TooManyRequestsError extends HttpError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=HttpError.d.ts.map

package/dist/errors/HttpError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpError.d.ts","sourceRoot":"","sources":["../../src/errors/HttpError.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,UAAU,EAAE,MAAM,CAAC;gBAEP,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAQhD;AAED,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,SAAgB;CAGpC;AAED,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,SAAiB;CAGrC;AAED,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,SAAkB;CAGtC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAc;CAGlC;AAED,qBAAa,aAAc,SAAQ,SAAS;gBAC9B,OAAO,SAAa;CAGjC;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,OAAO,SAAsB;CAG1C"}

package/dist/errors/HttpError.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TooManyRequestsError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = exports.HttpError = void 0;
+/**
+ * Base class for errors that should be turned into a specific HTTP response
+ * by the shared errorHandler, instead of every controller hand-rolling
+ * try/catch + string-matching on error.message to pick a status code.
+ *
+ * Express 5 forwards rejected promises from async route handlers to the
+ * mounted error handler automatically, so controllers can just
+ * `throw new NotFoundError(...)` and stop wrapping in try/catch.
+ */
+class HttpError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.name = new.target.name;
+        this.statusCode = statusCode;
+        // Restore the prototype chain (needed when compiling to ES2018 targets
+        // where `extends Error` doesn't preserve instanceof checks correctly).
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.HttpError = HttpError;
+class BadRequestError extends HttpError {
+    constructor(message = 'Bad request') {
+        super(400, message);
+    }
+}
+exports.BadRequestError = BadRequestError;
+class UnauthorizedError extends HttpError {
+    constructor(message = 'Unauthorized') {
+        super(401, message);
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;
+class ForbiddenError extends HttpError {
+    constructor(message = 'Access denied') {
+        super(403, message);
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+class NotFoundError extends HttpError {
+    constructor(message = 'Not found') {
+        super(404, message);
+    }
+}
+exports.NotFoundError = NotFoundError;
+class ConflictError extends HttpError {
+    constructor(message = 'Conflict') {
+        super(409, message);
+    }
+}
+exports.ConflictError = ConflictError;
+class TooManyRequestsError extends HttpError {
+    constructor(message = 'Too many requests') {
+        super(429, message);
+    }
+}
+exports.TooManyRequestsError = TooManyRequestsError;
+//# sourceMappingURL=HttpError.js.map

package/dist/errors/HttpError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpError.js","sourceRoot":"","sources":["../../src/errors/HttpError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;GAQG;AACH,MAAa,SAAU,SAAQ,KAAK;IAClC,UAAU,CAAS;IAEnB,YAAY,UAAkB,EAAE,OAAe;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,uEAAuE;QACvE,uEAAuE;QACvE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAXD,8BAWC;AAED,MAAa,eAAgB,SAAQ,SAAS;IAC5C,YAAY,OAAO,GAAG,aAAa;QACjC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtB,CAAC;CACF;AAJD,0CAIC;AAED,MAAa,iBAAkB,SAAQ,SAAS;IAC9C,YAAY,OAAO,GAAG,cAAc;QAClC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtB,CAAC;CACF;AAJD,8CAIC;AAED,MAAa,cAAe,SAAQ,SAAS;IAC3C,YAAY,OAAO,GAAG,eAAe;QACnC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtB,CAAC;CACF;AAJD,wCAIC;AAED,MAAa,aAAc,SAAQ,SAAS;IAC1C,YAAY,OAAO,GAAG,WAAW;QAC/B,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtB,CAAC;CACF;AAJD,sCAIC;AAED,MAAa,aAAc,SAAQ,SAAS;IAC1C,YAAY,OAAO,GAAG,UAAU;QAC9B,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtB,CAAC;CACF;AAJD,sCAIC;AAED,MAAa,oBAAqB,SAAQ,SAAS;IACjD,YAAY,OAAO,GAAG,mBAAmB;QACvC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACtB,CAAC;CACF;AAJD,oDAIC"}

package/dist/health/healthController.d.ts

@@ -0,0 +1,21 @@
+import { Request, Response } from 'express';
+import { metricsHandler } from '../metrics';
+/**
+ * Health check endpoint with database connectivity
+ * Returns comprehensive health status for monitoring
+ */
+export declare const healthCheck: (req: Request, res: Response) => Promise<void>;
+/**
+ * Liveness check: confirms the process is up and serving HTTP, without
+ * touching MongoDB or any other dependency. Used by the Docker-level
+ * HEALTHCHECK so a transient DB outage doesn't get reported as the
+ * container itself being unhealthy — `/health` (above) is the DB-aware
+ * readiness check for dashboards/monitoring.
+ */
+export declare const healthLive: (req: Request, res: Response) => void;
+/**
+ * Prometheus metrics endpoint
+ * Exposes application metrics for monitoring
+ */
+export { metricsHandler };
+//# sourceMappingURL=healthController.d.ts.map

package/dist/health/healthController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthController.d.ts","sourceRoot":"","sources":["../../src/health/healthController.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAU,KAAK,OAAO,EAAE,KAAK,QAAQ,kBA8B5D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,EAAE,KAAK,QAAQ,SAErD,CAAC;AAEF;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/health/healthController.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metricsHandler = exports.healthLive = exports.healthCheck = void 0;
+const mongoose_1 = __importDefault(require("mongoose"));
+const metrics_1 = require("../metrics");
+Object.defineProperty(exports, "metricsHandler", { enumerable: true, get: function () { return metrics_1.metricsHandler; } });
+/**
+ * Health check endpoint with database connectivity
+ * Returns comprehensive health status for monitoring
+ */
+const healthCheck = async (req, res) => {
+    try {
+        // Check MongoDB connection
+        const mongoState = mongoose_1.default.connection.readyState;
+        const isMongoHealthy = mongoState === 1; // 1 = connected
+        const healthResponse = {
+            status: isMongoHealthy ? 'ok' : 'error',
+            service: process.env.SERVICE_NAME || 'unknown-service',
+            type: 'backend',
+            timestamp: new Date().toISOString(),
+            version: process.env.npm_package_version || '1.0.0',
+            description: process.env.SERVICE_DESCRIPTION || 'Backend service',
+            dependencies: {
+                mongodb: isMongoHealthy ? 'connected' : 'disconnected'
+            }
+        };
+        res.status(isMongoHealthy ? 200 : 503).json(healthResponse);
+    }
+    catch (error) {
+        res.status(503).json({
+            status: 'error',
+            service: process.env.SERVICE_NAME || 'unknown-service',
+            type: 'backend',
+            timestamp: new Date().toISOString(),
+            version: process.env.npm_package_version || '1.0.0',
+            description: process.env.SERVICE_DESCRIPTION || 'Backend service',
+            error: 'Health check failed'
+        });
+    }
+};
+exports.healthCheck = healthCheck;
+/**
+ * Liveness check: confirms the process is up and serving HTTP, without
+ * touching MongoDB or any other dependency. Used by the Docker-level
+ * HEALTHCHECK so a transient DB outage doesn't get reported as the
+ * container itself being unhealthy — `/health` (above) is the DB-aware
+ * readiness check for dashboards/monitoring.
+ */
+const healthLive = (req, res) => {
+    res.status(200).json({ status: 'ok' });
+};
+exports.healthLive = healthLive;
+//# sourceMappingURL=healthController.js.map

package/dist/health/healthController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthController.js","sourceRoot":"","sources":["../../src/health/healthController.ts"],"names":[],"mappings":";;;;;;AACA,wDAAgC;AAChC,wCAA4C;AAqDnC,+FArDA,wBAAc,OAqDA;AAnDvB;;;GAGG;AACI,MAAM,WAAW,GAAG,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,EAAE;IAC/D,IAAI,CAAC;QACH,2BAA2B;QAC3B,MAAM,UAAU,GAAG,kBAAQ,CAAC,UAAU,CAAC,UAAU,CAAC;QAClD,MAAM,cAAc,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,gBAAgB;QAEzD,MAAM,cAAc,GAAG;YACrB,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;YACvC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,iBAAiB;YACtD,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO;YACnD,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,iBAAiB;YACjE,YAAY,EAAE;gBACZ,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc;aACvD;SACF,CAAC;QAEF,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC9D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,MAAM,EAAE,OAAO;YACf,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,iBAAiB;YACtD,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,OAAO;YACnD,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,iBAAiB;YACjE,KAAK,EAAE,qBAAqB;SAC7B,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;AA9BW,QAAA,WAAW,eA8BtB;AAEF;;;;;;GAMG;AACI,MAAM,UAAU,GAAG,CAAC,GAAY,EAAE,GAAa,EAAE,EAAE;IACxD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC,CAAC;AAFW,QAAA,UAAU,cAErB"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { createBaseApp } from './app/createBaseApp';
+export type { CreateBaseAppOptions } from './app/createBaseApp';
+export { default as logger } from './logging/logger';
+export { healthCheck, healthLive, metricsHandler } from './health/healthController';
+export { connectDB, disconnectDB } from './database/connection';
+export { requireEnv } from './config/env';
+export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError } from './errors/HttpError';
+export { authenticateToken } from './middleware/authMiddleware';
+export { createCorsMiddleware } from './middleware/corsMiddleware';
+export { errorHandler } from './middleware/errorHandler';
+export { requestLogger, requestLoggerWithMetrics, simpleRequestLogger } from './middleware/requestLogger';
+export { securityHeaders, createRateLimiter, standardRateLimiter, strictRateLimiter } from './middleware/security';
+export { validate } from './middleware/validate';
+export type { UserPayload } from './types/auth';
+export { generateCorrelationId, correlationMiddleware } from './utils/correlation';
+export { createApiResponse, sendSuccess, sendError } from './utils/response';
+export type { ApiResponse } from './utils/response';
+export { metricsMiddleware, httpRequestDuration, httpRequestsTotal, databaseQueryDuration, databaseQueriesTotal, businessMetrics, register } from './metrics';
+export { initTracer, getTracer, startSpan, tracingMiddleware, createChildSpan, logToSpan, setSpanTag, injectHeaders, extractSpanContext } from './tracing';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGpF,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAGvJ,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACnH,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGjD,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACT,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,UAAU,EACV,aAAa,EACb,kBAAkB,EACnB,MAAM,WAAW,CAAC"}