snitcher 0.4.0.pre2 → 0.4.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 52b46733dac8b3d6892d836ce73c27527c705f4c
-  data.tar.gz: 8117b728733b857dd8840491a6fa16f0a2db6ba0
+  metadata.gz: 85ae5078348c51d73c8830f198ff49a276a5ef36
+  data.tar.gz: 18bf74b6a9b887f3ca6c213cbf2cd38bb7814be0
 SHA512:
-  metadata.gz: fe9a30bdb596ffc377f951fd853ac66b00b22370cde6989224bd7a9e8ffa05a8b5a8832f14e74b0a779d458a29c4216e8efd8098720311c53fdb15491460dad0
-  data.tar.gz: f37a6ee3a9473e27e2a905bb81469c7df72990f3a35c16cc5892ffa5961ac92b5a52e7917af65a223767004666464104e6c2f7cce04ea620186e441f813d5318
+  metadata.gz: fabe574bb26a7766144e532bcf6e12562e2a9ad0d8029dd5e04984ba5ba97ac5de44b7da7dba229618bfc388d43639182f38d5cfb3ba6f5b5b53688329b89d55
+  data.tar.gz: b67166b247c7648b4d6a18a22c0894373176afb7bd5b62ecb5595770e9b25ced02462360c408ee69db4ff95c6ed1fa845d7f01c95ccc2becb87e61790c7cc70e

data/Gemfile

@@ -4,10 +4,11 @@ gemspec
 
 group :development do
   gem "pry"
+  gem "yard-ghpages"
 end
 
 group :test do
   gem "coveralls", require: false
   gem "rspec"
-  gem "webmock"
+  gem "webmock", ">= 2.0"
 end

data/README.md

@@ -68,7 +68,7 @@ client = Snitcher::API::Client.new(ENV["DEADMANSSNITCH_API_KEY"])
 client.snitches
 ```
 
-Returns an array of snitches.
+Returns an array of Snitches.
 
 ### Retrieve a Single Snitch
 
@@ -77,7 +77,7 @@ token = "c2354d53d2"
 client.snitch(token)
 ```
 
-Returns a snitch.
+Returns a Snitch.
 
 ### Retrieve Snitches That Match a Set of Tags
 
@@ -86,11 +86,12 @@ tags = ["critical", "sales"]
 client.tagged_snitches(tags)
 ```
 
-Returns an array of snitches.
+Returns an array of Snitches.
 
 ### Create a Snitch
 
-Required attributes are name and interval. Optional attributes are notes and tags.
+Required attributes are name and interval. Optional attributes are notes and
+tags.
 
 ```ruby
 attributes = { "name": "Nightly User Data Backups",
@@ -101,23 +102,24 @@ attributes = { "name": "Nightly User Data Backups",
 client.create_snitch(attributes)
 ```
 
-Returns the newly-created snitch.
+Returns the newly-created Snitch.
 
-### Edit a Snitch
+### Updating a Snitch
 
-You only need to pass the edit_snitch function the attributes you want to change. The rest of a snitch's attributes will remain the same.
+You only need to pass the update_snitch function the attributes you want to
+change. The rest of a Snitch's attributes will remain the same.
 
 ```ruby
 token = "c2354d53d2"
 new_attributes = { "name": "Important Nightly User Data Backups" }
-client.edit_snitch(token, new_attributes)
+client.update_snitch(token, new_attributes)
 ```
 
-Returns the edited snitch.
+Returns the edited Snitch.
 
 ### Adding Tags to a Snitch
 
-This function adds tags to a snitch, retaining whatever tags it already has.
+This function adds tags to a Snitch, retaining whatever tags it already has.
 
 ```ruby
 token = "c2354d53d2"
@@ -125,11 +127,11 @@ tags = ["spring_campaign", "support"]
 client.add_tags(token, tags)
 ```
 
-Returns an array of all of the snitch's tags.
+Returns an array of all of the Snitch's tags.
 
 ### Deleting a Tag From a Snitch
 
-This function is for deleting a single tag from a snitch.
+This function is for deleting a single tag from a Snitch.
 
 ```ruby
 token = "c2354d53d2"
@@ -137,11 +139,11 @@ tag = "support"
 client.remove_tag(token, tag)
 ```
 
-Returns an array of all of the snitch's remaining tags.
+Returns an array of all of the Snitch's remaining tags.
 
 ### Replace Tags on a Snitch
 
-Replaces all of a snitch's tags with an array of new tags.
+Replaces all of a Snitch's tags with an array of new tags.
 
 ```ruby
 token = "c2354d53d2"
@@ -149,18 +151,18 @@ tags = ["csv", "server_a"]
 client.replace_tags(token, tags)
 ```
 
-Returns the updated snitch.
+Returns the updated Snitch.
 
 ### Remove Tags From a Snitch
 
-Removes all of a snitch's tags.
+Removes all of a Snitch's tags.
 
 ```ruby
 token = "c2354d53d2"
 client.clear_tags(token)
 ```
 
-Returns the updated snitch.
+Returns the updated Snitch.
 
 ### Pause a Snitch
 

data/Rakefile

@@ -1,8 +1,10 @@
 require "bundler"
-require "rspec/core/rake_task"
-
 Bundler::GemHelper.install_tasks
 
+require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
+require "yard-ghpages"
+Yard::GHPages::Tasks.install_tasks
+
 task default: :spec

data/lib/snitcher.rb

@@ -6,20 +6,28 @@ require "snitcher/version"
 module Snitcher
   extend self
 
-  # Public: Check-in to Deadman's Snitch
+  # Check-in to Dead Man's Snitch.
   #
-  # token:  The Snitch token given by Deadman's Snitch (see the install page).
-  # opts:   The hash of optional parameters that can be given during check-in:
-  #           :message - Text message limited to ~250 characters.
-  #           :timeout - Number of seconds to set as connect and read timeout.
-  #           :uri - URL to use for snitch checkins.
+  # @param token [String] The unique Snitch token to check-in with. This can be
+  #   found on the Setup page as the last part of the HTTP check-in url. For
+  #   example, c2354d53d2 is the token in http://nosnch.in/c2354d53d2.
   #
-  # Examples
+  # @param [Hash] opts
   #
+  # @option opts [String] :message Text message to include with the check-in.
+  #   The message is limited to 256 characters.
+  #
+  # @option opts [Float, Fixnum] :timeout Number of seconds to wait for a
+  #   response from the server. Default is 5 seconds.
+  #   no
+  #
+  # @example
   #   Snitch.snitch("c2354d53d2")
   #   # => true
   #
-  # Returns true if the check-in succeeded or false if it failed
+  # @raise [Timeout::Error] if the request took too long and timed out.
+  #
+  # @return [Boolean] if the check-in succeeded.
   def snitch(token, opts = {})
     uri       = URI.parse(checkin_url(opts, token))
     uri.query = URI.encode_www_form(m: opts[:message]) if opts[:message]

data/lib/snitcher/api.rb

@@ -12,23 +12,25 @@ module Snitcher
     # Snitcher::API::Error and subclasses
     require "snitcher/api/error"
 
-    # Public: Retrieve API Key
+    # Retrieve an API Key for your account.
     #
-    # username: The username associated with a Deadman's Snitch account
-    # password: The password associated with a Deadman's Snitch account
+    # @param username [String] username for your Dead Man's Snitch account.
+    # @param password [String] password for your Dead Man's Snitch account.
     #
-    # options:
-    #   uri     - String URL of the DMS API to connect to.
-    #   timeout - Number of seconds to wait for open, read, and ssl handshake.
-    #
-    # Example
+    # @param [Hash] options
+    # @option options [String] uri location of alternative Dead Man's Snitch API
+    # @option timeout [Float, Fixnum] timeout number of seconds to wait for
+    #   server response before timing out.
     #
+    # @example
     #   Snitcher::API.get_key("alice@example.com", "password")
     #   # => "_caeEiZXnEyEzXXYVh2NhQ"
     #
-    # Returns the string api_key
-    # Raises Snitcher::API::Error based on the type from the server.
-    # Raises Timeout::Error if the request timed out.
+    # @raise [Timeout::Error] if the API request took too long to execute.
+    # @raise [Snitcher::API::AuthenticationError] credentials are invalid.
+    # @raise [Snitcher::API::Error] if any other API errors occur.
+    #
+    # @return [String] the API key to use for further API requests.
     def get_key(username, password, options={})
       api = options.fetch(:uri, "https://api.deadmanssnitch.com")
       uri = URI.parse("#{api}/v1/api_key")

data/lib/snitcher/api/client.rb

@@ -10,19 +10,21 @@ require "snitcher/api/error"
 class Snitcher::API::Client
   DEFAULT_ENDPOINT = "https://api.deadmanssnitch.com"
 
-  # Public: Create a new Client
+  # Create a new API Client for taling to Dead Man's Snitch's API.
   #
-  # key - Access key available at https://deadmanssnitch.com/account/keys.
+  # @param key [String] API access key (available at
+  #   https://deadmanssnitch.com/account/keys).
   #
-  # options
-  #   endpoint - String URL of the DMS API connecting to.
-  #   timeout  - Number of seconds to wait at most when making a request.
+  # @param [Hash] options advanced options for customizing the client
+  # @option options [String] :endpoint URL of the DMS API to connect to
+  # @option options [Float, Fixnum] :timeout number of seconds to wait at most
+  #   for a response from the API.
   #
-  # Example
-  #
-  #   Initialize API client for user with api key "abc123"
-  #     @client = Snitcher::API::Client.new("abc123")
+  # @example Creating a new Client with an API key
+  #   client = Snitcher::API::Client.new("abc123")
+  #   # => #<Snitcher::API::Client...>
   #
+  # @return [Snitcher::API::Client] New API Client.
   def initialize(key, options = {})
     endpoint = options[:endpoint] || DEFAULT_ENDPOINT
 
@@ -31,70 +33,58 @@ class Snitcher::API::Client
     @timeout  = options.fetch(:timeout, 5.0)
   end
 
-  # Public: List snitches on the account
+  # Get the list snitches on the account
   #
-  # Example
+  # @example List the Snitches on an account
+  #     client.snitches
+  #     # => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]
   #
-  #   Get a list of all snitches
-  #     @client.snitches
-  #     => [#<Snitcher::API::Snitch:0x007fdcf51ec380 @token="c2354d53d3",
-  #          @name="Daily Backups", @tags=["production", "critical"],
-  #          @status="healthy", @checked_in_at="2014-01-01T12:00:00.000Z",
-  #          @interval="daily", @check_in_url="https://nosnch.in/c2354d53d3",
-  #          @created_at="2014-01-01T08:00:00.000Z", @notes=nil>,
-  #         #<Snitcher::API::Snitch:0x007fdcf51ec358 @token="c2354d53d4",
-  #          @name="Hourly Emails", @tags=[], @status="healthy",
-  #          @checked_in_at="2014-01-01T12:00:00.000Z", @interval="hourly",
-  #          @check_in_url="https://nosnch.in/c2354d53d4",
-  #          @created_at="2014-01-01T07:50:00.000Z", @notes=nil>]
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::Error] if any API errors occur.
   #
-  # Raise Timeout::Error if the API request times out
+  # @return [Array<Snitcher::API::Snitch>] the snitches on the account.
   def snitches
     snitch_array(get("/v1/snitches"))
   end
 
-  # Public: Get a single snitch by unique token
+  # Get a single Snitch by it's unique token.
   #
-  # token: The unique token of the snitch to get. Should be a string.
+  # @param token [String] The unique token of the Snitch to get
   #
-  # Example
+  # @example Get the Snitch with token "c2354d53d2"
+  #   client.snitch("c2354d53d2")
   #
-  #   Get the snitch with token "c2354d53d2"
+  #   # => #<Snitcher::API:: @token="c2354d53d2" ...>
   #
-  #     @client.snitch("c2354d53d2")
-  #     => #<Snitcher::API::Snitch:0x007fdcf50ad2d0 @token="c2354d53d3",
-  #         @name="Daily Backups", @tags=["production", "critical"],
-  #         @status="pending", @checked_in_at=nil, @interval="daily",
-  #         @check_in_url="https://nosnch.in/c2354d53d3",
-  #         @created_at="2015-08-15T12:15:00.234Z",
-  #         @notes="Important user data.">
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::ResourceNotFoundError] if a Snitch does not exist
+  #   with that token
+  # @raise [Snitcher::API::Error] if any other API errors occur.
   #
-  # Raise Timeout::Error if the API request times out
+  # @return [Snitcher::API::Snitch] the Snitch
   def snitch(token)
     payload = get("/v1/snitches/#{token}")
     Snitcher::API::Snitch.new(payload)
   end
 
-  # Public: Retrieve snitches that match all of the tags in a list
+  # Retrieve Snitches filtered by a list of tags. Only Snitches that are tagged
+  # with all of the given tags will be returned.
   #
-  # tags: An array of strings. Each string is a tag.
+  # @param tags [String, Array<String>] the tag(s) to filter by.
   #
-  # Example
+  # @example Get the snitches that match a list of tags
+  #   client.tagged_snitches(["production","critical"])
   #
-  #   Get the snitches that match a list of tags
-  #     @client.tagged_snitches(["production","critical"])
-  #     => [#<Snitcher::API::Snitch:0x007fdcf51ec380 @token="c2354d53d3",
-  #          @name="Daily Backups", @tags=["production", "critical"],
-  #          @status="pending", @checked_in_at=nil, @interval="daily",
-  #          @check_in_url="https://nosnch.in/c2354d53d3",
-  #          @created_at="2014-01-01T08:00:00.000Z", @notes=nil>,
-  #         #<Snitcher::API::Snitch:0x007fdcf51ec358 @token="c2354d53d4",
-  #          @name="Hourly Emails", @tags=["production", "critical"],
-  #          @status="healthy", @checked_in_at="2014-01-01T12:00:00.000Z",
-  #          @interval="hourly", @check_in_url="https://nosnch.in/c2354d53d4",
-  #          @created_at="2014-01-01T07:50:00.000Z", @notes=nil>]
+  #   # => [
+  #     #<Snitcher::API::Snitch tags=["production", "critical"]>,
+  #     #<Snitcher::API::Snitch tags=["production", "critical"]>,
+  #   ]
   #
-  # Raise Timeout::Error if the API request times out
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  #   with that token
+  # @raise [Snitcher::API::Error] if any API errors occur.
+  #
+  # @return [Array<Snitcher::API::Snitch>] list of Snitches matching all tags.
   def tagged_snitches(*tags)
     (tags ||= []).flatten!
 
@@ -107,204 +97,179 @@ class Snitcher::API::Client
     snitch_array(get("/v1/snitches?#{query}"))
   end
 
-  # Public: Create a snitch using passed-in values. Returns the new snitch.
-  #
-  # attributes: A hash of the snitch properties. It should include these keys:
-  #               "name":     String value is the name of the snitch
-  #               "interval": String value representing how often the snitch is
-  #                           expected to fire. Options are "hourly", "daily",
-  #                           "weekly", "monthly"
-  #               "notes":    Optional string value for recording additional
-  #                           information about the snitch
-  #               "tags":     Optional array of string tags
-  #
-  # Example
-  #
-  #   Create a new snitch
-  #     attributes = {
-  #       "name": "Daily Backups",
-  #       "interval": "daily",
-  #       "notes": "Customer and supplier tables",
-  #       "tags": ["backups", "maintenance"]
-  #     }
-  #     @client.create_snitch(attributes)
-  #     => #<Snitcher::API::Snitch:0x007fdcf50ad2d0 @token="c2354d53d3",
-  #         @name="Daily Backups", @tags=["backups", "maintenance"],
-  #         @status="pending", @checked_in_at=nil, @interval="daily",
-  #         @check_in_url="https://nosnch.in/c2354d53d3",
-  #         @created_at="2015-08-15T12:15:00.234Z",
-  #         @notes="Customer and supplier tables">
-  #
-  # Raise Timeout::Error if the API request times out
+  # Create a new Snitch.
+  #
+  # @param [Hash] attributes The properties for the new Snitch
+  # @option attributes [String] :name The label used for the Snitch
+  # @option attributes [String] :interval How often the snitch is expected to
+  #   check-in. One of: "15_minute", "30_minute", "hourly", "daily", "weekly",
+  #   or "monthly".
+  # @option attributes [optional, String] :notes Additional information about
+  #   the Snitch. Useful to put instructions of investigating or fixing any
+  #   errors.
+  # @option attributes [optional, Array<String>] :tags List of labels to tag the
+  #   Snitch with.
+  #
+  # @example Create a new Snitch
+  #   client.create_snitch({
+  #     name:  "Daily Backups",
+  #     type:  { interval: "hourly" },
+  #     notes: "On error check the print tray for paper jams",
+  #     tags:  [ "backups", "maintenance" ],
+  #   })
+  #
+  #   # => #<Snitcher::API::Snitch:...>
+  #
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::ResourceInvalidError] if the attributes are not valid
+  #   for a Snitch.
+  # @raise [Snitcher::API::Error] if any other API errors occur.
+  #
+  # @return [Snitcher::API::Snitch] the new Snitch.
   def create_snitch(attributes={})
-    payload = post("/v1/snitches", attributes)
-    Snitcher::API::Snitch.new(payload)
+    if attributes.has_key?(:interval)
+      type = attributes[:type] ||= {}
+      type[:interval] ||= attributes.delete(:interval)
+    end
+
+    response = post("/v1/snitches", attributes)
+    Snitcher::API::Snitch.new(response)
   end
 
-  # Public: Edit an existing snitch, identified by token, using passed-in
-  #         values. Only changes those values included in the attributes
-  #         hash; other attributes are not changed. Returns the updated snitch.
-  #
-  # token:      The unique token of the snitch to get. Should be a string.
-  # attributes: A hash of the snitch properties. It should only include those
-  #             values you want to change. Options include these keys:
-  #               "name":     String value is the name of the snitch
-  #               "interval": String value representing how often the snitch
-  #                           is expected to fire. Options are "hourly",
-  #                           "daily", "weekly", and "monthly".
-  #               "notes":    Optional string value for recording additional
-  #                           information about the snitch
-  #               "tags":     Optional array of string tags
-  #
-  # Example
-  #
-  #   Edit an existing snitch using values passed in a hash.
-  #     token      = "c2354d53d2"
-  #     attributes = {
-  #       "name":     "Monthly Backups",
-  #       "interval": "monthly"
-  #     }
-  #     @client.edit_snitch(token, attributes)
-  #     => #<Snitcher::API::Snitch:0x007fdcf50ad2d0 @token="c2354d53d3",
-  #         @name="Monthly Backups", @tags=["backups", "maintenance"],
-  #         @status="pending", @checked_in_at=nil, @interval="monthly",
-  #         @check_in_url="https://nosnch.in/c2354d53d3",
-  #         @created_at="2015-08-15T12:15:00.234Z",
-  #         @notes="Customer and supplier tables">
+  # Update a snitch, identified by token, using passed-in values. Only changes
+  # those values included in the attributes hash; other attributes are not
+  # changed.
+  #
+  # @param token [String] The unique token of the Snitch.
+  # @param [Hash] attributes the set of Snitch attributes to change.
+  #
+  # @option attributes [String] :name The label used for the Snitch
+  # @option attributes [String] :interval How often the snitch is expected to
+  #   check-in. One of: "15_minute", "30_minute", "hourly", "daily", "weekly",
+  #   or "monthly".
+  # @option attributes [optional, String] :notes Additional information about
+  #   the Snitch. Useful to put instructions of investigating or fixing any
+  #   errors.
+  # @option attributes [optional, Array<String>, nil] :tags List of labels to
+  #   tag the Snitch with.
+  #
+  # @example Update an existing Snitch
+  #   client.update_snitch("c2354d53d2", {
+  #     name: "Monthly Backups",
+  #   })
+  #   # => #<Snitcher::API::Snitch:...>
+  #
+  # @example Setting Tags for a Snitch
+  #   client.update_snitch("c2354d53d2", tags: ["production", "backup"])
+  #   # => #<Snitcher::API::Snitch: @tags=["production", "backup"])
+  #
+  # @example Removing Tags from a Snitch
+  #   client.update_snitch("c2354d53d2", tags: [])
+  #   or
+  #   client.update_snitch("c2354d53d2", tags: nil)
+  #
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::ResourceInvalidError] if the changes are not valid.
+  # @raise [Snitcher::API::ResourceNotFoundError] if the Snitch does not exist.
+  # @raise [Snitcher::API::Error] if any other API errors occur.
   #
   # Raise Timeout::Error if the API request times out
-  def edit_snitch(token, attributes={})
+  def update_snitch(token, attributes={})
+    if attributes.has_key?(:tags)
+      attributes[:tags] = [attributes[:tags]].flatten.compact
+    end
+
+    if attributes.has_key?(:interval)
+      type = attributes[:type] ||= {}
+      type[:interval] ||= attributes.delete(:interval)
+    end
+
     payload = patch("/v1/snitches/#{token}", attributes)
     Snitcher::API::Snitch.new(payload)
   end
 
-  # Public: Add one or more tags to an existing snitch, identified by token.
-  #         Returns an array of the snitch's tags.
+  # Add one or more tags to an existing snitch, identified by token.
   #
-  # token:  The unique token of the snitch to edit. Should be a string.
-  # tags:   Array of string tags. Will append these tags to any existing tags.
+  # @param token [String] The unique token of the Snitch.
+  # @param tags  [Array<String>] Tag or tags to add to the list of tags already
+  #   on the Snitch.
   #
-  # Example
+  # @example Add tags to an existing snitch.
+  #   client.add_tags("c2354d53d2", ["red", "green"])
+  #   # => [ "yellow", "red", "green" ]
   #
-  #   Add tags to an existing snitch.
-  #     @client.add_tags("c2354d53d2", %w("red", "green")
-  #     => [ "yellow", "red", "green" ]
+  # @example Adding a single tag
+  #   client.add_tags("c2354d53d2", "orange")
+  #   # => [ "yellow", "orange" ]
   #
-  #   Adding a single tag
-  #     @client.add_tags("c2354d53d2", "orange")
-  #     => [ "yellow", "orange" ]
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::ResourceNotFoundError] if the Snitch does not exist.
+  # @raise [Snitcher::API::Error] if an API errors occur.
   #
-  # Raise Timeout::Error if the API request times out
+  # @return [Array<String>] full list of tags on the Snitch.
   def add_tags(token, tags=[])
     tags = [tags].flatten
     post("/v1/snitches/#{token}/tags", tags)
   end
 
-  # Public: Remove a tag from an existing snitch, identified by token.
-  #         Returns an array of the snitch's tags.
+  # Remove a tag from a Snitch.
   #
-  # token:  The unique token of the snitch to edit. Should be a string.
-  # tag:    Tag to be removed from a snitch's tags. Should be a string.
+  # @param token [String] The unique token of the Snitch.
+  # @param tag   [String] The tag to remove from the Snitch.
   #
-  # Example
+  # @example Removing the "production" tag from a Snitch
+  #   client.remove_tag("c2354d53d2", "production")
+  #   # => [ "critical" ]
   #
-  #   Assume a snitch that already has the tags "critical" and "production"
-  #     token = "c2354d53d2"
-  #     tag =   "production"
-  #     @client.remove_tag(token, tag)
-  #     => [
-  #           "critical"
-  #        ]
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::ResourceNotFoundError] if the Snitch does not exist.
+  # @raise [Snitcher::API::Error] if any other API errors occur.
   #
-  # Raise Timeout::Error if the API request times out
+  # @return [Array<String>] list of the remaining tags on the Snitch.
   def remove_tag(token, tag)
     delete("/v1/snitches/#{token}/tags/#{tag}")
   end
 
-  # Public: Replace all of a snitch's tags with those supplied.
-  #         Returns the updated snitch.
-  #
-  # token:  The unique token of the snitch to edit. Should be a string.
-  # tags:   Array of string tags. Will replace the snitch's current tags with
-  #         these.
-  #
-  # Example
-  #
-  #   Assume a snitch with the tag "critical". Replace with tags provided.
-  #     token = "c2354d53d3"
-  #     tags =  ["production", "urgent"]
-  #     @client.replace_tags(token, tags)
-  #     => #<Snitcher::API::Snitch:0x007fdcf50ad2d0 @token="c2354d53d3",
-  #         @name="Daily Backups", @tags=["production", "urgent"],
-  #         @status="pending", @checked_in_at=nil, @interval="daily",
-  #         @check_in_url="https://nosnch.in/c2354d53d3",
-  #         @created_at="2015-08-15T12:15:00.234Z",
-  #         @notes="Customer and supplier tables">
-  #
-  # Raise Timeout::Error if the API request times out
-  def replace_tags(token, tags=[])
-    attributes = {"tags" => tags}
-
-    edit_snitch(token, attributes)
-  end
-
-  # Public: Remove all of a snitch's tags.
-  #         Returns the updated snitch.
-  #
-  # token: The unique token of the snitch to edit. Should be a string.
-  #
-  # Example
-  #
-  #   Remove all tags.
-  #     token = "c2354d53d3"
-  #     @client.clear_tags(token)
-  #     => #<Snitcher::API::Snitch:0x007fdcf50ad2d0 @token="c2354d53d3",
-  #         @name="Daily Backups", @tags=[], @status="pending",
-  #         @checked_in_at=nil, @interval="daily",
-  #         @check_in_url="https://nosnch.in/c2354d53d3",
-  #         @created_at="2015-08-15T12:15:00.234Z",
-  #         @notes="Customer and supplier tables">
-  #
-  # Raise Timeout::Error if the API request times out
-  def clear_tags(token)
-    edit_snitch(token, :tags => [])
-  end
-
-  # Public: Pauses a snitch. The return is a hash with the message "Response
-  #         complete".
+  # Pauses a Snitch if it can be paused. Snitches can only be paused if their
+  # status is currently "failing" or "errored".
   #
-  # token: The unique token of the snitch to pause. Should be a string.
+  # @param token [String] The unique token of the Snitch.
   #
-  # Example
+  # @example Pause a Snitch
+  #   client.pause_snitch("c2354d53d2")
+  #   # => true
   #
-  #   Pause a snitch.
-  #     token = "c2354d53d3"
-  #     @client.pause_snitch(token)
-  #     => { :message => "Response complete" }
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::ResourceNotFoundError] if the Snitch does not exist.
+  # @raise [Snitcher::API::Error] if any other API errors occur.
   #
-  # Raise Timeout::Error if the API request times out
+  # @return [nil]
   def pause_snitch(token)
     post("/v1/snitches/#{token}/pause")
+
+    nil
   end
 
-  # Public: Deletes a snitch. The return is a hash with the message "Response
-  #         complete".
+  # Deletes a Snitch.
   #
-  # token: The unique token of the snitch to delete. Should be a string.
+  # @param token [String] The unique token of the Snitch to delete.
   #
-  # Example
+  # @example Delete a Snitch.
+  #   client.delete_snitch("c2354d53d2")
+  #   # => { :message => "Response complete" }
   #
-  #   Delete a snitch.
-  #     token = "c2354d53d3"
-  #     @client.delete_snitch(token)
-  #     => { :message => "Response complete" }
+  # @raise [Timeout::Error] if the API request took too long to execute.
+  # @raise [Snitcher::API::ResourceNotFoundError] if the Snitch does not exist.
+  # @raise [Snitcher::API::Error] if any other API errors occur.
   #
-  # Raise Timeout::Error if the API request times out
+  # @return [nil]
   def delete_snitch(token)
     delete("/v1/snitches/#{token}")
+
+    nil
   end
 
-  protected
+  private
 
   def user_agent
     # RUBY_ENGINE was not added until 1.9.3

data/lib/snitcher/api/snitch.rb

@@ -1,11 +1,38 @@
 class Snitcher::API::Snitch
-  attr_accessor :token, :name, :tags, :status, :checked_in_at,
-    :interval, :check_in_url, :created_at, :notes
+  # @return [String] unique token used to identify a Snitch.
+  attr_accessor :token
 
-  # Public: Return a Snitcher::API::Snitch object based on a hash payload.
-  #
-  # Example
+  # @return [String] useful name for the Snitch to help identify it.
+  attr_accessor :name
+
+  # @return [Array<String>] list of tags on the Snitch.
+  attr_accessor :tags
+
+  # @return [String] the current reporting status of the Snitch. One of
+  #   "pending", "healthy", "paused", "failed", or "errored".
+  attr_accessor :status
+
+  # @return [String] when the Snitch last checked_in
+  attr_accessor :checked_in_at
+
+  # @return [String] how often Dead Man's Snitch expects to hear from the
+  #   Snitch. One of "15_minute", "30_minute", "hourly", "daily", "weekly", or
+  #   "monthly".
+  attr_accessor :interval
+
+  # @return [String] url used to check-in in the Snitch as healthy.
+  attr_accessor :check_in_url
+
+  # @return [String] when the Snitch was created.
+  attr_accessor :created_at
+
+  # @return [String] generic notes for the Snitch. Useful for specifying actions
+  #   to take when a Snitch stops reporting.
+  attr_accessor :notes
+
+  # Create a new Snitch from an API response.
   #
+  # @example
   #   payload = {
   #     "token" => "c2354d53d3",
   #     "href" => "/v1/snitches/c2354d53d3",
@@ -25,20 +52,19 @@ class Snitcher::API::Snitch
   #   }
   #
   #   Snitcher::API::Snitch.new(payload)
-  #   => #<Snitcher::API::Snitch:0x007fdcf50ad2d0 @token="c2354d53d3",
-  #       @name="Daily Backups", @tags=["production", "critical"],
-  #       @status="pending", @checked_in_at=nil, @interval="daily",
-  #       @check_in_url="https://nosnch.in/c2354d53d3",
-  #       @created_at="2015-08-15T12:15:00.234Z", @notes="Important user data.">
+  #   # => #<Snitcher::API::Snitch...>
+  #
+  # @return Snitcher::API::Snitch
   def initialize(payload)
-    @token = payload["token"]
-    @name = payload["name"]
-    @tags = payload["tags"]
-    @status = payload["status"]
+    @token     = payload["token"]
+    @name      = payload["name"]
+    @tags      = payload["tags"]
+    @status    = payload["status"]
+    @interval  = payload["type"]["interval"]
+    @notes     = payload["notes"]
+
+    @created_at    = payload["created_at"]
+    @check_in_url  = payload["check_in_url"]
     @checked_in_at = payload["checked_in_at"]
-    @interval = payload["type"]["interval"]
-    @check_in_url = payload["check_in_url"]
-    @created_at = payload["created_at"]
-    @notes = payload["notes"]
   end
 end

data/lib/snitcher/version.rb

@@ -1,3 +1,3 @@
 module Snitcher
-  VERSION = "0.4.0.pre2"
+  VERSION = "0.4.0.rc1"
 end

data/spec/api/client_spec.rb

@@ -9,7 +9,7 @@ describe Snitcher::API::Client do
   end
 
   let(:stub_url)   { /api\.dms\.dev/ }
-  let(:snitch_url) { "http://key:@api.dms.dev/v1/snitches" }
+  let(:snitch_url) { "http://api.dms.dev/v1/snitches" }
 
   describe "#snitches" do
     let(:url)   { snitch_url }
@@ -45,7 +45,9 @@ describe Snitcher::API::Client do
                 }
 
     before do
-      stub_request(:get, stub_url).to_return(:body => body, :status => 200)
+      stub_request(:get, stub_url).
+        with(basic_auth: ["key", ""]).
+        to_return(:body => body, :status => 200)
     end
 
     it "pings API with the api_key" do
@@ -171,10 +173,10 @@ describe Snitcher::API::Client do
   describe "#create_snitch" do
     let(:data)  {
                   {
-                    "name"     => "Daily Backups",
+                    "name"  => "Daily Backups",
                     "interval" => "daily",
-                    "notes"    => "Customer and supplier tables",
-                    "tags"     => ["backups", "maintenance"]
+                    "notes" => "Customer and supplier tables",
+                    "tags"  => ["backups", "maintenance"]
                    }
                 }
     let(:url)   { snitch_url }
@@ -211,6 +213,49 @@ describe Snitcher::API::Client do
       expect(client.create_snitch(data)).to be_a(Snitcher::API::Snitch)
     end
 
+    it "takes interval as a top level key" do
+      # The API as designed requires `type: { interval: "" }` with the
+      # expectation that there will be more types of Snitches. This hasn't
+      # happend as of 2016 and it's expected that interval will be required
+      # regardless of future changes.
+      #
+      # Allowing interval as a top level key makes using the API easier.
+
+      req =
+        stub_request(:post, stub_url).with do |request|
+          payload = JSON.parse(request.body)
+
+          expect(payload).to have_key("type")
+          expect(payload["type"]["interval"]).to eq("hourly")
+        end
+        .to_return(:body => body, :status => 201)
+
+      client.create_snitch(name: "Snitch", interval: "hourly")
+
+      expect(req).to have_been_made
+    end
+
+    it "puts precedences on type/interval over just interval" do
+      # :interval is a helper but the API documentation specifies type/interval.
+
+      req =
+        stub_request(:post, stub_url).with do |request|
+          payload = JSON.parse(request.body)
+
+          expect(payload).to have_key("type")
+          expect(payload["type"]["interval"]).to eq("weekly")
+        end
+        .to_return(:body => body, :status => 201)
+
+      client.create_snitch({
+        name: "Snitch",
+        interval: "daily",
+        type: { interval: "weekly" },
+      })
+
+      expect(req).to have_been_made
+    end
+
     describe "validation errors" do
       let(:data) do
         {
@@ -245,7 +290,7 @@ describe Snitcher::API::Client do
     end
   end
 
-  describe "#edit_snitch" do
+  describe "#update_snitch" do
     let(:token) { "c2354d53d2" }
     let(:data)  {
                   {
@@ -276,13 +321,85 @@ describe Snitcher::API::Client do
     end
 
     it "pings API with the api_key" do
-      client.edit_snitch(token, data)
+      client.update_snitch(token, data)
 
       expect(a_request(:patch, url)).to have_been_made.once
     end
 
     it "returns the modified snitch" do
-      expect(client.edit_snitch(token, data)).to be_a(Snitcher::API::Snitch)
+      expect(client.update_snitch(token, data)).to be_a(Snitcher::API::Snitch)
+    end
+
+    it "takes interval as a top level key" do
+      req =
+        stub_request(:patch, stub_url).with do |request|
+          payload = JSON.parse(request.body)
+
+          expect(payload).to have_key("type")
+          expect(payload["type"]["interval"]).to eq("hourly")
+        end
+        .to_return(:body => body, :status => 200)
+
+      client.update_snitch("c2354d53d2", interval: "hourly")
+
+      expect(req).to have_been_made
+    end
+
+    it "puts precedences on type/interval over just interval" do
+      # :interval is a helper but the API documentation specifies type/interval.
+
+      req =
+        stub_request(:patch, stub_url).with do |request|
+          payload = JSON.parse(request.body)
+
+          expect(payload).to have_key("type")
+          expect(payload["type"]["interval"]).to eq("weekly")
+        end
+        .to_return(:body => body, :status => 200)
+
+      client.update_snitch("c2354d53d2", {
+        interval: "daily",
+        type: { interval: "weekly" },
+      })
+
+      expect(req).to have_been_made
+    end
+
+
+    it "can tag using a single string" do
+      req =
+        stub_request(:patch, stub_url).with do |request|
+          payload = JSON.parse(request.body)
+          expect(payload["tags"]).to eq(["production"])
+        end.
+        and_return(body: body)
+
+      client.update_snitch("c2354d53d2", tags: "production")
+      expect(req).to have_been_made
+    end
+
+    it "can remove all tags using `nil`" do
+      req =
+        stub_request(:patch, stub_url).with do |request|
+          payload = JSON.parse(request.body)
+          expect(payload["tags"]).to eq([])
+        end.
+        and_return(body: body)
+
+      client.update_snitch("c2354d53d2", tags: nil)
+      expect(req).to have_been_made
+    end
+
+    it "can remove all tags using an empty hash" do
+      req =
+        stub_request(:patch, stub_url).with do |request|
+          payload = JSON.parse(request.body)
+          expect(payload["tags"]).to eq([])
+        end.
+        and_return(body: body)
+
+      client.update_snitch("c2354d53d2", tags: [])
+      expect(req).to have_been_made
     end
   end
 
@@ -314,10 +431,7 @@ describe Snitcher::API::Client do
     let(:token) { "c2354d53d2" }
     let(:tag)   { "critical" }
     let(:url)   { "#{snitch_url}/#{token}/tags/#{tag}" }
-    let(:body)  { '[
-                     "critical"
-                   ]'
-                }
+    let(:body)  { '[ "critical" ]' }
 
     before do
       stub_request(:delete, stub_url).to_return(:body => body, :status => 200)
@@ -336,82 +450,12 @@ describe Snitcher::API::Client do
     end
   end
 
-  describe "#replace_tags" do
-    let(:token) { "c2354d53d2" }
-    let(:tags)  { ["red", "green"] }
-    let(:url)   { "#{snitch_url}/#{token}" }
-    let(:body)  { '{
-                     "token": "c2354d53d2",
-                     "href": "/v1/snitches/c2354d53d2",
-                     "name": "Daily Backups",
-                     "tags": [
-                       "red",
-                       "green"
-                     ],
-                     "status": "pending",
-                     "checked_in_at": "",
-                     "type": {
-                       "interval": "daily"
-                     },
-                     "notes": "Sales data."
-                   }'
-                }
-
-    before do
-      stub_request(:patch, stub_url).to_return(:body => body, :status => 200)
-    end
-
-    it "pings API with the api_key" do
-      client.replace_tags(token, tags)
-
-      expect(a_request(:patch, url)).to have_been_made.once
-    end
-
-    it "returns the updated snitch" do
-      expect(client.replace_tags(token, tags)).to be_a(Snitcher::API::Snitch)
-    end
-  end
-
-  describe "#clear_tags" do
-    let(:token) { "c2354d53d2" }
-    let(:url)   { "#{snitch_url}/#{token}" }
-    let(:body)  { '{
-                     "token": "c2354d53d2",
-                     "href": "/v1/snitches/c2354d53d2",
-                     "name": "Daily Backups",
-                     "tags": [
-                     ],
-                     "status": "pending",
-                     "checked_in_at": "",
-                     "type": {
-                       "interval": "daily"
-                     },
-                     "notes": "Sales data."
-                   }'
-                }
-
-    before do
-      stub_request(:patch, stub_url).to_return(:body => body, :status => 200)
-    end
-
-    it "pings API with the api_key" do
-      client.clear_tags(token)
-
-      expect(a_request(:patch, url)).to have_been_made.once
-    end
-
-    it "returns the updated snitch" do
-      expect(client.clear_tags(token)).to be_a(Snitcher::API::Snitch)
-    end
-  end
-
   describe "#pause_snitch" do
     let(:token) { "c2354d53d2" }
     let(:url)   { "#{snitch_url}/#{token}/pause" }
-    let(:body)  { '{}' }
 
     before do
-      stub_request(:post, stub_url).to_return(:body => body, :status => 200)
+      stub_request(:post, stub_url).to_return(:status => 204)
     end
 
     it "pings API with the api_key" do
@@ -422,7 +466,7 @@ describe Snitcher::API::Client do
 
     context "when successful" do
       it "returns an empty response" do
-        expect(client.pause_snitch(token)).to eq(JSON.parse(body))
+        expect(client.pause_snitch(token)).to eq(nil)
       end
     end
   end
@@ -430,10 +474,9 @@ describe Snitcher::API::Client do
   describe "#delete_snitch" do
     let(:token) { "c2354d53d2" }
     let(:url)   { "#{snitch_url}/#{token}" }
-    let(:body)  { '{}' }
 
     before do
-      stub_request(:delete, stub_url).to_return(:body => body, :status => 200)
+      stub_request(:delete, stub_url).to_return(:status => 204)
     end
 
     it "pings API with the api_key" do
@@ -444,7 +487,7 @@ describe Snitcher::API::Client do
 
     context "when successful" do
       it "returns an empty response" do
-        expect(client.delete_snitch(token)).to eq(JSON.parse(body))
+        expect(client.delete_snitch(token)).to eq(nil)
       end
     end
   end

data/spec/api_spec.rb

@@ -11,7 +11,8 @@ describe Snitcher::API do
       user = "alice@example.com"
       pass = "password"
 
-      request = stub_request(:get, "https://#{user}:#{pass}@api.deadmanssnitch.com/v1/api_key").
+      request = stub_request(:get, "https://api.deadmanssnitch.com/v1/api_key").
+        with(basic_auth: [user, pass]).
         to_return({
           :body   => '{"api_key": "_caeEiZXnEyEzXXYVh2NhQ"}',
           :status => 200
@@ -27,7 +28,8 @@ describe Snitcher::API do
       user = "lol@notreally.horse"
       pass = "nope"
 
-      request = stub_request(:get, "https://#{user}:#{pass}@api.deadmanssnitch.com/v1/api_key").
+      request = stub_request(:get, "https://api.deadmanssnitch.com/v1/api_key").
+        with(basic_auth: [user, pass]).
         to_return({
           :body => JSON.generate({
             :type  => "sign_in_incorrect",
@@ -60,7 +62,8 @@ describe Snitcher::API do
     end
 
     it "allows the API URI to be provided" do
-      request = stub_request(:any, "user:pass@dms.dev:4000/v1/api_key").
+      request = stub_request(:any, "dms.dev:4000/v1/api_key").
+        with(basic_auth: ["user", "pass"]).
         to_return({
           :body   => '{"api_key": "this_is_an_api_key"}',
           :status => 200

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: snitcher
 version: !ruby/object:Gem::Version
-  version: 0.4.0.pre2
+  version: 0.4.0.rc1
 platform: ruby
 authors:
 - Collective Idea
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-25 00:00:00.000000000 Z
+date: 2016-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -102,3 +102,4 @@ test_files:
 - spec/spec_helper.rb
 - spec/support/random.rb
 - spec/support/webmock.rb
+has_rdoc: