assistly 0.1

data/lib/assistly/client/interaction.rb

@@ -0,0 +1,41 @@
+module Assistly
+  class Client
+    # Defines methods related to interactions
+    module Interaction
+      
+      # Returns extended information of up to 100 interactions
+      #
+      #   @option options [Boolean, String, Integer]
+      #   @example Return extended information for 12345
+      #     Assistly.interactions(:since_id => 12345)
+      #     Assistly.interactions(:since_id => 12345, :count => 5)
+      # @format :json
+      # @authenticated true
+      # @see http://dev.assistly.com/docs/api/interactions
+      def interactions(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("interactions",options)
+        response['results']
+      end
+
+      # Creates an interaction
+      #
+      # @format :json
+      # @authenticated true
+      # @rate_limited true
+      # @return [Array] The requested users.
+      # @see http://dev.assistly.com/docs/api/interactions/create
+      # @example Create a new interaction
+      #   Assistly.create_interaction(:interaction_subject => "this is an api test", :customer_email => "foo@example.com")
+      def create_interaction(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = post('interactions', options)
+        if response['success']
+          return response['results']
+        else
+          return response['errors']
+        end
+      end
+    end
+  end
+end

data/lib/assistly/client/user.rb

@@ -0,0 +1,38 @@
+module Assistly
+  class Client
+    # Defines methods related to users
+    module User
+      # Returns extended information of a given user
+      #
+      # @overload user(user, options={})
+      #   @param user [Integer] An Assitely user ID
+      #   @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      #   @return [Hashie::Mash] The requested user.
+      #   @example Return extended information for 12345
+      #     Assistly.user(12345)
+      # @format :json, :xml
+      # @authenticated true
+      # @see http://dev.assistly.com/docs/api/users/show
+      def user(id,*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get("users/#{id}",options)
+        response.user
+      end
+
+      # Returns extended information for up to 100 users
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited true
+      # @return [Array] The requested users.
+      # @see http://dev.assistly.com/docs/api/users
+      # @example Return extended information account users
+      #   Assistly.users
+      def users(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        response = get('users', options)
+        response['results'].collect{|result| result.user}
+      end
+    end
+  end
+end

data/lib/assistly/client/utils.rb

@@ -0,0 +1,83 @@
+# -*- encoding: utf-8 -*-
+module Assistly
+  class Client
+    # @private
+    module Utils
+      private
+
+      # Returns the configured screen name or the screen name of the authenticated user
+      #
+      # @return [String]
+      def get_screen_name
+        @screen_name ||= self.verify_credentials.screen_name
+      end
+
+      # Take a single user ID or screen name and merge it into an options hash with the correct key
+      #
+      # @param user_id_or_screen_name [Integer, String] A Twitter user ID or screen_name.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
+      def merge_user_into_options!(user_id_or_screen_name, options={})
+        case user_id_or_screen_name
+        when Fixnum
+          options[:user_id] = user_id_or_screen_name
+        when String
+          options[:screen_name] = user_id_or_screen_name
+        end
+        options
+      end
+
+      # Take a multiple user IDs and screen names and merge them into an options hash with the correct keys
+      #
+      # @param users_id_or_screen_names [Array] An array of Twitter user IDs or screen_names.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
+      def merge_users_into_options!(user_ids_or_screen_names, options={})
+        user_ids, screen_names = [], []
+        user_ids_or_screen_names.flatten.each do |user_id_or_screen_name|
+          case user_id_or_screen_name
+          when Fixnum
+            user_ids << user_id_or_screen_name
+          when String
+            screen_names << user_id_or_screen_name
+          end
+        end
+        options[:user_id] = user_ids.join(',') unless user_ids.empty?
+        options[:screen_name] = screen_names.join(',') unless screen_names.empty?
+        options
+      end
+
+      # Take a single owner ID or owner screen name and merge it into an options hash with the correct key
+      # (for Twitter API endpoints that want :owner_id and :owner_screen_name)
+      #
+      # @param owner_id_or_owner_screen_name [Integer, String] A Twitter user ID or screen_name.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
+      def merge_owner_into_options!(owner_id_or_owner_screen_name, options={})
+        case owner_id_or_owner_screen_name
+        when Fixnum
+          options[:owner_id] = owner_id_or_owner_screen_name
+        when String
+          options[:owner_screen_name] = owner_id_or_owner_screen_name
+        end
+        options
+      end
+
+      # Take a single list ID or slug and merge it into an options hash with the correct key
+      #
+      # @param list_id_or_slug [Integer, String] A Twitter list ID or slug.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
+      def merge_list_into_options!(list_id_or_screen_name, options={})
+        case list_id_or_screen_name
+        when Fixnum
+          options[:list_id] = list_id_or_screen_name
+        when String
+          options[:slug] = list_id_or_screen_name
+        end
+        options
+      end
+
+    end
+  end
+end

data/lib/assistly/configuration.rb

@@ -0,0 +1,104 @@
+require 'faraday'
+require 'assistly/version'
+
+module Assistly
+  # Defines constants and methods related to configuration
+  module Configuration
+    # An array of valid keys in the options hash when configuring a {Twitter::API}
+    VALID_OPTIONS_KEYS = [
+      :adapter,
+      :consumer_key,
+      :consumer_secret,
+      :endpoint,
+      :format,
+      :oauth_token,
+      :oauth_token_secret,
+      :proxy,
+      :subdomain,
+      :user_agent,
+      :version].freeze
+
+    # An array of valid request/response formats
+    #
+    # @note Not all methods support the XML format.
+    VALID_FORMATS = [
+      :json].freeze
+
+    # The adapter that will be used to connect if none is set
+    #
+    # @note The default faraday adapter is Net::HTTP.
+    DEFAULT_ADAPTER = Faraday.default_adapter
+
+    # By default, don't set an application key
+    DEFAULT_CONSUMER_KEY = nil
+
+    # By default, don't set an application secret
+    DEFAULT_CONSUMER_SECRET = nil
+
+    # The response format appended to the path and sent in the 'Accept' header if none is set
+    #
+    # @note JSON is preferred over XML because it is more concise and faster to parse.
+    DEFAULT_FORMAT = :json
+
+    # By default, don't set a user oauth token
+    DEFAULT_OAUTH_TOKEN = nil
+
+    # By default, don't set a user oauth secret
+    DEFAULT_OAUTH_TOKEN_SECRET = nil
+
+    # By default, don't use a proxy server
+    DEFAULT_PROXY = nil
+    
+    # By default, don't set a subdomain
+    DEFAULT_SUBDOMAIN = "zencoder"
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_USER_AGENT = "Assistly Ruby Gem #{Assistly::VERSION}".freeze
+
+    # The user agent that will be sent to the API endpoint if none is set
+    DEFAULT_VERSION = "v1".freeze
+    
+    # The endpoint that will be used to connect if none is set
+    #
+    # @note This is configurable in case you want to use HTTP instead of HTTPS, specify a different API version, or use a Twitter-compatible endpoint.
+    # @see http://status.net/wiki/Twitter-compatible_API
+    # @see http://en.blog.wordpress.com/2009/12/12/twitter-api/
+    # @see http://staff.tumblr.com/post/287703110/api
+    # @see http://developer.typepad.com/typepad-twitter-api/twitter-api.html
+    DEFAULT_ENDPOINT = "https://#{DEFAULT_SUBDOMAIN}.assistly.com/api/#{DEFAULT_VERSION}/".freeze
+
+    # @private
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # When this module is extended, set all configuration options to their default values
+    def self.extended(base)
+      base.reset
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    def configure
+      yield self
+    end
+
+    # Create a hash of options and their values
+    def options
+      Hash[VALID_OPTIONS_KEYS.map {|key| [key, send(key)] }]
+    end
+
+    # Reset all configuration options to defaults
+    def reset
+      self.adapter            = DEFAULT_ADAPTER
+      self.consumer_key       = DEFAULT_CONSUMER_KEY
+      self.consumer_secret    = DEFAULT_CONSUMER_SECRET
+      self.endpoint           = DEFAULT_ENDPOINT
+      self.format             = DEFAULT_FORMAT
+      self.oauth_token        = DEFAULT_OAUTH_TOKEN
+      self.oauth_token_secret = DEFAULT_OAUTH_TOKEN_SECRET
+      self.proxy              = DEFAULT_PROXY
+      self.subdomain          = DEFAULT_SUBDOMAIN
+      self.user_agent         = DEFAULT_USER_AGENT
+      self.version            = DEFAULT_VERSION
+      self
+    end
+  end
+end

data/lib/assistly/connection.rb

@@ -0,0 +1,39 @@
+require 'faraday_middleware'
+require 'faraday/request/multipart_with_file'
+require 'faraday/response/raise_http_4xx'
+require 'faraday/response/raise_http_5xx'
+
+module Assistly
+  # @private
+  module Connection
+    private
+
+    def connection(raw=false)
+      options = {
+        :headers => {'Accept' => "application/#{format}", 'User-Agent' => user_agent},
+        :proxy => proxy,
+        :ssl => {:verify => false},
+        :url => api_endpoint,
+      }
+
+      Faraday.new(options) do |builder|
+        builder.use Faraday::Request::MultipartWithFile
+        builder.use Faraday::Request::OAuth, authentication if authenticated?
+        builder.use Faraday::Request::Multipart
+        builder.use Faraday::Request::UrlEncoded
+        builder.use Faraday::Response::RaiseHttp4xx
+        builder.use Faraday::Response::Rashify unless raw
+        unless raw
+          case format.to_s.downcase
+          when 'json'
+            builder.use Faraday::Response::ParseJson
+          when 'xml'
+            builder.use Faraday::Response::ParseXml
+          end
+        end
+        builder.use Faraday::Response::RaiseHttp5xx
+        builder.adapter(adapter)
+      end
+    end
+  end
+end

data/lib/assistly/error.rb

@@ -0,0 +1,62 @@
+module Assistly
+  # Custom error class for rescuing from all Assistly errors
+  class Error < StandardError
+    attr_reader :http_headers
+
+    def initialize(message, http_headers)
+      http_headers ||= {}
+      @http_headers = Hash[http_headers]
+      super message
+    end
+
+    def ratelimit_reset
+      Time.at(@http_headers.values_at('x-ratelimit-reset', 'X-RateLimit-Reset').detect {|value| value }.to_i)
+    end
+
+    def ratelimit_limit
+      @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect {|value| value }.to_i
+    end
+
+    def ratelimit_remaining
+      @http_headers.values_at('x-ratelimit-limit', 'X-RateLimit-Limit').detect {|value| value }.to_i
+    end
+
+    def retry_after
+      [(ratelimit_reset - Time.now).ceil, 0].max
+    end
+  end
+
+  # Raised when Assistly returns the HTTP status code 400
+  class BadRequest < Error; end
+
+  # Raised when Assistly returns the HTTP status code 401
+  class Unauthorized < Error; end
+
+  # Raised when Assistly returns the HTTP status code 403
+  class Forbidden < Error; end
+
+  # Raised when Assistly returns the HTTP status code 404
+  class NotFound < Error; end
+
+  # Raised when Assistly returns the HTTP status code 406
+  class NotAcceptable < Error; end
+
+  # Raised when Assistly returns the HTTP status code 420
+  class EnhanceYourCalm < Error
+    # The number of seconds your application should wait before requesting date from the Search API again
+    #
+    # @see http://dev.Assistly.com/pages/rate-limiting
+    def retry_after
+      @http_headers.values_at('retry-after', 'Retry-After').detect {|value| value }.to_i
+    end
+  end
+
+  # Raised when Assistly returns the HTTP status code 500
+  class InternalServerError < Error; end
+
+  # Raised when Assistly returns the HTTP status code 502
+  class BadGateway < Error; end
+
+  # Raised when Assistly returns the HTTP status code 503
+  class ServiceUnavailable < Error; end
+end

data/lib/assistly/request.rb

@@ -0,0 +1,44 @@
+module Assistly
+  # Defines HTTP request methods
+  module Request
+    # Perform an HTTP GET request
+    def get(path, options={}, raw=false)
+      request(:get, path, options, raw)
+    end
+
+    # Perform an HTTP POST request
+    def post(path, options={}, raw=false)
+      request(:post, path, options, raw)
+    end
+
+    # Perform an HTTP PUT request
+    def put(path, options={}, raw=false)
+      request(:put, path, options, raw)
+    end
+
+    # Perform an HTTP DELETE request
+    def delete(path, options={}, raw=false)
+      request(:delete, path, options, raw)
+    end
+
+    private
+
+    # Perform an HTTP request
+    def request(method, path, options, raw=false)
+      response = connection(raw).send(method) do |request|
+        case method
+        when :get, :delete
+          request.url(formatted_path(path), options)
+        when :post, :put
+          request.path = formatted_path(path)
+          request.body = options unless options.empty?
+        end
+      end
+      raw ? response : response.body
+    end
+
+    def formatted_path(path)
+      [path, format].compact.join('.')
+    end
+  end
+end

data/lib/assistly/search.rb

@@ -0,0 +1,473 @@
+require 'cgi'
+
+module Twitter
+  # Wrapper for the Twitter Search API
+  #
+  # @note As of April 1st 2010, the Search API provides an option to retrieve
+  #   "popular tweets" in addition to real-time search results. In an upcoming release,
+  #   this will become the default and clients that don't want to receive popular tweets
+  #   in their search results will have to explicitly opt-out. See {Twitter::Search#result_type}
+  #   for more information.
+  # @note The user ids in the Search API are different from those in the REST API
+  #   ({http://dev.twitter.com/pages/api_overview about the two APIs}). This defect is
+  #   being tracked by {http://code.google.com/p/twitter-api/issues/detail?id=214 Issue 214}.
+  #   This means that the to_user_id and from_user_id field vary from the actualy user id on
+  #   Twitter.com. Applications will have to perform a screen name-based lookup with
+  #   {Twitter::Client::User#user} to get the correct user id if necessary.
+  # @see http://dev.twitter.com/doc/get/search Twitter Search API Documentation
+  class Search < API
+    include Enumerable
+
+    # @private
+    attr_reader :query
+
+    # Creates a new search
+    #
+    # @example Initialize a Twitter search
+    #   search = Twitter::Search.new
+    def initialize(*)
+      clear
+      super
+    end
+
+    alias :api_endpoint :search_endpoint
+
+    # Clears all query filters and cached results
+    #
+    # @return [Twitter::Search] self
+    # @example Clear a search for "twitter"
+    #   search = Twitter::Search.new
+    #   search.containing("twitter").fetch
+    #   search.clear
+    #   search.fetch_next_page #=> 403 Forbidden: You must enter a query.
+    def clear
+      @cache = nil
+      @query = {}
+      @query[:q] = []
+      @query[:tude] = []
+      self
+    end
+
+    # @group Generic filters
+
+    # Search query
+    #
+    # @param query [String] The search query.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter"
+    #   Twitter::Search.new.containing("twitter").fetch
+    #   Twitter::Search.new.contains("twitter").fetch   # Shortcut for the above
+    #   Twitter::Search.new.q("twitter").fetch          # Even shorter-cut
+    def containing(query)
+      @query[:q] << query
+      self
+    end
+    alias :contains :containing
+    alias :q :containing
+
+    # Negative search query
+    #
+    # @param query [String] The negative search query.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "beer" but not "root"
+    #   Twitter::Search.new.containing("beer").not_containing("root").fetch
+    #   Twitter::Search.new.containing("beer").does_not_contain("root").fetch # Same as above
+    #   Twitter::Search.new.containing("beer").excluding("root").fetch        # Shortcut for the above
+    #   Twitter::Search.new.contains("beer").excludes("root").fetch           # Even shorter
+    #   Twitter::Search.new.q("beer").exclude("root").fetch                   # Shorter still
+    def not_containing(query)
+      @query[:q] << "-#{query}"
+      self
+    end
+    alias :does_not_contain :not_containing
+    alias :excluding :not_containing
+    alias :excludes :not_containing
+    alias :exclude :not_containing
+
+    # Search for a specific phrase instead of a group of words
+    #
+    # @param phrase [String] The search phrase.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing the phrase "happy hour"
+    #   Twitter::Search.new.phrase("happy hour").fetch
+    def phrase(phrase)
+      @query[:phrase] = phrase
+      self
+    end
+
+    # Only include tweets that contain URLs
+    #
+    # @param filter [String] A type of search filter. Only 'links' is currently effective.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" and URLs
+    #   Twitter::Search.new.containing("twitter").filter.fetch
+    def filter(filter='links')
+      @query[:q] << "filter:#{filter}"
+      self
+    end
+
+    # Only include tweets from after a given date
+    #
+    # @param date [String] A date in the format YYYY-MM-DD.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" since October 1, 2010
+    #   Twitter::Search.new.containing("twitter").since_date("2010-10-01").fetch
+    def since_date(date)
+      @query[:since] = date
+      self
+    end
+    alias :since :since_date
+
+    # Only include tweets from before a given date
+    #
+    # @param date [String] A date in the format YYYY-MM-DD.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" up until October 1, 2010
+    #   Twitter::Search.new.containing("twitter").since_date("2010-10-01").fetch
+    def until_date(date)
+      @query[:until] = date
+      self
+    end
+    alias :until :until_date
+
+    # Only include tweets with a positive attitude
+    #
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing happy emoticons
+    #   Twitter::Search.new.positive.fetch
+    def positive
+      @query[:tude] << ":)"
+      self
+    end
+
+    # Only include tweets with a negative attitude
+    #
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing sad emoticons
+    #   Twitter::Search.new.negative.fetch
+    def negative
+      @query[:tude] << ":("
+      self
+    end
+
+    # Only include tweets that are asking a question
+    #
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing question marks
+    #   Twitter::Search.new.question.fetch
+    def question
+      @query[:tude] << "?"
+      self
+    end
+
+    # @group Demographic filters
+
+    # Only include tweets in a given language, specified by an ISO 639-1 code
+    #
+    # @param code [String] An ISO 639-1 code.
+    # @return [Twitter::Search] self
+    # @example Return an array of French-language tweets containing "twitter"
+    #   Twitter::Search.new.containing("twitter").language("fr").fetch
+    #   Twitter::Search.new.containing("twitter").lang("fr").fetch     # Shortcut for the above
+    # @see http://en.wikipedia.org/wiki/ISO_639-1
+    def language(code)
+      @query[:lang] = code
+      self
+    end
+    alias :lang :language
+
+    # Specify the locale of the query you are sending
+    #
+    # @param code [String] An ISO 639-1 code (only 'ja' is currently effective).
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets from Japan containing "twitter"
+    #   Twitter::Search.new.containing("twitter").locale("ja").fetch
+    # @see http://en.wikipedia.org/wiki/ISO_639-1
+    def locale(code)
+      @query[:locale] = code
+      self
+    end
+
+    # Only include tweets from users in a given radius of a given location
+    #
+    # @param lat [Float] A latitude.
+    # @param long [Float] A longitude.
+    # @param radius [String] A search radius, specified in either 'mi' (miles) or 'km' (kilometers).
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets within a 1-mile radius of Twitter HQ
+    #   Twitter::Search.new.containing("twitter").geocode(37.781157, -122.398720, "1mi").fetch
+    def geocode(lat, long, radius)
+      @query[:geocode] = [lat, long, radius].join(",")
+      self
+    end
+
+    # Only include tweets from users in a given place, specified by a place ID
+    #
+    # @param place_id [String] A place ID.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets from San Francisco
+    #   Twitter::Search.new.place("5a110d312052166f").fetch
+    def place(place_id)
+      @query[:q] << "place:#{place_id}"
+      self
+    end
+
+    # Only include tweets from users near a given location
+    #
+    # @param location [String] A location name.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets near San Francisco
+    #   Twitter::Search.new.near("San Francisco").fetch
+    def near(location)
+      @query[:q] << "near:#{location.inspect}"
+      self
+    end
+
+    # @group User filters
+
+    # Only include tweets from a given user, specified by screen_name
+    #
+    # @param screen_name [String] A Twitter user name.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" from @sferik
+    #   Twitter::Search.new.containing("twitter").from("sferik").fetch
+    def from(screen_name)
+      @query[:q] << "from:#{screen_name}"
+      self
+    end
+
+    # Exclude tweets from a given user, specified by screen_name
+    #
+    # @param screen_name [String] A Twitter user name.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" from everyone except @sferik
+    #   Twitter::Search.new.containing("twitter").not_from("sferik").fetch
+    def not_from(screen_name)
+      @query[:q] << "-from:#{screen_name}"
+      self
+    end
+
+    # Only include tweets to a given user, specified by screen_name
+    #
+    # @param screen_name [String] A Twitter user name.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" to @sferik
+    #   Twitter::Search.new.containing("twitter").to("sferik").fetch
+    def to(screen_name)
+      @query[:q] << "to:#{screen_name}"
+      self
+    end
+
+    # Exclude tweets to a given user, specified by screen_name
+    #
+    # @param screen_name [String] A Twitter user name.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" to everyone except @sferik
+    #   Twitter::Search.new.containing("twitter").not_to("sferik").fetch
+    def not_to(screen_name)
+      @query[:q] << "-to:#{screen_name}"
+      self
+    end
+
+    # Only include tweets mentioning a given user, specified by screen_name
+    #
+    # @param screen_name [String] A Twitter user name.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" and mentioning @sferik
+    #   Twitter::Search.new.containing("twitter").mentioning("sferik").fetch
+    def mentioning(screen_name)
+      @query[:q] << "@#{screen_name.gsub('@', '')}"
+      self
+    end
+    alias :referencing :mentioning
+    alias :mentions :mentioning
+    alias :references :mentioning
+
+    # Exclude tweets mentioning a given user, specified by screen_name
+    #
+    # @param screen_name [String] A Twitter user name.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" but not mentioning @sferik
+    #   Twitter::Search.new.containing("twitter").not_mentioning("sferik").fetch
+    def not_mentioning(screen_name)
+      @query[:q] << "-@#{screen_name.gsub('@', '')}"
+      self
+    end
+    alias :not_referencing :not_mentioning
+    alias :does_not_mention :not_mentioning
+    alias :does_not_reference :not_mentioning
+
+    # @group Twitter filters
+
+    # Only include retweets
+    #
+    # @return [Twitter::Search] self
+    # @example Return an array of retweets containing "twitter"
+    #   Twitter::Search.new.containing("twitter").retweets.fetch
+    def retweets
+      @query[:q] << "rt"
+      self
+    end
+
+    # Only include original status updates (i.e., not retweets)
+    #
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter", excluding retweets
+    #   Twitter::Search.new.containing("twitter").no_retweets.fetch
+    def no_retweets
+      @query[:q] << "-rt"
+      self
+    end
+
+    # Only include tweets containing a given hashtag
+    #
+    # @param tag [String] A Twitter hashtag.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing the hashtag #FollowFriday
+    #   Twitter::Search.new.hashtag("FollowFriday").fetch
+    def hashtag(tag)
+      @query[:q] << "\##{tag.gsub('#', '')}"
+      self
+    end
+
+    # Exclude tweets containing a given hashtag
+    #
+    # @param tag [String] A Twitter hashtag.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing the hashtag #FollowFriday but not #FF
+    #   Twitter::Search.new.hashtag("FollowFriday").excluding_hashtag("FF").fetch
+    #   Twitter::Search.new.hashtag("FollowFriday").excludes_hashtag("FF").fetch  # Shortcut for the above
+    #   Twitter::Search.new.hashtag("FollowFriday").exclude_hashtag("FF").fetch   # Even shorter
+    def excluding_hashtag(tag)
+      @query[:q] << "-\##{tag.gsub('#', '')}"
+      self
+    end
+    alias :excludes_hashtag :excluding_hashtag
+    alias :exclude_hashtag :excluding_hashtag
+
+    # Only include tweets with an ID greater than the specified ID
+    #
+    # @param id [Integer] A Twitter status ID.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" with an ID greater than 123456789
+    #   Twitter::Search.new.containing("twitter").since_id(123456789).fetch
+    def since_id(id)
+      @query[:since_id] = id
+      self
+    end
+
+    # Only include tweets with an ID less than or equal to the specified ID
+    #
+    # @param id [Integer] A Twitter status ID.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter" with an ID less than or equal to 123456789
+    #   Twitter::Search.new.containing("twitter").max_id(123456789).fetch
+    #
+    def max_id(id)
+      @query[:max_id] = id
+      self
+    end
+    alias :max :max_id
+
+    # Specify what type of search results you want to receive
+    #
+    # @param result_type [String] The type of results you want to receive ('recent', 'popular', or 'mixed').
+    # @return [Twitter::Search] self
+    # @example Return an array of recent tweets containing "twitter"
+    #   Twitter::Search.new.containing("twitter").result_type("recent").fetch
+    def result_type(result_type="mixed")
+      @query[:result_type] = result_type
+      self
+    end
+
+    # Only include tweets from a given source
+    #
+    # @param source [String] A Twitter source.
+    # @return [Twitter::Search] self
+    # @example Return an array of tweets containing "twitter", posted from Hibari
+    #   Twitter::Search.new.containing("twitter").source("Hibari").fetch
+    def source(source)
+      @query[:q] << "source:#{source}"
+      self
+    end
+
+    # @group Paging
+
+    # Specify the number of tweets to return per page
+    #
+    # @param number [Integer] The number of tweets to return per page, up to a max of 100.
+    # @return [Twitter::Search] self
+    # @example Return an array of 100 tweets containing "twitter"
+    #   Twitter::Search.new.containing("twitter").per_page(100).fetch
+    def per_page(number=15)
+      @query[:rpp] = number
+      self
+    end
+    alias :rpp :per_page
+
+    # Specify the page number to return, up to a maximum of roughly 1500 results
+    #
+    # @param number [Integer] The page number (starting at 1) to return, up to a max of roughly 1500 results (based on {Twitter::Client::Search#per_page} * {Twitter::Client::Search#page}).
+    # @return [Twitter::Search] self
+    # @example Return the second page of tweets containing "twitter"
+    #   Twitter::Search.new.containing("twitter").page(2).fetch
+    def page(number)
+      @query[:page] = number
+      self
+    end
+
+    # Indicates if there are additional results to be fetched
+    #
+    # @return [Boolean]
+    # @example
+    #   search = Twitter::Search.new.containing("twitter").fetch
+    #   search.next_page? #=> true
+    def next_page?
+      fetch if @cache.nil?
+      !!@cache["next_page"]
+    end
+
+    # @group Fetching
+
+    # Fetch the next page of results of the query
+    #
+    # @return [Array] Tweets that match specified query.
+    # @example Return the first two pages of results
+    #   search = Twitter::Search.new.containing("twitter").fetch
+    #   search.fetch_next_page
+    def fetch_next_page
+      if next_page?
+        @cache = get("search", CGI.parse(@cache["next_page"][1..-1]))
+        @cache.results
+      end
+    end
+
+    # Fetch the results of the query
+    #
+    # @param force [Boolean] Ignore the cache and hit the API again.
+    # @return [Array] Tweets that match specified query.
+    # @example Return an array of tweets containing "twitter"
+    #   search = Twitter::Search.new.containing("twitter").fetch
+    def fetch(force=false)
+      if @cache.nil? || force
+        options = query.dup
+        options[:q] = options[:q].join(" ")
+        @cache = get("search", options)
+      end
+      @cache.results
+    end
+
+    # Calls block once for each element in self, passing that element as a parameter
+    #
+    # @yieldparam [Hashie::Mash] result Tweet that matches specified query.
+    # @return [Array] Tweets that match specified query.
+    # @example
+    #   Twitter::Search.new.containing('marry me').to('justinbieber').each do |result|
+    #     puts "#{result.from_user}: #{result.text}"
+    #   end
+    def each
+      fetch.each{|result| yield result}
+    end
+
+  end
+end