@mostajs/school-billing 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog — @mostajs/school-billing
+## [0.1.0] — 2026-06-18
+### Added
+- Frais (inscription/mensuel/niveau) + remises/promotions (percent/amount/code) + factures/reçus + paiement (payment) + mensuel (subscriptions-plan) + revenu. 6 tests + exemple §12.

package/README.md

@@ -0,0 +1,12 @@
+# @mostajs/school-billing
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (6 tests verts)
+> Frais scolaires + remises/promotions + factures/reçus + mensuel. Autonome ; compose payment/subscriptions-plan/numbering/file-export.
+```js
+import { createSchoolBilling, createMemoryRepositories } from '@mostajs/school-billing';
+const b = createSchoolBilling({ repositories: createMemoryRepositories(), payment, numbering });
+const f = await b.fees.define({ label:'Mensualité', kind:'mensuel', amount:6000 });
+await b.discounts.define({ label:'Fratrie -15%', type:'percent', value:15, code:'FRATRIE' });
+const inv = await b.invoices.create(studentId, { feeIds:[f.id], discountCode:'FRATRIE' });
+await b.invoices.pay(inv.id, { method:'cib' });
+```
+Lancer : `node test-scripts/unit/school-billing.test.mjs && node examples/frais/run.mjs`

package/docs/00-PROPOSITION-PLAN-SCHOOL-BILLING-18062026.md

@@ -0,0 +1,10 @@
+# @mostajs/school-billing — DEVRULES (§4 + #3 condensés)
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18 · **Statut** : cas C mince (P2 ATC F5).
+## §4
+Frais scolaires (inscription/mensuel/par niveau) + **remises/promotions** + factures/reçus + abonnement mensuel.
+Le moteur paiement/récurrence existe (`payment`+`subscriptions-plan`) → school-billing = la **couche frais scolaires mince** qui les compose.
+## §3 (API)
+`createSchoolBilling({repositories,payment?,subscriptions?,numbering?,fileExport?})` → `fees.{define,list}`, `discounts.{define,list,byCode}`,
+`invoices.{create(feeIds,discountCode),pay,listByStudent,outstanding,get,receipt}`, `subscribeMonthly(studentId,planId)`, `revenue({from,to})`.
+**Compose (§10)** : payment (encaissement), subscriptions-plan (mensuel), numbering (n° reçu), file-export (reçu). Alimente reporting. Délègue l'élève à @mostajs/school.
+## §4 (tests) : facture(somme), remise %/montant+promo, paiement(payment), outstanding+revenu, reçu(file-export), mensuel(subscriptions). (6 verts)

package/examples/frais/run.mjs

@@ -0,0 +1,15 @@
+// Exemple §12 — frais ATC (inscription + mensuel + remise fratrie). node examples/frais/run.mjs
+import assert from 'node:assert/strict';
+import { createSchoolBilling, createMemoryRepositories } from '../../src/index.js';
+const b=createSchoolBilling({ repositories:createMemoryRepositories(),
+  numbering:{ next:()=> 'REC-2026-'+Math.floor(Math.random()*9999) },
+  payment:{ async charge(p){ return {ref:'CIB-'+Date.now()}; } },
+  fileExport:{ async exportDoc(fmt,doc){ return `(${fmt}) ${doc.title} = ${doc.items.at(-1).fields.montant}`; } } });
+const insc=await b.fees.define({ label:"Frais d'inscription", kind:'inscription', amount:3000 });
+const mens=await b.fees.define({ label:'Mensualité Anglais A1', kind:'mensuel', amount:6000 });
+await b.discounts.define({ label:'Fratrie -15%', type:'percent', value:15, code:'FRATRIE' });
+const inv=await b.invoices.create('eleve-ines',{ feeIds:[insc.id,mens.id], discountCode:'FRATRIE' });
+await b.invoices.pay(inv.id,{ method:'cib' });
+assert.equal(inv.subtotal,9000); assert.equal(inv.total,7650);
+console.log('✅ school-billing — facture %s : %d - %d (fratrie) = %d DZD · payé · reçu: %s',
+  inv.receiptNo, inv.subtotal, inv.reduction, inv.total, await b.invoices.receipt(inv.id));

package/llms.txt

@@ -0,0 +1,13 @@
+# @mostajs/school-billing — fiche LLM
+RÔLE
+  Frais scolaires : inscription/mensuel/par niveau + remises/promotions + factures/reçus + abonnement mensuel. Autonome/DB-agnostique.
+  Compose (injectés) : payment (encaissement), subscriptions-plan (mensuel), numbering (n° reçu), file-export (reçu). Alimente reporting. Délègue l'élève à @mostajs/school.
+EXPORTS
+  createSchoolBilling({ repositories, payment?, subscriptionsPlan?, numbering?, fileExport?, now? }) -> { fees, discounts, invoices, subscribeMonthly, revenue }
+  createMemoryRepositories(); FeeSchema, DiscountSchema, InvoiceSchema
+API
+  fees.define({label,kind:'inscription'|'mensuel'|'niveau',amount})/list ; discounts.define({label,type:'percent'|'amount',value,code})/list/byCode
+  invoices.create(studentId,{feeIds,discountCode|discountId})->{subtotal,reduction,total,receiptNo}/pay(id,{method})/listByStudent/outstanding/get/receipt(id,format)
+  subscribeMonthly(studentId,planId) [subscriptions-plan] ; revenue({from,to})
+PIÈGES
+  - remise percent (×%) ou amount (montant fixe, plafonné au subtotal). pay compose payment.charge. mensuel = subscriptions-plan (scope 'student').

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mostajs/school-billing",
+  "version": "0.1.0",
+  "description": "Frais scolaires : inscription/mensuel/par niveau, remises & promotions, factures/reçus, abonnement mensuel. DB-agnostique ; compose payment/subscriptions-plan/numbering/file-export. Alimente reporting.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./schemas": "./src/schemas.js"
+  },
+  "keywords": [
+    "mostajs",
+    "school-billing",
+    "fees",
+    "tuition",
+    "discounts",
+    "invoices"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/school-billing.test.mjs",
+    "example": "node examples/frais/run.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// @mostajs/school-billing — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+export { createSchoolBilling } from './school-billing.js';
+export { createMemoryRepositories } from './memory-repo.js';
+export { FeeSchema, DiscountSchema, InvoiceSchema } from './schemas.js';

package/src/memory-repo.js

@@ -0,0 +1,6 @@
+function coll(){ const m=new Map(); return {
+  async create(d){ const id=d.id||globalThis.crypto.randomUUID(); const now=new Date(); const r={id,createdAt:now,updatedAt:now,...d}; m.set(id,r); return {...r}; },
+  async findById(id){ const r=m.get(id); return r?{...r}:null; },
+  async update(id,p){ const r=m.get(id); if(!r)return null; const x={...r,...p,updatedAt:new Date()}; m.set(id,x); return {...x}; },
+  async find(f=()=>true){ return [...m.values()].filter(f).map(r=>({...r})); } }; }
+export function createMemoryRepositories(){ return { fees:coll(), discounts:coll(), invoices:coll() }; }

package/src/schemas.js

@@ -0,0 +1,11 @@
+// @mostajs/school-billing — schémas. Author: Dr Hamid MADANI <drmdh@msn.com>
+export const FeeSchema = { name:'Fee', collection:'fees', timestamps:true, fields:{
+  label:{type:'string',required:true}, kind:{type:'string',enum:['inscription','mensuel','niveau'],default:'inscription'},
+  amount:{type:'number',required:true}, currency:{type:'string',default:'DZD'} } };
+export const DiscountSchema = { name:'Discount', collection:'discounts', timestamps:true, fields:{
+  label:{type:'string',required:true}, type:{type:'string',enum:['percent','amount'],default:'percent'}, value:{type:'number',required:true}, code:{type:'string'} } };
+export const InvoiceSchema = { name:'Invoice', collection:'invoices', timestamps:true, fields:{
+  studentId:{type:'string',required:true}, items:{type:'array'}, subtotal:{type:'number'}, discountLabel:{type:'string'},
+  reduction:{type:'number',default:0}, total:{type:'number'}, currency:{type:'string',default:'DZD'},
+  status:{type:'string',enum:['pending','paid','cancelled'],default:'pending'}, receiptNo:{type:'string'}, paymentRef:{type:'string'}, at:{type:'date'}, paidAt:{type:'date'} },
+  indexes:[{fields:{studentId:'asc'}},{fields:{status:'asc'}}] };

package/src/school-billing.js

@@ -0,0 +1,70 @@
+// @mostajs/school-billing — frais scolaires (mince). Author: Dr Hamid MADANI <drmdh@msn.com>
+// Autonome/DB-agnostique. Compose (injectés) : payment (encaissement), subscriptions-plan (mensuel récurrent),
+// numbering (n° reçu), file-export (reçu PDF). Délègue la scolarité à @mostajs/school ; alimente @mostajs/reporting.
+
+export function createSchoolBilling({ repositories, payment, subscriptionsPlan, numbering, fileExport, now = () => new Date() } = {}) {
+  if (!repositories?.invoices) throw new Error('createSchoolBilling: repositories.invoices requis');
+  const { fees, discounts, invoices } = repositories;
+  const receiptNo = () => (numbering?.next ? numbering.next('school-receipt') : `REC-${now().getFullYear()}-${Math.floor(now().getTime() % 1000000)}`);
+
+  const applyDiscount = (subtotal, d) => {
+    if (!d) return { reduction: 0, total: subtotal };
+    const reduction = d.type === 'percent' ? Math.round(subtotal * (d.value / 100)) : Math.min(subtotal, d.value);
+    return { reduction, total: Math.max(0, subtotal - reduction) };
+  };
+
+  const api = {
+    fees: {
+      define: (dto) => fees.create({ kind: 'inscription', currency: 'DZD', ...dto }),   // kind: inscription|mensuel|niveau
+      list: (f = {}) => fees.find((x) => Object.entries(f).every(([k, v]) => x[k] === v)),
+    },
+    discounts: {
+      define: (dto) => discounts.create({ type: 'percent', ...dto }),                    // type: percent|amount ; code? (promo)
+      list: () => discounts.find(),
+      byCode: async (code) => (await discounts.find((d) => d.code === code))[0] || null,
+    },
+    invoices: {
+      /** Crée une facture pour un élève à partir de frais + remise/promo éventuelle. */
+      async create(studentId, { feeIds = [], discountCode, discountId } = {}) {
+        const items = [];
+        for (const id of feeIds) { const f = await fees.findById(id); if (!f) throw new Error(`frais introuvable: ${id}`); items.push({ feeId: id, label: f.label, amount: f.amount }); }
+        const subtotal = items.reduce((s, i) => s + i.amount, 0);
+        const d = discountCode ? await api.discounts.byCode(discountCode) : (discountId ? await discounts.findById(discountId) : null);
+        const { reduction, total } = applyDiscount(subtotal, d);
+        return invoices.create({ studentId, items, subtotal, discountLabel: d?.label || null, reduction, total, currency: 'DZD', status: 'pending', receiptNo: receiptNo(), at: now() });
+      },
+      /** Encaissement (compose @mostajs/payment). */
+      async pay(invoiceId, { method } = {}) {
+        const inv = await invoices.findById(invoiceId); if (!inv) throw new Error('facture introuvable');
+        if (inv.status === 'paid') return inv;
+        let paymentRef = null;
+        if (payment?.charge) { const r = await payment.charge({ amount: inv.total, currency: inv.currency, method, purpose: 'school-fee', studentId: inv.studentId }); paymentRef = r?.ref ?? r?.id; }
+        return invoices.update(invoiceId, { status: 'paid', paymentRef, paidAt: now() });
+      },
+      listByStudent: (studentId) => invoices.find((i) => i.studentId === studentId),
+      async outstanding(studentId) { return (await invoices.find((i) => i.studentId === studentId && i.status !== 'paid')).reduce((s, i) => s + i.total, 0); },
+      get: (id) => invoices.findById(id),
+      async receipt(invoiceId, format = 'pdf') {
+        const inv = await invoices.findById(invoiceId); if (!inv) throw new Error('facture introuvable');
+        const doc = { title: `Reçu ${inv.receiptNo}`, items: [...inv.items.map((i) => ({ title: i.label, fields: { montant: i.amount } })),
+          ...(inv.reduction ? [{ title: `Remise ${inv.discountLabel || ''}`, fields: { montant: -inv.reduction } }] : []),
+          { title: 'TOTAL', fields: { montant: `${inv.total} ${inv.currency}` } }] };
+        return fileExport?.exportDoc ? fileExport.exportDoc(format, doc) : doc;
+      },
+    },
+    /** Abonnement mensuel récurrent (compose @mostajs/subscriptions-plan). */
+    async subscribeMonthly(studentId, planId) {
+      if (!subscriptionsPlan?.subscribeToPlan) throw new Error('@mostajs/subscriptions-plan requis (mensuel)');
+      return subscriptionsPlan.subscribeToPlan({ accountId: studentId, planId, scope: { scopeType: 'student', scopeId: studentId } });
+    },
+    /** Revenu encaissé (alimente @mostajs/reporting). */
+    async revenue({ from, to } = {}) {
+      const paid = await invoices.find((i) => i.status === 'paid');
+      const inWin = (i) => (!from || new Date(i.paidAt || i.at) >= new Date(from)) && (!to || new Date(i.paidAt || i.at) <= new Date(to));
+      const w = paid.filter(inWin);
+      return { total: w.reduce((s, i) => s + i.total, 0), count: w.length };
+    },
+    repositories,
+  };
+  return api;
+}

package/test-scripts/unit/school-billing.test.mjs

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import { createSchoolBilling, createMemoryRepositories } from '../../src/index.js';
+let pass=0; const test=async(n,f)=>{await f();pass++;console.log('  ✓',n);};
+const mk=(o={})=>createSchoolBilling({ repositories:createMemoryRepositories(), ...o });
+
+await test('facture = somme des frais', async()=>{
+  const b=mk(); const f1=await b.fees.define({label:'Inscription',kind:'inscription',amount:2000});
+  const f2=await b.fees.define({label:'Mensuel juin',kind:'mensuel',amount:5000});
+  const inv=await b.invoices.create('e1',{feeIds:[f1.id,f2.id]});
+  assert.equal(inv.subtotal,7000); assert.equal(inv.total,7000); assert.ok(inv.receiptNo);
+});
+await test('remise % et montant + promo code', async()=>{
+  const b=mk(); const f=await b.fees.define({label:'Mensuel',amount:10000});
+  await b.discounts.define({label:'Fratrie -10%',type:'percent',value:10,code:'FRATRIE'});
+  const inv=await b.invoices.create('e1',{feeIds:[f.id],discountCode:'FRATRIE'});
+  assert.equal(inv.reduction,1000); assert.equal(inv.total,9000);
+  await b.discounts.define({label:'Bourse 3000',type:'amount',value:3000,code:'BOURSE'});
+  const inv2=await b.invoices.create('e2',{feeIds:[f.id],discountCode:'BOURSE'});
+  assert.equal(inv2.total,7000);
+});
+await test('paiement (compose payment) + statut', async()=>{
+  const charged=[]; const b=mk({ payment:{ async charge(p){charged.push(p);return {ref:'CIB-1'};} } });
+  const f=await b.fees.define({label:'X',amount:1000}); const inv=await b.invoices.create('e1',{feeIds:[f.id]});
+  await b.invoices.pay(inv.id,{method:'cib'});
+  assert.equal((await b.invoices.get(inv.id)).status,'paid'); assert.equal(charged[0].purpose,'school-fee');
+});
+await test('encours (outstanding) + revenu', async()=>{
+  const b=mk(); const f=await b.fees.define({label:'X',amount:1000});
+  const a=await b.invoices.create('e1',{feeIds:[f.id]}); await b.invoices.create('e1',{feeIds:[f.id]});
+  assert.equal(await b.invoices.outstanding('e1'),2000);
+  await b.invoices.pay(a.id); assert.equal(await b.invoices.outstanding('e1'),1000);
+  assert.equal((await b.revenue()).total,1000);
+});
+await test('reçu (compose file-export)', async()=>{
+  const exp=[]; const b=mk({ fileExport:{ async exportDoc(fmt,doc){exp.push(fmt);return 'recu.pdf';} } });
+  const f=await b.fees.define({label:'X',amount:500}); const inv=await b.invoices.create('e1',{feeIds:[f.id]});
+  assert.equal(await b.invoices.receipt(inv.id),'recu.pdf'); assert.equal(exp[0],'pdf');
+});
+await test('mensuel : compose subscriptions-plan', async()=>{
+  const subs=[]; const b=mk({ subscriptionsPlan:{ async subscribeToPlan(p){subs.push(p);return {id:'sub1'};} } });
+  await b.subscribeMonthly('e1','plan-mensuel'); assert.equal(subs[0].planId,'plan-mensuel'); assert.equal(subs[0].scope.scopeId,'e1');
+});
+console.log(`\n✅ @mostajs/school-billing — ${pass} tests OK`);