uma_db_client

defmodule UmaDbClient.Builder do
  @moduledoc """
  Convenience constructors for UmaDB proto message structs.

  These are thin wrappers around the generated `UmaDb.V1.*` structs. You can
  always build structs directly if you prefer.
  """

  alias UmaDb.V1

  @doc """
  Builds an `UmaDb.V1.Event` struct.

  `metadata` is a map or keyword list of `{key, value}` string pairs, each
  converted into an `UmaDb.V1.MetadataEntry`.
  """
  @spec event(String.t(), [String.t()], binary(), Enumerable.t()) :: V1.Event.t()
  def event(type, tags \\ [], data \\ <<>>, metadata \\ []) do
    %V1.Event{
      event_type: type,
      tags: tags,
      data: data,
      metadata: Enum.map(metadata, fn {k, v} -> %V1.MetadataEntry{key: k, value: v} end)
    }
  end

  @doc "Builds a `UmaDb.V1.Query` from a list of `UmaDb.V1.QueryItem` structs."
  @spec query([V1.QueryItem.t()]) :: V1.Query.t()
  def query(items) when is_list(items) do
    %V1.Query{items: items}
  end

  @doc "Builds a `UmaDb.V1.QueryItem` that matches events by type and/or tag."
  @spec query_item([String.t()], [String.t()]) :: V1.QueryItem.t()
  def query_item(types \\ [], tags \\ []) do
    %V1.QueryItem{types: types, tags: tags}
  end

  @doc """
  Builds an `UmaDb.V1.AppendCondition` for optimistic concurrency.

  ## Options

  - `:fail_if_events_match` — `UmaDb.V1.Query`; the append fails if any matching event exists
  - `:after` — only consider events after this position when evaluating the condition
  """
  @spec append_condition(keyword()) :: V1.AppendCondition.t()
  def append_condition(opts \\ []) do
    %V1.AppendCondition{
      fail_if_events_match: Keyword.get(opts, :fail_if_events_match),
      after: Keyword.get(opts, :after)
    }
  end

  @doc "Builds an `UmaDb.V1.TrackingInfo` to advance a named tracking cursor on append."
  @spec tracking_info(String.t(), non_neg_integer()) :: V1.TrackingInfo.t()
  def tracking_info(source, position) do
    %V1.TrackingInfo{source: source, position: position}
  end
end