snitcher 0.4.0.rc1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 85ae5078348c51d73c8830f198ff49a276a5ef36
-  data.tar.gz: 18bf74b6a9b887f3ca6c213cbf2cd38bb7814be0
+SHA256:
+  metadata.gz: 2613d8b9e2918478b19e16717aa65726a8a0b6aae250846bd0b966b5b34bffa5
+  data.tar.gz: ab08596c2a1fe6e7fba7db7e4c7ecb9b092eb6dd1ac16dae8b75fd68e2f7efd1
 SHA512:
-  metadata.gz: fabe574bb26a7766144e532bcf6e12562e2a9ad0d8029dd5e04984ba5ba97ac5de44b7da7dba229618bfc388d43639182f38d5cfb3ba6f5b5b53688329b89d55
-  data.tar.gz: b67166b247c7648b4d6a18a22c0894373176afb7bd5b62ecb5595770e9b25ced02462360c408ee69db4ff95c6ed1fa845d7f01c95ccc2becb87e61790c7cc70e
+  metadata.gz: 8ca6c380e026b3c086683eba26b836429ac32a6b61dad10f48a0a906012d2d0783c6e15097100b5ffeb4b6a4edfb47736d33e026533afd85e9c86e168fe1f6ba
+  data.tar.gz: a04bdb064748796ba5297a28268fed83c0c4c2867f10cecd22be56a595e8914feb7fb5fe5b56ea43d1842cbb775800ed519e1fa47859755df69972b5e1b86b1c

data/.travis.yml

@@ -1,22 +1,20 @@
-branches:
-  only:
-    - master
+dist: bionic
+
 language: ruby
 matrix:
   allow_failures:
     - rvm: ruby-head
 
-before_install:
-  - gem install bundler
-
-# Disable support for sudo to get faster builds with Docker
-sudo: false
-
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1
-  - 2.2
-  - 2.3.0
+  - 2.5
+  - 2.6
+  - 2.7
+  - 3.0
   - jruby
   - ruby-head
+
+notifications:
+  webhooks:
+    urls:
+      - http://buildlight.collectiveidea.com/
+    on_start: always

data/CHANGELOG.md

@@ -1,8 +1,16 @@
-## 0.4.0 / TBD
-* [FEATURE] Add Snitcher::API for integrating with the DMS API ([[@danabrit](https://github.com/danabrit))
+## 0.4.2 / 2021-06-07
+* [BUG] Fixed Ruby 3.0 support ([@gaffneyc](https://github.com/gaffneyc))
+
+## 0.4.1 / 2018-07-09
+* [FEATURE] Added :status option to Snitcher.snitch! ([@gaffneyc](https://github.com/gaffneyc))
+*
+
+## 0.4.0 / 2016-06-20
+* [FEATURE] Added Snitcher::API for integrating with the DMS API ([@danabrit](https://github.com/danabrit))
+* [FEATURE] Added Snitcher.snitch! which raises exceptions on errors ([@gaffneyc](https://github.com/gaffneyc))
 
 ## 0.3.2 / 2015-08-13
-* [BUG] Fixed passing messaging during a check-in ([@ryoung](https://github.com/ryoung))
+* [BUG] Fixed passing messages during a check-in ([@ryoung](https://github.com/ryoung))
 
 ## 0.3.1 / 2015-06-23
 * [ENHANCEMENT] Add a custom User-Agent

data/Gemfile

@@ -4,7 +4,6 @@ gemspec
 
 group :development do
   gem "pry"
-  gem "yard-ghpages"
 end
 
 group :test do

data/README.md

@@ -3,7 +3,7 @@
 Simple API client for [Dead Man's Snitch](https://deadmanssnitch.com)
 
 [![Gem Version](https://badge.fury.io/rb/snitcher.png)](http://badge.fury.io/rb/snitcher)
-[![Build Status](https://travis-ci.org/deadmanssnitch/snitcher.png?branch=master)](https://travis-ci.org/deadmanssnitch/snitcher)
+[![Build Status](https://travis-ci.com/deadmanssnitch/snitcher.png?branch=master)](https://travis-ci.com/deadmanssnitch/snitcher)
 [![Code Climate](https://codeclimate.com/github/deadmanssnitch/snitcher.png)](https://codeclimate.com/github/deadmanssnitch/snitcher)
 [![Coverage Status](https://coveralls.io/repos/deadmanssnitch/snitcher/badge.png)](https://coveralls.io/r/deadmanssnitch/snitcher)
 
@@ -23,23 +23,21 @@ You also may provide a message with the check in:
 Snitcher.snitch("c2354d53d2", message: "Finished in 23.8 seconds.")
 ```
 
-The default timeout of 5 seconds can be overridden:
+Errors can be reported by providing the `status` option. A status of `nil`,
+`0`, or `""` are all considered a success. Any other status is treated as a
+failure.
 
 ```ruby
-Snitcher.snitch("c2354d53d2", timeout: 10)
+Snitcher.snitch("c2354d53d2", status: 1)
 ```
 
-## API Access
-
-### Retrieving Your API Key At Command Line
+The default timeout of 5 seconds can be overridden:
 
 ```ruby
-require "snitcher/api"
-
-key = Snitcher::API.get_key("jane@example.com", "password")
+Snitcher.snitch("c2354d53d2", timeout: 10)
 ```
 
-Returns an authentication key to access the api.
+## API Access
 
 ### Setup
 
@@ -82,22 +80,22 @@ Returns a Snitch.
 ### Retrieve Snitches That Match a Set of Tags
 
 ```ruby
-tags = ["critical", "sales"]
-client.tagged_snitches(tags)
+client.snitches(tags: ["critical", "sales"])
 ```
 
 Returns an array of Snitches.
 
 ### Create a Snitch
 
-Required attributes are name and interval. Optional attributes are notes and
-tags.
+Both `:name` and `:interval` are required. Optional attributes include `:notes`,
+and `:tags`. For a full list see [the API documentation](https://deadmanssnitch.com/docs/api/v1#creating-a-snitch).
 
 ```ruby
-attributes = { "name": "Nightly User Data Backups",
-  "interval": "daily",
-  "notes": "User login and usage data",
-  "tags": ["users", "critical"]
+attributes = {
+  name: "Nightly User Data Backups",
+  interval: "daily",
+  notes: "User login and usage data",
+  tags: ["users", "critical"],
 }
 client.create_snitch(attributes)
 ```
@@ -111,8 +109,8 @@ change. The rest of a Snitch's attributes will remain the same.
 
 ```ruby
 token = "c2354d53d2"
-new_attributes = { "name": "Important Nightly User Data Backups" }
-client.update_snitch(token, new_attributes)
+attrs = { "name": "Important Nightly User Data Backups" }
+client.update_snitch(token, attrs)
 ```
 
 Returns the edited Snitch.
@@ -123,7 +121,7 @@ This function adds tags to a Snitch, retaining whatever tags it already has.
 
 ```ruby
 token = "c2354d53d2"
-tags = ["spring_campaign", "support"]
+tags  = ["spring_campaign", "support"]
 client.add_tags(token, tags)
 ```
 
@@ -141,29 +139,20 @@ client.remove_tag(token, tag)
 
 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.
+### Setting the Tags on a Snitch
 
 ```ruby
 token = "c2354d53d2"
-tags = ["csv", "server_a"]
-client.replace_tags(token, tags)
+client.update_snitch(token, tags: [ "production", "critical" ])
 ```
 
-Returns the updated Snitch.
-
-### Remove Tags From a Snitch
-
-Removes all of a Snitch's tags.
+### Removing all Tags from a Snitch
 
 ```ruby
 token = "c2354d53d2"
-client.clear_tags(token)
+client.update_snitch(token, tags: [])
 ```
 
-Returns the updated Snitch.
-
 ### Pause a Snitch
 
 ```ruby
@@ -171,7 +160,7 @@ token = "c2354d53d2"
 client.pause_snitch(token)
 ```
 
-Returns a hash with a `message` key, whose value is "Response complete".
+Returns a nil object.
 
 ### Delete a Snitch
 
@@ -180,7 +169,7 @@ token = "c2354d53d2"
 client.delete_snitch(token)
 ```
 
-Returns a hash with a `message` key, whose value is "Response complete".
+Returns a nil object.
 
 ## Contributing
 

data/Rakefile

@@ -4,7 +4,4 @@ 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/examples/api.rb

@@ -0,0 +1,51 @@
+$:.unshift File.expand_path("../../lib", __FILE__)
+
+# Need to require the API separately as it is not required by Snitcher itself.
+require "snitcher/api"
+
+if !ENV["DMS_API_KEY"]
+  puts "Set DMS_API_KEY environment variable to your deadmanssnitch.com API key"
+  puts "before running this example."
+  puts
+  puts "example: DMS_API_KEY=c23452notarealkeyhello! ruby examples/api.rb"
+
+  exit 1
+end
+
+# Get an API key for a given user with password
+key = ENV["DMS_API_KEY"]
+
+# Create a new API client
+client = Snitcher::API::Client.new(key)
+
+# Create an hourly Snitch called "Monitor All The Things"
+snitch = client.create_snitch({
+  name: "Monitor All The Things",
+  tags: ["things"],
+  interval: "hourly",
+})
+puts "Created: #{snitch.inspect}"
+
+# Change the name and notes of an existing Snitch
+snitch = client.update_snitch(snitch.token, {
+  name: "Monitor Fewer Things",
+  notes: "Only monitoring a couple things",
+})
+
+# Add new tags to a Snitch
+snitch.tags = client.add_tags(snitch.token, ["production", "critical issues"])
+
+# Remove the "critical issues" tag from the Snitch
+snitch.tags = client.remove_tag(snitch.token, "critical issues")
+
+# Get a list of Snitches tagged with "production"
+production = client.snitches(tags: ["production"])
+puts "Production Snitches:"
+production.each { |s| puts "  - #{s.inspect}"}
+
+# Pause a Snitch if it's currently missing or errored
+client.pause_snitch(snitch.token)
+
+# Delete a Snitch
+client.delete_snitch(snitch.token)
+puts "Deleted: #{snitch.token}"

data/lib/snitcher.rb

@@ -6,7 +6,7 @@ require "snitcher/version"
 module Snitcher
   extend self
 
-  # Check-in to Dead Man's Snitch.
+  # Check-in to Dead Man's Snitch, exceptions are raised on failures.
   #
   # @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
@@ -17,20 +17,30 @@ module Snitcher
   # @option opts [String] :message Text message to include with the check-in.
   #   The message is limited to 256 characters.
   #
+  # @option opts [String, Fixnum, nil] :status Exit code for the check-in. A
+  #   status of "", nil, or 0 are all treated as the job finishing successfully.
+  #
   # @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
   #
-  # @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]
+  def snitch!(token, opts = {})
+    params = {}
+    params[:m] = opts[:message] if opts[:message]
+
+    # It's unnecessary to send an empty status
+    if opts[:status] && opts[:status] != ""
+      params[:s] = opts[:status]
+    end
+
+    uri = URI.parse(checkin_url(opts, token))
+    if params.any?
+      uri.query = URI.encode_www_form(params)
+    end
 
     opts = initialize_opts(opts, uri)
 
@@ -41,7 +51,33 @@ module Snitcher
       response = http.request(request)
       response.is_a?(Net::HTTPSuccess)
     end
-  rescue ::Timeout::Error
+  end
+
+  # Check-in to Dead Man's Snitch.
+  #
+  # @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.
+  #
+  # @param [Hash] opts
+  #
+  # @option opts [String] :message Text message to include with the check-in.
+  #   The message is limited to 256 characters.
+  #
+  # @option opts [String, Fixnum, nil] :status Exit code for the check-in. A
+  #   status of "", nil, or 0 are all treated as the job finishing successfully.
+  #
+  # @option opts [Float, Fixnum] :timeout Number of seconds to wait for a
+  #   response from the server. Default is 5 seconds.
+  #
+  # @example
+  #   Snitch.snitch("c2354d53d2")
+  #   # => true
+  #
+  # @return [Boolean] if the check-in succeeded.
+  def snitch(*args)
+    snitch!(*args)
+  rescue StandardError
     false
   end
 
@@ -54,7 +90,7 @@ module Snitcher
       open_timeout: timeout,
       read_timeout: timeout,
       ssl_timeout:  timeout,
-      use_ssl:      use_ssl?(uri)
+      use_ssl:      use_ssl?(uri),
     }
   end
 

data/lib/snitcher/api.rb

@@ -7,67 +7,8 @@ require "snitcher/version"
 
 module Snitcher
   module API
-    extend self
-
     # Snitcher::API::Error and subclasses
     require "snitcher/api/error"
-
-    # Retrieve an API Key for your account.
-    #
-    # @param username [String] username for your Dead Man's Snitch account.
-    # @param password [String] password for your Dead Man's Snitch account.
-    #
-    # @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"
-    #
-    # @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")
-
-      timeout = options.fetch(:timeout, 5)
-      http_options = {
-        open_timeout: timeout,
-        read_timeout: timeout,
-        ssl_timeout:  timeout,
-        use_ssl:      uri.scheme == "https",
-      }
-
-      Net::HTTP.start(uri.host, uri.port, http_options) do |http|
-        request = Net::HTTP::Get.new(uri.path)
-        request["User-Agent"] = user_agent
-        request.basic_auth(username, password)
-
-        response = http.request(request)
-
-        if response.is_a?(Net::HTTPSuccess)
-          JSON.parse(response.body)["api_key"]
-        else
-          error = JSON.parse(response.body)
-
-          raise ::Snitcher::API::Error.new(error)
-        end
-      end
-    end
-
-    private
-
-    def user_agent
-      # RUBY_ENGINE was not added until 1.9.3
-      engine = defined?(::RUBY_ENGINE) ? ::RUBY_ENGINE : "Ruby"
-
-      "Snitcher; #{engine}/#{RUBY_VERSION}; #{RUBY_PLATFORM}; v#{::Snitcher::VERSION}"
-    end
   end
 end
 

data/lib/snitcher/api/client.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 require "net/https"
 require "timeout"
 require "json"
+require "cgi"
 
 require "snitcher/api"
 require "snitcher/version"
@@ -35,16 +38,46 @@ class Snitcher::API::Client
 
   # Get the list snitches on the account
   #
+  # @param [Hash] filters
+  # @option filters [String, Array<String>] tags only return Snitches that are
+  #   tagged with _all_ of the given tags. For example, if a Snitch is tagged
+  #   with "production" and "critical" it will be returned when filtering by
+  #   "production", "critical", or ["production", "critical"] but not
+  #   ["production", "backups"].
+  #
   # @example List the Snitches on an account
-  #     client.snitches
-  #     # => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]
+  #   client.snitches
+  #   # => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]
+  #
+  # @example List Snitches with a specific tag
+  #   client.snitches(tags: "production")
+  #   # => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]
+  #
+  # @example List Snitches with multiple tags
+  #   client.snitches(tags: ["production", "critical"])
+  #   # => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]
   #
   # @raise [Timeout::Error] if the API request took too long to execute.
   # @raise [Snitcher::API::Error] if any API errors occur.
   #
   # @return [Array<Snitcher::API::Snitch>] the snitches on the account.
-  def snitches
-    snitch_array(get("/v1/snitches"))
+  def snitches(filters = {})
+    query = {}
+
+    # Tags allow for labeling Snitches for better categorization. This allows
+    # filtering by a set of tags.
+    if tags = filters[:tags]
+      tags = Array(tags).flatten
+      query[:tags] = tags.map(&:strip).compact.uniq.join(",")
+    end
+
+    # JSON array of Snitch attributes
+    response = get("/v1/snitches", query)
+
+    # Convert the attributes hashes into Objects
+    response.map! do |snitch|
+      Snitcher::API::Snitch.new(snitch)
+    end
   end
 
   # Get a single Snitch by it's unique token.
@@ -63,40 +96,12 @@ class Snitcher::API::Client
   #
   # @return [Snitcher::API::Snitch] the Snitch
   def snitch(token)
+    token = CGI.escape(token)
+
     payload = get("/v1/snitches/#{token}")
     Snitcher::API::Snitch.new(payload)
   end
 
-  # Retrieve Snitches filtered by a list of tags. Only Snitches that are tagged
-  # with all of the given tags will be returned.
-  #
-  # @param tags [String, Array<String>] the tag(s) to filter by.
-  #
-  # @example Get the snitches that match a list of tags
-  #   client.tagged_snitches(["production","critical"])
-  #
-  #   # => [
-  #     #<Snitcher::API::Snitch tags=["production", "critical"]>,
-  #     #<Snitcher::API::Snitch tags=["production", "critical"]>,
-  #   ]
-  #
-  # @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!
-
-    query = URI.encode_www_form({
-      # Strip extra spaces, dedupe, and clean up the list of tags to be filtered
-      # by.
-      tags: tags.map(&:strip).compact.uniq.join(","),
-    })
-
-    snitch_array(get("/v1/snitches?#{query}"))
-  end
-
   # Create a new Snitch.
   #
   # @param [Hash] attributes The properties for the new Snitch
@@ -113,7 +118,7 @@ class Snitcher::API::Client
   # @example Create a new Snitch
   #   client.create_snitch({
   #     name:  "Daily Backups",
-  #     type:  { interval: "hourly" },
+  #     interval: "hourly",
   #     notes: "On error check the print tray for paper jams",
   #     tags:  [ "backups", "maintenance" ],
   #   })
@@ -126,10 +131,10 @@ class Snitcher::API::Client
   # @raise [Snitcher::API::Error] if any other API errors occur.
   #
   # @return [Snitcher::API::Snitch] the new Snitch.
-  def create_snitch(attributes={})
-    if attributes.has_key?(:interval)
+  def create_snitch(attributes = {})
+    if interval = attributes.delete(:interval)
       type = attributes[:type] ||= {}
-      type[:interval] ||= attributes.delete(:interval)
+      type[:interval] ||= interval
     end
 
     response = post("/v1/snitches", attributes)
@@ -174,17 +179,20 @@ class Snitcher::API::Client
   # @raise [Snitcher::API::Error] if any other API errors occur.
   #
   # Raise Timeout::Error if the API request times out
-  def update_snitch(token, attributes={})
-    if attributes.has_key?(:tags)
+  def update_snitch(token, attributes = {})
+    if attributes.key?(:tags)
       attributes[:tags] = [attributes[:tags]].flatten.compact
     end
 
-    if attributes.has_key?(:interval)
+    # Expand the interval key to the full structure required by the API
+    if interval = attributes.delete(:interval)
       type = attributes[:type] ||= {}
-      type[:interval] ||= attributes.delete(:interval)
+      type[:interval] ||= interval
     end
 
+    token = CGI.escape(token)
     payload = patch("/v1/snitches/#{token}", attributes)
+
     Snitcher::API::Snitch.new(payload)
   end
 
@@ -207,9 +215,10 @@ class Snitcher::API::Client
   # @raise [Snitcher::API::Error] if an API errors occur.
   #
   # @return [Array<String>] full list of tags on the Snitch.
-  def add_tags(token, tags=[])
-    tags = [tags].flatten
-    post("/v1/snitches/#{token}/tags", tags)
+  def add_tags(token, tags = [])
+    token = CGI.escape(token)
+
+    post("/v1/snitches/#{token}/tags", Array(tags).flatten)
   end
 
   # Remove a tag from a Snitch.
@@ -227,6 +236,9 @@ class Snitcher::API::Client
   #
   # @return [Array<String>] list of the remaining tags on the Snitch.
   def remove_tag(token, tag)
+    token = CGI.escape(token)
+    tag = CGI.escape(tag)
+
     delete("/v1/snitches/#{token}/tags/#{tag}")
   end
 
@@ -245,6 +257,8 @@ class Snitcher::API::Client
   #
   # @return [nil]
   def pause_snitch(token)
+    token = CGI.escape(token)
+
     post("/v1/snitches/#{token}/pause")
 
     nil
@@ -264,6 +278,8 @@ class Snitcher::API::Client
   #
   # @return [nil]
   def delete_snitch(token)
+    token = CGI.escape(token)
+
     delete("/v1/snitches/#{token}")
 
     nil
@@ -278,12 +294,12 @@ class Snitcher::API::Client
     "Snitcher; #{engine}/#{RUBY_VERSION}; #{RUBY_PLATFORM}; v#{::Snitcher::VERSION}"
   end
 
-  def execute_request(request, options={})
+  def execute_request(request)
     http_options = {
       open_timeout: @timeout,
       read_timeout: @timeout,
-      ssl_timeout:  @timeout,
-      use_ssl:      @endpoint.scheme == "https",
+      ssl_timeout: @timeout,
+      use_ssl: @endpoint.scheme == "https",
     }
 
     Net::HTTP.start(@endpoint.host, @endpoint.port, http_options) do |http|
@@ -294,7 +310,7 @@ class Snitcher::API::Client
       if request.body
         request["Content-Type"] = "application/json"
 
-        # Some trickiery to allow pushing the JSON rendering down as far as
+        # Some trickery to allow pushing the JSON rendering down as far as
         # possible.
         if !request.body.is_a?(String)
           request.body = JSON.generate(request.body)
@@ -315,9 +331,10 @@ class Snitcher::API::Client
     when Net::HTTPInternalServerError
       # InternalServerError does not have a parseable body as the error may not
       # be generated by the application itself.
-      raise ::Snitcher::API::InternalServerError.new(
-        "http_#{response.code}", response.body
-      )
+      raise ::Snitcher::API::InternalServerError.new({
+        "type"  => "internal_server_error",
+        "error" => response.body,
+      })
     else
       error = JSON.parse(response.body)
 
@@ -325,37 +342,32 @@ class Snitcher::API::Client
     end
   end
 
-  def get(path, options={})
+  def get(path, query = {})
+    # Only add the query param if any valid filters were given.
+    if query.any?
+      path = "#{path}?#{URI.encode_www_form(query)}"
+    end
+
     request = Net::HTTP::Get.new(path)
-    execute_request(request, options)
+    execute_request(request)
   end
 
-  def post(path, data=nil, options={})
+  def post(path, data = nil)
     request = Net::HTTP::Post.new(path)
     request.body = data
 
-    execute_request(request, options)
+    execute_request(request)
   end
 
-  def patch(path, data, options={})
+  def patch(path, data)
     request = Net::HTTP::Patch.new(path)
     request.body = data
 
-    execute_request(request, options)
+    execute_request(request)
   end
 
-  def delete(path, options={})
+  def delete(path)
     request = Net::HTTP::Delete.new(path)
-    execute_request(request, options)
-  end
-
-  private
-
-  def snitch_array(json_payload)
-    arr = []
-    json_payload.each do |payload|
-      arr << Snitcher::API::Snitch.new(payload)
-    end
-    arr
+    execute_request(request)
   end
 end

data/lib/snitcher/api/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Snitcher::API
   # Error is the base class for all API specific errors. For a full list of
   # errors and how they can happen please refer to the API documentation.
@@ -13,14 +15,15 @@ module Snitcher::API
       klass =
         case type.to_s
           # sign_in_incorrect is only returned when using username + password.
-          when "sign_in_incorrect";  AuthenticationError
+          when "sign_in_incorrect";     AuthenticationError
           # api_key_invalid is only returned when using the API key.
-          when "api_key_invalid";    AuthenticationError
-          when "plan_limit_reached"; PlanLimitReachedError
-          when "account_on_hold";    AccountOnHoldError
-          when "resource_not_found"; ResourceNotFoundError
-          when "resource_invalid";   ResourceInvalidError
-          else                       Error
+          when "api_key_invalid";       AuthenticationError
+          when "plan_limit_reached";    PlanLimitReachedError
+          when "account_on_hold";       AccountOnHoldError
+          when "resource_not_found";    ResourceNotFoundError
+          when "resource_invalid";      ResourceInvalidError
+          when "internal_server_error"; InternalServerError
+          else                          Error
         end
 
       error = klass.allocate

data/lib/snitcher/api/snitch.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Snitcher::API::Snitch
   # @return [String] unique token used to identify a Snitch.
   attr_accessor :token
@@ -12,6 +14,14 @@ class Snitcher::API::Snitch
   #   "pending", "healthy", "paused", "failed", or "errored".
   attr_accessor :status
 
+  # alert_email is a list of email addresses that will be notified when this
+  # Snitch goes missing, errors, or becomes healthy again. When this is set,
+  # only the email addresses in the list will be notified. When the list is
+  # empty then all team members will be alerted by default.
+  #
+  # @return [Array<String>] override list of email addresses
+  attr_accessor :alert_email
+
   # @return [String] when the Snitch last checked_in
   attr_accessor :checked_in_at
 
@@ -37,6 +47,7 @@ class Snitcher::API::Snitch
   #     "token" => "c2354d53d3",
   #     "href" => "/v1/snitches/c2354d53d3",
   #     "name" => "Daily Backups",
+  #     "alert_email" => [],
   #     "tags" => [
   #       "production",
   #       "critical"
@@ -64,6 +75,7 @@ class Snitcher::API::Snitch
     @notes     = payload["notes"]
 
     @created_at    = payload["created_at"]
+    @alert_email   = payload["alert_email"] || []
     @check_in_url  = payload["check_in_url"]
     @checked_in_at = payload["checked_in_at"]
   end

data/lib/snitcher/version.rb

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

data/snitcher.gemspec

@@ -19,6 +19,6 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = ">= 1.9.3"
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake", "~> 10.1"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
 end

data/spec/api/client_spec.rb

@@ -3,7 +3,7 @@ require "snitcher/api/client"
 require "base64"
 require "securerandom"
 
-describe Snitcher::API::Client do
+RSpec.describe Snitcher::API::Client do
   subject(:client) do
     Snitcher::API::Client.new("key", endpoint: "http://api.dms.dev")
   end
@@ -60,6 +60,34 @@ describe Snitcher::API::Client do
       expect(client.snitches).to be_a(Array)
       expect(client.snitches.first).to be_a(Snitcher::API::Snitch)
     end
+
+    it "allows filtering by a tag" do
+      request = stub_request(:get, "#{snitch_url}?tags=production")
+        .to_return(body: body, status: 200)
+
+      client.snitches(tags: "production")
+      expect(request).to have_been_made.once
+    end
+
+    it "allows filtering by multiple tags" do
+      request = stub_request(:get, "#{snitch_url}?tags=phoenix%20foundary,murggle")
+        .to_return(body: body, status: 200)
+
+      client.snitches(tags: ["phoenix foundary", "murggle"])
+      expect(request).to have_been_made.once
+    end
+
+    context "when Net::HTTPInternalServerError" do
+      it "raise ::Snitcher::API::InternalServerError" do
+        stub_request(:any, "#{snitch_url}?tags=phoenix")
+          .to_return(body: "Server Error", status: 500)
+
+        expect { client.snitches(tags: ["phoenix"]) }.to raise_error do |error|
+          expect(error).to be_a(::Snitcher::API::InternalServerError)
+          expect(error.message).to eq("Server Error")
+        end
+      end
+    end
   end
 
   describe "#snitch" do
@@ -99,77 +127,6 @@ describe Snitcher::API::Client do
     end
   end
 
-  describe "#tagged_snitches" do
-    let(:tags)  { ["sneetch", "belly"] }
-    let(:url)   { "#{snitch_url}?tags=sneetch,belly" }
-    let(:body)  { '[
-                     {
-                       "token": "c2354d53d2",
-                       "href": "/v1/snitches/c2354d53d2",
-                       "name": "Best Kind of Sneetch on the Beach",
-                       "tags": [
-                         "sneetch",
-                         "belly",
-                         "star-belly"
-                       ],
-                       "status": "pending",
-                       "checked_in_at": "",
-                       "type": {
-                         "interval": "hourly"
-                       }
-                     },
-                     {
-                       "token": "c2354d53d3",
-                       "href": "/v1/snitches/c2354d53d3",
-                       "name": "Have None Upon Thars",
-                       "tags": [
-                         "sneetch",
-                         "belly",
-                         "plain-belly"
-                       ],
-                       "status": "pending",
-                       "checked_in_at": "",
-                       "type": {
-                         "interval": "hourly"
-                       }
-                     }
-                   ]'
-                }
-
-    before do
-      stub_request(:get, stub_url).to_return(:body => body, :status => 200)
-    end
-
-    it "pings API with the api_key" do
-      client.tagged_snitches(tags)
-
-      expect(a_request(:get, url)).to have_been_made.once
-    end
-
-    it "returns the snitches" do
-      expect(client.tagged_snitches(tags)).to be_a(Array)
-      expect(client.tagged_snitches(tags).first).to be_a(Snitcher::API::Snitch)
-    end
-
-    it "supports spaces in tags" do
-      request = stub_request(:get, "#{snitch_url}?tags=phoenix%20foundary,murggle").
-        to_return(body: body, status: 200)
-
-      client.tagged_snitches("phoenix foundary", "murggle")
-
-      expect(request).to have_been_made.once
-    end
-
-    it "allows an array to be passed for tags" do
-      request = stub_request(:get, "#{snitch_url}?tags=murggle,gurgggle").
-        to_return(body: body, status: 200)
-
-      client.tagged_snitches(["murggle", "gurgggle"])
-
-      expect(request).to have_been_made.once
-    end
-  end
-
   describe "#create_snitch" do
     let(:data)  {
                   {
@@ -443,6 +400,14 @@ describe Snitcher::API::Client do
       expect(a_request(:delete, url)).to have_been_made.once
     end
 
+    it "properly escapes tags with spaces" do
+      request = stub_request(:delete, "#{snitch_url}/c2354d53d2/tags/tag+with+spaces").
+        to_return(:body => body, :status => 200)
+
+      client.remove_tag(token, "tag with spaces")
+      expect(request).to have_been_made.once
+    end
+
     context "when successful" do
       it "returns an array of the snitch's remaining tags" do
         expect(client.remove_tag(token, tag)).to eq(JSON.parse(body))

data/spec/api/error_spec.rb

@@ -1,4 +1,7 @@
-describe Snitcher::API::Error do
+require "spec_helper"
+require "snitcher/api"
+
+RSpec.describe Snitcher::API::Error do
   it "returns a AuthenticationError for 'sign_in_incorrect'" do
     error = Snitcher::API::Error.new({
       "type"  => "sign_in_incorrect",
@@ -58,5 +61,4 @@ describe Snitcher::API::Error do
     expect(error).to be_a(Snitcher::API::ResourceNotFoundError)
     expect(error.message).to eq("I can't find that!!")
   end
-
 end

data/spec/api/snitch_spec.rb

@@ -2,30 +2,32 @@ require "spec_helper"
 require "snitcher/api"
 require "snitcher/api/snitch"
 
-describe Snitcher::API::Snitch do
+RSpec.describe Snitcher::API::Snitch do
   describe "#new" do
-    before do
+    let(:snitch) do
       payload = {
-        "token" => "c2354d53d3",
-        "name" => "Daily Backups",
-        "type" => {
-          "interval" => "daily"
+        "token"       => "c2354d53d3",
+        "name"        => "Daily Backups",
+        "alert_email" => ["user@example.com"],
+        "notes"       => "Important user data.",
+        "type"        => {
+          "interval" => "daily",
         },
-        "notes" => "Important user data."
       }
 
-      @snitch = Snitcher::API::Snitch.new(payload)
+      Snitcher::API::Snitch.new(payload)
     end
 
     it "returns a Snitch object" do
-      expect(@snitch).to be_a(Snitcher::API::Snitch)
+      expect(snitch).to be_a(Snitcher::API::Snitch)
     end
 
     it "sets appropriate values" do
-      expect(@snitch.name).to eq("Daily Backups")
-      expect(@snitch.token).to eq("c2354d53d3")
-      expect(@snitch.notes).to eq("Important user data.")
-      expect(@snitch.interval).to eq("daily")
+      expect(snitch.name).to eq("Daily Backups")
+      expect(snitch.token).to eq("c2354d53d3")
+      expect(snitch.notes).to eq("Important user data.")
+      expect(snitch.interval).to eq("daily")
+      expect(snitch.alert_email).to eq(["user@example.com"])
     end
   end
 end

data/spec/api_spec.rb

@@ -1,78 +1,6 @@
 require "spec_helper"
 
-require "base64"
-require "securerandom"
-
 require "snitcher/api"
 
 describe Snitcher::API do
-  describe "#get_key" do
-    it "returns the api_key" do
-      user = "alice@example.com"
-      pass = "password"
-
-      request = stub_request(:get, "https://api.deadmanssnitch.com/v1/api_key").
-        with(basic_auth: [user, pass]).
-        to_return({
-          :body   => '{"api_key": "_caeEiZXnEyEzXXYVh2NhQ"}',
-          :status => 200
-        })
-
-      actual = Snitcher::API.get_key(user, pass)
-
-      expect(actual).to eq("_caeEiZXnEyEzXXYVh2NhQ")
-      expect(request).to have_been_made.once
-    end
-
-    it "raises an error if authentication failed" do
-      user = "lol@notreally.horse"
-      pass = "nope"
-
-      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",
-            :error => "Invalid email or password."
-          }),
-          :status => 401
-        })
-
-      expect {
-        # Some shenanigans to verify type
-        begin
-          Snitcher::API.get_key(user, pass)
-        rescue Snitcher::API::Error => e
-          expect(e.type).to eq("sign_in_incorrect")
-          expect(e.message).to eq("Invalid email or password.")
-
-          raise e
-        end
-      }.to raise_error(Snitcher::API::AuthenticationError)
-
-      expect(request).to have_been_made.once
-    end
-
-    it "raises Timeout::Error on a timeout" do
-      stub_request(:any, "https://api.deadmanssnitch.com/v1/api_key").to_timeout
-
-      expect {
-        Snitcher::API.get_key("", "")
-      }.to raise_error(Timeout::Error)
-    end
-
-    it "allows the API URI to be provided" do
-      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
-        })
-
-      actual = Snitcher::API.get_key("user", "pass", uri: "http://dms.dev:4000")
-
-      expect(actual).to eq("this_is_an_api_key")
-      expect(request).to have_been_made.once
-    end
-  end
 end

data/spec/snitcher_spec.rb

@@ -9,15 +9,15 @@ describe Snitcher do
     stub_request(:get, /nosnch\.in/)
   end
 
-  describe ".snitch" do
+  describe ".snitch!" do
     it "pings DMS with the given token" do
-      Snitcher.snitch(token)
+      Snitcher.snitch!(token)
 
       expect(a_request(:get, "https://nosnch.in/#{token}")).to have_been_made.once
     end
 
     it "includes a custom user-agent" do
-      Snitcher.snitch(token)
+      Snitcher.snitch!(token)
 
       expect(
         a_request(:get, "https://nosnch.in/#{token}").with(
@@ -26,42 +26,61 @@ describe Snitcher do
       ).to have_been_made
     end
 
-    context "when successful" do
-      before do
-        stub_request(:get, "https://nosnch.in/#{token}").to_return(status: 200)
-      end
+    it "returns true when successful" do
+      request = stub_request(:get, "https://nosnch.in/#{token}").to_return(status: 202)
 
-      it "returns true" do
-        expect(Snitcher.snitch(token)).to eq(true)
-      end
+      expect(Snitcher.snitch!(token)).to eq(true)
+      expect(request).to have_been_made.once
     end
 
-    context "when unsuccessful" do
-      before do
-        stub_request(:get, "https://nosnch.in/#{token}").to_return(status: 404)
-      end
+    it "returns false when unsuccessful" do
+      request = stub_request(:get, "https://nosnch.in/#{token}").to_return(status: 404)
 
-      it "returns false" do
-        expect(Snitcher.snitch(token)).to eq(false)
-      end
+      expect(Snitcher.snitch!(token)).to eq(false)
+      expect(request).to have_been_made.once
     end
 
     describe "with message" do
       it "includes the message as a query param" do
-        Snitcher.snitch(token, message: "A thing just happened")
+        Snitcher.snitch!(token, message: "A thing just happened")
 
         expect(a_request(:get, "https://nosnch.in/#{token}?m=A%20thing%20just%20happened")).to have_been_made
       end
     end
 
-    describe "timeout" do
-      before do
-        stub_request(:get, "https://nosnch.in/#{token}").to_raise(::Timeout::Error)
-      end
+    specify "with status" do
+      Snitcher.snitch!(token, status: "0")
+      expect(a_request(:get, "https://nosnch.in/#{token}?s=0")).to have_been_made
 
-      it "returns false when timed out" do
-        expect(Snitcher.snitch(token)).to eq(false)
-      end
+      Snitcher.snitch!(token, status: 1237)
+      expect(a_request(:get, "https://nosnch.in/#{token}?s=1237")).to have_been_made
+
+      # Both nil and "" avoid adding the `s` query param.
+      Snitcher.snitch!(token, status: nil)
+      Snitcher.snitch!(token, status: "")
+      expect(a_request(:get, "https://nosnch.in/#{token}")).to have_been_made.twice
+    end
+
+    it "raises a Timeout::Error if the request timesout" do
+      stub_request(:get, "https://nosnch.in/#{token}").to_timeout
+
+      expect { Snitcher.snitch!(token) }.to raise_error(Timeout::Error)
+    end
+  end
+
+  describe ".snitch" do
+    it "returns true on a successfuly check-in" do
+      stub_request(:get, "https://nosnch.in/#{token}").to_return(status: 202)
+
+      result = Snitcher.snitch(token)
+      expect(result).to be(true)
+    end
+
+    it "returns false on a timeout" do
+      stub_request(:get, "https://nosnch.in/#{token}").to_timeout
+
+      result = Snitcher.snitch(token)
+      expect(result).to be(false)
     end
   end
 

metadata

@@ -1,44 +1,44 @@
 --- !ruby/object:Gem::Specification
 name: snitcher
 version: !ruby/object:Gem::Version
-  version: 0.4.0.rc1
+  version: 0.4.2
 platform: ruby
 authors:
 - Collective Idea
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2016-05-13 00:00:00.000000000 Z
+date: 2021-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.1'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.1'
-description: 
+        version: '0'
+description:
 email: hi@deadmanssnitch.com
 executables:
 - snitch
@@ -54,6 +54,7 @@ files:
 - Rakefile
 - bin/snitch
 - doc/get_them_stitches.jpg
+- examples/api.rb
 - lib/snitcher.rb
 - lib/snitcher/api.rb
 - lib/snitcher/api/client.rb
@@ -73,7 +74,7 @@ homepage: https://github.com/deadmanssnitch/snitcher
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -84,13 +85,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
-signing_key: 
+rubygems_version: 3.2.15
+signing_key:
 specification_version: 4
 summary: Simple API client for deadmanssnitch.com
 test_files:
@@ -102,4 +102,3 @@ test_files:
 - spec/spec_helper.rb
 - spec/support/random.rb
 - spec/support/webmock.rb
-has_rdoc: