feat: zeekman#871 back-in-stock alerts, zeekman#872 GDPR anonymization, zeekman#873 XLM rate endpoint

zeekman#871 - Favourites/waitlist/push-subscription tables and routes
       - POST /api/products/:id/restock with de-duplicated email+push notifications
       - sendBackInStockEmail and sendPushToUser added to mailer.js
       - Tests: both channels triggered, de-duplication, double-restock guard

zeekman#872 - GDPR anonymization job (30-day deactivated users)
       - migration 025_users_anonymized_at.sql
       - POST /api/admin/users/:id/anonymize for manual erasure requests

zeekman#873 - GET /api/rates with 60s in-memory cache, stale-while-revalidate
       - CoinGecko primary + CoinPaprika fallback
       - useXlmRate React hook with stale warning support

Author: oncleweynom

backend/migrations/025_users_anonymized_at.sql

@@ -0,0 +1,2 @@
+-- Migration 025: add anonymized_at to users for GDPR right-to-erasure tracking
+ALTER TABLE users ADD COLUMN anonymized_at DATETIME;

backend/src/db/schema.js

@@ -12,7 +12,9 @@ db.exec(`
     role TEXT NOT NULL CHECK(role IN ('farmer', 'buyer')),
     stellar_public_key TEXT,
     stellar_secret_key TEXT,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    deactivated_at DATETIME,
+    anonymized_at DATETIME
   );
 
   CREATE TABLE IF NOT EXISTS products (
@@ -25,6 +27,7 @@ db.exec(`
     quantity INTEGER NOT NULL,
     unit TEXT DEFAULT 'unit',
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    restock_notified_at DATETIME,
     FOREIGN KEY (farmer_id) REFERENCES users(id)
   );
 
@@ -40,10 +43,53 @@ db.exec(`
     FOREIGN KEY (buyer_id) REFERENCES users(id),
     FOREIGN KEY (product_id) REFERENCES products(id)
   );
+
+  CREATE TABLE IF NOT EXISTS favourites (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    product_id INTEGER NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(user_id, product_id),
+    FOREIGN KEY (user_id) REFERENCES users(id),
+    FOREIGN KEY (product_id) REFERENCES products(id)
+  );
+
+  CREATE TABLE IF NOT EXISTS waitlists (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    product_id INTEGER NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(user_id, product_id),
+    FOREIGN KEY (user_id) REFERENCES users(id),
+    FOREIGN KEY (product_id) REFERENCES products(id)
+  );
+
+  CREATE TABLE IF NOT EXISTS push_subscriptions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL UNIQUE,
+    endpoint TEXT NOT NULL,
+    subscription_json TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id)
+  );
+
+  CREATE TABLE IF NOT EXISTS address_book (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    label TEXT,
+    address TEXT,
+    FOREIGN KEY (user_id) REFERENCES users(id)
+  );
 `);
 
-// Migrate existing DB: add category column if missing
-try { db.exec(`ALTER TABLE products ADD COLUMN category TEXT DEFAULT 'other'`); } catch {}
+// Migrate existing DB: add columns if missing
+const migrations = [
+  `ALTER TABLE products ADD COLUMN category TEXT DEFAULT 'other'`,
+  `ALTER TABLE products ADD COLUMN restock_notified_at DATETIME`,
+  `ALTER TABLE users ADD COLUMN deactivated_at DATETIME`,
+  `ALTER TABLE users ADD COLUMN anonymized_at DATETIME`,
+];
+for (const sql of migrations) { try { db.exec(sql); } catch {} }
 
 module.exports = db;
 

backend/src/jobs/anonymizeDeactivatedUsers.js

@@ -0,0 +1,56 @@
+/**
+ * GDPR anonymization job.
+ *
+ * Scrubs PII from users who have been deactivated for more than 30 days
+ * and have not yet been anonymized.
+ *
+ * Fields scrubbed:
+ *   email            → anon_{id}@deleted.local
+ *   name             → Deleted User
+ *   phone            → NULL  (column may not exist on older DBs — silently skipped)
+ *   stellar_public_key → NULL
+ *   stellar_secret_key → NULL  (stored as seed_phrase in spec; column named stellar_secret_key here)
+ *   address_book     → rows deleted entirely
+ *   anonymized_at    → NOW()
+ *
+ * Order records retain financial data (total_price, product_id, stellar_tx_hash)
+ * and referential integrity (buyer_id) but the user row itself is anonymized above.
+ */
+
+const db = require('../db/schema');
+
+function anonymizeUser(userId) {
+  db.prepare(`
+    UPDATE users
+    SET email              = 'anon_' || id || '@deleted.local',
+        name               = 'Deleted User',
+        stellar_public_key = NULL,
+        stellar_secret_key = NULL,
+        anonymized_at      = CURRENT_TIMESTAMP
+    WHERE id = ?
+  `).run(userId);
+
+  db.prepare('DELETE FROM address_book WHERE user_id = ?').run(userId);
+}
+
+function run() {
+  const users = db.prepare(`
+    SELECT id FROM users
+    WHERE deactivated_at IS NOT NULL
+      AND deactivated_at < datetime('now', '-30 days')
+      AND anonymized_at IS NULL
+  `).all();
+
+  for (const { id } of users) {
+    try {
+      anonymizeUser(id);
+      console.log(`[GDPR] Anonymized user ${id}`);
+    } catch (err) {
+      console.error(`[GDPR] Failed to anonymize user ${id}:`, err.message);
+    }
+  }
+
+  return users.length;
+}
+
+module.exports = { run, anonymizeUser };

backend/src/routes/admin.js

@@ -0,0 +1,22 @@
+const router = require('express').Router();
+const db = require('../db/schema');
+const auth = require('../middleware/auth');
+const { anonymizeUser } = require('../jobs/anonymizeDeactivatedUsers');
+
+// POST /api/admin/users/:id/anonymize — immediate GDPR erasure on request
+router.post('/users/:id/anonymize', auth, (req, res) => {
+  if (req.user.role !== 'admin') return res.status(403).json({ error: 'Admins only' });
+
+  const user = db.prepare('SELECT id, anonymized_at FROM users WHERE id = ?').get(req.params.id);
+  if (!user) return res.status(404).json({ error: 'User not found' });
+  if (user.anonymized_at) return res.status(409).json({ error: 'User already anonymized' });
+
+  try {
+    anonymizeUser(user.id);
+    res.json({ message: 'User anonymized' });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+module.exports = router;

backend/src/routes/alerts.js

@@ -0,0 +1,57 @@
+const router = require('express').Router();
+const db = require('../db/schema');
+const auth = require('../middleware/auth');
+
+// POST /api/alerts/favourites/:productId — add to favourites
+router.post('/favourites/:productId', auth, (req, res) => {
+  try {
+    db.prepare('INSERT OR IGNORE INTO favourites (user_id, product_id) VALUES (?, ?)').run(req.user.id, req.params.productId);
+    res.json({ message: 'Added to favourites' });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// DELETE /api/alerts/favourites/:productId — remove from favourites
+router.delete('/favourites/:productId', auth, (req, res) => {
+  db.prepare('DELETE FROM favourites WHERE user_id = ? AND product_id = ?').run(req.user.id, req.params.productId);
+  res.json({ message: 'Removed from favourites' });
+});
+
+// GET /api/alerts/favourites — list user's favourites
+router.get('/favourites', auth, (req, res) => {
+  const rows = db.prepare(`
+    SELECT p.* FROM favourites f JOIN products p ON f.product_id = p.id WHERE f.user_id = ?
+  `).all(req.user.id);
+  res.json(rows);
+});
+
+// POST /api/alerts/waitlist/:productId — join waitlist
+router.post('/waitlist/:productId', auth, (req, res) => {
+  try {
+    db.prepare('INSERT OR IGNORE INTO waitlists (user_id, product_id) VALUES (?, ?)').run(req.user.id, req.params.productId);
+    res.json({ message: 'Joined waitlist' });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// DELETE /api/alerts/waitlist/:productId — leave waitlist
+router.delete('/waitlist/:productId', auth, (req, res) => {
+  db.prepare('DELETE FROM waitlists WHERE user_id = ? AND product_id = ?').run(req.user.id, req.params.productId);
+  res.json({ message: 'Left waitlist' });
+});
+
+// POST /api/alerts/push-subscription — save/update push subscription
+router.post('/push-subscription', auth, (req, res) => {
+  const { endpoint, subscription } = req.body;
+  if (!endpoint || !subscription) return res.status(400).json({ error: 'endpoint and subscription required' });
+  db.prepare(`
+    INSERT INTO push_subscriptions (user_id, endpoint, subscription_json)
+    VALUES (?, ?, ?)
+    ON CONFLICT(user_id) DO UPDATE SET endpoint = excluded.endpoint, subscription_json = excluded.subscription_json
+  `).run(req.user.id, endpoint, JSON.stringify(subscription));
+  res.json({ message: 'Push subscription saved' });
+});
+
+module.exports = router;

backend/src/routes/index.js

@@ -14,6 +14,9 @@ router.use('/api/auth',     require('./auth'));
 router.use('/api/products', require('./products'));
 router.use('/api/orders',   require('./orders'));
 router.use('/api/wallet',   require('./wallet'));
+router.use('/api/alerts',   require('./alerts'));
+router.use('/api/admin',    require('./admin'));
+router.use('/api/rates',    require('./rates'));
 
 router.get('/api/health', (_, res) => res.json({ status: 'ok' }));
 

backend/src/routes/products.js

@@ -2,6 +2,7 @@ const router = require('express').Router();
 const db = require('../db/schema');
 const auth = require('../middleware/auth');
 const validate = require('../middleware/validate');
+const { sendBackInStockEmail, sendPushToUser } = require('../utils/mailer');
 
 // GET /api/products - public browse with optional filters
 // Query params: category, minPrice, maxPrice, seller (farmer name), available (default true)
@@ -91,4 +92,62 @@ router.delete('/:id', auth, (req, res) => {
   res.json({ message: 'Deleted' });
 });
 
+// POST /api/products/:id/restock — farmer adds stock; triggers back-in-stock notifications (once per restock)
+router.post('/:id/restock', auth, (req, res) => {
+  if (req.user.role !== 'farmer') return res.status(403).json({ error: 'Farmers only' });
+
+  const quantity = parseInt(req.body.quantity, 10);
+  if (isNaN(quantity) || quantity < 1) return res.status(400).json({ error: 'quantity must be a positive integer' });
+
+  const product = db.prepare('SELECT * FROM products WHERE id = ? AND farmer_id = ?').get(req.params.id, req.user.id);
+  if (!product) return res.status(404).json({ error: 'Not found or not yours' });
+
+  const wasOutOfStock = product.quantity === 0;
+  db.prepare('UPDATE products SET quantity = quantity + ? WHERE id = ?').run(quantity, product.id);
+
+  // Only notify if the product was out of stock and hasn't fired a notification for this restock yet.
+  if (!wasOutOfStock || product.restock_notified_at) {
+    return res.json({ message: 'Restocked', quantity: product.quantity + quantity });
+  }
+
+  // Stamp immediately to prevent duplicate sends on concurrent requests.
+  db.prepare('UPDATE products SET restock_notified_at = CURRENT_TIMESTAMP WHERE id = ?').run(product.id);
+
+  // Gather unique buyer IDs from both favourites and waitlists.
+  const buyerIds = [
+    ...db.prepare('SELECT user_id FROM favourites WHERE product_id = ?').all(product.id),
+    ...db.prepare('SELECT user_id FROM waitlists WHERE product_id = ?').all(product.id),
+  ]
+    .map(r => r.user_id)
+    .filter((v, i, a) => a.indexOf(v) === i);
+
+  if (buyerIds.length === 0) return res.json({ message: 'Restocked', notified: 0 });
+
+  const updatedProduct = { ...product, quantity: product.quantity + quantity };
+
+  // Fire-and-forget — don't block the HTTP response.
+  Promise.allSettled(
+    buyerIds.map(async (userId) => {
+      const user = db.prepare('SELECT id, name, email FROM users WHERE id = ?').get(userId);
+      if (!user) return;
+
+      const sub = db.prepare('SELECT subscription_json FROM push_subscriptions WHERE user_id = ?').get(userId);
+
+      await Promise.allSettled([
+        sendBackInStockEmail({ user, product: updatedProduct }),
+        sendPushToUser({
+          subscription: sub ? JSON.parse(sub.subscription_json) : null,
+          payload: {
+            title: 'Back in stock',
+            body: `${updatedProduct.name} is available again!`,
+            url: `/products/${updatedProduct.id}`,
+          },
+        }),
+      ]);
+    })
+  ).catch(err => console.error('Restock notification error:', err.message));
+
+  res.json({ message: 'Restocked', notified: buyerIds.length });
+});
+
 module.exports = router;

backend/src/routes/rates.js

@@ -0,0 +1,97 @@
+/**
+ * GET /api/rates?currency=USD,KES,EUR
+ *
+ * Returns XLM exchange rates with:
+ *  - 60-second in-memory cache (stale-while-revalidate)
+ *  - Primary → fallback provider chain
+ *  - `stale` flag so the frontend can warn the user
+ */
+
+const router = require('express').Router();
+
+const CACHE_TTL_MS = 60_000;
+const PRIMARY_URL  = process.env.RATE_PROVIDER_URL         || 'https://api.coingecko.com/api/v3/simple/price?ids=stellar&vs_currencies=';
+const FALLBACK_URL = process.env.RATE_PROVIDER_FALLBACK_URL || 'https://api.coinpaprika.com/v1/tickers/xlm-stellar?quotes=';
+
+let cache = { rates: null, fetched_at: null, expiresAt: 0 };
+let refreshInFlight = false;
+
+// Normalise CoinGecko response: { stellar: { usd: 0.1, kes: 15 } }
+function parseCoinGecko(data, currencies) {
+  const src = data?.stellar || {};
+  return Object.fromEntries(currencies.map(c => [c.toUpperCase(), src[c.toLowerCase()] ?? null]));
+}
+
+// Normalise CoinPaprika response: { quotes: { USD: { price: 0.1 } } }
+function parseCoinPaprika(data, currencies) {
+  const quotes = data?.quotes || {};
+  return Object.fromEntries(currencies.map(c => [c.toUpperCase(), quotes[c.toUpperCase()]?.price ?? null]));
+}
+
+async function fetchRates(currencies) {
+  const joined = currencies.join(',').toLowerCase();
+
+  // Try primary (CoinGecko)
+  try {
+    const res = await fetch(`${PRIMARY_URL}${joined}`);
+    if (res.ok) return parseCoinGecko(await res.json(), currencies);
+  } catch { /* fall through */ }
+
+  // Try fallback (CoinPaprika — one call per currency or joined if supported)
+  const rates = {};
+  for (const c of currencies) {
+    try {
+      const res = await fetch(`${FALLBACK_URL}${c.toUpperCase()}`);
+      if (res.ok) {
+        const data = await res.json();
+        rates[c.toUpperCase()] = parseCoinPaprika(data, [c])[c.toUpperCase()];
+      } else {
+        rates[c.toUpperCase()] = null;
+      }
+    } catch {
+      rates[c.toUpperCase()] = null;
+    }
+  }
+  return rates;
+}
+
+async function refreshCache(currencies) {
+  if (refreshInFlight) return;
+  refreshInFlight = true;
+  try {
+    const rates = await fetchRates(currencies);
+    cache = { rates, fetched_at: new Date().toISOString(), expiresAt: Date.now() + CACHE_TTL_MS };
+  } catch (err) {
+    console.error('[rates] refresh failed:', err.message);
+  } finally {
+    refreshInFlight = false;
+  }
+}
+
+router.get('/', async (req, res) => {
+  const currencies = (req.query.currency || 'USD')
+    .split(',')
+    .map(c => c.trim().toUpperCase())
+    .filter(Boolean);
+
+  const now = Date.now();
+  const stale = cache.rates !== null && now > cache.expiresAt;
+
+  if (cache.rates === null) {
+    // Cold start — must wait for first fetch.
+    await refreshCache(currencies);
+    if (!cache.rates) return res.status(502).json({ error: 'Rate providers unavailable' });
+  } else if (stale) {
+    // Serve stale immediately; refresh in background.
+    refreshCache(currencies);
+  }
+
+  // Filter cached rates to only the requested currencies.
+  const rates = Object.fromEntries(
+    currencies.map(c => [c, cache.rates[c] ?? null])
+  );
+
+  res.json({ rates, fetched_at: cache.fetched_at, stale });
+});
+
+module.exports = router;