twitter 4.2.0 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. data/CHANGELOG.md +4 -0
  2. data/lib/twitter/api/direct_messages.rb +150 -0
  3. data/lib/twitter/api/favorites.rb +132 -0
  4. data/lib/twitter/api/friends_and_followers.rb +259 -0
  5. data/lib/twitter/api/help.rb +64 -0
  6. data/lib/twitter/api/lists.rb +570 -0
  7. data/lib/twitter/api/places_and_geo.rb +121 -0
  8. data/lib/twitter/api/saved_searches.rb +98 -0
  9. data/lib/twitter/api/search.rb +37 -0
  10. data/lib/twitter/api/spam_reporting.rb +30 -0
  11. data/lib/twitter/api/suggested_users.rb +54 -0
  12. data/lib/twitter/api/timelines.rb +213 -0
  13. data/lib/twitter/api/trends.rb +63 -0
  14. data/lib/twitter/api/tweets.rb +284 -0
  15. data/lib/twitter/api/undocumented.rb +116 -0
  16. data/lib/twitter/api/users.rb +427 -0
  17. data/lib/twitter/api/utils.rb +111 -0
  18. data/lib/twitter/client.rb +41 -13
  19. data/lib/twitter/core_ext/enumerable.rb +1 -1
  20. data/lib/twitter/default.rb +16 -18
  21. data/lib/twitter/error/already_favorited.rb +1 -1
  22. data/lib/twitter/error/already_retweeted.rb +1 -1
  23. data/lib/twitter/profile_banner.rb +18 -0
  24. data/lib/twitter/version.rb +1 -1
  25. data/spec/fixtures/profile_banner.json +1 -0
  26. data/spec/twitter/api/direct_messages_spec.rb +32 -32
  27. data/spec/twitter/api/favorites_spec.rb +114 -0
  28. data/spec/twitter/api/{friendships_spec.rb → friends_and_followers_spec.rb} +146 -146
  29. data/spec/twitter/api/geo_spec.rb +28 -28
  30. data/spec/twitter/api/help_spec.rb +1 -1
  31. data/spec/twitter/api/lists_spec.rb +82 -82
  32. data/spec/twitter/api/saved_searches_spec.rb +1 -1
  33. data/spec/twitter/api/search_spec.rb +1 -17
  34. data/spec/twitter/api/{report_spam_spec.rb → spam_reporting_spec.rb} +1 -1
  35. data/spec/twitter/api/suggested_users_spec.rb +94 -0
  36. data/spec/twitter/api/timelines_spec.rb +138 -0
  37. data/spec/twitter/api/trends_spec.rb +1 -1
  38. data/spec/twitter/api/tweets_spec.rb +249 -0
  39. data/spec/twitter/api/undocumented_spec.rb +103 -0
  40. data/spec/twitter/api/users_spec.rb +308 -17
  41. data/spec/twitter/client_spec.rb +1 -1
  42. data/spec/twitter/profile_banner_spec.rb +13 -0
  43. data/twitter.gemspec +3 -2
  44. metadata +44 -21
  45. data/lib/twitter/api.rb +0 -2558
  46. data/spec/twitter/api/account_spec.rb +0 -152
  47. data/spec/twitter/api/activity_spec.rb +0 -37
  48. data/spec/twitter/api/blocks_spec.rb +0 -122
  49. data/spec/twitter/api/statuses_spec.rb +0 -541
@@ -0,0 +1,64 @@
1
+ require 'twitter/api/utils'
2
+ require 'twitter/configuration'
3
+ require 'twitter/language'
4
+
5
+ module Twitter
6
+ module API
7
+ module Help
8
+ include Twitter::API::Utils
9
+
10
+ # Returns the current configuration used by Twitter
11
+ #
12
+ # @see https://dev.twitter.com/docs/api/1.1/get/help/configuration
13
+ # @rate_limited Yes
14
+ # @authentication_required Requires user context
15
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
16
+ # @return [Twitter::Configuration] Twitter's configuration.
17
+ # @example Return the current configuration used by Twitter
18
+ # Twitter.configuration
19
+ def configuration(options={})
20
+ object_from_response(Twitter::Configuration, :get, "/1.1/help/configuration.json", options)
21
+ end
22
+
23
+ # Returns the list of languages supported by Twitter
24
+ #
25
+ # @see https://dev.twitter.com/docs/api/1.1/get/help/languages
26
+ # @rate_limited Yes
27
+ # @authentication_required Requires user context
28
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
29
+ # @return [Array<Twitter::Language>]
30
+ # @example Return the list of languages Twitter supports
31
+ # Twitter.languages
32
+ def languages(options={})
33
+ collection_from_response(Twitter::Language, :get, "/1.1/help/languages.json", options)
34
+ end
35
+
36
+ # Returns {https://twitter.com/privacy Twitter's Privacy Policy}
37
+ #
38
+ # @see https://dev.twitter.com/docs/api/1.1/get/help/privacy
39
+ # @rate_limited Yes
40
+ # @authentication_required Requires user context
41
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
42
+ # @return [String]
43
+ # @example Return {https://twitter.com/privacy Twitter's Privacy Policy}
44
+ # Twitter.privacy
45
+ def privacy(options={})
46
+ get("/1.1/help/privacy.json", options)[:body][:privacy]
47
+ end
48
+
49
+ # Returns {https://twitter.com/tos Twitter's Terms of Service}
50
+ #
51
+ # @see https://dev.twitter.com/docs/api/1.1/get/help/tos
52
+ # @rate_limited Yes
53
+ # @authentication_required Requires user context
54
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
55
+ # @return [String]
56
+ # @example Return {https://twitter.com/tos Twitter's Terms of Service}
57
+ # Twitter.tos
58
+ def tos(options={})
59
+ get("/1.1/help/tos.json", options)[:body][:tos]
60
+ end
61
+
62
+ end
63
+ end
64
+ end
@@ -0,0 +1,570 @@
1
+ require 'twitter/api/utils'
2
+ require 'twitter/cursor'
3
+ require 'twitter/error/forbidden'
4
+ require 'twitter/error/not_found'
5
+ require 'twitter/list'
6
+ require 'twitter/tweet'
7
+ require 'twitter/user'
8
+
9
+ module Twitter
10
+ module API
11
+ module Lists
12
+ include Twitter::API::Utils
13
+ MAX_USERS_PER_REQUEST = 100
14
+
15
+ # Returns all lists the authenticating or specified user subscribes to, including their own
16
+ #
17
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/list
18
+ # @rate_limited Yes
19
+ # @authentication_required Requires user context
20
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
21
+ # @return [Array<Twitter::List>]
22
+ # @overload memberships(options={})
23
+ # @param options [Hash] A customizable set of options.
24
+ # @example Returns all lists the authenticating user subscribes to
25
+ # Twitter.lists
26
+ # @overload memberships(user, options={})
27
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
28
+ # @param options [Hash] A customizable set of options.
29
+ # @example Returns all lists that @sferik subscribes to
30
+ # Twitter.lists('sferik')
31
+ # Twitter.lists(7505382)
32
+ def lists(*args)
33
+ objects_from_response(Twitter::List, :get, "/1.1/lists/list.json", args)
34
+ end
35
+ alias lists_subscribed_to lists
36
+
37
+ # Show tweet timeline for members of the specified list
38
+ #
39
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/statuses
40
+ # @rate_limited Yes
41
+ # @authentication_required Requires user context
42
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
43
+ # @return [Array<Twitter::Tweet>]
44
+ # @overload list_timeline(list, options={})
45
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
46
+ # @param options [Hash] A customizable set of options.
47
+ # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
48
+ # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
49
+ # @option options [Integer] :count The number of results to retrieve.
50
+ # @example Show tweet timeline for members of the authenticated user's "presidents" list
51
+ # Twitter.list_timeline('presidents')
52
+ # Twitter.list_timeline(8863586)
53
+ # @overload list_timeline(user, list, options={})
54
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
55
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
56
+ # @param options [Hash] A customizable set of options.
57
+ # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
58
+ # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
59
+ # @option options [Integer] :count The number of results to retrieve.
60
+ # @example Show tweet timeline for members of @sferik's "presidents" list
61
+ # Twitter.list_timeline('sferik', 'presidents')
62
+ # Twitter.list_timeline('sferik', 8863586)
63
+ # Twitter.list_timeline(7505382, 'presidents')
64
+ # Twitter.list_timeline(7505382, 8863586)
65
+ def list_timeline(*args)
66
+ options = args.extract_options!
67
+ options.merge_list!(args.pop)
68
+ options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
69
+ collection_from_response(Twitter::Tweet, :get, "/1.1/lists/statuses.json", options)
70
+ end
71
+
72
+ # Removes the specified member from the list
73
+ #
74
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy
75
+ # @rate_limited No
76
+ # @authentication_required Requires user context
77
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
78
+ # @return [Twitter::List] The list.
79
+ # @overload list_remove_member(list, user_to_remove, options={})
80
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
81
+ # @param user_to_remove [Integer, String] The user id or screen name of the list member to remove.
82
+ # @param options [Hash] A customizable set of options.
83
+ # @example Remove @BarackObama from the authenticated user's "presidents" list
84
+ # Twitter.list_remove_member('presidents', 813286)
85
+ # Twitter.list_remove_member('presidents', 'BarackObama')
86
+ # Twitter.list_remove_member(8863586, 'BarackObama')
87
+ # @overload list_remove_member(user, list, user_to_remove, options={})
88
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
89
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
90
+ # @param user_to_remove [Integer, String] The user id or screen name of the list member to remove.
91
+ # @param options [Hash] A customizable set of options.
92
+ # @example Remove @BarackObama from @sferik's "presidents" list
93
+ # Twitter.list_remove_member('sferik', 'presidents', 813286)
94
+ # Twitter.list_remove_member('sferik', 'presidents', 'BarackObama')
95
+ # Twitter.list_remove_member('sferik', 8863586, 'BarackObama')
96
+ # Twitter.list_remove_member(7505382, 'presidents', 813286)
97
+ def list_remove_member(*args)
98
+ list_modify_member(:post, "/1.1/lists/members/destroy.json", args)
99
+ end
100
+
101
+ # List the lists the specified user has been added to
102
+ #
103
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/memberships
104
+ # @rate_limited Yes
105
+ # @authentication_required Requires user context
106
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
107
+ # @return [Twitter::Cursor]
108
+ # @overload memberships(options={})
109
+ # @param options [Hash] A customizable set of options.
110
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
111
+ # @option options [Boolean, String, Integer] :filter_to_owned_lists When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.
112
+ # @example List the lists the authenticated user has been added to
113
+ # Twitter.memberships
114
+ # @overload memberships(user, options={})
115
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
116
+ # @param options [Hash] A customizable set of options.
117
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
118
+ # @option options [Boolean, String, Integer] :filter_to_owned_lists When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.
119
+ # @example List the lists that @sferik has been added to
120
+ # Twitter.memberships('sferik')
121
+ # Twitter.memberships(7505382)
122
+ def memberships(*args)
123
+ lists_from_response(:get, "/1.1/lists/memberships.json", args)
124
+ end
125
+
126
+ # Returns the subscribers of the specified list
127
+ #
128
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/subscribers
129
+ # @rate_limited Yes
130
+ # @authentication_required Requires user context
131
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
132
+ # @return [Twitter::Cursor] The subscribers of the specified list.
133
+ # @overload list_subscribers(list, options={})
134
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
135
+ # @param options [Hash] A customizable set of options.
136
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
137
+ # @example Return the subscribers of the authenticated user's "presidents" list
138
+ # Twitter.list_subscribers('presidents')
139
+ # Twitter.list_subscribers(8863586)
140
+ # @overload list_subscribers(user, list, options={})
141
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
142
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
143
+ # @param options [Hash] A customizable set of options.
144
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
145
+ # @example Return the subscribers of @sferik's "presidents" list
146
+ # Twitter.list_subscribers('sferik', 'presidents')
147
+ # Twitter.list_subscribers('sferik', 8863586)
148
+ # Twitter.list_subscribers(7505382, 'presidents')
149
+ def list_subscribers(*args)
150
+ list_users(:get, "/1.1/lists/subscribers.json", args)
151
+ end
152
+
153
+ # Make the authenticated user follow the specified list
154
+ #
155
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/create
156
+ # @rate_limited No
157
+ # @authentication_required Requires user context
158
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
159
+ # @return [Twitter::List] The specified list.
160
+ # @overload list_subscribe(list, options={})
161
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
162
+ # @param options [Hash] A customizable set of options.
163
+ # @example Subscribe to the authenticated user's "presidents" list
164
+ # Twitter.list_subscribe('presidents')
165
+ # Twitter.list_subscribe(8863586)
166
+ # @overload list_subscribe(user, list, options={})
167
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
168
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
169
+ # @param options [Hash] A customizable set of options.
170
+ # @example Subscribe to @sferik's "presidents" list
171
+ # Twitter.list_subscribe('sferik', 'presidents')
172
+ # Twitter.list_subscribe('sferik', 8863586)
173
+ # Twitter.list_subscribe(7505382, 'presidents')
174
+ def list_subscribe(*args)
175
+ list_from_response(:post, "/1.1/lists/subscribers/create.json", args)
176
+ end
177
+
178
+ # Check if a user is a subscriber of the specified list
179
+ #
180
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/subscribers/show
181
+ # @rate_limited Yes
182
+ # @authentication_required Requires user context
183
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
184
+ # @return [Boolean] true if user is a subscriber of the specified list, otherwise false.
185
+ # @overload list_subscriber?(list, user_to_check, options={})
186
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
187
+ # @param user_to_check [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
188
+ # @param options [Hash] A customizable set of options.
189
+ # @example Check if @BarackObama is a subscriber of the authenticated user's "presidents" list
190
+ # Twitter.list_subscriber?('presidents', 813286)
191
+ # Twitter.list_subscriber?(8863586, 813286)
192
+ # Twitter.list_subscriber?('presidents', 'BarackObama')
193
+ # @overload list_subscriber?(user, list, user_to_check, options={})
194
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
195
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
196
+ # @param user_to_check [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
197
+ # @param options [Hash] A customizable set of options.
198
+ # @example Check if @BarackObama is a subscriber of @sferik's "presidents" list
199
+ # Twitter.list_subscriber?('sferik', 'presidents', 813286)
200
+ # Twitter.list_subscriber?('sferik', 8863586, 813286)
201
+ # Twitter.list_subscriber?(7505382, 'presidents', 813286)
202
+ # Twitter.list_subscriber?('sferik', 'presidents', 'BarackObama')
203
+ # @return [Boolean] true if user is a subscriber of the specified list, otherwise false.
204
+ def list_subscriber?(*args)
205
+ list_user?(:get, "/1.1/lists/subscribers/show.json", args)
206
+ end
207
+
208
+ # Unsubscribes the authenticated user form the specified list
209
+ #
210
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/destroy
211
+ # @rate_limited No
212
+ # @authentication_required Requires user context
213
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
214
+ # @return [Twitter::List] The specified list.
215
+ # @overload list_unsubscribe(list, options={})
216
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
217
+ # @param options [Hash] A customizable set of options.
218
+ # @example Unsubscribe from the authenticated user's "presidents" list
219
+ # Twitter.list_unsubscribe('presidents')
220
+ # Twitter.list_unsubscribe(8863586)
221
+ # @overload list_unsubscribe(user, list, options={})
222
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
223
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
224
+ # @param options [Hash] A customizable set of options.
225
+ # @example Unsubscribe from @sferik's "presidents" list
226
+ # Twitter.list_unsubscribe('sferik', 'presidents')
227
+ # Twitter.list_unsubscribe('sferik', 8863586)
228
+ # Twitter.list_unsubscribe(7505382, 'presidents')
229
+ def list_unsubscribe(*args)
230
+ list_from_response(:post, "/1.1/lists/subscribers/destroy.json", args)
231
+ end
232
+
233
+ # Adds specified members to a list
234
+ #
235
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/members/create_all
236
+ # @note Lists are limited to having 500 members, and you are limited to adding up to 100 members to a list at a time with this method.
237
+ # @rate_limited No
238
+ # @authentication_required Requires user context
239
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
240
+ # @return [Twitter::List] The list.
241
+ # @overload list_add_members(list, users, options={})
242
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
243
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
244
+ # @param options [Hash] A customizable set of options.
245
+ # @example Add @BarackObama and @pengwynn to the authenticated user's "presidents" list
246
+ # Twitter.list_add_members('presidents', ['BarackObama', 'pengwynn'])
247
+ # Twitter.list_add_members('presidents', [813286, 18755393])
248
+ # Twitter.list_add_members(8863586, ['BarackObama', 'pengwynn'])
249
+ # Twitter.list_add_members(8863586, [813286, 18755393])
250
+ # @overload list_add_members(user, list, users, options={})
251
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
252
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
253
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
254
+ # @param options [Hash] A customizable set of options.
255
+ # @example Add @BarackObama and @pengwynn to @sferik's "presidents" list
256
+ # Twitter.list_add_members('sferik', 'presidents', ['BarackObama', 'pengwynn'])
257
+ # Twitter.list_add_members('sferik', 'presidents', [813286, 18755393])
258
+ # Twitter.list_add_members(7505382, 'presidents', ['BarackObama', 'pengwynn'])
259
+ # Twitter.list_add_members(7505382, 'presidents', [813286, 18755393])
260
+ # Twitter.list_add_members(7505382, 8863586, ['BarackObama', 'pengwynn'])
261
+ # Twitter.list_add_members(7505382, 8863586, [813286, 18755393])
262
+ def list_add_members(*args)
263
+ list_modify_members(:post, "/1.1/lists/members/create_all.json", args)
264
+ end
265
+
266
+ # Check if a user is a member of the specified list
267
+ #
268
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/members/show
269
+ # @authentication_required Requires user context
270
+ # @rate_limited Yes
271
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
272
+ # @return [Boolean] true if user is a member of the specified list, otherwise false.
273
+ # @overload list_member?(list, user_to_check, options={})
274
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
275
+ # @param user_to_check [Integer, String] The user ID or screen name of the list member.
276
+ # @param options [Hash] A customizable set of options.
277
+ # @example Check if @BarackObama is a member of the authenticated user's "presidents" list
278
+ # Twitter.list_member?('presidents', 813286)
279
+ # Twitter.list_member?(8863586, 'BarackObama')
280
+ # @overload list_member?(user, list, user_to_check, options={})
281
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
282
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
283
+ # @param user_to_check [Integer, String] The user ID or screen name of the list member.
284
+ # @param options [Hash] A customizable set of options.
285
+ # @example Check if @BarackObama is a member of @sferik's "presidents" list
286
+ # Twitter.list_member?('sferik', 'presidents', 813286)
287
+ # Twitter.list_member?('sferik', 8863586, 'BarackObama')
288
+ # Twitter.list_member?(7505382, 'presidents', 813286)
289
+ def list_member?(*args)
290
+ list_user?(:get, "/1.1/lists/members/show.json", args)
291
+ end
292
+
293
+ # Returns the members of the specified list
294
+ #
295
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/members
296
+ # @rate_limited Yes
297
+ # @authentication_required Requires user context
298
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
299
+ # @return [Twitter::Cursor]
300
+ # @overload list_members(list, options={})
301
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
302
+ # @param options [Hash] A customizable set of options.
303
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
304
+ # @example Return the members of the authenticated user's "presidents" list
305
+ # Twitter.list_members('presidents')
306
+ # Twitter.list_members(8863586)
307
+ # @overload list_members(user, list, options={})
308
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
309
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
310
+ # @param options [Hash] A customizable set of options.
311
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
312
+ # @example Return the members of @sferik's "presidents" list
313
+ # Twitter.list_members('sferik', 'presidents')
314
+ # Twitter.list_members('sferik', 8863586)
315
+ # Twitter.list_members(7505382, 'presidents')
316
+ # Twitter.list_members(7505382, 8863586)
317
+ def list_members(*args)
318
+ list_users(:get, "/1.1/lists/members.json", args)
319
+ end
320
+
321
+ # Add a member to a list
322
+ #
323
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/members/create
324
+ # @note Lists are limited to having 500 members.
325
+ # @rate_limited No
326
+ # @authentication_required Requires user context
327
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
328
+ # @return [Twitter::List] The list.
329
+ # @overload list_add_member(list, user_to_add, options={})
330
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
331
+ # @param user_to_add [Integer, String] The user id or screen name to add to the list.
332
+ # @param options [Hash] A customizable set of options.
333
+ # @example Add @BarackObama to the authenticated user's "presidents" list
334
+ # Twitter.list_add_member('presidents', 813286)
335
+ # Twitter.list_add_member(8863586, 813286)
336
+ # @overload list_add_member(user, list, user_to_add, options={})
337
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
338
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
339
+ # @param user_to_add [Integer, String] The user id or screen name to add to the list.
340
+ # @param options [Hash] A customizable set of options.
341
+ # @example Add @BarackObama to @sferik's "presidents" list
342
+ # Twitter.list_add_member('sferik', 'presidents', 813286)
343
+ # Twitter.list_add_member('sferik', 8863586, 813286)
344
+ # Twitter.list_add_member(7505382, 'presidents', 813286)
345
+ # Twitter.list_add_member(7505382, 8863586, 813286)
346
+ def list_add_member(*args)
347
+ list_modify_member(:post, "/1.1/lists/members/create.json", args)
348
+ end
349
+
350
+ # Deletes the specified list
351
+ #
352
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/destroy
353
+ # @note Must be owned by the authenticated user.
354
+ # @rate_limited No
355
+ # @authentication_required Requires user context
356
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
357
+ # @return [Twitter::List] The deleted list.
358
+ # @overload list_destroy(list, options={})
359
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
360
+ # @param options [Hash] A customizable set of options.
361
+ # @example Delete the authenticated user's "presidents" list
362
+ # Twitter.list_destroy('presidents')
363
+ # Twitter.list_destroy(8863586)
364
+ # @overload list_destroy(user, list, options={})
365
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
366
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
367
+ # @param options [Hash] A customizable set of options.
368
+ # @example Delete @sferik's "presidents" list
369
+ # Twitter.list_destroy('sferik', 'presidents')
370
+ # Twitter.list_destroy('sferik', 8863586)
371
+ # Twitter.list_destroy(7505382, 'presidents')
372
+ # Twitter.list_destroy(7505382, 8863586)
373
+ def list_destroy(*args)
374
+ list_from_response(:post, "/1.1/lists/destroy.json", args)
375
+ end
376
+
377
+ # Updates the specified list
378
+ #
379
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/update
380
+ # @rate_limited No
381
+ # @authentication_required Requires user context
382
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
383
+ # @return [Twitter::List] The created list.
384
+ # @overload list_update(list, options={})
385
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
386
+ # @param options [Hash] A customizable set of options.
387
+ # @option options [String] :mode ('public') Whether your list is public or private. Values can be 'public' or 'private'.
388
+ # @option options [String] :description The description to give the list.
389
+ # @example Update the authenticated user's "presidents" list to have the description "Presidents of the United States of America"
390
+ # Twitter.list_update('presidents', :description => "Presidents of the United States of America")
391
+ # Twitter.list_update(8863586, :description => "Presidents of the United States of America")
392
+ # @overload list_update(user, list, options={})
393
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
394
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
395
+ # @param options [Hash] A customizable set of options.
396
+ # @option options [String] :mode ('public') Whether your list is public or private. Values can be 'public' or 'private'.
397
+ # @option options [String] :description The description to give the list.
398
+ # @example Update the @sferik's "presidents" list to have the description "Presidents of the United States of America"
399
+ # Twitter.list_update('sferik', 'presidents', :description => "Presidents of the United States of America")
400
+ # Twitter.list_update(7505382, 'presidents', :description => "Presidents of the United States of America")
401
+ # Twitter.list_update('sferik', 8863586, :description => "Presidents of the United States of America")
402
+ # Twitter.list_update(7505382, 8863586, :description => "Presidents of the United States of America")
403
+ def list_update(*args)
404
+ list_from_response(:post, "/1.1/lists/update.json", args)
405
+ end
406
+
407
+ # Creates a new list for the authenticated user
408
+ #
409
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/create
410
+ # @note Accounts are limited to 20 lists.
411
+ # @rate_limited No
412
+ # @authentication_required Requires user context
413
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
414
+ # @return [Twitter::List] The created list.
415
+ # @param name [String] The name for the list.
416
+ # @param options [Hash] A customizable set of options.
417
+ # @option options [String] :mode ('public') Whether your list is public or private. Values can be 'public' or 'private'.
418
+ # @option options [String] :description The description to give the list.
419
+ # @example Create a list named 'presidents'
420
+ # Twitter.list_create('presidents')
421
+ def list_create(name, options={})
422
+ object_from_response(Twitter::List, :post, "/1.1/lists/create.json", options.merge(:name => name))
423
+ end
424
+
425
+ # Show the specified list
426
+ #
427
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/show
428
+ # @note Private lists will only be shown if the authenticated user owns the specified list.
429
+ # @rate_limited Yes
430
+ # @authentication_required Requires user context
431
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
432
+ # @return [Twitter::List] The specified list.
433
+ # @overload list(list, options={})
434
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
435
+ # @param options [Hash] A customizable set of options.
436
+ # @example Show the authenticated user's "presidents" list
437
+ # Twitter.list('presidents')
438
+ # Twitter.list(8863586)
439
+ # @overload list(user, list, options={})
440
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
441
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
442
+ # @param options [Hash] A customizable set of options.
443
+ # @example Show @sferik's "presidents" list
444
+ # Twitter.list('sferik', 'presidents')
445
+ # Twitter.list('sferik', 8863586)
446
+ # Twitter.list(7505382, 'presidents')
447
+ # Twitter.list(7505382, 8863586)
448
+ def list(*args)
449
+ list_from_response(:get, "/1.1/lists/show.json", args)
450
+ end
451
+
452
+ # List the lists the specified user follows
453
+ #
454
+ # @see https://dev.twitter.com/docs/api/1.1/get/lists/subscriptions
455
+ # @rate_limited Yes
456
+ # @authentication_required Requires user context
457
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
458
+ # @return [Twitter::Cursor]
459
+ # @overload subscriptions(options={})
460
+ # @param options [Hash] A customizable set of options.
461
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
462
+ # @example List the lists the authenticated user follows
463
+ # Twitter.subscriptions
464
+ # @overload subscriptions(user, options={})
465
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
466
+ # @param options [Hash] A customizable set of options.
467
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
468
+ # @example List the lists that @sferik follows
469
+ # Twitter.subscriptions('sferik')
470
+ # Twitter.subscriptions(7505382)
471
+ def subscriptions(*args)
472
+ lists_from_response(:get, "/1.1/lists/subscriptions.json", args)
473
+ end
474
+
475
+ # Removes specified members from the list
476
+ #
477
+ # @see https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy_all
478
+ # @rate_limited No
479
+ # @authentication_required Requires user context
480
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
481
+ # @return [Twitter::List] The list.
482
+ # @overload list_remove_members(list, users, options={})
483
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
484
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
485
+ # @param options [Hash] A customizable set of options.
486
+ # @example Remove @BarackObama and @pengwynn from the authenticated user's "presidents" list
487
+ # Twitter.list_remove_members('presidents', ['BarackObama', 'pengwynn'])
488
+ # Twitter.list_remove_members('presidents', [813286, 18755393])
489
+ # Twitter.list_remove_members(8863586, ['BarackObama', 'pengwynn'])
490
+ # Twitter.list_remove_members(8863586, [813286, 18755393])
491
+ # @overload list_remove_members(user, list, users, options={})
492
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
493
+ # @param list [Integer, String, Twitter::List] A Twitter list ID, slug, or object.
494
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
495
+ # @param options [Hash] A customizable set of options.
496
+ # @example Remove @BarackObama and @pengwynn from @sferik's "presidents" list
497
+ # Twitter.list_remove_members('sferik', 'presidents', ['BarackObama', 'pengwynn'])
498
+ # Twitter.list_remove_members('sferik', 'presidents', [813286, 18755393])
499
+ # Twitter.list_remove_members(7505382, 'presidents', ['BarackObama', 'pengwynn'])
500
+ # Twitter.list_remove_members(7505382, 'presidents', [813286, 18755393])
501
+ # Twitter.list_remove_members(7505382, 8863586, ['BarackObama', 'pengwynn'])
502
+ # Twitter.list_remove_members(7505382, 8863586, [813286, 18755393])
503
+ def list_remove_members(*args)
504
+ list_modify_members(:post, "/1.1/lists/members/destroy_all.json", args)
505
+ end
506
+
507
+ private
508
+
509
+ # @param request_method [Symbol]
510
+ # @param url [String]
511
+ # @param args [Array]
512
+ # @return [Array<Twitter::User>]
513
+ def list_from_response(request_method, url, args)
514
+ options = args.extract_options!
515
+ options.merge_list!(args.pop)
516
+ options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
517
+ object_from_response(Twitter::List, request_method, url, options)
518
+ end
519
+
520
+ # @param request_method [Symbol]
521
+ # @param url [String]
522
+ # @param args [Array]
523
+ # @return [Array<Twitter::List>]
524
+ def lists_from_response(request_method, url, args)
525
+ options = args.extract_options!
526
+ merge_default_cursor!(options)
527
+ options.merge_user!(args.pop)
528
+ cursor_from_response(:lists, Twitter::List, request_method, url, options, calling_method)
529
+ end
530
+
531
+ def list_users(request_method, url, args)
532
+ options = args.extract_options!
533
+ merge_default_cursor!(options)
534
+ options.merge_list!(args.pop)
535
+ options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
536
+ cursor_from_response(:users, Twitter::User, request_method, url, options, calling_method)
537
+ end
538
+
539
+ def list_user?(request_method, url, args)
540
+ options = args.extract_options!
541
+ options.merge_user!(args.pop)
542
+ options.merge_list!(args.pop)
543
+ options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
544
+ send(request_method.to_sym, url, options)
545
+ true
546
+ rescue Twitter::Error::NotFound, Twitter::Error::Forbidden
547
+ false
548
+ end
549
+
550
+ def list_modify_member(request_method, url, args)
551
+ options = args.extract_options!
552
+ options.merge_user!(args.pop)
553
+ options.merge_list!(args.pop)
554
+ options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
555
+ object_from_response(Twitter::List, request_method, url, options)
556
+ end
557
+
558
+ def list_modify_members(request_method, url, args)
559
+ options = args.extract_options!
560
+ members = args.pop
561
+ options.merge_list!(args.pop)
562
+ options.merge_owner!(args.pop || screen_name) unless options[:owner_id] || options[:owner_screen_name]
563
+ members.flatten.each_slice(MAX_USERS_PER_REQUEST).threaded_map do |users|
564
+ object_from_response(Twitter::List, request_method, url, options.merge_users(users))
565
+ end.last
566
+ end
567
+
568
+ end
569
+ end
570
+ end