# Hire a Player API

Endpoints for creating and managing **"Hire a Player"** hunt listings. These listings appear in the shared hunt feed alongside the other hunt types (opponent, ground, umpire, etc.) under the type `hire_a_player`.

All routes are under `/api/hunt` and require the API key header:

```
x-api-key: <API_KEY>
```

All listing fields are **optional except `user_id`** (on create). Omitted fields are stored as `NULL`.

---

## Fields

| Field | Type | Notes |
|-------|------|-------|
| `user_id` | integer | **Required on create.** The owner of the listing. |
| `ad_headline` | string | e.g. "Hire a Fast Bowler - wicket-taker" |
| `listing_owner` | string | Listing owner / team name, e.g. "Super Strikers" |
| `player_position` | string | `All` \| `Batsman` \| `Bowler` \| `All-rounder` \| `Wicket-keeper` |
| `bowling_style` | string | `All` \| `Fast` \| `Spin` |
| `player_category` | string | `Pro` \| `Amateur` |
| `specialization_role` | string | e.g. "Right-arm Fast, Death Overs specialist" |
| `match_fee` | integer | Match fee / cost in INR |
| `negotiable` | boolean | "Negotiable per match" checkbox. Accepts `true`/`false` or `"true"`/`"false"`. |
| `budget_min` | integer | Budget range lower bound (INR) |
| `budget_max` | integer | Budget range upper bound (INR) |
| `communication_methods` | string[] | Accepts an array or a single string, e.g. `["Phone Call", "Direct Message (DM)"]` |
| `net_session_duration` | string | Net session duration, e.g. `1 hr` \| `2 hr` \| `Half day` \| `Full day` |
| `description` | string | Free-text description (up to 300 chars in the UI) |

---

## Create a listing

`POST /api/hunt/hire-a-player`

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{
    "user_id": 42,
    "ad_headline": "Hire a Fast Bowler - wicket-taker",
    "listing_owner": "Super Strikers",
    "player_position": "Bowler",
    "bowling_style": "Fast",
    "player_category": "Pro",
    "specialization_role": "Right-arm Fast, Death Overs specialist",
    "match_fee": 9000,
    "negotiable": true,
    "budget_min": 0,
    "budget_max": 23000,
    "communication_methods": ["Phone Call", "Direct Message (DM)"],
    "net_session_duration": "2 hr",
    "description": "Looking for an experienced death-overs specialist for the weekend league."
  }' \
  http://localhost:3000/api/hunt/hire-a-player
```

**Minimal request** (only `user_id` required):

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{ "user_id": 42 }' \
  http://localhost:3000/api/hunt/hire-a-player
```

**Response** `201 Created`:

```json
{
  "id": 7,
  "user_id": 42,
  "ad_headline": "Hire a Fast Bowler - wicket-taker",
  "listing_owner": "Super Strikers",
  "player_position": "Bowler",
  "bowling_style": "Fast",
  "player_category": "Pro",
  "specialization_role": "Right-arm Fast, Death Overs specialist",
  "match_fee": 9000,
  "negotiable": true,
  "budget_min": 0,
  "budget_max": 23000,
  "communication_methods": ["Phone Call", "Direct Message (DM)"],
  "net_session_duration": "2 hr",
  "description": "Looking for an experienced death-overs specialist for the weekend league.",
  "created_at": "2026-07-08T07:25:00.000Z"
}
```

Errors: `400` if `user_id` is missing, `500` on server error.

---

## Show listings in the hunt feed

`GET /api/hunt/?page=1&limit=10`

The hunt feed is a combined listing of all hunt types. Pass a `filters` array in the request body to restrict to one or more types. To show only Hire-a-Player listings:

```bash
curl -X GET \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{ "filters": ["hire_a_player"] }' \
  "http://localhost:3000/api/hunt/?page=1&limit=10"
```

- Empty `filters` (`[]`) returns all types from the last 7 days.
- Each item is returned as `{ type: "hire_a_player", data: { ...listing }, post_owner, profile_picture, created_at }`.

The per-user feed works the same way: `GET /api/hunt/:user_id` with the same `filters` body.

---

## Get a single listing

`GET /api/hunt/posts/:post_id?post_type=hire_a_player`

```bash
curl -X GET \
  -H "x-api-key: <API_KEY>" \
  "http://localhost:3000/api/hunt/posts/7?post_type=hire_a_player"
```

---

## Update a listing

`PUT /api/hunt/hire-a-player/:id`

Only the fields you send are updated (each is `COALESCE`d, so omitted fields keep their current value).

```bash
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "x-api-key: <API_KEY>" \
  -d '{ "match_fee": 12000, "negotiable": false }' \
  http://localhost:3000/api/hunt/hire-a-player/7
```

**Response** `200 OK`: `{ "message": "Post updated successfully", "data": { ...listing } }`
Returns `404` if the listing id does not exist.

---

## Delete a listing

`DELETE /api/hunt/:post_id?post_type=hire_a_player`

```bash
curl -X DELETE \
  -H "x-api-key: <API_KEY>" \
  "http://localhost:3000/api/hunt/7?post_type=hire_a_player"
```

**Response** `200 OK`: `{ "message": "Post deleted successfully!!" }`

---

## Database

Requires the `hire_a_player` table (see `src/db/hire_a_player.sql`). Run once:

```bash
psql "$DATABASE_URL" -f src/db/hire_a_player.sql
```