whmcs-ruby 0.0.1

data/lib/whmcs/config.rb

@@ -0,0 +1,20 @@
+module WHMCS
+  # WHMCS::Config stores configuration data for connecting to the WHMCS API
+  class Config
+    # The WHMCS API username
+    attr_accessor :api_username
+
+    # The WHMCS API password
+    attr_accessor :api_password
+
+    # The WHMCS API URL
+    attr_accessor :api_url
+
+    # Create a new config object
+    def initialize
+      @api_username = 'example_api_user'
+      @api_password = 'example_api_pass'
+      @api_url      = 'http://example.com/api.php'
+    end
+  end
+end

data/lib/whmcs/invoice.rb

@@ -0,0 +1,194 @@
+module WHMCS
+  # WHMCS::Invoice is the class for managing invoices
+  class Invoice < Base
+
+    # Get invoices
+    #
+    # Parameters:
+    #
+    # * <tt>:userid</tt> - the client ID to retrieve invoices for
+    # * <tt>:status</tt> - the status to filter for, Paid, Unpaid, Cancelled, etc...
+    # * <tt>:limitstart</tt> - the offset number to start at when returning matches (optional, default 0)
+    # * <tt>:limitnum</tt> - the number of records to return (optional, default 25)
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Invoices
+    def self.get_invoices(params = {})
+      params.merge!(:action => 'getinvoices')
+      send_request(params)
+    end
+
+    # Get an invoice
+    #
+    # Parameters:
+    #
+    # * <tt>:invoiceid</tt> - should be the invoice id you wish to retrieve
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Invoice
+    def self.get_invoice(params = {})
+      params.merge!(:action => 'getinvoice')
+      send_request(params)
+    end
+
+    # Create a new invoice
+    #
+    # Parameters:
+    #
+    # * <tt>:userid</tt> - should contain the user id of the client you wish to create the invoice for
+    # * <tt>:date</tt> - the date the invoice is created in the format YYYYMMDD
+    # * <tt>:duedate</tt> - the date the invoice is due in the format YYYYMMDD
+    # * <tt>:taxrate</tt> - the rate of tax that should be charged
+    # * <tt>:paymentmethod</tt> - the payment method for the invoice eg. banktransfer
+    # * <tt>:notes</tt> - any additional notes the invoice should display to the customer
+    # * <tt>:sendinvoice</tt> - set to true to send the "Invoice Created" email to the customer
+    #
+    # * <tt>:itemdescription1</tt> - item 1 description
+    # * <tt>:itemamount1</tt> - item 1 amount
+    # * <tt>:itemtaxed1</tt> - set to true if item 1 should be taxed
+    # * <tt>:itemdescription2</tt> - item 2 description
+    # * <tt>:itemamount2</tt> - item 2 amount
+    # * <tt>:itemtaxed2</tt> - set to true if item 2 should be taxed
+    #
+    # etc...
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Create_Invoice
+    def self.create_invoice(params = {})
+      params.merge!(:action => 'createinvoice')
+      send_request(params)
+    end
+
+    # Update an existing invoice
+    #
+    # Parameters:
+    #
+    # * <tt>:invoiceid</tt> - The ID of the invoice to update
+    # * <tt>:itemdescription</tt> - Array of existing line item descriptions to update. Line ID from database needed
+    # * <tt>:itemamount</tt> - Array of existing line item amounts to update
+    # * <tt>:itemtaxed</tt> - Array of existing line items taxed or not
+    # * <tt>:newitemdescription</tt> - Array of new line item descriptipons to add
+    # * <tt>:newitemamount</tt> - Array of new line item amounts
+    # * <tt>:newitemtaxed</tt> - Array of new line items taxed or not
+    # * <tt>:date</tt> - date of invoice format yyyymmdd
+    # * <tt>:duedate</tt> - duedate of invoice format yyyymmdd
+    # * <tt>:datepaid</tt> - date invoice was paid format yyyymmdd
+    # * <tt>:status</tt> - status of invoice. Unpaid, Paid, Cancelled, Collection, Refunded
+    # * <tt>:paymentmethod</tt> - payment method of invoice eg paypal, banktransfer
+    #
+    # Other than invoiceid, no other fields are required
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Update_Invoice
+    def self.update_invoice(params = {})
+      params.merge!(:action => 'updateinvoice')
+      send_request(params)
+    end
+
+    # Add an invoice payment
+    #
+    # Parameters:
+    #
+    # * <tt>:invoiceid</tt> - should contact the ID number of the invoice to add the payment to
+    # * <tt>:transid</tt> - should contain the transaction number for the payment
+    # * <tt>:amount</tt> - should contact the amount paid, can be left blank to take full amount of invoice
+    # * <tt>:fees</tt> - optional, if set defines how much fees were involved in the transaction
+    # * <tt>:gateway</tt> - should contain the gateway used in system name format, eg. paypal, authorize, etc...
+    # * <tt>:noemail</tt> - set to true to not send an email if the payment marks the invoice paid
+    # * <tt>:date</tt> - optional, if set defines the date the payment was made
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Add_Invoice_Payment
+    def self.add_invoice_payment(params = {})
+      params.merge!(:action => 'addinvoicepayment')
+      send_request(params)
+    end
+
+    # Attempt to capture payment for an invoice
+    #
+    # Parameters:
+    #
+    # * <tt>:invoiceid</tt> - the ID of the invoice the capture is to be attempted for
+    # * <tt>:cvv</tt> - optionally can be used to pass the cards verification value in the payment request
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Capture_Payment
+    def self.capture_payment(params = {})
+      params.merge!(:action => 'capturepayment')
+      send_request(params)
+    end
+
+    # Add a new billable item
+    #
+    # Parameters:
+    #
+    # * <tt>:clientid</tt>
+    # * <tt>:description</tt>
+    # * <tt>:amount</tt>
+    # * <tt>:recur</tt> - frequency to recur - 1,2,3,etc...
+    # * <tt>:recurcycle</tt> - Days, Weeks, Months or Years
+    # * <tt>:recurfor</tt> - number of times to repeat
+    # * <tt>:invoiceaction</tt> - noinvoice, nextcron, nextinvoice, duedate, recur
+    # * <tt>:duedate</tt> - date the invoice should be due
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Add_Billable_Item
+    def self.add_billable_item(params = {})
+      params.merge!(:action => 'addbillableitem')
+      send_request(params)
+    end
+
+    # Add a credit to client's account
+    #
+    # Parameters:
+    #
+    # * <tt>:clientid</tt> - the ID of the client the credit is to be added to
+    # * <tt>:description</tt> - reason for credit being added (stored in admin credit log)
+    # * <tt>:amount</tt> - the amount to be added
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Add_Credit
+    def self.add_credit(params = {})
+      params.merge!(:action => 'addcredit')
+      send_request(params)
+    end
+
+    # Add transaction
+    #
+    # Parameters:
+    #
+    # * <tt>:userid</tt> - Optional Add Transaction to a user
+    # * <tt>:invoiceid</tt> - Optional Add transaction to a particular invoice
+    # * <tt>:description</tt> - Description of the transaction
+    # * <tt>:amountin</tt> - amount to add to the account
+    # * <tt>:amountout</tt> - if an outgoing enter this
+    # * <tt>:fees</tt> - transaction fee you were charged
+    # * <tt>:paymentmethod</tt> - gateway used in WHMCS
+    # * <tt>:transid</tt> - Transaction ID you wish to assign
+    # * <tt>:date</tt> - date of transaction (same format as your WHMCS eg DD/MM/YYYY)
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Add_Transaction
+    def self.add_transaction(params = {})
+      send_request(params.merge(:action => 'addtransaction'))
+    end
+
+    # Get configured payment methods
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Payment_Methods
+    def self.get_payment_methods
+      send_request(:action => 'getpaymentmethods')
+    end
+  end
+end

data/lib/whmcs/misc.rb

@@ -0,0 +1,168 @@
+module WHMCS
+  # The WHMCS::Misc class contains miscelaneous WHMCS API functions
+  class Misc < Base
+
+    # Perform a whois lookup for a domain name
+    #
+    # Parameters:
+    #
+    # * <tt>:domain</tt> - the domain to check
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Domain_WHOIS
+    def self.domain_whois(params = {})
+      params.merge!(:action => 'domainwhois')
+      send_request(params)
+    end
+
+    # Get activity log
+    #
+    # Parameters:
+    #
+    # * <tt>:limitstart</tt> - Which User ID to start at (default = 0)
+    # * <tt>:limitnum</tt> - Limit by number (default = 25)
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Activity_Log
+    def self.get_activity_log(params = {})
+      params.merge!(:action => 'getactivitylog')
+      send_request(params)
+    end
+
+    # Get administrator details
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Admin_Details
+    def self.get_admin_details
+      send_request(:action => 'getadmindetails')
+    end
+
+    # Update administrator notes
+    #
+    # Parameters:
+    #
+    # * <tt>:notes</tt> - notes to enter
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Update_Admin_Notes
+    def self.update_admin_notes(params = {})
+      params.merge!(:action => 'updateadminnotes')
+      send_request(params)
+    end
+
+    # Get allowed currencies
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Currencies
+    def self.get_currencies
+      send_request(:action => 'getcurrencies')
+    end
+
+    # Get promotions
+    #
+    # Note: WHMCS has this listed under Misc as well as invoices. It's
+    # aliased here for consistancy with their API docs
+    #
+    # Parameters:
+    #
+    # * <tt>:code</tt> - the specific promotion code to return information for (optional)
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Promotions
+    def self.get_promotions(params = {})
+      Invoice.get_promotions(params)
+    end
+
+    # Get email templates
+    #
+    # Parameters:
+    #
+    # * <tt>:type</tt> - optional - from product,domain,support,general,invoice,affiliate
+    # * <tt>:language</tt> - optional - only required for additional languages
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Email_Templates
+    def self.get_email_templates(params = {})
+      params.merge!(:action => 'getemailtemplates')
+      send_request(params)
+    end
+
+    # Get todo items
+    #
+    # Parameters:
+    #
+    # * <tt>:status</tt> - optional - from New,Pending,In Progress,Completed,Postponed
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_To-Do_Items
+    def self.get_todo_items(params = {})
+      params.merge!(:action => 'gettodoitems')
+      send_request(params)
+    end
+
+    # Get configured todo item statuses
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_To-Do_Items_Statuses
+    def self.get_todo_item_statuses
+      send_request(:action => 'gettodoitemstatuses')
+    end
+
+    # Get staff online
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Staff_Online
+    def self.get_staff_online
+      send_request(:action => 'getstaffonline')
+    end
+
+    # Get stats
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Stats
+    def self.get_stats
+      send_request(:action => 'getstats')
+    end
+
+    # Encrypt a password with the WHMCS algorithm
+    #
+    # Parameters:
+    #
+    # * <tt>:password2</tt> - should contain the string you want encrypting
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Encrypt_Password
+    def self.encrypt_password(params = {})
+      params.merge!(:action => 'encryptpassword')
+      send_request(params)
+    end
+
+    # Decrypt a string with the WHMCS algorithm
+    #
+    # NOTE: This cannot be used to decrypt the clients password.
+    #
+    # Parameters:
+    #
+    # * <tt>:password2</tt> - should contain the string you want decrypting
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Decrypt_Password
+    def self.decrypt_password(params = {})
+      params.merge!(:action => 'decryptpassword')
+      send_request(params)
+    end
+  end
+end

data/lib/whmcs/module.rb

@@ -0,0 +1,62 @@
+module WHMCS
+  # WHMCS::Module is the class for working with hosting account modules
+  class Module < Base
+
+    # Run the module create command
+    #
+    # Parameters:
+    #
+    # * <tt>:accountid</tt> - the unique id number of the account in the tblhosting table
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Module_Create
+    def self.module_create(params = {})
+      params.merge!(:action => 'modulecreate')
+      send_request(params)
+    end
+
+    # Run the module suspend command
+    #
+    # Parameters:
+    #
+    # * <tt>:accountid</tt> - the unique id number of the account in the tblhosting table
+    # * <tt>:suspendreason</tt> - an explanation of why the suspension has been made shown to clients & staff
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Module_Suspend
+    def self.module_suspend(params = {})
+      params.merge!(:action => 'modulesuspend')
+      send_request(params)
+    end
+
+    # Run the module unsuspend command
+    #
+    # Parameters:
+    #
+    # * <tt>:accountid</tt> - the unique id number of the account in the tblhosting table
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Module_Unsuspend
+    def self.module_unsuspend(params = {})
+      params.merge!(:action => 'moduleunsuspend')
+      send_request(params)
+    end
+
+    # Run the module terminate command
+    #
+    # Parameters:
+    #
+    # * <tt>:accountid</tt> - the unique id number of the account in the tblhosting table
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Module_Terminate
+    def self.module_terminate(params = {})
+      params.merge!(:action => 'moduleterminate')
+      send_request(params)
+    end
+  end
+end

data/lib/whmcs/order.rb

@@ -0,0 +1,166 @@
+module WHMCS
+  # WHMCS::Order is the class for managing orders
+  class Order < Base
+
+    # Create a new order
+    #
+    # Parameters:
+    #
+    # * <tt>:clientid</tt> - client id for order
+    # * <tt>:pid</tt> - product id
+    # * <tt>:domain</tt> - domain name
+    # * <tt>:billingcycle</tt> - onetime, monthly, quarterly, semiannually, etc..
+    # * <tt>:addons</tt> - comma seperated list of addon ids
+    # * <tt>:customfields</tt> - a base64 encoded serialized array of custom field values
+    # * <tt>:configoptions</tt> - a base64 encoded serialized array of configurable product options
+    # * <tt>:domaintype</tt> - set for domain registration - register or transfer
+    # * <tt>:regperiod</tt> - 1,2,3,etc...
+    # * <tt>:dnsmanagement</tt> - true to enable
+    # * <tt>:emailforwarding - true to enable
+    # * <tt>:idprotection</tt> - true to enable
+    # * <tt>:eppcode</tt> - if transfer
+    # * <tt>:nameserver1</tt> - first nameserver (req for domain reg only)
+    # * <tt>:nameserver2</tt> - second nameserver
+    # * <tt>:nameserver3</tt> - third nameserver
+    # * <tt>:nameserver4</tt> - fourth nameserver
+    # * <tt>:paymentmethod</tt> - paypal, authorize, etc...
+    # * <tt>:promocode</tt> - pass coupon code to apply to the order (optional)
+    # * <tt>:affid</tt> - affiliate ID if you want to assign the order to an affiliate (optional)
+    # * <tt>:noinvoice</tt> - set true to not generate an invoice for this order
+    # * <tt>:noemail</tt> - set true to surpress the order confirmation email
+    # * <tt>:clientip</tt> - can be used to pass the customers IP (optional)
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Add_Order
+    def self.add_order(params = {})
+      params.merge!(:action => 'addorder')
+      send_request(params)
+    end
+
+    # Get orders
+    #
+    # Parameters:
+    #
+    # * <tt>:limitstart</tt> - The record number to start at (default = 0)
+    # * <tt>:limitnum</tt> - The number of order records to return (default = 25)
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Orders
+    def self.get_orders(params = {})
+      params.merge!(:action => 'getorders')
+      send_request(params)
+    end
+
+    # Get products
+    #
+    # Parameters:
+    #
+    # * <tt>:pid</tt> - can be used to just retrieve the details of a specific product ID
+    # * <tt>:gid</tt> - can be passed to just retrieve products in a specific group
+    # * <tt>:module</tt> - can be passed to just retrieve products assigned to a specific module
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Products
+    def self.get_products(params = {})
+      params.merge!(:action => 'getproducts')
+      send_request(params)
+    end
+
+    # Get promotions
+    #
+    # Parameters:
+    #
+    # * <tt>:code</tt> - the specific promotion code to return information for (optional)
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Promotions
+    def self.get_promotions(params = {})
+      params.merge!(:action => 'getpromotions')
+      send_request(params)
+    end
+
+    # Get order statuses
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Get_Order_Statuses
+    def self.get_order_statuses
+      params.merge!(:action => 'getorderstatuses')
+      send_request(params)
+    end
+
+    # Accept an order
+    #
+    # Parameters:
+    #
+    # * <tt>:orderid</tt> - the Order ID
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Accept_Order
+    def self.accept_order(params = {})
+      params.merge!(:action => 'acceptorder')
+      send_request(params)
+    end
+
+    # Place an order in pending
+    #
+    # Parameters:
+    #
+    # * <tt>:orderid</tt> - the Order ID
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Pending_Order
+    def self.pending_order(params = {})
+      params.merge!(:action => 'pendingorder')
+      send_request(params)
+    end
+
+    # Cancel an order
+    #
+    # Parameters:
+    #
+    # * <tt>:orderid</tt> - the Order ID
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Cancel_Order
+    def self.cancel_order(params = {})
+      params.merge!(:action => 'cancelorder')
+      send_request(params)
+    end
+
+    # Mark an order as fraud
+    #
+    # Parameters:
+    #
+    # * <tt>:orderid</tt> - the Order ID
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Fraud_Order
+    def self.fraud_order(params = {})
+      params.merge!(:action => 'fraudorder')
+      send_request(params)
+    end
+
+    # Delete an order
+    #
+    # Parameters:
+    #
+    # * <tt>:orderid</tt> - the Order ID
+    #
+    # See:
+    #
+    # http://wiki.whmcs.com/API:Delete_Order
+    def self.delete_order(params = {})
+      params.merge!(:action => 'deleteorder')
+      send_request(params)
+    end
+  end
+end