Hi ${user.name}, your account is ready.
Sign in and create your first order. Your starter zones for ${company.country} are already set up.
`), }; } function credentialsEmail({ company, manager, tempPassword }) { return { subject: `Your Shiprex Lite account for ${company.name}`, html: wrap('Your Shiprex Lite account', `Hi ${manager.name}, an account was created for you.
Email: ${manager.email}
Temporary password: ${tempPassword}
Please sign in and change it. Open Shiprex Lite
`), }; } function salesNotifyEmail({ lead }) { return { subject: `New ${lead.kind} lead: ${lead.name}`, html: wrap('New lead', `Kind: ${lead.kind}
Name: ${lead.name}
Email: ${lead.email}
Phone: ${lead.phone || '-'}
Company: ${lead.company || '-'}
Message: ${lead.message || '-'}
`), }; } module.exports = { welcomeEmail, credentialsEmail, salesNotifyEmail }; ``` ### Step 3 — Event listeners (wire email to events) Create **`server/src/listeners/emailListeners.js`**: ```js const { bus, EVENTS } = require('../lib/events'); const { sendTransactional, upsertContact } = require('../services/email/brevo'); const { welcomeEmail, credentialsEmail } = require('../services/email/templates'); const { env } = require('../config/env'); function register() { bus.on(EVENTS.USER_REGISTERED, async ({ user, company }) => { const { subject, html } = welcomeEmail({ company, user }); await sendTransactional({ to: user.email, toName: user.name, subject, html }); const listIds = env.brevo.contactListId ? [Number(env.brevo.contactListId)] : []; await upsertContact({ email: user.email, attributes: { COMPANY: company.name, COUNTRY: company.country, PLAN: company.plan }, listIds }); }); bus.on(EVENTS.COMPANY_CREATED, async ({ company, manager, tempPassword }) => { const { subject, html } = credentialsEmail({ company, manager, tempPassword }); await sendTransactional({ to: manager.email, toName: manager.name, subject, html }); }); } module.exports = { register }; ``` Listeners are `async` and call fail-soft functions, so they never throw into the emitter. ### Step 4 — Register listeners at startup In **`server/src/app.js`**, inside `createApp()` **before** mounting routes, add: ```js require('./listeners/emailListeners').register(); ``` (Require once; `register()` attaches the bus handlers.) ### Step 5 — `leads` table migration ```bash npm --workspace server run migrate:make leads ``` Open the new file under `server/src/db/migrations/` and fill: ```js exports.up = async (knex) => { await knex.schema.createTable('leads', (t) => { t.increments('id').primary(); t.string('kind', 32).notNullable(); // callback | sales | upgrade t.string('name', 191).notNullable(); t.string('email', 191).notNullable(); t.string('phone', 64).nullable(); t.string('company', 191).nullable(); t.text('message').nullable(); t.integer('company_id').unsigned().nullable() .references('id').inTable('companies').onDelete('SET NULL'); // set if submitted while logged in t.string('ip', 64).nullable(); t.timestamp('created_at').notNullable().defaultTo(knex.fn.now()); t.index(['kind']); }); }; exports.down = async (knex) => { await knex.schema.dropTableIfExists('leads'); }; ``` Run it: ```bash npm run migrate ``` ### Step 6 — Leads module (endpoint) Create **`server/src/modules/leads/leads.routes.js`**: ```js const express = require('express'); const { z } = require('zod'); const db = require('../../db/knex'); const { asyncHandler } = require('../../middleware/error'); const { rateLimit } = require('../../middleware/rateLimit'); // from PRP-006 const { sendTransactional, upsertContact } = require('../../services/email/brevo'); const { salesNotifyEmail } = require('../../services/email/templates'); const { env } = require('../../config/env'); const { ok } = require('../../utils/response'); const router = express.Router(); const leadSchema = z.object({ name: z.string().min(2).max(191), email: z.string().email().max(191), phone: z.string().max(64).optional(), company: z.string().max(191).optional(), message: z.string().max(2000).optional(), kind: z.enum(['callback', 'sales', 'upgrade']), website: z.string().max(0).optional(), // honeypot: must be empty/absent }); router.post('/', rateLimit({ max: 10, key: 'leads' }), asyncHandler(async (req, res) => { const data = leadSchema.parse(req.body); if (data.website) return ok(res, { received: true }); // silently drop bots const [id] = await db('leads').insert({ kind: data.kind, name: data.name, email: data.email, phone: data.phone || null, company: data.company || null, message: data.message || null, ip: req.ip, }); const lead = { id, ...data }; // fail-soft side effects const listIds = env.brevo.contactListId ? [Number(env.brevo.contactListId)] : []; await upsertContact({ email: data.email, attributes: { NAME: data.name, PHONE: data.phone || '', LEAD_KIND: data.kind }, listIds }); if (env.brevo.salesNotifyEmail) { const { subject, html } = salesNotifyEmail({ lead }); await sendTransactional({ to: env.brevo.salesNotifyEmail, subject, html }); } return res.status(202).json({ success: true, data: { received: true } }); })); module.exports = router; ``` Mount it in **`server/src/routes.js`**: ```js const leadsRoutes = require('./modules/leads/leads.routes'); router.use('/leads', leadsRoutes); // public ``` ### Step 7 — Frontend "Talk to sales / Call me back" form Create **`client/src/components/LeadForm.tsx`** (a modal): fields name, email, phone, company, message, a hidden `website` honeypot input, and a `kind` (default `sales`). On submit `await api('/leads', { method: 'POST', body })`; show success state. Open it from upgrade CTAs (PRP-010 decides which CTAs open the form vs. link out). ### Step 8 — Build & test (see §6). --- ## 5. API endpoints & Postman documentation ### POST `/api/leads` (public) — NEW Capture a sales/callback/upgrade lead → store + Brevo contact + notify sales. - **Auth:** none (public). **Rate limit:** 10/min per IP. - **Headers:** `Content-Type: application/json` - **Request body** ```json { "name": "Omar Aziz", "email": "omar@store.test", "phone": "+201000000000", "company": "Omar Store", "message": "Interested in drivers + invoicing", "kind": "sales" } ``` `kind` ∈ `callback | sales | upgrade`. Optional honeypot field `website` must be empty. - **202 response** ```json { "success": true, "data": { "received": true } } ``` - **422** validation error. **Postman setup (add a new folder "Leads"):** - Request **POST /api/leads**, URL `{{baseUrl}}/api/leads`, body = JSON above, no auth header. - Test: `pm.test('accepted', () => pm.expect(pm.response.code).to.eql(202));` > Note: the welcome and credentials emails have **no endpoint** — they fire from events. Verify them via > the Brevo dashboard / inbox, not Postman. --- ## 6. Manual test / acceptance verification ```bash B=http://localhost:3000/api # 1. Welcome email: register with a REAL inbox, then check it arrived curl -s -X POST $B/auth/register -H "Content-Type: application/json" \ -d '{"company_name":"Mail Test","contact_name":"You","email":"YOUR_REAL@inbox","phone":"+201","country":"EG","password":"password123"}' >/dev/null # 2. Lead capture → 202, contact in Brevo list, notify email to SALES_NOTIFY_EMAIL curl -s -o /dev/null -w "%{http_code}\n" -X POST $B/leads -H "Content-Type: application/json" \ -d '{"name":"Omar","email":"omar@store.test","kind":"sales","message":"hi"}' # 3. Missing config safety: temporarily unset BREVO_API_KEY → flows still 201/202, warning logged ``` Cleanup test rows: ```bash "/c/xampp/mysql/bin/mysql.exe" -uroot -h127.0.0.1 shiprexlite -e "DELETE FROM leads; DELETE FROM companies WHERE email LIKE '%@inbox';" ``` **Acceptance criteria** - [x] Registering sends a welcome email (verify in inbox/Brevo logs). - [x] `POST /leads` → 202, adds Brevo contact + emails `SALES_NOTIFY_EMAIL`. - [x] Missing/invalid Brevo config does not break signup or leads (warning logged, request succeeds). - [x] Honeypot `website` filled → silently accepted, no DB row spam. - [x] Password reset flow: `POST /auth/forgot-password` → email sent; `POST /auth/reset-password` → password changed. --- ## 7. Git commits (follow in order) **Commit 1 — Brevo service + templates** ```bash git add server/src/services/email git commit -m "feat(email): PRP-009 Brevo transactional service + templates Adds fail-soft Brevo send/upsert (native fetch) and welcome/credentials/sales HTML templates. No-op with a warning when BREVO_API_KEY is unset. Co-Authored-By: Claude Opus 4.8