updates on the api endpoints on the customer page and more

docs/miler-app-api.md

@@ -1,6 +1,6 @@
 # Doormile Miler App — API reference
 
-The rider-app surface only (`/miler/*`). 38 routes: 3 auth + 35 authenticated.
+The rider-app surface only (`/miler/*`). 45 routes: 3 auth + 42 authenticated.
 Base URL `https://api.doormile.com/api/v1`.
 
 This supersedes "Miler App API Contract v1.0" where the two disagree — several
@@ -126,6 +126,44 @@ prefix it's hyperlocal and the consignment goes straight to `Out_for_Delivery`
 in the rider's hands. Otherwise it routes via the hub. The consignment inherits
 the **booking's** tenant, not the rider's.
 
+It returns `next_action` and, when the next leg is a base, `next_hub` with all
+six fields (`id, name, address, pincode, latitude, longitude`) — the app never
+picks a base itself. `consignment_id` is always present.
+
+```jsonc
+{ "consignment_id": 4821, "consignmentstatus": "Created",
+  "next_action": "inward_at_hub",
+  "next_hub": { "id": 1, "name": "Coimbatore Hub",
+                "address": "14 Avinashi Road, Peelamedu, Coimbatore",
+                "pincode": "641004", "latitude": 11.0272, "longitude": 76.9905 } }
+```
+
+## The base handover
+
+```
+POST /miler/consignments/:id/inward-at-hub     Idempotency-Key supported
+{ "hub_id": 1, "latitude": 11.0272, "longitude": 76.9905 }
+→ { consignmentstatus: "Inwarded_at_Hub", inwardedat, hub, next_action,
+    already_inwarded }
+```
+
+The authoritative record that a rider handed a parcel in at a base. The body is
+optional (it defaults to the base the parcel is routed to); `hubid`, `lat` and
+`lon` are accepted as aliases. Answers with the resulting state, never a bare
+200. A parcel already inwarded answers 200 with `already_inwarded: true`.
+
+```
+GET /miler/bases        ?status=Active &applocationid=
+```
+
+Base master data on a rider token — the six fields per base, plus `distance_km`
+and nearest-first ordering once the rider has reported a position.
+`/admin/tenants/:id/locations` is a different dataset (a client's own sites) and
+is closed to role 5 by design.
+
+**Wording:** the wire says hub, the rider app says Base. Full contract and state
+transitions in [`logistics-base-handover.md`](logistics-base-handover.md).
+
 ## Delivery
 
 | Method | Path | Body |
@@ -151,6 +189,20 @@ the **booking's** tenant, not the rider's.
 | GET | `/miler/bookings` | `?status=&date=YYYY-MM-DD` |
 | GET | `/miler/earnings` | `?period=daily\|weekly\|monthly&date=YYYY-MM-DD` |
 
+Every `/miler/bookings` row carries the leg and the pickup source, rebuilt from
+server state on each read, so a poll or a cold restart needs no local cache:
+
+| Field | Values |
+|---|---|
+| `next_action` | `pickup`, `inward_at_hub`, `start_delivery`, `deliver`, `handed_to_hub`, `none` |
+| `next_hub` | the six base fields, or null when the next leg isn't a base |
+| `pickup_source_type` | `hub`, `customer`, `merchant`, `store` — always sent, `customer` is a value not an omission |
+| `sourceid` / `pickuplocationid` | the base or client-site id; null for a customer door |
+| `pickup_source_name` | the base/site name, or the sender's name for a door pickup |
+
+An unrecognised `pickup_source_type` should be treated as a generic pickup — new
+values may be added.
+
 `bonuspoints` stays zero — nothing writes it yet. That's known and deliberate.
 
 ## Telemetry (Redis-backed, high frequency)
@@ -235,4 +287,9 @@ build a UI that depends on it.
    decided.
 2. `bonuspoints` is never written.
 3. `assignments/:id/reject` and `bookings/:id/vehicle-required` have never had a
-   real request against them.
+   real request against them. (`reject` accepts its reason in the body *or* as
+   `?reason=`, preferring the body — both spellings are honoured.)
+4. `At_Customer` on `milerprofiles.availabilitystatus` means **arrived at the
+   pickup** — it is written only by `POST /miler/bookings/:bookingid/reached`.
+   The name predates the current lifecycle; a rider heading to a receiver is
+   `On_Delivery`.