itunes_store_transporter 0.0.1

data/README.rdoc

@@ -0,0 +1,127 @@
+= iTunes::Store::Transporter
+
+Upload and manage your assets in the iTunes Store using the iTunes Store's Transporter (+iTMSTransporter+).
+
+=== Overview
+
+ require "itunes/store/transporter"
+
+ itms = iTunes::Store::Transporter.new(:username => "CouchCaster",
+                                       :shortname => "bigtimer",
+                                       :password => "w3c@llYoU!")
+
+ itms.upload("/path/to/yourpackage.itmsp")
+ metadata = itms.lookup(:apple_id => "yourpackage")
+
+ begin
+   itms.verify("/path/to/package2.itmsp", :verify_asssets => false)
+ rescue iTunes::Store::Transporter::ExecutionError => e
+   puts "Exited with #{e.exitstatus}"
+
+   e.errors.each do |error|
+     puts "#{error.message} - #{error.code}"
+     puts "Basically, you have some faulty metadata" if error.missing_data?
+   end
+ end
+
+=== Description
+
+iTunes::Store::Transporter is a wrapper around Apple's +iTMSTransporter+ program. It currently
+supports the following operations:
+
+* Upload packages
+* Validate packages
+* Retrieve status information
+* Lookup package metadata
+* List providers
+* Retrieve iTunes metadata schemas
+
+It also includes +itms+, an executable that's sorta like using +iTMSTransporter+ directly, except 
+that it can send email notifications and allows one to set global/per-command defaults via <code>$HOME/.itms</code>.
+
+=== Requirements
+
+* Optout v0.0.2 (<code>gem install optout</code>)
+* iTunes Store Transporter (http://www.apple.com/itunes/sellcontent)
+
+=== Running on Windows
+
+On Windows +iTMSTransporter+ is called via the +iTMSTransporter.CMD+ batch file. This file does not handle the
++iTMSTransporter+'s exit status correctly, causing <code>iTunes::Store::Transporter</code> to report everything as a success. 
+
+This can be fixed by modifying +iTMSTransporter.CMD+ (note that the following does not mimic the batch file exactly):
+
+  ...
+
+  call iTMSTransporter\iTMSTransporter %*
+
+  REM Add this line:
+  set exited=%errorlevel%
+
+  cd %olddir%
+
+  REM Add this line too:
+  exit /b %exited%
+
+=== Using itms
+
+<code>itms COMMAND [OPTIONS]</code>
+
+* +COMMAND+ - The command (<code>iTunes::Store::Transporter</code> method) to run
+* +OPTIONS+ - These are equivalent to the given +COMMAND+'s options except they must be given in long option format. For example <code>:apple_id => "X123"</code> would be <code>--apple-id=X123</code>.
+
+==== Config file
+
+Default options and email notifications can be placed in a YAML file at <code>$HOME/.itms</code>. 
+
+    # Global command defaults
+    path: /usr/bin
+    username: sshaw
+    password: Pa55W0rd!
+
+    # Global email defaults    
+    email:
+      to: everyone@example.com
+      from: no-reply@example.com
+      host: smtp.example.com
+
+    # Verify command
+    verify:
+      shortname: lUzer
+
+    # Upload command
+    upload:
+      shortname: enc0d3rz
+      transport: Aspera
+      rate: 750_000
+      # Email notifications for the upload command
+      email:
+        success:
+          cc: assets@example.com
+          subject: iTunes Upload <%= @apple_id %>
+          message: |        
+            <% @username > uploaded it using <%= @transport %>
+
+            Bye!
+        failure:
+          to: support@example.com
+          subject: Upload Failed!
+          message: |
+            Here's the problem: 
+
+            <%= @error %>	
+
+            Fix it!
+
+=== More Info
+
+* Source Code: http://github.com/sshaw/itunes_store_transporter
+* Bugs: http://github.com/sshaw/itunes_store_transporter/issues
+
+=== Author
+
+Skye Shaw [sshaw AT lucas.cis.temple.edu]
+
+=== License
+
+Released under the MIT License: http://www.opensource.org/licenses/MIT

data/bin/itms

@@ -0,0 +1,243 @@
+#!/usr/bin/env ruby
+
+require "erb"
+require "yaml"
+require "net/smtp"
+require "itunes/store/transporter"
+
+# Command line interface to the ITunes::Store::Transporter library. 
+# Using this is sorta like using iTMSTransporter except it can send email notifications and allows
+# one to set global/per-command defaults via $HOME/.itms
+
+module Command
+
+  class << self
+    def execute(name, options, argv)
+      name = name.capitalize
+      # Avoid Ruby 1.8/1.9 String/Symbol/const_defined? differences      
+      unless constants.include?(name) || constants.include?(name.to_sym)
+        raise ArgumentError, "unknown command '#{name}'"
+      end
+
+      command = const_get(name).new(options)
+      command.execute(argv) 
+    end
+  end
+
+  class Base
+    def initialize(options)
+      @itms = ITunes::Store::Transporter.new(options)
+      @options = options
+    end
+  end
+  
+  class Providers < Base
+    def initialize(options)
+      # Let iTMSTransporter print the providers
+      options[:print_stdout] = true
+      super
+    end
+
+    def execute(args = [])
+      @itms.providers
+    end
+  end
+
+  class Lookup < Base
+    def execute(args = [])
+      filename = "#{@options[:apple_id] || @options[:vendor_id]}.xml"
+      metadata = @itms.lookup
+      File.open(filename, "w") { |f| f.write(metadata) }
+      puts "Metadata saved to #{filename}"
+    end
+  end
+  
+  class Schema < Base
+    def execute(args = [])
+      filename = "#{@options[:version]}-#{@options[:type]}.rng"
+      schema = @itms.schema
+      File.open(filename, "w") { |f| f.write(schema) }
+      puts "Schema saved to #{filename}"
+    end
+  end
+  
+  class Status < Base
+    def initialize(options)
+      # Let iTMSTransporter print the status
+      options[:print_stdout] = true
+      super
+    end
+
+    def execute(args = [])
+      @itms.status(args.shift)
+    end
+  end
+
+  class Upload < Base
+    def initialize(options)
+      # These can take a while so we let the user know what's going on 
+      options[:print_stderr] = true unless options.include?(:print_stderr)
+      super
+    end
+
+    def execute(args = [])
+      @itms.upload(args.shift)
+      puts "Upload complete"
+    end
+  end
+
+  class Verify < Base
+    def execute(args = [])
+      @itms.verify(args.shift)
+      puts "Package is valid"
+    end
+  end
+
+  class Version < Base
+    def execute(args = [])
+      puts @itms.version
+    end
+  end
+end  
+
+class Email  
+  Binding = Class.new do
+    def initialize(options = {})
+      options.each do |k, v|
+        name = k.to_s.gsub(/[^\w]+/, "_")
+        instance_variable_set("@#{name}", v)
+      end
+    end
+  end
+  
+  def initialize(config = {})
+    unless config["to"]
+      raise "No email recipeints provided, you must specify at least one" 
+    end
+
+    @config = config
+  end
+  
+  def send(params = {})    
+    to      = @config["to"].to_s.split /,/
+    host    = @config["host"] || "localhost"
+    from    = @config["from"] || "#{ENV["USER"]}@#{host}"
+    params  = params.merge(@config)
+    message = ::ERB.new(build_template).def_class(Binding).new(params).result
+
+    # TODO: auth
+    smtp = ::Net::SMTP.start(host, @config["port"]) do |mail|
+      mail.send_message message, from, to
+    end
+  end
+
+  protected
+  def build_template
+    %w[to from subject cc bcc].inject("") do |t, key|
+      t << "#{key}: #{@config[key]}\n" if @config[key]
+      t
+    end + "\n#{@config["message"]}"
+  end
+end
+
+COMMANDS = ITunes::Store::Transporter.instance_methods(false).map(&:to_s)
+RC_FILE_NAME = ".itms"
+
+def home
+  ENV["HOME"] || ENV["USERPROFILE"]
+end
+
+# Should probably create a class for the options
+def load_config(command)
+  config = {}
+  return config unless home
+
+  path = File.join(home, RC_FILE_NAME)
+  return config unless File.file?(path)
+
+  config = YAML.load_file(path) 
+  
+  # Get the global defaults. select() returns an aray on Ruby < 1.9
+  defaults = config.select { |k,v| !v.is_a?(Hash) } 
+  defaults = Hash[defaults] unless defaults.is_a?(Hash) 
+
+  config[command] = defaults.merge(config[command] || {})
+  
+  # Normalize the email config
+  email = Hash.new { |h, k| h[k] = {} }
+
+  %w[success failure].each do |type|  
+    email[type] = (config[command]["email"] ||= {})[type]    
+    next unless email[type]
+
+    # Merge the global email options & the command's "global" options with the success/failure options 
+    settings = (config["email"].to_a + config[command]["email"].to_a).reject { |k, v| k == "success" or k == "failure" }
+    settings.each do |k, v|
+      email[type][k] = email[type][k] ? "#{email[type][k]}, #{v}" : v
+    end
+  end
+
+  # ITunes::Store::Transporter uses Symbols for options
+  config[command] = config[command].inject({}) do |cfg, (k,v)| 
+    cfg[k.to_sym] = v unless k.empty? # Avoid intern empty string errors in 1.8
+    cfg 
+  end
+
+  config[command][:email] = email
+  config[command]
+end
+
+def print_errors(e)
+  $stderr.puts "#{e.errors.length} error(s)"
+  $stderr.puts "-" * 25
+  # TODO: group by type
+  e.errors.each_with_index do |msg, i|
+    $stderr.puts "#{i+1}. #{msg}"
+  end
+end
+
+def send_email(config, options)
+  return unless config
+  mail = Email.new(config)
+  mail.send(options)
+end
+
+command = ARGV.shift
+abort("usage: itms command [options]") unless command
+abort("invalid command '#{command}', valid commands are: #{COMMANDS.sort.join(', ')}") unless COMMANDS.include?(command)
+
+options = load_config(command)
+
+while ARGV.any?   
+  opt = ARGV.first.dup
+  break unless opt.sub!(/\A--(?=\w)/, "")
+  
+  key, val = opt.split(/=/, 2)
+  key.gsub!(/-/, "_")
+  # TODO: false, --no-xxxx
+  val = true unless val
+  val = val.to_i if val =~ /\A\d+\z/                         
+  options[key.to_sym] = val                        
+  ARGV.shift                         
+end
+
+# Keys for this are strings
+email_options = options.delete(:email) || {}
+command_options = options.dup
+options[:argv] = ARGV.dup
+options[:command] = command
+
+begin 
+  puts "Running command '#{command}'"
+  Command.execute(command, command_options, ARGV)
+  send_email(email_options["success"], options)
+rescue ITunes::Store::Transporter::ExecutionError => e 
+  print_errors(e)
+  options[:error] = e
+  send_email(email_options["failure"], options)
+  exit 1
+rescue ITunes::Store::Transporter::TransporterError => e
+  $stderr.puts e
+  exit 2
+end
+

data/lib/itunes/store/transporter.rb

@@ -0,0 +1,236 @@
+require "itunes/store/transporter/command"
+require "itunes/store/transporter/command/lookup"
+require "itunes/store/transporter/command/providers"
+require "itunes/store/transporter/command/schema"
+require "itunes/store/transporter/command/status"
+require "itunes/store/transporter/command/upload"
+require "itunes/store/transporter/command/verify"
+require "itunes/store/transporter/command/version"
+
+module ITunes
+  module Store      
+    ##
+    # Upload and manage your assets in the iTunes Store using the iTunes Store's Transporter (+iTMSTransporter+).
+
+    class Transporter
+
+      ##
+      # === Arguments 
+      #
+      # [options (Hash)] Transporter options
+      #
+      # === Options
+      #  
+      # Options given here will be used as defaults for all subsequent method calls. Thus you can set method specific options here but, if you call a method that does not accept one of these options, an OptionError will be raised.
+      # 
+      # See specific methods for a list of options. 
+      #
+      # [:username (String)] Your username
+      # [:password (String)] Your password
+      # [:shortname (String)] Your shortname. Optional, not every iTunes account has one
+      # [:path (String)] The path to the +iTMSTransporter+. Optional.
+      # [:print_stdout (Boolean)] Print +iTMSTransporter+'s stdout to your stdout. Defaults to +false+. 
+      # [:print_stderr (Boolean)] Print +iTMSTransporter+'s stderr to your stderr. Defaults to +false+. 
+      #
+
+      def initialize(options = nil)
+        @defaults = create_options(options)
+        @config = { 
+          :path	        => @defaults.delete(:path),
+          :print_stdout => @defaults.delete(:print_stdout), 
+          :print_stderr => @defaults.delete(:print_stderr), 
+        }        
+      end
+
+      ##
+      # :method: lookup
+      # :call-seq: 
+      #   lookup(options = {})
+      #            
+      # Retrieve the metadata for a previously delivered package. 
+      #
+      # === Arguments 
+      #
+      # [options (Hash)] Transporter options
+      #
+      # ==== Options
+      #
+      # You must use either the +:apple_id+ or +:vendor_id+ option to identify the package
+      #
+      # === Errors
+      #
+      # TransporterError, OptionError, ExecutionError
+      #
+      # === Returns
+      #
+      # [String] The metadata
+
+      ##
+      # :method: providers
+      # :call-seq: 
+      #   providers(options = {})
+      #
+      # List of Providers for whom your account is authorzed to deliver for.
+      #
+      # === Arguments 
+      #
+      # [options (Hash)] Transporter options
+      #
+      # === Errors
+      #
+      # TransporterError, OptionError, ExecutionError
+      #
+      # === Returns
+      #
+      # [Array] Each element is a +Hash+ with two keys: +:shortname+ and +:longname+ representing the given provider's long and short names
+
+      ##
+      # :method: schema
+      # :call-seq: 
+      #   schema(options = {})
+      #
+      # Download a RelaxNG schema file for a particular metadata specification.
+      #    
+      # === Arguments 
+      #
+      # [options (Hash)] Transporter options
+      #
+      # === Options
+      #
+      # [:type (String)] transitional or strict
+      # [:version (String)] The schema version you'd like to download. This is typically in the form of +schemaVERSION+. E.g., +film4.8+
+      #
+      # === Errors
+      #
+      # TransporterError, OptionError, ExecutionError      
+      #
+      # === Returns
+      #
+      # [String] The schema
+      
+      ##
+      # :method: status
+      # :call-seq: 
+      #   status(options = {})
+      #
+      # Retrieve the status of a previously uploaded package.
+      #      
+      # === Arguments 
+      #
+      # [options (Hash)] Transporter options
+      #
+      # === Options 
+      #
+      # [:vendor_id (String)] ID of the package you want status info on
+      #
+      # === Errors
+      #
+      # TransporterError, OptionError, ExecutionError
+      #
+      # === Returns
+      #
+      # [Hash] Descibes various facets of the package's status.
+      
+      ##
+      # :method: upload
+      # :call-seq: 
+      #   upload(package, options = {})
+      #
+      # Upload a package to the iTunes Store.
+      #
+      # === Arguments
+      # 
+      # [package (String)] The path to the package directory to upload. Package names must end in +.itmsp+.
+      # [options (Hash)] Transporter options
+      #      
+      # === Options
+      #
+      # [:transport (String)] The method/protocol used to upload your package. Optional. Can be one of: <code>"Aspera"</code>, <code>"Signiant"</code>, or <code>"DEV"</code>. By default +iTMSTransporter+ automatically selects the transport.
+      # [:rate (Integer)] Target bitrate in Kbps. Optional, only used with +Aspera+ and +Signiant+ 
+      # [:success (String)] A directory to move the package to if the upload succeeds
+      # [:failure (String)] A directory to move the package to if the upload fails
+      # [:delete (Boolean)] Delete the package if the upload succeeds. Defaults to +false+.
+      # [:log_history (String)] Write an +iTMSTransporter+ log to this directory. Off by default.
+      #
+      # === Errors
+      #
+      # TransporterError, OptionError, ExecutionError
+      #
+      # === Returns
+      # 
+      # +true+ if the upload was successful.
+            
+      ##
+      # :method: verify      
+      # :call-seq: 
+      #   verify(package, options = {})
+      #      
+      # Validate the contents of a package's metadata and assets.      
+      #
+      # If verification fails an ExecutionError containing the errors will be raised. 
+      # Each error message is an instance of TransporterMessage.
+      #
+      # === Arguments
+      #
+      # [package (String)] The path to the package directory to verify. Package names must end in +.itmsp+.
+      # [options (Hash)] Verify options
+      #
+      # === Options
+      #
+      # [:verify_assets (Boolean)] If false the assets will not be verified. Defaults to +true+.
+      #
+      # === Errors
+      #
+      # TransporterError, OptionError, ExecutionError
+      #
+      # === Returns
+      # 
+      # +true+ if the package was verified.
+      
+      ##
+      # :method: version
+      # :call-seq: 
+      #   version
+      #
+      # Return the underlying +iTMSTransporter+ version.
+      #
+      # === Returns
+      #
+      # [String] The version number
+      
+      %w|upload verify|.each do |command|
+        define_method(command) do |package, *options| 
+          cmd_options = create_options(options.first)
+          cmd_options[:package] = package
+          run_command(command, cmd_options)
+        end
+      end
+      
+      %w|lookup providers schema status version|.each do |command|
+        define_method(command) { |*options| run_command(command, options.shift) }
+      end          
+
+      private 
+      def run_command(name, options) 
+        Command.const_get(name.capitalize).new(@config, @defaults).run(create_options(options))
+      end
+
+      def create_options(options)
+        options ||= {}
+        raise ArgumentError, "options must be a Hash" unless Hash === options
+        options.dup
+      end
+    end
+  end
+end
+
+unless ENV["ITUNES_STORE_TRANSPORTER_NO_SYNTAX_SUGAR"].to_i > 0
+  def iTunes
+    ITunes
+  end
+end
+
+
+
+
+