module Totter
  class Client
    # Client methods for working with timelines
    module Timelines
      # Get recent decisions from the global timeline.
      #
      # @param options [Hash] Parameters for returning selected items
      # @option options [Numeric] :limit Number of items to return. Default is 20
      # @option options [String] :since A user_id/decision_id pair in the format '1,15' when paging forward
      # @option options [String] :until A user_id/decision_id pair in the format '1,15' when paging backwards
      # @return [Array]
      # @example
      #   Seesaw.global_timeline(limit: 20, since: '1,15')
      def global_timeline(options = default_options)
        get "timelines/global", options
      end

      # Get recent decisions from a hashtag timeline
      #
      # @param hashtag [String] The hashtag to return
      # @param options [Hash] Parameters for returning selected items
      # @option options [Numeric] :limit Number of items to return. Default is 20
      # @option options [String] :since A user_id/decision_id pair in the format '1,15' when paging forward
      # @option options [String] :until A user_id/decision_id pair in the format '1,15' when paging backwards
      # @return [Array]
      # @example
      #   Seesaw.global_timeline(limit: 20, since: '1,15')
      def hashtag_timeline(hashtag, options = default_options)
        get "timelines/global", options.merge({hashtag: hashtag})
      end

      # Get recent decisions from a sticker timeline
      #
      # @param sticker [String] The sticker to return
      # @param options [Hash] Parameters for returning selected items
      # @option options [Numeric] :limit Number of items to return. Default is 20
      # @option options [String] :since A user_id/decision_id pair in the format '1,15' when paging forward
      # @option options [String] :until A user_id/decision_id pair in the format '1,15' when paging backwards
      # @return [Array]
      # @example
      #   Seesaw.global_timeline(limit: 20, since: '1,15')
      def sticker_timeline(sticker, options = default_options)
        get "timelines/global", options.merge({sticker: sticker})
      end

      # Search for published items
      #
      # @param query [String] The query to search for
      # @param options [Hash] Parameters for returning selected items
      # @option options [Numeric] :limit Number of items to return. Default is 20
      # @option options [String] :since A user_id/decision_id pair in the format '1,15' when paging forward
      # @option options [String] :until A user_id/decision_id pair in the format '1,15' when paging backwards
      # @return [Array]
      # @example
      #   Seesaw.global_timeline(limit: 20, since: '1,15')
      def search_timeline(query, options = default_options)
        get "timelines/search", options.merge({query: query})
      end

      # Get recent decisions from the flagged-for-review timeline
      #
      # @param options [Hash] Parameters for returning selected items
      # @option options [Numeric] :limit Number of items to return. Default is 20
      # @option options [String] :since A user_id/decision_id pair in the format '1,15' when paging forward
      # @option options [String] :until A user_id/decision_id pair in the format '1,15' when paging backwards
      # @return [Array]
      # @example
      #   Seesaw.global_timeline(limit: 20, since: '1,15')
      def flagged_timeline(options = default_options)
        get "timelines/flagged", options
      end

      private

      def default_options
        {
          limit: 20
        }
      end
    end
  end
end