// Copyright 2025 MOIA GmbH

syntax = "proto3";

package moia.trip.customer.v1;

option go_package = "./customerv1";
option java_multiple_files = false;
option java_outer_classname = "CustomerServiceV1";
option java_package = "io.moia.protos.trip.customer.v1";

// The customer service to manage customers.
service CustomerService {
  // Get a customer by ID.
  //
  // Fails with `NOT_FOUND` with the reason `CUSTOMER_NOT_FOUND` if the customer does not exist.
  rpc GetCustomer(GetCustomerRequest) returns (GetCustomerResponse);
  // List customers.
  //
  // 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 ListCustomers(ListCustomersRequest) returns (ListCustomersResponse);
  // Create a customer.
  //
  // Fails with `INVALID_ARGUMENT` with the following reasons:
  // * `INVALID_PHONE_NUMBER` if the provided phone number is invalid.
  // * `INVALID_GIVEN_NAME` if the provided given name is longer than 100 characters.
  // * `INVALID_FAMILY_NAME` if the provided family name is longer than 100 characters.
  // * `INVALID_NAME` if neither a given name nor family name is provided.
  // * `INVALID_LANGUAGE_CODE` if the provided language code is unknown or invalid.
  // * `INVALID_EMAIL_ADDRESS` if the provided email address is longer than 250 characters or is invalid.
  rpc CreateCustomer(CreateCustomerRequest) returns (CreateCustomerResponse);
  // Updates a customer.
  //
  // Fails with `NOT_FOUND` with the reason `CUSTOMER_NOT_FOUND` if the customer does not exist.
  //
  // Fails with `INVALID_ARGUMENT` with the following reasons:
  // * `INVALID_PHONE_NUMBER` if the provided phone number is invalid.
  // * `INVALID_GIVEN_NAME` if the provided given name is longer than 100 characters.
  // * `INVALID_FAMILY_NAME` if the provided family name is longer than 100 characters.
  // * `INVALID_NAME` if neither a given name or family name is provided.
  // * `INVALID_LANGUAGE_CODE` if the provided language code is unknown or invalid.
  // * `INVALID_EMAIL_ADDRESS` if the provided email address is longer than 250 characters or is invalid.
  rpc UpdateCustomer(UpdateCustomerRequest) returns (UpdateCustomerResponse);
  // Deletes a customer.
  //
  // Fails with `NOT_FOUND` with the reason `CUSTOMER_NOT_FOUND` if the customer does not exist.
  rpc DeleteCustomer(DeleteCustomerRequest) returns (DeleteCustomerResponse);
  // List customer flags.
  //
  // Fails with `NOT_FOUND` with the reason `CUSTOMER_NOT_FOUND` if the customer does not exist.
  //
  // 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 ListCustomerFlags(ListCustomerFlagsRequest) returns (ListCustomerFlagsResponse);
  // Adds a customer flag.
  // Succeeds if the flag already exists.
  // Flags may be configured with your service configuration manager.
  //
  // Fails with `NOT_FOUND` with the reason `CUSTOMER_NOT_FOUND` if the customer does not exist.
  //
  // Fails with `INVALID_ARGUMENT` with the reason `INVALID_FLAG` if the provided flag is not available or read-only.
  rpc AddCustomerFlag(AddCustomerFlagRequest) returns (AddCustomerFlagResponse);
  // Removes a customer flag.
  // Succeeds if the flag does not exist.
  //
  // Fails with `NOT_FOUND` with the reason `CUSTOMER_NOT_FOUND` if the customer does not exist.
  rpc RemoveCustomerFlag(RemoveCustomerFlagRequest) returns (RemoveCustomerFlagResponse);
}

// The request to get a customer by ID.
message GetCustomerRequest {
  // The ID of the customer.
  string id = 1;
}

// The response containing the requested customer.
message GetCustomerResponse {
  // The customer with the given ID.
  Customer customer = 1;
}

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

// The response containing the customers.
message ListCustomersResponse {
  // The customers.
  repeated Customer customers = 1;
  // 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 = 2;
}

// The request to create a customer.
message CreateCustomerRequest {
  // The customer's e-mail address.
  // The email address is expected to be confirmed before.
  // Used by customer support to contact the customer.
  // The maximum allowed length is 250 characters.
  string email_address = 1;
  // The customer's phone number.
  // The phone number is expected to be confirmed before.
  // Used by customer support to contact the customer.
  // The phone number must follow the [E.164](https://en.wikipedia.org/wiki/E.164) format.
  // For example '+4930726219941'.
  string phone_number = 2;
  // The customer's given name.
  // The maximum allowed length is 100 characters.
  // Empty strings are allowed. If empty, the family name must not be empty.
  string given_name = 3;
  // The customer's family name.
  // The maximum allowed length is 100 characters.
  // Empty strings are allowed. If empty, the given name must not be empty.
  string family_name = 4;
  // The customer's preferred language.
  // The language code needs to follow the [IETF BCP-47](https://en.wikipedia.org/wiki/IETF_language_tag) format.
  // For example 'en' or 'de'.
  string language_code = 5;
}

// The response containing the created customer.
message CreateCustomerResponse {
  // The created customer.
  Customer customer = 1;
}

// The request to update a customer.
message UpdateCustomerRequest {
  // The updated customer.
  Customer customer = 1;
}

// The response containing the updated customer.
message UpdateCustomerResponse {
  // The updated customer.
  Customer customer = 1;
}

// The request to delete a customer.
message DeleteCustomerRequest {
  // The ID of the customer to delete.
  string id = 1;
}

// The response indicating the customer was deleted.
message DeleteCustomerResponse {}

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

// The response to list the flags for a customer.
message ListCustomerFlagsResponse {
  // The active flags for the customer.
  repeated string flags = 1;
  // 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 = 2;
}

// The request to add a flag to a customer.
message AddCustomerFlagRequest {
  // The ID of the customer.
  string customer_id = 1;
  // The flag to add.
  string flag = 2;
}

// The response indicating a flag was added to a customer.
message AddCustomerFlagResponse {}

// The request to remove a flag from a customer.
message RemoveCustomerFlagRequest {
  // The ID of the customer.
  string customer_id = 1;
  // The flag to remove.
  string flag = 2;
}

// The response indicating a flag was removed from a customer.
message RemoveCustomerFlagResponse {}

// A customer.
message Customer {
  // The ID of the customer.
  string id = 1;
  // The customer's e-mail address.
  // The email address is expected to be confirmed before.
  // Used by customer support to contact the customer.
  // The maximum allowed length is 250 characters.
  string email_address = 2;
  // The customer's phone number.
  // The phone number is expected to be confirmed before.
  // Used by customer support to contact the customer.
  // The phone number must follow the [E.164](https://en.wikipedia.org/wiki/E.164) format.
  // For example '+4930726219941'.
  string phone_number = 3;
  // The customer's given name.
  // The maximum allowed length is 100 characters.
  // Empty strings are allowed. If empty, the family name must not be empty.
  string given_name = 4;
  // The customer's family name.
  // The maximum allowed length is 100 characters.
  // Empty strings are allowed. If empty, the given name must not be empty.
  string family_name = 5;
  // The customer's preferred language.
  // The language code needs to follow the [IETF BCP-47](https://en.wikipedia.org/wiki/IETF_language_tag) format.
  string language_code = 6;
}