Merge pull request #1 from stephanwesten/claude/read-readme-011CUg1iz7CDZJZUN4o9j1pz

Claude/read readme 011 c ug1iz7 cdzjzun4o9j1pz

Author: stephanwesten

.github/workflows/deploy.yml

@@ -0,0 +1,34 @@
+name: Deploy to Cloudflare Workers
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch: # Allow manual triggering
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+        continue-on-error: true # Continue even if tests fail (for now, since we don't have tests yet)
+
+      - name: Deploy to Cloudflare Workers
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

.gitignore

@@ -0,0 +1,24 @@
+# Dependencies
+node_modules/
+
+# Wrangler
+.wrangler/
+.dev.vars
+dist/
+
+# TypeScript
+*.tsbuildinfo
+
+# Environment variables (local development only)
+.env
+.env.local
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

DEPLOYMENT.md

@@ -0,0 +1,125 @@
+# Deployment Guide
+
+## Prerequisites
+
+1. **Cloudflare Account**: Sign up at https://dash.cloudflare.com
+2. **Node.js**: v20 or higher
+3. **Wrangler CLI**: Installed via npm (included in dev dependencies)
+
+## Local Development
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure Local Environment
+
+Create a `.dev.vars` file in the project root for local development:
+
+```bash
+PERSONAL_EMAIL=your-personal@example.com
+WORK_EMAIL=your-work@example.com
+MAILCHANNELS_API_KEY=your-mailchannels-key
+PINCODE=your-secret-pincode
+FROM_EMAIL=noreply@yourdomain.com
+FROM_NAME=MailRelay
+```
+
+### 3. Run Locally
+
+```bash
+npm run dev
+```
+
+Visit `http://localhost:8787` to test locally.
+
+## Production Deployment
+
+### Option 1: GitHub Actions (Automatic)
+
+#### Setup GitHub Secrets
+
+Go to your repository Settings → Secrets and variables → Actions, and add:
+
+1. **CLOUDFLARE_API_TOKEN**
+   - Go to https://dash.cloudflare.com/profile/api-tokens
+   - Create token with "Edit Cloudflare Workers" permissions
+   - Copy and paste into GitHub secret
+
+2. **CLOUDFLARE_ACCOUNT_ID**
+   - Find at https://dash.cloudflare.com
+   - Look in the URL or Workers & Pages section
+   - Copy your Account ID
+
+#### Configure Worker Secrets
+
+Set environment variables in Cloudflare:
+
+```bash
+# Using Wrangler CLI locally
+wrangler secret put PERSONAL_EMAIL
+wrangler secret put WORK_EMAIL
+wrangler secret put MAILCHANNELS_API_KEY
+wrangler secret put PINCODE
+wrangler secret put FROM_EMAIL
+wrangler secret put FROM_NAME
+```
+
+Or set them in the Cloudflare Dashboard:
+- Go to Workers & Pages → mailrelay → Settings → Variables
+- Add each secret
+
+#### Deploy
+
+Push to `main` branch:
+
+```bash
+git push origin main
+```
+
+GitHub Actions will automatically deploy to Cloudflare Workers.
+
+### Option 2: Manual Deployment
+
+```bash
+# Build and deploy
+npm run deploy
+```
+
+## MailChannels Setup
+
+MailRelay uses MailChannels for email delivery. You need:
+
+1. **Domain with SPF/DKIM configured** for MailChannels
+2. **MailChannels API access** (free for Cloudflare Workers users)
+
+See: https://blog.cloudflare.com/sending-email-from-workers-with-mailchannels/
+
+## Verification
+
+After deployment:
+
+1. Visit your worker URL (e.g., `https://mailrelay.<your-subdomain>.workers.dev`)
+2. You should see "Deployment Test Successful"
+3. Test sending an email through the form
+
+## Troubleshooting
+
+### Deployment fails
+
+- Check GitHub Actions logs
+- Verify CLOUDFLARE_API_TOKEN has correct permissions
+- Verify CLOUDFLARE_ACCOUNT_ID is correct
+
+### Worker runs but emails don't send
+
+- Check MailChannels API key is set correctly
+- Verify domain SPF/DKIM records
+- Check worker logs in Cloudflare Dashboard
+
+### Local development issues
+
+- Ensure `.dev.vars` file exists with all required variables
+- Run `wrangler login` if authentication fails

README.md

@@ -14,16 +14,17 @@ MailRelay is an email relay service built on Cloudflare Workers using MailChanne
 
 ### 1. Web Form Interface
 
+- **Pincode Authentication**: Optional URL parameter (`?pincode=xxx`) for bookmarking. If not provided, displays pincode input field
 - **Address Toggle**: Switch between personal and work email addresses
-- **Subject Field**: Text input for email subject line
+- **Subject Field**: Text input for email subject line (required)
 - **Message Field**: Textarea for email body/description
 - **Submit Button**: Send email via form submission
 - **Success/Error Feedback**: Visual confirmation of email delivery status
 
 ### 2. REST API
 
 - **POST Endpoint**: `/api/send` for programmatic email sending
-- **Authentication**: API key/token for secure access
+- **Authentication**: Pincode in request body for simple authentication
 - **JSON Payload**: Accepts structured email data
 - **Response Codes**: Standard HTTP status codes with error messages
 
@@ -54,9 +55,9 @@ MailRelay is an email relay service built on Cloudflare Workers using MailChanne
 PERSONAL_EMAIL=your-personal@example.com
 WORK_EMAIL=your-work@example.com
 MAILCHANNELS_API_KEY=xxx
-API_AUTH_TOKEN=xxx (for API endpoint security)
+PINCODE=your-secret-pincode
 FROM_EMAIL=noreply@yourdomain.com
-FROM_NAME=MailRally
+FROM_NAME=MailRelay
 ```
 
 -----
@@ -68,14 +69,14 @@ FROM_NAME=MailRally
 **Headers:**
 
 ```
-Authorization: Bearer {API_AUTH_TOKEN}
 Content-Type: application/json
 ```
 
 **Request Body:**
 
 ```json
 {
+  "pincode": "string",
   "destination": "personal" | "work",
   "subject": "string",
   "message": "string"
@@ -88,7 +89,9 @@ Content-Type: application/json
 {
   "success": true,
   "message": "Email sent successfully",
-  "destination": "personal"
+  "data": {
+    "destination": "personal"
+  }
 }
 ```
 
@@ -97,10 +100,18 @@ Content-Type: application/json
 ```json
 {
   "success": false,
-  "error": "Error message description"
+  "message": "Error message description",
+  "data": null
 }
 ```
 
+**Consistent Structure Benefits:**
+
+- Client only needs to check `success` boolean
+- `message` always contains human-readable feedback
+- `data` contains payload (object on success, null on error)
+- Same parsing logic for all responses
+
 -----
 
 ## User Interface Design
@@ -112,6 +123,9 @@ Content-Type: application/json
 │          MailRelay 📧               │
 ├─────────────────────────────────────┤
 │                                     │
+│  Pincode:  [________________]       │
+│            (hidden if in URL)       │
+│                                     │
 │  Send To:  ( ) Personal  ( ) Work   │
 │                                     │
 │  Subject:  [________________]       │
@@ -127,17 +141,22 @@ Content-Type: application/json
 └─────────────────────────────────────┘
 ```
 
+**Pincode URL Parameter**: Users can bookmark `/?pincode=xxx` to skip entering pincode each time.
+
 Error feedback is crucial. log all information and print all information except for sensitive information like keys to make debugging easier. 
 In the API return in the response an error message with as much information as possible. 
 -----
 
 ## Security Considerations
 
-- API authentication via Bearer token
-- Rate limiting to prevent abuse
-- Input validation and sanitization
-- CORS configuration for API access
-- Environment variables for sensitive data (never in code)
+- **Simple Pincode Authentication**: Pincode compared against `PINCODE` environment variable
+  - Can be passed as URL parameter `?pincode=xxx` for web form bookmarking
+  - Required in API request body
+  - Not highly secure, but sufficient for personal use MVP
+- **Input Validation**: Validate and sanitize all user inputs
+- **CORS Configuration**: Configure appropriate CORS headers for API access
+- **Environment Variables**: Store all sensitive data (emails, pincode, API keys) in environment variables, never in code
+- **No Rate Limiting**: Intentionally omitted for MVP simplicity (add later if needed)
 
 -----
 
@@ -169,9 +188,8 @@ In the API return in the response an error message with as much information as p
 
 **Questions to finalize:**
 
-1. Do you want TypeScript or JavaScript?  depends, typescript requires compilation, but is type safe. depends on github actions. 
-1. Any specific styling preferences (minimal, modern, colorful)? minimal but modern. 
-1. Should the form have validation (required fields, max length)?  Title is required. 
+1. Do you want TypeScript or JavaScript?  depends, typescript requires compilation, but is type safe. depends on github actions.
+1. Any specific styling preferences (minimal, modern, colorful)? minimal but modern.
+1. Should the form have validation (required fields, max length)?  Subject is required.
 1. Do you want email confirmation/receipts? no
-1. Rate limiting: how many emails per hour/day? 5
 

claude.md

@@ -0,0 +1,79 @@
+# Development Guidelines for MailRelay
+
+## Development Methodology
+
+This project follows **Test-Driven Development (TDD)** and **Extreme Programming (XP)** practices.
+
+### Test-Driven Development (TDD)
+
+Follow the Red-Green-Refactor cycle:
+
+1. **Red**: Write a failing test first
+2. **Green**: Write minimal code to make the test pass
+3. **Refactor**: Improve code while keeping tests green
+
+#### TDD Principles
+
+- Write tests before implementation code
+- Tests should be small, focused, and fast
+- Each test should verify one behavior
+- All code must have corresponding tests
+- Run tests frequently during development
+
+### Extreme Programming (XP) Practices
+
+#### Core Practices
+
+- **Simple Design**: Implement the simplest solution that works
+- **Refactoring**: Continuously improve code structure
+- **Continuous Integration**: Integrate and test code frequently
+- **Small Releases**: Deploy small, incremental changes
+- **Collective Code Ownership**: Any developer can improve any part of the code
+
+#### Coding Standards
+
+- Write clear, self-documenting code
+- Follow consistent naming conventions
+- Keep functions small and focused
+- DRY (Don't Repeat Yourself)
+- YAGNI (You Aren't Gonna Need It) - don't add functionality until needed
+
+### Testing Strategy
+
+#### Unit Tests
+
+- Test individual functions and modules in isolation
+- Mock external dependencies (MailChannels API, environment variables)
+- Fast execution (milliseconds)
+
+#### Integration Tests
+
+- Test API endpoints end-to-end
+- Test web form submission flow
+- Verify error handling and edge cases
+
+#### Test Coverage Goals
+
+- Aim for >80% code coverage
+- 100% coverage for critical paths (email sending, authentication)
+- All error handlers must be tested
+
+### Development Workflow
+
+1. Create a failing test for new feature/bugfix
+2. Write minimal code to pass the test
+3. Refactor if needed
+4. Run full test suite
+5. Commit with descriptive message
+6. Push and deploy via CI/CD
+
+### Tools
+
+- **Testing Framework**: Vitest (or Jest)
+- **Mocking**: Built-in test framework mocks
+- **CI/CD**: GitHub Actions
+- **Code Quality**: ESLint, Prettier
+
+---
+
+**Remember**: If it's not tested, it's broken.