trubl 1.4.2

data/.yardopts

@@ -0,0 +1,8 @@
+--no-private
+--protected
+--tag rate_limited:"Rate Limited?"
+--tag authentication_required:"Authentication Required?"
+--markup markdown
+-
+LICENSE.md
+README.md

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Aaron Terrell
+
+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,72 @@
+# Trubl
+
+A Ruby 1.9 interface for the Tout API. Right now, the read only API calls have been implemented, 
+but given proper user auth implementation, the infrastructure is ready for writing back as well.
+
+[![Build Status](https://api.travis-ci.org/Tout/trubl.png)](https://travis-ci.org/Tout/trubl)
+
+Intended as sample code initially, help take it to greatness!
+
+See http://developer.tout.com/ and https://github.com/Tout/trubl for details.
+
+# Using Trubl
+
+## Requirements
+
+* Ruby
+    * Battle tested with MRI 1.9.3 
+    * Specs pass for JRuby 1.7.3
+    * Unkown for Rbx 2.0.0rc1
+* On Debian or Ubuntu you should run `sudo apt-get install libcurl4-gnutls-dev`
+
+## Installation
+```sh
+bundle install
+```
+
+## Run unit tests
+```sh
+bundle exec rspec -d -f d
+```
+
+## Run sample script with valid app credentials
+```sh
+export CLIENT_ID=#{your client id}
+export CLIENT_SECRET=#{your client secret}
+export CALLBACK_URL=#{your callback url}
+bundle exec ruby bin/trubl_sample
+```
+
+## Use a client instance
+Get a client instance, and authenticate with tout.com:
+```rb
+client = Trubl.client('client_id', 'client_secret')
+client.auth()
+# or
+client = Trubl::Client.new('client_id', 'client_secret')
+client.auth()
+```
+
+Search for users matching a keyword
+```rb
+collection = client.search_users('aaron', 2, 4)
+collection.pagination
+# => hash of pagination data
+collection.users
+# => get an array of Trubl::User instances
+```
+
+etc, etc
+
+## Contributing to trubl
+ 
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+
+## Copyright
+
+Copyright (c) 2013 Aaron Terrell, Tout. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :test => :spec
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/trubl.rb

@@ -0,0 +1,30 @@
+if RUBY_ENGINE == 'ruby'
+  require 'yajl'
+  require 'yajl/json_gem'
+end
+
+require 'logger'
+require 'trubl/client'
+
+module Trubl
+  class << self
+
+    # Returns a Trubl::Client instance
+    #
+    # @param [String] client_id
+    # @param [String] client_secret
+    # @param [String] access_token
+    # @return [Trubl::Client]
+    def client(client_id='', client_secret='', callback_url='', access_token=nil)
+      @client = Trubl::Client.new(client_id, client_secret, callback_url, access_token) unless defined?(@client) && @client.access_token == access_token && @client.access_token != nil
+      @client
+    end
+
+    def logger(level=Logger::INFO)
+      @logger = Logger.new(STDOUT) unless defined?(@logger) and @logger.level != level
+      @logger.level = level
+      @logger
+    end
+
+  end
+end

data/lib/trubl/api/category.rb

@@ -0,0 +1,33 @@
+require_relative '../category'
+require_relative '../channel'
+require_relative '../users'
+require_relative '../touts'
+
+module Trubl
+  module API
+    module Category
+
+      # implements categories/:uid
+      # returns Trubl::Category instance or nil
+      def retrieve_category(uid)
+        response = get("categories/#{uid}")
+        Trubl::Category.new(JSON.parse(response.body)["category"])
+      end
+
+      # implements categories/:uid/users
+      # returns Array of Trubl::User instances or nil
+      def retrieve_category_users(uid, order=nil, per_page=nil, page=nil)
+        response = get("categories/#{uid}/users", query: {order: order, per_page: per_page, page: page})
+        Trubl::Users.new.from_response(response)
+      end
+
+      # implements categories/:uid/touts
+      # returns Array of Trubl::Tout instances or nil
+      def retrieve_category_touts(uid, order=nil, per_page=nil, page=nil)
+        response = get("categories/#{uid}/touts", query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+    end
+  end
+end

data/lib/trubl/api/channel.rb

@@ -0,0 +1,32 @@
+require_relative '../channel'
+require_relative '../users'
+require_relative '../touts'
+
+module Trubl
+  module API
+    module Channel
+
+      # implements http://developer.tout.com/api/channel-api/apimethod/retrieve-channel
+      # returns Trubl::Channel instance or nil
+      def retrieve_channel(uid)
+        response = get("/api/v1/channels/#{uid}")
+        Trubl::Channel.new(JSON.parse(response.body)["channel"])
+      end
+
+      # implements http://developer.tout.com/api/channel-api/apimethod/retrieve-channel-users
+      # returns Array of Trubl::User instances or nil
+      def retrieve_channel_users(uid, order=nil, per_page=nil, page=nil)
+        response = get("/api/v1/channels/#{uid}/users", query: {order: order, per_page: per_page, page: page})
+        Trubl::Users.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/channel-api/apimethod/retrieve-channel-touts
+      # returns Array of Trubl::Tout instances or nil
+      def retrieve_channel_touts(uid, order=nil, per_page=nil, page=nil)
+        response = get("/api/v1/channels/#{uid}/touts", query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+    end
+  end
+end

data/lib/trubl/api/conversation.rb

@@ -0,0 +1,31 @@
+require_relative '../conversation'
+require_relative '../touts'
+
+module Trubl
+  module API
+    module Conversation
+
+      # implements http://developer.tout.com/api/conversation-api/apimethod/retrieve-conversation
+      # returns Trubl::Conversation instance or nil
+      def retrieve_conversation(uid)
+        response = get("conversations/#{uid}")
+        Trubl::Conversation.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/conversation-api/apimethod/retrieve-conversation-participants
+      # returns Array of Trubl::User instances or nil
+      def retrieve_conversation_participants(uid, order=nil, per_page=nil, page=nil)
+        response = get("conversations/#{uid}/authors", query: {order: order, per_page: per_page, page: page})
+        Trubl::Users.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/conversation-api/apimethod/retrieve-conversation-touts
+      # returns Array of Trubl::Tout instances or nil
+      def retrieve_conversation_touts(uid, order=nil, per_page=nil, page=nil)
+        response = get("conversations/#{uid}/touts", query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+    end
+  end
+end

data/lib/trubl/api/hashtags.rb

@@ -0,0 +1,45 @@
+require_relative '../hashtags'
+require_relative '../touts'
+
+module Trubl
+  module API
+    module Hashtags
+
+      # returns Trubl::Hashtag instance or nil
+      def retrieve_hashtag(uid)
+        response = get("hashtags/#{uid}")
+        Trubl::Hashtag.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/hashtags-api/apimethod/retrieve-hashtags-touts
+      # returns Array of Trubl::Hastag instances or nil
+      def retrieve_hashtag_touts(uid, order=nil, per_page=nil, page=nil)
+        response = get("hashtags/#{uid}/touts", query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+      # http://developer.tout.com/api/hashtags-api/apimethod/retrieve-list-trending-hashtags
+      # returns Array of Trubl::Hastag instances or nil
+      def retrieve_trending_hashtags(per_page=nil, page=nil)
+        response = get("trending_hashtags", query: {per_page: per_page, page: page})
+        Trubl::Hashtags.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/conversation-api/apimethod/retrieve-conversation
+      # returns Array of Trubl::Hastag instances or nil
+      def retrieve_suggested_hashtags(q, limit=nil)
+        response = get("suggested_hashtags", query: {q: q, limit: limit})
+        Trubl::Hashtags.new.from_response(response)
+      end
+
+      def follow_hashtag(uid)
+        post("/api/v1/hashtags/#{uid}/subscribes")
+      end
+
+      def unfollow_hashtag(uid)
+        delete("/api/v1/hashtags/#{uid}/subscribes")
+      end
+
+    end
+  end
+end

data/lib/trubl/api/me.rb

@@ -0,0 +1,68 @@
+require_relative '../user'
+require_relative '../authorizations'
+
+module Trubl
+  module API
+    module Me
+      # implements http://developer.tout.com/api-overview/me-api
+
+      # implements http://developer.tout.com/api/me-api/apimethod/retrieve-authenticated-user
+      # returns Trubl::User instance or nil
+      def get_me
+        Trubl::User.new.from_response(get("me"))
+      end
+
+      # TODO update_me should return meaningful exceptions instead of nil
+      def update_me(params={})
+        return nil if params.blank? or params[:user].blank?
+
+        allowed_properties = [:email, :password, :password_confirmation, :username, :avatar, :fullname, :location, :bio, :headline]
+        unallowed_properties = params[:user].keys.map(&:to_sym) - allowed_properties
+
+        raise "#{unallowed_properties.join(', ')} are not supported" if unallowed_properties.present?
+
+        response = put("me", {body: params})
+
+        Trubl::User.new.from_response(response)
+      end
+
+      # implements me/authorizations
+      def get_my_authorizations
+        response = get("me/authorizations")
+        Trubl::Authorizations.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/me-api/apimethod/retrieve-sharing-settings
+      def get_my_fb_sharing_settings
+        response = get("me/sharing/facebook")
+        JSON.parse(response.body)
+      end
+
+      # implements http://developer.tout.com/api/me-api/apimethod/retrieve-list-touts-authenticated-user
+      # returns Array of Trubl::Tout instances or nil
+      def get_my_touts(order="most_recent_first", per_page=nil, page=nil)
+        response = get("me/touts", query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+      # returns Array of Trubl::Tout instances or nil
+      def get_my_liked_touts(order="most_recent_first", per_page=nil, page=nil)
+        response = get("me/likes", query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+      # returns Array of Trubl::User instances or nil
+      def friends(order=nil, per_page=nil, page=nil)
+        response = get("me/friends", query: {order: order, per_page: per_page, page: page})
+        Trubl::Users.new.from_response(response)
+      end
+
+      # order, per_page, page arent supported at the moment
+      def widgets(order=nil, per_page=nil, page=nil)
+        response = get("me/widgets")
+        Trubl::Widgets.new.from_response(response)
+      end
+
+    end
+  end
+end

data/lib/trubl/api/search.rb

@@ -0,0 +1,35 @@
+require_relative '../hashtags'
+require_relative '../touts'
+require_relative '../users'
+
+module Trubl
+  module API
+    module Search
+      # implements http://developer.tout.com/api-overview/search-api
+
+      def search_hashtags(query, per_page=nil, page=nil)
+        response = search('hashtags', query, per_page, page)
+        Trubl::Hashtags.new.from_response(response)
+      end
+
+      def search_users(query, per_page=nil, page=nil)
+        response = search('users', query, per_page, page)
+        Trubl::Users.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/search-api/apimethod/search-touts
+      def search_touts(query, per_page=nil, page=nil)
+        response = search('touts', query, per_page, page)
+        Trubl::Touts.new.from_response(response)
+      end
+
+      private
+
+      def search(type, query, per_page=nil, page=nil)
+        response = get("search/#{type}", query: {q: query, per_page: per_page, page: page})
+        response
+      end
+
+    end
+  end
+end

data/lib/trubl/api/streams.rb

@@ -0,0 +1,14 @@
+require_relative '../touts'
+
+module Trubl
+  module API
+    module Streams
+
+      def retrieve_stream_touts(uid, order=nil, per_page=nil, page=nil)
+        response = get("streams/#{uid}/touts", query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+    end
+  end
+end

data/lib/trubl/api/suggested_users.rb

@@ -0,0 +1,16 @@
+require_relative '../users'
+
+module Trubl
+  module API
+    module Suggested_Users
+
+      # http://localhost:3000/api/v1/suggested_users.json?access_token=aa054fba7f546a2cafc1f6b960c0742cd45eabb8e188044704efb36ce8d1d5ae&q=puiyee
+      # returns Array of Trubl::User instances or nil
+      def suggested_users(query, per_page=nil, page=nil)
+        response = get("suggested_users.json", query: {q: query, per_page: per_page, page: page})
+        Trubl::Users.new.from_response(response)
+      end
+
+    end
+  end
+end

data/lib/trubl/api/touts.rb

@@ -0,0 +1,143 @@
+require_relative '../touts'
+require_relative '../users'
+
+# todo: all api modules should simply return responses
+
+module Trubl
+  module API
+    module Touts
+      # implements http://developer.tout.com/api-overview/touts-api
+
+      # http://developer.tout.com/api/touts-api/apimethod/retrieve-list-featured-touts
+      # returns Array of Trubl::Tout instances or nil
+      def featured_touts(opts={})
+        response = get("featured", query: {per_page: opts[:per_page], page: opts[:page]})
+        Trubl::Touts.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/retrieve-list-users-who-have-liked-tout
+      # returns Array of Trubl::User instances or nil
+      def tout_liked_by(uid, order=nil, per_page=nil, page=nil)
+        response = get("touts/#{uid}/liked_by", query: {order: order, per_page: per_page, page: page})
+        Trubl::Users.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/retrieve-tout
+      # returns Trubl::Tout instance or nil
+      def retrieve_tout(uid)
+        response = get("touts/#{uid}")
+        Trubl::Tout.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/users-api/apimethod/retrieve-touts
+      # @param uids [Array<String>] of tout uids
+      # @return [Array<Trubl::Tout>]
+      def retrieve_touts(uids=[])
+        uids = (uids.is_a?(Array) ? uids : [uids]).compact.uniq.sort
+        return [] if uids.blank?
+
+        requests = uids.in_groups_of(100, false).collect do |uid_group|
+          {path: "touts", query: {uids: uid_group.join(',')} }
+        end
+
+        multi_request(:get, requests).
+          collect { |response| Trubl::Touts.new.from_response(response) }.
+          flatten.
+          compact
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/retrieve-touts-conversation
+      # returns Trubl::Conversation instance or nil
+      def retrieve_tout_conversation(uid)
+        response = get("touts/#{uid}/conversation")
+        Trubl::Conversation.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/retrieve-latest-touts
+      # returns Array of Trubl::Tout instances or nil
+      def latest_touts(per_page=nil, page=nil)
+        response = get("latest", query: {per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/retrieve-touts-hashtags-and-users-followed-given-user
+      # ToDo: is this api call documented in the right place?
+      # returns Array of Trubl::Tout instances or nil
+      def retrieve_updates(order=nil, per_page=nil, page=nil)
+        response = get("me/updates",query: {order: order, per_page: per_page, page: page})
+        Trubl::Touts.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/create-tout
+      # returns Trubl::Tout instance or nil
+      def create_tout(params={})
+        response = if params[:url].nil?
+          params[:data] = params[:tout].delete(:data)
+          multipart_post("touts", params)
+        else
+          post("touts", params)
+        end
+
+        Trubl::Tout.new.from_response(response)
+      end
+
+      def update_tout(uid, params={})
+        return nil if params.blank? or params[:tout].blank?
+
+        raise "Not implemented" if params[:tout].keys.map(&:to_sym) != [:text]
+
+        response = put("touts/#{uid}", {body: params})
+
+        Trubl::Tout.new.from_response(response)
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/delete-tout
+      # returns true or false
+      def delete_tout(uid)
+        delete("touts/#{uid}").code == 200
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/tout
+      # ToDo: could return an updated Tout object
+      # returns true or false
+      def like_tout(uid)
+        response = post("touts/#{uid}/likes")
+        
+        JSON.parse(response.body)["like"]["status"] == "liked"
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/unlike-tout
+      # ToDo: could return an updated Tout object
+      # returns true or false
+      def unlike_tout(uid)
+        response = delete("touts/#{uid}/likes")
+
+        JSON.parse(response.body)["like"]["status"] == "not_liked"
+      end
+
+      def retout_tout(uid)
+        response = post("touts/#{uid}/retouts")
+        if response.code == 200
+          Trubl::Tout.new.from_response(response)
+        else
+          nil
+        end
+      end
+
+
+=begin
+      # implements http://developer.tout.com/api/touts-api/apimethod/share-tout
+      def share_tout(uid)
+        response = post("touts/#{uid}/share")
+        raise "Not implemented"
+      end
+
+      # implements http://developer.tout.com/api/touts-api/apimethod/update-touts-text
+      def update_tout_text(uid)
+        response = put("touts/#{uid}.json?")
+        raise "Not implemented; see update_tout"
+      end
+=end
+    end
+  end
+end