TheFlow 2298d36bed fix(submissions): restructure Economist package and fix article display

- Create Economist SubmissionTracking package correctly:
  * mainArticle = full blog post content
  * coverLetter = 216-word SIR— letter
  * Links to blog post via blogPostId
- Archive 'Letter to The Economist' from blog posts (it's the cover letter)
- Fix date display on article cards (use published_at)
- Target publication already displaying via blue badge

Database changes:
- Make blogPostId optional in SubmissionTracking model
- Economist package ID: 68fa85ae49d4900e7f2ecd83
- Le Monde package ID: 68fa2abd2e6acd5691932150

Next: Enhanced modal with tabs, validation, export

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-24 08:47:42 +13:00

4.9 KiB

Raw Blame History

Stripe Customer Portal Setup Guide

Overview

The Stripe Customer Portal allows donors to self-service manage their subscriptions without contacting support. This includes:

Viewing subscription details and invoices
Updating payment methods
Cancelling subscriptions
Viewing payment history

Implementation Status

✅ Backend endpoint created: POST /api/koha/portal ✅ Frontend UI added to koha.html ✅ i18n translations added ✅ Route configured in koha.routes.js

⚠️ REQUIRED: Configure Customer Portal in Stripe Dashboard (both test and live mode)

Step 1: Configure Test Mode Portal

Go to: https://dashboard.stripe.com/test/settings/billing/portal
Click "Activate test mode" or "Configure"
Enable the following features:

Customer Information

✅ Email address: Allow customers to edit
✅ Payment methods: Allow customers to update

Subscriptions

✅ Allow customers to cancel subscriptions: Yes
Cancellation behavior: Cancel at period end (recommended)
✅ Cancellation survey: Enable with custom questions:
- "Why are you cancelling?" (required)
  - Too expensive
  - No longer need it
  - Found an alternative
  - Not what I expected
  - Other (with text input)
- "How can we improve?" (optional, text input)

Invoice History

✅ Show invoice history: Yes

Business Information

Business name: Tractatus AI Safety Framework
Support email: support@agenticgovernance.digital
Privacy policy URL: https://agenticgovernance.digital/about/values.html
Terms of service URL: https://agenticgovernance.digital/about/values.html

Click "Save changes"

Step 2: Configure Live Mode Portal

Switch to Live mode in Stripe Dashboard (toggle in top-right)
Go to: https://dashboard.stripe.com/settings/billing/portal
Repeat exact same configuration as test mode above
Click "Save changes"

Step 3: Test the Portal (Test Mode)

Open http://localhost:9000/koha.html in your browser
Scroll to the "Manage Your Subscription" section
Enter the email address of a test subscription (e.g., the one you created during testing)
Click "Manage"
You should be redirected to the Stripe Customer Portal
Verify:
- Subscription details are visible
- Payment method can be updated
- Cancellation option is available
- Cancellation survey appears when attempting to cancel

Step 4: Deploy to Production

Once test mode is configured and working:

Configure live mode (Step 2 above)
Deploy updated files:
```
./scripts/deploy-full-project-SAFE.sh
```
Files being deployed:
- src/controllers/koha.controller.js (new createPortalSession endpoint)
- src/routes/koha.routes.js (new /portal route)
- public/koha.html (new Manage Subscription section)
- public/js/koha-donation.js (new portal functionality)
- public/locales/en/koha.json (new translations)
Verify production:
- Go to https://agenticgovernance.digital/koha.html
- Test "Manage Subscription" with your live subscription email
- Confirm portal redirect works
- Test cancellation flow (you can cancel the test $5 subscription if desired)

Exit Survey Data Access

After customers cancel subscriptions, you can view their survey responses:

Go to Stripe Dashboard → Billing → Subscriptions
Click on a cancelled subscription
Look for "Cancellation feedback" section
Survey responses will be displayed there

This data helps you understand churn reasons and improve the donation experience.

Security Notes

✅ Email verification: The portal endpoint only accepts email addresses that match Stripe customer records
✅ Rate limiting: Portal endpoint is protected by rate limiter (10 requests/hour per IP)
✅ No authentication required: This is intentional - Stripe Customer Portal has its own secure authentication via email
✅ Session expiration: Portal sessions expire after 30 minutes

Troubleshooting

Error: "No subscription found for this email address"

The email doesn't have an active Stripe subscription
Check that the email matches exactly (case-insensitive)
Verify the subscription exists in Stripe Dashboard

Error: "No configuration provided..."

Customer Portal not configured in Stripe Dashboard
Follow Step 1 (test) or Step 2 (live) above

Portal session created but redirect fails

Check browser console for errors
Verify FRONTEND_URL in .env is correct
Check that koha-donation.js has window.location.href = data.data.url;

Next Steps

✅ Configure test mode portal (Step 1)
✅ Test locally (Step 3)
✅ Configure live mode portal (Step 2)
✅ Deploy to production (Step 4)
🎉 Donors can now self-manage their subscriptions!

Last Updated: 2025-10-18 Status: Ready for configuration and deployment

4.9 KiB Raw Blame History