powr-sdk-api 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# PowrStack API Core Library
+
+A shared library for Express API projects in the PowrStack ecosystem. This library provides common middleware and utilities for error handling, response formatting, logging, and Swagger documentation.
+
+## Installation
+
+```bash
+npm install powr-sdk-api
+```
+
+## Features
+
+- Error handling middleware with `APIError` class
+- Response formatting middleware
+- Request/Response logging middleware
+- Swagger documentation setup
+- Async handler utility
+
+## Usage
+
+### Basic Setup
+
+```javascript
+const express = require('express');
+const {
+  errorHandler,
+  responseHandler,
+  logger,
+  createSwaggerSpec
+} = require('powr-sdk-api');
+
+const app = express();
+
+// Apply middleware
+app.use(logger);
+app.use(responseHandler);
+
+// Setup Swagger
+const swaggerSpec = createSwaggerSpec({
+  title: 'Your API',
+  version: '1.0.0',
+  description: 'Your API description',
+  serverUrl: 'http://localhost:3000'
+});
+
+// Apply error handler last
+app.use(errorHandler);
+```
+
+### Error Handling
+
+```javascript
+const { APIError, asyncHandler } = require('powr-sdk-api');
+
+// In your route handler
+app.get('/users/:id', asyncHandler(async (req, res) => {
+  const user = await User.findById(req.params.id);
+  if (!user) {
+    throw new APIError('User not found', 404);
+  }
+  res.success(user);
+}));
+```
+
+### Response Formatting
+
+```javascript
+// Success response
+res.success(data, 'Operation successful', 200);
+
+// Error response
+res.error('Something went wrong', 500, { details: 'Error details' });
+```
+
+### Swagger Documentation
+
+```javascript
+const swaggerUi = require('swagger-ui-express');
+const { createSwaggerSpec } = require('powr-sdk-api');
+
+const swaggerSpec = createSwaggerSpec({
+  title: 'Your API',
+  version: '1.0.0',
+  description: 'Your API description',
+  serverUrl: 'http://localhost:3000'
+});
+
+app.use('/swagger', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+```
+
+## API Reference
+
+### Error Handling
+
+- `APIError`: Custom error class for API errors
+- `asyncHandler`: Wrapper for async route handlers
+- `errorHandler`: Global error handling middleware
+
+### Response Formatting
+
+- `responseHandler`: Middleware for standardizing API responses
+- `res.success()`: Send a success response
+- `res.error()`: Send an error response
+
+### Logging
+
+- `logger`: Middleware for logging requests and responses
+
+### Swagger
+
+- `createSwaggerSpec`: Function to create Swagger specification
+
+## License
+
+ISC 

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+
+/**
+ * PowrStack API Core Library
+ * A shared library for Express API projects
+ */
+
+const errorMiddleware = require('./middleware/error');
+const responseMiddleware = require('./middleware/response');
+const loggerMiddleware = require('./middleware/logger');
+const createSwaggerSpec = require('./swagger');
+module.exports = {
+  // Error handling
+  APIError: errorMiddleware.APIError,
+  asyncHandler: errorMiddleware.asyncHandler,
+  errorHandler: errorMiddleware.errorHandler,
+  // Response formatting
+  responseHandler: responseMiddleware,
+  // Logging
+  logger: loggerMiddleware,
+  // Swagger
+  createSwaggerSpec
+};

package/dist/middleware/error.js

@@ -0,0 +1,36 @@
+"use strict";
+
+/**
+ * Error handling middleware for Express applications
+ */
+
+class APIError extends Error {
+  constructor(message, statusCode = 500, details = null) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = 'APIError';
+  }
+}
+const asyncHandler = fn => (req, res, next) => {
+  Promise.resolve(fn(req, res, next)).catch(next);
+};
+const errorHandler = (err, req, res, next) => {
+  console.error('Error:', {
+    message: err.message,
+    stack: err.stack,
+    details: err.details
+  });
+  const statusCode = err.statusCode || 500;
+  const message = err.message || 'Internal Server Error';
+  res.status(statusCode).json({
+    success: false,
+    message,
+    details: err.details
+  });
+};
+module.exports = {
+  APIError,
+  asyncHandler,
+  errorHandler
+};

package/dist/middleware/logger.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/**
+ * Logging middleware for Express applications
+ */
+
+const logger = (req, res, next) => {
+  // Log request
+  console.log('Request:', {
+    timestamp: new Date().toISOString(),
+    method: req.method,
+    url: req.url,
+    ip: req.ip,
+    headers: req.headers,
+    body: req.body,
+    query: req.query
+  });
+
+  // Store original send and json methods
+  const originalSend = res.send;
+  const originalJson = res.json;
+
+  // Override send method to log response
+  res.send = function (body) {
+    console.log('Response:', {
+      timestamp: new Date().toISOString(),
+      statusCode: res.statusCode,
+      body: body
+    });
+    return originalSend.call(this, body);
+  };
+
+  // Override json method to log response
+  res.json = function (body) {
+    console.log('Response:', {
+      timestamp: new Date().toISOString(),
+      statusCode: res.statusCode,
+      body: body
+    });
+    return originalJson.call(this, body);
+  };
+  next();
+};
+module.exports = logger;

package/dist/middleware/response.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/**
+ * Response formatting middleware for Express applications
+ */
+
+const responseHandler = (req, res, next) => {
+  // Add success method to response object
+  res.success = function (data = null, message = 'Success', statusCode = 200) {
+    return this.status(statusCode).json({
+      success: true,
+      message,
+      data
+    });
+  };
+
+  // Add error method to response object
+  res.error = function (message = 'Error', statusCode = 500, details = null) {
+    return this.status(statusCode).json({
+      success: false,
+      message,
+      details
+    });
+  };
+
+  // Store original json method
+  const originalJson = res.json;
+
+  // Override json method to ensure consistent format
+  res.json = function (data) {
+    // If response is already formatted, use original json
+    if (data && typeof data === 'object' && 'success' in data) {
+      return originalJson.call(this, data);
+    }
+
+    // Format the response
+    return originalJson.call(this, {
+      success: true,
+      data
+    });
+  };
+  next();
+};
+module.exports = responseHandler;

package/dist/swagger/index.js

@@ -0,0 +1,115 @@
+"use strict";
+
+/**
+ * Swagger configuration for Express applications
+ */
+
+const swaggerJsdoc = require('swagger-jsdoc');
+const createSwaggerSpec = (options = {}) => {
+  const defaultOptions = {
+    definition: {
+      openapi: '3.0.0',
+      info: {
+        title: options.title || 'API Documentation',
+        version: options.version || '1.0.0',
+        description: options.description || 'API documentation'
+      },
+      servers: [{
+        url: options.serverUrl || 'http://localhost:3000',
+        description: process.env.NODE_ENV === 'production' ? 'Production server' : 'Development server'
+      }],
+      components: {
+        schemas: {
+          Error: {
+            type: 'object',
+            properties: {
+              success: {
+                type: 'boolean',
+                example: false
+              },
+              message: {
+                type: 'string',
+                example: 'Error message'
+              },
+              details: {
+                type: 'object',
+                example: null
+              }
+            }
+          },
+          Success: {
+            type: 'object',
+            properties: {
+              success: {
+                type: 'boolean',
+                example: true
+              },
+              message: {
+                type: 'string',
+                example: 'Operation successful'
+              },
+              data: {
+                type: 'object',
+                example: null
+              }
+            }
+          }
+        },
+        responses: {
+          UnauthorizedError: {
+            description: 'Access token is missing or invalid',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error'
+                }
+              }
+            }
+          },
+          NotFoundError: {
+            description: 'The specified resource was not found',
+            content: {
+              'application/json': {
+                schema: {
+                  $ref: '#/components/schemas/Error'
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    apis: options.apis || ['./routes/*.js'] // Path to the API routes
+  };
+  const swaggerSpec = swaggerJsdoc(defaultOptions);
+
+  // Remove sensitive information in production
+  if (process.env.NODE_ENV === 'production') {
+    // Remove server URLs in production
+    swaggerSpec.servers = [];
+
+    // Remove any sensitive examples or descriptions
+    if (swaggerSpec.paths) {
+      Object.keys(swaggerSpec.paths).forEach(path => {
+        Object.keys(swaggerSpec.paths[path]).forEach(method => {
+          const operation = swaggerSpec.paths[path][method];
+          if (operation.responses) {
+            Object.keys(operation.responses).forEach(statusCode => {
+              const response = operation.responses[statusCode];
+              if (response.content) {
+                Object.keys(response.content).forEach(contentType => {
+                  const content = response.content[contentType];
+                  if (content.examples) {
+                    delete content.examples;
+                  }
+                });
+              }
+            });
+          }
+        });
+      });
+    }
+  }
+  return swaggerSpec;
+};
+module.exports = createSwaggerSpec;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "powr-sdk-api",
+  "version": "1.0.0",
+  "description": "Shared API core library for PowrStack projects",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "jest --passWithNoTests",
+    "lint": "eslint .",
+    "build": "babel src -d dist",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run test"
+  },
+  "keywords": [
+    "api",
+    "express",
+    "middleware",
+    "error-handling",
+    "response-formatting",
+    "logging",
+    "swagger",
+    "documentation"
+  ],
+  "author": "PowrStack",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/powrstack/powr-sdk-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/powrstack/powr-sdk-api/issues"
+  },
+  "homepage": "https://github.com/powrstack/powr-sdk-api#readme",
+  "dependencies": {
+    "express": "^4.18.2",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.23.9",
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@types/express": "^4.17.21",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.6",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "express": "^4.18.2"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}