syntax = "proto3";

package maps.booking.feeds;

message FeedMetadata {
  enum ProcessingInstruction {
    // By default we will assume that this feed is an incremental feed.
    PROCESS_UNKNOWN = 0;

    // This Feed message is one shard of a complete feed. Anything previously
    // supplied by this partner will be deleted; the contents of this feed
    // represent the entire state of the world.
    PROCESS_AS_COMPLETE = 1;

    // This Feed message is one shard of an incremental feed. Existing entities
    // will be left untouched except as modified in this feed.
    PROCESS_AS_INCREMENTAL = 2;
  }

  // Instructs us how to process the feed: either as a shard of a complete feed,
  // or as a shard of an incremental update.
  ProcessingInstruction processing_instruction = 1;

  // The current shard and total number of shards for this feed.
  //
  // Shard number is assumed to be zero-based.
  //
  // There does not need to be any relationship to the file name.
  //
  // Shards do not need to be transferred in order, and they may not be
  // processed in order.
  int32 shard_number = 2;
  int32 total_shards = 3;

  // An identifier that must be consistent across all shards in a feed.
  // This value must be globally unique across each feed type.
  //
  // This value ensures that complete feeds spanning multiple shards are
  // processed together correctly.
  //
  // Clients only need to set this value when the processing_instruction is set
  // to PROCESS_AS_COMPLETE and the feed spans multiple shards (defined by
  // total_shards).
  //
  // Feeds that span multiple shards must set this nonce to the same value.
  uint64 nonce = 5;

  // The timestamp at which this feed shard was generated.
  //
  // In Unix time format (seconds since the epoch).
  int64 generation_timestamp = 4;
}

message AvailabilityFeed {
  FeedMetadata metadata = 1;
  repeated ServiceAvailability service_availability = 2;
}

message ServiceAvailability {
  // If provided, we will consider the Availability entities provided to be a
  // complete snapshot from [start_timestamp_restrict, end_timestamp_restrict).
  // That is, all existing availability will be deleted if the following
  // condition holds true:
  //
  //    start_timestamp_restrict <= Availability.start_sec &&
  //    Availability.start_sec < end_timestamp_restrict
  //
  // If a resource_restrict message is set, the condition is further restricted:
  //
  //    Availability.resource.staff_id == resource_restrict.staff_id &&
  //    Availability.resource.room_id == resource_restrict.room_id
  //
  // These fields are typically used to provide a complete update of
  // availability in a given time range.
  //
  // Setting start_timestamp_restrict while leaving end_timestamp_restrict unset
  // is interpreted to mean all time beginning at start_timestamp_restrict.
  //
  // Setting end_timestamp_restrict while leaving start_timestamp_restrict unset
  // is interpreted to mean all time up to the end_timestamp_restrict.
  //
  // In Unix time format (seconds since the epoch).
  int64 start_timestamp_restrict = 1;
  int64 end_timestamp_restrict = 2;

  // If provided, the timestamp restricts will be applied only to the given
  // merchant or service.
  //
  // These fields are typically used to provide complete snapshot of
  // availability in a given range (defined above) for a specific merchant or
  // service.
  //
  // Leaving these fields unset, or setting these to the empty string or null,
  // is interpreted to mean that no restrict is intended.
  string merchant_id_restrict = 3;
  string service_id_restrict = 4;

  // Setting resources_restrict further restricts the scope of the update to
  // just this set of resources. All id fields of the resources must match
  // exactly.
  Resources resources_restrict = 6;

  repeated Availability availability = 5;
}

// An availability of the merchant's service, indicating time and number
// of spots.
// The availability feed should be a list of this message.
// Please note that it's up to the partner to call out all the possible
// availabilities.
// If a massage therapist is available 9am-12pm, and they provide
// one-hour massage sessions, the aggregator should provide the feed as
//   availability {start_sec: 9am, duration: 60 minutes, ...}
//   availability {start_sec: 10am, duration: 60 minutes, ...}
//   availability {start_sec: 11am, duration: 60 minutes, ...}
// instead of
//   availability {start_sec: 9am, duration: 180 minutes, ...}
//
message Availability {
  // An opaque string from an aggregator to identify a merchant.
  string merchant_id = 1;
  // An opaque string from aggregator to identify a service of the
  // merchant.
  string service_id = 2;
  // Start time of this availability, using epoch time in seconds.
  int64 start_sec = 3;
  // Duration of the service in seconds, e.g. 30 minutes for a chair massage.
  int64 duration_sec = 4;
  // Number of total spots and open spots of this availability.
  // E.g. a Yoga class of 10 spots with 3 booked.
  //   availability {spots_total: 10, spots_open: 7 ...}
  // E.g. a chair massage session which was already booked.
  //   availability {spots_total: 1, spots_open: 0 ...}
  //
  // Note: If sending requests using the availability compression format defined
  //       below, these two fields will be inferred. A Recurrence
  //       implies spots_total=1 and spots_open=1. A ScheduleException implies
  //       spots_total=1 and spots_open=0.
  int64 spots_total = 5;
  int64 spots_open = 6;
  // An optional opaque string to identify this availability slot. If set, it
  // will be included in the requests that book/update/cancel appointments.
  string availability_tag = 7;

  // Optional resources used to disambiguate this availability slot from
  // others when different staff, room, or party_size values are part
  // of the service.
  //
  // E.g. the same Yoga class with two 2 instructors.
  //  availability { resources { staff_id: "1" staff_name: "Amy" }
  //                 spots_total: 10 spots_open: 7 }
  //  availability { resources { staff_id: "2" staff_name: "John" }
  //                 spots_total: 5 spots_open: 2 }
  Resources resources = 8;

  // A list of ids referencing the payment options which can be used to pay
  // for this slot. The actual payment options are defined at the Merchant
  // level, and can also be shared among multiple Merchants.
  //
  // This field overrides any payment_option_ids specified in the service
  // message. Similarly payment_option_ids specified here do NOT have to be
  // present in the service message, though must be defined at the
  // Merchant level.
  repeated string payment_option_id = 9;

  // Recurrence messages are optional, but allow for a more compact
  // representation of consistently repeating availability slots. They typically
  // represent a day's working schedule.
  // ScheduleException messages are then used to represent booked/unavailable
  // time ranges within the work day.
  //
  // Requirements:
  //   1. The expansion of availability slots or recurrences must NOT create
  //      identical slots. If the ids, start_sec, duration_sec, and resources
  //      match, slots are considered identical.
  //   2. Do NOT mix the standard availability format and recurrence within the
  //      slots of a single service. Recurrence benefits merchants/services that
  //      offer appointments. The standard format is geared towards
  //      merchants/services with regularly scheduled classes.
  message Recurrence {
    // The inclusive maximum UTC timestamp the availability repeats until.
    int64 repeat_until_sec = 1;
    // Defines the time between successive availability slots.
    //
    // E.g. An availability with a duration of 20 min, a repeat_every_sec of
    // 30 min, a start_sec of 9:00am, and a repeat_until_sec of 11:00am will
    // yield slots at 9-9:20am, 9:30-9:50am, 10-10:20am, 10:30-10:50am,
    // 11-11:20am.
    int32 repeat_every_sec = 2;
  }
  // The recurrence information for the availability, representing more than one
  // start time. A recurrence should contain appointments for one working day.
  Recurrence recurrence = 10;

  // ScheduleException messages are used to represent booked/unavailable time
  // ranges within the work day. As time slots are booked, the list of
  // exceptions should grow to reflect the newly unavailable time ranges.
  // The recurrence itself shouldn't be modified.
  message ScheduleException {
    // The time range of the exception.
    TimeRange time_range = 1;
  }
  // When this service cannot be scheduled. To limit the number of
  // schedule_exception messages consider joining adjacent exceptions.
  repeated ScheduleException schedule_exception = 11;
}

// A resource is used to disambiguate availability slots from one another when
// different staff, room or party_size values are part of the service.
// Multiple slots for the same service and time interval can co-exist when they
// have different resources.
message Resources {
  // Optional id for a staff member providing the service. This field identifies
  // the staff member across all merchants, services, and availability records.
  // It also needs to be stable over time to allow correlation with past
  // bookings.
  // This field must be present if staff_name is present.
  string staff_id = 1;

  // Optional name of a staff member providing the service. This field will be
  // displayed to users making a booking, and should be human readable, as
  // opposed to an opaque identifier.
  // This field must be present if staff_id is present.
  string staff_name = 2;

  // An optional id for the room the service is located in. This field
  // identifies the room across all merchants, services, and availability
  // records. It also needs to be stable over time to allow correlation with
  // past bookings.
  // This field must be present if room_name is present.
  string room_id = 3;

  // An optional name for the room the service is located in. This
  // field will be displayed to users making a booking, and should be human
  // readable, as opposed to an opaque identifier.
  // This field must be present if room_id is present.
  string room_name = 4;

  // Applicable only for Dining: The party size which can be accommodated
  // during this time slot. A restaurant can be associated with multiple Slots
  // for the same time, each specifying a different party_size, if for instance
  // 2, 3, or 4 people can be seated with a reservation.
  int32 party_size = 5;
}

message TimeRange {
  int64 begin_sec = 1;
  int64 end_sec = 2;
}

message ServiceFeed {
  FeedMetadata metadata = 1;
  repeated Service service = 2;
}

// The definition of a service provided by a merchant.
message Service {
  // An opaque string from an aggregator partner which uniquely identifies a
  // merchant. (required)
  string merchant_id = 1;
  // An opaque string from an aggregator partner which uniquely identifies the
  // service. (required)
  string service_id = 2;
  // The name of the service, suitable for display to users, e.g. "Men's
  // haircut". (required)
  string name = 3;
  // The description of the service, suitable for display to users.
  //
  // This field now supports both plain text and HTML-like formatting rules to
  // display structural contents to end-users. Unlike plain text sections,
  // customized layouts can be created here using headings, paragraphs, lists
  // and some phrase tags. Please read the following instructions and notes
  // carefully to create better user-experience.
  //
  // Supported HTML-like formatting tags:
  //
  // Heading tags: <h1>, <h2>, <h3>, <h4>, <h5>, <h6>
  //   Heading tags can be used to display titles and sub-titles. For example,
  //   <h1>Itinerary</h1> will display the inline text as the most important
  //   heading of the section. Note that any inner HTML tags, styles or
  //   attributes will be ignored. For example, <h1 style=".."> will be treated
  //   the same as <h1>. Only pure text wil be preserved.
  //
  // Paragraph tag: <p>:
  //   Paragraph tag can be used to wrap detailed introduction or contents. Any
  //   inner tags, styles or attributes will be ignored with a few exceptions:
  //   <br>, <strong> and <em>. Please see the phrase tag section below for more
  //   details.
  //
  // List tags: <ul>, <ol>, <li>
  //   <ul> tag can be used with <li> tag to display unordered lists, and <ol>
  //   tag can be used with <li> to display ordered lists. This is a good tool
  //   to display checklists, highlights or any other lists that fit your
  //   use-cases.
  // Example: To show a list of features of a cruise trip:
  //  <ol>
  //    <li>Wonderful ocean view and chances to play with wildlife.</li>
  //    <li>Carefully designed travel arrangements and services.</li>
  //    <li>Gauranteed lowest price.</li>
  // </ol>
  // Note that only <li> children under <ul> or <ol> tags will be converted. All
  // other children will be dropped. Also any inner tags, attributes and styles
  // will be ignored, only pure text contents are preserved.
  //
  // Division tag: <div>
  //   All supported inner tags of the <div> tag will be parsed with the rules
  //   stated above. But <div> tag itself does not mean any grouping or
  //   indenting here. Also any inner attributes and styles will be ignored.
  //
  // Phrase tags: <br>, <strong>, <em>:
  //   Only the three tags mentioned above are supported. <br> can be used to
  //   break lines in paragraphs, and <strong>/<em> can be used to highlight
  //   important text. Any other phrase tags will be ignored.
  //
  // Unsupported tags:
  //   * <html>, <header> and <body> tags are not allowed.
  //   * Any URLs, anchors, links will be striped, and will never be displayed
  //   to end-users. If you want to use photos to create a rich user experience,
  //   please use the "related_media" field below to send your photo urls
  //   * Any other tags not mentioned above are not supported (for example
  //   <table>, <td> ...).
  //
  // Important notes:
  //   * Try not to use other tags except for the supported ones mentioned
  //   above, because contents within unsupported tags will be excluded from UI
  //   rendering and may lead to undesired user experience.
  //   * Try avoid deep nested structures like more than 3 different heading
  //   levels or nested lists. Keeping the structure flat, simple and
  //   straightforward helps to create a better user experience.
  //   * If the currently supported layouts are not enough for your use cases,
  //   please contact Google with your requests and we will find the best
  //   approach for you.
  //
  // (required)
  string description = 4;
  // The price of the service. (optional, overridden when payment options or
  // ticket types present)
  Price price = 5;
  // Rules to book/cancel an appointment. (optional)
  SchedulingRules rules = 6;
  // Intake forms to customize the service. (optional)
  repeated ServiceIntakeForm form = 7;

  // Enum to indicate the prepayment type.
  enum PrepaymentType {
    // By default we will assume that the prepayment is NOT_SUPPORTED.
    PREPAYMENT_TYPE_UNSPECIFIED = 0;
    // The user has to pay this service at the booking time.
    REQUIRED = 1;
    // The user can choose to pre-pay this service at the booking time or later,
    // but it is not required in order to book.
    OPTIONAL = 2;
    // The prepayment is not supported for this service.
    NOT_SUPPORTED = 3;
  }
  // Whether a prepayment is required, optional or not supported. (optional)
  PrepaymentType prepayment_type = 8;

  // The service's tax rate. If present this field overrides any tax_rate set at
  // the merchant level. An empty message (i.e. tax_rate { }) will reset the
  // applied tax rate to zero. (optional)
  TaxRate tax_rate = 9;

  // A list of ids referencing the payment options which can be used to pay
  // for this service. The actual payment options are defined at the Merchant
  // level, and can also be shared among multiple Merchants. (optional)
  repeated string payment_option_id = 10;

  // Defines how a deposit may be charged to the user. Can be overridden at the
  // availability level. (optional)
  Deposit deposit = 11;

  // Defines a no show fee that may be charged to the user. Can be overridden
  // at the availability level. (optional)
  NoShowFee no_show_fee = 12;

  // Indicates whether the user must provide a credit card in order to book this
  // service.
  // This value can be overridden at the availability level. (optional)
  RequireCreditCard require_credit_card = 13;

  // An action link related to this service.
  repeated ActionLink action_link = 14;

  enum ServiceType {
    SERVICE_TYPE_UNSPECIFIED = 0;
    SERVICE_TYPE_DINING_RESERVATION = 1;
    SERVICE_TYPE_FOOD_ORDERING = 2;
    SERVICE_TYPE_EVENT_TICKET = 3;
    SERVICE_TYPE_TRIP_TOUR = 4;
  }

  // The predefined type of this service. Currently, only used with action_link.
  ServiceType type = 15;

  // Types of tickets that can be booked/purchased for this service, if tickets
  // are supported. (optional)
  repeated TicketType ticket_type = 16;

  // Photos related to this service. Google will crawl these media to
  // ensure that they are displayed to end-users in the most efficient way.
  // (optional)
  repeated RelatedMedia related_media = 17;

  // Service attribute values that apply to this service (optional).
  // Each Service may have zero or more values for each service attribute
  // defined in the corresponding Merchant.
  repeated ServiceAttributeValueId service_attribute_value_id = 18;
}

// The price of a service or a fee.
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).
  // (required)
  int64 price_micros = 1;
  // The currency of the price that is defined in ISO 4217. (required)
  string currency_code = 2;
  // An optional and opaque string that identifies the pricing option that is
  // associated with the extended price. (optional)
  string pricing_option_tag = 3;
}
// The scheduling rules for a service.
message SchedulingRules {
  // The minimum advance notice in seconds required to book an appointment.
  // (optional)
  int64 min_advance_booking = 1;

  // The minimum advance notice in seconds required to cancel a booked
  // appointment online. (optional)
  int64 min_advance_online_canceling = 2;

  // The fee for canceling within the minimum advance notice period.
  Price late_cancellation_fee = 3 [deprecated = true];

  // The fee for no-show without canceling.
  Price noshow_fee = 4 [deprecated = true];
}

// A tax rate applied when charging the user for a service, and which can be set
// on either a per merchant, or per service basis.
message TaxRate {
  // A tax rate in millionths of one percent, effectively giving 6 decimals of
  // precision. For example, if the tax rate is 7.253%, this field should be set
  // to 7253000.
  //
  // If this field is left unset or set to 0, the total price charged to a user
  // for any service provided by this merchant is the exact price specified by
  // Service.price. The service price is assumed to be exempt from or already
  // inclusive of applicable taxes. Taxes will not be shown to the user as a
  // separate line item.
  //
  // If this field is set to any nonzero value, the total price charged to a
  // user for any service provided by this merchant will include the service
  // price plus the tax assessed using the tax rate provided here. Fractions of
  // the smallest currency unit (for example, fractions of one cent) will be
  // rounded using nearest even rounding. Taxes will be shown to the user as a
  // separate line item. (required)
  int32 micro_percent = 1;
}

// Defines a field that is included in a ServiceIntakeForm.
message ServiceIntakeFormField {
  // Enum to indicate the type of field.
  enum FieldType {
    // Fields of unspecified or unknown type will be ignored.
    FIELD_TYPE_UNSPECIFIED = 0;
    // A one-line input field for text.
    SHORT_ANSWER = 1;
    // A multi-line input field for text.
    PARAGRAPH = 2;
    // A set of radio buttons that requires one choice from many options.
    MULTIPLE_CHOICE = 3;
    // One or more enumerated items with checkboxes.
    CHECKBOXES = 4;
    // A selection from a dropdown.
    DROPDOWN = 5;
    // A yes/no button.
    BOOLEAN = 6;
  }

  // The type of this field. (required)
  FieldType type = 1;

  // The text shown to the user for this field. (required)
  string label = 2;

  // For MULTIPLE_CHOICE, CHECKBOXES, or DROPDOWN, the values to enumerate.
  // (optional)
  repeated string value = 3;

  // Indicates whether an answer to this field is required by a user. (optional)
  bool is_required = 4;
}

// Defines an intake form that customizes the service provided by a merchant.
message ServiceIntakeForm {
  // Fields that will be displayed to the user. (required)
  repeated ServiceIntakeFormField field = 1;

  // If true, this form will be shown to first time customers.
  // (one of first_time_customers or returning_customers required)
  bool first_time_customers = 2;

  // If true, this form will be shown to repeat customers.
  // (one of first_time_customers or returning_customers required)
  bool returning_customers = 3;
}

// A deposit that the user may be charged or have a hold on their credit card
// for.
message Deposit {
  // Deposit amount.
  Price deposit = 1;

  // Minimum advance cancellation for the deposit.
  int64 min_advance_cancellation_sec = 2;

  // Defines how the deposit is determined from the availability.
  PriceType deposit_type = 3;
}

// A fee that a user may be charged if they have made a booking but do not
// show up.
message NoShowFee {
  // The amount the user may be charged if they do not show up for their
  // reservation.
  Price fee = 1;

  // Defines how the fee is determined from the availability.
  PriceType fee_type = 3;
}

// Defines how a total price is determined from an availability.
enum PriceType {
  // The price is for a fixed amount. This is the default value if the field is
  // not set.
  FIXED_RATE_DEFAULT = 0;
  // The price specified is per person, and the total price is calculated
  // according to the party size specified in Resources as
  // price_micros * party_size. A PER_PERSON price must be accompanied by a
  // party size in the availability resources. If it is not, a party size of one
  // is used.
  PER_PERSON = 1;
}

// Defines whether a credit card is required in order to book an appointment.
enum RequireCreditCard {
  // The credit card requirement is not explicitly specified and the
  // behaviour is identical to the one specified for CONDITIONAL.
  REQUIRE_CREDIT_CARD_UNSPECIFIED = 0;

  // Google will require a credit card for the booking if any of the following
  // conditions are met:
  // * the availability has a price and the prepayment_type is REQUIRED
  // * the no_show_fee is set
  // * the deposit field is set.
  REQUIRE_CREDIT_CARD_CONDITIONAL = 1;

  // A credit card is always required in order to book this availability
  // regardless of other field values.
  REQUIRE_CREDIT_CARD_ALWAYS = 2;
}

// An action URL with associated language, list of countries restricted to, and
// optional platform that indicates which platform this action should be
// performed on.
message ActionLink {
  // The entry point URL for this action link.
  string url = 1;

  // The BCP-47 language tag identifying the language in which the content
  // from this URI is available.
  string language = 2;

  // ISO 3166-1 alpha-2 country code. Leave empty for unrestricted visibility.
  repeated string restricted_country = 3;

  // The platform that this action should be performed on. If this field is
  // unset, ACTION_PLATFORM_WEB_APPLICATION will be used as fallback.
  ActionPlatform platform = 4;
}

// The platform that the action is performed on. Web application is the general
// fallback. It is recommended to have at least one ActionLink with
// ACTION_PLATFORM_WEB_APPLICATION. Links with Android and iOS as platform are
// only used on the respective system.
enum ActionPlatform {
  // The platform is unspecified.
  ACTION_PLATFORM_UNSPECIFIED = 0;

  // The action platform is web in general.
  ACTION_PLATFORM_WEB_APPLICATION = 1;

  // The action platform is web on mobile devices.
  ACTION_PLATFORM_MOBILE_WEB = 2;

  // The action platform is Android OS.
  ACTION_PLATFORM_ANDROID = 3;

  // The action platform is iOS.
  ACTION_PLATFORM_IOS = 4;
}

// TicketType is used to differentiate among tickets (where a ticket can be a
// spot on a raft trip, an admission to a museum, etc.) with different prices
// and/or availabilities due to different user types or different service
// attributes.
message TicketType {
  // The ticket id is used to differentiate among different ticket types of the
  // same service, and is only expected to be unique within a service.
  string ticket_type_id = 1;

  // This can be user visible, e.g., “adult”, "child", “veteran”, “Row J”, etc.
  string short_description = 2;

  // The price of a single ticket of this type, exclusive of any taxes. The tax
  // rate of Service is applied to its tickets.
  Price price = 3;
}

// Defines a media source. This field only contains the URL of this media source
// (only photos are supported for now). Google will crawl the media data to
// ensure that they are displayed to end-users in the most efficient way.
message RelatedMedia {
  // URL of this media source.
  string url = 1;

  // Type of this media source.
  MediaType type = 2;

  // Enum to indicate the type of this media source. Only photos are supported.
  // Please reach out to Google if supporting animations or videos is
  // important to your feature and we will find the best solution for you.
  enum MediaType {
    // Unused.
    TYPE_UNSPECIFIED = 0;
    // Indicates the media provided by the url is a photo.
    PHOTO = 1;
  }

  // Caption of the media, only plain text is supported. (optional)
  string caption = 3;
}

// Identifies a particular value of a service attribute to be applied to a
// Service.
message ServiceAttributeValueId {
  // ID of an attribute as defined in Merchant.service_attribute, e.g.
  // "service-type".
  string attribute_id = 1;

  // ID of the value for this attribute, e.g. "haircut". Must match a value_id
  // in the service attribute definition.
  string value_id = 2;
}