// 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";

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 = "DataSourceProto";
option java_package = "com.google.devicesandservices.health.v4";
option php_namespace = "Google\\DevicesAndServices\\Health\\V4";
option ruby_package = "Google::DevicesAndServices::Health::V4";

// Data Source definition to track the origin of data.
//
// Each health data point, regardless of the complexity or data model (whether a
// simple step count or a detailed sleep session) must retain information about
// its source of origin (e.g. the device or app that collected it).
message DataSource {
  // Captures metadata about the device that recorded the measurement.
  message Device {
    // Form factor of the device, e.g. phone, watch, band, etc.
    enum FormFactor {
      // The form factor is unspecified.
      FORM_FACTOR_UNSPECIFIED = 0;

      // The device is a fitness band.
      FITNESS_BAND = 1;

      // The device is a watch.
      WATCH = 2;

      // The device is a phone.
      PHONE = 3;

      // The device is a ring.
      RING = 4;

      // The device is a chest strap.
      CHEST_STRAP = 5;

      // The device is a scale.
      SCALE = 6;

      // The device is a tablet.
      TABLET = 7;

      // The device is a head mounted device.
      HEAD_MOUNTED = 8;

      // The device is a smart display.
      SMART_DISPLAY = 9;
    }

    // Optional. Captures the form factor of the device.
    FormFactor form_factor = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. An optional manufacturer of the device.
    string manufacturer = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. An optional name for the device.
    string display_name = 3 [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional metadata for the application that provided this data.
  message Application {
    // Output only. A unique identifier for the mobile application
    // that was the source of the data.
    //
    // This is typically the application's package name on Android (e.g.,
    // `com.google.fitbit`) or the bundle ID on iOS. This field is informational
    // and helps trace data origin. This field is system-populated when the data
    // is uploaded from the Fitbit mobile application, Health Connect or Health
    // Kit.
    string package_name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The client ID of the application that recorded the data.
    //
    // This ID is a legacy Fitbit API client ID, which is different from a
    // Google OAuth client ID. Example format: `ABC123`.
    // This field is system-populated and used for tracing data from
    // legacy Fitbit API integrations. This field is system-populated when
    // the data is uploaded from a legacy Fitbit API integration.
    string web_client_id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The Google OAuth 2.0 client ID of the web application or
    // service that recorded the data.
    //
    // This is the client ID used during the Google OAuth
    // flow to obtain user credentials. This field is system-populated when
    // the data is uploaded from Google Web API.
    string google_web_client_id = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The method by which the data was recorded.
  enum RecordingMethod {
    // The recording method is unspecified.
    RECORDING_METHOD_UNSPECIFIED = 0;

    // The data was manually entered by the user.
    MANUAL = 1;

    // The data was passively measured by a device.
    PASSIVELY_MEASURED = 2;

    // The data was derived from other data, e.g., by an algorithm in the
    // backend.
    DERIVED = 3;

    // The data was actively measured by a device.
    ACTIVELY_MEASURED = 4;

    // The recording method is unknown. This is set when the data is uploaded
    // from a third party app that does not provide this information.
    UNKNOWN = 5;
  }

  // The platform that uploaded the data.
  // Additional values may be added in the future. Clients should be prepared to
  // handle unknown values gracefully.
  enum Platform {
    // The platform is unspecified.
    PLATFORM_UNSPECIFIED = 0;

    // The data was uploaded from Fitbit.
    FITBIT = 1;

    // The data was uploaded from Health Connect.
    HEALTH_CONNECT = 2;

    // The data was uploaded from Health Kit.
    HEALTH_KIT = 3;

    // The data was uploaded from Google Fit.
    FIT = 4;

    // The data was uploaded from Fitbit legacy Web API.
    FITBIT_WEB_API = 5;

    // The data was uploaded from Nest devices.
    NEST = 6;

    // The data was uploaded from Google Health API.
    GOOGLE_WEB_API = 7;

    // The data was uploaded from Google Partner Integrations.
    GOOGLE_PARTNER_INTEGRATION = 8;
  }

  // Optional. Captures how the data was recorded.
  RecordingMethod recording_method = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Captures metadata for raw data points originating from devices.
  // We expect this data source to be used for data points written on
  // device sync.
  Device device = 2 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Captures metadata for the application that provided this data.
  Application application = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Captures the platform that uploaded the data.
  Platform platform = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}