98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# 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.
|