go-cart-actor/README.md

# Go Cart Actor

A distributed cart management system using the actor model pattern.

## Prerequisites

- Go 1.24.2+
- Protocol Buffers compiler (`protoc`)
- protoc-gen-go and protoc-gen-go-grpc plugins

### Installing Protocol Buffers

On Windows:
```powershell
winget install protobuf
```

On macOS:
```bash
brew install protobuf
```

On Linux:
```bash
# Ubuntu/Debian
sudo apt install protobuf-compiler

# Or download from: https://github.com/protocolbuffers/protobuf/releases
```

### Installing Go protobuf plugin

```bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
```

## Working with Protocol Buffers

### Generating Go code from proto files

After modifying any proto (`proto/messages.proto`, `proto/cart_actor.proto`, `proto/control_plane.proto`), regenerate the Go code (all three share the unified `messages` package):

```bash
cd proto
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       messages.proto cart_actor.proto control_plane.proto
```

### Protocol Buffer Messages

The `proto/messages.proto` file defines the following message types:

- `AddRequest` - Add items to cart (includes quantity, sku, country, optional storeId)
- `SetCartRequest` - Set entire cart contents
- `AddItem` - Complete item information for cart
- `RemoveItem` - Remove item from cart
- `ChangeQuantity` - Update item quantity
- `SetDelivery` - Configure delivery options
- `SetPickupPoint` - Set pickup location
- `PickupPoint` - Pickup point details
- `RemoveDelivery` - Remove delivery option
- `CreateCheckoutOrder` - Initiate checkout
- `OrderCreated` - Order creation response

### Building the project

```bash
go build .
```

### Running tests

```bash
go test ./...
```

## HTTP API Quick Start (curl Examples)

Assuming the service is reachable at http://localhost:8080 and the cart API is mounted at /cart.
Most endpoints use an HTTP cookie named `cartid` to track the cart. The first request will set it.

### 1. Get (or create) a cart
```bash
curl -i http://localhost:8080/cart/
```
Response sets a `cartid` cookie and returns the current (possibly empty) cart JSON.

### 2. Add an item by SKU (implicit quantity = 1)
```bash
curl -i --cookie-jar cookies.txt http://localhost:8080/cart/add/TEST-SKU-123
```
Stores cookie in `cookies.txt` for subsequent calls.

### 3. Add an item with explicit payload (country, quantity)
```bash
curl -i --cookie cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"sku":"TEST-SKU-456","quantity":2,"country":"se"}' \
  http://localhost:8080/cart/
```

### 4. Change quantity of an existing line
(First list the cart to find `id` of the line; here we use id=1 as an example)
```bash
curl -i --cookie cookies.txt \
  -X PUT -H "Content-Type: application/json" \
  -d '{"id":1,"quantity":3}' \
  http://localhost:8080/cart/
```

### 5. Remove an item
```bash
curl -i --cookie cookies.txt -X DELETE http://localhost:8080/cart/1
```

### 6. Set entire cart contents (overwrites items)
```bash
curl -i --cookie cookies.txt \
  -X POST -H "Content-Type: application/json" \
  -d '{"items":[{"sku":"TEST-SKU-AAA","quantity":1,"country":"se"},{"sku":"TEST-SKU-BBB","quantity":2,"country":"se"}]}' \
  http://localhost:8080/cart/set
```

### 7. Add a delivery (provider + optional items)
If `items` is empty or omitted, all items without a delivery get this one.
```bash
curl -i --cookie cookies.txt \
  -X POST -H "Content-Type: application/json" \
  -d '{"provider":"standard","items":[1,2]}' \
  http://localhost:8080/cart/delivery
```

### 8. Remove a delivery by deliveryId
```bash
curl -i --cookie cookies.txt -X DELETE http://localhost:8080/cart/delivery/1
```

### 9. Set a pickup point for a delivery
```bash
curl -i --cookie cookies.txt \
  -X PUT -H "Content-Type: application/json" \
  -d '{"id":"PUP123","name":"Locker 5","address":"Main St 1","city":"Stockholm","zip":"11122","country":"SE"}' \
  http://localhost:8080/cart/delivery/1/pickupPoint
```

### 10. Checkout (returns HTML snippet from Klarna)
```bash
curl -i --cookie cookies.txt http://localhost:8080/cart/checkout
```

### 11. Using a known cart id directly (bypassing cookie)
If you already have a cart id (e.g. 1720000000000000):
```bash
CART_ID=1720000000000000
curl -i http://localhost:8080/cart/byid/$CART_ID
curl -i -X POST -H "Content-Type: application/json" \
  -d '{"sku":"TEST-SKU-XYZ","quantity":1,"country":"se"}' \
  http://localhost:8080/cart/byid/$CART_ID
```

### 12. Clear cart cookie (forces a new cart on next request)
```bash
curl -i --cookie cookies.txt -X DELETE http://localhost:8080/cart/
```

Tip: Use `--cookie-jar` and `--cookie` to persist the session across multiple commands:
```bash
curl --cookie-jar cookies.txt http://localhost:8080/cart/
curl --cookie cookies.txt http://localhost:8080/cart/add/TEST-SKU-123
```

## Important Notes

- Always regenerate protobuf Go code after modifying any `.proto` files (messages/cart_actor/control_plane)
- The generated `messages.pb.go` file should not be edited manually
- Make sure your PATH includes the protoc-gen-go binary location (usually `$GOPATH/bin`)