app_store 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Fabien Jakimowicz
+
+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.rdoc

@@ -0,0 +1,91 @@
+= AppStore
+
+== DESCRIPTION
+AppStore is an unofficial implementation of the Apple AppStore API.
+It provides way to search for applications, navigate through categories.
+
+== SYNOPSIS
+=== Examples
+* Simple search
+   @applications = AppStore::Application.search('upnp')
+   @applications.class            # => Array
+   @applications.length           # => 8
+   @applications.first.title      # => "PlugPlayer"
+   @applications.first.price      # => 4.99
+
+* Find an application by its id
+   @fontpicker = AppStore::Application.find_by_id(327076783)
+   @fontpicker.class             # => AppStore::Application
+   @fontpicker.title             # => "FontPicker"
+   @fontpicker.price             # => 0.0
+   @fontpicker.company.title     # => "Etienne Segonzac"
+
+* User reviews
+   @remote = AppStore::Application.find_by_id(284417350)
+   @remote.title                # => "Remote"
+   @remote.user_reviews.length  # => 10
+
+   @review = @remote.user_reviews.first
+
+   @review.user_name            # => "Ebolavoodoo on Aug 27, 2009"
+   @review.average_user_rating  # => 1.0
+   @review.text                 # => "Simply amazing. My new favorite app. Instantly responds. Easy to navigate and control. For those who say it doesn't work. Stinks to be you."
+
+* Categories
+   # Fetch featured categories
+   @categories = AppStore::Category.featured
+   @categories.class              # => Array
+   @categories.length             # => 20
+   
+   # Use category
+   @category = @categories.first
+   @category.title                # => "Games"
+   @category.item_count           # => 1573
+   
+   # Go through subcategories and applications
+   @subcategory = @category.items.last
+   @subcategory.class             # => AppStore::Category
+   @subcategory.title             # => "Word"
+   @subcategory.items.length      # => 26
+   @subcategory.items.first.class # => AppStore::Application
+   @subcategory.items.last.class  # => AppStore::Category
+   @subcategory.items.last.title  # => "Twenty Five More..."
+
+== REQUIREMENTS
+
+* mechanize gem
+* plist gem
+
+== INSTALL
+  gem install app_store
+
+== TODO
+* handle medias (screenshots, icons, ...)
+* optimize navigation through lists
+* handle 'links' to avoid calling AppStore API for each items in a list
+* use FakeMechanize to unit test each calls
+* handle multiple store/language
+
+== LICENSE
+
+(The MIT License)
+
+Copyright (c) 2009, Fabien Jakimowicz <fabien@jakimowicz.com>
+
+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/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "app_store"
+    gem.summary = "AppStore is an unofficial implementation of the Apple AppStore API"
+    gem.description = "AppStore allows you to fetch informations about applications (title, description, size, reviews, ...), make searches, go through categories ..."
+    gem.email = "fabien@jakimowicz.com"
+    gem.homepage = "http://github.com/jakimowicz/app_store"
+    gem.authors = ["Fabien Jakimowicz"]
+    gem.rubyforge_project = "app_store"
+    gem.add_development_dependency "thoughtbot-shoulda"
+    gem.add_development_dependency "fake_mechanize"
+    gem.add_dependency "nokogiri"
+    gem.add_dependency "mechanize"
+    gem.add_dependency "plist"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::RubyforgeTasks.new do |rubyforge|
+    rubyforge.doc_task = "rdoc"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "AppStore #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/app_store/application.rb

@@ -0,0 +1,100 @@
+require "app_store/base"
+require "app_store/company"
+require "app_store/user_review"
+require "app_store/artwork"
+require "app_store/list"
+require "app_store/link"
+
+# Represents an application in the AppStore.
+# Available attributes:
+# * <tt>average_user_rating</tt>: average rating from all user_reviews.
+# * <tt>user_rating_count</tt>: user_reviews count.
+# * <tt>release_date</tt>: release date on the AppStore for the application.
+# * <tt>description</tt>: application description.
+# * <tt>screenshots</tt>: array of Image objects for screenshots.
+# * <tt>item_id</tt>: application id.
+# * <tt>version</tt>: application version.
+# * <tt>company</tt>: a Company object, the one which submit the application.
+# * <tt>title</tt>: application title.
+# * <tt>price</tt>: price of the application on the Apple AppStore.
+# * <tt>icon</tt>: Image object of the application icon.
+# * <tt>size</tt>: size of the application in byte.
+class AppStore::Application < AppStore::Base
+  ApplicationURL        = "http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware"
+  
+  attr_reader :company, :price, :size, :artworks, :icon, :icon_thumbnail, :screenshots
+  
+  plist :accepted_type => 'software',
+    :mapping => {
+      'average-user-rating' => :average_user_rating,
+      'user-rating-count'   => :user_rating_count,
+      'release-date'        => :release_date,
+      'description'         => :description,
+      'item-id'             => :item_id,
+      'version'             => :version,
+      'title'               => :title
+    }
+  
+  # Search an Application by its <tt>id</tt>. Accepts only one <tt>id</tt> and returns an Application instance.
+  def self.find_by_id(id)
+    plist = AppStore::Caller.get(AppStore::Caller::ApplicationURL, :id => id)
+    # TODO : Check if everything was right before instancianting
+    new :plist => plist['item-metadata']
+  end
+  
+  # Search an Application by a <tt>text</tt>.
+  # Returns an array with matching application or an empty array if no result found.
+  def self.search(text)
+    plist = AppStore::Caller.get(AppStore::Caller::SearchURL, :media => 'software', :term => text)
+    AppStore::List.new :list => plist['items']
+  end
+  
+  def initialize(attrs = {})
+    @screenshots ||= []
+    super
+  end
+  
+  # Returns an AppStore::List of UserReview objects.
+  def user_reviews
+    if @user_reviews.nil?
+      plist = AppStore::Caller.get(@raw['view-user-reviews-url'])
+      @user_reviews = AppStore::List.new(:list => plist['items'])
+    end
+    @user_reviews
+  end
+  
+  def itunes_url
+    "#{ApplicationURL}?id=#{item_id}"
+  end
+  
+  def icon
+    if @icon.nil?
+      parsed = AppStore::Caller.itunes_get(AppStore::Caller::ApplicationURL, :id => item_id)
+      @icon = AppStore::Image.new(:plist => parsed.search('PictureView[@height="100"][@width="100"]').first)
+    end
+    
+    @icon
+  end
+  
+  protected
+  def custom_init_from_plist(plist)
+    # Set size and price
+    @price  = plist['store-offers']['STDQ']['price']
+    @size   = plist['store-offers']['STDQ']['size']
+    
+    # Seek for company
+    @company  = AppStore::Company.new(:plist => plist['company'])
+    
+    # Parse artwork
+    @artworks = plist['artwork-urls'].collect do |plist_artwork|
+      # OPTIMIZE : handle default_screenshot
+      if plist_artwork['image-type'] and plist_artwork['default']
+        artwork = AppStore::Artwork.new :plist => plist_artwork
+        @icon_thumbnail ||= artwork.default if artwork.is_icon?
+        @screenshots << artwork.default unless artwork.is_icon?
+        artwork
+      end
+    end
+    @artworks.compact!
+  end
+end

data/lib/app_store/artwork.rb

@@ -0,0 +1,19 @@
+require "app_store/base"
+require "app_store/image"
+
+class AppStore::Artwork < AppStore::Base
+  attr_reader :default, :thumbnail
+  
+  plist :mapping => { 'image-type'  => :image_type }
+    
+  def is_icon?
+    image_type == 'software-icon'
+  end
+
+  protected
+  def custom_init_from_plist(plist)
+    @default = AppStore::Image.new(:plist => plist['default']) if plist['default']
+    @thumbnail = AppStore::Image.new(:plist => plist['thumbnail']) if plist['thumbnail']
+  end
+
+end

data/lib/app_store/base.rb

@@ -0,0 +1,22 @@
+require "app_store/caller"
+require "app_store/helpers/plist"
+
+# Implements basic operations for AppStore objects : initialization, plist parsing, ...
+class AppStore::Base
+  attr_reader :raw
+  
+  extend AppStore::Helper::Plist
+  
+  # Instanciate a new object.
+  # <tt>attrs</tt> accepts:
+  # * <tt>:plist</tt>: a plist object to be parsed
+  def initialize(attrs = {})
+    init_from_plist attrs[:plist] if attrs[:plist]
+  end
+  
+  protected
+  def init_from_plist(plist)
+    custom_init_from_plist plist if respond_to?(:custom_init_from_plist)
+    @raw = plist
+  end
+end

data/lib/app_store/caller.rb

@@ -0,0 +1,45 @@
+require "rubygems"
+require "nokogiri"
+require "mechanize"
+require "plist"
+
+require "app_store"
+
+# Caller regroups all the calling and xml parsing mechanism to call the AppStore.
+module AppStore::Caller
+  extend self
+  
+  FeaturedCategoriesURL = "http://ax.itunes.apple.com/WebObjects/MZStore.woa/wa/viewFeaturedSoftwareCategories"
+  ApplicationURL        = "http://ax.itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware"
+  CategoryURL           = "http://ax.itunes.apple.com/WebObjects/MZStore.woa/wa/viewGenre"
+  SearchURL             = "http://ax.search.itunes.apple.com/WebObjects/MZSearch.woa/wa/search"
+
+  # Call the Apple AppStore using given <tt>url</tt> and passing <tt>params</tt> with an HTTP Get method.
+  def iphone_get(url, params = {})
+    # About the X-Apple-Store-Front header: this is used to select which store and which language.
+    # Format is XXXXXX-Y,Z where XXXXXX is the store number (us, french, ...), Y the language and Z the return format.
+    # If you omit the language, the default one for the store is used.
+    # Return format can be either "1" or "2" : "1" returns data to be directly displayed and "2" is a more structured format.
+    answer = iphone_agent.get(:url => url, :headers => {"X-Apple-Store-Front" => '143441,2'}, :params => params)
+    raise AppStore::RequestError if answer.code.to_s != '200'
+    Plist::parse_xml answer.body
+  end
+  
+  alias :get :iphone_get
+  
+  def itunes_get(url, params = {})
+    answer = itunes_agent.get(url, params)
+    raise AppStore::RequestError if answer.code.to_s != '200'
+    Nokogiri.parse answer.body
+  end
+  
+  protected
+  def iphone_agent
+    @iphone_agent ||= WWW::Mechanize.new { |a| a.user_agent = 'iTunes-iPhone/3.0 (2)' }
+  end
+  
+  def itunes_agent
+    @itunes_agent ||= WWW::Mechanize.new
+  end
+
+end

data/lib/app_store/category.rb

@@ -0,0 +1,38 @@
+require "app_store/base"
+require "app_store/application"
+
+# A category like categories on the AppStore.
+# Available attributes:
+# * <tt>item-count</tt>: total items count for this category.
+# * <tt>title</tt>: title for the category.
+class AppStore::Category < AppStore::Base
+  plist :mapping => {
+    'item-count'  => :item_count,
+    'title'       => :title
+  }
+  
+  # Returns an array of featured categories (main categories).
+  # It is the same list as the one displayed in the iPhone AppStore.
+  def self.featured
+    plist = AppStore::Caller.get(AppStore::Caller::FeaturedCategoriesURL)
+    plist['items'].collect { |item| new :plist => item }
+  end
+  
+  # Returns an array of items contained in the category, with a maximum of 25 items (Apple limitation).
+  # If there are more than 25 items in the category, an extra item is added at the end of the list
+  # as a link to the next 25 entries.
+  # Each element can be either a Category or an Application.
+  def items
+    if @items.nil?
+      plist = AppStore::Caller.get(@raw['url'])
+      @items = AppStore::List.new(
+        :list                 => plist['items'],
+        :element_type         => 'link',
+        :element_initializer  => lambda {|element|
+          (element['link-type'] == 'software' ? AppStore::Link : AppStore::Category).new(:plist => element)
+        }
+      )
+    end
+    @items
+  end
+end

data/lib/app_store/company.rb

@@ -0,0 +1,9 @@
+require "app_store"
+
+# Represents a company (the application developper)
+# The following attributes are available:
+# * <tt>title</tt>: title of the company, or name of the developper.
+# * <tt>url</tt>: website url.
+class AppStore::Company < AppStore::Base
+  plist :mapping => { 'title' => :title, 'url' => :url }
+end

data/lib/app_store/helper.rb

@@ -0,0 +1,2 @@
+module AppStore::Helper
+end

data/lib/app_store/helpers/plist.rb

@@ -0,0 +1,22 @@
+require "app_store/helper"
+
+module AppStore::Helper::Plist
+  def plist(params = {})
+    mapping = params[:mapping].collect do |plist_key, attr_name|
+      # First, make attribute readable outside the instance
+      class_eval "attr_reader :#{attr_name}"
+      
+      # Then, build the content of init_from_plist function
+      "@#{attr_name} = plist['#{plist_key}']"
+    end rescue []
+    
+    class_eval <<-EOV, __FILE__, __LINE__
+      protected
+      def init_from_plist(plist)
+        #{"raise AppStore::ParseError unless plist['type'] == '#{params[:accepted_type]}'" if params[:accepted_type]}
+        super
+        #{mapping.join("\n")}
+      end
+    EOV
+  end
+end

data/lib/app_store/image.rb

@@ -0,0 +1,10 @@
+require 'app_store/base'
+
+class AppStore::Image < AppStore::Base
+  plist :mapping => {
+      'box-height'  => :height,
+      'box-width'   => :width,
+      'needs-shine' => :needs_shine,
+      'url'         => :url,
+    }
+end

data/lib/app_store/link.rb

@@ -0,0 +1,20 @@
+require "app_store/base"
+require "app_store/caller"
+
+class AppStore::Link < AppStore::Base
+  plist :mapping => {
+    'link-type'   => :item_type,
+    'item-id'     => :item_id,
+    'title'       => :title,
+    'url'         => :url
+  }
+  
+  def destination
+    @destination ||= case @item_type
+    when 'software'
+      AppStore::Application.new :plist => AppStore::Caller.get(@url)['item-metadata']
+    else
+      raise 'unsupported'
+    end
+  end
+end

data/lib/app_store/list.rb

@@ -0,0 +1,94 @@
+require 'app_store'
+
+# Represents a list based on data from Apple AppStore.
+# If a list contains too much elements (> 25), the Apple AppStore
+# sends only 24 elements followed by a link for the next 24 elements.
+# This class represents an abstraction of Apple AppStore lists, have
+# a real count attribute and is enumerable over the entire list.
+class AppStore::List
+  include Enumerable
+  
+  # All the elements already gathered.
+  attr_reader :elements
+  
+  # A required attribute <tt>:element_initializer</tt> can be used
+  # to specify a block used for the initialization of each element
+  # of the list
+  def initialize(attrs = {})
+    @element_initializer  = attrs[:element_initializer]
+    @element_type         = attrs[:element_type]
+    @elements ||= []
+    
+    process_new_elements attrs[:list]
+  end
+  
+  # Returns the real elements count, not a count based on the elements
+  # already fetched.
+  def count
+    @count ||= @elements.count
+  end
+  
+  def each(&block)
+    collect(&block)
+    @elements
+  end
+  
+  def collect
+    # First, iterate through already fetched elements
+    result = @elements.collect {|element| yield element}
+    
+    # Then, iterate until we have no more links to follow
+    while (last_elements = fetch_next_elements) do
+      result += last_elements.collect {|element| yield element}
+    end
+    
+    # Returns full array
+    result
+  end
+  
+  private
+  # Fetch next elements using link, append them to @elements
+  # Return last fetched elements if any, nil otherwise
+  def fetch_next_elements
+    return nil if @link_to_next_elements.nil?
+    process_new_elements(AppStore::Caller.get(@link_to_next_elements)['items'])
+  end
+  
+  def process_new_elements(new_elements)
+    result = []
+    @link_to_next_elements = nil
+    
+    new_elements.each do |element|
+      case element['type']
+      when @element_type
+        result << initialize_element_and_append(element)
+      when 'software'
+        result << append_element(AppStore::Application.new(:plist => element))
+      when 'review'
+        result << append_element(AppStore::UserReview.new(:plist => element))
+      when 'link'
+        result << append_element(AppStore::Link.new(:plist => element))
+      when 'more'
+        @count                  = element['total-items']
+        @link_to_next_elements  = element['url']
+      when 'review-header'
+        ;
+      else
+        raise "unsupported type" unless @element_initializer
+      end
+    end
+    
+    result
+  end
+  
+  # Initialize given <tt>element</tt> using @element_initializer block if given,
+  # append block execution result to @elements and return it.
+  def initialize_element_and_append(element)
+    append_element @element_initializer[element]
+  end  
+  
+  def append_element(element)
+    @elements << element
+    element
+  end
+end

data/lib/app_store/user_review.rb

@@ -0,0 +1,17 @@
+require "app_store/base"
+
+# Each Application can have multiple user reviews.
+# Available attributes:
+# * <tt>average_user_rating</tt>: rating given by the user for the application.
+# * <tt>user_name</tt>: name of the user who made the rating.
+# * <tt>title</tt>: title of the rating (probably some internal apple stuff).
+# * <tt>text</tt>: comment leaved by the user.
+class AppStore::UserReview < AppStore::Base
+  plist :accepted_type => 'review',
+    :mapping => {
+      'average-user-rating' => :average_user_rating,
+      'user-name'           => :user_name, # TODO : parse user_name to separate username and comment date
+      'title'               => :title,
+      'text'                => :text
+    }
+end

data/lib/app_store.rb

@@ -0,0 +1,12 @@
+module AppStore
+  # Error while comunicating with the AppStore
+  class RequestError < StandardError
+  end
+  
+  # A parse error is raised if data returned by the AppStore was not expected
+  class ParseError < StandardError
+  end
+end
+
+require "app_store/application"
+require "app_store/category"