@solutionspool/node-micro-contracts 1.0.0

package/USAGE_GUIDE.md

@@ -0,0 +1,434 @@
+# Contracts Package Usage Guide
+
+## Complete Guide to Using @node-micro/contracts
+
+This guide shows you how to integrate the contracts package into your microservices.
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Request Validation](#request-validation)
+3. [Event Publishing](#event-publishing)
+4. [Event Consumption](#event-consumption)
+5. [Error Handling](#error-handling)
+6. [Best Practices](#best-practices)
+
+## Installation
+
+The package is already installed in both services. If you need to reinstall:
+
+```bash
+# In auth-service or user-service
+npm install ../../packages/contracts
+```
+
+## Request Validation
+
+### Using Middleware (Recommended)
+
+The easiest way to validate requests is using the built-in middleware:
+
+```javascript
+const express = require("express");
+const router = express.Router();
+const {
+  UserRegistrationSchema,
+  UserLoginSchema,
+  UserProfileUpdateSchema,
+  validateRequest,
+} = require("@node-micro/contracts");
+
+// Registration endpoint with validation
+router.post(
+  "/register",
+  validateRequest(UserRegistrationSchema),
+  async (req, res) => {
+    // req.validatedData contains the validated and sanitized data
+    const { name, email, password, role, mobile } = req.validatedData;
+
+    // Your logic here...
+  },
+);
+
+// Login endpoint with validation
+router.post("/login", validateRequest(UserLoginSchema), async (req, res) => {
+  const { email, password } = req.validatedData;
+  // Your logic here...
+});
+
+// Profile update with validation
+router.put(
+  "/profile",
+  verifyToken, // Your auth middleware
+  validateRequest(UserProfileUpdateSchema),
+  async (req, res) => {
+    const updates = req.validatedData;
+    // Your logic here...
+  },
+);
+```
+
+### Manual Validation
+
+For more control, validate manually in your controllers:
+
+```javascript
+const { UserRegistrationSchema } = require("@node-micro/contracts");
+
+async function register(req, res) {
+  // Safe parse returns { success, data, error }
+  const result = UserRegistrationSchema.safeParse(req.body);
+
+  if (!result.success) {
+    return res.status(400).json({
+      error: "Validation failed",
+      details: result.error.errors.map((err) => ({
+        path: err.path.join("."),
+        message: err.message,
+      })),
+    });
+  }
+
+  const validData = result.data;
+  // Continue with valid data...
+}
+```
+
+## Event Publishing
+
+Always validate event data before publishing to ensure contract compliance:
+
+### In auth-service Controller
+
+```javascript
+const {
+  UserRegisteredEventSchema,
+  UserUpdatedEventSchema,
+} = require("@node-micro/contracts");
+
+class AuthController {
+  constructor(messageQueue) {
+    this.messageQueue = messageQueue;
+  }
+
+  async register(req, res) {
+    try {
+      // ... create user logic ...
+
+      // Validate and publish event
+      if (this.messageQueue) {
+        try {
+          const eventData = UserRegisteredEventSchema.parse({
+            userId: user.id,
+            name: user.name,
+            email: user.email,
+            mobile: req.body.mobile,
+            role: user.role,
+            createdAt: user.createdAt,
+          });
+
+          await this.messageQueue.publishEvent(
+            "users",
+            "user.registered",
+            eventData,
+          );
+        } catch (error) {
+          console.error("Event validation failed:", error.message);
+          // Log but don't fail the request
+        }
+      }
+
+      res.status(201).json({ message: "User registered", token, user });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  }
+}
+```
+
+## Event Consumption
+
+Validate incoming events to ensure data integrity:
+
+### In user-service Event Listeners
+
+```javascript
+const {
+  UserRegisteredEventSchema,
+  UserVerifiedEventSchema,
+  UserUpdatedEventSchema,
+} = require("@node-micro/contracts");
+const { User } = require("../models");
+
+async function subscribeToEvents(messageQueue) {
+  // User registered event
+  await messageQueue.subscribeToEvent(
+    "users",
+    "user-service-queue",
+    "user.registered",
+    async (rawData) => {
+      try {
+        // Validate incoming event data
+        const userData = UserRegisteredEventSchema.parse(rawData);
+
+        // Create user with validated data
+        await User.create({
+          id: userData.userId,
+          name: userData.name,
+          email: userData.email,
+          mobile: userData.mobile,
+          role: userData.role,
+          createdAt: userData.createdAt,
+        });
+
+        console.log(`✓ User profile created for ${userData.email}`);
+      } catch (error) {
+        if (error.name === "ZodError") {
+          console.error("Invalid event data:", error.errors);
+          // Send to dead letter queue or alert
+        } else if (error.name === "SequelizeUniqueConstraintError") {
+          console.log(`User ${rawData.email} already exists`);
+        } else {
+          console.error("Failed to create user:", error.message);
+          throw error; // Trigger retry
+        }
+      }
+    },
+  );
+
+  // User verified event
+  await messageQueue.subscribeToEvent(
+    "users",
+    "user-service-queue",
+    "user.verified",
+    async (rawData) => {
+      try {
+        const verificationData = UserVerifiedEventSchema.parse(rawData);
+
+        await User.update(
+          {
+            emailVerified: true,
+            verifiedAt: verificationData.verifiedAt,
+          },
+          { where: { id: verificationData.userId } },
+        );
+
+        console.log(`✓ User verified: ${verificationData.email}`);
+      } catch (error) {
+        if (error.name === "ZodError") {
+          console.error("Invalid verification event:", error.errors);
+        } else {
+          throw error;
+        }
+      }
+    },
+  );
+}
+
+module.exports = { subscribeToEvents };
+```
+
+## Error Handling
+
+### Validation Error Format
+
+When validation fails, errors are returned in a consistent format:
+
+```json
+{
+  "error": "Validation failed",
+  "details": [
+    {
+      "path": "email",
+      "message": "Invalid email format"
+    },
+    {
+      "path": "password",
+      "message": "Password must be at least 6 characters"
+    }
+  ]
+}
+```
+
+### Handling Zod Errors
+
+```javascript
+try {
+  const validData = UserRegistrationSchema.parse(data);
+} catch (error) {
+  if (error.name === "ZodError") {
+    // Access specific error details
+    error.errors.forEach((err) => {
+      console.log(`Field: ${err.path.join(".")}`);
+      console.log(`Message: ${err.message}`);
+      console.log(`Code: ${err.code}`);
+    });
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Validate at Boundaries
+
+- ✅ Validate HTTP requests at route level
+- ✅ Validate events before publishing
+- ✅ Validate events when consuming
+
+### 2. Use Type Inference
+
+```javascript
+const { z } = require("zod");
+const { UserRegistrationSchema } = require("@node-micro/contracts");
+
+// Get the inferred type (useful for TypeScript or JSDoc)
+/** @typedef {z.infer<typeof UserRegistrationSchema>} UserRegistration */
+```
+
+### 3. Handle Validation Errors Gracefully
+
+```javascript
+// For requests - return 400 Bad Request
+if (!result.success) {
+  return res.status(400).json({
+    error: "Validation failed",
+    details: result.error.errors,
+  });
+}
+
+// For events - log and send to DLQ
+if (error.name === "ZodError") {
+  console.error("Invalid event:", error.errors);
+  await sendToDeadLetterQueue(rawData);
+  return; // Don't throw - prevent infinite retries
+}
+```
+
+### 4. Partial Validation
+
+For optional fields or partial updates:
+
+```javascript
+const { UserProfileUpdateSchema } = require("@node-micro/contracts");
+
+// All fields are optional in UserProfileUpdateSchema
+const result = UserProfileUpdateSchema.parse({
+  name: "New Name", // email not provided - that's ok
+});
+```
+
+### 5. Custom Schemas
+
+Extend existing schemas for specific use cases:
+
+```javascript
+const { z } = require("zod");
+const { UserBaseSchema } = require("@node-micro/contracts");
+
+// Create a custom schema with additional fields
+const UserWithStatsSchema = UserBaseSchema.extend({
+  loginCount: z.number().int().min(0),
+  lastLoginAt: z.date().optional(),
+});
+```
+
+### 6. Environment-Specific Validation
+
+```javascript
+const { UserRegistrationSchema } = require("@node-micro/contracts");
+
+// In development, be strict
+const isDevelopment = process.env.NODE_ENV === "development";
+
+function validateRegistration(data) {
+  if (isDevelopment) {
+    // Throw on validation error in dev
+    return UserRegistrationSchema.parse(data);
+  } else {
+    // Return result in production for better error handling
+    return UserRegistrationSchema.safeParse(data);
+  }
+}
+```
+
+## Migration Strategy
+
+### Step 1: Add Validation Middleware to Routes
+
+```javascript
+// Before
+router.post("/register", authController.register);
+
+// After
+router.post(
+  "/register",
+  validateRequest(UserRegistrationSchema),
+  authController.register,
+);
+```
+
+### Step 2: Update Controllers to Use Validated Data
+
+```javascript
+// Before
+async register(req, res) {
+  const { name, email, password } = req.body;
+  // ...
+}
+
+// After
+async register(req, res) {
+  const { name, email, password } = req.validatedData; // Use validatedData
+  // ...
+}
+```
+
+### Step 3: Add Event Validation
+
+```javascript
+// Before
+await messageQueue.publishEvent("users", "user.registered", {
+  userId: user.id,
+  name: user.name,
+  // ...
+});
+
+// After
+const eventData = UserRegisteredEventSchema.parse({
+  userId: user.id,
+  name: user.name,
+  // ...
+});
+await messageQueue.publishEvent("users", "user.registered", eventData);
+```
+
+## Available Schemas Reference
+
+### Request Schemas
+
+- `UserRegistrationSchema` - name, email, mobile?, password, role?
+- `UserLoginSchema` - email, password
+- `UserProfileUpdateSchema` - name?, email?, role?
+
+### Event Schemas
+
+- `UserRegisteredEventSchema` - userId, name, email, mobile?, role, createdAt
+- `UserVerifiedEventSchema` - userId, email, verifiedAt
+- `UserUpdatedEventSchema` - userId, name?, email?, role?, updatedAt
+- `UserDeletedEventSchema` - userId, email, deletedAt
+
+### Response Schemas
+
+- `UserResponseSchema` - User data without password
+- `AuthResponseSchema` - message, token, user
+- `JWTPayloadSchema` - iss, sub, id, email, role, iat?, exp?
+
+### Middleware
+
+- `validateRequest(schema)` - Validates req.body
+- `validateQuery(schema)` - Validates req.query
+- `validateParams(schema)` - Validates req.params
+
+## Questions?
+
+Check the `/examples` directory in the contracts package for more examples, or review the schemas directly in `/schemas`.

package/examples/auth-routes.example.js

@@ -0,0 +1,38 @@
+/**
+ * Example: Using Contracts in Auth Service Routes
+ *
+ * This file demonstrates how to use the @node-micro/contracts package
+ * for request validation in auth-service routes
+ */
+
+const express = require("express");
+const router = express.Router();
+const {
+  UserRegistrationSchema,
+  UserLoginSchema,
+  validateRequest,
+} = require("@node-micro/contracts");
+
+// Example: Register route with validation
+router.post(
+  "/register",
+  validateRequest(UserRegistrationSchema),
+  async (req, res) => {
+    // req.validatedData contains the validated data
+    const { name, email, password, role, mobile } = req.validatedData;
+
+    // Your controller logic here
+    // authController.register(req, res);
+  },
+);
+
+// Example: Login route with validation
+router.post("/login", validateRequest(UserLoginSchema), async (req, res) => {
+  // req.validatedData contains the validated data
+  const { email, password } = req.validatedData;
+
+  // Your controller logic here
+  // authController.login(req, res);
+});
+
+module.exports = router;

package/examples/event-consumption.example.js

@@ -0,0 +1,109 @@
+/**
+ * Example: Using Contracts for Event Consumption
+ *
+ * This file demonstrates how to use the @node-micro/contracts package
+ * for validating incoming event data in event listeners
+ */
+
+const {
+  UserRegisteredEventSchema,
+  UserVerifiedEventSchema,
+  UserUpdatedEventSchema,
+} = require("@node-micro/contracts");
+const { User } = require("../models");
+
+async function subscribeToEventsExample(messageQueue) {
+  // Subscribe to user.registered event with validation
+  await messageQueue.subscribeToEvent(
+    "users",
+    "user-service-queue",
+    "user.registered",
+    async (rawData) => {
+      try {
+        // Validate incoming event data
+        const userData = UserRegisteredEventSchema.parse(rawData);
+
+        // Now userData is validated and type-safe
+        await User.create({
+          id: userData.userId,
+          name: userData.name,
+          email: userData.email,
+          mobile: userData.mobile,
+          role: userData.role,
+          createdAt: userData.createdAt,
+        });
+
+        console.log(`✓ User profile created for ${userData.email}`);
+      } catch (error) {
+        if (error.name === "ZodError") {
+          console.error("Event validation failed:", error.errors);
+          // Handle validation error - maybe send to DLQ
+        } else if (error.name === "SequelizeUniqueConstraintError") {
+          console.log(`User already exists`);
+        } else {
+          console.error("Failed to create user profile:", error.message);
+          throw error;
+        }
+      }
+    },
+  );
+
+  // Subscribe to user.verified event with validation
+  await messageQueue.subscribeToEvent(
+    "users",
+    "user-service-queue",
+    "user.verified",
+    async (rawData) => {
+      try {
+        const verificationData = UserVerifiedEventSchema.parse(rawData);
+
+        // Update user with validated data
+        await User.update(
+          { emailVerified: true, verifiedAt: verificationData.verifiedAt },
+          { where: { id: verificationData.userId } },
+        );
+
+        console.log(`✓ User verified: ${verificationData.email}`);
+      } catch (error) {
+        if (error.name === "ZodError") {
+          console.error("Event validation failed:", error.errors);
+        } else {
+          console.error("Failed to verify user:", error.message);
+          throw error;
+        }
+      }
+    },
+  );
+
+  // Subscribe to user.updated event with validation
+  await messageQueue.subscribeToEvent(
+    "users",
+    "user-service-queue",
+    "user.updated",
+    async (rawData) => {
+      try {
+        const updateData = UserUpdatedEventSchema.parse(rawData);
+
+        // Build update object from validated data
+        const updates = {};
+        if (updateData.name) updates.name = updateData.name;
+        if (updateData.email) updates.email = updateData.email;
+        if (updateData.role) updates.role = updateData.role;
+        updates.updatedAt = updateData.updatedAt;
+
+        await User.update(updates, { where: { id: updateData.userId } });
+
+        console.log(`✓ User updated: ${updateData.userId}`);
+      } catch (error) {
+        if (error.name === "ZodError") {
+          console.error("Event validation failed:", error.errors);
+        } else {
+          console.error("Failed to update user:", error.message);
+          throw error;
+        }
+      }
+    },
+  );
+}
+
+module.exports = { subscribeToEventsExample };

package/examples/event-publishing.example.js

@@ -0,0 +1,82 @@
+/**
+ * Example: Using Contracts for Event Publishing
+ *
+ * This file demonstrates how to use the @node-micro/contracts package
+ * for validating event data before publishing
+ */
+
+const {
+  UserRegisteredEventSchema,
+  UserUpdatedEventSchema,
+  UserDeletedEventSchema,
+} = require("@node-micro/contracts");
+
+class AuthControllerExample {
+  constructor(messageQueue) {
+    this.messageQueue = messageQueue;
+  }
+
+  async register(req, res) {
+    try {
+      // ... user creation logic ...
+      const user = {
+        id: "uuid",
+        name: "John",
+        email: "john@example.com",
+        role: "user",
+        createdAt: new Date(),
+      };
+
+      // Validate event data before publishing
+      const eventData = UserRegisteredEventSchema.parse({
+        userId: user.id,
+        name: user.name,
+        email: user.email,
+        mobile: req.body.mobile,
+        role: user.role,
+        createdAt: user.createdAt,
+      });
+
+      // Publish validated event
+      await this.messageQueue.publishEvent(
+        "users",
+        "user.registered",
+        eventData,
+      );
+
+      res.status(201).json({ message: "User registered" });
+    } catch (error) {
+      if (error.name === "ZodError") {
+        return res.status(500).json({
+          error: "Event validation failed",
+          details: error.errors,
+        });
+      }
+      res.status(500).json({ error: error.message });
+    }
+  }
+
+  async updateUser(req, res) {
+    try {
+      // ... update logic ...
+      const user = { id: "uuid", name: "Jane", email: "jane@example.com" };
+
+      // Validate event data
+      const eventData = UserUpdatedEventSchema.parse({
+        userId: user.id,
+        name: user.name,
+        email: user.email,
+        role: user.role,
+        updatedAt: new Date(),
+      });
+
+      await this.messageQueue.publishEvent("users", "user.updated", eventData);
+
+      res.json({ message: "User updated" });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  }
+}
+
+module.exports = AuthControllerExample;

package/index.js

@@ -0,0 +1,25 @@
+/**
+ * @node-micro/contracts
+ *
+ * Centralized contracts and schemas for microservices communication
+ * Uses Zod for runtime validation and type inference
+ */
+
+const userSchemas = require("./schemas/user.schema");
+const eventSchemas = require("./schemas/events.schema");
+const commonSchemas = require("./schemas/common.schema");
+const validators = require("./middleware/validate");
+
+module.exports = {
+  // User Schemas
+  ...userSchemas,
+
+  // Event Schemas
+  ...eventSchemas,
+
+  // Common Schemas (params, query)
+  ...commonSchemas,
+
+  // Validators/Middleware
+  ...validators,
+};