instagram 0.3.2 → 0.6

data/.gitignore

@@ -0,0 +1,12 @@
+*.gem
+*.rbc
+.DS_Store
+.bundle
+.rvmrc
+.yardoc
+.rake_tasks~
+Gemfile.lock
+coverage/*
+doc/*
+log/*
+pkg/*

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format=nested
+--backtrace

data/.yardopts

@@ -0,0 +1,9 @@
+--no-private
+--protected
+--tag format:"Supported formats"
+--tag authenticated:"Requires Authentication"
+--tag rate_limited:"Rate Limited"
+--markup markdown
+-
+HISTORY.mkd
+LICENSE.mkd

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Instagram (Burbn, Inc.)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,55 +1,144 @@
-# [Instagram][] Ruby library
-
-This library acts as a client for the [unofficial Instagram API][wiki]. It was used to create [the missing Instagram web interface][web].
-
-    $ gem install instagram
-
-With it, you can:
-
-* fetch popular photos;
-* get user info;
-* browse photos by a user.
-
-Caveat: you need to know user IDs; usernames can't be used. However, you can start from the popular feed and drill down from there.
-
-## Example usage
-
-    require 'instagram'
-    
-    photos = Instagram::popular
-    photo = photos.first
-    
-    photo.caption     #=> "Extreme dog closeup"
-    photo.likes.size  #=> 54
-    photo.filter_name #=> "X-Pro II"
-    
-    photo.user.username      #=> "johndoe"
-    photo.user.full_name     #=> "John Doe"
-    photo.comments[1].text   #=> "That's so cute"
-    photo.images.last.width  #=> 612
-    
-    # available sizes: 150px / 306px / 612px square
-    photo.image_url(612)
-    # => "http://distillery.s3.amazonaws.com/media/-.jpg" (612×612px image)
-    
-    # fetch extended info for John
-    john_info = Instagram::user_info(photo.user.id)
-    
-    john_info.media_count    #=> 32
-    john_info.follower_count #=> 160
-    
-    
-    # find more photos by John
-    photos_by_john = Instagram::by_user(photo.user.id)
-
-To see which models and properties are available, see [models.rb][models].
-
-## Credits
-
-Instagram API documentation and Ruby library written by Mislav Marohnić.
-
-
-[instagram]: http://instagr.am/
-[web]: http://instagram.heroku.com
-[wiki]: https://github.com/mislav/instagram/wiki "Instagram API"
-[models]: https://github.com/mislav/instagram/blob/master/lib/instagram/models.rb
+The Instagram Ruby Gem
+====================
+A Ruby wrapper for the Instagram REST and Search APIs
+
+
+Installation
+------------
+	gem install instagram
+
+
+Follow @instagramapi on Twitter
+----------------------------
+You should [follow @instagramapi on Twitter](http://twitter.com/#!/instagramapi) for announcements,
+updates, and news about the Instagram gem.
+
+
+Join the mailing list!
+----------------------
+<https://groups.google.com/group/instagram-ruby-gem>
+
+
+Does your project or organization use this gem?
+-----------------------------------------------
+Add it to the [apps](http://github.com/Instagram/instagram-ruby-gem/wiki/apps) wiki!
+
+
+Sample Application
+------------------
+	require "sinatra"
+	require "instagram"
+
+	enable :sessions
+
+	CALLBACK_URL = "http://localhost:4567/oauth/callback"
+
+	Instagram.configure do |config|
+	  config.client_id = "YOUR_CLIENT_ID"
+	  config.client_secret = "YOUR_CLIENT_SECRET"
+	end
+
+	get "/" do
+	  '<a href="/oauth/connect">Connect with Instagram</a>'
+	end
+
+	get "/oauth/connect" do
+	  redirect Instagram.authorize_url(:redirect_uri => CALLBACK_URL)
+	end
+
+	get "/oauth/callback" do
+	  response = Instagram.get_access_token(params[:code], :redirect_uri => CALLBACK_URL)
+	  session[:access_token] = response.access_token
+	  redirect "/feed"
+	end
+
+	get "/feed" do
+	  client = Instagram.client(:access_token => session[:access_token])
+	  user = client.user
+
+	  html = "<h1>#{user.username}'s recent photos</h1>"
+	  for media_item in client.user_recent_media
+	    html << "<img src='#{media_item.images.thumbnail.url}'>"
+	  end
+	  html
+	end
+
+
+API Usage Examples
+------------------
+    require "rubygems"
+    require "instagram"
+
+    # Get a list of a user's most recent media
+    puts Instagram.user_recent_media(777)
+
+    # Get the currently authenticated user's media feed
+    puts Instagram.user_media_feed
+
+    # Get a list of recent media at a given location, in this case, the Instagram office
+    puts Instagram.location_recent_media(514276)
+
+    # All methods require authentication (either by client ID or access token).
+	# To get your Instagram OAuth credentials, register an app at http://instagr.am/oauth/client/register/
+    Instagram.configure do |config|
+      config.client_id = YOUR_CLIENT_KEY
+      config.access_token = YOUR_ACCESS_TOKEN
+    end
+
+    # Get a list of all the users you're following
+    puts Instagram.follows
+
+    # Get a list of media close to a given latitude and longitude
+    puts Instagram.media_search("37.7808851,-122.3948632")
+
+	# Get a list of the overall most popular media items
+	puts Instagram.media_popular
+
+	# Search for users on instagram, by name or username
+	puts Instagram.user_search("shayne sweeney")
+
+
+Contributing
+------------
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project.
+
+Here are some ways *you* can contribute:
+
+* by using alpha, beta, and prerelease versions
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace)
+* by refactoring code
+* by closing [issues](http://github.com/Instagram/instagram-ruby-gem/issues)
+* by reviewing patches
+
+
+Submitting an Issue
+-------------------
+We use the [GitHub issue tracker](http://github.com/Instagram/instagram-ruby-gem/issues) to track bugs and
+features. Before submitting a bug report or feature request, check to make sure it hasn't already
+been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
+bug report, please include a [Gist](http://gist.github.com/) that includes a stack trace and any
+details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
+operating system. Ideally, a bug report should include a pull request with failing specs.
+
+
+Submitting a Pull Request
+-------------------------
+1. Fork the project.
+2. Create a topic branch.
+3. Implement your feature or bug fix.
+4. Add documentation for your feature or bug fix.
+5. Run <tt>bundle exec rake doc:yard</tt>. If your changes are not 100% documented, go back to step 4.
+6. Add specs for your feature or bug fix.
+7. Run <tt>bundle exec rake spec</tt>. If your changes are not 100% covered, go back to step 6.
+8. Commit and push your changes.
+9. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)
+
+
+Copyright
+---------
+Copyright (c) 2010 Instagram (Burbn, Inc).
+See [LICENSE](https://github.com/Instagram/instagram-ruby-gem/blob/master/LICENSE.md) for details.

data/Rakefile

@@ -1,10 +1,22 @@
-task :app do
-  $LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
-  $LOAD_PATH.unshift File.dirname($LOAD_PATH.first)
-  require 'app'
-end
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
 
-task :clear => :app do
-  items = CachedInstagram.cache.clear
-  puts "#{items.size} removed"
-end
+task :default => :spec
+
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['HISTORY.mkd', 'LICENSE.mkd', 'lib/**/*.rb']
+    task.options = [
+      '--protected',
+      '--output-dir', 'doc/yard',
+      '--tag', 'format:Supported formats',
+      '--tag', 'authenticated:Requires Authentication',
+      '--tag', 'rate_limited:Rate Limited',
+      '--markup', 'markdown',
+    ]
+  end
+end

data/instagram.gemspec

@@ -0,0 +1,41 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/instagram/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.add_development_dependency('bundler', '~> 1.0')
+  s.add_development_dependency('rake', '~> 0.8')
+  s.add_development_dependency('rspec', '~> 2.4')
+  s.add_development_dependency('yard', '~> 0.6')
+  s.add_development_dependency('simplecov', '~> 0.3')
+  s.add_development_dependency('webmock', '~> 1.6')
+  s.add_development_dependency('ZenTest', '~> 4.4')
+  s.add_runtime_dependency('faraday', '~> 0.5.4')
+  s.add_runtime_dependency('faraday_middleware', '~> 0.3.1')
+  s.add_runtime_dependency('multi_json', '~> 0.0.5')
+  s.add_runtime_dependency('hashie', '~> 1.0.0')
+  s.authors = ["Shayne Sweeney"]
+  s.description = %q{A Ruby wrapper for the Instagram REST and Search APIs}
+  s.post_install_message =<<eos
+********************************************************************************
+
+  Follow @instagram on Twitter for announcements, updates, and news.
+  https://twitter.com/instagramapi
+
+  Join the mailing list!
+  https://groups.google.com/group/instagram-ruby-gem
+
+********************************************************************************
+eos
+  s.email = ['shayne@instagr.am']
+  s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.files = `git ls-files`.split("\n")
+  s.homepage = 'https://github.com/Instagram/instagramrb'
+  s.name = 'instagram'
+  s.platform = Gem::Platform::RUBY
+  s.require_paths = ['lib']
+  s.required_rubygems_version = Gem::Requirement.new('>= 1.3.6') if s.respond_to? :required_rubygems_version=
+  s.rubyforge_project = s.name
+  s.summary = %q{Ruby wrapper for the Instagram API}
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.version = Instagram::VERSION.dup
+end

data/lib/faraday/oauth2.rb

@@ -0,0 +1,36 @@
+require 'faraday'
+
+# @private
+module Faraday
+  # @private
+  class Request::OAuth2 < Faraday::Middleware
+    def call(env)
+
+      if env[:method] == :get or env[:method] == :delete
+        env[:url].query_values = {} if env[:url].query_values.nil?
+        if @access_token and not env[:url].query_values["client_secret"]
+          env[:url].query_values = env[:url].query_values.merge(:access_token => @access_token)
+          env[:request_headers] = env[:request_headers].merge('Authorization' => "Token token=\"#{@access_token}\"")
+        elsif @client_id
+          env[:url].query_values = env[:url].query_values.merge(:client_id => @client_id)
+        end
+      else
+        if @access_token and not env[:body] && env[:body][:client_secret]
+          env[:body] = {} if env[:body].nil?
+          env[:body] = env[:body].merge(:access_token => @access_token)
+          env[:request_headers] = env[:request_headers].merge('Authorization' => "Token token=\"#{@access_token}\"")
+        elsif @client_id
+          env[:body] = env[:body].merge(:client_id => @client_id)
+        end
+      end
+
+      @app.call env
+    end
+
+    def initialize(app, client_id, access_token=nil)
+      @app = app
+      @client_id = client_id
+      @access_token = access_token
+    end
+  end
+end

data/lib/faraday/raise_http_4xx.rb

@@ -0,0 +1,37 @@
+require 'faraday'
+
+# @private
+module Faraday
+  # @private
+  class Response::RaiseHttp4xx < Response::Middleware
+    def self.register_on_complete(env)
+      env[:response].on_complete do |response|
+        case response[:status].to_i
+        when 400
+          raise Instagram::BadRequest, error_message(response)
+        when 404
+          raise Instagram::NotFound, error_message(response)
+        end
+      end
+    end
+
+    def initialize(app)
+      super
+      @parser = nil
+    end
+
+    private
+
+    def self.error_message(response)
+      "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{response[:status]}#{error_body(response[:body])}"
+    end
+
+    def self.error_body(body)
+      if body.nil?
+        nil
+      elsif body['meta'] and not body['meta']['error_message'].blank?
+        ": #{body['meta']['error_message']}"
+      end
+    end
+  end
+end

data/lib/faraday/raise_http_5xx.rb

@@ -0,0 +1,29 @@
+require 'faraday'
+
+# @private
+module Faraday
+  # @private
+  class Response::RaiseHttp5xx < Response::Middleware
+    def self.register_on_complete(env)
+      env[:response].on_complete do |response|
+        case response[:status].to_i
+        when 500
+          raise Instagram::InternalServerError, error_message(response, "Something is technically wrong.")
+        when 503
+          raise Instagram::ServiceUnavailable, error_message(response, "Instagram is rate limiting your requests.")
+        end
+      end
+    end
+
+    def initialize(app)
+      super
+      @parser = nil
+    end
+
+    private
+
+    def self.error_message(response, body=nil)
+      "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{[response[:status].to_s + ':', body].compact.join(' ')}"
+    end
+  end
+end

data/lib/instagram.rb

@@ -1,60 +1,26 @@
-require 'addressable/uri'
-require 'addressable/template'
-require 'net/http'
-require 'instagram/models'
+require File.expand_path('../instagram/error', __FILE__)
+require File.expand_path('../instagram/configuration', __FILE__)
+require File.expand_path('../instagram/api', __FILE__)
+require File.expand_path('../instagram/client', __FILE__)
 
 module Instagram
-  
-  extend self
-  
-  Popular = Addressable::URI.parse 'http://instagr.am/api/v1/feed/popular/'
-  UserFeed = Addressable::Template.new 'http://instagr.am/api/v1/feed/user/{user_id}/'
-  UserInfo = Addressable::Template.new 'http://instagr.am/api/v1/users/{user_id}/info/'
-  SearchTags = Addressable::URI.parse 'http://instagr.am/api/v1/tags/search/'
-  TagFeed = Addressable::Template.new 'http://instagr.am/api/v1/feed/tag/{tag}/'
-  
-  def popular(params = {}, options = {})
-    parse_response(Popular.dup, params, options.fetch(:parse_with, Timeline))
-  end
-  
-  def by_user(user_id, params = {}, options = {})
-    url = UserFeed.expand :user_id => user_id
-    parse_response(url, params, options.fetch(:parse_with, Timeline))
-  end
-  
-  def user_info(user_id, params = {}, options = {})
-    url = UserInfo.expand :user_id => user_id
-    parse_response(url, params, options.fetch(:parse_with, UserWrap))
-  end
-  
-  def search_tags(query, params = {}, options = {})
-    params = {:q => query}.merge(params)
-    parse_response(SearchTags.dup, params, options.fetch(:parse_with, SearchTagsResults))
-  end
-  
-  def by_tag(tag, params = {}, options = {})
-    url = TagFeed.expand :tag => tag
-    parse_response(url, params, options.fetch(:parse_with, Timeline))
+  extend Configuration
+
+  # Alias for Instagram::Client.new
+  #
+  # @return [Instagram::Client]
+  def self.client(options={})
+    Instagram::Client.new(options)
   end
-  
-  private
-  
-  def parse_response(url, params, parser = nil)
-    url.query_values = params
-    body = get_url url
-    parser ? parser.parse(body) : body
+
+  # Delegate to Instagram::Client
+  def self.method_missing(method, *args, &block)
+    return super unless client.respond_to?(method)
+    client.send(method, *args, &block)
   end
-  
-  def get_url(url)
-    response = Net::HTTP.start(url.host, url.port) { |http|
-      http.get url.request_uri, 'User-agent' => 'Instagram Ruby client'
-    }
-    
-    if Net::HTTPSuccess === response
-      response.body
-    else
-      response.error!
-    end
+
+  # Delegate to Instagram::Client
+  def self.respond_to?(method)
+    return client.respond_to?(method) || super
   end
-  
-end
+end