Introduce Transactional APIs for lodging

.github/workflows/build.yaml

@@ -41,6 +41,11 @@ jobs:
         with:
           go-version: 1.22.2
 
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
       - name: Setup JDK
         uses: actions/setup-java@v4
         with:

book/lodging/build.gradle.kts

@@ -0,0 +1,46 @@
+import org.jetbrains.kotlin.gradle.dsl.ExplicitApiMode
+
+plugins {
+    id("com.google.protobuf")
+}
+
+description = "Models comprising the Lodging Book and Manage functionality in the Engine Partner API."
+
+dependencies {
+    api(projects.grpcEcosystemProtocGenOpenapiv2)
+    api(projects.enginePartnerApiCommon)
+    api(projects.enginePartnerApiContent)
+    api(projects.enginePartnerApiShopLodging)
+    api(libs.protobuf.java)
+    api(libs.protobuf.kotlin)
+}
+
+kotlin {
+    explicitApi = ExplicitApiMode.Disabled
+}
+
+protobuf {
+    protoc {
+        artifact = libs.protobuf.protoc.get().toString()
+    }
+    plugins {
+        create("doc") {
+            artifact = libs.grpc.protoc.genDoc.get().toString()
+        }
+    }
+    generateProtoTasks {
+        all().forEach {
+            it.generateDescriptorSet = true
+            it.descriptorSetOptions.includeImports = true
+
+            it.plugins {
+                create("doc") {
+                    option("markdown,${project.name}-${version}.md")
+                }
+            }
+            it.builtins {
+                create("kotlin")
+            }
+        }
+    }
+}

book/lodging/src/main/proto/engine/book/lodging/v1/booking.proto

@@ -0,0 +1,73 @@
+//
+// 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.book.lodging.v1;
+
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+import "engine/book/lodging/v1/metadata.proto";
+import "engine/book/lodging/v1/reservation.proto";
+import "engine/book/lodging/v1/status.proto";
+import "engine/common/v1/refund.proto";
+
+option go_package = "engine.com/engine-partner-api/v1/book/lodging";
+option java_package = "com.engine.book.v1.lodging";
+option java_multiple_files = true;
+
+// The details of an Engine Lodging [Booking] and the Property [Reservation] it describes.
+message BookingDetails {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_BookingDetails_v1"
+    }
+  };
+
+  // A unique identifier for the [Booking].
+  string booking_id = 1;
+
+  // Details of the state of the [Booking].
+  .engine.book.lodging.v1.BookingStatus status = 2;
+
+  // Details of the Property [Reservation]
+  .engine.book.lodging.v1.ReservationDetails reservation_details = 3;
+
+  // Optionally, the details of the cancellation action taken for the [Booking].
+  .engine.book.lodging.v1.CancellationDetails cancellation_details = 4;
+
+  // Any metadata provided while [Booking].
+  // Maximum length: 10
+  repeated .engine.book.lodging.v1.BookingMetadata metadata = 5 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+    max_items: 10;
+  }];
+}
+
+// Details of the cancellation of a [Booking].
+message CancellationDetails {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_CancellationDetails_v1"
+    }
+  };
+
+  // An ISO-8601-compliant date and time at which the [Booking] was canceled.
+  // See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations
+  string canceled_at = 1;
+
+  // The details of the Refund granted when canceled.
+  .engine.common.v1.Refund refund = 2;
+}

book/lodging/src/main/proto/engine/book/lodging/v1/guests.proto

@@ -0,0 +1,79 @@
+//
+// 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.book.lodging.v1;
+
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+import "engine/common/v1/loyalty.proto";
+
+option go_package = "engine.com/engine-partner-api/v1/book/lodging";
+option java_package = "com.engine.book.v1.lodging";
+option java_multiple_files = true;
+
+// Details of the guests staying within a single room during the stay.
+message RoomGuests {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_RoomGuests_v1"
+    }
+  };
+
+  // The primary guest of a room
+  .engine.book.lodging.v1.GuestWithLoyalty primary_guest = 1;
+
+  // Any additional names you wish to be able to check-in to the room without the [RoomGuests.primary_guest] present.
+  // Not all Properties allow additional guests to check-in.
+  // The primary guest should not be included in the `additional_guests` field.
+  repeated .engine.book.lodging.v1.Guest additional_guests = 2;
+}
+
+// A traveler who may be awarded Loyalty Rewards for the stay.
+message GuestWithLoyalty {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_GuestWithLoyalty_v1"
+    }
+  };
+
+  // The traveler details.
+  .engine.book.lodging.v1.Guest guest = 1;
+
+  // The identifier to provide to the Property during Booking.
+  // Invalid identifiers may result in Booking failures with some Properties.
+  // Not all Offers include loyalty rewards.
+  .engine.common.v1.LodgingLoyaltyProgramIdentifier loyalty_program_identifier = 2;
+}
+
+// A traveler for the stay.
+message Guest {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_Guest_v1"
+    }
+  };
+
+  // The guest's family name or last name.
+  string family_name = 1;
+
+  // The guest's given name or first name.
+  string given_name = 2;
+
+  // True if the guest is an adult.
+  bool is_adult = 3;
+}

book/lodging/src/main/proto/engine/book/lodging/v1/metadata.proto

@@ -0,0 +1,54 @@
+//
+// 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.book.lodging.v1;
+
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+import "engine/common/v1/loyalty.proto";
+
+option go_package = "engine.com/engine-partner-api/v1/book/lodging";
+option java_package = "com.engine.book.v1.lodging";
+option java_multiple_files = true;
+
+// Custom Metadata attached to a [Booking].
+// Metadata values allow a Partner API customer to carry a small amount of context on a [Booking] for their own use.
+message BookingMetadata {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_BookingMetadata_v1"
+    }
+  };
+
+  // A textual key to represent the purpose of the metadata, for example, "Contract ID".
+  // Keys must be unique within a [Booking].
+  // Maximum length: 40 characters
+  string key = 1 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+    max_length: 40;
+  }];
+
+  // A textual value.
+  // Maximum length: 100 characters
+  string value = 2 [(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+    max_length: 100;
+  }];
+
+  // If true, this Metadata entry will be included on invoices and reports.
+  // If false, this entry will only be available via direct API access.
+  bool external = 3;
+}

book/lodging/src/main/proto/engine/book/lodging/v1/quote.proto

@@ -0,0 +1,60 @@
+//
+// 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.book.lodging.v1;
+
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+import "engine/common/v1/actions.proto";
+import "engine/shop/lodging/v1/offer.proto";
+import "engine/shop/lodging/v1/room.proto";
+
+option go_package = "engine.com/engine-partner-api/v1/book/lodging";
+option java_package = "com.engine.book.v1.lodging";
+option java_multiple_files = true;
+
+// The full details of the item to be Booked.
+message Quote {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_Quote_v1"
+    }
+  };
+
+  // An ISO-8601-compliant date on which the stay begins.
+  // See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates
+  string check_in_date = 1;
+
+  // An ISO-8601-compliant date on which the stay ends.
+  // See https://en.wikipedia.org/wiki/ISO_8601#Calendar_dates
+  string check_out_date = 2;
+
+  // The details of the [Offer] to be Booked.
+  .engine.shop.lodging.v1.OfferSummary offer_summary = 3;
+
+  // The number of rooms to be Booked.
+  int32 room_count = 4;
+
+  // The details of the [Room] to be booked.
+  .engine.shop.lodging.v1.RoomDescription room_description = 5;
+
+  // Optionally, the actions (such as cancellation) that are available for the [Booking] if they are known.
+  // Not every action will be available through the API for every reservation.
+  // Some may be available but the availability is not known at the point of the [LodgingBookingService.ConfirmOffer] or the [LodgingBookingService.Book] request.
+  .engine.common.v1.AvailableActions available_actions = 6;
+}

book/lodging/src/main/proto/engine/book/lodging/v1/reservation.proto

@@ -0,0 +1,52 @@
+//
+// 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.book.lodging.v1;
+
+import "protoc-gen-openapiv2/options/annotations.proto";
+
+import "engine/book/lodging/v1/guests.proto";
+import "engine/book/lodging/v1/metadata.proto";
+import "engine/book/lodging/v1/quote.proto";
+import "engine/common/v1/refund.proto";
+
+option go_package = "engine.com/engine-partner-api/v1/book/lodging";
+option java_package = "com.engine.book.v1.lodging";
+option java_multiple_files = true;
+
+// Details of the Reservation made with the [Property].
+message ReservationDetails {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
+    json_schema: {
+      title: "Book_Lodging_ReservationDetails_v1"
+    }
+  };
+
+  // The confirmation numbers provided by the [Property] after a successful [Reservation].
+  // Confirmation numbers may not be available immediately after booking.
+  // The quantity of confirmation numbers may vary by the [Property] booked.
+  repeated string confirmation_numbers = 1;
+
+  // An ISO-8601-compliant date and time at which the [Reservation] was booked.
+  // See https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations
+  string created_at = 2;
+
+  // The details of the [Quote] that was purchased.
+  .engine.book.lodging.v1.Quote quote = 3;
+}
+