instagram_basic_display 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f91c7c3b242f6488c78b3cfafb99ec3ae263c3ce158c8bdfd0a29c6a4a515241
-  data.tar.gz: 0107b170ee8997987a12a0c8136d5346150c70e555b36f20bc381ea30ad3f7f6
+  metadata.gz: 917e8dc235fd078d724ccbd775d6306e5b61411443f3fe64a083e2dc988f89db
+  data.tar.gz: 9d842051035ee2852e273d195109570dd953e053116caa99a242d337705fcbf8
 SHA512:
-  metadata.gz: e4c9a9b95abc448be189ddd0c024bb24412aff97feb75a551219810e1cbe39aa5bc1ef991b34402b8a919bc21953675ac8e18e78c2238e7214aabb3921eca4f5
-  data.tar.gz: d4b1ae2e93ff561878f7d71acba22ce318709013f1fe43de29b2409853c486c44a0f06c0c9de512fb705e94c28de61cf732af88fedad6d8423e519c276f97f67
+  metadata.gz: 83c536d281626fe977a917869f805aee783f982b9c458c752da2b23f6b80d6af32d4e6c4add9d5ebc592e18f74861616fcb403a7a0ca990ba6c6b477ea636fc9
+  data.tar.gz: 9099d5adad7117b3368fa7724f7dba4ec8379fb214b6de4585a4a72ec49e1975fae71c2ac5cebdb47635047da08da8cbb7a868c203cd37a340f492ff12f46ebd

data/.ruby-version

@@ -1 +1 @@
-2.5.3
+3.2.2

data/Gemfile

@@ -1,15 +1,15 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 gemspec
 
 group :development, :test do
-  gem 'rubocop', '~> 0.74.0'
-  gem 'pry'
   gem 'dotenv'
+  gem 'pry'
+  gem 'rubocop', '~> 1.68'
 end
 
 group :test do
-  gem 'rspec', '~> 3.8.0'
-  gem 'webmock'
+  gem 'rspec', '~> 3.13.0'
   gem 'vcr'
+  gem 'webmock'
 end

data/Gemfile.lock

@@ -1,73 +1,87 @@
 PATH
   remote: .
   specs:
-    instagram_basic_display (0.2.0)
+    instagram_basic_display (0.2.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
-      public_suffix (>= 2.0.2, < 5.0)
-    ast (2.4.0)
-    coderay (1.1.2)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    diff-lcs (1.3)
-    dotenv (2.7.5)
-    hashdiff (1.0.0)
-    jaro_winkler (1.5.4)
-    method_source (0.9.2)
-    parallel (1.19.1)
-    parser (2.7.0.2)
-      ast (~> 2.4.0)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    public_suffix (4.0.3)
-    rainbow (3.0.0)
-    rake (10.5.0)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.2)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.6)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.2)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
+    coderay (1.1.3)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    diff-lcs (1.5.1)
+    dotenv (3.1.4)
+    hashdiff (1.1.1)
+    json (2.8.1)
+    language_server-protocol (3.17.0.3)
+    method_source (1.1.0)
+    parallel (1.26.3)
+    parser (3.3.6.0)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    public_suffix (6.0.1)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    regexp_parser (2.9.2)
+    rexml (3.3.9)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.2)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.3)
-    rubocop (0.74.0)
-      jaro_winkler (~> 1.5.1)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (1.68.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 2.6)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.4, < 3.0)
+      rubocop-ast (>= 1.32.2, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
-    ruby-progressbar (1.10.1)
-    safe_yaml (1.0.5)
-    unicode-display_width (1.6.1)
-    vcr (5.0.0)
-    webmock (3.8.0)
-      addressable (>= 2.3.6)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.34.0)
+      parser (>= 3.3.1.0)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (2.6.0)
+    vcr (6.3.1)
+      base64
+    webmock (3.24.0)
+      addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
+  arm64-darwin-22
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.16)
+  bundler (~> 2.5.23)
   dotenv
   instagram_basic_display!
   pry
-  rake (~> 10.0)
-  rspec (~> 3.8.0)
-  rubocop (~> 0.74.0)
+  rake (~> 13.2)
+  rspec (~> 3.13.0)
+  rubocop (~> 1.68)
   vcr
   webmock
 
 BUNDLED WITH
-   1.17.3
+   2.5.23

data/README.md

@@ -1,8 +1,8 @@
-# InstagramBasicDisplay
+# Instagram Basic Display
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/instagram_basic_display`. To experiment with that code, run `bin/console` for an interactive prompt.
+This is a client gem for Instagram’s [Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api/). It’s a small wrapper around the API that provides access to users’ media and profile information. Not every endpoint has been implemented, so pull requests are welcome to round things out!
 
-TODO: Delete this and the text above, and describe your gem
+Updates to the documentation are also very welcome!
 
 ## Installation
 
@@ -20,9 +20,204 @@ Or install it yourself as:
 
     $ gem install instagram_basic_display
 
-## Usage
+## Usage and examples
 
-TODO: Write usage instructions here
+### Configuration
+
+Set three environment variables to configure the client:
+
+```
+INSTAGRAM_CLIENT_ID=your_client_id
+INSTAGRAM_CLIENT_SECRET=your_client_secret
+INSTAGRAM_REDIRECT_URI=your_redirect_url
+```
+
+These variables can be obtained from the Facebook developer console.
+
+### Using the client
+
+When initializing the client, you can optionally pass in an auth token from Instagram, which will be used to make further requests. If you do not already have a token, you can use one of the methods provided to retrieve one.
+
+```ruby
+client = InstagramBasicDisplay::Client.new
+
+# OR
+
+client = InstagramBasicDisplay::Client.new(auth_token: token)
+```
+
+### Getting auth tokens
+
+Authenticating with Instagram starts with an access code. This access code is retrieved by implementing Instagram's [authortization window](https://developers.facebook.com/docs/instagram-basic-display-api/overview#authorization-window), and is not covered by this gem.
+
+Once you have an access code, you can exchange it for a short-lived authentication token.
+
+```ruby
+user = User.first
+client = InstagramBasicDisplay::Client.new
+
+short_token_request = client.short_lived_token(access_code: code)
+
+if short_token_request.success?
+  auth_token = token_request.payload.access_token
+  expires_in = token_request.payload.expires_in
+  user.update_instagram_token(token: token, expires_in: expires_in)
+else
+  render json: short_token_request.error, status: 400
+end
+```
+
+You can exchange your short-lived token for a long-lived token.
+
+```ruby
+client = InstagramBasicDisplay::Client.new
+user = User.first
+
+long_token_request = client.long_lived_token(short_lived_token: user.instagram_token)
+
+if long_token_request.success?
+  auth_token = token_request.payload.access_token
+  expires_in = token_request.payload.expires_in
+  user.update_instagram_token(token: token, expires_in: expires_in)
+else
+  render json: long_token_request.error, status: 400
+end
+```
+
+You can also pass an access code to `#long_lived_token`. It will be exchanged for a short-lived token, and then that will immediately be exchanged for a long-lived token.
+
+```ruby
+access_code = params[:access_code]
+client = InstagramBasicDisplay::Client.new
+user = User.first
+
+long_token_request = client.long_lived_token(access_code: access_code)
+
+if long_token_request.success?
+  auth_token = token_request.payload.access_token
+  expires_in = token_request.payload.expires_in
+  user.update_instagram_token(token: token, expires_in: expires_in)
+else
+  render json: long_token_request.error, status: 400
+end
+```
+
+You can refresh a long-lived token so that it remains valid for another period (at this stage, Instagram have set the validity period to 60 days).
+
+```ruby
+user = User.first
+client = InstagramBasicDisplay::Client.new
+
+refresh_request = client.refresh_long_lived_token(token: user.instagram_token)
+
+if refresh_request.success?
+  client.update_instagram_token(token: token_request.payload.access_token)
+else
+  render json: refresh_request.error, status: 400
+end
+```
+
+To use an auth token when making requests, you can either pass it in when initializing the client,
+or on-the-fly.
+
+```ruby
+auth_token = User.first.instagram_token
+
+client = InstagramBasicDisplay::Client.new(auth_token: auth_token)
+
+# OR
+
+client = InstagramBasicDisplay::Client.new
+client.configuration.auth_token = auth_token
+```
+
+### Getting profile information
+
+You can retrieve a user's profile information (e.g. their username and Instagram id).
+
+If no `user_id` is provided, the request will be made against the user associated with the client's auth token. For example:
+
+```ruby
+auth_token = User.first.instagram_token
+
+client = InstagramBasicDisplay::Client.new(auth_token: auth_token)
+response = client.profile
+
+instagram_id = response.payload.id
+instagram_username = response.payload.username
+```
+
+But you can also pass in a `user_id`, and request specific profile fields. Check the Instagram documentation to find out [which fields are supported](https://developers.facebook.com/docs/instagram-basic-display-api/reference/user#fields).
+
+```ruby
+user = User.first
+
+client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
+response = client.profile(user_id: user.instagram_id, fields: %i[username])
+
+instagram_username = response.payload.username
+```
+
+### Getting media
+
+You can query a user's media feed like this:
+
+```ruby
+user = User.first
+
+client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
+response = client.media_feed
+
+media = response.payload.data
+```
+
+You can query for specific fields on the media, but by default you'll receive the `id` and `media_url` of each item. Refer to the Instagram documentation to [find out about other fields](https://developers.facebook.com/docs/instagram-basic-display-api/reference/media/).
+
+```ruby
+user = User.first
+
+client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
+response = client.media_feed(fields: %i[caption media_url])
+
+media = response.payload.data
+```
+
+For pagination, the Instagram API provides previous/next links. Use those to retrieve the next page of results.
+
+```ruby
+
+user = User.first
+
+client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
+
+first_page = client.media_feed(fields: %i[caption media_url])
+
+# you can ask the response whether there is a next/previous page
+has_next_page_link = first_page.next_page?
+
+# or ask for the url
+next_page_link = first_page.next_page_link
+
+second_page = client.media_feed(fields: %i[caption media_url], paginated_url: next_page_link)
+```
+
+You can pass some additional parameters to the media feed. They aren't yet well-documented by Instagram, but you can make some reasonable guesses at what will be accepted, based on the Facebook API. For example, to limit the number of results retrieved:
+
+```ruby
+user = User.first
+
+client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
+client.media_feed(limit: 10)
+```
+
+To retrieve a single piece of media, you'll need to know its id. As with the other requests, you can request whichever fields are supported by Instagram.
+
+```ruby
+user = User.first
+client = InstagramBasicDisplay::Client.new(auth_token: user.instagram_token)
+
+client.media_node(media_id: id, fields: %i[caption media_url id])
+```
 
 ## Development
 
@@ -32,8 +227,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/instagram_basic_display. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
-## Code of Conduct
-
-Everyone interacting in the InstagramBasicDisplay project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/instagram_basic_display/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/convertkit/instagram_basic_display. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/instagram_basic_display.gemspec

@@ -1,27 +1,27 @@
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "instagram_basic_display/version"
+require 'instagram_basic_display/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "instagram_basic_display"
+  spec.name          = 'instagram_basic_display'
   spec.version       = InstagramBasicDisplay::VERSION
-  spec.authors       = ["ConvertKit, LLC"]
-  spec.email         = ["engineering@convertkit.com"]
+  spec.authors       = ['Kit, LLC']
+  spec.email         = ['engineering@kit.com']
 
-  spec.summary       = %q{A ruby wrapper for the Instagram Basic Display API}
-  spec.description   = %q{A ruby wrapper for the Instagram Basic Display API}
-  spec.homepage      = "https://github.com/ConvertKit/instagram_basic_display"
+  spec.summary       = 'A ruby wrapper for the Instagram Basic Display API'
+  spec.description   = 'A ruby wrapper for the Instagram Basic Display API'
+  spec.homepage      = 'https://github.com/Kit/instagram_basic_display'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'bundler', '~> 2.5.23'
+  spec.add_development_dependency 'rake', '~> 13.2'
+  spec.add_development_dependency 'rspec', '~> 3.13.0'
 end

data/lib/instagram_basic_display/auth.rb

@@ -19,14 +19,34 @@ require 'instagram_basic_display/configuration'
 require 'instagram_basic_display/response'
 
 module InstagramBasicDisplay
+  # A module to handle authentication requests to the Instagram API. Allows you to retrieve
+  # short- and long-lived tokens, and refresh long-lived tokens.
+  #
+  # Does not handle retrieving access codes. These must be retrieved by implementing Instagram's
+  #  authentication window.
+  #  https://developers.facebook.com/docs/instagram-basic-display-api/overview#authentication-window
   class Auth
+    # Constructor
+    #
+    # @param configuration [InstagramBasicDisplay::Configuration] configuration information
+    #   that should be used to make requests against the Instagram API.
+    #
+    # @return void
     def initialize(configuration)
       @configuration = configuration
     end
 
+    # Exchanges an access code for a _short-lived_ access token. A short-lived token is valid
+    # for one hour, but can be exchanged for a long-lived token. Refer to Instagram's documentation.
+    # https://developers.facebook.com/docs/instagram-basic-display-api/overview#short-lived-access-tokens
+    #
+    # @param access_code [String] A code retrieved by implementing Instagram's authentication window
+    #   flow: https://developers.facebook.com/docs/instagram-basic-display-api/overview#authentication-window
+    #
+    # @return [InstagramBasicDisplay::Response] a response object containing either the token or an error
     def short_lived_token(access_code:)
       response = Net::HTTP.post_form(
-        URI('https://api.instagram.com/oauth/access_token'),
+        URI(auth_url),
         client_id: configuration.client_id,
         client_secret: configuration.client_secret,
         grant_type: 'authorization_code',
@@ -37,6 +57,13 @@ module InstagramBasicDisplay
       InstagramBasicDisplay::Response.new(response)
     end
 
+    # Exchanges _either_ an access code OR a short-lived token for a long-lived token.
+    #  If an access code is passed, it will first be exchanged for a short-lived token.
+    #  Once that is achieved, the short-lived token will be exchanged for a long-lived token.
+    #  Refer to Instagram's documentation for more information on tokens:
+    #  https://developers.facebook.com/docs/instagram-basic-display-api/overview
+    #
+    # @return [InstagramBasicDisplay::Response] a response object containing either the token or an error
     def long_lived_token(short_lived_token: nil, access_code: nil)
       short_lived_token ||= short_lived_token(access_code: access_code).payload.access_token
 
@@ -52,6 +79,9 @@ module InstagramBasicDisplay
       InstagramBasicDisplay::Response.new(response)
     end
 
+    # Refreshes a long-lived token for a new period of validity.
+    #
+    # @return [InstagramBasicDisplay::Response] a response object containing either the token or an error
     def refresh_long_lived_token(token:)
       uri = URI('https://graph.instagram.com/refresh_access_token')
       params = {
@@ -67,5 +97,13 @@ module InstagramBasicDisplay
     private
 
     attr_reader :configuration
+
+    def auth_url
+      if configuration.version == 1
+        'https://api.instagram.com/oauth/access_token'
+      else
+        'https://graph.instagram.com/oauth/access_token'
+      end
+    end
   end
 end

data/lib/instagram_basic_display/client.rb

@@ -19,23 +19,43 @@ require 'instagram_basic_display/auth'
 require 'instagram_basic_display/profile'
 
 module InstagramBasicDisplay
+  # Exposes all the functionality of the gem, so that you can interact with the Instagram API.
+  # Methods are defined in separate modules, but delegated here for simplicity when interacting
+  # with the gem.
   class Client
     extend Forwardable
 
     def_delegators :@auth, :short_lived_token, :long_lived_token, :refresh_long_lived_token
     def_delegators :@profile, :profile, :media_feed, :media_node, :media_feed_from_link
 
-    def initialize(auth_token: nil)
+    # Constructor method
+    #
+    # @param auth_token [String] optionally pass an auth token that will be used to
+    # make requests. If you do not have a token, you can retrieve one by using the
+    # authentication utilities provided.
+    #
+    # @return void
+    def initialize(auth_token: nil, version: 1)
       @auth_token = auth_token
+      @version = version
 
       @auth = Auth.new(configuration)
       @profile = Profile.new(configuration)
     end
 
+    # Configuration that will be used to make requests against the Instagram API:
+    # redirect_uri, client secret, and client ID. These are automatically picked up from
+    # environment variables. Optionally, you can pass an auth token which will be used
+    # to make requests.
+    #
+    # @return [InstagramBasicDisplay::Configuration]
     def configuration
-      @configuration ||= InstagramBasicDisplay::Configuration.new(auth_token: @auth_token)
+      @configuration ||= InstagramBasicDisplay::Configuration.new(auth_token: @auth_token, version: @version)
     end
 
+    # Sets the gem's configuration
+    #
+    # @return void
     def configure
       yield(configuration) if block_given?
       nil

data/lib/instagram_basic_display/configuration.rb

@@ -15,10 +15,18 @@
 # limitations under the License.
 
 module InstagramBasicDisplay
+  # Holds configuration values that are used to make requests against the
+  # Instagram API
   class Configuration
-    attr_accessor :client_id, :client_secret, :redirect_uri, :auth_token
+    attr_accessor :client_id, :client_secret, :redirect_uri, :auth_token, :version
 
-    def initialize(auth_token: nil)
+    # Constructor method
+    #
+    # @param auth_token [String] token that will be used to make requests
+    #
+    # @return void
+    def initialize(auth_token: nil, version: 1)
+      @version = version
       @client_id = set_client_id
       @client_secret = set_client_secret
       @redirect_uri = set_redirect_uri
@@ -26,15 +34,27 @@ module InstagramBasicDisplay
     end
 
     def set_client_id
-      ENV.fetch('INSTAGRAM_CLIENT_ID')
+      if version == 1
+        ENV.fetch('INSTAGRAM_CLIENT_ID')
+      else
+        ENV.fetch('INSTAGRAM_CLIENT_ID_V2')
+      end
     end
 
     def set_client_secret
-      ENV.fetch('INSTAGRAM_CLIENT_SECRET')
+      if version == 1
+        ENV.fetch('INSTAGRAM_CLIENT_SECRET')
+      else
+        ENV.fetch('INSTAGRAM_CLIENT_SECRET_V2')
+      end
     end
 
     def set_redirect_uri
-      ENV.fetch('INSTAGRAM_REDIRECT_URI')
+      if version == 1
+        ENV.fetch('INSTAGRAM_REDIRECT_URI')
+      else
+        ENV.fetch('INSTAGRAM_REDIRECT_URI_V2')
+      end
     end
   end
 end

data/lib/instagram_basic_display/profile.rb

@@ -20,11 +20,37 @@ require 'instagram_basic_display/response'
 require 'instagram_basic_display/errors'
 
 module InstagramBasicDisplay
+  # Module for interacting with an Instagram user's profile. You can retrieve profile information
+  #  and media.
   class Profile
+    # Constructor
+    #
+    # @param configuration [InstagramBasicDisplay::Configuration] the configuration
+    #   information to use when making requests to Instagram.
+    #
+    # @return void
     def initialize(configuration)
       @configuration = configuration
     end
 
+    # Method for interacting with an Instagram user's profile. Can be used to retrieve
+    #   information such as their id and username.
+    #
+    # @param user_id [String] the id of the user whose information you are retrieving.
+    #   If no user_id is passed, the query will be made agains the user associated with the
+    #   current auth token.
+    #
+    # @param fields [Array<Symbol>] array of fields to retrieve. Defaults to id and username.
+    #   The full list of fields can be found in the Instagram documentation:
+    #   https://developers.facebook.com/docs/instagram-basic-display-api/reference/user#fields
+    #
+    # @param params [Hash] any additional request parameters that should be passed to the API.
+    #
+    # @return [InstagramBasicDisplay::Response] a response object containing the response from
+    #   the Instagram API.
+    #
+    # @raise [InstagramBasicDisplay::NoAuthToken] raises when no auth token is provided in the
+    #  client configuration
     def profile(user_id: nil, fields: %i[id username], **params)
       check_for_auth_token!(params)
 
@@ -38,7 +64,23 @@ module InstagramBasicDisplay
       make_request(uri, params)
     end
 
-    # document that you can add a limit here
+    # Method for retrieving a user's media feed.
+    #
+    # @param user_id [String] the id of the user whose information you are retrieving.
+    #   If no user_id is passed, the query will be made agains the user associated with the
+    #   current auth token.
+    #
+    # @param fields [Array<Symbol>] array of fields to retrieve. Defaults to id and media_url.
+    #   The full list of fields can be found in the Instagram documentation:
+    #   https://developers.facebook.com/docs/instagram-basic-display-api/reference/media/
+    #
+    # @param paginated_url [String] a url to retrieve the next or previous set of results
+    #   from the API. This url is provided by the response from Instagram.
+    #
+    # @param params [Hash] any additional request parameters that should be passed to the API
+    #
+    # @raise [InstagramBasicDisplay::NoAuthToken] raises when no auth token is provided in the
+    #  client configuration
     def media_feed(user_id: nil, fields: %i[id media_url], paginated_url: nil, **params)
       check_for_auth_token!(params)
 
@@ -57,7 +99,18 @@ module InstagramBasicDisplay
       make_request(uri, params)
     end
 
-
+    # Method for retrieving information for a particular media node (i.e. one image or video).
+    #
+    # @param media_id [String] the id of the media you are querying for.
+    #
+    # @param fields [Array<Symbol>] array of fields to retrieve. Defaults to id and media_url.
+    #   The full list of fields can be found in the Instagram documentation:
+    #   https://developers.facebook.com/docs/instagram-basic-display-api/reference/media/
+    #
+    # @param params [Hash] any additional request parameters that should be passed to the API
+    #
+    # @raise [InstagramBasicDisplay::NoAuthToken] raises when no auth token is provided in the
+    #  client configuration
     def media_node(media_id:, fields: %i[id media_url], **params)
       check_for_auth_token!(params)
 

data/lib/instagram_basic_display/response.rb

@@ -18,6 +18,10 @@ module InstagramBasicDisplay
   class Response
     attr_reader :status, :body, :response, :paging
 
+    # Constructor
+    # @param response [String] raw JSON repsonse from the Instagram API
+    #
+    # @return void
     def initialize(response)
       @response = response
       @body = JSON.parse(response.body)
@@ -25,30 +29,44 @@ module InstagramBasicDisplay
       @paging = body['paging']
     end
 
+    # Returns whether or not a next page of results from the Instagram API is available
+    # @return [Boolean]
     def next_page?
       !next_page_link.nil?
     end
 
+    # Returns whether or not a previous page of results from the Instagram API is available
+    # @return [Boolean]
     def previous_page?
       !previous_page_link.nil?
     end
 
+    # Returns a link to the next page of results from the Instagram API
+    # @return [String]
     def next_page_link
       paging['next'] if paging
     end
 
+    # Returns a link to the previous page of results from the Instagram API
+    # @return [String]
     def previous_page_link
       paging['previous'] if paging
     end
 
+    # Returns whether the request to the Instagram API was a success
+    # @return [Boolean]
     def success?
       response.message == 'OK'
     end
 
+    # Returns the raw payload from Instagram's API deserialized into a Struct
+    # @return [Struct]
     def payload
       deserialize_json(body)
     end
 
+    # If an error is returned from the Instagram API, returns it as a Struct
+    # @return [Nil, Struct]
     def error
       return unless body['error'] || body['error_message']
 

data/lib/instagram_basic_display/version.rb

@@ -15,6 +15,5 @@
 # limitations under the License.
 
 module InstagramBasicDisplay
-  VERSION = '0.2.0'
+  VERSION = '0.2.2'
 end
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: instagram_basic_display
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
-- ConvertKit, LLC
-autorequire: 
+- Kit, LLC
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-02-25 00:00:00.000000000 Z
+date: 2024-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,45 +16,45 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: 2.5.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: 2.5.23
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 3.13.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 3.13.0
 description: A ruby wrapper for the Instagram Basic Display API
 email:
-- engineering@convertkit.com
+- engineering@kit.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -80,10 +80,10 @@ files:
 - lib/instagram_basic_display/profile.rb
 - lib/instagram_basic_display/response.rb
 - lib/instagram_basic_display/version.rb
-homepage: https://github.com/ConvertKit/instagram_basic_display
+homepage: https://github.com/Kit/instagram_basic_display
 licenses: []
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -98,9 +98,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: A ruby wrapper for the Instagram Basic Display API
 test_files: []