gandi_v5 0.5.0 → 0.9.1

data/lib/gandi_v5/billing/info/prepaid.rb

@@ -22,6 +22,7 @@ class GandiV5
         member :updated_at, converter: GandiV5::Data::Converter::Time
 
         # Check if current balance is below the warning threshold.
+        # @return [Boolean]
         def warning?
           return nil if warning_threshold.nil?
 

data/lib/gandi_v5/data.rb

@@ -3,6 +3,7 @@
 class GandiV5
   # Addin providing a DSL to manage declaring attributes and how to map
   # and convert to/from Gandi's fields.
+  # @api private
   module Data
     # api private
     # Add contents of ClassMethods to the Class which includes this module.
@@ -149,8 +150,8 @@ class GandiV5
         return nil if data.nil?
 
         new(
-          translate_gandi(data).transform_keys(&:to_sym)
-                               .select { |k, _v| data_member?(k) }
+          **translate_gandi(data).transform_keys(&:to_sym)
+                                 .select { |k, _v| data_member?(k) }
         )
       end
 

data/lib/gandi_v5/data/converter.rb

@@ -3,6 +3,7 @@
 class GandiV5
   module Data
     # Namespace for converters to/from Gandi's format.
+    # @api private
     class Converter
       # Initialize a new simple converter.
       # The passed procs will be run at the appropriate time.
@@ -21,8 +22,8 @@ class GandiV5
         to_gandi_proc.call value
       end
 
-      # @param [Object]
-      # @return value [Object]
+      # @param value [Object]
+      # @return [Object]
       def from_gandi(value)
         return value unless from_gandi_proc
 

data/lib/gandi_v5/data/converter/array_of.rb

@@ -4,6 +4,7 @@ class GandiV5
   module Data
     class Converter
       # Used for applying the same converter to each item in an array.
+      # @api private
       class ArrayOf
         # @param converter the converter to apply to each item in the array.
         def initialize(converter)
@@ -18,8 +19,8 @@ class GandiV5
           value.map { |item| converter.to_gandi(item) }
         end
 
-        # @param [Array<Object>]
-        # @return value [Array<Object>]
+        # @param value [Array<Object>]
+        # @return [Array<Object>]
         def from_gandi(value)
           return nil if value.nil?
 

data/lib/gandi_v5/data/converter/integer.rb

@@ -4,6 +4,7 @@ class GandiV5
   module Data
     class Converter
       # Methods for converting strings to/from integerss.
+      # @api private
       class Integer
         # @param value [Integer]
         # @return [String]
@@ -13,8 +14,8 @@ class GandiV5
           value.to_s
         end
 
-        # @param [String]
-        # @return value [Integer]
+        # @param value [String]
+        # @return [Integer]
         def self.from_gandi(value)
           return nil if value.nil?
 

data/lib/gandi_v5/data/converter/symbol.rb

@@ -4,6 +4,7 @@ class GandiV5
   module Data
     class Converter
       # Methods for converting strings to/from symbols.
+      # @api private
       class Symbol
         # @param value [Symbol]
         # @return [String]
@@ -13,8 +14,8 @@ class GandiV5
           value.to_s
         end
 
-        # @param [String]
-        # @return value [Symbol]
+        # @param value [String]
+        # @return [Symbol]
         def self.from_gandi(value)
           return nil if value.nil?
 

data/lib/gandi_v5/data/converter/time.rb

@@ -4,6 +4,7 @@ class GandiV5
   module Data
     class Converter
       # Methods for converting times to/from Gandi ("2019-02-13T11:04:18Z").
+      # @api private
       class Time
         # Convert a time to Gandi's prefered string format.
         # @param value [Time]
@@ -15,8 +16,8 @@ class GandiV5
         end
 
         # Convert a time from Gandi's prefered string format.
-        # @param [String]
-        # @return value [Time]
+        # @param value [String]
+        # @return [Time]
         def self.from_gandi(value)
           return nil if value.nil?
 

data/lib/gandi_v5/domain.rb

@@ -7,7 +7,7 @@ class GandiV5
   #   @return [String] fully qualified domain name, written in its native alphabet (IDN).
   # @!attribute [r] fqdn_unicode
   #   @return [String] fully qualified domain name, written in unicode.
-  #     @see https://docs.gandi.net/en/domain_names/register/idn.html
+  #   @see https://docs.gandi.net/en/domain_names/register/idn.html
   # @!attribute [r] name_servers
   #   @return [Array<String>]
   # @!attribute [r] services
@@ -15,12 +15,12 @@ class GandiV5
   #      gandidns, redirection, gandimail, packmail, dnssec, blog, hosting,
   #      paas, site, certificate, gandilivedns, mailboxv2
   # @!attribute [r] sharing_space
-  #   @return [GandiV5::Domain::SharingSpace]
+  #   @return [GandiV5::SharingSpace]
   # @!attribute [r] status
   #   @return [String] one of: "clientHold", "clientUpdateProhibited", "clientTransferProhibited",
   #     "clientDeleteProhibited", "clientRenewProhibited", "serverHold", "pendingTransfer",
   #     "serverTransferProhibited"
-  #     @see https://docs.gandi.net/en/domain_names/faq/domain_statuses.html
+  #   @see https://docs.gandi.net/en/domain_names/faq/domain_statuses.html
   # @!attribute [r] tld
   #   @return [String]
   # @!attribute [r] dates
@@ -107,7 +107,7 @@ class GandiV5
     member(
       :sharing_space,
       gandi_key: 'sharing_space',
-      converter: GandiV5::Domain::SharingSpace
+      converter: GandiV5::SharingSpace
     )
 
     member(
@@ -206,7 +206,7 @@ class GandiV5
     end
 
     # Renew domain.
-    # Warning! This is not a free operation. Please ensure your prepaid account has enough credit.
+    # @note This is not a free operation. Please ensure your prepaid account has enough credit.
     # @see https://api.gandi.net/docs/domains#post-v5-domain-domains-domain-renew
     # @param duration [Integer, #to_s] how long to renew for (in years).
     # @return [String] confirmation message from Gandi.
@@ -242,7 +242,7 @@ class GandiV5
     end
 
     # Restore an expired domain.
-    # Warning! This is not a free operation. Please ensure your prepaid account has enough credit.
+    # @note This is not a free operation. Please ensure your prepaid account has enough credit.
     # @see https://docs.gandi.net/en/domain_names/renew/restore.html
     # @see https://api.gandi.net/docs/domains#post-v5-domain-domains-domain-restore
     # @return [String] The confirmation message from Gandi.
@@ -399,23 +399,26 @@ class GandiV5
       data['message']
     end
 
+    # Get email mailboxes for the domain.
     # @see GandiV5::Email::Mailbox.list
     def mailboxes(**params)
       GandiV5::Email::Mailbox.list(**params, fqdn: fqdn)
     end
 
+    # Get email slots for the domain.
     # @see GandiV5::Email::Slot.list
     def mailbox_slots(**params)
       GandiV5::Email::Slot.list(**params, fqdn: fqdn)
     end
 
+    # Get email forwards for the domain.
     # @see GandiV5::Email::Forward.list
     def email_forwards(**params)
       GandiV5::Email::Forward.list(**params, fqdn: fqdn)
     end
 
     # Create (register) a new domain.
-    # Warning! This is not a free operation. Please ensure your prepaid account has enough credit.
+    # @note This is not a free operation. Please ensure your prepaid account has enough credit.
     # @see https://api.gandi.net/docs/domains#post-v5-domain-domains
     # @param fqdn [String, #to_s] the fully qualified domain name to create.
     # @param dry_run [Boolean]
@@ -459,7 +462,7 @@ class GandiV5
     #   Contents of a Signed Mark Data file (used for newgtld sunrises, tld_period must be sunrise).
     # @param tld_period ["sunrise", "landrush", "eap1", "eap2", "eap3", "eap4", "eap5", "eap6",
     #   "eap7", "eap8", "eap9", "golive", #to_gandi, #to_json] (optional)
-    #   @see https://docs.gandi.net/en/domain_names/register/new_gtld.html
+    # @see https://docs.gandi.net/en/domain_names/register/new_gtld.html
     # @return [GandiV5::Domain] the created domain
     # @return [Hash] if doing a dry run, you get what Gandi returns
     # @raise [GandiV5::Error::GandiError] if Gandi returns an error
@@ -492,24 +495,20 @@ class GandiV5
     # @param page [#each<Integer, #to_s>] the page(s) of results to retrieve.
     #   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 per_page [Integer, #to_s] (optional default 100) how many results to get per page.
     # @param fqdn [String, #to_s] (optional)
     #   filters the list by domain name, with optional patterns.
     #   e.g. "example.net", "example.*", "*ample.com"
-    # @param sort_by [String, #to_s] (optional default "fqdn") how to sort the list.
+    # @param resellee_id [String, #to_s] (optional)
+    #   filters the list by resellee_id (from the Organization API).
     # @param tld [String, #to_s] (optional) used to filter by just the top level domain.
+    # @param sort_by [String, #to_s] (optional default "fqdn") how to sort the list.
     # @return [Array<GandiV5::Domain>]
     # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
     def self.list(page: (1..), per_page: 100, **params)
-      page = [page.to_i] unless page.respond_to?(:each)
-
       domains = []
-      page.each do |page_number|
-        _resp, data = GandiV5.get url, params: params.merge(page: page_number, per_page: per_page)
-        break if data.empty?
-
+      GandiV5.paginated_get(url, page, per_page, params: params) do |data|
         domains += data.map { |domain| from_gandi domain }
-        break if data.count < per_page
       end
       domains
     end

data/lib/gandi_v5/domain/availability/product/period.rb

@@ -4,7 +4,7 @@ class GandiV5
   class Domain
     class Availability
       class Product
-        # Information about an available product.
+        # Information about an available product's period.
         # @!attribute [r] name
         #   @return [String]
         # @!attribute [r]

data/lib/gandi_v5/domain/contact.rb

@@ -4,15 +4,15 @@ class GandiV5
   class Domain
     # Information for a single contact for a domain.
     # @!attribute [r] country
-    #   @return [String] .
+    #   @return [String]
     # @!attribute [r] email
-    #   @return [String] .
+    #   @return [String]
     # @!attribute [r] family
-    #   @return [String] .
+    #   @return [String]
     # @!attribute [r] given
-    #   @return [String] .
+    #   @return [String]
     # @!attribute [r] address
-    #   @return [String] .
+    #   @return [String]
     # @!attribute [r] type
     #   @return [:person, :company, :association, :'public body', :reseller]
     # @!attribute [r] brand_number

data/lib/gandi_v5/domain/tld.rb

@@ -12,7 +12,7 @@ class GandiV5
     # @!attribute [r] category
     #   @return [String]
     # @!attribute [r] change_owner
-    #   @return [Boolean] whther changing owner is pemritted.
+    #   @return [Boolean] whether changing owner is pemritted.
     # @!attribute [r] corporate
     #   @return [Boolean] whether this is a corporate TLD.
     # @!attribute [r] ext_trade
@@ -27,7 +27,7 @@ class GandiV5
 
       # List of available TLDs.
       # @see https://api.gandi.net/docs/domains#get-v5-domain-tlds
-      # @return Array<GandiV5::Domain::TLD>
+      # @return [Array<GandiV5::Domain::TLD>]
       # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def self.list
         GandiV5.get(url)

data/lib/gandi_v5/domain/transfer_in.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+class GandiV5
+  class Domain
+    # Manage a domain's transfer to Gandi.
+    # @!attribute [r] fqdn
+    #   @return [String] the fully qualified domain name being transfered
+    # @!attribute [r] created_at
+    #   @return [Time]
+    # @!attribute [r] updated_at
+    #   @return [Time]
+    # @!attribute [r] owner_contact
+    #   @return [String]
+    # @!attribute [r] step
+    #   @return [String]
+    # @!attribute [r] step_number
+    #   @return [Integer]
+    # @!attribute [r] errortype
+    #   @return [String] (optional)
+    # @!attribute [r] errortype_label
+    #   @return [String] (optional)
+    # @!attribute [r] duration
+    #   @return [Integer] (optional)
+    # @!attribute [r] reseller_uuid
+    #   @return [String] (optional)
+    # @!attribute [r] version
+    #   @return [Integer] (optional)
+    # @!attribute [r] foa
+    #   @return [Hash{String=>String}] (optional) email => status
+    # @!attribute [r] inner_step
+    #   @return [String] (optional)
+    # @!attribute [r] transfer_procedure
+    #   @return [String] (optional)
+    # @!attribute [r] start_at
+    #   @return [Time] (optional)
+    # @!attribute [r] regac_at
+    #   @return [Time] (optional)
+    class TransferIn
+      include GandiV5::Data
+
+      members :fqdn, :owner_contact, :step, :errortype, :errortype_label, :inner_step,
+              :transfer_procedure, :reseller_uuid, :version, :foa_status, :duration
+
+      member :step_number, gandi_key: 'step_nb'
+      member :created_at, converter: GandiV5::Data::Converter::Time
+      member :updated_at, converter: GandiV5::Data::Converter::Time
+      member :regac_at, converter: GandiV5::Data::Converter::Time
+      member :start_at, converter: GandiV5::Data::Converter::Time
+
+      # Relaunch the transfer process after something went wrong.
+      # @see https://api.gandi.net/docs/domains/#put-v5-domain-transferin-domain
+      # @return [String] the confirmation message from Gandi
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+      def relaunch
+        TransferIn.relaunch fqdn
+      end
+
+      # Resend the {https://icannwiki.org/FOA Form Of Authorization} email.
+      # @see https://api.gandi.net/docs/domains/#post-v5-domain-transferin-domain-foa
+      # @return [String] the confirmation message from Gandi
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+      def resend_foa_emails(email_address)
+        TransferIn.resend_foa_emails fqdn, email_address
+      end
+
+      # Start the transfer of a domain to Gandi.
+      # @note This is not a free operation. Please ensure your prepaid account has enough credit.
+      # @see https://api.gandi.net/docs/domains/#post-v5-domain-transferin
+      # @param fqdn [String, #to_s] the fully qualified domain name to create.
+      # @param dry_run [Boolean]
+      #   whether the details should be checked instead of actually creating the domain.
+      # @param sharing_id [String] either:
+      #   * nil (default) - nothing special happens
+      #   * an organization ID - pay using another organization
+      #     (you need to have billing permissions on the organization
+      #     and use the same organization name for the domain name's owner).
+      #     The invoice will be edited using this organization's information.
+      #   * a reseller ID - buy a domain for a customer using a reseller account
+      #     (you need to have billing permissions on the reseller organization
+      #     and have your customer's information for the owner).
+      #     The invoice will be edited using the reseller organization's information.
+      # @param owner [GandiV5::Domain::Contact, #to_gandi, #to_h] (required)
+      #   the owner of the new domain.
+      # @param admin [GandiV5::Domain::Contact, #to_gandi, #to_h] (optional, defaults to owner)
+      #   the administrative contact for the new domain.
+      # @param bill [GandiV5::Domain::Contact, #to_gandi, #to_h] (optional, defaults to owner)
+      #   the billing contact for the new domain.
+      # @param tech [GandiV5::Domain::Contact, #to_gandi, #to_h] (optional, defaults to owner)
+      #   the technical contact for the new domain.
+      # @param currency ["EUR", "USD", "GBP", "TWD", "CNY"] (optional)
+      #   the currency you wish to be charged in.
+      # @param duration [Integer] (optional, default 1, minimum 1 maximum 10)
+      #   how many years to register for.
+      # @param enforce_premium [Boolean] (optional)
+      #   must be set to true if the domain is a premium domain.
+      # @param extra_parameters [Hash, #to_gandi, #to_json] (optional)
+      #   unknown - not documented at Gandi.
+      # @param nameserver_ips [Hash<String => Array<String>>, #to_gandi, #to_json] (optional)
+      #   For glue records only - dictionnary associating a nameserver to a list of IP addresses.
+      # @param nameservers [Array<String>, #to_gandi, #to_json] (optional)
+      #   List of nameservers. Gandi's LiveDNS nameservers are used if omitted..
+      # @param price [Numeric, #to_gandi, #to_json] (optional) unknown - not documented at Gandi.
+      # @param resellee_id [String, #to_gandi, #to_json] (optional)
+      #   unknown - not documented at Gandi.
+      # @param change_owner [Boolean] (optional)
+      #   whether the change the domain's owner during the transfer.
+      # @param auth_code [String] (optional) authorization code (if required).
+      # @return [String] the confirmation message from Gandi
+      # @return [Hash] if doing a dry run, you get what Gandi returns
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error
+      def self.create(fqdn, dry_run: false, sharing_id: nil, **params)
+        fail ArgumentError, 'missing keyword: owner' unless params.key?(:owner)
+
+        body = params.merge(fqdn: fqdn)
+                     .transform_values { |val| val.respond_to?(:to_gandi) ? val.to_gandi : val }
+                     .to_json
+        url_ = sharing_id ? "#{url}?sharing_id=#{sharing_id}" : url
+
+        _response, data = GandiV5.post(url_, body, 'Dry-Run': dry_run ? 1 : 0)
+        dry_run ? data : data['message']
+      end
+
+      # Get information on an existing transfer.
+      # @see https://api.gandi.net/docs/domains/#get-v5-domain-transferin-domain
+      # @param fqdn [String, #to_s] the fully qualified domain name to check.
+      # @return [GandiV5::Domain::TransferIn]
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+      def self.fetch(fqdn)
+        _response, data = GandiV5.get url(fqdn)
+        transfer = from_gandi data
+        transfer.instance_exec { @fqdn = data.dig('params', 'domain') }
+        transfer.instance_exec { @reseller_uuid = data.dig('params', 'reseller') }
+        transfer.instance_exec { @version = data.dig('params', 'version') }
+        transfer.instance_exec { @duration = data.dig('params', 'duration') }
+        if data.key?('foa')
+          transfer.instance_exec do
+            @foa_status = Hash[data['foa'].map { |hash| hash.values_at('email', 'answer') }]
+          end
+        end
+        transfer
+      end
+
+      # Relaunch the transfer process after something went wrong.
+      # @see https://api.gandi.net/docs/domains/#put-v5-domain-transferin-domain
+      # @return [String] the confirmation message from Gandi
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+      def self.relaunch(fqdn)
+        _response, data = GandiV5.put url(fqdn)
+        data['message']
+      end
+
+      # Resend the {https://icannwiki.org/FOA Form Of Authorization} email.
+      # @see https://api.gandi.net/docs/domains/#post-v5-domain-transferin-domain-foa
+      # @return [String] the confirmation message from Gandi
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+      def self.resend_foa_emails(fqdn, email_address)
+        _response, data = GandiV5.post "#{url(fqdn)}/foa", { 'email' => email_address }.to_json
+        data['message']
+      end
+
+      private
+
+      def self.url(fqdn = nil)
+        "#{BASE}domain/transferin" +
+          (fqdn ? "/#{CGI.escape fqdn}" : '')
+      end
+      private_class_method :url
+    end
+  end
+end