timestamp_api 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a0f32becb73b472f08339084946177bd46c4e91
-  data.tar.gz: 6231f1d36873b7467d6d5d70d4d2ea1db26e3e74
+  metadata.gz: 67c11519366433b792e43a3d44a6a2dae38e6b2a
+  data.tar.gz: 72c994d54a419b40ba8bc14bb7459edba86b18e8
 SHA512:
-  metadata.gz: 84bc0fe028acd831ee41d3e1f81d7c11e78a807974fcae420ab2f382fb808ea9bb112d4b1e90b8dce21b7f71908ed1a1d4e167fb39f5904a5774c0ed4a7e73ad
-  data.tar.gz: 71a13d05744b67fc07ec4f13ce5bc50135c9428a731b50157105ed7dfecbd67e27eac8383734f97124dd03c52e346d402b1e9dc73b24d3767946ef0a33899056
+  metadata.gz: 7e743c9cbeb2fac5c20a97895f9fec04f6c0636a73fe3ddedd070ec794fc126146bbcd775764d79ea2008378e0256234c7214dcbaaf3fa3bb5306c2999719604
+  data.tar.gz: b4dede14115223f3445e1d86e987cad5fa018b772b91332bd1afe2f819bece132b722abc0e8789bad132d174a2292b20fee9c94045da57f00c53e182f24dc061

data/README.md

@@ -27,47 +27,112 @@ Or install it yourself as:
 
 ## Usage
 
-Configure your Timestamp API key by setting environment variable `TIMESTAMP_API_KEY` or manually:
+Configure your Timestamp API key by setting environment variable `TIMESTAMP_API_KEY`:
+```shell
+$ TIMESTAMP_API_KEY="YOUR_API_KEY" bin/console
+```
+
+Or set it manually from the console:
+```ruby
+TimestampAPi.api_key = "YOUR_API_KEY"
+```
+
+#### Clients
+
+List clients:
 ```ruby
-TimestampAPi.api_key = "YOUR_TIMESTAMP_API_KEY"
+TimestampAPI::Client.all # => Returns all clients
+```
+
+Find a given client:
+```ruby
+client = TimestampAPI::Client.find(123)
+
+client.name # => "My beloved customer"
 ```
 
 #### Projects
 
-List all projects:
+List projects:
 ```ruby
-TimestampAPI::Project.all
+TimestampAPI::Project.all # => Returns all projects
 ```
 
 Find a given project:
 ```ruby
 project = TimestampAPI::Project.find(123)
 
-project.name # => "My awesome project"
+project.name                            # => "My awesome project"
+project.client.name                     # => "My beloved customer"
+project.enter_time(123, Date.today, 60) # => Creates a 60 minutes time entry for today on task 123 and returns the created TimeEntry
 ```
 
-#### Clients
+#### Users
 
-List all clients:
+List users:
 ```ruby
-TimestampAPI::Client.all
+TimestampAPI::User.all # => Returns all users
 ```
 
-Find a given client:
+Find a given user:
 ```ruby
-client = TimestampAPI::Client.find(123)
+user = TimestampAPI::User.find(123)
 
-client.name # => "My beloved customer"
+user.full_name # => "Great developer"
 ```
 
-Find the client of a project
+#### Tasks
+
+List tasks:
 ```ruby
-project = TimestampAPI::Project.find(123)
+TimestampAPI::Task.all                 # => Returns all tasks
+TimestampAPI::Task.for_project_id(123) # => Returns tasks for project 123
+```
 
-project.client.name # => "My beloved customer"
+Find a given task:
+```ruby
+task = TimestampAPI::Task.find(123)
+
+task.name         # => "My fantastic task"
+task.project.name # => "My awesome project"
 ```
 
-## Models
+#### TimeEntry
+
+List time entries:
+```ruby
+TimestampAPI::TimeEntry.all              # => Returns all time entries
+TimestampAPI::TimeEntry.for_task_id(123) # => Returns time entries for task 123
+```
+
+Find a given time entry:
+```ruby
+time_entry = TimestampAPI::TimeEntry.find(123)
+
+time_entry.comment        # => "Stuff got done"
+time_entry.client.name    # => "My beloved customer"
+time_entry.project.name   # => "My awesome project"
+time_entry.task.name      # => "My fantastic task"
+time_entry.user.full_name # => "Great developer"
+```
+
+#### Event
+
+List events:
+```ruby
+TimestampAPI::Event.all # => Returns all events
+```
+
+Find a given event:
+```ruby
+event = TimestampAPI::Event.find(123)
+
+event.object # => Returns the object on which event occured
+```
+
+## Objects representation
+
+#### Models
 
 The objects are represented by model classes (that inherits from `TimestampAPI::Model`):
 ```ruby
@@ -77,6 +142,8 @@ project.class                     # => TimestampAPI::Project
 project.is_a? TimestampAPI::Model # => true
 ```
 
+#### Collections
+
 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
@@ -85,6 +152,19 @@ projects.class       # => TimestampAPI::Collection
 projects.map(&:name) # => ["A project", "Another project", "One more project"]
 ```
 
+#### Relationships
+
+Models can can bound together and are accessible using a simple getter:
+
+Exemple: find the client bound to a project:
+```ruby
+project = TimestampAPI::Project.find(123)
+
+project.client.name # => "My beloved customer"
+```
+
+:information_source: First call to such a relation getter will trigger an API request and memoize the response for network optimization.
+
 ## Filtering
 
 You can filter any object collection using the handy `.where()` syntax:
@@ -129,6 +209,8 @@ There's also a `bin/console` executable provided with this gem, if you want a RE
 * [x] `Client` model
 * [x] `Task` model
 * [x] `User` model (their `roles` could be enhanced, though)
+* [x] `TimeEntry` model
+* [x] `Event` model
 * [x] `belongs_to` relationships
 
 ### What's not implemented yet ?
@@ -136,6 +218,7 @@ There's also a `bin/console` executable provided with this gem, if you want a RE
 * [ ] _all other models_ :scream:
 * [ ] `has_many` relationships
 * [ ] document and integrate [Inch-CI](https://inch-ci.org)
+* [ ] timers
 
 ## Development
 

data/lib/timestamp_api.rb

@@ -11,10 +11,12 @@ require "timestamp_api/model_relations"
 require "timestamp_api/model_default_api_methods"
 require "timestamp_api/model"
 require "timestamp_api/collection"
+require "timestamp_api/models/event"
 require "timestamp_api/models/project"
 require "timestamp_api/models/client"
 require "timestamp_api/models/task"
 require "timestamp_api/models/user"
+require "timestamp_api/models/time_entry"
 
 module TimestampAPI
   extend Utils
@@ -25,9 +27,10 @@ module TimestampAPI
     attr_accessor :api_endpoint, :api_key, :verbose
   end
 
-  def self.request(method, path, query_params = {})
-    output(method, path, camelize_keys(query_params)) if verbose
-    response = RestClient::Request.execute(request_options(method, path, camelize_keys(query_params)))
+  def self.request(method, path, query_params = {}, payload = {})
+    request_options = request_options(method, path, query_params, payload)
+    output(request_options) if verbose
+    response = RestClient::Request.execute(request_options)
     modelify(JSON.parse(response))
   rescue RestClient::Forbidden
     raise InvalidAPIKey
@@ -37,15 +40,16 @@ module TimestampAPI
 
 private
 
-  def self.request_options(method, path, query_params)
+  def self.request_options(method, path, query_params, payload)
     {
       method:  method,
       url:     api_endpoint + path,
+      payload: camelize_keys(payload).to_json,
       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)",
-        :params     => query_params
+        :params     => camelize_keys(query_params)
       }
     }
   end
@@ -57,11 +61,12 @@ private
     end
   end
 
-  def self.output(method, path, query_params)
+  def self.output(request_options)
     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)
+    print "#{request_options[:method].upcase} ".colorize(:yellow)
+    full_path =  request_options[:url]
+    full_path += "?#{request_options[:headers][:params].each_with_object([]) { |p, acc| acc << "#{p[0]}=#{p[1]}" }.join("&")}" unless request_options[:headers][:params].empty?
+    print full_path.colorize(:yellow)
+    puts " #{request_options[:payload] unless request_options[:payload].empty?}".colorize(:green)
   end
 end

data/lib/timestamp_api/model.rb

@@ -25,7 +25,7 @@ module TimestampAPI
 
     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
+      raise InvalidModelData.new(class_basename, json_data) unless json_data.is_a?(Hash) && json_data["object"] == camelize(class_basename)
     end
   end
 end

data/lib/timestamp_api/model_registry.rb

@@ -1,5 +1,7 @@
 module TimestampAPI
   class ModelRegistry
+    extend Utils
+
     class << self
 
       @@registry = {}
@@ -20,7 +22,7 @@ module TimestampAPI
     private
 
       def registry_key(klass)
-        klass.name.split("::").last.gsub(/(.)([A-Z])/, '\1_\2').downcase
+        camelize(klass.name.split("::").last)
       end
     end
   end

data/lib/timestamp_api/models/event.rb

@@ -0,0 +1,11 @@
+module TimestampAPI
+  class Event < Model
+    api_path "/events"
+
+    has_attributes :resource_object, :change_type, :data
+
+    def object
+      TimestampAPI::ModelRegistry.model_for(data).new(data)
+    end
+  end
+end

data/lib/timestamp_api/models/project.rb

@@ -6,5 +6,15 @@ module TimestampAPI
                    :target_completion_date, :is_archived, :is_billable, :is_public, :is_approvable
 
     belongs_to :client
+
+    def enter_time(task_id, day, duration_in_minutes, comment = "")
+      TimestampAPI.request(:post, "#{@@api_path}/#{id}/enterTime", {}, {
+        task_id:    task_id,
+        day:        day.strftime("%FT%T%:z"),
+        time_value: duration_in_minutes,
+        time_unit:  "Minutes",
+        comment:    comment
+      }).object
+    end
   end
 end

data/lib/timestamp_api/models/time_entry.rb

@@ -0,0 +1,16 @@
+module TimestampAPI
+  class TimeEntry < Model
+    api_path "/timeEntries"
+
+    has_attributes :id, :created_at, :comment, :day, :minutes, :is_archived, :is_approved, :is_invoiced, :is_externally_owned, :is_locked
+
+    belongs_to :client
+    belongs_to :project
+    belongs_to :task
+    belongs_to :user
+
+    def self.for_task_id(task_id)
+      all("$filter" => "TaskId%20eq%20#{task_id}")
+    end
+  end
+end

data/lib/timestamp_api/models/user.rb

@@ -4,5 +4,9 @@ module TimestampAPI
 
     has_attributes :id, :created_at, :user_type, :first_name, :last_name, :email_address, :time_zone, :culture, :is_active,
                    :avatar_url, :last_accessed, :invited_at, :roles, :employment_type, :time_entry_mode, :importStatus, :invited
+
+    def full_name
+      "#{first_name} #{last_name}"
+    end
   end
 end

data/lib/timestamp_api/version.rb

@@ -1,3 +1,3 @@
 module TimestampAPI
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timestamp_api
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Michael Baudino
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-31 00:00:00.000000000 Z
+date: 2016-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -165,8 +165,10 @@ files:
 - lib/timestamp_api/model_registry.rb
 - lib/timestamp_api/model_relations.rb
 - lib/timestamp_api/models/client.rb
+- lib/timestamp_api/models/event.rb
 - lib/timestamp_api/models/project.rb
 - lib/timestamp_api/models/task.rb
+- lib/timestamp_api/models/time_entry.rb
 - lib/timestamp_api/models/user.rb
 - lib/timestamp_api/utils.rb
 - lib/timestamp_api/version.rb