gandi_v5 0.1.0 → 0.6.0

data/lib/gandi_v5/email/mailbox.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'mailbox/responder'
-
 class GandiV5
   class Email
     # A mailbox that lives within a domain.
@@ -44,33 +42,43 @@ class GandiV5
 
       alias mailbox_uuid uuid
 
+      # Create a new GandiV5::Email::Mailbox
+      # @param members [Hash<Symbol => Object>]
+      # @return [GandiV5::Email::Slot]
+      def initialize(**members)
+        super(**members)
+        responder.instance_exec(self) { |mb| @mailbox = mb } if responder?
+      end
+
       # 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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def delete
-        data = GandiV5.delete url
+        _response, 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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def purge
-        data = GandiV5.delete "#{url}/contents"
+        _response, 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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def refresh
-        data = GandiV5.get url
+        _response, data = GandiV5.get url
         from_gandi data
+        responder.instance_exec(self) { |mb| @mailbox = mb } if responder?
+        self
       end
 
       # Update the mailbox's settings.
@@ -81,8 +89,7 @@ class GandiV5
       # @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
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def update(**body)
         return 'Nothing to update.' if body.empty?
 
@@ -93,11 +100,43 @@ class GandiV5
           body[:responder] = responder.respond_to?(:to_gandi) ? responder.to_gandi : responder.to_h
         end
 
-        data = GandiV5.patch url, body.to_json
+        _response, data = GandiV5.patch url, body.to_json
         refresh
         data['message']
       end
-      # rubocop:enable Metrics/AbcSize
+
+      # Upgrade a standard mailbox to premium.
+      # If the current slot is a free one, a new premium slot is created and
+      # used for the mailbox. Otherwise, the slot is upgraded to premium.
+      # @see https://api.gandi.net/docs/email#patch-v5-email-mailboxes-domain-mailbox_id-type
+      # @param sharing_id [String, #to_s, nil] (optional)
+      #   the organisation ID to bill for the mailbox.
+      # @param dry_run [Boolean] whether the details should be checked instead
+      #                          of actually upgrading the mailbox.
+      # @return [true] if the mailbox was upgraded
+      # @return [false] if the mailbox was not upgraded (it's already premium)
+      # @return [Hash] if doing a dry run, you get what Gandi returns
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error
+      def upgrade(sharing_id: nil, dry_run: false)
+        patch_type :premium, sharing_id, dry_run
+      end
+
+      # Downgrade a premium mailbox to standard.
+      # If a free slot is available, the premium slot is destroyed
+      # (and refunded) and the free one is used for the mailbox.
+      # Otherwise, the slot is downgraded to standard.
+      # @see https://api.gandi.net/docs/email#patch-v5-email-mailboxes-domain-mailbox_id-type
+      # @param sharing_id [String, #to_s, nil] (optional)
+      #   the organisation ID to bill for the mailbox.
+      # @param dry_run [Boolean] whether the details should be checked instead
+      #                          of actually downgrading the mailbox.
+      # @return [true] if the mailbox was downgraded
+      # @return [false] if the mailbox was not downgraded (it's already standard)
+      # @return [Hash] if doing a dry run, you get what Gandi returns
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error
+      def downgrade(sharing_id: nil, dry_run: false)
+        patch_type :standard, sharing_id, dry_run
+      end
 
       # Create a new mailbox.
       # Note that before you can create a mailbox, you must have a slot available.
@@ -107,13 +146,19 @@ class GandiV5
       # @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
+      # @param dry_run [Boolean] whether the details should be checked instead
+      #                          of actually creating the mailbox.
+      # @return [GandiV5::Email::Mailbox] The created mailbox.
+      # @raise [GandiV5::Error] if no slots are available.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+      # rubocop:disable Metrics/AbcSize
+      def self.create(fqdn, login, password, aliases: [], type: :standard, dry_run: false)
+        fail ArgumentError, "#{type.inspect} is not a valid type" unless TYPES.include?(type)
+        if GandiV5::Email::Slot.list.none? { |slot| slot.mailbox_type == type && slot.inactive? }
+          fail GandiV5::Error, "no available #{type} slots"
+        end
+
         check_password password
-        # TODO: Check if a slot is available
 
         body = {
           mailbox_type: type,
@@ -122,18 +167,20 @@ class GandiV5
           aliases: aliases.push
         }.to_json
 
-        data = GandiV5.post url(fqdn), body
-        data['message']
+        response, data = GandiV5.post(url(fqdn), body, 'Dry-Run': dry_run ? 1 : 0)
+
+        dry_run ? data : fetch(fqdn, response.headers[:location].split('/').last)
       end
+      # rubocop:enable Metrics/AbcSize
 
       # 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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def self.fetch(fqdn, uuid)
-        data = GandiV5.get url(fqdn, uuid)
+        _response, data = GandiV5.get url(fqdn, uuid)
         from_gandi data
       end
 
@@ -149,7 +196,7 @@ class GandiV5
       # @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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def self.list(fqdn, page: (1..), **params)
         page = [page.to_i] unless page.respond_to?(:each)
 
@@ -158,7 +205,7 @@ class GandiV5
 
         mailboxes = []
         page.each do |page_number|
-          data = GandiV5.get url(fqdn), params: params.merge(page: page_number)
+          _response, data = GandiV5.get url(fqdn), params: params.merge(page: page_number)
           break if data.empty?
 
           mailboxes += data.map { |mailbox| from_gandi mailbox }
@@ -231,6 +278,20 @@ class GandiV5
       def crypt_password(password)
         self.class.send :crypt_password, password
       end
+
+      def patch_type(new_type, sharing_id, dry_run)
+        fail ArgumentError unless TYPES.include?(new_type)
+        return false if type == new_type
+
+        url_ = "#{url}/type"
+        url_ = sharing_id ? "#{url_}?sharing_id=#{sharing_id}" : url_
+        body = { mailbox_type: new_type }
+
+        _response, data = GandiV5.patch(url_, body.to_json, 'Dry-Run': dry_run ? 1 : 0)
+
+        @type = new_type unless dry_run
+        dry_run ? data : true
+      end
     end
   end
 end

data/lib/gandi_v5/email/mailbox/responder.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# TODO: Allow enable/disable from here too ???
-
 class GandiV5
   class Email
     class Mailbox
@@ -15,13 +13,26 @@ class GandiV5
       #   @return [nil, Time]
       # @!attribute [r] message
       #   @return [nil, String]
+      # @!attribute [r] mailbox
+      #   @return [GandiV5::Email::Mailbox] the mailbox this repsonder belongs to.
       class Responder
         include GandiV5::Data
 
+        attr_reader :mailbox
+
         members :enabled, :message
         member :starts_at, converter: GandiV5::Data::Converter::Time
         member :ends_at, converter: GandiV5::Data::Converter::Time
 
+        # Create a new GandiV5::Email::Mailbox::Responder
+        # @param mailbox [GandiV5::Email::Mailbox] the mailbox this responder belongs to.
+        # @param members [Hash<Symbol => Object>]
+        # @return [GandiV5::Email::Slot]
+        def initialize(mailbox: nil, **members)
+          super(**members)
+          @mailbox = mailbox
+        end
+
         # Check if this responder is currently active.
         # @return [Boolean] whether the responder is enabled,
         #   started in the past and ends in the future.
@@ -30,6 +41,36 @@ class GandiV5
             (starts_at.nil? || starts_at < Time.now) &&
             (ends_at.nil? || ends_at > Time.now)
         end
+
+        # Enable the auto responder in Gandi.
+        # @param message [String]
+        # @param starts_at [Time]
+        # @param ends_at [Time]
+        # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+        def enable(message:, ends_at:, starts_at: Time.now)
+          mailbox.update responder: {
+            message: message,
+            starts_at: GandiV5::Data::Converter::Time.to_gandi(starts_at),
+            ends_at: GandiV5::Data::Converter::Time.to_gandi(ends_at),
+            enabled: true
+          }
+
+          self.starts_at = starts_at
+          self.ends_at = ends_at
+          self.message = message
+          self.enabled = true
+        end
+
+        # Disable the auto responder in Gandi.
+        # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+        def disable
+          mailbox.update responder: { enabled: false }
+
+          self.starts_at = nil
+          self.ends_at = nil
+          self.message = nil
+          self.enabled = false
+        end
       end
     end
   end

data/lib/gandi_v5/email/offer.rb

@@ -17,9 +17,9 @@ class GandiV5
       # @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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def self.fetch(fqdn)
-        data = GandiV5.get "#{BASE}email/offers/#{CGI.escape fqdn}"
+        _response, data = GandiV5.get "#{BASE}email/offers/#{CGI.escape fqdn}"
         from_gandi data
       end
     end

data/lib/gandi_v5/email/slot.rb

@@ -39,12 +39,12 @@ class GandiV5
       alias slot_id id
 
       # Create a new GandiV5::Email::Slot
-      # @param string [fqdn] the fully qualified domain this slot belongs to.
+      # @param fqdn [String] 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
+        @fqdn = fqdn
       end
 
       # Delete this slot if it is inactive and refundable.
@@ -53,20 +53,23 @@ class GandiV5
       # @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
+      # @raise [GandiV5::Error] if slot is active.
+      # @raise [GandiV5::Error] if slot is not refundable.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def delete
-        data = GandiV5.delete url
+        fail GandiV5::Error, 'slot can\'t be deleted whilst active' if active?
+        fail GandiV5::Error, 'slot can\'t be deleted if it\'s not refundable' unless refundable
+
+        _response, 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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def refresh
-        data = GandiV5.get url
+        _response, data = GandiV5.get url
         from_gandi data
       end
 
@@ -75,17 +78,24 @@ class GandiV5
       # 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.
+      # @param type [:standard, :premium] The type of slot to add.
+      # @param sharing_id [nil, String, #to_s] 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.
       # @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)
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
+      def self.create(fqdn, type: :standard, sharing_id: nil)
         body = {
           mailbox_type: type
         }.to_json
 
-        data = GandiV5.post url(fqdn), body
-        data['message']
+        url_ = url(fqdn)
+        url_ += "?sharing_id=#{sharing_id}" if sharing_id
+        response, _data = GandiV5.post url_, body
+        fetch fqdn, response.headers[:location].split('/').last
       end
 
       # Get information for a slot.
@@ -93,9 +103,9 @@ class GandiV5
       # @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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def self.fetch(fqdn, id)
-        data = GandiV5.get url(fqdn, id)
+        _response, data = GandiV5.get url(fqdn, id)
         slot = from_gandi data
         slot.instance_eval { @fqdn = fqdn }
         slot
@@ -105,9 +115,9 @@ class GandiV5
       # @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.
+      # @raise [GandiV5::Error::GandiError] if Gandi returns an error.
       def self.list(fqdn)
-        data = GandiV5.get url(fqdn)
+        _response, data = GandiV5.get url(fqdn)
         data.map { |item| from_gandi item }
             .each { |item| item.instance_eval { @fqdn = fqdn } }
       end
@@ -118,6 +128,30 @@ class GandiV5
         status.eql?(:active)
       end
 
+      # Check if the slot is inactive (not in use)
+      # @return [Boolean]
+      def inactive?
+        status.eql?(:inactive)
+      end
+
+      # Check if the slot's mailbox_type is :free
+      # @return [Boolean]
+      def free?
+        mailbox_type.eql?(:free)
+      end
+
+      # Check if the slot's mailbox_type is :standard
+      # @return [Boolean]
+      def standard?
+        mailbox_type.eql?(:standard)
+      end
+
+      # Check if the slot's mailbox_type is :premium
+      # @return [Boolean]
+      def premium?
+        mailbox_type.eql?(:premium)
+      end
+
       private
 
       def url

data/lib/gandi_v5/error.rb

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

data/lib/gandi_v5/error/gandi_error.rb

@@ -4,9 +4,9 @@ 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.
+      # Generate a new GandiV5::Error::GandiError from the hash returned by Gandi.
       # @param hash [Hash] the hash returned by Gandi.
-      # @return [GandiV5::Error::GandiError::GandiError]
+      # @return [GandiV5::Error::GandiError]
       def self.from_hash(hash)
         hash['errors'] ||= []
 

data/lib/gandi_v5/live_dns.rb

@@ -11,6 +11,26 @@ class GandiV5
       WKS SRV LOC SPF CAA DS SSHFP PTR KEY DNAME TLSA OPENPGPKEY CDS
     ].freeze
 
+    # @see GandiV5::LiveDNS::Domain.fetch
+    def self.domain(fqdn)
+      GandiV5::LiveDNS::Domain.fetch(fqdn)
+    end
+
+    # @see GandiV5::LiveDNS::Domain.list
+    def self.domains
+      GandiV5::LiveDNS::Domain.list
+    end
+
+    # @see GandiV5::LiveDNS::Zone.fetch
+    def self.zone(uuid)
+      GandiV5::LiveDNS::Zone.fetch(uuid)
+    end
+
+    # @see GandiV5::LiveDNS::Zone.list
+    def self.zones
+      GandiV5::LiveDNS::Zone.list
+    end
+
     # Raise an error if passed type is invalid.
     # @param type [String] the record type to check.
     # @return [nil]
@@ -24,7 +44,3 @@ class GandiV5
     # rubocop:enable Style/GuardClause
   end
 end
-
-require_relative 'live_dns/record_set'
-require_relative 'live_dns/domain'
-require_relative 'live_dns/zone'