// 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.maps.navconnect.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/field_info.proto";
import "google/api/resource.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "google/type/latlng.proto";

option go_package = "cloud.google.com/go/maps/navconnect/apiv1/navconnectpb;navconnectpb";
option java_multiple_files = true;
option java_outer_classname = "NavConnectServiceProto";
option java_package = "com.google.maps.navconnect.v1";

// Service for NavConnect clients to create and get trips.
service NavConnectService {
  option (google.api.default_host) = "navigationconnect.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Creates a trip. This must be called before the mobile application can start
  // the trip. The returned trip will have the `auth_token` field set.
  rpc CreateTrip(CreateTripRequest) returns (Trip) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*}/trips"
      body: "trip"
    };
    option (google.api.method_signature) = "parent,trip,trip_id";
  }

  // Gets a trip.
  rpc GetTrip(GetTripRequest) returns (Trip) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/trips/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// A trip.
message Trip {
  option (google.api.resource) = {
    type: "navconnect.googleapis.com/Trip"
    pattern: "projects/{project}/trips/{trip}"
    plural: "trips"
    singular: "trip"
  };

  // All possible trip states.
  enum State {
    // The trip state is unspecified.
    STATE_UNSPECIFIED = 0;

    // The trip was created but has not yet started.
    NEW = 1;

    // The transporter is enroute to the destination.
    ENROUTE = 2;

    // The transporter arrived at the destination.
    ARRIVED = 3;

    // The trip was suspended.
    SUSPENDED = 4;

    // The trip failed to complete successfully.
    FAILED = 5;

    // The trip failed due to a client error.
    CLIENT_ERROR = 6;
  }

  // Output only. Identifier. The resource name of the trip.
  // Format: projects/{project_number}/trips/{trip_id}.
  string name = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = IDENTIFIER
  ];

  // Immutable. The configuration for the trip.
  TripConfig config = 7 [(google.api.field_behavior) = IMMUTABLE];

  // Input only. Immutable. The Android application ID of the mobile application
  // that will use the trip. At least one of `android_app_id` or `ios_app_id`
  // must be set.
  string android_app_id = 8 [
    (google.api.field_behavior) = INPUT_ONLY,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Input only. Immutable. The iOS bundle ID of the mobile application that
  // will use the trip. At least one of `android_app_id` or `ios_app_id` must be
  // set.
  string ios_app_id = 9 [
    (google.api.field_behavior) = INPUT_ONLY,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Output only. An opaque token that authorizes access to begin a NavConnect
  // trip in Google Maps or Waze and grants these applications access to update
  // the trip. Only returned by `CreateTrip`.
  AuthToken auth_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The Trip state.
  State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The latest data about the execution of the trip. This may not
  // be set if the trip is in an error state.
  TripExecution execution = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time according to the server when the trip was created.
  google.protobuf.Timestamp create_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time at which the server received the latest trip update.
  google.protobuf.Timestamp update_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Configuration for the trip.
message TripConfig {
  // Optional. Whether to enable high frequency trip updates.
  //
  // NOTE: Enabling this feature logs the trip under Enterprise Tier usage, and
  // is subject to Enterprise Tier rates.
  bool enable_high_frequency_updates = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Whether to enable pubsub notifications for the trip.
  bool enable_pubsub = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. If set, only the specified subset of the Trip fields will be
  // included in the pubsub notifications.
  //
  // If not set, all Trip fields will be included in the pubsub notifications
  // (default behavior).
  //
  // The following fields are not supported:
  //
  // * `android_app_id`
  // * `ios_app_id`
  // * `auth_token`
  // * `config`
  //
  // NOTE: This field is ignored if `enable_pubsub` is false.
  google.protobuf.FieldMask pubsub_field_mask = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// An authentication token.
message AuthToken {
  // Output only. The authentication token that should be passed to the mobile
  // application.
  string token = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time at which the authentication token will expire.
  google.protobuf.Timestamp expire_time = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Data about the execution of the trip.
message TripExecution {
  // Output only. Origin of the trip which is generally the transporter's
  // location at start of the NavConnect trip.
  Location origin = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The destination of the trip as reported by the mobile
  // application.
  Stop destination = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The location signal representing the last known location of
  // the transporter. This will be the road snapped location if available.
  Location location = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time traveled thus far.
  google.protobuf.Duration traveled_duration = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Time left on this trip as estimated by Google.
  google.protobuf.Duration remaining_duration = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Distance traveled from the origin in meters.
  optional int32 traveled_distance_meters = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Distance remaining to the destination in meters.
  optional int32 remaining_distance_meters = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Indicates whether a stop was added along the route.
  optional bool stop_added_in_route = 8
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A stop in the trip where some task is to be performed.
message Stop {
  // Required. The location of the stop as a lat/lng.
  google.type.LatLng point = 1 [(google.api.field_behavior) = REQUIRED];
}

// A location as reported by the mobile application.
message Location {
  // Output only. The location lat/lng.
  google.type.LatLng point = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time when the location was sourced as denoted by the
  // client.
  google.protobuf.Timestamp source_time = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time at which the server received this location update.
  google.protobuf.Timestamp server_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request message for NavConnectService.CreateTrip.
message CreateTripRequest {
  // Required. The parent resource under which this trip will be created.
  // Format: projects/{project_number}
  string parent = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The ID to use for the trip, which will become the final component
  // of the trip's resource name.
  //
  // This value must be a valid RFC-4122 UUID.
  string trip_id = 2 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = REQUIRED
  ];

  // Required. The trip to create.
  Trip trip = 3 [(google.api.field_behavior) = REQUIRED];
}

// Request message for NavConnectService.GetTrip.
message GetTripRequest {
  // Required. The resource name of the trip to get.
  // Format: projects/{project}/trips/{trip_id}
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "navconnect.googleapis.com/Trip" }
  ];
}