mailgun-tracking 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 87dcc660603620c0e746e9ed5cf5cc1584149ece
-  data.tar.gz: aad18416dca8c386cb96104c67a07512f847e84c
+  metadata.gz: 0f2b53add355033fc2a5b6cc4f93dc1818fdd4f5
+  data.tar.gz: 2abd9e0afdc9621f48584160547756b721ca0e10
 SHA512:
-  metadata.gz: d858782b928aa9b6e4ef1025c9614001f64ada0ac7a9fd42e37ddbe24b9f08ff2d1a94428a80f67dbb08bca0d853dfbb1d06fa06f5c6784a47df75335a09844e
-  data.tar.gz: 3fb5f7a36243749311a452ea220df5dcc1fea92ac9671f54febdb9d818f64f7ebdc47c812d7c75acbc930c336b790c236f1eb1de5b810f5025d5d0e805592d8b
+  metadata.gz: 8d6781261987073ad9cee2f8bf7b516892798a8b08dd5aebfe392204fcb417e2033ac8481a4f4c17a9114c7ecaf052b1b4e4f314bb9165ebedad7752f017dcd2
+  data.tar.gz: cff2a9d86aec1d5bb1b23e39074ae3eafb8e96cdf1907b8ec63b7055119c269f2321764393622206921d8ea82849435633cf8485d2e5d92369b69d18865a6751

data/lib/generators/mailgun/tracking/install_generator.rb

@@ -0,0 +1,19 @@
+module Mailgun
+  module Tracking
+    # Creates the Mailgun Tracking initializer file for Rails apps.
+    #
+    # @example Invokation from terminal
+    #   rails generate mailgun:tracking:install API_KEY ENDPOINT
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('../templates', __FILE__)
+
+      argument :api_key, required: false
+      argument :endpoint, required: false
+
+      # Copies the initialization file.
+      def copy_initializer_file
+        template('mailgun_tracking.rb.erb', 'config/initializers/mailgun_tracking.rb')
+      end
+    end
+  end
+end

data/lib/generators/mailgun/tracking/templates/mailgun_tracking.rb.erb

@@ -0,0 +1,15 @@
+Mailgun::Tracking.configure do |config|
+  # Mailgun API public key.
+<% if api_key -%>
+  config.api_key = <%= api_key %>
+<% else -%>
+  config.api_key = ENV['MAILGUN_API_KEY']
+<% end -%>
+
+  # Mailgun Webhook API endpoint. Default is '/mailgun'.
+<% if endpoint -%>
+  config.endpoint = <%= endpoint %>
+<% else -%>
+  # config.endpoint = '/mailgun-tracking'
+<% end -%>
+end

data/lib/mailgun/tracking.rb

@@ -7,14 +7,30 @@ require 'mailgun/tracking/subscriber'
 require 'mailgun/tracking/version'
 require 'mailgun/tracking/railtie' if defined?(Rails)
 
+# Module for interacting with the Mailgun.
 module Mailgun
+  # Namespace for classes and modules that handle Mailgun Webhooks.
   module Tracking
     DEFAULT_ENDPOINT = '/mailgun'.freeze
 
     class << self
-      attr_accessor :api_key,
-                    :endpoint
+      # Mailgun API public key.
+      #
+      # @return [String]
+      attr_accessor :api_key
 
+      # Mailgun Webhook API endpoint
+      #
+      # @return [String]
+      attr_accessor :endpoint
+
+      # Default way to setup Mailgun Tracking.
+      #
+      # @example
+      #   Mailgun::Tracking.configure do |config|
+      #     config.api_key = ENV['MAILGUN_API_KEY']
+      #     config.endpoint = '/mailgun-tracking'
+      #   end
       def configure
         yield(self)
       end
@@ -24,6 +40,22 @@ module Mailgun
 
     module_function
 
+    # A Notifier instance.
+    #
+    # @example
+    #   Mailgun::Tracking.configure do |config|
+    #     config.notifier.subscribe :delivered do |payload|
+    #       # Do something with the incoming data.
+    #     end
+    #
+    #     config.notifier.subscribe :bounced, Bounced.new
+    #
+    #     config.notifier.all do |payload|
+    #       # Handle all event types.
+    #     end
+    #   end
+    #
+    # @return [Mailgun::Tracking::Notifier]
     def notifier
       @notifier ||= Notifier.new
     end

data/lib/mailgun/tracking/exceptions.rb

@@ -1,6 +1,9 @@
 module Mailgun
   module Tracking
+    # A general Mailgun Tracking exception.
     Error = Class.new(StandardError)
+
+    # Raised when signature is invalid.
     InvalidSignature = Class.new(Error)
   end
 end

data/lib/mailgun/tracking/listener.rb

@@ -1,22 +1,50 @@
 module Mailgun
   module Tracking
+    # Represents a mechanism for event listeners to subscribe to events and for event broadcasts.
     class Listener
+      # List of subscribers.
+      #
+      # @return [Array<Mailgun::Tracking::Subscriber::AllMessages, Mailgun::Tracking::Subscriber::Evented>]
       attr_reader :subscribers
 
+      # Initializes a new Listener object.
+      #
+      # @return [Mailgun::Tracking::Listener]
       def initialize
         @subscribers = []
       end
 
+      # Adds a subscriber to the list of subscribers for the specified event.
+      #
+      # @param event [Symbol, String] The name of event.
+      # @param callable [Proc, Class] The listener of event.
+      #   The callable objects should respond to call.
+      #
+      # @return [Array<Mailgun::Tracking::Subscriber::AllMessages, Mailgun::Tracking::Subscriber::Evented>]
+      #   The list of subscribers.
       def add_subscriber(event, callable)
         @subscribers << Subscriber.for(event, callable)
       end
 
+      # Broadcasts an event to the subscribers.
+      #
+      # @param event [String] The name of event.
+      # @param payload [Hash] The response parameters.
+      #
+      # @return [Array<Mailgun::Tracking::Subscriber::AllMessages, Mailgun::Tracking::Subscriber::Evented>]
+      #   The list of subscribers.
       def broadcast(event, payload)
         subscribers_for(event).each { |subscriber| subscriber.call(payload) }
       end
 
       private
 
+      # Selects the subscribers for the specified event.
+      #
+      # @param event [String] The name of event.
+      #
+      # @return [Array<Mailgun::Tracking::Subscriber::AllMessages, Mailgun::Tracking::Subscriber::Evented>]
+      #   The list of subscribers.
       def subscribers_for(event)
         @subscribers.select { |subscriber| subscriber.subscribed_to?(event) }
       end

data/lib/mailgun/tracking/middleware.rb

@@ -1,16 +1,25 @@
 module Mailgun
   module Tracking
+    # Rack-based middleware to handle event notifications.
     class Middleware
+      # Initializes a new Middleware object.
+      #
+      # @param app the next Rack middleware in the stack.
       def initialize(app)
         @app = app
       end
 
+      # Responds to Rack requests.
+      #
+      # @param env [Hash] Environment hash.
+      #
+      # @return [Array(Numeric,Hash,Array)] The Rack-style response.
       def call(env)
         @env = env
 
         if mailgun_tracking_request?
           Mailgun::Tracking.notifier.broadcast(request.params.fetch('event'), request.params)
-          [200, {}, []]
+          null_response
         else
           @app.call(env)
         end
@@ -18,15 +27,26 @@ module Mailgun
 
       private
 
+      # Interface to a Rack environment.
+      #
+      # @return [Rack::Request]
       def request
         ::Rack::Request.new(@env)
       end
 
+      # Checks if the path of the request is equal to the endpoint.
+      #
+      # @return [Boolean]
       def mailgun_tracking_request?
         return false unless request.post?
         return false unless request.path == Mailgun::Tracking.endpoint
         true
       end
+
+      # @return [Array(Numeric,Hash,Array)] The Rack-style response.
+      def null_response
+        [200, {}, []]
+      end
     end
   end
 end

data/lib/mailgun/tracking/notifier.rb

@@ -1,18 +1,43 @@
 module Mailgun
   module Tracking
+    # Wraps the {Listener} which gives a friendlier way to subscribe or broadcast.
     class Notifier
+      # Initializes a new Notifier object.
+      #
+      # @param listener [Mailgun::Tracking::Listener] Event listener.
+      #
+      # @return [Mailgun::Tracking::Notifier]
       def initialize(listener = Listener.new)
         @listener ||= listener
       end
 
+      # Adds subscriber for the specified event.
+      #
+      # @param event [Symbol, String] The name of event.
+      # @param callable [Proc, Class] The listener of event.
+      #   The callable objects should respond to call.
+      #
+      # @return [NilClass]
       def subscribe(event, callable = Proc.new)
         listener.add_subscriber(event, callable)
       end
 
+      # Adds a subscriber for all events.
+      #
+      # @param callable [Proc, Class] The listener of event.
+      #   The callable objects should respond to call.
+      #
+      # @return [NilClass]
       def all(callable = Proc.new)
         listener.add_subscriber(nil, callable)
       end
 
+      # Broadcasts parameters to event subscribers.
+      #
+      # @param event [String] The name of event.
+      # @param payload [Hash] The response parameters.
+      #
+      # @return [NilClass]
       def broadcast(event, payload)
         Signature.verify!(payload)
         listener.broadcast(event, payload)
@@ -20,6 +45,7 @@ module Mailgun
 
       private
 
+      # @return [Mailgun::Tracking::Listener]
       attr_reader :listener
     end
   end

data/lib/mailgun/tracking/railtie.rb

@@ -1,5 +1,6 @@
 module Mailgun
   module Tracking
+    # Mailgun Tracking Railtie.
     class Railtie < Rails::Railtie
       initializer 'mailgun-tracking.insert_middleware' do |app|
         app.config.middleware.use(Mailgun::Tracking::Middleware)

data/lib/mailgun/tracking/signature.rb

@@ -2,29 +2,47 @@ require 'openssl'
 
 module Mailgun
   module Tracking
+    # A Mailgun::Tracking::Signature object is used to verify the signature.
     class Signature
+      # Verify the signature of the response parameters.
+      #
+      # @param payload [Hash]
+      # @raise [InvalidSignature] Error raised when signature is invalid.
+      #
+      # @return [Boolean]
+      #   Always returns true.
       def self.verify!(payload)
         signature = new(payload)
         raise InvalidSignature unless signature.valid?
         true
       end
 
+      # Initializes a new Signature object.
+      #
+      # @param payload [Hash]
+      #
+      # @return [Mailgun::Tracking::Signature]
       def initialize(payload)
         @token = payload.fetch('token')
         @timestamp = payload.fetch('timestamp')
         @signature = payload.fetch('signature')
       end
 
+      # @return [Boolean]
       def valid?
         @signature == OpenSSL::HMAC.hexdigest(digest, Mailgun::Tracking.api_key, data)
       end
 
       private
 
+      # @return [OpenSSL::Digest::SHA256]
       def digest
         OpenSSL::Digest::SHA256.new
       end
 
+      # Joins the timestamp and the response token.
+      #
+      # @return [String]
       def data
         [@timestamp, @token].join
       end

data/lib/mailgun/tracking/subscriber.rb

@@ -3,7 +3,15 @@ require 'mailgun/tracking/subscriber/evented'
 
 module Mailgun
   module Tracking
+    # Namespace for classes that wraps subscribers.
     module Subscriber
+      # Determines the type of subscription.
+      #
+      # @param name [Symbol, String] The name of event.
+      # @param callable [Proc, Class] The callable object.
+      #   The callable objects should respond to call.
+      #
+      # @return [Mailgun::Tracking::Subscriber::Evented, Mailgun::Tracking::Subscriber::AllMessages]
       def self.for(name, callable)
         if name
           Evented.new(name, callable)

data/lib/mailgun/tracking/subscriber/all_messages.rb

@@ -1,15 +1,31 @@
 module Mailgun
   module Tracking
     module Subscriber
+      # Wraps the subscriber for events.
       class AllMessages
+        # Initializes a new AllMessages object.
+        #
+        # @param callable [Proc, Class] The callable object.
+        #   The callable objects should respond to call.
+        #
+        # @return [Mailgun::Tracking::Subscriber::AllMessages]
         def initialize(callable)
           @callable = callable
         end
 
+        # Invokes the callable object.
+        #
+        # @param payload [Hash] The response parameters.
+        #
+        # @return [void]
         def call(payload)
           @callable.call(payload)
         end
 
+        # Checks if a callable object is a subscribed to the specified event.
+        #
+        # @return [Boolean]
+        #   Always returns true.
         def subscribed_to?(*)
           true
         end

data/lib/mailgun/tracking/subscriber/evented.rb

@@ -1,16 +1,34 @@
 module Mailgun
   module Tracking
     module Subscriber
+      # Wraps the evented subscriber.
       class Evented
+        # Initializes a new Evented object.
+        #
+        # @param name [Symbol, String] The name of event.
+        # @param callable [Proc, Class] The callable object.
+        #   The callable objects should respond to call.
+        #
+        # @return [Mailgun::Tracking::Subscriber::Evented]
         def initialize(name, callable)
           @name = name.to_sym
           @callable = callable
         end
 
+        # Invokes the callable object.
+        #
+        # @param payload [Hash] The response parameters.
+        #
+        # @return [void]
         def call(payload)
           @callable.call(payload)
         end
 
+        # Checks if a callable object is a subscribed to the specified event.
+        #
+        # @param name [String] The name of event.
+        #
+        # @return [Boolean]
         def subscribed_to?(name)
           @name == name.to_sym
         end

data/lib/mailgun/tracking/version.rb

@@ -1,5 +1,5 @@
 module Mailgun
   module Tracking
-    VERSION = '0.2.0'.freeze
+    VERSION = '0.2.1'.freeze
   end
 end

data/spec/mailgun/tracking/signature_spec.rb

@@ -11,7 +11,7 @@ RSpec.describe Mailgun::Tracking::Signature do
     end
 
     context 'when the signature comparison is unsuccessful' do
-      before { payload.merge!('timestamp' => '') }
+      before { payload['timestamp'] = '' }
 
       it { expect { described_class.verify!(payload) }.to raise_error(Mailgun::Tracking::InvalidSignature) }
     end
@@ -23,7 +23,7 @@ RSpec.describe Mailgun::Tracking::Signature do
     end
 
     context 'when the signature comparison is unsuccessful' do
-      before { payload.merge!('timestamp' => '') }
+      before { payload['timestamp'] = '' }
 
       it { is_expected.not_to be_valid }
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mailgun-tracking
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Artem Chubchenko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-16 00:00:00.000000000 Z
+date: 2017-07-23 00:00:00.000000000 Z
 dependencies: []
 description: Integration with Mailgun Webhooks
 email:
@@ -17,6 +17,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/generators/mailgun/tracking/install_generator.rb
+- lib/generators/mailgun/tracking/templates/mailgun_tracking.rb.erb
 - lib/mailgun/tracking.rb
 - lib/mailgun/tracking/exceptions.rb
 - lib/mailgun/tracking/listener.rb
@@ -66,16 +68,16 @@ signing_key:
 specification_version: 4
 summary: Integration with Mailgun Webhooks
 test_files:
-- spec/fixtures/delivered.json
-- spec/spec_helper.rb
-- spec/mailgun/tracking_spec.rb
-- spec/mailgun/tracking/listener_spec.rb
-- spec/mailgun/tracking/middleware_spec.rb
-- spec/mailgun/tracking/notifier_spec.rb
-- spec/mailgun/tracking/subscriber_spec.rb
 - spec/mailgun/tracking/signature_spec.rb
-- spec/mailgun/tracking/subscriber/evented_spec.rb
 - spec/mailgun/tracking/subscriber/all_messages_spec.rb
-- spec/support/fixture.rb
+- spec/mailgun/tracking/subscriber/evented_spec.rb
+- spec/mailgun/tracking/subscriber_spec.rb
+- spec/mailgun/tracking/listener_spec.rb
+- spec/mailgun/tracking/notifier_spec.rb
+- spec/mailgun/tracking/middleware_spec.rb
+- spec/mailgun/tracking_spec.rb
 - spec/support/rack_helpers.rb
+- spec/support/fixture.rb
 - spec/support/shared_examples/subscriber.rb
+- spec/fixtures/delivered.json
+- spec/spec_helper.rb