mingle-api 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 94199aaae96d4214cecaf879930b8cea304b36f9
+  data.tar.gz: a0d01b5477bc18c396343320352e3beee40b466a
+SHA512:
+  metadata.gz: b9200be2eb9fca66d9e947dbd7f59b521cc911e1ca4845d9d621603fad06b3da9f77f30bdef5d76c445896f9666903de6accb2e6d7cc6e9f7fb6c83adaef0872
+  data.tar.gz: 63440ec88b25d78fa9af6e7386a106616933bd61cb1da12cef41262d2bb5285a83d309174d198722f091b123ff0c9917b0b9be51ba3a8902338d9ed8f4b04f85

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rbenv-vars

@@ -0,0 +1,4 @@
+MINGLE_SITE=xiao-test100
+MINGLE_USERNAME=admin
+MINGLE_PASSWORD=pass12!
+MINGLE_SECRET_KEY=c1Ur61d/bhmgcH2cqWKyovlNgYHmpuZPu3ZSKzCjCXc=

data/.ruby-version

@@ -0,0 +1 @@
+2.1.0

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Xiao Li
+
+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,93 @@
+# Mingle::Api
+
+[Built with :yellow_heart: and :coffee: in San Francisco](http://getmingle.io)
+
+[Mingle](http://getmingle.io) is a software development team collaborative tool, developed by ThoughtWorks Studios.
+The Mingle API gem provides simple interface for you to build application talks to Mingle.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mingle-api'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mingle-api
+
+## Usage
+
+### Initialize with HMac Auth for SaaS Mingle site
+
+    mingle = Mingle.new('site-name', hmac: [username, secret_key])
+
+### Initialize with Basic Auth for SaaS Mingle site
+
+    mingle = Mingle.new('site-name', basic_auth: [username, password])
+
+### Initialize with HMac for onsite Mingle site
+
+    mingle = Mingle.new('https://your-mingle-site-url', hmac: [username, secret_key])
+
+### Get all projects
+
+    projects = mingle.projects
+
+### Get project by identifier
+
+    project = mingle.projects('your_first_project')
+
+### Create project
+
+    mingle.create_project("Project Name")
+    # => OpenStruct.new(identifier, url)
+
+Create with project description and from template
+
+    mingle.create_project("Project Name", description: "description", template: 'kanban')
+
+### Get first page cards in project
+
+    mingle.cards('project_identifier')
+
+### Get card by card number and project identifier
+
+Let's say you have a project named Mingle and its identifier is mingle,
+and card number 123 has a text property named Status and user property named Owner
+
+    mingle.card('mingle', 123)
+
+You will get an OpenStruct object with attributes: name, description, type, status, owner
+As Owner is a user property, the value of the owner will be the user login if it exists
+
+### Create card
+
+    mingle.create_card('project_identifier', name: 'card name', type: 'Story',
+      attachments: [['/path/to/file', "image/png"]],
+      properties: {status: 'New', priority: 'high'})
+    # => OpenStruct.new(number, url)
+
+## API design
+
+1. flat: one level API, you can find all APIs definition in class Mingle.
+2. data: all APIs return data object only, they are:
+   1. Primitive type in Ruby
+   2. OpenStruct object, with primitive type values (rule #1 flat)
+
+## Setup development environment
+
+See .rbenv-vars file for environment variables need for test.
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/mingle-api/fork )
+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 a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*test.rb']
+  t.verbose = true
+end
+
+

data/TODO

@@ -0,0 +1,20 @@
+* Error handling
+** auth failure
+** Mingle's 5xx error
+** 4xx errors
+** Parse error message if Mingle responds
+** 3xx errors?
+* Card type api
+* property definition api
+* Card APIs
+** get all card attributes
+** update card
+** delete card
+** attachments
+** transitions
+* Project APIs
+** get all project attributes
+* MQL execution
+* Favorite APIs
+* User APIs
+* option to turn off OpenSSL::SSL::VERIFY_NONE

data/lib/mingle/api/version.rb

@@ -0,0 +1,5 @@
+module Mingle
+  module Api
+    VERSION = "0.0.1"
+  end
+end

data/lib/mingle/api.rb

@@ -0,0 +1,7 @@
+require "mingle/api/version"
+
+module Mingle
+  module Api
+    # Your code goes here...
+  end
+end

data/lib/mingle/http.rb

@@ -0,0 +1,61 @@
+require 'net/http'
+require 'net/https'
+require 'net/http/post/multipart'
+require 'api-auth'
+
+class Mingle
+  class Http
+    class Error < StandardError
+      def initialize(request_class, url, response)
+        super("error[#{request_class.name}][#{url}][#{response.code}]: #{response.body}")
+      end
+    end
+
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    def get(url)
+      process(Net::HTTP::Get, url)
+    end
+
+    def post(url, params)
+      process(Net::HTTP::Post::Multipart, url, params)
+    end
+
+    def process(request_class, url, form_data={}, headers=nil)
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+
+      if uri.scheme == 'https'
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+
+      request = request_class.new(uri.request_uri, form_data)
+
+      if headers
+        headers.each do |key, value|
+          request[key] = value
+        end
+      end
+
+      if @credentials[:hmac]
+        ApiAuth.sign!(request, *@credentials[:hmac])
+      elsif @credentials[:basic_auth]
+        request.basic_auth *@credentials[:basic_auth]
+      end
+
+      response = http.request(request)
+      raise Error.new(request_class, url, response) if response.code.to_i >= 300
+
+      to_canonical_response(response)
+    end
+
+    def to_canonical_response(response)
+      headers = {}
+      response.each_header {|key, value|  headers[key] = value }
+      [response.code.to_i, response.body, headers]
+    end
+  end
+end

data/lib/mingle/macro.rb

@@ -0,0 +1,33 @@
+class Mingle
+  class Macro
+    def text(node, css)
+      if ret = node.at_css(css)
+        ret.text
+      end
+    end
+
+    def apply(node, attr)
+      case attr
+      when String
+        [attr, text(node, attr)]
+      when Symbol
+        apply(node, attr.to_s)
+      when Array
+        attr.map do |a|
+          apply(node, a)
+        end.flatten
+      when Hash
+        attr.map do |key, value|
+          case value
+          when Symbol
+            [value, text(node, key)]
+          when Proc
+            node.css(key).map do |child|
+              self.instance_exec(child, &value)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mingle.rb

@@ -0,0 +1,129 @@
+require 'ostruct'
+require 'nokogiri'
+
+require 'mingle/http'
+require 'mingle/macro'
+
+class Mingle
+
+  attr_reader :site
+
+  PROJECT = [:name, :identifier, :description]
+  CARD = [:name, :description,
+    {
+      "card_type name" => :type,
+      'properties property' => lambda do |node|
+        name = text(node, 'name')
+        value = case node[:type_description]
+        when /team list/
+          text(node, 'value login')
+        else
+          text(node, 'value')
+        end
+        [name.downcase, value]
+      end
+    }
+  ]
+
+  def initialize(site, credentials)
+    @site, @http = site, Http.new(credentials)
+  end
+
+  def projects
+    list(fetch(:projects), PROJECT)
+  end
+
+  def project(identifier)
+    ostruct(fetch(:projects, identifier), PROJECT)
+  end
+
+  def create_project(name, options={})
+    identifier = name.downcase.gsub(/[^a-z0-9_]/, '_')
+    @http.post(v2(:projects), {
+      "project[name]" => name,
+      "project[identifier]" => identifier,
+      "project[description]" => options[:description],
+      "project[template]" => false,
+      "template_name" => options[:template] ? "yml_#{options[:template]}_template" : nil
+    })
+    OpenStruct.new(:identifier => identifier, :url => url('projects', identifier))
+  end
+
+  def cards(project_identifier)
+    list(fetch(:projects, project_identifier, :cards), CARD)
+  end
+
+  def card(project_identifier, number)
+    ostruct(fetch(:projects, project_identifier, :cards, number), CARD)
+  end
+
+  def create_card(project_identifier, attrs)
+    params = [
+      ["card[name]", attrs[:name]],
+      ["card[card_type_name]", attrs[:type]],
+      ["card[description]", attrs[:description]]
+    ]
+    Array(attrs[:attachments]).each_with_index do |attachment, i|
+      path, content_type = attachment
+      params << ["attachments[#{i}]", UploadIO.new(File.new(path), content_type, File.basename(path))]
+    end
+    Array(attrs[:properties]).each_with_index do |prop, i|
+      name, value = prop
+      params << ["card[properties][][name]", name]
+      params << ["card[properties][][value]", value]
+    end
+    resp = @http.post(v2(:projects, project_identifier, :cards), params)
+    number = resp[2]["location"].split("/").last.split('.').first
+    OpenStruct.new(:number => number, :url => url('projects', project_identifier, 'cards', number))
+  end
+
+  def site_api_url
+    gen_site_url(api_host)
+  end
+
+  def site_url
+    gen_site_url(host)
+  end
+
+  private
+  def url(*parts)
+    File.join(site_url, *parts)
+  end
+
+  def api_host
+    'mingle-api.thoughtworks.com' || ENV['MINGLE_API_HOST']
+  end
+
+  def host
+    'mingle.thoughtworks.com' || ENV['MINGLE_HOST']
+  end
+
+  def fetch(*resources)
+    dom(@http.get(v2(*resources))[1]).root
+  end
+
+  def list(dom, attrs)
+    dom.children.map do |child|
+      ostruct(child, attrs)
+    end
+  end
+
+  def ostruct(node, attrs)
+    macro = Macro.new
+    OpenStruct.new(Hash[*macro.apply(node, attrs)])
+  end
+
+  def dom(xml)
+    Nokogiri::XML(xml) do |config|
+      config.options = Nokogiri::XML::ParseOptions::NOBLANKS | Nokogiri::XML::ParseOptions::STRICT | Nokogiri::XML::ParseOptions::NONET
+    end
+  end
+
+  def v2(*parts)
+    [File.join(site_api_url, 'api/v2', *parts.map(&:to_s)), 'xml'].join('.')
+  end
+
+  def gen_site_url(h)
+    site =~ /^http/i ? site : "https://#{site}.#{h}"
+  end
+end

data/mingle-api.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mingle/api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "mingle-api"
+  spec.version       = Mingle::Api::VERSION
+  spec.authors       = ["Xiao Li"]
+  spec.email         = ["swing1979@gmail.com"]
+  spec.summary       = %q{[The Mingle API gem provides simple interface for you to build ruby application talks to Mingle.}
+  spec.description   = %q{[Mingle](http://getmingle.io) is a software development team collaborative tool, developed by ThoughtWorks Studios. The Mingle API gem provides simple interface for you to build ruby application talks to Mingle.}
+  spec.homepage      = "https://github.com/ThoughtWorksStudios/mingle-api"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency('api-auth')
+  spec.add_dependency('multipart-post')
+  spec.add_dependency('nokogiri')
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest"
+end

data/test/mingle_test.rb

@@ -0,0 +1,63 @@
+require 'test_helper'
+
+class MingleTest < Minitest::Test
+  def test_projects
+    mingle = create_basic_auth_mingle
+    first_proj = mingle.projects.find{|proj| proj.identifier == 'your_first_project'}
+    assert first_proj
+    assert_equal 'Your First Project', first_proj.name
+  end
+
+  def test_find_project_by_identifier
+    mingle = create_basic_auth_mingle
+    first_proj = mingle.project('your_first_project')
+    assert first_proj
+    assert_equal 'Your First Project', first_proj.name
+  end
+
+  def test_create_project
+    t = Time.now
+    mingle = create_basic_auth_mingle
+    project = mingle.create_project("Hello #{t.to_i}", description: "proj created at #{t}", template: 'kanban')
+    assert_equal "hello_#{t.to_i}", project.identifier
+    assert_equal "https://xiao-test100.mingle.thoughtworks.com/projects/hello_#{t.to_i}", project.url
+
+    proj = mingle.project(project.identifier)
+    assert_equal "proj created at #{t}", proj.description
+  end
+
+  def test_cards
+    mingle = create_hmac_auth_mingle
+    cards = mingle.cards('your_first_project')
+    assert cards.size > 0
+  end
+
+  def test_find_card_by_number
+    mingle = create_hmac_auth_mingle
+    card1 = mingle.card('your_first_project', 1)
+    assert_equal 'Welcome to Mingle', card1.name
+    assert_equal 'Story', card1.type
+    assert_equal 'New', card1.status
+    assert_equal 'xli_test100', card1.owner
+
+    card2 = mingle.card('your_first_project', 2)
+    assert_equal 'card name', card2.name
+    assert_equal 'Story', card2.type
+    assert_equal 'New', card2.status
+    assert_equal nil, card2.owner
+  end
+
+  def test_create_card
+    mingle = create_hmac_auth_mingle
+    card = mingle.create_card('your_first_project', name: 'card name', type: 'Story', description: 'card desc', properties: {status: 'new', priority: 'must'}, attachments: [[__FILE__, 'plain/text']])
+    assert card.number
+    assert_equal "https://xiao-test100.mingle.thoughtworks.com/projects/your_first_project/cards/#{card.number}", card.url
+
+    card = mingle.card('your_first_project', card.number)
+    assert_equal 'card desc', card.description
+    assert_equal 'card name', card.name
+    assert_equal 'Story', card.type
+    assert_equal 'New', card.status
+    assert_equal 'Must', card.priority
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,11 @@
+
+require 'mingle'
+require "minitest/autorun"
+
+def create_basic_auth_mingle
+  Mingle.new(ENV['MINGLE_SITE'], basic_auth: [ENV['MINGLE_USERNAME'], ENV['MINGLE_PASSWORD']])
+end
+
+def create_hmac_auth_mingle
+  Mingle.new(ENV['MINGLE_SITE'], hmac: [ENV['MINGLE_USERNAME'], ENV['MINGLE_SECRET_KEY']])
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: mingle-api
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Xiao Li
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: api-auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: multipart-post
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "[Mingle](http://getmingle.io) is a software development team collaborative
+  tool, developed by ThoughtWorks Studios. The Mingle API gem provides simple interface
+  for you to build ruby application talks to Mingle."
+email:
+- swing1979@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rbenv-vars"
+- ".ruby-version"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO
+- lib/mingle.rb
+- lib/mingle/api.rb
+- lib/mingle/api/version.rb
+- lib/mingle/http.rb
+- lib/mingle/macro.rb
+- mingle-api.gemspec
+- test/mingle_test.rb
+- test/test_helper.rb
+homepage: https://github.com/ThoughtWorksStudios/mingle-api
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: "[The Mingle API gem provides simple interface for you to build ruby application
+  talks to Mingle."
+test_files:
+- test/mingle_test.rb
+- test/test_helper.rb