Merge pull request #165 from allantl/feature/71

Support all standard params for filter, sample statuses and user events

src/main/scala/com/danielasfregola/twitter4s/entities/enums/FilterLevel.scala

@@ -0,0 +1,9 @@
+package com.danielasfregola.twitter4s.entities.enums
+
+object FilterLevel extends Enumeration {
+  type FilterLevel = Value
+
+  val None = Value("none")
+  val Low = Value("low")
+  val Medium = Value("medium")
+}

src/main/scala/com/danielasfregola/twitter4s/http/clients/streaming/sites/TwitterSiteClient.scala

@@ -19,32 +19,32 @@ trait TwitterSiteClient {
 
   /** Starts a streaming connection from Twitter's site API. Streams messages for a set of users,
     * as described in <a href="https://developer.twitter.com/en/docs/tutorials/consuming-streaming-data" target="_blank">Site streams</a>.
-    * The function returns a future of a `TwitterStream` that can be use to close or replace the stream when needed.
+    * The function returns a future of a `TwitterStream` that can be used to close or replace the stream when needed.
     * If there are failures in establishing the initial connection, the Future returned will be completed with a failure.
     * Since it's an asynchronous event stream, all the events will be parsed as entities of type `SiteStreamingMessage`
     * and processed accordingly to the partial function `f`. All the messages that do not match `f` are automatically ignored.
     * For more information see
     * <a href="https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream" target="_blank">
     *   https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream</a>.
     *
-    * @param follow : Empty by default. A comma separated list of user IDs, indicating the users to return statuses for in the stream.
+    * @param follow : Empty by default. List of user IDs, indicating the users whose Tweets should be delivered on the stream.
     *                 For more information <a href="https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream" target="_blank">
     *                   https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream</a>
-    * @param with: `User` by default. Specifies whether to return information for just the users specified in the follow parameter, or include messages from accounts they follow.
+    * @param with : `User` by default. Specifies whether to return information for just the users specified in the follow parameter, or include messages from accounts they follow.
     *              For more information see <a href="https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream" target="_blank">
     *                https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream</a>
-    * @param replies: Optional. By default @replies are only sent if the current user follows both the sender and receiver of the reply.
+    * @param replies : Optional. By default @replies are only sent if the current user follows both the sender and receiver of the reply.
     *                 To receive all the replies, set the argument to `true`.
     *                 For more information see <a href="https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream" target="_blank">
     *                   https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream</a>
-    * @param stringify_friend_ids: Optional. Specifies whether to send the Friend List preamble as an array of integers or an array of strings.
+    * @param stringify_friend_ids : Optional. Specifies whether to send the Friend List preamble as an array of integers or an array of strings.
     *                              For more information see <a href="https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream" tagert="_blank">
     *                                https://developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/site-stream</a>
-    * @param languages : Empty by default. A comma separated list of 'BCP 47' language identifiers.
+    * @param languages : Empty by default. List of 'BCP 47' language identifiers.
     *                    For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters" target="_blank">
     *                      https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters</a>
     * @param stall_warnings : Default to false. Specifies whether stall warnings (`WarningMessage`) should be delivered as part of the updates.
-    * @param f: the function that defines how to process the received messages
+    * @param f : Function that defines how to process the received messages.
     */
   def siteEvents(follow: Seq[Long] = Seq.empty,
                  `with`: WithFilter = WithFilter.User,

src/main/scala/com/danielasfregola/twitter4s/http/clients/streaming/statuses/TwitterStatusClient.scala

@@ -1,6 +1,8 @@
 package com.danielasfregola.twitter4s
 package http.clients.streaming.statuses
 
+import com.danielasfregola.twitter4s.entities.enums.FilterLevel
+import com.danielasfregola.twitter4s.entities.enums.FilterLevel.FilterLevel
 import com.danielasfregola.twitter4s.entities.enums.Language.Language
 import com.danielasfregola.twitter4s.entities.streaming.CommonStreamingMessage
 import com.danielasfregola.twitter4s.http.clients.streaming.statuses.parameters._
@@ -18,62 +20,74 @@ trait TwitterStatusClient {
   /** Starts a streaming connection from Twitter's public API, filtered with the 'follow', 'track' and 'location' parameters.
     * Although all of those three params are optional, at least one must be specified.
     * The track, follow, and locations fields should be considered to be combined with an OR operator.
-    * The function returns a future of a `TwitterStream` that can be use to close or replace the stream when needed.
+    * The function returns a future of a `TwitterStream` that can be used to close or replace the stream when needed.
     * If there are failures in establishing the initial connection, the Future returned will be completed with a failure.
     * Since it's an asynchronous event stream, all the events will be parsed as entities of type `CommonStreamingMessage`
     * and processed accordingly to the partial function `f`. All the messages that do not match `f` are automatically ignored.
     * For more information see
     * <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html" target="_blank">
     *   https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html</a>.
     *
-    * @param follow : Empty by default. A comma separated list of user IDs, indicating the users to return statuses for in the stream.
+    * @param follow : Empty by default. List of user IDs, indicating the users whose Tweets should be delivered on the stream.
     *                 For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html" target="_blank">
     *                   https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html</a>
-    * @param tracks : Empty by default. Keywords to track. Phrases of keywords are specified by a comma-separated list.
-    *                For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html" target="_blank">
+    * @param tracks : Empty by default. List of phrases which will be used to determine what Tweets will be delivered on the stream.
+    *                 Each phrase must be between 1 and 60 bytes, inclusive.
+    *                 For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html" target="_blank">
     *                  https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html</a>
     * @param locations : Empty by default. Specifies a set of bounding boxes to track.
     *                    For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html" target="_blank">
     *                      https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html</a>
-    * @param languages : Empty by default. A comma separated list of 'BCP 47' language identifiers.
+    * @param languages : Empty by default. List of 'BCP 47' language identifiers.
     *                    For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters" target="_blank">
     *                      https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters</a>
     * @param stall_warnings : Default to false. Specifies whether stall warnings (`WarningMessage`) should be delivered as part of the updates.
-    * @param f: the function that defines how to process the received messages
+    * @param filter_level : Default value is none, which includes all available Tweets.
+    *                       Set the minimum value of the filter_level Tweet attribute required to be included in the stream.
+    * @param f : Function that defines how to process the received messages.
     */
   def filterStatuses(follow: Seq[Long] = Seq.empty,
                      tracks: Seq[String] = Seq.empty,
                      locations: Seq[Double] = Seq.empty,
                      languages: Seq[Language] = Seq.empty,
-                     stall_warnings: Boolean = false)(f: PartialFunction[CommonStreamingMessage, Unit]): Future[TwitterStream] = {
+                     stall_warnings: Boolean = false,
+                     filter_level: FilterLevel = FilterLevel.None)(f: PartialFunction[CommonStreamingMessage, Unit]): Future[TwitterStream] = {
     import streamingClient._
     require(follow.nonEmpty || tracks.nonEmpty || locations.nonEmpty, "At least one of 'follow', 'tracks' or 'locations' needs to be non empty")
-    val filters = StatusFilters(follow, tracks, locations, languages, stall_warnings)
+    val filters = StatusFilters(follow, tracks, locations, languages, stall_warnings, filter_level)
     preProcessing()
     Post(s"$statusUrl/filter.json", filters).processStream(f)
   }
 
   /** Starts a streaming connection from Twitter's public API, which is a a small random sample of all public statuses.
     * The Tweets returned by the default access level are the same, so if two different clients connect to this endpoint, they will see the same Tweets.
-    * The function returns a future of a `TwitterStream` that can be use to close or replace the stream when needed.
+    * The function returns a future of a `TwitterStream` that can be used to close or replace the stream when needed.
     * If there are failures in establishing the initial connection, the Future returned will be completed with a failure.
     * Since it's an asynchronous event stream, all the events will be parsed as entities of type `CommonStreamingMessage`
     * and processed accordingly to the partial function `f`. All the messages that do not match `f` are automatically ignored.
     * For more information see
     * <a href="https://developer.twitter.com/en/docs/tweets/sample-realtime/overview/GET_statuse_sample" target="_blank">
     *   https://developer.twitter.com/en/docs/tweets/sample-realtime/overview/GET_statuse_sample</a>.
     *
-    * @param languages : Empty by default. A comma separated list of 'BCP 47' language identifiers.
+    * @param languages : Empty by default. List of 'BCP 47' language identifiers.
     *                    For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters" target="_blank">
     *                      https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters</a>
     * @param stall_warnings : Default to false. Specifies whether stall warnings (`WarningMessage`) should be delivered as part of the updates.
-    * @param f: the function that defines how to process the received messages
+    * @param tracks : Empty by default. List of phrases which will be used to determine what Tweets will be delivered on the stream.
+    *                 Each phrase must be between 1 and 60 bytes, inclusive.
+    *                 For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html" target="_blank">
+    *                  https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter.html</a>
+    * @param filter_level : Default value is none, which includes all available Tweets.
+    *                       Set the minimum value of the filter_level Tweet attribute required to be included in the stream.
+    * @param f : Function that defines how to process the received messages.
     */
   def sampleStatuses(languages: Seq[Language] = Seq.empty,
-                     stall_warnings: Boolean = false)
+                     stall_warnings: Boolean = false,
+                     tracks: Seq[String] = Seq.empty,
+                     filter_level: FilterLevel = FilterLevel.None)
                     (f: PartialFunction[CommonStreamingMessage, Unit]): Future[TwitterStream] = {
     import streamingClient._
-    val parameters = StatusSampleParameters(languages, stall_warnings)
+    val parameters = StatusSampleParameters(languages, stall_warnings, tracks, filter_level)
     preProcessing()
     Get(s"$statusUrl/sample.json", parameters).processStream(f)
   }
@@ -83,19 +97,19 @@ trait TwitterStatusClient {
     * Creative use of a combination of other resources and various access levels can satisfy nearly every application use case.
     * For more information see <a href="https://dev.twitter.com/streaming/reference/get/statuses/firehose" target="_blank">
     *   https://dev.twitter.com/streaming/reference/get/statuses/firehose</a>.
-    * The function returns a future of a `TwitterStream` that can be use to close or replace the stream when needed.
+    * The function returns a future of a `TwitterStream` that can be used to close or replace the stream when needed.
     * If there are failures in establishing the initial connection, the Future returned will be completed with a failure.
     * Since it's an asynchronous event stream, all the events will be parsed as entities of type `CommonStreamingMessage`
     * and processed accordingly to the partial function `f`. All the messages that do not match `f` are automatically ignored.
     *
-    * @param count: Optional. The number of messages to backfill.
+    * @param count : Optional. The number of messages to backfill.
     *               For more information see <a href="https://dev.twitter.com/streaming/overview/request-parameters#count" target="_blank">
     *                 https://dev.twitter.com/streaming/overview/request-parameters#count</a>
-    * @param languages : Empty by default. A comma separated list of 'BCP 47' language identifiers.
+    * @param languages : Empty by default. List of 'BCP 47' language identifiers.
     *                    For more information <a href="https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters" target="_blank">
     *                      https://developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters</a>
     * @param stall_warnings : Default to false. Specifies whether stall warnings (`WarningMessage`) should be delivered as part of the updates.
-    * @param f: the function that defines how to process the received messages.
+    * @param f : Function that defines how to process the received messages.
     */
   def firehoseStatuses(count: Option[Int] = None,
                        languages: Seq[Language] = Seq.empty,

src/main/scala/com/danielasfregola/twitter4s/http/clients/streaming/statuses/parameters/StatusFilters.scala

@@ -1,9 +1,11 @@
 package com.danielasfregola.twitter4s.http.clients.streaming.statuses.parameters
 
+import com.danielasfregola.twitter4s.entities.enums.FilterLevel.FilterLevel
 import com.danielasfregola.twitter4s.entities.enums.Language.Language
 
 private[twitter4s] final case class StatusFilters(follow: Seq[Long],
                                             track: Seq[String],
                                             locations: Seq[Double],
                                             language: Seq[Language],
-                                            stall_warnings: Boolean)
+                                            stall_warnings: Boolean,
+                                            filter_level: FilterLevel)

src/main/scala/com/danielasfregola/twitter4s/http/clients/streaming/statuses/parameters/StatusSampleParameters.scala

@@ -1,6 +1,10 @@
 package com.danielasfregola.twitter4s.http.clients.streaming.statuses.parameters
 
+import com.danielasfregola.twitter4s.entities.enums.FilterLevel.FilterLevel
 import com.danielasfregola.twitter4s.entities.enums.Language.Language
 import com.danielasfregola.twitter4s.http.marshalling.Parameters
 
-private[twitter4s] final case class StatusSampleParameters(language: Seq[Language], stall_warnings: Boolean) extends Parameters
+private[twitter4s] final case class StatusSampleParameters(language: Seq[Language],
+                                                     stall_warnings: Boolean,
+                                                     tracks: Seq[String],
+                                                     filter_level: FilterLevel) extends Parameters