// Copyright 2025 MOIA GmbH

syntax = "proto3";

package moia.trip.refund.v1;

import "moia/type/v1/money.proto";

option go_package = "./refundv1";
option java_multiple_files = false;
option java_outer_classname = "RefundServiceV1";
option java_package = "io.moia.protos.trip.refund.v1";

// The refund service provides functionality for refunds.
service RefundService {
  // Gets a refund by ID.
  //
  // Fails with `NOT_FOUND` with the reason `REFUND_NOT_FOUND` if there is no refund for the requested ID.
  rpc GetRefund(GetRefundRequest) returns (GetRefundResponse);
  // Lists refunds.
  //
  // 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 ListRefunds(ListRefundsRequest) returns (ListRefundsResponse);
}

// The request to get a refund.
message GetRefundRequest {
  // The ID of the refund.
  string refund_id = 1;
}

// The response containing the requested refund.
message GetRefundResponse {
  // The refund with the given ID.
  Refund refund = 1;
}

// Request to list refunds.
message ListRefundsRequest {
  // The ID of the customer for whom to list all refunds.
  // Optional: If not specified, all refunds of all customers are listed.
  // Only leave this out if you really need all refunds of all customers because the list might easily become very long.
  optional string customer_id = 1;
  // The maximum number of refunds to return.
  // The service may return fewer than this value.
  // If unspecified or set to zero, at most 25 refunds 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 `ListRefundsRequest` call.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListRefundsRequest` must match
  // the call that provided the page token.
  optional string page_token = 3;
}

// Response to list refunds.
message ListRefundsResponse {
  // The list of refunds, ordered by date from newest to oldest.
  repeated Refund refunds = 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;
}

// A refund.
message Refund {
  // The ID of the refund.
  string id = 1;
  // The ID of the customer who requested the refund.
  string customer_id = 2;
  // The ID of the trip for which the refund was requested.
  string trip_id = 3;
  // The gross amount to be refunded to the customer.
  // This is equal to the original price of the trip.
  // Must be greater than zero.
  moia.type.v1.Money refund = 4;
}