syntax = "proto3";

package einride.saga.extend.book.v1beta1;

import "einride/iam/v1/annotations.proto";
import "einride/saga/extend/book/v1beta1/shipment.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/field_mask.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

// A Saga space.
option (google.api.resource_definition) = {
  type: "api.saga.einride.tech/Space"
  pattern: "spaces/{space}"
};
// A Saga organization.
option (google.api.resource_definition) = {
  type: "api.saga.einride.tech/Organization"
  pattern: "organizations/{organization}"
};
// A Saga user.
option (google.api.resource_definition) = {
  type: "api.saga.einride.tech/User"
  pattern: "organizations/{user}"
};
// A Saga sender.
option (google.api.resource_definition) = {
  type: "api.saga.einride.tech/Sender"
  pattern: "spaces/{space}/senders/{sender}"
};
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "Einride Extend: Shipment API"
    version: "v1beta1"
    description:
      "Based on REST principles, with optional support for gRPC, the Einride Extend Shipment API enables modern API-based integration to Einride Saga for transport booking.\n"
      "\n"
      "API design\n"
      "----------\n"
      "\n"
      "The Einride Extend APIs are designed using the [AIP](https://aip.dev) design framework, which means that they are resource-oriented and work like standard [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\n"
      "\n"
      "### Resource-oriented design\n"
      "\n"
      "*See also: [AIP-121: Resource-oriented design](https://google.aip.dev/121)*\n"
      "\n"
      "The fundamental building blocks of this API are individually-named resources (nouns) and the relationships and hierarchy that exist between them.\n"
      "\n"
      "A number of standard methods (verbs) provide the semantics for common [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations. Custom methods are available where custom operations are required, such as for cancelling shipments.\n"
      "\n"
      "### Resource names\n"
      "\n"
      "*See also: [AIP-122: Resource names](https://google.aip.dev/122)*\n"
      "\n"
      "This API exposes resources which users are able to create, retrieve, and manipulate. Resources are named: each resource has a unique identifier that users use to reference that resource, and these names are what users should store as the canonical names for the resources.\n"
      "\n"
      "As such, the unique identifier for a resource in this API is called a *resource name*.\n"
      "\n"
      "Protocols\n"
      "---------\n"
      "\n"
      "The Einride Extend APIs support both HTTP and gRPC protocols.\n"
      "\n"
      "### HTTP\n"
      "\n"
      "The Einride Extend APIs are available as RESTful HTTP endpoints.\n"
      "\n"
      "See this document for the OpenAPI specifications, or use the API documentation at [extend.saga.einride.tech](https://extend.saga.einride.tech), where you can also try out the REST APIs and make example requests.\n"
      "\n"
      "### gRPC\n"
      "\n"
      "[gRPC](https://grpc.io) is a high performance, open source universal RPC framework that works across programming languages and platforms.\n"
      "\n"
      "To for more information about using Einride Extend APIs via gRPC, please contact your Einride representative.\n"
      "\n"
      "Authentication\n"
      "---------\n"
      "\n"
      "The Einride Extend use standard [Bearer token authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). When using the HTTP APIs, make sure to always provide the following header in all requests:\n"
      "\n"
      "\n"
      "    Authorization: Bearer <token>\n"
      "\n"
      "\n"
      "Where `<token>` is the authentication token for your integration. Please contact your Einride representative to obtain an authentication token for your integration.\n"
      "\n"
      "API address\n"
      "---------\n"
      "\n"
      "The Einride Extend API is available via the following root address:\n"
      "\n"
      "https://api.saga.einride.tech\n"
  }
  schemes: HTTPS
  consumes: "application/json"
  produces: "application/json"
  security_definitions: {
    security: {
      key: "Authorization"
      value: {
        type: TYPE_API_KEY
        in: IN_HEADER
        name: "authorization"
      }
    }
  }
  security: {
    security_requirement: {
      key: "Authorization"
      value: {}
    }
  }
};

// Shipment service.
service ShipmentService {
  option (google.api.default_host) = "api.saga.einride.tech";

  // Create a shipment in a space.
  //
  // This is an AIP standard [Create](https://google.aip.dev/133) method.
  rpc CreateShipment(CreateShipmentRequest) returns (Shipment) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=spaces/*}/shipments"
      body: "shipment"
    };
    option (google.api.method_signature) = "parent,shipment";
    option (einride.iam.v1.method_authorization) = {
      permission: "book.shipments.create"
      before: {
        expression: "test(caller, request.parent)"
        description: "The caller must have permission to create a shipment in the parent space."
      }
    };
  }

  // Get a shipment.
  //
  // This is an AIP standard [Get](https://google.aip.dev/131) method.
  rpc GetShipment(GetShipmentRequest) returns (Shipment) {
    option (google.api.http) = {get: "/v1beta1/{name=spaces/*/shipments/*}"};
    option (google.api.method_signature) = "name";
    option (einride.iam.v1.method_authorization) = {
      permission: "book.shipments.get"
      before: {
        expression: "test(caller, request.name)"
        description: "The caller must have permission to get the shipment"
      }
    };
  }

  // List shipments in a space.
  //
  // This is an AIP standard [List](https://google.aip.dev/132) method.
  rpc ListShipments(ListShipmentsRequest) returns (ListShipmentsResponse) {
    option (google.api.http) = {get: "/v1beta1/{parent=spaces/*}/shipments"};
    option (google.api.method_signature) = "parent";
    option (einride.iam.v1.method_authorization) = {
      permission: "book.shipments.list"
      before: {
        expression: "test(caller, request.parent)"
        description: "The caller must have permission to list all shipments in the parent space."
      }
    };
  }

  // Release a shipment.
  //
  // The state of the shipment after releasing it is RELEASED.
  //
  // This is an AIP [state](https://google.aip.dev/216) transition method.
  rpc ReleaseShipment(ReleaseShipmentRequest) returns (Shipment) {
    option (google.api.http) = {
      post: "/v1beta1/{name=spaces/*/shipments/*}:release"
      body: "*"
    };
    option (google.api.method_signature) = "name";
    option (einride.iam.v1.method_authorization) = {
      permission: "book.shipments.release"
      before: {
        expression: "test(caller, request.name)"
        description: "The caller must have permission to release shipment."
      }
    };
  }

  // Cancel a shipment.
  //
  // The state of the shipment after cancelling it is CANCELLED.
  //
  // This is an AIP [state](https://google.aip.dev/216) transition method.
  rpc CancelShipment(CancelShipmentRequest) returns (Shipment) {
    option (google.api.http) = {
      post: "/v1beta1/{name=spaces/*/shipments/*}:cancel"
      body: "*"
    };
    option (google.api.method_signature) = "name";
    option (einride.iam.v1.method_authorization) = {
      permission: "book.shipments.cancel"
      before: {
        expression: "test(caller, request.name)"
        description: "The caller must have permission to cancel shipment."
      }
    };
  }

  // Update a shipment in a space.
  //
  // This is an AIP standard [Update](https://google.aip.dev/134) method.
  rpc UpdateShipment(UpdateShipmentRequest) returns (Shipment) {
    option (google.api.http) = {
      patch: "/v1beta1/{shipment.name=spaces/*/shipments/*}"
      body: "shipment"
    };
    option (google.api.method_signature) = "shipment,update_mask";
    option (einride.iam.v1.method_authorization) = {
      permission: "book.shipments.update"
      before: {
        expression: "test(caller, request.shipment.name)"
        description: "The caller must have permission to update the shipment."
      }
    };
  }
}

// Request message for BookService.CreateShipment.
message CreateShipmentRequest {
  // The parent space in which to create the shipment.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.saga.einride.tech/Space"},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      field_configuration: {path_param_name: "space"}
    }
  ];

  // The shipment to create.
  Shipment shipment = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request message for BookService.GetShipment.
message GetShipmentRequest {
  // The resource name of the shipment to retrieve.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.saga.einride.tech/Shipment"},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      field_configuration: {path_param_name: "shipment"}
    }
  ];
}

// Request message for ShipmentService.ListShipments.
message ListShipmentsRequest {
  // The resource name of the parent, which owns this collection of shipments.
  // Format: spaces/{space}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.saga.einride.tech/Space"}
  ];

  // Requested page size. Server may return fewer shipments 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 ListShipmentsResponse.page_token
  // returned from the previous call to `ListShipments` method.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // How the results should be sorted. Presently, the only permitted values are:
  //
  // - `"create_time desc"` (default if no order_by is specified)
  // - `"create_time asc"`
  // Example:
  // ```
  // order_by = "create_time desc"
  // ``
  string order_by = 4 [(google.api.field_behavior) = OPTIONAL];

  // Controls whether deleted shipments should be returned. Defaults to false.
  bool show_deleted = 5 [(google.api.field_behavior) = OPTIONAL];

  // Allows to skip results.
  int32 skip = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for ShipmentService.ListShipments.
message ListShipmentsResponse {
  // The list of shipments.
  repeated Shipment shipments = 1;
  // A token to retrieve next page of results.  Pass this value in the ListShipmentsRequest.page_token field in the
  // subsequent call to `ListShipments` method to retrieve the next page of results.
  string next_page_token = 2;
  // The total size of shipments found in a space.
  int32 total_size = 3;
}

// Request message for BookService.ReleaseShipment.
message ReleaseShipmentRequest {
  // The resource name of the shipment to release.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.saga.einride.tech/Shipment"},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      field_configuration: {path_param_name: "shipment"}
    }
  ];
}

// Request message for BookService.CancelShipment.
message CancelShipmentRequest {
  // The resource name of the shipment to cancel.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.saga.einride.tech/Shipment"},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      field_configuration: {path_param_name: "shipment"}
    }
  ];
}

// Request to UpdateShipment method.
message UpdateShipmentRequest {
  // The resource which replaces the current resource.
  Shipment shipment = 1 [(google.api.field_behavior) = REQUIRED];
  // The update mask applies to the shipment.
  //
  // Currently, it allows updating with the following:
  // * external_reference_id
  // * units
  // For units you cannot update individual units, so you MUST provide all the other units
  // * vehicle
  // * vehicle.reference_id
  // * vehicle.driver_reference_id
  // * vehicle.carrier_reference_id
  // * pickup_address
  // * pickup_instructions
  // * delivery_address
  // * delivery_instructions
  // * annotations
  // * service
  //
  // The star (*) update mask will update the above listed masks
  // This applies also for empty update mask partial update
  // For the `FieldMask` definition, see:
  // https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask
  // Disable false positives for required update mask, keep as is.
  // (-- api-linter: core::0134::update-mask-optional-behavior=disabled --)
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
}