Mcollect Web Manager Lib (mcollecte-web-manager-lib)

Une bibliothèque TypeScript pour interagir avec l'API publique du système Mcollecte. Cette bibliothèque fournit des méthodes pratiques pour récupérer les informations du site, les articles de blog, les catégories, et les blocs de contenu utilisés dans les sites alimentés par Mcollecte.

Fonctionnalités

• Récupération des informations générales du site web.
• Récupération de la liste des catégories de blog.
• Récupération des articles de blog (tous ou par catégorie).
• Récupération d’un article de blog via son URL (slug), avec les articles similaires.
• Récupération de blocs de contenu personnalisés (blocs).
• Consultation d’un bloc spécifique via son ID (après initialisation).
• Réponses typées avec TypeScript.

Installation

npm install mcollecte-web-manager-lib

ou

yarn add mcollecte-web-manager-lib

Configuration

Voici comment configurer votre mcollect-web-manager-lin

    const url = "http://localhost:2006";
    const site_token = "29952c36-191d-405a-937d-cf31593123b7";
    const cls = new McollectWebManagerLib({ api_url: url, site_token: site_token });

Le api url c'est l'url source de votre api Le site_token est le token d'indentification de votre site web dans la partie admin mcollecte

Dans votre fichier .env

URL_API=http://localhost:2006
SITE_TOKEN=29952c36-191d-405a-937d-cf31593123b7

Utilisation

import McollectWebManagerLib from 'mcollecte-web-manager-lib';


// --- Example Usage (using async IIFE) ---   
export const Test = async () => {
    const url = "http://localhost:2006";
    const site_token = "29952c36-191d-405a-937d-cf31593123b7";
    const tokenUser = `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImRkZTQ1OGY3LWM1NTMtNDgyMy05YTRlLTAwNjQ0YTQ1MTIzZSIsInJvbGUiOiJVc2VyIiwiaWF0IjoxNzQ2MDM1Nzg4fQ.Yq0wQSsgxstfgHPM_sNUMp8cf16fivvf-xn3agunCKs`

    const cls = new McollectWebManagerLib({ api_url: url, site_token: site_token, tokenUser });

    try {
        // Initialize if your methods depend on pre-loaded data (like getBlocById might)
        // await cls.initialize(); // Uncomment if needed

        // --- Test Get Blog by URL ---
        // const blogsCategory = await cls.getBlogsCategory();
        // console.log('All blogsCategory :: ', blogsCategory);
        // const blogs = await cls.getBlogs();
        // console.log('All blogs :: ', blogs);  
        // const blogUrlSlug = 'je-suis-le-premier-blog'; 
        // console.log(`\nFetching blog by URL: ${blogUrlSlug}...`);
        // const blogDetail = await cls.getBlogByUrl(blogUrlSlug);
        // console.log('Blog found by URL:', blogDetail.blog.title);
        // console.log('Favorite Blogs Count in same category:', blogDetail.favoritBlogs.count);
        // if (blogDetail.favoritBlogs.rows.length > 0) {
        //     console.log('First favorite blog title:', blogDetail.favoritBlogs.rows[0].title);
        // }

        // --- Test Get Blogs by Category ---
        // const categoryIdToTest = '7331361b-8990-43d6-9db8-b73aaadd18de'; // Example category ID
        // console.log(`\nFetching blogs for category ID: ${categoryIdToTest}...`);
        // const blogsInCategory = await cls.getBlogsByCategory(categoryIdToTest);
        // console.log(`Found ${blogsInCategory.count} blog(s) in category ${categoryIdToTest}.`);
        // if (blogsInCategory.rows.length > 0) {
        //     console.log('First blog title in category:', blogsInCategory.rows[0].title);
        //     // You could loop through blogsInCategory.rows here
        // }

        // ---- Get bloc by Id 
        // const blocIdToTest = 'dbbea4bc-130f-4cab-a258-d7147d278561'; // Example bloc ID
        // console.log(`\nFetching bloc by ID: ${blocIdToTest}...`);
        // const bloc = await cls.getBlocById(blocIdToTest);
        // console.log('Fetched bloc:', bloc?.imageList);

        // ----- Test send message
        // await cls.createContactMessage({
        //     email: '[email protected]',
        //     message: "Je suis le message de test",
        //     name: 'Willson Antoine',
        //     sujet: 'Contact pour entrevue'
        // })

        // ----- Test get product
        // const result = await cls.getProduct({ categoryId: '', search: '', subCategoryId: '' });
        // console.log(result.product[0]);

        // ----- Test get members
        // const { count, rows } = await cls.getMembers();
        // console.log('Members:', rows);
        // console.log('Members count:', count);
        // if (rows.length > 0) {
        //     console.log('First member name:', rows[0].member.fullname);
        // } 
        // ------ Test signup   
        // const user = await cls.signUp({ name: 'user1', password: '1234', phone: '+243148250506', email: '[email protected]' });
        // console.log('User created:', user);

        // ------ Test resend OTP
        // const otp = await cls.resendOtp({ phone: '+243128250506' });
        // console.log('OTP sent:', otp);
        // ------ Test verify OTP 
        // const verify = await cls.verifyOtp({ otp: '480293', phone: '+243148250506' });
        // console.log('OTP verified:', verify);
        // ------ Test sign in 
        // const signIn = await cls.signIn({ phone: '+243148250506', password: '1234' });
        // console.log('User signed in:', signIn); 

        // ------ Recover password
        // const recoverPassword = await cls.recoverPassword({ phone: '+243990084881' });
        // console.log('Password recovered:', recoverPassword);
   
        // ------ Test commande
        // const commande = await cls.commande({
        //     phoneNumber: '+243148250522',
        //     payementMethod: 'mobile', lines: [
        //         { productId: 'c95a2bcc-8014-41da-8a28-e38359cb658f', quantity: 2 },
        //      ]
        // });
        // console.log('Commande response:', commande);

        // ------ getCommandes ------
        // Recuperer la liste des commandes
        // const { data } = await cls.getCommandes();
        // console.log(data);
        // for (let i = 0; i < data.length; i++) {
        //     const element = data[i];
        //     console.log('Commande:', element.lines);
        // }

        // --------- Get Current Profil
        // const profil = await cls.getCurrentProfil();
        // console.log('Profil Name:', profil.data?.username);

        // ---------- Update profil-----------
        // const updateProfil = await cls.updateProfil({
        //     username: 'willson', oldPassword: '@Aa12345678', password: '@Aa12345678', confirmPassword: '@Aa12345678'
        // });

        // console.log(updateProfil)

    } catch (error) {
        console.error("\n--- An error occurred during testing ---:", error);
    }
}

Test();

Pour envoyer un message via un formulaire de contact voici l'exemple de code:

 // ----- Test send message
        await cls.createContactMessage({
            email: '[email protected]',
            message: "message",
            name: 'mon_nom',
            sujet: 'suject'
        })

API

| Méthode | Description | |--------|-------------| | initialize() | Prépare la bibliothèque (nécessaire pour certains appels comme getBlocById). | | getWebInfo() | Récupère les informations du site. | | getBlogsCategory() | Récupère les catégories de blog disponibles. | | getBlogs() | Récupère les blogs publiés. | | getBlogByUrl(blogUrl: string) | Récupère un blog via son slug + suggestions. | | getBlogsByCategory(categoryId: string) | Blogs d'une catégorie spécifique. | | getBlocById(id: string) | Récupère un bloc via son ID. Nécessite initialize(). | | createContactMessage| Création du message via le formulaire de contact | | getProduct| Récupération des produits et catégories | | getMembers| Récupération des membres ou staff | | commande| Enregistrement du panier de l'utilisateur en cours... | signIn| Connexion utilisateur | signUp| Créeation du compte utilisateur | verifyOtp| Vérification de l'otp | resendOtp| Renvoie de l'otp | getCommandes| Récupération des commandes | recoverPassword| Récupération du mot de passe

Types TypeScript fournis

• ISiteInfos
• IBlogCategoryResponse
• BlogPost
• BlogApiResponse
• BlogByUrlResponse
• BlocItem
• BlocApiResponse
• CategoryDetail
• BlocText
• IContactMessage
• CategoryItem
• SubCategoryItem
• ProductItem
• ISiteMember
• IMember
• IUser
• ICommande

Import exemple :

import { BlocText } from "mcollecte-web-manager-lib";  

Récupération des produits et catégories

Cette méthode vous permet de récupérer dynamiquement la liste des produits ainsi que leurs catégories, avec la possibilité de filtrer par categoryId, subCategoryId, et terme de recherche.

Exemple d'utilisation

import McollectWebManagerLib from 'mcollecte-web-manager-lib';

const cls = new McollectWebManagerLib({
    api_url: "http://localhost:2006",
    site_token: "29952c36-191d-405a-937d-cf31593123b7"
});

(async () => {
    try {
        const result = await cls.getProduct({
            categoryId: "d3059a5f-94e2-4c8c-a02d-0ec90f8ccfab",
            subCategoryId: "cd71dd05-c922-474d-aca2-e5dcff1210da",
            search: "chemise"
        });

        console.log("Produits trouvés:", result.product);
        console.log("Catégories associées:", result.category);
    } catch (error) {
        console.error("Erreur lors de la récupération des produits :", error);
    }
})();

Signature de la méthode

getProduct({
    categoryId?: string,
    subCategoryId?: string,
    search?: string
}): Promise<{ product: ProductItem[], category: CategoryItem[] }>

Paramètres

| Nom | Type | Description | |-----|------|-------------| | categoryId | string | (Optionnel) L'identifiant de la catégorie principale. | | subCategoryId | string | (Optionnel) L'identifiant d'une sous-catégorie spécifique. | | search | string | (Optionnel) Terme de recherche pour filtrer les produits. |

Type de retour

{
    product: ProductItem[], // liste de produits trouvés
    category: CategoryItem[] // liste de catégories associées aux produits
}

Exemple de réponse typique

{
  "product": [
    {
      "id": "c95a2bcc-8014-41da-8a28-e38359cb658f",
      "name": "CHEMISE 100% POLYESTER",
      "url": "chemise-100-polyester",
      "description": "<p>Description</p><p>Détaillez les spécifications, avantages ou autres informations du produit.</p>",
      "price_min": 0,
      "price_max": 0,
      "unite": "sachet",
      "currency": {
        "id": "82fa5bb2-9378-48c7-abe6-a986c58d76de",
        "name": "USD"
      },
      "subCategory": {
        "name": "Habillement enfant",
        "category": {
          "name": "Matériels informatiques"
        }
      }
    }
  ],
  "category": [
    {
      "id": "d3059a5f-94e2-4c8c-a02d-0ec90f8ccfab",
      "name": "Matériels informatiques",
      "subCategories": [
        {
          "id": "cd71dd05-c922-474d-aca2-e5dcff1210da",
          "name": "Habillement enfant"
        }
      ]
    }
  ]
}

Affichage de la liste des membres ou du staff

Ce module permet de récupérer et d’afficher la liste des membres ou du personnel (staff) d’une organisation ou d’une entreprise sur un site web.

Exemple d'utilisation

// --- Récupération des membres
const { count, rows } = await cls.getMembers();

console.log('Liste des membres :', rows);
console.log('Nombre total de membres :', count);

if (rows.length > 0) {
    console.log('Nom du premier membre :', rows[0].member.fullname);
}

Interfaces

export interface ISiteMember {
    id: string;             // Identifiant unique du membre dans le site
    statusAt: string;       // Date à laquelle le statut a été attribué
    updatedAt: string;      // Date de la dernière mise à jour
    member: IMember;        // Informations détaillées du membre
}

export interface IMember {
    fullname: string;       // Nom complet du membre
    img: string;            // URL de l’image ou avatar du membre
    number: string;         // Numéro de téléphone ou identifiant
    adress: string;         // Adresse physique ou localisation
    fonction: IFonction;    // Fonction ou rôle au sein de l'organisation
}

export interface IFonction {
    name: string;           // Intitulé de la fonction
    description: string;    // Description du rôle ou des responsabilités
}

👤 Compte utilisateur (Account)

Cette section présente les principales opérations liées à la gestion du compte utilisateur dans mcollecte-web-manager-lib.

🔹 1. signUp(): Créer un compte utilisateur

const user = await cls.signUp({
  name: 'user1',
  password: '1234',
  phone: '+243148250506',
  email: '[email protected]'
});

console.log('User created:', user);

🔹 2. verifyOtp(): Vérifier le code OTP

const verify = await cls.verifyOtp({
  otp: '480293',
  phone: '+243148250506'
});

console.log('OTP verified:', verify);

🔹 3. signIn(): Connexion utilisateur

const signIn = await cls.signIn({
  phone: '+243148250506',
  password: '1234'
});

🔹 4. recoverPassword(): Restaurer le mot de passe via un numéro de téléphone

        const recoverPassword = await cls.recoverPassword({ phone: '+243000000000' });
        console.log('Password recovered:', recoverPassword);

console.log('User signed in:', signIn);

🔹 4. Commande ou panier : Pour permettre à un utilisateur connecté de soumettre son panier ou une commande de produits

Cette méthode permet à un utilisateur authentifié de passer une commande avec un ou plusieurs produits.

✅ Initialisation avec authentification :

Avant d'appeler la méthode commande(), il faut d'abord initialiser la bibliothèque avec un tokenUser (JWT) obtenu lors de la connexion (signIn).

const url = "http://localhost:2006";
const site_token = "29952c36-191d-405a-937d-cf31593123b7";
const tokenUser = `------token-------`;

const cls = new McollectWebManagerLib({
  api_url: url,
  site_token: site_token,
  tokenUser: tokenUser
});

🛒 Soumission d'une commande :

const commande = await cls.commande({
  phoneNumber: '+243148250506',
  payementMethod: 'mobile',
  lines: [
    { productId: 'c95a2bcc-8014-41da-8a28-e38359cb658f', quantity: 2 },
    { productId: 'c95a2bcc-8014-41da-8a28-e38359cb658f', quantity: 2 }
  ]
});

console.log('Commande response:', commande);

🧾 Paramètres :

• phoneNumber (string) : Numéro de téléphone de l'utilisateur connecté.
• payementMethod (string) : Méthode de paiement (ex : "mobile", "cash").
• lines (array) : Détails du panier :
  • productId (string) : ID unique du produit à commander.
  • quantity (number) : Quantité de ce produit.

🔐 Note :

L'utilisateur doit être connecté et le tokenUser doit être valide pour que la commande soit acceptée. Sinon, une erreur d'autorisation sera renvoyée.

Get Commandes:

    // Recuperer la liste des commandes
     const { data } = await cls.getCommandes();
    for (let i = 0; i < data.length; i++) {
            const element = data[i];
            console.log('Commande:', element.lines);
    }

À propos du concepteur

Ce projet a été conçu et développé par Willson Vulembere Antoine, ingénieur en informatique passionné par les technologies communautaires, l'agriculture et les systèmes numériques durables. Willson est spécialisé dans le développement backend, les architectures distribuées, et la conception de solutions technologiques pour des environnements à faible connectivité.

GitHub : @willsonantoine
Projet : mcollecte-web-manager-lib

Licence

Ce projet est sous licence MIT – vous pouvez l’utiliser librement dans vos projets personnels ou commerciaux.