# Consultant Slots: `from` / `to` Date Filter (frontend guide)

**Audience:** admin dashboard, trainer dashboard and storefront (learner) frontend teams
**API base (stage):** `https://bateel-back.elkady.aait-d.com/api/v1`
**Related:** [consultations-admin.md](./consultations-admin.md) · [consultations-trainer.md](./consultations-trainer.md) · [consultations-user.md](./consultations-user.md)

Every list of consultant slots can now be narrowed to a day range with two
optional query parameters, `from` and `to`. Use this to load one calendar
month (or week, or day) of slots at a time instead of every slot an offering
has ever had.

---

## What changed for each app

| App | Endpoint | Status | What to do |
|---|---|---|---|
| Admin dashboard | `GET /admin/trainer-consultants/{trainer_consultant}/slots` | Unchanged (already supported `from`/`to`) | Nothing required. Documented below for completeness. |
| Admin dashboard | `GET /admin/trainer-consultants/{trainer_consultant}` | Unchanged (already supported `from`/`to` on its embedded `slots`) | Nothing required. |
| Storefront (learner) | `GET /user/trainer-consultants/{trainer_consultant}/slots` | **New: accepts `from` / `to`** | Send the visible month's range from the booking date picker. |
| Trainer dashboard | `GET /trainer/consultant-offerings/{trainerConsultant}/slots` | **New endpoint** | Use it for the offering's slot calendar instead of reading `slots` from the offerings list. |

Nothing was removed or renamed. Requests that don't send `from` / `to`
behave exactly as before.

---

## The filter contract (same on every endpoint)

| Param | Type | Required | Rules |
|---|---|---|---|
| `from` | date `YYYY-MM-DD` | no | Must be a valid date. |
| `to` | date `YYYY-MM-DD` | no | Must be a valid date, and on or after `from` when both are sent. |

How it matches:

- **Whole days, inclusive at both ends.** A slot matches when the *day* of
  its `starts_at` is `>= from` and `<= to`. `from=2026-10-01&to=2026-10-31`
  returns every slot on October 1 through October 31, including one at
  `2026-10-31 23:30:00`. There is no need to send `to` as the next day.
- **Either end can be left out.** `from` only means "this day and later".
  `to` only means "up to and including this day". Neither means no date
  filter.
- **Days are UTC.** `starts_at` is stored and returned in UTC
  (`"2026-10-05 14:00:00"`, no offset), and the day comparison uses UTC too.
  If you display slots in the viewer's local timezone, a slot near midnight
  can fall on a different local day than its UTC day. See
  [Timezones](#timezones) below.
- **Only the date part is used.** Send `2026-10-05`, not `2026-10-05T10:00`.
  A time part is accepted by validation but ignored by the filter.
- **Results stay sorted** by `starts_at`, earliest first.

### Validation error (422)

Sending `to` before `from`, or a value that isn't a date, returns the
standard validation failure. `message` is the first validation error,
localized by `Accept-Language`:

```http
GET /api/v1/user/trainer-consultants/9c1f.../slots?from=2026-10-10&to=2026-10-05
```

```json
{
  "status": "fail",
  "message": "The to field must be a date after or equal to from.",
  "data": null
}
```

The frontend should prevent this case (disable end dates before the start
date in the range picker), so seeing it usually means a bug in how the
range is built.

---

## Storefront (learner): booking date picker

### `GET /user/trainer-consultants/{trainer_consultant}/slots`

**Auth:** public (no token needed). **New:** `from`, `to`.

This endpoint still returns **only open slots**, meaning not booked and not
in the past. The date filter narrows that list further. It never brings back
booked or past slots.

**Request: the slots shown in October's calendar**

```http
GET /api/v1/user/trainer-consultants/9c1f2a7e-.../slots?from=2026-10-01&to=2026-10-31
Accept: application/json
Accept-Language: ar
```

**200 OK**

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": [
    { "id": "a41b...", "starts_at": "2026-10-05 10:00:00" },
    { "id": "b72c...", "starts_at": "2026-10-05 14:00:00" },
    { "id": "c93d...", "starts_at": "2026-10-12 10:00:00" }
  ]
}
```

- No pagination. The full list for the range is returned.
- No `is_booked` field here, since every returned slot is open.
- Pass the chosen slot's `id` as `slot_id` to
  `POST /user/consultation-bookings`, which is unchanged.

**Suggested picker flow**

1. When the picker opens, request the current month:
   `from = first day of month`, `to = last day of month`.
2. Group the returned slots by day and mark days that have no slots as
   unavailable.
3. When the user moves to another month, request that month's range. Cache
   the results by month so going back and forth doesn't refetch.
4. After a booking fails with `"This slot is no longer available."`,
   refetch the current month. Another user probably took that slot.

---

## Trainer dashboard: my offering's slots

### `GET /trainer/consultant-offerings/{trainerConsultant}/slots` (new)

**Auth:** `Bearer {{trainer_token}}`, trainer accounts only. **Permissions:**
none beyond owning the offering. `manage_consultation_slots` is only needed
to *publish* slots, not to view them.

Returns **every** slot on the trainer's own offering: past and future,
booked and open. Each slot includes `is_booked` so the calendar can tell them
apart.

**Request**

```http
GET /api/v1/trainer/consultant-offerings/5e8d.../slots?from=2026-10-01&to=2026-10-31
Authorization: Bearer <trainer_token>
Accept: application/json
```

**200 OK**

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": [
    { "id": "a41b...", "starts_at": "2026-10-05 10:00:00", "is_booked": true },
    { "id": "b72c...", "starts_at": "2026-10-05 14:00:00", "is_booked": false },
    { "id": "c93d...", "starts_at": "2026-10-12 10:00:00", "is_booked": false }
  ]
}
```

- No pagination. The full list for the range is returned.
- `{trainerConsultant}` is the offering's `id` from
  `GET /trainer/consultant-offerings`.

**403: the offering belongs to another trainer**

```json
{
  "status": "error",
  "message": "This consultation offering is not yours.",
  "data": { "error_code": "PERMISSION_DENIED" }
}
```

**404:** the offering uuid doesn't exist.

**Migrating from the offerings list.** `GET /trainer/consultant-offerings`
still embeds each offering's `slots`, but that list is **unfiltered** and
keeps growing as slots are published. For an offering's calendar or slot
table, switch to this endpoint with the visible range. After publishing
slots with `POST .../slots`, refetch the visible range to show them.

---

## Admin dashboard (unchanged, for reference)

### `GET /admin/trainer-consultants/{trainer_consultant}/slots`

**Auth:** `Bearer {{admin_token}}`. Returns every slot (past and future,
booked and open) with `{id, starts_at, is_booked}`.

| Param | Type | Notes |
|---|---|---|
| `from` | date | As above. |
| `to` | date | As above. |
| `paginate` | boolean | Default `false`. `true` wraps the response in a paginator. |
| `per_page` | integer | 1–100, default 15. Only used when `paginate=true`. |
| `page` | integer | Only used when `paginate=true`. |

Without `paginate`, `data` is a plain array (same shape as the trainer
endpoint). With `paginate=true`:

```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "data": [
      { "id": "a41b...", "starts_at": "2026-10-05 10:00:00", "is_booked": true }
    ],
    "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
    "meta": { "current_page": 1, "last_page": 2, "per_page": 15, "total": 23 }
  }
}
```

### `GET /admin/trainer-consultants/{trainer_consultant}`

The detail endpoint accepts the same `from`, `to`, `paginate`, `per_page` and
`page` params. They apply to the embedded `slots` only, not to the offering
itself.

---

## Timezones

The API works in UTC. `from`/`to` are UTC days, and `starts_at` is a UTC
time without an offset. For most slots (daytime hours) the UTC day and the
local day are the same, so sending the local calendar month works fine.

If your UI converts `starts_at` to local time and must be exact at the edges
of the range, widen the request by one day on each side and drop any slot
whose *local* day falls outside the visible range. For Saudi Arabia (UTC+3),
this only affects slots published between 00:00 and 03:00 local time.

---

## Checklist

**Storefront**
- [ ] Booking date picker sends `from`/`to` for the visible month.
- [ ] Month navigation fetches (and caches) each month's range.
- [ ] Days with no returned slots are shown as unavailable.

**Trainer dashboard**
- [ ] Offering slot calendar/table uses `GET /trainer/consultant-offerings/{id}/slots?from=&to=`.
- [ ] Booked slots are shown differently (`is_booked: true`).
- [ ] Visible range is refetched after publishing new slots.

**Admin dashboard**
- [ ] No change required. Optionally, send `from`/`to` for the visible month on the slot calendar if it doesn't already.

**All**
- [ ] Range picker never lets `to` be before `from` (otherwise the API returns 422).
- [ ] Dates are sent as `YYYY-MM-DD`.
