sm_sms_campaign_webhook 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfbcb58c24ec5e86d522e8bbd6523bdf0c348c562aa04ac33fc610860de7fbb2
-  data.tar.gz: d23266b0bd2ba7b5f65e0ad24d4ca34eb35059b224217ad3f93f566785e1da04
+  metadata.gz: 9ee7507ed2364d7482af89dc6a0fda95b689ffe0c9e12f12b4a8cd8f1edf07d0
+  data.tar.gz: a0a7d6b50a54b6d518d5ef870727217b7c3cee1816ef1038cab61e6f5d506907
 SHA512:
-  metadata.gz: ae0eb7921ee8ef9b295427c8333627c3938281977a97cc08ca10eefd6363c11699014aa3cbd987b05ced256760a758e909970708d1d9d6ea2481e83320d0778a
-  data.tar.gz: 380100e28e9a8a4646fc61c132afe8824088947e378bfee1ef08785e48dc983d71fa39330d4d93b941cdf9cc2a9cfbd6fd4e4b4e84aa32de2d32dd8926aaaf3d
+  metadata.gz: cb4b43bfc4733b09458fea2a6c008f33a3a271918ae16cecd66571b6f97bc221f67748c8f5b9b7ef6ce811232ac96b5ce44433da6cb64d91083979b625f4a8f2
+  data.tar.gz: b078c3040867520148ad9e129a6845100c82d277a4e68b60beb8b51495876c2915251c13f208a0e3326f14dbe64c46e4355077a95719d4e5abcefe58569f55b9

data/CHANGELOG.md

@@ -6,6 +6,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2019-07-26
+### Added
+- Mountable Rails engine as API
+- POST /api/webhook resource requiring JSON payload for asynchronous dispatching and processing
+- Require inbound POST requests be authorization requests with an auth token
+- Support for Rails 5.2.x, 6.0.x
+- Data models for campaign engagement event payloads
+- Helper method to get specific campaign engagement answer
+- Payload operation library to dispatch and process deserialized JSON with supported event data modeling
+- Processable behavior definition for app implementors
+- Default processor mixing in processable behavior with noisy errors
+- ActiveJob library for asynchronous handling of payload dispatching and processing
+- Configuration support for required app implementation values
+
+### Changed
+- Require Ruby >= 2.5
+- CI to test against Ruby 2.5.5, 2.6.3
+- CI to test against Rails 5.2.x, 6.0.x
+
+## [0.1.1] - 2019-07-16
+### Changed
+- Changelog URI to correct value in gemspec
+
 ## [0.1.0] - 2019-07-16
 ### Added
 - NOOP gem configured for development

data/README.md

@@ -1,4 +1,6 @@
-# SmSmsCampaignWebhook: Middleware providing webhook for Southern Made SMS Campaign Engagement
+# SmSmsCampaignWebhook
+
+![Southern Made - Galaxy Logo](https://raw.github.com/SouthernMade/sm_sms_campaign_webhook/develop/logo_galaxymark.png) by [Southern Made](https://www.southernmade.com/)
 
 [![Gem Version](https://badge.fury.io/rb/sm_sms_campaign_webhook.svg)](https://badge.fury.io/rb/sm_sms_campaign_webhook)
 [![Travis Build Status](https://travis-ci.org/SouthernMade/sm_sms_campaign_webhook.svg?branch=develop)](https://travis-ci.org/SouthernMade/sm_sms_campaign_webhook)
@@ -15,12 +17,36 @@ This gem will help app implementors using [Rails](https://rubyonrails.org) setup
 
 Work closely with your Southern Made project manager to gather details about what needs to be tracked, what fields to verify, and which scenarios are expected to be supported!
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Auto Generate Config](#auto-generate-config)
+  - [Webhook Auth Token](#webhook-auth-token)
+  - [ActiveJob](#activejob)
+  - [Mount the Webhook Engine](#mount-the-webhook-engine)
+  - [Webhook Initializer](#webhook-initializer)
+  - [Payload Processor](#payload-processor)
+- [Usage](#usage)
+  - [Campaign Engagement](#campaign-engagement)
+    - [Processor Expections](#processor-expections)
+    - [Campaign Engagement Data Model](#campaign-engagement-data-model)
+    - [Campaign Engagement Answer Data Model](#campaign-engagement-answer-data-model)
+- [Development](#development)
+  - [Versioning](#versioning)
+  - [Testing](#testing)
+  - [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
+This gem is tested with Rails 5.2.x, 6.0.x versions.
+
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'sm_sms_campaign_webhook'
+gem 'sm_sms_campaign_webhook', '~> 1.0'
 ```
 
 And then execute:
@@ -31,9 +57,223 @@ Or install it yourself as:
 
     $ gem install sm_sms_campaign_webhook
 
+## Configuration
+
+These are the steps to configure your app to be ready to capture SMS campaign service payloads.
+
+### Auto Generate Config
+
+You can setup most app configuration by running the generator:
+
+```
+$ bundle exec rails generate sm_sms_campaign_webhook:install
+```
+
+Some things will still require manual configuration and will be identified after generation:
+
+- [Webhook Auth Token](#webhook-auth-token)
+- [ActiveJob](#activejob)
+
+After that, be sure to read the [Usage](#usage) section for payload processor details!
+
+If you prefer to setup everything by hand, be sure to check out:
+
+- [Webhook Initializer](#webhook-initializer)
+- [Payload Processor](#payload-processor)
+
+### Webhook Auth Token
+
+The `SM_SMS_CAMPAIGN_WEBHOOK_AUTH_TOKEN` value is required to be an `ENV` value to avoid leaking production values. It will be used to authorize payload requests from the SMS campaign service.
+
+Set this value using the rails secret generator:
+
+```
+$ bundle exec rails secret
+```
+
+And copy the result to your `.env` or applicable config file:
+
+```
+SM_SMS_CAMPAIGN_WEBHOOK_AUTH_TOKEN="******"
+```
+
+### ActiveJob
+
+Payloads will be dispatched and processed asynchronously using [ActiveJob](https://edgeguides.rubyonrails.org/active_job_basics.html). Southern Made prefers that the app be configured with [Sidekiq](https://github.com/mperham/sidekiq) as the queue adapter.
+
+You can set the adapter in `config/application.rb` with:
+
+```ruby
+class Application < Rails::Application
+  config.active_job.queue_adapter = :sidekiq
+end
+```
+
+Update your Procfile or appropriate config to launch worker processes:
+
+```
+worker: RAILS_MAX_THREADS=${SIDEKIQ_CONCURRENCY:-5} bundle exec sidekiq --config config/sidekiq.yml
+```
+
+More detailed instructions about using Sidekiq can be found in the [Sidekiq Wiki](https://github.com/mperham/sidekiq/wiki).
+
+### Mount the Webhook Engine
+
+If you opted to [auto generate the config](#auto-generate-config), this can be skipped.
+
+Add the following to `config/routes.rb` in your app to mount the webhook:
+
+```ruby
+mount SmSmsCampaignWebhook::Engine => "/sms_campaign"
+```
+
+This sets the app up to receive POST requests from the SMS campaign service:
+
+    POST /sms_campaign/api/webhook
+
+Be sure to replace `/sms_campaign` with whatever mount point you choose. Once you share the webhook URI with your project manager, avoid changing it; they will configure it with the correspending SMS campaign!
+
+### Webhook Initializer
+
+If you opted to [auto generate the config](#auto-generate-config), this can be skipped.
+
+App implementors must configure some library options. Here are all supported configuration options identifying their default values for `config/initializers/sm_sms_campaign_webhook.rb`:
+
+```ruby
+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
+```
+
+### Payload Processor
+
+If you opted to [auto generate the config](#auto-generate-config), this can be skipped. However, you will still need to implement the processor methods!
+
+The default payload processor will raise errors while processing. You are required to provide a working payload processor to properly handle the data received from the SMS campaign service.
+
+To create a processor, create a custom class mixing in `SmSmsCampaignWebhook::Processable` behavior. For example, we can create a custom processor named `SmsPayloadProcessor`:
+
+```ruby
+class SmsPayloadProcessor
+  include SmSmsCampaignWebhook::Processable
+
+  # Implement required methods for Processable behavior.
+
+  # @param campaign_engagement [SmSmsCampaignWebhook::CampaignEngagement]
+  # def self.process_campaign_engagement(campaign_engagement)
+  #   # NOOP - I need to be implemented.
+  # end
+end
+```
+
+This class will continue raising errors until the required methods are implemented. Please see the [Processable mixin](https://github.com/SouthernMade/sm_sms_campaign_webhook/blob/develop/app/processors/sm_sms_campaign_webhook/processable.rb) for expected method definitions.
+
+Finally the configuration needs to be updated to use the custom processor. Add this within the config block in `config/initializers/sm_sms_campaign_webhook.rb`:
+
+```ruby
+SmSmsCampaignWebhook.config do |config|
+  #...
+  config.processor = SmsPayloadProcessor
+  #...
+end
+```
+
 ## Usage
 
-Right now, nothing happens! Soon, some useful details will emerge about how to ingest the SMS campaign payloads.
+The main goal is to ingest the data contained in payloads received from the SMS campaign service. Your app knows best what to do with the data, so your primary focus is implementing the required methods of a payload processor.
+
+Assuming that you completed configuration with the [auto generate installer](#auto-generate-config) or [manually created a processor](#payload-processor), this section will expand what to do with it.
+
+### Campaign Engagement
+
+This payload represents a user's phone interaction with the SMS campaign. This includes:
+
+- First contact with a SMS campaign by keyword
+- Responding to subsequent SMS campaign messages
+- Continued engagement for multi-entry SMS campaigns
+
+Payloads will POST to the webhook every time a phone interacts with the campaign, so the processor behavior should expect to see repeats of inbound payloads from a phone!
+
+It is important that you work closely with your Southern Made project manager to determine which scenarios are relevant for your app. They will be able to tell you:
+
+- Fields + value types that will be in answers
+- Required fields to complete registration/entry
+- How to interpret voting style numeric answers
+
+#### Processor Expections
+
+You must behavior for this method to ingest campaign engagement data in your paylod processor:
+
+```ruby
+def self.process_campaign_engagement(campaign_engagement)
+  # ...
+end
+```
+
+It will receive an instance of the [SmSmsCampaignWebhook::CampaignEngagement](https://github.com/SouthernMade/sm_sms_campaign_webhook/blob/develop/app/models/sm_sms_campaign_webhook/campaign_engagement.rb) data model. This method will need to handle scenarios such as:
+
+- Registering/creating a user account
+- Logging registration/entries
+- Interpreting + logging vote responses
+
+Check with your Southern Made project manager for expectations.
+
+#### Campaign Engagement Data Model
+
+The payload will be modeled with the [SmSmsCampaignWebhook::CampaignEngagement](https://github.com/SouthernMade/sm_sms_campaign_webhook/blob/develop/app/models/sm_sms_campaign_webhook/campaign_engagement.rb) class. It provides basic methods to extract values out of the payload. The data model coerces values to the appropriate types in Ruby.
+
+Some example message passing to an instance:
+
+```ruby
+campaign_engagement.event_uuid        # UUID - unique payload event
+campaign_engagement.campaign_keyword  # String - SMS campaign entry point
+campaign_engagement.phone_id          # Integer - represents specific phone
+campaign_engagement.phone_number      # String - phone number interacting with SMS campaign
+
+# This represents a specific phone engaging with a specific campaign.
+# The value will differ for each entry in multi-entry campaigns.
+# For standard campaigns we will only see one value.
+campaign_engagement.phone_campaign_state_id   # Integer
+
+# These values help determine if and when answers were received
+# for all campaign messages.
+campaign_engagement.phone_campaign_state_completed?     # TrueClass,FalseClass
+campaign_engagement.phone_campaign_state_completed_at   # DateTime
+```
+
+It also provides a useful helper methods related to campaign engagement answers. For example:
+
+```ruby
+# Are any campaign engagement answers in the payload?
+campaign_engagement.phone_campaign_state_answers? # TrueClass,FalseClass
+
+# This tries to find an answer for the requested field.
+# If a match is found it returns instance of
+# SmSmsCampaignWebhook::CampaignEngagement::Answer data model.
+# If a match is not found it return nil (NilClass).
+campaign_enagement.answer_for(field: "email")     # Returned type answer specific
+```
+
+#### Campaign Engagement Answer Data Model
+
+The [SmSmsCampaignWebhook::CampaignEngagement::Answer](https://github.com/SouthernMade/sm_sms_campaign_webhook/blob/develop/app/models/sm_sms_campaign_webhook/campaign_engagement/answer.rb) class models the answer data contained in the campaign engagement payload. It consists of:
+
+- field (`String`)
+- value (varies)
+- collected_at (`DateTime`)
+
+The value data types could be one of the following:
+
+- string (`String`)
+- email (`String`)
+- date (`Date`)
+- number (`Integer`)
+- boolean (`TrueClass`, `FalseClass`)
+- us_state (`String`)
 
 ## Development
 
@@ -43,7 +283,6 @@ This gem uses [git-flow](https://github.com/nvie/gitflow) to manage deployments.
 
 Gem versioning follows [Semantic Versioning](https://semver.org).
 
-
 ### Testing
 
 This project uses Rspec for testing. Specs must be green for any PR to be accepted!

data/app/controllers/sm_sms_campaign_webhook/application_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "action_controller/metal/http_authentication"
+require "active_support/security_utils"
+
+module SmSmsCampaignWebhook
+  # General webhook controller configuration.
+  class ApplicationController < ActionController::API
+    include ActionController::HttpAuthentication::Token::ControllerMethods
+
+    before_action :authenticate
+
+    protected
+
+    # Verify auth token is present and matches the configured value.
+    def authenticate
+      authenticate_or_request_with_http_token do |token, options|
+        ActiveSupport::SecurityUtils.secure_compare(token, SmSmsCampaignWebhook.auth_token)
+      end
+    end
+  end
+end

data/app/controllers/sm_sms_campaign_webhook/webhook_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json"
+require_dependency "sm_sms_campaign_webhook/application_controller"
+
+module SmSmsCampaignWebhook
+  # API webhook for POST requests from SMS campaign service.
+  class WebhookController < ApplicationController
+    # POST /api/webhook
+    # @see DispatchPayloadJob#perform
+    def create
+      # Deserialize the payload.
+      payload = JSON.parse(request.body.read)
+      logger.debug "#{self.class} - Payload: #{payload.inspect}"
+
+      # Dispatch the payload to the appropriate payload processor.
+      DispatchPayloadJob.perform_later(payload)
+
+      head :no_content
+    rescue JSON::ParserError => e
+      logger.warn "#{self.class} - Bad Request: #{e.class} - #{e}"
+      head :bad_request
+    end
+  end
+end

data/app/exceptions/sm_sms_campaign_webhook/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # General base error type for custom errors.
+  class Error < StandardError; end
+end

data/app/exceptions/sm_sms_campaign_webhook/invalid_payload.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # Error type for invalid payload schema received by the SMS webhook.
+  class InvalidPayload < Error; end
+end

data/app/exceptions/sm_sms_campaign_webhook/invalid_payload_value.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # Error type for invalid value in the payload received by the SMS webhook.
+  class InvalidPayloadValue < Error; end
+end

data/app/exceptions/sm_sms_campaign_webhook/missing_config_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # Error type for missing config values for this library.
+  class MissingConfigError < Error; end
+end

data/app/exceptions/sm_sms_campaign_webhook/payload_dispatch_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # Error type for improperly dispatch SMS campaign payloads.
+  class PayloadDispatchError < Error; end
+end

data/app/jobs/sm_sms_campaign_webhook/application_job.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SmSmsCampaignWebhook
+  # General async job configuration.
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/sm_sms_campaign_webhook/dispatch_payload_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_dependency "sm_sms_campaign_webhook/application_job"
+
+module SmSmsCampaignWebhook
+  # Handles SMS campaign payload dispatch to processor async.
+  class DispatchPayloadJob < ApplicationJob
+    # @param payload [Hash] Deserialized payload from SMS campaign service
+    # @see PayloadOperation.dispatch
+    def perform(payload)
+      PayloadOperation.dispatch(payload: payload)
+    end
+  end
+end

data/app/jobs/sm_sms_campaign_webhook/process_campaign_engagement_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_dependency "sm_sms_campaign_webhook/application_job"
+
+module SmSmsCampaignWebhook
+  # Handles campaign engagement payload processing async.
+  class ProcessCampaignEngagementJob < ApplicationJob
+    # @param payload [Hash] Campaign engagement event payload
+    # @see CampaignEngagementOperation.process
+    def perform(payload)
+      CampaignEngagementOperation.process(payload: payload)
+    end
+  end
+end