defmodule SudregEx do
  @moduledoc """
  Elixir client for the Croatian Court Register (Sudski registar) public
  open-data REST API.

  Access requires free registration at <https://sudreg-data.gov.hr/>, which
  yields OAuth2 `client_id`/`client_secret` credentials (they legitimately end in
  `..`). Authentication uses the OAuth2 client-credentials flow; tokens are valid
  for 6 hours and are cached for you by `SudregEx.TokenCache`.

  > Note: you must **confirm your registration e-mail** (click "Potvrdi") before
  > data calls work — until then the token endpoint issues a token but every
  > endpoint returns `401 Unauthorized`.

  ## Quickstart

      client =
        SudregEx.Client.new(
          client_id: "your-id..",
          client_secret: "your-secret.."
        )

      # one record type for all subjects (paginated)
      {:ok, %SudregEx.Response{data: rows}} =
        SudregEx.Api.subjekti(client, only_active: true, limit: 50)

      # everything about one subject (the API caps this at 6 requests/minute;
      # `SudregEx.RateLimiter` can enforce it client-side)
      {:ok, %SudregEx.Response{data: subject}} =
        SudregEx.Api.detalji_subjekta(client, tip_identifikatora: "oib", identifikator: "12345678901")

      # stream a whole table, pinned to one snapshot for a consistent read
      {:ok, snapshot_id} = SudregEx.Api.latest_snapshot_id(client)

      SudregEx.Api.stream(client, :tvrtke, snapshot_id: snapshot_id)
      |> Stream.map(& &1["ime"])
      |> Enum.take(10)

  ## Where things live

    * `SudregEx.Api` — a function per endpoint (all 39), plus `stream/3` and
      `latest_snapshot_id/2`
    * `SudregEx.Client` — configuration; `SudregEx.Response` / `SudregEx.Error`
      — the result shapes
    * `SudregEx.Format` — zero-pad MBS/OIB, parse the timezone-less timestamp
    * `SudregEx.RateLimiter` — optional client-side throttle for `detalji_subjekta`

  ## Reference

  The OpenAPI spec ships with the package at
  `priv/doc/open_api_javni_v3.json`. The official developer guide (Croatian PDF)
  is in the [repository](https://gitlab.com/banianitc/sudreg_ex) and on the
  [portal](https://sudreg-data.gov.hr/).
  """
end