feat(tour): add search Tours

Introduces new endpoint to enable searching for Tour resources based on their external or internal IDs.
TRA-1209

openapiv2/book.swagger.yaml

@@ -71,6 +71,83 @@ consumes:
 produces:
   - application/json
 paths:
+  /v1/tours:search:
+    get:
+      summary: Search tours.
+      description: |-
+        Search for Tours in a space.
+        - You can search for Tours by external_reference_id
+      operationId: BookingService_SearchTours
+      responses:
+        "200":
+          description: A successful response.
+          schema:
+            $ref: '#/definitions/v1beta1SearchToursResponse'
+        default:
+          description: An unexpected error response.
+          schema:
+            $ref: '#/definitions/rpcStatus'
+      parameters:
+        - name: parent
+          description: |-
+            The resource name of the parent, which owns this collection of tours.
+            Format: spaces/{space}
+          in: query
+          required: true
+          type: string
+        - name: pageSize
+          description: |-
+            Requested page size. Server may return fewer tours than requested.
+            If unspecified, server will pick an appropriate default.
+          in: query
+          required: false
+          type: integer
+          format: int32
+        - name: pageToken
+          description: |-
+            A token identifying a page of results the server should return.
+            Typically, this is the value of
+            [SearchToursResponse.page_token][einride.saga.book.v1.SearchToursResponse.page_token]
+            returned from the previous call to `SearchTours` method.
+          in: query
+          required: false
+          type: string
+        - name: skip
+          description: Allows for skipping result
+          in: query
+          required: false
+          type: integer
+          format: int32
+        - name: query
+          description: |-
+            Filters
+            Multiple filters will be combined with the logical operator AND.
+
+            Returned tours contain the query string in ANY of the fields:
+            tour_id, external_reference_id
+          in: query
+          required: false
+          type: string
+        - name: showDeleted
+          description: Includes deleted tours in result
+          in: query
+          required: false
+          type: boolean
+        - name: orderBy
+          description: |-
+            How the results should be sorted. Presently, the only permitted values are:
+
+            - `"create_time asc"` (default if no order_by is specified)
+            - `"create_time desc"`
+            Example:
+            ```
+            order_by = "create_time desc"
+            ```
+          in: query
+          required: false
+          type: string
+      tags:
+        - BookingService
   /v1beta1/{parent}/shipments:
     get:
       summary: List shipments in a space.
@@ -1123,6 +1200,26 @@ definitions:
         format: int32
         description: The total size of tours found in a space.
     description: Response message for TourService.ListTours.
+  v1beta1SearchToursResponse:
+    type: object
+    properties:
+      tours:
+        type: array
+        items:
+          type: object
+          $ref: '#/definitions/v1beta1Tour'
+        description: The list of tours.
+      nextPageToken:
+        type: string
+        description: |-
+          A token to retrieve next page of results. Pass this value in the
+          SearchToursRequest.page_token field in the subsequent call to `SearchTours` method
+          to retrieve the next page of results.
+      totalSize:
+        type: integer
+        format: int32
+        description: The total size of tours found using the search filters.
+    description: Response message for TourService.SearchTours.
   v1beta1Shipment:
     type: object
     properties:

proto/einride/saga/extend/book/v1beta1/booking_service.proto

@@ -63,6 +63,21 @@ service BookingService {
     };
   }
 
+  // Search tours.
+  //
+  // Search for Tours in a space.
+  // - You can search for Tours by external_reference_id
+  rpc SearchTours(SearchToursRequest) returns (SearchToursResponse) {
+    option (google.api.http) = {get: "/v1/tours:search"};
+    option (einride.iam.v1.method_authorization) = {
+      permission: "book.tours.search"
+      before: {
+        expression: "test(caller, request.parent)"
+        description: "The caller must have permission to list all tours in the parent space."
+      }
+    };
+  }
+
   // Confirm a Provisional tour.
   //
   // Reconfirming a tour that is already confirmed will return an InvalidArgument Error.
@@ -170,6 +185,61 @@ message ListToursResponse {
   int32 total_size = 3 [(google.api.field_behavior) = OPTIONAL];
 }
 
+// Request to search tours
+message SearchToursRequest {
+  // The resource name of the parent, which owns this collection of tours.
+  // Format: spaces/{space}
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {type: "account.saga.einride.tech/Space"}
+  ];
+
+  // Requested page size. Server may return fewer tours than requested.
+  // If unspecified, server will pick an appropriate default.
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // A token identifying a page of results the server should return.
+  // Typically, this is the value of
+  // [SearchToursResponse.page_token][einride.saga.book.v1.SearchToursResponse.page_token]
+  // returned from the previous call to `SearchTours` method.
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Allows for skipping result
+  int32 skip = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Filters
+  // Multiple filters will be combined with the logical operator AND.
+  //
+  // Returned tours contain the query string in ANY of the fields:
+  // tour_id, external_reference_id
+  string query = 5 [(google.api.field_behavior) = OPTIONAL];
+
+  // Includes deleted tours in result
+  bool show_deleted = 8 [(google.api.field_behavior) = OPTIONAL];
+
+  // How the results should be sorted. Presently, the only permitted values are:
+  //
+  // - `"create_time asc"` (default if no order_by is specified)
+  // - `"create_time desc"`
+  // Example:
+  // ```
+  // order_by = "create_time desc"
+  // ```
+  string order_by = 7 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response message for TourService.SearchTours.
+message SearchToursResponse {
+  // The list of tours.
+  repeated Tour tours = 1 [(google.api.field_behavior) = OPTIONAL];
+  // A token to retrieve next page of results. Pass this value in the
+  // SearchToursRequest.page_token field in the subsequent call to `SearchTours` method
+  // to retrieve the next page of results.
+  string next_page_token = 2 [(google.api.field_behavior) = OPTIONAL];
+  // The total size of tours found using the search filters.
+  int32 total_size = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
 // The request message to confirm a tour.
 message ConfirmTourRequest {
   // The resource name of the tour to confirm.