feat(bookings): booking approval for reservation requests

apps/companion/app/(tabs)/bookings/[id].tsx

@@ -751,15 +751,22 @@ function BookingDetailScreen({ id }: { id: string }) {
     startQuantityPicker();
   };
 
+  // A reservation that will wait for approval is a request, and the prompt,
+  // the button and the success message must say so; otherwise the pending
+  // state that follows reads as a failure.
+  const reservationIsRequest = booking?.reservationNeedsApproval === true;
+
   const handleReserve = () => {
     if (!booking || !currentOrg) return;
     Alert.alert(
-      "Reserve Booking",
-      `Reserve "${booking.name}"? This confirms the booking and checks for conflicts.`,
+      reservationIsRequest ? "Request Reservation" : "Reserve Booking",
+      reservationIsRequest
+        ? `Request "${booking.name}"? The items are held while an administrator or manager reviews the request. You will be notified by email.`
+        : `Reserve "${booking.name}"? This confirms the booking and checks for conflicts.`,
       [
         { text: "Cancel", style: "cancel" },
         {
-          text: "Reserve",
+          text: reservationIsRequest ? "Request" : "Reserve",
           onPress: async () => {
             setIsActioning(true);
             const { error: err } = await api.reserveBooking(
@@ -775,9 +782,13 @@ function BookingDetailScreen({ id }: { id: string }) {
             Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
             // Mutation changed this booking — force the list to refetch.
             markBookingsListDirty();
-            Alert.alert("Reserved", `"${booking.name}" is now reserved.`, [
-              { text: "OK", onPress: () => fetchBooking() },
-            ]);
+            Alert.alert(
+              reservationIsRequest ? "Request sent" : "Reserved",
+              reservationIsRequest
+                ? `"${booking.name}" is waiting for approval. You will receive an email once it has been reviewed.`
+                : `"${booking.name}" is now reserved.`,
+              [{ text: "OK", onPress: () => fetchBooking() }]
+            );
           },
         },
       ]
@@ -835,6 +846,38 @@ function BookingDetailScreen({ id }: { id: string }) {
   // Each is permission/status-gated server-side AND only offered when the
   // detail endpoint's `bookingActions` flag says this role/status may use it.
 
+  // Approve a pending reservation request. Offered only when the detail
+  // endpoint says this caller may decide it (`canApprove`), which is the same
+  // `booking:approve` answer the web button and the endpoint enforce.
+  const handleApprove = () => {
+    if (!booking || !currentOrg) return;
+    Alert.alert(
+      "Approve booking request",
+      `Approve "${booking.name}"? The custodian will be notified by email and the booking can then be checked out.`,
+      [
+        { text: "Not now", style: "cancel" },
+        {
+          text: "Approve",
+          onPress: async () => {
+            setIsActioning(true);
+            const { error: err } = await api.approveBooking(
+              currentOrg.id,
+              booking.id
+            );
+            setIsActioning(false);
+            if (err) {
+              Alert.alert("Couldn't approve", err);
+              return;
+            }
+            Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+            markBookingsListDirty();
+            fetchBooking();
+          },
+        },
+      ]
+    );
+  };
+
   const handleCancel = () => {
     if (!booking || !currentOrg) return;
     Alert.alert(
@@ -1836,6 +1879,26 @@ function BookingDetailScreen({ id }: { id: string }) {
                     {formatStatus(booking.status)}
                   </Text>
                 </View>
+                {booking.isPendingApproval ? (
+                  // Approval pill: web parity for the derived pending state.
+                  // The server also refuses checkout while pending and sends
+                  // `canCheckout: false`, so this is display-only.
+                  <View
+                    style={[
+                      styles.statusBadgeLg,
+                      { backgroundColor: colors.warningBg },
+                    ]}
+                  >
+                    <Text
+                      style={[
+                        styles.statusTextLg,
+                        { color: colors.warningText },
+                      ]}
+                    >
+                      Pending approval
+                    </Text>
+                  </View>
+                ) : null}
               </View>
 
               {booking.description ? (
@@ -2076,7 +2139,11 @@ function BookingDetailScreen({ id }: { id: string }) {
                     // the disabled state without setting it by hand.
                     disabled={!!reserveBlockedReason}
                     onPress={handleReserve}
-                    accessibilityLabel="Reserve this booking"
+                    accessibilityLabel={
+                      reservationIsRequest
+                        ? "Request a reservation for this booking"
+                        : "Reserve this booking"
+                    }
                     accessibilityHint={reserveBlockedReason ?? undefined}
                     accessibilityRole="button"
                   >
@@ -2085,7 +2152,9 @@ function BookingDetailScreen({ id }: { id: string }) {
                       size={18}
                       color={colors.primaryForeground}
                     />
-                    <Text style={styles.actionButtonText}>Reserve</Text>
+                    <Text style={styles.actionButtonText}>
+                      {reservationIsRequest ? "Request reservation" : "Reserve"}
+                    </Text>
                   </TouchableOpacity>
                 )}
               </View>
@@ -2202,6 +2271,27 @@ function BookingDetailScreen({ id }: { id: string }) {
               </TouchableOpacity>
             )}
 
+            {/* A pending reservation request offers Approve in place of the
+                check-out paths: the server refuses check-out until it is
+                approved, and `canApprove` is the server's own answer on who
+                may decide it. */}
+            {booking.canApprove === true && (
+              <TouchableOpacity
+                style={styles.actionButton}
+                onPress={handleApprove}
+                disabled={isActioning}
+                accessibilityLabel="Approve this booking request"
+                accessibilityRole="button"
+              >
+                <Ionicons
+                  name="checkmark-circle-outline"
+                  size={18}
+                  color={colors.primaryForeground}
+                />
+                <Text style={styles.actionButtonText}>Approve request</Text>
+              </TouchableOpacity>
+            )}
+
             {/* Full check-out is RESERVED-only (web parity); the loader's
                 canCheckout reflects that. It is hidden when the workspace
                 requires explicit check-out for this role, which leaves

apps/companion/lib/api/bookings.ts

@@ -362,6 +362,19 @@ export const bookingsApi = {
       }
     ),
 
+  /**
+   * Approve a pending reservation request. The booking stays RESERVED and
+   * becomes checkout-able; who may approve is enforced server-side.
+   */
+  approveBooking: (orgId: string, bookingId: string) =>
+    apiFetch<BookingMutationResponse>(
+      `/api/mobile/bookings/approve?orgId=${orgId}`,
+      {
+        method: "POST",
+        body: JSON.stringify({ bookingId }),
+      }
+    ),
+
   /**
    * Cancel a booking (RESERVED/ONGOING/OVERDUE -> CANCELLED). Frees the
    * assets/kits; status guard + ownership enforced server-side.

apps/companion/lib/api/types.ts

@@ -1161,6 +1161,28 @@ export type BookingDetail = {
    * as `false` rather than blocking Reserve.
    */
   hasAlreadyBookedAssets?: boolean;
+  /**
+   * True while this reservation request awaits a decision (the workspace
+   * requires approval for a role and the booking has no `approvedAt`).
+   * Optional for rolling-deploy safety: an older server omits it, and absent
+   * must read as `false` so nothing is hidden.
+   */
+  isPendingApproval?: boolean;
+  /**
+   * Whether this caller may approve the pending request: the server's
+   * `booking:approve` answer (Owner, Administrator, Manager), false unless
+   * {@link isPendingApproval}. The booking screen offers "Approve request"
+   * only when true; the approve endpoint enforces the permission on its own.
+   * Absent on an older server.
+   */
+  canApprove?: boolean;
+  /**
+   * True on a DRAFT whose reservation by this caller would wait for approval
+   * (workspace requires it, and the caller's role is one whose reservations
+   * do). The screen then words Reserve as a request. Absent on an older
+   * server, which reads as a plain reservation.
+   */
+  reservationNeedsApproval?: boolean;
   /**
    * Segmented lifecycle progress (Booked / Partial / Fully out / Returned),
    * computed server-side by the SAME shared helper the web booking overview