nodebb-plugin-onekite-calendar 1.0.12 → 1.0.13

package/lib/api.js

@@ -0,0 +1,941 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const meta = require.main.require('./src/meta');
+const emailer = require.main.require('./src/emailer');
+const nconf = require.main.require('nconf');
+const user = require.main.require('./src/user');
+const groups = require.main.require('./src/groups');
+const db = require.main.require('./src/database');
+const logger = require.main.require('./src/logger');
+
+const dbLayer = require('./db');
+
+// Fast membership check without N calls to groups.isMember.
+// NodeBB's groups.getUserGroups([uid]) returns an array (per uid) of group objects.
+// We compare against both group slugs and names to be tolerant with older settings.
+async function userInAnyGroup(uid, allowed) {
+  if (!uid || !Array.isArray(allowed) || !allowed.length) return false;
+  const ug = await groups.getUserGroups([uid]);
+  const list = (ug && ug[0]) ? ug[0] : [];
+  const seen = new Set();
+  for (const g of list) {
+    if (!g) continue;
+    if (g.slug) seen.add(String(g.slug));
+    if (g.name) seen.add(String(g.name));
+    if (g.groupName) seen.add(String(g.groupName));
+    if (g.displayName) seen.add(String(g.displayName));
+  }
+  return allowed.some(v => seen.has(String(v)));
+}
+
+
+function normalizeAllowedGroups(raw) {
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.map(v => String(v).trim()).filter(Boolean);
+  const s = String(raw).trim();
+  if (!s) return [];
+  // Some admin UIs store JSON arrays as strings
+  if ((s.startsWith('[') && s.endsWith(']')) || (s.startsWith('"[') && s.endsWith(']"'))) {
+    try {
+      const parsed = JSON.parse(s.startsWith('"') ? JSON.parse(s) : s);
+      if (Array.isArray(parsed)) return parsed.map(v => String(v).trim()).filter(Boolean);
+    } catch (e) {}
+  }
+  return s.split(',').map(v => String(v).trim().replace(/^"+|"+$/g, '')).filter(Boolean);
+}
+
+// NOTE: Avoid per-group async checks (groups.isMember) when possible.
+
+
+const helloasso = require('./helloasso');
+const discord = require('./discord');
+
+// Email helper: NodeBB's Emailer signature differs across versions.
+// We try the common forms. Any failure is logged for debugging.
+async function sendEmail(template, toEmail, subject, data) {
+  if (!toEmail) return;
+  try {
+    // NodeBB core signature (historically):
+    //   Emailer.sendToEmail(template, email, language, params[, callback])
+    // Subject is not a positional arg; it must be injected (either by NodeBB itself
+    // or via filter:email.modify). We always pass it in params.subject.
+    const language = (meta && meta.config && (meta.config.defaultLang || meta.config.defaultLanguage)) || 'fr';
+    const params = Object.assign({}, data || {}, subject ? { subject } : {});
+    if (typeof emailer.sendToEmail === 'function') {
+      await emailer.sendToEmail(template, toEmail, language, params);
+      return;
+    }
+    // Fallback for older/unusual builds (rare)
+    if (typeof emailer.send === 'function') {
+      // Some builds accept (template, email, language, params)
+      if (emailer.send.length >= 4) {
+        await emailer.send(template, toEmail, language, params);
+        return;
+      }
+      // Some builds accept (template, email, params)
+      await emailer.send(template, toEmail, params);
+    }
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn('[calendar-onekite] Failed to send email', { template, toEmail, err: String(err) });
+  }
+}
+
+function normalizeBaseUrl(meta) {
+  // Prefer meta.config.url, fallback to nconf.get('url')
+  let base = (meta && meta.config && (meta.config.url || meta.config['url'])) ? (meta.config.url || meta.config['url']) : '';
+  if (!base) {
+    base = String(nconf.get('url') || '').trim();
+  }
+  base = String(base || '').trim().replace(/\/$/, '');
+  // Ensure absolute with scheme
+  if (base && !/^https?:\/\//i.test(base)) {
+    base = `https://${base.replace(/^\/\//, '')}`;
+  }
+  return base;
+}
+
+function normalizeCallbackUrl(configured, meta) {
+  const base = normalizeBaseUrl(meta);
+  let url = (configured || '').trim();
+  if (!url) {
+    // Default webhook endpoint (recommended): namespaced under /plugins
+    url = base ? `${base}/plugins/calendar-onekite/helloasso` : '';
+  }
+  if (url && url.startsWith('/') && base) {
+    url = `${base}${url}`;
+  }
+  // Ensure scheme for absolute URLs
+  if (url && !/^https?:\/\//i.test(url)) {
+    url = `https://${url.replace(/^\/\//, '')}`;
+  }
+  return url;
+}
+
+function normalizeReturnUrl(meta) {
+  const base = normalizeBaseUrl(meta);
+  return base ? `${base}/calendar` : '';
+}
+
+
+function overlap(aStart, aEnd, bStart, bEnd) {
+  return aStart < bEnd && bStart < aEnd;
+}
+
+
+function formatFR(tsOrIso) {
+  const d = new Date(typeof tsOrIso === 'string' && /^[0-9]+$/.test(tsOrIso) ? parseInt(tsOrIso, 10) : tsOrIso);
+  const dd = String(d.getDate()).padStart(2, '0');
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const yyyy = d.getFullYear();
+  return `${dd}/${mm}/${yyyy}`;
+}
+
+function buildHelloAssoItemName(baseLabel, itemNames, start, end) {
+  const base = String(baseLabel || '').trim();
+  const items = Array.isArray(itemNames) ? itemNames.map((s) => String(s || '').trim()).filter(Boolean) : [];
+  const range = (start && end) ? ('Du ' + formatFR(start) + ' au ' + formatFR(end)) : '';
+
+  // IMPORTANT:
+  // On the public HelloAsso checkout page, line breaks are not always rendered consistently.
+  // Build a single-line label using bullet separators.
+  let out = '';
+  if (base) out += base;
+  if (items.length) out += (out ? ' — ' : '') + items.map((it) => '• ' + it).join(' ');
+  if (range) out += (out ? ' — ' : '') + range;
+
+  out = String(out || '').trim();
+  if (!out) out = 'Réservation matériel';
+
+  // HelloAsso constraint: itemName max 250 chars
+  if (out.length > 250) {
+    out = out.slice(0, 249).trimEnd() + '…';
+  }
+  return out;
+}
+
+function toTs(v) {
+  if (v === undefined || v === null || v === '') return NaN;
+  // Accept milliseconds timestamps passed as strings or numbers.
+  if (typeof v === 'number') return v;
+  const s = String(v).trim();
+  if (/^[0-9]+$/.test(s)) return parseInt(s, 10);
+
+  // IMPORTANT: Date-only strings like "2026-01-09" are interpreted as UTC by JS Date(),
+  // which can create 1h overlaps in Europe/Paris (and other TZs) between consecutive days.
+  // We treat date-only inputs as local-midnight by appending a time component.
+  if (/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+    const dLocal = new Date(s + 'T00:00:00');
+    return dLocal.getTime();
+  }
+
+  const d = new Date(s);
+  return d.getTime();
+}
+
+function yearFromTs(ts) {
+  const d = new Date(Number(ts));
+  return Number.isFinite(d.getTime()) ? d.getFullYear() : new Date().getFullYear();
+}
+
+function autoCreatorGroupForYear(year) {
+  return `onekite-ffvl-${year}`;
+}
+
+
+// (removed) group slug/name resolving helpers: we now use userInAnyGroup() which
+// matches both slugs and names and avoids extra DB lookups.
+
+
+function autoFormSlugForYear(year) {
+  return `locations-materiel-${year}`;
+}
+
+async function canRequest(uid, settings, startTs) {
+  if (!uid) return false;
+
+  // Always allow administrators to create.
+  try {
+    if (await groups.isMember(uid, 'administrators')) return true;
+  } catch (e) {}
+
+  const year = yearFromTs(startTs);
+  const defaultGroup = autoCreatorGroupForYear(year);
+
+  // ACP may store group slugs as CSV string or array depending on NodeBB/admin UI.
+  // On some installs, the UI stores *names* rather than slugs; we accept both.
+  const raw = settings.creatorGroups ?? settings.allowedGroups ?? [];
+  const extraGroups = normalizeAllowedGroups(raw);
+
+  const allowed = [...new Set([defaultGroup, ...extraGroups].filter(Boolean))];
+  if (!allowed.length) return false;
+
+  // Fast path: compare against user's groups (slug + name).
+  try {
+    if (await userInAnyGroup(uid, allowed)) return true;
+  } catch (e) {
+    // ignore
+  }
+
+  // Fallback: try isMember on each allowed entry (slug on most installs)
+  for (const g of allowed) {
+    try {
+      if (await groups.isMember(uid, g)) return true;
+    } catch (err) {}
+  }
+  return false;
+}
+
+async function canValidate(uid, settings) {
+  // Always allow forum administrators (and global moderators) to validate,
+  // even if validatorGroups is empty.
+  try {
+    const isAdmin = await groups.isMember(uid, 'administrators');
+    if (isAdmin) return true;
+  } catch (e) {}
+
+  const allowed = normalizeAllowedGroups(settings.validatorGroups || '');
+  if (!allowed.length) return false;
+  if (await userInAnyGroup(uid, allowed)) return true;
+
+  return false;
+}
+
+async function canCreateSpecial(uid, settings) {
+  if (!uid) return false;
+  try {
+    const isAdmin = await groups.isMember(uid, 'administrators');
+    if (isAdmin) return true;
+  } catch (e) {}
+  const allowed = normalizeAllowedGroups(settings.specialCreatorGroups || '');
+  if (!allowed.length) return false;
+  if (await userInAnyGroup(uid, allowed)) return true;
+
+  return false;
+}
+
+async function canDeleteSpecial(uid, settings) {
+  if (!uid) return false;
+  try {
+    const isAdmin = await groups.isMember(uid, 'administrators');
+    if (isAdmin) return true;
+  } catch (e) {}
+  const allowed = normalizeAllowedGroups(settings.specialDeleterGroups || settings.specialCreatorGroups || '');
+  if (!allowed.length) return false;
+  if (await userInAnyGroup(uid, allowed)) return true;
+
+  return false;
+}
+
+function eventsFor(resv) {
+  const status = resv.status;
+  const icons = { pending: '⏳', awaiting_payment: '💳', paid: '✅' };
+  const colors = { pending: '#f39c12', awaiting_payment: '#d35400', paid: '#27ae60' };
+  const startIsoDate = new Date(parseInt(resv.start, 10)).toISOString().slice(0, 10);
+  const endIsoDate = new Date(parseInt(resv.end, 10)).toISOString().slice(0, 10);
+
+  const itemIds = Array.isArray(resv.itemIds) ? resv.itemIds : (resv.itemId ? [resv.itemId] : []);
+  const itemNames = Array.isArray(resv.itemNames) ? resv.itemNames : (resv.itemName ? [resv.itemName] : []);
+
+  // One line = one material: return one calendar event per item
+  const out = [];
+  const count = Math.max(itemIds.length, itemNames.length, 1);
+  for (let i = 0; i < count; i++) {
+    const itemId = String(itemIds[i] || itemIds[0] || resv.itemId || '');
+    const itemName = String(itemNames[i] || itemNames[0] || resv.itemName || itemId);
+    out.push({
+      // keep id unique per item for FullCalendar, but keep the real rid in extendedProps.rid
+      id: `${resv.rid}:${itemId || i}`,
+      title: `${icons[status] || ''} ${itemName}`.trim(),
+      backgroundColor: colors[status] || '#3498db',
+      borderColor: colors[status] || '#3498db',
+      textColor: '#ffffff',
+      allDay: true,
+      start: startIsoDate,
+      end: endIsoDate,
+      extendedProps: {
+        rid: resv.rid,
+        status,
+        uid: resv.uid,
+        approvedBy: resv.approvedBy || 0,
+        approvedByUsername: resv.approvedByUsername || '',
+        itemIds: itemIds.filter(Boolean),
+        itemNames: itemNames.filter(Boolean),
+        itemIdLine: itemId,
+        itemNameLine: itemName,
+      },
+    });
+  }
+  return out;
+}
+
+function eventsForSpecial(ev) {
+  const start = new Date(parseInt(ev.start, 10));
+  const end = new Date(parseInt(ev.end, 10));
+  const startIso = start.toISOString();
+  const endIso = end.toISOString();
+  return {
+    id: `special:${ev.eid}`,
+    title: `${ev.title || 'Évènement'}`.trim(),
+    allDay: false,
+    start: startIso,
+    end: endIso,
+    backgroundColor: '#8e44ad',
+    borderColor: '#8e44ad',
+    textColor: '#ffffff',
+    extendedProps: {
+      type: 'special',
+      eid: ev.eid,
+      title: ev.title || '',
+      notes: ev.notes || '',
+      pickupAddress: ev.address || '',
+      pickupLat: ev.lat || '',
+      pickupLon: ev.lon || '',
+      createdBy: ev.uid || 0,
+      username: ev.username || '',
+    },
+  };
+}
+
+const api = {};
+
+function computeEtag(payload) {
+  // Weak ETag is fine here: it is only used to skip identical JSON payloads.
+  const hash = crypto.createHash('sha1').update(JSON.stringify(payload)).digest('hex');
+  return `W/"${hash}"`;
+}
+
+api.getEvents = async function (req, res) {
+  const startTs = toTs(req.query.start) || 0;
+  const endTs = toTs(req.query.end) || (Date.now() + 365 * 24 * 3600 * 1000);
+
+  const settings = await meta.settings.get('calendar-onekite');
+  const canMod = req.uid ? await canValidate(req.uid, settings) : false;
+  const canSpecialCreate = req.uid ? await canCreateSpecial(req.uid, settings) : false;
+  const canSpecialDelete = req.uid ? await canDeleteSpecial(req.uid, settings) : false;
+
+  // Fetch a wider window because an event can start before the query range
+  // and still overlap.
+  const wideStart = Math.max(0, startTs - 366 * 24 * 3600 * 1000);
+  const ids = await dbLayer.listReservationIdsByStartRange(wideStart, endTs, 5000);
+  const out = [];
+  // Batch fetch = major perf win when there are many reservations.
+  const reservations = await dbLayer.getReservations(ids);
+  for (const r of (reservations || [])) {
+    if (!r) continue;
+    // Only show active statuses
+    if (!['pending', 'awaiting_payment', 'paid'].includes(r.status)) continue;
+    const rStart = parseInt(r.start, 10);
+    const rEnd = parseInt(r.end, 10);
+    if (!(rStart < endTs && startTs < rEnd)) continue; // overlap check
+    const evs = eventsFor(r);
+    for (const ev of evs) {
+      const p = ev.extendedProps || {};
+      const minimal = {
+        id: ev.id,
+        title: ev.title,
+        backgroundColor: ev.backgroundColor,
+        borderColor: ev.borderColor,
+        textColor: ev.textColor,
+        allDay: ev.allDay,
+        start: ev.start,
+        end: ev.end,
+        extendedProps: {
+          type: 'reservation',
+          rid: p.rid,
+          status: p.status,
+          uid: p.uid,
+          canModerate: canMod,
+        },
+      };
+      // Only expose username on the event list to owner/moderators.
+      if (r.username && ((req.uid && String(req.uid) === String(r.uid)) || canMod)) {
+        minimal.extendedProps.username = String(r.username);
+      }
+      // Let the UI decide if a "Payer" button might exist, without exposing the URL in list.
+      if (r.status === 'awaiting_payment' && r.paymentUrl && (/^https?:\/\//i).test(String(r.paymentUrl))) {
+        if ((req.uid && String(req.uid) === String(r.uid)) || canMod) {
+          minimal.extendedProps.hasPayment = true;
+        }
+      }
+      out.push(minimal);
+    }
+  }
+
+  // Special events
+  try {
+    const specialIds = await dbLayer.listSpecialIdsByStartRange(wideStart, endTs, 5000);
+    const specials = await dbLayer.getSpecialEvents(specialIds);
+    for (const sev of (specials || [])) {
+      if (!sev) continue;
+      const sStart = parseInt(sev.start, 10);
+      const sEnd = parseInt(sev.end, 10);
+      if (!(sStart < endTs && startTs < sEnd)) continue;
+      const full = eventsForSpecial(sev);
+      const minimal = {
+        id: full.id,
+        title: full.title,
+        allDay: full.allDay,
+        start: full.start,
+        end: full.end,
+        backgroundColor: full.backgroundColor,
+        borderColor: full.borderColor,
+        textColor: full.textColor,
+        extendedProps: {
+          type: 'special',
+          eid: sev.eid,
+          canCreateSpecial: canSpecialCreate,
+          canDeleteSpecial: canSpecialDelete,
+        },
+      };
+      if (sev.username && (canMod || canSpecialDelete || (req.uid && String(req.uid) === String(sev.uid)))) {
+        minimal.extendedProps.username = String(sev.username);
+      }
+      out.push(minimal);
+    }
+  } catch (e) {
+    // ignore
+  }
+
+  // Stable ordering -> stable ETag
+  out.sort((a, b) => {
+    const as = String(a.start || '');
+    const bs = String(b.start || '');
+    if (as !== bs) return as < bs ? -1 : 1;
+    const ai = String(a.id || '');
+    const bi = String(b.id || '');
+    return ai < bi ? -1 : ai > bi ? 1 : 0;
+  });
+
+  const etag = computeEtag(out);
+  res.setHeader('ETag', etag);
+  res.setHeader('Cache-Control', 'private, max-age=0, must-revalidate');
+  if (String(req.headers['if-none-match'] || '') === etag) {
+    return res.status(304).end();
+  }
+
+  return res.json(out);
+};
+
+api.getReservationDetails = async function (req, res) {
+  const uid = req.uid;
+  if (!uid) return res.status(401).json({ error: 'not-logged-in' });
+
+  const settings = await meta.settings.get('calendar-onekite');
+  const canMod = await canValidate(uid, settings);
+
+  const rid = String(req.params.rid || '').trim();
+  if (!rid) return res.status(400).json({ error: 'missing-rid' });
+  const r = await dbLayer.getReservation(rid);
+  if (!r) return res.status(404).json({ error: 'not-found' });
+
+  const isOwner = String(r.uid) === String(uid);
+  if (!isOwner && !canMod) return res.status(403).json({ error: 'not-allowed' });
+
+  const out = {
+    rid: r.rid,
+    status: r.status,
+    uid: r.uid,
+    username: r.username || '',
+    itemNames: Array.isArray(r.itemNames) ? r.itemNames : (r.itemName ? [r.itemName] : []),
+    itemIds: Array.isArray(r.itemIds) ? r.itemIds : (r.itemId ? [r.itemId] : []),
+    start: r.start,
+    end: r.end,
+    approvedByUsername: r.approvedByUsername || '',
+    pickupAddress: r.pickupAddress || '',
+    pickupTime: r.pickupTime || '',
+    pickupLat: r.pickupLat || '',
+    pickupLon: r.pickupLon || '',
+    notes: r.notes || '',
+    refusedReason: r.refusedReason || '',
+    total: r.total || 0,
+    canModerate: canMod,
+  };
+
+  if (r.status === 'awaiting_payment' && r.paymentUrl && (/^https?:\/\//i).test(String(r.paymentUrl))) {
+    out.paymentUrl = String(r.paymentUrl);
+  }
+
+  return res.json(out);
+};
+
+api.getSpecialEventDetails = async function (req, res) {
+  const uid = req.uid;
+  if (!uid) return res.status(401).json({ error: 'not-logged-in' });
+
+  const settings = await meta.settings.get('calendar-onekite');
+  const canMod = await canValidate(uid, settings);
+  const canSpecialDelete = await canDeleteSpecial(uid, settings);
+
+  const eid = String(req.params.eid || '').trim();
+  if (!eid) return res.status(400).json({ error: 'missing-eid' });
+  const ev = await dbLayer.getSpecialEvent(eid);
+  if (!ev) return res.status(404).json({ error: 'not-found' });
+
+  // Anyone who can see the calendar can view special events, but creator username
+  // is only visible to moderators/allowed users or the creator.
+  const out = {
+    eid: ev.eid,
+    title: ev.title || '',
+    start: ev.start,
+    end: ev.end,
+    address: ev.address || '',
+    lat: ev.lat || '',
+    lon: ev.lon || '',
+    notes: ev.notes || '',
+    canDeleteSpecial: canSpecialDelete,
+  };
+  if (ev.username && (canMod || canSpecialDelete || (uid && String(uid) === String(ev.uid)))) {
+    out.username = String(ev.username);
+  }
+  return res.json(out);
+};
+
+api.getCapabilities = async function (req, res) {
+  const settings = await meta.settings.get('calendar-onekite');
+  const uid = req.uid || 0;
+  const canMod = uid ? await canValidate(uid, settings) : false;
+  res.json({
+    canModerate: canMod,
+    canCreateSpecial: uid ? await canCreateSpecial(uid, settings) : false,
+    canDeleteSpecial: uid ? await canDeleteSpecial(uid, settings) : false,
+  });
+};
+
+api.createSpecialEvent = async function (req, res) {
+  const settings = await meta.settings.get('calendar-onekite');
+  if (!req.uid) return res.status(401).json({ error: 'not-logged-in' });
+  const ok = await canCreateSpecial(req.uid, settings);
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+
+  const title = String((req.body && req.body.title) || '').trim() || 'Évènement';
+  const startTs = toTs(req.body && req.body.start);
+  const endTs = toTs(req.body && req.body.end);
+  if (!Number.isFinite(startTs) || !Number.isFinite(endTs) || !(startTs < endTs)) {
+    return res.status(400).json({ error: 'bad-dates' });
+  }
+  const address = String((req.body && req.body.address) || '').trim();
+  const notes = String((req.body && req.body.notes) || '').trim();
+  const lat = String((req.body && req.body.lat) || '').trim();
+  const lon = String((req.body && req.body.lon) || '').trim();
+
+  const u = await user.getUserFields(req.uid, ['username']);
+  const eid = crypto.randomUUID();
+  const ev = {
+    eid,
+    title,
+    start: String(startTs),
+    end: String(endTs),
+    address,
+    notes,
+    lat,
+    lon,
+    uid: String(req.uid),
+    username: u && u.username ? String(u.username) : '',
+    createdAt: String(Date.now()),
+  };
+  await dbLayer.saveSpecialEvent(ev);
+  res.json({ ok: true, eid });
+};
+
+api.deleteSpecialEvent = async function (req, res) {
+  const settings = await meta.settings.get('calendar-onekite');
+  if (!req.uid) return res.status(401).json({ error: 'not-logged-in' });
+  const ok = await canDeleteSpecial(req.uid, settings);
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const eid = String(req.params.eid || '').replace(/^special:/, '').trim();
+  if (!eid) return res.status(400).json({ error: 'bad-id' });
+  await dbLayer.removeSpecialEvent(eid);
+  res.json({ ok: true });
+};
+
+api.getItems = async function (req, res) {
+  const settings = await meta.settings.get('calendar-onekite');
+
+  const env = settings.helloassoEnv || 'prod';
+  const token = await helloasso.getAccessToken({
+    env,
+    clientId: settings.helloassoClientId,
+    clientSecret: settings.helloassoClientSecret,
+  });
+    if (!token) {
+
+    }
+
+  if (!token) {
+    return res.json([]);
+  }
+
+  // Important: the /items endpoint on HelloAsso lists *sold items*.
+  // For a shop catalog, use the /public form endpoint and extract the catalog.
+  const year = new Date().getFullYear();
+  const { items: catalog } = await helloasso.listCatalogItems({
+    env,
+    token,
+    organizationSlug: settings.helloassoOrganizationSlug,
+    formType: settings.helloassoFormType,
+    // Form slug is derived from the year
+    formSlug: autoFormSlugForYear(year),
+  });
+
+  const normalized = (catalog || []).map((it) => ({
+    id: it.id,
+    name: it.name,
+    price: typeof it.price === 'number' ? it.price : 0,
+  })).filter(it => it.id && it.name);
+
+  res.json(normalized);
+};
+
+api.createReservation = async function (req, res) {
+  const uid = req.uid;
+  if (!uid) return res.status(401).json({ error: 'not-logged-in' });
+
+  const settings = await meta.settings.get('calendar-onekite');
+  const startPreview = toTs(req.body.start);
+  const ok = await canRequest(uid, settings, startPreview);
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+
+  const start = parseInt(toTs(req.body.start), 10);
+  const end = parseInt(toTs(req.body.end), 10);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+    return res.status(400).json({ error: "bad-dates" });
+  }
+
+  // Support both legacy single itemId and new itemIds[] payload
+  const itemIds = Array.isArray(req.body.itemIds) ? req.body.itemIds.map(String) : ((req.body.itemId ? [String(req.body.itemId)] : []));
+  const itemNames = Array.isArray(req.body.itemNames) ? req.body.itemNames.map(String) : (req.body.itemName ? [String(req.body.itemName)] : []);
+
+  const total = typeof req.body.total === 'number' ? req.body.total : parseFloat(String(req.body.total || '0'));
+
+  if (!start || !end || !itemIds.length) {
+    return res.status(400).json({ error: 'missing-fields' });
+  }
+
+  // Prevent double booking: block if any selected item overlaps with an active reservation
+  const blocking = new Set(['pending', 'awaiting_payment', 'paid']);
+  const wideStart2 = Math.max(0, start - 366 * 24 * 3600 * 1000);
+  const candidateIds = await dbLayer.listReservationIdsByStartRange(wideStart2, end, 5000);
+  const conflicts = [];
+  const existingRows = await dbLayer.getReservations(candidateIds);
+  for (const existing of (existingRows || [])) {
+    if (!existing || !blocking.has(existing.status)) continue;
+    const exStart = parseInt(existing.start, 10);
+    const exEnd = parseInt(existing.end, 10);
+    if (!(exStart < end && start < exEnd)) continue;
+    const exItemIds = Array.isArray(existing.itemIds) ? existing.itemIds : (existing.itemId ? [existing.itemId] : []);
+    const shared = exItemIds.filter(x => itemIds.includes(String(x)));
+    if (shared.length) {
+      conflicts.push({ rid: existing.rid, itemIds: shared, status: existing.status });
+    }
+  }
+  if (conflicts.length) {
+    return res.status(409).json({ error: 'conflict', conflicts });
+  }
+
+  const now = Date.now();
+  const rid = crypto.randomUUID();
+
+  // Snapshot username for display in calendar popups
+  let username = null;
+  try {
+    username = await user.getUserField(uid, 'username');
+  } catch (e) {}
+
+  const resv = {
+    rid,
+    uid,
+    username: username || null,
+    itemIds,
+    itemNames: itemNames.length ? itemNames : itemIds,
+    // keep legacy fields for backward compatibility
+    itemId: itemIds[0],
+    itemName: (itemNames[0] || itemIds[0]),
+    start,
+    end,
+    status: 'pending',
+    createdAt: now,
+    total: isNaN(total) ? 0 : total,
+  };
+
+  // Save
+  await dbLayer.saveReservation(resv);
+
+  // Notify groups by email (NodeBB emailer config)
+  try {
+    const notifyGroups = (settings.notifyGroups || '').split(',').map(s => s.trim()).filter(Boolean);
+    if (notifyGroups.length) {
+      const requester = await user.getUserFields(uid, ['username', 'email']);
+      const itemsLabel = (resv.itemNames || []).join(', ');
+      for (const g of notifyGroups) {
+        const members = await groups.getMembers(g, 0, -1);
+        const uids = Array.isArray(members) ? members : [];
+
+        // Batch fetch user email/username when supported by this NodeBB version.
+        let usersData = [];
+        try {
+          if (typeof user.getUsersFields === 'function') {
+            usersData = await user.getUsersFields(uids, ['username', 'email']);
+          } else {
+            usersData = await Promise.all(uids.map(async (memberUid) => {
+              try { return await user.getUserFields(memberUid, ['username', 'email']); }
+              catch (e) { return null; }
+            }));
+          }
+        } catch (e) {
+          usersData = [];
+        }
+
+        for (const md of (usersData || [])) {
+          if (md && md.email) {
+            await sendEmail('calendar-onekite_pending', md.email, 'Location matériel - Demande de réservation', {
+              username: md.username,
+              requester: requester.username,
+              itemName: itemsLabel,
+              itemNames: resv.itemNames || [],
+              dateRange: `Du ${formatFR(start)} au ${formatFR(end)}`,
+              start: formatFR(start),
+              end: formatFR(end),
+              total: resv.total || 0,
+            });
+          }
+        }
+      }
+    }
+  } catch (e) {
+    console.warn('[calendar-onekite] Failed to send pending email', e && e.message ? e.message : e);
+  }
+
+  // Discord webhook (optional)
+  try {
+    await discord.notifyReservationRequested(settings, {
+      rid: resv.rid,
+      uid: resv.uid,
+      username: resv.username || '',
+      itemIds: resv.itemIds || [],
+      itemNames: resv.itemNames || [],
+      start: resv.start,
+      end: resv.end,
+      status: resv.status,
+    });
+  } catch (e) {}
+
+  res.json({ ok: true, rid });
+};
+
+// Validator actions (from calendar popup)
+api.approveReservation = async function (req, res) {
+  const uid = req.uid;
+  if (!uid) return res.status(401).json({ error: 'not-logged-in' });
+  const settings = await meta.settings.get('calendar-onekite');
+  const ok = await canValidate(uid, settings);
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+
+  const rid = req.params.rid;
+  const r = await dbLayer.getReservation(rid);
+  if (!r) return res.status(404).json({ error: 'not-found' });
+  if (r.status !== 'pending') return res.status(400).json({ error: 'bad-status' });
+
+  r.status = 'awaiting_payment';
+  // Backwards compatible: old clients sent `adminNote` to describe the pickup place.
+  r.pickupAddress = String((req.body && (req.body.pickupAddress || req.body.adminNote)) || '').trim();
+  r.notes = String((req.body && req.body.notes) || '').trim();
+  r.pickupTime = String((req.body && req.body.pickupTime) || '').trim();
+  r.pickupLat = String((req.body && req.body.pickupLat) || '').trim();
+  r.pickupLon = String((req.body && req.body.pickupLon) || '').trim();
+  r.approvedAt = Date.now();
+  try {
+    const approver = await user.getUserFields(uid, ['username']);
+    r.approvedBy = uid;
+    r.approvedByUsername = approver && approver.username ? approver.username : '';
+  } catch (e) {
+    r.approvedBy = uid;
+    r.approvedByUsername = '';
+  }
+  // Create HelloAsso payment link on validation
+  try {
+    const settings2 = await meta.settings.get('calendar-onekite');
+    const token = await helloasso.getAccessToken({ env: settings2.helloassoEnv || 'prod', clientId: settings2.helloassoClientId, clientSecret: settings2.helloassoClientSecret });
+    const payer = await user.getUserFields(r.uid, ['email']);
+    const year = yearFromTs(r.start);
+    const intent = await helloasso.createCheckoutIntent({
+      env: settings2.helloassoEnv,
+      token,
+      organizationSlug: settings2.helloassoOrganizationSlug,
+      formType: settings2.helloassoFormType,
+      // Form slug is derived from the year of the reservation start date
+      formSlug: autoFormSlugForYear(year),
+      // r.total is stored as an estimated total in euros; HelloAsso expects cents.
+      totalAmount: (() => {
+        const cents = Math.max(0, Math.round((Number(r.total) || 0) * 100));
+        if (!cents) {
+          console.warn('[calendar-onekite] HelloAsso totalAmount is 0 (approve API)', { rid, total: r.total });
+        }
+        return cents;
+      })(),
+      payerEmail: payer && payer.email ? payer.email : '',
+      // By default, point to the forum base url so the webhook hits this NodeBB instance.
+      // Can be overridden via ACP setting `helloassoCallbackUrl`.
+      callbackUrl: normalizeReturnUrl(meta),
+      webhookUrl: normalizeCallbackUrl(settings2.helloassoCallbackUrl, meta),
+      itemName: buildHelloAssoItemName('', r.itemNames || (r.itemName ? [r.itemName] : []), r.start, r.end),
+      containsDonation: false,
+      metadata: {
+        reservationId: String(rid),
+        items: (Array.isArray(r.itemNames) ? r.itemNames : (r.itemName ? [r.itemName] : [])).filter(Boolean),
+        dateRange: `Du ${formatFR(r.start)} au ${formatFR(r.end)}`,
+      },
+    });
+    const paymentUrl = intent && (intent.paymentUrl || intent.redirectUrl) ? (intent.paymentUrl || intent.redirectUrl) : (typeof intent === 'string' ? intent : null);
+    const checkoutIntentId = intent && intent.checkoutIntentId ? String(intent.checkoutIntentId) : null;
+    if (paymentUrl) {
+      r.paymentUrl = paymentUrl;
+      if (checkoutIntentId) {
+        r.checkoutIntentId = checkoutIntentId;
+      }
+    } else {
+      console.warn('[calendar-onekite] HelloAsso payment link not created (approve API)', { rid });
+    }
+  } catch (e) {
+    // ignore payment link errors, admin can retry
+  }
+
+  await dbLayer.saveReservation(r);
+
+  // Email requester
+  const requester = await user.getUserFields(r.uid, ['username', 'email']);
+  if (requester && requester.email) {
+    const latNum = Number(r.pickupLat);
+    const lonNum = Number(r.pickupLon);
+    const mapUrl = (Number.isFinite(latNum) && Number.isFinite(lonNum))
+      ? `https://www.openstreetmap.org/?mlat=${encodeURIComponent(String(latNum))}&mlon=${encodeURIComponent(String(lonNum))}#map=18/${encodeURIComponent(String(latNum))}/${encodeURIComponent(String(lonNum))}`
+      : '';
+    await sendEmail('calendar-onekite_approved', requester.email, 'Location matériel - Réservation validée', {
+      username: requester.username,
+      itemName: (Array.isArray(r.itemNames) ? r.itemNames.join(', ') : (r.itemName || '')),
+        itemNames: (Array.isArray(r.itemNames) ? r.itemNames : (r.itemName ? [r.itemName] : [])),
+        dateRange: `Du ${formatFR(r.start)} au ${formatFR(r.end)}`,
+      start: formatFR(r.start),
+      end: formatFR(r.end),
+      pickupAddress: r.pickupAddress || '',
+      notes: r.notes || '',
+      pickupTime: r.pickupTime || '',
+      pickupLat: r.pickupLat || '',
+      pickupLon: r.pickupLon || '',
+      mapUrl,
+      paymentUrl: r.paymentUrl || '',
+      validatedBy: r.approvedByUsername || '',
+      validatedByUrl: (r.approvedByUsername ? `https://www.onekite.com/user/${encodeURIComponent(String(r.approvedByUsername))}` : ''),
+    });
+  }
+  return res.json({ ok: true });
+};
+
+api.refuseReservation = async function (req, res) {
+  const uid = req.uid;
+  if (!uid) return res.status(401).json({ error: 'not-logged-in' });
+  const settings = await meta.settings.get('calendar-onekite');
+  const ok = await canValidate(uid, settings);
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+
+  const rid = req.params.rid;
+  const r = await dbLayer.getReservation(rid);
+  if (!r) return res.status(404).json({ error: 'not-found' });
+
+  r.status = 'refused';
+  r.refusedAt = Date.now();
+  r.refusedReason = String((req.body && (req.body.reason || req.body.refusedReason || req.body.refuseReason)) || '').trim();
+  await dbLayer.saveReservation(r);
+
+  const requester = await user.getUserFields(r.uid, ['username', 'email']);
+  if (requester && requester.email) {
+    await sendEmail('calendar-onekite_refused', requester.email, 'Location matériel - Demande de réservation', {
+      username: requester.username,
+      itemName: (Array.isArray(r.itemNames) ? r.itemNames.join(', ') : (r.itemName || '')),
+        itemNames: (Array.isArray(r.itemNames) ? r.itemNames : (r.itemName ? [r.itemName] : [])),
+        dateRange: `Du ${formatFR(r.start)} au ${formatFR(r.end)}`,
+      start: formatFR(r.start),
+      end: formatFR(r.end),
+      refusedReason: r.refusedReason || '',
+    });
+  }
+
+  return res.json({ ok: true });
+};
+
+
+
+api.cancelReservation = async function (req, res) {
+  const uid = req.uid;
+  if (!uid) return res.status(401).json({ error: 'not-logged-in' });
+
+  const settings = await meta.settings.get('calendar-onekite');
+  const rid = String(req.params.rid || '').trim();
+  if (!rid) return res.status(400).json({ error: 'missing-rid' });
+
+  const r = await dbLayer.getReservation(rid);
+  if (!r) return res.status(404).json({ error: 'not-found' });
+
+  const canMod = await canValidate(uid, settings);
+  const isOwner = String(r.uid) === String(uid);
+
+  // Owner can cancel their own reservation only while payment is not completed.
+  // Validators/admins can cancel any reservation.
+  if (!isOwner && !canMod) return res.status(403).json({ error: 'not-allowed' });
+
+  const isPaid = String(r.status) === 'paid';
+  if (isOwner && isPaid) return res.status(400).json({ error: 'cannot-cancel-paid' });
+
+  if (r.status === 'cancelled') return res.json({ ok: true, status: 'cancelled' });
+
+  r.status = 'cancelled';
+  r.cancelledAt = Date.now();
+  r.cancelledBy = uid;
+
+  await dbLayer.saveReservation(r);
+  return res.json({ ok: true, status: 'cancelled' });
+};
+
+module.exports = api;