fusebox 0.1.1 → 0.2.0

data/README.md

@@ -1,18 +1,30 @@
+# fusebox
+
+## Description
+
 [FuseMail](http://fusemail.com) is a business email hosting provider offering outsourced email hosting to businesses and resellers.
 
 **fusebox** is a ruby gem that provides a 1:1 native ruby interface for every command of [FuseMail Platform Programming Interface v2.6](http://www.fusemail.com/support/administration-api), which allows you to manage your accounts, domains, forwards, and aliases via an underlying HTTP interface.
 
 ## Installation
-    gem install fusebox
+    $ gem install fusebox
 
 ## Configuration
-Although the library supports passing a username and password to {Fusebox::Request#initialize}, we recommend storing authentication information in a yaml file within {Fusebox::Request.auth_yaml_paths} as:
+Although the library supports passing a username and password to {Fusebox::Request#initialize}, we recommend storing authentication information in a YAML file within {Fusebox::Request.auth_yaml_paths} as:
 
-    # cat ~/.fusemail.yaml
+    $ cat ~/.fusemail.yaml
     username: my_username
     password: my_password
 
-## Examples
+## Command Line Interface (CLI)
+fusebox comes with a command line interface (written on the amazing [thor](http://github.com/wycats/thor/)).  CLI usage requires the setup of a ~/.fusemail.yaml authentication file. For a command list type:
+    $ fusebox help
+or for command specific flags, e.g. "rm"
+    $ fusebox help rm
+
+Note: The CLI interface *currently* assumes all group accounts are named postmaster@example.com, and that the username for all accounts is a full email address.
+
+## Library Examples
 ### Fetch a list of users
     response = Fusebox::Request.new.report
     if response.success?
@@ -27,13 +39,13 @@ Although the library supports passing a username and password to {Fusebox::Reque
       puts "Failure: " + response.detail
     end
 
+See the [Fusebox::Request](http://rubydoc.info/github/mudbugmedia/fusebox/master/Fusebox/Request) documentation for more commands.
 
 ## Documentation
-http://rubydoc.info/github/mudbugmedia/fusebox/master/frames
+* [Project Documentation](http://rubydoc.info/github/mudbugmedia/fusebox/master/frames)
+* [Command Documentation](http://rubydoc.info/github/mudbugmedia/fusebox/master/Fusebox/Request)
 
 ## TODO
-* Ruby 1.8's OpenSSL does not verify certificates and displays "warning: peer certificate won't be verified in this SSL session"
-* CLI tools with Thor
 * Logging hook
 * Leverage ActiveModel to create Account, Domain, Alias, etc, classes.
 

data/bin/fusebox

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require File.expand_path('../../lib/fusebox', __FILE__)
+require 'fusebox/cli'
+
+# Unavailable until we can confirm our final behavior
+# config_rc = File.expand_path('~/.fuseboxrc')
+# require config_rc if File.exist?(config_rc)
+
+Fusebox::Cli.start

data/lib/fusebox/cli.rb

@@ -0,0 +1,131 @@
+require 'thor'
+require 'fusebox/core_ext/array'
+
+module Fusebox
+
+  # These methods are executed via the `bin/fusebox` executable
+  # @todo
+  #   * Allow specification of group admin username-part instead of 'postmaster' (via yaml? fuseboxrc?)
+  #   * Exit codes
+  #   * Flags for simple, non-table output for report methods (to allow piping)
+  class Cli < Thor
+    include Thor::Actions
+
+    desc "add user@example.com password first_name last_name", "Create user account under a group"
+    def add (username, password, first_name, last_name)
+      group_parent = username.gsub /.*(@.*)/, 'postmaster\1'
+      response = Fusebox::Request.new.order(:account_type => 'group_subaccount', :group_parent => group_parent, :user => username, :password => password, :first_name => first_name, :last_name => last_name)
+      say response.detail
+    end
+
+    desc "alias-add user@example.com alias1@example.com [alias2@example.com [...]]", "Add an alias to an account"
+    def alias_add(username, *aliases)
+      response = Fusebox::Request.new.modify(:user => username, :alias => aliases)
+      say response.detail
+    end
+    
+    desc "alias-ls user@example.com", "List aliases for a user"
+    def alias_ls (username)
+      response = Fusebox::Request.new.reportmail(:user => username, :report_type => 'alias')
+      if response.success?
+        response.records.sort { |x,y| x[:email_name] <=> y[:email_name]}.each { |a| say a[:email_name] }
+      else
+        warn response.detail
+      end
+    end
+    
+    desc "alias-rm user@example.com alias1@example.com", "Remove an alias from a maccount"
+    def alias_rm (username, alias_address)
+      response = Fusebox::Request.new.removealias(:user => username, :alias => alias_address)
+      say response.detail
+    end
+    
+    desc "domain-add [postmaster@]example.com new.example.com", "Add a domain a group account"
+    def domain_add (username, domain)
+      username = "postmaster@#{username}" unless username =~ /@/
+      response = Fusebox::Request.new.adddomain(:user => username, :domain => domain)
+      say response.detail
+    end
+    
+    desc "domain-rm secondary.example.com", "Remove a domain"
+    method_options [:force, '-f'] => false
+    def domain_rm (domain)
+      if options[:force] || yes?("Are you sure you want to remove domain: #{domain}? [y/N]")
+        response = Fusebox::Request.new.removedomain(:domain => domain, :confirm => true)
+        say response.detail
+      end
+    end
+    
+    desc "enable user@example.com", "Enable a suspended user account"
+    def enable (username)
+      response = Fusebox::Request.new.enable(:user => username)
+      say response.detail
+    end
+    
+    desc "get [user@]example.com", "Get aliases, forwarders, and mailing lists for an account"
+    # @todo Display account metadata from `report`
+    def get (username)
+      username = "postmaster@#{username}" unless username =~ /@/
+      response = Fusebox::Request.new.reportmail(:user => username)
+      if response.success?
+        say response.records.sort { |x,y| x[:email_name] <=> y[:email_name]}.to_ascii_table [:username, :internal_account_id, :email_type, :email_name, :email_destination], %w(Username ID Type Name Destination)
+      else
+        warn response.detail
+      end
+    end
+    
+    desc "group-add [postmaster@]example.com [password]", "Create a group account"
+    def group_add (username, password = nil)
+      username = "postmaster@#{username}" unless username =~ /@/
+      last, first = username.split /@/
+      password ||= ActiveSupport::SecureRandom.hex
+      response = Fusebox::Request.new.order(:account_type => 'standard', :user => username, :password => password, :first_name => first, :last_name => last)
+      say response.detail
+    end
+    
+    desc "ls [[postmaster@]example.com]", "List accounts. This will list all group accounts if argument is blank"
+    method_options [:recursive, '-r'] => :boolean
+    # @todo add flag for ignoring terminated accounts
+    def ls (username = 'all')
+      username = "postmaster@#{username}" unless username =~ /@/ || username == 'all'
+      recursive = options[:recursive] || (username == 'all' ? false : true)
+      response = Fusebox::Request.new.report(:user => username, :group_subaccount => recursive, :report_type => 'extended')
+      if response.success?
+        say response.records.sort { |x,y| x[:username] <=> y[:username]}.to_ascii_table([:username, :creation_date, :internal_account_id, :status, :disk_usage], %w(Username Created ID Status Disk))
+      else
+        warn response.detail
+      end
+    end
+    
+    desc "passwd user@example.com [newpassword]", "Change a user's password (will prompt if password left blank)"
+    def passwd (username, password = nil)
+      password = ask "New Password:" unless password
+      response = Fusebox::Request.new.modify(:user => username, :password => password)
+      say response.detail
+    end
+    
+    desc "rename old@example.com new@example.com", "Rename an account's username"
+    def rename (old_username, new_username)
+      response = Fusebox::Request.new.changeusername(:user => old_username, :newuser => new_username)
+      say response.detail
+    end
+
+    desc "rm user@example.com", "Terminate a user or group account immediately"
+    method_options :purge => false
+    method_options [:force, '-f'] => false
+    def rm (username)
+      if options[:force] || yes?("Are you sure you want to remove user: #{username}? [y/N]")
+        response = Fusebox::Request.new.terminate(:user => username, :purge => options[:purge])
+        say response.detail
+      else
+        say "No action taken."
+      end
+    end
+    
+    desc "suspend user@example.com", "Suspend a user account"
+    def suspend (username)
+      response = Fusebox::Request.new.suspend(:user => username)
+      say response.detail
+    end
+  end
+end

data/lib/fusebox/core_ext/array.rb

@@ -0,0 +1,47 @@
+class Array
+  
+  # Return an ASCII table for an array of hashes
+  # @example
+  #     [{:a => "Uno", :b => "Dos"}, {:a => "Ichi", :b => "Ni"}].to_ascii_table([:a, :b], %w(One Two))
+  # @param [Array<Symbol>] keys Which keys to display, in order
+  # @param [Array<Symbol>] labels Column headings for the keys
+  # @return [String]
+  def to_ascii_table (keys, labels)    
+    raise ArgumentError, "`labels` length does not match `keys` length" if keys.length != labels.length
+    return '' if self.length == 0
+    raise ArgumentError, "expected elements to be Hash instances; instead received: #{first.inspect}" unless first.is_a?(Hash)
+    
+    widths = keys.map do |key|
+      ([Hash[keys.zip(labels)]] + self).map { |row| row[key].to_s.length }.max
+    end
+    
+    text = ''
+    
+    text += to_ascii_table_hr(widths)
+    
+    labels.each_with_index do |key, i|
+      text += "| " + labels[i].ljust(widths[i] + 1)
+    end
+    text += "|\n"
+    
+    text += to_ascii_table_hr(widths)
+    
+    each do |row|
+      keys.each_with_index do |key, i|
+        text +=  "| " + row[key].ljust(widths[i] + 1)
+      end
+      text +=  "|\n"
+    end
+    
+    text += to_ascii_table_hr(widths)
+    text
+  end
+  
+protected
+  # Print a horizonal divider calc
+  # @param [Array<Fixnum>] widths List of column widths
+  def to_ascii_table_hr(widths)
+    '+' + '-' * (widths.inject(&:+) + widths.length * 3 - 1 ) + "+\n"
+  end
+  
+end

data/lib/fusebox/request.rb

@@ -203,8 +203,8 @@ module Fusebox
     # The terminate request is used to permanently remove an account and all of the account data associated with it. This operation cannot be reversed and therefore should be used with caution.
     # @see http://www.fusemail.com/support/administration-api/requests/terminate terminate API documentation
     # @param [Array] opts
-    # @option opts [String] 'user' Username of FuseMail account to terminate
-    # @option opts [Boolean] 'purge' (false) Will purge all data (such as removing the username) from our system. This process might take a few hours to complete.
+    # @option opts [String] :user Username of FuseMail account to terminate
+    # @option opts [Boolean] :purge (false) Will purge all data (such as removing the username) from our system. This process might take a few hours to complete.
     # @return [Response]
     def terminate (opts)
       default_options = {
@@ -219,8 +219,8 @@ module Fusebox
     # This request will remove a single alias from a fusemail account
     # @see http://www.fusemail.com/support/administration-api/requests/removealias removealias API documentation
     # @param [Array] opts
-    # @option opts [String] 'user' FuseMail user to delete alias from
-    # @option opts [String] 'alias' alias to delete (e.g. user@example.com )
+    # @option opts [String] :user FuseMail user to delete alias from
+    # @option opts [String] :alias alias to delete (e.g. user@example.com )
     # @return [Response]
     def removealias (opts)
       default_options = {
@@ -235,8 +235,8 @@ module Fusebox
     # This request will remove a domain name and all its mail aliases, auto-responders, mailing lists & forwarders associated with it. Please see below for the specific requirements for this request.
     # @see http://www.fusemail.com/support/administration-api/requests/removedomain removedomain API documentation
     # @param [Array] opts
-    # @option opts [String] 'domain' The domain to delete
-    # @option opts [Boolean] 'confirm' (true) This must be set to true to confirm that you understand all aliases, auto-responders, mailing lists & forwarders with this domain will be permanently deleted.
+    # @option opts [String]  :domain The domain to delete
+    # @option opts [Boolean] :confirm (true) This must be set to true to confirm that you understand all aliases, auto-responders, mailing lists & forwarders with this domain will be permanently deleted.
     # @return [Response]
     def removedomain (opts)
       default_options = {
@@ -252,9 +252,9 @@ module Fusebox
     # This request will remove an existing email forwarder
     # @see http://www.fusemail.com/support/administration-api/requests/removeforward removeforward API documentation
     # @param [Array] opts
-    # @option opts [String] 'user' Username of FuseMail account to remove forwarder to
-    # @option opts [String] 'forward_what' Email address of forwarder
-    # @option opts [String] 'forward_to' External email address that forwarder will send to
+    # @option opts [String] :user Username of FuseMail account to remove forwarder to
+    # @option opts [String] :forward_what Email address of forwarder
+    # @option opts [String] :forward_to External email address that forwarder will send to
     # @return [Response]
     def removeforward (opts)
       default_options = {
@@ -270,9 +270,9 @@ module Fusebox
     # This request will provide information about one or more accounts under your platform in CSV format
     # @see http://www.fusemail.com/support/administration-api/requests/report report API documentation
     # @param [Array] opts
-    # @option opts [String] 'user' ('all') The username you wish to query for information; you may also enter the username "all" to get information about all users under your platform
-    # @option opts [Boolean] 'group_subaccount' (true) Provide information not only for the Group Administration account but also for the group sub-accounts under the Group Administration account
-    # @option opts ['basic', 'extended'] report_type ('basic') Level of detailed in returned results
+    # @option opts [String] :user ('all') The username you wish to query for information; you may also enter the username "all" to get information about all users under your platform
+    # @option opts [Boolean] :group_subaccount (true) Provide information not only for the Group Administration account but also for the group sub-accounts under the Group Administration account
+    # @option opts ['basic', 'extended'] :report_type ('basic') Level of detailed in returned results
     # @return [Response]
     def report (opts = {})
       default_options = {
@@ -288,9 +288,9 @@ module Fusebox
     # This request will provide information about mail aliases, forwarders, autoresponders, or mailing lists on one or more accounts under your platform in CSV format.
     # @see http://www.fusemail.com/support/administration-api/requests/reportmail reportmail API documentation
     # @param [Array] opts
-    # @option opts [String] 'user' ('all') The username you wish to query for information; you may also enter the username "all" to get information about all users under your platform
-    # @option opts [Boolean] 'group_subaccount' (true) Provide information not only for the Group Administration account but also for the group sub-accounts under the Group Administration account
-    # @option opts ['all', 'alias', 'forwarder', 'autorespond', 'mailinglist'] report_type ('all')
+    # @option opts [String] :user ('all') The username you wish to query for information; you may also enter the username "all" to get information about all users under your platform
+    # @option opts [Boolean] :group_subaccount (true) Provide information not only for the Group Administration account but also for the group sub-accounts under the Group Administration account
+    # @option opts ['all', 'alias', 'forwarder', 'autorespond', 'mailinglist'] :report_type ('all')
     #   * 'all' = Provide aliases, forwarders, autoresponders, and mailing list info
     #   * 'alias' = Provide only alias information
     #   * 'forwarder' = Provide only fowarder information
@@ -301,7 +301,7 @@ module Fusebox
       default_options = {
         :user => 'all',
         :group_subaccount => true,
-        :report_type => 'extended'
+        :report_type => 'all'
       }
       
       opts.reverse_merge! default_options
@@ -311,7 +311,7 @@ module Fusebox
     # The suspend request allow you to suspend an account under your platform or temporarily stop access to the account without deleting any of the accounts data. Below are the variables that are specific to this request.
     # @see http://www.fusemail.com/support/administration-api/requests/suspend suspend API documentation
     # @param [Array] opts
-    # @option opts [String] 'user' Username of FuseMail account to suspend
+    # @option opts [String] :user Username of FuseMail account to suspend
     # @return [Response]
     def suspend (opts)
       default_options = {

data/lib/fusebox/version.rb

@@ -1,4 +1,4 @@
 module Fusebox
   # @return [String] Version number
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/fusebox.rb

@@ -9,4 +9,6 @@ require 'net/https'
 require 'fusebox/version'
 require 'fusebox/request'
 require 'fusebox/response'
-require 'fusebox/core_ext/net_http'
+require 'fusebox/core_ext/net_http'
+
+# 'fusebox/cli' is intentionally not loaded to reduce overhead; bin/fusebox requires it instead

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: fusebox
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Gabe Martin-Dempesy
@@ -34,9 +34,24 @@ dependencies:
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: thor
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 0
+        - 14
+        version: "0.14"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -46,17 +61,19 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id002
-description: FuseMail API client library
+  version_requirements: *id003
+description: FuseMail API client library and CLI
 email: 
 - gabe@mudbugmedia.com.com
-executables: []
-
+executables: 
+- fusebox
 extensions: []
 
 extra_rdoc_files: []
 
 files: 
+- lib/fusebox/cli.rb
+- lib/fusebox/core_ext/array.rb
 - lib/fusebox/core_ext/net_http.rb
 - lib/fusebox/request.rb
 - lib/fusebox/response.rb
@@ -69,6 +86,7 @@ files:
 - spec/spec_helper.rb
 - LICENSE
 - README.md
+- bin/fusebox
 has_rdoc: true
 homepage: http://github.com/mudbugmedia/fusebox
 licenses: []
@@ -104,6 +122,6 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: FuseMail API client library
+summary: FuseMail API client library and CLI
 test_files: []