From 745b7d5980468c46156e3cf1c6004c394b296dbc Mon Sep 17 00:00:00 2001 From: Anthony Chen Date: Wed, 21 Feb 2018 09:23:59 -0800 Subject: [PATCH] docs(readme): adds configuration instructions, contributing, license (#13) --- CONTRIBUTING.md | 19 ++++++++++++++ LICENSE.txt | 22 ++++++++++++++++ README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE.txt diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ef646a2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,19 @@ +# How to Contribute + +We welcome contributions from the community and are pleased to have them. Please follow this guide when logging issues or making code changes. + +Make sure you have Elixir 1.4 or greater installed. Copy and paste the following commands in your projects directory. + + git clone https://github.com/lob/lob-elixir.git + cd lob-elixir + mix deps.get + +## Contributing Instructions + +1. Fork repo. +2. Create your feature branch (`git checkout -b my-new-feature`). +3. Commit your changes (`git commit -am 'Add some feature'`). +4. Push to the branch (`git push origin my-new-feature`). +5. Make sure the tests pass (`mix coveralls.html`). +6. Open up `cover/excoveralls.html` in your browser and add tests if required to meet the minimum coverage threshold. +7. Create new Pull Request. diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..584636d --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,22 @@ +Copyright (c) 2018 Lob.com + +MIT License + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index fedb67a..ee4555b 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ # lob_elixir (alpha) [![Build Status](https://travis-ci.org/lob/lob-elixir.svg?branch=master)](https://travis-ci.org/lob/lob-elixir) +[![Hex.pm](https://img.shields.io/hexpm/v/lob_elixir.svg)](https://hex.pm/packages/lob_elixir) [![Coverage Status](https://coveralls.io/repos/github/lob/lob-elixir/badge.svg?branch=master)](https://coveralls.io/github/lob/lob-elixir?branch=master) +[![Libraries.io for releases](https://img.shields.io/librariesio/release/hex/lob_elixir.svg)](https://libraries.io/hex/lob_elixir) -Elixir Library for [Lob API](https://lob.com/) +Elixir library for [Lob API](https://lob.com/). ### This is an ALPHA library for the Lob API. @@ -20,3 +22,68 @@ def deps do ] end ``` + +## Getting Started + +This library implements the Lob API. Please read through the official [API Documentation](#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](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_KEY` environment variable. + +```elixir +# Configuring an API key with configs +config :lob_elixir, + api_key: "your_api_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: + + mix test + +To run tests with a coverage report: + + mix coveralls.html + +Then view the report at `cover/excoveralls.html`. + +======================= + +Copyright © 2018 Lob.com + +Released under the MIT License, which can be found in the repository in [`LICENSE.txt`](LICENSE.txt).