@mostajs/wagon-engine

Auteur : Dr Hamid MADANI [email protected] · AGPL-3.0-or-later · Node ≥ 20

Le wagon d'un SaaS, une fois pour toutes. Il fournit les comptes, la connexion (mot de passe ou code par courriel), les paliers et leurs quotas, le paiement (Stripe, Chargily, SATIM, PayPal), l'espace client, l'administration, les pages légales, le référencement, les sauvegardes, et trois langues (fr, en, ar).

Une greffe n'apporte que ce qu'elle vend :

| la greffe écrit | rôle | |---|---| | wagon.config.mjs | identité, couleurs, langues, paliers et prix, moyens de paiement proposés | | charge/index.mjs | ses pages et son API (routes), ses ressources mesurées, son accueil | | legal/*.md | ses textes légaux, avec des jetons {{…}} remplis par la configuration | | .env | ses secrets et ses adresses |

Installer

npm install @mostajs/wagon-engine

Démarrer une greffe

// server.mjs
import { demarrer } from '@mostajs/wagon-engine';
import config from './wagon.config.mjs';
import charge from './charge/index.mjs';
await demarrer({ config, charge });

demarrer lit .env dans le dossier courant (@mostajs/config, cascade MOSTA_ENV), monte le courriel, la base et les moyens de paiement actifs, puis écoute sur PORT.

| .env | rôle | |---|---| | PORT, HOST | écoute (4800, 127.0.0.1) | | BASE_URL | l'adresse publique (liens des courriels, retours de paiement) | | DB_DIALECT, SGBD_URI | la base : sqlite et un chemin, ou postgres et postgresql://… | | EMAIL_SERVER_HOST, …_PORT, …_USER, …_PASSWORD, EMAIL_FROM | le courriel (SMTP) | | STRIPE_SECRET_KEY (ou STRIPE_RESTRICTED_KEY), STRIPE_WEBHOOK_SECRET | Stripe | | CHARGILY_SECRET_KEY · SATIM_MERCHANT_ID, SATIM_PASSWORD, SATIM_TERMINAL_ID · PAYPAL_… | les banques prépayées proposées par config.paiement.prepaye | | PAIEMENT_STRIPE=off, PAIEMENT_CHARGILY=off, PAIEMENT_SATIM=off, PAIEMENT_PAYPAL=off | coupe un moyen sans toucher à ses clés | | ADMIN_EMAILS | les courriels administrateurs (confirmés par un code reçu) | | PAIEMENT_VENDEUR_DZD, PAIEMENT_VENDEUR_EUR… | 0.6 — le vendeur de chaque devise (dénomination, forme, adresse, immatriculations) ; dès qu'une est déclarée, une devise sans vendeur n'est pas vendue, et {{VENDEUR}} des CGV les nomme | | PAIEMENT_STRIPE_DEVISES | 0.6 — la devise de Stripe (défaut EUR) |

Le .env d'abord. Toutes les clés passent par getEnv de @mostajs/config : cascade MOSTA_ENV (PROD_CLÉ l'emporte sur CLÉ), valeur vide = absente, et loadEnv n'écrase jamais une variable déjà posée par l'orchestrateur. Une clé porte le nom de sa fonction ; le seul préfixe est celui du profil (PROD_SGBD_URI, DEV_BASE_URL). Depuis la 0.9, les anciens noms WAGON_… ne sont plus lus : le démarrage signale ceux qui restent. Si wagon.config.mjs lit des variables, il appelle loadEnv lui-même, en tête.

Un vendeur par devise (0.6). Un SaaS qui vend en dinars par un auto-entrepreneur et en euros par une société pose PAIEMENT_VENDEUR_DZD=… et PAIEMENT_VENDEUR_EUR=…. Une devise déclarée vide (PAIEMENT_VENDEUR_EUR=, la société n'est pas encore immatriculée) n'est pas vendue : Stripe est écarté même avec sa clé. Sans aucune PAIEMENT_VENDEUR_*, rien ne change.

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 GREFFE :

npx mjs-unit node_modules/@mostajs/wagon-engine/src/conformite/conformite.test.mjs

Elle contrôle les comptes, le quota, le paiement (signatures Stripe réelles, banques simulées), la sécurité (CSRF, en-têtes, cookie), l'administration, les pages légales, la sauvegarde et les permissions par page. Un essai sans objet pour une greffe est ignoré avec son motif, jamais compté réussi.

Vérifier

node examples/verifier.mjs   # une greffe de vingt lignes démarre : paiement, paliers, texte légal, quota

Revenir où l'on était

Une page de la charge qui demande un compte envoie le visiteur vers /inscription?suite=/ma-page (ou /connexion?suite=/ma-page) : une fois inscrit ou connecté, il y revient. Seul un chemin du site est suivi.

Référence

L'API et le contrat complet de la charge sont dans llms.txt.