@mostajs/events 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — @mostajs/events
+
+## [0.1.0] — 2026-06-22
+### Ajouté
+- Cœur métier événements : création (organisateur externe/entreprise/Hadhinat, gratuit/payant), publication, capacité/sièges.
+- Inscriptions + billets à jeton signé (HMAC) ; événement payant → compose `payment.charge`.
+- Contrôle d'accès `checkin.validate` à entrée unique (badge → used ; rejeu refusé ; jeton falsifié rejeté).
+- `createMemoryRepositories()` (dev/démo). 7 tests @mostajs/mjs-unit.
+- Encodeur QR extrait vers `@mostajs/qrpanel/qr-svg` (pur JS, vérifié contre le vecteur de référence ISO).
+
+[0.1.0]: #

package/README.md

@@ -0,0 +1,25 @@
+# @mostajs/events
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+
+Cœur métier **mince, zéro-dépendance** de gestion d'événements (salon, atelier, conférence) : événements (organisateur externe / entreprise hébergée / Hadhinat, **gratuit ou payant**), inscriptions, **billets**, et **contrôle d'accès par QR** (invitation / badge / check-in à entrée unique). Le rendu QR est délégué à `@mostajs/qrpanel/qr-svg` (séparation domaine / présentation).
+
+## Aperçu
+
+```js
+import { createEvents, createMemoryRepositories } from '@mostajs/events';
+import { qrSvg } from '@mostajs/qrpanel/qr-svg';
+
+const events = createEvents({ repositories: createMemoryRepositories(), numbering, payment, secret });
+const e = await events.events.create({ title: 'Salon', organizer: { type: 'hadhinat', name: 'Hadhinat' }, capacity: 200, fee: 0 });
+await events.events.publish(e.id);
+const { ticket } = await events.registrations.register(e.id, { name: 'Sami', email: 'sami@x.dz' });
+const badge = qrSvg(ticket.token);                 // QR de badge (SVG)
+const r = await events.checkin.validate(ticket.token);   // contrôle d'accès → { ok: true } (puis 'already_used')
+```
+
+## Tests
+`npm test` — @mostajs/mjs-unit (domaine événements ; le QR est testé dans @mostajs/qrpanel).
+
+## Licence
+AGPL-3.0-or-later · © Dr Hamid MADANI

package/llms.txt

@@ -0,0 +1,21 @@
+# @mostajs/events
+
+Cœur métier MINCE de gestion d'événements (salon/atelier/conférence) + contrôle d'accès par QR. Zéro-dépendance. Motif domaine mince (cf. @mostajs/incubator, @mostajs/advisory). Le RENDU QR est délégué à @mostajs/qrpanel/qr-svg (séparation domaine/présentation).
+
+## Façade
+`createEvents({ repositories:{events,registrations,tickets}, numbering?, payment?, audit?, secret, now? })`
+- `events.create({ title, organizer:{type:'external'|'company'|'hadhinat', name, companyId?}, startsAt, endsAt, venue, capacity, fee=0, description }) → event` (statut 'draft')
+- `events.publish/cancel/close(id)` · `events.get(id)` · `events.list(filtre)` · `events.seats(id) → {capacity,taken,remaining}`
+- `registrations.register(eventId, {name,email,phone}) → {registration, ticket, paid}` — refuse si non publié / complet / email manquant. Émet un BILLET avec jeton signé (charge utile QR badge). Événement PAYANT (fee>0) → compose `payment.charge` ; sans transport paiement → billet 'pending-payment'.
+- `registrations.list(eventId)` · `registrations.cancel(id)`
+- `tickets.get(id)` · `tickets.byRegistration(regId)` · `tickets.token(ticketId)`
+- `checkin.validate(token) → {ok, reason?, event, registration, ticket}` — signature OK + billet valide + non utilisé → marque 'used' (entrée unique). Rejeu → reason 'already_used' ; faux → 'bad_signature' ; impayé → 'unpaid'.
+- `checkin.peek(token)` (sans consommer) · `sign(payload)` / `verify(token)` (helpers QR)
+
+## 3 usages QR (rendus par l'app via @mostajs/qrpanel/qr-svg)
+1. **Invitation** : QR de l'URL publique de l'événement → scan = page d'inscription.
+2. **Badge** : QR du `ticket.token` (jeton signé) → présenté à l'entrée.
+3. **Contrôle d'accès** : le staff scanne le badge → `checkin.validate(token)`.
+
+## Composition
+numbering (n° EVT/TKT) · payment (events payants) · audit. Jeton = HMAC single-purpose (node:crypto). Repositories in-mem via `createMemoryRepositories()` (DB réelle via @mostajs/orm en prod).

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@mostajs/events",
+  "version": "0.1.0",
+  "description": "Cœur métier mince de gestion d'événements (salon/atelier/conférence) : événements (organisateur externe/entreprise/Hadhinat, gratuit ou payant), inscriptions, billets, et contrôle d'accès par QR (invitation/badge/check-in). Encodeur QR→SVG zéro-dépendance inclus. Compose numbering/payment/audit.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./qr": "./src/qr.js"
+  },
+  "keywords": [
+    "mostajs",
+    "events",
+    "ticketing",
+    "qrcode",
+    "qr",
+    "checkin",
+    "access-control",
+    "incubator"
+  ],
+  "devDependencies": {
+    "@mostajs/mjs-unit": "^0.3.0"
+  },
+  "scripts": {
+    "test": "bash test-scripts/run-tests.sh"
+  }
+}

package/src/events.js

@@ -0,0 +1,135 @@
+// @mostajs/events — cœur métier MINCE de gestion d'événements (salon, atelier, conférence). Author: Dr Hamid MADANI <drmdh@msn.com>
+// N'implémente QUE le domaine « événement + inscriptions + billets + contrôle d'accès par QR ». Motif domaine mince (cf. incubator/advisory).
+// COMPOSE (injecté, optionnel) : numbering (n° EVT/TKT), payment (événement PAYANT → charge), audit. Le RENDU QR est délégué à l'app (token signé → image).
+// Organisateur : externe | entreprise hébergée | Hadhinat. Billet GRATUIT ou PAYANT. 3 usages QR : invitation (inscription), badge (billet), contrôle d'accès (check-in).
+import crypto from 'node:crypto';
+
+const EVENT_STAGES = ['draft', 'published', 'closed', 'cancelled'];
+const ORG_TYPES = ['external', 'company', 'hadhinat'];
+
+// ── Jeton signé (HMAC single-purpose) : sert de charge utile au QR « badge » et au contrôle d'accès. ──
+function signTicket(secret, payload) {
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const sig = crypto.createHmac('sha256', secret).update(body).digest('base64url');
+  return `${body}.${sig}`;
+}
+function verifyTicket(secret, token) {
+  const parts = String(token || '').split('.');
+  if (parts.length !== 2) return { ok: false, reason: 'malformed' };
+  const [body, sig] = parts;
+  const expected = crypto.createHmac('sha256', secret).update(body).digest('base64url');
+  const a = Buffer.from(sig, 'base64url'); const b = Buffer.from(expected, 'base64url');
+  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return { ok: false, reason: 'bad_signature' };
+  try { return { ok: true, payload: JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) }; }
+  catch { return { ok: false, reason: 'malformed' }; }
+}
+
+export function createEvents({ repositories, numbering, payment, audit, secret = 'dev-events-secret-change-me', now = () => new Date() } = {}) {
+  if (!repositories?.events || !repositories?.registrations || !repositories?.tickets) {
+    throw new Error('createEvents: repositories.{events,registrations,tickets} requis');
+  }
+  const { events, registrations, tickets } = repositories;
+  const evtNo = () => (numbering?.next ? numbering.next('event') : `EVT-${now().getFullYear()}-${Math.floor(now().getTime() % 100000)}`);
+  const tktNo = () => (numbering?.next ? numbering.next('ticket') : `TKT-${now().getFullYear()}-${Math.floor(now().getTime() % 1000000)}`);
+  const trace = (type, data) => audit?.log?.({ type, ...data, at: now() });
+
+  const api = {
+    eventStages: EVENT_STAGES, organizerTypes: ORG_TYPES, secret,
+
+    events: {
+      /** Crée un événement (brouillon). organizer = { type:'external'|'company'|'hadhinat', name, companyId? }. fee=0 → gratuit. */
+      async create({ title, organizer = {}, startsAt = null, endsAt = null, venue = null, capacity = 0, fee = 0, description = null } = {}) {
+        if (!title) throw new Error('title (intitulé) requis');
+        if (organizer.type && !ORG_TYPES.includes(organizer.type)) throw new Error(`organizer.type inconnu: ${organizer.type}`);
+        const e = await events.create({
+          no: evtNo(), title, organizerType: organizer.type || 'hadhinat', organizerName: organizer.name || 'Hadhinat',
+          organizerCompanyId: organizer.companyId || null, startsAt, endsAt, venue, capacity: Number(capacity) || 0,
+          fee: Number(fee) || 0, description, status: 'draft',
+        });
+        trace('event.created', { eventId: e.id });
+        return e;
+      },
+      get: (id) => events.findById(id),
+      list: (f = {}) => events.find((e) => Object.entries(f).every(([k, v]) => e[k] === v)),
+      async publish(id) { const e = await events.findById(id); if (!e) throw new Error('événement introuvable'); if (e.status !== 'draft') throw new Error(`publication impossible depuis '${e.status}'`); const r = await events.update(id, { status: 'published' }); trace('event.published', { eventId: id }); return r; },
+      async cancel(id) { const r = await events.update(id, { status: 'cancelled' }); trace('event.cancelled', { eventId: id }); return r; },
+      async close(id) { const r = await events.update(id, { status: 'closed' }); return r; },
+      /** Sièges : capacité, inscrits (hors annulés), restants. */
+      async seats(id) { const e = await events.findById(id); const taken = (await registrations.find((r) => r.eventId === id && r.status !== 'cancelled')).length; const capacity = e?.capacity || 0; return { capacity, taken, remaining: capacity ? Math.max(0, capacity - taken) : null }; },
+    },
+
+    registrations: {
+      /**
+       * Inscrit un participant à un événement publié. Émet un BILLET (token signé = charge utile du QR badge).
+       * Événement PAYANT (fee>0) → compose payment.charge si `payment` injecté ; sinon le billet reste 'pending-payment'.
+       */
+      async register(eventId, { name, email, phone = null } = {}) {
+        const e = await events.findById(eventId); if (!e) throw new Error('événement introuvable');
+        if (e.status !== 'published') throw new Error('inscriptions fermées (événement non publié)');
+        if (!email) throw new Error('email requis');
+        const s = await api.events.seats(eventId);
+        if (s.remaining === 0) throw new Error('complet : plus de place disponible');
+        const reg = await registrations.create({ eventId, name: name || email, email: String(email).toLowerCase(), phone, status: 'registered', at: now().toISOString() });
+        // Billet + jeton signé (badge / contrôle d'accès)
+        let paid = e.fee <= 0, paymentRef = null;
+        if (e.fee > 0 && payment?.charge) { const c = await payment.charge({ amount: e.fee, currency: 'DZD', purpose: 'event', eventId, registrationId: reg.id }); paid = !!c?.ok || !!c?.id; paymentRef = c?.id || c?.ref || null; }
+        const t = await tickets.create({ no: tktNo(), eventId, registrationId: reg.id, status: paid ? 'valid' : 'pending-payment', paymentRef });
+        const token = signTicket(secret, { t: t.id, e: eventId, r: reg.id });
+        await tickets.update(t.id, { token });
+        trace('event.registered', { eventId, registrationId: reg.id, ticketId: t.id, paid });
+        return { registration: reg, ticket: { ...t, token }, paid };
+      },
+      list: (eventId) => registrations.find((r) => r.eventId === eventId),
+      get: (id) => registrations.findById(id),
+      async cancel(id) { return registrations.update(id, { status: 'cancelled' }); },
+    },
+
+    tickets: {
+      get: (id) => tickets.findById(id),
+      byRegistration: async (regId) => (await tickets.find((t) => t.registrationId === regId))[0] || null,
+      /** Charge utile QR « badge » d'un billet (token signé). */
+      token: async (ticketId) => { const t = await tickets.findById(ticketId); return t?.token || null; },
+    },
+
+    checkin: {
+      /**
+       * Contrôle d'accès : valide un jeton QR scanné. Signature OK + billet valide + non déjà utilisé → marque 'used' (entrée).
+       * Renvoie { ok, reason?, event, registration, ticket }.
+       */
+      async validate(token) {
+        const v = verifyTicket(secret, token);
+        if (!v.ok) return { ok: false, reason: v.reason };
+        const t = await tickets.findById(v.payload.t);
+        if (!t) return { ok: false, reason: 'unknown_ticket' };
+        if (t.status === 'pending-payment') return { ok: false, reason: 'unpaid', ticket: t };
+        if (t.status === 'used') return { ok: false, reason: 'already_used', ticket: t };
+        if (t.status !== 'valid') return { ok: false, reason: 'invalid', ticket: t };
+        await tickets.update(t.id, { status: 'used', usedAt: now().toISOString() });
+        const reg = await registrations.findById(t.registrationId);
+        const event = await events.findById(t.eventId);
+        trace('event.checkin', { eventId: t.eventId, ticketId: t.id });
+        return { ok: true, event, registration: reg, ticket: { ...t, status: 'used' } };
+      },
+      /** Vérifie un jeton SANS le consommer (aperçu). */
+      peek: (token) => verifyTicket(secret, token),
+    },
+
+    // Helpers exposés pour l'app (génération des charges utiles QR).
+    sign: (payload) => signTicket(secret, payload),
+    verify: (token) => verifyTicket(secret, token),
+  };
+  return api;
+}
+
+// Repositories en mémoire (dev/démo) — DB réelle via @mostajs/orm en prod. Forme uniforme findById/find/create/update.
+export function createMemoryRepositories() {
+  const mk = () => { let seq = 0; const rows = new Map(); return {
+    async create(o) { const id = 'ev' + (++seq) + '-' + Math.floor((seq * 2654435761) % 1e6); const r = { id, ...o }; rows.set(id, r); return { ...r }; },
+    async findById(id) { const r = rows.get(id); return r ? { ...r } : null; },
+    async find(pred) { return [...rows.values()].filter(pred).map((r) => ({ ...r })); },
+    async update(id, patch) { const r = rows.get(id); if (!r) return null; Object.assign(r, patch); return { ...r }; },
+  }; };
+  return { events: mk(), registrations: mk(), tickets: mk() };
+}
+
+export default { createEvents, createMemoryRepositories };

package/src/index.js

@@ -0,0 +1,5 @@
+// @mostajs/events — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+// Domaine événements pur. Le RENDU QR (invitation/badge/contrôle d'accès) est délégué à @mostajs/qrpanel/qr-svg :
+// l'app signe une charge utile via events.sign()/ticket.token puis l'encode avec qrSvg() — séparation domaine / présentation.
+export { createEvents, createMemoryRepositories } from './events.js';
+export { default } from './events.js';