pivit 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YzVkYzI3ZjE4Zjk1ZjJjNzIxM2IxZDc4YWE0MDE0YzVmZWY3ZjkwYQ==
+  data.tar.gz: !binary |-
+    ZjMzNDg1ZjRjZDY0ZGQ2MjQyYWUwMTJmMzJkYzYyNzlkMWZhNDdlZA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NDFhYzMxMzM3NjZiM2I0ODZlZDg4MTA0M2VjNjU4NGQ0ZjhiZWE5YWUzOTAw
+    MDE2MmZjZjZhNjRkMjE5NDJjY2JlMDE5ZDJlZDBkZmUzYzFjYjhkY2I0NWE1
+    MTU4YWE0ODg4ZTc5YjhiM2ZmZGFhZDgzMjliNzc5MjQ3YTk2YTA=
+  data.tar.gz: !binary |-
+    M2RlZWZmYzEyMmYzNzQxM2Q3ZTI2NTQ2NWNiM2MxY2Q1OTZjMjhiOGQ2YTdk
+    YzNiMTRjZTRmYzlmYjdjMTlkOGZiYmYxMGNkMDVkZDRjOTQ3Mzc2MzUyNWFi
+    OTgyNjdjN2VjN2U3NzUxM2Q2MGU2OGQ4NmQyMWVhOTQ0YTIwMjc=

data/.gitignore

@@ -0,0 +1,30 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+spec/fixtures/authentications.yml
+
+spec/cassettes/*
+spec/.DS_Store
+
+spec/pivit/.DS_Store
+
+spec/pivit/client/.DS_Store
+
+spec/irb_setup_script.rb
+
+.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pivit.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jason Truluck
+
+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,94 @@
+# Pivit 
+
+Pivit is a api wrapper for the Pivotal Tracker API. Most features are currently
+build out but some are still being implemented.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pivit'
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install pivit
+
+## Documentation
+
+http://rdoc.info/github/jasontruluck/pivit/master/index
+
+## Configuration
+
+Configuration allows for specifying your Pivotal Tracker instances variables. To connect to the API you only need either the `api_token` or the `username` and `password` not both.
+
+`api_token` - The api token provided via Pivotal Tracker
+
+`username`  - The username of the user you use for Pivotal Tracker
+
+`password`  - The password associated with your account
+
+`ssl`       - If you would like to use SSL to communicate with Pivotal Tracker (default: true)
+
+Within an initializer `config/initializer/pivit.rb`
+
+```ruby
+Pivit.configure do |c|
+  c.ssl   = true
+  c.api_token = "super-secret-token"
+end
+```
+
+### Setting up a new client
+
+```ruby
+client = Pivit::Client.new(:username => "username", :password =>"super-secret")
+```
+or
+```ruby
+client = Pivit.new(:username => "username", :password =>"super-secret")
+```
+
+You can also pass configuration keys such as  etc. as well.
+
+### Using Limit and Offset
+
+For methods that allow you to specify a limit and/or offset simply pass the limit or offset you want via an option
+
+```ruby
+client.iteration(My-Awesome-Project-ID, {:limit => 1})
+```
+
+## Testing
+
+This gem uses VCR to record requests to the api so you must test using a valid Pivotal Tracker server and credentails to test
+
+Add a sample authentications file to your `spec/fixtures` directory:
+
+```ruby
+#spec/fixtures/authentications.yml
+USERNAME:   myusername
+PASSWORD:   supersecret
+TOKEN:      supersecret
+PROJECT:    "12345"                      # ID of a project
+STORY:      "12345"                      # ID of a story
+STORY_B:    "12345"                      # ID of an alternate story
+MEMBERSHIP: "12345"                      # a id of a membership of a user in your project
+NOTE:       "This some note text"        # Some test text
+TASK:       "12345"                      # ID of a task within your pivotal tracker project 
+FILE:       "../../../fixtures/test.png" # File locatin of the image/doc/text you would like to use to test with
+```
+
+sample is included in the [source](https://github.com/jasontruluck/pivit/blob/master/spec/fixtures/authentications.yml.sample).
+
+*Note: for tests concerning disabling, deleting, restarting, etc they are mocked explicitly with webmock and will not effect your project*
+
+## Contributing
+  1. Fork it
+  2. Create your feature branch (`git checkout -b my-new-feature`)
+  3. Commit your changes (`git commit -am 'Add some feature'`)
+  4. Push to the branch (`git push origin my-new-feature`)
+  5. Create new Pull Request</job>)

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/pivit.rb

@@ -0,0 +1,20 @@
+require "pivit/version"
+require "pivit/configuration"
+require "pivit/client"
+require "pivit/error"
+
+module Pivit
+  extend Configuration
+
+  class << self
+    # Alias for Pivit::Client.new
+    # @return [Pivit::Client]
+    def new(options = {})
+      Pivit::Client.new(options)
+    end
+
+    def respond_to?(method, include_private=false)
+      new.respond_to?(method, include_private) || super(method, include_private)
+    end
+  end
+end

data/lib/pivit/authentication.rb

@@ -0,0 +1,22 @@
+# Authentication Module
+module Pivit
+  module Authentication
+    def authenticated?
+      !self.api_token.nil?
+    end
+
+    def authenticate(options)
+      if !options[:username].nil? && !options[:password].nil?
+        self.username  = URI::encode(options[:username])
+        self.password  = URI::encode(options[:password])
+        self.api_token = get("tokens/active").token.guid
+        build_endpoint
+      elsif !options[:token].nil?
+        self.api_token = options[:token]
+        build_endpoint
+      else
+        raise "Your authentication credentials are invalid."
+      end 
+    end
+  end
+end

data/lib/pivit/client.rb

@@ -0,0 +1,40 @@
+#Client Module
+require "pivit/authentication"
+require "pivit/connection"
+require "pivit/request"
+
+require "pivit/client/activity"
+require "pivit/client/iteration"
+require "pivit/client/membership"
+require "pivit/client/note"
+require "pivit/client/project"
+require "pivit/client/story"
+require "pivit/client/task"
+
+module Pivit
+  class Client
+    attr_accessor(*Configuration::VALID_OPTIONS_KEYS)
+
+    def initialize(options = {})
+      options = Pivit.options.merge(options)
+
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+
+      authenticate(options)
+    end
+
+    include Pivit::Authentication
+    include Pivit::Connection
+    include Pivit::Request
+
+    include Pivit::Client::Activity
+    include Pivit::Client::Iteration
+    include Pivit::Client::Membership
+    include Pivit::Client::Note
+    include Pivit::Client::Project
+    include Pivit::Client::Story
+    include Pivit::Client::Task
+  end
+end

data/lib/pivit/client/activity.rb

@@ -0,0 +1,34 @@
+module Pivit
+  class Client
+    # Activity management
+    # 
+    # @see http://www.pivotaltracker.com/help/api?version=v3#getting_activity
+    module Activity
+      # Retrieve all activity from your account
+      #
+      # Pass any of the specified query parameters via options 
+      # Available from Pivotal Tracker:
+      # limit - you can limit the number of activity feed items to a desired
+      # number. Note the default value is 10, and there is a upper cap of 100
+      # occurred_since_date - allows restricting the activity feed to only those
+      # items that occurred after a supplied date (example format: 2009/12/18
+      # 21:00:00 UTC)
+      # newer_than_version - allows restricting the activity feed to only those
+      # items that have a greater than supplied version
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_activity
+      #
+      # @return [Hashie::Mash] activity response
+      #
+      # @example 
+      #   Pivit::Client.activity
+      #
+      #   Pivit::Client.activity({:limit => 50})
+      # 
+      # @author Jason Truluck
+      def activity(options = {})
+        get("activities", options).activities
+      end
+    end
+  end
+end

data/lib/pivit/client/iteration.rb

@@ -0,0 +1,88 @@
+module Pivit
+  class Client
+    # Iteration management
+    # 
+    # @see http://www.pivotaltracker.com/help/api?version=v3#getting_iterations
+    module Iteration
+      # Retrieve all iterations from the project
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_iterations
+      #
+      # @param project_id the id of the project
+      #
+      # @return [Hashie::Mash] iterations response
+      #
+      # @example 
+      #   Pivit::Client.iterations(1111111)
+      # 
+      # @author Jason Truluck
+      def iterations(project_id, options = {})
+        get("projects/#{project_id}/iterations", options).iterations
+      end
+
+      # Retrieve all done iterations from the project
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_iterations
+      #
+      # @param project_id the id of the project
+      #
+      # @return [Hashie::Mash] iterations response
+      #
+      # @example 
+      #   Pivit::Client.done_iterations(1111111)
+      # 
+      # @author Jason Truluck
+      def done_iterations(project_id, options = {})
+        get("projects/#{project_id}/iterations/done", options).iterations
+      end
+
+      # Retrieve all iterations from the project
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_iterations
+      #
+      # @param project_id the id of the project
+      #
+      # @return [Hashie::Mash] iterations response
+      #
+      # @example 
+      #   Pivit::Client.iteration_backlog(1111111)
+      # 
+      # @author Jason Truluck
+      def iteration_backlog(project_id, options = {})
+        get("projects/#{project_id}/iterations/backlog", options).iterations
+      end
+
+      # Retrieve all iterations from the project
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_iterations
+      #
+      # @param project_id the id of the project
+      #
+      # @return [Hashie::Mash] iterations response
+      #
+      # @example 
+      #   Pivit::Client.iteration_current(1111111)
+      # 
+      # @author Jason Truluck
+      def iteration_current(project_id, options = {})
+        get("projects/#{project_id}/iterations/current", options).iterations
+      end
+      
+      # Retrieve all iterations from the project
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_iterations
+      #
+      # @param project_id the id of the project
+      #
+      # @return [Hashie::Mash] iterations response
+      #
+      # @example 
+      #   Pivit::Client.iteration_current_and_backlog(1111111)
+      # 
+      # @author Jason Truluck
+      def iteration_current_and_backlog(project_id, options = {})
+        get("projects/#{project_id}/iterations/current_backlog", options).iterations
+      end
+    end
+  end
+end

data/lib/pivit/client/membership.rb

@@ -0,0 +1,92 @@
+# Membership
+
+module Pivit
+  class Client
+    # Membership management
+    # 
+    # @see http://www.pivotaltracker.com/help/api?version=v3#getting_memberships
+    module Membership
+      # Retrieve a single membership from your account
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_memberships
+      #
+      # @param [Integer] project_id the id of the project that you want to
+      # retrieve memberships from
+      # @param [Integer] membership_id the id of the membership that you want to
+      # retrieve
+      #
+      # @param [Integer] project_id the id of the project that contains the
+      # membership
+      #
+      # @return [Hashie::Mash] membership response
+      #
+      # @example 
+      #   Pivit::Client.membership(1111111, 123456)
+      #
+      # @author Jason Truluck
+      def membership(project_id, membership_id, options = {})
+        get("projects/#{project_id}/memberships/#{membership_id}", options).memberships.first
+      end
+
+      # Retrieve all memberships from your account
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#getting_memberships
+      #
+      # @param [Integer] project_id the id of the project that contains the
+      #memberships
+      #
+      # @return [Hashie::Mash] memberships response
+      #
+      # @example 
+      #   Pivit::Client.memberships(1111111)
+      # 
+      # @author Jason Truluck
+      def memberships(project_id, options = {})
+        get("projects/#{project_id}/memberships", options).memberships
+      end
+
+      # Create a membership
+      # 
+      # Provide the parameters you want to use for the membership via the options
+      # hash. 
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#add_membership
+      #
+      # @param [Integer] project_id the id of the project that contains the
+      # membership
+      # @param [Integer] email the email address of the member that is being
+      # added
+      # @param [Integer] role the role of the member that is being added
+      #
+      # @return [Hashie::Mash] membership created response
+      #
+      # @example 
+      #   Pivit::Client.create_membership(12345, "test@example.com", "Member")
+      #
+      # @author Jason Truluck
+      def create_membership(project_id, email, role,  options = {})
+        options.merge!({ :membership => { :role => role, :person => { :email => email }}})
+        post("projects/#{project_id}/memberships", options).membership
+      end
+    
+      # Delete a membership
+      # 
+      #
+      # @see http://www.pivotaltracker.com/help/api?version=v3#delete_membership
+      #
+      # @param [Integer] project_id the id of the project that contains the
+      # membership
+      # @param [Integer] membership_id the id of the membership that is getting deleted
+      #
+      # @return [Hashie::Mash] membership deleted response
+      #
+      # @example 
+      #   Pivit::Client.update_membership(12345, 11111)
+      ##
+      # @author Jason Truluck
+      def delete_membership(project_id, membership_id, options = {})
+        delete("projects/#{project_id}/memberships/#{membership_id}", options).membership
+      end
+    end
+  end
+end