sm_sms_campaign_webhook 0.1.1 → 2.1.0

data/app/models/sm_sms_campaign_webhook/campaign_engagement.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "date"
+
+module SmSmsCampaignWebhook
+  # Data model for campaign engagement event from SMS campaign.
+  class CampaignEngagement
+    attr_reader :payload
+
+    # @param payload [Hash] Campaign engagement event payload
+    def initialize(payload:)
+      @payload = payload.deep_dup.freeze
+    end
+
+    # @return [String] Campaign engagement event UUID
+    # @raise [InvalidPayload] when uuid missing from payload
+    def event_uuid
+      @event_uuid ||= String(
+        payload.fetch("uuid") {
+          raise_invalid_payload_for("uuid")
+        }.freeze
+      )
+    end
+
+    # @return [String] Campaign engagement event type
+    # @raise [InvalidPayload] when type missing from payload
+    def event_type
+      @event_type ||= String(
+        payload.fetch("type") {
+          raise_invalid_payload_for("type")
+        }.freeze
+      )
+    end
+
+    # @return [DateTime] Campaign engagement event timestamp
+    # @raise [InvalidPayload] when created_at missing from payload
+    # @raise [InvalidPayloadValue] when created_at not datetime
+    def event_created_at
+      @event_created_at ||= begin
+        raw_created_at = payload.fetch("created_at") {
+          raise_invalid_payload_for("created_at")
+        }
+        DateTime.parse(raw_created_at).freeze
+      end
+    rescue ArgumentError
+      raise InvalidPayloadValue,
+        "created_at has invalid datetime value #{payload.inspect}"
+    end
+
+    # @return [Integer] ID of the engaged campaign
+    # @raise [InvalidPayload] when campaign id missing from payload
+    # @raise [InvalidPayloadValue] when campaign id not numeric
+    def campaign_id
+      @campaign_id ||= Integer(
+        campaign_hash.fetch("id") {
+          raise_invalid_payload_for("campaign id")
+        }
+      )
+    rescue ArgumentError
+      raise InvalidPayloadValue,
+        "campaign id has invalid integer value #{payload.inspect}"
+    end
+
+    # @return [String] Keyword of the engaged campaign
+    # @raise [InvalidPayload] when campaign keyword missing from payload
+    def campaign_keyword
+      @campaign_keyword ||= String(
+        campaign_hash.fetch("keyword") {
+          raise_invalid_payload_for("campaign keyword")
+        }.freeze
+      )
+    end
+
+    # @return [Integer] ID of the engaging phone
+    # @raise [InvalidPayload] when phone id missing from payload
+    # @raise [InvalidPayloadValue] when phone id not numeric
+    def phone_id
+      @phone_id ||= Integer(
+        phone_hash.fetch("id") {
+          raise_invalid_payload_for("phone id")
+        }
+      )
+    rescue ArgumentError
+      raise InvalidPayloadValue,
+        "phone id has invalid integer value #{payload.inspect}"
+    end
+
+    # @return [String] Phone number engaging the campaign
+    # @raise [InvalidPayload] when phone number missing from payload
+    def phone_number
+      @phone_number ||= String(
+        phone_hash.fetch("number") {
+          raise_invalid_payload_for("phone number")
+        }.freeze
+      )
+    end
+
+    # @return [Integer] ID of campaign engagement state record
+    # @raise [InvalidPayload] when phone_campaign_state id missing from payload
+    # @raise [InvalidPayloadValue] when phone_campaign_state id not numeric
+    def phone_campaign_state_id
+      @phone_campaign_state_id ||= Integer(
+        phone_campaign_state_hash.fetch("id") {
+          raise_invalid_payload_for("phone_campaign_state id")
+        }
+      )
+    rescue ArgumentError
+      raise InvalidPayloadValue,
+        "phone_campaign_state id has invalid integer value #{payload.inspect}"
+    end
+
+    # @return [TrueClass,FalseClass] Has campaign engagement completed?
+    # @raise [InvalidPayload] when phone_campaign_state completed missing from payload
+    # @raise [InvalidPayloadValue] when phone_campaign_state completed is not boolean
+    def phone_campaign_state_completed?
+      # Has the boolean value already been assigned?
+      unless @phone_campaign_state_completed.nil?
+        return @phone_campaign_state_completed
+      end
+
+      # Extract the value and memoize it.
+      @phone_campaign_state_completed = begin
+        completed = phone_campaign_state_hash
+          .fetch("completed") {
+            raise_invalid_payload_for("phone_campaign_state completed")
+          }
+
+        # Is this a boolean value?
+        if [true, false].none?(completed)
+          raise InvalidPayloadValue,
+            "phone_campaign_state completed has invalid boolean value #{payload.inspect}"
+        end
+
+        completed
+      end
+    end
+
+    # @return [DateTime,NilClass] Timestamp of campaign engagement completion if completed
+    # @raise [InvalidPayload] when phone_campaign_state completed_at missing from payload
+    # @raise [InvalidPayloadValue] when phone_campaign_state completed_at not datetime
+    def phone_campaign_state_completed_at
+      @phone_campaign_state_completed_at ||= begin
+        raw_completed_at = phone_campaign_state_hash.fetch("completed_at") {
+          raise_invalid_payload_for("phone_campaign_state completed_at")
+        }
+        DateTime.parse(raw_completed_at).freeze if raw_completed_at
+      end
+    rescue ArgumentError
+      raise InvalidPayloadValue,
+        "phone_campaign_state completed_at has invalid datetime value #{payload.inspect}"
+    end
+
+    # @return [Array<Answer>] Modeled campaign engagement answers
+    # @raise [InvalidPayload] when phone_campaign_state answers missing from payload
+    # @raise [InvalidPayloadValue] when phone_campaign_state answers not hash
+    def phone_campaign_state_answers
+      @phone_campaign_state_answers ||= begin
+        # Extract answers data from payload.
+        data = phone_campaign_state_hash.fetch("answers") {
+          raise_invalid_payload_for("phone_campaign_state answers")
+        }
+
+        # Is this hash data?
+        unless data.is_a?(Hash)
+          raise InvalidPayloadValue,
+            "phone_campaign_state answers has invalid hash value #{payload.inspect}"
+        end
+
+        # Cast answers data.
+        Answer.cast(data: data).freeze
+      end
+    end
+
+    # @return [TrueClass,FalseClass] Are any campaign engagement answers present?
+    def phone_campaign_state_answers?
+      !phone_campaign_state_answers.empty?
+    end
+
+    # @param field [String] Answer data to find
+    # @return [Answer,NilClass] Modeled answer for field when found
+    def answer_for(field:)
+      phone_campaign_state_answers.detect do |answer|
+        answer.field == field
+      end
+    end
+
+    private
+
+    # @param attr [String] Expected attribute missing from payload
+    def raise_invalid_payload_for(attr)
+      raise InvalidPayload, "#{attr} missing from payload #{payload.inspect}"
+    end
+
+    # @return [Hash] Data from campaign engagement payload
+    def payload_data
+      @payload_data ||= payload.fetch("data", {}).freeze
+    end
+
+    # @return [Hash] Campaign hash from payload data
+    def campaign_hash
+      @campaign_hash ||= payload_data.fetch("campaign", {}).freeze
+    end
+
+    # @return [Hash] Phone hash from payload data
+    def phone_hash
+      @phone_hash ||= payload_data.fetch("phone", {}).freeze
+    end
+
+    # @return [Hash] Campaign engagement state hash from payload data
+    def phone_campaign_state_hash
+      @phone_campaign_state_hash ||= payload_data
+        .fetch("phone_campaign_state", {})
+        .freeze
+    end
+  end
+end

data/app/operations/sm_sms_campaign_webhook/campaign_engagement_operation.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # Handles campaign engagement payload data modeling and processing.
+  class CampaignEngagementOperation
+    # Models the campaign engagement payload and hands of processing
+    # of the data to the processor.
+    #
+    # @param payload [Hash] Deserialized SMS campaign engagement payload
+    # @raise [PayloadDispatchError] when not campaign engagement payload
+    # @see .processor
+    def self.process(payload:)
+      logger.debug "#{name} - Processing campaign engagement payload: #{payload.inspect}"
+
+      if payload.fetch("type") != "campaign.engagement"
+        raise PayloadDispatchError,
+          "dispatched payload different from campaign.engagement #{payload.inspect}"
+      end
+
+      campaign_engagement = CampaignEngagement.new(payload: payload)
+      processor.process_campaign_engagement(campaign_engagement)
+    end
+
+    # @return [Processable] Configured SMS campaign payload processor
+    # @see SmSmsCampaignWebhook.processor
+    def self.processor
+      @processor ||= SmSmsCampaignWebhook.processor
+    end
+
+    # @return [ActiveSupport::Logger] Abstraction of app logger
+    def self.logger
+      @logger ||= Rails.logger
+    end
+    private_class_method :logger
+  end
+end

data/app/operations/sm_sms_campaign_webhook/payload_operation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # Handles payload data modeling and data processing.
+  class PayloadOperation
+    # @param payload [Hash] Deserialized payload from SMS campaign service
+    # @see ProcessCampaignEngagementJob#perform
+    def self.dispatch(payload:)
+      logger.debug "#{name} - Dispatching payload: #{payload.inspect}"
+
+      case payload.fetch("type", "unknown")
+      when "campaign.engagement"
+        ProcessCampaignEngagementJob.perform_later(payload)
+      else
+        # NOOP - Unsupported event type.
+        logger.warn "#{name} - Unsupported event type"
+      end
+    end
+
+    # @return [ActiveSupport::Logger] Abstraction of app logger
+    def self.logger
+      @logger ||= Rails.logger
+    end
+    private_class_method :logger
+  end
+end

data/app/processors/sm_sms_campaign_webhook/default_processor.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_dependency "sm_sms_campaign_webhook/processable"
+
+module SmSmsCampaignWebhook
+  # Default processor with NOOP implementations.
+  # @see Processable
+  class DefaultProcessor
+    include Processable
+  end
+end

data/app/processors/sm_sms_campaign_webhook/processable.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # Define behavior that SMS campaign payload processors must implement.
+  module Processable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Campaign engagement operation sends modeled campaign engagement payload
+      # to this method for applying business logic. Implementors should define
+      # the app behavior to properly handle this data.
+      #
+      # @param campaign_engagement [CampaignEngagement] modeled payload
+      # @raise [NotImplementedError] requiring implementing class to define behavior
+      def process_campaign_engagement(campaign_engagement)
+        raise NotImplementedError,
+          "#{self.class} must implement .process_campaign_engagement receiving campaign_engagement param"
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+SmSmsCampaignWebhook::Engine.routes.draw do
+  scope "/api" do
+    resources :webhook, only: [:create]
+  end
+end

data/lib/generators/sm_sms_campaign_webhook/install/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Configures the app to handle inbound requests from the SMS campaign service.
+
+Example:
+    rails generate sm_sms_campaign_webhook:install
+
+    This will create:
+        app/processors/sms_payload_processor.rb
+        config/initializers/sm_sms_campaign_webhook.rb
+
+    This will mount the engine in:
+        config/routes.rb

data/lib/generators/sm_sms_campaign_webhook/install/install_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module SmSmsCampaignWebhook
+  # Namespace for generators provided by the gem.
+  module Generators
+    # Installs files to prep an app for SMS campaign webhook.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      # Copy initializer template to config/initializers
+      def copy_initializer
+        template "sm_sms_campaign_webhook.rb", "config/initializers/sm_sms_campaign_webhook.rb"
+      end
+
+      # Copy processor template to app/processors
+      def copy_processor
+        template "sms_payload_processor.rb.erb", "app/processors/sms_payload_processor.rb"
+      end
+
+      # Mount engine to path in config/routes.rb
+      def add_mount_path
+        insert_into_file "config/routes.rb",
+          "  mount SmSmsCampaignWebhook::Engine => \"/sms_campaign\"\n",
+          after: "Rails.application.routes.draw do\n"
+      end
+
+      # Dump the README for the app developer
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/sm_sms_campaign_webhook/install/templates/README

@@ -0,0 +1,25 @@
+================================================================================
+
+Some setup you must do manually if you haven't yet:
+
+  1. Set the ENV value SM_SMS_CAMPAIGN_WEBHOOK_AUTH_TOKEN with a Rails secret:
+
+       $ bundle exec rails secret
+
+  2. Prep the app for ActiveJob using Sidekiq. In config/application.rb:
+
+       config.active_job.queue_adapter = :sidekiq
+
+     In Procfile or appropriate app launch config:
+
+       worker: bundle exec sidekiq --config config/sidekiq.yml
+
+  3. Implement SmsPayloadProcessor behavior. Remember, the generated processor
+     provides the skeleton but will raise errors out of the box. Data handling
+     is app specific!
+
+This will configure the app to be ready to accept SMS campaign service payloads.
+
+Happy hacking!
+
+================================================================================

data/lib/generators/sm_sms_campaign_webhook/install/templates/sm_sms_campaign_webhook.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "sm_sms_campaign_webhook"
+
+SmSmsCampaignWebhook.config do |config|
+  # SMS campaign payload processor implementing SmSmsCampaignWebhook::Processable behavior.
+  # default: SmSmsCampaignWebhook::DefaultProcessor (raises errors for processing)
+  config.processor = SmsPayloadProcessor
+end

data/lib/generators/sm_sms_campaign_webhook/install/templates/sms_payload_processor.rb.erb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Processes SMS campaign service payloads.
+# @see https://github.com/SouthernMade/sm_sms_campaign_webhook/blob/v<%= SmSmsCampaignWebhook::VERSION %>/app/processors/sm_sms_campaign_webhook/processable.rb SmSmsCampaignWebhook::Processable
+class SmsPayloadProcessor
+  include SmSmsCampaignWebhook::Processable
+
+  # @param campaign_engagement [SmSmsCampaignWebhook::CampaignEngagement]
+  # @see https://github.com/SouthernMade/sm_sms_campaign_webhook/blob/v<%= SmSmsCampaignWebhook::VERSION %>/app/models/sm_sms_campaign_webhook/campaign_engagement.rb SmSmsCampaignWebhook::CampaignEngagement
+  # @todo Implement business logic to process campaign engagement.
+  # def self.process_campaign_engagement(campaign_engagement)
+  # end
+end

data/lib/sm_sms_campaign_webhook/engine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module SmSmsCampaignWebhook
+  # General Rails engine configuration.
+  class Engine < ::Rails::Engine
+    isolate_namespace SmSmsCampaignWebhook
+    config.generators.api_only = true
+  end
+end

data/lib/sm_sms_campaign_webhook/version.rb

@@ -2,5 +2,5 @@
 
 module SmSmsCampaignWebhook
   # @return [String] gem version
-  VERSION = "0.1.1"
+  VERSION = "2.1.0"
 end

data/lib/sm_sms_campaign_webhook.rb

@@ -1,9 +1,32 @@
 # frozen_string_literal: true
 
+require "sm_sms_campaign_webhook/engine"
 require "sm_sms_campaign_webhook/version"
 
 # Namespace for SMS campaign webhook.
 module SmSmsCampaignWebhook
-  # General base error type for custom errors.
-  class Error < StandardError; end
+  # @return [SmSmsCampaignWebhook] self for configuration purposes
+  def self.config(&block)
+    yield self if block
+  end
+
+  # @return [String] SMS campaign webhook auth token
+  # @raise [MissingConfigError] when ENV does not contain SM_SMS_CAMPAIGN_WEBHOOK_AUTH_TOKEN value
+  def self.auth_token
+    @auth_token ||= ENV.fetch("SM_SMS_CAMPAIGN_WEBHOOK_AUTH_TOKEN") {
+      raise MissingConfigError,
+        "ENV does not contain SM_SMS_CAMPAIGN_WEBHOOK_AUTH_TOKEN value"
+    }
+  end
+
+  # @return [Processable] SMS campaign payload processor used by operations
+  def self.processor
+    @processor ||= DefaultProcessor
+  end
+
+  # @param processor [Processable] Custom SMS campaign payload processor
+  # @see Processable
+  def self.processor=(processor)
+    @processor = processor
+  end
 end

data/sm_sms_campaign_webhook.gemspec

@@ -1,34 +1,48 @@
+# frozen_string_literal: true
+
 lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "sm_sms_campaign_webhook/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "sm_sms_campaign_webhook"
-  spec.version       = SmSmsCampaignWebhook::VERSION
-  spec.authors       = ["Cameron Dykes", "Matt Mueller"]
-  spec.email         = ["cameron@southernmade.com", "matt@southernmade.com"]
-
-  spec.summary       = %q{Middleware providing webhook for Southern Made SMS Campaign Engagement.}
-  spec.homepage      = "https://github.com/SouthernMade/sm_sms_campaign_webhook"
-  spec.license       = "MIT"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.name = "sm_sms_campaign_webhook"
+  spec.version = SmSmsCampaignWebhook::VERSION
+  spec.license = "MIT"
+  spec.summary = "Middleware providing webhook for Southern Made SMS Campaign Engagement."
+  spec.description = "Middleware providing webhook for Southern Made SMS Campaign Engagement."
+  spec.homepage = "https://github.com/SouthernMade/sm_sms_campaign_webhook"
+  spec.authors = ["Cameron Dykes", "Matt Mueller"]
+  spec.email = ["cameron@southernmade.com", "matt@southernmade.com"]
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/SouthernMade/sm_sms_campaign_webhook"
-  spec.metadata["changelog_uri"] = "https://github.com/SouthernMade/sm_sms_campaign_webhook/blob/develop/CHANGELOG.md"
+  spec.metadata = {
+    "allowed_push_host" => "https://rubygems.org",
+    "changelog_uri" => "#{spec.homepage}/blob/develop/CHANGELOG.md",
+    "documentation_uri" => "https://www.rubydoc.info/gems/sm_sms_campaign_webhook/#{spec.version}",
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage
+  }
 
   # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.files = Dir[
+    "{app,config,lib}/**/*",
+    "CHANGELOG.md",
+    "LICENSE.txt",
+    "README.md",
+    "sm_sms_campaign_webhook.gemspec"
+  ]
   spec.require_paths = ["lib"]
 
+  # Required version of Ruby guided by Rails.
+  spec.required_ruby_version = ">= 2.7.5"
+
+  # Runtime dependencies.
+  spec.add_dependency "rails", [">= 6.0", "< 7.1"]
+
+  # Development + test dependencies.
   spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 12.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec-rails", "~> 5.0"
+  spec.add_development_dependency "simplecov", "~> 0.20"
+  spec.add_development_dependency "standard", "~> 1.0"
   spec.add_development_dependency "yard", "~> 0.9"
 end