ex_immich

ex_immich is an Elixir library for interacting with the Immich API.

Status

This project is currently in early development (0.2.0) and the public API may change.

Installation

Add ex_immich to your dependencies in mix.exs:

def deps do
  [
    {:ex_immich, "~> 0.2.0"}
  ]
end

Then fetch dependencies:

mix deps.get

Usage

The main entry point is Immich.API, which covers the common flow:

1. Start OAuth with authorize/2
2. Complete login callback with callback/3
3. Use the returned %Immich.API.Session{} for authenticated API calls

Basic API flow

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

Sync processing flow

Use Immich.Sync.run/5 when you want a full stream -> process -> acknowledge pipeline.

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

Modules of interest:

• Immich.API - OAuth facade and authenticated endpoints
• Immich.API.OAuth - PKCE and token exchange details
• Immich.API.Session - authenticated session struct
• Immich.Sync - callback-driven sync orchestration

Development

Run tests with:

mix test