timestamp_api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6a870a3e355cac05312491e1f1de0868959a58cb
-  data.tar.gz: 030bdb7e4306a523c303f66121b003661b7ea38a
+  metadata.gz: 1a9b651bd6a1f81bb14b9edc23be1403ee37a4d3
+  data.tar.gz: 50238b9ee2ab12eb51b8fd4e5f82657c3cfb0385
 SHA512:
-  metadata.gz: b84b0632fd788418b36bc86a1398326973cc64f9676a875579285e35345aa2523f4789ddc75d427fe34b74e08866f2c762e355556e2f17b35ea831fe1a8c165f
-  data.tar.gz: d63292c7170080dc6b3b72b6a5183db06fe0bbb986610d22a9bf11769a1adfbf6cb4ec7043c53d97060685389114c0ab6ddee2a8ec9ef6d1396f77b25cb68286
+  metadata.gz: 5a72476235ef88e59f68f3e8d56a0d34c657581cf2f0cd4e2bbe626db7ec8d4193f89b5e90d45a14b7a299f326d431c93d204cd0d9ac4bfc9cd2ed974a46caa3
+  data.tar.gz: f6b28f91da78b36c7d8240fc1c37c5d16b21c2fac7242d4397fdcdb09cb87e0bf5773bcc60b4f46aa865333c337b7305ef3114277f72dce03f37942013e1d4c2

data/README.md

@@ -32,18 +32,72 @@ Configure your Timestamp API key by setting environment variable `TIMESTAMP_API_
 TimestampAPi.api_key = "YOUR_TIMESTAMP_API_KEY"
 ```
 
+#### Projects
+
 List all projects:
 ```ruby
-projects = TimestampAPI::Project.all
-projects.map(&:name) # => ["A project", "Another project", "One more project"]
+TimestampAPI::Project.all
 ```
 
 Find a given project:
 ```ruby
-project = TimestampAPI::Project.find(123456)
+project = TimestampAPI::Project.find(123)
+
+project.name # => "My awesome project"
+```
+
+#### Clients
+
+List all clients:
+```ruby
+TimestampAPI::Client.all
+```
+
+Find a given client:
+```ruby
+client = TimestampAPI::Client.find(123)
+
+client.name # => "My beloved customer"
+```
+
+Find the client of a project
+```ruby
+project = TimestampAPI::Project.find(123)
+
 project.client.name # => "My beloved customer"
 ```
 
+## Models
+
+The objects are represented by model classes (that inherits from `TimestampAPI::Model`):
+```ruby
+project = TimestampAPI::Project.find(123456)
+
+project.class                     # => TimestampAPI::Project
+project.is_a? TimestampAPI::Model # => true
+```
+
+Collections of objects are represented by `TimestampAPI::Collection` that inherits from `Array` (and implement the chainable `.where(conditions)` filter method described above). It means any `Array` method works on `TimestampAPI::Collection`:
+```ruby
+projects = TimestampAPI::Project.all
+
+projects.class       # => TimestampAPI::Collection
+projects.map(&:name) # => ["A project", "Another project", "One more project"]
+```
+
+## Filtering
+
+You can filter any object collection using the handy `.where()` syntax:
+```ruby
+projects = TimestampAPI::Project.all
+
+projects.where(is_public: true)                          # => returns all public projects
+projects.where(is_public: true, is_billable: true)       # => returns all projects that are both public and billable
+projects.where(is_public: true).where(is_billable: true) # => same as above: `where` is chainable \o/
+```
+
+:information_source: This does not filter objects **before** the network call (like ActiveRecord does), it's only a more elegant way of calling `Array#select` on the `Collection`
+
 ### Low level API calls
 
 The above methods are simple wrappers around the generic low-level-ish API request method `TimestampAPI.request` that take a HTTP `method` (verb) and a `path` (to be appended to preconfigured API endpoint URL):
@@ -52,12 +106,9 @@ TimestampAPI.request(:get, "/projects")        # Same as TimestampAPI::Project.a
 TimestampAPI.request(:get, "/projects/123456") # Same as TimestampAPI::Project.find(123456)
 ```
 
-Response is provided as a [RecursiveOpenStruct](https://github.com/aetherknight/recursive-open-struct) (or as an `Array` of `RecursiveOpenStruct`), thus can be accessed by:
+To output all network requests done, you can set verbosity on:
 ```ruby
-project = TimestampAPI.request(:get, "/projects/123456")
-project.id          # => 123456
-project.name        # => "Awesome project"
-project.client.name # => "My beloved customer"
+TimestampAPI.verbose = true
 ```
 
 ## Reverse engineering
@@ -74,12 +125,14 @@ There's also a `bin/console` executable provided with this gem, if you want a RE
 
 ### What's implemented already ?
 
-* [x] Project#all
-* [x] Project#find
+* [x] `Project#all`
+* [x] `Project#find`
+* [x] `belongs_to` relationships
 
 ### What's not implemented yet ?
 
-* [ ] _everything else_ :scream:
+* [ ] _all other models_ :scream:
+* [ ] `has_many` relationships
 
 ## Development
 

data/lib/timestamp_api/collection.rb

@@ -0,0 +1,10 @@
+module TimestampAPI
+  class Collection < Array
+    def where(conditions)
+      raise TimestampAPI::InvalidWhereContitions unless conditions.is_a? Hash
+      conditions.each_with_object(self.dup) do |condition, acc|
+        acc.select! { |i| i.send(condition.first.to_sym) == condition.last }
+      end
+    end
+  end
+end

data/lib/timestamp_api/errors.rb

@@ -5,9 +5,92 @@ module TimestampAPI
     end
   end
 
+  class InvalidAPIKey < StandardError
+    def message
+      "Configured API key is invalid."
+    end
+  end
+
   class InvalidServerResponse < StandardError
     def message
-      "Server responded with invalid JSON. A possible cause is an invalid or revoked API key."
+      "Server responded with invalid JSON."
+    end
+  end
+
+  class InvalidModelData < StandardError
+    attr_reader :caller_class, :json_data
+
+    def initialize(caller_class, json_data)
+      @caller_class = caller_class
+      @json_data    = json_data
+    end
+
+    def message
+      if json_data.is_a? Hash
+        "A `#{caller_class}` class was initialized with JSON data for a `#{json_data["object"] || "unknown"}` object."
+      else
+        "A `#{caller_class}` class was initialized with data which is not a `Hash` (it was a `#{json_data.class}`, actually)."
+      end
+    end
+  end
+
+  class UnknownModelData < StandardError
+    attr_reader :json_object
+
+    def initialize(json_object = nil)
+      @json_object = json_object
+    end
+
+    def message
+      if json_object
+        "JSON data with object type `#{json_object}` has no matching model implemented."
+      else
+        "JSON data doesn't have an `object` field or it's not valid JSON data."
+      end
+    end
+  end
+
+  class InvalidWhereContitions < StandardError
+    def message
+      "Conditions passed to `Collection#where` must be a hash."
+    end
+  end
+
+  class UnknownAssociation < StandardError
+    attr_reader :klass, :association_name
+
+    def initialize(klass, association_name)
+      @klass            = klass
+      @association_name = association_name
+    end
+
+    def message
+      "Association `#{association_name}` could not be found on model `#{klass}`."
+    end
+  end
+
+  class ResourceNotFound < StandardError
+    attr_reader :klass, :id
+
+    def initialize(klass, id)
+      @klass = klass
+      @id    = id
+    end
+
+    def message
+      "No `#{klass}` was found with id `#{id}` (API returned 404)"
+    end
+  end
+
+  class APIPathNotSet < StandardError
+    attr_reader :klass
+
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def message
+      "API path not defined in `#{klass}` model. Use `api_path` to define it."
     end
   end
 end

data/lib/timestamp_api/model.rb

@@ -0,0 +1,31 @@
+module TimestampAPI
+  class Model
+    attr_reader :json_data
+
+    include Hooks
+    define_hooks :after_initialize, :after_inherited
+
+    include Utils
+    include ModelAttributes
+    include ModelRelations
+    include ModelDefaultAPIMethods
+
+    def self.inherited(subclass)
+      ModelRegistry.register(subclass)
+      run_hook :after_inherited, subclass
+    end
+
+    def initialize(json_data)
+      @json_data = json_data
+      validate_init_data!
+      run_hook :after_initialize
+    end
+
+  private
+
+    def validate_init_data!
+      class_basename = self.class.name.split("::").last
+      raise InvalidModelData.new(class_basename, json_data) unless json_data.is_a?(Hash) && json_data["object"] == class_basename.downcase
+    end
+  end
+end

data/lib/timestamp_api/model_attributes.rb

@@ -0,0 +1,27 @@
+module TimestampAPI
+  module ModelAttributes
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        after_initialize do
+          self.class.class_variable_get(:@@attributes).each do |attribute|
+            instance_variable_set(:"@#{attribute}", json_data[camelize(attribute)])
+          end
+        end
+
+        after_inherited do |subclass|
+          subclass.class_variable_set(:@@attributes, [])
+        end
+      end
+    end
+
+    module ClassMethods
+      def has_attributes(*attributes)
+        # Add those attributes to the list of attributes for this class
+        self.class_variable_set(:@@attributes, self.class_variable_get(:@@attributes) + attributes)
+        # Define getters for those attributes
+        self.send(:attr_accessor, *attributes)
+      end
+    end
+  end
+end

data/lib/timestamp_api/model_default_api_methods.rb

@@ -0,0 +1,31 @@
+module TimestampAPI
+  module ModelDefaultAPIMethods
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        after_inherited do |subclass|
+          subclass.class_variable_set(:@@api_path, nil)
+        end
+      end
+    end
+
+    module ClassMethods
+      def api_path(path = nil)
+        path.nil? ? self.class_variable_get(:@@api_path) : self.class_variable_set(:@@api_path, path)
+      end
+
+      def all
+        raise APIPathNotSet.new(self) if api_path.nil?
+        TimestampAPI.request(:get, api_path)
+      end
+
+      def find(id)
+        return nil if id.nil?
+        raise APIPathNotSet.new(self) if api_path.nil?
+        TimestampAPI.request(:get, "#{api_path}/#{id}")
+      rescue RestClient::ResourceNotFound
+        raise ResourceNotFound.new(self, id)
+      end
+    end
+  end
+end

data/lib/timestamp_api/model_registry.rb

@@ -0,0 +1,27 @@
+module TimestampAPI
+  class ModelRegistry
+    class << self
+
+      @@registry = {}
+
+      def register(klass)
+        @@registry[registry_key(klass)] = klass unless klass.name.nil?
+      end
+
+      def registry
+        @@registry
+      end
+
+      def model_for(json_data)
+        raise UnknownModelData.new unless json_data.is_a? Hash
+        registry[json_data["object"]] || raise(UnknownModelData.new(json_data["object"]))
+      end
+
+    private
+
+      def registry_key(klass)
+        klass.name.split("::").last.gsub(/(.)([A-Z])/, '\1_\2').downcase
+      end
+    end
+  end
+end

data/lib/timestamp_api/model_relations.rb

@@ -0,0 +1,33 @@
+module TimestampAPI
+  module ModelRelations
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        after_initialize do
+          self.class.class_variable_get(:@@belongs_to).each do |association_name|
+            instance_variable_set(:"@_#{association_name}_id", json_data[camelize(association_name)]["id"]) if json_data.has_key? camelize(association_name)
+          end
+        end
+
+        after_inherited do |subclass|
+          subclass.class_variable_set(:@@belongs_to, [])
+        end
+      end
+    end
+
+    module ClassMethods
+      def belongs_to(association_name)
+        # Add this association to the list of associations for this class
+        self.class_variable_set(:@@belongs_to, self.class_variable_get(:@@belongs_to) + [association_name])
+        # Define a memoizing getter for this association
+        define_method(association_name) do
+          return instance_variable_get(:"@#{association_name}") unless instance_variable_get(:"@#{association_name}").nil?
+          unknown_association_error = UnknownAssociation.new(self, association_name)
+          associationship_id = instance_variable_get(:"@_#{association_name}_id")
+          association_class  = ModelRegistry.registry[association_name.to_s] || raise(unknown_association_error)
+          instance_variable_set(:"@#{association_name}", association_class.find(associationship_id))
+        end
+      end
+    end
+  end
+end

data/lib/timestamp_api/models/client.rb

@@ -0,0 +1,7 @@
+module TimestampAPI
+  class Client < Model
+    api_path "/clients"
+
+    has_attributes :id, :created_at, :updated_at, :account_id, :name, :code, :is_archived, :is_account_default
+  end
+end

data/lib/timestamp_api/models/project.rb

@@ -0,0 +1,10 @@
+module TimestampAPI
+  class Project < Model
+    api_path "/projects"
+
+    has_attributes :id, :created_at, :updated_at, :account_id, :name, :code, :color, :initiation_date,
+                   :target_completion_date, :is_archived, :is_billable, :is_public, :is_approvable
+
+    belongs_to :client
+  end
+end

data/lib/timestamp_api/utils.rb

@@ -0,0 +1,7 @@
+module TimestampAPI
+  module Utils
+    def camelize(symbol)
+      symbol.to_s.split('_').each_with_index.map{ |chunk, idx| idx == 0 ? chunk : chunk.capitalize }.join
+    end
+  end
+end

data/lib/timestamp_api/version.rb

@@ -1,3 +1,3 @@
 module TimestampAPI
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/timestamp_api.rb

@@ -1,41 +1,63 @@
 require "rest-client"
-require "recursive-open-struct"
+require "colorize"
+require "hooks"
 
 require "timestamp_api/version"
 require "timestamp_api/errors"
-require "timestamp_api/project"
+require "timestamp_api/utils"
+require "timestamp_api/model_registry"
+require "timestamp_api/model_attributes"
+require "timestamp_api/model_relations"
+require "timestamp_api/model_default_api_methods"
+require "timestamp_api/model"
+require "timestamp_api/collection"
+require "timestamp_api/models/project"
+require "timestamp_api/models/client"
 
 module TimestampAPI
   @api_endpoint = "https://api.ontimestamp.com/api"
 
   class << self
-    attr_accessor :api_endpoint, :api_key
+    attr_accessor :api_endpoint, :api_key, :verbose
   end
 
-  def self.request(method, url)
-    response = RestClient::Request.execute(request_options(method, url))
-    objectify(JSON.parse(response))
+  def self.request(method, path, query_params = {})
+    output(method, path, query_params) if verbose
+    response = RestClient::Request.execute(request_options(method, path, query_params))
+    modelify(JSON.parse(response))
+  rescue RestClient::Forbidden
+    raise InvalidAPIKey
   rescue JSON::ParserError
     raise InvalidServerResponse
   end
 
-  def self.request_options(method, url)
+private
+
+  def self.request_options(method, path, query_params)
     {
       method:  method,
-      url:     api_endpoint + url,
+      url:     api_endpoint + path,
       headers: {
         "X-API-Key" => api_key || ENV["TIMESTAMP_API_KEY"] || raise(MissingAPIKey),
         :accept     => :json,
-        :user_agent => "TimestampAPI Ruby gem https://github.com/alpinelab/timestamp_api"
+        :user_agent => "TimestampAPI Ruby gem (https://github.com/alpinelab/timestamp_api)",
+        :params     => query_params
       }
     }
   end
 
-  def self.objectify(json)
+  def self.modelify(json)
     case json
-    when Array then json.map { |item| RecursiveOpenStruct.new(item, recurse_over_arrays: true) }
-    when Hash  then RecursiveOpenStruct.new(json, recurse_over_arrays: true)
-    else json
+    when Array then Collection.new(json.map { |item| modelify(item) })
+    when Hash  then ModelRegistry.model_for(json).new(json)
     end
   end
+
+  def self.output(method, path, query_params)
+    print "TimestampAPI ".colorize(:red)
+    print "#{method.upcase} ".colorize(:yellow)
+    full_path =  path
+    full_path += "?#{query_params.each_with_object([]) { |p, acc| acc << "#{p[0]}=#{p[1]}" }.join("&")}" unless query_params.empty?
+    puts full_path.colorize(:yellow)
+  end
 end

data/timestamp_api.gemspec

@@ -19,12 +19,14 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "rest-client"
-  spec.add_runtime_dependency "recursive-open-struct"
+  spec.add_runtime_dependency "rest-client", ">= 1.7.3"
+  spec.add_runtime_dependency "colorize"
+  spec.add_runtime_dependency "hooks"
 
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "awesome_print"
+  spec.add_development_dependency "webmock", "~> 1.22"
 end

metadata

@@ -1,17 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: timestamp_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Baudino
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-24 00:00:00.000000000 Z
+date: 2016-01-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.3
+- !ruby/object:Gem::Dependency
+  name: colorize
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: recursive-open-struct
+  name: hooks
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -108,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.22'
 description: 'Timestamp is "real-time project tracking for you and your clients" according
   to their website: https://www.timestamphq.com'
 email:
@@ -129,8 +157,16 @@ files:
 - bin/console
 - bin/setup
 - lib/timestamp_api.rb
+- lib/timestamp_api/collection.rb
 - lib/timestamp_api/errors.rb
-- lib/timestamp_api/project.rb
+- lib/timestamp_api/model.rb
+- lib/timestamp_api/model_attributes.rb
+- lib/timestamp_api/model_default_api_methods.rb
+- lib/timestamp_api/model_registry.rb
+- lib/timestamp_api/model_relations.rb
+- lib/timestamp_api/models/client.rb
+- lib/timestamp_api/models/project.rb
+- lib/timestamp_api/utils.rb
 - lib/timestamp_api/version.rb
 - timestamp_api.gemspec
 homepage: https://github.com/alpinelab/timestamp_api

data/lib/timestamp_api/project.rb

@@ -1,11 +0,0 @@
-module TimestampAPI
-  class Project
-    def self.all
-      TimestampAPI.request(:get, "/projects")
-    end
-
-    def self.find(id)
-      TimestampAPI.request(:get, "/projects/#{id}")
-    end
-  end
-end