Modules API

Référence rapide pour savoir où chercher un endpoint. Chaque module est un dossier dans packages/api/src/modules/<module>/ suivant la structure modulaire.

Vue d'ensemble

Module	Prefix	Auth	Usage
cardex	`/cardex`	staff+	gestion des guests
rooms	`/rooms`	staff+	inventory chambres
booking	`/booking`	auth	services guest (restaurant/room-service/laundry/spa)
chat	`/chat`	auth	conversations guest ↔ AI ↔ staff
ai	`/ai`	auth	concierge IA (streaming)
payment	`/payment`	auth	Stripe Payment Intents
integrations	`/integrations`	admin+	PMS adapters config
tickets	`/tickets`	staff+	escalations
today	`/today`	staff+	notes staff du jour
menu	`/menu`	staff+ (CRUD), auth (read)	catalogue services
users	`/users`	manager+	staff list + invite
analytics	`/analytics`	manager+	KPIs et reports
auth proxy	`/api/auth/*`	—	Better Auth handler
webhooks	`/webhooks/:provider`	HMAC	ingestion PMS / Stripe
health	`/health`	—	liveness probe

cardex

Gestion des profils guest (lecture, création, lien avec user, envoi d'email de check-in, confirmation d'arrivée, checkout).

Méthode	Route	Auth	Résumé
`GET`	`/cardex/guests`	staff+	Liste guests (query: search, vipOnly, staying)
`GET`	`/cardex/guests/:id`	staff+	Détail guest
`GET`	`/cardex/guest-groups/:id`	staff+	Détail groupe + membres
`POST`	`/cardex/guests`	staff+	Création manuelle guest
`PATCH`	`/cardex/guests/:id`	staff+	Update guest
`DELETE`	`/cardex/guests/:id`	manager+	Soft delete
`POST`	`/cardex/guests/toggle-vip`	staff+	Bulk toggle VIP (body: `{ guestIds, isVip }`)
`POST`	`/cardex/send-check-in-email`	staff+	Reacher + BullMQ send (body: `{ guestId }`)
`POST`	`/cardex/confirm-arrival`	staff+	Passe `arrived`, bridge PMS check-in
`POST`	`/cardex/checkout-guest`	staff+	Passe `checked_out`, bridge PMS process
`POST`	`/cardex/link-guest-to-user`	auth	Post-signup : lier guest existant au user
`POST`	`/cardex/complete-check-in`	auth	Guest : marquer digital done
`GET`	`/cardex/my-status`	auth	Guest : fetch `check_in_status` courant
`GET`	`/cardex/status-stream`	auth	Guest : SSE pour unlock

rooms

CRUD de l'inventory, update status + bridge PMS.

Méthode	Route	Auth	Résumé
`GET`	`/rooms`	staff+	Liste rooms (query: status, type, floor)
`GET`	`/rooms/:id`	staff+	Détail room
`POST`	`/rooms`	manager+	Création room
`PATCH`	`/rooms/:id`	manager+	Update room
`DELETE`	`/rooms/:id`	manager+	Delete
`POST`	`/rooms/update-status`	staff+	Update status (body: `{ roomId, status }`), bridge PMS

booking

Sous-modules : restaurant, room-service, laundry, spa. Chaque sous-module a le même pattern.

Méthode	Route	Auth	Résumé
`POST`	`/booking/restaurant`	auth (guest)	Crée restaurant_booking
`GET`	`/booking/restaurant/mine`	auth (guest)	Liste mes bookings restaurant
`GET`	`/booking/restaurant`	staff+	Liste toutes les bookings restaurant de l'org
`POST`	`/booking/restaurant/update-status`	staff+	Update status
(idem pour `/booking/room-service`, `/booking/laundry`, `/booking/spa`)

Tous : création enqueue job bridgePostCharges vers PMS après paiement confirmé (webhook Stripe).

chat

Conversations unifiées (guest_ai / guest_staff / staff_internal).

Méthode	Route	Auth	Résumé
`GET`	`/chat/active`	staff+	Liste des chats actifs (query: search, priority, isResolved)
`GET`	`/chat/:id`	staff+	Détail conversation + messages
`POST`	`/chat/:id/send-reply`	staff+	Staff envoie un message
`POST`	`/chat/:id/assign`	staff+	Assigner à un staff
`POST`	`/chat/:id/update-metadata`	staff+	Priority / tags
`POST`	`/chat/:id/mark-resolved`	staff+	Toggle is_resolved
`POST`	`/chat/:id/escalate`	auth (guest)	Guest demande un humain
`GET`	`/chat/:id/stream`	auth	SSE messages

ai

Concierge IA. Utilise @elysiajs/ai-sdk.

Méthode	Route	Auth	Résumé
`POST`	`/ai/chat`	auth	Envoie un message, streame la réponse (SSE)
`POST`	`/ai/generate-title`	auth	AI-generate titre d'une conversation depuis le premier message
`GET`	`/ai/user-profile`	auth	Contexte du guest courant (room, hôtel, dates) pour l'UI

payment

Stripe. Tout est async via webhook.

Méthode	Route	Auth	Résumé
`POST`	`/payment/create-intent`	auth	Crée PaymentIntent Stripe (amount, currency, metadata)
`GET`	`/payment/status/:intentId`	auth	Vérifie statut côté Stripe
`POST`	`/webhooks/stripe`	HMAC	Reçoit webhook Stripe, verify signature, enqueue job

integrations

Hub PMS.

Méthode	Route	Auth	Résumé
`GET`	`/integrations`	admin+	Liste les intégrations de l'org
`POST`	`/integrations/configure`	admin+	Add/update (body: provider, credentials, platformUrl) — test connexion
`POST`	`/integrations/:id/full-sync`	admin+	Enqueue full sync immédiat
`POST`	`/integrations/:id/toggle`	admin+	Activate / deactivate
`DELETE`	`/integrations/:id`	admin+	Delete
`GET`	`/integrations/:id/sync-logs`	admin+	Logs sync (pagination)
`POST`	`/webhooks/mews`	HMAC	Webhook Mews entrant
`POST`	`/webhooks/opera`	HMAC	Webhook Opera entrant (futur)
`POST`	`/webhooks/:provider`	HMAC	Dynamic webhook endpoint

tickets

Escalations.

Méthode	Route	Auth	Résumé
`GET`	`/tickets`	staff+	Liste (query: status, priority, category)
`GET`	`/tickets/stats`	staff+	Counts par statut
`GET`	`/tickets/:id`	staff+	Détail + comments
`POST`	`/tickets`	staff+	Création (body: conversationId?, category, priority, title, description)
`POST`	`/tickets/:id/update-status`	staff+	Change status (state machine validé)
`POST`	`/tickets/:id/assign`	manager+	Assign to staff
`POST`	`/tickets/:id/comments`	staff+	Ajouter un commentaire

today

Staff notes.

Méthode	Route	Auth	Résumé
`GET`	`/today/notes`	staff+	Liste (query: status, priority, search)
`POST`	`/today/notes`	staff+	Création
`PATCH`	`/today/notes/:id`	staff+	Update (comment trail enregistré)
`POST`	`/today/notes/:id/update-status`	staff+	Change status
`DELETE`	`/today/notes/:id`	staff+	Delete
`GET`	`/today/notes/:id/history`	staff+	Audit trail

Catalogue des services.

Méthode	Route	Auth	Résumé
`GET`	`/menu/categories`	auth	Liste categories (query: categoryType)
`GET`	`/menu/categories/:id`	auth	Catégorie + items
`POST`	`/menu/categories`	manager+	Création
`PATCH`	`/menu/categories/:id`	manager+	Update
`DELETE`	`/menu/categories/:id`	manager+	Delete
`GET`	`/menu/items`	auth	Liste items (query: categoryId, featured)
`POST`	`/menu/items`	manager+	Création item
`PATCH`	`/menu/items/:id`	manager+	Update item
`DELETE`	`/menu/items/:id`	manager+	Delete item

users

Staff + invitations (Better Auth en backend).

Méthode	Route	Auth	Résumé
`GET`	`/users/me`	auth	Mon profil + mes orgs
`GET`	`/users`	manager+	Liste staff + invitations pending
`POST`	`/users/invite`	manager+	Invite par email (délègue à Better Auth)
`POST`	`/users/:id/update-role`	owner	Change role
`DELETE`	`/users/:id`	owner	Révoquer du org
`DELETE`	`/users/invitations/:id`	manager+	Annuler invitation

analytics

KPIs et reports.

Méthode	Route	Auth	Résumé
`GET`	`/analytics/hotel-stats`	manager+	RevPAR, Occupancy, Revenue, Satisfaction (live)
`GET`	`/analytics/interactions`	manager+	Chats/jour (period, offset)
`GET`	`/analytics/conversion`	manager+	Funnel chat → booking
`GET`	`/analytics/time-saved`	manager+	Minutes économisées par l'IA
`GET`	`/analytics/requests`	manager+	Breakdown par service
`GET`	`/analytics/satisfaction`	manager+	% positives
`GET`	`/analytics/upsells`	manager+	Revenus upsells par canal
`GET`	`/analytics/activity`	manager+	Heatmap horaire
`GET`	`/calendar/overview`	staff+	Calendar mensuel (arrivées, départs, events)

auth proxy

Les routes /api/auth/* sont gérées directement par Better Auth — pas dans un module Elysia manuel. On monte betterAuth.handler sur ces paths.

Endpoints standards :

POST /api/auth/sign-up
POST /api/auth/sign-in/email
POST /api/auth/sign-out
POST /api/auth/forget-password
POST /api/auth/reset-password
POST /api/auth/organization/invite
POST /api/auth/organization/accept-invitation
POST /api/auth/magic-link/send
GET /api/auth/magic-link/verify

webhooks

Méthode	Route	Verify	Action
`POST`	`/webhooks/stripe`	HMAC Stripe signature	Update payment status, enqueue process job
`POST`	`/webhooks/mews`	HMAC Mews webhookSecret	Enqueue sync entity
`POST`	`/webhooks/:provider`	HMAC par provider	Dynamic ingestion

Tous retournent 200 immédiatement (acknowledgment), le traitement est async via BullMQ.

health

Méthode	Route	Auth	Résumé
`GET`	`/health`	—	Liveness (DB ping, Redis ping)
`GET`	`/health/ready`	—	Readiness (schema migrations up, BullMQ reachable)

Utilisé par Docker healthcheck + Dokploy.

Ajouter un nouveau module

Voir le skill bell-feature-module (à scaffolder) ou manuellement :

mkdir packages/api/src/modules/<name>/
Créer <name>.schemas.ts, <name>.service.ts, <name>.repository.ts, <name>.routes.ts
Tester avec <name>.service.test.ts + <name>.routes.test.ts
Ajouter l'import + .use(<name>Module) dans packages/api/src/index.ts
Le type App se met à jour, Eden Treaty côté client détecte automatiquement le nouveau module

Modules API

On this page