lap.rb

# frozen_string_literal: true

module Strava
  module Models
    #
    # Represents a lap within an activity.
    #
    # Laps are splits within an activity, either created manually by the athlete
    # or auto-generated by the recording device. Each lap contains metrics like
    # distance, time, speed, and elevation for that specific segment of the activity.
    #
    # Includes helper mixins for formatting distance, time, and elevation.
    #
    # @example List activity laps
    #   laps = client.activity_laps(1234567890)
    #   laps.each_with_index do |lap, i|
    #     puts "Lap #{i+1}: #{lap.name}"
    #     puts "Distance: #{lap.distance_s}"
    #     puts "Time: #{lap.moving_time_in_hours_s}"
    #     puts "Elevation: #{lap.total_elevation_gain_s}"
    #   end
    #
    # @see https://developers.strava.com/docs/reference/#api-models-Lap
    #
    class Lap < Strava::Models::Response
      # @return [Integer] Lap ID
      property 'id'

      # @return [MetaActivity] The activity this lap belongs to
      property 'activity', transform_with: ->(v) { Strava::Models::MetaActivity.new(v) }

      # @return [MetaAthlete] The athlete who recorded this lap
      property 'athlete', transform_with: ->(v) { Strava::Models::MetaAthlete.new(v) }

      # @return [Float, nil] Average cadence (RPM for cycling, steps/minute for running)
      property 'average_cadence'

      # @return [Float] Average speed in meters per second
      property 'average_speed'

      include Mixins::Distance
      include Mixins::MovingTime
      include Mixins::ElapsedTime

      # @return [Integer] Starting index in the activity's data stream
      property 'start_index'

      # @return [Integer] Ending index in the activity's data stream
      property 'end_index'

      # @return [Integer] The lap number (1-indexed)
      property 'lap_index'

      # @return [Float] Maximum speed in meters per second
      property 'max_speed'

      # @return [String] Lap name (e.g., 'Lap 1', 'Manual Lap')
      property 'name'

      # @return [Integer, nil] Pace zone indicator
      property 'pace_zone'

      # @return [Integer, nil] Split number within the lap
      property 'split'

      # @return [Time] Start date and time (UTC)
      property 'start_date', transform_with: ->(v) { Time.parse(v) }

      include Mixins::StartDateLocal
      include Mixins::TotalElevationGain

      # @note Undocumented in official API
      # @return [Integer, nil] Resource state indicator
      property 'resource_state'

      # @note Undocumented in official API
      # @return [Boolean, nil] Whether the watts are from a power meter (true) or estimated (false)
      property 'device_watts'

      # @note Undocumented in official API
      # @return [Float, nil] Average power in watts
      property 'average_watts'

      # @note Undocumented in official API
      # @return [Float, nil] Average heart rate in beats per minute
      property 'average_heartrate'

      # @note Undocumented in official API
      # @return [Float, nil] Maximum heart rate in beats per minute
      property 'max_heartrate'
    end
  end
end