freealberta/influence/RESPONSE_WALL_UPDATES.md

# Response Wall Feature Updates

## Overview
Updated the Response Wall submission modal to include two new features:
1. **Postal Code Lookup** - Auto-fill representative details by searching postal codes
2. **Response Verification** - Option to send verification email to representatives

## Frontend Changes Completed

### 1. HTML Updates (`response-wall.html`)
- Added postal code search input field with search button
- Added representative selection dropdown (hidden by default, shows after search)
- Added hidden field for storing representative email
- Added "Send verification request" checkbox option
- Included `api-client.js` script dependency

### 2. JavaScript Updates (`response-wall.js`)
- Added `loadedRepresentatives` array to store search results
- Implemented `formatPostalCodeInput()` - formats postal code as "A1A 1A1"
- Implemented `validatePostalCode()` - validates Canadian (Alberta) postal codes
- Implemented `handlePostalLookup()` - fetches representatives from API
- Implemented `displayRepresentativeOptions()` - populates dropdown with results
- Implemented `handleRepresentativeSelect()` - auto-fills form when rep selected
- Implemented `determineGovernmentLevel()` - maps office type to government level
- Updated `handleSubmitResponse()` - includes verification flag and rep email
- Updated `closeSubmitModal()` - resets postal lookup fields

### 3. CSS Updates (`response-wall.css`)
- Added `.postal-lookup-container` styles for search UI
- Added `#rep-select` and `#rep-select-group` styles for dropdown
- Added checkbox styling improvements
- Added disabled state styling for verification checkbox

## Backend Implementation - ✅ COMPLETED

### 1. API Endpoint Updates - ✅ COMPLETED

#### Update: `POST /api/campaigns/:slug/responses` - ✅ COMPLETED
The endpoint now handles new fields:

**New Request Fields:**
```javascript
{
  // ... existing fields ...
  representative_email: String,     // Email address of the representative
  send_verification: Boolean        // Whether to send verification email
}
```

**Implementation Requirements:**
1. Accept and validate `representative_email` field
2. Accept `send_verification` boolean flag
3. When `send_verification === true` AND `representative_email` is present:
   - Generate a unique verification token
   - Store token with the response record
   - Send verification email to representative

### 2. Database Schema Updates - ✅ COMPLETED

**responses table additions:** ✅ Implemented in `scripts/build-nocodb.sh`
- `representative_email` - Email field for storing rep email
- `verification_token` - SingleLineText for unique verification token
- `verification_sent_at` - DateTime for tracking when email was sent
- `verified_at` - DateTime for tracking verification timestamp
- `verified_by` - SingleLineText for tracking who verified

### 3. Verification Email Template - ✅ COMPLETED

Created email templates in `app/templates/email/`:

**Subject:** "Verification Request: Response Submission on BNKops Influence"

**Body:**
```
Dear [Representative Name],

A constituent has submitted a response they received from you on the BNKops Influence platform.

Campaign: [Campaign Name]
Response Type: [Email/Letter/etc.]
Submitted: [Date]

To verify this response is authentic, please click the link below:
[Verification Link]

If you did not send this response, please click here to report it:
[Report Link]

This helps maintain transparency and accountability in constituent communications.

Best regards,
BNKops Influence Team
```

### 4. Verification Endpoints (New) - ✅ COMPLETED

#### `GET /api/responses/:id/verify/:token` - ✅ COMPLETED
Implemented in `app/controllers/responses.js`:
- Verifies response using unique token
- Updates `verified_at` timestamp
- Marks response as verified (`is_verified: true`)
- Auto-approves response (`status: 'approved'`)
- Returns styled HTML success page

#### `GET /api/responses/:id/report/:token` - ✅ COMPLETED
Implemented in `app/controllers/responses.js`:
- Marks response as disputed by representative
- Updates response status to 'rejected'
- Sets `is_verified: false`
- Hides from public view (rejected status)
- Returns styled HTML confirmation page

### 5. Email Service Integration - ✅ COMPLETED

Updated email service with verification support:

**File:** `app/services/email.js`

```javascript
async function sendVerificationEmail(responseId, representativeEmail, representativeName, verificationToken) {
  const verificationUrl = `${process.env.BASE_URL}/api/responses/${responseId}/verify/${verificationToken}`;
  const reportUrl = `${process.env.BASE_URL}/api/responses/${responseId}/report/${verificationToken}`;
  
  // Send email using your email service
  // Include verification and report links
}
```

### 6. Environment Variables - ✅ COMPLETED

Added to `example.env`:
```env
APP_NAME="BNKops Influence"
BASE_URL=http://localhost:3333
```

**Note:** Update your `.env` file with these values for production deployment.

## User Flow

### Submitting with Verification
1. User clicks "Share a Response"
2. User enters postal code and clicks search
3. System fetches representatives from Represent API
4. User selects their representative from dropdown
5. Form auto-fills: name, title, level, email (hidden)
6. User completes response details
7. User checks "Send verification request"
8. User submits form
9. **Backend**: Response saved as pending/unverified
10. **Backend**: Verification email sent to representative
11. User sees success message

### Representative Verification
1. Representative receives email
2. Clicks verification link
3. Redirects to verification endpoint
4. Response marked as verified
5. Response becomes visible with "Verified" badge

## Testing Checklist

### Frontend Testing
- [ ] Postal code search works with valid Alberta codes
- [ ] Validation rejects non-Alberta codes
- [ ] Representative dropdown populates correctly
- [ ] Selecting a rep auto-fills form fields
- [ ] Verification checkbox is disabled when no email
- [ ] Verification checkbox is enabled when rep has email
- [ ] Form submits successfully with verification flag
- [ ] Manual entry still works without postal lookup
- [ ] Modal resets properly when closed

### Backend Testing
- [ ] Backend receives verification parameters correctly
- [ ] Verification token is generated and stored
- [ ] Verification email is sent when opted in
- [ ] Email contains correct verification and report URLs
- [ ] Verification endpoint validates token correctly
- [ ] Verification endpoint updates database correctly
- [ ] Report endpoint marks response as disputed
- [ ] Styled HTML pages display correctly on verify/report
- [ ] Security: Invalid tokens are rejected
- [ ] Security: Already verified responses show appropriate message

## Security Considerations

1. **Token Security**: Use cryptographically secure random tokens
2. **Token Expiry**: Verification tokens should expire (e.g., 30 days)
3. **Rate Limiting**: Limit verification emails per IP/session
4. **Email Validation**: Validate representative email format
5. **XSS Prevention**: Sanitize all form inputs on backend
6. **CSRF Protection**: Ensure CSRF tokens on form submission

## Future Enhancements

1. Add notification when representative verifies
2. Show verification status prominently on response cards
3. Add statistics: "X% of responses verified"
4. Allow representatives to add comments during verification
5. Add representative dashboard to manage verifications
6. Support for multiple verification methods (SMS, etc.)