# UmadbClient

An Elixir gRPC client for [UmaDB](https://umadb.io)'s DCB (Dynamic Consistency
Boundary) event store service. It wraps the generated `UmaDb.V1.DCB.Stub` with a
small, ergonomic API for appending events, reading and subscribing to event
streams, querying by type and tags, tracking consumer positions, and optimistic
concurrency control — plus `UmaDbClient.Builder` convenience constructors for the
underlying proto message structs.

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `umadb_client` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:umadb_client, "~> 0.6.4"}
  ]
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at <https://hexdocs.pm/umadb_client>.

## Regenerating `uma_db.pb.ex` from the proto

`lib/uma_db/v1/uma_db.pb.ex` is generated from the `umadb.proto` definition
published in the [`umadb-proto`](https://crates.io/crates/umadb-proto) crate.
When that proto changes, regenerate the module as follows.

### Prerequisites (one-time)

- [`protoc`](https://grpc.io/docs/protoc-installation/) — the Protocol Buffers
  compiler.
- The Elixir protobuf plugin, installed as an escript on your `PATH`:

  ```bash
  mix escript.install hex protobuf
  # ensure ~/.mix/escripts is on your PATH
  ```

### Steps

1. Fetch the target proto version. The source of truth is the `umadb-proto`
   crate; grab the version you want from crates.io and extract it:

   ```bash
   VERSION=0.6.4
   curl -sSL "https://crates.io/api/v1/crates/umadb-proto/${VERSION}/download" \
     -H "User-Agent: umadb-client-dev" -o "/tmp/umadb-proto-${VERSION}.crate"
   tar xzf "/tmp/umadb-proto-${VERSION}.crate" -C /tmp
   # proto now at /tmp/umadb-proto-${VERSION}/proto/v1/umadb.proto
   ```

   (If you already have the crate locally, e.g. via a Rust build, it lives under
   `~/.cargo/registry/src/*/umadb-proto-${VERSION}/proto/v1/umadb.proto`.)

2. Run `protoc` to generate the Elixir module:

   ```bash
   protoc --elixir_out=plugins=grpc:./lib \
          --proto_path="/tmp/umadb-proto-${VERSION}/proto" \
          v1/umadb.proto
   ```

3. `protoc` writes to `lib/v1/umadb.pb.ex` (following the proto path). Move it
   into this project's layout and update the header comment with the proto
   version:

   ```bash
   mv lib/v1/umadb.pb.ex lib/uma_db/v1/uma_db.pb.ex
   rmdir lib/v1 2>/dev/null || true
   ```

4. Format and verify:

   ```bash
   mix format
   mix compile
   mix test
   ```

If the proto adds or changes fields, also update the hand-written convenience
constructors in `lib/uma_db_client/builder.ex` and the public API in
`lib/uma_db_client.ex` to surface them.