docs: rewrite API docs in txt endpoint-by-endpoint format

docs/API_MANUAL.md

@@ -1,622 +0,0 @@
-# Trisolaris Server API Manual (Manual, No Script)
-
-Last updated: 2026-02-04
-Source: current Kotlin controllers in this repo.
-
-## Global rules
-
-- Base API domain: `api.hoteltrisolaris.in`
-- Auth: Firebase bearer token (`MyPrincipal`) for all non-public endpoints.
-- Super admin bypass: property membership/role checks are bypassed by `superAdmin=true` (via `PropertyAccess`).
-- Global API error shape:
-  ```json
-  {
-    "timestamp": "...",
-    "status": 400,
-    "error": "Bad Request",
-    "message": "...",
-    "path": "/..."
-  }
-  ```
-- Common auth/permission errors:
-  - `401 Unauthorized`: missing principal / user not found
-  - `403 Forbidden`: missing membership/role
-
-## Public endpoints (no auth required)
-
-- `GET /`
-- `GET /health`
-- `GET /auth/*`
-- `GET /properties/{propertyId}/rooms/available`
-- `GET /properties/{propertyId}/rooms/by-type/{roomTypeCode}`
-- `GET /properties/{propertyId}/room-types`
-- `GET /properties/{propertyId}/room-types/{roomTypeCode}/images`
-- `GET /properties/{propertyId}/rooms/{roomId}/images`
-- `GET /properties/{propertyId}/rooms/{roomId}/images/{imageId}/file`
-- `GET /properties/{propertyId}/guests/{guestId}/documents/{documentId}/file` (or token-based access)
-- `GET /properties/{propertyId}/cancellation-policy`
-- `GET /image-tags`
-- `GET /icons/png`
-- `GET /icons/png/{filename}`
-- `POST /properties/{propertyId}/razorpay/webhook`
-- `POST /properties/{propertyId}/razorpay/return/success`
-- `POST /properties/{propertyId}/razorpay/return/failure`
-
-## Core storage map
-
-- Property + config: `property`, `property_email_address`, `property_email_alias`, `property_transport_mode`
-- Users + membership: `app_user`, `property_user`, `property_user_role`, `property_access_code`, `property_access_code_role`
-- Room inventory: `room_type`, `room_type_alias`, `room_type_amenity_link`, `room`, `room_amenity`
-- Stays + cards: `room_stay`, `room_stay_audit_log`, `issued_card`, `property_card_counter`
-- Booking + billing: `booking`, `booking_room_request`, `booking_billing_policy_audit_log`, `charge`, `payment`
-- Guest data: `guest`, `guest_vehicle`, `guest_rating`, `guest_document`
-- Rates: `rate_plan`, `rate_calendar`
-- Email ingest: `inbound_email`
-- Room media: `room_image`, `room_image_tag`, `room_image_tag_link`
-- Razorpay: `razorpay_settings`, `razorpay_qr_request`, `razorpay_payment_link_request`, `razorpay_payment_attempt`, `razorpay_webhook_log`
-- File storage roots:
-  - documents/signatures: `/home/androidlover5842/docs`
-  - emails: `/home/androidlover5842/docs/emails`
-  - room images: `/home/androidlover5842/docs/rooms`
-  - icons: `/home/androidlover5842/docs/icons/png`
-
----
-
-## 1) Auth APIs
-
-- `POST /auth/verify`
-  - What it does: resolves Firebase principal (creates app user if missing), returns user + property memberships.
-  - Access: public.
-  - Stores data: may insert/update `app_user`; reads `property_user`.
-- `GET /auth/me`
-  - What it does: same shape as verify.
-  - Access: public.
-  - Stores data: may create `app_user` if resolver is used.
-- `PUT /auth/me`
-  - Request: `{ "name": "..." }`
-  - What it does: updates current user name.
-  - Access: authenticated user.
-  - Stores data: updates `app_user.name`.
-
-## 2) System + Static assets
-
-- `GET /health` / `GET /`
-  - What it does: health payload with build identifier.
-  - Access: public.
-  - Stores data: none.
-- `GET /icons/png`
-  - What it does: lists PNG filenames in icon root.
-  - Access: public.
-  - Stores data: reads filesystem only.
-- `GET /icons/png/{filename}`
-  - What it does: serves icon PNG.
-  - Access: public.
-  - Stores data: reads filesystem only.
-
-## 3) Property + User management
-
-- `POST /properties`
-  - Request: `PropertyCreateRequest`.
-  - Access: authenticated user.
-  - Stores data: inserts `property` (+ email/alias/transport collections); inserts `property_user` with `ADMIN`.
-- `GET /properties`
-  - What it does: list properties (all for super admin, memberships for others).
-  - Access: authenticated user.
-  - Stores data: reads `property`, `property_user`.
-- `GET /properties/{propertyId}/code`
-  - Access: property member.
-  - Stores data: reads `property.code`.
-- `PUT /properties/{propertyId}`
-  - Request: `PropertyUpdateRequest`.
-  - Access: `ADMIN`.
-  - Stores data: updates `property` and its collection tables.
-- `GET /properties/{propertyId}/billing-policy`
-  - Access: property member.
-  - Stores data: reads `property.billing_checkin_time`, `property.billing_checkout_time`.
-- `PUT /properties/{propertyId}/billing-policy`
-  - Request: `PropertyBillingPolicyRequest`.
-  - Access: `ADMIN`.
-  - Stores data: updates `property` billing policy.
-- `GET /properties/{propertyId}/users`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: reads `property_user`, `app_user`.
-- `PUT /properties/{propertyId}/users/{userId}/roles`
-  - Request: `PropertyUserRoleRequest`.
-  - Access: super admin / `ADMIN` / `MANAGER` (role-limited by hierarchy).
-  - Stores data: upserts `property_user` + `property_user_role`.
-- `PUT /properties/{propertyId}/users/{userId}/disabled`
-  - Request: `PropertyUserDisableRequest`.
-  - Access: hierarchy-based.
-  - Stores data: updates `property_user.is_disabled`.
-- `DELETE /properties/{propertyId}/users/{userId}`
-  - Access: `ADMIN`.
-  - Stores data: deletes `property_user` membership.
-
-### Access codes + directory
-
-- `POST /properties/{propertyId}/access-codes`
-  - Request: `PropertyAccessCodeCreateRequest` (`roles`, no `ADMIN`).
-  - Access: `ADMIN`.
-  - Stores data: inserts `property_access_code` + `property_access_code_role` (1-minute expiry).
-- `POST /properties/access-codes/join`
-  - Request: `PropertyAccessCodeJoinRequest` (`propertyCode` + `code`).
-  - Access: authenticated.
-  - Stores data: inserts `property_user`; marks `property_access_code.used_at/used_by`.
-- `GET /users`
-  - Query: optional `phone`.
-  - Access: super admin only.
-  - Stores data: reads `app_user`.
-- `GET /properties/{propertyId}/users/search`
-  - Query: optional `phone`.
-  - Access: `ADMIN`.
-  - Stores data: reads `property_user`, `app_user`.
-
-### Cancellation policy + transport modes
-
-- `GET /properties/{propertyId}/cancellation-policy`
-  - Access: public.
-  - Stores data: reads `property_cancellation_policy` (or default response).
-- `PUT /properties/{propertyId}/cancellation-policy`
-  - Request: `CancellationPolicyUpsertRequest`.
-  - Access: `ADMIN`.
-  - Stores data: upserts `property_cancellation_policy`.
-- `GET /properties/{propertyId}/transport-modes`
-  - Access: property member.
-  - Stores data: reads `property.allowedTransportModes`.
-
-## 4) Room amenities + image tags
-
-- `GET /amenities`
-  - Access: authenticated.
-  - Stores data: reads `room_amenity`.
-- `POST /amenities`
-  - Request: `AmenityUpsertRequest`.
-  - Access: super admin only.
-  - Stores data: inserts `room_amenity`.
-- `PUT /amenities/{amenityId}`
-  - Request: `AmenityUpsertRequest`.
-  - Access: super admin only.
-  - Stores data: updates `room_amenity`.
-- `DELETE /amenities/{amenityId}`
-  - Access: super admin only.
-  - Stores data: deletes `room_amenity`; removes links from `room_type_amenity_link`.
-
-- `GET /image-tags`
-  - Access: public.
-  - Stores data: reads `room_image_tag`.
-- `POST /image-tags`
-  - Request: `RoomImageTagUpsertRequest`.
-  - Access: super admin only.
-  - Stores data: inserts `room_image_tag`.
-- `PUT /image-tags/{tagId}`
-  - Request: `RoomImageTagUpsertRequest`.
-  - Access: super admin only.
-  - Stores data: updates `room_image_tag`.
-- `DELETE /image-tags/{tagId}`
-  - Access: super admin only.
-  - Stores data: deletes links from `room_image_tag_link`, deletes `room_image_tag`.
-
-## 5) Room types
-
-- `GET /properties/{propertyId}/room-types`
-  - Access: public (or member when auth present).
-  - Stores data: reads `room_type` + alias/amenity links.
-- `POST /properties/{propertyId}/room-types`
-  - Request: `RoomTypeUpsertRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: inserts `room_type`, `room_type_alias`, `room_type_amenity_link`.
-- `PUT /properties/{propertyId}/room-types/{roomTypeId}`
-  - Request: `RoomTypeUpsertRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: updates `room_type` and links.
-- `DELETE /properties/{propertyId}/room-types/{roomTypeId}`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: soft delete by setting `room_type.is_active=false`.
-- `GET /properties/{propertyId}/room-types/{roomTypeCode}/rate?date=...&ratePlanCode=...`
-  - Access: public/member.
-  - Stores data: reads `room_type`, `rate_plan`, `rate_calendar`.
-
-## 6) Rooms + availability + board
-
-- `GET /properties/{propertyId}/rooms`
-  - Access: property member (agents see only free sellable rooms).
-  - Stores data: reads `room`, active stays in `room_stay`, temp cards in `issued_card`.
-- `POST /properties/{propertyId}/rooms`
-  - Request: `RoomUpsertRequest`.
-  - Access: `ADMIN`.
-  - Stores data: inserts `room`.
-- `PUT /properties/{propertyId}/rooms/{roomId}`
-  - Request: `RoomUpsertRequest`.
-  - Access: `ADMIN`.
-  - Stores data: updates `room`.
-- `DELETE /properties/{propertyId}/rooms/{roomId}`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: deletes room image files + `room_image` rows, then deletes `room` (blocked if any `room_stay` exists).
-
-- `GET /properties/{propertyId}/rooms/board`
-  - Access: member (agent filtered to FREE).
-  - Stores data: reads `room`, active occupancy from `room_stay`.
-- `GET /properties/{propertyId}/rooms/board/stream`
-  - Access: member.
-  - Stores data: no writes; SSE from derived room board events.
-- `GET /properties/{propertyId}/rooms/availability`
-  - Access: member.
-  - Stores data: reads `room`, `room_stay`.
-- `GET /properties/{propertyId}/rooms/available`
-  - Access: public.
-  - Stores data: reads `room`, `room_stay`, `issued_card`.
-- `GET /properties/{propertyId}/rooms/by-type/{roomTypeCode}?availableOnly=true|false`
-  - Access: public.
-  - Stores data: reads `room_type`, `room`, `room_stay`, `issued_card`.
-- `GET /properties/{propertyId}/rooms/availability-range?from=YYYY-MM-DD&to=YYYY-MM-DD`
-  - Access: member.
-  - Stores data: reads `room`, `room_stay`, `property.timezone`.
-- `GET /properties/{propertyId}/rooms/available-range-with-rate?from=...&to=...&ratePlanCode=...`
-  - Access: member.
-  - Stores data: reads `room`, `room_stay`, `rate_plan`, `rate_calendar`, `property`.
-
-## 7) Room images
-
-- `GET /properties/{propertyId}/rooms/{roomId}/images`
-  - Access: public.
-  - Stores data: reads `room_image`; deletes missing-file rows; reads filesystem.
-- `POST /properties/{propertyId}/rooms/{roomId}/images`
-  - Multipart: file + optional `tagIds`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: writes files under `/docs/rooms`; inserts `room_image` + `room_image_tag_link`.
-- `DELETE /properties/{propertyId}/rooms/{roomId}/images/{imageId}`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: deletes files + `room_image`; reorders sort fields.
-- `PUT /properties/{propertyId}/rooms/{roomId}/images/{imageId}/tags`
-  - Request: `RoomImageTagUpdateRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: updates `room_image_tag_link`.
-- `PUT /properties/{propertyId}/rooms/{roomId}/images/reorder-room`
-  - Request: `RoomImageReorderRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: updates `room_image.sort_order`.
-- `PUT /properties/{propertyId}/rooms/{roomId}/images/reorder-room-type`
-  - Request: `RoomImageReorderRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: updates `room_image.room_type_sort_order`.
-- `GET /properties/{propertyId}/rooms/{roomId}/images/{imageId}/file?size=full|thumb`
-  - Access: public/member.
-  - Stores data: reads filesystem + `room_image` metadata.
-- `GET /properties/{propertyId}/room-types/{roomTypeCode}/images`
-  - Access: public.
-  - Stores data: reads `room_image`; prunes missing-file rows.
-
-## 8) Room stays + cards
-
-- `GET /properties/{propertyId}/room-stays/active`
-  - Access: member except AGENT-only users.
-  - Stores data: reads `room_stay`, `booking`, `guest`, `room`.
-- `POST /properties/{propertyId}/room-stays/{roomStayId}/void`
-  - Request: `RoomStayVoidRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF` (staff blocked after first booking payment).
-  - Stores data: updates `room_stay` (`is_voided`, `to_at`), inserts `room_stay_audit_log`, may update `booking` to `CHECKED_OUT`.
-
-### Issued cards (room stay)
-
-- `POST /properties/{propertyId}/room-stays/{roomStayId}/cards/prepare`
-  - Request: `CardPrepareRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: increments `property_card_counter`; returns encoded payload only.
-- `POST /properties/{propertyId}/room-stays/{roomStayId}/cards`
-  - Request: `IssueCardRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: inserts `issued_card`.
-- `GET /properties/{propertyId}/room-stays/{roomStayId}/cards`
-  - Access: `STAFF`/`ADMIN`/`MANAGER`/`SUPERVISOR`.
-  - Stores data: reads `issued_card`.
-- `POST /properties/{propertyId}/room-stays/cards/{cardIndex}/revoke`
-  - Access: ADMIN for regular cards; ADMIN/MANAGER for temp cards.
-  - Stores data: updates `issued_card.revoked_at` and `expires_at`.
-- `GET /properties/{propertyId}/room-stays/cards/{cardIndex}`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: reads `issued_card`.
-
-### Temporary room cards
-
-- `POST /properties/{propertyId}/rooms/{roomId}/cards/prepare-temp`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: increments `property_card_counter`; returns payload only.
-- `POST /properties/{propertyId}/rooms/{roomId}/cards/temp`
-  - Request: `IssueTempCardRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: inserts temp `issued_card` (7-minute expiry).
-
-## 9) Booking APIs
-
-- `POST /properties/{propertyId}/bookings`
-  - Request: `BookingCreateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: inserts `booking`; creates placeholder `guest` if needed.
-- `GET /properties/{propertyId}/bookings?status=...`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`/`HOUSEKEEPING`/`FINANCE`.
-  - Stores data: reads `booking`, `room_stay`, `charge`, `payment`.
-- `GET /properties/{propertyId}/bookings/{bookingId}`
-  - Access: same as list.
-  - Stores data: reads booking snapshot from `booking`, `guest`, `room_stay`, `guest_vehicle`, `charge`, `payment`.
-- `GET /properties/{propertyId}/bookings/{bookingId}/stream`
-  - Access: same as list.
-  - Stores data: no writes; SSE booking event stream.
-- `POST /properties/{propertyId}/bookings/{bookingId}/link-guest`
-  - Request: `BookingLinkGuestRequest`.
-  - Access: property member.
-  - Stores data: updates `booking.primary_guest_id`; may delete placeholder `guest` when safe.
-- `POST /properties/{propertyId}/bookings/{bookingId}/check-in/bulk`
-  - Request: `BookingBulkCheckInRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: inserts `room_stay`; updates `booking` to `CHECKED_IN`; may fulfill `booking_room_request`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/expected-dates`
-  - Request: `BookingExpectedDatesUpdateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: updates `booking.expected_checkin_at` / `booking.expected_checkout_at`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/billing-policy`
-  - Request: `BookingBillingPolicyUpdateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: updates `booking.billing_*`; inserts `booking_billing_policy_audit_log` when changed.
-- `POST /properties/{propertyId}/bookings/{bookingId}/check-out`
-  - Request: `BookingCheckOutRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: closes active `room_stay` rows (`to_at`), inserts `room_stay_audit_log`, updates `booking` to `CHECKED_OUT`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/room-stays/{roomStayId}/check-out`
-  - Request: `BookingCheckOutRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: closes specific `room_stay`, inserts audit log, may auto-close `booking`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/cancel`
-  - Request: `BookingCancelRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: updates `booking.status=CANCELLED`; may insert penalty row in `charge`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/no-show`
-  - Request: `BookingNoShowRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: updates `booking.status=NO_SHOW`; may insert penalty row in `charge`.
-
-### Room requests + booking balance
-
-- `POST /properties/{propertyId}/bookings/{bookingId}/room-requests`
-  - Request: `BookingRoomRequestCreateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: inserts `booking_room_request`.
-- `GET /properties/{propertyId}/bookings/{bookingId}/room-requests`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`/`HOUSEKEEPING`/`FINANCE`.
-  - Stores data: reads `booking_room_request`.
-- `DELETE /properties/{propertyId}/bookings/{bookingId}/room-requests/{requestId}`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: sets `booking_room_request.status=CANCELLED`.
-- `GET /properties/{propertyId}/bookings/{bookingId}/balance`
-  - Access: property member.
-  - Stores data: reads `room_stay`, `charge`, `payment` and returns computed ledger balance.
-
-## 10) Charges + Payments APIs
-
-- `POST /properties/{propertyId}/bookings/{bookingId}/charges`
-  - Request: `ChargeCreateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`FINANCE`.
-  - Stores data: inserts `charge`.
-- `GET /properties/{propertyId}/bookings/{bookingId}/charges`
-  - Access: property member.
-  - Stores data: reads `charge`.
-
-- `POST /properties/{propertyId}/bookings/{bookingId}/payments`
-  - Request: `PaymentCreateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: inserts `payment`.
-- `GET /properties/{propertyId}/bookings/{bookingId}/payments`
-  - Access: property member.
-  - Stores data: reads `payment`.
-- `DELETE /properties/{propertyId}/bookings/{bookingId}/payments/{paymentId}`
-  - Access: `ADMIN` (super admin allowed through bypass).
-  - Stores data: deletes `payment` only when method is CASH and booking is OPEN/CHECKED_IN.
-
-## 11) Guest APIs
-
-- `PUT /properties/{propertyId}/guests/{guestId}`
-  - Request: `GuestUpdateRequest`.
-  - Access: property member.
-  - Stores data: updates `guest`.
-- `GET /properties/{propertyId}/guests/search?phone=...|vehicleNumber=...`
-  - Access: property member.
-  - Stores data: reads `guest`, `guest_vehicle`, `guest_rating`.
-- `GET /properties/{propertyId}/guests/{guestId}`
-  - Access: property member.
-  - Stores data: reads `guest`, `guest_vehicle`, `guest_rating`.
-- `GET /properties/{propertyId}/guests/visit-count?phone=...`
-  - Access: property member.
-  - Stores data: reads `guest`, booking count from `booking`.
-- `POST /properties/{propertyId}/guests/{guestId}/vehicles`
-  - Request: `GuestVehicleRequest`.
-  - Access: property member.
-  - Stores data: inserts/updates `guest_vehicle`.
-- `POST /properties/{propertyId}/guests/{guestId}/signature`
-  - Multipart SVG file.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: writes file under documents root; updates `guest.signature_path`.
-- `GET /properties/{propertyId}/guests/{guestId}/signature/file`
-  - Access: property member.
-  - Stores data: reads signature file path from `guest`.
-
-### Guest documents
-
-- `POST /properties/{propertyId}/guests/{guestId}/documents?bookingId=...`
-  - Multipart file.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: writes document file under docs root; inserts `guest_document`; queues AI extraction and updates `guest_document.extracted_data`.
-- `GET /properties/{propertyId}/guests/{guestId}/documents`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: reads `guest_document`.
-- `GET /properties/{propertyId}/guests/{guestId}/documents/stream`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: no writes; SSE extraction updates.
-- `GET /properties/{propertyId}/guests/{guestId}/documents/{documentId}/file`
-  - Access: public with token OR `ADMIN`/`MANAGER`.
-  - Stores data: reads `guest_document` + filesystem.
-- `DELETE /properties/{propertyId}/guests/{guestId}/documents/{documentId}`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: deletes file + `guest_document` row (only OPEN/CHECKED_IN booking).
-
-### Guest ratings
-
-- `POST /properties/{propertyId}/guests/{guestId}/ratings`
-  - Request: `GuestRatingCreateRequest`.
-  - Access: property member.
-  - Stores data: inserts `guest_rating`.
-- `GET /properties/{propertyId}/guests/{guestId}/ratings`
-  - Access: property member.
-  - Stores data: reads `guest_rating`.
-
-## 12) Inbound Email APIs
-
-- `GET /properties/{propertyId}/inbound-emails/{emailId}/file`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: reads `inbound_email.raw_pdf_path` and PDF file.
-- `POST /properties/{propertyId}/inbound-emails/manual`
-  - Multipart PDF.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: writes PDF under `/docs/emails`; inserts `inbound_email`; triggers ingestion workflow.
-
-## 13) Rate plan APIs
-
-- `POST /properties/{propertyId}/rate-plans`
-  - Request: `RatePlanCreateRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: inserts `rate_plan`.
-- `GET /properties/{propertyId}/rate-plans?roomTypeCode=...`
-  - Access: property member.
-  - Stores data: reads `rate_plan`.
-- `PUT /properties/{propertyId}/rate-plans/{ratePlanId}`
-  - Request: `RatePlanUpdateRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: updates `rate_plan`.
-- `DELETE /properties/{propertyId}/rate-plans/{ratePlanId}`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: deletes `rate_calendar` rows for plan, then deletes `rate_plan`.
-- `POST /properties/{propertyId}/rate-plans/{ratePlanId}/calendar`
-  - Request: `RateCalendarRangeUpsertRequest`.
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: upserts `rate_calendar` rows in date range.
-- `GET /properties/{propertyId}/rate-plans/{ratePlanId}/calendar?from=...&to=...`
-  - Access: property member.
-  - Stores data: reads `rate_calendar` + `rate_plan`; returns average.
-- `DELETE /properties/{propertyId}/rate-plans/{ratePlanId}/calendar/{rateDate}`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: deletes one `rate_calendar` override row.
-
-## 14) Razorpay APIs
-
-### Settings + return + webhook
-
-- `GET /properties/{propertyId}/razorpay-settings`
-  - Access: `ADMIN`/`MANAGER`.
-  - Stores data: reads `razorpay_settings`.
-- `PUT /properties/{propertyId}/razorpay-settings`
-  - Request: `RazorpaySettingsUpsertRequest`.
-  - Access: `ADMIN`.
-  - Stores data: inserts/updates `razorpay_settings`.
-- `POST /properties/{propertyId}/razorpay/webhook`
-  - Access: public (signature validated).
-  - Stores data: inserts `razorpay_webhook_log`, inserts `razorpay_payment_attempt`, updates `razorpay_qr_request` / `razorpay_payment_link_request`, inserts `payment` for capture/refund events.
-- `POST /properties/{propertyId}/razorpay/return/success`
-  - Access: public.
-  - Stores data: none.
-- `POST /properties/{propertyId}/razorpay/return/failure`
-  - Access: public.
-  - Stores data: none.
-
-### QR + links + request close + refund
-
-- `POST /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/qr`
-  - Request: `RazorpayQrGenerateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: inserts `razorpay_qr_request` (or returns active existing).
-- `GET /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/qr/active`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: reads `razorpay_qr_request`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/qr/close`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: updates latest active `razorpay_qr_request.status`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/qr/{qrId}/close`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: updates specific `razorpay_qr_request.status`.
-- `GET /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/qr/{qrId}/events`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: reads `razorpay_webhook_log`.
-- `GET /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/qr/{qrId}/events/stream`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: SSE stream only.
-- `GET /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/qr`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: reads `razorpay_qr_request`.
-
-- `POST /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/payment-link`
-  - Request: `RazorpayPaymentLinkCreateRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: inserts `razorpay_payment_link_request` (or returns existing open one).
-- `GET /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/requests`
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: reads open `razorpay_qr_request` + `razorpay_payment_link_request`.
-- `POST /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/close`
-  - Request: `RazorpayPaymentRequestCloseRequest`.
-  - Access: `ADMIN`/`MANAGER`/`STAFF`.
-  - Stores data: updates closed status in corresponding Razorpay request row.
-- `POST /properties/{propertyId}/bookings/{bookingId}/payments/razorpay/refund`
-  - Request: `RazorpayRefundRequest`.
-  - Access: `ADMIN`/`MANAGER`/`FINANCE`.
-  - Stores data: no local insert here; refund call is external and webhook later records ledger entry.
-
----
-
-## Detailed example (as requested format)
-
-### Expected checkout planning API
-
-**Expected checkout API is:**
-
-`POST /properties/{propertyId}/bookings/{bookingId}/expected-dates`
-
-**What it does:**
-
-- Updates planned dates on booking (`expectedCheckinAt`, `expectedCheckoutAt`), not actual checkout.
-- For `OPEN` bookings: can update both expected check-in and expected check-out.
-- For `CHECKED_IN`: can update only `expectedCheckOutAt` (check-in change is blocked).
-- For `CHECKED_OUT` / `CANCELLED` / `NO_SHOW`: returns conflict (`Booking closed`).
-- Validates range: if both are present, checkout must be after checkin.
-- Returns `204 No Content`.
-- Emits booking SSE update event.
-
-**Request body (`BookingExpectedDatesUpdateRequest`):**
-
-```json
-{
-  "expectedCheckInAt": "2026-02-05T12:00:00+05:30",
-  "expectedCheckOutAt": "2026-02-06T11:00:00+05:30"
-}
-```
-
-**Allowed roles:**
-
-- `ADMIN`, `MANAGER`, `STAFF` (property-scoped)
-- `superAdmin` can also access (bypasses property membership/role checks)
-- Requires authenticated Firebase principal (`MyPrincipal`)
-
-**Data store:**
-
-- Updates row in `booking` table (`expected_checkin_at`, `expected_checkout_at`, `updated_at`)
-
-**Error codes:**
-
-- `400 Bad Request`
-  - Invalid timestamp format (`"Invalid timestamp"`) for `expectedCheckInAt` / `expectedCheckOutAt`
-  - Invalid range (`"Invalid date range"`) when checkout is not after check-in
-- `401 Unauthorized`
-  - Missing auth principal / user not found
-- `403 Forbidden`
-  - Authenticated but not a property member or missing role (`ADMIN`, `MANAGER`, `STAFF`)
-- `404 Not Found`
-  - Booking not found, or booking does not belong to that property
-- `409 Conflict`
-  - `"Cannot change expected check-in after check-in"`
-  - `"Booking closed"` for `CHECKED_OUT`, `CANCELLED`, `NO_SHOW`
-