SDK Node.js

SDK officiel Node.js/TypeScript pour l'API MonCréneau, publié sur npm.

Installation

npm install @moncreneau/api
# ou
yarn add @moncreneau/api
# ou
pnpm add @moncreneau/api

Configuration

import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

CommonJS :

const { default: Moncreneau } = require('@moncreneau/api');

const client = new Moncreneau('YOUR_API_KEY');

Avec variables d'environnement :

import Moncreneau from '@moncreneau/api';

const client = new Moncreneau(process.env.MONCRENEAU_API_KEY);

Lister les départements

import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

async function listDepartments() {
try {
  const departments = await client.departments.list();

  departments.forEach(dept => {
    console.log(`ID: ${dept.id} - ${dept.name}`);
  });
} catch (error) {
  console.error('Erreur:', error.message);
}
}

listDepartments();

Créer un rendez-vous

import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

async function createAppointment() {
try {
  const appointment = await client.appointments.create({
    departmentId: 5,
    dateTime: '2026-02-15T10:00:00',
    name: 'Amadou Diallo'
  });

  console.log('✅ Rendez-vous créé !');
  console.log('ID:', appointment.id);
  console.log('QR Code:', appointment.qrCode);
  console.log('Statut:', appointment.status);

} catch (error) {
  if (error.code === 'INSUFFICIENT_CREDITS') {
    console.error('❌ Crédits insuffisants:', error.message);
  } else {
    console.error('❌ Erreur:', error.message);
  }
}
}

createAppointment();

Vérifier la disponibilité d'un créneau

Le backend vérifie un créneau précis (dateTime), pas une plage de dates.

import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

async function checkAvailability() {
try {
  const availability = await client.departments.getAvailability(
    '5',
    '2026-02-15T10:00:00'
  );

  if (availability.available) {
    console.log('✅ Créneau disponible !');
    console.log('Places restantes:', availability.remainingSlots);
  } else {
    console.log('❌ Créneau indisponible');
    console.log('Raison:', availability.unavailabilityReason);
  }
} catch (error) {
  console.error('Erreur:', error.message);
}
}

checkAvailability();

Annuler un rendez-vous

import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

async function cancelAppointment(appointmentId) {
try {
  await client.appointments.cancel(appointmentId);
  console.log('✅ Rendez-vous annulé, 1 crédit remboursé');
} catch (error) {
  console.error('❌ Erreur:', error.message);
}
}

cancelAppointment('123');

Intégration Express

import express from 'express';
import Moncreneau from '@moncreneau/api';

const app = express();
app.use(express.json());

const client = new Moncreneau(process.env.MONCRENEAU_API_KEY);

// Créer un rendez-vous
app.post('/appointments', async (req, res) => {
try {
  const { departmentId, dateTime, name } = req.body;

  const appointment = await client.appointments.create({
    departmentId,
    dateTime,
    name
  });

  res.status(201).json(appointment);
} catch (error) {
  if (error.code === 'INSUFFICIENT_CREDITS') {
    return res.status(402).json({ error: error.message });
  }
  res.status(error.statusCode || 500).json({ error: error.message });
}
});

// Vérifier la disponibilité d'un créneau
app.get('/departments/:id/availability', async (req, res) => {
try {
  const { id } = req.params;
  const { dateTime } = req.query;

  const availability = await client.departments.getAvailability(id, dateTime);

  res.json(availability);
} catch (error) {
  res.status(error.statusCode || 500).json({ error: error.message });
}
});

app.listen(3000, () => {
console.log('Server running on port 3000');
});

Gestion des erreurs

Il n'existe qu'une seule classe d'erreur, MoncreneauError — le code métier se distingue via .code :

import Moncreneau, { MoncreneauError } from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

try {
const appointment = await client.appointments.create(data);
} catch (error) {
if (error instanceof MoncreneauError) {
  switch (error.code) {
    case 'INSUFFICIENT_CREDITS':
      console.error('Crédits insuffisants:', error.message);
      break;
    case 'VALIDATION_ERROR':
      console.error('Validation:', error.details);
      break;
    case 'INVALID_API_KEY':
      console.error('Clé API invalide');
      break;
    default:
      console.error(`Erreur ${error.code} (HTTP ${error.statusCode}):`, error.message);
  }
} else {
  console.error('Erreur réseau:', error);
}
}

Configuration avancée

import Moncreneau from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY', {
baseUrl: 'https://mc-prd.duckdns.org/api/v1',
timeout: 30000, // 30 secondes
maxRetries: 3
});

Vérification des webhooks

verifyWebhookSignature est une méthode statique sur la classe Moncreneau, pas une méthode d'instance :

import express from 'express';
import Moncreneau from '@moncreneau/api';

const app = express();

app.post('/webhooks/moncreneau', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-moncreneau-signature'];
const payload = req.body.toString('utf8');

const isValid = Moncreneau.verifyWebhookSignature(
  payload,
  signature,
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

const event = JSON.parse(payload);
console.log('Event:', req.headers['x-moncreneau-event'], event);

res.json({ received: true });
});

Voir Sécurité des webhooks pour le détail du format de signature.

TypeScript

Le SDK est écrit en TypeScript et exporte tous ses types :

import Moncreneau, {
Department,
Appointment,
CreateAppointmentRequest,
SlotAvailability
} from '@moncreneau/api';

const client = new Moncreneau('YOUR_API_KEY');

async function example(): Promise<void> {
const departments: Department[] = await client.departments.list();

const request: CreateAppointmentRequest = {
  departmentId: 5,
  dateTime: '2026-02-15T10:00:00',
  name: 'Amadou Diallo'
};

const appointment: Appointment = await client.appointments.create(request);
}