go-cart-actor/proto/cart_actor.proto

syntax = "proto3";

package messages;

option go_package = "git.tornberg.me/go-cart-actor/proto;messages";

import "messages.proto";

// -----------------------------------------------------------------------------
// Cart Actor gRPC API (Breaking v2 - Per-Mutation RPCs)
// -----------------------------------------------------------------------------
// This version removes the previous MutationEnvelope + Mutate RPC.
// Each mutation now has its own request wrapper and dedicated RPC method
// providing simpler, type-focused client stubs and enabling per-mutation
// metrics, auth and rate limiting.
//
// Regenerate Go code after editing:
//   protoc --go_out=. --go_opt=paths=source_relative \
//          --go-grpc_out=. --go-grpc_opt=paths=source_relative \
//          proto/cart_actor.proto proto/messages.proto
//
// Backward compatibility: This is a breaking change (old clients must update).
// -----------------------------------------------------------------------------

// Shared reply for all mutation RPCs.
message CartMutationReply {
  int32 status_code = 1;          // HTTP-like status (200 success, 4xx client, 5xx server)
  oneof result {
    CartState state = 2;          // Updated cart state on success
    string error = 3;             // Error message on failure
  }
  int64 server_timestamp = 4;     // Server-assigned Unix timestamp (optional auditing)
}

// Fetch current cart state without mutation.
message StateRequest {
  string cart_id = 1;
}

message StateReply {
  int32 status_code = 1;
  oneof result {
    CartState state = 2;
    string error = 3;
  }
}

// Per-mutation request wrappers. We wrap the existing inner mutation
// messages (defined in messages.proto) to add cart_id + optional metadata
// without altering the inner message definitions.

message AddRequestRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  AddRequest payload = 10;
}

message AddItemRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  AddItem payload = 10;
}

message RemoveItemRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  RemoveItem payload = 10;
}

message RemoveDeliveryRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  RemoveDelivery payload = 10;
}

message ChangeQuantityRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  ChangeQuantity payload = 10;
}

message SetDeliveryRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  SetDelivery payload = 10;
}

message SetPickupPointRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  SetPickupPoint payload = 10;
}

message CreateCheckoutOrderRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  CreateCheckoutOrder payload = 10;
}

message SetCartItemsRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  SetCartRequest payload = 10;
}

message OrderCompletedRequest {
  string cart_id = 1;
  int64 client_timestamp = 2;
  OrderCreated payload = 10;
}

// -----------------------------------------------------------------------------
// Cart state snapshot (unchanged from v1 except envelope removal context)
// -----------------------------------------------------------------------------
message CartState {
  string cart_id = 1;
  repeated CartItemState items = 2;
  int64 total_price = 3;
  int64 total_tax = 4;
  int64 total_discount = 5;
  repeated DeliveryState deliveries = 6;
  bool payment_in_progress = 7;
  string order_reference = 8;
  string payment_status = 9;
}

message CartItemState {
  int64 id = 1;
  int64 source_item_id = 2;
  string sku = 3;
  string name = 4;
  int64 unit_price = 5;
  int32 quantity = 6;
  int64 total_price = 7;
  int64 total_tax = 8;
  int64 org_price = 9;
  int32 tax_rate = 10;
  int64 total_discount = 11;
  string brand = 12;
  string category = 13;
  string category2 = 14;
  string category3 = 15;
  string category4 = 16;
  string category5 = 17;
  string image = 18;
  string article_type = 19;
  string seller_id = 20;
  string seller_name = 21;
  string disclaimer = 22;
  string outlet = 23;
  string store_id = 24;
  int32 stock = 25;
}

message DeliveryState {
  int64 id = 1;
  string provider = 2;
  int64 price = 3;
  repeated int64 item_ids = 4;
  PickupPoint pickup_point = 5; // Defined in messages.proto
}

// (CheckoutRequest / CheckoutReply removed - checkout handled at HTTP layer)

// -----------------------------------------------------------------------------
// Service definition (per-mutation RPCs + checkout)
// -----------------------------------------------------------------------------
service CartActor {
  rpc AddRequest(AddRequestRequest) returns (CartMutationReply);
  rpc AddItem(AddItemRequest) returns (CartMutationReply);
  rpc RemoveItem(RemoveItemRequest) returns (CartMutationReply);
  rpc RemoveDelivery(RemoveDeliveryRequest) returns (CartMutationReply);
  rpc ChangeQuantity(ChangeQuantityRequest) returns (CartMutationReply);
  rpc SetDelivery(SetDeliveryRequest) returns (CartMutationReply);
  rpc SetPickupPoint(SetPickupPointRequest) returns (CartMutationReply);
  // (Checkout RPC removed - handled externally)
  rpc SetCartItems(SetCartItemsRequest) returns (CartMutationReply);
  rpc OrderCompleted(OrderCompletedRequest) returns (CartMutationReply);

  rpc GetState(StateRequest) returns (StateReply);
}

// -----------------------------------------------------------------------------
// Future enhancements:
// * BatchMutate RPC (repeated heterogeneous mutations)
// * Streaming state updates (WatchState)
// * Versioning / optimistic concurrency control
// -----------------------------------------------------------------------------