# Environment Variables Configuration

This document describes the environment variables used in this project.

## PDF Upload Configuration

Add these to your `.env` file to customize PDF upload limits:

```env
# Maximum PDF file size in megabytes (default: 150)
MAX_PDF_SIZE_MB=150

# Memory limit for upload operations in megabytes (default: 512)
UPLOAD_MEMORY_LIMIT_MB=512

# Maximum execution time for upload operations in seconds (default: 300)
UPLOAD_MAX_EXECUTION_TIME=300

# Default PDF quality preset: low, medium, or high (default: medium)
# - low: scale 1.2, multiplier 1.5 (~20-30MB files)
# - medium: scale 1.5, multiplier 2.0 (~40-60MB files)
# - high: scale 1.8, multiplier 2.5 (~70-90MB files)
PDF_DEFAULT_QUALITY=medium
```

## WhatsApp Server Authentication

**IMPORTANT**: You must set this token for security!

```env
# Authentication token for WhatsApp WebSocket server
# Generate a secure random token: openssl rand -base64 32
WHATSAPP_AUTH_TOKEN=your-secure-random-token-here

# Optional footer automatically appended to every WhatsApp message
# Leave blank to disable globally. Individual admins can switch the footer on/off or override the content from the settings page.
WHATSAPP_MESSAGE_FOOTER="Looking forward to celebrating with you!"
```

## Email OTP Verification

The OTP code is now delivered exclusively over email. You can still fine-tune its behaviour via the same environment variables:

```env
# OTP behaviour tuning (all optional)
OTP_EXPIRY_MINUTES=10
OTP_MAX_ATTEMPTS=5
OTP_RESEND_COOLDOWN_SECONDS=60
```

## Email Verification Hardening

Block disposable inboxes before OTP delivery and, optionally, require routable MX records:

```env
# Enable DNS lookups for MX records (default: false)
EMAIL_REQUIRE_MX=true

# Extend the default disposable domain blocklist (comma-separated)
EMAIL_BLOCKED_DOMAINS=mailinator.com,yopmail.com,example.net
```

### How to Generate a Secure Token

On Linux/Mac:
```bash
openssl rand -base64 32
```

On Windows (PowerShell):
```powershell
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))
```

### Using the Token

When connecting to WhatsApp server endpoints, include the token:

**Socket.IO Connection:**
```javascript
const socket = io('http://localhost:3000', {
    query: { sessionId: 'user-123', token: 'your-token-here' }
});
```

**REST API Calls:**
```javascript
fetch('http://localhost:3000/send-message/user-123', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer your-token-here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ ... })
});
```

## Server Configuration

Ensure your PHP configuration files also match these limits:

### .user.ini (PHP-FPM)
```ini
upload_max_filesize = 150M
post_max_size = 150M
memory_limit = 512M
max_execution_time = 300
```

### .htaccess (Apache mod_php)
```apache
php_value upload_max_filesize 150M
php_value post_max_size 150M
php_value memory_limit 512M
```

### nginx + PHP-FPM
```nginx
client_max_body_size 150M;
```

## Deployment Checklist

- [ ] Set `MAX_PDF_SIZE_MB` in `.env`
- [ ] Set `WHATSAPP_AUTH_TOKEN` in `.env` with a secure random token
- [ ] Update PHP configuration files (php.ini or .user.ini)
- [ ] Update web server configuration (Apache .htaccess or nginx.conf)
- [ ] Restart PHP-FPM service: `sudo systemctl restart php8.x-fpm`
- [ ] Restart web server: `sudo systemctl restart apache2` or `nginx`
- [ ] Test large PDF upload (close to 150MB) to verify configuration
- [ ] Update WhatsApp server clients to include authentication token

## Troubleshooting

### PDF uploads fail with "Request Entity Too Large"

1. Check `post_max_size` in php.ini is >= 150M
2. Check `upload_max_filesize` in php.ini is >= 150M
3. Check web server limits (nginx `client_max_body_size`)
4. Restart PHP-FPM and web server after changes

### WhatsApp server returns 401 Unauthorized

1. Verify `WHATSAPP_AUTH_TOKEN` is set in `.env`
2. Ensure client is sending the token in `Authorization` header or query param
3. Check token matches exactly (no extra spaces/newlines)

### Memory limit errors

1. Increase `UPLOAD_MEMORY_LIMIT_MB` in `.env`
2. Update `memory_limit` in php.ini to match
3. Consider reducing PDF quality preset to `medium` or `low`

## Additional Resources

- Laravel Configuration: https://laravel.com/docs/configuration
- PHP Configuration: https://www.php.net/manual/en/ini.core.php
- Socket.IO Authentication: https://socket.io/docs/v4/middlewares/


