// Shelf Inventory – the gRPC service of the Shelf practice sandbox.
//
// Download this file from the start page (/inventory.proto) and import it into Postman
// (New > gRPC > Import a .proto file), or skip the file: the server also offers reflection,
// so grpcurl and Postman can discover the service on their own.
//
// Reads (GetStock, ListStock) need no sign-in. ReserveItems needs your token or API key in the
// call metadata:  authorization: Bearer <token>   or   x-api-key: <key>.
// What you reserve is yours alone: the catalog's stock is shared and read-only, and your
// reservations are subtracted only from the "available" count you see.
syntax = "proto3";

package shelf.inventory.v1;

service Inventory {
  // One product by SKU. NOT_FOUND when the catalog has no such product.
  rpc GetStock(GetStockRequest) returns (StockItem);

  // The catalog's stock as a server stream: one StockItem per message, ordered by SKU.
  rpc ListStock(ListStockRequest) returns (stream StockItem);

  // Reserve units for yourself, all lines or none. Needs authentication.
  rpc ReserveItems(ReserveItemsRequest) returns (ReserveItemsResponse);
}

message GetStockRequest {
  // For example "KT-1003": two capital letters, a hyphen and four digits.
  string sku = 1;
}

message ListStockRequest {
  // Filter by category, for example "kettles". Empty means all.
  string category = 1;
  // How many products to send: 1 to 100. 0 means the default, 20.
  int32 page_size = 2;
  // Skip products with no units on hand.
  bool in_stock_only = 3;
  // Pause between messages in milliseconds, 0 to 2000, so a stream is easy to watch. Default 0.
  int32 interval_ms = 4;
}

message StockItem {
  string sku = 1;
  string name = 2;
  string category = 3;
  // Units in the catalog. Shared by everyone, never changes.
  int32 on_hand = 4;
  // Units YOU have reserved.
  int32 reserved = 5;
  // on_hand minus reserved.
  int32 available = 6;
  // Price in cents, with the currency code next to it.
  int64 price_cents = 7;
  string currency = 8;
}

message ReserveItemsRequest {
  // 1 to 10 lines, each SKU at most once.
  repeated ReserveLine items = 1;
}

message ReserveLine {
  string sku = 1;
  // 1 to 10 units.
  int32 quantity = 2;
}

message ReserveItemsResponse {
  // For example "RSV-4F9A21C7".
  string reservation_id = 1;
  repeated ReservedLine items = 2;
}

message ReservedLine {
  string sku = 1;
  int32 quantity = 2;
  // What is still available to you for this product after the reservation.
  int32 available_after = 3;
}