{
  "openapi": "3.0.3",
  "info": {
    "title": "AquaWatch API",
    "description": "Water Level Monitoring System API v2.0",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ultimatesolutions.co.ke",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "security": [
    { "BearerAuth": [] }
  ],
  "paths": {

    "/api/auth.php?action=register": {
      "post": {
        "tags": ["Auth"],
        "summary": "Register new account",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email", "example": "user@example.com" },
                  "password": { "type": "string", "minLength": 8, "example": "secret123" },
                  "full_name": { "type": "string", "example": "John Doe" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Account created, returns JWT token and user" },
          "400": { "description": "Validation error or email already exists" }
        }
      }
    },

    "/api/auth.php?action=login": {
      "post": {
        "tags": ["Auth"],
        "summary": "Login with email and password",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email", "example": "user@example.com" },
                  "password": { "type": "string", "example": "secret123" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Login successful, returns JWT token and user" },
          "401": { "description": "Invalid email or password" }
        }
      }
    },

    "/api/auth.php?action=logout": {
      "post": {
        "tags": ["Auth"],
        "summary": "Logout (blacklists token)",
        "responses": {
          "200": { "description": "Logged out, token blacklisted" }
        }
      }
    },

    "/api/auth.php?action=session": {
      "get": {
        "tags": ["Auth"],
        "summary": "Get current session / user info",
        "responses": {
          "200": { "description": "Current user data" },
          "401": { "description": "Not authenticated" }
        }
      }
    },

    "/api/auth.php?action=update": {
      "put": {
        "tags": ["Auth"],
        "summary": "Update profile (name and/or password)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "full_name": { "type": "string", "example": "Jane Doe" },
                  "password": { "type": "string", "minLength": 8, "example": "newpass123" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Profile updated" }
        }
      }
    },

    "/api/auth.php?action=reset-request": {
      "post": {
        "tags": ["Auth"],
        "summary": "Request password reset token",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email"],
                "properties": {
                  "email": { "type": "string", "format": "email", "example": "user@example.com" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Returns reset_token and expires_at" }
        }
      }
    },

    "/api/auth.php?action=reset-password": {
      "post": {
        "tags": ["Auth"],
        "summary": "Reset password with token",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["token", "password"],
                "properties": {
                  "token": { "type": "string", "example": "abc123resettoken" },
                  "password": { "type": "string", "minLength": 8, "example": "newpass123" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Password reset, returns new JWT token" },
          "401": { "description": "Invalid or expired token" }
        }
      }
    },

    "/api/devices.php?action=list": {
      "get": {
        "tags": ["Devices"],
        "summary": "List all user devices",
        "responses": {
          "200": { "description": "Array of devices with location and online status" }
        }
      }
    },

    "/api/devices.php?action=register": {
      "post": {
        "tags": ["Devices"],
        "summary": "Register a new device",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["mac_or_serial"],
                "properties": {
                  "mac_or_serial": { "type": "string", "example": "AA:BB:CC:DD:EE:FF" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Device registered" },
          "409": { "description": "Device already registered to another user" }
        }
      }
    },

    "/api/devices.php?action=check": {
      "get": {
        "tags": ["Devices"],
        "summary": "Check if user has registered devices",
        "responses": {
          "200": { "description": "Returns has_device boolean and count" }
        }
      }
    },

    "/api/devices.php?action=primary": {
      "get": {
        "tags": ["Devices"],
        "summary": "Get user's primary (first registered) device",
        "responses": {
          "200": { "description": "Primary device details" },
          "404": { "description": "No device registered" }
        }
      }
    },

    "/api/devices.php?action=exists&mac={mac}": {
      "get": {
        "tags": ["Devices"],
        "summary": "Check if a MAC/serial is already registered",
        "parameters": [
          { "name": "mac", "in": "query", "required": true, "schema": { "type": "string" }, "example": "AA:BB:CC:DD:EE:FF" }
        ],
        "responses": {
          "200": { "description": "Returns exists and owned_by_me booleans" }
        }
      }
    },

    "/api/devices.php?action=update-name": {
      "put": {
        "tags": ["Devices"],
        "summary": "Update device name",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["mac_or_serial"],
                "properties": {
                  "mac_or_serial": { "type": "string", "example": "AA:BB:CC:DD:EE:FF" },
                  "device_name": { "type": "string", "example": "Main Tank" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Device name updated" },
          "404": { "description": "Device not found" }
        }
      }
    },

    "/api/devices.php?action=remove&id={id}": {
      "delete": {
        "tags": ["Devices"],
        "summary": "Remove a device",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "device-uuid" }
        ],
        "responses": {
          "200": { "description": "Device removed" },
          "404": { "description": "Device not found" }
        }
      }
    },

    "/api/devices.php?action=location&id={id}": {
      "get": {
        "tags": ["Devices"],
        "summary": "Get device location and location history",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "device-uuid" }
        ],
        "responses": {
          "200": { "description": "Device location, online status, and last 10 GPS readings" },
          "404": { "description": "Device not found" }
        }
      }
    },

    "/api/devices.php?action=api-key": {
      "post": {
        "tags": ["Devices"],
        "summary": "Generate API key for a device",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["device_id"],
                "properties": {
                  "device_id": { "type": "string", "example": "device-uuid" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Returns generated api_key" }
        }
      }
    },

    "/api/sensors.php?action=latest&device_id={device_id}": {
      "get": {
        "tags": ["Sensors"],
        "summary": "Get latest readings for a device",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "device-uuid" }
        ],
        "responses": {
          "200": { "description": "Latest readings per sensor" }
        }
      }
    },

    "/api/sensors.php?action=history&device_id={device_id}": {
      "get": {
        "tags": ["Sensors"],
        "summary": "Get historical readings",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "hours", "in": "query", "schema": { "type": "integer", "default": 24, "minimum": 1, "maximum": 168 } },
          { "name": "sensor_name", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Historical readings array" }
        }
      }
    },

    "/api/sensors.php?action=reading": {
      "post": {
        "tags": ["Sensors"],
        "summary": "Submit a new sensor reading (via app)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["device_id", "sensor_name", "level"],
                "properties": {
                  "device_id": { "type": "string", "example": "device-uuid" },
                  "sensor_name": { "type": "string", "example": "tank-1" },
                  "level": { "type": "number", "example": 75.5 },
                  "level_cm": { "type": "number", "example": 45.2 },
                  "volume": { "type": "number", "example": 5000 },
                  "temperature": { "type": "number", "example": 22.3 },
                  "pump_status": { "type": "string", "enum": ["on", "off"] },
                  "latitude": { "type": "number", "example": -1.2921 },
                  "longitude": { "type": "number", "example": 36.8219 },
                  "status": { "type": "string", "enum": ["normal", "warning", "critical"], "default": "normal" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Reading recorded" }
        }
      }
    },

    "/api/sensors.php?action=summary&device_id={device_id}": {
      "get": {
        "tags": ["Sensors"],
        "summary": "Get sensor summary (avg, min, max)",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "hours", "in": "query", "schema": { "type": "integer", "default": 24, "minimum": 1, "maximum": 168 } }
        ],
        "responses": {
          "200": { "description": "Aggregated sensor stats" }
        }
      }
    },

    "/api/sensor_configs.php?action=list&device_id={device_id}": {
      "get": {
        "tags": ["Sensor Configs"],
        "summary": "List sensor configs for a device",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Array of sensor configs" }
        }
      }
    },

    "/api/sensor_configs.php?action=save": {
      "post": {
        "tags": ["Sensor Configs"],
        "summary": "Create or update sensor config",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["device_id", "sensor_name"],
                "properties": {
                  "device_id": { "type": "string", "example": "device-uuid" },
                  "sensor_name": { "type": "string", "example": "tank-1" },
                  "capacity": { "type": "integer", "minimum": 100, "maximum": 100000, "example": 5000 },
                  "high_threshold": { "type": "integer", "minimum": 50, "maximum": 99, "example": 90 },
                  "low_threshold": { "type": "integer", "minimum": 1, "maximum": 49, "example": 10 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Config updated" },
          "201": { "description": "Config created" }
        }
      }
    },

    "/api/sensor_configs.php?action=remove&id={id}": {
      "delete": {
        "tags": ["Sensor Configs"],
        "summary": "Delete a sensor config",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Config removed" }
        }
      }
    },

    "/api/pump_commands.php?action=list&device_id={device_id}": {
      "get": {
        "tags": ["Pump Commands"],
        "summary": "List pump commands for a device",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }
        ],
        "responses": {
          "200": { "description": "Array of pump commands with source and acknowledged_at" }
        }
      }
    },

    "/api/pump_commands.php?action=pending&device_id={device_id}": {
      "get": {
        "tags": ["Pump Commands"],
        "summary": "Get pending (unexecuted) commands",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Array of pending commands" }
        }
      }
    },

    "/api/pump_commands.php?action=send": {
      "post": {
        "tags": ["Pump Commands"],
        "summary": "Send a pump command",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["device_id", "sensor_name", "command"],
                "properties": {
                  "device_id": { "type": "string", "example": "device-uuid" },
                  "sensor_name": { "type": "string", "example": "tank-1" },
                  "command": { "type": "string", "enum": ["on", "off", "auto", "schedule"] },
                  "turn_on_below": { "type": "number", "example": 20 },
                  "turn_off_above": { "type": "number", "example": 80 }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Command sent" }
        }
      }
    },

    "/api/pump_commands.php?action=mark-executed&id={id}": {
      "put": {
        "tags": ["Pump Commands"],
        "summary": "Mark command as executed",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Command marked as executed" }
        }
      }
    },

    "/api/pump_commands.php?action=cancel&id={id}": {
      "delete": {
        "tags": ["Pump Commands"],
        "summary": "Cancel a pending command",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Command cancelled" }
        }
      }
    },

    "/api/alerts.php?action=list&device_id={device_id}": {
      "get": {
        "tags": ["Alerts"],
        "summary": "List alerts for a device",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } },
          { "name": "severity", "in": "query", "schema": { "type": "string", "enum": ["critical", "warning", "info"] } }
        ],
        "responses": {
          "200": { "description": "Array of alerts" }
        }
      }
    },

    "/api/alerts.php?action=unread-count&device_id={device_id}": {
      "get": {
        "tags": ["Alerts"],
        "summary": "Get unread alert count",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Unread count" }
        }
      }
    },

    "/api/alerts.php?action=create": {
      "post": {
        "tags": ["Alerts"],
        "summary": "Create an alert",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["device_id", "type", "message"],
                "properties": {
                  "device_id": { "type": "string", "example": "device-uuid" },
                  "type": { "type": "string", "enum": ["overflow", "low", "sensor", "pump", "offline", "maintenance"] },
                  "severity": { "type": "string", "enum": ["critical", "warning", "info"], "default": "info" },
                  "message": { "type": "string", "example": "Water level critically low" },
                  "sensor_name": { "type": "string", "example": "tank-1" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Alert created" }
        }
      }
    },

    "/api/alerts.php?action=mark-read&id={id}": {
      "put": {
        "tags": ["Alerts"],
        "summary": "Mark alert as read",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Alert marked as read" }
        }
      }
    },

    "/api/alerts.php?action=mark-all-read&device_id={device_id}": {
      "put": {
        "tags": ["Alerts"],
        "summary": "Mark all alerts as read",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "All alerts marked as read" }
        }
      }
    },

    "/api/alerts.php?action=delete&id={id}": {
      "delete": {
        "tags": ["Alerts"],
        "summary": "Delete an alert",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Alert deleted" }
        }
      }
    },

    "/api/reports.php?action=daily": {
      "get": {
        "tags": ["Reports"],
        "summary": "Daily averages report",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["1d", "7d", "30d", "90d"], "default": "7d" } },
          { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "sensor_name", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Daily aggregated data" }
        }
      }
    },

    "/api/reports.php?action=usage": {
      "get": {
        "tags": ["Reports"],
        "summary": "Water usage / consumption report",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["1d", "7d", "30d", "90d"], "default": "7d" } },
          { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "sensor_name", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Daily usage data with total_volume_change" }
        }
      }
    },

    "/api/reports.php?action=alerts": {
      "get": {
        "tags": ["Reports"],
        "summary": "Alert history report",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["1d", "7d", "30d", "90d"], "default": "7d" } },
          { "name": "severity", "in": "query", "schema": { "type": "string", "enum": ["critical", "warning", "info"] } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["overflow", "low", "sensor", "pump", "offline", "maintenance"] } },
          { "name": "sensor_name", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Alert list with summary counts" }
        }
      }
    },

    "/api/reports.php?action=pump": {
      "get": {
        "tags": ["Reports"],
        "summary": "Pump activity report",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["1d", "7d", "30d", "90d"], "default": "7d" } },
          { "name": "command", "in": "query", "schema": { "type": "string", "enum": ["on", "off", "auto", "schedule"] } },
          { "name": "sensor_name", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Pump commands with total/executed/pending summary" }
        }
      }
    },

    "/api/reports.php?action=export": {
      "get": {
        "tags": ["Reports"],
        "summary": "Export raw sensor data",
        "parameters": [
          { "name": "device_id", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "csv"], "default": "json" } },
          { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["1d", "7d", "30d", "90d"], "default": "7d" } },
          { "name": "sensor_name", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Raw data as JSON or CSV download" }
        }
      }
    },

    "/iot_push.php": {
      "post": {
        "tags": ["IoT Device"],
        "summary": "Push sensor reading from ESP32",
        "description": "Direct endpoint for IoT devices. Accepts form-urlencoded. Auth by MAC + optional API key.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["mac_address", "water_level_percent"],
                "properties": {
                  "mac_address": { "type": "string", "example": "AA:BB:CC:DD:EE:FF" },
                  "water_level_percent": { "type": "number", "example": 75.5 },
                  "water_level_cm": { "type": "number", "example": 45.2 },
                  "pump_status": { "type": "string", "enum": ["on", "off"], "example": "off" },
                  "latitude": { "type": "number", "example": -1.2921 },
                  "longitude": { "type": "number", "example": 36.8219 },
                  "api_key": { "type": "string", "example": "your-device-api-key" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Reading recorded with auto-detected status" },
          "404": { "description": "Device MAC not registered" },
          "401": { "description": "Invalid API key" }
        }
      }
    },

    "/iot_commands.php": {
      "get": {
        "tags": ["IoT Device"],
        "summary": "Poll for pending pump commands",
        "security": [],
        "parameters": [
          { "name": "mac_address", "in": "query", "required": true, "schema": { "type": "string" }, "example": "AA:BB:CC:DD:EE:FF" },
          { "name": "api_key", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Array of pending commands" },
          "404": { "description": "Device MAC not registered" }
        }
      }
    },

    "/iot_ack.php": {
      "post": {
        "tags": ["IoT Device"],
        "summary": "Acknowledge command execution",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["mac_address", "command_id"],
                "properties": {
                  "mac_address": { "type": "string", "example": "AA:BB:CC:DD:EE:FF" },
                  "command_id": { "type": "string", "example": "command-uuid" },
                  "api_key": { "type": "string", "example": "your-device-api-key" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Command acknowledged" },
          "404": { "description": "Command not found or already executed" }
        }
      }
    }
  }
}