Initial commit: add .gitignore and README

TROUBLESHOOTING.md

@@ -0,0 +1,150 @@
+# Troubleshooting Guide
+
+## Authentication Issues
+
+### 403 Forbidden from CloudFront
+
+**Symptoms:**
+- All login URL attempts return 403 Forbidden
+- Error message mentions "CloudFront" or "distribution is not configured to allow the HTTP request method"
+
+**Possible Causes:**
+1. **IP Address Restrictions**: Your IP address may not be whitelisted in the Omada Cloud controller
+2. **Regional Restrictions**: The endpoint may only be accessible from certain regions
+3. **CloudFront Configuration**: CloudFront CDN may be blocking POST requests (only allows cacheable GET requests)
+4. **Endpoint Changes**: The API endpoint structure may have changed
+
+**Solutions:**
+
+1. **Verify Your IP is Whitelisted**
+   - Contact TP-Link/Omada support to whitelist your IP address
+   - Check if your organization has IP restrictions configured
+
+2. **Check Regional Access**
+   - Verify that `OMADA_CONTROLLER_BASE` matches your region
+   - EU: `https://euw1-omada-controller.tplinkcloud.com`
+   - US: `https://usw1-omada-controller.tplinkcloud.com`
+   - Asia: `https://ap1-omada-controller.tplinkcloud.com`
+
+3. **Use OAuth Instead**
+   - If password authentication is blocked, try using OAuth (Client ID/Secret)
+   - Ensure `TP_LINK_CLIENT_ID` and `TP_LINK_CLIENT_SECRET` are configured
+   - The system will automatically try OAuth first, then fall back to password
+
+4. **Contact TP-Link Support**
+   - Provide them with:
+     - Your Omada ID
+     - The exact error message
+     - Your IP address
+     - The endpoint you're trying to access
+
+### OAuth Authentication Not Working
+
+**Symptoms:**
+- OAuth Client Credentials flow fails
+- System falls back to password authentication
+
+**Solutions:**
+1. Verify OAuth credentials are correct in `.env`
+2. Check if TP-LINK Open API supports Client Credentials flow
+3. You may need to implement Authorization Code flow instead
+4. Contact TP-Link to verify OAuth endpoint and flow
+
+### Database Connection Issues
+
+**Symptoms:**
+- "Connection refused" or "Connection timeout"
+- "Database does not exist"
+
+**Solutions:**
+1. **Verify PostgreSQL is Running**
+   ```bash
+   # Check if PostgreSQL is running
+   sudo systemctl status postgresql
+   # Or with Docker
+   docker ps | grep postgres
+   ```
+
+2. **Check DATABASE_URL**
+   ```env
+   DATABASE_URL=postgresql://user:password@host:port/database?schema=public
+   ```
+   - Verify username, password, host, and port are correct
+   - Ensure the database exists
+
+3. **Test Connection**
+   ```bash
+   # Using psql
+   psql $DATABASE_URL
+   
+   # Or test with Prisma
+   pnpm run prisma:studio
+   ```
+
+### Missing Environment Variables
+
+**Symptoms:**
+- "Missing required environment variables" error on startup
+
+**Solutions:**
+1. Check `.env` file exists in project root
+2. Verify all required variables are set:
+   - `OMADA_ID`
+   - `OMADA_CONTROLLER_BASE`
+   - `OMADA_NORTHBOUND_BASE`
+   - `DATABASE_URL`
+   - `JWT_SECRET`
+   - Either OAuth credentials OR username/password
+
+3. Use setup script:
+   ```bash
+   pnpm run setup:env
+   ```
+
+## API Endpoint Issues
+
+### 404 Not Found
+
+**Symptoms:**
+- API calls return 404
+- "Route not found" errors
+
+**Solutions:**
+1. Verify the endpoint URL is correct
+2. Check if the Omada API version has changed
+3. Ensure `OMADA_NORTHBOUND_BASE` is correct
+
+### Rate Limiting
+
+**Symptoms:**
+- 429 Too Many Requests errors
+- API calls start failing after many requests
+
+**Solutions:**
+1. Implement request throttling
+2. Add delays between requests
+3. Cache responses when possible
+4. Contact TP-Link about rate limits
+
+## Getting Help
+
+1. **Check Logs**
+   - Application logs: `logs/combined.log`
+   - Error logs: `logs/error.log`
+   - Set `LOG_LEVEL=debug` for detailed logging
+
+2. **Enable Debug Mode**
+   ```env
+   LOG_LEVEL=debug
+   NODE_ENV=development
+   ```
+
+3. **Test Authentication**
+   ```bash
+   pnpm run test:auth
+   ```
+
+4. **Contact Support**
+   - TP-Link Omada Support
+   - Include error logs and configuration (redact sensitive info)
+