uma_db_client

# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.7.2] - 2026-08-04

### Added

- `use UmaDbClient, encode: &Jason.encode!/1, decode: &Jason.decode!/1` generates
  a client facade that encodes event payloads on the way in and decodes them on
  the way out, so payloads no longer need encoding at every call site. Both
  options are optional and independent, and each accepts a one-argument
  function, a `{module, function}` tuple, or a module exporting `encode!/1` /
  `decode!/1`. `:raw_data` bypasses the encoder for already-encoded values, and
  passing both `:data` and `:raw_data` raises `ArgumentError`. The facade also
  delegates `connect/2`, `append/3`, `head/1`, `get_tracking_info/2` and the
  `UmaDbClient.Builder` constructors.
- `UmaDbClient.Event` — the struct returned by facade reads and subscriptions,
  with the payload decoded, `metadata` as a plain map, and `uuid` as `nil` when
  absent. An event recorded without a payload reads back as `data: nil`.
  `UmaDbClient.read/2` and `UmaDbClient.subscribe/2` are unchanged and still
  return `UmaDb.V1.SequencedEvent` structs.
- `UmaDb.V1.SequencedEvent` gains an optional `tracking_info` field, added to the
  proto in umadb 0.7.0. Reads and subscriptions now return the tracking cursor
  that was recorded with the append. The change is additive and wire-compatible.
  `UmaDbClient.Event` exposes it as a `%{source: ..., position: ...}` map, or
  `nil` when the event was appended without one.

### Changed

- **BREAKING:** the positional four-argument `Builder.event` is replaced by
  `UmaDbClient.Builder.event/1`, which takes a keyword list. `:type` is required;
  `:tags`, `:data`, `:metadata` and the new `:uuid` are optional. Unknown options
  and a missing `:type` raise `ArgumentError`.

  ```elixir
  # before
  Builder.event("OrderPlaced", ["order:1"], data, %{"user" => "alice"})

  # after
  Builder.event(
    type: "OrderPlaced",
    tags: ["order:1"],
    data: data,
    metadata: %{"user" => "alice"}
  )
  ```

  The new `:uuid` option makes idempotent conditional appends reachable from the
  builder; previously it required constructing a `%UmaDb.V1.Event{}` by hand.

- Track `umadb-proto` 0.7.2, up from 0.6.4. The only schema change in that range
  is the `SequencedEvent.tracking_info` field noted above, introduced in 0.7.0;
  0.7.1 and 0.7.2 are byte-identical to it.

### Fixed

- ExDoc `main` pointed at `UmadbClient` instead of `UmaDbClient`, so the generated
  documentation's landing page redirected to a nonexistent module page.

### Documentation

- Rewrite the README around usage examples: connecting (including TLS), appending
  (idempotent retries and optimistic concurrency), reading and querying,
  subscribing, head and tracking positions, a data-type reference, error handling,
  and end-to-end examples. Also documents current limitations (no API-key auth,
  `read/2` does not surface the head position) and the fact that the streams
  returned by `read/2` and `subscribe/2` are single-use.
- Move the proto regeneration instructions out of the README and into `CLAUDE.md`,
  along with the `Umadb.V1` vs. `UmaDb.V1` module-naming caveat.

## [0.6.7] - 2026-07-24

### Changed

- Track `umadb-proto` 0.6.7. The proto surface (messages, fields, and the five
  `DCB` RPCs) is unchanged from 0.6.4, so there are no wire or public-API changes;
  this release only aligns the client version with the latest UmaDB.

## [0.6.4] - 2026-07-07

### Added

- Initial published release: gRPC client for UmaDB's DCB (Dynamic Consistency
  Boundary) event store, wrapping `UmaDb.V1.DCB.Stub` with `connect/2`, `head/1`,
  `get_tracking_info/2`, `append/3`, `read/2`, and `subscribe/2`, plus
  `UmaDbClient.Builder` convenience constructors.
- Build and publish GitHub Actions workflows.
- MIT license.

[0.7.2]: https://github.com/evntd/uma_db_client/compare/v0.6.7...v0.7.2
[0.6.7]: https://github.com/evntd/uma_db_client/compare/v0.6.4...v0.6.7
[0.6.4]: https://github.com/evntd/uma_db_client/releases/tag/v0.6.4