Project

namely

0.03
No release in over 3 years
Low commit activity in last 3 years
Wraps the Namely HTTP API in lovely Ruby.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.7
>= 0
~> 10.0
>= 0
>= 0
>= 0

Runtime

 Project Readme

Namely

Codacy Badge Codacy Badge Travis Code Climate

The Namely gem wraps the Namely HTTP API, allowing you to manipulate your account through Ruby.

Installation

Add this line to your application's Gemfile:

gem "namely"

And then execute:

$ bundle

Or install it yourself as:

$ gem install namely

Establishing a connection

First, you'll need to create a connection to your Namely account using your access token and subdomain.

namely = Namely::Connection.new(
  access_token: "your_access_token",
  subdomain: "your-organization",
)

An access token can be obtained through your organization's Namely account.

Namely associates a subdomain with your organization. For example, if your account is at http://your-organization.namely.com/, your subdomain would be "your-organization".

Configuration

You can override default configuration using Namely.configuration like:

Namely.configuration do |config|

  # While returning paged results, which http codes should be rescued and
  # retried? Defaults to none.
  config.http_codes_to_retry = [504] # gateway timeout

  # The number of times to retry the requests rescued above. Default is 0
  config.retries = 2
end

Usage Examples

Once you've created a connection you can use it to access your data.

namely.countries.all.each do |country|
  puts "#{country.id} - #{country.name}"
end
# AF - Afghanistan
# AL - Albania
# DZ - Algeria
# AS - American Samoa
# ...
if namely.countries.exists?("BE")
  "Belgium exists!"
else
  "Hmm."
end # => "Belgium exists!"
namely.countries.find("BE")
# => <Namely::Model id="BE", name="Belgium", subdivision_type="Province", links={"subdivisions"=>[{"id"=>"BRU", "name"=>"Brussels"}, {"id"=>"VAN", "name"=>"Antwerpen (nl)"}, {"id"=>"VBR", "name"=>"Vlaams Brabant (nl)"}, {"id"=>"VLI", "name"=>"Limburg (nl)"}, {"id"=>"VOV", "name"=>"Oost-Vlaanderen (nl)"}, {"id"=>"VWV", "name"=>"West-Vlaanderen (nl)"}, {"id"=>"WBR", "name"=>"Brabant Wallon (fr)"}, {"id"=>"WHT", "name"=>"Hainaut (fr)"}, {"id"=>"WLG", "name"=>"Liège (fr)"}, {"id"=>"WLX", "name"=>"Luxembourg (fr)"}, {"id"=>"WNA", "name"=>"Namur (fr)"}]}>
foo_bar = namely.profiles.create!(
  first_name: "Dade",
  last_name: "Murphy",
  email: "crash_override@example.com"
)

foo_bar.id # => "37c919e2-f1c8-4beb-b1d4-a9a36ccc830c"

Contributing

Wanna help out? Great! Here are a few resources that might help you started:

Setting up a development environment

After you have cloned this repo, run this setup script to set up your machine with the necessary dependencies to run and test this app:

% ./bin/setup

The Namely gem uses dotenv to manage environment variables. Visit the .env file and change a plug in appropriate values:

TEST_ACCESS_TOKEN=my-sample-access-token
TEST_SUBDOMAIN=my-sample-subdomain

You'll need admin access to a Namely site to get tokens for these variables. You can create application and permanent tokens on the API page of the site.

Submitting your changes

  1. Fork it!
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am "Add some feature"). Be sure to include tests!
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new pull request. We'll review it and leave feedback for you ASAP.