lob_elixir

Elixir library for Lob API.

Installation

The package can be installed by adding :lob_elixir to your list of dependencies in mix.exs:

def deps do
  [
    {:lob_elixir, "~> 1.5.0"}
  ]
end

Getting Started

This library implements the Lob API. Please read through the official API Documentation 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. Once you have created an account, you can access your API Keys from the Settings Panel.

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.

# 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:

# 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.

# 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.

# 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 file.

Testing

Tests are written using ExUnit, 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.