module Totter
  class Client
    # Client methods for working with timelines.
    module Timelines
      # Default options sent with every timeline request unless otherwise specified.
      DEFAULT_TIMELINE_OPTIONS = {
        :limit => 20
      }

      # 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] An array of `Hashie::Mash` objects representing decisions
      # @example
      #   Totter.global_timeline(limit: 20, since: '1,15')
      def global_timeline(options = DEFAULT_TIMELINE_OPTIONS)
        format_timeline_result 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] An array of `Hashie::Mash` objects representing decisions
      # @example
      #   Totter.global_timeline(limit: 20, since: '1,15')
      def hashtag_timeline(hashtag, options = DEFAULT_TIMELINE_OPTIONS)
        format_timeline_result 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
      #   Totter.global_timeline(limit: 20, since: '1,15')
      def sticker_timeline(sticker, options = DEFAULT_TIMELINE_OPTIONS)
        format_timeline_result 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] An array of `Hashie::Mash` objects representing decisions
      # @example
      #   Totter.global_timeline(limit: 20, since: '1,15')
      def search_timeline(query, options = DEFAULT_TIMELINE_OPTIONS)
        format_timeline_result 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] An array of `Hashie::Mash` objects representing decisions
      # @example
      #   Totter.global_timeline(limit: 20, since: '1,15')
      def flagged_timeline(options = DEFAULT_TIMELINE_OPTIONS)
        format_timeline_result get('timelines/flagged', options)
      end

      # Get recent decisions from a given user.
      #
      # @param user_id [Fixnum] The user ID for the timeline you are trying to view.
      # @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] An array of `Hashie::Mash` objects representing decisions
      # @example
      #   Totter.user_timeline(4, limit: 20, since: '1,15')
      def user_timeline(user_id, options = DEFAULT_TIMELINE_OPTIONS)
        format_timeline_result get("users/#{user_id}/timelines/user", options)
      end

      # Get the friends timeline (also known as "feed" or "home") for a given user.
      # Note, you must use the user ID that belongs to the access token as the `user_id` parameter.
      #
      # Requires authenticatied client.
      #
      # @param user_id [Fixnum] The user ID for the timeline you are trying to view.
      # @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] An array of `Hashie::Mash` objects representing decisions
      # @example
      #   Totter.friends_timeline(4, limit: 20, since: '1,15')
      def friends_timeline(user_id, options = DEFAULT_TIMELINE_OPTIONS)
        format_timeline_result get("users/#{user_id}/timelines/friends", options)
      end

    private

      def format_timeline_result(http_result)
        Hashie::Mash.new(:items => http_result.body, :pusher_channel => http_result.headers['x-pusher-channel'])
      end
    end
  end
end