## Package API Documentation

This API allows users to interact with package plans, view purchased packages, buy new ones, and check the status of
existing packages. Authentication is required for all the endpoints, and the requests should use the appropriate token.

### List of Contents

- [List Package Plans](#1-list-package-plans)
- [List Purchased Packages](#2-list-purchased-packages)
- [Purchase Package](#3-purchase-package)
- [Check Package Status](#4-check-package-status)

### Authentication

- Authentication is handled using [Sanctum](https://laravel.com/docs/sanctum) tokens. Ensure that you include a valid
  token in the `Authorization` header of your requests to access protected endpoints.

### Content Type

- All API endpoints operate with `application/json` for both requests and responses.

---

#### 1. List Package Plans

- **Endpoint:** `POST /api/v1/package/plans`
- **Description:** Retrieves a list of all available package plans for users.
- **Authentication:** Yes
- **Permissions:** User

#### Request Example:

No parameters required.

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": [
        {
            "id": 1,
            "name": "Diamond",
            "ad_credits": 200,
            "price": "150000.00"
        },
        {
            "id": 2,
            "name": "Gold",
            "ad_credits": 100,
            "price": "100000.00"
        },
        {
            "id": 3,
            "name": "Silver",
            "ad_credits": 75,
            "price": "75000.00"
        },
        {
            "id": 4,
            "name": "Bronze",
            "ad_credits": 30,
            "price": "25000.00"
        }
    ]
}
```

---

#### 2. List Purchased Packages

- **Endpoint:** `POST /api/v1/package/purchased`
- **Description:** Retrieves a list of packages purchased by the authenticated user.
- **Authentication:** Yes
- **Permissions:** User

#### Request Example:

No parameters required.

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": [
        {
            "id": 1,
            "package": {
                "id": 1,
                "name": "Basic Package"
            },
            "remaining_credits": 10,
            "is_expired": false,
            "expire_date": "2025-09-13",
            "purchased_at": "2023-09-13"
        }
    ]
}
```

---

#### 3. Purchase Package

- **Endpoint:** `POST /api/v1/package/purchase`
- **Description:** Allows the user to purchase a package.
- **Authentication:** Yes
- **Permissions:** User

##### Request Parameters:

| Parameter    | Required/Optional | Type    | Description                        |
|--------------|-------------------|---------|------------------------------------|
| `package_id` | Required          | Integer | The ID of the package to purchase. |

##### Request Example:

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "order_id": 1,
        "amount": 25000,
        "tracking_code": "2024091841369",
        "uuid": "49a92585-83a8-47f0-8468-675b303fb7bc",
        "payment_type": "payment"
    }
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "user_package_id": 3
    }
}
```

---

#### 4. Check Package Status

- **Endpoint:** `POST /api/v1/package/status`
- **Description:** Retrieves the status of a specific package purchased by the authenticated user.
- **Authentication:** Yes
- **Permissions:** User

##### Request Parameters:

| Parameter         | Required/Optional | Type    | Description                      |
|-------------------|-------------------|---------|----------------------------------|
| `user_package_id` | Required          | Integer | The ID of the purchased package. |

##### Request Example:

```json
{
    "user_package_id": 3
}
```

##### Response Example:

```json
{
    "status": true,
    "message": "success!",
    "data": {
        "id": 3,
        "purchaser": {
            "id": 1,
            "name": "John Doe",
            "email": "john.doe@example.com"
        },
        "package": {
            "id": 1,
            "name": "Basic Package"
        },
        "remaining_credits": 10,
        "is_expired": false,
        "expire_date": "2025-09-13",
        "purchased_at": "2023-09-13"
    }
}
```

---