agmission/Development/server/README.md

# AgMission Server

📚 **[Documentation Index](docs/DOCUMENTATION_INDEX.md)** | 🔄 **[Partner Integration](README_PARTNER_INTEGRATION.md)** | 📝 **[DLQ System](docs/DLQ_INDEX.md)**

## Quick Links
- [Partner Integration Guide](./README_PARTNER_INTEGRATION.md) - Complete guide for partner system integration
- [DLQ Documentation](./docs/DLQ_INDEX.md) - Dead Letter Queue management (all queues)
- [DLQ Quick Start](./docs/DLQ_QUICKSTART.md) - Get started with DLQ in 5 minutes
- [Payment Failure Handling](./docs/PAYMENT_FAILURE_HANDLING.md) - **CRITICAL**: Billing security and failed payment handling
- [Payment Failure Fix Summary](./docs/PAYMENT_FAILURE_FIX_SUMMARY.md) - Recent fix documentation and testing guide
- [API Documentation](./docs/API_SPECIFICATION.md) - RESTful API reference
- [Architecture Overview](./docs/ARCHITECTURE_SUMMARY.md) - System architecture documentation

## Environment keys
| Syntax            | Description                        |
| ----------------- | ---------------------------------  |
| AGM_PORT          | BackEnd endpoint port              |
| PRODUCTION        | Whether runnung in production mode |
| DEBUG             | debug pattern. E.g:                |
| AGM_PORT          | BackEnd endpoint port DEBUG=agm:*  |
| STRIPE_SECRET_KEY | Stripe secret key                  |
| STRIPE_PUBLISHABLE_KEY | Stripe publishable key        |
| STRIPE_API_VERSION | Stripe API Version                |
| STRIPE_WH_SEC      | Stripe Webhooks Endpoint secret   |
| [Package]_[Number]| Stripe package in uppercased 3-first character and number. E.g: ESS_1 for essential package 1 |

## Partner Integration Environment Keys
| Syntax            | Description                        |
| ----------------- | ---------------------------------  |
| SATLOC_API_ENDPOINT | SatLoc API base URL               |
| SATLOC_API_TIMEOUT | Request timeout in milliseconds   |
| SATLOC_RETRY_ATTEMPTS | Number of API retry attempts    |
| SATLOC_RATE_LIMIT | API requests per second limit      |
| PARTNER_SYNC_INTERVAL | Partner data sync interval (ms) |
| PARTNER_HEALTH_CHECK_INTERVAL | Health check interval (ms) |
| PARTNER_MAX_CONCURRENT_JOBS | Max concurrent partner jobs |
| PARTNER_ENCRYPT_CREDENTIALS | Whether to encrypt partner credentials |
| QUEUE_NAME_PARTNER | Partner task queue name (auto-prefixes with 'dev_' in development, defaults to 'partner_tasks' in production) |
| PARTNER_MAX_RETRIES | Maximum retry attempts before DLQ (default: 5) |
| DLQ_CHECK_INTERVAL | DLQ monitoring interval (default: 5 min) |

*Note: Partner authentication now uses customer-specific credentials stored in PartnerSystemUser records, not global environment variables.*

*For complete partner integration setup, see [README_PARTNER_INTEGRATION.md](./README_PARTNER_INTEGRATION.md)*

## Debug Stripe Webhook

### Prerequisites
1. Install Stripe CLI: https://stripe.com/docs/stripe-cli
2. Make sure your server is running locally
3. Have your Stripe account credentials ready

### Setup Steps

1. **Login to Stripe CLI**
   ```bash
   stripe login
   ```

2. **Forward webhook events to your local server**
   ```bash
   # Forward to local development server (default port 3000)
   stripe listen --forward-to https://localhost:4100/stripe_webhooks --skip-verify
   
   # Or specify custom port if your AGM_PORT is different
   stripe listen --forward-to localhost:YOUR_AGM_PORT/webhook/stripe
   ```

3. **Get the webhook signing secret**
   When you run the `stripe listen` command, it will output a webhook signing secret like:
   ```
   > Ready! Your webhook signing secret is whsec_1234567890abcdef...
   ```

4. **Update your environment variables**
   Add or update the webhook secret in your `.env` file:
   ```bash
   STRIPE_WH_SEC=whsec_1234567890abcdef...
   ```

5. **Enable debug logging**
   Set the DEBUG environment variable to see webhook processing logs:
   ```bash
   DEBUG=agm:* npm start
   # Or specifically for webhook debugging:
   DEBUG=agm:webhook,agm:stripe npm start
   ```

### Testing Webhook Events

1. **Trigger test events from Stripe CLI**
   ```bash
   # Test subscription created event
   stripe trigger invoice.payment_succeeded
   
   # Test subscription updated event
   stripe trigger customer.subscription.updated
   
   # Test payment failed event
   stripe trigger invoice.payment_failed
   
   # Test subscription cancelled event
   stripe trigger customer.subscription.deleted
   ```

2. **Create test events from Stripe Dashboard**
   - Go to your Stripe Dashboard
   - Navigate to Developers > Webhooks
   - Click "Send test webhook"
   - Select the event type you want to test

### Debug Output

When debugging is enabled, you should see output like:
```
agm:webhook Received Stripe webhook: invoice.payment_succeeded
agm:stripe Processing subscription payment for customer: cus_...
agm:db -> MongoDB connected - Main Application ready
```

### Common Issues

1. **Webhook signature verification failed**
   - Make sure `STRIPE_WH_SEC` matches the secret from `stripe listen`
   - Ensure the webhook endpoint path is correct (`/webhook/stripe`)

2. **Connection refused**
   - Verify your server is running on the correct port
   - Check that the `--forward-to` URL matches your server address

3. **No webhook events received**
   - Confirm `stripe listen` is still running
   - Check that events are being sent to the correct endpoint
   - Verify your webhook endpoint is accessible

### Production Webhook Setup

For production, configure webhooks directly in your Stripe Dashboard:
1. Go to Developers > Webhooks
2. Click "Add endpoint"
3. Set endpoint URL: `https://yourdomain.com/webhook/stripe`
4. Select events to listen for
5. Copy the signing secret to your production `STRIPE_WH_SEC` environment variable

## DLQ (Dead Letter Queue) Monitoring

The DLQ system provides **global queue-native operations** for managing failed tasks across **all queue types**.

### Documentation

Complete DLQ documentation: **[docs/DLQ_INDEX.md](./docs/DLQ_INDEX.md)**

Quick links:
- [Quick Start Guide](./docs/DLQ_QUICKSTART.md) - Get started in 5 minutes
- [API Reference](./docs/DLQ_API_REFERENCE.md) - Complete API documentation
- [Operations Guide](./docs/DLQ_OPERATIONS.md) - Advanced operations

### Web Dashboard

```
http://localhost:4100/dlq-monitor.html
```

Features:
- Real-time DLQ statistics for all queues
- View failed messages with error details
- One-click retry operations
- Queue selection dropdown
- Auto-refresh every 30 seconds

### Quick API Examples

**View DLQ Messages:**
```bash
curl http://localhost:4100/api/dlq/partner_tasks/messages?limit=20 \
  -H "Authorization: Bearer $TOKEN"
```

**Retry All Messages:**
```bash
curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryAll \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxMessages": 50}'
```

**Multiple Queue Support:**
```bash
# Partner queue
POST /api/dlq/partner_tasks/retryAll

# Job queue
POST /api/dlq/dev_jobs/retryAll

# Future queues (no code changes needed!)
POST /api/dlq/notifications/retryAll
```

### API Endpoints

Global DLQ endpoints (work for ANY queue):

- `GET /api/dlq/:queueName/messages` - View DLQ messages
- `GET /api/dlq/:queueName/stats` - Get DLQ statistics
- `POST /api/dlq/:queueName/retryAll` - Retry all messages
- `POST /api/dlq/:queueName/retryByPosition` - Retry by position range
- `POST /api/dlq/:queueName/retryByHeader` - Retry by header match
- `DELETE /api/dlq/:queueName/purge` - Purge queue ⚠️

For complete API documentation, see [docs/DLQ_API_REFERENCE.md](./docs/DLQ_API_REFERENCE.md)


### Automated Processing

**Use the web dashboard** at `http://localhost:4100/dlq-monitor.html` or API endpoints:

```bash
# Retry all DLQ messages
curl -X POST http://localhost:4100/api/dlq/partner_tasks/retryAll \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxMessages": 100}'
```