postageapp 1.3.1 → 1.4.0

data/lib/postageapp/cli.rb

@@ -0,0 +1,14 @@
+module PostageApp::CLI
+  class UnknownCommand < StandardError
+  end
+
+  def self.parse!(command_name, *args)
+    if (command = PostageApp::CLI::Command.defined[command_name.to_sym])
+      command.parse!(*args)
+    else
+      raise UnknownCommand, "The command #{command_name.inspect} is not known."
+    end
+  end
+end
+
+require_relative './cli/command'

data/lib/postageapp/cli/command.rb

@@ -0,0 +1,110 @@
+require 'optparse'
+
+class PostageApp::CLI::Command
+  class APICallError < StandardError
+  end
+
+  class MissingArguments < StandardError
+  end
+
+  def self.defined
+    @defined ||= { }
+  end
+
+  def self.define(command_name = nil, &block)
+    command_name ||= $command_name
+    command = self.defined[command_name] = new(command_name)
+
+    command.instance_eval(&block) if (block_given?)
+  end
+
+  def initialize(command_name)
+    @command_name = command_name
+    @api_key_context = :project
+    @argument = { }
+  end
+
+  def api_key(context)
+    @api_key_context = context
+  end
+
+  def argument(name, optional: false, type: String, desc: nil, boolean: false)
+    @argument[name] = {
+      optional: optional,
+      type: String,
+      desc: desc,
+      boolean: boolean
+    }
+  end
+
+  def perform(&block)
+    @perform = block
+  end
+
+  def parse!(*args)
+    arguments = { }
+
+    op = OptionParser.new do |parser|
+      parser.banner = "Usage: postageapp #{@command_name} [options]"
+
+      @argument.each do |name, attributes|
+        if (attributes[:boolean])
+          parser.on("--#{name}", attributes[:desc]) do
+            arguments[name] = true
+          end
+        else
+          parser.on("--#{name} VALUE", "#{attributes[:desc]} (#{attributes[:optional] ? 'optional' : 'required'})") do |v|
+            arguments[name] = v
+          end
+        end
+      end
+    end
+    
+    op.parse!(args)
+
+    missing = @argument.select do |name, attributes|
+      !attributes[:optional] && arguments[name].nil?
+    end.keys
+
+    if (missing.any?)
+      $stderr.puts("Error: missing options #{missing.join(', ')}")
+
+      puts op.help
+
+      raise MissingArguments
+    end
+
+    case (@api_key_context)
+    when :account
+      arguments['api_key'] = PostageApp.configuration.account_api_key
+    end
+
+    case (@perform&.arity)
+    when 1
+      return @perform.call(arguments)
+    when 0
+      return @perform.call
+    end
+
+    response = PostageApp::Request.new(@command_name, arguments).send
+
+    case (response.status)
+    when "ok"
+      puts JSON.pretty_generate(response.data)
+    else
+      $stderr.puts("Received error: #{response.status}")
+
+      if (response.message)
+        $stderr.puts('  ' + response.message)
+      end
+
+      raise APICallError
+    end
+  end
+end
+
+Dir.glob(File.expand_path('./command/*.rb', __dir__)) do |command|
+  $command_name = File.basename(command, '.rb').to_sym
+
+  require command
+end

data/lib/postageapp/cli/command/config.rb

@@ -0,0 +1,74 @@
+PostageApp::CLI::Command.define do
+  argument :'no-header',
+    optional: true,
+    boolean: true,
+    desc: 'An identifier to refer to this mailbox on subsequent API calls'
+
+  argument :markdown,
+    optional: true,
+    boolean: true,
+    desc: 'Emit markdown formatted description of variables'
+
+  perform do |arguments|
+    if (arguments[:markdown])
+      PostageApp::Configuration.params.each do |param, config|
+        case (default = config[:default])
+        when Proc
+          default = default.call
+        end
+
+        puts '* `%s`: %s (%s)' % [
+          param,
+          config[:desc],
+          case (config[:required])
+          when String
+            'required %s' % config[:required]
+          when true
+            'required'
+          else
+            default ? 'default: `%s`' % default : 'optional'
+          end
+        ]
+
+        config[:aliases]&.each do |param_alias|
+          puts '* `%s`: Alias for `%s`' % [
+            param_alias,
+            param
+          ]
+        end
+      end
+    else
+      unless (arguments[:'no-header'])
+        puts '%-40s %s' % [ 'Variable', 'Description' ]
+        puts '-' * 78
+      end
+  
+      PostageApp::Configuration.params.each do |param, config|
+        case (default = config[:default])
+        when Proc
+          default = default.call
+        end
+
+        puts '%-40s %s (%s)' % [
+          param,
+          config[:desc],
+          case (config[:required])
+          when String
+            'required %s' % config[:required]
+          when true
+            'required'
+          else
+            default ? 'default: %s' % default : 'optional'
+          end
+        ]
+
+        config[:aliases]&.each do |param_alias|
+          puts '%-40s Alias for %s' % [
+            param_alias,
+            param
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/postageapp/cli/command/create_mailbox.rb

@@ -0,0 +1,21 @@
+PostageApp::CLI::Command.define do
+  api_key :account
+
+  argument :uid,
+    optional: true,
+    desc: 'An identifier to refer to this mailbox on subsequent API calls'
+  argument :label,
+    optional: true,
+    desc: 'A descriptive name for this mailbox'
+  argument :host,
+    desc: 'IMAP server hostname'
+  argument :port,
+    optional: true,
+    desc: 'IMAP server port (default 993)'
+  argument :username,
+    desc: 'Username/email-address used to authenticate with the IMAP server'
+  argument :password,
+    desc: 'Password used to authenticate with the IMAP server'
+  argument :postback_url,
+    desc: 'The URL to post received email content to'
+end

data/lib/postageapp/cli/command/env.rb

@@ -0,0 +1,58 @@
+PostageApp::CLI::Command.define do
+  argument :'no-header',
+    optional: true,
+    boolean: true,
+    desc: 'Suppress display of header'
+
+  argument :markdown,
+    optional: true,
+    boolean: true,
+    desc: 'Emit markdown formatted description of variables'
+
+  perform do |arguments|
+    if (arguments[:markdown])
+      PostageApp::Configuration.params.each do |param, config|
+        config[:env_vars]&.each_with_index do |var, i|
+          case (i)
+          when 0
+            case (default = config[:default])
+            when Proc
+              default = default.call
+            end
+
+            puts '* `%s`: %s (%s)' % [
+              var,
+              config[:desc],
+              case (config[:required])
+              when String
+                'required %s' % config[:required]
+              when true
+                'required'
+              else
+                default ? 'default: `%s`' % default : 'optional'
+              end
+            ]
+          else
+            puts '* `%s`: Alias for `%s`' % [
+              var,
+              config[:env_vars][0]
+            ]
+          end
+        end
+      end
+    else
+      unless (arguments[:'no-header'])
+        puts '%-40s %s' % [ 'Variable', 'Setting' ]
+        puts '-' * 78
+      end
+  
+      PostageApp::Configuration.params.each do |param, config|
+        config[:env_vars]&.each do |var|
+          puts '%-40s %s' % [
+            var, ENV[var]
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/postageapp/cli/command/get_project_info.rb

@@ -0,0 +1,3 @@
+PostageApp::CLI::Command.define do
+  # No arguments required for this command
+end

data/lib/postageapp/configuration.rb

@@ -32,8 +32,8 @@
 # -------------
 # :proxy_host - Proxy server hostname
 # :proxy_port - Proxy server port
-# :proxy_user - Proxy server username
-# :proxy_pass - Proxy server password
+# :proxy_username - Proxy server username
+# :proxy_password - Proxy server password
 
 # Advanced Options
 # ----------------
@@ -45,8 +45,6 @@
 class PostageApp::Configuration
   # == Constants ============================================================
 
-  HOST_DEFAULT = 'api.postageapp.com'.freeze
-
   SOCKS5_PORT_DEFAULT = 1080
   HTTP_PORT_DEFAULT = 80
   HTTPS_PORT_DEFAULT = 443
@@ -56,96 +54,254 @@ class PostageApp::Configuration
     false => 'http'.freeze
   }.freeze
 
-  PATH_DEFAULT = '/'.freeze
-
-  FRAMEWORK_DEFAULT = 'Ruby'.freeze
-  ENVIRONMENT_DEFAULT = 'production'.freeze
+  CONFIG_PARAMS = {
+    api_key: {
+      default: nil,
+      desc: 'Project API key to use',
+      required: 'for project API functions'
+    },
+    account_api_key: {
+      default: nil,
+      desc: 'Account API key to use',
+      required: 'for account API functions'
+    },
+    postback_secret: {
+      default: nil,
+      desc: 'Secret to use for validating ActionMailbox requests'
+    },
+    project_root: {
+      default: -> {
+        if (defined?(Rails) and Rails.respond_to?(:root))
+          Rails.root
+        else
+          Dir.pwd
+        end
+      },
+      desc: 'Project root for logging purposes'
+    },
+    recipient_override: {
+      default: nil,
+      interrogator: true,
+      desc: 'Override sender on `send_message` calls'
+    },
+    logger: {
+      default: nil,
+      env: false,
+      desc: 'Logger instance to use'
+    },
+    secure: {
+      default: true,
+      interrogator: true,
+      env: false,
+      after_set: -> (config) {
+        if (config.secure?)
+          config.protocol = 'https'
+          if (config.port == 80)
+            config.port = 443
+          end
+        else
+          config.protocol = 'http'
+          if (config.port == 443)
+            config.port = 80
+          end
+        end
+      },
+      desc: 'Enable verifying TLS connections'
+    },
+    verify_tls: {
+      default: true,
+      aliases: [ :verify_certificate ],
+      interrogator: true,
+      parse: -> (v) {
+        case (v)
+        when 'true', 'yes', 'on'
+          true
+        when String
+          v.to_i != 0
+        else
+          !!v
+        end
+      },
+      desc: 'Enable TLS certificate verification'
+    },
+    host: {
+      default: 'api.postageapp.com'.freeze,
+      desc: 'API host to contact'
+    },
+    port: {
+      default: 443,
+      desc: 'API port to contact'
+    },
+    scheme: {
+      default: 'https'.freeze,
+      aliases: [ :protocol ],
+      desc: 'HTTP scheme to use'
+    },
+    proxy_username: {
+      default: nil,
+      aliases: [ :proxy_user ],
+      desc: 'SOCKS5 proxy username'
+    },
+    proxy_password: {
+      default: nil,
+      aliases: [ :proxy_pass ],
+      desc: 'SOCKS5 proxy password'
+    },
+    proxy_host: {
+      default: nil,
+      desc: 'SOCKS5 proxy host'
+    },
+    proxy_port: {
+      default: 1080,
+      parse: -> (v) { v.to_i },
+      desc: 'SOCKS5 proxy port'
+    },
+    open_timeout: {
+      default: 5,
+      aliases: [ :http_open_timeout ],
+      parse: -> (v) { v.to_i },
+      desc: 'Timeout in seconds when initiating requests'
+    },
+    read_timeout: {
+      default: 10,
+      aliases: [ :http_read_timeout ],
+      parse: -> (v) { v.to_i },
+      desc: 'Timeout in seconds when awaiting responses'
+    },
+    retry_methods: {
+      default: %w[ send_message ].freeze,
+      aliases: [ :requests_to_resend ],
+      parse: -> (v) {
+        case (v)
+        when String
+          v.split(/\s*(?:,|\s)\s*/).grep(/\S/)
+        else
+          v
+        end
+      },
+      desc: 'Which API calls to retry, comma and/or space separated'
+    },
+    framework: {
+      default: -> {
+        if (defined?(Rails) and Rails.respond_to?(:version))
+          'Ruby %s / Ruby on Rails %s' % [
+            RUBY_VERSION,
+            Rails.version
+          ]
+        else
+          'Ruby %s' % RUBY_VERSION
+        end
+      },
+      desc: 'Framework used'
+    },
+    environment: {
+      default: 'production',
+      desc: 'Environment to use'
+    }
+  }.freeze
 
   # == Properties ===========================================================
 
-  attr_accessor :secure
-  attr_writer :scheme
-  attr_accessor :host
-  attr_writer :port
-  attr_accessor :proxy_host
-  attr_writer :proxy_port
-  attr_accessor :proxy_user
-  attr_accessor :proxy_pass
-
-  attr_accessor :verify_certificate
-  attr_accessor :http_open_timeout
-  attr_accessor :http_read_timeout
-  attr_accessor :recipient_override
-  attr_accessor :requests_to_resend
-  attr_accessor :project_root
-  attr_accessor :framework
-  attr_accessor :environment
-  attr_accessor :logger
+  CONFIG_PARAMS.each do |param, config|
+    attr_reader param
 
-  # == Instance Methods =====================================================
-  
-  def initialize
-    @secure = true
-    @verify_certificate = true
+    ivar = config[:ivar] ||= :"@#{param}"
+    mutator_method = :"#{param}="
+    config[:sources] = [ param ]
+    after_set = config[:after_set]
+
+    if (parser = config[:parse])
+      define_method(mutator_method) do |v|
+        instance_variable_set(ivar, parser.call(v))
+      end
+    else
+      define_method(mutator_method) do |v|
+        instance_variable_set(ivar, v)
 
-    @host = ENV['POSTAGEAPP_HOST'] || HOST_DEFAULT
+        after_set and after_set[self]
+      end
+    end
 
-    @proxy_port = SOCKS5_PORT_DEFAULT
+    interrogator_method = nil
 
-    @http_open_timeout = 5
-    @http_read_timeout = 10
+    if (config[:interrogator])
+      interrogator_method = :"#{param}?"
+      define_method(interrogator_method) do
+        !!instance_variable_get(ivar)
+      end
+    end
 
-    @requests_to_resend = %w[ send_message ]
+    if (param_aliases = config[:aliases])
+      param_aliases.each do |param_alias|
+        config[:sources] << param_alias
 
-    @framework = FRAMEWORK_DEFAULT
-    @environment = ENVIRONMENT_DEFAULT
-  end
-  
-  alias_method :secure?, :secure
-  alias_method :verify_certificate?, :verify_certificate
+        alias_method param_alias, param
+        alias_method :"#{param_alias}=", mutator_method
 
-  def port_default?
-    if (self.secure?)
-      self.port == HTTPS_PORT_DEFAULT
-    else
-      self.port == HTTP_PORT_DEFAULT
+        if (config[:interrogator])
+          alias_method :"#{param_alias}?", interrogator_method
+        end
+      end
     end
-  end
 
-  def proxy?
-    self.proxy_host and self.proxy_host.match(/\A\S+\z/)
-  end
+    unless (config[:env] === false)
+      config[:env_vars] = config[:sources].map do |source|
+        'POSTAGEAPP_' + source.to_s.upcase
+      end
+    end
 
-  # Assign which API key is used to make API calls. Can also be specified
-  # using the `POSTAGEAPP_API_KEY` environment variable.
-  def api_key=(key)
-    @api_key = key
+    # config[:getters] = config[:sources].map do |source|
+    #   -> (credentials) { credentials[:source] }
+    # end + config[:env_vars].map do |var|
+    #   -> (_) { ENV[var] }
+    # end
   end
-  
-  # Returns the API key used to make API calls. Can be specified as the
-  # `POSTAGEAPP_API_KEY` environment variable.
-  def api_key
-    @api_key ||= ENV['POSTAGEAPP_API_KEY']
+
+  # == Class Methods ========================================================
+
+  def self.params
+    CONFIG_PARAMS
   end
-  
-  # Returns the HTTP scheme used to make API calls
-  def scheme
-    @scheme ||= SCHEME_FOR_SECURE[self.secure?]
+
+  # == Instance Methods =====================================================
+
+  def initialize
+    credentials = self.rails_credentials
+
+    CONFIG_PARAMS.each do |param, config|
+      value = (
+        config[:sources]&.map { |s| credentials[s] }&.compact&.first ||
+        config[:env_vars]&.map { |v| ENV[v] }&.compact&.first
+      )
+
+      if (value)
+        if (config[:parse])
+          instance_variable_set(config[:ivar], config[:parse].call(value))
+        else
+          instance_variable_set(config[:ivar], value)
+        end
+      else
+        case (config[:default])
+        when Proc
+          instance_variable_set(config[:ivar], config[:default].call)
+        else
+          instance_variable_set(config[:ivar], config[:default])
+        end
+      end
+    end
   end
 
-  alias_method :protocol=, :scheme=
-  alias_method :protocol, :scheme
-  
-  # Returns the port used to make API calls
-  def port
-    @port ||= (self.secure? ? HTTPS_PORT_DEFAULT : HTTP_PORT_DEFAULT)
+  # Returns true if the port used for the API is the default port, otherwise
+  # false. 80 for HTTP, 443 for HTTPS.
+  def port_default?
+    self.port == (self.secure? ? HTTPS_PORT_DEFAULT : HTTP_PORT_DEFAULT)
   end
 
-  # Returns the port used to connect via SOCKS5
-  def proxy_port
-    @proxy_port ||= SOCKS5_PORT_DEFAULT
+  # Returns true if a proxy is defined, otherwise false.
+  def proxy?
+    self.proxy_host and self.proxy_host.match(/\A\S+\z/)
   end
-  
+
   # Returns the endpoint URL to make API calls
   def url
     '%s://%s%s' % [
@@ -159,4 +315,11 @@ class PostageApp::Configuration
   def http
     PostageApp::HTTP.connect(self)
   end
+
+protected
+  def rails_credentials
+    if (PostageApp::Env.rails_with_encrypted_credentials?)
+      Rails.application.credentials.postageapp
+    end or { }
+  end
 end