nodebb-plugin-calendar-onekite 10.0.17 → 10.0.18

package/README.md

@@ -0,0 +1,42 @@
+# nodebb-plugin-calendar-onekite
+
+Plugin NodeBB (testé avec NodeBB v4.x) qui ajoute un calendrier de réservation de matériel basé sur FullCalendar.
+
+## Fonctionnalités
+
+- Page publique: `/calendar`
+- Création de demandes de réservation (clic ou sélection de plage)
+- Blocage temporaire des demandes en attente (expiration automatique)
+- Validation/refus via l'ACP
+- Synchronisation des items (matériel + prix) depuis HelloAsso
+- Création de checkout-intents HelloAsso lors de la validation
+- Purge du calendrier par année
+
+## Installation
+
+Dans le dossier NodeBB:
+
+```bash
+npm install /path/to/nodebb-plugin-calendar-onekite
+./nodebb build
+./nodebb restart
+```
+
+Activez le plugin dans l'ACP.
+
+## Configuration (ACP)
+
+ACP → Plugins → Calendar (OneKite)
+
+- Groupes autorisés à demander une réservation (CSV)
+- Groupes notifiés par email (CSV)
+- Durée de blocage en attente (minutes)
+- Paramètres HelloAsso (sandbox/prod, clientId/secret, organizationSlug, formType, formSlug, returnURL, ...)
+
+## Webhook HelloAsso
+
+Endpoint: `/api/calendar-onekite/helloasso/webhook`
+
+> Le plugin fournit un endpoint minimal pour marquer une réservation comme payée à partir d'un `checkoutIntentId`.
+> Adaptez-le selon votre stratégie (notification HelloAsso / polling / etc.).
+

package/lib/controllers.js

@@ -0,0 +1,534 @@
+'use strict';
+
+const axios = require('axios');
+
+const db = require.main.require('./src/database');
+const meta = require.main.require('./src/meta');
+const groups = require.main.require('./src/groups');
+const user = require.main.require('./src/user');
+const emailer = require.main.require('./src/emailer');
+const plugins = require.main.require('./src/plugins');
+const winston = require.main.require('./src/logger');
+const nconf = require.main.require('nconf');
+
+const SETTINGS_KEY = 'calendar-onekite';
+const RES_COUNTER_KEY = 'calendar-onekite:nextid';
+const RES_HASH_PREFIX = 'calendar-onekite:res:';
+const RES_ZSET_BY_START = 'calendar-onekite:res:byStart';
+const ITEMS_KEY = 'calendar-onekite:items';
+
+let backgroundStarted = false;
+
+function nowMs() {
+  return Date.now();
+}
+
+function parseCsv(str) {
+  return (str || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+async function getSettings() {
+  const defaults = {
+    requesterGroups: 'registered-users',
+    notifyGroups: 'administrators',
+    pendingHoldMinutes: '5',
+    apiEnv: 'sandbox',
+    helloassoClientId: '',
+    helloassoClientSecret: '',
+    helloassoOrganizationSlug: '',
+    helloassoFormType: '',
+    helloassoFormSlug: '',
+    helloassoReturnUrl: '',
+    helloassoBackUrl: '',
+    helloassoErrorUrl: '',
+    helloassoWebhookSecret: ''
+  };
+  const settings = await meta.settings.get(SETTINGS_KEY);
+  return Object.assign({}, defaults, settings || {});
+}
+
+function helloAssoBaseUrl(apiEnv) {
+  // HelloAsso docs show api.helloasso.com & api.helloasso-sandbox.com
+  return apiEnv === 'prod' ? 'https://api.helloasso.com' : 'https://api.helloasso-sandbox.com';
+}
+
+async function helloAssoGetToken(settings) {
+  const base = helloAssoBaseUrl(settings.apiEnv);
+  const url = `${base}/oauth2/token`;
+  const body = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: settings.helloassoClientId,
+    client_secret: settings.helloassoClientSecret,
+  });
+  const res = await axios.post(url, body, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
+  return res.data.access_token;
+}
+
+async function helloAssoFetchItems(settings) {
+  const token = await helloAssoGetToken(settings);
+  const base = helloAssoBaseUrl(settings.apiEnv);
+  const url = `${base}/v5/organizations/${encodeURIComponent(settings.helloassoOrganizationSlug)}/forms/${encodeURIComponent(settings.helloassoFormType)}/${encodeURIComponent(settings.helloassoFormSlug)}/items`;
+  const res = await axios.get(url, { headers: { Authorization: `Bearer ${token}` } });
+  // Normalise to our format
+  const items = (res.data?.data || res.data || []).map(it => ({
+    id: String(it.id ?? it.itemId ?? it.item?.id ?? ''),
+    name: it.name ?? it.itemName ?? it.item?.name ?? 'Item',
+    price: (it.price ?? it.amount ?? it.unitPrice ?? 0),
+    raw: it,
+  })).filter(it => it.id);
+  return items;
+}
+
+async function helloAssoCreateCheckoutIntent(settings, reservation) {
+  const token = await helloAssoGetToken(settings);
+  const base = helloAssoBaseUrl(settings.apiEnv);
+  const url = `${base}/v5/organizations/${encodeURIComponent(settings.helloassoOrganizationSlug)}/checkout-intents`;
+
+  const amountCents = Number(reservation.priceCents || 0);
+  const body = {
+    totalAmount: amountCents,
+    initialAmount: amountCents,
+    itemName: reservation.itemName,
+    backUrl: settings.helloassoBackUrl || undefined,
+    errorUrl: settings.helloassoErrorUrl || undefined,
+    returnUrl: settings.helloassoReturnUrl || undefined,
+    metadata: {
+      source: 'nodebb-plugin-calendar-onekite',
+      reservationId: reservation.id,
+      uid: reservation.uid,
+    },
+  };
+
+  const res = await axios.post(url, body, { headers: { Authorization: `Bearer ${token}` } });
+  return {
+    checkoutIntentId: String(res.data?.id ?? res.data?.checkoutIntentId ?? ''),
+    redirectUrl: res.data?.redirectUrl || res.data?.url || res.data?.paymentUrl || res.data?.redirect || null,
+    raw: res.data,
+  };
+}
+
+async function reservationKey(id) {
+  return `${RES_HASH_PREFIX}${id}`;
+}
+
+async function getNextReservationId() {
+  const id = await db.incrObjectField('global', RES_COUNTER_KEY);
+  return String(id);
+}
+
+async function loadReservation(id) {
+  const data = await db.getObject(await reservationKey(id));
+  if (!data || !data.id) return null;
+  // Convert some fields
+  data.start = Number(data.start);
+  data.end = Number(data.end);
+  data.createdAt = Number(data.createdAt);
+  data.updatedAt = Number(data.updatedAt);
+  data.expiresAt = Number(data.expiresAt || 0);
+  data.priceCents = Number(data.priceCents || 0);
+  return data;
+}
+
+async function saveReservation(reservation) {
+  reservation.updatedAt = nowMs();
+  await db.setObject(await reservationKey(reservation.id), reservation);
+  await db.sortedSetAdd(RES_ZSET_BY_START, reservation.start, reservation.id);
+}
+
+async function deleteReservation(id) {
+  await db.delete(await reservationKey(id));
+  await db.sortedSetRemove(RES_ZSET_BY_START, id);
+}
+
+function isExpiredPending(reservation) {
+  return reservation.status === 'pending' && reservation.expiresAt && reservation.expiresAt <= nowMs();
+}
+
+async function expirePendingReservations() {
+  try {
+    // Scan last ~180 days (fast enough). If you need bigger, you can widen.
+    const to = nowMs();
+    const from = to - 180 * 24 * 60 * 60 * 1000;
+    const ids = await db.getSortedSetRangeByScore(RES_ZSET_BY_START, 0, -1, from, to);
+    for (const id of ids) {
+      const r = await loadReservation(id);
+      if (r && isExpiredPending(r)) {
+        r.status = 'expired';
+        await saveReservation(r);
+      }
+    }
+  } catch (e) {
+    winston.error(`[calendar-onekite] expire job error: ${e.message}`);
+  }
+}
+
+async function userInAllowedGroups(uid, allowedGroups) {
+  const groupNames = parseCsv(allowedGroups);
+  for (const g of groupNames) {
+    try {
+      const isMember = await groups.isMember(uid, g);
+      if (isMember) return true;
+    } catch (e) {
+      // ignore missing group
+    }
+  }
+  return false;
+}
+
+async function notifyGroupsByEmail(groupList, subject, body) {
+  const groupNames = parseCsv(groupList);
+  const uids = new Set();
+
+  for (const g of groupNames) {
+    try {
+      const members = await groups.getMembers(g, 0, 10000);
+      for (const m of members) uids.add(m.uid);
+    } catch (e) {
+      // ignore
+    }
+  }
+
+  if (!uids.size) return;
+
+  const users = await user.getUsersFields([...uids], ['email', 'username', 'uid']);
+  const emails = users.map(u => u.email).filter(Boolean);
+  if (!emails.length) return;
+
+  // NodeBB's emailer expects a template usually. We'll use sendToEmail with raw text as fallback.
+  // If sendToEmail isn't available, we log.
+  if (typeof emailer.sendToEmail === 'function') {
+    await Promise.all(emails.map(email => emailer.sendToEmail('calendar-onekite', email, {
+      subject,
+      text: body,
+    }).catch(() => {})));
+  } else if (typeof emailer.send === 'function') {
+    await Promise.all(emails.map(email => emailer.send('calendar-onekite', email, {
+      subject,
+      text: body,
+    }).catch(() => {})));
+  } else {
+    winston.warn('[calendar-onekite] emailer API not found on this NodeBB version');
+  }
+}
+
+function toFullCalendarEvent(r) {
+  const titleParts = [r.itemName];
+  if (r.status === 'pending') titleParts.push('⏳');
+  if (r.status === 'awaiting_payment') titleParts.push('✅ 💳');
+  if (r.status === 'paid') titleParts.push('✅');
+  if (r.status === 'refused') titleParts.push('❌');
+  if (r.status === 'expired') titleParts.push('⌛');
+
+  return {
+    id: r.id,
+    title: titleParts.join(' '),
+    start: new Date(r.start).toISOString(),
+    end: new Date(r.end).toISOString(),
+    allDay: false,
+    extendedProps: {
+      status: r.status,
+      itemId: r.itemId,
+      itemName: r.itemName,
+      priceCents: r.priceCents,
+      uid: r.uid,
+      username: r.username,
+      paymentUrl: r.paymentUrl || null,
+    },
+  };
+}
+
+const controllers = {};
+
+controllers.ensureBackgroundJob = async function () {
+  if (backgroundStarted) return;
+  backgroundStarted = true;
+  // Periodically expire pending holds
+  setInterval(expirePendingReservations, 60 * 1000).unref();
+  // One immediate run
+  expirePendingReservations();
+};
+
+controllers.renderCalendar = async function (req, res) {
+  const settings = await getSettings();
+  res.render('calendar', {
+    title: 'Calendrier',
+    calendarOnekite: {
+      requesterGroups: settings.requesterGroups,
+    },
+  });
+};
+
+controllers.renderAdmin = async function (req, res) {
+  const settings = await getSettings();
+  res.render('admin/plugins/calendar-onekite', {
+    title: 'Calendar (OneKite)',
+    settings,
+  });
+};
+
+controllers.apiGetSettings = async function (req, res) {
+  const settings = await getSettings();
+  // Only expose non-secrets
+  res.json({
+    requesterGroups: settings.requesterGroups,
+    pendingHoldMinutes: Number(settings.pendingHoldMinutes || 5),
+    apiEnv: settings.apiEnv,
+    orgSlug: settings.helloassoOrganizationSlug,
+    formType: settings.helloassoFormType,
+    formSlug: settings.helloassoFormSlug,
+  });
+};
+
+controllers.apiGetItems = async function (req, res) {
+  const items = await db.getObjectField('global', ITEMS_KEY);
+  let parsed = [];
+  try {
+    parsed = JSON.parse(items || '[]');
+  } catch (e) {}
+  res.json({ items: parsed });
+};
+
+controllers.apiListReservations = async function (req, res) {
+  await expirePendingReservations();
+  const start = req.query.start ? Date.parse(req.query.start) : null;
+  const end = req.query.end ? Date.parse(req.query.end) : null;
+  const from = Number.isFinite(start) ? start : (nowMs() - 30 * 24 * 60 * 60 * 1000);
+  const to = Number.isFinite(end) ? end : (nowMs() + 180 * 24 * 60 * 60 * 1000);
+
+  const ids = await db.getSortedSetRangeByScore(RES_ZSET_BY_START, 0, -1, from, to);
+  const reservations = (await Promise.all(ids.map(loadReservation))).filter(Boolean);
+  const events = reservations
+    .filter(r => r.status !== 'cancelled')
+    .map(toFullCalendarEvent);
+
+  res.json(events);
+};
+
+controllers.apiCreateReservation = async function (req, res) {
+  const settings = await getSettings();
+  const uid = req.uid;
+
+  const allowed = await userInAllowedGroups(uid, settings.requesterGroups);
+  if (!allowed) {
+    return res.status(403).json({ error: 'not-allowed' });
+  }
+
+  const { itemId, itemName, priceCents, start, end } = req.body || {};
+  const startMs = Number(start);
+  const endMs = Number(end);
+
+  if (!itemId || !itemName || !Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs <= startMs) {
+    return res.status(400).json({ error: 'invalid-payload' });
+  }
+
+  // Ensure not already booked (pending/awaiting_payment/paid) overlapping on the same item
+  await expirePendingReservations();
+  const overlapIds = await db.getSortedSetRangeByScore(RES_ZSET_BY_START, 0, -1, startMs - 365 * 24 * 60 * 60 * 1000, endMs);
+  for (const id of overlapIds) {
+    const r = await loadReservation(id);
+    if (!r) continue;
+    const active = ['pending', 'awaiting_payment', 'paid'].includes(r.status);
+    const overlaps = r.itemId === String(itemId) && r.start < endMs && r.end > startMs;
+    if (active && overlaps) {
+      return res.status(409).json({ error: 'already-booked' });
+    }
+  }
+
+  const id = await getNextReservationId();
+  const u = await user.getUserFields(uid, ['username']);
+  const holdMinutes = Math.max(1, Number(settings.pendingHoldMinutes || 5));
+  const reservation = {
+    id,
+    uid: String(uid),
+    username: u.username || 'user',
+    itemId: String(itemId),
+    itemName: String(itemName),
+    priceCents: Number(priceCents || 0),
+    start: startMs,
+    end: endMs,
+    status: 'pending',
+    createdAt: nowMs(),
+    updatedAt: nowMs(),
+    expiresAt: nowMs() + holdMinutes * 60 * 1000,
+  };
+
+  await saveReservation(reservation);
+
+  // Notify admins by email
+  const subject = `[OneKite] Nouvelle demande de réservation (#${id})`;
+  const body = `Une nouvelle demande de réservation a été créée.
+
+Matériel: ${reservation.itemName}
+Début: ${new Date(reservation.start).toLocaleString()}
+Fin: ${new Date(reservation.end).toLocaleString()}
+Utilisateur: ${reservation.username} (uid ${reservation.uid})
+
+À valider/refuser dans l'ACP: /admin/plugins/calendar-onekite`;
+  notifyGroupsByEmail(settings.notifyGroups, subject, body).catch(() => {});
+
+  res.json({ ok: true, id, status: reservation.status, expiresAt: reservation.expiresAt });
+};
+
+controllers.apiCancelReservation = async function (req, res) {
+  const id = req.params.id;
+  const r = await loadReservation(id);
+  if (!r) return res.status(404).json({ error: 'not-found' });
+
+  const isOwner = String(r.uid) === String(req.uid);
+  const isAdmin = req.user && req.user.isAdmin;
+  if (!isOwner && !isAdmin) return res.status(403).json({ error: 'forbidden' });
+
+  r.status = 'cancelled';
+  await saveReservation(r);
+  res.json({ ok: true });
+};
+
+controllers.apiAdminListPending = async function (req, res) {
+  await expirePendingReservations();
+  const to = nowMs() + 365 * 24 * 60 * 60 * 1000;
+  const from = nowMs() - 90 * 24 * 60 * 60 * 1000;
+  const ids = await db.getSortedSetRangeByScore(RES_ZSET_BY_START, 0, -1, from, to);
+  const reservations = (await Promise.all(ids.map(loadReservation))).filter(Boolean);
+  res.json({
+    pending: reservations.filter(r => r.status === 'pending'),
+    awaiting_payment: reservations.filter(r => r.status === 'awaiting_payment'),
+  });
+};
+
+controllers.apiAdminSaveSettings = async function (req, res) {
+  try {
+    const current = await getSettings();
+    const toSave = { ...current, ...(req.body || {}) };
+    // Do not allow purging settings key from request
+    delete toSave.purgeYear;
+
+    await meta.settings.set(SETTINGS_KEY, toSave);
+    res.json({ ok: true });
+  } catch (err) {
+    winston.error('[calendar-onekite] failed to save settings: ' + err.message);
+    res.status(500).json({ error: err.message });
+  }
+};
+
+controllers.apiApproveReservation = async function (req, res) {
+  const id = req.params.id;
+  const settings = await getSettings();
+  const r = await loadReservation(id);
+  if (!r) return res.status(404).json({ error: 'not-found' });
+  if (r.status !== 'pending') return res.status(409).json({ error: 'invalid-status' });
+  if (isExpiredPending(r)) {
+    r.status = 'expired';
+    await saveReservation(r);
+    return res.status(409).json({ error: 'expired' });
+  }
+
+  // Create checkout intent (if HelloAsso configured)
+  let payment = null;
+  if (settings.helloassoClientId && settings.helloassoClientSecret && settings.helloassoOrganizationSlug) {
+    try {
+      payment = await helloAssoCreateCheckoutIntent(settings, r);
+    } catch (e) {
+      winston.error(`[calendar-onekite] helloasso checkout intent failed: ${e.message}`);
+    }
+  }
+
+  r.status = 'awaiting_payment';
+  r.approvedBy = String(req.uid);
+  r.checkoutIntentId = payment?.checkoutIntentId || '';
+  r.paymentUrl = payment?.redirectUrl || '';
+  await saveReservation(r);
+
+  // Notify requester (email if available)
+  try {
+    const u = await user.getUserFields(Number(r.uid), ['email', 'username']);
+    if (u.email) {
+      const subject = `[OneKite] Réservation validée (#${r.id})`;
+      const body = `Votre réservation a été validée.
+
+Matériel: ${r.itemName}
+Début: ${new Date(r.start).toLocaleString()}
+Fin: ${new Date(r.end).toLocaleString()}
+
+Lien de paiement: ${r.paymentUrl || '(non disponible)'}
+
+Merci.`;
+      await notifyGroupsByEmail('', subject, body); // no-op
+      if (typeof emailer.sendToEmail === 'function') {
+        await emailer.sendToEmail('calendar-onekite', u.email, { subject, text: body });
+      }
+    }
+  } catch (e) {}
+
+  res.json({ ok: true, paymentUrl: r.paymentUrl || null });
+};
+
+controllers.apiRefuseReservation = async function (req, res) {
+  const id = req.params.id;
+  const r = await loadReservation(id);
+  if (!r) return res.status(404).json({ error: 'not-found' });
+  if (r.status !== 'pending') return res.status(409).json({ error: 'invalid-status' });
+
+  r.status = 'refused';
+  r.refusedBy = String(req.uid);
+  await saveReservation(r);
+
+  res.json({ ok: true });
+};
+
+controllers.apiSyncItems = async function (req, res) {
+  const settings = await getSettings();
+  if (!settings.helloassoClientId || !settings.helloassoClientSecret || !settings.helloassoOrganizationSlug || !settings.helloassoFormType || !settings.helloassoFormSlug) {
+    return res.status(400).json({ error: 'missing-helloasso-settings' });
+  }
+
+  const items = await helloAssoFetchItems(settings);
+  await db.setObjectField('global', ITEMS_KEY, JSON.stringify(items));
+  res.json({ ok: true, count: items.length });
+};
+
+controllers.apiPurge = async function (req, res) {
+  const year = Number(req.body?.year);
+  if (!Number.isInteger(year) || year < 2000 || year > 2200) {
+    return res.status(400).json({ error: 'invalid-year' });
+  }
+  const from = Date.parse(`${year}-01-01T00:00:00.000Z`);
+  const to = Date.parse(`${year + 1}-01-01T00:00:00.000Z`);
+  const ids = await db.getSortedSetRangeByScore(RES_ZSET_BY_START, 0, -1, from, to);
+  for (const id of ids) {
+    await deleteReservation(id);
+  }
+  res.json({ ok: true, purged: ids.length });
+};
+
+controllers.apiHelloAssoWebhook = async function (req, res) {
+  // Basic webhook handler (must be configured on HelloAsso side).
+  const settings = await getSettings();
+  const secret = settings.helloassoWebhookSecret;
+  if (secret && req.headers['x-calendar-onekite-secret'] !== secret) {
+    return res.status(401).json({ error: 'unauthorized' });
+  }
+
+  const reservationId = req.body?.metadata?.reservationId || req.body?.reservationId;
+  const status = req.body?.status || req.body?.code || req.body?.eventType;
+
+  if (!reservationId) {
+    return res.status(400).json({ error: 'missing-reservationId' });
+  }
+
+  const r = await loadReservation(String(reservationId));
+  if (!r) return res.status(404).json({ error: 'not-found' });
+
+  // Heuristic: if webhook indicates succeeded, mark paid
+  const success = ['succeeded', 'paid', 'PAYMENT_SUCCEEDED', 'PaymentSucceeded'].includes(String(status));
+  if (success) {
+    r.status = 'paid';
+    await saveReservation(r);
+  }
+
+  res.json({ ok: true });
+};
+
+module.exports = controllers;

package/lib/routes.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const controllers = require('./controllers');
+
+module.exports.init = function (router, middleware) {
+  // Public calendar page
+  router.get('/calendar', middleware.buildHeader, controllers.renderCalendar);
+  router.get('/api/calendar', controllers.renderCalendar);
+
+  // Admin (ACP) page
+  router.get('/admin/plugins/calendar-onekite', middleware.admin.buildHeader, controllers.renderAdmin);
+  router.get('/api/admin/plugins/calendar-onekite', controllers.renderAdmin);
+
+  // Public API
+  router.get('/api/calendar-onekite/settings', controllers.apiGetSettings);
+  router.get('/api/calendar-onekite/items', controllers.apiGetItems);
+  router.get('/api/calendar-onekite/reservations', controllers.apiListReservations);
+  router.post('/api/calendar-onekite/reservations', middleware.ensureLoggedIn, controllers.apiCreateReservation);
+  router.delete('/api/calendar-onekite/reservations/:id', middleware.ensureLoggedIn, controllers.apiCancelReservation);
+
+  // Admin API
+  router.get('/api/admin/calendar-onekite/pending', middleware.admin.checkPrivileges, controllers.apiAdminListPending);
+  router.post('/api/admin/calendar-onekite/settings', middleware.admin.checkPrivileges, controllers.apiAdminSaveSettings);
+  router.put('/api/admin/calendar-onekite/reservations/:id/approve', middleware.admin.checkPrivileges, controllers.apiApproveReservation);
+  router.put('/api/admin/calendar-onekite/reservations/:id/refuse', middleware.admin.checkPrivileges, controllers.apiRefuseReservation);
+  router.post('/api/admin/calendar-onekite/sync-items', middleware.admin.checkPrivileges, controllers.apiSyncItems);
+  router.post('/api/admin/calendar-onekite/purge', middleware.admin.checkPrivileges, controllers.apiPurge);
+
+  // HelloAsso webhook
+  router.post('/api/calendar-onekite/helloasso/webhook', controllers.apiHelloAssoWebhook);
+};