From 0f7a8c1162f6c9fa53c76e24ab53d831cd697aea Mon Sep 17 00:00:00 2001
From: hamed <15238-genius.ha@users.noreply.drupalcode.org>
Date: Mon, 15 Jun 2026 16:27:10 +0330
Subject: [PATCH] docs(api): document booking window meta and
 month-availability endpoint

- appointment-settings.md: weekly-schedule meta (online_booking_enabled,
  booking_window value/unit), defaults, and the slot-gating behavior.
- appointment.md: new public month-availability endpoint (Gregorian
  year/month, disabled/enabled dates) and the empty-slots conditions for
  appointment-slots.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/api/appointment-settings.md | 26 ++++++++++++++++
 docs/api/appointment.md          | 51 ++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+)

diff --git a/docs/api/appointment-settings.md b/docs/api/appointment-settings.md
index 15cb33d9..edc74651 100644
--- a/docs/api/appointment-settings.md
+++ b/docs/api/appointment-settings.md
@@ -77,6 +77,27 @@ Create or update the weekly schedule for a doctor (upsert).
 | `doctor_uuid` | string (UUID) | ✅ | Doctor UUID |
 | `schedule` | object | ✅ | Keys `"0"` through `"6"` (day indices) |
 | `schedule.{n}.sessions` | array | ✅ | Array of session config objects |
+| `meta` | object | ❌ | Online-booking settings (see below) |
+
+**Online-booking `meta` object:**
+
+```json
+{
+  "meta": {
+    "online_booking_enabled": true,
+    "booking_window_value": 2,
+    "booking_window_unit": "month"
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `online_booking_enabled` | boolean | ❌ | `false` = no online booking; the public slot/month endpoints return no availability |
+| `booking_window_value` | integer | ❌ | How far ahead patients may book (≥ 1) |
+| `booking_window_unit` | string | ❌ | `"week"` or `"month"` |
+
+> Defaults when `meta` is absent: `{ online_booking_enabled: true, booking_window_value: 1, booking_window_unit: "month" }`. `meta` is stored inside the schedule `setting` JSON (no DB migration) and is **preserved** when only `schedule` is sent. `SlotCalculatorService` rejects any date in the past, beyond `today + value unit`, or when online booking is disabled — for the weekly schedule, date overrides, and `appointment-slots` alike.
 
 **Session Config Object:**
 
@@ -111,6 +132,11 @@ Create or update the weekly schedule for a doctor (upsert).
         "5": { "sessions": [] },
         "6": { "sessions": [] }
       },
+      "meta": {
+        "online_booking_enabled": true,
+        "booking_window_value": 1,
+        "booking_window_unit": "month"
+      },
       "created_at": 1717000000,
       "updated_at": 1717000000
     }
diff --git a/docs/api/appointment.md b/docs/api/appointment.md
index 21282f2c..bea43dab 100644
--- a/docs/api/appointment.md
+++ b/docs/api/appointment.md
@@ -57,6 +57,8 @@ Get all appointment slots (available and booked) for a doctor on a specific date
 ```
 
 > Returns **all** slots grouped by work shift. `is_available: false` means the slot has an active (pending/confirmed) appointment. Session boundaries match the doctor's `WeeklySchedule` or date override config.
+>
+> Returns an **empty** `sessions` array when the date is a holiday, a closed date override, in the past, beyond the doctor's booking window, or when online booking is disabled (see `meta` in `appointment-settings.md`).
 
 ### Errors
 | Code | HTTP | Description |
@@ -66,6 +68,55 @@ Get all appointment slots (available and booked) for a doctor on a specific date
 
 ---
 
+## GET `/api/v1/appointment-settings/month-availability/{doctorUuid}`
+
+Which days of a month are bookable — used by the public calendar to grey out unavailable days.
+
+**Permission:** `PUBLIC`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `doctorUuid` | string (UUID) | Doctor UUID |
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `year` | integer | ✅ | **Gregorian** year (e.g. `2026`) |
+| `month` | integer | ✅ | Gregorian month `1`–`12` |
+
+> Input is Gregorian. A Jalali (Shamsi) front-end must convert the displayed month to the Gregorian month(s) it spans before calling.
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "year": 2026,
+    "month": 6,
+    "disabled_dates": ["2026-06-01", "2026-06-17", "2026-06-26"],
+    "enabled_dates": ["2026-06-15", "2026-06-16", "2026-06-18"],
+    "online_booking_enabled": true,
+    "booking_window": { "value": 1, "unit": "month" }
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `disabled_dates` | string[] | `Y-m-d` days with no bookable slot (holiday / closed override / non-working / past / out-of-window) |
+| `enabled_dates` | string[] | `Y-m-d` days with at least one slot |
+| `online_booking_enabled` | boolean | Doctor's online-booking flag |
+| `booking_window` | object | `{ value, unit }` — `unit` is `week` or `month` |
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_VALIDATION_002` | 404 | Doctor not found |
+| `ERR_VALIDATION_001` | 422 | Invalid year/month |
+
+---
+
 ## POST `/api/v1/appointment`
 
 Book an appointment slot.