@stuartshay/otel-graphql-types 1.0.94 → 1.0.445

package/schema.graphql

@@ -122,6 +122,10 @@ type Location {
   UTC timestamp when the record was inserted into the database
   """
   created_at: String
+  """
+  Short formatted address from reverse geocoding
+  """
+  display_address: String
 }
 
 """
@@ -188,10 +192,175 @@ type LocationDetail {
   Original OwnTracks JSON payload as received from the MQTT broker
   """
   raw_payload: JSON
+  """
+  Full reverse-geocoded address components from Pelias
+  """
+  address: GeocodedAddress
 }
 
 scalar JSON
 
+# -------------------------------------------------------
+# Geocoding
+# -------------------------------------------------------
+"""
+Reverse-geocoded address components from Pelias.
+"""
+type GeocodedAddress {
+  """
+  Full formatted address label from Pelias
+  """
+  display_address: String
+  """
+  Street name
+  """
+  street: String
+  """
+  House or building number
+  """
+  housenumber: String
+  """
+  Neighbourhood name
+  """
+  neighbourhood: String
+  """
+  City or town
+  """
+  locality: String
+  """
+  State or province
+  """
+  region: String
+  """
+  Country name
+  """
+  country: String
+  """
+  Postal or ZIP code
+  """
+  postalcode: String
+  """
+  Pelias confidence score (0-1)
+  """
+  confidence: Float
+  """
+  Geocoding status: success, no_coverage, error, pending
+  """
+  status: String!
+  """
+  UTC timestamp when geocoding was performed
+  """
+  geocoded_at: String
+}
+
+"""
+Coverage statistics for geocoded location records.
+"""
+type GeocodingStatus {
+  """
+  Total number of OwnTracks location records
+  """
+  total_locations: Int!
+  """
+  Number of locations with a geocoded address (any status)
+  """
+  geocoded: Int!
+  """
+  Number of successfully geocoded locations
+  """
+  success: Int!
+  """
+  Number of locations awaiting geocoding
+  """
+  pending: Int!
+  """
+  Number of locations outside Pelias coverage area
+  """
+  no_coverage: Int!
+  """
+  Number of locations that failed geocoding
+  """
+  errors: Int!
+  """
+  Percentage of locations with a geocoded address
+  """
+  coverage_percent: Float!
+  """
+  Per-source breakdown of geocoding coverage (owntracks, garmin)
+  """
+  by_source: GeocodingStatusBySource!
+}
+
+"""
+Coverage statistics for a single geocoding source (owntracks or garmin).
+"""
+type GeocodingSourceStatus {
+  """
+  Number of successfully geocoded records for this source
+  """
+  success: Int!
+  """
+  Number of records awaiting geocoding for this source
+  """
+  pending: Int!
+  """
+  Number of records outside Pelias coverage area
+  """
+  no_coverage: Int!
+  """
+  Number of records that failed geocoding
+  """
+  errors: Int!
+  """
+  Total number of geocoded_addresses rows for this source
+  """
+  total: Int!
+}
+
+"""
+Per-source breakdown of geocoding coverage.
+"""
+type GeocodingStatusBySource {
+  """
+  Coverage stats for OwnTracks rows
+  """
+  owntracks: GeocodingSourceStatus!
+  """
+  Coverage stats for Garmin rows
+  """
+  garmin: GeocodingSourceStatus!
+  """
+  Total number of Garmin activities (denominator for activity-level coverage)
+  """
+  garmin_activities_total: Int!
+  """
+  Number of Garmin activities that have at least one address row
+  """
+  garmin_activities_geocoded: Int!
+  """
+  Percentage of Garmin activities with at least one geocoded address
+  """
+  garmin_coverage_percent: Float!
+}
+
+"""
+Result of triggering a batch geocoding operation.
+"""
+type GeocodingTriggerResult {
+  """
+  Number of records processed in this batch
+  """
+  processed: Int!
+  """
+  Number of records still awaiting geocoding
+  """
+  remaining: Int!
+  """
+  Number of records skipped via proximity deduplication
+  """
+  skipped_dedup: Int!
+}
+
 """
 Paginated list of OwnTracks location records.
 """
@@ -242,9 +411,49 @@ type LocationCount {
   device_id: String
 }
 
+"""
+Earliest and latest timestamps in the locations table.
+"""
+type LocationDateRange {
+  """
+  Earliest location timestamp (ISO 8601)
+  """
+  min_date: DateTime!
+  """
+  Latest location timestamp (ISO 8601)
+  """
+  max_date: DateTime!
+}
+
 # -------------------------------------------------------
 # Garmin
 # -------------------------------------------------------
+"""
+Recording device metadata captured from a Garmin activity's FIT file.
+"""
+type GarminDevice {
+  """
+  Recording device serial number
+  """
+  device_id: Float
+  """
+  Device manufacturer (e.g. garmin)
+  """
+  manufacturer: String
+  """
+  Raw Garmin product enum id from the FIT file (e.g. 4061)
+  """
+  garmin_product: Int
+  """
+  Friendly device model name (e.g. Edge 540 Solar)
+  """
+  model: String
+  """
+  Device firmware/software version (e.g. 31.30)
+  """
+  software_version: String
+}
+
 """
 Summary of a Garmin Connect activity parsed from a FIT file.
 """
@@ -286,6 +495,62 @@ type GarminActivity {
   """
   max_heart_rate: Int
   """
+  Whether this activity has usable heart-rate data in summary or track points
+  """
+  hr_available: Boolean!
+  """
+  Minimum heart rate in beats per minute
+  """
+  min_heart_rate: Int
+  """
+  Aerobic training effect score
+  """
+  aerobic_training_effect: Float
+  """
+  Anaerobic training effect score
+  """
+  anaerobic_training_effect: Float
+  """
+  Exercise load score
+  """
+  exercise_load: Int
+  """
+  Average respiration rate in breaths per minute
+  """
+  avg_respiration_rate: Int
+  """
+  Minimum respiration rate in breaths per minute
+  """
+  min_respiration_rate: Int
+  """
+  Maximum respiration rate in breaths per minute
+  """
+  max_respiration_rate: Int
+  """
+  Estimated sweat loss in millilitres
+  """
+  sweat_loss_ml: Int
+  """
+  Moderate intensity minutes
+  """
+  moderate_intensity_minutes: Int
+  """
+  Vigorous intensity minutes
+  """
+  vigorous_intensity_minutes: Int
+  """
+  Total intensity minutes
+  """
+  total_intensity_minutes: Int
+  """
+  Distance over paved surfaces in kilometres
+  """
+  paved_distance_km: Float
+  """
+  Distance over unpaved surfaces in kilometres
+  """
+  unpaved_distance_km: Float
+  """
   Average cadence in RPM
   """
   avg_cadence: Int
@@ -294,6 +559,10 @@ type GarminActivity {
   """
   max_cadence: Int
   """
+  Total activity strokes
+  """
+  total_strokes: Int
+  """
   Total calories burned
   """
   calories: Int
@@ -326,6 +595,10 @@ type GarminActivity {
   """
   device_manufacturer: String
   """
+  Recording device metadata (manufacturer, model, firmware)
+  """
+  device: GarminDevice
+  """
   Average ambient temperature in degrees C
   """
   avg_temperature_c: Int
@@ -381,6 +654,248 @@ type GarminActivityConnection {
   offset: Int!
 }
 
+"""
+Earliest and latest timestamps in the Garmin activities table.
+"""
+type GarminDateRange {
+  """
+  Earliest Garmin activity timestamp (ISO 8601)
+  """
+  min_date: DateTime!
+  """
+  Latest Garmin activity timestamp (ISO 8601)
+  """
+  max_date: DateTime!
+}
+
+"""
+Garmin-native ClimbPro typed split for an activity.
+"""
+type GarminActivityClimb {
+  """
+  Unique climb row identifier
+  """
+  id: Float!
+  """
+  Parent Garmin activity identifier
+  """
+  activity_id: String!
+  """
+  Zero-based Garmin typed split order
+  """
+  source_split_index: Int!
+  """
+  Garmin message index
+  """
+  message_index: Int
+  """
+  Garmin split type label when provided
+  """
+  split_type: String
+  """
+  Garmin ClimbPro typed split type
+  """
+  climb_type: String
+  """
+  UTC climb start time
+  """
+  start_time: String
+  """
+  UTC climb end time
+  """
+  end_time: String
+  """
+  Local climb start time from Garmin
+  """
+  start_time_local: String
+  """
+  Climb duration in seconds
+  """
+  duration_seconds: Float
+  """
+  Elapsed climb duration in seconds
+  """
+  elapsed_duration_seconds: Float
+  """
+  Moving climb duration in seconds
+  """
+  moving_duration_seconds: Float
+  """
+  Climb distance in meters
+  """
+  distance_meters: Float
+  """
+  Climb elevation gain in meters
+  """
+  elevation_gain_meters: Float
+  """
+  Climb elevation loss in meters
+  """
+  elevation_loss_meters: Float
+  """
+  Climb start elevation in meters
+  """
+  start_elevation_meters: Float
+  """
+  Average climb grade percent
+  """
+  average_grade_percent: Float
+  """
+  Maximum climb grade percent
+  """
+  max_grade_percent: Float
+  """
+  Average speed in meters per second
+  """
+  average_speed_mps: Float
+  """
+  Average moving speed in meters per second
+  """
+  average_moving_speed_mps: Float
+  """
+  Maximum speed in meters per second
+  """
+  max_speed_mps: Float
+  """
+  Average vertical speed in meters per second
+  """
+  average_vertical_speed_mps: Float
+  """
+  Average elapsed vertical speed in meters per second
+  """
+  average_elapsed_vertical_speed_mps: Float
+  """
+  Climb start latitude
+  """
+  start_latitude: Float
+  """
+  Climb start longitude
+  """
+  start_longitude: Float
+  """
+  Climb end latitude
+  """
+  end_latitude: Float
+  """
+  Climb end longitude
+  """
+  end_longitude: Float
+  """
+  Garmin ClimbPro difficulty
+  """
+  climb_pro_difficulty: String
+  """
+  Calories recorded for this climb
+  """
+  calories: Float
+  """
+  BMR calories recorded for this climb
+  """
+  bmr_calories: Float
+  """
+  Average temperature in degrees C
+  """
+  average_temperature_c: Float
+  """
+  Minimum temperature in degrees C
+  """
+  min_temperature_c: Float
+  """
+  Maximum temperature in degrees C
+  """
+  max_temperature_c: Float
+  """
+  UTC timestamp when the row was inserted
+  """
+  created_at: String
+  """
+  UTC timestamp when the row was last updated
+  """
+  updated_at: String
+}
+
+"""
+Garmin-native or derived activity lap row.
+"""
+type GarminActivityLap {
+  """
+  Unique lap row identifier
+  """
+  id: Float!
+  """
+  Parent Garmin activity identifier
+  """
+  activity_id: String!
+  """
+  One-based lap order within the activity
+  """
+  lap_index: Int!
+  """
+  UTC lap start time
+  """
+  start_time: String
+  """
+  UTC lap end time
+  """
+  end_time: String
+  """
+  Lap timer duration in seconds
+  """
+  duration_seconds: Float
+  """
+  Lap elapsed duration in seconds
+  """
+  elapsed_duration_seconds: Float
+  """
+  Lap moving duration in seconds
+  """
+  moving_duration_seconds: Float
+  """
+  Lap distance in meters
+  """
+  distance_meters: Float
+  """
+  Lap paved distance in meters
+  """
+  paved_distance_meters: Float
+  """
+  Lap unpaved distance in meters
+  """
+  unpaved_distance_meters: Float
+  """
+  Average lap speed in meters per second
+  """
+  avg_speed_mps: Float
+  """
+  Average lap heart rate in bpm
+  """
+  avg_heart_rate: Int
+  """
+  Maximum lap heart rate in bpm
+  """
+  max_heart_rate: Int
+  """
+  Lap elevation gain in meters
+  """
+  total_ascent_meters: Float
+  """
+  Lap elevation loss in meters
+  """
+  total_descent_meters: Float
+  """
+  Calories recorded for this lap
+  """
+  calories: Float
+  """
+  UTC timestamp when the row was inserted
+  """
+  created_at: String
+  """
+  UTC timestamp when the row was last updated
+  """
+  updated_at: String
+}
+
 """
 Individual GPS track point within a Garmin activity.
 """
@@ -422,6 +937,14 @@ type GarminTrackPoint {
   """
   heart_rate: Int
   """
+  Heart-rate zone index (1-5)
+  """
+  hr_zone: Int
+  """
+  Respiration rate in breaths per minute
+  """
+  respiration_rate: Int
+  """
   Pedal/step cadence in RPM
   """
   cadence: Int
@@ -430,9 +953,149 @@ type GarminTrackPoint {
   """
   temperature_c: Float
   """
+  Road or terrain type
+  """
+  surface_type: String
+  """
+  Effort classification label
+  """
+  effort_level: String
+  """
   UTC timestamp when the record was inserted
   """
   created_at: String
+  """
+  Compact reverse-geocoded address summary, when geocoded
+  """
+  address: GeocodedAddressSummary
+}
+
+"""
+Compact reverse-geocoded address summary embedded in track-point payloads.
+"""
+type GeocodedAddressSummary {
+  """
+  Full formatted address label from Pelias
+  """
+  display_address: String
+  """
+  Street name
+  """
+  street: String
+  """
+  House or building number
+  """
+  housenumber: String
+  """
+  Neighbourhood name
+  """
+  neighbourhood: String
+  """
+  City or town
+  """
+  locality: String
+  """
+  State or province
+  """
+  region: String
+  """
+  Country name
+  """
+  country: String
+  """
+  Postal or ZIP code
+  """
+  postalcode: String
+  """
+  Pelias confidence score (0-1)
+  """
+  confidence: Float
+  """
+  Role of this waypoint within a Garmin activity (start, end, waypoint). Null for OwnTracks records.
+  """
+  waypoint_kind: String
+  """
+  Geocoding status: success, no_coverage, error, pending
+  """
+  status: String!
+  """
+  UTC timestamp when geocoding was performed
+  """
+  geocoded_at: String
+}
+
+"""
+Full reverse-geocoded address attached to a Garmin activity waypoint.
+"""
+type GarminActivityAddress {
+  """
+  garmin_track_points.id this address was geocoded from
+  """
+  track_point_id: Int!
+  """
+  Parent Garmin activity identifier
+  """
+  activity_id: String!
+  """
+  Role of this waypoint within the activity: start, end, or waypoint
+  """
+  waypoint_kind: String!
+  """
+  UTC timestamp of the track point this address was derived from
+  """
+  timestamp: DateTime!
+  """
+  GPS latitude in decimal degrees (WGS 84)
+  """
+  latitude: Float!
+  """
+  GPS longitude in decimal degrees (WGS 84)
+  """
+  longitude: Float!
+  """
+  Full formatted address label from Pelias
+  """
+  display_address: String
+  """
+  Street name
+  """
+  street: String
+  """
+  House or building number
+  """
+  housenumber: String
+  """
+  Neighbourhood name
+  """
+  neighbourhood: String
+  """
+  City or town
+  """
+  locality: String
+  """
+  State or province
+  """
+  region: String
+  """
+  Country name
+  """
+  country: String
+  """
+  Postal or ZIP code
+  """
+  postalcode: String
+  """
+  Pelias confidence score (0-1)
+  """
+  confidence: Float
+  """
+  Geocoding status: success, no_coverage, error, pending
+  """
+  status: String!
+  """
+  UTC timestamp when geocoding was performed
+  """
+  geocoded_at: String
 }
 
 """
@@ -471,6 +1134,20 @@ type SportInfo {
   activity_count: Int!
 }
 
+"""
+Garmin activity count grouped by recording device model.
+"""
+type GarminDeviceCount {
+  """
+  Device model label, or Manual when an activity has no recording device.
+  """
+  label: String!
+  """
+  Number of activities for this device label.
+  """
+  activity_count: Int!
+}
+
 """
 Lightweight track point optimised for time-series chart rendering.
 """
@@ -496,6 +1173,14 @@ type GarminChartPoint {
   """
   heart_rate: Int
   """
+  Heart-rate zone index (1-5)
+  """
+  hr_zone: Int
+  """
+  Respiration rate in breaths per minute
+  """
+  respiration_rate: Int
+  """
   Pedal/step cadence in RPM
   """
   cadence: Int
@@ -513,6 +1198,36 @@ type GarminChartPoint {
   longitude: Float!
 }
 
+"""
+Aggregated Garmin activity totals for a single time bucket (week, month, or year).
+"""
+type GarminActivityTotal {
+  """
+  Start date of the period bucket (DATE_TRUNC of week/month/year)
+  """
+  period_start: String!
+  """
+  Number of activities in the period
+  """
+  activity_count: Int!
+  """
+  Sum of distance in kilometres
+  """
+  total_distance_km: Float
+  """
+  Sum of active duration in seconds (excludes pauses)
+  """
+  total_duration_seconds: Int
+  """
+  Sum of elevation gain in meters
+  """
+  total_ascent_m: Int
+  """
+  Sum of calories burned
+  """
+  total_calories: Int
+}
+
 # -------------------------------------------------------
 # Unified GPS
 # -------------------------------------------------------
@@ -638,6 +1353,42 @@ type DailyActivitySummary {
   total_calories: Int
 }
 
+"""
+Paginated list of daily activity summaries.
+"""
+type DailySummaryConnection {
+  """
+  List of daily activity summary items in the current page
+  """
+  items: [DailyActivitySummary!]!
+  """
+  Total number of items matching the query
+  """
+  total: Int!
+  """
+  Maximum number of items per page
+  """
+  limit: Int!
+  """
+  Number of items skipped from the start
+  """
+  offset: Int!
+}
+
+"""
+Earliest and latest activity dates available in the daily activity summary view.
+"""
+type DailySummaryDateRange {
+  """
+  Earliest activity date with daily summary data (YYYY-MM-DD)
+  """
+  min_date: String!
+  """
+  Latest activity date with daily summary data (YYYY-MM-DD)
+  """
+  max_date: String!
+}
+
 # -------------------------------------------------------
 # Reference Locations
 # -------------------------------------------------------
@@ -893,7 +1644,17 @@ type Query {
     device_id: String
   ): LocationCount!
 
+  """
+  Get the earliest and latest location timestamps.
+  """
+  locationDateRange: LocationDateRange!
+
   # Garmin
+  """
+  Get the earliest and latest Garmin activity timestamps.
+  """
+  garminDateRange: GarminDateRange!
+
   """
   Retrieve a paginated list of Garmin activities.
   """
@@ -973,6 +1734,11 @@ type Query {
   """
   garminSports: [SportInfo!]!
 
+  """
+  List Garmin recording device labels with activity counts.
+  """
+  garminDeviceCounts: [GarminDeviceCount!]!
+
   """
   Retrieve chart-optimised track points for a Garmin activity.
   """
@@ -983,6 +1749,58 @@ type Query {
     activity_id: String!
   ): [GarminChartPoint!]!
 
+  """
+  Retrieve Garmin-native ClimbPro typed splits for a Garmin activity.
+  """
+  garminActivityClimbs(
+    """
+    Garmin Connect activity identifier
+    """
+    activity_id: String!
+  ): [GarminActivityClimb!]!
+
+  """
+  Retrieve Garmin-native or derived laps for a Garmin activity.
+  """
+  garminActivityLaps(
+    """
+    Garmin Connect activity identifier
+    """
+    activity_id: String!
+  ): [GarminActivityLap!]!
+
+  """
+  Retrieve all reverse-geocoded addresses for a Garmin activity (start, mid-route waypoints, and end).
+  """
+  garminActivityAddresses(
+    """
+    Garmin Connect activity identifier
+    """
+    activity_id: String!
+  ): [GarminActivityAddress!]!
+
+  """
+  Aggregate Garmin activity totals grouped by week, month, or year.
+  """
+  garminActivityTotals(
+    """
+    Aggregation period: 'week', 'month', or 'year'
+    """
+    period: String!
+    """
+    Filter by sport (e.g. cycling, running)
+    """
+    sport: String
+    """
+    Inclusive lower bound on activity start time (YYYY-MM-DD)
+    """
+    date_from: String
+    """
+    Inclusive upper bound on activity start time (YYYY-MM-DD)
+    """
+    date_to: String
+  ): [GarminActivityTotal!]!
+
   # Unified GPS
   """
   Retrieve a paginated list of unified GPS points from all sources.
@@ -1012,6 +1830,14 @@ type Query {
     Sort direction
     """
     order: SortOrder
+    """
+    Exclude stationary points where speed is zero
+    """
+    exclude_stationary: Boolean
+    """
+    Remove points with duplicate coordinates (rounded to ~11m precision)
+    """
+    deduplicate: Boolean
   ): UnifiedGpsConnection!
 
   """
@@ -1027,10 +1853,19 @@ type Query {
     """
     date_to: String
     """
-    Maximum number of days to return
+    Maximum number of days to return per page
     """
     limit: Int
-  ): [DailyActivitySummary!]!
+    """
+    Number of items to skip for pagination
+    """
+    offset: Int
+  ): DailySummaryConnection!
+
+  """
+  Get the earliest and latest activity dates available in the daily activity summary view.
+  """
+  dailySummaryDateRange: DailySummaryDateRange!
 
   # Reference Locations
   """
@@ -1113,6 +1948,12 @@ type Query {
     """
     limit: Int
   ): WithinReferenceResult!
+
+  # Geocoding
+  """
+  Get geocoding coverage statistics.
+  """
+  geocodingStatus: GeocodingStatus!
 }
 
 # -------------------------------------------------------
@@ -1132,4 +1973,18 @@ type Mutation {
     """
     lookback: Int
   ): GarminSyncTriggerResult!
+
+  """
+  Trigger batch reverse-geocoding of un-geocoded location records.
+  """
+  triggerGeocoding(
+    """
+    Number of locations to geocode in this batch (default 100)
+    """
+    batch_size: Int
+    """
+    Re-process previously failed location records (for example, those with status `no_coverage`)
+    """
+    retry_failed: Boolean
+  ): GeocodingTriggerResult!
 }