itunes-connect 0.9.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Alex Vollmer
+
+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,86 @@
+= itunes_connect
+
+This gem provides a very simple command-line utility and backing
+"library" (if I can be so bold to use the term in this context) for
+accessing sales reports from Apple's iTunes Connect website. If you
+want to automate getting reports out of the App Store, this tool is
+for you.
+
+== Usage
+
+=== Command-Line Usage
+
+This gem comes with the <tt>itunes_connect</tt> executable which you can use
+to download reports, import into a sqlite database and report
+from.
+
+You can specify the default values for a handful of command-line
+options by putting them in a file named <tt>.itunesrc</tt> in your
+home directory. The file is in YAML format and should have the
+following keys: 
+
+  * username
+  * password
+  * database (path to sqlite3 file, optional)
+
+==== Downloading Reports
+You can download reports from iTunes Connect using <tt>itunes_connect
+download</tt>. You may specify your iTunes Connect credentials on
+the command line _or_ you can put them in YAML format in
+<tt>~/.itunesrc</tt> with the keys of <tt>:username</tt> and
+<tt>:password</tt>.
+
+You can also dump the report to a file (or standard out):
+
+  itunes_connect download -o /tmp/report.txt
+
+Or you can dump it directly into a sqlite3 database:
+
+  itunes_connect download -b /tmp/report.db
+
+By default the <tt>download</tt> command will retrieve the most recent
+daily report. If you have a <tt>database</tt> key in your
+<tt>~/.itunesrc</tt> file and you _don't_ specify an out file, the
+report will be automatically imported into the database.
+
+You can also ask for weekly or monthly reports by using the
+<tt>-r</tt> command-line option. Note that you can _not_ import a
+montly report directly into the database because the monthly reports
+don't have any days associated with the entries.
+
+Run <tt>itunes_connect help download</tt> for full usage details.
+
+==== Importing Reports
+The <tt>import</tt> command allows you to dump an existing report file
+into the database. This is useful if you've already downloaded a
+number of reports from iTunes Connect and you just want to put them
+into the database.
+
+Run <tt>itunes_connect help import</tt> for full usage details.
+
+==== Reporting
+The <tt>report</tt> command queries your database and can produce
+either detailed, or grouped output. In both cases you can constrain
+the query to any combination of country, start date and end date.
+
+Run <tt>itunes_connect help report</tt> for full usage details.
+
+=== Programmatic Usage
+
+See the documentation for the ItunesConnect::Connection,
+ItunesConnect::Report and ItunesConnect::Store classes for details.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+   bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2009 Alex Vollmer. See LICENSE for details.

data/bin/itunes_connect

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require "itunes_connect"
+require "clip"
+
+ItunesConnect::Commands.usage("No command given") if ARGV.empty?
+
+case command_name = ARGV.shift
+when '--help', '-h'
+  cli = Clip::Parser.new
+  ItunesConnect::Commands::Help.new(cli).execute!(cli)
+else
+  cli = ItunesConnect::Commands.default_clip
+  command = ItunesConnect::Commands.for_name(command_name, cli)
+  ItunesConnect::Commands.usage("Unrecognized command '#{command_name}'") if command.nil?
+  begin
+    cli.parse(ARGV)
+    if cli.valid?
+      command.execute!(cli, cli.remainder)
+    else
+      $stderr.puts(cli)
+    end
+  rescue => e
+    $stderr.puts(e.message)
+    $stderr.puts e.backtrace.join("\n") if cli.verbose?
+  end
+end

data/lib/itunes_connect.rb

@@ -0,0 +1,5 @@
+require "itunes_connect/connection"
+require "itunes_connect/report"
+require "itunes_connect/store"
+require "itunes_connect/commands"
+

data/lib/itunes_connect/commands.rb

@@ -0,0 +1,41 @@
+require "itunes_connect/commands/download"
+require "itunes_connect/commands/import"
+require "itunes_connect/commands/report"
+require "itunes_connect/commands/help"
+require "clip"
+
+module ItunesConnect::Commands       # :nodoc:
+  class << self
+    def for_name(name, clip)
+      self.const_get(name.capitalize.to_sym).new(clip)
+    rescue NameError => e
+      nil
+    end
+
+    def all
+      [Download, Import, Report, Help]
+    end
+
+    def usage(msg)
+      $stderr.puts msg if msg
+      $stderr.puts "USAGE: itunes_connect [command] [options]"
+      ItunesConnect::Commands.all.each do |cmd_cls|
+        cli = Clip do |c|
+          c.banner = "'#{cmd_cls.to_s.split('::').last.downcase}' command options:"
+
+          cmd_cls.new(c)
+        end
+        puts(cli.help)
+        puts
+      end
+      exit 1
+    end
+
+    def default_clip
+      cli = Clip::Parser.new
+      cli.flag('v', 'verbose', :desc => 'Make output more verbose')
+      cli.flag('g', 'debug', :desc => 'Enable debug output/features (dev only)')
+      cli
+    end
+  end
+end

data/lib/itunes_connect/commands/download.rb

@@ -0,0 +1,76 @@
+require "itunes_connect/rc_file"
+require "itunes_connect/report"
+
+module ItunesConnect::Commands
+  class Download                # :nodoc:
+    def initialize(c, rcfile=ItunesConnect::RcFile.default)
+      c.opt('u', 'username', :desc => 'iTunes Connect username')
+      c.opt('p', 'password', :desc => 'iTunes Connect password')
+      c.opt('d', 'date', :desc => 'Daily report date (MM/DD/YYYY format)',
+            :default => (Date.today - 1).strftime('%m/%d/%Y'))
+      c.opt('o', 'out', :desc => 'Dump report to file, - is stdout')
+      c.opt('b', 'db', :desc => 'Dump report to sqlite DB at the given path')
+      c.opt('r', 'report',
+            :desc => 'Report type. One of "Daily", "Weekly", "Monthly"',
+            :default => 'Daily') do |r|
+        r.capitalize
+      end
+      @rcfile = rcfile
+    end
+
+    def execute!(opts, args=[])
+      username, password = if opts.username and opts.password
+                             [opts.username, opts.password]
+                           else
+                             [@rcfile.username, @rcfile.password]
+                           end
+
+      raise ArgumentError.new("Please provide a username") unless username
+      raise ArgumentError.new("Please provide a password") unless password
+
+      if opts.db and opts.out
+        raise ArgumentError.new("You can only specify :out or :db, not both")
+      end
+
+      if opts.report =~ /^Monthly/ and opts.db
+        raise ArgumentError.new("You cannot persist monthly reports to a " +
+                                "database because these reports have no dates " +
+                                "associated with them")
+      end
+
+      connection = ItunesConnect::Connection.new(username,
+                                            password,
+                                            opts.verbose?,
+                                            opts.debug?)
+      db = opts.db || @rcfile.database
+      out = if opts.out.nil?
+              db ? StringIO.new : $stdout
+            else
+              opts.out == "-" ? $stdout : File.open(opts.out, "w")
+            end
+      connection.get_report(opts.date || Date.today - 1, out, opts.report)
+
+      if db and StringIO === out
+        $stdout.puts "Importing into database file: #{db}" if opts.verbose?
+        store = ItunesConnect::Store.new(db, opts.verbose?)
+        out.rewind
+        report = ItunesConnect::Report.new(out)
+        count = 0
+        report.each do |entry|
+          count += 1 if store.add(entry.date,
+                                  entry.country,
+                                  entry.install_count,
+                                  entry.upgrade_count)
+        end
+        $stdout.puts "Inserted #{count} rows into #{opts.db}" if opts.verbose?
+      end
+
+      out.flush
+      out.close unless out == $stdout
+    end
+
+    def description
+      "Retrieves reports from the iTunes Connect site"
+    end
+  end
+end

data/lib/itunes_connect/commands/help.rb

@@ -0,0 +1,31 @@
+require "itunes_connect/commands"
+
+module ItunesConnect::Commands
+  class Help                    # :nodoc:
+    def initialize(c)
+      # nothing to do here
+    end
+
+    def execute!(opts={ }, args=[], out=$stdout)
+      if args.empty?
+        out.puts "Available commands:"
+        out.puts
+        ItunesConnect::Commands.all.each do |cmd|
+          out.printf("%-9s %s\n",
+                     cmd.to_s.split('::').last.downcase,
+                     cmd.new(Clip::Parser.new).description)
+        end
+      else
+        cli = ItunesConnect::Commands.default_clip
+        cmd = ItunesConnect::Commands.for_name(args.first, cli)
+        cli.banner = "Command options for '#{cmd.class.to_s.split('::').last.downcase}':"
+        raise ArgumentError.new("Unrecognized command '#{args.first}'") if cmd.nil?
+        out.puts(cli.help)
+      end
+    end
+
+    def description
+      "Describe a particular command"
+    end
+  end
+end

data/lib/itunes_connect/commands/import.rb

@@ -0,0 +1,35 @@
+require "itunes_connect/rc_file"
+require "itunes_connect/report"
+
+module ItunesConnect::Commands
+  class Import                  # :nodoc:
+    def initialize(c, rcfile=ItunesConnect::RcFile.default)
+      c.opt('b', 'db', :desc => 'Dump report to sqlite DB at the given path')
+      c.req('f', 'file', :desc => 'The file to import, - means standard in')
+      @rcfile = rcfile
+    end
+
+    def execute!(opts, args=[])
+      db = opts.db || @rcfile.database || nil
+      raise ArgumentError.new("Missing :db option") unless db
+      raise ArgumentError.new("Missing :file option") if opts.file.nil?
+      store = ItunesConnect::Store.new(db, opts.verbose?)
+      input = opts.file == '-' ? $stdin : open(opts.file, 'r')
+      count = 0
+      ItunesConnect::Report.new(input).each do |entry|
+        count += 1 if store.add(entry.date,
+                                entry.country,
+                                entry.install_count,
+                                entry.upgrade_count)
+      end
+
+      if opts.verbose?
+        $stdout.puts "Added #{count} rows to the database"
+      end
+    end
+
+    def description
+      "Imports report data into a database file"
+    end
+  end
+end

data/lib/itunes_connect/commands/report.rb

@@ -0,0 +1,78 @@
+require "itunes_connect/rc_file"
+require "itunes_connect/store"
+
+module ItunesConnect::Commands
+  class Report                  # :nodoc:
+    def initialize(c, rcfile=ItunesConnect::RcFile.default)
+      c.opt('b', 'db', :desc => 'Dump report to sqlite DB at the given path')
+      c.opt('c', 'country',
+            :desc => 'A two-letter country code to filter results with')
+      c.opt('f', 'from', :desc => 'The starting date, inclusive') do |f|
+        Date.parse(f)
+      end
+      c.opt('t', 'to', :desc => 'The ending date, inclusive') do |t|
+        Date.parse(t)
+      end
+      c.flag('s', 'summarize', :desc => 'Summarize results by country code')
+      c.flag('n', 'no-header', :desc => 'Suppress the column headers on output')
+      c.opt('d', 'delimiter',
+             :desc => 'The delimiter to use for output (normally TAB)',
+            :default => "\t")
+      c.flag('o', 'total', :desc => 'Add totals at the end of the report')
+      @rcfile = rcfile
+    end
+
+    def execute!(opts, args=[], out=$stdout)
+      db = opts.db || @rcfile.database || nil
+      raise ArgumentError.new("Missing :db option") if db.nil?
+      store = ItunesConnect::Store.new(db)
+      params = {
+        :to => opts.to,
+        :from => opts.from,
+        :country => opts.country
+      }
+
+      total_installs, total_upgrades = 0, 0
+
+      unless opts.no_header?
+        out.puts([opts.summarize? ? nil : "Date",
+                  "Country",
+                  "Installs",
+                  "Upgrades"
+                 ].compact.join(opts.delimiter))
+      end
+
+      if opts.summarize?
+        store.country_counts(params).each do |x|
+          out.puts [x.country,
+                    x.install_count,
+                    x.update_count].join(opts.delimiter)
+          total_installs += x.install_count
+          total_upgrades += x.update_count
+        end
+      else
+        store.counts(params).each do |x|
+          out.puts [x.report_date,
+                    x.country,
+                    x.install_count,
+                    x.update_count].join(opts.delimiter)
+          total_installs += x.install_count
+          total_upgrades += x.update_count
+        end
+      end
+
+      if opts.total?
+        out.puts ["Total",
+                  opts.summarize? ? nil : "-",
+                  total_installs,
+                  total_upgrades
+                 ].compact.join(opts.delimiter)
+      end
+      out.flush
+    end
+
+    def description
+      "Generates reports from a local database"
+    end
+  end
+end

data/lib/itunes_connect/connection.rb

@@ -0,0 +1,162 @@
+require "digest/md5"
+require "tempfile"
+require "yaml"
+require "zlib"
+require "rubygems"
+require "httpclient"
+require "nokogiri"
+
+module ItunesConnect
+
+  # Abstracts the iTunes Connect website.
+  # Implementation inspired by
+  # http://code.google.com/p/itunes-connect-scraper/
+  class Connection
+
+    REPORT_PERIODS = ["Monthly Free", "Weekly", "Daily"]
+
+    BASE_URL = 'https://itts.apple.com' # :nodoc:
+    REFERER_URL = 'https://itts.apple.com/cgi-bin/WebObjects/Piano.woa' # :nodoc:
+
+    # Create a new instance with the username and password used to sign
+    # in to the iTunes Connect website
+    def initialize(username, password, verbose=false, debug=false)
+      @username, @password = username, password
+      @verbose = verbose
+      @debug = debug
+    end
+
+    def verbose?                # :nodoc:
+      !!@verbose
+    end
+
+    def debug?                  # :nodoc:
+      !!@debug
+    end
+
+    # Retrieve a report from iTunes Connect. This method will return the
+    # raw report file as a String. If specified, the <tt>date</tt>
+    # parameter should be a <tt>Date</tt> instance, and the
+    # <tt>period</tt> parameter must be one of the values identified
+    # in the <tt>REPORT_PERIODS</tt> array, or this method will raise
+    # and <tt>ArgumentError</tt>.
+    #
+    # Any dates given that equal the current date or newer will cause
+    # this method to raise an <tt>ArgumentError</tt>.
+    #
+    def get_report(date, out, period='Daily')
+      date = Date.parse(date) if String === date
+      if date >= Date.today
+        raise ArgumentError, "You must specify a date before today"
+      end
+
+      period = 'Monthly Free' if period == 'Monthly'
+      unless REPORT_PERIODS.member?(period)
+        raise ArgumentError, "'period' must be one of #{REPORT_PERIODS.join(', ')}"
+      end
+
+      # grab the home page
+      doc = Nokogiri::HTML(get_content(REFERER_URL))
+      login_path = (doc/"form/@action").to_s
+
+      # login
+      doc = Nokogiri::HTML(get_content(login_path, {
+                                         'theAccountName' => @username,
+                                         'theAccountPW' => @password,
+                                         '1.Continue.x' => '36',
+                                         '1.Continue.y' => '17',
+                                         'theAuxValue' => ''
+                                       }))
+
+      report_url = (doc / "//*[@name='frmVendorPage']/@action").to_s
+      report_type_name = (doc / "//*[@id='selReportType']/@name").to_s
+      date_type_name = (doc / "//*[@id='selDateType']/@name").to_s
+
+      # handle first report form
+      doc = Nokogiri::HTML(get_content(report_url, {
+                                         report_type_name => 'Summary',
+                                         date_type_name => period,
+                                         'hiddenDayOrWeekSelection' => period,
+                                         'hiddenSubmitTypeName' => 'ShowDropDown'
+                                       }))
+      report_url = (doc / "//*[@name='frmVendorPage']/@action").to_s
+      report_type_name = (doc / "//*[@id='selReportType']/@name").to_s
+      date_type_name = (doc / "//*[@id='selDateType']/@name").to_s
+      date_name = (doc / "//*[@id='dayorweekdropdown']/@name").to_s
+
+      # now get the report
+      date_str = case period
+                 when 'Daily'
+                   date.strftime("%m/%d/%Y")
+                 when 'Weekly', 'Monthly Free'
+                   date = (doc / "//*[@id='dayorweekdropdown']/option").find do |d|
+                     d1, d2 = d.text.split(' To ').map { |x| Date.parse(x) }
+                     date >= d1 and date <= d2
+                   end[:value] rescue nil
+                 end
+
+      raise ArgumentError, "No reports are available for that date" unless date_str
+
+      report = get_content(report_url, {
+                             report_type_name => 'Summary',
+                             date_type_name => period,
+                             date_name => date_str,
+                             'download' => 'Download',
+                             'hiddenDayOrWeekSelection' => date_str,
+                             'hiddenSubmitTypeName' => 'Download'
+                           })
+
+      begin
+        gunzip = Zlib::GzipReader.new(StringIO.new(report))
+        out << gunzip.read
+      rescue => e
+        doc = Nokogiri::HTML(report)
+        msg = (doc / "//font[@id='iddownloadmsg']").text.strip
+        $stderr.puts "Unable to download the report, reason:"
+        $stderr.puts msg.strip
+      end
+    end
+
+    private
+
+    def client
+      @client ||= client = HTTPClient.new
+    end
+
+    def get_content(uri, query=nil, headers={ })
+      $stdout.puts "Querying #{uri} with #{query.inspect}" if self.debug?
+      if @referer
+        headers = {
+          'Referer' => @referer,
+          'User-Agent' => 'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/531.9 (KHTML, like Gecko) Version/4.0.3 Safari/531.9'
+        }.merge(headers)
+      end
+      url = case uri
+            when /^https?:\/\//
+              uri
+            else
+              BASE_URL + uri
+            end
+
+      response = client.get(url, query, headers)
+
+      if self.debug?
+        md5 = Digest::MD5.new; md5 << url; md5 << Time.now.to_s
+        path = File.join(Dir.tmpdir, md5.to_s + ".html")
+        out = open(path, "w") do |f|
+          f << "Status: #{response.status}\n"
+          f << response.header.all.map do |name, value|
+            "#{name}: #{value}"
+          end.join("\n")
+          f << "\n\n"
+          f << response.body.dump
+        end
+        puts "#{url} -> #{path}"
+      end
+
+      @referer = url
+      response.body.dump
+    end
+
+  end
+end