sm_sms_campaign_webhook 0.1.1 → 1.0.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") do
+          raise_invalid_payload_for("uuid")
+        end.freeze
+      )
+    end
+
+    # @return [String] Campaign engagement event type
+    # @raise [InvalidPayload] when type missing from payload
+    def event_type
+      @event_type ||= String(
+        payload.fetch("type") do
+          raise_invalid_payload_for("type")
+        end.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") do
+          raise_invalid_payload_for("created_at")
+        end
+        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") do
+          raise_invalid_payload_for("campaign id")
+        end
+      )
+    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") do
+          raise_invalid_payload_for("campaign keyword")
+        end.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") do
+          raise_invalid_payload_for("phone id")
+        end
+      )
+    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") do
+          raise_invalid_payload_for("phone number")
+        end.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") do
+          raise_invalid_payload_for("phone_campaign_state id")
+        end
+      )
+    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?
+      if !@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") do
+            raise_invalid_payload_for("phone_campaign_state completed")
+          end
+
+        # 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") do
+          raise_invalid_payload_for("phone_campaign_state completed_at")
+        end
+        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") do
+          raise_invalid_payload_for("phone_campaign_state answers")
+        end
+        
+        # Is this hash data?
+        if !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/models/sm_sms_campaign_webhook/campaign_engagement/answer.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "date"
+
+module SmSmsCampaignWebhook
+  class CampaignEngagement
+    # Data model for campaign engagement answer data.
+    class Answer
+      # @param data [Hash] Answers from payload
+      # @return [Array<Answer>] Modeled answer data sorted by collected_at
+      def self.cast(data:)
+        data.map do |field, answer_hash|
+          new(field: field, answer_hash: answer_hash)
+        end.sort_by(&:collected_at)
+      end
+
+      attr_reader :field,
+                  :answer_hash
+
+      # @param field [String] Field describing the answer
+      # @param answer_hash [Hash] Answer data from payload
+      def initialize(field:, answer_hash:)
+        @field = String(field)
+        @answer_hash = answer_hash.freeze
+      end
+
+      # Collected answer could be many different value types.
+      #
+      # The SMS campaign service collects answers of type:
+      # string, email, date, number, boolean, us_state
+      #
+      # The possible types are from SMS campaign service perspective.
+      # They are coerced to the appropriate type in Ruby.
+      #
+      # @return [String,Integer,Date,TrueClass,FalseClass] Coerced answer
+      # @raise [InvalidPayload] when value is missing from answer_hash
+      def value
+        # Could be boolean so cannot rely on double pipe assignment guard.
+        if !@value.nil?
+          return @value
+        end
+
+        # Extract the value and memoize it.
+        @value = begin
+         raw_value = answer_hash.fetch("value") do
+           raise InvalidPayload,
+                 "value missing from answer_hash #{answer_hash.inspect}"
+         end.freeze
+
+         # Attempt to parse date value falling back to raw value.
+         Date.strptime(raw_value, "%Y-%m-%d").freeze rescue raw_value
+        end
+      end
+
+      # @return [DateTime] Timestamp of answer value collection
+      # @raise [InvalidPayload] when collected_at missing from answer_hash
+      # @raise [InvalidPayloadValue] when collected_at not datetime
+      def collected_at
+        @collected_at ||= begin
+          raw_collected_at = answer_hash.fetch("collected_at") do
+            raise InvalidPayload,
+                  "collected_at missing from answer_hash #{answer_hash.inspect}"
+          end
+          DateTime.parse(raw_collected_at).freeze
+        end
+      rescue ArgumentError
+        raise InvalidPayloadValue,
+              "collected_at has invalid datetime value #{answer_hash.inspect}"
+      end
+    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_enagement = CampaignEngagement.new(payload: payload)
+      processor.process_campaign_engagement(campaign_enagement)
+    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