namely 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c6c9e3f2c619a62f8ecf845c656d50ff12f025d9
-  data.tar.gz: e17424ee887917ba69dd1928557bb6cd5c64ab02
+  metadata.gz: a5bb34f16c66dc6a4c03d22c8001877df63c1596
+  data.tar.gz: 6d524bf7b582e3400b69501d7f3c765b47471ab3
 SHA512:
-  metadata.gz: 2a9a3dc86ec13b62778feca282add92456013a154dfc8fa5e652a761a9f58350e35ee626184b5bf4aaf60cc47a9d58f56e6aeef156f6204ae16bc58ebdb11a0a
-  data.tar.gz: 5a025299aad278901b62a0fc0a24a4977cb4c56aaee28fcbc93f85c65811e70598c400366a487e872f8a78c2d8a19a4f65baecb577e4de15404d7375da07d297
+  metadata.gz: e4a363d03f16638af12ce7a2e375eb0e24f2cc6b479a97ec4c6363a455153f463fdabe13b0be46e340d6990ac24679356db22016f07c7b2e0bb33f6d1cbdba78
+  data.tar.gz: b03735ea330318c229197c12135f6470d119e6178844afcae57e834d8873dd5daeacab625ee02e184d50f7f7181104959ba2470467430e4faec2cd0ff476cb30

data/README.md

@@ -3,7 +3,8 @@
 [![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
+The Namely gem wraps the Namely HTTP API, allowing you to manipulate
+your account through Ruby.
 
 ## Installation
 
@@ -21,34 +22,31 @@ Or install it yourself as:
 
     $ gem install namely
 
-## Configuration
+## Establishing a connection
 
-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:
+First, you'll need to create a connection to your Namely account using
+your access token and subdomain.
 
 ```ruby
-Namely.configure do |config|
-  config.access_token = "your_access_token"
-  config.subdomain = "your-organization"
-end
+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. 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`.
+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"`.
 
 ## Usage Examples
 
+Once you've created a connection you can use it to access your data.
+
 ```ruby
-Namely::Country.all.each do |country|
+namely.countries.all.each do |country|
   puts "#{country.id} - #{country.name}"
 end
 # AF - Afghanistan
@@ -59,7 +57,7 @@ end
 ```
 
 ```ruby
-if Namely::Country.exists?("BE")
+if namely.countries.exists?("BE")
   "Belgium exists!"
 else
   "Hmm."
@@ -67,15 +65,15 @@ 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)"}]}>
+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)"}]}>
 ```
 
 ```ruby
-foo_bar = Namely::Profile.create!(
-  first_name: "Metasyntactic",
-  last_name: "Variable",
-  email: "foo_bar@namely.com"
+foo_bar = namely.profiles.create!(
+  first_name: "Dade",
+  last_name: "Murphy",
+  email: "crash_override@example.com"
 )
 
 foo_bar.id # => "37c919e2-f1c8-4beb-b1d4-a9a36ccc830c"

data/lib/namely.rb

@@ -6,109 +6,10 @@ 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/collection"
+require "namely/connection"
 
 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

@@ -67,7 +67,11 @@ module Namely
     #
     # @return [Hash]
     def retrieve_tokens(options)
-      request_tokens(options, "authorization_code", options.fetch(:code))
+      request_tokens(
+        options,
+        grant_type: "authorization_code",
+        code: options.fetch(:code),
+      )
     end
 
     # Get an updated access token using the refresh token.
@@ -95,24 +99,66 @@ module Namely
     #
     # @return [Hash]
     def refresh_access_token(options)
-      request_tokens(options, "refresh_token", options.fetch(:refresh_token))
+      request_tokens(
+        options,
+        grant_type: "refresh_token",
+        refresh_token: options.fetch(:refresh_token),
+      )
+    end
+
+    # Return the profile of the user accessing the API.
+    #
+    # @param [Hash] options
+    # @option options [String] access_token (required)
+    # @option options [String] subdomain (required)
+    #
+    # @return [Model] the profile of the current user.
+    def current_user(options)
+      access_token = options.fetch(:access_token)
+      subdomain = options.fetch(:subdomain)
+
+      user_url = URL.new(options.merge(
+        params: {
+          access_token: access_token,
+        },
+        path: "/api/v1/profiles/me",
+      )).to_s
+
+      response = RestClient.get(
+        user_url,
+        accept: :json,
+      )
+      build_profile(
+        access_token,
+        subdomain,
+        JSON.parse(response)["profiles"].first
+      )
     end
 
     private
 
     attr_reader :client_id, :client_secret
 
-    def request_tokens(options, grant_type, token)
+    def request_tokens(url_options, post_params)
       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,
+        URL.new(url_options.merge(path: "/api/v1/oauth2/token")).to_s,
+        {
+          client_id: client_id,
+          client_secret: client_secret,
+        }.merge(post_params),
       )
       JSON.parse(response)
     end
 
+    def build_profile(access_token, subdomain, attributes)
+      profile_gateway = ResourceGateway.new(
+        access_token: access_token,
+        endpoint: "profiles",
+        subdomain: subdomain,
+      )
+      Model.new(profile_gateway, attributes)
+    end
+
     class URL
       def initialize(options)
         @options = options
@@ -149,14 +195,15 @@ module Namely
       end
 
       def params
-        options.fetch(:params, {}).merge(redirect_uri_param)
+        options.fetch(:params, {}).merge(optional_params)
       end
 
-      def redirect_uri_param
-        if options.has_key?(:redirect_uri)
-          { redirect_uri: options[:redirect_uri] }
-        else
-          {}
+      def optional_params
+        [:redirect_uri, :state].inject({}) do |additional_params, key|
+          if options.has_key?(key)
+            additional_params[key] = options[key]
+          end
+          additional_params
         end
       end
     end

data/lib/namely/collection.rb

@@ -0,0 +1,78 @@
+require_relative "model"
+
+module Namely
+  class Collection
+    def initialize(resource_gateway)
+      @resource_gateway = resource_gateway
+    end
+
+    # Return every instance of this model.
+    #
+    # A model might have quite a few instances. If this is the case,
+    # the query may take some time (several seconds) and the resulting
+    # array may be very large.
+    #
+    # @return [Array<Model>]
+    def all
+      resource_gateway.json_index.map { |model| build(model) }
+    end
+
+    # Instantiate (but don't save) a new Model with the given attributes.
+    #
+    # @param [Hash] attributes the attributes of the model being built.
+    #
+    # @return [Model]
+    def build(attributes)
+      Model.new(resource_gateway, attributes)
+    end
+
+    # Create a new Model on the server with the given attributes.
+    #
+    # @param [Hash] attributes the attributes of the model being created.
+    #
+    # @example
+    #   profiles_collection.create!(
+    #     first_name: "Beardsly",
+    #     last_name: "McDog",
+    #     email: "beardsly@namely.com"
+    #   )
+    #
+    # @return [Model] the created model.
+    def create!(attributes)
+      build(attributes).save!
+    end
+
+    def endpoint
+      resource_gateway.endpoint
+    end
+
+    # Returns true if a Model with this ID exists, false otherwise.
+    #
+    # @param [#to_s] id
+    #
+    # @return [Boolean]
+    def exists?(id)
+      resource_gateway.show_head(id)
+      true
+    rescue RestClient::ResourceNotFound
+      false
+    end
+
+    # Fetch a model from the server by its ID.
+    #
+    # @param [#to_s] id
+    #
+    # @raise [NoSuchModelError] if the model wasn't found.
+    #
+    # @return [Model]
+    def find(id)
+      build(resource_gateway.json_show(id))
+    rescue RestClient::ResourceNotFound
+      raise NoSuchModelError, "Can't find any #{endpoint} with id \"#{id}\""
+    end
+
+    private
+
+    attr_reader :resource_gateway
+  end
+end

data/lib/namely/connection.rb

@@ -0,0 +1,90 @@
+module Namely
+  class Connection
+    # Instantiate a new connection to the server.
+    #
+    # @param [Hash] options
+    # @option options [String] access_token (required)
+    # @option options [String] subdomain (required)
+    #
+    # @example
+    #   Namely.configure do |config|
+    #     config.access_token = "your_access_token"
+    #     config.subdomain = "your-organization"
+    #   end
+    #
+    # @raise [KeyError] if access_token and subdomain aren't provided.
+    #
+    # @return [Connection]
+    def initialize(options)
+      @access_token = options.fetch(:access_token)
+      @subdomain = options.fetch(:subdomain)
+    rescue KeyError
+      raise ArgumentError, "Please supply an access_token and subdomain."
+    end
+
+    # Return a Collection of countries.
+    #
+    # @return [Collection]
+    def countries
+      collection("countries")
+    end
+
+    # Return a Collection of currency types.
+    #
+    # @return [Collection]
+    def currency_types
+      collection("currency_types")
+    end
+
+    # Return a Collection of countries.
+    #
+    # @return [Collection]
+    def events
+      collection("events")
+    end
+
+    # Return a Collection of profile fields.
+    #
+    # @return [Collection]
+    def fields
+      collection("profiles/fields")
+    end
+
+    # Return a Collection of job tiers.
+    #
+    # @return [Collection]
+    def job_tiers
+      collection("job_tiers")
+    end
+
+    # Return a Collection of profiles.
+    #
+    # @return [Collection]
+    def profiles
+      collection("profiles")
+    end
+
+    # Return a Collection of reports.
+    #
+    # @return [Collection]
+    def reports
+      collection("reports")
+    end
+
+    private
+
+    attr_reader :access_token, :subdomain
+
+    def collection(endpoint)
+      Namely::Collection.new(gateway(endpoint))
+    end
+
+    def gateway(endpoint)
+      ResourceGateway.new(
+        access_token: access_token,
+        endpoint: endpoint,
+        subdomain: subdomain,
+      )
+    end
+  end
+end