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
@@ -1,3 +1,7 @@
1
+ 4.3.0
2
+ -----
3
+ * [Add Twitter::API#profile_banner](https://github.com/sferik/twitter/commit/5879ef3fcc486ac3849426ef0d44ee0288ed9599)
4
+
1
5
  4.2.0
2
6
  -----
3
7
  * [Use new resource for `Twitter::API#retweets_of_me`](https://github.com/sferik/twitter/commit/d88ca1e91af06e748c31dcda287326028cf28258)
@@ -0,0 +1,150 @@
1
+ require 'twitter/api/utils'
2
+ require 'twitter/direct_message'
3
+ require 'twitter/user'
4
+
5
+ module Twitter
6
+ module API
7
+ module DirectMessages
8
+ include Twitter::API::Utils
9
+
10
+ # Returns the 20 most recent direct messages sent to the authenticating user
11
+ #
12
+ # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages
13
+ # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
14
+ # @rate_limited Yes
15
+ # @authentication_required Requires user context
16
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
17
+ # @return [Array<Twitter::DirectMessage>] Direct messages sent to the authenticating user.
18
+ # @param options [Hash] A customizable set of options.
19
+ # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
20
+ # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
21
+ # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
22
+ # @option options [Integer] :page Specifies the page of results to retrieve.
23
+ # @example Return the 20 most recent direct messages sent to the authenticating user
24
+ # Twitter.direct_messages_received
25
+ def direct_messages_received(options={})
26
+ collection_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages.json", options)
27
+ end
28
+
29
+ # Returns the 20 most recent direct messages sent by the authenticating user
30
+ #
31
+ # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/sent
32
+ # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
33
+ # @rate_limited Yes
34
+ # @authentication_required Requires user context
35
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
36
+ # @return [Array<Twitter::DirectMessage>] Direct messages sent by the authenticating user.
37
+ # @param options [Hash] A customizable set of options.
38
+ # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
39
+ # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
40
+ # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
41
+ # @option options [Integer] :page Specifies the page of results to retrieve.
42
+ # @example Return the 20 most recent direct messages sent by the authenticating user
43
+ # Twitter.direct_messages_sent
44
+ def direct_messages_sent(options={})
45
+ collection_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages/sent.json", options)
46
+ end
47
+
48
+ # Returns a direct message
49
+ #
50
+ # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/show
51
+ # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
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 [Twitter::DirectMessage] The requested messages.
56
+ # @param id [Integer] A Tweet IDs.
57
+ # @param options [Hash] A customizable set of options.
58
+ # @example Return the direct message with the id 1825786345
59
+ # Twitter.direct_message(1825786345)
60
+ def direct_message(id, options={})
61
+ options[:id] = id
62
+ object_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages/show.json", options)
63
+ end
64
+
65
+ # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
66
+ # @rate_limited Yes
67
+ # @authentication_required Requires user context
68
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
69
+ # @return [Array<Twitter::DirectMessage>] The requested messages.
70
+ # @overload direct_messages(options={})
71
+ # Returns the 20 most recent direct messages sent to the authenticating user
72
+ #
73
+ # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages
74
+ # @param options [Hash] A customizable set of options.
75
+ # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
76
+ # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
77
+ # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
78
+ # @option options [Integer] :page Specifies the page of results to retrieve.
79
+ # @example Return the 20 most recent direct messages sent to the authenticating user
80
+ # Twitter.direct_messages
81
+ # @overload direct_messages(*ids)
82
+ # Returns direct messages
83
+ #
84
+ # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/show
85
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
86
+ # @example Return the direct message with the id 1825786345
87
+ # Twitter.direct_messages(1825786345)
88
+ # @overload direct_messages(*ids, options)
89
+ # Returns direct messages
90
+ #
91
+ # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/show
92
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
93
+ # @param options [Hash] A customizable set of options.
94
+ def direct_messages(*args)
95
+ options = args.extract_options!
96
+ if args.empty?
97
+ direct_messages_received(options)
98
+ else
99
+ args.flatten.threaded_map do |id|
100
+ direct_message(id, options)
101
+ end
102
+ end
103
+ end
104
+
105
+ # Destroys direct messages
106
+ #
107
+ # @see https://dev.twitter.com/docs/api/1.1/post/direct_messages/destroy
108
+ # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
109
+ # @rate_limited No
110
+ # @authentication_required Requires user context
111
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
112
+ # @return [Array<Twitter::DirectMessage>] Deleted direct message.
113
+ # @overload direct_message_destroy(*ids)
114
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
115
+ # @example Destroys the direct message with the ID 1825785544
116
+ # Twitter.direct_message_destroy(1825785544)
117
+ # @overload direct_message_destroy(*ids, options)
118
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
119
+ # @param options [Hash] A customizable set of options.
120
+ def direct_message_destroy(*args)
121
+ options = args.extract_options!
122
+ args.flatten.threaded_map do |id|
123
+ object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/destroy.json", options.merge(:id => id))
124
+ end
125
+ end
126
+
127
+ # Sends a new direct message to the specified user from the authenticating user
128
+ #
129
+ # @see https://dev.twitter.com/docs/api/1.1/post/direct_messages/new
130
+ # @rate_limited No
131
+ # @authentication_required Requires user context
132
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
133
+ # @return [Twitter::DirectMessage] The sent message.
134
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
135
+ # @param text [String] The text of your direct message, up to 140 characters.
136
+ # @param options [Hash] A customizable set of options.
137
+ # @example Send a direct message to @sferik from the authenticating user
138
+ # Twitter.direct_message_create('sferik', "I'm sending you this message via @gem!")
139
+ # Twitter.direct_message_create(7505382, "I'm sending you this message via @gem!") # Same as above
140
+ def direct_message_create(user, text, options={})
141
+ options.merge_user!(user)
142
+ options[:text] = text
143
+ object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/new.json", options)
144
+ end
145
+ alias d direct_message_create
146
+ alias m direct_message_create
147
+
148
+ end
149
+ end
150
+ end
@@ -0,0 +1,132 @@
1
+ require 'twitter/api/utils'
2
+ require 'twitter/error/already_favorited'
3
+ require 'twitter/error/forbidden'
4
+ require 'twitter/tweet'
5
+ require 'twitter/user'
6
+
7
+ module Twitter
8
+ module API
9
+ module Favorites
10
+ include Twitter::API::Utils
11
+
12
+ # @see https://dev.twitter.com/docs/api/1.1/get/favorites/list
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 [Array<Twitter::Tweet>] favorite Tweets.
17
+ # @overload favorites(options={})
18
+ # Returns the 20 most recent favorite Tweets for the authenticating user
19
+ #
20
+ # @param options [Hash] A customizable set of options.
21
+ # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 100.
22
+ # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
23
+ # @example Return the 20 most recent favorite Tweets for the authenticating user
24
+ # Twitter.favorites
25
+ # @overload favorites(user, options={})
26
+ # Returns the 20 most recent favorite Tweets for the specified user
27
+ #
28
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
29
+ # @param options [Hash] A customizable set of options.
30
+ # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 100.
31
+ # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
32
+ # @example Return the 20 most recent favorite Tweets for @sferik
33
+ # Twitter.favorites('sferik')
34
+ def favorites(*args)
35
+ options = args.extract_options!
36
+ if user = args.pop
37
+ options.merge_user!(user)
38
+ end
39
+ collection_from_response(Twitter::Tweet, :get, "/1.1/favorites/list.json", options)
40
+ end
41
+ alias favourites favorites
42
+
43
+ # Un-favorites the specified Tweets as the authenticating user
44
+ #
45
+ # @see https://dev.twitter.com/docs/api/1.1/post/favorites/destroy
46
+ # @rate_limited No
47
+ # @authentication_required Requires user context
48
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
49
+ # @return [Array<Twitter::Tweet>] The un-favorited Tweets.
50
+ # @overload unfavorite(*ids)
51
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
52
+ # @example Un-favorite the tweet with the ID 25938088801
53
+ # Twitter.unfavorite(25938088801)
54
+ # @overload unfavorite(*ids, options)
55
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
56
+ # @param options [Hash] A customizable set of options.
57
+ def unfavorite(*args)
58
+ options = args.extract_options!
59
+ args.flatten.threaded_map do |id|
60
+ object_from_response(Twitter::Tweet, :post, "/1.1/favorites/destroy.json", options.merge(:id => id))
61
+ end
62
+ end
63
+ alias favorite_destroy unfavorite
64
+ alias favourite_destroy unfavorite
65
+ alias unfavourite unfavorite
66
+
67
+ # Favorites the specified Tweets as the authenticating user
68
+ #
69
+ # @see https://dev.twitter.com/docs/api/1.1/post/favorites/create
70
+ # @rate_limited No
71
+ # @authentication_required Requires user context
72
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
73
+ # @return [Array<Twitter::Tweet>] The favorited Tweets.
74
+ # @overload favorite(*ids)
75
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
76
+ # @example Favorite the Tweet with the ID 25938088801
77
+ # Twitter.favorite(25938088801)
78
+ # @overload favorite(*ids, options)
79
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
80
+ # @param options [Hash] A customizable set of options.
81
+ def favorite(*args)
82
+ options = args.extract_options!
83
+ args.flatten.threaded_map do |id|
84
+ begin
85
+ object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", options.merge(:id => id))
86
+ rescue Twitter::Error::Forbidden => error
87
+ raise unless error.message == Twitter::Error::AlreadyFavorited::MESSAGE
88
+ end
89
+ end.compact
90
+ end
91
+ alias fav favorite
92
+ alias fave favorite
93
+ alias favorite_create favorite
94
+ alias favourite_create favorite
95
+
96
+ # Favorites the specified Tweets as the authenticating user and raises an error if one has already been favorited
97
+ #
98
+ # @see https://dev.twitter.com/docs/api/1.1/post/favorites/create
99
+ # @rate_limited No
100
+ # @authentication_required Requires user context
101
+ # @raise [Twitter::Error::AlreadyFavorited] Error raised when tweet has already been favorited.
102
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
103
+ # @return [Array<Twitter::Tweet>] The favorited Tweets.
104
+ # @overload favorite(*ids)
105
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
106
+ # @example Favorite the Tweet with the ID 25938088801
107
+ # Twitter.favorite(25938088801)
108
+ # @overload favorite(*ids, options)
109
+ # @param ids [Array<Integer>, Set<Integer>] An array of Tweet IDs.
110
+ # @param options [Hash] A customizable set of options.
111
+ def favorite!(*args)
112
+ options = args.extract_options!
113
+ args.flatten.threaded_map do |id|
114
+ begin
115
+ object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", options.merge(:id => id))
116
+ rescue Twitter::Error::Forbidden => error
117
+ if error.message == "You have already favorited this status"
118
+ raise Twitter::Error::AlreadyFavorited.new("Tweet with the ID #{id} has already been favorited by the authenticated user.")
119
+ else
120
+ raise
121
+ end
122
+ end
123
+ end
124
+ end
125
+ alias fav! favorite!
126
+ alias fave! favorite!
127
+ alias favorite_create! favorite!
128
+ alias favourite_create! favorite!
129
+
130
+ end
131
+ end
132
+ end
@@ -0,0 +1,259 @@
1
+ require 'twitter/api/utils'
2
+ require 'twitter/cursor'
3
+ require 'twitter/error/forbidden'
4
+ require 'twitter/relationship'
5
+ require 'twitter/user'
6
+
7
+ module Twitter
8
+ module API
9
+ module FriendsAndFollowers
10
+ include Twitter::API::Utils
11
+
12
+ # @see https://dev.twitter.com/docs/api/1.1/get/friends/ids
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::Cursor]
17
+ # @overload friend_ids(options={})
18
+ # Returns an array of numeric IDs for every user the authenticated user is following
19
+ #
20
+ # @param options [Hash] A customizable set of options.
21
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
22
+ # @example Return the authenticated user's friends' IDs
23
+ # Twitter.friend_ids
24
+ # @overload friend_ids(user, options={})
25
+ # Returns an array of numeric IDs for every user the specified user is following
26
+ #
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
+ # @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.
30
+ # @example Return @sferik's friends' IDs
31
+ # Twitter.friend_ids('sferik')
32
+ # Twitter.friend_ids(7505382) # Same as above
33
+ def friend_ids(*args)
34
+ ids_from_response(:get, "/1.1/friends/ids.json", args)
35
+ end
36
+
37
+ # @see https://dev.twitter.com/docs/api/1.1/get/followers/ids
38
+ # @rate_limited Yes
39
+ # @authentication_required Requires user context
40
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
41
+ # @return [Twitter::Cursor]
42
+ # @overload follower_ids(options={})
43
+ # Returns an array of numeric IDs for every user following the authenticated user
44
+ #
45
+ # @param options [Hash] A customizable set of options.
46
+ # @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.
47
+ # @example Return the authenticated user's followers' IDs
48
+ # Twitter.follower_ids
49
+ # @overload follower_ids(user, options={})
50
+ # Returns an array of numeric IDs for every user following the specified user
51
+ #
52
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
53
+ # @param options [Hash] A customizable set of options.
54
+ # @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
55
+ # @example Return @sferik's followers' IDs
56
+ # Twitter.follower_ids('sferik')
57
+ # Twitter.follower_ids(7505382) # Same as above
58
+ def follower_ids(*args)
59
+ ids_from_response(:get, "/1.1/followers/ids.json", args)
60
+ end
61
+
62
+ # Returns the relationship of the authenticating user to the comma separated list of up to 100 screen_names or user_ids provided. Values for connections can be: following, following_requested, followed_by, none.
63
+ #
64
+ # @see https://dev.twitter.com/docs/api/1.1/get/friendships/lookup
65
+ # @rate_limited Yes
66
+ # @authentication_required Requires user context
67
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
68
+ # @return [Array<Twitter::User>] The requested users.
69
+ # @overload friendships(*users)
70
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
71
+ # @example Return extended information for @sferik and @pengwynn
72
+ # Twitter.friendships('sferik', 'pengwynn')
73
+ # Twitter.friendships('sferik', 14100886) # Same as above
74
+ # Twitter.friendships(7505382, 14100886) # Same as above
75
+ # @overload friendships(*users, options)
76
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
77
+ # @param options [Hash] A customizable set of options.
78
+ def friendships(*args)
79
+ options = args.extract_options!
80
+ options.merge_users!(Array(args))
81
+ collection_from_response(Twitter::User, :get, "/1.1/friendships/lookup.json", options)
82
+ end
83
+
84
+ # Returns an array of numeric IDs for every user who has a pending request to follow the authenticating user
85
+ #
86
+ # @see https://dev.twitter.com/docs/api/1.1/get/friendships/incoming
87
+ # @rate_limited Yes
88
+ # @authentication_required Requires user context
89
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
90
+ # @return [Twitter::Cursor]
91
+ # @param options [Hash] A customizable set of options.
92
+ # @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.
93
+ # @example Return an array of numeric IDs for every user who has a pending request to follow the authenticating user
94
+ # Twitter.friendships_incoming
95
+ def friendships_incoming(options={})
96
+ merge_default_cursor!(options)
97
+ cursor_from_response(:ids, nil, :get, "/1.1/friendships/incoming.json", options)
98
+ end
99
+
100
+ # Returns an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request
101
+ #
102
+ # @see https://dev.twitter.com/docs/api/1.1/get/friendships/outgoing
103
+ # @rate_limited Yes
104
+ # @authentication_required Requires user context
105
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
106
+ # @return [Twitter::Cursor]
107
+ # @param options [Hash] A customizable set of options.
108
+ # @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.
109
+ # @example Return an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request
110
+ # Twitter.friendships_outgoing
111
+ def friendships_outgoing(options={})
112
+ merge_default_cursor!(options)
113
+ cursor_from_response(:ids, nil, :get, "/1.1/friendships/outgoing.json", options)
114
+ end
115
+
116
+ # Allows the authenticating user to follow the specified users, unless they are already followed
117
+ #
118
+ # @see https://dev.twitter.com/docs/api/1.1/post/friendships/create
119
+ # @rate_limited No
120
+ # @authentication_required Requires user context
121
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
122
+ # @return [Array<Twitter::User>] The followed users.
123
+ # @overload(*users)
124
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
125
+ # @example Follow @sferik
126
+ # Twitter.follow('sferik')
127
+ # @overload(*users, options)
128
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
129
+ # @param options [Hash] A customizable set of options.
130
+ # @option options [Boolean] :follow (false) Enable notifications for the target user.
131
+ def follow(*args)
132
+ options = args.extract_options!
133
+ # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
134
+ # so only send follow if it's true
135
+ options[:follow] = true if !!options.delete(:follow)
136
+ existing_friends = Thread.new do
137
+ friend_ids.ids
138
+ end
139
+ new_friends = Thread.new do
140
+ users(args).map(&:id)
141
+ end
142
+ follow!(new_friends.value - existing_friends.value, options)
143
+ end
144
+ alias friendship_create follow
145
+
146
+ # Allows the authenticating user to follow the specified users
147
+ #
148
+ # @see https://dev.twitter.com/docs/api/1.1/post/friendships/create
149
+ # @rate_limited No
150
+ # @authentication_required Requires user context
151
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
152
+ # @return [Array<Twitter::User>] The followed users.
153
+ # @overload follow!(*users)
154
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
155
+ # @example Follow @sferik
156
+ # Twitter.follow!('sferik')
157
+ # @overload follow!(*users, options)
158
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
159
+ # @param options [Hash] A customizable set of options.
160
+ # @option options [Boolean] :follow (false) Enable notifications for the target user.
161
+ def follow!(*args)
162
+ options = args.extract_options!
163
+ # Twitter always turns on notifications if the "follow" option is present, even if it's set to false
164
+ # so only send follow if it's true
165
+ options[:follow] = true if !!options.delete(:follow)
166
+ args.flatten.threaded_map do |user|
167
+ begin
168
+ options.merge_user!(user)
169
+ object_from_response(Twitter::User, :post, "/1.1/friendships/create.json", options)
170
+ rescue Twitter::Error::Forbidden
171
+ # This error will be raised if the user doesn't have permission to
172
+ # follow list_member, for whatever reason.
173
+ end
174
+ end.compact
175
+ end
176
+ alias friendship_create! follow!
177
+
178
+ # Allows the authenticating user to unfollow the specified users
179
+ #
180
+ # @see https://dev.twitter.com/docs/api/1.1/post/friendships/destroy
181
+ # @rate_limited No
182
+ # @authentication_required Requires user context
183
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
184
+ # @return [Array<Twitter::User>] The unfollowed users.
185
+ # @overload unfollow(*users)
186
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
187
+ # @example Unfollow @sferik
188
+ # Twitter.unfollow('sferik')
189
+ # @overload unfollow(*users)
190
+ # @param users [Array<Integer, String, Twitter::User>, Set<Integer, String, Twitter::User>] An array of Twitter user IDs, screen names, or objects.
191
+ # @param options [Hash] A customizable set of options.
192
+ def unfollow(*args)
193
+ threaded_users_from_response(:post, "/1.1/friendships/destroy.json", args)
194
+ end
195
+ alias friendship_destroy unfollow
196
+
197
+ # Allows one to enable or disable retweets and device notifications from the specified user.
198
+ #
199
+ # @see https://dev.twitter.com/docs/api/1.1/post/friendships/update
200
+ # @rate_limited No
201
+ # @authentication_required Requires user context
202
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
203
+ # @return [Twitter::Relationship]
204
+ # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, or object.
205
+ # @param options [Hash] A customizable set of options.
206
+ # @option options [Boolean] :device Enable/disable device notifications from the target user.
207
+ # @option options [Boolean] :retweets Enable/disable retweets from the target user.
208
+ # @example Enable rewteets and devise notifications for @sferik
209
+ # Twitter.friendship_update('sferik', :device => true, :retweets => true)
210
+ def friendship_update(user, options={})
211
+ options.merge_user!(user)
212
+ object_from_response(Twitter::Relationship, :post, "/1.1/friendships/update.json", options)
213
+ end
214
+
215
+ # Returns detailed information about the relationship between two users
216
+ #
217
+ # @see https://dev.twitter.com/docs/api/1.1/get/friendships/show
218
+ # @rate_limited Yes
219
+ # @authentication_required Requires user context
220
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
221
+ # @return [Twitter::Relationship]
222
+ # @param source [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the source user.
223
+ # @param target [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the target user.
224
+ # @param options [Hash] A customizable set of options.
225
+ # @example Return the relationship between @sferik and @pengwynn
226
+ # Twitter.friendship('sferik', 'pengwynn')
227
+ # Twitter.friendship('sferik', 14100886) # Same as above
228
+ # Twitter.friendship(7505382, 14100886) # Same as above
229
+ def friendship(source, target, options={})
230
+ options.merge_user!(source, "source")
231
+ options[:source_id] = options.delete(:source_user_id) unless options[:source_user_id].nil?
232
+ options.merge_user!(target, "target")
233
+ options[:target_id] = options.delete(:target_user_id) unless options[:target_user_id].nil?
234
+ object_from_response(Twitter::Relationship, :get, "/1.1/friendships/show.json", options)
235
+ end
236
+ alias friendship_show friendship
237
+ alias relationship friendship
238
+
239
+ # Test for the existence of friendship between two users
240
+ #
241
+ # @see https://dev.twitter.com/docs/api/1.1/get/friendships/show
242
+ # @rate_limited Yes
243
+ # @authentication_required Requires user context
244
+ # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
245
+ # @return [Boolean] true if user_a follows user_b, otherwise false.
246
+ # @param source [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the source user.
247
+ # @param target [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the target user.
248
+ # @param options [Hash] A customizable set of options.
249
+ # @example Return true if @sferik follows @pengwynn
250
+ # Twitter.friendship?('sferik', 'pengwynn')
251
+ # Twitter.friendship?('sferik', 14100886) # Same as above
252
+ # Twitter.friendship?(7505382, 14100886) # Same as above
253
+ def friendship?(source, target, options={})
254
+ friendship(source, target, options).source.following?
255
+ end
256
+
257
+ end
258
+ end
259
+ end