agep-cargo Backend

This is a minimal Express backend for the AGEPOLY cargobike booking platform.

Setup

Copy the example env file and update it:

cp .env.example .env

then edit .env to set DATABASE_URL

and (optional) Postal settings for email sending
Install dependencies

npm install
Run migration (using psql or your database tool) to create the bookings table:

psql "$DATABASE_URL" -f migrations/create_bookings.sql
Start the server

npm run dev

API

GET /api/health - health check
GET /api/bikes - list available bike types
POST /api/bookings - create a booking (bike_type, start_date, end_date, name, email)
GET /api/bookings - list recent bookings
PATCH /api/bookings/:id/status - update booking status (pending | accepted | refused)
PATCH /api/bookings/:id - update booking fields
DELETE /api/bookings/:id - delete a booking

Email sending (Postal)

When a booking is transitioned to "accepted", the backend attempts to send a confirmation email to the booking's email address(es) using Postal.

Configuration (in .env):

POSTAL_URL: Base URL of your Postal server (no trailing slash), e.g. https://postal.example.com
POSTAL_API_KEY: API key with permission to send messages
POSTAL_FROM: From email address used for sending, e.g. no-reply@yourdomain.tld
POSTAL_FROM_NAME: Optional display name for the from address (e.g. "AGEP Cargobike")
POSTAL_REPLY_TO: Optional reply-to email address

Notes:

If Postal variables are not set, the server will skip email sending and log a warning.
Multiple recipient emails are supported; separate with commas or semicolons.

Quick test of email sending

Use a date within the next 31 days (inclusive) to satisfy the booking window restriction.

Create a pending booking (adjust dates and recipient):

POST http://localhost:3000/api/bookings Content-Type: application/json { "bike_types": [1000], "start_date": "<YYYY-MM-DD within 31 days>", "start_time": "10:00", "end_date": "<same day or within 31 days>", "end_time": "12:00", "name": "Association Test", "email": "recipient@example.com" }
Accept the booking (replace by the returned id); this triggers the Postal email:

PATCH http://localhost:3000/api/bookings//status Content-Type: application/json { "status": "accepted" }

If Postal is configured correctly, a confirmation email will be sent in the background. Check your Postal logs if you need to diagnose delivery.

Telegram notifications

The backend can notify a Telegram chat or group whenever a new booking request is created.

Configuration (in .env):

TELEGRAM_BOT_TOKEN: Bot token obtained from @BotFather
TELEGRAM_CHAT_ID: Chat ID to send messages to. For groups/supergroups this is often a negative number like -1001234567890. You can provide multiple IDs separated by commas or semicolons to broadcast to several chats.
FRONTEND_URL: Optional. Base URL of your frontend (must be an absolute http/https URL). When set, the Telegram message includes an "Ouvrir admin" button linking to ${FRONTEND_URL}/admin. If not set or not absolute, the admin button is omitted to avoid Telegram URL errors.

Behavior:

On POST /api/bookings (new request), a message is posted with the association name, requested period, and selected cargobikes.
Messages use Telegram's HTML parse mode. The format is defined in server.js where the msg string is constructed.

Local smoke test (no real network):

Run scripts/test-telegram-local.js to see the constructed payload and a mocked success response.

Notes:

If the Telegram env variables are not set, notifications are skipped and a warning is logged; booking creation is not interrupted.
Ensure the bot is added to the target group and the bot has permission to send messages.

then edit .env to set DATABASE_URL