defmodule Immich do
  @moduledoc """
  Elixir client library for working with the Immich API.

  `Immich` is the top-level namespace for a small set of focused modules that
  cover the core integration workflow:

  - `Immich.API` provides a facade for OAuth login, authenticated user lookup,
    and sync endpoints.
  - `Immich.API.OAuth` handles PKCE generation and token exchange.
  - `Immich.API.Session` represents an authenticated session.
  - `Immich.Sync` offers helpers for consuming and processing sync streams.

  In most applications, start with `Immich.API` and use the lower-level modules
  only when you need finer control.

  ## Example

      redirect_uri = "http://localhost:4000/auth/immich/callback"

      with {:ok, login_url, oauth_context} <- Immich.API.authorize(redirect_uri),
           :ok <- open_browser(login_url),
           {:ok, session} <- Immich.API.callback(received_callback_url, oauth_context),
           {:ok, user} <- Immich.API.current_user(session) do
        IO.inspect(user, label: "Authenticated Immich user")
      end

  After obtaining a session, you can also call `Immich.API.sync_stream/3` and
  `Immich.API.sync_ack/3` to consume and acknowledge sync events.

  ## Sync example

  `Immich.Sync.run/5` can orchestrate the full sync loop for you: stream events,
  process them in chunks, then acknowledge each processed chunk.

      defmodule MyApp.SyncProcessor do
        @behaviour Immich.Sync.EventProcessor

        @impl true
        def process_events(events, _opts) do
          Enum.each(events, fn event ->
            persist_event(event.type, event.data)
          end)

          :ok
        end

        defp persist_event(_type, _data), do: :ok
      end

      # session is an `%Immich.API.Session{}` obtained via OAuth
      event_types = ["AssetsV1", "StacksV1"]

      Immich.Sync.run(
        session,
        event_types,
        Immich.API,
        MyApp.SyncProcessor,
        batch_size: 200,
        event_stream_opts: [reset?: false]
      )
  """
end