totter 0.2.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+bundler_args: --without development
+rvm:
+  - 1.9.3

data/Contributing.markdown

@@ -0,0 +1,19 @@
+## Submitting a Pull Request
+
+1. [Fork the repository.][fork]
+2. [Create a topic branch.][branch]
+3. Add tests for your unimplemented feature or bug fix.
+4. Run `bundle exec rake`. If your tests pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake`. If your tests fail, return to step 5.
+7. Run `open coverage/index.html`. If your changes are not completely covered
+   by your tests, return to step 3.
+8. Add documentation for your feature or bug fix.
+9. Run `bundle exec rake doc`. If your changes are not 100% documented, go
+   back to step 8.
+10. Add, commit, and push your changes.
+11. [Submit a pull request.][pr]
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: http://learn.github.com/p/branching.html
+[pr]: http://help.github.com/send-pull-requests/

data/Gemfile

@@ -0,0 +1,22 @@
+source 'https://rubygems.org'
+
+# Gem dependencies
+gemspec
+
+gem 'rake', group: [:development, :test]
+
+# Development dependencies
+group :development do
+  gem 'yard'
+  gem 'redcarpet'
+end
+
+# Testing dependencies
+group :test do
+  gem 'minitest'
+  gem 'minitest-wscolor'
+  gem 'webmock', require: 'webmock/minitest'
+  gem 'vcr'
+  gem 'mocha', require: 'mocha/setup'
+  gem 'simplecov', require: false
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Seesaw Decisions Corporation
+
+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/Rakefile

@@ -0,0 +1,21 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+task default: :test
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new(:doc) do |task|
+    task.files   = ['Readme.markdown', 'LICENSE', 'lib/**/*.rb']
+    task.options = [
+      '--output-dir', 'doc',
+      '--markup', 'markdown',
+    ]
+  end
+rescue LoadError
+end

data/Readme.markdown

@@ -0,0 +1,49 @@
+# Totter
+
+Totter, as in teeter-totter, let's you work with the Seesaw API in Ruby.
+
+All networking is done with Net::HTTP so you don't have to worry about version conflicts with whatever networking library you may be using.
+
+Read the [documentation](http://rubydoc.info/github/seesawco/totter-rb/master/frames) online.
+
+[![Build Status](https://travis-ci.org/seesawco/totter-rb.png?branch=master)](https://travis-ci.org/seesawco/totter-rb) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/seesawco/totter-rb)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+``` ruby
+gem 'totter'
+```
+
+And then execute:
+
+``` shell
+$ bundle
+```
+
+Or install it yourself as:
+
+``` shell
+$ gem install totter
+```
+
+## Usage
+
+A client takes an optional access token when you initialize it. If you don't provide one, you can still use it to make unauthenticated requests. If you do provide one, it will set the authorization header for all requests.
+
+``` ruby
+> client = Totter::Client.new(access_token: 'your_access_token')
+> current_user = client.me
+> current_user.username
+#=> "soffes"
+> decision = client.decision(5, 3276)
+#=> "Which lamp for the new apartment?"
+> slug = client.slug('d/3I0n0g')
+> slug.decision.user.username
+#=> "soffes"
+```
+
+## Contributing
+
+See the [contributing guide](Contributing.markdown).

data/lib/totter.rb

@@ -0,0 +1,26 @@
+require 'totter/version'
+require 'totter/client'
+require 'totter/error'
+
+# Totter, as in teeter-totter, let's you work with the Seesaw API in Ruby.
+module Totter
+  class << self
+    # Alias for Totter::Client.new
+    #
+    # @return [Totter::Client]
+    def new(options = {})
+      Client.new(options)
+    end
+
+    # Delegate to Totter::Client.new
+    def method_missing(method, *args, &block)
+      return super unless new.respond_to?(method)
+      new.send(method, *args, &block)
+    end
+
+    # Forward respond_to? to Totter::Client.new
+    def respond_to?(method, include_private = false)
+      new.respond_to?(method, include_private) || super(method, include_private)
+    end
+  end
+end

data/lib/totter/client.rb

@@ -0,0 +1,152 @@
+require 'net/http'
+require 'net/https'
+require 'uri'
+require 'multi_json'
+require 'hashie'
+
+require 'totter/client/users'
+require 'totter/client/decisions'
+require 'totter/client/slugs'
+require 'totter/client/timelines'
+require 'totter/client/choices'
+require 'totter/client/votes'
+
+module Totter
+  # API client for interacting with the Seesaw API
+  class Client
+    include Totter::Client::Decisions
+    include Totter::Client::Users
+    include Totter::Client::Slugs
+    include Totter::Client::Timelines
+    include Totter::Client::Choices
+    include Totter::Client::Votes
+
+    attr_reader :access_token
+    attr_reader :api_scheme
+    attr_reader :api_host
+    attr_reader :api_version
+
+    # Initialize a new client.
+    #
+    # @param options [Hash] optionally specify `:access_token`, `:api_scheme`, `:api_host`, `:api_version`, or `:client_token`
+    def initialize(options = {})
+      options = { access_token: options } if options.is_a? String
+
+      @access_token = options[:access_token] if options[:access_token]
+      @api_scheme = (options[:api_scheme] or 'https')
+      @api_host = (options[:api_host] or 'api.seesaw.co')
+      @api_version = (options[:api_version] or 1)
+      @client_token = options[:client_token] if options[:client_token]
+    end
+
+    # API base URL.
+    #
+    # @return [String] API base URL
+    def base_url
+      "#{@api_scheme}://#{@api_host}/v#{@api_version}/"
+    end
+
+    # Is the client has an access token.
+    #
+    # @return [Boolean] true if it is using one and false if it is not
+    def authenticated?
+      @access_token != nil and @access_token.length > 0
+    end
+
+    # Is the client using SSL.
+    #
+    # @return [Boolean] true if it is using SSL and false if it is not
+    def ssl?
+      @api_scheme == 'https'
+    end
+
+  private
+
+    def http
+      return @http if @http
+
+      uri = URI.parse(self.base_url)
+      @http = Net::HTTP.new(uri.host, uri.port)
+      @http.use_ssl = self.ssl?
+      @http
+    end
+
+    def request(method, path, params = nil)
+      # Build request
+      request = build_request(method, URI.parse("#{self.base_url}#{path}"))
+
+      # Add headers
+      request['Authorization'] = "Bearer #{self.access_token}" if authenticated?
+      request['X-Seesaw-Client-Token'] = @client_token if @client_token
+      request['Content-Type'] = 'application/json'
+
+      # Add params as JSON if they exist
+      request.body = MultiJson.dump(params) if method == :post and params
+
+      # Request
+      response = http.request(request)
+
+      # Check for errors
+      handle_error(response)
+
+      # Return the raw response object
+      response
+    end
+
+    def build_request(method, uri)
+      case method
+        when :get
+          Net::HTTP::Get.new(uri.request_uri)
+        when :post
+          Net::HTTP::Post.new(uri.request_uri)
+        when :put
+          Net::HTTP::Put.new(uri.request_uri)
+        when :delete
+          Net::HTTP::Delete.new(uri.request_uri)
+      end
+    end
+
+    def handle_error(response)
+      # Find error or return
+      return unless error = Totter::ERROR_MAP[response.code.to_i]
+
+      # Try to add a useful message
+      message = nil
+      begin
+        message = MultiJson.load(response.body)['error_description']
+      rescue MultiJson::DecodeError => e
+      end
+
+      # Raise error
+      raise error.new(message)
+    end
+
+    def json_request(*args)
+      # Preform request
+      response = request(*args)
+
+      # Parse JSON
+      object = MultiJson.load(response.body)
+
+      # Hash
+      return Hashie::Mash.new(object) if object.is_a? Hash
+
+      # Array
+      return object.map { |h| Hashie::Mash.new(h) } if object.is_a? Array
+
+      # Fallback incase it's not a hash or array
+      object
+    end
+
+    def boolean_from_response(*args)
+      response = request(*args)
+      (200..299).include? response.code.to_i
+    end
+
+    [:get, :post, :put, :delete].each do |method|
+      define_method method do |*args|
+        json_request(method, *args)
+      end
+    end
+  end
+end

data/lib/totter/client/choices.rb

@@ -0,0 +1,74 @@
+module Totter
+  class Client
+    # Client methods for working with choices
+    module Choices
+      # Get a single choice
+      #
+      # @param user_id [Numeric] The choice's decision's user id
+      # @param decision_id [Numeric] The choice's decision's id
+      # @param choice_id [Numeric] The choice's id
+      # @return [Hashie::Mash]
+      # @example
+      #   Seesaw.choice(1, 1, 1)
+      def choice(user_id, decision_id, choice_id)
+        get "users/#{user_id}/decisions/#{decision_id}/choices/#{choice_id}"
+      end
+
+
+      # Create a new choice using a supplied image url
+      #
+      # @param user_id [Numeric] The choice's decision's user id
+      # @param decision_id [Numeric] The choice's decision's id
+      # @param options [Hash]
+      # @option options [String] :image_url The image url (required)
+      # @option options [String] :subject The image label
+      # @option options [String] :link_url A link to this image's page
+      # @option options [String] :link_title The title of a link to this image's page
+      # @return [Hashie::Mash]
+      # @example
+      #   Seesaw.create_choice_for_image(1, 1, image_url: 'http://recess.s3.amazonaws.com/default_avatars/v1/photo_1.png', \
+      #     subject: 'Sample Avatar', link_url: 'https://seesaw.co', link_title: 'Seesaw')
+      def create_choice_for_image(user_id, decision_id, options = {})
+        raise ArgumentError.new('image_url option is required') unless options[:image_url]
+
+        data = {
+          choice: {
+            type: 'image',
+            image_url: options[:image_url],
+            subject: options[:subject],
+            meta: {
+              link_url: options[:link_url],
+              link_title: options[:link_title]
+            }
+          }
+        }
+
+        post "users/#{user_id}/decisions/#{decision_id}/choices", data
+      end
+
+      # Create a new choice upload. Resulting hash contains an #upload parameter
+      # providing keys necessary to perform a signed S3 upload.
+      #
+      # @param user_id [Numeric] The choice's decision's user id
+      # @param decision_id [Numeric] The choice's decision's id
+      # @return [Hashie::Mash]
+      # @example
+      #   Seesaw.create_choice_upload(1, 1)
+      def create_choice_upload(user_id, decision_id)
+        post "users/#{user_id}/decisions/#{decision_id}/choices"
+      end
+
+      # Destroy a choice
+      #
+      # @param user_id [Numeric] The choice's decision's user id
+      # @param decision_id [Numeric] The choice's decision's id
+      # @param choice_id [Numeric] The choice's id
+      # @return [Boolean] True if follow was successful, false otherwise.
+      # @example
+      #   Seesaw.destroy_choice(1, 1)
+      def destroy_choice(user_id, decision_id, choice_id)
+        boolean_from_response :delete, "users/#{user_id}/decisions/#{decision_id}/choices/#{choice_id}"
+      end
+    end
+  end
+end

data/lib/totter/client/decisions.rb

@@ -0,0 +1,91 @@
+module Totter
+  class Client
+    # Client methods for working with decisions
+    module Decisions
+      # Get a single decision
+      #
+      # @param user_id [Numeric] The decision's user id
+      # @param decision_id [Numeric] The decision's id
+      # @return [Hashie::Mash]
+      # @example
+      #   Seesaw.decision(1, 1)
+      def decision(user_id, decision_id)
+        get "users/#{user_id}/decisions/#{decision_id}"
+      end
+
+      # Create a decision
+      #
+      # @param user_id [Numeric] A Seesaw user id
+      # @return [Hashie::Mash]
+      # @example
+      #   Seesaw.create_decision(1)
+      def create_decision(user_id)
+        post "users/#{user_id}/decisions"
+      end
+
+      # Publish a decision
+      #
+      # @param user_id [Numeric] The decision's user id
+      # @param decision_id [Numeric] The decision's id
+      # @param options [Hash] Decision options
+      # @option options [String] :question The question for the decision
+      # @option options [Numeric] :latitude Latitude
+      # @option options [Numeric] :longitude Longitude
+      # @option options [Hash] :choice_attributes Additional attributes for decision choices
+      # @return [Hashie::Mash]
+      # @example
+      #   Seesaw.publish_decision(1, 1, question: 'Why is the sky blue?')
+      def publish_decision(user_id, decision_id, options = {})
+        decision_options = {
+          decision: options
+        }
+
+        post "users/#{user_id}/decisions/#{decision_id}/publish", decision_options
+      end
+
+      # Destroy a decision
+      #
+      # @param user_id [Numeric] The decision's user id
+      # @param decision_id [Numeric] The decision's id
+      # @return [Boolean] True if follow was successful, false otherwise.
+      # @example
+      #   Seesaw.destroy_decision(1, 1)
+      def destroy_decision(user_id, decision_id)
+        boolean_from_response :delete, "users/#{user_id}/decisions/#{decision_id}"
+      end
+
+      # Get decision analytics
+      #
+      # @param user_id [Numeric] The decision's user id
+      # @param decision_id [Numeric] The decision's id
+      # @return [Hashie::Mash]
+      # @example
+      #   Seesaw.decision_analytics(1, 1)
+      def decision_analytics(user_id, decision_id)
+        get "users/#{user_id}/decisions/#{decision_id}/analytics"
+      end
+
+      # Flag a decision for content review
+      #
+      # @param user_id [Numeric] The decision's user id
+      # @param decision_id [Numeric] The decision's id
+      # @return [Boolean] True if follow was successful, false otherwise.
+      # @example
+      #   Seesaw.flag_decision(1, 1)
+      def flag_decision(user_id, decision_id)
+        boolean_from_response :post, "users/#{user_id}/decisions/#{decision_id}/flag"
+      end
+
+      # Unflag a decision for content review
+      #
+      # @param user_id [Numeric] The decision's user id
+      # @param decision_id [Numeric] The decision's id
+      # @return [Boolean] True if follow was successful, false otherwise.
+      # @example
+      #   Seesaw.unflag_decision(1, 1)
+      def unflag_decision(user_id, decision_id)
+        boolean_from_response :post, "users/#{user_id}/decisions/#{decision_id}/unflag"
+      end
+    end
+  end
+end