miler map

lib/data/lifecycle.dart

@@ -279,6 +279,65 @@ abstract final class MilerLifecycle {
     );
   }
 
+  /// `POST /miler/consignments/:id/inward-at-hub`.
+  ///
+  /// Confirmed when the response says the parcel is now the base's —
+  /// `Inwarded_at_Hub`, or `already_inwarded: true` for a retry whose first
+  /// attempt landed and whose answer was lost.
+  ///
+  /// ── Why `already_inwarded` is a success and not an error ──
+  ///
+  /// A rider hands a parcel over at a loading bay, the reply is dropped, and he
+  /// presses again. The server has already done the work; refusing the second
+  /// press would tell him the hand-over failed for a parcel now sitting on the
+  /// base's counter, and he has no way to prove otherwise from where he is
+  /// standing. So the second answer confirms the first — which is exactly what
+  /// the backend's 200-with-a-flag shape is for, and the app must not turn it
+  /// back into a failure.
+  static StateTransition inwardAtHub(ApiResult res) {
+    if (!res.ok) {
+      return StateTransition(
+        outcome: TransitionOutcome.refused,
+        bookingStatus: BookingStatus.unknown,
+        consignmentState: ConsignmentState.unknown,
+        code: res.code,
+        message: res.message,
+        evidence: 'HTTP ${res.status} ${res.code} ${res.message}',
+      );
+    }
+
+    final raw = _str(res.data, const [
+      'consignmentstatus',
+      'consignment_status',
+      'status',
+    ]);
+    final state = consignmentStateFromRaw(raw);
+    final stamp = _str(res.data, const ['inwardedat', 'inwarded_at']);
+    final next = _str(res.data, const ['next_action', 'nextaction']).toLowerCase();
+
+    // `_str` skips `false`-ish values by design, so the flag is read straight.
+    final already =
+        res.data['already_inwarded'] == true ||
+        res.data['alreadyInwarded'] == true;
+
+    final confirmed =
+        state == ConsignmentState.inwardedAtHub ||
+        already ||
+        next == 'handed_to_hub';
+
+    return StateTransition(
+      outcome: confirmed
+          ? TransitionOutcome.confirmed
+          : TransitionOutcome.unconfirmed,
+      bookingStatus: BookingStatus.unknown,
+      consignmentState: state,
+      nextAction: next,
+      evidence:
+          'consignment="$raw" inwardedat="$stamp" next="$next" '
+          'already=$already',
+    );
+  }
+
   /// One line, in the shape a backend ticket wants.
   static void report(String verb, StateTransition t) {
     switch (t.outcome) {