gandi_v5 0.5.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eac7a49d78a12be6f28ce2a12aab37a8fcbe25e24ffd40f215a7bf088df81125
-  data.tar.gz: bb0e28904dc4869a6846c6cd4204b7c9c9e97937f9a1d7ef9dcbf1ceef7b7ea2
+  metadata.gz: 4bfa3d695cec03737e8e5c3639c7744300babd00d59081f4edf14f013d2e9787
+  data.tar.gz: ce687383ed1d014889d22e9d33a068dad8a8dc8ec2a73a38c9150014195a3f0b
 SHA512:
-  metadata.gz: 3fa831c1c527c6b06f97627d36ba3085586f5675690ff120a075f9a88a24bde2493d83c4b7b04803e00295459af2a49f92e049f0172af288634c04d32d4c1f6c
-  data.tar.gz: 7116bae0e14637e37ff361e530d711a3d2d68177554df107963a020049746b955cc9cfbb61e9dca5ad354ced47b5d88d4c3047ec2a3b7f9d4bf8005426b1ebdc
+  metadata.gz: a2752f84704fbd326503b2bada3e3193d2215abc6c19e1b71198b29eabaf4e67f473249d076aa806ca2c937195a35c7d2a8c490e1f586d0c3f121be5900c1ae5
+  data.tar.gz: 398dc026b251a700432dee898e23c207bee4fa10c5bcc879f706f0e9c0ed0793d3b670861b97221bd4f64bfbfd27c32a589b5b7eeb911662b95623461ec90f59

data/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Gandi V5 API Gem Changelog
 
+## Version 0.9.1
+
+* Add testing against ruby 2.7.2 and 3.0.0
+
+## 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:
+  * .list - add resellee_id filter
+* Added simple hosting: (I don't use simple hosting 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)
+  * SimpleHosting::Instance
+  * SimpleHosting::Instance::VirtualHost
+  * SimpleHosting::Instance::Application
+  * SimpleHosting::Instance::Database
+  * SimpleHosting::Instance::Language
+  * SimpleHosting::Instance::Upgrade
+* GandiV5::Domain::SharingSpace moved to GandiV5::SharingSpace
+
+## Version 0.7.0
+
+* LiveDNS:
+  * Rename LiveDNS::RecordSet to LiveDNS::Domain::Record
+  * Domains:
+    * .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
+      * 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
+      * ::DnssecKeys, #dnssec_keys, #fetch_dnssec_keys
+  * Snapshots:
+    * Moved to live under LiveDNS::Domain not LiveDNS::Zone
+    * Are now accessed via the fully qualified domain name NOT the zone's UUID
+    * Ability to access the zone from a snapshot is removed
+    * Taking a snapshot now allows for named snapshots
+    * Added automatic attribute for when a snapshot was taken due to a zone change
+    * .list now returns an array of snapshots (records are fetched in a seperate request when first needed)
+  * Zone removed.
+
+## Version 0.6.0
+
+* GandiV5::Email::Slot.create now supports sharing_id
+* GandiV5::Email::Slot.create's type argument is now named not positional
+* Add reseller information to GandiV5::Domain
+
 ## Version 0.5.0
 
 * Add support for truffleruby 20.1.0
@@ -33,11 +97,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
@@ -46,14 +110,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/LICENSE.md

@@ -1,14 +1,10 @@
-##Copyright
-Copyright (c) 2018, Robert Gauld. All rights reserved.
-
-
-##License
+## License
 This code can be used under the BSD License (reproduced below).
 Commiters to the project give Robert Gauld the right to redistribute their commits
 under the BSD license.
 
 
-###BSD License
+### BSD License
 Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:
 

data/README.md

@@ -1,16 +1,16 @@
 [![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.
 
 * ruby:
   * 2.6.0 - 2.6.6
-  * 2.7.0 - 2.7.1
-  * truffleruby 20.1.0
+  * 2.7.0 - 2.7.2
+  * 3.0.0
+  * truffleruby 20.1.0 - 20.2.0
 * jruby, once it's reached parity with ruby 2.6.x
 * rubinius, once it's reached parity with ruby 2.6.x
 
@@ -25,23 +25,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.1'
+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.1'
+gem install gandi_v5 -v '~> 0.8'
 ```
 
 ## Usage
@@ -58,6 +59,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,19 +115,21 @@ 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.4.0           | 2019-10-01             |
-| 0.3.0           | 2019-08-22             |
-| 0.2.0           | 2019-05-16             |
-| 0.1.0           | 2019-05-16             |
+| 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) |
+| 0.5.0           | 2019-10-01               |
+| 0.4.0           | 2019-10-01               |
+| 0.3.0           | 2019-08-22               |
+| 0.2.0           | 2019-05-16               |
+| 0.1.0           | 2019-05-16               |
 
 See <https://api.gandi.net/docs/reference#API-Changelog> to find out what
 Gandi changed on each date.

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,16 +94,59 @@ 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::Conflict
-    #  * 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?
+
+        page = [page]
+      end
+
+      headers[:params] ||= {}
+      headers[:params].transform_keys!(&:to_s)
+      headers[:params]['per_page'] = per_page
+
+      page.each do |page_number|
+        headers[:params]['page'] = page_number
+        _resp, this_data = get(url, **headers)
+        break if this_data.empty?
+
+        yield this_data
+        break if this_data.count < per_page
+      end
+    end
+
+    # 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
@@ -103,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'
@@ -123,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'
@@ -143,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'
@@ -169,16 +245,6 @@ class GandiV5
       @api_key ||= ENV.fetch('GANDI_API_KEY')
     end
 
-    def authorisation_header(url)
-      if url.start_with?(BASE)
-        { Authorization: "Apikey #{api_key}" }
-      elsif url.start_with?(GandiV5::LiveDNS::BASE)
-        { 'X-Api-Key': api_key }
-      else
-        fail ArgumentError, "Don't know how to authorise for url: #{url}"
-      end
-    end
-
     def parse_response(response)
       type = response.headers.fetch(:content_type).split(';').first.chomp
       case type
@@ -196,10 +262,11 @@ class GandiV5
       end
     end
 
-    def prepare_headers(headers, url)
-      headers.transform_keys!(&:to_sym)
+    def prepare_headers(headers, _url)
+      headers.transform_keys! { |key| key.to_s.downcase.to_sym }
       headers[:accept] ||= 'application/json'
-      headers.merge!(authorisation_header(url))
+      headers[:authorization] = "Apikey #{api_key}"
+      headers
     end
 
     def handle_bad_request(exception)