# Mobile App Integration Guide (Delivery Partner)

This developer guide details how to implement the real-time delivery dispatch flow in the Delivery Partner mobile application (e.g. React Native, Flutter, or Native iOS/Android).

---

### Step 1: Establish Socket Connection (on Login / Going Online)
Initialize the socket connection and pass the JWT token in the handshake authentication options.

```javascript
import { io } from "socket.io-client";

// Replace with your backend server URL
const socket = io("http://YOUR_BACKEND_IP:8000", {
  auth: {
    token: DRIVER_JWT_TOKEN // Pass the verified driver token here
  }
});

socket.on("connect", () => {
  console.log("Connected to dispatch server!");
});
```

---

### Step 2: Listen for Incoming Offers (`delivery_offer`)
When the socket receives the `delivery_offer` event, display a modal or popup banner in your UI with the order details and Accept/Reject buttons.

```javascript
socket.on("delivery_offer", (offer) => {
  console.log("New offer received:", offer);
  
  // Example UI action: Open the screen showing details
  showNewOfferModal({
    deliveryId: offer.deliveryId,
    orderId: offer.orderId,
    pickupAddress: offer.pickupAddress.label,
    dropAddress: offer.dropAddress.label,
    amount: offer.totalAmount,
    distance: offer.distanceKm
  });
});
```

---

### Step 3: Respond to the Offer (Accept / Reject)
When the driver clicks Accept or Reject, hit the existing REST endpoint `POST /delivery-partners/deliveries/{id}/respond`.

```javascript
async function respondToOffer(deliveryId, isAccepted) {
  const action = isAccepted ? "ACCEPT" : "REJECT";
  
  try {
    const response = await fetch(`http://YOUR_BACKEND_IP:8000/delivery-partners/deliveries/${deliveryId}/respond`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${DRIVER_JWT_TOKEN}`
      },
      body: JSON.stringify({ action })
    });
    
    const result = await response.json();
    if (response.ok) {
      console.log(`Successfully responded with action: ${action}`);
      // Close the modal or update app state
    } else {
      console.error(result.message);
    }
  } catch (error) {
    console.error("Network error: ", error);
  }
}
```

---

### Step 4: Handle App Restarts / Notification Clicks
If the app was closed when the offer was dispatched or opened via a push notification:

1. On app launch, call `GET /delivery-partners/deliveries/pending-offer`.
2. If the offer is not `null`, load the accept/reject screen immediately.

```javascript
async function checkPendingOffers() {
  const response = await fetch("http://YOUR_BACKEND_IP:8000/delivery-partners/deliveries/pending-offer", {
    headers: { 'Authorization': `Bearer ${DRIVER_JWT_TOKEN}` }
  });
  
  const data = await response.json();
  if (data.offer) {
    showNewOfferModal(data.offer); // Load the screen if there's a pending offer
  }
}
```

---

### App State Lifecycle & Flow Handling

Depending on the operational state of the delivery partner's mobile application, the offer is received and presented to the rider in different ways:

| App State | Delivery Offer Trigger Mechanism | What Happens |
| :--- | :--- | :--- |
| **Foreground (Open & Active)** | **WebSocket Listener** | The `delivery_offer` WebSocket event fires instantly (handled in **Step 2**). The modal or bottom sheet overlay pops up immediately in front of the rider. |
| **Background (Open but Minimized)** | **Push Notification (FCM / APNs)** | Mobile OSs sleep WebSocket connections when minimized. The backend dispatches a push notification. Tapping the notification brings the app to the foreground and calls `checkPendingOffers()` (handled in **Step 4**) to display the offer. |
| **Closed / Killed (Not Running)** | **Push Notification (FCM / APNs)** | The backend dispatches a push notification. Tapping it starts up the app, which then runs `checkPendingOffers()` on load to retrieve the pending offer. |