Metadata-Version: 2.4
Name: monicka-booking
Version: 0.1.1
Summary: Accessible Persian clinic booking pages for Monicka API
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Django<6,>=4.2
Requires-Dist: requests<3,>=2.31
Provides-Extra: test
Requires-Dist: pytest<9,>=8; extra == "test"
Requires-Dist: pytest-django<5,>=4.8; extra == "test"

# Monicka Booking

An accessible, Persian right-to-left booking app for Django clinic websites. It is a server-rendered Django app distributed as a pip package; it does not expose clinic API keys to the visitor's browser and uses no JavaScript framework or external font service.

## Install

```sh
pip install monicka-booking
```

Add the app, set its API key in the website process environment, and mount its URLs:

```python
# settings.py
INSTALLED_APPS += ["monicka_booking"]
MONICKA_API_KEY = "<the clinic API key>"  # Prefer an environment variable/secret manager.
```

```python
# urls.py
from django.urls import include, path

urlpatterns += [path("booking/", include("monicka_booking.urls"))]
```

Then run `python manage.py migrate`. A staff user can configure title, colors, text size, displayed currency label, and optional support phone in Django admin under **Booking page settings**. Set the API origin and home clinic ID there. The API key is intentionally configured outside admin and is never sent to the browser.

### Static files in production

The package contains its CSS, JavaScript, and logo under Django's app static directory. Django's development server discovers these directly when `django.contrib.staticfiles` and `monicka_booking` are in `INSTALLED_APPS`. Production servers do not serve app assets automatically: configure `STATIC_ROOT` and run `collectstatic` whenever the package is installed or upgraded, then serve that directory through Nginx or WhiteNoise.

```python
# settings.py
STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
```

```sh
python manage.py collectstatic --noinput
```

For Nginx, map `/static/` to the `STATIC_ROOT` directory. If the site uses a manifest-based static storage backend, keep its collected manifest and hashed assets together. A successful `collectstatic` should include `monicka_booking/booking.css`, `monicka_booking/booking.js`, `monicka_booking/assessment.js`, and `monicka_booking/monicka-logo.png`.

## API setup

Issue a clinic API key in Monicka and set the key's home clinic `website_url` to this site's HTTPS origin (including the same origin used by the plugin payment return URL). Set each clinic's `plugin_booking_days` in API admin. The default booking window is 20 future days. All clinics with the same owner are offered as branches in one catalog. Therapist profile fields (short bio and specialties) are maintained in API admin.

The package talks to the API over HTTPS using `X-Clinic-API-Key`. Website hosting must allow outbound HTTPS requests to the configured API. The payment callback returns to the plugin completion page, where the package verifies the confirmation code server-to-server before showing appointment status.

### Direct therapist booking links

To link directly to one therapist at one branch, use the regular booking URL with both public IDs:

```text
/booking/?therapist=133&clinic=5
```

The plugin checks that this therapist is actually offered at that clinic before entering the calendar step. The page then contains only that therapist and branch, skips the therapist/branch directory, and continues through the normal availability, booking, and payment checks. Invalid or mismatched IDs show an error instead of opening the full directory. These IDs are selectors, not credentials; do not put a patient's name, phone number, or other personal details in a URL. The API still validates every selected time and booking.

## Booking flow and accessibility

The initial therapist catalog is server-rendered. JavaScript progressively loads the Jalali calendar's available days and slots from same-origin Django views; dates and slots are always validated again by the API at booking time. The responsive UI uses semantic form labels, keyboard-operable buttons, visible focus rings, large controls, live status announcements, high-contrast light themes, adjustable type size, and reduced-motion support.

Theme choices are intentionally CSS-variable based so future themes can be added without introducing a UI framework. The calendar uses the browser's built-in Persian calendar formatter.

## Development

```sh
pip install -e '.[test]'
python -m django test --settings tests.settings
```

You can also run the source checkout as a standalone local Django site without installing `monicka-booking`. Use an existing Python environment with Django and Requests available:

```sh
export PYTHONPATH="$PWD/src"
DJANGO_PYTHON="/path/to/python-with-django"
"$DJANGO_PYTHON" -m django migrate --settings tests.dev_settings
"$DJANGO_PYTHON" -m django createsuperuser --settings tests.dev_settings
"$DJANGO_PYTHON" -m django runserver 127.0.0.1:8000 --settings tests.dev_settings
```

Open `http://localhost:8000/booking/` for the booking page or `/admin/` to configure its title and theme. This local setup uses a persistent SQLite database at `dev.sqlite3`; the test settings continue to use an in-memory database. Without `MONICKA_API_KEY` and a reachable API the page shows its friendly unavailable state. To try real slots and payment handoff, point it at a staging API and test gateway. A production project supplies its own Django settings, database, and admin configuration.
