dnsmadeeasy 0.1.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e64f1077e858bdf6f2f0610f25435d4a5e47ba76
-  data.tar.gz: b9960e5fc0e030d18bd0cb94688ca7d816ea8547
+  metadata.gz: f3fe4a8e5e7490cd827fe1c39b7cb9eec1458ee6
+  data.tar.gz: 6b3f939c99808e319bcd77a4f77f34a456a3957f
 SHA512:
-  metadata.gz: '08d663e73e365d22490e6066e94342aedc03519ad40a2a7ce99909a7b6369aa5344d6697c0410c5a8e6bb2e4935c3eaabdf78d862a6132be837a43ed4c2311e6'
-  data.tar.gz: 8f6b7e12f70dafd2ec645ef21edad1dc81af84b69fa8193996060d0dd06dac71ed2bd27c9e23827f4225368408a88b6275b1ec734b4c21ca629bfee44b17ef6f
+  metadata.gz: ceed4e0e1ac07e7047ba55b39e723c6203c050add20167419f200ef2be3c513400b6a9b628c496bf7ab5e6177cd52be072213fcaa7edecf231bd0c19772b8613
+  data.tar.gz: 5d33110950c9d523d9c7a25bd4f57f3cef57f42a788d8f138374d67dfb1bbf991850f3133b0e994c79c6c08a7ec9bd136b2b48736193a1a08b37550cba80abb9

data/README.md

@@ -18,28 +18,28 @@ Once you have the key and the secret, you have several choices:
 
   1. Perhaps the most conveniently, you can store them in a small YAML file, that must be placed in a specific location within your home folder:  `~/.dnsmadeeasy/credentials.yml`. The file should look like this one below (NOTE: these are not real credentials, btw):
 
-    ```yaml
-    # file: ~/.dnsmadeeasy/credentials.yml
-    credentials:
-      api_key: 2062259f-f666b17-b1fa3b48-042ad4030
-      api_secret: 2265bc3-e31ead-95b286312e-c215b6a0
-    ```
+      ```yaml
+      # file: ~/.dnsmadeeasy/credentials.yml
+      credentials:
+        api_key: 2062259f-f666b17-b1fa3b48-042ad4030
+        api_secret: 2265bc3-e31ead-95b286312e-c215b6a0
+      ```
 
-    With this file existing, you can query right away, by using the shortcut module `DME`, such as         
+      With this file existing, you can query right away, by using the shortcut module `DME`, such as         
 
-    ```ruby
-    require 'dnsmadeeasy/dme' # this loads a `DME` shortcut.
-    DME.domains.data.first.name #=> 'moo.gamespot.com'
-    ```
+      ```ruby
+      require 'dme'
+      DME.domains.data.first.name #=> 'moo.gamespot.com'
+      ```
 
   2. Or, you can directly instantiate a new instance of the `Client` class, by passing your API key and API secrets as arguments:
 
-     ```ruby
-     require 'dnsmadeeasy'
-     @client = DnsMadeEasy::Api::Client.new(api_key, api_secret)
-     ```
+      ```ruby
+      require 'dnsmadeeasy'
+      @client = DnsMadeEasy::Api::Client.new(api_key, api_secret)
+      ```
 
-     The advantage of this method is that you can query multiple DnsMadeEasy accounts from the same Ruby VM. With other methods, only one account can be connected to.
+      The advantage of this method is that you can query multiple DnsMadeEasy accounts from the same Ruby VM. With other methods, only one account can be connected to.
 
   3. Or, you can use the `DnsMadeEasy.configure` method to configure the key/secret pair, and then use `DnsMadeEasy` namespace to call the methods:
 
@@ -54,25 +54,40 @@ Once you have the key and the secret, you have several choices:
      DnsMadeEasy.domains.data.first.name #=> 'moo.gamespot.com'     
      ```
 
-### Shortcut Module `DME` and `DnsMadeEasy` Namespaces
+### Which Namespace to Use? What is `DME` versus `DnsMadeEasy`?
+
+Since `DnsMadeEasy` is a bit of a mouthful, we decided to offer (in addition to the standard `DnsMadeEasy` namespace) the abbreviated module `DME` that simply forwards all messages to the module `DnsMadeEasy`. If in your Ruby VM there is no conflicting top-level class `DME`, then you can `require 'dnsmadeeasy/dme'` to get all of the DnsMadeEasy client library functionality without having to type the full name once. You can even do `require 'dme'`.
 
-Since `DnsMadeEasy` is a bit of a mouthful, we decided to offer (in addition) the abbreviated module `DME` that simply forwards all method calls to `DnsMadeEasy`. You can now `require 'dme'` to get all of the DnsMadeEasy client library loaded up, assuming it does not clash with any other `dme` file in your project.
+Whenever you require `dme` you also import the `DnsMadeEasy` namespace.  **The opposite is not true.** 
 
-And then you can use `DME.method(*args)` as you would on `DnsMadeEasy.method(*args)` or on the instance of the actual worker-horse class of this library, the gorgeous blone with a very long name: `DnsMadeEasy::Api::Client`.
+So if you DO have a name clash with another top-level module `DME`, simply do `require 'dnsmadeeasy'` and none of the `DME` module namespace will be loaded.
 
+In a nutshell you have three ways to access all methods provided by the [`DnsMadeEasy::Api::Client`](http://www.rubydoc.info/gems/dnsmadeeasy/DnsMadeEasy/Api/Client) class:
+
+ 1. Instantiate and use the client class directly,
+ 2. Use the top-level module `DnsMadeEasy` with `require 'dnsmadeeasy'`
+ 3. Use the shortened top-level module `DME` with `require 'dnsmadeeasy/dme'`
 
 ### Examples
 
-If you are not planning on accessing more than one DnsMadeEasy account from the same Ruby VM, it's recommended to save the credentials in the above mentioned file. **DO NOT check that file into any repository.**
+If you are planning on accessing *only one DnsMadeEasy account from the same Ruby VM*, it's recommended that you save your credentials (the API key and the secret) in the above mentioned file `~/.dnsmadeeasy/credentials.yml`.
 
-Assuming my credentials are stored, I can access everything about my domains as follows (let's pretend that I own a bunch of `gamespot` domains):
+___
 
+> **NOTE:**
+> 
+> * DO NOT check that file into your repo!  
+> * The examples that follow assume credentials have been read from that file.
 
-```ruby
+___
 
+Using the `DME` module (or `DnsMadeEasy` if you prefer) you can access all of your records through the available API method calls, for example:
 
-IRB(main):003:0> require 'dme' #=> true
-IRB(main):003:0> DME.domains.data.map(&:name)
+```ruby
+IRB > require 'dme' #=> true
+# Or you can also do
+IRB > require 'dnsmadeeasy/dme' #=> true
+IRB > DME.domains.data.map(&:name)
  ⤷ ["demo.gamespot.systems",
       "dev.gamespot.systems",
              "gamespot.live",
@@ -80,41 +95,86 @@ IRB(main):003:0> DME.domains.data.map(&:name)
      "prod.gamespot.systems"
    ]
 
-IRB(main):008:0> DME.api_key
+# These have been read from the file ~/.dnsmadeeasy/credentials.yml
+IRB > DME.api_key
  ⤷ "2062259f-f666b17-b1fa3b48-042ad4030"
 
-IRB(main):009:0> DME.api_secret
+IRB > DME.api_secret
  ⤷ "2265bc3-e31ead-95b286312e-c215b6a0"
+ 
+IRB > DME.domain('gamespot.live').delegateNameServers
+ ⤷ #<Hashie::Array ["ns-125-c.gandi.net.", "ns-129-a.gandi.net.", "ns-94-b.gandi.net."]>
 
-IRB(main):010:0> @client = DME.client
+# Let's inspect the Client — after all, all methods are simply delegated to it:
+IRB > @client = DME.client
  ⤷ #<DnsMadeEasy::Api::Client:0x00007fb6b416a4c8
     @api_key="2062259f-f666b17-b1fa3b48-042ad4030",
     @api_secret="2265bc3-e31ead-95b286312e-c215b6a0",
     @options={},
     @requests_remaining=149,
     @request_limit=150,
-    @base_uri="https://api.dnsmadeeasy.com/V2.0">
+    @base_uri="https://api.dnsmadeeasy.com/V2.0"> 
 ```
 
-### Return Values
+Next, let's fetch a particular domain, get it's records and compute the counts for each record type, such as 'A', 'NS', etc.
 
-Whever DnsMadeEasy returns is typically a Hash, but we wrap it in a [`Hashie::Mash`](https://github.com/intridea/hashie) instance, which offers some additional benefits, such as the ability to call nested values via method calls instead of using square brackets. You can always call either `to_hash` or `to_h` on an instance of a `Hashie::Mash` to get a pure hash representation.
+```ruby
+IRB > records = DME.records_for('gamespot.com')
+IRB > [ records.totalPages, records.totalRecords ]
+ ⤷ [1, 33]
+IRB > records.data.select{|f| f.type == 'A' }.map(&:name)
+ ⤷ ["www", "vpn-us-east1", "vpn-us-east2", "staging", "yourmom"]
+IRB > types = records.data.map(&:type)
+ ⤷ [....]
+IRB > require 'awesome_print' 
+IRB > ap Hash[types.group_by {|x| x}.map {|k,v| [k,v.count]}]
+{
+       "MX" => 2,
+      "TXT" => 1,
+    "CNAME" => 3,
+       "NS" => 22,
+        "A" => 5
+}
+```
+
+### Return Value Types
+
+All public methods of this library return a Hash-like object, that is actually an instance of the class [`Hashie::Mash`](https://github.com/intridea/hashie). `Hashie::Mash` supports the very useful ability to reach deeply nested hash values via a chain of method calls instead of using a train of square brackets. You can always convert it to a regular hash either `to_hash` or `to_h` on an instance of a `Hashie::Mash` to get a pure hash representation.
 
-All return values are the direct JSON responses from DNS Made Easy converted into a Hash.
+> NOTE: `to_hash` converts the entire object to a regular hash, including the deeply nested hashes, while `to_h` only converts the primary object, but not the nested hashes. Here is an example below — in the first instance where we call `to_h` we are still able to call `.value` on the nested object, because only the top-level `Mash` has been converted into a `Hash`. In the second example, this call fails, because this method does not exist, and the value must be accessed via the square brackets:
+> 
+> ```ruby
+> IRB > recs.to_h['data'].last.value
+>  ⤷ "54.200.26.233"
+> IRB > recs.to_hash['data'].last.value
+> "NoMethodError: undefined method `value` for #<Hash:0x00007fe36fab0f68>"
+> IRB > recs.to_hash['data'].last['value']
+>  ⤷ "54.200.26.233"
+> ```
 
 For more information on the actual JSON API, please refer to the [following PDF document](http://www.dnsmadeeasy.com/integration/pdf/API-Docv2.pdf).
 
-## Method Calls
+## Available Actions
 
 Here is the complete of all methods supported by the `DnsMadeEasy::Api::Client`:
 
-* `base_uri=`
+#### Domains
+
+* `create_domain`
+* `create_domains`
+* `delete_domain`
+* `domain`
+* `domains`
+* `get_id_by_domain`
+
+#### Records
+
+* `records_for`
+* `all`
 * `base_uri`
 * `create_a_record`
 * `create_aaaa_record`
 * `create_cname_record`
-* `create_domain`
-* `create_domains`
 * `create_httpred_record`
 * `create_mx_record`
 * `create_ns_record`
@@ -124,54 +184,143 @@ Here is the complete of all methods supported by the `DnsMadeEasy::Api::Client`:
 * `create_srv_record`
 * `create_txt_record`
 * `delete_all_records`
-* `delete_domain`
 * `delete_record`
 * `delete_records`
-* `domain`
-* `domains`
-* `find_record_id`
-* `find`
-* `get_id_by_domain`
-* `records_for`
-* `request_limit`
-* `requests_remaining`
-* `update_record`
-* `update_records`
+* `find_all`
+* `find_first`
+* `find_record_ids`
 
+## CLI Client
+
+This library offers a simple CLI client `dme` that maps the command line arguments to method arguments for corresponding actions:
+
+```bash
+❯ dme --help
+Usage:
+  # Execute an API call:
+  dme [ --json | --yaml ] operation [ arg1 arg2 ... ]
+
+  # Print suported operations:
+  dme op[erations]
+
+Credentials:
+  Store your credentials in a YAML file
+  /Users/kig/.dnsmadeeasy/credentials.yml as follows:
+
+  credentials:
+    api_key: XXXX
+    api_secret: YYYY
+
+Examples:
+   dme domain moo.com
+   dme --json domain moo.com
+   dme find_all moo.com A www
+   dme find_first moo.com CNAME vpn-west
+   dme --yaml find_first moo.com CNAME vpn-west
+```
+
+You can run `dme operations` to see the supported list of operations:
+
+```bash
+❯ dme op
+Actions:
+  Checkout the README and RubyDoc for the arguments to each operation,
+  which is basically a method on a DnsMadeEasy::Api::Client instance.
+  http://www.rubydoc.info/gems/dnsmadeeasy/DnsMadeEasy/Api/Client
+
+Valid Operations Are:
+  all
+  base_uri
+  create_a_record
+  create_aaaa_record
+  create_cname_record
+  create_domain
+  create_domains
+  create_httpred_record
+  create_mx_record
+  create_ns_record
+  create_ptr_record
+  create_record
+  create_spf_record
+  create_srv_record
+  create_txt_record
+  delete_all_records
+  delete_domain
+  delete_record
+  delete_records
+  domain
+  domains
+  find_all
+  find_first
+  find_record_ids
+  get_id_by_domain
+  records_for
+  update_record
+  update_records
+```
+
+For example:
+
+```bash
+❯ dme domains moo.com
+```
+
+is equivalent to `DME.domains("moo.com")`. You can use any operation listed above, and output the result in either `YAML` or `JSON` (in addition to the default "awesome_print"), for example:
+
+```bash
+❯ dme --yaml find_all moo.com www CNAME
+---
+- dynamicDns: false
+  failed: false
+  gtdLocation: DEFAULT
+  hardLink: false
+  ttl: 60
+  failover: false
+  monitor: false
+  sourceId: 5861234
+  source: 1
+  name: www
+  value: ec2-54-202-251-7.us-west-2.compute.amazonaws.com
+  id: 43509989
+  type: CNAME
+```
 
 ### Managing Domains
 
+> NOTE: below we can be using `@client` instantiated with given key and secret, or 
+> `DME` or `DnsMadeEasy` module.
+
 To retrieve all domains:
 
 ```ruby
-@client.domains
+require 'dnsmadeeasy/dme'
+DME.domains
 ```
 
 To retreive the id of a domain by the domain name:
 
 ```ruby
-@client.get_id_by_domain('test.io')
+DME.get_id_by_domain('test.io')
 ```
 
 To retrieve the full domain record by domain name:
 
 ```ruby
-@client.domain('test.io')
+DME.domain('test.io')
 ```
 
 To create a domain:
 
 ```ruby
-@client.create_domain('test.io')
-
+DME.create_domain('test.io')
 # Multiple domains can be created by:
-@client.create_domains(%w[test.io moo.re])
+DME.create_domains(%w[test.io moo.re])
 ```
 
 To delete a domain:
 
 ```ruby
-@client.delete_domain        ('test.io')
+DME.delete_domain        ('test.io')
 ```
 
 ### Managing Records
@@ -179,62 +328,68 @@ To delete a domain:
 To retrieve all records for a given domain name:
 
 ```ruby
-@client.records_for          ('test.io')
+DME.all('test.io')
 ```
 
 To find the record id for a given domain, name, and type:
 
-This finds the id of the A record 'woah.test.io'.
+This finds all of the IDs matching 'woah.test.io' type 'A':
 
 ```ruby
-@client.find_record_id       ('test.io', 'woah', 'A')
+DME.find_record_ids      ('test.io', 'woah', 'A')
+# => [ 234234, 2342345 ]
 ```
 
-To delete a record by domain name and record id (the record id can be retrieved from `find_record_id`:
-
 ```ruby
-@client.delete_record        ('test.io', 123)
-
+# To delete a record by domain name and record id (the record id can be retrieved from `find_record_id`:
+DME.delete_record        ('test.io', 123)
 # To delete multiple records:
-
-@client.delete_records       ('test.io', [123, 143])
-
+DME.delete_records       ('test.io', [123, 143])
 # To delete all records in the domain:
+DME.delete_all_records   ('test.io')
+```
 
-@client.delete_all_records   ('test.io')
+To create records of various types:
+
+```ruby
+# The generic method:
+DME.create_record        ('test.io', 'woah', 'A', '127.0.0.1', { 'ttl' => '60' })
+
+# Specialized methods:
+DME.create_a_record      ('test.io', 'woah', '127.0.0.1', {})
+DME.create_aaaa_record   ('test.io', 'woah', '127.0.0.1', {})
+DME.create_ptr_record    ('test.io', 'woah', '127.0.0.1', {})
+DME.create_txt_record    ('test.io', 'woah', '127.0.0.1', {})
+DME.create_cname_record  ('test.io', 'woah', '127.0.0.1', {})
+DME.create_ns_record     ('test.io', 'woah', '127.0.0.1', {})
+DME.create_spf_record    ('test.io', 'woah', '127.0.0.1', {})
 ```
 
-To create a record:
+#### Specialized Record Types
+
+Below are the method calls for `MX`, `SRV`, and `HTTPRED` types:
 
 ```ruby
-@client.create_record        ('test.io', 'woah', 'A', '127.0.0.1', { 'ttl' => '60' })
-@client.create_a_record      ('test.io', 'woah', '127.0.0.1', {})
-@client.create_aaaa_record   ('test.io', 'woah', '127.0.0.1', {})
-@client.create_ptr_record    ('test.io', 'woah', '127.0.0.1', {})
-@client.create_txt_record    ('test.io', 'woah', '127.0.0.1', {})
-@client.create_cname_record  ('test.io', 'woah', '127.0.0.1', {})
-@client.create_ns_record     ('test.io', 'woah', '127.0.0.1', {})
-@client.create_spf_record    ('test.io', 'woah', '127.0.0.1', {})
 # Arguments are: domain_name, name, priority, value, options = {}
-@client.create_mx_record     ('test.io', 'woah', 5, '127.0.0.1', {})
+DME.create_mx_record     ('test.io', 'woah', 5, '127.0.0.1', {})
 # Arguments are: domain_name, name, priority, weight, port, value, options = {}
-@client.create_srv_record    ('test.io', 'woah', 1, 5, 80, '127.0.0.1', {})
-# Arguments are: domain_name, name, value, redirectType, description, keywords, title, options = {}
-@client.create_httpred_record('test.io', 'woah', '127.0.0.1', 'STANDARD - 302',
+DME.create_srv_record    ('test.io', 'woah', 1, 5, 80, '127.0.0.1', {})
+# Arguments are: domain_name, name, value, redirectType, 
+DME.create_httpred_record('test.io', 'woah', '127.0.0.1', 'STANDARD - 302',
+                               # description, keywords, title, options = {}
                               'a description', 'keywords', 'a title', {})
 ```
 
 To update a record:
 
 ```ruby
-@client.update_record        ('test.io', 123, 'woah', 'A', '127.0.1.1',  
-                             { 'ttl' => '60' })
+DME.update_record('test.io', 123, 'woah', 'A', '127.0.1.1',  { 'ttl' => '60' })
 ```
 
 To update several records:
 
 ```ruby
-@client.update_records('test.io',
+DME.update_records('test.io',
   [
     { 'id'   => 123,
       'name' => 'buddy',
@@ -248,7 +403,7 @@ To update several records:
 To get the number of API requests remaining after a call:
 
 ```ruby
-@client.requests_remaining
+DME.requests_remaining
 #=> 19898
 ```
 > NOTE: Information is not available until an API call has been made
@@ -256,10 +411,11 @@ To get the number of API requests remaining after a call:
 To get the API request total limit after a call:
 
 ```ruby
-@client.request_limit
+DME.request_limit
 #=> 2342
 ```
->Information is not available until an API call has been made
+> NOTE: Information is not available until an API call has been made
+
 
 ## Installation
 
@@ -294,7 +450,7 @@ The current maintainer [Konstantin Gredeskoul](https://github.com/kigster) wishe
 
  * Arnoud Vermeer for the original `dnsmadeeasy-rest-api` gem
  * Andre Arko, Paul Henry, James Hart formerly of [Wanelo](wanelo.com) fame, for bringing the REST API gem up to the level.
- * Phil Cohen, who graciously transferred the ownership of this gem on RubyGems to the current maintainer.
+ * Phil Cohen, who graciously transferred the ownership of the name of this gem on RubyGems.org to the current maintainer.
 
 
 ## Contributing
@@ -304,3 +460,5 @@ Bug reports and pull requests are welcome on GitHub at [https://github.com/kigst
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+

data/dnsmadeeasy.gemspec

@@ -18,6 +18,19 @@ Gem::Specification.new do |spec|
   spec.email         = %w(kigster@gmail.com letuboy@gmail.com hjhart@gmail.com)
   spec.summary       = DnsMadeEasy::DESCRIPTION
   spec.description   = DnsMadeEasy::DESCRIPTION
+  spec.post_install_message = <<-EOF
+
+Thank you for using the DnsMadeEasy ruby gem, the Ruby client 
+API for DnsMadeEasy.com's SDK v2. Please note that this gem 
+comes with a command line utility 'dme' which you can use 
+instead of the ruby API if you prefer. Run `dme` with no
+arguments to see the help message.
+
+You can store your credentials in a YAML file in your home
+directory. For more information, please see README at:
+https://github.com/kigster/dnsmadeeasy
+
+  EOF
 
   spec.homepage      = 'https://github.com/kigster/dnsmadeeasy'
   spec.license       = 'MIT'
@@ -31,6 +44,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'hashie'
+  spec.add_dependency 'colored2'
+  spec.add_dependency 'awesome_print'
 
   spec.add_development_dependency 'yard'
   spec.add_development_dependency 'simplecov'

data/exe/dme

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
 
-require 'dnsmadeeasy'
-# require 'dnsmadeeasy/cli'
+require 'dnsmadeeasy/runner'
+
+DnsMadeEasy::Runner.new(ARGV).execute!
+
+
 
-# DnsMadeEasy::CLI::Runner.new(ARGV).execute!
-puts "Not yet implemented"

data/lib/dme.rb

@@ -2,6 +2,10 @@ require 'dnsmadeeasy'
 
 module DME
   class << self
+    def [](key, secret)
+      ::DnsMadeEasy::Api::Client.new(key, secret)
+    end
+
     def method_missing(method, *args, &block)
       begin
         DnsMadeEasy.send(method, *args, &block)

data/lib/dnsmadeeasy.rb

@@ -3,11 +3,12 @@ module DnsMadeEasy
   API_BASE_URL_SANDBOX    = 'https://sandboxapi.dnsmadeeasy.com/V2.0'
 end
 
-require_relative 'dnsmadeeasy/credentials'
-require_relative 'dnsmadeeasy/api/client'
+require 'dnsmadeeasy/credentials'
+require 'dnsmadeeasy/api/client'
 
 module DnsMadeEasy
   class Error < StandardError;  end
+  class AuthenticationError < Error; end
   class APIKeyAndSecretMissingError < Error; end
 
   class << self
@@ -48,8 +49,13 @@ module DnsMadeEasy
     end
 
     def default!
+      assign_default_credentials
+    end
+
+
+    def assign_default_credentials
       if Credentials.exist?
-        self.credentials = Credentials.default_file
+        self.credentials = Credentials.default_credentials_file
       end
     end
 

data/lib/dnsmadeeasy/api/client.rb

@@ -4,27 +4,46 @@ require 'json'
 require 'uri'
 require 'net/http'
 require 'hashie/mash'
+require 'dnsmadeeasy/credentials'
 
 module DnsMadeEasy
   module Api
     class Client
 
+      class << self
+        def public_operations
+          (new('a', 'b').methods - Object.methods).map(&:to_s).reject { |r| r =~ /[=]$|^(api_|on_|request)/ }.sort
+        end
+      end
+
       attr_accessor :base_uri
-      attr_reader :requests_remaining
-      attr_reader :request_limit
+      attr_reader :requests_remaining,
+                  :request_limit,
+                  :api_key,
+                  :api_secret
 
 
       def initialize(api_key, api_secret, sandbox = false, options = {})
         fail 'api_key is undefined' unless api_key
         fail 'api_secret is undefined' unless api_secret
 
-        @api_key = api_key
-        @api_secret = api_secret
-        @options = options
+        @api_key            = api_key
+        @api_secret         = api_secret
+        @options            = options
         @requests_remaining = -1
-        @request_limit = -1
+        @request_limit      = -1
+
+        sandbox ? on_sandbox : on_production
+      end
+
+
+      def on_sandbox(&block)
+        with_url(::DnsMadeEasy::API_BASE_URL_SANDBOX, &block)
+      end
+
 
-        self.base_uri = sandbox ? API_BASE_URL_SANDBOX : API_BASE_URL_PRODUCTION
+      def on_production(&block)
+        with_url(::DnsMadeEasy::API_BASE_URL_PRODUCTION, &block)
       end
 
 
@@ -71,15 +90,25 @@ module DnsMadeEasy
       end
 
 
-      def find(domain_name, name, type)
+      alias all records_for
+
+
+      def find_all(domain_name, name, type)
         records = records_for(domain_name)
-        records['data'].detect { |r| r['name'] == name && r['type'] == type }
+        return nil unless records
+        records['data'].select { |r| r['name'] == name && r['type'] == type }
       end
 
 
-      def find_record_id(domain_name, name, type)
+      def find_first(domain_name, name, type)
         records = records_for(domain_name)
+        return nil unless records
+        records['data'].detect { |r| r['name'] == name && r['type'] == type }
+      end
 
+
+      def find_record_ids(domain_name, name, type)
+        records = records_for(domain_name)
         records['data'].select { |r| r['name'] == name && r['type'] == type }.map { |r| r['id'] }
       end
 
@@ -109,6 +138,8 @@ module DnsMadeEasy
       end
 
 
+      # Specific record types
+
       def create_a_record(domain_name, name, value, options = {})
         # TODO: match IPv4 for value
         create_record domain_name, name, 'A', value, options
@@ -178,12 +209,12 @@ module DnsMadeEasy
       def update_records(domain, records, options = {})
         body = records.map do |record|
           {
-            'id' => record['id'],
-            'name' => record['name'],
-            'type' => record['type'],
-            'value' => record['value'],
+            'id'          => record['id'],
+            'name'        => record['name'],
+            'type'        => record['type'],
+            'value'       => record['value'],
             'gtdLocation' => record['gtdLocation'],
-            'ttl' => record['ttl']
+            'ttl'         => record['ttl']
           }.merge(options)
         end
         put "/dns/managed/#{get_id_by_domain(domain)}/records/updateMulti/", body
@@ -201,7 +232,7 @@ module DnsMadeEasy
 
       def delete(path, body = nil)
         request(path) do |uri|
-          req = Net::HTTP::Delete.new(uri)
+          req      = Net::HTTP::Delete.new(uri)
           req.body = body.to_json if body
           req
         end
@@ -210,7 +241,7 @@ module DnsMadeEasy
 
       def put(path, body = nil)
         request(path) do |uri|
-          req = Net::HTTP::Put.new(uri)
+          req      = Net::HTTP::Put.new(uri)
           req.body = body.to_json if body
           req
         end
@@ -219,7 +250,7 @@ module DnsMadeEasy
 
       def post(path, body)
         request(path) do |uri|
-          req = Net::HTTP::Post.new(uri)
+          req      = Net::HTTP::Post.new(uri)
           req.body = body.to_json
           req
         end
@@ -229,9 +260,9 @@ module DnsMadeEasy
       def request(path)
         uri = URI("#{base_uri}#{path}")
 
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = true
-        http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @options.key?(:ssl_verify_none)
+        http              = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl      = true
+        http.verify_mode  = OpenSSL::SSL::VERIFY_NONE if @options.key?(:ssl_verify_none)
         http.open_timeout = @options[:open_timeout] if @options.key?(:open_timeout)
         http.read_timeout = @options[:read_timeout] if @options.key?(:read_timeout)
 
@@ -241,35 +272,53 @@ module DnsMadeEasy
           request[key] = value
         end
 
-        response = http.request(request)
-        response.value # raise Net::HTTPServerException unless response was 2xx
+        process_response!(http.request(request))
+      end
 
-        process_rate_limits(response)
 
+      def process_response!(response)
+        response.value # raise Net::HTTPServerException unless response was 2xx
+        process_rate_limits(response)
         unparsed_json = response.body.to_s.empty? ? '{}' : response.body
-
         Hashie::Mash.new(JSON.parse(unparsed_json))
+      rescue Net::HTTPServerException => e
+        if e.message =~ /403.*forbidden/i
+          raise ::DnsMadeEasy::AuthenticationError.new(e)
+        else
+          raise e
+        end
       end
 
 
       def process_rate_limits(response)
         response.each_header do |header, value|
           @requests_remaining = value.to_i if header == 'x-dnsme-requestsremaining'
-          @request_limit = value.to_i if header == 'x-dnsme-requestlimit'
+          @request_limit      = value.to_i if header == 'x-dnsme-requestlimit'
         end
       end
 
 
       def request_headers
         request_date = Time.now.httpdate
-        hmac = OpenSSL::HMAC.hexdigest('sha1', @api_secret, request_date)
+        hmac         = OpenSSL::HMAC.hexdigest('sha1', @api_secret, request_date)
         {
-          'Accept' => 'application/json',
-          'x-dnsme-apiKey' => @api_key,
+          'Accept'              => 'application/json',
+          'x-dnsme-apiKey'      => @api_key,
           'x-dnsme-requestDate' => request_date,
-          'x-dnsme-hmac' => hmac
+          'x-dnsme-hmac'        => hmac
         }
       end
+
+
+      def with_url(url)
+        old_value     = self.base_uri
+        self.base_uri = url
+        if block_given?
+          yield
+          self.base_uri = old_value
+        end
+        self
+      end
     end
   end
 end

data/lib/dnsmadeeasy/credentials.rb

@@ -25,7 +25,7 @@ module DnsMadeEasy
   #
   #
   class Credentials < Hash
-    DEFAULT_CREDENTIALS_FILE = File.expand_path('~/.dnsmadeeasy/credentials.yml').freeze
+    #DEFAULT_CREDENTIALS_FILE = File.expand_path('~/.dnsmadeeasy/credentials.yml').freeze
 
     class CredentialsFileNotFound < StandardError
     end
@@ -33,13 +33,16 @@ module DnsMadeEasy
     #
     # Class Methods
     #
-
+    #
     class << self
-      def exist?(file = DEFAULT_CREDENTIALS_FILE)
+      # Default credential file that's used if no argument is passed.
+      attr_accessor :default_credentials_file
+
+      def exist?(file = default_credentials_file)
         File.exist?(file)
       end
 
-      def load(file = DEFAULT_CREDENTIALS_FILE)
+      def load(file = default_credentials_file)
         validate_argument(file)
 
         new.tap do |local|
@@ -48,10 +51,6 @@ module DnsMadeEasy
         end
       end
 
-      def default_file
-        DEFAULT_CREDENTIALS_FILE
-      end
-
 
       private
 
@@ -72,6 +71,8 @@ module DnsMadeEasy
       end
     end
 
+    # Set the default
+    self.default_credentials_file ||= File.expand_path('~/.dnsmadeeasy/credentials.yml').freeze
 
     # Instance Methods
     # NOTE: we are subclassing Hash, which isn't awesome, but gets the job done.
@@ -116,7 +117,7 @@ module DnsMadeEasy
         when String, Symbol
           hash[key.to_sym] = value
         else
-          hash[key] = value
+          hash[key.to_s.to_sym] = value
       end
     end
 

data/lib/dnsmadeeasy/runner.rb

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+
+require 'colored2'
+require 'awesome_print'
+require 'dnsmadeeasy'
+require 'dnsmadeeasy/api/client'
+
+
+module DnsMadeEasy
+  class Runner
+    SUPPORTED_FORMATS = %w(json yaml)
+
+    attr_accessor :format, :argv, :operation
+
+
+    def initialize(argv = nil)
+      self.argv = argv || ARGV.dup
+      configure_authentication
+      self.format = process_flags_format
+    end
+
+
+    def execute!
+      if argv.empty? || argv.size < 1
+        print_help_message
+      else
+        self.operation = argv.shift.to_sym
+        exit call_through_client(operation)
+      end
+    end
+
+
+    private
+
+    def call_through_client(method)
+      begin
+        result = DnsMadeEasy.client.send(method, *argv)
+        case result
+          when NilClass
+            puts 'No records returned.'
+          when Hashie::Mash
+            print_formatted(result.to_hash, format)
+          when Array
+            print_formatted(result.map(&:to_hash), format)
+          else
+            print_formatted(result, format)
+        end
+        0
+      rescue ArgumentError => e
+        sig = method_signature(e, method)
+        (sig.shift == method.to_s) ?
+          print_signature(method, sig) :
+          print_error('Action', "#{method.to_s.bold.yellow}", 'has generated an error'.red, exception: e)
+        1
+      rescue NoMethodError
+        print_error('Action', "#{method.to_s.bold.yellow}", 'is not valid.'.red)
+        puts 'HINT: try running ' + 'dme operations'.bold.green + ' to see the list of valid operations.'
+        2
+      rescue Net::HTTPServerException => e
+        print_error(exception: e)
+        3
+      end
+    end
+
+
+    def print_error(*args, exception: nil)
+      unless args.empty?
+        puts <<-EOF
+#{'Error:'.bold.red} #{args.join(' ').red}
+        EOF
+      end
+
+      if exception
+        puts <<-EOF
+#{'Exception: '.bold.red}#{exception.inspect.red}
+        EOF
+      end
+    end
+
+
+    def print_signature(method, sig)
+      puts <<-EOF
+#{'Error: '.bold.yellow}
+  #{'You are missing some arguments for this operation:'.red}
+
+#{'Correct Usage: '.bold.yellow}
+  #{method.to_s.bold.green} #{sig.join(' ').blue }
+
+      EOF
+    end
+
+
+    def process_flags_format
+      if argv.first&.start_with?('--')
+        format = argv.shift.gsub(/^--/, '')
+        if format =~ /^h(elp)?$/i
+          print_help_message
+        end
+        unless SUPPORTED_FORMATS.include?(format)
+          puts "Error: format #{format.bold.red} is not supported."
+          puts "Supported values are: #{SUPPORTED_FORMATS.join(', ')}"
+          exit 1
+        end
+      elsif argv.first =~ /^ope?r?a?t?i?o?n?$/i
+        print_supported_operations
+        exit 0
+      end
+      format
+    end
+
+
+    def configure_authentication
+      if ENV['DNSMADEEASY_API_KEY'] && ENV['DNSMADEEASY_API_SECRET']
+        DnsMadeEasy.configure do |config|
+          config.api_key    = ENV['DNSMADEEASY_API_KEY']
+          config.api_secret = ENV['DNSMADEEASY_API_SECRET']
+        end
+      else
+        DnsMadeEasy.credentials = (ENV['DNSMADEEASY_CREDENTIALS'] || DnsMadeEasy::Credentials.default_credentials_file)
+      end
+    end
+
+
+    def print_usage_message
+      puts <<-EOF
+#{'Usage:'.bold.yellow}
+  #{'# Execute an API call:'.dark}
+  #{"dme [ #{SUPPORTED_FORMATS.map { |f| "--#{f}" }.join(' | ')} ] operation [ arg1 arg2 ... ] ".bold.green}
+
+  #{'# Print suported operations:'.dark}
+  #{'dme op[erations]'.bold.green}
+
+      EOF
+    end
+
+
+    def print_help_message
+      print_usage_message
+
+      puts <<-EOF
+#{'Credentials:'.bold.yellow}
+  Store your credentials in a YAML file 
+  #{DnsMadeEasy::Credentials.default_credentials_file} as follows:
+
+  #{'credentials:
+    api_key: XXXX
+    api_secret: YYYY'.bold.magenta}
+
+#{'Examples:'.bold.yellow}
+   #{'dme domain moo.com 
+   dme --json domain moo.com 
+   dme find_all moo.com A www
+   dme find_first moo.com CNAME vpn-west
+   dme --yaml find_first moo.com CNAME vpn-west'.green}
+
+      EOF
+      exit 1
+    end
+
+
+    def print_supported_operations
+      puts <<-EOF
+#{'Actions:'.bold.yellow}      
+  Checkout the README and RubyDoc for the arguments to each operation,
+  which is basically a method on a DnsMadeEasy::Api::Client instance.
+  #{'http://www.rubydoc.info/gems/dnsmadeeasy/DnsMadeEasy/Api/Client'.blue.bold.underlined}
+
+#{'Valid Operations Are:'.bold.yellow}
+  #{DnsMadeEasy::Api::Client.public_operations.join("\n  ").green.bold}
+
+      EOF
+    end
+
+
+    def print_formatted(result, format = nil)
+      if format
+        puts result.send("to_#{format}".to_sym)
+      else
+        ap(result, indent: 10)
+      end
+    end
+
+
+    # e.backtrack.first looks like this:
+    # ..../dnsmadeeasy/lib/dnsmadeeasy/api/client.rb:143:in `create_a_record'
+    def method_signature(e, method)
+      file, line, call_method = e.backtrace.first.split(':')
+      call_method             = call_method.gsub(/[']/, '').split('`').last
+      if call_method && call_method.to_sym == method.to_sym
+        source_line = File.open(file).to_a[line.to_i - 1].chomp!
+        if source_line =~ /def #{method}/
+          signature = source_line.strip.gsub(/,/, '').split(%r{[ ()]})
+          signature.shift # remove def
+          return signature.reject { |a| a =~ /^([={}\)\(])*$/ }
+        end
+      end
+      []
+    rescue
+      []
+    end
+  end
+end
+
+
+

data/lib/dnsmadeeasy/version.rb

@@ -1,3 +1,3 @@
 module DnsMadeEasy
-  VERSION = '0.1.1'.freeze
+  VERSION = '0.2.3'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dnsmadeeasy
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -12,7 +12,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-12-09 00:00:00.000000000 Z
+date: 2017-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -28,6 +28,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: colored2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -170,12 +198,18 @@ files:
 - lib/dnsmadeeasy/api/client.rb
 - lib/dnsmadeeasy/credentials.rb
 - lib/dnsmadeeasy/dme.rb
+- lib/dnsmadeeasy/runner.rb
 - lib/dnsmadeeasy/version.rb
 homepage: https://github.com/kigster/dnsmadeeasy
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message: "\nThank you for using the DnsMadeEasy ruby gem, the Ruby client
+  \nAPI for DnsMadeEasy.com's SDK v2. Please note that this gem \ncomes with a command
+  line utility 'dme' which you can use \ninstead of the ruby API if you prefer. Run
+  `dme` with no\narguments to see the help message.\n\nYou can store your credentials
+  in a YAML file in your home\ndirectory. For more information, please see README
+  at:\nhttps://github.com/kigster/dnsmadeeasy\n\n"
 rdoc_options: []
 require_paths:
 - lib