namely 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c6c9e3f2c619a62f8ecf845c656d50ff12f025d9
+  data.tar.gz: e17424ee887917ba69dd1928557bb6cd5c64ab02
+SHA512:
+  metadata.gz: 2a9a3dc86ec13b62778feca282add92456013a154dfc8fa5e652a761a9f58350e35ee626184b5bf4aaf60cc47a9d58f56e6aeef156f6204ae16bc58ebdb11a0a
+  data.tar.gz: 5a025299aad278901b62a0fc0a24a4977cb4c56aaee28fcbc93f85c65811e70598c400366a487e872f8a78c2d8a19a4f65baecb577e4de15404d7375da07d297

data/.gitignore

@@ -0,0 +1,3 @@
+.env
+.yardoc
+doc

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 1.9.3
+  - jruby-19mode
+  - 2.0.0
+  - 2.1.3

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    namely (0.0.1)
+      backports
+      rest_client
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.6)
+    backports (3.6.3)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    dotenv (1.0.2)
+    netrc (0.7.9)
+    rake (10.3.2)
+    rest_client (1.8.1)
+      netrc (~> 0.7.7)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+    safe_yaml (1.0.4)
+    vcr (2.9.3)
+    webmock (1.8.7)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+    yard (0.8.7.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  dotenv
+  namely!
+  rake (~> 10.0)
+  rspec
+  vcr
+  webmock
+  yard

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 
+
+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.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Namely
+
+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.

data/README.md

@@ -0,0 +1,125 @@
+# Namely
+
+[![Travis](https://travis-ci.org/namely/ruby-client.svg?branch=master)](https://travis-ci.org/namely/ruby-client/builds)
+[![Code Climate](https://codeclimate.com/github/namely/ruby-client/badges/gpa.svg)](https://codeclimate.com/github/namely/ruby-client)
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "namely"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install namely
+
+## Configuration
+
+You'll need to configure the gem to use your Namely account. Do this
+by setting the `access_token` and `subdomain` variables in a
+configuration block:
+
+```ruby
+Namely.configure do |config|
+  config.access_token = "your_access_token"
+  config.subdomain = "your-organization"
+end
+```
+
+An access token can be obtained through your organization's Namely
+account.
+
+Namely associates a subdomain with your
+organization. organization. For example, if your account is at
+`http://your-organization.namely.com/`, your subdomain would be
+`"your-organization"`.
+
+In a Rails application this configuration belongs in
+`config/initializers/namely.rb`.
+
+## Usage Examples
+
+```ruby
+Namely::Country.all.each do |country|
+  puts "#{country.id} - #{country.name}"
+end
+# AF - Afghanistan
+# AL - Albania
+# DZ - Algeria
+# AS - American Samoa
+# ...
+```
+
+```ruby
+if Namely::Country.exists?("BE")
+  "Belgium exists!"
+else
+  "Hmm."
+end # => "Belgium exists!"
+```
+
+```ruby
+Namely::Country.find("BE")
+# => <Namely::Country 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)"}]}>
+```
+
+```ruby
+foo_bar = Namely::Profile.create!(
+  first_name: "Metasyntactic",
+  last_name: "Variable",
+  email: "foo_bar@namely.com"
+)
+
+foo_bar.id # => "37c919e2-f1c8-4beb-b1d4-a9a36ccc830c"
+```
+
+## Contributing
+
+Wanna help out? Great! Here are a few resources that might help you
+started:
+
+* Documentation on [Namely's HTTP API]
+* Namely tries to stick to the [JSON API standard]. If we're seriously
+  deviating from it, that may well be a bug.
+* For coding style, we like [thoughtbot's style guide]
+
+### Setting up a development environment
+
+The Namely gem uses [dotenv] to manage environment variables. To run
+the tests you'll need to create a `.env` file in the project's root
+directory and assign a few variables in it.
+
+Just take this example `.env` file and 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.
+
+[Namely's HTTP API]: http://namely.readme.io/v1/docs
+[thoughtbot's style guide]: https://github.com/thoughtbot/guides/tree/master/style
+[JSON API standard]: http://jsonapi.org/
+[dotenv]: https://github.com/bkeepers/dotenv
+[Fork it!]: https://github.com/namely/ruby-client/fork

data/Rakefile

@@ -0,0 +1,16 @@
+require "rspec/core/rake_task"
+require "bundler/gem_tasks"
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ["--color"]
+end
+
+task :console do
+  exec "irb -r namely -I ./lib"
+end
+
+task :documentation do
+  exec "yardoc --no-private"
+end
+
+task default: :spec

data/lib/namely.rb

@@ -0,0 +1,114 @@
+require "backports"
+require "json"
+require "ostruct"
+require "rest_client"
+
+require "namely/authenticator"
+require "namely/exceptions"
+require "namely/resource_gateway"
+require "namely/restful_model"
+
+require "namely/country"
+require "namely/currency_type"
+require "namely/event"
+require "namely/field"
+require "namely/job_tier"
+require "namely/profile"
+require "namely/report"
+
+require "namely/version"
+
+module Namely
+  class << self
+    attr_writer :configuration
+  end
+
+  # Return the current configuration.
+  #
+  # @raise [ImproperlyConfiguredError] if the subdomain or access token
+  #   haven't been configured.
+  #
+  # @return [Configuration]
+  def self.configuration
+    @configuration || raise(
+      ImproperlyConfiguredError,
+      "Before using the Namely gem, you'll need to configure it with `Namely.configure`."
+    )
+  end
+
+  # Set the configuration variables (the subdomain and access token)
+  # that allow the Namely gem to access your account.
+  #
+  # @yieldparam [Configuration] configuration the Configuration
+  #   object, the attributes of which can be set in the block.
+  #
+  # @example
+  #   Namely.configure do |config|
+  #     config.access_token = "your_access_token"
+  #     config.subdomain = "your-organization"
+  #   end
+  #
+  # @return [void]
+  def self.configure
+    @configuration ||= Configuration.new
+    yield configuration
+  end
+
+  # Return a resource gateway for interfacing with a given resource.
+  #
+  # @param [String] resource_name
+  # @param [String] endpoint
+  #
+  # @return [ResourceGateway]
+  def self.resource_gateway(resource_name, endpoint)
+    configuration.resource_gateway(resource_name, endpoint)
+  end
+
+  class Configuration
+    attr_writer :access_token, :subdomain
+
+    # Get the access token.
+    #
+    # @raise [ImproperlyConfiguredError] if the access token hasn't
+    #   been configured.
+    #
+    # @return [String] the access token
+    def access_token
+      @access_token || raise_missing_variable_error(:access_token)
+    end
+
+    # Get the subdomain.
+    #
+    # @raise [ImproperlyConfiguredError] if the subdomain hasn't been
+    #   configured.
+    #
+    # @return [String] the subdomain
+    def subdomain
+      @subdomain || raise_missing_variable_error(:subdomain)
+    end
+
+    # Create a resource gateway for interfacing with a given resource.
+    #
+    # @param [String] resource_name
+    # @param [String] endpoint
+    #
+    # @return [ResourceGateway]
+    def resource_gateway(resource_name, endpoint)
+      Namely::ResourceGateway.new(
+        access_token: access_token,
+        endpoint: endpoint,
+        resource_name: resource_name,
+        subdomain: subdomain
+      )
+    end
+
+    private
+
+    def raise_missing_variable_error(variable)
+      raise(
+        ImproperlyConfiguredError,
+        "The Namely `#{variable}` configuration variable hasn't been set... did you set it when you called `Namely.configure`?"
+      )
+    end
+  end
+end

data/lib/namely/authenticator.rb

@@ -0,0 +1,164 @@
+require "cgi"
+
+module Namely
+  class Authenticator
+    # Return a new Authenticator instance.
+    #
+    # @param [Hash] options
+    # @option options [String] client_id
+    # @option options [String] client_secret
+    #
+    # @example
+    #   authenticator = Authenticator.new(
+    #     client_id: "my-client-id",
+    #     client_secret: "my-client-secret"
+    #   )
+    #
+    # @return [Authenticator]
+    def initialize(options)
+      @client_id = options.fetch(:client_id)
+      @client_secret = options.fetch(:client_secret)
+    end
+
+    # Returns a URL to begin the authorization code workflow. If you
+    # provide a redirect_uri you can receive the server's response.
+    #
+    # @param [Hash] options
+    # @option options [String] host (optional)
+    # @option options [String] protocol (optional, defaults to "https")
+    # @option options [String] subdomain (required)
+    # @option options [String] redirect_uri (optional)
+    #
+    # @return [String]
+    def authorization_code_url(options)
+      URL.new(options.merge(
+        path: "/api/v1/oauth2/authorize",
+        params: {
+          response_type: "code",
+          approve: "true",
+          client_id: client_id,
+        },
+      )).to_s
+    end
+
+    # Request an access token and refresh token.
+    #
+    # @param [Hash] options
+    # @option options [String] code (required)
+    # @option options [String] redirect_uri (required)
+    # @option options [String] subdomain (required)
+    #
+    # @example
+    #   authenticator = Authenticator.new(
+    #     client_id: "my-client-id",
+    #     client_secret: "my-client-secret"
+    #   )
+    #
+    #   tokens = authenticator.retrieve_tokens(
+    #     code: "my-code",
+    #     subdomain: "my-subdomain",
+    #     redirect_uri: "my-redirect-uri"
+    #   )
+    #
+    #   tokens["access_token"] # => "my-access-token"
+    #   tokens["refresh_token"] # => "my-refresh-token"
+    #   tokens["expires_in"] # => 1234
+    #   tokens["token_type"] # => "bearer"
+    #
+    # @return [Hash]
+    def retrieve_tokens(options)
+      request_tokens(options, "authorization_code", options.fetch(:code))
+    end
+
+    # Get an updated access token using the refresh token.
+    #
+    # @param [Hash] options
+    # @option options [String] redirect_uri (required)
+    # @option options [String] refresh_token (required)
+    # @option options [String] subdomain (required)
+    #
+    # @example
+    #   authenticator = Authenticator.new(
+    #     client_id: "my-client-id",
+    #     client_secret: "my-client-secret"
+    #   )
+    #
+    #   tokens = authenticator.refresh_access_token(
+    #     redirect_uri: "my-redirect-uri",
+    #     refresh_token: "my-refresh-token",
+    #     subdomain: "my-subdomain"
+    #   )
+    #
+    #   tokens["access_token"] # => "my-access-token"
+    #   tokens["expires_in"] # => 1234
+    #   tokens["token_type"] # => "bearer"
+    #
+    # @return [Hash]
+    def refresh_access_token(options)
+      request_tokens(options, "refresh_token", options.fetch(:refresh_token))
+    end
+
+    private
+
+    attr_reader :client_id, :client_secret
+
+    def request_tokens(options, grant_type, token)
+      response = RestClient.post(
+        URL.new(options.merge(path: "/api/v1/oauth2/token")).to_s,
+        grant_type: grant_type,
+        client_id: client_id,
+        client_secret: client_secret,
+        refresh_token: token,
+      )
+      JSON.parse(response)
+    end
+
+    class URL
+      def initialize(options)
+        @options = options
+      end
+
+      def to_s
+        "#{protocol}://#{host}#{path}?#{query}"
+      end
+
+      private
+
+      attr_reader :options
+
+      def protocol
+        options.fetch(:protocol, "https")
+      end
+
+      def host
+        if options.has_key?(:subdomain)
+          "#{options[:subdomain]}.namely.com"
+        else
+          options.fetch(:host)
+        end
+      end
+
+      def path
+        options.fetch(:path)
+      end
+
+      def query
+        params.
+          map { |key, value| "#{CGI.escape(key.to_s)}=#{CGI.escape(value)}" }.
+          join("&")
+      end
+
+      def params
+        options.fetch(:params, {}).merge(redirect_uri_param)
+      end
+
+      def redirect_uri_param
+        if options.has_key?(:redirect_uri)
+          { redirect_uri: options[:redirect_uri] }
+        else
+          {}
+        end
+      end
+    end
+  end
+end