# Elixir MediaWiki client

Unofficial client modules for connecting to Wikipedia, Wikidata, and other MediaWiki sites from Elixir code.  Supports multiple APIs: Action, EventStreams, and Scoring.

API reference for the current version: [Documentation and examples](https://hexdocs.pm/mediawiki_client/api-reference.html)

Overview:
* `Wiki.Action` is the primary read/write interface for wikis, connecting to the
[Action API](https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page).
This is a rich set of commands to query or edit almost anything on a wiki.
* `Wiki.EventStreams` is a real-time
[EventStreams](https://wikitech.wikimedia.org/wiki/Event_Platform/EventStreams)
feed allowing an application to process edits as they happen.
* `Wiki.Ores` is a [scoring service](https://www.mediawiki.org/wiki/ORES)
for estimating revision and edit quality.

## Installation

Install this package by adding `mediawiki_client` to your dependencies in `mix.exs`,

```elixir
def deps do
  [
    {:mediawiki_client, "~> 0.3"}
  ]
end
```

Documentation is generated with `mix docs`.

## Updating

The [change log](CHANGELOG.md) will have information about new features and any
breaking changes.  Expect the interfaces to evolve until the 1.0 release is reached.

## Usage

Fetch some statistics about German Wikipedia,

```elixir
Wiki.SiteMatrix.new()
|> Wiki.SiteMatrix.get!("dewiki")
|> Wiki.Action.new()
|> Wiki.Action.get!(
  action: :query,
  meta: :siteinfo,
  siprop: :statistics
)
# %Wiki.Action.Session{
#   ...
#   result: %{
#     "batchcomplete" => true,
#     "query" => %{
#       "statistics" => %{
#         "activeusers" => 19687,
#         "admins" => 188,
#         "articles" => 2583285,
#         "edits" => 211219883,
#         "images" => 130199,
#         "jobs" => 0,
#         "pages" => 7163473,
#         "queued-massmessages" => 0,
#         "users" => 3715461
#       }
#     }
#   },
#   ...
# }
```

See the module documentation for more examples.

### Error handling

Methods come in an assertive and a non-assertive form, for example the
`Wiki.Action.get()` method returns an `{:ok, ...}` or a `{:error, ...}` tuple, and
the `Wiki.Action.get!()` method raises an error directly.

### Configuration

Configuration variables (TODO: refactor away from config) under the
`:mediawiki_client` application will override the built-in adapters.

* `:ores_endpoint` - API endpoint for `Wiki.Ores`.
* `:tesla_adapter` - Defaults to `Tesla.Adapter.Hackney`, a stable client which
performs certificate validation.
* `:user_agent` - Sent in request headers, defaults to `mediawiki_client_ex/<version>`...

For example:

```elixir
config :mediawiki_client,
  # HTTP client to use for EventStreams.  Defaults to `HTTPoison`.
  eventsource_adapter: Wiki.Tests.HTTPoisonMock,
  # API endpoint for `Wiki.EventStreams`.  Defaults to 
  eventstream_endpoint:
  tesla_adapter: Wiki.Tests.TeslaAdapterMock,
  ores_endpoint: "https://ores.test/v3/scores/",
```

## Development

Find the [project homepage](https://gitlab.com/adamwight/mediawiki_client_ex) on GitLab.
To contribute, feel free to write an issue, push a merge request, or contact the author.

Several linters are configured, these are called on `git push`.  To install hooks:

```shell script
mix git_hooks.install
```

To push without running tests call `git push --no-verify`, but please don't do this on the main branch.

To generate a test coverage report,
```shell script
mix coveralls.html
```