whmcs-ruby 0.0.1

data/README.markdown

@@ -0,0 +1,29 @@
+# whmcs-ruby
+
+whmcs-ruby provides Ruby bindings for the [WHMCS API](http://wiki.whmcs.com/API:Functions).
+
+
+## Usage
+
+    require 'whmcs'
+
+    WHMCS.configure do |config|
+      config.api_url      = 'http://example.com/includes/api.php'
+      config.api_username = 'someusername'
+      config.api_password = 'c4ca4238a0b923820dcc509a6f75849b' # md5 hash
+    end
+
+    WHMCS::Client.get_clients_details(:clientid => '1')
+
+See the [documentation](http://dotblock.github.com/whmcs-ruby/) for more
+details.
+
+
+## Installation
+
+    gem install whmcs-ruby
+
+
+## Copyright
+
+Copyright (c) 2011 DotBlock.com, see LICENSE in this repo for details.

data/Rakefile

@@ -0,0 +1,31 @@
+$:.unshift 'lib'
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test' << '.'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/whmcs.rb -I ./lib"
+end
+
+require 'sdoc_helpers'
+desc "Push a new version to Gemcutter"
+task :publish do
+  require 'whmcs/version'
+
+  ver = WHMCS::Version
+
+  sh "gem build whmcs-ruby.gemspec"
+  sh "gem push whmcs-ruby-#{ver}.gem"
+  sh "git tag -a -m 'whmcs-ruby v#{ver}' v#{ver}"
+  sh "git push origin v#{ver}"
+  sh "git push origin master"
+  sh "git clean -fd"
+  sh "rake pages"
+end

data/lib/whmcs.rb

@@ -0,0 +1,30 @@
+module WHMCS
+  autoload :Version, "whmcs/version"
+  autoload :Config,  "whmcs/config"
+  autoload :Base,    "whmcs/base"
+  autoload :Client,  "whmcs/client"
+  autoload :Invoice, "whmcs/invoice"
+  autoload :Misc,    "whmcs/misc"
+  autoload :Module,  "whmcs/module"
+  autoload :Order,   "whmcs/order"
+  autoload :Quote,   "whmcs/quote"
+  autoload :Ticket,  "whmcs/ticket"
+
+  class << self
+    attr_accessor :config
+  end
+
+  self.config ||= Config.new
+
+  # Pass a block to configure the WHMCS API
+  #
+  #   WHMCS.configure do |config|
+  #     config.api_username = 'apiuser'
+  #     config.api_password = 'c4ca4238a0b923820dcc509a6f75849b'
+  #     config.api_url      = 'http://example.com/includes/api.php
+  #   end
+  def self.configure
+    yield config
+    config
+  end
+end

data/lib/whmcs/base.rb

@@ -0,0 +1,69 @@
+require 'net/http'
+require 'net/https'
+require 'crack'
+
+module WHMCS
+  # WHMCS::Base is the main class used to subclass WHMCS API resources
+  class Base
+
+    # Sends an API request to the WHMCS API
+    #
+    # Parameters:
+    # * <tt>:action</tt> - The API action to perform
+    #
+    # All other paramters are passed along as HTTP POST variables
+    def self.send_request(params = {})
+      if params[:action].blank?
+        raise "No API action set"
+      end
+
+      params.merge!(
+        :username => WHMCS.config.api_username,
+        :password => WHMCS.config.api_password
+      )
+
+      url = URI.parse(WHMCS.config.api_url)
+
+      http = Net::HTTP.new(url.host, url.port)
+
+      if url.port == 443
+        http.use_ssl = true
+      end
+
+      req = Net::HTTP::Post.new(url.path)
+      req.set_form_data(params)
+
+      res = http.start { |http| http.request(req) }
+      parse_response(res.body)
+    end
+
+    # Converts the API response to a Hash
+    def self.parse_response(raw)
+      return {} if raw.to_s.blank?
+
+      if raw.match(/xml version/)
+        Crack::XML.parse(raw)
+      else
+        Hash[raw.split(';').map { |line| line.split('=') }]
+      end
+    end
+  end
+end
+
+# Fix Net::HTTP so we dont get
+# warning: peer certificate won't be verified in this SSL session
+#
+# See:
+#
+# http://www.5dollarwhitebox.org/drupal/node/64
+module Net #:nodoc:all
+  class HTTP
+    alias_method :old_initialize, :initialize
+
+    def initialize(*args)
+      old_initialize(*args)
+      @ssl_context = OpenSSL::SSL::SSLContext.new
+      @ssl_context.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    end
+  end
+end

data/lib/whmcs/client.rb

@@ -0,0 +1,326 @@
+module WHMCS
+  # WHMCS::Client is the class for managing clients
+  class Client < Base
+
+    # Create a new client
+    #
+    # Parameters:
+    #
+    # * <tt>:firstname</tt>
+    # * <tt>:lastname</tt>
+    # * <tt>:companyname</tt> - optional
+    # * <tt>:email</tt>
+    # * <tt>:address1</tt>
+    # * <tt>:address2</tt> - optional
+    # * <tt>:city</tt>
+    # * <tt>:state</tt>
+    # * <tt>:postcode</tt>
+    # * <tt>:country</tt> - two letter ISO country code
+    # * <tt>:phonenumber</tt>
+    # * <tt>:password2</tt> - password for the new user account
+    # * <tt>:currency</tt> - the ID of the currency to set the user to
+    # * <tt>:groupid</tt> - used to assign the client to a client group
+    # * <tt>:notes</tt>
+    # * <tt>:cctype</tt> - Visa, Mastercard, etc...
+    # * <tt>:cardnum</tt>
+    # * <tt>:expdate</tt> - in the format MMYY
+    # * <tt>:startdate</tt>
+    # * <tt>:issuenumber</tt>
+    # * <tt>:customfields</tt> - a base64 encoded serialized array of custom field values
+    # * <tt>:noemail</tt> - pass as true to surpress the client signup welcome email sending
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Add_Client
+    def self.add_client(params = {})
+      params.merge!(:action => 'addclient')
+      send_request(params)
+    end
+
+    # Update a client's info
+    #
+    # Parameters:
+    #
+    # * <tt>:firstname</tt>
+    # * <tt>:lastname</tt>
+    # * <tt>:companyname</tt>
+    # * <tt>:email</tt>
+    # * <tt>:address1</tt>
+    # * <tt>:address2</tt>
+    # * <tt>:city</tt>
+    # * <tt>:state</tt>
+    # * <tt>:postcode</tt>
+    # * <tt>:country</tt> - two letter ISO country code
+    # * <tt>:phonenumber</tt>
+    # * <tt>:password2</tt>
+    # * <tt>:credit</tt> - credit balance
+    # * <tt>:taxexempt</tt> - true to enable
+    # * <tt>:notes</tt>
+    # * <tt>:cardtype</tt> - visa, mastercard, etc...
+    # * <tt>:cardnum</tt> - cc number
+    # * <tt>:expdate</tt> - cc expiry date
+    # * <tt>:startdate</tt> - cc start date
+    # * <tt>:issuenumber</tt> - cc issue number
+    # * <tt>:language</tt> - default language
+    # * <tt>:status</tt> - active or inactive
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Update_Client
+    def self.update_client(params = {})
+      params.merge!(:action => 'updateclient')
+      send_request(params)
+    end
+
+    # Delete a client
+    #
+    # Parameters:
+    #
+    # * <tt>:clientid</tt> - ID Number of the client to delete
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Delete_Client
+    def self.delete_client(params = {})
+      params.merge!(:action => 'deleteclient')
+      send_request(params)
+    end
+
+    # Get multiple clients
+    #
+    # Parameters:
+    #
+    # * <tt>:limitstart</tt> - Record to start at (default = 0)
+    # * <tt>:limitnum</tt> - Number of records to return (default = 25)
+    # * <tt>:search</tt> - Can be passed to filter for clients with a name/email matching the term entered
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Clients
+    def self.get_clients(params = {})
+      params.merge!(:action => 'getclients')
+      send_request(params)
+    end
+
+    # Get a client's info
+    #
+    # Parameters:
+    #
+    # * <tt>:clientid</tt> - the id number of the client
+    # * <tt>:email</tt> - the email address of the client
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Clients_Details
+    def self.get_clients_details(params = {})
+      params.merge!(:action => 'getclientsdetails')
+      send_request(params)
+    end
+
+    # Get a hash of a client's password
+    #
+    # Parameters:
+    #
+    # * <tt>:userid</tt> - should contain the user id of the client you wish to get the password for
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Clients_Password
+    def self.get_clients_password(params = {})
+      params.merge!(:action => 'getclientpassword')
+      send_request(params)
+    end
+
+    # Add a client contact
+    #
+    # Parameters:
+    #
+    # * <tt>:clientid</tt> - the client ID to add the contact to
+    # * <tt>:firstname</tt>
+    # * <tt>:lastname</tt>
+    # * <tt>:companyname</tt>
+    # * <tt>:email</tt>
+    # * <tt>:address1</tt>
+    # * <tt>:address2</tt>
+    # * <tt>:city</tt>
+    # * <tt>:state</tt>
+    # * <tt>:postcode</tt>
+    # * <tt>:country</tt> - two letter ISO country code
+    # * <tt>:phonenumber</tt>
+    # * <tt>:password2</tt> - if creating a sub-account
+    # * <tt>:permissions</tt> - can specify sub-account permissions eg manageproducts,managedomains
+    # * <tt>:generalemails</tt> - set true to receive general email types
+    # * <tt>:productemails</tt> - set true to receive product related emails
+    # * <tt>:domainemails</tt> - set true to receive domain related emails
+    # * <tt>:invoiceemails</tt> - set true to receive billing related emails
+    # * <tt>:supportemails</tt> - set true to receive support ticket related emails
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Add_Contact
+    def self.add_contact(params = {})
+      params.merge!(:action => 'addcontact')
+      send_request(params)
+    end
+
+    # Get client's contacts
+    #
+    # Parameters:
+    #
+    # * <tt>:limitstart</tt> - Record to start at (default = 0)
+    # * <tt>:limitnum</tt> - Number of records to return (default = 25)
+    # * <tt>:userid</tt>
+    # * <tt>:firstname</tt>
+    # * <tt>:lastname</tt>
+    # * <tt>:companyname</tt>
+    # * <tt>:email</tt>
+    # * <tt>:address1</tt>
+    # * <tt>:address2</tt>
+    # * <tt>:city</tt>
+    # * <tt>:state</tt>
+    # * <tt>:postcode</tt>
+    # * <tt>:country</tt>
+    # * <tt>:phonenumber</tt>
+    # * <tt>:subaccount</tt> - true/false
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Contacts
+    def self.get_contacts(params = {})
+      params.merge!(:action => 'getcontacts')
+      send_request(params)
+    end
+
+    # Update a client's contact
+    #
+    # Parameters:
+    #
+    # * <tt>:contactid</tt> - The ID of the contact to delete
+    # * <tt>:generalemails</tt> - set to true to receive general emails
+    # * <tt>:productemails</tt> - set to true to receive product emails
+    # * <tt>:domainemails</tt> - set to true to receive domain emails
+    # * <tt>:invoiceemails</tt> - set to true to receive invoice emails
+    # * <tt>:supportemails</tt> - set to true to receive support emails
+    # * <tt>:firstname</tt> - change the firstname
+    # * <tt>:lastname</tt> - change the lastname
+    # * <tt>:companyname</tt> - change the companyname
+    # * <tt>:email</tt> - change the email address
+    # * <tt>:address1</tt> - change address1
+    # * <tt>:address2</tt> - change address2
+    # * <tt>:city</tt> - change city
+    # * <tt>:state</tt> - change state
+    # * <tt>:postcode</tt> - change postcode
+    # * <tt>:country</tt> - change country
+    # * <tt>:phonenumber</tt> - change phonenumber
+    # * <tt>:subaccount</tt> - enable subaccount
+    # * <tt>:password</tt> - change the password
+    # * <tt>:permissions</tt> - set permissions eg manageproducts,managedomains
+    #
+    # Only send fields you wish to update
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Update_Contact
+    def self.update_contact(params = {})
+      params.merge!(:action => 'updatecontact')
+      send_request(params)
+    end
+
+    # Delete a client's contact
+    #
+    # Parameters:
+    #
+    # * <tt>:contactid</tt> - The ID of the contact to delete
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Delete_Contact
+    def self.delete_contact(params = {})
+      params.merge!(:action => 'deletecontact')
+      send_request(params)
+    end
+
+    # Get client's products
+    #
+    # Parameters:
+    #
+    # * <tt>:clientid</tt> - the ID of the client to retrieve products for
+    # * <tt>:serviceid</tt> - the ID of the service to retrieve details for
+    # * <tt>:domain</tt> - the domain of the service to retrieve details for
+    # * <tt>:pid</tt> - the product ID of the services to retrieve products for
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Clients_Products
+    def self.get_clients_products(params = {})
+      params.merge!(:action => 'getclientsproducts')
+      send_request(params)
+    end
+
+    # Update client's product
+    #
+    # Parameters:
+    #
+    # * <tt>:serviceid</tt> - the ID of the service to be updated
+    # * <tt>:pid</tt>
+    # * <tt>:serverid</tt>
+    # * <tt>:regdate</tt> - Format: YYYY-MM-DD
+    # * <tt>:nextduedate</tt> - Format: YYYY-MM-DD
+    # * <tt>:domain</tt>
+    # * <tt>:firstpaymentamount</tt>
+    # * <tt>:recurringamount</tt>
+    # * <tt>:billingcycle</tt>
+    # * <tt>:paymentmethod</tt>
+    # * <tt>:status</tt>
+    # * <tt>:serviceusername</tt>
+    # * <tt>:servicepassword</tt>
+    # * <tt>:subscriptionid</tt>
+    # * <tt>:promoid</tt>
+    # * <tt>:overideautosuspend</tt> - on/off
+    # * <tt>:overidesuspenduntil</tt> - Format: YYYY-MM-DD
+    # * <tt>:ns1</tt>
+    # * <tt>:ns2</tt>
+    # * <tt>:dedicatedip</tt>
+    # * <tt>:assignedips</tt>
+    # * <tt>:notes</tt>
+    # * <tt>:autorecalc</tt> - pass true to auto set price based on product ID or billing cycle change
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Update_Client_Product
+    def self.update_client_product(params = {})
+      params.merge!(:action => 'updateclientproduct')
+      send_request(params)
+    end
+
+    # Validate client login info
+    #
+    # Parameters:
+    #
+    # * <tt>:email</tt> - the email address of the user trying to login
+    # * <tt>:password2</tt> - the password they supply for authentication
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Validate_Login
+    def self.validate_login(params = {})
+      params.merge!(:action => 'validatelogin')
+      send_request(params)
+    end
+
+    # Send email to client
+    #
+    # Parameters:
+    #
+    # * <tt>:messagename</tt> - unique name of the email template to send from WHMCS
+    # * <tt>:id</tt> - related ID number to send message for
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Send_Email
+    def self.send_email(params = {})
+      params.merge!(:action => 'sendemail')
+      send_request(params)
+    end
+  end
+end