docs/API_REFERENCE.md

# API Reference

Base URL is the deployed backend host.

Recommended production backend host:

- Railway service URL for this repository

Current public model-service host (used by backend when `MODEL_INFERENCE_PROVIDER=remote`):

- `https://pant0x-ealpr-ocr.hf.space`

## Authentication Model

Most business endpoints require:

- `Authorization: Bearer <supabase_access_token>`
- For device integrations, backend can also accept:
  - `Authorization: Bearer <barrier_token>`
  - Enabled when `BARRIER_API_TOKEN` or `BARRIER_API_TOKENS` is configured.

Auth behavior is controlled by backend env config.

### Backend auth endpoints

1. `POST /auth/register`
    - JSON body:
       - `first_name` (recommended)
       - `last_name` (recommended)
       - `username` (required)
       - `phone` or `phone_number` (required)
       - `password` (required)
       - `email` (optional)
       - `nid` or `national_id` (optional)
       - legacy fallback: `full_name` or `name` (optional)
       - optional vehicle payload fields:
          - `plate_letters_ar`, `plate_numbers_ar`
          - `plate_letters_en`, `plate_numbers_en`
          - `car_model`, `car_color`
          - or nested under `vehicle` object
    - Returns user object + session tokens.
    - `user.full_name` is derived from `first_name + last_name`.
      - Register contract is idempotent for OTP-created users: if OTP verify already created/authenticated a user for the same email, register finalizes profile/password instead of failing on duplicate email for the same account.

2. `POST /auth/login`
    - JSON body:
       - `identifier` (username OR phone OR email OR nid)
       - `password`
    - Also accepts direct keys (`username`, `phone`, `email`, `nid`) instead of `identifier`.
    - Returns user object + session tokens.

3. `POST /auth/otp/request`
    - JSON body:
       - `purpose` (`register`, `vehicle_verify`, `profile_update`)
       - `channel` (`email` or `phone`)
       - contact value (`email` or `phone`) unless inferable from authenticated profile
       - optional `redirect_to` for email OTP link flows
    - Sends OTP via Supabase auth.
      - For `purpose=register|signup`, backend forces `create_user=true` to ensure new emails/phones can receive OTP for account creation.
      - For non-register purposes, `create_user` from client is still honored.
      - If OTP signup is disabled in provider config for register flow, API returns a clear contract error:
         `OTP signup is disabled in backend auth configuration (otp_disabled). purpose=register cannot proceed with OTP until OTP signups are enabled.`

4. `POST /auth/otp/verify`
    - JSON body:
       - `channel` (`email` or `phone`)
       - `otp_token`
       - contact value (`email` or `phone`)
       - optional `verify_type`
    - Verifies OTP and returns auth session payload.

## Endpoint Catalog

### Authentication

1. `POST /auth/register`
2. `POST /auth/login`
3. `POST /auth/otp/request`
4. `POST /auth/otp/verify`
5. `POST /auth/forgot-password`
   - JSON body:
      - `identifier` (username OR phone OR email OR nid)
      - optional `redirect_to` URL (HTTPS or app deep-link scheme)
   - Backend always forwards a reset redirect URL to Supabase:
      - payload `redirect_to` if provided, otherwise
      - `PASSWORD_RESET_REDIRECT_URL` env, otherwise
      - `<backend-host>/auth/reset-password-page`

6. `POST /auth/reset-password`
   - JSON body:
      - `access_token`
      - `new_password`

7. `POST /auth/reset-password/resolve-token`
   - JSON body:
      - one of: `access_token`, `token_hash`, `code`
      - optional: `type` (defaults to `recovery`), `email`
   - Resolves Supabase recovery links that provide `token_hash`/`code` into a usable access token.

8. `GET /auth/reset-password-page`
   - Hosted reset page that reads token from the recovery link, submits to `/auth/reset-password`, then shows a success view and auto-opens the app deep link.

9. `GET /auth/reset-password-bridge`
   - Bridge page that opens mobile deep link reset flow (`ainelaql://auth/reset`) and provides browser fallback.

### User profile

1. `PUT /profile/update`
   - JSON body (any subset):
      - `first_name`
      - `last_name`
      - `full_name`
      - `phone` or `phone_number`
      - `email`
   - Updates profile metadata and mirrors auth metadata.
   - `full_name` is always normalized from `first_name + last_name` (legacy `full_name` input is still accepted and split into parts).

### Vehicles (multi-vehicle CRUD)

1. `POST /vehicles/add`
2. `GET /vehicles/my`
   - Optional query: `include_inactive=true|false`
3. `PUT /vehicles/{id}`
4. `DELETE /vehicles/{id}`
5. `POST /vehicles/verify`
   - OTP-backed ownership verification for a vehicle.

### Notifications

1. `POST /notifications/fcm-token`
   - Stores or updates FCM token for the authenticated user.
2. `GET /notifications/my`
   - Returns latest notification events for the authenticated user.
   - Notification events are server-generated (service role).
   - Authenticated users can only update their own `read_at` state; they cannot create, delete, or edit notification content.

### Health and diagnostics

1. `GET /`
   - Lightweight service entry endpoint.
   - Returns links to docs and health endpoints.

2. `GET /health`
   - Service health, inference provider wiring, and pricing config snapshot.

3. `GET /supabase/health`
   - Supabase readiness checks (tables, buckets, auth wiring).

4. `GET /models`
   - Inference provider details and local model info when local loading is enabled.

### Inference and session events

1. `POST /predict`
   - Input: `multipart/form-data`
   - Required: `image`
   - Optional: `event_type`, `parking_location`, `camera_source`
   - Auth:
      - Supabase user token (mobile/web/staff clients), or
      - barrier token (camera/barrier devices)
   - Returns AI output + pricing + gate decision + persistence metadata.

2. `POST /model/infer`
   - Input: `multipart/form-data`
   - Required: `image`
   - Intended for backend-to-backend model inference calls.
   - Requires `MODEL_SERVICE_ENABLE_LOCAL_ENDPOINT=true` in the model runtime.
   - If `MODEL_SERVICE_SHARED_SECRET` is configured, caller must send the configured header.

### Operations feeds

1. `GET /events/entered-cars`
2. `GET /events/leaving-cars-within-5-minutes`
3. `GET /events/left-cars`
4. `GET /events/inside-cars`
5. `GET /parking/history`

Common optional query params:

- `limit`
- `for_user_id` (global-scope roles: `admin`, `security`, `barrier`)

### Location pricing and occupancy

1. `GET /parking/locations`
   - Returns pricing defaults + garage occupancy + per-location pricing/occupancy blocks.
   - Occupancy includes breakdown fields:
      - `inside_from_registered_sessions`
      - `inside_from_inferred_unmatched`

2. `GET /parking/occupancy`
   - Returns occupancy-focused response for dashboards.
   - Uses same occupancy breakdown fields under each location.

### Payments and gate flow

1. `POST /payments/paymob/create`
2. `POST /payments/paymob/webhook`
3. `POST /payments/manual/cash-confirm`
4. `POST /gate/decision`

`POST /gate/decision` can be called by:

- session owner
- staff roles (`admin`, `security`)
- `barrier` role token

### Maintenance

1. `POST /admin/maintenance/weekly-refresh`

## Key Response Blocks (Flutter-critical)

From `/predict` and feed/history responses, consume:

1. `plate_info` and normalized `plate` sections
2. `app_registration`
3. `payment_status`
4. `pricing`
5. `gate_decision`
6. `left_within_5_minutes`
7. image fields under `user_page` and `admin_page`
8. Supabase persistence IDs/paths under `supabase`
9. `inference_provider` (`local` or `remote`)

For `GET /events/inside-cars` and `GET /parking/history`, some items can include:

1. `inferred_unmatched=true`
2. `plate` object (`key`, `arabic`, `english`)
3. `event_count`

These rows are inferred from unmatched OCR event streams (events that are not linked to a registered vehicle/session).

## Status and Error Behavior

- `400`: validation/input formatting issues
- `401`: missing/invalid auth token
- `403`: role/scope violations
- `404`: missing session/resource
- `502/503`: upstream or integration failures (Supabase/Paymob/service config)

## Testing Minimum

1. `GET /health`
2. `GET /supabase/health`
3. `POST /predict` for entry
4. `POST /predict` for exit
5. `GET /parking/locations`
6. `GET /parking/occupancy`