agep-cargo/backend/README.md

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

1. Create a pending booking (adjust dates and recipient):

   curl -sS -X POST http://localhost:3000/api/bookings
   -H 'Content-Type: application/json'
   -d '{ "bike_types": [1000], "start_date": "2025-10-20", "start_time": "10:00", "end_date": "2025-10-20", "end_time": "12:00", "name": "Association Test", "email": "recipient@example.com" }'

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

   curl -sS -X PATCH http://localhost:3000/api/bookings//status
   -H 'Content-Type: application/json'
   -d '{"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.