lumberg 1.1.1 → 2.0.0.pre3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b22e147b50255ebe87b7c3592dc4f6e42c1d15cb
+  data.tar.gz: aaea7f8b4385e62a9913f77d72a0a6efe754a9b3
+SHA512:
+  metadata.gz: 20e11aa01b835eea33dceccf8fcf758b58dae495896b5c2b45cab92c474a389dab8c9590fed251fff9c3820f066af321c0e4f28b5e6b674b34899bc31cea09b5
+  data.tar.gz: e3d4b304d424184e3e5d8137c8240d8c59ff16c87e5bba7d117c3279418d193b28fe4534a0557fbe6f28f6dcc03b627c02fe04549ba9fab9742be947f4636cd6

data/.travis.yml

@@ -7,11 +7,6 @@ notifications:
     on_success: never
     on_failure: always
 rvm:
-  - 1.8.7
-  - 1.9.2
   - 1.9.3
-  - ree
-  - rbx-head
-  - rbx-18mode
-  - jruby-18mode
+  - 2.0.0
   - jruby-19mode

data/README.md

@@ -1,5 +1,4 @@
-Lumberg [![Lumberg Build Status][Build Icon]][Build Status]
-===========================================================
+# Lumberg [![Lumberg Build Status][Build Icon]][Build Status]
 
 ![Lumberg logo](http://i.imgur.com/xC4Sw.jpg)
 
@@ -8,21 +7,19 @@ beta-ish. Please report any issues you find. :)
 
 [RDoc](http://rdoc.info/github/site5/lumberg/master/frames)
 
-Confirmed to work with ruby 1.8.7, 1.9.2, Rubinius, REE and JRuby 1.6.0 on
+Confirmed to work with ruby 1.8.7, 1.9.2, REE and JRuby 1.6.0 on
 cPanel 11.28+
 
 [Build Status]: http://travis-ci.org/site5/lumberg
 [Build Icon]: https://secure.travis-ci.org/site5/lumberg.png?branch=master
 
 
-Install
--------
+## Install
 
     gem install lumberg
 
 
-Usage
------
+## Usage
 
 Create a server object and connect to WHM using your host and hash:
 
@@ -108,8 +105,7 @@ pp result[:params][:acct].first
 ```
 
 
-Account Example
----------------
+### Account Example
 
 Creating a new account requires only a username, domain, and password.
 
@@ -168,8 +164,7 @@ newuser account removed
 ```
 
 
-Reseller Example
-----------------
+### Reseller Example
 
 Creating a reseller works by changing the status of an existing user account,
 so first we create a user account and then we can create that user as a reseller.
@@ -218,20 +213,133 @@ p result[:message]
 Account Terminations Complete
 ```
 
-Contributors
-============
+### Accessing cPanel API
 
-* [Justin Mazzi](http://github.com/jmazzi)
-* [Tim Parkin](http://github.com/tparkin)
+[cPanel API](http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/ApiIntroduction)
+interface is provided by the `Lumberg::Cpanel` module. Classes within the module
+correspond to cPanel API modules. cPanel API module coverage is currently
+incomplete and we're seeking contributions. Check out [Extending
+Lumberg::Cpanel](#extending-lumbergcpanel) for details on how you can help.
 
-Note on Patches/Pull Requests
-=============================
 
-All HTTP interactions are recorded using VCR and FakeWeb. Please be sure to
-remove any sensitive information from your cassettes.
+#### Email example
+
+```ruby
+# Create an interface object for cPanel API Email module
+email = Lumberg::Cpanel::Email.new(
+  :server       => server,  # An instance of Lumberg::Server
+  :api_username => "jerry"  # User whose cPanel we'll be interacting with
+)
+
+# Get a list of email accounts
+email.accounts[:params][:data] #=> Array of info hashes for each email account
+
+# Add an email forwarder to forward mail for my-forwarder@domain.com to
+# dest@other-domain.com
+email.add_forwarder(
+  :domain   => "domain.com",
+  :email    => "my-forwarder",
+  :fwdopt   => "fwd",
+  :fwdemail => "dest@other-domain.com"
+)
+
+```
+
+## Contributing
+
+### Extending Lumberg::Cpanel
+
+1. Find a cPanel API module that isn't already covered. See
+   [cPanel API documentation](http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/ApiIntroduction)
+   for a full list of available API modules.
+
+2. Create a file (underscore style) in `lib/lumberg/cpanel/` named after the
+   cPanel API module you're working on. If the cPanel API module is "LangMods"
+   name the file "lang_mods.rb". You'll define your class here. `require` this
+   file from `lib/lumberg/cpanel.rb`.
+
+3. Define a class that inherits from `Lumberg::Cpanel::Base`:
+   ```ruby
+   # Create a class for (fictional) "SomeModule" API module
+   module Lumberg
+     module Cpanel
+       class SomeModule < Base
+       end
+     end
+   end
+   ```
+   The cPanel API module name is normally inferred from the class name, e.g., if
+   the class name is `Email` the cPanel "Email" API module will be used. If the
+   cPanel API module you're working with doesn't match up with Ruby class naming
+   convention, override the `::api_module` class method:
+   ```ruby
+   module Lumberg
+     module Cpanel
+       class SslInfo
+         def self.api_module; "SSLInfo"; end
+       end
+     end
+   end
+   ```
+4. Fill in the methods.
+   ```ruby
+   module Lumberg
+     module Cpanel
+       class Branding
+         # Public: Get URL locations for specific sprites.
+         #
+         # options - Hash options for API call params (default: {}):
+         #  :img        - String branding object label for the image you want to
+         #                retrieve.
+         #  :imgtype    - String branding image type you want to retrieve, e.g.,
+         #                "icon" or "heading".
+         #  :method     - String specification for returned value options.
+         #                Acceptable values are: "only_filetype_gif",
+         #                "skip_filetype_gif", "snap_to_smallest_width", and
+         #                "scale_60percent".
+         #  :subtype    - String branding image subtype, e.g., "img", "bg",
+         #                "compleximg".
+         #  :image      - String parameter allows you to force appropriate
+         #                output by setting it to "heading" (optional).
+         #  :skipgroups - String parameter allows you to specify whether or not
+         #                to include "img" values that begin with "group_" in
+         #                the output. "1" indicates that you wish to skip "img"
+         #                values that begin with "group_" (optional).
+         #
+         # Returns Hash API response.
+         def list_sprites(options = {})
+           perform_request({
+            :api_function => "spritelist"
+           }.merge(options))
+         end
+       end
+     end
+   end
+   ```
+   - In many cases, you'll name your methods to match up
+     with the documented cPanel API methods. However, the documented method
+     names are sometimes a bit lengthy, confusing, or otherwise unwiedly; feel
+     free to give your corresponding method an improved name.
+   - Use [TomDoc](http://tomdoc.org/) documentation for your methods.
+     Be sure to document all required and optional parameters from the
+     cPanel API documentation.
+   - All methods should take an options arg that defaults to {}.
+     These options should be merged onto the options passed to
+     #perform_request to allow overriding of :api_username or
+     other parameters.
+
+### Sanitizing VCR cassettes
+All HTTP interactions are recorded using VCR and FakeWeb. Please be sure to remove
+sensitive data from your cassettes. A Rake task is provided for this purpose:
+```
+WHM_HOST=my-cpanel-server.com WHM_HASH=$(cat my-access-hash) bundle exec rake sanitize_cassettes
+```
+Once you've sanitized your cassettes, manually verify that there's no sensitive
+information still present (check URLs, authorization params, etc.).
+
+### Note on Patches/Pull Requests
 
 * Fork the project.
-* Add yourself to the Contributors list
 * 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.
@@ -240,7 +348,6 @@ remove any sensitive information from your cassettes.
   commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
-Copyright
-=========
+## Copyright
 
-Copyright (c) 2012 Site5.com. See LICENSE for details.
+Copyright (c) 2012-2013 Site5.com. See LICENSE for details.

data/lib/lumberg.rb

@@ -7,6 +7,7 @@ require 'uri'
 require 'faraday'
 require 'faraday_middleware'
 require 'logger'
+require 'resolv'
 
 # Internal Libs
 require 'lumberg/format_whm'
@@ -14,6 +15,7 @@ require 'lumberg/version'
 require 'lumberg/exceptions'
 require 'lumberg/config'
 require 'lumberg/whm'
+require 'lumberg/cpanel'
 
 module Lumberg
 

data/lib/lumberg/cpanel.rb

@@ -0,0 +1,29 @@
+module Lumberg
+  module Cpanel
+    require "lumberg/cpanel/base"
+    require "lumberg/cpanel/addon_domain"
+    require "lumberg/cpanel/sub_domain"
+    require "lumberg/cpanel/park"
+    require "lumberg/cpanel/email"
+    require "lumberg/cpanel/backups"
+    require "lumberg/cpanel/box_trapper"
+    require "lumberg/cpanel/branding"
+    require "lumberg/cpanel/contact"
+    require "lumberg/cpanel/cron"
+    require "lumberg/cpanel/ssl"
+    require "lumberg/cpanel/dns_lookup"
+    require "lumberg/cpanel/domain_lookup"
+    require "lumberg/cpanel/password"
+    require "lumberg/cpanel/file_manager"
+    require "lumberg/cpanel/zone_edit"
+    require "lumberg/cpanel/support"
+    require "lumberg/cpanel/random_data"
+    require "lumberg/cpanel/net"
+    require "lumberg/cpanel/mime"
+    require "lumberg/cpanel/redirect"
+    require "lumberg/cpanel/gpg"
+    require "lumberg/cpanel/locale"
+    require "lumberg/cpanel/mysql"
+    require "lumberg/cpanel/domain_keys"
+  end
+end

data/lib/lumberg/cpanel/addon_domain.rb

@@ -0,0 +1,50 @@
+module Lumberg
+  module Cpanel
+    class AddonDomain < Base
+      # Public: Delete an addon domain. This will also remove the corresponding
+      # subdomain and FTP account.
+      #
+      # options - Hash options for API call params (default: {}):
+      #   :domain    - String addon domain to be deleted.
+      #   :subdomain - String adddon domain's username followed by "_", then
+      #                the addon domain's main domain, e.g.,
+      #                "user_addon.com"
+      #
+      # Returns Hash API response.
+      def remove(options = {})
+        perform_request({
+          :api_function => "deladdondomain"
+        }.merge(options))
+      end
+
+      # Public: Add an addon domain with a coresponding subdomain.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :dir       - String path for addon domain docroot.
+      #  :newdomain - String domain to use for addon domain.
+      #  :subdomain - String subdomain / FTP username corresponding to new
+      #               addon domain, e.g., "user".
+      #
+      # Returns Hash API response.
+      def add(options = {})
+        perform_request({
+          :api_function => "addaddondomain"
+        }.merge(options))
+      end
+
+      # Public: Get a list of addon domains.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :regex - String regular expression to filter search results
+      #           (optional).
+      #
+      # Returns Hash API response.
+      def list(options={})
+        perform_request({
+          :api_function => "listaddondomains"
+        }.merge(options))
+      end
+    end
+  end
+end
+

data/lib/lumberg/cpanel/backups.rb

@@ -0,0 +1,16 @@
+module Lumberg
+  module Cpanel
+    class Backups < Base
+      # Public: Get a list backups.
+      #
+      # options - Hash options for API call params (default: {})
+      #
+      # Returns Hash API response.
+      def list(options = {})
+        perform_request({
+          :api_function => "listfullbackups"
+        }.merge(options))
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/base.rb

@@ -0,0 +1,56 @@
+module Lumberg
+  module Cpanel
+    class Base < Whm::Base
+      attr_accessor :api_username
+
+      # Public: Gets cPanel API module name based on class name. This method
+      # should be overriden in subclasses where the cPanel API module name
+      # and the class name don't match up.
+      #
+      # Returns String cPanel API module name.
+      def self.api_module
+        self.name.split("::").last
+      end
+
+      # Public: Initialize a new cPanel API interface.
+      #
+      # options - Hash options (default: {}):
+      #   :api_username - String username to set as the default account
+      #                   username for cPanel API calls (optional).
+      def initialize(options = {})
+        @api_username = options.delete(:api_username)
+
+        super options
+      end
+
+      # Public: Perform a cPanel API method call.
+      #
+      # options - Hash options for API call params (default: {}):
+      #   :api_function - String API function name to call.
+      #   :api_module   - String API module on which API function will be
+      #                   called (optional, default: self.class.api_module).
+      #   :response_key - String key used to select desired part of API
+      #                   response (optional, default: "cpanelresult").
+      #   :api_username - String account username for API call (optional,
+      #                   default: @api_username)
+      #   :api_version  - Integer cPanel API version to use (optional,
+      #                   default: 2)
+      #
+      # Returns Hash API response.
+      def perform_request(options = {})
+        options[:api_username] ||= api_username
+
+        api_module = options.delete(:api_module) || self.class.api_module
+        params = {
+          :response_key              => options.delete(:response_key) || "cpanelresult",
+          :cpanel_jsonapi_user       => options.delete(:api_username),
+          :cpanel_jsonapi_module     => api_module,
+          :cpanel_jsonapi_func       => options.delete(:api_function),
+          :cpanel_jsonapi_apiversion => options.delete(:api_version) || 2,
+        }.merge(options)
+
+        server.perform_request("cpanel", params)
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/box_trapper.rb

@@ -0,0 +1,18 @@
+module Lumberg
+  module Cpanel
+    class BoxTrapper < Base
+      # Public: Get list of email accounts and their BoxTrapper statuses.
+      #
+      # options - Hash options for API call params (default: {}):
+      #   :regex - String regular expression to filter search results
+      #            (optional).
+      #
+      # Returns Hash API response.
+      def list(options = {})
+        perform_request({
+          :api_function => "accountmanagelist"
+        }.merge(options))
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/branding.rb

@@ -0,0 +1,89 @@
+module Lumberg
+  module Cpanel
+    class Branding < Base
+      # Public: Get list of branding packages.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :onlyshowyours - Return only packages that the user owns?
+      #                   String "1" or "0" (optional).
+      #  :showroot      - Only return system branding packages?
+      #                   String "1" or "0" (optional).
+      #  :skipglobal    - Only return customized branding packages?
+      #                   String "1" or "0" (optional).
+      #  :skiphidden    - Skip branding packages owned by the user?
+      #                   String "1" or "0" (optional).
+      #
+      # Returns Hash API response.
+      def list_pkgs(options = {})
+        perform_request({
+          :api_function => "showpkgs"
+        }.merge(options))
+      end
+
+      # Public: Get URL locations for specific sprites.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :img        - String branding object label for the image you want to
+      #                retrieve.
+      #  :imgtype    - String branding image type you want to retrieve, e.g.,
+      #                "icon" or "heading".
+      #  :method     - String specification for returned value options.
+      #                Acceptable values are: "only_filetype_gif",
+      #                "skip_filetype_gif", "snap_to_smallest_width", and
+      #                "scale_60percent".
+      #  :subtype    - String branding image subtype, e.g., "img", "bg",
+      #                "compleximg".
+      #  :image      - String parameter allows you to force appropriate
+      #                output by setting it to "heading" (optional).
+      #  :skipgroups - String parameter allows you to specify whether or not
+      #                to include "img" values that begin with "group_" in
+      #                the output. "1" indicates that you wish to skip "img"
+      #                values that begin with "group_" (optional).
+      #
+      # Returns Hash API response.
+      def list_sprites(options = {})
+        perform_request({
+          :api_function => "spritelist"
+        }.merge(options))
+      end
+
+      # Public: Retrieve a list of icons within the x3 interface.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :nvarglist - String parameter allows you to specify the order in
+      #               which you wish to have groups returned, separated by
+      #               pipes, e.g., "mail|files|domains|logs". This is the
+      #               last filter on the data and is stored in your
+      #               xmaingroupsorder NVDATA variable (optional).
+      #
+      # Returns Hash API response.
+      def list_icons(options = {})
+        perform_request({
+          :api_function => "applist"
+        }.merge(options))
+      end
+
+      # Public: Get list of branding object types.
+      #
+      # options - Hash options for API call params (default: {}):
+      #
+      # Returns Hash API response.
+      def list_object_types(options = {})
+        perform_request({
+          :api_function => "listobjecttypes"
+        }.merge(options))
+      end
+
+      # Public: Get list of branding image types.
+      #
+      # options - Hash options for API call params (default: {}):
+      #
+      # Returns Hash API response.
+      def list_image_types(options = {})
+        perform_request({
+          :api_function => "listimgtypes"
+        }.merge(options))
+      end
+    end
+  end
+end