instagram-community-maintained 1.1.6

Sign up to get free protection for your applications and to get access to all the features.
Files changed (91) hide show
  1. checksums.yaml +7 -0
  2. data/.gitignore +14 -0
  3. data/.rspec +3 -0
  4. data/.travis.yml +7 -0
  5. data/.yardopts +9 -0
  6. data/Gemfile +3 -0
  7. data/LICENSE.md +30 -0
  8. data/PATENTS.md +23 -0
  9. data/README.md +261 -0
  10. data/Rakefile +27 -0
  11. data/instagram.gemspec +53 -0
  12. data/lib/faraday/loud_logger.rb +75 -0
  13. data/lib/faraday/oauth2.rb +42 -0
  14. data/lib/faraday/raise_http_exception.rb +59 -0
  15. data/lib/instagram.rb +27 -0
  16. data/lib/instagram/api.rb +31 -0
  17. data/lib/instagram/client.rb +21 -0
  18. data/lib/instagram/client/comments.rb +62 -0
  19. data/lib/instagram/client/embedding.rb +28 -0
  20. data/lib/instagram/client/geographies.rb +29 -0
  21. data/lib/instagram/client/likes.rb +58 -0
  22. data/lib/instagram/client/locations.rb +75 -0
  23. data/lib/instagram/client/media.rb +82 -0
  24. data/lib/instagram/client/subscriptions.rb +211 -0
  25. data/lib/instagram/client/tags.rb +59 -0
  26. data/lib/instagram/client/users.rb +310 -0
  27. data/lib/instagram/client/utils.rb +28 -0
  28. data/lib/instagram/configuration.rb +122 -0
  29. data/lib/instagram/connection.rb +31 -0
  30. data/lib/instagram/error.rb +31 -0
  31. data/lib/instagram/oauth.rb +36 -0
  32. data/lib/instagram/request.rb +82 -0
  33. data/lib/instagram/response.rb +21 -0
  34. data/lib/instagram/version.rb +3 -0
  35. data/spec/faraday/response_spec.rb +86 -0
  36. data/spec/fixtures/access_token.json +9 -0
  37. data/spec/fixtures/approve_user.json +8 -0
  38. data/spec/fixtures/block_user.json +8 -0
  39. data/spec/fixtures/deny_user.json +8 -0
  40. data/spec/fixtures/follow_user.json +8 -0
  41. data/spec/fixtures/followed_by.json +1 -0
  42. data/spec/fixtures/follows.json +1 -0
  43. data/spec/fixtures/geography_recent_media.json +1 -0
  44. data/spec/fixtures/liked_media.json +1 -0
  45. data/spec/fixtures/location.json +1 -0
  46. data/spec/fixtures/location_recent_media.json +1 -0
  47. data/spec/fixtures/location_search.json +1 -0
  48. data/spec/fixtures/location_search_fsq.json +1 -0
  49. data/spec/fixtures/media.json +1 -0
  50. data/spec/fixtures/media_comment.json +1 -0
  51. data/spec/fixtures/media_comment_deleted.json +1 -0
  52. data/spec/fixtures/media_comments.json +1 -0
  53. data/spec/fixtures/media_liked.json +1 -0
  54. data/spec/fixtures/media_likes.json +1 -0
  55. data/spec/fixtures/media_popular.json +1 -0
  56. data/spec/fixtures/media_search.json +1 -0
  57. data/spec/fixtures/media_shortcode.json +1 -0
  58. data/spec/fixtures/media_unliked.json +1 -0
  59. data/spec/fixtures/mikeyk.json +1 -0
  60. data/spec/fixtures/oembed.json +14 -0
  61. data/spec/fixtures/recent_media.json +1 -0
  62. data/spec/fixtures/relationship.json +9 -0
  63. data/spec/fixtures/requested_by.json +12 -0
  64. data/spec/fixtures/shayne.json +1 -0
  65. data/spec/fixtures/subscription.json +12 -0
  66. data/spec/fixtures/subscription_deleted.json +1 -0
  67. data/spec/fixtures/subscription_payload.json +14 -0
  68. data/spec/fixtures/subscriptions.json +22 -0
  69. data/spec/fixtures/tag.json +1 -0
  70. data/spec/fixtures/tag_recent_media.json +1 -0
  71. data/spec/fixtures/tag_search.json +1 -0
  72. data/spec/fixtures/unblock_user.json +8 -0
  73. data/spec/fixtures/unfollow_user.json +8 -0
  74. data/spec/fixtures/user_media_feed.json +1 -0
  75. data/spec/fixtures/user_search.json +1 -0
  76. data/spec/instagram/api_spec.rb +285 -0
  77. data/spec/instagram/client/comments_spec.rb +71 -0
  78. data/spec/instagram/client/embedding_spec.rb +36 -0
  79. data/spec/instagram/client/geography_spec.rb +37 -0
  80. data/spec/instagram/client/likes_spec.rb +66 -0
  81. data/spec/instagram/client/locations_spec.rb +127 -0
  82. data/spec/instagram/client/media_spec.rb +99 -0
  83. data/spec/instagram/client/subscriptions_spec.rb +174 -0
  84. data/spec/instagram/client/tags_spec.rb +79 -0
  85. data/spec/instagram/client/users_spec.rb +424 -0
  86. data/spec/instagram/client/utils_spec.rb +32 -0
  87. data/spec/instagram/client_spec.rb +23 -0
  88. data/spec/instagram/request_spec.rb +56 -0
  89. data/spec/instagram_spec.rb +109 -0
  90. data/spec/spec_helper.rb +71 -0
  91. metadata +328 -0
@@ -0,0 +1,82 @@
1
+ module Instagram
2
+ class Client
3
+ # Defines methods related to media items
4
+ module Media
5
+ # Returns extended information of a given media item
6
+ #
7
+ # @overload media_item(id)
8
+ # @param user [Integer] An Instagram media item ID
9
+ # @return [Hashie::Mash] The requested media item.
10
+ # @example Return extended information for media item 1234
11
+ # Instagram.media_item(1324)
12
+ # @format :json
13
+ # @authenticated false unless requesting media from a protected user
14
+ #
15
+ # If getting this data of a protected user, you must authenticate (and be allowed to see that user).
16
+ # @rate_limited true
17
+ # @see http://instagram.com/developer/endpoints/media/#get_media
18
+ def media_item(*args)
19
+ id = args.first || 'self'
20
+ response = get("media/#{id}")
21
+ response
22
+ end
23
+
24
+ # Returns extended information of a given media item
25
+ #
26
+ # @overload media_shortcode(shortcode)
27
+ # @param shortcode [String] An Instagram media item shortcode
28
+ # @return [Hashie::Mash] The requested media item.
29
+ # @example Return extended information for media item with shortcode 'D'
30
+ # Instagram.media_shortcode('D')
31
+ # @format none
32
+ # @authenticated false unless requesting media from a protected user
33
+ #
34
+ # If getting this data of a protected user, you must authenticate (and be allowed to see that user).
35
+ # @rate_limited true
36
+ # @see http://instagram.com/developer/endpoints/media/#get_media_by_shortcode
37
+ def media_shortcode(*args)
38
+ shortcode = args.first
39
+ response = get("media/shortcode/#{shortcode}", {}, false, false, true)
40
+ response
41
+ end
42
+
43
+ # Returns a list of the overall most popular media
44
+ #
45
+ # @overload media_popular(options={})
46
+ # @param options [Hash] A customizable set of options.
47
+ # @return [Hashie::Mash]
48
+ # @example Returns a list of the overall most popular media
49
+ # Instagram.media_popular
50
+ # @see http://instagram.com/developer/endpoints/media/#get_media_popular
51
+ # @format :json
52
+ # @authenticated false unless requesting it from a protected user
53
+ #
54
+ # If getting this data of a protected user, you must authenticate (and be allowed to see that user).
55
+ # @rate_limited true
56
+ def media_popular(*args)
57
+ options = args.last.is_a?(Hash) ? args.pop : {}
58
+ id = args.first || "self"
59
+ response = get("media/popular", options)
60
+ response
61
+ end
62
+
63
+ # Returns media items within proximity of given lat,lng
64
+ #
65
+ # @param lat [String] A given latitude in decimal format
66
+ # @param lng [String] A given longitude in decimal format
67
+ # @param options [Hash] A customizable set of options.
68
+ # @option options [Integer] :count The number of media items to retrieve.
69
+ # @return [Hashie::Mash] A list of matching media
70
+ # @example Return media around 37.7808851, -122.3948632 (164 S Park, SF, CA USA)
71
+ # Instagram.media_search("37.7808851", "-122.3948632")
72
+ # @see http://instagram.com/developer/endpoints/media/#get_media_search
73
+ # @format :json
74
+ # @authenticated false
75
+ # @rate_limited true
76
+ def media_search(lat, lng, options={})
77
+ response = get('media/search', options.merge(:lat => lat, :lng => lng))
78
+ response
79
+ end
80
+ end
81
+ end
82
+ end
@@ -0,0 +1,211 @@
1
+ require 'openssl'
2
+ require 'multi_json'
3
+
4
+ module Instagram
5
+ class Client
6
+ # Defines methods related to real-time
7
+ module Subscriptions
8
+ # Returns a list of active real-time subscriptions
9
+ #
10
+ # @overload subscriptions(options={})
11
+ # @return [Hashie::Mash] The list of subscriptions.
12
+ # @example Returns a list of subscriptions for the authenticated application
13
+ # Instagram.subscriptions
14
+ # @format :json
15
+ # @authenticated true
16
+ #
17
+ # Requires client_secret to be set on the client or passed in options
18
+ # @rate_limited true
19
+ # @see https://api.instagram.com/developer/realtime/
20
+ def subscriptions(options={})
21
+ response = get("subscriptions", options.merge(:client_secret => client_secret))
22
+ response
23
+ end
24
+
25
+ # Creates a real-time subscription
26
+ #
27
+ # @overload create_subscription(options={})
28
+ # @param options [Hash] A set of parameters
29
+ # @option options [String] :object The object you'd like to subscribe to (user, tag, location or geography)
30
+ # @option options [String] :callback_url The subscription callback URL
31
+ # @option options [String] :aspect The aspect of the object you'd like to subscribe to (in this case, "media").
32
+ # @option options [String, Integer] :object_id When specifying a location or tag use the location's ID or tag name respectively
33
+ # @option options [String, Float] :lat The center latitude of an area, used when subscribing to a geography object
34
+ # @option options [String, Float] :lng The center longitude of an area, used when subscribing to a geography object
35
+ # @option options [String, Integer] :radius The distance in meters you'd like to capture around a given point
36
+ # @overload create_subscription(object, callback_url, aspect="media", options={})
37
+ # @param object [String] The object you'd like to subscribe to (user, tag, location or geography)
38
+ # @param callback_url [String] The subscription callback URL
39
+ # @param aspect [String] he aspect of the object you'd like to subscribe to (in this case, "media").
40
+ # @param options [Hash] Addition options and parameters
41
+ # @option options [String, Integer] :object_id When specifying a location or tag use the location's ID or tag name respectively
42
+ # @option options [String, Float] :lat The center latitude of an area, used when subscribing to a geography object
43
+ # @option options [String, Float] :lng The center longitude of an area, used when subscribing to a geography object
44
+ # @option options [String, Integer] :radius The distance in meters you'd like to capture around a given point
45
+ #
46
+ # Note that we only support "media" at this time, but we might support other types of subscriptions in the future.
47
+ # @return [Hashie::Mash] The subscription created.
48
+ # @example Creates a new subscription to receive notifications for user media changes.
49
+ # Instagram.create_subscription("user", "http://example.com/instagram/callback")
50
+ # @format :json
51
+ # @authenticated true
52
+ #
53
+ # Requires client_secret to be set on the client or passed in options
54
+ # @rate_limited true
55
+ # @see https://api.instagram.com/developer/realtime/
56
+ def create_subscription(*args)
57
+ options = args.last.is_a?(Hash) ? args.pop : {}
58
+ object = args.shift
59
+ callback_url = args.shift
60
+ aspect = args.shift
61
+ options.tap {|o|
62
+ o[:object] = object unless object.nil?
63
+ o[:callback_url] = callback_url unless callback_url.nil?
64
+ o[:aspect] = aspect || o[:aspect] || "media"
65
+ }
66
+ response = post("subscriptions", options.merge(:client_secret => client_secret), signature=true)
67
+ response
68
+ end
69
+
70
+ # Deletes a real-time subscription
71
+ #
72
+ # @overload delete_subscription(options={})
73
+ # @param options [Hash] Addition options and parameters
74
+ # @option options [Integer] :subscription_id The subscription's ID
75
+ # @option options [String] :object When specified will remove all subscriptions of this object type, unless an :object_id is also specified (user, tag, location or geography)
76
+ # @option options [String, Integer] :object_id When specifying :object, inlcude an :object_id to only remove subscriptions of that object and object_id
77
+ # @overload delete_subscription(subscription_id, options={})
78
+ # @param subscription_id [Integer] The subscription's ID
79
+ # @param options [Hash] Addition options and parameters
80
+ # @option options [String] :object When specified will remove all subscriptions of this object type, unless an :object_id is also specified (user, tag, location or geography)
81
+ # @option options [String, Integer] :object_id When specifying :object, inlcude an :object_id to only remove subscriptions of that object and object_id
82
+ # @return [Hashie::Mash]
83
+ # @example Deletes an application's user change subscription
84
+ # Instagram.delete_subscription(:object => "user")
85
+ # @format :json
86
+ # @authenticated true
87
+ #
88
+ # Requires client_secret to be set on the client or passed in options
89
+ # @rate_limited true
90
+ # @see https://api.instagram.com/developer/realtime/
91
+ def delete_subscription(*args)
92
+ options = args.last.is_a?(Hash) ? args.pop : {}
93
+ subscription_id = args.first
94
+ options.merge!(:id => subscription_id) if subscription_id
95
+ response = delete("subscriptions", options.merge(:client_secret => client_secret), signature=true)
96
+ response
97
+ end
98
+
99
+ # As a security measure (to prevent DDoS attacks), Instagram sends a verification request to your server
100
+ # after you request a subscription.
101
+ # This method parses the challenge params and makes sure the call is legitimate.
102
+ #
103
+ # @param params the request parameters sent by Instagram. (You can pass in a Rails params hash.)
104
+ # @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
105
+ #
106
+ # @yield verify_token if you need to compute the verification token
107
+ # (for instance, if your callback URL includes a record ID, which you look up
108
+ # and use to calculate a hash), you can pass meet_challenge a block, which
109
+ # will receive the verify_token received back from Instagram.
110
+ #
111
+ # @return the challenge string to be sent back to Instagram, or false if the request is invalid.
112
+ def meet_challenge(params, verify_token = nil, &verification_block)
113
+ if params["hub.mode"] == "subscribe" &&
114
+ # you can make sure this is legitimate through two ways
115
+ # if your store the token across the calls, you can pass in the token value
116
+ # and we'll make sure it matches
117
+ ((verify_token && params["hub.verify_token"] == verify_token) ||
118
+ # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
119
+ # you can pass in a block, which we'll call with the verify_token sent by Instagram
120
+ # if it's legit, return anything that evaluates to true; otherwise, return nil or false
121
+ (verification_block && yield(params["hub.verify_token"])))
122
+ params["hub.challenge"]
123
+ else
124
+ false
125
+ end
126
+ end
127
+
128
+ # Public: As a security measure, all updates from Instagram are signed using
129
+ # X-Hub-Signature: XXXX where XXX is the sha1 of the json payload
130
+ # using your application secret as the key.
131
+ #
132
+ # Example:
133
+ # # in Rails controller
134
+ # def receive_update
135
+ # if Instagram.validate_update(request.body, headers)
136
+ # ...
137
+ # else
138
+ # render text: "not authorized", status: 401
139
+ # end
140
+ # end
141
+ def validate_update(body, headers)
142
+ unless client_secret
143
+ raise ArgumentError, "client_secret must be set during configure"
144
+ end
145
+
146
+ if request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE']
147
+ calculated_signature = OpenSSL::HMAC.hexdigest('sha1', client_secret, body)
148
+ calculated_signature == request_signature
149
+ end
150
+ end
151
+
152
+ # Process a subscription notification JSON payload
153
+ #
154
+ # @overload process_subscription(json, &block)
155
+ # @param json [String] The JSON response received by the Instagram real-time server
156
+ # @param block [Proc] A callable in which callbacks are defined
157
+ # @option options [String] :signature Pass in an X-Hub-Signature to use for payload validation
158
+ # @return [nil]
159
+ # @example Process and handle a notification for a user media change
160
+ # Instagram.process_subscription(params[:body]) do |handler|
161
+ #
162
+ # handler.on_user_changed do |user_id, data|
163
+ #
164
+ # user = User.by_instagram_id(user_id)
165
+ # @client = Instagram.client(:access_token => _access_token_for_user(user))
166
+ # latest_media = @client.user_recent_media[0]
167
+ # user.media.create_with_hash(latest_media)
168
+ # end
169
+ #
170
+ # end
171
+ # @format :json
172
+ # @authenticated true
173
+ #
174
+ # Requires client_secret to be set on the client or passed in options
175
+ # @rate_limited true
176
+ # @see https://api.instagram.com/developer/realtime/
177
+ def process_subscription(json, options={}, &block)
178
+ raise ArgumentError, "callbacks block expected" unless block_given?
179
+
180
+ if options.has_key?(:signature)
181
+ if !client_secret
182
+ raise ArgumentError, "client_secret must be set during configure"
183
+ end
184
+ digest = OpenSSL::Digest.new('sha1')
185
+ verify_signature = OpenSSL::HMAC.hexdigest(digest, client_secret, json)
186
+
187
+ if options[:signature] != verify_signature
188
+ raise Instagram::InvalidSignature, "invalid X-Hub-Signature does not match verify signature against client_secret"
189
+ end
190
+ end
191
+
192
+ payload = MultiJson.decode(json)
193
+ @changes = Hash.new { |h,k| h[k] = [] }
194
+ for change in payload
195
+ @changes[change['object']] << change
196
+ end
197
+ block.call(self)
198
+ end
199
+
200
+ [:user, :tag, :location, :geography].each do |object|
201
+ class_eval <<-RUBY_EVAL, __FILE__, __LINE__ +1
202
+ def on_#{object}_changed(&block)
203
+ for change in @changes['#{object}']
204
+ yield change.delete('object_id'), change
205
+ end
206
+ end
207
+ RUBY_EVAL
208
+ end
209
+ end
210
+ end
211
+ end
@@ -0,0 +1,59 @@
1
+ module Instagram
2
+ class Client
3
+ # Defines methods related to tags
4
+ module Tags
5
+ # Returns extended information of a given Instagram tag
6
+ #
7
+ # @overload tag(tag)
8
+ # @param tag [String] An Instagram tag name
9
+ # @return [Hashie::Mash] The requested tag.
10
+ # @example Return extended information for the tag "cat"
11
+ # Instagram.tag('cat')
12
+ # @format :json
13
+ # @authenticated false
14
+ # @rate_limited true
15
+ # @see http://instagram.com/developer/endpoints/tags/#get_tags
16
+ def tag(tag, *args)
17
+ response = get("tags/#{tag}")
18
+ response
19
+ end
20
+
21
+ # Returns a list of recent media items for a given Instagram tag
22
+ #
23
+ # @overload tag_recent_media(tag, options={})
24
+ # @param tag-name [String] An Instagram tag name.
25
+ # @param options [Hash] A customizable set of options.
26
+ # @option options [Integer] :max_tag_id (nil) Returns results with an ID less than (that is, older than) or equal to the specified ID. The value can be retrieved from the returned response via pagination.max_tag_id.
27
+ # @option options [Integer] :min_tag_id (nil) Returns results with an ID greater than (that is, newer than) or equal to the specified ID. The value can be retrieved from the returned response via pagination.min_tag_id.
28
+ # @return [Hashie::Mash]
29
+ # @example Return a list of the most recent media items tagged "cat"
30
+ # Instagram.tag_recent_media('cat')
31
+ # @see https://instagram.com/developer/endpoints/tags/#get_tags_media_recent
32
+ # @format :json
33
+ # @authenticated false
34
+ # @rate_limited true
35
+ def tag_recent_media(id, *args)
36
+ options = args.last.is_a?(Hash) ? args.pop : {}
37
+ response = get("tags/#{id}/media/recent", options, false, false, false)
38
+ response
39
+ end
40
+
41
+ # Returns a list of tags starting with the given search query
42
+ #
43
+ # @format :json
44
+ # @authenticated false
45
+ # @rate_limited true
46
+ # @param query [String] The beginning or complete tag name to search for
47
+ # @param options [Hash] A customizable set of options.
48
+ # @option options [Integer] :count The number of media items to retrieve.
49
+ # @return [Hashie::Mash]
50
+ # @see http://instagram.com/developer/endpoints/tags/#get_tags_search
51
+ # @example Return tags that start with "cat"
52
+ # Instagram.tag_search("cat")
53
+ def tag_search(query, options={})
54
+ response = get('tags/search', options.merge(:q => query))
55
+ response
56
+ end
57
+ end
58
+ end
59
+ end
@@ -0,0 +1,310 @@
1
+ module Instagram
2
+ class Client
3
+ # Defines methods related to users
4
+ module Users
5
+ # Returns extended information of a given user
6
+ #
7
+ # @overload user(id=nil, options={})
8
+ # @param user [Integer] An Instagram user ID
9
+ # @return [Hashie::Mash] The requested user.
10
+ # @example Return extended information for @shayne
11
+ # Instagram.user(20)
12
+ # @format :json
13
+ # @authenticated false unless requesting it from a protected user
14
+ #
15
+ # If getting this data of a protected user, you must authenticate (and be allowed to see that user).
16
+ # @rate_limited true
17
+ # @see http://instagram.com/developer/endpoints/users/#get_users
18
+ def user(*args)
19
+ options = args.last.is_a?(Hash) ? args.pop : {}
20
+ id = args.first || 'self'
21
+ response = get("users/#{id}", options)
22
+ response
23
+ end
24
+
25
+ # Returns users that match the given query
26
+ #
27
+ # @format :json
28
+ # @authenticated false
29
+ # @rate_limited true
30
+ # @param query [String] The search query to run against user search.
31
+ # @param options [Hash] A customizable set of options.
32
+ # @option options [Integer] :count The number of users to retrieve.
33
+ # @return [Hashie::Mash]
34
+ # @see http://instagram.com/developer/endpoints/users/#get_users_search
35
+ # @example Return users that match "Shayne Sweeney"
36
+ # Instagram.user_search("Shayne Sweeney")
37
+ def user_search(query, options={})
38
+ response = get('users/search', options.merge(:q => query))
39
+ response
40
+ end
41
+
42
+ # Returns a list of users whom a given user follows
43
+ #
44
+ # @overload user_follows(id=nil, options={})
45
+ # @param options [Hash] A customizable set of options.
46
+ # @return [Hashie::Mash]
47
+ # @example Returns a list of users the authenticated user follows
48
+ # Instagram.user_follows
49
+ # @overload user_follows(id=nil, options={})
50
+ # @param user [Integer] An Instagram user ID.
51
+ # @param options [Hash] A customizable set of options.
52
+ # @option options [Integer] :cursor (nil) Breaks the results into pages. Provide values as returned in the response objects's next_cursor attribute to page forward in the list.
53
+ # @option options [Integer] :count (nil) Limits the number of results returned per page.
54
+ # @return [Hashie::Mash]
55
+ # @example Return a list of users @mikeyk follows
56
+ # Instagram.user_follows(4) # @mikeyk user ID being 4
57
+ # @see http://instagram.com/developer/endpoints/relationships/#get_users_follows
58
+ # @format :json
59
+ # @authenticated false unless requesting it from a protected user
60
+ #
61
+ # If getting this data of a protected user, you must authenticate (and be allowed to see that user).
62
+ # @rate_limited true
63
+ def user_follows(*args)
64
+ options = args.last.is_a?(Hash) ? args.pop : {}
65
+ id = args.first || "self"
66
+ response = get("users/#{id}/follows", options)
67
+ response
68
+ end
69
+ end
70
+
71
+ # Returns a list of users whom a given user is followed by
72
+ #
73
+ # @overload user_followed_by(id=nil, options={})
74
+ # @param options [Hash] A customizable set of options.
75
+ # @return [Hashie::Mash]
76
+ # @example Returns a list of users the authenticated user is followed by
77
+ # Instagram.user_followed_by
78
+ # @overload user_followed_by(id=nil, options={})
79
+ # @param user [Integer] An Instagram user ID.
80
+ # @param options [Hash] A customizable set of options.
81
+ # @option options [Integer] :cursor (nil) Breaks the results into pages. Provide values as returned in the response objects's next_cursor attribute to page forward in the list.
82
+ # @option options [Integer] :count (nil) Limits the number of results returned per page.
83
+ # @return [Hashie::Mash]
84
+ # @example Return a list of users @mikeyk is followed by
85
+ # Instagram.user_followed_by(4) # @mikeyk user ID being 4
86
+ # @see http://instagram.com/developer/endpoints/relationships/#get_users_followed_by
87
+ # @format :json
88
+ # @authenticated false unless requesting it from a protected user
89
+ #
90
+ # If getting this data of a protected user, you must authenticate (and be allowed to see that user).
91
+ # @rate_limited true
92
+ def user_followed_by(*args)
93
+ options = args.last.is_a?(Hash) ? args.pop : {}
94
+ id = args.first || "self"
95
+ response = get("users/#{id}/followed-by", options)
96
+ response
97
+ end
98
+
99
+ # Returns a list of users who have requested the currently authorized user's permission to follow
100
+ #
101
+ # @overload user_requested_by()
102
+ # @param options [Hash] A customizable set of options.
103
+ # @return [Hashie::Mash]
104
+ # @example Returns a list of users awaiting approval of a ollow request, for the authenticated user
105
+ # Instagram.user_requested_by
106
+ # @overload user_requested_by()
107
+ # @return [Hashie::Mash]
108
+ # @example Return a list of users who have requested to follow the authenticated user
109
+ # Instagram.user_requested_by()
110
+ # @see http://instagram.com/developer/endpoints/relationships/#get_incoming_requests
111
+ # @format :json
112
+ # @authenticated true
113
+ # @rate_limited true
114
+ def user_requested_by()
115
+ response = get("users/self/requested-by")
116
+ response
117
+ end
118
+
119
+ # Returns most recent media items from the currently authorized user's feed
120
+ #
121
+ # @overload user_media_feed(options={})
122
+ # @param options [Hash] A customizable set of options.
123
+ # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
124
+ # @option options [Integer] :min_id Return media later than this min_id
125
+ # @option options [Integer] :count Specifies the number of records to retrieve, per page.
126
+ # @return [Hashie::Mash]
127
+ # @example Return most recent media images that would appear on @shayne's feed
128
+ # Instagram.user_media_feed() # assuming @shayne is the authorized user
129
+ # @format :json
130
+ # @authenticated true
131
+ # @rate_limited true
132
+ # @see http://instagram.com/developer/endpoints/users/#get_users_feed
133
+ def user_media_feed(*args)
134
+ options = args.first.is_a?(Hash) ? args.pop : {}
135
+ response = get('users/self/feed', options)
136
+ response
137
+ end
138
+
139
+ # Returns a list of recent media items for a given user
140
+ #
141
+ # @overload user_recent_media(options={})
142
+ # @param options [Hash] A customizable set of options.
143
+ # @return [Hashie::Mash]
144
+ # @example Returns a list of recent media items for the currently authenticated user
145
+ # Instagram.user_recent_media
146
+ # @overload user_recent_media(id=nil, options={})
147
+ # @param user [Integer] An Instagram user ID.
148
+ # @param options [Hash] A customizable set of options.
149
+ # @option options [Integer] :max_id (nil) Returns results with an ID less than (that is, older than) or equal to the specified ID.
150
+ # @option options [Integer] :count (nil) Limits the number of results returned per page.
151
+ # @return [Hashie::Mash]
152
+ # @example Return a list of media items taken by @mikeyk
153
+ # Instagram.user_recent_media(4) # @mikeyk user ID being 4
154
+ # @see http://instagram.com/developer/endpoints/users/#get_users_media_recent
155
+ # @format :json
156
+ # @authenticated false unless requesting it from a protected user
157
+ #
158
+ # If getting this data of a protected user, you must authenticate (and be allowed to see that user).
159
+ # @rate_limited true
160
+ def user_recent_media(*args)
161
+ options = args.last.is_a?(Hash) ? args.pop : {}
162
+ id = args.first || "self"
163
+ response = get("users/#{id}/media/recent", options)
164
+ response
165
+ end
166
+
167
+ # Returns a list of media items liked by the current user
168
+ #
169
+ # @overload user_liked_media(options={})
170
+ # @param options [Hash] A customizable set of options.
171
+ # @option options [Integer] :max_like_id (nil) Returns results with an ID less than (that is, older than) or equal to the specified ID.
172
+ # @option options [Integer] :count (nil) Limits the number of results returned per page.
173
+ # @return [Hashie::Mash]
174
+ # @example Returns a list of media items liked by the currently authenticated user
175
+ # Instagram.user_liked_media
176
+ # @see http://instagram.com/developer/endpoints/users/#get_users_liked_feed
177
+ # @format :json
178
+ # @authenticated true
179
+ # @rate_limited true
180
+ def user_liked_media(options={})
181
+ response = get("users/self/media/liked", options)
182
+ response
183
+ end
184
+
185
+ # Returns information about the current user's relationship (follow/following/etc) to another user
186
+ #
187
+ # @overload user_relationship(id, options={})
188
+ # @param user [Integer] An Instagram user ID.
189
+ # @param options [Hash] An optional options hash
190
+ # @return [Hashie::Mash]
191
+ # @example Return the relationship status between the currently authenticated user and @mikeyk
192
+ # Instagram.user_relationship(4) # @mikeyk user ID being 4
193
+ # @see http://instagram.com/developer/endpoints/relationships/#get_relationship
194
+ # @format :json
195
+ # @authenticated true
196
+ # @rate_limited true
197
+ def user_relationship(id, options={})
198
+ response = get("users/#{id}/relationship", options)
199
+ response
200
+ end
201
+
202
+ # Create a follows relationship between the current user and the target user
203
+ #
204
+ # @overload follow_user(id, options={})
205
+ # @param user [Integer] An Instagram user ID.
206
+ # @param options [Hash] An optional options hash
207
+ # @return [Hashie::Mash]
208
+ # @example Request the current user to follow the target user
209
+ # Instagram.follow_user(4)
210
+ # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
211
+ # @format :json
212
+ # @authenticated true
213
+ # @rate_limited true
214
+ def follow_user(id, options={})
215
+ options["action"] = "follow"
216
+ response = post("users/#{id}/relationship", options, signature=true)
217
+ response
218
+ end
219
+
220
+ # Destroy a follows relationship between the current user and the target user
221
+ #
222
+ # @overload unfollow_user(id, options={})
223
+ # @param user [Integer] An Instagram user ID.
224
+ # @param options [Hash] An optional options hash
225
+ # @return [Hashie::Mash]
226
+ # @example Remove a follows relationship between the current user and the target user
227
+ # Instagram.unfollow_user(4)
228
+ # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
229
+ # @format :json
230
+ # @authenticated true
231
+ # @rate_limited true
232
+ def unfollow_user(id, options={})
233
+ options["action"] = "unfollow"
234
+ response = post("users/#{id}/relationship", options, signature=true)
235
+ response
236
+ end
237
+
238
+ # Block a relationship between the current user and the target user
239
+ #
240
+ # @overload unfollow_user(id, options={})
241
+ # @param user [Integer] An Instagram user ID.
242
+ # @param options [Hash] An optional options hash
243
+ # @return [Hashie::Mash]
244
+ # @example Block a relationship between the current user and the target user
245
+ # Instagram.block_user(4)
246
+ # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
247
+ # @format :json
248
+ # @authenticated true
249
+ # @rate_limited true
250
+ def block_user(id, options={})
251
+ options["action"] = "block"
252
+ response = post("users/#{id}/relationship", options, signature=true)
253
+ response
254
+ end
255
+
256
+ # Remove a relationship block between the current user and the target user
257
+ #
258
+ # @overload unblock_user(id, options={})
259
+ # @param user [Integer] An Instagram user ID.
260
+ # @param options [Hash] An optional options hash
261
+ # @return [Hashie::Mash]
262
+ # @example Remove a relationship block between the current user and the target user
263
+ # Instagram.unblock_user(4)
264
+ # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
265
+ # @format :json
266
+ # @authenticated true
267
+ # @rate_limited true
268
+ def unblock_user(id, options={})
269
+ options["action"] = "unblock"
270
+ response = post("users/#{id}/relationship", options, signature=true)
271
+ response
272
+ end
273
+
274
+ # Approve a relationship request between the current user and the target user
275
+ #
276
+ # @overload approve_user(id, options={})
277
+ # @param user [Integer] An Instagram user ID.
278
+ # @param options [Hash] An optional options hash
279
+ # @return [Hashie::Mash]
280
+ # @example Approve a relationship request between the current user and the target user
281
+ # Instagram.approve_user(4)
282
+ # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
283
+ # @format :json
284
+ # @authenticated true
285
+ # @rate_limited true
286
+ def approve_user(id, options={})
287
+ options["action"] = "approve"
288
+ response = post("users/#{id}/relationship", options, signature=true)
289
+ response
290
+ end
291
+
292
+ # Deny a relationship request between the current user and the target user
293
+ #
294
+ # @overload deny_user(id, options={})
295
+ # @param user [Integer] An Instagram user ID.
296
+ # @param options [Hash] An optional options hash
297
+ # @return [Hashie::Mash]
298
+ # @example Deny a relationship request between the current user and the target user
299
+ # Instagram.deny_user(4)
300
+ # @see http://instagram.com/developer/endpoints/relationships/#post_relationship
301
+ # @format :json
302
+ # @authenticated true
303
+ # @rate_limited true
304
+ def deny_user(id, options={})
305
+ options["action"] = "deny"
306
+ response = post("users/#{id}/relationship", options, signature=true)
307
+ response
308
+ end
309
+ end
310
+ end