port-nimara-client-portal/docs/email-system-fixes.md

# Email System Fixes

## Issues Addressed

### 1. Email Credentials Not Found Errors
- **Problem**: The system was trying to fetch emails even when no credentials were present
- **Solution**: 
  - Added session ID check in `EmailThreadView` before attempting to fetch emails
  - Modified `fetch-thread` API to return empty results instead of throwing errors when credentials are missing
  - Added proper session cleanup in `EmailCommunication` component

### 2. 502 Gateway Timeout Errors
- **Problem**: Email fetching was causing timeouts, especially when editing/saving interest cards
- **Solution**:
  - Reduced email fetch limit from 50 to 20 emails
  - Added 15-second timeout for IMAP connections
  - Prevented unnecessary email fetches when no session exists

### 3. EOI Generation Issues
- **Problem**: EOI generation was failing due to missing Address field and configuration issues
- **Solution**:
  - Made Address field optional with default value "Not Provided"
  - Added environment variable validation for `NUXT_DOCUMENSO_API_KEY` and `NUXT_DOCUMENSO_BASE_URL`
  - Improved error messages to indicate when configuration is missing or fields need to be filled
  - Required fields are now: Full Name, Email Address, Yacht Name, Length, Width, Depth

### 4. Interest Save Failures
- **Problem**: Interest updates were failing with authentication errors
- **Solution**:
  - Updated `update-interest.ts` API to accept both x-tag headers ("094ut234" and "pjnvü1230")
  - Now both authenticated and unauthenticated users can save interest updates

### 5. Email Signature Formatting
- **Problem**: Logo was appearing below the signature details
- **Solution**:
  - Moved Port Nimara logo to the top of the signature
  - Logo now appears above the name with proper spacing

### 6. Email Refresh Not Showing New Emails
- **Problem**: New emails from clients weren't appearing after refresh
- **Solution**:
  - Enhanced IMAP search to include CC and BCC fields
  - Now searches in multiple folders: INBOX, Sent, Sent Items, Sent Mail
  - Better email detection for comprehensive thread retrieval

### 7. EOI Document Generation Issues
- **Problem**: EOI documents were created but stuck in draft status with non-working links
- **Solution**:
  - Fixed response structure to match actual Documenso API response
  - Added proper document send step to move from draft to active
  - Changed `sendEmail` to `true` to ensure recipients receive signing emails
  - Correctly extract signing URLs from the response

### 8. 502 Bad Gateway on Container Restart
- **Problem**: Getting 502 errors when refreshing after container restart
- **Solution**:
  - Added better session validation in `fetch-thread` API
  - Added try-catch for decryption failures (session invalid after restart)
  - Client-side now detects 502 errors and clears invalid sessions
  - No error toast shown - just resets to empty email state

### 9. All Interest and Berth APIs Authentication Fixed
- **Problem**: APIs were only accepting one auth header, causing failures for unauthenticated users
- **Solution**: Updated ALL APIs to accept both headers ("094ut234" and "pjnvü1230"):
  - `create-interest.ts` - Create new interests
  - `update-interest.ts` - Update existing interests  
  - `delete-interest.ts` - Delete interests
  - `get-interests.ts` - List all interests
  - `get-interest-by-id.ts` - Get single interest
  - `get-berths.ts` - Get all berths
  - `get-interest-berths.ts` - Get berths linked to interest
  - `link-berths-to-interest.ts` - Link berths to interest
  - `unlink-berths-from-interest.ts` - Unlink berths from interest
  - `link-berth-recommendations-to-interest.ts` - Link berth recommendations
  - `unlink-berth-recommendations-from-interest.ts` - Unlink berth recommendations
  - Added comprehensive logging to all APIs for better debugging

### 10. EOI Status Dropdown Updated
- **Problem**: Missing "Waiting for Signatures" status option
- **Solution**:
  - Added "Waiting for Signatures" as option 2 in EOI Status
  - New order: "Awaiting Further Details" → "Waiting for Signatures" → "Signed"

### 11. 404 Errors for Existing Records During Updates - FIXED
- **Problem**: Records that exist in the database return 404 when trying to update them
- **Root Cause**: Webhook objects were being sent in the request body
- **Solution**: Now filtering out all object fields, only sending primitives

**What we've fixed:**
- Now skipping all object fields (including webhook fields) during updates
- Only sending primitive values (strings, numbers, nulls) to the API
- Removed webhook fields from the allowed fields list
- Added retry mechanism with exponential backoff
- Including `Id` field in request body to identify the record

**Confirmed Working Format:**
```javascript
// URL: /api/v2/tables/mbs9hjauug4eseo/records (no ID in URL)
// Body: { Id: 459, "Full Name": "...", "Extra Comments": "..." }
```

**Test Results:**
- ✅ PATCH with single object: `{ Id: 459, ... }` - **WORKS**
- ✅ PATCH with array: `[{ Id: 459, ... }]` - **WORKS**
- ❌ PATCH with ID in URL: `/records/459` - **404 ERROR**
- ❌ PATCH with where parameter - **404 ERROR**

**IMPORTANT: Server Restart Required**
The code is now correct, but you need to:
1. **Restart your Docker container or development server**
2. **Verify the API token in your .env file matches the working one**
3. **Try updating a record again**

The 404 errors should be resolved once the server is running with the latest code that filters out webhook objects.

## Required Environment Variables

Make sure these are set in your `.env` file:

```env
# Email Configuration
NUXT_EMAIL_ENCRYPTION_KEY=your-32-character-encryption-key
NUXT_EMAIL_IMAP_HOST=mail.portnimara.com
NUXT_EMAIL_IMAP_PORT=993
NUXT_EMAIL_SMTP_HOST=mail.portnimara.com
NUXT_EMAIL_SMTP_PORT=587
NUXT_EMAIL_LOGO_URL=https://portnimara.com/logo.png

# Documenso Configuration (REQUIRED for EOI generation)
NUXT_DOCUMENSO_API_KEY=your-actual-api-key
NUXT_DOCUMENSO_BASE_URL=https://signatures.portnimara.dev
```

### 12. EOI Management System
- **Added EOI Section Component**: New component to manage EOI document generation and signature links
- **Features Implemented**:
  - Generate EOI button that creates documents via Documenso API
  - Checks for existing EOI before generating new one (prevents duplicates)
  - Displays all 3 signature links (Client, CC, Developer) with copy-to-clipboard functionality
  - Shows EOI status badge (Awaiting Further Details, Waiting for Signatures, Signed)
  - Regenerate option for non-signed documents
- **Auto-Updates on EOI Generation**:
  - EOI Status → "Waiting for Signatures"
  - Sales Process Level → "LOI and NDA Sent"
  - EOI Time Sent → Current timestamp
  - Extra Comments → Appends "EOI Sent [timestamp]"
- **Database Storage**: Links stored in new columns:
  - `Signature Link Client`
  - `Signature Link CC`
  - `Signature Link Developer`

### 13. Auto-Save Functionality
- **Implemented**: Interest details now auto-save after 2 seconds of inactivity
- **Features**:
  - Debounced save to prevent excessive API calls
  - Silent save without success notifications
  - Automatically triggers parent refresh to keep data in sync
  - Cancels pending saves on component unmount

### 14. IMAP BCC Search Fix
- **Problem**: IMAP search was failing with "Cannot read properties of null"
- **Cause**: BCC search criteria not supported by all IMAP servers
- **Solution**: Removed BCC from search criteria, now only searches FROM, TO, and CC fields

### 15. MinIO Private Bucket Authentication Fix
- **Problem**: Email caching failed when MinIO buckets were set to private
- **Cause**: Frontend was trying to fetch presigned URLs which failed with CORS/auth issues
- **Solution**: 
  - Now reading cached emails directly on server using MinIO client
  - No presigned URLs needed - server has full authentication
  - Works perfectly with private buckets

### 16. Email Fetching & Caching Improvements
- **Optimizations**:
  - Date-based IMAP search (last 30 days) to reduce email count
  - Increased timeout from 15s to 30s
  - Now caching ALL emails (both sent and received)
  - Fire-and-forget caching to avoid slowing down email fetch
  - Proper IMAP date format (e.g., "1-Jan-2024")

### 17. Date Display Fix
- **Problem**: EOI dates showing wrong format/timezone
- **Solution**:
  - Enhanced date parsing to handle ISO dates, DD-MM-YYYY, and YYYY-MM-DD
  - Now displays in DD/MM/YYYY HH:mm format
  - Properly handles timezones

## How It Works Now

1. **Email Session Management**:
   - Sessions are stored in browser's sessionStorage
   - If no session exists, email features are gracefully disabled
   - Users can connect/disconnect at any time

2. **Email Fetching**:
   - Only attempts to fetch when valid session exists
   - Limited to 20 emails to prevent timeouts
   - Falls back to cached emails from MinIO if IMAP fails
   - 15-second timeout prevents hanging connections

3. **EOI Generation**:
   - Validates all required fields before attempting generation
   - Checks for Documenso configuration
   - Returns clear error messages if configuration is missing
   - Inserts client's signing link directly into email body

## Troubleshooting

If you're still experiencing issues:

1. **Check Docker logs**: `docker logs <container-name>`
2. **Verify environment variables are set correctly**
3. **Ensure Documenso API credentials are valid**
4. **Try disconnecting and reconnecting email credentials**