syntax = "proto3";

package ext.maps.booking.partner.v2;

import "google/protobuf/duration.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
  // Gets availability information for an appointment slot
  rpc CheckAvailability(CheckAvailabilityRequest)
      returns (CheckAvailabilityResponse) {
  }

  // Creates a new lease
  rpc CreateLease(CreateLeaseRequest) returns (CreateLeaseResponse) {
  }

  // Creates a booking
  rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {
  }

  // Updates an existing booking
  rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {
  }

  // Gets status for an existing booking
  rpc GetBookingStatus(GetBookingStatusRequest)
      returns (GetBookingStatusResponse) {
  }

  // Lists all bookings for a user
  rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {
  }
}

// An inventory slot
message Slot {
  // ID of the merchant for the slot
  string merchant_id = 1;

  // ID of the merchant service
  string service_id = 2;

  // Start time of the appointment slot
  google.protobuf.Timestamp start_time = 3;

  // Duration of the appointment slot
  google.protobuf.Duration duration = 4;

  // Opaque tag that identifies the availability slot and matches the value
  // provided in the availability feed
  string availability_tag = 5;

  // The set of resources that disambiguates the appointment slot, e.g. by
  // indicating the staff member and room selected by the user
  Resources resources = 6;

  reserved 7;
}

// Temporary lease for an inventory slot
message Lease {
  // ID of the lease.
  // Not populated in CreateLeaseRequest. The value is chosen by the partner and
  // has to be returned in the response of CreateLease.
  string lease_id = 1;

  // The appointment slot that the lease is created for.
  Slot slot = 2;

  // Unique identifier for this lease, chosen by Reserve with Google. Serves as
  // an idempotency token for [ext.maps.booking.partner.v2.CreateLease]
  // requests.
  string user_reference = 3;

  // Expiration time of the lease
  google.protobuf.Timestamp lease_expiration_time = 4;
}

// Reference to a [ext.maps.booking.partner.v2.Lease] that has been created via
// [ext.maps.booking.partner.v2.CreateLease]
message LeaseReference {
  // Lease ID
  string lease_id = 1;
}

// A booking for an inventory slot
message Booking {
  // ID of this booking
  string booking_id = 1;

  // The appointment slot of this booking
  Slot slot = 2;

  // Personal information of the user making the appointment
  UserInformation user_information = 3;

  // Status of the booking
  BookingStatus status = 4;

  // Information about payment transactions that relate to the booking.
  PaymentInformation payment_information = 5;
}

// Personal information about the person making a booking
message UserInformation {
  // Unique ID of the user to the partner, chosen by Reserve with Google.
  string user_id = 1;

  // Given name of the user
  string given_name = 2;

  // Family name of the user
  string family_name = 3;

  // Address of the user (optional)
  PostalAddress address = 4;

  // Phone number of the user (optional)
  string telephone = 5;

  // Email address of the user
  string email = 6;
}

// Postal address for a user
message PostalAddress {
  // The country, e.g. "USA".
  string address_country = 1;
  // The locality, e.g. "Mountain View".
  string address_locality = 2;
  // The region, e.g. "CA".
  string address_region = 3;
  // The post office box number, e.g. "3112", optional.
  string post_office_box_number = 4;
  // The postal code, e.g. "94043".
  string postal_code = 5;
  // The street address, e.g. "1600 Amphitheatre Pkwy".
  string street_address = 6;
}

// Parameters to specify how the partner will process payment for a given
// booking.
//
// A sample request:
//   processor: PROCESSOR_STRIPE
//   payment_method_token: "pk_live_12345abcdef"
//   version: "2017-06-15"
message PaymentProcessingParameters {
  enum PaymentProcessor {
    PAYMENT_PROCESSOR_UNSPECIFIED = 0;
    PROCESSOR_STRIPE = 1;
    PROCESSOR_BRAINTREE = 2;
  }
  PaymentProcessor processor = 1;

  // The token representing the payment method that will be used to pay
  // for this booking. This token can be only used once. This token can be
  // only used for the merchant associated with this booking.
  //
  // Each processor may choose its own format for this field.
  // Stripe uses "pk_live_1234abc..." for live keys and "pk_test_1234abc..."
  // for test keys.
  string payment_method_token = 2;

  // The payment processor API version that the given payment token is valid
  // for.
  //
  // Each processor may choose its own format for this field.
  // Stripe uses a date (e.g. "2017-06-15").
  string version = 3;
}

message Price {
  // The price in micro-units of the currency.
  // Fractions of smallest currency unit will be rounded using nearest even
  // rounding. (e.g. For USD 2.5 cents rounded to 2 cents, 3.5 cents rounded to
  // 4 cents, 0.5 cents rounded to 0 cents, 2.51 cents rounded to 3 cents).
  int64 price_micros = 1;
  // The currency of the price that is defined in ISO 4217.
  string currency_code = 2;
}

enum PaymentOptionType {
  PAYMENT_OPTION_TYPE_UNSPECIFIED = 0;
  PAYMENT_OPTION_SINGLE_USE = 1;
  PAYMENT_OPTION_MULTI_USE = 2;
  PAYMENT_OPTION_UNLIMITED_USE = 3;
}

// This describes a payment option, such as a pack, membership, or
// single-session pass after it has been purchased by a user. It includes an
// identifier for the user payment option, as well as some information about
// the payment option with which it is associated.
message UserPaymentOption {
  // A unique identifier for the user payment option. This Id MUST be unique
  // for all UserPaymentOptions across all merchants and users.
  string user_payment_option_id = 1;
  // The user payment option will be valid (usable) between start_time and
  // end_time. Attempts to use a user payment option to make a booking outside
  // of this interval  will fail.
  google.protobuf.Timestamp valid_start_time = 2;
  google.protobuf.Timestamp valid_end_time = 3;
  // The type of the payment option associated with this user payment option.
  // This can be unlimited for a membership or subscription, multi-use for a
  // pack, or single-use.
  PaymentOptionType type = 4;
  // The original number of uses for this user payment option when it was
  // purchased. This value is ignored for unlimited payment options.
  int32 original_count = 5;
  // The number of uses remaining for this user payment option. If this number
  // is 0 for a pack, attempts to use this payment option to make a booking will
  // fail.
  int32 current_count = 6;
  // The id of the payment option that has been used to purchase this user
  // payment option.
  string payment_option_id = 7;
}

// Payment details that are sent when creating a new booking.
message PaymentInformation {
  // Prepayment status of the booking.
  // If the prepayment_status is PREPAYMENT_PROVIDED, then
  // payment_transaction_id contains the associated unique transaction id for
  // the purchase.
  // If the prepayment status is PREPAYMENT_REFUNDED, then
  // payment_transaction_id contains the associated unique transaction id for
  // the refund.
  PrepaymentStatus prepayment_status = 1;

  // Unique identifier for a payment transaction associated with the booking.
  // Empty if not applicable.
  string payment_transaction_id = 2;

  // These fields must match the service price (specified in the Services feed)
  // or the PaymentOption corresponding with this service.
  // They are included in the booking request and response to verify that
  // the price indicated in the feed has not changed since the last feed
  // update.
  //
  // The price of the booking, exclusive of any taxes.
  // Existence of price or taxes does not imply that they have been paid,
  // prepayment_state should be used for that purpose.
  Price price = 3;
  // Taxes that are calculated to be paid for this booking.
  // If this field is absent the price is assumed to be exempt from or already
  // inclusive of applicable taxes.
  Price tax_amount = 4;

  // Who handles payment processing?
  // If payment is processed by the partner, CreateBooking request will
  // include additional parameters (PaymentProcessingParameters) indicating
  // the payment method to be used to process the payment.
  enum PaymentProcessedBy {
    PAYMENT_PROCESSED_BY_UNSPECIFIED = 0;
    PROCESSED_BY_GOOGLE = 1;
    PROCESSED_BY_PARTNER = 2;
  }
  PaymentProcessedBy payment_processed_by = 5;

  // The id of the payment option or user payment option associated with the
  // booking.
  // If a payment option is purchased as part of a booking, payment_option_id
  // will be set with the id of that payment option.
  // If an already purchased user payment option is being used to pay for a
  // booking, user_payment_option_id will be set with the id of that user
  // payment option.
  // When included as part of a response proto, the user_payment_option_id
  // should be set and must match the UserPaymentOption that is returned in the
  // RPC response (e.g. the user_payment_option returned in
  // CreateBookingResponse).
  oneof payment_id {
    // The id of the payment option associated with this booking. If this field
    // is populated, price (and tax_amount, if applicable) must be  populated as
    // well.
    string payment_option_id = 6;

    // The id of the user payment option used to pay for this booking.
    string user_payment_option_id = 7;
  }
}

// Status of a booking.
//
// Updating booking status does not change the status of the associated payment.
// Prepayment status updates should be done using the PrepaymentStatus enum.
//
// nextID: 6
enum BookingStatus {
  // Not specified.
  BOOKING_STATUS_UNSPECIFIED = 0;
  // Booking has been confirmed
  CONFIRMED = 1;
  // Booking is awaiting confirmation by the merchant before it can transition
  // into CONFIRMED status
  PENDING_MERCHANT_CONFIRMATION = 2;
  // Booking has been canceled on behalf of the user.
  // The merchant can still trigger a manual refund.
  CANCELED = 3;
  // User did not show for the appointment
  NO_SHOW = 4;
  // User did not show for the appointment in violation of the cancellation
  // policy.
  NO_SHOW_PENALIZED = 5;
}

// Status data that conveys why (1) creating a lease or (2) creating or updating
// a booking fails.
// BookingFailure is intended to primarily capture business logic errors.
message BookingFailure {
  enum Cause {
    // Default value: Don't use; amounts to an "unknown error"
    CAUSE_UNSPECIFIED = 0;
    // The referenced availability slot is not available any longer.
    SLOT_UNAVAILABLE = 1;
    // The user has already booked an appointment for the referenced
    // availability slot.
    SLOT_ALREADY_BOOKED_BY_USER = 2;
    // The lease (if provided) has expired and cannot be used any longer to
    // complete the requested booking.
    LEASE_EXPIRED = 3;
    // The requested cancellation cannot be performed at the current time due
    // to time restrictions in the merchant's cancellation policy.
    OUTSIDE_CANCELLATION_WINDOW = 4;
    // An error was encountered while processing the payment because the
    // provided credit card type was not accepted by the merchant. The credit
    // card type must be supplied in rejected_card_type.
    PAYMENT_ERROR_CARD_TYPE_REJECTED = 5;
    // An error was encountered while processing the payment because the
    // provided credit card was declined.
    PAYMENT_ERROR_CARD_DECLINED = 6;
    // An error was encountered with the pack/membership used to pay for the
    // booking. There could be no valid uses left, it could have expired, etc.
    PAYMENT_OPTION_NOT_VALID = 7;
    // An error was encountered while processing the payment for this booking.
    // Use this value to indicate a general payment related error, only if the
    // error does not match to a specific payment error above.
    PAYMENT_ERROR = 8;
    // User cannot use the given payment option (e.g. user trying to use a
    // first time price for the second time).
    USER_CANNOT_USE_PAYMENT_OPTION = 9;
    // A booking that the user tried to cancel has already been cancelled.
    BOOKING_ALREADY_CANCELLED = 10;
    // A booking that the user tried to cancel is not cancellable.
    BOOKING_NOT_CANCELLABLE = 11;
  }

  Cause cause = 1;

  // Set if cause is PAYMENT_ERROR_CARD_TYPE_REJECTED to indicate the type of
  // credit card that was rejected.
  enum CreditCardType {
    // Default value. Used if credit card type does not match to one below.
    CREDIT_CARD_TYPE_UNSPECIFIED = 0;
    VISA = 1;
    MASTERCARD = 2;
    AMERICAN_EXPRESS = 3;
    DISCOVER = 4;
  }
  CreditCardType rejected_card_type = 2;

  // This optional field is used for the partner to include additional
  // information for debugging purpose only.
  string description = 3;
}

// Prepayment status of a booking.
// Updating payment status will trigger an update on the payment status of the
// associated booking (if applicable).
// Currently, the only supported transition is from PREPAYMENT_PROVIDED to
// PREPAYMENT_REFUNDED, which will initiate a non-reversible refund on the
// associated payment transaction.
enum PrepaymentStatus {
  // Not specified, defaults to PREPAYMENT_NOT_PROVIDED.
  PREPAYMENT_STATUS_UNSPECIFIED = 0;
  // The fee for the booking has been paid in advance.
  PREPAYMENT_PROVIDED = 1;
  // The fee for the booking has not been paid in advance.
  PREPAYMENT_NOT_PROVIDED = 2;
  // The fee was previously PREPAYMENT_PROVIDED but has now been refunded.
  PREPAYMENT_REFUNDED = 3;
  // The fee was previously PREPAYMENT_PROVIDED but now has been credited
  // (user given a UserPaymentOption as a voucher for the booking).
  // If this is set, the response should also include the updated
  // UserPaymentOption.
  PREPAYMENT_CREDITED = 4;
}

// Resource specification that disambiguates an appointment slot
message Resources {
  // The staff ID as provided in the feed or empty if not applicable or no staff
  // was selected.
  string staff_id = 1;
  // The room ID as provided in the feed or empty if not applicable or no room
  // was selected.
  string room_id = 2;
  // For Dining Reservations only: the number of seats requested in the booking.
  int32 party_size = 3;
}

// Request to check availability for a [ext.maps.booking.partner.v2.Slot]
message CheckAvailabilityRequest {
  // The appointment slot that is being checked
  Slot slot = 1;
}

// Response for the [ext.maps.booking.partner.v2.CheckAvailability] RPC with the
// availability of the appointment slot
message CheckAvailabilityResponse {
  // The requested slot.
  Slot slot = 1;
  // Number of available spots.
  // 0 indicates that the appointment slot is not available.
  int32 count_available = 2;
  // This enum indicates what requirements exist for the user to acknowledge or
  // view the requested slots duration/end time.
  enum DurationRequirement {
    // The handling of the end time is not specified. This is the default.
    DURATION_REQUIREMENT_UNSPECIFIED = 0;

    // The end time is not shown to the user.
    DO_NOT_SHOW_DURATION = 1;

    // The end time has to be shown to the user before an appointment can be
    // made.
    MUST_SHOW_DURATION = 2;
  }
  // Optionally, return the requirement to show the slots duration and/or
  // endtime. This field will be ignored if slot is unavailable.
  DurationRequirement duration_requirement = 3;
}

// Request to create a [ext.maps.booking.partner.v2.Lease] for a slot in the
// inventory.  The expiration time in the returned Lease may be modified by the
// backend, e.g. if the requested lease period is too long.
message CreateLeaseRequest {
  // The lease to be created with information about the appointment slot
  Lease lease = 1;
}

// Response for the [ext.maps.booking.partner.v2.CreateLease] RPC with the
// created [ext.maps.booking.partner.v2.Lease]
message CreateLeaseResponse {
  // The created [ext.maps.booking.partner.v2.Lease]
  Lease lease = 1;

  // If creating a lease fails, this field should reflect the business logic
  // error (e.g., slot has become unavailable) and lease field is expected to be
  // unset.
  BookingFailure booking_failure = 2;
}

// Request to create a [ext.maps.booking.partner.v2.Booking] for an inventory
// slot. Consumes the lease if provided.
message CreateBookingRequest {
  // The inventory slot that is being requested to make this booking.
  // If lease_ref is provided, slot must match the lease; slot is provided for
  // the partner to verify the lease information.
  // If lease_ref is absent, then create the booking for the slot.
  Slot slot = 1;

  // The lease that is being confirmed to make this booking.
  // If lease_ref is provided, then create the booking using the lease.
  LeaseReference lease_ref = 2;

  // Personal information of the user making the appointment
  UserInformation user_information = 3;

  // Information about payments. When payment authorizations are handled by
  // Google, if the booking request does not succeed, payment authorizations are
  // automatically canceled.
  PaymentInformation payment_information = 4;

  // The parameters to be used if the payment is processed by the partner
  // (i.e. payment_information.payment_processed_by is equal to
  // PROCESSED_BY_PARTNER).
  PaymentProcessingParameters payment_processing_parameters = 5;

  // Idempotency token for [ext.maps.booking.partner.v2.CreateBooking] requests.
  string idempotency_token = 6;
}

// Response with the created [ext.maps.booking.partner.v2.Booking] for an
// inventory slot
message CreateBookingResponse {
  // The created booking
  Booking booking = 1;

  // The updated user payment option used in this booking.
  // If a new payment option was purchased to pay for the booking, this should
  // be a newly created user payment option.
  // If an already purchased user payment option was used for this booking,
  // this should reflect an updated version of that user payment option.
  UserPaymentOption user_payment_option = 2;

  // If creating a booking fails, this field should reflect the business logic
  // error (e.g., slot has become unavailable) and all other fields in the
  // CreateBookingResponse message are expected to be unset.
  BookingFailure booking_failure = 3;
}

// Request to update a [ext.maps.booking.partner.v2.Booking]
message UpdateBookingRequest {
  // Field mask of all booking fields to be updated
  google.protobuf.FieldMask update_mask = 1;

  // The booking to be updated
  // The following fields can be set in a booking:
  // - status, to cancel a booking.
  // - start_time and duration in the slot, to reschedule a booking.
  Booking booking = 2;
}

// Response with the updated [ext.maps.booking.partner.v2.Booking]
message UpdateBookingResponse {
  // The updated booking
  Booking booking = 1;

  // The updated user payment option originally used to pay for this booking.
  // This should be set if the UpdateBookingRequest results in a change to
  // the UserPaymentOption.
  // For instance, if the booking is canceled, the UserPaymentOption should
  // reflect an additional credit to the user. In the case of a multi-use
  // payment option, the current_count should be increased by one to
  // allow the user to create another booking with this payment option. In the
  // case of a single-use payment option, a new single-use user payment option
  // should be returned.
  UserPaymentOption user_payment_option = 2;

  // If updating a booking fails, this field should reflect the business logic
  // error (e.g., booking is not cancellable)
  BookingFailure booking_failure = 3;
}

// Request to get booking status and prepayment status for a
// [ext.maps.booking.partner.v2.Booking]
message GetBookingStatusRequest {
  // ID of the existing booking
  string booking_id = 1;
}

// Response for the [ext.maps.booking.partner.v2.GetBookingStatus] RPC with
// booking status and prepayment status
message GetBookingStatusResponse {
  // ID of the booking
  string booking_id = 1;

  // Status of the booking
  BookingStatus booking_status = 2;

  // Prepayment status of the booking
  PrepaymentStatus prepayment_status = 3;
}

// Request to list all bookings for a user
message ListBookingsRequest {
  // ID of the user
  string user_id = 1;
}

// Response for the [ext.maps.booking.partner.v2.ListBookings] RPC with all
// bookings for the requested user
message ListBookingsResponse {
  // All bookings of the user
  repeated Booking bookings = 1;
}