https://github.com/lob/lob-elixir
Elixir Library for Lob API
https://github.com/lob/lob-elixir
Last synced: 23 days ago
JSON representation
Elixir Library for Lob API
- Host: GitHub
- URL: https://github.com/lob/lob-elixir
- Owner: lob
- License: mit
- Created: 2017-10-06T21:53:49.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2023-04-20T17:59:40.000Z (about 2 years ago)
- Last Synced: 2025-04-25T00:42:50.164Z (about 1 month ago)
- Language: Elixir
- Homepage: https://lob.com
- Size: 1.36 MB
- Stars: 16
- Watchers: 58
- Forks: 11
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# lob_elixir
[](https://travis-ci.org/lob/lob-elixir)
[](https://coveralls.io/github/lob/lob-elixir?branch=master)
[](https://hex.pm/packages/lob_elixir)
[](https://hexdocs.pm/lob_elixir/)
[](https://hex.pm/packages/lob_elixir)
[](https://github.com/lob/lob_elixir/blob/master/LICENSE)
[](https://github.com/lob/lob-elixir/commits/master)
Elixir library for [Lob API](https://lob.com/).
## Installation
The package can be installed by adding `:lob_elixir` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:lob_elixir, "~> 1.5.0"}
]
end
```
## Getting Started
This library implements the Lob API. Please read through the official [API Documentation](https://docs.lob.com/) to get a complete sense of what to expect from each endpoint.
### Registration
The library requires a valid Lob API key to work properly. To acquire an API key, first create an account at [Lob.com](https://dashboard.lob.com/#/register). Once you have created an account, you can access your API Keys from the [Settings Panel](https://dashboard.lob.com/#/settings).
### API Key Configuration
The library will by default refer to the `:api_key` config when making authenticated requests. If that is not present, it will look for the `LOB_API_TEST_KEY` environment variable.
```elixir
# Configuring an API key with configs
config :lob_elixir,
api_key: "your_api_key"
```
The `{:system, "ENV_VAR"}` syntax is also supported, allowing the API key to be fetched at runtime. For example, if the API key is stored in an environment variable named `LOB_KEY`, the library could be configured with:
```elixir
# Configuring an API key with configs
config :lob_elixir,
api_key: {:system, "LOB_KEY"}
```
Similarly, the library allows users to optionally configure the API version through the `:api_version` config. If that is not present, it will look for the `LOB_API_VERSION` environment variable.
```elixir
# Configuring an API key and API version with configs
config :lob_elixir,
api_key: "your_api_key",
api_version: "2014-12-18"
```
### Usage
Requests return a 2-tuple or 3-tuple, depending on the response.
```elixir
# Successful response
{:ok, postcards, _headers} = Postcard.list()
# Unsuccessful response
{:error, %{message: ":nxdomain"}} = Postcard.list()
# Unsuccessful response with status code
{:error, %{message: "postcard not found", status_code: 404}} = Postcard.retrieve('nonexistent_resource')
```
## Contributing
To contribute, please see the [`CONTRIBUTING.md`](CONTRIBUTING.md) file.
## Testing
Tests are written using [ExUnit](https://hexdocs.pm/ex_unit/ExUnit.html), Elixir's built-in test framework.
Here's how you can run the tests:
LOB_API_TEST_KEY=YOUR_TEST_API_KEY mix test
To run tests with a coverage report:
LOB_API_TEST_KEY=YOUR_TEST_API_KEY mix coveralls.html
Then view the report at `cover/excoveralls.html`.
=======================
Copyright © 2021 Lob.com
Released under the MIT License, which can be found in the repository in [`LICENSE.txt`](LICENSE.txt).