registrar-client 0.1.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2011 by Anthony Eden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Readme.md

@@ -0,0 +1,70 @@
+# Registrar Client
+
+This library provides a common API for communicating with multiple registrars. This is necessary since different registrars support different TLDs and different add-on services.
+
+## Usage
+
+To construct a client, first require both the generic API interface as well as a specific provider. Construct the provider and pass it to the client interface:
+
+    require 'registrar'
+    require 'registrar/provider/enom'
+
+    # set url, username and password to Enom API endpoint, username and password respectively
+    provider = Registrar::Provider::Enom.new(url, username, password)
+    client = Registrar::Client.new(provider)
+
+To split a domain into its TLD and its remaining part:
+
+    name = 'example.com'
+    client.parse(name)
+    => ['example','com']
+
+To check the availability of a domain name for registration:
+
+    client.available?(name)
+    => true
+  
+To register a domain name, first construct contact:
+
+    registrant = Registrar::Contact.new(
+      :first_name => 'Anthony',
+      :last_name => 'Eden',
+      :address_1 => '123 SW 1st Street',
+      :city => 'Anywhere',
+      :country => 'US',
+      :postal_code => '12121',
+      :phone => '444 555 1212',
+      :email => 'anthony@dnsimple.com'
+    )
+  
+Next pass the name plus the contact (as the registrant) to the purchase method:
+  
+    order = client.purchase(name, registrant)
+
+The resulting order may be complete...
+  
+    domains = order.domains if order.complete?
+    => [#<Registrar::Domain:0x10034d298>]
+    domain = domains[0]
+    => 
+    domain.name
+    => "example.com"
+
+Or the resulting order may be in process...
+
+    order.status unless order.complete?
+    => :open
+
+The status of the domain may be open in cases where a domain is not registered in real-time. Quite often country-code top level domains are not real-time and require additional out-of-band processing and documentation.
+
+If you need to pass in additional purchase options:
+
+    purchase_options = Registrar::PurchaseOptions.new
+    purchase_options.name_servers << Registrar::NameServer.new('ns1.example.com')
+    purchase_options.name_servers << Registrar::NameServer.new('ns2.example.com')
+    purchase_options.extended_attributes << Registrar::ExtendedAttribute.new('name', 'value')
+    purchase_options.number_of_years = 2
+
+    order = client.purchase(name, registrant, purchase_options)
+    domain = order.domain
+    => #<Registrar::Domain:"example.com">

data/Spec.md

@@ -0,0 +1,55 @@
+
+
+
+
+
+
+
+
+
+  
+
+  domain.name_servers
+  => [#<Registrar::NameServer:"ns1.example.com">, #<Registrar::Domain:"ns2.example.com">]
+
+To find an already purchased domain by its name so you can get more details:
+
+  domain = client.find('example.com')
+  => #<Registrar::Domain:"example.com">
+
+To transfer a domain
+
+  transfer_order = client.transfer(name, registrant)
+
+Or, with purchase options:
+
+  transfer_options = Registrar::TransferOptions.new
+  purchase_options.name_servers << Registrar::NameServer.new('ns1.example.com')
+  purchase_options.name_servers << Registrar::NameServer.new('ns2.example.com')
+  purchase_options.extended_attributes << Registrar::ExtendedAttribute.new('name', 'value')
+  transfer_order = client.transfer(name, registrant, transfer_options)
+
+To renew a domain:
+
+  domain.expires_on
+  => '2011-03-04'
+  domain.renew
+  => true
+  domain.expires_on
+  => '2012-03-04'
+
+To delete a registration (this will not refund):
+
+  ip_address = '1.2.3.4'
+  domain.delete(ip_address)
+  => true
+
+To get a list of supported TLDs along with properties:
+
+  tld = client.tlds.first
+  tld.name
+  => "com"
+  tld.max_years
+  => 10
+ 
+  

data/examples/enom.example.yml

@@ -0,0 +1,4 @@
+url: http://resellertest.enom.com/interface.asp
+username: your_username
+password: your_password
+

data/examples/purchase_com.rb

@@ -0,0 +1,7 @@
+require 'registrar'
+require 'registrar/provider/enom'
+config = YAML.load_file('examples/enom.yml')
+provider = Registrar::Provider::Enom.new(config['url'], config['username'], config['password'])
+contact = Registrar::Contact.new(:first_name => "John", :last_name => "Doe")
+name = "test-domain-#{Time.now.to_i}-#{rand(10000)}.com"
+order = provider.purchase(name, contact)

data/lib/registrar-client.rb

@@ -0,0 +1 @@
+require 'registrar'

data/lib/registrar.rb

@@ -0,0 +1,14 @@
+require 'httparty'
+
+module Registrar
+  # Error indicating that a registrar provider is required but none was 
+  # available.
+  class ProviderRequiredError < RuntimeError
+  end
+
+  # Base error for any errors encountered while communicating with a registrar.
+  class RegistrarError < RuntimeError
+  end
+end
+
+require 'registrar/client'

data/lib/registrar/client.rb

@@ -0,0 +1,224 @@
+require 'registrar/contact'
+require 'registrar/domain'
+require 'registrar/purchase_options'
+require 'registrar/renewal_options'
+require 'registrar/extended_attribute_descriptor'
+require 'registrar/extended_attribute_option_descriptor'
+require 'registrar/extended_attribute'
+require 'registrar/name_server'
+require 'registrar/order'
+
+module Registrar #:nodoc:
+  # This class provides a generic client interface for accessing domain
+  # registrars as a domain reseller. The interface provides methods for 
+  # checking domain availability, registering domain names and finding
+  # details on domains that are already registered.
+  #
+  # For examples of how to use this interface please see README.textile.
+  class Client
+    attr_reader :provider
+
+    # Initialize the client with an provider.
+    #
+    # adapter - The provider instance.
+    def initialize(provider)
+      @provider = provider 
+    end
+
+    # Parse a domain name into it's top-level domain part and its remaining
+    # parts.
+    #
+    # name - The fully-qualified domain name to parse
+    #
+    # Returns an array with two elements. The first element is a string with
+    # all parts of the domain minus the TLD. The last element is the TLD
+    # string.
+    def parse(name)
+      name = name.downcase
+      parse_cache[name] ||= provider.parse(name)
+    end
+
+    def parse_cache
+      @parse_cache ||= {}
+    end
+    private :parse_cache
+
+    # Check for the availability of a domain.
+    #
+    # name - The fully-qualified domain name to check.
+    #
+    # Returns true if the name is available.
+    def available?(name)
+      provider.available?(name.downcase)
+    end
+
+    # Find a domain and return an object representing that domain.
+    # If the domain is not registered or is registered with another reseller then
+    # this method will return nil.
+    #
+    # name - The fully-qualified domain name.
+    #
+    # Returns a Registrar::Domain object.
+    def find(name)
+      provider.find(name.downcase)
+    end
+    alias :find_domain :find
+
+    # Get a set of extended attribute descriptor objects. This set can be
+    # used to determine what extended registry attributes must be collected
+    # for the given domain.
+    #
+    # name - The fully-qualified domain name.
+    # 
+    # Returns an array of Registrar::ExtendedAttribute objects.
+    def extended_attributes(name)
+      provider.extended_attributes(name)
+    end
+
+    # Purchase a domain name for the given registrant.
+    #
+    # name - The fully-qualified domain name to purchase.
+    # registrant - A complete Registrar::Contact instance.
+    # registration_options - Optional Registrar::RegistrationOptions instance.
+    #
+    # Returns a Registrar::Order
+    def purchase(name, registrant, registration_options=nil)
+      provider.purchase(name.downcase, registrant, registration_options)
+    end
+
+    # Get the order identified by the given ID
+    #
+    # id - The order ID
+    # 
+    # Returns a Registrar::Order
+    def order(id)
+      provider.order(id)
+    end
+
+    # Get the most recent order for the given name
+    # 
+    # name - The fully-qualified domain name
+    #
+    # Returns a Registrar::Order instance
+    def order_for_domain(name)
+      provider.order_for_domain(name)
+    end
+
+    # Renew a domain name.
+    #
+    # name - The fully-qualified domain name to renew.
+    # renewal_options - Optional Registrar::RenewalOptions instance.
+    #
+    # Returns a Registrar::Order
+    def renew(name, renewal_options=nil)
+      provider.renew(name.downcase, renewal_options)
+    end
+
+    # Return true if the domain is set up for auto renewal
+    #
+    # name - The fully-qualified domain name
+    #
+    # Returns true if the domain should be auto renewed by the registrar
+    def auto_renew?(name)
+      provider.auto_renew?(name)
+    end
+
+    # Enable auto-renewal for a domain
+    #
+    # name - The name to auto renew
+    #
+    # Returns true of auto-renewal was enabled
+    def enable_auto_renewal(name)
+      provider.enable_auto_renewal(name) 
+    end
+    alias :enable_auto_renew :enable_auto_renewal
+
+    # Disable auto-renewal for a domain
+    #
+    # name - The name that has auto renewal enabled
+    #
+    # Returns true if the auto-renewal was disabled
+    def disable_auto_renewal(name)
+      provider.disable_auto_renewal(name) 
+    end
+    alias :disable_auto_renew :disable_auto_renewal
+
+    # List name servers for a domain. 
+    #
+    # name - The fully-qualified domain name.
+    #
+    # Returns a list of name servers attached to this domain
+    def name_servers(name)
+      provider.name_servers(name.downcase)
+    end
+    alias :nameservers :name_servers
+
+    # Set the name servers for a given name.
+    #
+    # name - The fully-qualified domain name.
+    # name_servers - A set of name server names as strings.
+    #
+    # Returns the list of name servers
+    def set_name_servers(name, name_servers=[])
+      provider.set_name_servers(name, name_servers)
+    end
+
+    # Find a name server by name.
+    #
+    # name - The name server name
+    #
+    # Returns a Registrar::NameServer instance
+    def find_name_server(name)
+      provider.find_name_server(name)
+    end
+
+    # Registers a name server with various registries
+    #
+    # name_server - The NameServer to register, including IP address
+    def register_name_server(name_server)
+      provider.register_name_server(name_server)
+    end
+
+    # Return the minimum number of years required to register a domain.
+    #
+    # tld - The TLD.
+    #
+    # Returns the minimum number of years required for registration.
+    def minimum_number_of_years(tld)
+      provider.minimum_number_of_years(tld.downcase)
+    end
+
+    # Return the retail transfer price for the given TLD.
+    #
+    # tld - The TLD.
+    #
+    # Returns the transfer price.
+    def tld_retail_transfer_price(tld)
+      provider.tld_retail_transfer_price(tld)
+    end
+
+    def contacts(name)
+      provider.contacts(name)
+    end
+
+    def update_registrant(name, contact)
+      provider.update_registrant(name, contact)
+    end
+
+    def update_contacts(name, contact)
+      provider.update_contacts(name, contact)
+    end
+
+    def update_technical_contact(name, contact)
+      provider.update_technical_contact(name, contact)
+    end
+
+    def update_administrative_contact(name, contact)
+      provider.update_administrative_contact(name, contact)
+    end
+
+    def update_aux_billing_contact(name, contact)
+      provider.update_aux_billing_contact(name, contact)
+    end
+  end
+end

data/lib/registrar/contact.rb

@@ -0,0 +1,31 @@
+module Registrar
+  class Contact
+    attr_accessor :identifier
+    attr_accessor :first_name
+    attr_accessor :last_name
+    attr_accessor :address_1
+    attr_accessor :address_2
+    attr_accessor :city
+    attr_accessor :state_province
+    attr_accessor :state_province_choice
+    attr_accessor :country
+    attr_accessor :postal_code
+    attr_accessor :phone
+    attr_accessor :phone_ext
+    attr_accessor :fax
+    attr_accessor :email
+    attr_accessor :organization_name
+    attr_accessor :job_title
+    
+    # Create a new contact optionally providing a Hash with name/value pairs
+    # representing one or more of the contact attributes.
+    def initialize(attributes={})
+      attributes.each do |k, v|
+        m = "#{k}="
+        if respond_to?(m)
+          send(m, v)
+        end
+      end
+    end
+  end
+end

data/lib/registrar/domain.rb

@@ -0,0 +1,26 @@
+module Registrar
+  class Domain
+    attr_reader :name
+
+    attr_accessor :registrant
+    attr_accessor :order
+
+    attr_accessor :expiration
+    attr_accessor :registration_status
+
+    attr_accessor :lockable
+    attr_accessor :real_time
+
+    def initialize(name)
+      @name = name
+    end
+
+    def lockable?
+      !!lockable
+    end
+
+    def real_time?
+      !!real_time
+    end
+  end
+end