# hipchat_elixir


HipChat client library for [Elixir](

- [API Documentation](
- Generated from HipChat Swagger API specifications in [ymtszw/hipchat_swagger](

Depends on `hackney` for HTTP client.

# Status

Basic chat related APIs (CRUD operation of rooms/users, sending messages/notifications) are covered.

Add-on (extension) related APIs are yet to be covered.

# Policy

- No state. Access tokens and other credentials should be retrieved/stored by caller applications.
    - Although, `hackney` application does have some states.
- Relying HipChat cloud/server for parameter validations.
- Cover APIs used in server side only.

# Basic Usage

0. Add [`:hipchat_elixir`]( as a dependency.
1. Create client struct (``).
    - Pass `access_token` if the targeted API requires authentication.
    - `access_token` can be one of four types (according to
      [the doc](
        - Add-on token
        - User token
        - Personal access token
        - Room notification token
    - See below for more
2. Pass the resultant client and other parameters to the targeted API function.

  |> Hipchat.V2.Rooms.send_room_notification("room_id", %{message: "Hello HipChat!"})
  # {:ok, %Hipchat.Httpc.Response{body: "", headers: ..., status: 204}}

# About `access_token`s

See [here]( for complete coverage.
Though a little explanations will not hurt so here they are:

## Add-on token or User token Retrieval

They are automatically generated and retrieved after installations (in case of User tokens, upon users' approval, at least) .

To do that with this library:

0. Prepare your Add-on server with:
    - [Installation Flow]( handling logics,
      which involves:
        - Capability descriptor endpoint URL
        - Stable storage for `client_id` and `client_secret` per installation
    - (For User token) Callback URL to which users are redirected after approval
1. Create an OAuth client struct (``) with generated `client_id` and `client_secret`.
2. Create a body which must include `grant_type` and other requirements.
    - `grant_type` should be:
        - `client_credentials` for Add-on token
        - `authorization_code` for initial retrieval of User tokens
        - `refresh_token` for refreshing User tokens
    - See [here]( for details.
3. Request with OAuth Sessions API function.

  ```elixir"client_id", "client_secret")
  |> Hipchat.V2.OauthSessions.generate_token(%{grant_type: "client_credentials", scope: "send_notification"})
  # {:ok, %Hipchat.Httpc.Response{body: "<should contain access_token>", headers: ..., status: 200}}

4. Your server have to store generated `access_token`s (and `refresh_token`s) for later uses. If they expire, re-generate or refresh.

## User generated tokens

After logging in to HipChat, you can manually generate Personal Access Tokens with arbitrary access `scope`s,
or room-only Notification Tokens.

They are convenient because,
(1) they do not require automatic installation logics on your server and,
(2) they are semi-permanent (year-long expiration as of 2016/12).

If you just need notifications or other limited-scope actions in your Add-on or Bots,
they come in very handy.

**Be sure to properly control visibility of those tokens**.
They must be visible only to their owners and trusted third parties, as with any other similar API credentials out in the world.

# Code generation

This library codes are generated from [ymtszw/hipchat_swagger](, with below rules:

- Treat each API's:
    - `summary` as identifiers (i.e. source of function names), with lower-casing and underscoring.
    - `description` as `@doc` contents, though expecting only links to official API docs.
    - `tags` as API categories, with camel-casing. They are used for separating modules (files). Expecting only **one** tag per API.
- Basically discarding parameters' schema/type information, at least currently.
- Response information are discarded too.
- Request bodies are sent as formdata. Since `hackney` can send key-value data list as formdata by itself.
    - To send as JSONs, we must introduce some JSON serializer library, which could be `poison`, `jsone` or whatever, depending on users.
      I want to reduce the number of runtime dependencies.

# Todo

- [x] Generate basic APIs.
- [ ] Generate Add-on specific APIs.
- [x] Helper client for handling OAuth client ID and secrets to retrieve short-lived Add-on token or User token.
    - Ready to be used. See `Hipchat.OauthClient`.

# License