@solutionspool/node-micro-contracts 1.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,302 @@
+# Contracts Package Architecture
+
+## 📊 System Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     @node-micro/contracts                        │
+│                  Centralized Contract Package                    │
+└─────────────────────────────────────────────────────────────────┘
+                               │
+                ┌──────────────┴──────────────┐
+                │                             │
+                ▼                             ▼
+    ┌───────────────────┐          ┌───────────────────┐
+    │  auth-service     │          │  user-service     │
+    │                   │          │                   │
+    │  • Routes         │          │  • Routes         │
+    │  • Controllers    │          │  • Controllers    │
+    │  • Event Pub      │──────────▶  • Event Sub      │
+    └───────────────────┘          └───────────────────┘
+```
+
+## 🏗️ Package Structure
+
+```
+@node-micro/contracts
+│
+├── 📄 index.js                    # Main exports
+│
+├── 📁 schemas/
+│   ├── user.schema.js             # User-related schemas
+│   │   ├── UserRole              # Enum: user|provider|admin
+│   │   ├── UserBaseSchema        # Base user fields
+│   │   ├── UserRegistrationSchema
+│   │   ├── UserLoginSchema
+│   │   ├── UserProfileUpdateSchema
+│   │   ├── UserResponseSchema
+│   │   ├── JWTPayloadSchema
+│   │   └── AuthResponseSchema
+│   │
+│   └── events.schema.js           # Event schemas
+│       ├── UserRegisteredEventSchema
+│       ├── UserVerifiedEventSchema
+│       ├── UserUpdatedEventSchema
+│       └── UserDeletedEventSchema
+│
+├── 📁 middleware/
+│   └── validate.js                # Validation middleware
+│       ├── validateRequest()
+│       ├── validateQuery()
+│       └── validateParams()
+│
+├── 📁 examples/
+│   ├── auth-routes.example.js
+│   ├── event-publishing.example.js
+│   └── event-consumption.example.js
+│
+└── 📁 docs/
+    ├── README.md
+    ├── QUICKSTART.md
+    └── USAGE_GUIDE.md
+```
+
+## 🔄 Data Flow
+
+### 1. HTTP Request Flow (with Validation)
+
+```
+┌──────────┐      ┌──────────────┐      ┌──────────┐      ┌──────────┐
+│  Client  │─────▶│  Validation  │─────▶│  Route   │─────▶│Controller│
+│          │      │  Middleware  │      │          │      │          │
+└──────────┘      └──────────────┘      └──────────┘      └──────────┘
+                         │
+                         │ (if valid)
+                         ▼
+                  req.validatedData
+```
+
+### 2. Event Publishing Flow (auth-service)
+
+```
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│  Controller  │─────▶│   Validate   │─────▶│  RabbitMQ    │
+│  (create     │      │   Event      │      │  Exchange    │
+│   user)      │      │   Schema     │      │              │
+└──────────────┘      └──────────────┘      └──────────────┘
+                            │
+                            ▼
+              UserRegisteredEventSchema.parse()
+```
+
+### 3. Event Consumption Flow (user-service)
+
+```
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│  RabbitMQ    │─────▶│   Validate   │─────▶│  Create      │
+│  Queue       │      │   Event      │      │  User        │
+│              │      │   Schema     │      │  Profile     │
+└──────────────┘      └──────────────┘      └──────────────┘
+                            │
+                            ▼
+              UserRegisteredEventSchema.parse()
+```
+
+## 📋 Contract Types
+
+### Request Contracts (HTTP)
+
+```javascript
+// Input validation for API endpoints
+UserRegistrationSchema  →  POST /register
+UserLoginSchema        →  POST /login
+UserProfileUpdateSchema →  PUT /profile
+```
+
+### Event Contracts (Message Queue)
+
+```javascript
+// Inter-service communication
+UserRegisteredEventSchema  →  auth-service → user-service
+UserVerifiedEventSchema    →  auth-service → user-service
+UserUpdatedEventSchema     →  any-service  → user-service
+UserDeletedEventSchema     →  any-service  → user-service
+```
+
+### Response Contracts
+
+```javascript
+// Standardized API responses
+UserResponseSchema     →  User data (no password)
+AuthResponseSchema     →  Login/Register response
+JWTPayloadSchema       →  Token payload structure
+```
+
+## 🔐 Validation Layers
+
+```
+Layer 1: API Gateway (Kong)
+           │
+           ▼
+Layer 2: Request Validation (Zod Middleware)
+           │
+           ▼
+Layer 3: Business Logic (Controller)
+           │
+           ▼
+Layer 4: Event Validation (Zod Schema)
+           │
+           ▼
+Layer 5: Message Queue (RabbitMQ)
+           │
+           ▼
+Layer 6: Event Consumption Validation (Zod Schema)
+           │
+           ▼
+Layer 7: Database (Sequelize)
+```
+
+## 🎯 Usage Patterns
+
+### Pattern 1: Route + Middleware
+
+```javascript
+router.post(
+  "/register",
+  validateRequest(UserRegistrationSchema), // Middleware
+  controller.register, // Handler
+);
+```
+
+### Pattern 2: Manual Validation
+
+```javascript
+const result = UserRegistrationSchema.safeParse(data);
+if (!result.success) {
+  return handleError(result.error);
+}
+```
+
+### Pattern 3: Event Publishing
+
+```javascript
+const eventData = UserRegisteredEventSchema.parse(data);
+await messageQueue.publishEvent("users", "user.registered", eventData);
+```
+
+### Pattern 4: Event Consumption
+
+```javascript
+await messageQueue.subscribeToEvent(
+  "users",
+  "queue",
+  "user.registered",
+  async (rawData) => {
+    const validated = UserRegisteredEventSchema.parse(rawData);
+    await processUser(validated);
+  },
+);
+```
+
+## 🚀 Benefits by Layer
+
+| Layer             | Without Contracts               | With Contracts                    |
+| ----------------- | ------------------------------- | --------------------------------- |
+| **Routes**        | Manual validation, inconsistent | Middleware, standardized          |
+| **Controllers**   | Type uncertainty                | Type-safe data                    |
+| **Events**        | No validation, trust data       | Validated at source & destination |
+| **Consumers**     | Risk of invalid data            | Guaranteed valid structure        |
+| **Debugging**     | Hard to trace issues            | Clear validation errors           |
+| **Documentation** | Separate docs needed            | Self-documenting schemas          |
+
+## 🔄 Update Flow
+
+```
+1. Update Schema
+   /packages/contracts/schemas/user.schema.js
+
+2. Changes Immediately Available (symlinked)
+   auth-service  ✓
+   user-service  ✓
+
+3. Tests Still Pass
+   npm run test
+
+4. Deploy
+   All services get updated contracts
+```
+
+## 📊 Contract Governance
+
+```
+┌─────────────────────────────────────────┐
+│         Contract Owner                   │
+│      (contracts package)                 │
+└─────────────────────────────────────────┘
+              │
+    ┌─────────┴─────────┐
+    ▼                   ▼
+┌─────────┐       ┌─────────┐
+│Producer │       │Consumer │
+│Services │       │Services │
+│         │       │         │
+│ auth-   │       │ user-   │
+│ service │       │ service │
+└─────────┘       └─────────┘
+
+All changes must go through the contract package
+No direct data structure changes in services
+```
+
+## 🎨 Example: Complete User Registration Flow
+
+```
+1. Client → POST /register
+             │
+2. validateRequest(UserRegistrationSchema)
+             │
+             ├─ Valid? → Continue
+             └─ Invalid? → 400 Error with details
+             │
+3. Controller creates user
+             │
+4. UserRegisteredEventSchema.parse(userData)
+             │
+5. Publish to RabbitMQ
+             │
+6. user-service receives event
+             │
+7. UserRegisteredEventSchema.parse(eventData)
+             │
+8. Create user profile
+             │
+9. ✓ Success - User exists in both services
+```
+
+## 📈 Scalability
+
+```
+Current:
+  auth-service  ──┐
+                  ├──▶ @node-micro/contracts
+  user-service  ──┘
+
+Future:
+  auth-service     ──┐
+  user-service     ──┤
+  booking-service  ──┼──▶ @node-micro/contracts
+  provider-service ──┤
+  payment-service  ──┘
+```
+
+All services share the same contract definitions!
+
+---
+
+**Visual Key:**
+
+- 📄 File
+- 📁 Folder
+- ─▶ Data Flow
+- ✓ Success
+- ✗ Failure

package/QUICKSTART.md

@@ -0,0 +1,204 @@
+# Quick Start: Using Contracts
+
+## 🚀 3-Minute Integration Guide
+
+### 1. Import What You Need
+
+```javascript
+const {
+  // Validation Middleware
+  validateRequest,
+
+  // Request Schemas
+  UserRegistrationSchema,
+  UserLoginSchema,
+  UserProfileUpdateSchema,
+
+  // Event Schemas
+  UserRegisteredEventSchema,
+  UserUpdatedEventSchema,
+  UserDeletedEventSchema,
+} = require("@node-micro/contracts");
+```
+
+### 2. Add to Your Routes (auth-service)
+
+```javascript
+// routes/auth.js
+const express = require("express");
+const router = express.Router();
+const {
+  validateRequest,
+  UserRegistrationSchema,
+  UserLoginSchema,
+} = require("@node-micro/contracts");
+const AuthController = require("../controllers/authController");
+
+const authController = new AuthController(messageQueue);
+
+router.post("/register", validateRequest(UserRegistrationSchema), (req, res) =>
+  authController.register(req, res),
+);
+
+router.post("/login", validateRequest(UserLoginSchema), (req, res) =>
+  authController.login(req, res),
+);
+
+module.exports = router;
+```
+
+### 3. Update Your Controller (auth-service)
+
+```javascript
+// controllers/authController.js
+const { UserRegisteredEventSchema } = require("@node-micro/contracts");
+
+class AuthController {
+  async register(req, res) {
+    try {
+      // Use req.validatedData instead of req.body
+      const { name, email, password, role, mobile } = req.validatedData;
+
+      // ... create user ...
+
+      // Validate event before publishing
+      if (this.messageQueue) {
+        const eventData = UserRegisteredEventSchema.parse({
+          userId: user.id,
+          name: user.name,
+          email: user.email,
+          mobile: mobile,
+          role: user.role,
+          createdAt: user.createdAt,
+        });
+
+        await this.messageQueue.publishEvent(
+          "users",
+          "user.registered",
+          eventData,
+        );
+      }
+
+      res.status(201).json({ message: "Success", token, user });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  }
+}
+```
+
+### 4. Validate Events in Listeners (user-service)
+
+```javascript
+// events/listeners.js
+const { UserRegisteredEventSchema } = require("@node-micro/contracts");
+
+async function subscribeToEvents(messageQueue) {
+  await messageQueue.subscribeToEvent(
+    "users",
+    "user-service-queue",
+    "user.registered",
+    async (rawData) => {
+      try {
+        // Validate incoming event
+        const userData = UserRegisteredEventSchema.parse(rawData);
+
+        // Use validated data
+        await User.create({
+          id: userData.userId,
+          name: userData.name,
+          email: userData.email,
+          mobile: userData.mobile,
+          role: userData.role,
+          createdAt: userData.createdAt,
+        });
+      } catch (error) {
+        if (error.name === "ZodError") {
+          console.error("Invalid event:", error.errors);
+        } else {
+          throw error;
+        }
+      }
+    },
+  );
+}
+```
+
+## ✅ That's It!
+
+You now have:
+
+- ✅ Request validation on all endpoints
+- ✅ Event validation for publishing
+- ✅ Event validation for consumption
+- ✅ Consistent error messages
+- ✅ Type-safe data contracts
+
+## 📚 Next Steps
+
+- Read [USAGE_GUIDE.md](./USAGE_GUIDE.md) for complete documentation
+- Check [/examples](./examples) for more patterns
+- Review [/schemas](./schemas) to see all available schemas
+
+## 🎯 Common Patterns
+
+### Validate but Don't Fail Registration if Event Publish Fails
+
+```javascript
+if (this.messageQueue) {
+  try {
+    const eventData = UserRegisteredEventSchema.parse(data);
+    await this.messageQueue.publishEvent("users", "user.registered", eventData);
+  } catch (error) {
+    console.error("Event publish failed:", error);
+    // Don't throw - user is already created
+  }
+}
+```
+
+### Handle Duplicate Users in Event Listener
+
+```javascript
+try {
+  const userData = UserRegisteredEventSchema.parse(rawData);
+  await User.create(userData);
+} catch (error) {
+  if (error.name === "ZodError") {
+    console.error("Invalid event data");
+  } else if (error.name === "SequelizeUniqueConstraintError") {
+    console.log("User already exists - skipping");
+  } else {
+    throw error; // Trigger retry
+  }
+}
+```
+
+### Manual Validation with Better Error Messages
+
+```javascript
+const result = UserRegistrationSchema.safeParse(req.body);
+
+if (!result.success) {
+  return res.status(400).json({
+    error: "Validation failed",
+    details: result.error.errors.map((err) => ({
+      field: err.path.join("."),
+      message: err.message,
+    })),
+  });
+}
+```
+
+## 🛠️ Troubleshooting
+
+**Q: Validation middleware not working?**  
+A: Make sure the middleware is placed BEFORE your controller in the route chain.
+
+**Q: Getting ZodError in production?**  
+A: Use `safeParse()` instead of `parse()` to handle errors gracefully.
+
+**Q: Need to update contracts?**  
+A: Edit schemas in `/schemas`, then reinstall in services: `npm install ../../packages/contracts`
+
+**Q: How to add custom validation?**  
+A: Extend existing schemas or create custom ones using Zod's `.extend()` and `.refine()` methods.

package/README.md

@@ -0,0 +1,95 @@
+# @node-micro/contracts
+
+Centralized contracts and schemas for node-micro microservices communication.
+
+## Overview
+
+This package provides Zod-based schemas for validating data contracts between microservices. It ensures type safety and consistent data structures across the auth-service and user-service.
+
+## Installation
+
+```bash
+npm install file:../../packages/contracts
+```
+
+## Usage
+
+### Basic Import
+
+```javascript
+const {
+  UserRegistrationSchema,
+  UserLoginSchema,
+  UserRegisteredEventSchema,
+  JWTPayloadSchema,
+} = require("@node-micro/contracts");
+```
+
+### Validation Example
+
+```javascript
+// Validate registration data
+const result = UserRegistrationSchema.safeParse(req.body);
+
+if (!result.success) {
+  return res.status(400).json({
+    error: "Validation failed",
+    details: result.error.errors,
+  });
+}
+
+const validData = result.data;
+```
+
+### Event Validation
+
+```javascript
+// Validate event data before publishing
+const eventData = {
+  userId: user.id,
+  name: user.name,
+  email: user.email,
+  mobile: user.mobile,
+  role: user.role,
+  createdAt: user.createdAt,
+};
+
+const validated = UserRegisteredEventSchema.parse(eventData);
+await messageQueue.publishEvent("users", "user.registered", validated);
+```
+
+## Available Schemas
+
+### User Schemas
+
+- `UserRole` - Enum for user roles (user, provider, admin)
+- `UserBaseSchema` - Base user fields
+- `UserRegistrationSchema` - User registration request
+- `UserLoginSchema` - User login request
+- `UserProfileUpdateSchema` - User profile update
+- `UserResponseSchema` - User response (without password)
+- `JWTPayloadSchema` - JWT token payload
+- `AuthResponseSchema` - Auth response with token
+
+### Event Schemas
+
+- `UserRegisteredEventSchema` - User registration event
+- `UserVerifiedEventSchema` - User verification event
+- `UserUpdatedEventSchema` - User update event
+- `UserDeletedEventSchema` - User deletion event
+
+## Type Inference
+
+Use Zod's type inference for TypeScript-like type safety:
+
+```javascript
+const { z } = require("zod");
+const { UserRegistrationSchema } = require("@node-micro/contracts");
+
+// Infer the type
+// type UserRegistration = z.infer<typeof UserRegistrationSchema>;
+```
+
+## License
+
+ISC