# agep-cargo Backend

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

Setup

1. 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

2. Install dependencies

   npm install

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

   psql "$DATABASE_URL" -f migrations/create_bookings.sql

4. 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.

1) 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"
   }

2) Accept the booking (replace <ID> by the returned id); this triggers the Postal email:

   PATCH http://localhost:3000/api/bookings/<ID>/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.