// Copyright 2025 MOIA GmbH

syntax = "proto3";

package moia.trip.servicearea.v1;

import "google/protobuf/timestamp.proto";
import "moia/type/v1/latlon.proto";
import "moia/type/v1/time_interval.proto";

option go_package = "./serviceareav1";
option java_multiple_files = false;
option java_outer_classname = "ServiceAreaServiceV1";
option java_package = "io.moia.protos.trip.servicearea.v1";

// This ServiceAreaService provides methods to query service areas.
service ServiceAreaService {
  // Get service area by ID.
  //
  // Fails with `NOT_FOUND` with the reason `SERVICE_AREA_NOT_FOUND` if the service area does not exist.
  rpc GetServiceArea(GetServiceAreaRequest) returns (GetServiceAreaResponse);
  // List service areas, paginated.
  // Returns an empty list if none are found.
  //
  // Fails with `INVALID_ARGUMENT` with the following reasons:
  // * `INVALID_PAGE_SIZE` if the `page_size` is less than zero.
  // * `INVALID_PAGE_TOKEN` if the `page_token` does not match previous requests.
  rpc ListServiceAreas(ListServiceAreasRequest) returns (ListServiceAreasResponse);
  // List service hours for a service area.
  //
  // Fails with `INVALID_ARGUMENT` with the following reasons:
  // * `INVALID_PAGE_SIZE` if the `page_size` is less than zero.
  // * `INVALID_PAGE_TOKEN` if the `page_token` does not match previous requests.
  rpc ListServiceHours(ListServiceHoursRequest) returns (ListServiceHoursResponse);
}

// The request to get a service area by ID.
message GetServiceAreaRequest {
  // The ID of the service area.
  string id = 1;
}

// The response containing the requested service area.
message GetServiceAreaResponse {
  // The service area with the given ID.
  ServiceArea service_area = 1;
}

// The request to list service areas.
message ListServiceAreasRequest {
  // The maximum number of service areas to return.
  // The service may return fewer than this value.
  // If unspecified or set to zero, at most 5 service areas will be returned.
  // The maximum value is 100; values above 100 will be coerced to 100.
  // Negative values won't be accepted.
  optional int32 page_size = 1;
  // A page token, received from a previous `ListServiceAreasRequest` call.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListServiceAreasRequest` must match
  // the call that provided the page token.
  optional string page_token = 2;
}

// The response containing service areas.
message ListServiceAreasResponse {
  // List of service areas.
  repeated ServiceArea service_areas = 1;
  // A token, which can be sent as `page_token` in the next request to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  optional string next_page_token = 2;
}

// The request to list a service area's service hours.
message ListServiceHoursRequest {
  // The ID of the service area.
  string service_area_id = 1;
  // The maximum number of service hours to return.
  // The service may return fewer than this value.
  // If unspecified or set to zero, at most 25 service hours will be returned.
  // The maximum value is 100; values above 100 will be coerced to 100.
  // Negative values won't be accepted.
  optional int32 page_size = 2;
  // A page token, received from a previous `ListServiceHoursResponse`.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListServiceHoursRequest` must match
  // the call that provided the page token.
  optional string page_token = 3;
}

// The list of a service area's service hours.
message ListServiceHoursResponse {
  // The time intervals in which ridepooling in this service area is in service.
  // The time intervals are ordered chronologically from the current time to the future.
  repeated moia.type.v1.TimeInterval service_hour_intervals = 1;
  // The ID of the service area.
  string service_area_id = 2;
  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  optional string next_page_token = 3;
}

// A service area is an area in the physical world where a ridepooling service is in operation.
message ServiceArea {
  // Unique name of the service area.
  string name = 1;
  // ID of the service area.
  string id = 2;
  // Polygon with a list of locations delineating the exact boundaries of the service area.
  repeated moia.type.v1.LatLon polygon = 3;
  // Time zone ID in IANA Time Zone codes e.g. Europe/Berlin.
  string time_zone = 4;
  // ISO 3166-1 alpha-2 country code of the country this service area is located in.
  string country = 5;
  // Service area creation date.
  google.protobuf.Timestamp create_time = 6;
  // Service area last modified date.
  google.protobuf.Timestamp modify_time = 7;
}