//
// Copyright 2025 HotelEngine, Inc., d/b/a Engine
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at:
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

syntax = "proto3";

package engine.content.v1.lodging;

option go_package = "engine.com/engine-partner-api/v1/content";
option java_package = "com.engine.content.v1.lodging";
option java_multiple_files = true;

import "engine/common/v1/amenities.proto";
import "engine/common/v1/contact.proto";
import "engine/common/v1/geo.proto";
import "engine/common/v1/image.proto";
import "engine/common/v1/loyalty.proto";
import "engine/common/v1/media.proto";
import "engine/common/v1/postal_address.proto";
import "engine/content/v1/lodging/lodging_amenity_code.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

//
// An individual Lodging location identified by [Engine].
//
message Property {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      title: "Content_Property_v1"
    }
  };

  //
  // The [Engine] identifier for this [Property].
  //
  string id = 1;

  //
  // The full name of this [Property].
  //
  string name = 11;

  //
  // The physical address of this [Property].
  // This may differ from the mailing, billing, or other administrative addresses.
  //
  .engine.common.v1.PostalAddress physical_address = 21;

  //
  // The geographic location of this [Property].
  //
  .engine.common.v1.GeoPoint coordinates = 22;

  //
  // If available, A URI to the image to use as the primary image to identify this [Property].
  //
  optional string hero_image_uri = 31;

  //
  // If available, a brief textual description of this [Property].
  //
  optional string description = 41;

  //
  // If available, an E.164-compliant primary phone number for this [Property].
  // See https://en.wikipedia.org/wiki/E.164
  //
  optional string phone_number = 51;

  //
  // Contact email addresses for this property.
  // May include general contact, billing, or reservation emails.
  //
  repeated .engine.common.v1.ContactEmail emails = 61;

  //
  // Star rating for this property.
  // Represents the official star rating classification system.
  // See https://en.wikipedia.org/wiki/Hotel_rating
  // Examples: "4", "5", "3.5"
  //
  optional string star_rating = 71;

  //
  // Property amenities for this [Property].
  // List of amenity names describing features and services available to guests.
  // Examples: "Free WiFi", "Pool", "Fitness Center", "Free Breakfast"
  //
  repeated .engine.content.v1.lodging.PropertyAmenity amenities = 81;

  //
  // Media items for property gallery.
  // Collection of media URIs for detailed property viewing and marketing.
  //
  repeated .engine.common.v1.MediaItem media_items = 91;

  //
  // External catalog identifiers for this property.
  // Used for integration with external booking systems.
  //
  .engine.content.v1.lodging.ExternalCatalogIdentifiers catalog = 101;

  //
  // Check-in time in local time HH:MM 24-hour format (e.g., "15:00") for the [Property].
  //
  optional string check_in_time = 102;

  //
  // Check-out time in local time HH:MM 24-hour format (e.g., "11:00") for the [Property].
  //
  optional string check_out_time = 103;

  //
  // The loyalty rewards program associated with the [Property].
  //
  optional .engine.common.v1.LoyaltyRewardsProgram loyalty_rewards_program = 104;

  //
  // The time zone for the [Property] in the IANA format.
  // See https://www.iana.org/time-zones
  // Examples: "America/Denver", "Atlantic/Madeira"
  //
  optional string time_zone = 105;
}



//
// [Property] amenity containing name for property features and services.
//
message PropertyAmenity {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      title: "Content_PropertyAmenity_v1"
    }
  };

  //
  // Amenity name describing a [Property] feature or service.
  // Examples: "Free WiFi", "Free Breakfast"
  //
  string amenity_name = 1;

  //
  // Amenity code, providing an easily machine readable representation of a [Property] feature or
  // service, if mapped.
  //
  optional .engine.content.v1.lodging.LodgingAmenityCode amenity_code = 2;
}

//
// A list of external catalog identifiers for a single catalog key.
//
message ExternalCatalogIdentifierList {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      title: "Content_ExternalCatalogIdentifierList_v1"
    }
  };

  //
  // Supplier property identifiers for the associated catalog key.
  // May contain multiple identifiers when more than one external record is mapped to the Engine record.
  //
  repeated string identifiers = 1;
}

//
// External catalog identifiers for property mapping.
//
message ExternalCatalogIdentifiers {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      title: "Content_ExternalCatalogIdentifiers_v1"
    }
  };

  //
  // GIATA identifier for this property.
  //
  optional string giata_identifier = 1;

  //
  // Catalog identifiers keyed by source keys.
  //
  map<string, .engine.content.v1.lodging.ExternalCatalogIdentifierList> catalog_identifiers = 2;
}