gandi_v5 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bcedab1f98eded02f20893ca2f4b8c5a47abe1d72d3e055ef5688b2969104df
-  data.tar.gz: 6db74218bd3914c662c2b6cac47c76a4d9497368f80b3ef4f31ad7e6537604a5
+  metadata.gz: '00492db9ea48e7cd3d616485712dc3f0c9736cb12faebc0159de840285375d6a'
+  data.tar.gz: 79bb285c08c2851de059d69a91aa253ccea6b1b92ea6a42ca7226cb7ec9bf553
 SHA512:
-  metadata.gz: 29dad44ec126323a917bcc5c4ac8dd200e1acc7ac32cfdf7c4608a919dd872e9f2071031b371d7ad8bae8a2ed09e6bd2bf660d0095b59999859e91d180b53e70
-  data.tar.gz: 1d2c599205a31b449c003cf4e2628b0326cf90d45ae3c75a68356879e463ee708c6d81f5fb64e1ee75ffe73fbc5402cc3e2fc290fddfe6777c0fb304ccb45a8f
+  metadata.gz: aa18bb67286e8eb23eedbb76cddc973868054eb1499ae37e7cce920600211c26d9bed1a6fb62296df670daaddb2d712a74933f323752ec7e8c183628b8699494
+  data.tar.gz: 98a55427b458e40adb22ab8c3da8da6224c0614b1251ade51082a2a55d6837490788c95a9584cc8a00233f1b9f40f01e7ad6e06e6e8efe78b00cdd5e7554b467

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Gandi V5 API Gem Changelog
 
+## Version 0.9.0
+
+* Add transferring a domain to Gandi (I don't have any domains outside Gandi to test this myself so it's possible I've misread the docs and a bug is waiting to be found, please add an issue if I have):
+  * GandiV5::Domain::TransferIn:
+    * .create(fqdn, \*\*options)
+    * .fetch(fqdn)
+    * .relaunch(fqdn)
+    * .resend_foa_emails(fqdn, email_address)
+    * \#relaunch
+    * \#resend_foa_emails(email_address)
+  * GandiV5::Domain::TransferIn::Availabillity:
+    * .fetch(fqdn, auth_code = nil)
+* Documentation improvements
+
 ## Version 0.8.0
 
 * Domain:
@@ -21,15 +35,15 @@
     * .list now returns an array of strings
     * Can no longer change the zone used by a domain
     * Added automatic_snapshots attribute for whether snapshots are automatically created when a modification is made to this domain's records
-    * #replace_records and #replace_records_for merged into #replace_records
+    * \#replace_records and \#replace_records_for merged into \#replace_records
       * If replacing with a zone file use the new #replace_zone_lines
     * Added:
       * .create
       * .record_types
       * .generic_name_servers(fqdn)
-      * #name_servers and #fetch_name_servers
-      * #tsig_keys, #fetch_tsig_keys, #add_tsig_key, #remove_tsig_key
-      * #axfr_clients, #fetch_axfr_clients, #add_axfr_client, #remove_axfr_client
+      * \#name_servers and #fetch_name_servers
+      * \#tsig_keys, #fetch_tsig_keys, \#add_tsig_key, \#remove_tsig_key
+      * \#axfr_clients, #fetch_axfr_clients, #add_axfr_client, \#remove_axfr_client
       * ::DnssecKeys, #dnssec_keys, #fetch_dnssec_keys
   * Snapshots:
     * Moved to live under LiveDNS::Domain not LiveDNS::Zone
@@ -79,11 +93,11 @@
 ## Version 0.2.0
 
 * Enhancements to GandiV5::Domain
-  * .availability(fqdn, **options) moved to GandiV5::Domain::Availability.fetch(fqdn, **options)
+  * .availability(fqdn, \*\*options) moved to GandiV5::Domain::Availability.fetch(fqdn, \*\*options)
   * .create now returns created domain (except in dry-run mode)
   * .tlds moved to GandiV5::Domain::TLD.list
   * .tld(name) moved to GandiV5::Domain::TLD.fetch(name)
-  * #renewal_price(currency: 'GBP', period: 1) added
+  * \#renewal_price(currency: 'GBP', period: 1) added
 * Enhancements to GandiV5::Email::Mailbox
   * .create now returns created mailbox
   * .create now checks for available slots and a valid type has been passed
@@ -92,14 +106,14 @@
   * Add #disable to disable the auto responder in Gandi
 * Enhancements to GandiV5::Email::Slot
   * .create now returns created slot
-  * #delete now checks for inactiveness and refundableness
+  * \#delete now checks for inactiveness and refundableness
 * Enhancements to GandiV5::LiveDNS::Domain
   * Add #zone and #fetch_zone
-  * Remove #replace_*_records_for methods
+  * Remove #replace_\*_records_for methods
   * Changes to #replace_records_for to allow calling with name, type, ttl and values. When calling with name and fecords records MUST be passed as an array.
 * Enhancements to GandiV5::LiveDNS::Zone
   * .create now returns created zone
-  * Remove #replace_*_records_for methods
+  * Remove #replace_\*_records_for methods
   * Changes to #replace_records_for to allow calling with name, type, ttl and values. When calling with name and fecords records MUST be passed as an array.
 * Enhancements to GandiV5::LiveDNS::Zone::Snapshot
   * Add .list

data/README.md

@@ -1,8 +1,7 @@
 [![Gem Version](https://badge.fury.io/rb/gandi_v5.png)](http://badge.fury.io/rb/gandi_v5)
-[![Build Status](https://secure.travis-ci.org/robertgauld/gandi_v5.png?branch=master)](http://travis-ci.org/robertgauld/gandi_v5)
-[![Coveralls Status](https://coveralls.io/repos/robertgauld/gandi_v5/badge.png?branch=master)](https://coveralls.io/r/robertgauld/gandi_v5)
-[![Code Climate](https://codeclimate.com/github/robertgauld/gandi_v5.png?branch=master)](https://codeclimate.com/github/robertgauld/gandi_v5)
-[![security](https://hakiri.io/github/robertgauld/gandi_v5/master.svg)](https://hakiri.io/github/robertgauld/gandi_v5/master)
+[![Build Status](https://secure.travis-ci.org/robertgauld/gandi_v5.png?branch=main)](http://travis-ci.org/robertgauld/gandi_v5)
+[![Coveralls Status](https://coveralls.io/repos/robertgauld/gandi_v5/badge.png?branch=main)](https://coveralls.io/r/robertgauld/gandi_v5)
+[![Code Climate](https://codeclimate.com/github/robertgauld/gandi_v5.png?branch=main)](https://codeclimate.com/github/robertgauld/gandi_v5)
 
 ## Ruby Versions
 This gem supports the following versions of ruby, it may work on other versions but is not tested against them so don't rely on it.
@@ -25,23 +24,24 @@ Gandi say: **_"Please note that this API is currently in BETA testing, so care s
 
 But then you were going to be careful anyway as this gem is currently in the version 0.something range weren't you!
 
-Details of the API can be found at:
+Details of Gandi's API can be found at:
 
 * <https://api.gandi.net/docs/>
 * <https://doc.livedns.gandi.net/>
 
+Details of the gem's API can be found at <https://rubydoc.info/github/robertgauld/gandi_v5/main>
 
 ## Installation
 
 If you're using bundler then add it to your Gemfile and run the bundle command.
 
 ```ruby
-gem 'gandi_v5', '~> 0.7'
+gem 'gandi_v5', '~> 0.8'
 ```
 
 If you're not using bundler then install it from the command line.
 ```bash
-gem install gandi_v5 -v '~> 0.7'
+gem install gandi_v5 -v '~> 0.8'
 ```
 
 ## Usage
@@ -58,6 +58,52 @@ GandiV5.api_key = '…' # Unless you've set it in the environment variable GANDI
 
 ### Examples
 
+#### List renewal dates and costs for all domains
+```ruby
+# For each domain (sorted by assending renewal date) print <date>\t<cost>\t<fqdn>
+GandiV5::Domain.list.each do |domain|
+  puts [
+    domain.dates.registry_ends_at.to_date,
+    "£#{domain.renewal_price.price_after_taxes}",
+    domain.fqdn
+  ].join("\t")
+end
+```
+
+#### List email addresses for all domains
+
+```ruby
+# For each domain:
+#   1. Create an empty hash to store address => description
+#   2. Get the mailboxes and add them to the hash
+#   3. Get the forwards and add them to the hash
+#   4. Sort the hash by email address
+#   5. Print the list
+GandiV5::Domain.list.each do |domain|
+  emails = {}
+
+  mailboxes = GandiV5::Email::Mailbox.list(domain.fqdn)
+  mailboxes.each do |mailbox|
+    mailbox.refresh
+    emails["#{mailbox.login}@#{domain.fqdn}"] = "#{mailbox.type} mailbox " \
+                                         "(#{mailbox.quota_usage.to_i}% " \
+                                         "of #{(mailbox.quota / 1024**3).round}GB used)"
+    mailbox.aliases.each do |alias_name|
+      emails["#{alias_name}@#{domain.fqdn}"] = "alias for #{mailbox.login}@#{domain.fqdn}"
+    end
+  end
+
+  forwards = GandiV5::Email::Forward.list(domain.fqdn)
+  forwards.each do |forward|
+    emails["#{forward.source}@#{domain.fqdn}"] = "forwards to #{forward.destinations.join(', ')}"
+  end
+
+  emails.sort.each do |address, text|
+    puts "#{address}\t#{text}"
+  end
+end
+```
+
 #### Domains
 
 ```ruby
@@ -68,15 +114,13 @@ domains = GandiV5.domains
 domains.map!(&:refresh)
 ```
 
-TODO: More examples!
-
-
 ## Versioning
 
 We follow the [Semantic Versioning](http://semver.org/) concept.
 
 | Gem Version     | Gandi API Release Date   |
 | --------------- | ------------------------ |
+| 0.9.0           | 2020-07-29               |
 | 0.8.0           | 2020-07-10               |
 | 0.7.0           | 2020-05-07               |
 | 0.6.0           | 2020-05-07 (not LiveDNS) |

data/lib/gandi_v5.rb

@@ -5,11 +5,12 @@ require 'securerandom'
 require 'zeitwerk'
 
 # Custom inflector for Zeitwerk.
+# @api private
 class MyInflector < Zeitwerk::Inflector
   # Convert file's base name to class name when
   # Zeitwerk's included inflector gets it wrong.
   # @param basename [String] the file's base name (no path or extension)
-  # @param abspath [String] the file's absolute path
+  # @param _abspath [String] the file's absolute path
   # @return [String] the class name
   def camelize(basename, _abspath)
     case basename
@@ -31,32 +32,37 @@ loader.setup
 
 # Namespace for classes which access the Gandi V5 API.
 # Also provides useful methods and constants for them.
-# This is where you configure the gem:
-#  * Setting your Gandi API key:
-#    1. Get your API key - Login to Gandi and visit User Settings ->
-#       Change password & configure access restrictions.
+# To get your API key login to Gandi and visit
+# "User Settings" -> "Change password & configure access restrictions".
+# Set your API key either in the GANDI_API_KEY environment variable or
+# by setting the api_key class attribute.
 # @see https://api.gandi.net/docs/
 # @see https://doc.livedns.gandi.net/
 # @!attribute [w] api_key
 #   @return [String]
 class GandiV5
+  # Base URL for all API requests.
   BASE = 'https://api.gandi.net/v5/'
 
+  # Get information on a domain.
   # @see GandiV5::Domain.fetch
   def self.domain(fqdn)
     GandiV5::Domain.fetch(fqdn)
   end
 
+  # Get information on all domains.
   # @see GandiV5::Domain.list
   def self.domains(**params)
     GandiV5::Domain.list(**params)
   end
 
+  # List mailboxes for a domain.
   # @see GandiV5::Email::Mailbox.list
   def self.mailboxes(fqdn, **params)
     GandiV5::Email::Mailbox.list(fqdn, **params)
   end
 
+  # List email slots for a domain.
   # @see GandiV5::Email::Slot.list
   def self.mailbox_slots(fqdn)
     GandiV5::Email::Slot.list(fqdn)
@@ -65,15 +71,21 @@ class GandiV5
   class << self
     attr_writer :api_key
 
-    # Might raise:
-    #  * RestClient::NotFound
-    #  * RestClient::Unauthorized
-    #      Bad authentication attempt because of a wrong API Key.
-    #  * RestClient::Forbidden
-    #      Access to the resource is denied.
-    #      Mainly due to a lack of permissions to access it.
-    #  * GandiV5::Error
-    #  * JSON::ParserError
+    # Make a GET request to a Gandi end point.
+    # @param url [String, #to_s]
+    #   the full URL (including GandiV5::BASE) to fetch.
+    # @param headers [Hash{String, Symbol, #to_s => String, Symbol, #to_s}]
+    #   the headers to send in the request, the authorisation will be added.
+    # @return [Array<(RestClient::Response, Object)>]
+    #   The response from the server and the result of parsing the responce's body.
+    # @raise [RestClient::NotFound]
+    # @raise [RestClient::Unauthorized]
+    #   Bad authentication attempt because of a wrong API Key.
+    # @raise [RestClient::Forbidden]
+    #   Access to the resource is denied.
+    #   Mainly due to a lack of permissions to access it.
+    # @raise [GandiV5::Error]
+    # @raise [JSON::ParserError]
     def get(url, **headers)
       prepare_headers headers, url
       response = RestClient.get url, **headers
@@ -82,15 +94,23 @@ class GandiV5
       handle_bad_request(e)
     end
 
-    # Might raise:
-    #  * RestClient::NotFound
-    #  * RestClient::Unauthorized
-    #      Bad authentication attempt because of a wrong API Key.
-    #  * RestClient::Forbidden
-    #      Access to the resource is denied.
-    #      Mainly due to a lack of permissions to access it.
-    #  * GandiV5::Error
-    #  * JSON::ParserError
+    # Make a GET request to a paginated end point at Gandi.
+    # @param url [String, #to_s]
+    #   the full URL (including GandiV5::BASE) to fetch.
+    # @param page [#each, Integer] the page/pages of results to get.
+    # @param per_page [Integer, #to_s] the number of items to get per page of results.
+    # @param headers [Hash{String, Symbol, #to_s => String, Symbol, #to_s}]
+    #   the headers to send in the request, the authorisation will be added.
+    # @return [Array<(RestClient::Response, Object)>]
+    #   The response from the server and the result of parsing the responce's body.
+    # @raise [RestClient::NotFound]
+    # @raise [RestClient::Unauthorized]
+    #   Bad authentication attempt because of a wrong API Key.
+    # @raise [RestClient::Forbidden]
+    #   Access to the resource is denied.
+    #   Mainly due to a lack of permissions to access it.
+    # @raise [GandiV5::Error]
+    # @raise [JSON::ParserError]
     def paginated_get(url, page = (1..), per_page = 100, **headers)
       unless page.respond_to?(:each)
         fail ArgumentError, 'page must be positive' unless page.positive?
@@ -112,16 +132,21 @@ class GandiV5
       end
     end
 
-    # Might raise:
-    #  * RestClient::NotFound
-    #  * RestClient::Unauthorized
-    #      Bad authentication attempt because of a wrong API Key.
-    #  * RestClient::Forbidden
-    #      Access to the resource is denied.
-    #      Mainly due to a lack of permissions to access it.
-    #  * RestClient::Conflict
-    #  * GandiV5::Error
-    #  * JSON::ParserError
+    # Make a DELETE request to a Gandi end point.
+    # @param url [String, #to_s]
+    #   the full URL (including GandiV5::BASE) to fetch.
+    # @param headers [Hash{String, Symbol, #to_s => String, Symbol, #to_s}]
+    #   the headers to send in the request, the authorisation will be added.
+    # @return [Array<(RestClient::Response, Object)>]
+    #   The response from the server and the result of parsing the responce's body.
+    # @raise [RestClient::NotFound]
+    # @raise [RestClient::Unauthorized]
+    #   Bad authentication attempt because of a wrong API Key.
+    # @raise [RestClient::Forbidden]
+    #   Access to the resource is denied.
+    #   Mainly due to a lack of permissions to access it.
+    # @raise [GandiV5::Error]
+    # @raise [JSON::ParserError]
     def delete(url, **headers)
       prepare_headers headers, url
       response = RestClient.delete url, **headers
@@ -133,17 +158,24 @@ class GandiV5
       handle_bad_request(e)
     end
 
-    # Might raise:
-    #  * RestClient::NotFound
-    #  * RestClient::Unauthorized
-    #      Bad authentication attempt because of a wrong API Key.
-    #  * RestClient::Forbidden
-    #      Access to the resource is denied.
-    #      Mainly due to a lack of permissions to access it.
-    #  * RestClient::BadRequest
-    #  * RestClient::Conflict
-    #  * GandiV5::Error
-    #  * JSON::ParserError
+    # Make a PATCH request to a Gandi end point.
+    # @param url [String, #to_s]
+    #   the full URL (including GandiV5::BASE) to fetch.
+    # @param payload [String, #to_s] the body for the request.
+    # @param headers [Hash{String, Symbol, #to_s => String, Symbol, #to_s}]
+    #   the headers to send in the request, the authorisation will be added.
+    # @return [Array<(RestClient::Response, Object)>]
+    #   The response from the server and the result of parsing the responce's body.
+    # @raise [RestClient::NotFound]
+    # @raise [RestClient::Unauthorized]
+    #   Bad authentication attempt because of a wrong API Key.
+    # @raise [RestClient::Forbidden]
+    #   Access to the resource is denied.
+    #   Mainly due to a lack of permissions to access it.
+    # @raise [RestClient::BadRequest]
+    # @raise [RestClient::Conflict]
+    # @raise [GandiV5::Error]
+    # @raise [JSON::ParserError]
     def patch(url, payload = '', **headers)
       prepare_headers headers, url
       headers[:'content-type'] ||= 'application/json'
@@ -153,17 +185,24 @@ class GandiV5
       handle_bad_request(e)
     end
 
-    # Might raise:
-    #  * RestClient::NotFound
-    #  * RestClient::Unauthorized
-    #      Bad authentication attempt because of a wrong API Key.
-    #  * RestClient::Forbidden
-    #      Access to the resource is denied.
-    #      Mainly due to a lack of permissions to access it.
-    #  * RestClient::BadRequest
-    #  * RestClient::Conflict
-    #  * GandiV5::Error
-    #  * JSON::ParserError
+    # Make a POST request to a Gandi end point.
+    # @param url [String, #to_s]
+    #   the full URL (including GandiV5::BASE) to fetch.
+    # @param payload [String, #to_s] the body for the request.
+    # @param headers [Hash{String, Symbol, #to_s => String, Symbol, #to_s}]
+    #   the headers to send in the request, the authorisation will be added.
+    # @return [Array<(RestClient::Response, Object)>]
+    #   The response from the server and the result of parsing the responce's body.
+    # @raise [RestClient::NotFound]
+    # @raise [RestClient::Unauthorized]
+    #   Bad authentication attempt because of a wrong API Key.
+    # @raise [RestClient::Forbidden]
+    #   Access to the resource is denied.
+    #   Mainly due to a lack of permissions to access it.
+    # @raise [RestClient::BadRequest]
+    # @raise [RestClient::Conflict]
+    # @raise [GandiV5::Error]
+    # @raise [JSON::ParserError]
     def post(url, payload = '', **headers)
       prepare_headers headers, url
       headers[:'content-type'] ||= 'application/json'
@@ -173,17 +212,24 @@ class GandiV5
       handle_bad_request(e)
     end
 
-    # Might raise:
-    #  * RestClient::NotFound
-    #  * RestClient::Unauthorized
-    #      Bad authentication attempt because of a wrong API Key.
-    #  * RestClient::Forbidden
-    #      Access to the resource is denied.
-    #      Mainly due to a lack of permissions to access it.
-    #  * RestClient::BadRequest
-    #  * RestClient::Conflict
-    #  * GandiV5::Error
-    #  * JSON::ParserError
+    # Make a PUT request to a Gandi end point.
+    # @param url [String, #to_s]
+    #   the full URL (including GandiV5::BASE) to fetch.
+    # @param payload [String, #to_s] the body for the request.
+    # @param headers [Hash{String, Symbol, #to_s => String, Symbol, #to_s}]
+    #   the headers to send in the request, the authorisation will be added
+    # @return [Array<(RestClient::Response, Object)>]
+    #   The response from the server and the result of parsing the responce's body.
+    # @raise [RestClient::NotFound]
+    # @raise [RestClient::Unauthorized]
+    #   Bad authentication attempt because of a wrong API Key.
+    # @raise [RestClient::Forbidden]
+    #   Access to the resource is denied.
+    #   Mainly due to a lack of permissions to access it.
+    # @raise [RestClient::BadRequest]
+    # @raise [RestClient::Conflict]
+    # @raise [GandiV5::Error]
+    # @raise [JSON::ParserError]
     def put(url, payload = '', **headers)
       prepare_headers headers, url
       headers[:'content-type'] ||= 'application/json'

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?