path: root/lib/matrix_app_service/client.ex

defmodule MatrixAppService.Client do
  @moduledoc """
  Convenience wrapper around `Polyjuice.Client.LowLevel`.

  Library users can use the wrapped functions or call `user/1` and pass the
  returned struct to Polyjuice functions.
  """

  @type client_options :: {:base_url, String.t()} | MatrixAppService.Client.LowLevel.create_opts()

  @doc """
  Returns a client for the application service.

  By default, the client gets its homeserver URL and access token from configuration.
  Different options can be provided to override the defaults, those are:

  * `:base_url`: homerver URL
  * `:acces_token`: access token
  * `:device_id`: device ID
  * `:user_id`: user ID
  * `:storage`: a `t:Polyjuice.Client.Storage.t/0`
  """
  @spec client([client_options()]) ::
          Polyjuice.Client.LowLevel.t()
  def client(opts \\ []) do
    base_url =
      Keyword.get(opts, :base_url, Application.fetch_env!(:matrix_app_service, :base_url))

    default_opts = [
      access_token: Application.fetch_env!(:matrix_app_service, :access_token),
      device_id: "APP_SERVICE"
    ]

    opts = Keyword.merge(default_opts, opts)

    Polyjuice.Client.LowLevel.create(base_url, opts)
  end

  @doc """
  Creates a Matrix room.

  Arguments:
  1. `options`: see `Polyjuice.Client.Room.create_room/2`
  2. `client_options`: see `client/1`
  """
  @spec create_room(Keyword.t()) :: {:ok, String.t()} | Any
  def create_room(options \\ [], client_options \\ []) do
    client(client_options)
    |> Polyjuice.Client.Room.create_room(options)
  end

  @doc """
  Creates a new alias for a Matrix room.

  Arguments:
  1. `room_id`: room ID
  2. `room_alias`: room alias
  3. `client_options`: see `client/1`
  """
  @spec create_alias(String.t(), String.t(), client_options()) :: {:ok, String.t()} | Any
  def create_alias(room_id, room_alias, client_options \\ []) do
    client(client_options)
    |> Polyjuice.Client.Room.create_alias(room_id, room_alias)
  end

  @doc """
  Sends a message to a Matrix room.

  Arguments:
  1. `room_id`: room ID
  2. `msg`: see `Polyjuice.Client.Room.send_message/3`
  3. `client_options`: see `client/1`
  """
  @spec send_message(String.t(), String.t(), client_options()) :: {:ok, String.t()} | Any
  def send_message(room_id, msg, client_options \\ []) do
    client(client_options)
    |> Polyjuice.Client.Room.send_message(room_id, msg)
  end

  @doc """
  Registers a new Matrix user.

  Arguments:
  1. `opts`: a keyword list that can contain these keys:
     * `:inhibit_login`: true
     * `:device_id`: device ID, defaults to `"APP_SERVICE"`
     * `:initial_device_display_name`: device name, defaults to
       `"ApplicationService"`
     * `:kind`: kind of account to register, defaults to `"user"`, can also be
       `"guest"`
  2. `client_options`: see `client/1`
  """
  @spec register(Polyjuice.Client.LowLevel.register_opts(), client_options()) ::
          {:ok, String.t()} | Any
  def register(opts \\ [], client_options \\ []) do
    default_opts = [
      inhibit_login: true,
      device_id: "APP_SERVICE",
      initial_device_display_name: "Application Service"
    ]

    opts = Keyword.merge(default_opts, opts)

    client(client_options)
    |> Polyjuice.Client.LowLevel.register(opts)
  end
end