openapi: 3.0.3
info:
  title: NovaTrek Weather Service
  description: |
    Integrates with on-site weather stations and third-party providers to deliver
    real-time conditions, multi-day forecasts, severe weather alerts, and trail condition
    assessments for NovaTrek Adventures regions.
  version: 1.0.0
  contact:
    name: NovaTrek Platform Team
    email: platform@novatrek.example.com

servers:
  - url: https://api.novatrek.example.com/weather/v1
    description: Production
  - url: https://api-staging.novatrek.example.com/weather/v1
    description: Staging

security:
  - bearerAuth: []

tags:
  - name: Weather
    description: Current conditions and forecasts
  - name: Alerts
    description: Severe weather alert management
  - name: Trail Conditions
    description: Trail-specific condition reports

paths:
  /weather/current:
    get:
      operationId: getCurrentWeather
      summary: Get current weather conditions
      description: Returns the latest weather data from the specified station, typically updated every 15 minutes.
      tags: [Weather]
      parameters:
        - name: station_id
          in: query
          required: true
          description: Weather station identifier
          schema:
            type: string
            example: "WS-ROCKYMTN-014"
      responses:
        '200':
          description: Current weather data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentWeatherResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /weather/forecast:
    get:
      operationId: getWeatherForecast
      summary: Get weather forecast
      description: Returns a multi-day forecast for the area covered by the specified weather station. Maximum 10-day lookahead.
      tags: [Weather]
      parameters:
        - name: station_id
          in: query
          required: true
          description: Weather station identifier
          schema:
            type: string
        - name: days
          in: query
          description: Number of forecast days (1-10)
          schema:
            type: integer
            minimum: 1
            maximum: 10
            default: 3
      responses:
        '200':
          description: Multi-day forecast
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForecastResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /weather/alerts:
    get:
      operationId: getWeatherAlerts
      summary: Get active weather alerts for a region
      description: |
        Returns all active weather alerts for the specified region.
        Region identifiers correspond to regions defined in svc-trip-catalog.
      tags: [Alerts]
      parameters:
        - name: region_id
          in: query
          required: true
          description: Region identifier (cross-ref svc-trip-catalog)
          schema:
            type: string
            format: uuid
        - name: severity
          in: query
          description: Filter by minimum severity level
          schema:
            $ref: '#/components/schemas/AlertSeverity'
      responses:
        '200':
          description: List of active alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'

    post:
      operationId: createWeatherAlert
      summary: Create a weather alert (internal)
      description: |
        Internal endpoint used by automated monitoring systems or operations staff
        to publish a weather alert for a region.
      tags: [Alerts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlertRequest'
      responses:
        '201':
          description: Alert created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherAlert'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /trail-conditions:
    get:
      operationId: getTrailConditions
      summary: Get current trail conditions
      description: |
        Returns real-time condition data for the specified trail, combining weather station
        readings with ranger reports. Trail identifiers correspond to svc-trail-management.
      tags: [Trail Conditions]
      parameters:
        - name: trail_id
          in: query
          required: true
          description: Trail identifier (cross-ref svc-trail-management)
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Trail condition report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrailCondition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    WeatherData:
      type: object
      description: Core weather observation data
      properties:
        temperature_c:
          type: number
          format: double
          description: Temperature in Celsius
          example: 18.5
        feels_like_c:
          type: number
          format: double
          example: 16.2
        humidity_percent:
          type: number
          format: double
          minimum: 0
          maximum: 100
          example: 65.0
        wind_speed_kmh:
          type: number
          format: double
          example: 22.4
        wind_direction_deg:
          type: integer
          minimum: 0
          maximum: 360
          example: 225
        precipitation_mm:
          type: number
          format: double
          description: Precipitation in the last hour
          example: 0.0
        uv_index:
          type: integer
          minimum: 0
          maximum: 11
          example: 7
        visibility_km:
          type: number
          format: double
          example: 15.0
        pressure_hpa:
          type: number
          format: double
          example: 1013.25
        cloud_cover_percent:
          type: integer
          minimum: 0
          maximum: 100
          example: 40

    CurrentWeatherResponse:
      type: object
      properties:
        station_id:
          type: string
          example: "WS-ROCKYMTN-014"
        station_name:
          type: string
          example: "Rocky Mountain Base Camp Station"
        observed_at:
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/WeatherData'
        condition_summary:
          type: string
          description: Human-readable summary
          example: "Partly cloudy with moderate winds"

    Forecast:
      type: object
      properties:
        date:
          type: string
          format: date
        high_c:
          type: number
          format: double
          example: 24.0
        low_c:
          type: number
          format: double
          example: 12.0
        precipitation_probability:
          type: number
          format: double
          minimum: 0
          maximum: 1
          example: 0.15
        condition:
          type: string
          enum: [CLEAR, PARTLY_CLOUDY, CLOUDY, RAIN, HEAVY_RAIN, SNOW, THUNDERSTORM, FOG]
        wind_speed_kmh:
          type: number
          format: double
        uv_index:
          type: integer
        sunrise:
          type: string
          format: time
        sunset:
          type: string
          format: time

    ForecastResponse:
      type: object
      properties:
        station_id:
          type: string
        generated_at:
          type: string
          format: date-time
        forecasts:
          type: array
          items:
            $ref: '#/components/schemas/Forecast'

    AlertType:
      type: string
      enum:
        - SEVERE_STORM
        - FLASH_FLOOD
        - HIGH_WIND
        - EXTREME_HEAT
        - EXTREME_COLD
        - AVALANCHE_WARNING
        - WILDFIRE

    AlertSeverity:
      type: string
      enum: [ADVISORY, WATCH, WARNING, EMERGENCY]

    CreateAlertRequest:
      type: object
      required: [region_id, alert_type, severity, title, description, effective_from]
      properties:
        region_id:
          type: string
          format: uuid
          description: Affected region (cross-ref svc-trip-catalog)
        alert_type:
          $ref: '#/components/schemas/AlertType'
        severity:
          $ref: '#/components/schemas/AlertSeverity'
        title:
          type: string
          maxLength: 200
          example: "Flash Flood Warning - Cascade Valley"
        description:
          type: string
          maxLength: 2000
        effective_from:
          type: string
          format: date-time
        effective_until:
          type: string
          format: date-time
        affected_trail_ids:
          type: array
          items:
            type: string
            format: uuid
          description: Specific trails affected (cross-ref svc-trail-management)

    WeatherAlert:
      type: object
      properties:
        id:
          type: string
          format: uuid
        region_id:
          type: string
          format: uuid
        alert_type:
          $ref: '#/components/schemas/AlertType'
        severity:
          $ref: '#/components/schemas/AlertSeverity'
        title:
          type: string
        description:
          type: string
        effective_from:
          type: string
          format: date-time
        effective_until:
          type: string
          format: date-time
        affected_trail_ids:
          type: array
          items:
            type: string
            format: uuid
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time

    AlertListResponse:
      type: object
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/WeatherAlert'
        total_count:
          type: integer

    TrailCondition:
      type: object
      properties:
        trail_id:
          type: string
          format: uuid
          description: Trail identifier (cross-ref svc-trail-management)
        trail_name:
          type: string
          example: "Cascade Ridge Loop"
        assessed_at:
          type: string
          format: date-time
        overall_status:
          type: string
          enum: [EXCELLENT, GOOD, FAIR, POOR, HAZARDOUS, IMPASSABLE]
        surface_condition:
          type: string
          enum: [DRY, WET, MUDDY, ICY, SNOW_COVERED, FLOODED]
        water_crossings_passable:
          type: boolean
        recent_weather:
          $ref: '#/components/schemas/WeatherData'
        active_alerts:
          type: array
          items:
            $ref: '#/components/schemas/WeatherAlert'
        ranger_notes:
          type: string
          description: Latest ranger observation notes
          example: "Bridge at mile 3.2 underwater—use alternate ford 200m upstream"

    ErrorResponse:
      type: object
      properties:
        error_code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              issue:
                type: string

  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
