gandi_v5 0.1.0

data/lib/gandi_v5/live_dns/record_set.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+class GandiV5
+  class LiveDNS
+    # A record set which comes from either a domain or zone.
+    # @!attribute [r] type
+    #   @return [String]
+    # @!attribute [r] ttl
+    #   @return [Integer]
+    # @!attribute [r] name
+    #   @return [String]
+    # @!attribute [r] values
+    #   @return [Array<String>]
+    class RecordSet
+      include GandiV5::Data
+
+      member :type, gandi_key: 'rrset_type'
+      member :ttl, gandi_key: 'rrset_ttl'
+      member :name, gandi_key: 'rrset_name'
+      member :values, gandi_key: 'rrset_values'
+
+      # Generate zone file lines for the record.
+      # @return [String]
+      def to_s
+        values.map do |value|
+          "#{name}\t#{ttl}\tIN\t#{type}\t#{value}"
+        end.join("\n")
+      end
+
+      GandiV5::LiveDNS::RECORD_TYPES.each do |t|
+        # Check the record type.
+        # @return [Boolean]
+        define_method "#{t.downcase}?" do
+          type.eql?(t)
+        end
+      end
+
+      # Check the TTL's value in seconds.
+      # @param number [Integer] the number of second(s) to check against.
+      # @return [Boolean]
+      def second?(number = 1)
+        ttl == number
+      end
+      alias seconds? second?
+
+      # Check the TTL's value in minutes.
+      # @param number [Integer] the number of minute(s) to check against.
+      # @return [Boolean]
+      def minute?(number = 1)
+        ttl == number * 60
+      end
+      alias minutes? minute?
+
+      # Check the TTL's value in hours.
+      # @param number [Integer] the number of hour(s) to check against.
+      # @return [Boolean]
+      def hour?(number = 1)
+        ttl == number * 3_600
+      end
+      alias hours? hour?
+
+      # Check the TTL's value in days.
+      # @param number [Integer] the number of day(s) to check against.
+      # @return [Boolean]
+      def day?(number = 1)
+        ttl == number * 86_400
+      end
+      alias days? day?
+
+      # Check the TTL's value in weeks.
+      # @param number [Integer] the number of week(s) to check against.
+      # @return [Boolean]
+      def week?(number = 1)
+        ttl == number * 604_800
+      end
+      alias weeks? day?
+    end
+  end
+end

data/lib/gandi_v5/live_dns/zone/snapshot.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class GandiV5
+  class LiveDNS
+    class Zone
+      # A snapshot (backup) of a zone.
+      # @!attribute [r] uuid
+      #   @return [String]
+      # @!attribute [r] zone_uuid
+      #   @return [String]
+      # @!attribute [r] created_at
+      #   @return [Time]
+      # @!attribute [r] records
+      #   @return [Array<GandiV5::LiveDNS::RecordSet>]
+      class Snapshot
+        include GandiV5::Data
+
+        members :uuid, :zone_uuid
+        member :created_at, gandi_key: 'date_created', converter: GandiV5::Data::Converter::Time
+        member(
+          :records,
+          gandi_key: 'zone_data',
+          converter: GandiV5::LiveDNS::RecordSet,
+          array: true
+        )
+
+        alias snapshot_uuid uuid
+
+        # Delete this snapshot.
+        # @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
+
+        # Get snapshot from Gandi.
+        # @param zone_uuid [String, #to_s] the UUID of the zone the snapshot was made of.
+        # @param snapshot_uuid [String, #to_s] the UUID of the snapshot to fetch.
+        # @return [GandiV5::LiveDNS::Zone::Snapshot]
+        # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+        def self.fetch(zone_uuid, snapshot_uuid)
+          data = GandiV5.get url(zone_uuid, snapshot_uuid)
+          from_gandi data
+        end
+
+        # TODO: Move listing snapshots to here
+
+        private
+
+        def url
+          "#{BASE}zones/#{CGI.escape zone_uuid}/snapshots/#{CGI.escape uuid}"
+        end
+
+        def self.url(zone_uuid, snapshot_uuid)
+          "#{BASE}zones/#{CGI.escape zone_uuid}/snapshots/#{CGI.escape snapshot_uuid}"
+        end
+        private_class_method :url
+      end
+    end
+  end
+end

data/lib/gandi_v5/live_dns/zone.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require_relative 'zone/snapshot'
+
+class GandiV5
+  class LiveDNS
+    # A zone within the LiveDNS system.
+    # Zones can be used by any number of domains.
+    # @!attribute [r] uuid
+    #   @return [String]
+    # @!attribute [r] name
+    #   @return [String]
+    # @!attribute [r] sharing_uuid
+    #   @return [String]
+    # @!attribute [r] soa_retry
+    #   @return [Integer] retry period, as reported in SOA record.
+    # @!attribute [r] soa_minimum
+    #   @return [Integer] minimum and negative TTL, as reported in SOA record.
+    # @!attribute [r] soa_refresh
+    #   @return [Integer] refresh period, as reported in SOA record.
+    # @!attribute [r] soa_expire
+    #   @return [Integer] expire period, as reported in SOA record.
+    # @!attribute [r] soa_serial
+    #   @return [Integer] serial number, as reported in SOA record.
+    # @!attribute [r] soa_email
+    #   @return [String] admin email address, as reported in SOA record.
+    # @!attribute [r] soa_primary_ns
+    #   @return [String] primary name server, as reported in SOA record.
+    class Zone
+      include GandiV5::Data
+
+      members :uuid, :name
+      member :sharing_uuid, gandi_key: 'sharing_id'
+      member :soa_retry, gandi_key: 'retry'
+      member :soa_minimum, gandi_key: 'minimum'
+      member :soa_refresh, gandi_key: 'refresh'
+      member :soa_expire, gandi_key: 'expire'
+      member :soa_serial, gandi_key: 'serial'
+      member :soa_email, gandi_key: 'email'
+      member :soa_primary_ns, gandi_key: 'primary_ns'
+
+      alias zone_uuid uuid
+
+      # Generate SOA record for the zone
+      # @return [String]
+      def to_s
+        "@\tIN\tSOA\t#{soa_primary_ns} #{soa_email} (\n" \
+        "\t#{soa_serial}\t;Serial\n" \
+        "\t#{soa_refresh}\t\t;Refresh\n" \
+        "\t#{soa_retry}\t\t;Retry\n" \
+        "\t#{soa_expire}\t\t;Expire\n" \
+        "\t#{soa_minimum}\t\t;Minimum & Negative TTL\n" \
+        ')'
+      end
+
+      # @overload fetch_records()
+      #   Fetch all records for this zone.
+      # @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 zone.
+      # @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 zone.
+      # @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 zone.
+      # @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 zone.
+      # @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 zone.
+      # @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 zone.
+        # @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
+
+      # List the domains that use this zone.
+      # @return [Array<String>] The FQDNs.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def list_domains
+        data = GandiV5.get "#{url}/domains"
+        data.map { |item| item['fqdn'] }
+      end
+
+      # Attach domain to this zone.
+      # @param fqdn [String, #fqdn, #to_s] the fully qualified domain name
+      #   that should start using this zone.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def attach_domain(fqdn)
+        fqdn = fqdn.fqdn if fqdn.respond_to?(:fqdn)
+        data = GandiV5.patch "#{BASE}domains/#{CGI.escape fqdn}", { zone_uuid: uuid }.to_json
+        data['message']
+      end
+
+      # Get snapshot UUIDs for this zone from Gandi.lib/gandi_v5/domain/auto_renew.rb
+      # @return [Hash{String => Time}] Mapping UUID to time made.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def snapshots
+        data = GandiV5.get "#{url}/snapshots"
+        Hash[data.map { |snapshot| [snapshot['uuid'], Time.parse(snapshot['date_created'])] }]
+      end
+
+      # Get snapshot from Gandi.
+      # @param uuid [String] the UUID of the snapshot to fetch.
+      # @return [GandiV5::LiveDNS::Zone::Snapshot]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def snapshot(uuid)
+        GandiV5::LiveDNS::Zone::Snapshot.fetch self.uuid, uuid
+      end
+
+      # Take a snapshot of this zone.
+      # @return [GandiV5::LiveDNS::Zone::Snapshot]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def take_snapshot
+        data = GandiV5.post "#{url}/snapshots"
+        snapshot data['uuid']
+      end
+
+      # Update this zone.
+      # @param name [String, #to_s] new name for the zone.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def update(name:)
+        data = GandiV5.patch url, { name: name }.to_json
+        self.name = name
+        data['message']
+      end
+
+      # Delete this zone from Gandi.
+      # @return [nil]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def delete
+        GandiV5.delete url
+      end
+
+      # Create a new zone.
+      # @param name [String] the name for the created zone.
+      # @param sharing_id [String] the UUID of the account to ceate the zone under.
+      # @return [String] The confirmation message from Gandi.
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      # TODO: Fetch created zone
+      def self.create(name, sharing_id: nil)
+        params = sharing_id ? { sharing_id: sharing_id } : {}
+
+        data = GandiV5.post(
+          url,
+          { name: name }.to_json,
+          params: params
+        )
+        data['message']
+      end
+
+      # List the zones.
+      # @return [Array<GandiV5::LiveDNS::Zone>]
+      # @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 zone from Gandi.
+      # @param uuid [String, #to_s] the UUID of the zone to fetch.
+      # @return [GandiV5::LiveDNS::Zone]
+      # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+      def self.fetch(uuid)
+        data = GandiV5.get url(uuid)
+        from_gandi data
+      end
+
+      private
+
+      def url
+        "#{BASE}zones/#{CGI.escape uuid}"
+      end
+
+      def self.url(uuid = nil)
+        BASE + (uuid ? "zones/#{CGI.escape(uuid)}" : 'zones')
+      end
+      private_class_method :url
+    end
+  end
+end

data/lib/gandi_v5/live_dns.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Namespace for classes which access LiveDNS details.
+class GandiV5
+  # Gandi LiveDNS Management API.
+  class LiveDNS
+    BASE = 'https://dns.api.gandi.net/api/v5/'
+
+    RECORD_TYPES = %w[
+      A AAAA CNAME MX NS TXT ALIAS
+      WKS SRV LOC SPF CAA DS SSHFP PTR KEY DNAME TLSA OPENPGPKEY CDS
+    ].freeze
+
+    # Raise an error if passed type is invalid.
+    # @param type [String] the record type to check.
+    # @return [nil]
+    # @raise [ArgumentError]
+    # rubocop:disable Style/GuardClause
+    def self.require_valid_record_type(type)
+      unless RECORD_TYPES.include?(type)
+        fail ArgumentError, "type must be one of #{RECORD_TYPES.join(', ')}"
+      end
+    end
+    # rubocop:enable Style/GuardClause
+  end
+end
+
+require_relative 'live_dns/record_set'
+require_relative 'live_dns/domain'
+require_relative 'live_dns/zone'

data/lib/gandi_v5/organization.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'email/mailbox'
+require_relative 'email/offer'
+require_relative 'email/slot'
+
+class GandiV5
+  # The Organization API is a read-only API.
+  # All organization management must be performed via the web interface.
+  # @see https://api.gandi.net/docs/organization
+  # @!attribute [r] uuid
+  #   @return [String] the sharing uuid of the user.
+  # @!attribute [r] username
+  #   @return [String] the username of the user.
+  # @!attribute [r] name
+  #   @return [String] the sharing name of the user.
+  # @!attribute [r] first_name
+  #   @return [nil, String] the first name of the user.
+  # @!attribute [r] last_name
+  #   @return [nil, String] the last name of the user.
+  # @!attribute [r] lang
+  #   @return [String] language used by the user.
+  # @!attribute [r] street_address
+  #   @return [nil, String] the street address of the user.
+  # @!attribute [r] city
+  #   @return [String] the city name of the address.
+  # @!attribute [r] zip
+  #   @return [nil, String] zip code of the address.
+  # @!attribute [r] country
+  #   @return [nil, String] country ISO code of the address.
+  # @!attribute [r] email
+  #   @return [String] the email address of the user.
+  # @!attribute [r] phone
+  #   @return [nil, String] the phone number of the user.
+  # @!attribute [r] security_email
+  #   @return [String] email address used for security processes such as account recovery.
+  # @!attribute [r] security_phone
+  #   @return [nil, String]
+  #      phone number used for security recovery processes such as totp recovery.
+  # @!attribute [r] security_email_validated
+  #   @return [Boolean] state of the email validation process.
+  # @!attribute [r] security_email_validation_deadline
+  #   @return [Time] deadline for the email address validation process.
+  class Organization
+    include GandiV5::Data
+
+    members :username, :name, :lang, :city, :zip, :country, :email, :phone, :security_phone,
+            :security_email, :security_email_validated, :security_email_validation_deadline
+    member :uuid, gandi_key: 'id'
+    member :first_name, gandi_key: 'firstname'
+    member :last_name, gandi_key: 'lastname'
+    member :street_address, gandi_key: 'streetaddr'
+    member :security_email_validation_deadline, converter: GandiV5::Data::Converter::Time
+
+    alias organization_uuid uuid
+
+    # Get information about the current authenticated user.
+    # @see https://api.gandi.net/docs/organization#get-v5-organization-user-info
+    # @return [GandiV5::Organization]
+    # @raise [GandiV5::Error::GandiError::GandiError] if Gandi returns an error.
+    def self.fetch
+      data = GandiV5.get "#{BASE}organization/user-info"
+      from_gandi data
+    end
+  end
+end

data/lib/gandi_v5/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class GandiV5
+  VERSION = '0.1.0'
+end