nodebb-plugin-onekite-calendar 2.0.11 → 2.0.13

package/pkg/package/lib/api.js

@@ -0,0 +1,1458 @@
+'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');
+
+// Resolve group identifiers from ACP.
+// Admins may enter a group *name* ("Test") or a *slug* ("onekite-ffvl-2026").
+// Depending on NodeBB version and group type (system/custom), some core methods
+// accept one or the other. We try both to be tolerant.
+async function getMembersByGroupIdentifier(groupIdentifier) {
+  const id = String(groupIdentifier || '').trim();
+  if (!id) return [];
+
+  // First try direct.
+  let members = [];
+  try {
+    members = await groups.getMembers(id, 0, -1);
+  } catch (e) {
+    members = [];
+  }
+  if (Array.isArray(members) && members.length) return members;
+
+  // Then try slug -> groupName mapping when available.
+  if (typeof groups.getGroupNameByGroupSlug === 'function') {
+    let groupName = null;
+    try {
+      if (groups.getGroupNameByGroupSlug.length >= 2) {
+        groupName = await new Promise((resolve) => {
+          groups.getGroupNameByGroupSlug(id, (err, name) => resolve(err ? null : name));
+        });
+      } else {
+        groupName = await groups.getGroupNameByGroupSlug(id);
+      }
+    } catch (e) {
+      groupName = null;
+    }
+
+    if (groupName && String(groupName).trim() && String(groupName).trim() !== id) {
+      try {
+        members = await groups.getMembers(String(groupName).trim(), 0, -1);
+      } catch (e) {
+        members = [];
+      }
+      if (Array.isArray(members) && members.length) return members;
+    }
+  }
+
+  return Array.isArray(members) ? members : [];
+}
+
+
+function normalizeUids(members) {
+  if (!Array.isArray(members)) return [];
+  const out = [];
+  for (const m of members) {
+    if (Number.isInteger(m)) { out.push(m); continue; }
+    if (typeof m === 'string' && m.trim() && !Number.isNaN(parseInt(m, 10))) { out.push(parseInt(m, 10)); continue; }
+    if (m && typeof m === 'object' && (Number.isInteger(m.uid) || (typeof m.uid === 'string' && m.uid.trim()))) {
+      const u = Number.isInteger(m.uid) ? m.uid : parseInt(m.uid, 10);
+      if (!Number.isNaN(u)) out.push(u);
+    }
+  }
+  // de-dupe
+  return Array.from(new Set(out));
+}
+
+// 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 4.x): always send by uid.
+// Subject must be provided inside params.subject.
+async function sendEmail(template, uid, subject, data) {
+  const toUid = Number.isInteger(uid) ? uid : (uid ? parseInt(uid, 10) : NaN);
+  if (!Number.isInteger(toUid) || toUid <= 0) return;
+
+  const params = Object.assign({}, data || {}, subject ? { subject } : {});
+
+  try {
+    if (typeof emailer.send !== 'function') return;
+    // NodeBB 4.x: send(template, uid, params)
+    // NOTE: Do NOT branch on function.length: it is unreliable once the function
+    // is wrapped/bound (common in production builds) and can lead to params being
+    // dropped, resulting in empty email bodies and missing subjects.
+    await emailer.send(template, toUid, params);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn('[calendar-onekite] Failed to send email', { template, uid: toUid, err: String((err && err.message) || 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 (all-day boundaries / FullCalendar):
+  // Depending on FullCalendar config (or how dates are built), all-day range
+  // boundaries can arrive as an ISO string at **midnight UTC** (Z or +00:00).
+  // Example: 2026-01-11T00:00:00.000Z
+  // In Europe/Paris this is 01:00 local, which makes consecutive all-day ranges
+  // appear to overlap by 1 hour and wrongly marks the next day as unavailable.
+  // When we detect a midnight-UTC boundary, we treat it as a calendar date and
+  // convert to **local midnight** for overlap computations.
+  const mUtcMidnight = /^((\d{4}-\d{2}-\d{2}))T00:00:00(?:\.\d{1,3})?(?:Z|\+00:00)$/.exec(s);
+  if (mUtcMidnight && mUtcMidnight[1]) {
+    const dLocal = new Date(mUtcMidnight[1] + 'T00:00:00');
+    return dLocal.getTime();
+  }
+
+  // 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();
+}
+
+// Calendar-day difference (end exclusive) computed purely from Y/M/D.
+// Uses UTC midnights to avoid any dependency on local timezone or DST.
+function calendarDaysExclusiveYmd(startYmd, endYmd) {
+  try {
+    const m1 = /^\d{4}-\d{2}-\d{2}$/.exec(String(startYmd || '').trim());
+    const m2 = /^\d{4}-\d{2}-\d{2}$/.exec(String(endYmd || '').trim());
+    if (!m1 || !m2) return null;
+    const [sy, sm, sd] = startYmd.split('-').map((x) => parseInt(x, 10));
+    const [ey, em, ed] = endYmd.split('-').map((x) => parseInt(x, 10));
+    const sUtc = Date.UTC(sy, sm - 1, sd);
+    const eUtc = Date.UTC(ey, em - 1, ed);
+    const diff = Math.floor((eUtc - sUtc) / (24 * 60 * 60 * 1000));
+    return Math.max(1, diff);
+  } catch (e) {
+    return null;
+  }
+}
+
+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 canModerate(uid) {
+  const settings = await meta.settings.get('calendar-onekite');
+  return await canValidate(uid, settings);
+}
+
+async function auditLog(action, actorUid, payload) {
+  try {
+    const uid = actorUid ? parseInt(actorUid, 10) : 0;
+    let actorUsername = '';
+    if (uid) {
+      try {
+        const u = await user.getUserFields(uid, ['username']);
+        actorUsername = (u && u.username) ? String(u.username) : '';
+      } catch (e) {}
+    }
+    const ts = Date.now();
+    const year = new Date(ts).getFullYear();
+    await dbLayer.addAuditEntry(Object.assign({
+      ts,
+      year,
+      action: String(action || ''),
+      actorUid: uid,
+      actorUsername,
+    }, payload || {}));
+  } catch (e) {
+    // never block user flows on audit
+  }
+}
+
+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' };
+  // IMPORTANT:
+  // Prefer stored date-only strings when available.
+  //
+  // Rationale: when reservations are stored as local-midnight timestamps (because
+  // the client sends YYYY-MM-DD), converting those timestamps with toISOString()
+  // shifts the date in Europe/Paris (UTC+1/+2) and can make ranges appear to
+  // overlap the following day in some UI flows (notably "Durée rapide").
+  //
+  // FullCalendar expects `end` to be EXCLUSIVE for all-day ranges, so we keep
+  // using the stored endDate as-is.
+  const startIsoDate = (resv.startDate && /^\d{4}-\d{2}-\d{2}$/.test(String(resv.startDate)))
+    ? String(resv.startDate)
+    : new Date(parseInt(resv.start, 10)).toISOString().slice(0, 10);
+  const endIsoDate = (resv.endDate && /^\d{4}-\d{2}-\d{2}$/.test(String(resv.endDate)))
+    ? String(resv.endDate)
+    : 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 qStartRaw = (req && req.query && req.query.start !== undefined) ? String(req.query.start).trim() : '';
+  const qEndRaw = (req && req.query && req.query.end !== undefined) ? String(req.query.end).trim() : '';
+
+  // If the client provides date-only strings (YYYY-MM-DD), prefer purely calendar-based
+  // overlap checks. This avoids any dependency on server timezone, user timezone, DST,
+  // or how JS Date() parses inputs.
+  const qStartYmd = (/^\d{4}-\d{2}-\d{2}$/.test(qStartRaw)) ? qStartRaw : null;
+  const qEndYmd = (/^\d{4}-\d{2}-\d{2}$/.test(qEndRaw)) ? qEndRaw : null;
+
+  const startTs = toTs(qStartRaw) || 0;
+  const endTs = toTs(qEndRaw) || (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 widgetMode = String((req.query && req.query.widget) || '') === '1';
+  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);
+
+  // Username map (needed for widget tooltip: "Réservée par ...")
+  let uidToUsername = {};
+  try {
+    const uids = Array.from(new Set((reservations || [])
+      .map((r) => String((r && r.uid) || ''))
+      .filter(Boolean)));
+    if (uids.length) {
+      let rows = [];
+      if (typeof user.getUsersFields === 'function') {
+        rows = await user.getUsersFields(uids, ['username']);
+        // Some NodeBB versions omit uid in returned rows; re-attach from input order.
+        if (Array.isArray(rows)) {
+          rows = rows.map((row, idx) => (row ? Object.assign({ uid: uids[idx] }, row) : null));
+        }
+      } else {
+        rows = await Promise.all(uids.map(async (uid) => {
+          try { return Object.assign({ uid }, await user.getUserFields(uid, ['username'])); } catch (e) { return { uid, username: '' }; }
+        }));
+      }
+      uidToUsername = (rows || []).reduce((acc, row) => {
+        if (row && row.uid) acc[String(row.uid)] = String(row.username || '');
+        return acc;
+      }, {});
+    }
+  } catch (e) {}
+  for (const r of (reservations || [])) {
+    if (!r) continue;
+    if (!r.username && r.uid && uidToUsername[String(r.uid)]) {
+      r.username = uidToUsername[String(r.uid)];
+    }
+    // Only show active statuses
+    if (!['pending', 'awaiting_payment', 'paid'].includes(r.status)) continue;
+    // Overlap check
+    // Prefer date-only strings (YYYY-MM-DD) for 100% reliable calendar-day logic.
+    const rStartYmd = (r.startDate && /^\d{4}-\d{2}-\d{2}$/.test(String(r.startDate))) ? String(r.startDate) : null;
+    const rEndYmd = (r.endDate && /^\d{4}-\d{2}-\d{2}$/.test(String(r.endDate))) ? String(r.endDate) : null;
+
+    if (qStartYmd && qEndYmd && rStartYmd && rEndYmd) {
+      // endDate is EXCLUSIVE (FullCalendar rule): overlap iff aStart < bEnd && bStart < aEnd
+      if (!(rStartYmd < qEndYmd && qStartYmd < rEndYmd)) continue;
+    } else {
+      const rStart = parseInt(r.start, 10);
+      const rEnd = parseInt(r.end, 10);
+      if (!(rStart < endTs && startTs < rEnd)) continue;
+    }
+    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,
+          // Needed client-side to gray out unavailable items in the reservation modal.
+          // Not sensitive: it is already visible in event titles and prevents double booking.
+          itemIds: Array.isArray(p.itemIds) ? p.itemIds.map(String) : [],
+          itemIdLine: p.itemIdLine ? String(p.itemIdLine) : '',
+          canModerate: canMod,
+          ...(widgetMode ? { reservedByUsername: String(r.username || '') } : {}),
+        },
+      };
+      // 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' });
+
+  // Idempotence: if already refused, return ok.
+  if (String(r.status) === 'refused') {
+    return res.json({ ok: true, status: 'refused' });
+  }
+
+  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);
+
+  // Maintenance (simple ON/OFF per item)
+  let maint = new Set();
+  try {
+    const ids = await dbLayer.listMaintenanceItemIds(20000);
+    maint = new Set((ids || []).map(String));
+  } catch (e) {}
+
+  const out = normalized.map((it) => Object.assign({}, it, {
+    maintenance: maint.has(String(it.id)),
+  }));
+
+  res.json(out);
+};
+
+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 isValidator = await canValidate(uid, settings);
+
+  const startRaw = req.body.start;
+  const endRaw = req.body.end;
+  const start = parseInt(toTs(startRaw), 10);
+  const end = parseInt(toTs(endRaw), 10);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+    return res.status(400).json({ error: "bad-dates" });
+  }
+
+  // Keep the original date-only strings when available. This allows
+  // calendar-day calculations that are 100% independent of hours/timezones/DST.
+  const startDate = (typeof startRaw === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(startRaw.trim())) ? startRaw.trim() : null;
+  const endDate = (typeof endRaw === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(endRaw.trim())) ? endRaw.trim() : null;
+
+  // Validators can create "free" reservations that skip the payment workflow.
+  // However, long rentals should follow the normal paid workflow.
+  // Setting: validatorFreeMaxDays (days, endDate exclusive). If empty/0 => always free.
+  let validatorFreeMaxDays = 0;
+  try {
+    const v = parseInt(String(settings.validatorFreeMaxDays || '').trim(), 10);
+    validatorFreeMaxDays = Number.isFinite(v) ? v : 0;
+  } catch (e) {
+    validatorFreeMaxDays = 0;
+  }
+
+  // Reliable calendar-day count (endDate is EXCLUSIVE)
+  const nbDays = (startDate && endDate) ? (calendarDaysExclusiveYmd(startDate, endDate) || 1) : Math.max(1, Math.round((end - start) / (24 * 60 * 60 * 1000)));
+
+  // A validator is "free" only if the rental duration is within the configured threshold.
+  const isValidatorFree = !!isValidator && (validatorFreeMaxDays <= 0 || nbDays <= validatorFreeMaxDays);
+
+  // Business rule: a reservation cannot start on the current day or in the past.
+  // We compare against server-local midnight. (Front-end also prevents it.)
+  try {
+    const today0 = new Date();
+    today0.setHours(0, 0, 0, 0);
+    const tomorrow0 = today0.getTime() + 24 * 60 * 60 * 1000;
+    if (start < tomorrow0) {
+      return res.status(400).json({
+        error: 'date-too-soon',
+        message: "Impossible de réserver pour aujourd’hui ou une date passée.",
+      });
+    }
+  } catch (e) {
+    // If anything goes wrong, fail safe by allowing the normal flow.
+  }
+
+  // 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' });
+  }
+
+  // Maintenance block (simple ON/OFF, no dates): reject if any selected item is in maintenance.
+  try {
+    const maintIds = new Set(((await dbLayer.listMaintenanceItemIds(20000)) || []).map(String));
+    const blockedByMaintenance = itemIds.filter((id) => maintIds.has(String(id)));
+    if (blockedByMaintenance.length) {
+      return res.status(409).json({
+        error: 'in-maintenance',
+        itemIds: blockedByMaintenance,
+        message: "Un ou plusieurs matériels sont en maintenance.",
+      });
+    }
+  } catch (e) {}
+
+  // 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 exStartYmd = (existing.startDate && /^\d{4}-\d{2}-\d{2}$/.test(String(existing.startDate))) ? String(existing.startDate) : null;
+    const exEndYmd = (existing.endDate && /^\d{4}-\d{2}-\d{2}$/.test(String(existing.endDate))) ? String(existing.endDate) : null;
+    if (startDate && endDate && exStartYmd && exEndYmd) {
+      // endDate is EXCLUSIVE: overlap iff aStart < bEnd && bStart < aEnd
+      if (!(exStartYmd < endDate && startDate < exEndYmd)) continue;
+    } else {
+      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,
+    startDate,
+    endDate,
+    status: isValidatorFree ? 'paid' : 'pending',
+    createdAt: now,
+    paidAt: isValidatorFree ? now : 0,
+    approvedBy: isValidatorFree ? uid : 0,
+    // total is used for accounting (paid reservations).
+    // Validator self-reservations are FREE (no payment required) and must not be
+    // counted as revenue.
+    isFree: !!isValidatorFree,
+    total: isValidatorFree ? 0 : (isNaN(total) ? 0 : total),
+  };
+
+  // NOTE: We intentionally do NOT compute a monetary total for validator self-reservations.
+  // Those are free "sorties" and are tracked separately in the accounting view.
+
+  // Save
+  await dbLayer.saveReservation(resv);
+
+  // Audit
+  await auditLog(isValidatorFree ? 'reservation_self_checked' : 'reservation_requested', uid, {
+    targetType: 'reservation',
+    targetId: String(resv.rid),
+    uid: Number(uid) || 0,
+    requesterUid: Number(uid) || 0,
+    requesterUsername: username || '',
+    itemIds: resv.itemIds || [],
+    itemNames: resv.itemNames || [],
+    startDate: resv.startDate || '',
+    endDate: resv.endDate || '',
+    status: resv.status,
+  });
+
+  if (!isValidatorFree) {
+
+
+  // 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 getMembersByGroupIdentifier(g);
+        const uids = normalizeUids(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']);
+            // Some NodeBB versions omit uid in returned rows; re-attach it from input order.
+            if (Array.isArray(usersData)) {
+              usersData = usersData.map((row, idx) => (row ? Object.assign({ uid: uids[idx] }, row) : null));
+            }
+          } 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 || [])) {
+          const memberUid = md && (md.uid || md.userId || md.userid || md.user_id);
+          const u = parseInt(memberUid, 10);
+          if (Number.isInteger(u) && u > 0) {
+            await sendEmail('calendar-onekite_pending', u, 'Location matériel - Demande de réservation', {
+              uid: u,
+              username: md && md.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, status: resv.status, autoPaid: !!isValidatorFree });
+};
+
+// 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' });
+  // Idempotence: if already approved (awaiting payment or paid), return ok.
+  if (r.status !== 'pending') {
+    if (['awaiting_payment', 'approved', 'paid'].includes(String(r.status))) {
+      return res.json({ ok: true, status: r.status });
+    }
+    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);
+
+    // Reliable calendar-day count (end is EXCLUSIVE, FullCalendar rule)
+    const days = calendarDaysExclusiveYmd(r.startDate, r.endDate) || 1;
+
+    // Recompute total from HelloAsso catalog to avoid any dependency on hours/DST
+    // and to ensure checkout amount is always consistent.
+    let recomputedTotalCents = null;
+    try {
+      const { items: catalog } = await helloasso.listCatalogItems({
+        env: settings2.helloassoEnv,
+        token,
+        organizationSlug: settings2.helloassoOrganizationSlug,
+        formType: settings2.helloassoFormType,
+        formSlug: autoFormSlugForYear(year),
+      });
+      const byId = new Map((catalog || []).map((it) => [String(it.id), (typeof it.price === 'number' ? it.price : 0)]));
+      const ids = (Array.isArray(r.itemIds) ? r.itemIds : (r.itemId ? [r.itemId] : [])).map(String);
+      const sumCentsPerDay = ids.reduce((acc, id) => acc + (byId.get(String(id)) || 0), 0);
+      if (sumCentsPerDay > 0) {
+        recomputedTotalCents = Math.max(0, Math.round(sumCentsPerDay * days));
+        // Keep stored total in sync (euros) for emails/UX.
+        r.total = recomputedTotalCents / 100;
+      }
+    } catch (e) {
+      // ignore recompute failures; fallback to stored total
+    }
+
+    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 = (typeof recomputedTotalCents === 'number')
+          ? recomputedTotalCents
+          : 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);
+
+  await auditLog('reservation_approved', uid, {
+    targetType: 'reservation',
+    targetId: String(rid),
+    reservationUid: Number(r.uid) || 0,
+    reservationUsername: String(r.username || ''),
+    itemIds: r.itemIds || (r.itemId ? [r.itemId] : []),
+    itemNames: r.itemNames || (r.itemName ? [r.itemName] : []),
+    startDate: r.startDate || '',
+    endDate: r.endDate || '',
+    status: r.status,
+  });
+
+  // Email requester
+  const requesterUid = parseInt(r.uid, 10);
+  const requester = await user.getUserFields(requesterUid, ['username']);
+  if (requesterUid) {
+    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', requesterUid, 'Location matériel - Réservation validée', {
+      uid: requesterUid,
+      username: requester && requester.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();
+  try {
+    const refuser = await user.getUserFields(uid, ['username']);
+    r.refusedBy = uid;
+    r.refusedByUsername = refuser && refuser.username ? refuser.username : '';
+  } catch (e) {
+    r.refusedBy = uid;
+    r.refusedByUsername = '';
+  }
+  await dbLayer.saveReservation(r);
+
+  await auditLog('reservation_refused', uid, {
+    targetType: 'reservation',
+    targetId: String(rid),
+    reservationUid: Number(r.uid) || 0,
+    reservationUsername: String(r.username || ''),
+    itemIds: r.itemIds || (r.itemId ? [r.itemId] : []),
+    itemNames: r.itemNames || (r.itemName ? [r.itemName] : []),
+    startDate: r.startDate || '',
+    endDate: r.endDate || '',
+    reason: r.refusedReason || '',
+    status: r.status,
+  });
+
+  const requesterUid2 = parseInt(r.uid, 10);
+  const requester = await user.getUserFields(requesterUid2, ['username']);
+  if (requesterUid2) {
+    await sendEmail('calendar-onekite_refused', requesterUid2, 'Location matériel - Demande de réservation', {
+      uid: requesterUid2,
+      username: requester && requester.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;
+
+  try {
+    const canceller = await user.getUserFields(uid, ['username']);
+    r.cancelledByUsername = canceller && canceller.username ? canceller.username : '';
+  } catch (e) {
+    r.cancelledByUsername = '';
+  }
+
+  await dbLayer.saveReservation(r);
+
+  await auditLog('reservation_cancelled', uid, {
+    targetType: 'reservation',
+    targetId: String(rid),
+    reservationUid: Number(r.uid) || 0,
+    reservationUsername: String(r.username || ''),
+    itemIds: r.itemIds || (r.itemId ? [r.itemId] : []),
+    itemNames: r.itemNames || (r.itemName ? [r.itemName] : []),
+    startDate: r.startDate || '',
+    endDate: r.endDate || '',
+    status: r.status,
+  });
+
+  // Discord webhook (optional)
+  try {
+    await discord.notifyReservationCancelled(settings, {
+      rid: r.rid,
+      uid: r.uid,
+      username: r.username || '',
+      itemIds: r.itemIds || [],
+      itemNames: r.itemNames || [],
+      start: r.start,
+      end: r.end,
+      status: r.status,
+      cancelledAt: r.cancelledAt,
+      cancelledBy: r.cancelledBy,
+      cancelledByUsername: r.cancelledByUsername || '',
+    });
+  } catch (e) {}
+
+
+  // Email requester
+  try {
+    const requesterUid = parseInt(r.uid, 10);
+    const requester = await user.getUserFields(requesterUid, ['username']);
+    const canceller = await user.getUserFields(uid, ['username']);
+    if (requesterUid) {
+      await sendEmail('calendar-onekite_cancelled', requesterUid, 'Location matériel - Réservation annulée', {
+        uid: requesterUid,
+        username: requester && requester.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)}`,
+        cancelledBy: (r.cancelledByUsername || (canceller && canceller.username) || ''),
+        cancelledByUrl: ((r.cancelledByUsername || (canceller && canceller.username)) ? `${normalizeBaseUrl(meta)}/user/${encodeURIComponent(String(r.cancelledByUsername || canceller.username))}` : ''),
+      });
+    }
+  } catch (e) {}
+
+  return res.json({ ok: true, status: 'cancelled' });
+};
+
+// --------------------
+// Maintenance (simple ON/OFF)
+// --------------------
+
+api.getMaintenance = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const ids = await dbLayer.listMaintenanceItemIds(20000);
+  return res.json({ itemIds: (ids || []).map(String) });
+};
+
+api.setMaintenance = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const itemId = String(req.params.itemId || '').trim();
+  if (!itemId) return res.status(400).json({ error: 'missing-itemId' });
+  const enabled = !!(req.body && (req.body.enabled === true || req.body.enabled === '1' || req.body.enabled === 1));
+  await dbLayer.setItemMaintenance(itemId, enabled);
+  await auditLog(enabled ? 'maintenance_on' : 'maintenance_off', uid, {
+    targetType: 'item',
+    targetId: itemId,
+  });
+  return res.json({ ok: true, itemId, enabled });
+};
+
+// Bulk toggle: enable/disable maintenance for ALL catalog items.
+// Uses the same permission as validate/delete.
+api.setMaintenanceAll = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+
+  const enabled = !!(req.body && (req.body.enabled === true || req.body.enabled === '1' || req.body.enabled === 1));
+
+  // When enabling, we need the current catalog IDs (HelloAsso shop)
+  let catalogIds = [];
+  if (enabled) {
+    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) {
+      return res.status(400).json({ error: 'helloasso-token-missing' });
+    }
+    const year = new Date().getFullYear();
+    const { items: catalog } = await helloasso.listCatalogItems({
+      env,
+      token,
+      organizationSlug: settings.helloassoOrganizationSlug,
+      formType: settings.helloassoFormType,
+      formSlug: autoFormSlugForYear(year),
+    });
+    catalogIds = (catalog || []).map((it) => it && it.id).filter(Boolean).map(String);
+  }
+
+  const result = await dbLayer.setAllMaintenance(enabled, catalogIds);
+  await auditLog(enabled ? 'maintenance_all_on' : 'maintenance_all_off', uid, {
+    targetType: 'maintenance',
+    targetId: enabled ? 'all_on' : 'all_off',
+    count: result && typeof result.count === 'number' ? result.count : (enabled ? catalogIds.length : 0),
+  });
+  return res.json(Object.assign({ ok: true, enabled }, result || {}));
+};
+
+// --------------------
+// Audit
+// --------------------
+
+api.getAudit = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const year = Number((req.query && req.query.year) || new Date().getFullYear());
+  const limit = Math.min(500, Math.max(1, Number((req.query && req.query.limit) || 200)));
+  const entries = await dbLayer.getAuditEntriesByYear(year, limit);
+  return res.json({ year, entries: entries || [] });
+};
+
+api.purgeAudit = async function (req, res) {
+  const uid = req.uid;
+  const ok = uid ? await canModerate(uid) : false;
+  if (!ok) return res.status(403).json({ error: 'not-allowed' });
+  const year = Number((req.body && req.body.year) || 0);
+  if (!year) return res.status(400).json({ error: 'missing-year' });
+  const result = await dbLayer.purgeAuditYear(year);
+  await auditLog('audit_purge_year', uid, { targetType: 'audit', targetId: String(year), removed: result && result.removed ? result.removed : 0 });
+  return res.json(result || { ok: true });
+};
+
+module.exports = api;