openapi: 3.0.3
info:
  title: Travel Router Control API
  description: |
    API for controlling a mini travel router with dual WiFi interfaces and Ethernet connectivity.
    The router can operate as a WiFi repeater, connecting to upstream networks while providing
    a hotspot for client devices.
  version: 1.0.0
  contact:
    name: API Support
  license:
    name: MIT

servers:
  - url: http://localhost:8080
    description: Local router API

tags:
  - name: WiFi
    description: WiFi client operations (upstream network connection)
  - name: Hotspot
    description: Access point operations (client-facing hotspot)
  - name: Devices
    description: Connected devices management
  - name: System
    description: System status and monitoring
  - name: Logs
    description: System logs and real-time monitoring

paths:
  /api/wifi/scan:
    get:
      tags:
        - WiFi
      summary: Scan for available WiFi networks
      description: |
        Triggers a WiFi scan using wpa_supplicant via D-Bus and returns all discovered networks
        sorted by signal strength. The scan takes approximately 2 seconds to complete.
      operationId: scanWiFi
      responses:
        '200':
          description: Successfully scanned networks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WiFiNetwork'
              example:
                - ssid: "Hotel-Guest"
                  signal: 5
                  security: "WPA2"
                  channel: 6
                  bssid: "aa:bb:cc:dd:ee:ff"
                - ssid: "Public-WiFi"
                  signal: 3
                  security: "Open"
                  channel: 11
                  bssid: "11:22:33:44:55:66"
        '500':
          description: Scan error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/wifi/connect:
    post:
      tags:
        - WiFi
      summary: Connect to a WiFi network
      description: |
        Connects the router to an upstream WiFi network using wpa_supplicant.
        Supports both open and password-protected networks (WPA/WPA2).
      operationId: connectWiFi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WiFiConnectRequest'
            examples:
              protected:
                summary: WPA2 protected network
                value:
                  ssid: "Hotel-Guest"
                  password: "guest1234"
              open:
                summary: Open network
                value:
                  ssid: "Public-WiFi"
                  password: ""
      responses:
        '200':
          description: Successfully connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Connection failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/wifi/disconnect:
    post:
      tags:
        - WiFi
      summary: Disconnect from WiFi network
      description: |
        Disconnects from the currently connected upstream WiFi network
        and removes all saved network configurations.
      operationId: disconnectWiFi
      responses:
        '200':
          description: Successfully disconnected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '500':
          description: Disconnection failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/hotspot/config:
    post:
      tags:
        - Hotspot
      summary: Configure hotspot settings
      description: |
        Updates the hotspot (access point) configuration including SSID, password,
        and WiFi channel. Changes are written to hostapd configuration file.
        The hotspot needs to be restarted for changes to take effect.
      operationId: configureHotspot
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotspotConfig'
      responses:
        '200':
          description: Configuration updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid configuration data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Configuration update failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/hotspot/toggle:
    post:
      tags:
        - Hotspot
      summary: Toggle hotspot on/off
      description: |
        Enables or disables the hotspot (access point) by starting/stopping
        the hostapd service. Returns the new enabled state.
      operationId: toggleHotspot
      responses:
        '200':
          description: Hotspot state changed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                    description: Current hotspot state after toggle
                required:
                  - enabled
              example:
                enabled: true
        '500':
          description: Failed to change hotspot state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/devices:
    get:
      tags:
        - Devices
      summary: Get connected devices
      description: |
        Returns a list of all devices currently connected to the hotspot.
        Device information is gathered from DHCP leases and ARP tables.
        Only devices with active ARP entries are considered connected.
      operationId: getDevices
      responses:
        '200':
          description: List of connected devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectedDevice'
              example:
                - name: "iPhone-12"
                  type: "mobile"
                  mac: "aa:bb:cc:11:22:33"
                  ip: "192.168.1.100"
                - name: "MacBook-Pro"
                  type: "laptop"
                  mac: "dd:ee:ff:44:55:66"
                  ip: "192.168.1.101"
        '500':
          description: Failed to retrieve device list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/status:
    get:
      tags:
        - System
      summary: Get system status
      description: |
        Returns comprehensive system status including WiFi connection state,
        hotspot status, connected device count, data usage, and uptime.
      operationId: getStatus
      responses:
        '200':
          description: Current system status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemStatus'

  /api/logs:
    get:
      tags:
        - Logs
      summary: Get system logs
      description: |
        Returns the last 100 log entries from the system.
        For real-time log streaming, use the WebSocket endpoint.
      operationId: getLogs
      responses:
        '200':
          description: List of log entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogEntry'
              example:
                - timestamp: "2025-10-28T14:32:10Z"
                  source: "WiFi"
                  message: "Scan terminé - 5 réseaux trouvés"
                - timestamp: "2025-10-28T14:32:15Z"
                  source: "WiFi"
                  message: "Tentative de connexion à Hotel-Guest"
    delete:
      tags:
        - Logs
      summary: Clear system logs
      description: Clears all stored log entries (keeps only the "logs cleared" entry)
      operationId: clearLogs
      responses:
        '200':
          description: Logs cleared successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'

  /ws/logs:
    get:
      tags:
        - Logs
      summary: WebSocket for real-time logs
      description: |
        WebSocket endpoint for receiving real-time log updates.
        Upon connection, all existing logs are sent, followed by new logs as they occur.

        This is a WebSocket endpoint - upgrade the HTTP connection to WebSocket protocol.
      operationId: logsWebSocket
      responses:
        '101':
          description: WebSocket connection established
        '400':
          description: WebSocket upgrade failed

components:
  schemas:
    WiFiNetwork:
      type: object
      description: Discovered WiFi network information
      properties:
        ssid:
          type: string
          description: Network SSID (name)
          example: "Hotel-Guest"
        signal:
          type: integer
          description: Signal strength (1-5 scale)
          minimum: 1
          maximum: 5
          example: 4
        security:
          type: string
          description: Security type
          enum:
            - Open
            - WEP
            - WPA
            - WPA2
          example: "WPA2"
        channel:
          type: integer
          description: WiFi channel number
          minimum: 1
          maximum: 165
          example: 6
        bssid:
          type: string
          description: Access point MAC address
          pattern: '^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$'
          example: "aa:bb:cc:dd:ee:ff"
      required:
        - ssid
        - signal
        - security
        - channel
        - bssid

    WiFiConnectRequest:
      type: object
      description: Request to connect to a WiFi network
      properties:
        ssid:
          type: string
          description: Network SSID to connect to
          example: "Hotel-Guest"
        password:
          type: string
          description: Network password (empty string for open networks)
          example: "guest1234"
      required:
        - ssid
        - password

    HotspotConfig:
      type: object
      description: Hotspot (access point) configuration
      properties:
        ssid:
          type: string
          description: Hotspot SSID (network name)
          minLength: 1
          maxLength: 32
          example: "TravelRouter"
        password:
          type: string
          description: WPA2 password (minimum 8 characters)
          minLength: 8
          maxLength: 63
          example: "secure123"
        channel:
          type: integer
          description: WiFi channel (1-11 for 2.4GHz)
          minimum: 1
          maximum: 14
          example: 6
      required:
        - ssid
        - password
        - channel

    ConnectedDevice:
      type: object
      description: Device connected to the hotspot
      properties:
        name:
          type: string
          description: Device hostname
          example: "iPhone-12"
        type:
          type: string
          description: Detected device type
          enum:
            - mobile
            - tablet
            - laptop
            - desktop
            - unknown
          example: "mobile"
        mac:
          type: string
          description: Device MAC address
          pattern: '^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$'
          example: "aa:bb:cc:11:22:33"
        ip:
          type: string
          description: Assigned IP address
          pattern: '^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$'
          example: "192.168.1.100"
      required:
        - name
        - type
        - mac
        - ip

    SystemStatus:
      type: object
      description: Overall system status
      properties:
        connected:
          type: boolean
          description: Whether router is connected to upstream WiFi
          example: true
        connectedSSID:
          type: string
          description: SSID of connected upstream network (empty if not connected)
          example: "Hotel-Guest"
        hotspotEnabled:
          type: boolean
          description: Whether the hotspot is currently enabled
          example: true
        connectedCount:
          type: integer
          description: Number of devices connected to hotspot
          minimum: 0
          example: 3
        dataUsage:
          type: number
          format: double
          description: Total data usage in MB (placeholder for future implementation)
          example: 145.7
        uptime:
          type: integer
          format: int64
          description: System uptime in seconds
          example: 3600
        connectedDevices:
          type: array
          description: List of devices connected to hotspot
          items:
            $ref: '#/components/schemas/ConnectedDevice'
      required:
        - connected
        - connectedSSID
        - hotspotEnabled
        - connectedCount
        - dataUsage
        - uptime
        - connectedDevices

    LogEntry:
      type: object
      description: System log entry
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the log entry was created
          example: "2025-10-28T14:32:10Z"
        source:
          type: string
          description: Log source component
          enum:
            - Système
            - WiFi
            - Hotspot
          example: "WiFi"
        message:
          type: string
          description: Log message
          example: "Scan terminé - 5 réseaux trouvés"
      required:
        - timestamp
        - source
        - message

    SuccessResponse:
      type: object
      description: Generic success response
      properties:
        status:
          type: string
          enum:
            - success
          example: "success"
      required:
        - status

    Error:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: Error message
          example: "Erreur lors du scan WiFi"
      required:
        - error