simple_spark 0.0.1

data/lib/simple_spark/endpoints/message_events.rb

@@ -0,0 +1,31 @@
+module SimpleSpark
+  module Endpoints
+    # Provides access to the /message-events endpoint
+    # @note See: https://developers.sparkpost.com/api/#/reference/message-events
+    class MessageEvents
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Returns sample message_events
+      # @param events [String] Event types for which to get a sample payload, use the Webhooks Events endpoint to list the
+      #   available event types, defaults to all event types
+      # @return [Array] a list of sample MessageEvent hash objects
+      # @note See: https://developers.sparkpost.com/api/#/reference/message-events/events-samples
+      def samples(events = nil)
+        query_params = events.nil? ? {} : { events: events }
+        @client.call(:get, 'message-events/events/samples', {}, query_params)
+      end
+
+      # Perform a filtered search for message event data. The response is sorted by descending timestamp.
+      # @param params [String] Params to use in the search
+      # @return [Array] a list of MessageEvent hash objects
+      # @note See: https://developers.sparkpost.com/api/#/reference/message-events/search-for-message-events
+      def search(params = {})
+        @client.call(:get, 'message-events', {}, params)
+      end
+    end
+  end
+end

data/lib/simple_spark/endpoints/sending_domains.rb

@@ -0,0 +1,74 @@
+module SimpleSpark
+  module Endpoints
+    # Provides access to the /sending-domains endpoint
+    # @note Example sending domain
+    #   { "domain": "example1.com", "tracking_domain": "click.example1.com",
+    #   "status": { "ownership_verified": true, "spf_status": "valid", "abuse_at_status": "valid",
+    #   "abuse_at_status": "valid", "dkim_status": "valid", "compliance_status": "valid", "postmaster_at_status": "valid" } }
+    # @note See: https://developers.sparkpost.com/api/#/reference/sending-domains
+    class SendingDomains
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Lists your sending domains
+      # @return [Array] a list of Sending Domain hash objects
+      # @note See: https://developers.sparkpost.com/api/#/reference/sending-domains/create-and-list/list-all-sending-domains
+      def list
+        @client.call(:get, 'sending-domains')
+      end
+
+      # Create a sending domain
+      # @param domain_name [String] the domain name to create
+      # @param tracking_domain [String] the domain name to track this domain against
+      # @note See: https://developers.sparkpost.com/api/#/reference/sending-domains/create-and-list
+      def create(domain_name, tracking_domain)
+        @client.call(:post, 'sending-domains', domain: domain_name, tracking_domain: tracking_domain)
+      end
+
+      # Retrieve a sending domain
+      # @param domain_name [String] the domain name to retrieve
+      # @return [Hash] an Sending Domain hash object
+      # @note See: https://developers.sparkpost.com/api/#/reference/sending-domains/retrieve-update-and-delete
+      def retrieve(domain_name)
+        domain_name = @client.url_encode(domain_name)
+        @client.call(:get, "sending-domains/#{domain_name}")
+      end
+
+      # Update a Sending Domain by its domain name
+      # @param domain_name [String] the domain to update
+      # @param values [Hash] the values to update the sending domain with
+      #
+      # @note See: https://developers.sparkpost.com/api/#/reference/sending-domains/retrieve-update-and-delete
+      def update(domain_name, values)
+        domain_name = @client.url_encode(domain_name)
+        @client.call(:put, "sending-domains/#{domain_name}", values)
+      end
+
+      # Verify a Sending Domain by its domain name
+      # @param domain_name [String] the domain to verify
+      # @param values [Hash] the values specifying how to verify the domain
+      #   Including the fields "dkim_verify" and/or "spf_verify" in the request initiates a check against the associated DNS record
+      #   type for the specified sending domain.Including the fields "postmaster_at_verify" and/or "abuse_at_verify" in the request
+      #   results in an email sent to the specified sending domain's postmaster@ and/or abuse@ mailbox where a verification link can
+      #   be clicked.Including the fields "postmaster_at_token" and/or "abuse_at_token" in the request initiates a check of the provided
+      #   token(s) against the stored token(s) for the specified sending domain.
+      #
+      # @note See: https://developers.sparkpost.com/api/#/reference/sending-domains/verify
+      def verify(domain_name, values)
+        domain_name = @client.url_encode(domain_name)
+        @client.call(:post, "sending-domains/#{domain_name}", values)
+      end
+
+      # Delete a sending domain
+      # @param domain_name [String] the domain name to delete
+      # @note See: https://developers.sparkpost.com/api/#/reference/sending-domains/retrieve-update-and-delete
+      def delete(domain_name)
+        domain_name = @client.url_encode(domain_name)
+        @client.call(:delete, "sending-domains/#{domain_name}")
+      end
+    end
+  end
+end

data/lib/simple_spark/endpoints/templates.rb

@@ -0,0 +1,80 @@
+module SimpleSpark
+  module Endpoints
+    # Provides access to the /templates endpoint
+    # @note See: https://developers.sparkpost.com/api/#/reference/templates
+    # @note Sample Template
+    #   { "id"=>"102293692714480130", "name"=>"Summer Sale!", "description"=>"", "published"=>false, "options"=>{},
+    #    "last_update_time"=>"2016-03-02T22:49:23+00:00",
+    #    "content"=>{"from"=>"marketing@neekme.com", "subject"=>"Summer deals", "html"=>"<b>Check out these deals!</b>"} }
+    class Templates
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Lists the most recent version of each template in your account.
+      # @return [Array] a list of Template hash objects
+      # @note See: https://developers.sparkpost.com/api/#/reference/templates/create-and-list
+      def list
+        @client.call(:get, 'templates')
+      end
+
+      # Create a template by providing values for the template object.
+      # @param values [Hash] containing the properties. At a minimum, the "name" and "content"
+      #   fields are required, where content must contain the "from", "subject", and at
+      #   least one of "html" or "text" fields.
+      # @return [boolean] true if success
+      # @note See: https://developers.sparkpost.com/api/#/reference/templates/create-and-list
+      def create(values)
+        @client.call(:post, 'templates', values)
+      end
+
+      # Retrieve a Template by its ID
+      # @param id [String] the Unique Template ID to retrieve
+      # @param draft [boolean] If true, returns the most recent draft template.
+      #   If false, returns the most recent published template.
+      #   If not provided, returns the most recent template version regardless of draft or published.
+      # @return [Hash] the Template object
+      # @note https://developers.sparkpost.com/api/#/reference/templates/retrieve
+      def retrieve(id, draft = nil)
+        path = "templates/#{id}"
+        query_params = draft.nil? ? {} : { draft: draft }
+        @client.call(:get, path, {}, query_params)
+      end
+
+      # Update a Template by its ID
+      # @param id [String] the Unique Template ID to update
+      # @param values [Hash] the values to update the template with
+      # @param update_published [boolean] If true, directly overwrite the existing published template. If false, create a new draft.
+      #   If this template isn't yet published, setting to 'true' will result in a NotFound error
+      #
+      # @note See: https://developers.sparkpost.com/api/#/reference/templates/update
+      def update(id, values, update_published = false)
+        @client.call(:put, "templates/#{id}", values,  update_published: update_published)
+      end
+
+      # Preview a Template by its ID
+      # @param id [String] the Unique Template ID to preview
+      # @param substitutions [Hash] the values to update the template with. Must contain a key 'substitution_data'
+      #    { "substitution_data" => { "name" => "Natalie", "age" => 35, "member" => true }
+      # @param draft [boolean] If true, returns the most recent draft template.
+      #   If false, returns the most recent published template.
+      #   If not provided, returns the most recent template version regardless of draft or published.
+      #
+      # @note See: https://developers.sparkpost.com/api/#/reference/templates/preview
+      def preview(id, substitutions, draft = nil)
+        query_params = draft.nil? ? {} : { draft: draft }
+        @client.call(:post, "templates/#{id}/preview", substitutions, query_params)
+      end
+
+      # Delete a Template by its ID
+      # @param id [String] the Unique Template ID to delete
+      #
+      # @note See: https://developers.sparkpost.com/api/#/reference/templates/delete
+      def delete(id)
+        @client.call(:delete, "templates/#{id}")
+      end
+    end
+  end
+end

data/lib/simple_spark/endpoints/transmissions.rb

@@ -0,0 +1,60 @@
+module SimpleSpark
+  module Endpoints
+    # Provides access to the /transmissions endpoint
+    # See: https://developers.sparkpost.com/api/#/reference/transmissions
+    class Transmissions
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Sends an email message
+      # @param values [Hash] the values to send with. This can be a complex object depending on the options chosen.
+      # @param num_rcpt_errors [Integer] limit the number of recipient errors returned. Will default to all
+      # @returns { results: { total_rejected_recipients: 0, total_accepted_recipients: 1, id: "11668787484950529" } }
+      # @note See: https://developers.sparkpost.com/api/#/reference/transmissions/create
+      # @note Example:
+      #   properties = {
+      #     options: { open_tracking: true, click_tracking: true },
+      #     campaign_id: 'christmas_campaign',
+      #     return_path: 'bounces-christmas-campaign@sp.neekme.com',
+      #     metadata: {user_type: 'students'},
+      #     substitution_data: { sender: 'Big Store Team' },
+      #     recipients:  [
+      #       { address: { email: 'yourcustomer@theirdomain.com', name: 'Your Customer' },
+      #         tags: ['greeting', 'sales'],
+      #         metadata: { place: 'Earth' }, substitution_data: { address: '123 Their Road' } }
+      #     ],
+      #     content:
+      #     { from: { name: 'Your Name', email: 'you@yourdomain.com' },
+      #       subject: 'I am a test email',
+      #       reply_to: 'Sales <sales@yourdomain.com>',
+      #       headers: { 'X-Customer-CampaignID' => 'christmas_campaign' },
+      #       text: 'Hi from {{sender}} ... this is a test, and here is your address {{address}}',
+      #       html: '<p>Hi from {{sender}}</p<p>This is a test</p>'
+      #     }
+      #   }
+      def create(values, num_rcpt_errors = nil)
+        query_params = num_rcpt_errors.nil? ? {} : { num_rcpt_errors: num_rcpt_errors }
+        @client.call(:post, 'transmissions', values, query_params)
+      end
+
+      # Sends an email message
+      # @param campaign_id [String] limit results to this Campaign ID
+      # @param template_id [String] limit results to this Template ID
+      # @returns [ { "content": { "template_id": "winter_sale" }, "id": "11713562166689858",
+      #   "campaign_id": "thanksgiving", "description": "", "state": "submitted" } ]
+      # @note See: https://developers.sparkpost.com/api/#/reference/transmissions/list
+      def list(campaign_id = nil, template_id = nil)
+        query_params = {}
+        query_params[:campaign_id] = campaign_id if campaign_id
+        query_params[:template_id] = template_id if template_id
+        @client.call(:get, 'transmissions', {}, query_params)
+      end
+
+      # send_message to be reserved as a 'quick' helper method to avoid using hash for Create
+      # alias_method :send_message, :create
+    end
+  end
+end

data/lib/simple_spark/endpoints/webhooks.rb

@@ -0,0 +1,77 @@
+module SimpleSpark
+  module Endpoints
+    # Provides access to the /webhooks endpoint
+    # @note Example webhook
+    # @note See: https://developers.sparkpost.com/api/#/reference/webhooks
+    class Webhooks
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      # List currently extant webhooks
+      # @return [Array] a list of Webhook hash objects
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/list
+      def list(timezone = nil)
+        query_params = timezone.nil? ? {} : { timezone: timezone }
+        @client.call(:get, 'webhooks', {}, query_params)
+      end
+
+      # Create a webhook
+      # @param values [Hash] the values to create the webhook with
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/create
+      def create(values)
+        @client.call(:post, 'webhooks', values)
+      end
+
+      # Retrieve details about a webhook by specifying its id
+      # @param id [String] the ID of the webhook
+      # @return [Hash] an Webhook hash object
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/retrieve
+      def retrieve(id)
+        @client.call(:get, "webhooks/#{id}")
+      end
+
+      # Update a Webhook by its ID
+      # @param id [String] the ID of the webhook
+      # @param values [Hash] the values to update the webhook with
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/update-and-delete
+      def update(id, values)
+        @client.call(:put, "webhooks/#{id}", values)
+      end
+
+      # Validates a Webhook by sending an example message event batch from the Webhooks API to the target URL
+      # @param id [String] the ID of the webhook
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/validate
+      def validate(id)
+        @client.call(:post, "webhooks/#{id}/validate")
+      end
+
+      # Batch status information
+      # @param id [String] the ID of the webhook
+      # @return [Array] a list of status hash objects
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/batch-status
+      def batch_status(id, limit = nil)
+        query_params = limit.nil? ? {} : { limit: limit }
+        @client.call(:get, "webhooks/#{id}/batch-status", {}, query_params)
+      end
+
+      # Returns sample event data
+      # @param events [String] Event types for which to get a sample payload
+      # @return [Array] a list of sample event hash objects
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/events-samples
+      def samples(events = nil)
+        query_params = events.nil? ? {} : { events: events }
+        @client.call(:get, 'webhooks/events/samples', {}, query_params)
+      end
+
+      # Delete a webhook
+      # @param id [String] the ID
+      # @note See: https://developers.sparkpost.com/api/#/reference/webhooks/update-and-delete
+      def delete(id)
+        @client.call(:delete, "webhooks/#{id}")
+      end
+    end
+  end
+end

data/lib/simple_spark/exceptions.rb

@@ -0,0 +1,39 @@
+module SimpleSpark
+  module Exceptions
+    # Adding an object to the exception to pass errors back
+    # begin
+    #   raise Error.new({ id: '1' }), "a message"
+    # rescue Error => e
+    #   puts e.message # => "a message"
+    #   puts e.object # => { id: '1' }
+    # end
+    class Error < StandardError
+      attr_reader :object
+
+      def initialize(object = nil)
+        @object = object
+      end
+
+      def self.fail_with_exception_for_status(status, errors)
+        exception = status_codes[status.to_s] || status_codes['default']
+        fail exception.new(errors), errors.map { |e| "#{e['message']}" + (e['description'] ? ": #{e['description']}" : '') }.join(', ')
+      end
+
+      def self.status_codes
+        {
+          'default' => Exceptions::UnprocessableEntity,
+          '400' => Exceptions::BadRequest,
+          '404' => Exceptions::NotFound,
+          '422' => Exceptions::UnprocessableEntity,
+          '420' => Exceptions::ThrottleLimitExceeded
+        }
+      end
+    end
+
+    class InvalidConfiguration < Error; end
+    class BadRequest < Error; end
+    class NotFound < Error; end
+    class UnprocessableEntity < Error; end
+    class ThrottleLimitExceeded < Error; end
+  end
+end

data/lib/simple_spark/version.rb

@@ -0,0 +1,3 @@
+module SimpleSpark
+  VERSION = "0.0.1"
+end

data/lib/simple_spark.rb

@@ -0,0 +1,10 @@
+require 'simple_spark/version'
+require 'simple_spark/client'
+require 'simple_spark/exceptions'
+require 'simple_spark/endpoints/transmissions'
+require 'simple_spark/endpoints/templates'
+require 'simple_spark/endpoints/inbound_domains'
+require 'simple_spark/endpoints/sending_domains'
+require 'simple_spark/endpoints/message_events'
+require 'simple_spark/endpoints/webhooks'
+

data/simple_spark.gemspec

@@ -0,0 +1,35 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'simple_spark/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'simple_spark'
+  spec.version       = SimpleSpark::VERSION
+  spec.authors       = ['Jak Charlton']
+  spec.email         = ['jakcharlton@gmail.com']
+  spec.summary       = 'A library for accessing the SparkPost REST API http://www.sparkpost.com'
+  spec.description   = 'An alternative to the official SparkPost Ruby gem'
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rake', '~> 0.9.6'
+
+  spec.add_development_dependency 'rspec', '~> 3.4.0'
+  spec.add_development_dependency 'rspec-nc', '~> 0'
+  spec.add_development_dependency 'guard', '~> 2.13'
+  spec.add_development_dependency 'guard-rspec', '~> 4.6.4'
+  spec.add_development_dependency 'pry', '~> 0'
+  spec.add_development_dependency 'pry-remote', '~> 0'
+  spec.add_development_dependency 'pry-nav', '~> 0'
+  spec.add_development_dependency 'climate_control', '~> 0'
+
+  spec.add_dependency 'json', '>= 1.7.7', '< 2.0'
+  spec.add_dependency 'excon', '>= 0.16.0', '< 1.0'
+end

data/spec/simple_spark/client_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe SimpleSpark::Client do
+  describe :initialize do
+    it 'will raise when no API key provided' do
+      expect { SimpleSpark::Client.new }.to raise_error(SimpleSpark::Exceptions::InvalidConfiguration, 'You must provide a SparkPost API key')
+    end
+
+    context 'defaults' do
+      let(:client) { SimpleSpark::Client.new('mykey') }
+      specify { expect(client.instance_variable_get(:@api_key)).to eq('mykey') }
+      specify { expect(client.instance_variable_get(:@api_host)).to eq('https://api.sparkpost.com') }
+      specify { expect(client.instance_variable_get(:@base_path)).to eq('/api/v1/') }
+      specify { expect(client.instance_variable_get(:@session).class).to eq(Excon::Connection) }
+      specify { expect(client.instance_variable_get(:@debug)).to eq(false) }
+    end
+
+    it 'will use the API key from the ENV var' do
+      with_modified_env SPARKPOST_API_KEY: 'mykey' do
+        expect(SimpleSpark::Client.new.instance_variable_get(:@api_key)).to eq('mykey')
+      end
+    end
+
+    it 'will use the base_path provided' do
+      expect(SimpleSpark::Client.new('mykey', nil, 'base').instance_variable_get(:@base_path)).to eq('base')
+    end
+
+    it 'will use the debug option provided' do
+      expect(SimpleSpark::Client.new('mykey', nil, nil, true).instance_variable_get(:@debug)).to eq(true)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'pry'
+require 'simple_spark'
+require 'climate_control'
+
+def with_modified_env(options, &block)
+  ClimateControl.modify(options, &block)
+end