@mostajs/aid-grants 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog — @mostajs/aid-grants
+## [0.1.0] — 2026-06-18
+### Added
+- Aides typées + cycle request/approve/pay/reject + suivi budgétaire (allocated/consumed/remaining) + versement (payment) + stats. 6 tests + exemple §12.

package/README.md

@@ -0,0 +1,11 @@
+# @mostajs/aid-grants
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later · **Statut** : 0.1.0 (6 tests verts)
+> Aides accordées + suivi budgétaire + versements. Autonome ; compose payment/numbering ; alimente reporting. Générique NGO.
+```js
+import { createAidGrants, createMemoryRepositories } from '@mostajs/aid-grants';
+const g = createAidGrants({ repositories: createMemoryRepositories(), payment });
+await g.budget.set('ramadan-2026', 100000);
+const a = await g.aids.request('veuve-12', { type:'financiere', amount:8000, budgetLine:'ramadan-2026' });
+await g.aids.approve(a.id); await g.aids.pay(a.id);   // contrôle budget + payment.disburse
+```
+Lancer : `node test-scripts/unit/aid-grants.test.mjs && node examples/aides/run.mjs`

package/docs/00-PROPOSITION-PLAN-AID-GRANTS-18062026.md

@@ -0,0 +1,10 @@
+# @mostajs/aid-grants — DEVRULES de bout en bout (§4 + #3 condensés)
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Date** : 2026-06-18 · **Statut** : cas C (P3 NGO, générique)
+**Principe** : EXTRACTION « gestion des aides » (asso-sel Modules 1.4/3). Autonome/DB-agnostique.
+## §4 / §3
+**Aides** typées (financière/alimentaire/parrainage/médicale/scolaire/saisonnière) + cycle (request→approve→pay/reject)
++ **suivi budgétaire** (lignes : allocated/consumed/remaining) + versement. Compose payment (disburse), numbering (n° aide) ;
+alimente @mostajs/reporting (stats). **Frontière** : le bénéficiaire = cœur métier (beneficiaries/medical-cases) ; aid-grants = l'aide+budget.
+**API** : `createAidGrants({repositories,payment?,numbering?})` → `aids.{request,approve,reject,pay,get,listByBeneficiary,byType,byStatus}`,
+`budget.{set,allocated,consumed,remaining}`, `stats({from,to})`.
+**Jalons** : 0.1 cycle+budget+stats · 0.2 payment(disburse) · 1.0 14 livrables.

package/examples/aides/run.mjs

@@ -0,0 +1,16 @@
+// Exemple §12 — aides (P3 ASSO-SEL) : parrainage + aide saisonnière (budget Ramadan). node examples/aides/run.mjs
+import assert from 'node:assert/strict';
+import { createAidGrants, createMemoryRepositories } from '../../src/index.js';
+const g=createAidGrants({ repositories:createMemoryRepositories(),
+  numbering:{ next:()=> 'AID-2026-'+Math.floor(Math.random()*9999) },
+  payment:{ async disburse(p){ console.log('   ↪ versé:',p.amount,'DZD →',p.purpose); return {ref:'CCP-'+Date.now()}; } } });
+await g.budget.set('ramadan-2026', 100000);
+// veuve : aide financière + parrainage orphelin
+const a1=await g.aids.request('veuve-12',{ type:'financiere', amount:8000, budgetLine:'ramadan-2026', note:'aide mensuelle' });
+await g.aids.approve(a1.id,{by:'commission'}); await g.aids.pay(a1.id,{by:'compta'});
+const a2=await g.aids.request('orphelin-7',{ type:'parrainage', amount:5000, budgetLine:'ramadan-2026' });
+await g.aids.approve(a2.id); await g.aids.pay(a2.id);
+assert.equal((await g.aids.byStatus('paid')).length,2);
+const st=await g.stats();
+console.log('✅ aid-grants — versé %d DZD · reste budget Ramadan: %d · ventilation %o',
+  st.total, await g.budget.remaining('ramadan-2026'), st.byType);

package/llms.txt

@@ -0,0 +1,13 @@
+# @mostajs/aid-grants — fiche LLM
+RÔLE
+  Aides accordées (financière/alimentaire/parrainage/médicale/scolaire/saisonnière) + suivi budgétaire + versements.
+  Autonome/DB-agnostique. Compose payment (disburse), numbering (n° aide). Alimente @mostajs/reporting. Générique NGO.
+EXPORTS
+  createAidGrants({ repositories, payment?, numbering?, now? }) -> { aids, budget, stats }
+  createMemoryRepositories(); AidSchema, BudgetSchema
+API
+  aids.request(beneficiaryId,{type,amount,note,budgetLine})/approve(id,{by})/reject/pay(id,{by})/get/listByBeneficiary/byType/byStatus
+  budget.set(line,allocated)/allocated(line)/consumed(line)/remaining(line)  ; stats({from,to}) -> {total,count,byType}
+PIÈGES
+  - cycle: requested→approved→paid | rejected. pay() contrôle le budget (throw 'budget insuffisant') si budgetLine.
+  - versement réel = compose payment.disburse. consumed = somme des aides 'paid' d'une ligne.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mostajs/aid-grants",
+  "version": "0.1.0",
+  "description": "Aides accordées (financières/alimentaires/parrainage/médicales/scolaires/saisonnières) + suivi budgétaire + versements. DB-agnostique ; compose payment/numbering ; alimente reporting. Générique NGO.",
+  "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",
+    "aid",
+    "grants",
+    "ngo",
+    "budget",
+    "welfare"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/aid-grants.test.mjs",
+    "example": "node examples/aides/run.mjs"
+  }
+}

package/src/aid-grants.js

@@ -0,0 +1,50 @@
+// @mostajs/aid-grants — aides accordées + suivi budgétaire. Author: Dr Hamid MADANI <drmdh@msn.com>
+// Autonome/DB-agnostique. Compose (injectés) : payment (versement), numbering (n° aide). Alimente @mostajs/reporting.
+
+export function createAidGrants({ repositories, payment, numbering, now = () => new Date() } = {}) {
+  if (!repositories?.aids) throw new Error('createAidGrants: repositories.aids requis');
+  const { aids, budgets } = repositories;
+  const ref = () => (numbering?.next ? numbering.next('aid') : `AID-${now().getFullYear()}-${Math.floor(now().getTime() % 1000000)}`);
+  const inWindow = ({ from, to } = {}) => (a) => (!from || new Date(a.at) >= new Date(from)) && (!to || new Date(a.at) <= new Date(to));
+
+  const budget = {
+    set: async (line, allocated) => { const ex = (await budgets.find((b) => b.line === line))[0]; return ex ? budgets.update(ex.id, { allocated }) : budgets.create({ line, allocated }); },
+    allocated: async (line) => ((await budgets.find((b) => b.line === line))[0]?.allocated || 0),
+    consumed: async (line) => (await aids.find((a) => a.budgetLine === line && a.status === 'paid')).reduce((s, a) => s + a.amount, 0),
+    async remaining(line) { return (await budget.allocated(line)) - (await budget.consumed(line)); },
+  };
+
+  const api = {
+    aids: {
+      request: async (beneficiaryId, { type, amount = 0, note, budgetLine } = {}) => {
+        if (!type) throw new Error('type d\'aide requis');
+        return aids.create({ beneficiaryId, type, amount, note, budgetLine, status: 'requested', ref: ref(), at: now() });
+      },
+      get: (id) => aids.findById(id),
+      approve: (id, { by } = {}) => aids.update(id, { status: 'approved', by }),
+      reject: (id, { by } = {}) => aids.update(id, { status: 'rejected', by }),
+      /** Versement : contrôle budgétaire + compose @mostajs/payment (disburse). */
+      async pay(id, { by } = {}) {
+        const a = await aids.findById(id); if (!a) throw new Error('aide introuvable');
+        if (a.status === 'paid') return a;
+        if (a.status === 'rejected') throw new Error('aide rejetée');
+        if (a.budgetLine && a.amount > 0) { const rem = await budget.remaining(a.budgetLine); if (a.amount > rem) throw new Error(`budget insuffisant (${a.budgetLine}: reste ${rem})`); }
+        let paymentRef = null;
+        if (payment?.disburse) { const r = await payment.disburse({ amount: a.amount, beneficiaryId: a.beneficiaryId, purpose: a.type }); paymentRef = r?.ref ?? r?.id; }
+        return aids.update(id, { status: 'paid', paymentRef, by, at: now() });
+      },
+      listByBeneficiary: (beneficiaryId) => aids.find((a) => a.beneficiaryId === beneficiaryId),
+      byType: (type) => aids.find((a) => a.type === type),
+      byStatus: (status) => aids.find((a) => a.status === status),
+    },
+    budget,
+    /** Statistiques (alimente @mostajs/reporting) : total versé + ventilation par type. */
+    async stats(window) {
+      const paid = (await aids.find((a) => a.status === 'paid')).filter(inWindow(window));
+      const byType = {}; for (const a of paid) byType[a.type] = (byType[a.type] || 0) + a.amount;
+      return { total: paid.reduce((s, a) => s + a.amount, 0), count: paid.length, byType };
+    },
+    repositories,
+  };
+  return api;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// @mostajs/aid-grants — point d'entrée. Author: Dr Hamid MADANI <drmdh@msn.com>
+export { createAidGrants } from './aid-grants.js';
+export { createMemoryRepositories } from './memory-repo.js';
+export { AidSchema, BudgetSchema } from './schemas.js';

package/src/memory-repo.js

@@ -0,0 +1,7 @@
+// @mostajs/aid-grants — repos mémoire. Author: Dr Hamid MADANI <drmdh@msn.com>
+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 { aids:coll(), budgets:coll() }; }

package/src/schemas.js

@@ -0,0 +1,10 @@
+// @mostajs/aid-grants — schémas (EntitySchema @mostajs/orm). Author: Dr Hamid MADANI <drmdh@msn.com>
+export const AidSchema = { name: 'Aid', collection: 'aids', timestamps: true, fields: {
+  beneficiaryId: { type: 'string', required: true },
+  type: { type: 'string', enum: ['financiere', 'alimentaire', 'parrainage', 'medicale', 'scolaire', 'saisonniere'], required: true },
+  amount: { type: 'number', default: 0 }, note: { type: 'string' }, budgetLine: { type: 'string', default: null },
+  status: { type: 'string', enum: ['requested', 'approved', 'paid', 'rejected'], default: 'requested' },
+  ref: { type: 'string' }, at: { type: 'date', default: 'now' }, paymentRef: { type: 'string', default: null }, by: { type: 'string', default: null } },
+  indexes: [{ fields: { beneficiaryId: 'asc' } }, { fields: { type: 'asc' } }, { fields: { status: 'asc' } }] };
+export const BudgetSchema = { name: 'Budget', collection: 'budgets', timestamps: true, fields: {
+  line: { type: 'string', required: true, unique: true }, allocated: { type: 'number', default: 0 } } };

package/test-scripts/unit/aid-grants.test.mjs

@@ -0,0 +1,42 @@
+// @mostajs/aid-grants — tests (DEVRULES §5). node test-scripts/unit/aid-grants.test.mjs
+import assert from 'node:assert/strict';
+import { createAidGrants, createMemoryRepositories } from '../../src/index.js';
+let pass=0; const test=async(n,f)=>{await f();pass++;console.log('  ✓',n);};
+const mk=(o={})=>createAidGrants({ repositories:createMemoryRepositories(), ...o });
+
+await test('cycle : request → approve → pay', async()=>{
+  const g=mk(); const a=await g.aids.request('ben1',{type:'financiere',amount:5000});
+  assert.equal(a.status,'requested'); assert.ok(a.ref);
+  await g.aids.approve(a.id,{by:'agent'}); assert.equal((await g.aids.get(a.id)).status,'approved');
+  await g.aids.pay(a.id,{by:'compta'}); assert.equal((await g.aids.get(a.id)).status,'paid');
+});
+await test('type requis ; aide rejetée non payable', async()=>{
+  const g=mk(); await assert.rejects(()=>g.aids.request('b',{amount:1}),/type/);
+  const a=await g.aids.request('b',{type:'alimentaire',amount:1}); await g.aids.reject(a.id);
+  await assert.rejects(()=>g.aids.pay(a.id),/rejet/);
+});
+await test('suivi budgétaire : allocated/consumed/remaining + refus si insuffisant', async()=>{
+  const g=mk(); await g.budget.set('ramadan-2026',10000);
+  const a1=await g.aids.request('b1',{type:'saisonniere',amount:7000,budgetLine:'ramadan-2026'}); await g.aids.pay(a1.id);
+  assert.equal(await g.budget.consumed('ramadan-2026'),7000);
+  assert.equal(await g.budget.remaining('ramadan-2026'),3000);
+  const a2=await g.aids.request('b2',{type:'saisonniere',amount:5000,budgetLine:'ramadan-2026'});
+  await assert.rejects(()=>g.aids.pay(a2.id),/budget insuffisant/);
+});
+await test('versement composé via payment (disburse)', async()=>{
+  const out=[]; const g=mk({ payment:{ async disburse(p){out.push(p);return {ref:'PAY-9'};} } });
+  const a=await g.aids.request('b',{type:'medicale',amount:3000}); await g.aids.pay(a.id);
+  assert.equal((await g.aids.get(a.id)).paymentRef,'PAY-9'); assert.equal(out[0].purpose,'medicale');
+});
+await test('stats : total versé + ventilation par type', async()=>{
+  const g=mk();
+  for (const [t,m] of [['financiere',1000],['alimentaire',500],['financiere',2000]]) { const a=await g.aids.request('b',{type:t,amount:m}); await g.aids.pay(a.id); }
+  const st=await g.stats(); assert.equal(st.total,3500); assert.equal(st.byType.financiere,3000); assert.equal(st.count,3);
+});
+await test('listes par bénéficiaire / type / statut', async()=>{
+  const g=mk(); await g.aids.request('b1',{type:'scolaire',amount:1}); const a=await g.aids.request('b1',{type:'medicale',amount:1});
+  assert.equal((await g.aids.listByBeneficiary('b1')).length,2);
+  assert.equal((await g.aids.byType('medicale')).length,1);
+  assert.equal((await g.aids.byStatus('requested')).length,2);
+});
+console.log(`\n✅ @mostajs/aid-grants — ${pass} tests OK`);