clubhouse.io-ruby 0.1.0

data/docs/projects.md

@@ -0,0 +1,74 @@
+# Projects
+
+This assumes that you have setup the default client, or will inject your own client.
+
+## Creating
+
+```ruby
+project = Clubhouse::Project.new(
+  name: "Project One",
+  description: 'Project description',
+  color: '#222'
+)
+
+project.save
+```
+
+Once saved the project object will be reloaded with the response from clubhouse so now your new
+object will have the created_at and updated_at time that is returned from the API.
+
+### Required Fields
+* name
+
+
+## Updating
+
+```ruby
+project = Clubhouse::Project.find(8)
+
+project.archived = true
+project.save # Save works for both creating and updating
+
+=> <#Clubhouse::Project... >
+
+```
+
+## Finding by id
+
+```ruby
+project = Clubhouse::Project.find(8)
+
+=> #<Clubhouse::Project:0x007ffcd58002d0 @archived=true, @id=8 ... >
+```
+
+## Deleting by id
+
+When an empty hash is returned this means it was successfull otherwise it will raise an exception
+
+```ruby
+Clubhouse::Project.delete(8)
+
+=> {}
+```
+
+## Listing
+
+Returns a list of all projects
+
+```ruby
+Clubhouse::Project.all
+
+=> [#<Clubhouse::Project:0x007fb142440458 @abbreviation="PT"...>]
+```
+
+## Listing all stories for a project
+
+Returns all the stories for the current project
+
+```ruby
+project = Clubhouse::Project.find(8)
+
+project.stories
+
+=> [#<Clubhouse::Story:0x007fb144089178 @archived=false, @comments=[{"...>, #<Clubhouse::Story>]
+```

data/docs/stories.md

@@ -0,0 +1,96 @@
+# Stories
+
+This assumes that you have setup the default client, or will inject your own client check out the README if you haven't already.
+
+## Creating
+
+```ruby
+story = Clubhouse::Story.new(
+  comments:[ {text: 'A comment to start the story'} ],
+  deadline: '2016-12-31T12:30:00Z',
+  estimate: 8,
+  labels: [ {name: 'High'}, {name: :bug } ],
+  name: "Can't login and get 503",
+  project_id: 17,
+  story_type: :bug,
+  tasks: [ {description: 'Monitor server load' } ],
+  workflow_state_id: 2
+)
+
+story.save
+```
+
+Once saved the story object will be reloaded with the response from clubhouse so now your new object will have the created_at and updated_at time that is returned from the API.
+
+### Required Fields
+* name
+* project_id
+
+
+## Updating
+
+```ruby
+story = Clubhouse::Story.new(name: "Can't login and get 503", project_id: 17).save
+
+story.story_type = 'bug'
+story.save # Save works for both creating and updating and only sends the attributes which are permitted
+
+=> <#Clubhouse::Story... >
+
+```
+
+## Finding by id
+
+```ruby
+story = Clubhouse::Story.find(696)
+
+=> #<Clubhouse::Story:0x007ffcd58002d0 @archived=false, @id=696 ... >
+```
+
+## Deleting by id
+
+When an empty hash is returned this means it was successfull otherwise it will raise an exception
+
+```ruby
+Clubhouse::Story.delete(696)
+
+=> {}
+```
+
+## Adding comments and tasks quickly
+
+Once you have saved your story or you find a story and want to add a comment or task quickly. You can do so with the following method calls
+
+```ruby
+
+story = Clubhouse::Story.find(696)
+
+story.add_comment('My comment here')
+=> [#<Clubhouse::Comment:0x007ffcd41518b8 @text="My comment here", @story_id=696, @author_id="57c75ddd-ad27-4531-8c7d-368d8702cc0d", @created_at... >, <#Clubhouse::Comment>]
+
+story.add_task('Add acceptance spec')
+=> [#<Clubhouse::Task:0x007ffcd434efd0 @complete=false, @created_at="2016-09-25T16:44:35Z", @description="Write acceptance spec"...>, <#Clubhouse::Task>]
+
+```
+
+When you add a comment or a task it will return an array of all the comments or tasks that exist
+on that story, you can access all the comments and task and modify them by calling comments or tasks on the story object.
+
+## Searching
+
+Searching for stories is open and not restricted. It takes a hash of key, value.
+You can check which search attributes are valid [here](https://clubhouse.io/api/v1/#search-stories)
+
+```ruby
+Clubhouse::Story.search(project_id: 17, estimate: 5, epic_id: 1)
+
+=> [#<Clubhouse::Story:0x007ffcd58002d0 @archived=false, @id=696 ... >]
+```
+
+## Failure
+All the request calls can fail and if they do you will be presented with an exception.
+The exception will be explanatory of the issue with the full body content response of the problem from Clubhouse API
+
+```
+Clubhouse::BadRequestError: {"message":"The request included invalid or missing parameters.","errors":{"name":"missing-required-key","project_id":"missing-required-key"}
+```

data/docs/story_links.md

@@ -0,0 +1,39 @@
+# StoryLinks
+
+This assumes that you have setup the default client, or will inject your own client.
+
+## Creating
+
+```ruby
+story_link = Clubhouse::StoryLink.new(
+  subject_id: 3,
+  object_id: 2,
+  verb: 'blocks'
+)
+
+story_link.save
+```
+
+Once saved the story link object will be reloaded with the response from clubhouse so now your new
+object will have the created_at and updated_at time that is returned from the API.
+
+### Required Fields
+* subject_id
+* object_id
+* verb (blocks, duplicates, relates to)
+
+
+## Updating
+
+You can't update a story link best thing is to delete and recreate
+
+
+## Deleting by id
+
+When an empty hash is returned this means it was successfull otherwise it will raise an exception
+
+```ruby
+Clubhouse::StoryLink.delete(8)
+
+=> {}
+```

data/docs/tasks.md

@@ -0,0 +1,66 @@
+# Tasks
+
+This assumes that you have setup the default client, or will inject your own client.
+
+It is recommended to create tasks from a story object as described [here](stories.md)
+
+## Creating
+
+```ruby
+task = Clubhouse::Task.new(
+  story_id: 34,
+  description: 'My task',
+  complete: false
+)
+
+task.save
+```
+
+Once saved the task object will be reloaded with the response from clubhouse so now your new
+object will have the created_at and updated_at time that is returned from the API.
+
+### Required Fields
+* story_id
+* description
+
+
+## Updating
+
+```ruby
+task = Clubhouse::Task.find(34, 9)
+
+task.description = "My task"
+task.complete = true
+task.save # Save works for both creating and updating
+
+=> <#Clubhouse::Task... >
+
+```
+
+## Finding by id
+
+Finding a task is different to all other resources the find method takes two arguments
+
+* story_id
+* task_id
+
+```ruby
+task = Clubhouse::Task.find(34, 8)
+
+=> #<Clubhouse::Task:0x007ffcd58002d0 @description="Updated task", @id=9, @complete=true ... >
+```
+
+## Deleting by id
+
+Deleting a task is different to all other resources the delete method takes two arguments
+
+* story_id
+* task_id
+
+When an empty hash is returned this means it was successfull otherwise it will raise an exception
+
+```ruby
+Clubhouse::Task.delete(34, 8)
+
+=> {}
+```

data/docs/users.md

@@ -0,0 +1,26 @@
+# Users
+
+This assumes that you have setup the default client, or will inject your own client.
+
+## Creating, Updating, Deleting
+
+You can't create, update or delete users via the API this needs to happen only via Clubhouse web
+
+
+## Finding by id
+
+```ruby
+epic = Clubhouse::User.find(3)
+
+=> #<Clubhouse::User:0x007ffcd58002d0 @disabled=false, @id=3 ... >
+```
+
+## Listing
+
+Returns a list of all users
+
+```ruby
+Clubhouse::User.all
+
+=> [#<Clubhouse::User:0x007fb142170e58 @name="Tester", @deactivated=false,..>, #<Clubhouse::User...>]
+```

data/docs/workflows.md

@@ -0,0 +1,17 @@
+# Workflows
+
+This assumes that you have setup the default client, or will inject your own client.
+
+## Creating, Updating, Deleting
+
+You can't create, update or delete workflows via the API this needs to happen only via Clubhouse web
+
+## Listing
+
+Returns a list of all workflows
+
+```ruby
+Clubhouse::Workflow.all
+
+=> [#<Clubhouse::Workflow:0x007fb142034030 @default_state_id=500000011, @id=500000009...>]
+```

data/lib/clubhouse.rb

@@ -0,0 +1,34 @@
+require 'net/http'
+require 'json'
+
+require 'clubhouse/version'
+require 'clubhouse/ext/string'
+require 'clubhouse/api_actions'
+require 'clubhouse/client'
+require 'clubhouse/base_resource'
+
+require 'clubhouse/story'
+require 'clubhouse/label'
+require 'clubhouse/user'
+require 'clubhouse/workflow'
+require 'clubhouse/project'
+require 'clubhouse/epic'
+require 'clubhouse/file'
+require 'clubhouse/linked_file'
+require 'clubhouse/task'
+require 'clubhouse/comment'
+require 'clubhouse/story_link'
+
+module Clubhouse
+  class NotSupportedByAPIError < StandardError; end
+  class MissingStoryIDError < StandardError; end
+  class StoryNotSavedError < StandardError; end
+
+  class << self
+    attr_accessor :default_client
+
+    def configure
+      yield self if block_given?
+    end
+  end
+end

data/lib/clubhouse/api_actions.rb

@@ -0,0 +1,10 @@
+module Clubhouse
+  class NoSuchResourceError < StandardError; end
+
+  module APIActions
+    def find(clazz, path, id)
+      payload = get("#{path}/#{id}")
+      clazz.new.update_object_from_payload(payload)
+    end
+  end
+end

data/lib/clubhouse/base_resource.rb

@@ -0,0 +1,108 @@
+module Clubhouse
+  class InvalidKeyAssignment < StandardError; end
+  class ClientNotSetup < StandardError; end
+
+  class BaseResource
+    attr_writer :client
+
+    class << self
+      attr_reader :endpoint
+
+      def resource(name)
+        @endpoint = name
+      end
+
+      def client
+        Clubhouse.default_client
+      end
+
+      def find(id)
+        client.find(self, self.endpoint, id)
+      end
+
+      def delete(id)
+        client.delete("#{self.endpoint}/#{id}")
+      end
+
+      def all
+        payload = client.get(self.endpoint)
+        payload.collect{|h| self.new.update_object_from_payload(h) }
+      end
+    end
+
+    def initialize(attr = {})
+      attr.each do |key, value|
+        begin
+          send("#{key}=", value)
+        rescue NoMethodError
+          raise InvalidKeyAssignment, "You can't assign value to #{key}"
+        end
+      end
+    end
+
+    def self.attributes(*keys, **opts)
+      readonly = Array(opts[:readonly])
+
+      class_eval do
+        define_method(:attribute_keys) { (keys + readonly) }
+
+        (keys + readonly).each do |key|
+          define_method(:"#{key}")  { instance_variable_get("@#{key}") }
+
+          if !readonly.include?(key)
+            define_method(:"#{key}=") {|v| instance_variable_set("@#{key}", v) }
+          end
+        end
+      end
+    end
+
+    def self.attributes_for_update(*keys)
+      class_eval do
+        define_method :update_attributes do
+          keys.reduce({}) do |h, k|
+            h.merge(k => instance_variable_get("@#{k}"))
+          end.reject{|k,v| v.nil?}
+        end
+      end
+    end
+
+    def self.attributes_for_create(*keys)
+      class_eval do
+        define_method :create_attributes do
+          keys.reduce({}) do |h, k|
+            h.merge(k => instance_variable_get("@#{k}"))
+          end.reject{|k,v| v.nil?}
+        end
+      end
+    end
+
+    def client
+      @client ||= Clubhouse.default_client
+    end
+
+    def update_object_from_payload(payload)
+      attribute_keys.each do |k|
+        self.instance_variable_set("@#{k}", payload[k.to_s])
+      end
+
+      self
+    end
+
+    def reload
+      payload = client.get("#{self.class.endpoint}/#{id}")
+      update_object_from_payload(payload)
+    end
+
+    def save
+      raise ClientNotSetup, "A default client or instance client is not setup" unless client
+
+      payload = if id
+                  client.put("#{self.class.endpoint}/#{id}", update_attributes)
+                else
+                  client.post(self.class.endpoint, create_attributes)
+                end
+
+      update_object_from_payload(payload)
+    end
+  end
+end