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:

{
  // ... 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

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:

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.)