# `Immich`

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]
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*