namecheap 0.2.0 → 0.3.1

data/README.md

@@ -1,86 +1,137 @@
-Overview
-========
+# Namecheap
 
-About this project
--------------
+`namecheap` is a Ruby wrapper for the [Namecheap XML API](https://www.namecheap.com/support/api/intro/). It supports the existing domains, DNS, nameserver, transfer, SSL, user, and domain privacy commands exposed by the gem.
 
-Namecheap is a ruby wrapper for the [Namecheap API](http://developer.namecheap.com/docs/doku.php?id=api-reference:index)
+Version 0.3.1 requires Ruby 3.3 or newer.
 
-The code was originally forked from https://github.com/hashrocket/namecheap
+## Installation
 
-At [Mindvalley](http://www.mindvalley.com) (the company I work for) we have something
-called 'HackdayFridays' where we spend the whole day hacking on an interesting
-project that may or may not be directly related to the business. It was enacted
-so that the tech and production team can unwind from what can be a monotonous
-work week, and hack on something more interesting.
+Add the gem to your bundle:
 
-One of the proposed projects was a 'big red button' where someone can just type
-in the domain name, push a big red button, and magically:
+```ruby
+gem "namecheap"
+```
 
-* the domain name is purchased
-* the DNS is pointed to our load balancer
-* a subversion repository is created (with users)
-* a template is committed to the repository with default pages
-* a project is created in webistrano
-* the initial setup and deployment is done
+Then run `bundle install`.
 
-Mostly everything is already automated except the domain name purchase and dns.
-We purchase most of our domains from Namecheap (and some from GoDaddy) and it was
-fortunate that Namecheap has an API. Unfortunately there didn't seem to be a gem
-that already existed.
+## API setup
 
-A search brought me to HashRocket's namecheap API wrapper. It didn't have any of
-the purchase API wrappers, but it was a good starting point (and allowed me to
-study how seasoned pros would approach API wrappers). So I forked, published a
-gem based on the fork, and hacked on it. And that's how it all began :)
+Enable API access in your Namecheap account and whitelist the public IPv4 address that will make requests. Sandbox and production use separate accounts and credentials.
 
-Usage
------
+The gem uses the sandbox endpoint unless `RACK_ENV` (or `Rails.env`) is `production`. Test requests against the sandbox before enabling production:
 
-In your initializers, configure Namecheap like so:
+```ruby
+Namecheap.configure do |config|
+  config.key = ENV.fetch("NAMECHEAP_API_KEY")
+  config.username = ENV.fetch("NAMECHEAP_USERNAME")
+  config.client_ip = ENV.fetch("NAMECHEAP_CLIENT_IP")
+end
+```
 
-    Namecheap.configure do |config|
-      config.key = 'apikey'
-      config.username = 'apiuser'
-      config.client_ip = '127.0.0.1'
-    end
+Applications can select the Namecheap environment independently of `RACK_ENV`
+or `Rails.env`. This is useful when a staging application runs in production
+mode but must continue using Namecheap's sandbox:
 
-Then you can do something like:
+```ruby
+Namecheap.configure do |config|
+  config.environment = "sandbox"
+end
+```
 
-    Namecheap.domains.get_list
+Set `environment` to either `"sandbox"` or `"production"`. Leave it unset, or
+set it to `nil`, to retain automatic Rails/Rack environment selection.
 
-Please see the Namecheap API documentation for more information
+Avoid committing API keys or account configuration to source control.
 
-License
--------
+## Usage
 
-Copyright (c) 2011 Tristan V. Gomez
+The resource methods mirror Namecheap command names:
 
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
+```ruby
+Namecheap.domains.get_list
+Namecheap.domains.check(["example.com", "example.net"])
+Namecheap.dns.get_hosts("example", "com")
+```
 
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
+Additional command parameters can be passed as a final hash:
 
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
+```ruby
+Namecheap.domains.get_list(page: 2, page_size: 50)
+```
 
+Namecheap returns XML responses. This version returns the `HTTParty::Response` directly so existing applications can inspect the parsed response, status, and headers.
 
-Credits
--------
+Configuration can also be loaded from an ERB-enabled YAML file. The selected top-level key must match `RACK_ENV`, or `development` when it is unset:
 
-Tristan V. Gomez: tristan dot gomez at gmail dot com
+```yaml
+development:
+  username: sandbox_user
+  key: <%= ENV.fetch("NAMECHEAP_API_KEY") %>
+  client_ip: 192.0.2.1
+  environment: sandbox
+```
 
-[Hashrocket](http://www.hashrocket.com/) from where the original code was forked from
+```ruby
+Namecheap::Config.load!("config/namecheap.yml")
+```
 
-[Mongoid](http://www.mongoid.org) from where the configuration code was modified from
+## Development
 
+Install dependencies and run the test and style checks:
 
-Plug!!
-------
+```shell
+mise exec -- bundle install
+mise exec -- bundle exec rake
+```
 
-Mindvalley is [hiring](http://www.mindvalley.com/careers) :)
+Build a local gem without publishing it:
+
+```shell
+mise exec -- bundle exec gem build namecheap.gemspec
+```
+
+### Manual release
+
+Releases from this legacy branch are intentionally manual. Start from a clean
+`legacy/0.3` checkout and confirm that `lib/namecheap/version.rb` and the dated
+changelog heading contain the same version. Then run:
+
+```shell
+mise exec -- bundle install
+mise exec -- bundle exec rake
+mise exec -- bundle exec gem build namecheap.gemspec
+mise exec -- ruby -rrubygems/package -e \
+  'spec = Gem::Package.new(ARGV.fetch(0)).spec; puts "#{spec.name} #{spec.version} (Ruby #{spec.required_ruby_version})"' \
+  namecheap-0.3.1.gem
+```
+
+Commit and push the finalized release changes before creating a signed,
+annotated tag for the exact release commit:
+
+```shell
+git tag -s v0.3.1 -m "Release 0.3.1"
+git push origin legacy/0.3
+git push origin v0.3.1
+```
+
+Publish the artifact to RubyGems manually. RubyGems may prompt for MFA:
+
+```shell
+mise exec -- gem push namecheap-0.3.1.gem
+```
+
+After RubyGems reports version 0.3.1 as published, create the corresponding
+GitHub Release:
+
+```shell
+gh release create v0.3.1 --verify-tag --generate-notes --title v0.3.1
+```
+
+Changing the version, building the gem, or pushing the branch does not publish
+a release.
+
+## License
+
+Copyright 2011 Tristan V. Gomez. This project is available under the GNU Lesser General Public License, version 3 or any later version. See [COPYING](COPYING).
+
+The original API wrapper was forked from Hashrocket's `namecheap` project.

data/lib/namecheap/api.rb

@@ -1,22 +1,75 @@
+require "active_support/core_ext/string/inflections"
+
 module Namecheap
   class Api
-    SANDBOX = 'https://api.sandbox.namecheap.com/xml.response'
-    PRODUCTION = 'https://api.namecheap.com/xml.response'
-    ENVIRONMENT = defined?(Rails) && Rails.respond_to?(:env) ? Rails.env : (ENV["RACK_ENV"] || 'development')
-    ENDPOINT = (ENVIRONMENT == 'production' ? PRODUCTION : SANDBOX)
-
-    def api_call(command, command_args)
-      args = init_args(command_args.merge :command => command)
-      query = ENDPOINT + '?' + args.to_param
-      HTTParty.get(query)
+    SANDBOX = "https://api.sandbox.namecheap.com/xml.response"
+    PRODUCTION = "https://api.namecheap.com/xml.response"
+    ENVIRONMENT = (defined?(Rails) && Rails.respond_to?(:env)) ? Rails.env.to_s : (ENV["RACK_ENV"] || "development")
+    ENDPOINT = (ENVIRONMENT == "production") ? PRODUCTION : SANDBOX
+
+    def get(command, options = {})
+      request "get", command, options
+    end
+
+    def post(command, options = {})
+      request "post", command, options
+    end
+
+    def put(command, options = {})
+      request "put", command, options
+    end
+
+    def delete(command, options = {})
+      request "delete", command, options
     end
 
-    def init_args(options = {})
-      args = {}
-      args['ApiUser'] = args['UserName'] = Namecheap.username
-      args['ApiKey'] = Namecheap.key
-      args['ClientIp'] = Namecheap.client_ip
-      args.merge options.camelize_keys!
+    def request(method, command, options = {})
+      command = "namecheap.#{command}"
+      options = init_args.merge(options).merge(command: command)
+      options.keys.each do |key|
+        options[key.to_s.camelize] = options.delete(key)
+      end
+
+      case method
+      when "get"
+        HTTParty.get(endpoint, query: options)
+      when "post"
+        HTTParty.post(endpoint, query: options)
+      when "put"
+        HTTParty.put(endpoint, query: options)
+      when "delete"
+        HTTParty.delete(endpoint, query: options)
+      end
+    end
+
+    def init_args
+      %w[username key client_ip].each do |key|
+        if Namecheap.config.public_send(key).nil?
+          raise Namecheap::Config::RequiredOptionMissing,
+            "Configuration parameter missing: #{key}, " \
+            "please add it to the Namecheap.configure block"
+        end
+      end
+
+      {
+        api_user: Namecheap.config.username,
+        user_name: Namecheap.config.username,
+        api_key: Namecheap.config.key,
+        client_ip: Namecheap.config.client_ip
+      }
+    end
+
+    private
+
+    def endpoint
+      case Namecheap.config.environment
+      when "sandbox"
+        SANDBOX
+      when "production"
+        PRODUCTION
+      else
+        ENDPOINT
+      end
     end
   end
-end
+end

data/lib/namecheap/config.rb

@@ -1,44 +1,26 @@
+require "erb"
+require "yaml"
+
 module Namecheap
   module Config
-    # Taken and modified from Mongoid config.rb
-
+    class RequiredOptionMissing < RuntimeError; end
     extend self
 
-    attr_accessor :settings, :defaults
-    @settings = {}
-    @defaults = {}
-
-    # Define a configuration option with a default.
-    #
-    # @example Define the option.
-    #   Config.option(:client_ip, :default => '127.0.0.1')
-    #
-    # @param [ Symbol ] name The name of the configuration option.
-    # @param [ Hash ] options Extras for the option.
-    #
-    # @option options [ Object ] :default The default value.
-    def option(name, options = {})
-      defaults[name] = settings[name] = options[:default]
-
-      class_eval <<-RUBY
-        def #{name}
-          settings[#{name.inspect}]
-        end
+    ENVIRONMENTS = %w[sandbox production].freeze
 
-        def #{name}=(value)
-          settings[#{name.inspect}] = value
-        end
+    attr_accessor :key, :username, :client_ip
+    attr_reader :environment
 
-        def #{name}?
-          #{name}
-        end
-      RUBY
+    def environment=(environment)
+      if environment.nil?
+        @environment = nil
+      elsif ENVIRONMENTS.include?(environment)
+        @environment = environment
+      else
+        raise ArgumentError, "environment must be sandbox or production"
+      end
     end
 
-    option :key, :default => 'apikey'
-    option :username, :default => 'apiuser'
-    option :client_ip, :default => '127.0.0.1'
-
     # Configure namecheap from a hash. This is usually called after parsing a
     # yaml config file such as mongoid.yml.
     #
@@ -60,19 +42,9 @@ module Namecheap
     #
     # @param [ String ] path The path to the file.
     def load!(path)
-      settings = YAML.load(ERB.new(File.new(path).read).result)[ENVIRONMENT]
-      if settings.present?
-        from_hash(settings)
-      end
+      contents = ERB.new(File.read(path)).result
+      settings = YAML.safe_load(contents, aliases: true)&.fetch(Namecheap::Api::ENVIRONMENT, nil)
+      from_hash(settings) if settings && !settings.empty?
     end
-
-    # Reset the configuration options to the defaults.
-    #
-    # @example Reset the configuration options.
-    #   config.reset
-    def reset
-      settings.replace(defaults)
-    end
-
   end
-end
+end

data/lib/namecheap/dns.rb

@@ -1,51 +1,56 @@
 module Namecheap
   class Dns < Api
+    # Sets domain to use Namecheap's default DNS servers.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.dns:setdefault
     def set_default(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.dns.setDefault', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.dns.setDefault", options
     end
 
+    # Sets domain to use custom DNS servers.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.dns:setcustom
     def set_custom(sld, tld, nameservers = [], options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      args['Nameservers'] = nameservers.respond_to?(:join) ? nameservers.join(',') : nameservers
-      api_call('namecheap.domains.dns.setCustom', args)
+      if nameservers.respond_to?(:join)
+        nameservers = nameservers.join(",")
+      end
+
+      options = {SLD: sld, TLD: tld, Nameservers: nameservers}.merge(options)
+      get "domains.dns.setCustom", options
     end
 
+    # Gets a list of DNS servers associated with the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.dns:getlist
     def get_list(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.dns.getList', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.dns.getList", options
     end
 
+    # Retrieves DNS host record settings for the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.dns:gethosts
     def get_hosts(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.dns.getHosts', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.dns.getHosts", options
     end
 
+    # Gets email forwarding settings for the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.dns:getemailforwarding
     def get_email_forwarding(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.dns.getEmailForwarding', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.dns.getEmailForwarding", options
     end
 
+    # Sets email forwarding for a domain name.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.dns:setemailforwarding
     def set_email_forwarding(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.dns.setEmailForwarding', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.dns.setEmailForwarding", options
     end
 
+    # Sets DNS host records settings for the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.dns:sethosts
     def set_hosts(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.dns.setHosts', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.dns.setHosts", options
     end
   end
 end

data/lib/namecheap/domains.rb

@@ -1,67 +1,82 @@
 module Namecheap
   class Domains < Api
+    # Returns a list of domains for the particular user.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:getlist
     def get_list(options = {})
-      args = options.clone
-      api_call('namecheap.domains.getList', args)
+      get "domains.getList", options
     end
 
+    # Gets contact information for the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:getcontacts
     def get_contacts(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.getContacts', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.getContacts", options
     end
 
+    # Registers a domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:create
     def create(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.create', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.create", options
     end
 
+    # Returns a list of tlds.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:gettldlist
     def get_tld_list(options = {})
-      args = options.clone
-      api_call('namecheap.domains.getTldList', args)
+      get "domains.getTldList", options
     end
 
+    # Sets contact information for the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:setcontacts
     def set_contacts(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.setContacts', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.setContacts", options
     end
 
+    # Checks the availability of domains.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:check
     def check(domains = [], options = {})
-      args = options.clone
-      args['DomainList'] = domains.respond_to?(:join) ? domains.join(',') : domains
-      api_call('namecheap.domains.check', args)
+      if domains.respond_to?(:join)
+        domains = domains.join(",")
+      end
+
+      options = {DomainList: domains}.merge(options)
+      get "domains.check", options
     end
 
+    # Reactivates an expired domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:reactivate
     def reactivate(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.reactivate', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.reactivate", options
     end
 
+    # Renews an expiring domain.
+    # http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:renew
     def renew(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.renew', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.renew", options
     end
 
+    # Gets the status of RegistrarLock for the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:getregistrarlock
     def get_registrar_lock(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.getRegistrarLock', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.getRegistrarLock", options
     end
 
+    # Sets the RegistrarLock status for a domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:setregistrarlock
     def set_registrar_lock(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.setRegistrarLock', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.setRegistrarLock", options
     end
 
+    # Returns information about the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains:getinfo
     def get_info(domain, options = {})
-      args = options.clone
-      args['DomainName'] = domain
-      api_call('namecheap.domains.getInfo', args)
+      options = {DomainName: domain}.merge(options)
+      get "domains.getInfo", options
     end
   end
 end

data/lib/namecheap/ns.rb

@@ -1,31 +1,31 @@
 module Namecheap
   class Ns < Api
+    # Creates a new nameserver.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.ns:create
     def create(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.ns.create', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.ns.create", options
     end
 
+    # Deletes a nameserver associated with the requested domain.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.ns:delete
     def delete(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.ns.delete', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.ns.delete", options
     end
 
+    # Retrieves information about a registered nameserver.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.ns:getinfo
     def get_info(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.ns.getInfo', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.ns.getInfo", options
     end
 
+    # Updates the IP address of a registered nameserver.
+    # @see http://developer.namecheap.com/docs/doku.php?id=api-reference:domains.ns:update
     def update(sld, tld, options = {})
-      args = options.clone
-      args['SLD'] = sld
-      args['TLD'] = tld
-      api_call('namecheap.domains.ns.update', args)
+      options = {SLD: sld, TLD: tld}.merge(options)
+      get "domains.ns.update", options
     end
   end
 end