# Equipment Reservation API Documentation

## Overview

The Equipment Reservation API provides endpoints for managing golf carts and boats with time slot reservations. The system supports 30-minute time slots from 6:00 AM to 6:00 PM daily.

## Base URL

```
http://your-domain.com/api
```

## Authentication

Most endpoints require authentication using Laravel Sanctum. Include the Bearer token in the Authorization header:

```
Authorization: Bearer {your-token}
```

## Equipment Endpoints

### 1. Get All Equipment

**GET** `/equipment`

Get a list of all available equipment with optional filtering.

**Query Parameters:**
- `type` (optional): Filter by equipment type (`golf_car`, `boat`)
- `status` (optional): Filter by status (`active`, `inactive`)
- `search` (optional): Search by name or description
- `per_page` (optional): Number of items per page (default: 10)

**Response:**
```json
{
    "success": true,
    "data": {
        "equipment": [
            {
                "id": 1,
                "name": "Golf Cart 1",
                "type": "golf_car",
                "type_name": "Golf Cart",
                "description": "Electric golf cart with comfortable seating for 4 passengers.",
                "image": "http://your-domain.com/storage/equipment/golf-cart-1.jpg",
                "is_active": true,
                "sort_order": 1,
                "start_time": "06:00",
                "end_time": "18:00",
                "slot_duration": 30,
                "created_at": "2025-06-29T08:00:00.000000Z",
                "updated_at": "2025-06-29T08:00:00.000000Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "last_page": 1,
            "per_page": 10,
            "total": 4,
            "from": 1,
            "to": 4
        },
        "filters": {
            "types": {
                "golf_car": "Golf Cart",
                "boat": "Boat"
            },
            "applied_filters": {}
        }
    },
    "message": "Equipment retrieved successfully"
}
```

### 2. Get Equipment by ID

**GET** `/equipment/{id}`

Get detailed information about a specific equipment.

**Response:**
```json
{
    "success": true,
    "data": {
        "equipment": {
            "id": 1,
            "name": "Golf Cart 1",
            "type": "golf_car",
            "type_name": "Golf Cart",
            "description": "Electric golf cart with comfortable seating for 4 passengers.",
            "image": "http://your-domain.com/storage/equipment/golf-cart-1.jpg",
            "is_active": true,
            "sort_order": 1,
            "start_time": "06:00",
            "end_time": "18:00",
            "slot_duration": 30,
            "created_at": "2025-06-29T08:00:00.000000Z",
            "updated_at": "2025-06-29T08:00:00.000000Z",
            "total_reservations": 5,
            "active_reservations": 3
        }
    },
    "message": "Equipment details retrieved successfully"
}
```

### 3. Get Equipment Time Slots

**GET** `/equipment/{id}/time-slots`

Get available and reserved time slots for a specific equipment on a specific date.

**Query Parameters:**
- `date` (required): Date in YYYY-MM-DD format

**Response:**
```json
{
    "success": true,
    "data": {
        "equipment": {
            "id": 1,
            "name": "Golf Cart 1",
            "type": "golf_car",
            "type_name": "Golf Cart"
        },
        "date": "2025-06-30",
        "time_slots": [
            {
                "start_time": "06:00",
                "end_time": "06:30",
                "is_reserved": false,
                "is_available": true
            },
            {
                "start_time": "06:30",
                "end_time": "07:00",
                "is_reserved": true,
                "is_available": false
            }
        ],
        "available_slots": [
            {
                "start_time": "06:00",
                "end_time": "06:30",
                "is_reserved": false,
                "is_available": true
            }
        ],
        "reserved_slots": [
            {
                "start_time": "06:30",
                "end_time": "07:00",
                "is_reserved": true,
                "is_available": false
            }
        ],
        "operating_hours": {
            "start_time": "06:00",
            "end_time": "18:00",
            "slot_duration": 30
        }
    },
    "message": "Time slots retrieved successfully"
}
```

### 4. Search Equipment

**GET** `/equipment/search`

Search equipment by name or description.

**Query Parameters:**
- `query` (required): Search term (minimum 2 characters)
- `per_page` (optional): Number of items per page (default: 10)

**Response:**
```json
{
    "success": true,
    "data": {
        "equipment": [...],
        "pagination": {...},
        "search_query": "golf"
    },
    "message": "Equipment search completed successfully"
}
```

### 5. Get Equipment by Type

**GET** `/equipment/types/{type}`

Get all equipment of a specific type.

**Path Parameters:**
- `type`: Equipment type (`golf_car` or `boat`)

**Response:**
```json
{
    "success": true,
    "data": {
        "equipment": [...],
        "type": "golf_car",
        "type_name": "Golf Cart",
        "count": 2
    },
    "message": "Equipment by type retrieved successfully"
}
```

### 6. Get Equipment Statistics

**GET** `/equipment/statistics`

Get equipment statistics.

**Response:**
```json
{
    "success": true,
    "data": {
        "total": 4,
        "active": 4,
        "by_type": {
            "golf_car": {
                "name": "Golf Cart",
                "total": 2,
                "active": 2
            },
            "boat": {
                "name": "Boat",
                "total": 2,
                "active": 2
            }
        },
        "total_reservations": 15,
        "today_reservations": 3,
        "upcoming_reservations": 12
    },
    "message": "Equipment statistics retrieved successfully"
}
```

## Equipment Reservation Endpoints

### 1. Get All Reservations

**GET** `/equipment-reservations`

Get a list of all reservations with optional filtering.

**Query Parameters:**
- `equipment_id` (optional): Filter by equipment ID
- `equipment_type` (optional): Filter by equipment type
- `status` (optional): Filter by status (`confirmed`, `cancelled`, `completed`)
- `date_from` (optional): Filter from date (YYYY-MM-DD)
- `date_to` (optional): Filter to date (YYYY-MM-DD)
- `search` (optional): Search by user name or equipment name
- `per_page` (optional): Number of items per page (default: 15)

**Response:**
```json
{
    "success": true,
    "data": {
        "reservations": [
            {
                "id": 1,
                "equipment_id": 1,
                "equipment_name": "Golf Cart 1",
                "equipment_type": "golf_car",
                "equipment_type_name": "Golf Cart",
                "user_id": 1,
                "user_name": "John Doe",
                "reservation_date": "2025-06-30",
                "formatted_date": "Jun 30, 2025",
                "start_time": "06:00",
                "end_time": "06:30",
                "formatted_time_range": "06:00 - 06:30",
                "duration_minutes": 30,
                "formatted_duration": "30 minutes",
                "status": "confirmed",
                "status_name": "Confirmed",
                "status_badge_class": "bg-success",
                "notes": "Early morning ride",
                "is_past": false,
                "is_today": false,
                "is_future": true,
                "created_at": "2025-06-29T08:00:00.000000Z",
                "updated_at": "2025-06-29T08:00:00.000000Z"
            }
        ],
        "pagination": {...},
        "filters": {
            "statuses": {
                "confirmed": "Confirmed",
                "cancelled": "Cancelled",
                "completed": "Completed"
            },
            "equipment_types": {
                "golf_car": "Golf Cart",
                "boat": "Boat"
            },
            "applied_filters": {}
        }
    },
    "message": "Reservations retrieved successfully"
}
```

### 2. Get Reservation by ID

**GET** `/equipment-reservations/{id}`

Get detailed information about a specific reservation.

**Response:**
```json
{
    "success": true,
    "data": {
        "reservation": {
            "id": 1,
            "equipment_id": 1,
            "equipment_name": "Golf Cart 1",
            "equipment_type": "golf_car",
            "equipment_type_name": "Golf Cart",
            "user_id": 1,
            "user_name": "John Doe",
            "reservation_date": "2025-06-30",
            "formatted_date": "Jun 30, 2025",
            "start_time": "06:00",
            "end_time": "06:30",
            "formatted_time_range": "06:00 - 06:30",
            "duration_minutes": 30,
            "formatted_duration": "30 minutes",
            "status": "confirmed",
            "status_name": "Confirmed",
            "status_badge_class": "bg-success",
            "notes": "Early morning ride",
            "is_past": false,
            "is_today": false,
            "is_future": true,
            "created_at": "2025-06-29T08:00:00.000000Z",
            "updated_at": "2025-06-29T08:00:00.000000Z",
            "equipment": {
                "id": 1,
                "name": "Golf Cart 1",
                "type": "golf_car",
                "type_name": "Golf Cart"
            },
            "user": {
                "id": 1,
                "name": "John Doe",
                "email": "john@example.com",
                "phone": "+1234567890"
            }
        }
    },
    "message": "Reservation details retrieved successfully"
}
```

### 3. Create Reservation

**POST** `/equipment-reservations`

Create a new equipment reservation.

**Request Body:**
```json
{
    "equipment_id": 1,
    "reservation_date": "2025-06-30",
    "start_time": "06:00",
    "notes": "Early morning ride"
}
```

**Validation Rules:**
- `equipment_id`: Required, must exist in equipment table
- `reservation_date`: Required, must be today or in the future
- `start_time`: Required, must be in HH:MM format
- `notes`: Optional, maximum 1000 characters

**Response:**
```json
{
    "success": true,
    "data": {
        "reservation": {
            "id": 1,
            "equipment_id": 1,
            "equipment_name": "Golf Cart 1",
            "equipment_type": "golf_car",
            "equipment_type_name": "Golf Cart",
            "user_id": 1,
            "user_name": "John Doe",
            "reservation_date": "2025-06-30",
            "formatted_date": "Jun 30, 2025",
            "start_time": "06:00",
            "end_time": "06:30",
            "formatted_time_range": "06:00 - 06:30",
            "duration_minutes": 30,
            "formatted_duration": "30 minutes",
            "status": "confirmed",
            "status_name": "Confirmed",
            "status_badge_class": "bg-success",
            "notes": "Early morning ride",
            "is_past": false,
            "is_today": false,
            "is_future": true,
            "created_at": "2025-06-29T08:00:00.000000Z",
            "updated_at": "2025-06-29T08:00:00.000000Z",
            "equipment": {...},
            "user": {...}
        }
    },
    "message": "Reservation created successfully"
}
```

### 4. Update Reservation

**PUT** `/equipment-reservations/{id}`

Update an existing reservation.

**Request Body:**
```json
{
    "equipment_id": 1,
    "reservation_date": "2025-06-30",
    "start_time": "07:00",
    "notes": "Updated notes"
}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "reservation": {...}
    },
    "message": "Reservation updated successfully"
}
```

### 5. Delete Reservation

**DELETE** `/equipment-reservations/{id}`

Delete a reservation.

**Response:**
```json
{
    "success": true,
    "data": [],
    "message": "Reservation deleted successfully"
}
```

### 6. Cancel Reservation

**POST** `/equipment-reservations/{id}/cancel`

Cancel a reservation.

**Response:**
```json
{
    "success": true,
    "data": {
        "reservation": {
            "id": 1,
            "status": "cancelled",
            "status_name": "Cancelled",
            "status_badge_class": "bg-danger"
        }
    },
    "message": "Reservation cancelled successfully"
}
```

### 7. Complete Reservation

**POST** `/equipment-reservations/{id}/complete`

Mark a reservation as completed.

**Response:**
```json
{
    "success": true,
    "data": {
        "reservation": {
            "id": 1,
            "status": "completed",
            "status_name": "Completed",
            "status_badge_class": "bg-info"
        }
    },
    "message": "Reservation marked as completed"
}
```

### 8. Get My Reservations

**GET** `/equipment-reservations/my-reservations`

Get the authenticated user's own reservations.

**Query Parameters:**
- `status` (optional): Filter by status
- `date_from` (optional): Filter from date
- `date_to` (optional): Filter to date
- `per_page` (optional): Number of items per page

**Response:**
```json
{
    "success": true,
    "data": {
        "reservations": [...],
        "pagination": {...},
        "filters": {
            "statuses": {...},
            "applied_filters": {}
        }
    },
    "message": "My reservations retrieved successfully"
}
```

### 9. Get Reservation Statistics

**GET** `/equipment-reservations/statistics`

Get reservation statistics.

**Response:**
```json
{
    "success": true,
    "data": {
        "total": 15,
        "confirmed": 10,
        "cancelled": 3,
        "completed": 2,
        "today": 3,
        "upcoming": 12,
        "past": 0,
        "by_equipment": {
            "1": {
                "name": "Golf Cart 1",
                "total": 8,
                "confirmed": 5,
                "cancelled": 2,
                "completed": 1
            }
        },
        "by_status": {
            "confirmed": {
                "name": "Confirmed",
                "count": 10
            },
            "cancelled": {
                "name": "Cancelled",
                "count": 3
            },
            "completed": {
                "name": "Completed",
                "count": 2
            }
        }
    },
    "message": "Reservation statistics retrieved successfully"
}
```

## Error Responses

All endpoints return consistent error responses:

```json
{
    "success": false,
    "message": "Error message",
    "data": null
}
```

Common HTTP status codes:
- `200`: Success
- `201`: Created
- `400`: Bad Request (validation errors)
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

## Usage Examples

### JavaScript/Fetch Example

```javascript
// Get available time slots for a golf cart
const response = await fetch('/api/equipment/1/time-slots?date=2025-06-30', {
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    }
});

const data = await response.json();
console.log(data.data.available_slots);

// Create a reservation
const reservationResponse = await fetch('/api/equipment-reservations', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        equipment_id: 1,
        reservation_date: '2025-06-30',
        start_time: '06:00',
        notes: 'Early morning ride'
    })
});

const reservationData = await reservationResponse.json();
console.log(reservationData.data.reservation);
```

### cURL Example

```bash
# Get all golf carts
curl -X GET "http://your-domain.com/api/equipment?type=golf_car" \
  -H "Authorization: Bearer your-token"

# Create a reservation
curl -X POST "http://your-domain.com/api/equipment-reservations" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "equipment_id": 1,
    "reservation_date": "2025-06-30",
    "start_time": "06:00",
    "notes": "Early morning ride"
  }'
```

## Notes

1. **Time Slots**: All equipment use 30-minute time slots from 6:00 AM to 6:00 PM
2. **Authentication**: Most endpoints require authentication except for public equipment listing
3. **Validation**: The system validates time slot availability and prevents double bookings
4. **Permissions**: Users can only manage their own reservations unless they are admins
5. **Status Flow**: Reservations can be confirmed → cancelled/completed
6. **Date Format**: All dates should be in YYYY-MM-DD format
7. **Time Format**: All times should be in HH:MM format (24-hour) 