harpoon

# Harpoon

Harpoon is an http client framework built on top of Tesla that produces clients that are pluggable, behave predictibly, and can easily be mocked. 

## Installation

If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `harpoon` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:harpoon, github: "ironbay/harpoon"}
    # Optional
    {:fishermane, github: "ironbay/harpoon"}
  ]
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at <https://hexdocs.pm/harpoon>.

## Documentation

Harpoon modules are simply [Tesla](github.com/teamon/tesla) modules.  The only requirement is to pass in `client()` to any HTTP calls.  To enable function mocking use the `hook` macro provided by Fisherman

```elixir
defmodule Harpoon.Example do
  use Harpoon
  import Fisherman

  plug(Harpoon.Response)
  plug(Tesla.Middleware.BaseUrl, "https://jsonplaceholder.typicode.com/")
  plug(Tesla.Middleware.JSON)

  hook todos() do
    get(client(), "/todos")
  end
end
```

Any application referencing this module can inject their own middleware or mock certain functions in the module via Fisherman

```elixir
config :harpoon, %{
  Harpoon.Example => %{
    # Adds middleware to the top
    pre: [Tesla.Middleware.Logger]
    # Adds middleware to the bottom
    post: [],
  },
  # Applies to all Harpoon clients
  :global => %{
  }
}

config :fisherman, %{
  Harpoon.Example => Harpoon.Example.Mock
}
```

If a mock module is specified, any function with matching arity will be called instead.  If `hook_catch/2` is defined it will serve as a catch all for all functions and be passed a function name and list of arguments

```elixir
defmodule Harpoon.Example.Mock do
  require Logger

  def todos() do
    {:ok,
     [
       %{
         "completed" => false,
         "id" => 1,
         "title" => "delectus aut autem",
         "userId" => 1
       },
       %{
         "completed" => true,
         "id" => 2,
         "title" => "quis ut nam facilis et officia qui",
         "userId" => 1
       }
     ]}
  end

  def hook_catch(fun, args) do
    Logger.info(inspect({fun, args}))
  end
end

```

## TODO

## Harpoon Clients

-   [harpoon_twilio](https://github.com/ironbay/harpoon_twilio/)