# User Dashboard & Appointments API Documentation

## Overview

This document describes the user dashboard and appointments APIs for managing upcoming bookings.

## Authentication

All endpoints require JWT authentication (Bearer token).

---

## 📊 Dashboard APIs

### Base URL: `/api/v1/dashboard`

### 1. Get Recent Upcoming Bookings

Get the user's most recent upcoming bookings (3-5 bookings).

**Endpoint:** `GET /api/v1/dashboard/recent-bookings`

**Authentication:** Required (JWT)

**Query Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| limit | integer | No | 5 | Number of bookings to return (1-10) |

**Request Example:**
```bash
GET /api/v1/dashboard/recent-bookings
GET /api/v1/dashboard/recent-bookings?limit=3
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Recent upcoming bookings retrieved successfully.",
  "data": {
    "bookings": [
      {
        "id": 123,
        "booking_date": "2026-01-20",
        "booking_time": "14:30",
        "status": "confirmed",
        "total_amount": 50.00,
        "is_visit": false,
        "is_flagged": false,
        "service": {
          "id": 5,
          "title": "Haircut",
          "slug": "haircut",
          "duration": 30,
          "price": 50,
          "image": "https://..."
        },
        "company": {
          "id": 2,
          "name": "Style Studio",
          "slug": "style-studio",
          "address": "123 Main Street",
          "phone": "+1234567890",
          "city": "New York"
        },
        "employee": {
          "id": 8,
          "name": "Jane Smith"
        },
        "notes": "First time customer"
      }
    ],
    "count": 5,
    "limit": 5
  }
}
```

---

### 2. Get Dashboard Summary

Get user's booking statistics and next appointment.

**Endpoint:** `GET /api/v1/dashboard/summary`

**Authentication:** Required (JWT)

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Dashboard summary retrieved successfully.",
  "data": {
    "upcoming_bookings": 5,
    "completed_bookings": 23,
    "cancelled_bookings": 2,
    "total_spent": "1250.00",
    "next_booking": {
      "id": 125,
      "booking_date": "2026-01-15",
      "booking_time": "10:00",
      "status": "confirmed",
      "service": {
        "title": "Massage",
        "duration": 60
      },
      "company": {
        "name": "Spa Center",
        "address": "456 Park Avenue"
      }
    }
  }
}
```

---

## 📅 Appointments APIs

### Base URL: `/api/v1/appointments`

### 1. Get All Upcoming Appointments

Get all upcoming appointments with filtering and pagination.

**Endpoint:** `GET /api/v1/appointments`

**Authentication:** Required (JWT)

**Query Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| status | string | No | - | Filter by status: `pending`, `confirmed`, `completed`, `cancelled` |
| service_id | integer | No | - | Filter by service ID |
| company_id | integer | No | - | Filter by company ID |
| from_date | date | No | - | Start date (Y-m-d format) |
| to_date | date | No | - | End date (Y-m-d format) |
| per_page | integer | No | 15 | Items per page (1-50) |

**Default Behavior:**
- Shows only upcoming bookings (today and future)
- Excludes `cancelled` and `completed` status
- Sorted by date (soonest first)

**Request Examples:**
```bash
# Get all upcoming appointments
GET /api/v1/appointments

# Get only confirmed appointments
GET /api/v1/appointments?status=confirmed

# Get appointments for specific date range
GET /api/v1/appointments?from_date=2026-01-15&to_date=2026-01-31

# Get paginated results
GET /api/v1/appointments?per_page=20&page=2
```

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Upcoming appointments retrieved successfully.",
  "data": {
    "appointments": [
      {
        "id": 123,
        "booking_date": "2026-01-15",
        "booking_time": "10:00",
        "status": "confirmed",
        "total_amount": 75.00,
        "service": {
          "id": 5,
          "title": "Full Body Massage",
          "slug": "full-body-massage",
          "duration": 60,
          "price": 75,
          "image": "https://..."
        },
        "company": {
          "id": 2,
          "name": "Relax Spa",
          "slug": "relax-spa",
          "address": "123 Main Street",
          "phone": "+1234567890",
          "city": "New York"
        },
        "employee": {
          "id": 8,
          "name": "Sarah Johnson"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 15,
      "total": 35,
      "last_page": 3,
      "from": 1,
      "to": 15
    }
  }
}
```

---

### 2. Get Appointment Details

Get details of a specific upcoming appointment.

**Endpoint:** `GET /api/v1/appointments/{id}`

**Authentication:** Required (JWT)

**URL Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | integer | Yes | Booking ID |

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Appointment details retrieved successfully.",
  "data": {
    "appointment": {
      "id": 123,
      "booking_date": "2026-01-15",
      "booking_time": "10:00",
      "status": "confirmed",
      "total_amount": 75.00,
      "is_visit": false,
      "is_flagged": false,
      "service": {
        "id": 5,
        "title": "Full Body Massage",
        "duration": 60,
        "price": 75,
        "image": "https://..."
      },
      "company": {
        "id": 2,
        "name": "Relax Spa",
        "address": "123 Main Street",
        "phone": "+1234567890",
        "city": "New York"
      },
      "employee": {
        "id": 8,
        "name": "Sarah Johnson"
      },
      "notes": "Please arrive 10 minutes early"
    }
  }
}
```

**Error Response (404):**
```json
{
  "success": false,
  "message": "Appointment not found.",
  "data": [],
  "code": 404
}
```

---

### 3. Get Appointments Summary

Get count summary of upcoming appointments by status.

**Endpoint:** `GET /api/v1/appointments/summary`

**Authentication:** Required (JWT)

**Response (200 OK):**
```json
{
  "success": true,
  "message": "Appointments summary retrieved successfully.",
  "data": {
    "summary": {
      "total_upcoming": 8,
      "pending": 3,
      "confirmed": 5
    },
    "next_appointment": {
      "id": 130,
      "booking_date": "2026-01-15",
      "booking_time": "10:00",
      "status": "confirmed",
      "service": {
        "title": "Haircut"
      },
      "company": {
        "name": "Style Studio"
      }
    }
  }
}
```

---

## Booking Status Values

| Status | Description |
|--------|-------------|
| `pending` | Booking is pending confirmation |
| `confirmed` | Booking is confirmed |
| `completed` | Service has been completed |
| `cancelled` | Booking was cancelled |
| `no_show` | Customer didn't show up |

---

## Filtering Examples

### Get appointments for this month:
```bash
GET /api/v1/appointments?from_date=2026-01-01&to_date=2026-01-31
```

### Get only confirmed appointments:
```bash
GET /api/v1/appointments?status=confirmed
```

### Get appointments for a specific service:
```bash
GET /api/v1/appointments?service_id=5
```

### Get appointments for a specific company:
```bash
GET /api/v1/appointments?company_id=2
```

---

## Common Use Cases

### 1. **User Dashboard Home Screen**
```javascript
// Show recent bookings (limit 3)
GET /api/v1/dashboard/recent-bookings?limit=3

// Show dashboard summary
GET /api/v1/dashboard/summary
```

### 2. **Appointments List Screen**
```javascript
// Get all upcoming appointments with pagination
GET /api/v1/appointments?page=1&per_page=20

// Get filtered appointments
GET /api/v1/appointments?status=confirmed&per_page=20
```

### 3. **Appointment Detail Screen**
```javascript
// Get single appointment details
GET /api/v1/appointments/123
```

### 4. **Calendar View**
```javascript
// Get appointments for specific date range
GET /api/v1/appointments?from_date=2026-01-01&to_date=2026-01-31
```

---

## Error Responses

### 401 Unauthorized
```json
{
  "success": false,
  "message": "Unauthorized",
  "data": [],
  "code": 401
}
```

### 422 Validation Error
```json
{
  "success": false,
  "message": "The given data was invalid.",
  "data": [],
  "code": 422
}
```

### 404 Not Found
```json
{
  "success": false,
  "message": "Appointment not found.",
  "data": [],
  "code": 404
}
```

---

## Testing

### Using cURL:
```bash
# Get recent bookings
curl -X GET "http://bookrah.test/api/v1/dashboard/recent-bookings?limit=5" \
  -H "Authorization: Bearer {token}"

# Get dashboard summary
curl -X GET "http://bookrah.test/api/v1/dashboard/summary" \
  -H "Authorization: Bearer {token}"

# Get all appointments
curl -X GET "http://bookrah.test/api/v1/appointments" \
  -H "Authorization: Bearer {token}"

# Get appointment details
curl -X GET "http://bookrah.test/api/v1/appointments/123" \
  -H "Authorization: Bearer {token}"
```

### Using JavaScript/Fetch:
```javascript
// Recent bookings
const response = await fetch('/api/v1/dashboard/recent-bookings?limit=5', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
const data = await response.json();

// All appointments
const response = await fetch('/api/v1/appointments?status=confirmed', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
const data = await response.json();
```

---

## Features

### ✅ **User Dashboard**
- Most recent upcoming bookings (3-5)
- Dashboard summary with statistics
- Next appointment details
- Total spent calculation

### ✅ **Appointments**
- All upcoming bookings
- Filter by status, service, company, date range
- Pagination support
- Detailed appointment view
- Summary by status

### ✅ **Data Included**
- Service name, duration, price, image
- Company name, address, phone, city
- Booking date and time
- Employee name
- Booking status
- Notes

### ✅ **Smart Filtering**
- Only upcoming bookings (today and future)
- Excludes cancelled and completed by default
- Soonest bookings first
- Configurable filters

---

## Notes

1. **Upcoming Bookings**: All APIs return only upcoming bookings (booking_date >= today)
2. **Past Bookings**: Use `/api/v1/bookings/my` endpoint to get all bookings including past
3. **Cancellation**: Use `/api/v1/bookings/{id}/cancel` to cancel an appointment
4. **Pagination**: Default 15 items per page, can be adjusted with `per_page` parameter

---

## Future Enhancements

Potential features for future versions:
- Calendar export (iCal format)
- Reminder settings
- Re-booking functionality
- Rating and reviews after appointment
- Appointment rescheduling