gandi_v5 0.1.0

data/lib/gandi_v5/email/mailbox.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require_relative 'mailbox/responder'
+
+class GandiV5
+  class Email
+    # A mailbox that lives within a domain.
+    # @!attribute [r] address
+    #   @return [String] full email address.
+    # @!attribute [r] fqdn
+    #   @return [String] domain name.
+    # @!attribute [r] uuid
+    #   @return [String]
+    # @!attribute [r] login
+    #   @return [String] mailbox login.
+    # @!attribute [r] type
+    #   @return [:standard, :premium, :free]
+    # @!attribute [r] quota_used
+    #   @return [Integer]
+    # @!attribute [r] aliases
+    #   @return [nil, Array<String>] mailbox alias list.
+    #     A local-part (what comes before the "@") of an email address. It can contain a wildcard
+    #     "*" before or after at least two characters to redirect everything thats matches the
+    #     local-part pattern.
+    # @!attribute [r] fallback_email
+    #   @return [nil, String] fallback email addresse.
+    # @!attribute [r] responder
+    #   @return [nil, GandiV5::Email::Mailbox::Responder]
+    class Mailbox
+      include GandiV5::Data
+
+      TYPES = %i[standard premium free].freeze
+      QUOTAS = {
+        free: 3 * 1024**3,
+        standard: 3 * 1024**3,
+        premium: 50 * 1024**3
+      }.freeze
+
+      members :address, :login, :quota_used, :aliases, :fallback_email
+      member :type, gandi_key: 'mailbox_type', converter: GandiV5::Data::Converter::Symbol
+      member :uuid, gandi_key: 'id'
+      member :fqdn, gandi_key: 'domain'
+      member :responder, converter: GandiV5::Email::Mailbox::Responder
+
+      alias mailbox_uuid uuid
+
+      # Delete the mailbox and it's contents.
+      # If you delete a mailbox for which you have purchased a slot,
+      # this action frees the slot so it once again becomes available
+      # for use with a new mailbox, or for deletion.
+      # @see https://api.gandi.net/docs/email#delete-v5-email-mailboxes-domain-mailbox_id
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def delete
+        data = GandiV5.delete url
+        data['message']
+      end
+
+      # Purge the contents of the mailbox.
+      # @see https://api.gandi.net/docs/email#delete-v5-email-mailboxes-domain-mailbox_id-contents
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def purge
+        data = GandiV5.delete "#{url}/contents"
+        data['message']
+      end
+
+      # Requery Gandi fo this mailbox's information.
+      # @return [GandiV5::Email::Mailbox]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def refresh
+        data = GandiV5.get url
+        from_gandi data
+      end
+
+      # Update the mailbox's settings.
+      # @see https://api.gandi.net/docs/email#patch-v5-email-mailboxes-domain-mailbox_id
+      # @param login [String, #to_s] the login name (and first part of email address).
+      # @param password [String, #to_s] the password to use.
+      # @param aliases [Array<String, #to_s>] any alternative email address to be used.
+      # @param responder [Hash, GandiV5::Mailbox::Responder, #to_gandi, #to_h]
+      #   auto responder settings.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      # rubocop:disable Metrics/AbcSize
+      def update(**body)
+        return 'Nothing to update.' if body.empty?
+
+        check_password body[:password] if body.key?(:password)
+
+        body[:password] = crypt_password(body[:password]) if body.key?(:password)
+        if (responder = body[:responder])
+          body[:responder] = responder.respond_to?(:to_gandi) ? responder.to_gandi : responder.to_h
+        end
+
+        data = GandiV5.patch url, body.to_json
+        refresh
+        data['message']
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      # Create a new mailbox.
+      # Note that before you can create a mailbox, you must have a slot available.
+      # @see https://api.gandi.net/docs/email#post-v5-email-mailboxes-domain
+      # @param fqdn [String, #to_s] the fully qualified domain name for the mailbox.
+      # @param login [String, #to_s] the login name (and first part of email address).
+      # @param password [String, #to_s] the password to use.
+      # @param aliases [Array<String, #to_s>] any alternative email address to be used.
+      # @param type [:standard, :premium] the type of mailbox slot to use.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      # TODO: Fetch created mailbox
+      def self.create(fqdn, login, password, aliases: [], type: :standard)
+        # TODO: Check type is valid
+        check_password password
+        # TODO: Check if a slot is available
+
+        body = {
+          mailbox_type: type,
+          login: login,
+          password: crypt_password(password),
+          aliases: aliases.push
+        }.to_json
+
+        data = GandiV5.post url(fqdn), body
+        data['message']
+      end
+
+      # Get information for a mailbox.
+      # @see https://api.gandi.net/docs/email#get-v5-email-mailboxes-domain-mailbox_id
+      # @param fqdn [String, #to_s] the fully qualified domain name for the mailbox.
+      # @param uuid [String, #to_s] unique identifier of the mailbox.
+      # @return [GandiV5::Email::Mailbox]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.fetch(fqdn, uuid)
+        data = GandiV5.get url(fqdn, uuid)
+        from_gandi data
+      end
+
+      # List mailboxes for a domain.
+      # @see https://api.gandi.net/docs/email#get-v5-email-mailboxes-domain
+      # @param fqdn [String, #to_s] the fully qualified domain name for the mailboxes.
+      # @param page [Integer, #each<Integer>] which page(s) of results to get.
+      #   If page is not provided keep querying until an empty list is returned.
+      #   If page responds to .each then iterate until an empty list is returned.
+      # @param per_page [Integer, #to_s] (optional default 100) how many results ot get per page.
+      # @param sort_by [#to_s] (optional default "login")
+      #   how to sort the results ("login", "-login").
+      # @param login [String] (optional) filter the list by login (pattern)
+      #   e.g. ("alice" "*lice", "alic*").
+      # @return [Array<GandiV5::Email::Mailbox>]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.list(fqdn, page: (1..), **params)
+        page = [page.to_i] unless page.respond_to?(:each)
+
+        params['~login'] = params.delete(:login)
+        params.reject! { |_k, v| v.nil? }
+
+        mailboxes = []
+        page.each do |page_number|
+          data = GandiV5.get url(fqdn), params: params.merge(page: page_number)
+          break if data.empty?
+
+          mailboxes += data.map { |mailbox| from_gandi mailbox }
+          break if data.count < params.fetch(:per_page, 100)
+        end
+        mailboxes
+      end
+
+      # Get the quota for this type of mailbox.
+      # @return [Integer] bytes.
+      def quota
+        QUOTAS[type]
+      end
+
+      # Get the quota usage for this mailbox.
+      # @return [Float] fraction of quota used (typically between 0.0 and 1.0)
+      def quota_usage
+        quota_used.to_f / quota
+      end
+
+      # Returns the string representation of the mailbox.
+      # Includes the type, address, quota usage, activeness of responder (if present)
+      # and aliases (if present).
+      # @return [String]
+      def to_s
+        s = "[#{type}] #{address} (#{quota_used}/#{quota} (#{(quota_usage * 100).round}%))"
+        s += " with #{responder.active? ? 'active' : 'inactive'} responder" if responder
+        s += " aka: #{aliases.join(', ')}" if aliases&.any?
+        s
+      end
+
+      private
+
+      # rubocop:disable Style/GuardClause
+      def self.check_password(password)
+        if !(9..200).cover?(password.length)
+          fail ArgumentError, 'password must be between 9 and 200 characters'
+        elsif password.count('A-Z') < 1
+          fail ArgumentError, 'password must contain at least one upper case character'
+        elsif password.count('0-9') < 3
+          fail ArgumentError, 'password must contain at least three numbers'
+        elsif password.count('^a-z^A-Z^0-9') < 1
+          fail ArgumentError, 'password must contain at least one special character'
+        end
+      end
+      private_class_method :check_password
+      # rubocop:enable Style/GuardClause
+
+      def check_password(password)
+        self.class.send :check_password, password
+      end
+
+      def url
+        "#{BASE}email/mailboxes/#{CGI.escape fqdn}/#{CGI.escape uuid}"
+      end
+
+      def self.url(fqdn, uuid = nil)
+        "#{BASE}email/mailboxes/#{CGI.escape fqdn}" +
+          (uuid ? "/#{CGI.escape uuid}" : '')
+      end
+      private_class_method :url
+
+      def self.crypt_password(password)
+        # You can also send a hashed password in sha512-crypt ie: {SHA512-CRYPT}$6$xxxx$yyyy
+        salt = SecureRandom.random_number(36**8).to_s(36)
+        password.crypt('$6$' + salt)
+      end
+      private_class_method :crypt_password
+
+      def crypt_password(password)
+        self.class.send :crypt_password, password
+      end
+    end
+  end
+end

data/lib/gandi_v5/email/offer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class GandiV5
+  class Email
+    # The current status of your mailbox offer.
+    # @!attribute [r] status
+    #   @return [:active, :inactive]
+    # @!attribute [r] version
+    #   @return [1, 2]
+    class Offer
+      include GandiV5::Data
+
+      member :version
+      member :status, converter: GandiV5::Data::Converter::Symbol
+
+      # Get the current status of your mailbox offer.
+      # @see https://api.gandi.net/docs/email#get-v5-email-offers-domain
+      # @param fqdn [String, #to_s] the fully qualified domain name to get the offer for.
+      # @return [GandiV5::Email::Offer]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.fetch(fqdn)
+        data = GandiV5.get "#{BASE}email/offers/#{CGI.escape fqdn}"
+        from_gandi data
+      end
+    end
+  end
+end

data/lib/gandi_v5/email/slot.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+class GandiV5
+  class Email
+    # A slot is attached to a domain and (optionally) contains a mailbox.
+    # There must be an available slot for a mailbox to be created.
+    # @!attribute [r] capacity
+    #   @return [Integer] slot capacity (in MB).
+    # @!attribute [r] created_at
+    #   @return [Time]
+    # @!attribute [r] id
+    #   @return [Integer]
+    # @!attribute [r] mailbox_type
+    #   @return [:standard, :premium]
+    # @!attribute [r] status
+    #   @return [:active, :inactive]
+    # @!attribute [r] refundable
+    #   @return [Boolean]
+    # @!attribute [r] refund_amount
+    #   @return [nil, Numeric] refunded amount if you delete this slot now.
+    # @!attribute [r] refund_currency
+    #   @return [nil, String] refund currency.
+    class Slot
+      include GandiV5::Data
+
+      attr_reader :fqdn
+
+      members :id, :refundable, :refund_amount, :refund_currency
+      member(
+        :capacity,
+        converter: GandiV5::Data::Converter.new(
+          from_gandi: ->(value) { value * 1_024**2 }
+        )
+      )
+      member :created_at, converter: GandiV5::Data::Converter::Time
+      member :mailbox_type, converter: GandiV5::Data::Converter::Symbol
+      member :status, converter: GandiV5::Data::Converter::Symbol
+
+      alias slot_id id
+
+      # Create a new GandiV5::Email::Slot
+      # @param string [fqdn] the fully qualified domain this slot belongs to.
+      # @param members [Hash<Symbol => Object>]
+      # @return [GandiV5::Email::Slot]
+      def initialize(fqdn: nil, **members)
+        super(**members)
+        @fqdn = fqdn if fqdn
+      end
+
+      # Delete this slot if it is inactive and refundable.
+      # When you delete a slot, the prepaid account that was used to purchase the slot
+      # will be refunded for the remaining time that will not be used.
+      # @see GandiV5::Email::Mailbox#delete
+      # @see https://api.gandi.net/docs/email#delete-v5-email-slots-domain-slot_id
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      # TODO: check for inactiveness
+      # TODO: check for refundableness
+      def delete
+        data = GandiV5.delete url
+        data['message']
+      end
+
+      # Requery Gandi for this slot's information.
+      # @see https://api.gandi.net/docs/email#get-v5-email-slots-domain-slot_id
+      # @return [GandiV5::Email::Slot]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def refresh
+        data = GandiV5.get url
+        from_gandi data
+      end
+
+      # Creates a new slot. You must have slots available before you can create a mailbox.
+      # If you have used the two free standard 3GB mailbox slots that are included with the domain,
+      # but require more mailboxes on that domain, you must first purchase additional slots.
+      # @see https://api.gandi.net/docs/email#post-v5-email-slots-domain
+      # @param fqdn [String, #to_s] the fully qualified domain name to add the slot to.
+      # @param type [:standard, :premium] Tyhe type of slot to add.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      # TODO: Fetch created slot
+      def self.create(fqdn, type = :standard)
+        body = {
+          mailbox_type: type
+        }.to_json
+
+        data = GandiV5.post url(fqdn), body
+        data['message']
+      end
+
+      # Get information for a slot.
+      # @see https://api.gandi.net/docs/email#get-v5-email-slots-domain-slot_id
+      # @param fqdn [String, #to_s] the fully qualified domain name the slot is on.
+      # @param id [String, #to_s] the ID of the slot to fetch.
+      # @return [GandiV5::Email::Slot]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.fetch(fqdn, id)
+        data = GandiV5.get url(fqdn, id)
+        slot = from_gandi data
+        slot.instance_eval { @fqdn = fqdn }
+        slot
+      end
+
+      # List slots for a domain.
+      # @see https://api.gandi.net/docs/email#
+      # @param fqdn [String, #to_s] the fully qualified domain name to list slots for.
+      # @return [Array<GandiV5::Email::Slot>]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.list(fqdn)
+        data = GandiV5.get url(fqdn)
+        data.map { |item| from_gandi item }
+            .each { |item| item.instance_eval { @fqdn = fqdn } }
+      end
+
+      # Check if the slot is active (in use)
+      # @return [Boolean]
+      def active?
+        status.eql?(:active)
+      end
+
+      private
+
+      def url
+        "#{BASE}email/slots/#{CGI.escape fqdn}/#{id}"
+      end
+
+      def self.url(fqdn, id = nil)
+        "#{BASE}email/slots/#{CGI.escape fqdn}" +
+          (id ? "/#{id}" : '')
+      end
+      private_class_method :url
+    end
+  end
+end

data/lib/gandi_v5/email.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'email/mailbox'
+require_relative 'email/offer'
+require_relative 'email/slot'
+
+class GandiV5
+  # Gandi Email Mailbox Management API.
+  class Email
+  end
+end

data/lib/gandi_v5/error/gandi_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class GandiV5
+  class Error < RuntimeError
+    # Generic error class for errors returned by Gandi.
+    class GandiError < GandiV5::Error
+      # Generate a new GandiV5::Error::GandiError::GandiError from the hash returned by Gandi.
+      # @param hash [Hash] the hash returned by Gandi.
+      # @return [GandiV5::Error::GandiError::GandiError]
+      def self.from_hash(hash)
+        hash['errors'] ||= []
+
+        new(
+          (hash['errors'].count > 1 ? "\n" : '') +
+            hash['errors'].map { |err| "#{err['location']}->#{err['name']}: #{err['description']}" }
+                               .join("\n")
+        )
+      end
+    end
+  end
+end

data/lib/gandi_v5/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'error/gandi_error'
+
+class GandiV5
+  # Generic error class for errors occuring using the API.
+  class Error < RuntimeError
+  end
+end

data/lib/gandi_v5/live_dns/domain.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+class GandiV5
+  class LiveDNS
+    # A domain name within the LiveDNS system.
+    # @!attribute [r] fqdn
+    #   @return [String]
+    # @!attribute [r] zone_uuid
+    #   @return [String]
+    class Domain
+      include GandiV5::Data
+
+      members :fqdn
+
+      member(
+        :zone_uuid,
+        gandi_key: 'zone',
+        converter: GandiV5::Data::Converter.new(from_gandi: ->(zone) { zone&.split('/')&.last })
+      )
+
+      # Refetch the information for this domain from Gandi.
+      # @return [GandiV5::LiveDNS::Domain]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def refresh
+        data = GandiV5.get url
+        from_gandi data
+      end
+
+      # @overload fetch_records()
+      #   Fetch all records for this domain.
+      # @overload fetch_records(name)
+      #   Fetch records for a name.
+      #   @param name [String] the name to fetch records for.
+      # @overload fetch_records(name, type)
+      #   Fetch records of a type for a name.
+      #   @param name [String] the name to fetch records for.
+      #   @param type [String] the record type to fetch.
+      # @return [Array<GandiV5::LiveDNS::RecordSet>]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def fetch_records(name = nil, type = nil)
+        GandiV5::LiveDNS.require_valid_record_type type if type
+
+        url_ = "#{url}/records"
+        url_ += "/#{CGI.escape name}" if name
+        url_ += "/#{CGI.escape type}" if type
+
+        data = GandiV5.get url_
+        data = [data] unless data.is_a?(Array)
+        data.map { |item| GandiV5::LiveDNS::RecordSet.from_gandi item }
+      end
+
+      # @overload fetch_zone_lines()
+      #   Fetch all records for this domain.
+      # @overload fetch_zone_lines(name)
+      #   Fetch records for a name.
+      #   @param name [String] the name to fetch records for.
+      # @overload fetch_zone_lines(name, type)
+      #   Fetch records of a type for a name.
+      #   @param name [String] the name to fetch records for.
+      #   @param type [String] the record type to fetch.
+      # @return [String]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def fetch_zone_lines(name = nil, type = nil)
+        GandiV5::LiveDNS.require_valid_record_type type if type
+
+        url_ = "#{url}/records"
+        url_ += "/#{CGI.escape name}" if name
+        url_ += "/#{CGI.escape type}" if type
+
+        GandiV5.get url_, accept: 'text/plain'
+      end
+
+      # Add record to this domain.
+      # @param name [String]
+      # @param type [String]
+      # @param ttl [Integer]
+      # @param values [Array<String>]
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def add_record(name, type, ttl, *values)
+        GandiV5::LiveDNS.require_valid_record_type type
+        fail ArgumentError, 'ttl must be positive and non-zero' unless ttl.positive?
+        fail ArgumentError, 'there must be at least one value' if values.none?
+
+        body = {
+          rrset_name: name,
+          rrset_type: type,
+          rrset_ttl: ttl,
+          rrset_values: values
+        }.to_json
+        data = GandiV5.post "#{url}/records", body
+        data['message']
+      end
+
+      # @overload delete_records()
+      #   Delete all records for this domain.
+      # @overload delete_records(name)
+      #   Delete records for a name.
+      #   @param name [String] the name to delete records for.
+      # @overload delete_records(name, type)
+      #   Delete records of a type for a name.
+      #   @param name [String] the name to delete records for.
+      #   @param type [String] the record type to delete.
+      # @return [nil]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def delete_records(name = nil, type = nil)
+        GandiV5::LiveDNS.require_valid_record_type(type) if type
+
+        url_ = "#{url}/records"
+        url_ += "/#{CGI.escape name}" if name
+        url_ += "/#{CGI.escape type}" if type
+        GandiV5.delete url_
+      end
+
+      # Replace all records for this domain.
+      # @param records
+      #   [Array<Hash<:name, :type => String, :ttl => Integer, :values => Array<String>>>]
+      #   the records to add.
+      # @param text [String] zone file lines to replace the records with.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [ArgumentError] if neither/both of records & test are passed.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def replace_records(records: nil, text: nil)
+        unless [records, text].count(&:nil?).eql?(1)
+          fail ArgumentError, 'you must pass ONE of records: or text:'
+        end
+
+        if records
+          body = {
+            items: records.map { |r| r.transform_keys { |k| "rrset_#{k}" } }
+          }.to_json
+          data = GandiV5.put "#{url}/records", body
+        elsif text
+          data = GandiV5.put "#{url}/records", text, 'content-type': 'text/plain'
+        end
+        data['message']
+      end
+
+      # Replace records for a name in this domain.
+      # @param name [String]
+      # @param records
+      #   [Array<Hash<type: String, ttl: Integer, values: Array<String>>>]
+      #   the records to add.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def replace_records_for(name, *records)
+        body = {
+          items: records.map { |r| r.transform_keys { |k| "rrset_#{k}" } }
+        }.to_json
+        data = GandiV5.put "#{url}/records/#{name}", body
+        data['message']
+      end
+
+      GandiV5::LiveDNS::RECORD_TYPES.each do |type|
+        # Replace records of a given type for a name in this domain.
+        # TODO: @param name [Type] description.
+        # TODO: @param ttl [Type] description.
+        # TODO: documentation for *values
+        # @return [String] The confirmation message from Gandi.
+        # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+        define_method "replace_#{type.downcase}_records_for" do |name, ttl, *values|
+          body = {
+            rrset_ttl: ttl,
+            rrset_values: values
+          }.to_json
+          data = GandiV5.put "#{url}/records/#{name}/#{type}", body
+          data['message']
+        end
+      end
+
+      # Change the zone used by this domain.
+      # @param uuid [String, #uuid, #to_s] the UUID of the zone this domain should now use.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def change_zone(uuid)
+        uuid = uuid.uuid if uuid.respond_to?(:uuid)
+        data = GandiV5.patch url, { zone_uuid: uuid }.to_json
+        self.zone_uuid = uuid
+        data['message']
+      end
+
+      # List the domains.
+      # @return [Array<GandiV5::LiveDNS::Domain>]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.list
+        data = GandiV5.get url
+        data.map { |item| from_gandi item }
+      end
+
+      # Get a domain.
+      # @param fqdn [String, #to_s] the fully qualified domain name to fetch.
+      # @return [GandiV5::LiveDNS::Domain]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.fetch(fqdn)
+        data = GandiV5.get url(fqdn)
+        from_gandi data
+      end
+
+      private
+
+      def url
+        "#{BASE}domains/#{CGI.escape(fqdn)}"
+      end
+
+      def self.url(fqdn = nil)
+        "#{BASE}domains" + (fqdn ? "/#{CGI.escape(fqdn)}" : '')
+      end
+      private_class_method :url
+    end
+  end
+end