payservedb 8.3.8 → 8.4.0

package/ZOHO_INTEGRATION_SCHEMA.md

@@ -0,0 +1,644 @@
+# Zoho Integration Schema - Implementation Summary
+
+## 📋 Overview
+
+The `ZohoIntegration` schema has been successfully created and added to the PayServe database package (psdb). This schema stores Zoho Books API credentials and synchronization data on a per-facility basis.
+
+**Package Version:** `8.3.8` (updated from 8.3.7)
+
+---
+
+## 🗄️ Schema Structure
+
+### Location
+- **File:** `psdb/src/models/zohoIntegration.js`
+- **Model Name:** `ZohoIntegration`
+- **Collection:** `zohointegrations`
+
+### Key Features
+- ✅ One integration per facility (unique constraint on `facilityId`)
+- ✅ Encrypted sensitive fields (clientSecret, refreshToken, accessToken)
+- ✅ Automatic sync tracking and statistics
+- ✅ Token expiry management
+- ✅ Connection status monitoring
+- ✅ Audit trail support
+- ✅ Built-in helper methods
+
+---
+
+## 📊 Schema Fields
+
+### Core Identification
+```javascript
+{
+  facilityId: ObjectId (required, unique, indexed)
+    - Links to Facility collection
+    - One Zoho config per facility
+}
+```
+
+### Zoho API Credentials
+```javascript
+{
+  clientId: String (required)
+    - Zoho OAuth client ID
+    - Example: "1000.XXXXXXXXXXXXX"
+
+  clientSecret: String (required, encrypted)
+    - Zoho OAuth client secret
+    - MUST be encrypted before storage
+
+  refreshToken: String (required, encrypted)
+    - Zoho OAuth refresh token
+    - MUST be encrypted before storage
+    - Example: "1000.XXXXXXXXXXXXX"
+
+  accessToken: String (encrypted, nullable)
+    - Current access token
+    - Auto-refreshed by system
+    - MUST be encrypted before storage
+
+  organizationId: String (required)
+    - Zoho Books organization ID
+    - Example: "902250663"
+}
+```
+
+### Integration Status
+```javascript
+{
+  isActive: Boolean (default: true)
+    - Whether integration is active
+
+  connectionStatus: Enum (default: "pending")
+    - Values: "connected", "disconnected", "error", "pending"
+    - Current connection state
+
+  connectionError: String (nullable)
+    - Last connection error message
+
+  lastConnectionTest: Date (nullable)
+    - Timestamp of last connection test
+}
+```
+
+### Token Management
+```javascript
+{
+  tokenExpiresAt: Date (nullable)
+    - When current access token expires
+
+  lastTokenRefreshAt: Date (nullable)
+    - Last successful token refresh
+
+  tokenRefreshCount: Number (default: 0)
+    - Total token refreshes performed
+}
+```
+
+### Sync Statistics
+```javascript
+{
+  lastSyncedAt: Date (nullable)
+    - Last successful sync timestamp
+
+  totalInvoicesSynced: Number (default: 0)
+    - Total invoices synced to Zoho
+
+  totalPaymentsSynced: Number (default: 0)
+    - Total payments synced to Zoho
+
+  totalCustomersSynced: Number (default: 0)
+    - Total customers synced to Zoho
+
+  successfulSyncs: Number (default: 0)
+    - Count of successful sync operations
+
+  failedSyncs: Number (default: 0)
+    - Count of failed sync operations
+}
+```
+
+### Sync Configuration
+```javascript
+{
+  autoSyncEnabled: Boolean (default: true)
+    - Enable automatic synchronization
+
+  syncFrequency: Enum (default: "realtime")
+    - Values: "realtime", "hourly", "daily", "manual"
+    - How often to sync
+
+  lastSyncError: String (nullable)
+    - Last sync error message
+
+  syncInvoicesOnCreation: Boolean (default: true)
+    - Auto-sync when invoice created
+
+  syncPaymentsOnReceipt: Boolean (default: true)
+    - Auto-sync when payment received
+
+  markInvoicesAsSent: Boolean (default: true)
+    - Mark invoices as "sent" in Zoho
+}
+```
+
+### API Configuration
+```javascript
+{
+  apiBaseUrl: String (default: "https://www.zohoapis.com/books/v3")
+    - Zoho API base URL
+
+  requestTimeout: Number (default: 30000)
+    - API request timeout in milliseconds
+    - Min: 1000ms
+
+  maxRetries: Number (default: 3)
+    - Max retry attempts for failed requests
+    - Min: 0, Max: 10
+}
+```
+
+### Audit Fields
+```javascript
+{
+  createdBy: ObjectId (nullable)
+    - User who created configuration
+
+  updatedBy: ObjectId (nullable)
+    - User who last updated configuration
+
+  lastModifiedBy: ObjectId (nullable)
+    - User who last modified configuration
+
+  createdAt: Date (auto)
+    - Creation timestamp
+
+  updatedAt: Date (auto)
+    - Last update timestamp
+}
+```
+
+### Metadata
+```javascript
+{
+  notes: String (nullable)
+    - Admin notes about integration
+
+  metadata: Mixed (default: {})
+    - Additional custom data
+}
+```
+
+---
+
+## 🔐 Security Considerations
+
+### Fields That MUST Be Encrypted
+
+⚠️ **CRITICAL:** These fields contain sensitive data and MUST be encrypted before storage:
+
+1. `clientSecret`
+2. `refreshToken`
+3. `accessToken`
+
+### Recommended Encryption Approach
+
+```javascript
+const crypto = require('crypto');
+
+// Encryption function (use environment variable for key)
+function encrypt(text) {
+  const algorithm = 'aes-256-cbc';
+  const key = Buffer.from(process.env.ENCRYPTION_KEY, 'hex');
+  const iv = crypto.randomBytes(16);
+
+  const cipher = crypto.createCipheriv(algorithm, key, iv);
+  let encrypted = cipher.update(text, 'utf8', 'hex');
+  encrypted += cipher.final('hex');
+
+  return iv.toString('hex') + ':' + encrypted;
+}
+
+// Decryption function
+function decrypt(text) {
+  const algorithm = 'aes-256-cbc';
+  const key = Buffer.from(process.env.ENCRYPTION_KEY, 'hex');
+
+  const parts = text.split(':');
+  const iv = Buffer.from(parts[0], 'hex');
+  const encryptedText = parts[1];
+
+  const decipher = crypto.createDecipheriv(algorithm, key, iv);
+  let decrypted = decipher.update(encryptedText, 'hex', 'utf8');
+  decrypted += decipher.final('utf8');
+
+  return decrypted;
+}
+```
+
+---
+
+## 🛠️ Built-in Methods
+
+### 1. `toSafeObject()`
+Returns a safe version of the document with masked sensitive fields.
+
+```javascript
+const config = await ZohoIntegration.findOne({ facilityId });
+const safeConfig = config.toSafeObject();
+
+// Output:
+// {
+//   clientSecret: "••••••••7e7d",
+//   refreshToken: "••••••••54d",
+//   accessToken: "••••••••xyz",
+//   ...other fields
+// }
+```
+
+### 2. `needsTokenRefresh()`
+Checks if the access token needs refreshing (5-minute buffer).
+
+```javascript
+const config = await ZohoIntegration.findOne({ facilityId });
+
+if (config.needsTokenRefresh()) {
+  // Refresh the token
+  const newToken = await refreshZohoToken(config);
+  config.accessToken = encrypt(newToken);
+  config.tokenExpiresAt = new Date(Date.now() + 3600000);
+  await config.save();
+}
+```
+
+### 3. `incrementSyncCounters(type, success)`
+Increments sync statistics after each operation.
+
+```javascript
+const config = await ZohoIntegration.findOne({ facilityId });
+
+// After successful invoice sync
+await config.incrementSyncCounters('invoice', true);
+
+// After failed payment sync
+await config.incrementSyncCounters('payment', false);
+```
+
+---
+
+## 📈 Virtual Properties
+
+### `syncSuccessRate`
+Calculates success rate as a percentage.
+
+```javascript
+const config = await ZohoIntegration.findOne({ facilityId });
+console.log(`Success Rate: ${config.syncSuccessRate}%`);
+// Output: "Success Rate: 98.50%"
+```
+
+---
+
+## 🔍 Indexes
+
+The schema includes optimized indexes for common queries:
+
+```javascript
+// Compound index for facility + active status
+{ facilityId: 1, isActive: 1 }
+
+// Index for connection status queries
+{ connectionStatus: 1 }
+
+// Index for sorting by last sync
+{ lastSyncedAt: -1 }
+```
+
+---
+
+## 💻 Usage Examples
+
+### Example 1: Create New Configuration
+
+```javascript
+const { ZohoIntegration } = require('payservedb');
+
+async function createZohoConfig(facilityId, credentials, userId) {
+  try {
+    const config = new ZohoIntegration({
+      facilityId,
+      clientId: credentials.clientId,
+      clientSecret: encrypt(credentials.clientSecret),
+      refreshToken: encrypt(credentials.refreshToken),
+      organizationId: credentials.organizationId,
+      connectionStatus: 'pending',
+      createdBy: userId,
+      updatedBy: userId
+    });
+
+    await config.save();
+    return config.toSafeObject();
+  } catch (error) {
+    if (error.code === 11000) {
+      throw new Error('Zoho integration already exists for this facility');
+    }
+    throw error;
+  }
+}
+```
+
+### Example 2: Get Configuration (Safe)
+
+```javascript
+async function getZohoConfig(facilityId) {
+  const config = await ZohoIntegration.findOne({
+    facilityId,
+    isActive: true
+  });
+
+  if (!config) {
+    return null;
+  }
+
+  // Return safe version (masked secrets)
+  return config.toSafeObject();
+}
+```
+
+### Example 3: Update Configuration
+
+```javascript
+async function updateZohoConfig(facilityId, updates, userId) {
+  const config = await ZohoIntegration.findOne({ facilityId });
+
+  if (!config) {
+    throw new Error('Configuration not found');
+  }
+
+  // Encrypt sensitive fields if provided
+  if (updates.clientSecret) {
+    updates.clientSecret = encrypt(updates.clientSecret);
+  }
+  if (updates.refreshToken) {
+    updates.refreshToken = encrypt(updates.refreshToken);
+  }
+
+  updates.updatedBy = userId;
+  updates.lastModifiedBy = userId;
+
+  Object.assign(config, updates);
+  await config.save();
+
+  return config.toSafeObject();
+}
+```
+
+### Example 4: Test Connection
+
+```javascript
+async function testZohoConnection(facilityId) {
+  const config = await ZohoIntegration.findOne({ facilityId });
+
+  if (!config) {
+    throw new Error('Configuration not found');
+  }
+
+  try {
+    // Test connection to Zoho API
+    const response = await axios.get(
+      `${config.apiBaseUrl}/organizations`,
+      {
+        headers: {
+          'Authorization': `Zoho-oauthtoken ${decrypt(config.accessToken)}`
+        }
+      }
+    );
+
+    // Update status
+    config.connectionStatus = 'connected';
+    config.lastConnectionTest = new Date();
+    config.connectionError = null;
+    await config.save();
+
+    return { success: true };
+  } catch (error) {
+    config.connectionStatus = 'error';
+    config.connectionError = error.message;
+    config.lastConnectionTest = new Date();
+    await config.save();
+
+    return { success: false, error: error.message };
+  }
+}
+```
+
+### Example 5: Disconnect Integration
+
+```javascript
+async function disconnectZoho(facilityId, userId) {
+  const config = await ZohoIntegration.findOne({ facilityId });
+
+  if (!config) {
+    throw new Error('Configuration not found');
+  }
+
+  config.isActive = false;
+  config.connectionStatus = 'disconnected';
+  config.updatedBy = userId;
+  await config.save();
+
+  return { success: true };
+}
+```
+
+### Example 6: Get Integration Statistics
+
+```javascript
+async function getZohoStats(facilityId) {
+  const config = await ZohoIntegration.findOne({ facilityId });
+
+  if (!config) {
+    return null;
+  }
+
+  return {
+    totalInvoicesSynced: config.totalInvoicesSynced,
+    totalPaymentsSynced: config.totalPaymentsSynced,
+    totalCustomersSynced: config.totalCustomersSynced,
+    successfulSyncs: config.successfulSyncs,
+    failedSyncs: config.failedSyncs,
+    successRate: config.syncSuccessRate,
+    lastSyncedAt: config.lastSyncedAt,
+    connectionStatus: config.connectionStatus,
+    isActive: config.isActive
+  };
+}
+```
+
+---
+
+## 🚀 Next Steps
+
+### 1. Update Backend Package
+
+```bash
+cd backend_main
+npm install payservedb@8.3.8
+# or
+npm update payservedb
+```
+
+### 2. Create Controllers
+
+Create the following files in `backend_main`:
+- `src/controllers/integrations/zohoIntegrationController.js`
+- `src/routes/integrations/zohoIntegrationRoutes.js`
+
+### 3. Implement Encryption
+
+Add encryption utilities:
+- `src/utils/encryption.js`
+
+Generate encryption key:
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+Add to `.env`:
+```env
+ENCRYPTION_KEY=your_generated_key_here
+```
+
+### 4. API Endpoints to Create
+
+```
+GET    /api/facility/:facilityId/integrations/zoho/config
+POST   /api/facility/:facilityId/integrations/zoho/config
+PUT    /api/facility/:facilityId/integrations/zoho/config
+DELETE /api/facility/:facilityId/integrations/zoho/config
+POST   /api/facility/:facilityId/integrations/zoho/test
+GET    /api/facility/:facilityId/integrations/zoho/stats
+```
+
+### 5. Frontend Integration
+
+Update the `IntegrationsTab.js` component to:
+- Call the new API endpoints
+- Display real configuration data
+- Handle encryption (send plain, receive masked)
+- Update UI based on connection status
+
+---
+
+## 📝 Migration Notes
+
+### For Existing Facilities
+
+If you need to migrate existing Zoho configurations:
+
+```javascript
+async function migrateExistingConfigs() {
+  // If you have configs stored elsewhere
+  const oldConfigs = await OldModel.find({});
+
+  for (const old of oldConfigs) {
+    await ZohoIntegration.create({
+      facilityId: old.facilityId,
+      clientId: old.clientId,
+      clientSecret: encrypt(old.clientSecret),
+      refreshToken: encrypt(old.refreshToken),
+      organizationId: old.organizationId,
+      connectionStatus: 'pending',
+      createdAt: old.createdAt || new Date()
+    });
+  }
+}
+```
+
+---
+
+## 🧪 Testing
+
+### Unit Test Example
+
+```javascript
+const { ZohoIntegration } = require('payservedb');
+
+describe('ZohoIntegration Model', () => {
+  it('should create config with unique facilityId', async () => {
+    const config = await ZohoIntegration.create({
+      facilityId: mongoose.Types.ObjectId(),
+      clientId: '1000.TEST123',
+      clientSecret: encrypt('secret123'),
+      refreshToken: encrypt('refresh123'),
+      organizationId: '123456'
+    });
+
+    expect(config).toBeDefined();
+    expect(config.isActive).toBe(true);
+    expect(config.connectionStatus).toBe('pending');
+  });
+
+  it('should mask sensitive fields in toSafeObject', () => {
+    const config = new ZohoIntegration({
+      clientSecret: 'very_secret_key',
+      refreshToken: 'refresh_token_123'
+    });
+
+    const safe = config.toSafeObject();
+    expect(safe.clientSecret).toContain('••••••••');
+    expect(safe.refreshToken).toContain('••••••••');
+  });
+
+  it('should calculate sync success rate', () => {
+    const config = new ZohoIntegration({
+      successfulSyncs: 95,
+      failedSyncs: 5
+    });
+
+    expect(config.syncSuccessRate).toBe('95.00');
+  });
+});
+```
+
+---
+
+## ⚠️ Important Warnings
+
+1. **NEVER** return decrypted secrets to the frontend
+2. **ALWAYS** use `toSafeObject()` when sending to API responses
+3. **ENCRYPT** sensitive fields before saving to database
+4. **VALIDATE** all inputs before storing
+5. **AUDIT** all configuration changes
+6. **MONITOR** connection status regularly
+7. **ROTATE** tokens periodically for security
+
+---
+
+## 📚 Related Documentation
+
+- **Zoho API Documentation:** [https://www.zoho.com/books/api/v3/](https://www.zoho.com/books/api/v3/)
+- **OAuth 2.0 Guide:** `backend_main/src/services/integrations/zoho/README.md`
+- **Frontend Component:** `app_main/src/components/facility/settings_management/IntegrationsTab.js`
+- **Payment Integration:** `backend_main/src/controllers/integrations/zoho/PAYMENT_GUIDE.md`
+
+---
+
+## ✅ Status
+
+- ✅ Schema created and validated
+- ✅ Model exported in payservedb package
+- ✅ Package version bumped to 8.3.8
+- ✅ Indexes defined for performance
+- ✅ Helper methods implemented
+- ✅ Security considerations documented
+- ⏳ Controllers and routes (pending)
+- ⏳ Encryption utilities (pending)
+- ⏳ Frontend integration (pending)
+
+---
+
+**Last Updated:** 2025-10-28
+**Schema Version:** 1.0.0
+**Package Version:** 8.3.8