// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.devicesandservices.health.v4;

import "google/api/field_behavior.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/type/date.proto";
import "google/type/timeofday.proto";

option csharp_namespace = "Google.DevicesAndServices.Health.V4";
option go_package = "google.golang.org/genproto/googleapis/devicesandservices/health/apiv4main;healthpb";
option java_multiple_files = true;
option java_outer_classname = "DataCoordinatesProto";
option java_package = "com.google.devicesandservices.health.v4";
option php_namespace = "Google\\DevicesAndServices\\Health\\V4";
option ruby_package = "Google::DevicesAndServices::Health::V4";

// Civil time representation similar to
// [google.type.DateTime][google.type.DateTime], but ensures that neither the
// timezone nor the UTC offset can be set to avoid confusion between civil and
// physical time queries.
message CivilDateTime {
  // Required. Calendar date.
  google.type.Date date = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Time of day. Defaults to the start of the day, at midnight if
  // omitted.
  google.type.TimeOfDay time = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Counterpart of [google.type.Interval][google.type.Interval], but using
// [CivilDateTime][google.devicesandservices.health.v4.CivilDateTime].
message CivilTimeInterval {
  // Required. The inclusive start of the range.
  CivilDateTime start = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The exclusive end of the range.
  CivilDateTime end = 2 [(google.api.field_behavior) = REQUIRED];
}

// Represents a time interval of an observed data point.
message ObservationTimeInterval {
  // Required. Observed interval start time.
  google.protobuf.Timestamp start_time = 1
      [(google.api.field_behavior) = REQUIRED];

  // Required. The offset of the user's local time at the start of the
  // observation relative to the Coordinated Universal Time (UTC).
  google.protobuf.Duration start_utc_offset = 2
      [(google.api.field_behavior) = REQUIRED];

  // Required. Observed interval end time.
  google.protobuf.Timestamp end_time = 3
      [(google.api.field_behavior) = REQUIRED];

  // Required. The offset of the user's local time at the end of the observation
  // relative to the Coordinated Universal Time (UTC).
  google.protobuf.Duration end_utc_offset = 4
      [(google.api.field_behavior) = REQUIRED];

  // Output only. Observed interval start time in civil time in the timezone the
  // subject is in at the start of the observed interval
  CivilDateTime civil_start_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Observed interval end time in civil time in the timezone the
  // subject is in at the end of the observed interval
  CivilDateTime civil_end_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Represents a time interval of session data point, which bundles multiple
// observed metrics together.
message SessionTimeInterval {
  // Required. The start time of the observed session.
  google.protobuf.Timestamp start_time = 1
      [(google.api.field_behavior) = REQUIRED];

  // Required. The offset of the user's local time at the start of the session
  // relative to the Coordinated Universal Time (UTC).
  google.protobuf.Duration start_utc_offset = 2
      [(google.api.field_behavior) = REQUIRED];

  // Required. The end time of the observed session.
  google.protobuf.Timestamp end_time = 3
      [(google.api.field_behavior) = REQUIRED];

  // Required. The offset of the user's local time at the end of the session
  // relative to the Coordinated Universal Time (UTC).
  google.protobuf.Duration end_utc_offset = 4
      [(google.api.field_behavior) = REQUIRED];

  // Output only. Session start time in civil time in the timezone the subject
  // is in at the start of the session.
  CivilDateTime civil_start_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Session end time in civil time in the timezone the subject is
  // in at the end of the session.
  CivilDateTime civil_end_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Represents a sample time of an observed data point.
message ObservationSampleTime {
  // Required. The time of the observation.
  google.protobuf.Timestamp physical_time = 1
      [(google.api.field_behavior) = REQUIRED];

  // Required. The offset of the user's local time during the observation
  // relative to the Coordinated Universal Time (UTC).
  google.protobuf.Duration utc_offset = 2
      [(google.api.field_behavior) = REQUIRED];

  // Output only. The civil time in the timezone the subject is in
  // at the time of the observation.
  CivilDateTime civil_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}