mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-06-21 14:21:46 +00:00
jubnl
6ef3c7ae6b
* feat(reservations): native booking-confirmation import via KDE KItinerary
Adds a two-step preview → confirm flow for importing booking emails,
PDFs, PKPass and HTML confirmations. The server invokes the KDE
kitinerary-extractor binary, maps JSON-LD schema.org output to TREK
reservation shapes, and persists via the existing createReservation
pipeline (accommodations, budget, places, WebSocket broadcasts).
- NestJS BookingImportModule: preview + confirm endpoints under
/api/trips/:tripId/reservations/import/booking{,/confirm}
- KitineraryExtractorService: spawns the binary, filters stderr noise,
handles QDateTime (@value) timezone-aware datetimes
- kitinerary-mapper: FlightReservation, TrainReservation, BusReservation,
BoatReservation, LodgingReservation, FoodEstablishmentReservation,
RentalCarReservation, EventReservation → typed preview items
- BookingImportService: auto-creates place rows; geocodes venues without
coordinates via Nominatim (name+address → address → name fallback);
resolves day IDs for accommodation linking
- BookingImportModal: drag-and-drop multi-file upload, preview cards
with type icons, per-item exclude toggle, confirm step
- Shared Zod contracts: BookingImportPreviewItem, PreviewResponse,
ConfirmRequest, ConfirmResponse — consumed by controller, service,
API client and modal
- Dockerfile: node:24-trixie-slim runtime; amd64 downloads KDE static
binary + locales; arm64 installs libkitinerary-bin + symlinks to
fixed path; ENV KITINERARY_EXTRACTOR_PATH set for both arches
- /api/health/features exposes { bookingImport: boolean } so the UI
hides the Import button when the binary is absent
- i18n keys (English), wiki docs, API.md, README one-liner
* i18n: add booking import translations for all 19 non-English locales
Adds 17 reservations.import.* keys and undo.importBooking to ar, br, cs,
de, es, fr, gr, hu, id, it, ja, ko, nl, pl, ru, tr, uk, zh, zh-TW.
* chore: enforce i18n parity
* docs(wiki): add KItinerary local setup instructions to dev environment guide
131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
# Reservations & Bookings
|
||
|
||
Track all your trip bookings — hotels, restaurants, events, tours, and more — in one place.
|
||
|
||
## Where to find it
|
||
|
||
Open your trip in the planner and select the **Reservations** tab. The panel lists all bookings grouped by status, with a type filter bar at the top.
|
||
|
||
|
||
|
||
## Reservation types
|
||
|
||
TREK supports nine reservation types:
|
||
|
||
| Type | How to create |
|
||
|------|--------------|
|
||
| Flight | [Transport modal](Transport-Flights-Trains-Cars) |
|
||
| Train | [Transport modal](Transport-Flights-Trains-Cars) |
|
||
| Car | [Transport modal](Transport-Flights-Trains-Cars) |
|
||
| Cruise | [Transport modal](Transport-Flights-Trains-Cars) |
|
||
| Hotel | Add button in Reservations panel — see [Accommodations](Accommodations) |
|
||
| Restaurant | Add button in Reservations panel |
|
||
| Event | Add button in Reservations panel |
|
||
| Tour | Add button in Reservations panel |
|
||
| Other | Add button in Reservations panel |
|
||
|
||
Transport types (Flight, Train, Car, Cruise) are created through the dedicated Transport modal, where you can enter endpoint and transit-specific fields. All other types are created directly from the Reservations panel.
|
||
|
||
## Pending and Confirmed
|
||
|
||
Reservations are grouped into two collapsible sections: **Pending** and **Confirmed**. You can collapse or expand each section independently — the open/closed state is saved per trip so it persists across page reloads. Status is set when you create or edit a reservation.
|
||
|
||
On desktop, a type filter bar lets you show only specific types. Filter selections are kept for the current browser session.
|
||
|
||
## Reservation card contents
|
||
|
||
Each card displays:
|
||
|
||
- **Status dot** — green for Confirmed, amber for Pending
|
||
- **Type chip** — icon and label for the reservation type
|
||
- **Needs review badge** — an amber badge shown on reservations flagged by importers that may need your attention
|
||
- **Title** — the reservation name
|
||
- **Edit and delete buttons** — visible only if you have edit permission
|
||
|
||
> **Admin:** Edit and delete buttons are gated by the `reservation_edit` permission. Members without this permission see read-only cards.
|
||
|
||
- **Date and time range** — start date, and end date/time if set
|
||
- **From → To** — origin and destination endpoints, shown for transport types
|
||
- **Confirmation code** — displayed in monospace. If you have **Blur booking codes** enabled in Display Settings, the code is blurred by default and revealed on hover or tap
|
||
- **Type-specific metadata:**
|
||
- Flights: airline name, flight number
|
||
- Trains: train number, platform, seat
|
||
- Hotels: check-in window, check-out time (see [Accommodations](Accommodations))
|
||
- **Location / address** — for non-hotel, non-transport types
|
||
- **Linked accommodation** — hotel name, if this reservation is linked to an accommodation record
|
||
- **Day-plan assignment** — the day and place this reservation is linked to
|
||
- **Notes**
|
||
- **Attached files** — shown as clickable download links
|
||
|
||
## Creating a reservation
|
||
|
||
Click **Add** (or the + button) in the Reservations panel. Fill in the form:
|
||
|
||
1. **Type** — choose Hotel, Restaurant, Event, Tour, or Other
|
||
2. **Title** — required
|
||
3. **Link to day-plan assignment** — optional; search across all days and places, grouped by day. Not available for Hotel type
|
||
4. **Start date and time** — not shown for Hotel type
|
||
5. **End date and time** — not shown for Hotel type
|
||
6. **Location / address** — not shown for Hotel type
|
||
7. **Confirmation code**
|
||
8. **Status** — Pending or Confirmed
|
||
9. **Hotel-specific fields** — shown only for Hotel type, immediately after status: hotel place, check-in day, check-out day, check-in time (window start and end), and check-out time. See [Accommodations](Accommodations)
|
||
10. **Notes**
|
||
11. **Files** — attach from your device (PDF, Word documents, text files, images) or link an existing trip file. Files added before saving are uploaded automatically after the reservation is created
|
||
12. **Price and budget category** — shown only when the Budget addon is enabled. Entering a price greater than zero automatically creates a linked budget entry. See [Budget-Tracking](Budget-Tracking)
|
||
|
||
<!-- TODO: screenshot: Create Reservation modal -->
|
||
|
||
## Import from booking confirmation
|
||
|
||
TREK can parse booking confirmation emails, PDFs, and pass files and create reservations automatically using [KDE Itinerary](https://apps.kde.org/itinerary/).
|
||
|
||
### Supported formats
|
||
|
||
| Format | Extension |
|
||
|--------|-----------|
|
||
| Booking confirmation email | `.eml` |
|
||
| PDF ticket or confirmation | `.pdf` |
|
||
| Apple Wallet pass | `.pkpass` |
|
||
| HTML confirmation page | `.html`, `.htm` |
|
||
| Plain-text email | `.txt` |
|
||
|
||
Up to 5 files, 10 MB each, per import.
|
||
|
||
### How to import
|
||
|
||
1. Open the **Reservations** tab.
|
||
2. Click the **Import** (download) button in the toolbar — the button is only shown when the extractor is available on your server.
|
||
3. Drag and drop your files onto the upload area, or click to browse.
|
||
4. TREK parses each file and shows a **preview list** of the detected reservations with type, title, dates, endpoints, and confirmation number.
|
||
5. Deselect any items you do not want to import by clicking the × on their card.
|
||
6. Click **Confirm** to create the selected reservations.
|
||
|
||
All created reservations appear immediately in the panel and are broadcast to all connected trip members in real time.
|
||
|
||
### What gets created automatically
|
||
|
||
- **Hotels** — a reservation *and* a linked accommodation row in the day plan (check-in/check-out dates are read from the confirmation).
|
||
- **Hotels / Restaurants / Events** — the venue is auto-created as a place with coordinates when the extractor returns location data.
|
||
- **All types** — a budget entry is created if the Budget addon is enabled and a price is present.
|
||
|
||
### When the button is not visible
|
||
|
||
The Import button is hidden when the `kitinerary-extractor` binary is not available. The binary ships inside the official TREK Docker image. If you run TREK from source, install the `libkitinerary-bin` package (Debian trixie / Ubuntu 25.04+) or set `KITINERARY_EXTRACTOR_PATH` to the binary's full path. See [Environment-Variables](Environment-Variables).
|
||
|
||
### Needs review flag
|
||
|
||
Items that the extractor could only partially parse are flagged **Needs review** — an amber badge on the card. Review these reservations after import and fill in any missing fields manually.
|
||
|
||
## Editing and deleting
|
||
|
||
Each card has a pencil icon to open the edit form and a trash icon to delete. Deleting requires confirmation in a dialog before the record is removed.
|
||
|
||
## Real-time sync
|
||
|
||
Reservation changes (create, update, delete) are broadcast instantly to all connected trip members via WebSocket, so everyone sees the latest state without refreshing.
|
||
|
||
---
|
||
|
||
**See also:** [Transport-Flights-Trains-Cars](Transport-Flights-Trains-Cars) · [Accommodations](Accommodations) · [Budget-Tracking](Budget-Tracking) · [Documents-and-Files](Documents-and-Files) · [Trip-Planner-Overview](Trip-Planner-Overview)
|