@mostajs/wagon-engine 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 **Auteur** : Dr Hamid MADANI <drmdh@msn.com>
 Format : Keep a Changelog ; versions : SemVer.
 
+## [0.7.0] — 2026-10-29
+
+### Ajouté
+- **Le paiement ponctuel de la charge** : `ctx.paiement.ouvrir({ moyen, montant, description, reference, metadata,
+  merci, annule })` ouvre une session chez une banque prépayée active (celle qui a un vendeur, 0.6) pour un achat à
+  l'unité de la charge (une place de cours de Speaking) ; `ctx.paiement.moyens` dit les moyens et leur devise ;
+  `ctx.paiement` est `null` sans banque. La banque confirme à `/api/paiement/charge/<moyen>` (webhook authentifié par
+  sa signature, hors CSRF et hors session) ou renvoie l'acheteur à `/api/paiement/charge-retour/<moyen>` (banque
+  réinterrogée, comme SATIM) ; le wagon remet le constat à `charge.paiementRegle({ reference, statut, commande, montant,
+  devise, moyen, metadata })`. Les chemins de retour sont locaux. La ligne `Payment` reste dans la base du wagon.
+  Essai T-ENG-16.
+
 ## [0.6.1] — 2026-10-28
 
 ### Corrigé

package/README.md

@@ -50,6 +50,8 @@ await demarrer({ config, charge });
 
 **Le paiement est au choix de l'utilisateur**, parmi les moyens actifs. Un moyen est actif quand ses clés sont dans le `.env` et que son commutateur n'est pas sur `off`. Une banque prépayée doit en plus être proposée par la configuration.
 
+**Un achat à l'unité de la charge (0.7).** `ctx.paiement.ouvrir({ moyen, montant, description, reference, metadata, merci, annule })` ouvre un paiement ponctuel (montant en unités mineures) chez une banque prépayée active ; `ctx.paiement.moyens` les liste, `ctx.paiement` est `null` sans banque. La banque confirme à `/api/paiement/charge/<moyen>` (signature) ou y renvoie l'acheteur (`/api/paiement/charge-retour/<moyen>`) ; le wagon appelle `charge.paiementRegle({ reference, statut, commande, montant, devise, moyen, metadata })`, que la charge écrit idempotent.
+
 ## Juger une greffe
 
 La suite de conformité est publiée avec le moteur. Elle juge la greffe du dossier courant, ou celle que désigne `WAGON_GREFFE` :

package/llms.txt

@@ -45,10 +45,11 @@ encore immatriculée → `PAIEMENT_VENDEUR_DZD=…`, `PAIEMENT_VENDEUR_EUR=` (vi
 ## CONTRAT DE LA CHARGE (charge/index.mjs)
 liens · ressources (quota { cle, limite, periode } | plafond { cle, limite, plafond: true }) · accueil (fiche { fr: { titre, lede, actions, preuves } }, ou 0.3 : async (ctx) => ({ titre, contenu, disposition, application, console })) · dispositions (0.3 : { nom: (p) => corps }) · textes ·
 routes(req, res, ctx) (passent en premier ; true si servie) · conformite (essai de quota T-WAG-3) · amorcer() (base au
-démarrage) · exporterCompte(id), effacerCompte(id) (RGPD) · sitemap() · sauvegarde() · permissions (0.11 :
+démarrage) · exporterCompte(id), effacerCompte(id) (RGPD) · sitemap() · sauvegarde() · paiementRegle(p) (0.7) · permissions (0.11 :
 { '/page': { microphone: 'self' }, '/dossier/*': … }, garde-http ≥ 0.2).
 ctx : chemin, methode, lang, t, ui, page({ titre, contenu }), envoyer, json, rediriger, formulaire, corpsJson({ strict }),
 compte, consommer(cle), refuser(v), palier({ compte? }), plafond(cle, n, { compte? }), courriel({ to, subject, text, html? }) → bool, admin.
+  0.7 : ctx.paiement (null sans banque prépayée active) = { moyens: [{ moyen, devise }], ouvrir({ moyen, montant (unités MINEURES), description, reference, metadata, merci: '/chemin', annule: '/chemin' }) → { ok, url, commande } | { ok: false, raison } } — paiement PONCTUEL de la charge (une place de cours…). La banque confirme à /api/paiement/charge/<moyen> (webhook, signature) ou renvoie l'acheteur à /api/paiement/charge-retour/<moyen> (SATIM) ; le wagon appelle alors charge.paiementRegle({ reference, statut: paid|failed|refunded|…, commande, montant (mineures), devise, moyen, metadata }), à écrire IDEMPOTENT (une banque rejoue). merci/annule : chemins locaux seulement.
   0.4 : /inscription?suite=/chemin et /connexion?suite=/chemin — retour à une page LOCALE après inscription (si ni clé ni paiement à montrer ; sinon bouton « Continuer ») ou connexion par mot de passe ; //hôte et adresses absolues ignorés.
   0.3 : ctx.page({ disposition: 'vitrine'|'application'|'console'|'nu'|<fournie>, application: { retour, titre, avatar, onglets, langues }, console: { menu, contexte, utilisateur } }) (wagon-ui 0.10) ; config.jetons { rayon, police, policeTitres, ombre, fond } ; config.marque.logo / logoClair (SVG en ligne ou chemin /…).
   0.2 : { compte } = identifiant d'un compte DÉSIGNÉ (requête sans session bornée par le palier d'un compte rattaché par la charge).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/wagon-engine",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Le wagon d'un SaaS, une fois pour toutes : comptes, connexion, paliers, quotas, paiement (Stripe, Chargily, SATIM), espace client, administration, pages légales, fr/en/ar. Une greffe n'apporte que wagon.config.mjs, charge/, legal/ et son .env ; la suite de conformité publiée juge la greffe.",
   "keywords": [
     "mostajs",

package/src/wagon.mjs

@@ -25,7 +25,8 @@ import { creerWagonUi, esc } from '@mostajs/wagon-ui';
 import { creerComptes, schemasComptes } from '@mostajs/comptes';
 import { createBilling, createStripeSale, createPrepaidSale, billingSchemas, checkLimits, assertMonotonicPlans } from '@mostajs/subscriptions-plan/server';
 import { PaymentSchema } from '@mostajs/payment';
-import { venteAutorisee, vendeursFromEnv } from '@mostajs/payment/server';
+import * as paymentServer from '@mostajs/payment/server';
+const { venteAutorisee, vendeursFromEnv } = paymentServer;
 import { formatNumber, resolveFormatLocale } from '@mostajs/i18n';
 import { createPasswordAuth, createEmailCodeAuth, SessionSchema, ipClient, memoryLimiter } from '@mostajs/auth-lite';
 import { emailCodeEmailHtml, emailCodeEmailText, emailCodeForm, emailLinkConfirmPage, AUTH_CSS } from '@mostajs/auth-ui';
@@ -259,6 +260,53 @@ export async function creerWagon({ config, charge, sgbd, baseUrl, stripe = null,
     return faits;
   }
   if (prepaye && Object.keys(banques).some((b) => SANS_WEBHOOK.includes(b))) setInterval(reprendrePaiements, 10 * 60 * 1000).unref?.();
+
+  /**
+   * 0.7 — le PAIEMENT PONCTUEL de la charge (une place de cours, un achat à l'unité), par les banques prépayées
+   * actives (celles qui ont un vendeur) : `ctx.paiement.ouvrir(…)` ouvre la session chez la banque ; la banque confirme
+   * à /api/paiement/charge/<moyen> (webhook) ou y renvoie l'acheteur (/api/paiement/charge-retour/<moyen>, SATIM). Le
+   * paiement se constate par @mostajs/payment (signature vérifiée, ou banque réinterrogée : rien de l'URL n'est cru),
+   * puis le wagon appelle `charge.paiementRegle({ reference, statut, commande, montant, devise, moyen, metadata })`.
+   * Le wagon ne garde que la ligne Payment ; ce que le paiement règle (une réservation…) est l'affaire de la charge,
+   * qui doit être idempotente (une banque rejoue ses webhooks).
+   */
+  const portPaiement = async () => paiement?.port?.createPaymentCheckout ? paiement.port : paymentServer;
+  const CHEMIN_LOCAL = /^\/(?!\/)[^\s]*$/;
+  const paiementCharge = Object.keys(banques).length ? Object.freeze({
+    moyens: Object.entries(banques).map(([moyen, devise]) => ({ moyen, devise: String(devise).toUpperCase() })),
+    /** `montant` en unités MINEURES ; `merci` et `annule` : des chemins de la greffe. Rend { ok, url, commande } ou { ok: false, raison }. */
+    async ouvrir({ moyen, montant, description = '', reference, metadata = {}, merci = '/', annule = '/' }) {
+      const devise = banques[moyen];
+      if (!devise) return { ok: false, raison: `moyen non proposé : ${moyen}` };
+      const m = Math.round(Number(montant));
+      if (!(m > 0)) return { ok: false, raison: 'montant invalide' };
+      if (!reference || !CHEMIN_LOCAL.test(merci) || !CHEMIN_LOCAL.test(annule)) return { ok: false, raison: 'référence ou chemins de retour invalides' };
+      const commande = `ch_${String(reference).replace(/[^\w-]/g, '').slice(0, 40)}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+      try {
+        const r = await (await portPaiement()).createPaymentCheckout({
+          dialect: d, providerName: moyen, orderId: commande, amount: m / 100, currency: String(devise).toUpperCase(), description,
+          successUrl: `${origine}${merci}`, cancelUrl: `${origine}${annule}`,
+          webhookUrl: `${origine}/api/paiement/charge/${moyen}`, returnUrl: `${origine}/api/paiement/charge-retour/${moyen}`,
+          metadata: { ...metadata, wagon_charge: String(reference), wagon_merci: merci, wagon_annule: annule },
+        });
+        if (!r?.checkout?.url) return { ok: false, raison: 'la banque n’a pas rendu d’adresse de paiement' };
+        return { ok: true, url: r.checkout.url, commande };
+      } catch (e) { return { ok: false, raison: String(e?.message ?? e) }; }
+    },
+  }) : null;
+  /** Constate un paiement de la charge et le lui remet : { status, paye, meta }. */
+  async function reglerCharge(moyen, corpsBrut, headers) {
+    if (!banques[moyen]) return { status: 404, paye: false, meta: {} };
+    const r = await (await portPaiement()).settlePaymentFromWebhook({ dialect: d, providerName: moyen, body: corpsBrut, headers });
+    if (!r?.ok) return { status: 400, paye: false, meta: {} };
+    const pay = r.payment;
+    const meta = typeof pay?.metadata === 'string' ? JSON.parse(pay.metadata || '{}') : (pay?.metadata ?? {});
+    if (!pay || !r.status || !meta.wagon_charge) return { status: 200, paye: false, meta };
+    try {
+      await charge.paiementRegle?.({ reference: meta.wagon_charge, statut: r.status, commande: String(r.orderId ?? pay.orderId), montant: Math.round(Number(pay.amount) * 100), devise: pay.currency, moyen, metadata: meta });
+    } catch (e) { journal.warn(`wagon : paiementRegle de la charge : ${e?.message ?? e}`); return { status: 500, paye: false, meta }; }
+    return { status: 200, paye: r.status === 'paid', meta };
+  }
   const admins = new Set([...(config.admins ?? []), ...String(getEnv('WAGON_ADMINS', '') ?? '').split(',')].map((x) => x.trim().toLowerCase()).filter(Boolean));
   /** Un courriel est administrateur s'il est DÉCLARÉ et CONFIRMÉ. */
   const estAdministrateur = async (courriel) => {
@@ -556,6 +604,19 @@ export async function creerWagon({ config, charge, sgbd, baseUrl, stripe = null,
       return rediriger(r.paid ? '/paiement/merci' : '/tarifs');
     }
 
+    // 0.7 — les paiements ponctuels de la charge : webhook (signature) et retour de l'acheteur (banque réinterrogée).
+    if (chemin.startsWith('/api/paiement/charge/') && methode === 'POST') {
+      if (!paiementCharge) return json(503, { ok: false, error: 'paiement non configuré' });
+      const r = await reglerCharge(decodeURIComponent(chemin.slice('/api/paiement/charge/'.length)), (await corps()).toString('utf8'), req.headers);
+      return json(r.status, { ok: r.status === 200 });
+    }
+    if (chemin.startsWith('/api/paiement/charge-retour/') && (methode === 'GET' || methode === 'POST')) {
+      if (!paiementCharge) return rediriger('/');
+      const r = await reglerCharge(decodeURIComponent(chemin.slice('/api/paiement/charge-retour/'.length)), methode === 'GET' ? url.searchParams.toString() : (await corps()).toString('utf8'), req.headers);
+      const vers = r.paye ? r.meta.wagon_merci : r.meta.wagon_annule;
+      return rediriger(typeof vers === 'string' && CHEMIN_LOCAL.test(vers) ? vers : '/');
+    }
+
     // La porte de service : une clé d'API ouvre /api/v1/* ; sans clé valable, 401 — jamais une page.
     let compteCle = null;
     if (chemin.startsWith('/api/v1/')) {
@@ -631,7 +692,8 @@ export async function creerWagon({ config, charge, sgbd, baseUrl, stripe = null,
       if (!transport) return false;
       try { await transport.envoyer(m); return true; } catch (e) { journal.warn(`wagon : courriel de la charge non parti : ${e?.message ?? e}`); return false; }
     };
-    const ctx = { chemin, methode, lang, t, ui, page, envoyer, json, rediriger, formulaire, corpsJson, compte, consommer, refuser, palier, plafond, courriel, admin: estAdmin && !compteCle };
+    const ctx = { chemin, methode, lang, t, ui, page, envoyer, json, rediriger, formulaire, corpsJson, compte, consommer, refuser, palier, plafond, courriel, admin: estAdmin && !compteCle,
+      paiement: paiementCharge };   // 0.7 — null sans banque prépayée active
     if (charge.routes && (await charge.routes(req, res, ctx))) return true;
     if (chemin.startsWith('/api/')) return json(404, { ok: false, error: 'introuvable' });