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;
}

// Excerpt: updated messages for camelCase JSON output
message CartState {
  string id = 1;                         // was cart_id
  repeated CartItemState items = 2;
  int64 totalPrice = 3;                  // was total_price
  int64 totalTax = 4;                    // was total_tax
  int64 totalDiscount = 5;               // was total_discount
  repeated DeliveryState deliveries = 6;
  bool paymentInProgress = 7;            // was payment_in_progress
  string orderReference = 8;             // was order_reference
  string paymentStatus = 9;              // was payment_status
  bool processing = 10;                  // NEW (mirrors legacy CartGrain.processing)
}

message CartItemState {
  int64 id = 1;
  int64 itemId = 2;                      // was source_item_id
  string sku = 3;
  string name = 4;
  int64 price = 5;                       // was unit_price
  int32 qty = 6;                         // was quantity
  int64 totalPrice = 7;                  // was total_price
  int64 totalTax = 8;                    // was total_tax
  int64 orgPrice = 9;                    // was org_price
  int32 taxRate = 10;                    // was tax_rate
  int64 totalDiscount = 11;
  string brand = 12;
  string category = 13;
  string category2 = 14;
  string category3 = 15;
  string category4 = 16;
  string category5 = 17;
  string image = 18;
  string type = 19;                      // was article_type
  string sellerId = 20;                  // was seller_id
  string sellerName = 21;                // was seller_name
  string disclaimer = 22;
  string outlet = 23;
  string storeId = 24;                   // was store_id
  int32 stock = 25;
}

message DeliveryState {
  int64 id = 1;
  string provider = 2;
  int64 price = 3;
  repeated int64 items = 4;              // was item_ids
  PickupPoint pickupPoint = 5;           // was pickup_point
}

// (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
// -----------------------------------------------------------------------------