twilio-rails 1.0.0

data/app/jobs/twilio/rails/application_job.rb

@@ -0,0 +1,6 @@
+module Twilio
+  module Rails
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/app/jobs/twilio/rails/phone/attach_recording_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      # Performs the {Twilio::Rails::Phone::AttachRecordingOperation}.
+      class AttachRecordingJob < ::Twilio::Rails::ApplicationJob
+        queue_as :default
+
+        def perform(recording_id:)
+          Twilio::Rails::Phone::AttachRecordingOperation.call(recording_id: recording_id)
+        end
+      end
+    end
+  end
+end

data/app/jobs/twilio/rails/phone/finished_call_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      # Performs the {Twilio::Rails::Phone::FinishedCallOperation}.
+      class FinishedCallJob < ::Twilio::Rails::ApplicationJob
+        queue_as :default
+
+        def perform(phone_call_id:)
+          Twilio::Rails::Phone::FinishedCallOperation.call(phone_call_id: phone_call_id)
+        end
+      end
+    end
+  end
+end

data/app/jobs/twilio/rails/phone/unanswered_call_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      # Performs the {Twilio::Rails::Phone::UnansweredCallOperation}.
+      class UnansweredCallJob < ::Twilio::Rails::ApplicationJob
+        queue_as :default
+
+        def perform(phone_call_id:)
+          Twilio::Rails::Phone::UnansweredCallOperation.call(phone_call_id: phone_call_id)
+        end
+      end
+    end
+  end
+end

data/app/mailers/twilio/rails/application_mailer.rb

@@ -0,0 +1,8 @@
+module Twilio
+  module Rails
+    class ApplicationMailer < ActionMailer::Base
+      default from: "from@example.com"
+      layout "mailer"
+    end
+  end
+end

data/app/models/twilio/rails/application_record.rb

@@ -0,0 +1,7 @@
+module Twilio
+  module Rails
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/operations/twilio/rails/application_operation.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    class ApplicationOperation < ActiveOperation::Base
+      # Annotates the log output for every operation with the execution time.
+      around do |instance, executable|
+        @operation_runtime_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        executable.call
+        @operation_runtime_stop = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        ::Twilio::Rails.config.logger.tagged(self.class) { |l| l.info("execution time #{ instance.operation_runtime_seconds } seconds")}
+      end
+
+      protected
+
+      def operation_runtime_seconds
+        (@operation_runtime_stop || Process.clock_gettime(Process::CLOCK_MONOTONIC)) - @operation_runtime_start
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/find_or_create_phone_caller_operation.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    # Finds and returns a {Twilio::Rails::Models::PhoneCaller} by phone number, or creates a new one if it does not
+    # exist. The operation will `halt` if the phone number is not valid or blank.
+    #
+    # *Note:* Operations should be called with `call(params)` and not by calling `new(params).execute` directly.
+    class FindOrCreatePhoneCallerOperation < ::Twilio::Rails::ApplicationOperation
+      input :phone_number, accepts: String, type: :keyword, required: false
+
+      # @param phone_number [String] The phone number to find or create the phone caller.
+      # @return [Twilio::Rails::Models::PhoneCaller] The found or newly created phone caller.
+      def execute
+        halt nil unless valid_phone_number
+
+        phone_caller = ::Twilio::Rails.config.phone_caller_class.find_or_initialize_by(phone_number: valid_phone_number)
+        phone_caller.save! if phone_caller.new_record?
+
+        phone_caller
+      end
+
+      private
+
+      def valid_phone_number
+        Twilio::Rails::Formatter.coerce_to_valid_phone_number(phone_number)
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/attach_recording_operation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      # Called by {Twilio::Rails::Phone::ReceiveRecordingOperation} to download and store the audio file from the URL
+      # provided by Twilio.
+      class AttachRecordingOperation < ::Twilio::Rails::ApplicationOperation
+        input :recording_id, accepts: Integer, type: :keyword, required: true
+
+        def execute
+          recording = ::Twilio::Rails.config.recording_class.find(recording_id)
+
+          if !recording.audio.attached?
+            if recording.url.blank?
+              raise Twilio::Rails::Phone::Error, "[AttachRecordingOperation] Has a blank URL and cannot be fetched recording_id=#{ recording.id }"
+            end
+
+            response = Faraday.get(recording.url)
+
+            if response.success?
+              recording.audio.attach(io: StringIO.new(response.body), filename: "recording.wav", content_type: "audio/wav")
+              recording.save!
+            else
+              raise Twilio::Rails::Phone::Error, "[AttachRecordingOperation] Failed to fetch recording recording_id=#{ recording.id } HTTP#{ response.status } from #{ recording.url }"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/base_operation.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      # Base class for all SMS operations. Requires the `phone_call_id` to be passed in.
+      class BaseOperation < ::Twilio::Rails::ApplicationOperation
+        input :phone_call_id, accepts: Integer, type: :keyword, required: true
+
+        protected
+
+        def phone_call
+          @phone_call ||= ::Twilio::Rails.config.phone_call_class.find(phone_call_id)
+        end
+
+        def phone_caller
+          phone_call.phone_caller
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/create_operation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class CreateOperation < ::Twilio::Rails::ApplicationOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+        input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+
+        def execute
+          phone_call = ::Twilio::Rails.config.phone_call_class.new(
+            sid: params["CallSid"],
+            direction: params["direction"].presence || "inbound",
+            call_status: params["CallStatus"],
+            tree_name: tree.name,
+            number: params["Called"].presence || params["To"].presence,
+            from_number: params["Caller"].presence || params["From"].presence,
+            from_city: params["CallerCity"].presence || params["FromCity"].presence,
+            from_province: params["CallerState"].presence || params["FromState"].presence,
+            from_country: params["CallerCountry"].presence || params["FromCountry"].presence,
+          )
+
+          phone_caller = Twilio::Rails::FindOrCreatePhoneCallerOperation.call(phone_number: phone_call.from_number)
+
+          if !phone_caller
+            error_message = if !Twilio::Rails::Formatter.valid_north_american_phone_number?(phone_call.from_number)
+              "The phone number is invalid."
+            else
+              "The phone caller could not be persisted or retrieved."
+            end
+
+            raise Twilio::Rails::Phone::Error, "Failed to handle incoming Twilio phone call. #{ error_message } phone_number=#{ phone_call.from_number } call_sid=#{ params["CallSid"] }"
+          end
+
+          phone_call.phone_caller = phone_caller
+          phone_call.save!
+
+          phone_call
+        rescue => e
+          Twilio::Rails.notify_exception(e,
+            message: "Failed to handle incoming Twilio phone call.",
+            context: { params: params, tree: tree },
+            exception_binding: binding
+          )
+          raise
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/find_operation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class FindOperation < ::Twilio::Rails::ApplicationOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+
+        def execute
+          ::Twilio::Rails.config.phone_call_class.find_by!(sid: params["CallSid"])
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/finished_call_operation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class FinishedCallOperation < ::Twilio::Rails::Phone::BaseOperation
+        def execute
+          if phone_call.finished?
+            Twilio::Rails.config.logger.tagged(self.class) { |l| l.warn("Skipping duplicate finished call job") }
+          else
+            phone_call.update!(finished: true)
+            phone_call.tree.finished_call.call(phone_call) if phone_call.tree.finished_call
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/receive_recording_operation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class ReceiveRecordingOperation < ::Twilio::Rails::Phone::BaseOperation
+        input :params, accepts: Hash, type: :keyword, required: true
+        input :response_id, accepts: Integer, type: :keyword, required: true
+
+        def execute
+          response = phone_call.responses.find(response_id)
+
+          if phone_call.recordings.sid(params["RecordingSid"]).any?
+            Twilio::Rails.config.logger.tagged(self.class) { |l| l.warn("duplicate recording for response_id=#{ response.id } recording_sid=#{ params["RecordingSid"] }") }
+          else
+            recording = phone_call.recordings.build(
+              recording_sid: params["RecordingSid"],
+              url: params["RecordingUrl"],
+              duration: params["RecordingDuration"].presence,
+            )
+            recording.save!
+
+            response.recording = recording
+            response.save!
+
+            if Twilio::Rails.config.attach_recording?(recording)
+              Twilio::Rails::Phone::AttachRecordingJob.set(wait: 5.seconds).perform_later(recording_id: recording.id)
+            end
+
+            recording
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/start_call_operation.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      class StartCallOperation < ::Twilio::Rails::ApplicationOperation
+        input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+        input :to, accepts: String, type: :keyword, required: true
+        input :from, accepts: [String, Twilio::Rails::PhoneNumber], type: :keyword, required: false
+        input :answering_machine_detection, accepts: [true, false], default: true, type: :keyword, required: false
+
+        def execute
+          from = if self.from.is_a?(Twilio::Rails::PhoneNumber)
+            self.from.number
+          elsif self.from.present?
+            self.from
+          else
+            Twilio::Rails.config.default_outgoing_phone_number
+          end
+
+          params = {
+            "CallSid" => nil,
+            "direction" => "outbound",
+            "To" => from,
+            "From" => to,
+          }
+
+          begin
+            sid = Twilio::Rails::Client.start_call(url: tree.outbound_url, to: to, from: from, answering_machine_detection: answering_machine_detection)
+            params["CallSid"] = sid
+          rescue Twilio::REST::TwilioError => e
+            Twilio::Rails.notify_exception(e,
+              message: "Failed to start Twilio phone call. Got REST error response.",
+              context: { params: params },
+              exception_binding: binding
+            )
+            raise
+          rescue => e
+            Twilio::Rails.notify_exception(e,
+              message: "Failed to start Twilio phone call. Got unknown error.",
+              context: { params: params },
+              exception_binding: binding
+            )
+            raise
+          end
+
+          # TODO: I think this may be a race condition
+          phone_call = Twilio::Rails::Phone::CreateOperation.call(params: params, tree: tree)
+          phone_call
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/twiml/after_operation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class AfterOperation < Twilio::Rails::Phone::Twiml::BaseOperation
+          input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+          input :after, accepts: Twilio::Rails::Phone::Tree::After, type: :keyword, required: true
+
+          def execute
+            unless after.hangup?
+              next_response = phone_call.responses.build(prompt_handle: after.prompt)
+              next_response.save!
+            end
+
+            twiml_response = Twilio::TwiML::VoiceResponse.new do |twiml|
+              add_messages(twiml, message_set: after.messages, response: next_response)
+
+              if after.hangup?
+                twiml.hangup
+              else
+                twiml.redirect(::Twilio::Rails::Engine.routes.url_helpers.phone_prompt_path(
+                  format: :xml,
+                  tree_name: tree.name,
+                  response_id: next_response.id
+                ))
+              end
+            end
+
+            Twilio::Rails.config.logger.info("after_twiml: #{twiml_response.to_s}")
+            twiml_response.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/twiml/base_operation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class BaseOperation < Twilio::Rails::Phone::BaseOperation
+          protected
+
+          # Adds messages to the TwiML response from the passed in message set. This mutates the passed in TwiML object,
+          # which isn't ideal.
+          #
+          # @param twiml [Twilio::TwiML::VoiceResponse] the TwiML response object to add messages to.
+          # @param message_set [Twilio::Rails::Phone::Tree::MessageSet, Hash, Proc, Array, String] the message or messages to add to the TwiML response.
+          # @param response [Twilio::Rails::Phone::Response] the response passed to the proc when they are called.
+          def add_messages(twiml, message_set:, response:)
+            message_set = message_set.call(response) if message_set.is_a?(Proc)
+            message_set = Twilio::Rails::Phone::Tree::MessageSet.new(message: message_set) unless message_set.is_a?(Twilio::Rails::Phone::Tree::MessageSet)
+
+            message_set.each do |message|
+              message = message.call(response) if message.is_a?(Proc)
+              message = Twilio::Rails::Phone::Tree::Message.new(**message) if message.is_a?(Hash)
+              next if message.blank?
+              message = Twilio::Rails::Phone::Tree::Message.new(say: message, voice: tree.config[:voice]) if message.is_a?(String)
+
+              raise Twilio::Rails::Phone::InvalidTreeError "unknown message #{ message } is a #{ message.class }" unless message.is_a?(Twilio::Rails::Phone::Tree::Message)
+
+              # TODO: if we want to make a transcript of sent messages this is where we would record outgoing messages
+
+              if message.say?
+                value = message.value
+                value = message.value.call(response) if message.value.is_a?(Proc)
+                twiml.say(voice: message.voice || tree.config[:voice], message: value) do |say|
+                  message.block.call(say) if message.block
+                end
+              elsif message.play?
+                value = message.value
+                value = message.value.call(response) if message.value.is_a?(Proc)
+                twiml.play(url: value)
+              elsif message.pause?
+                twiml.pause(length: message.value)
+              else
+                raise Twilio::Rails::Phone::InvalidTreeError, "unknown message #{ message }"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/twiml/error_operation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class ErrorOperation < Twilio::Rails::Phone::Twiml::BaseOperation
+          input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+          input :messages, accepts: Object, type: :keyword, required: false
+
+          def execute
+            twiml = Twilio::TwiML::VoiceResponse.new
+            add_messages(twiml, message_set: messages, response: phone_call.responses.build) if messages
+            twiml.hangup
+
+            Twilio::Rails.config.logger.info("error_twiml: #{twiml.to_s}")
+            twiml.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/twiml/greeting_operation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class GreetingOperation < Twilio::Rails::Phone::Twiml::BaseOperation
+          input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+
+          def execute
+            if !phone_caller.valid_north_american_phone_number? && tree.config[:invalid_phone_number]
+              Twilio::Rails::Phone::Twiml::ErrorOperation.call(phone_call_id: phone_call.id, tree: tree, messages: tree.config[:invalid_phone_number])
+            else
+              after = tree.greeting
+              after = Twilio::Rails::Phone::Tree::After.new(after.proc.call(phone_call.responses.build)) if after.proc
+              Twilio::Rails::Phone::Twiml::AfterOperation.call(phone_call_id: phone_call.id, tree: tree, after: after)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/twiml/prompt_operation.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class PromptOperation < Twilio::Rails::Phone::Twiml::BaseOperation
+          input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+          input :response_id, accepts: Integer, type: :keyword, required: true
+
+          def execute
+            return Twilio::Rails::Phone::Twiml::ErrorOperation.call(phone_call_id: phone_call.id, tree: tree) if phone_call.answering_machine?
+
+            response = phone_call.responses.find(response_id)
+            prompt = tree.prompts[response.prompt_handle]
+            raise Twilio::Rails::Phone::InvalidTreeError, "cannot find #{ response.prompt_handle } in #{ tree.name }" unless prompt
+
+            twiml_response = Twilio::TwiML::VoiceResponse.new do |twiml|
+              unless prompt.gather&.interrupt?
+                add_messages(twiml, message_set: prompt.messages, response: response)
+              end
+
+              case prompt.gather&.type
+              when :digits
+                args = {
+                  action: ::Twilio::Rails::Engine.routes.url_helpers.phone_prompt_response_path(
+                    format: :xml,
+                    tree_name: tree.name,
+                    response_id: response.id
+                  ),
+                  input: "dtmf",
+                  num_digits: prompt.gather.args[:number],
+                  timeout: prompt.gather.args[:timeout],
+                  action_on_empty_result: false,
+                }
+
+                args[:finish_on_key] = prompt.gather.args[:finish_on_key] if prompt.gather.args[:finish_on_key]
+
+                twiml.gather(**args) do |twiml|
+                  if prompt.gather&.interrupt?
+                    add_messages(twiml, message_set: prompt.messages, response: response)
+                  end
+                end
+                twiml.redirect(::Twilio::Rails::Engine.routes.url_helpers.phone_timeout_path(
+                  format: :xml,
+                  tree_name: tree.name,
+                  response_id: response.id
+                ))
+              when :voice
+                args = {
+                  max_length: prompt.gather.args[:length],
+                  play_beep: prompt.gather.args[:beep],
+                  # trim: "trim-silence",
+                  timeout: prompt.gather.args[:timeout],
+                  action: ::Twilio::Rails::Engine.routes.url_helpers.phone_prompt_response_path(
+                    format: :xml,
+                    tree_name: tree.name,
+                    response_id: response.id
+                  ),
+                  recording_status_callback: ::Twilio::Rails::Engine.routes.url_helpers.phone_receive_recording_path(
+                    response_id: response.id
+                  ),
+                }
+
+                if prompt.gather.args[:transcribe]
+                  args[:transcribe] = true
+                  args[:transcribe_callback] = ::Twilio::Rails::Engine.routes.url_helpers.phone_transcribe_path(response_id: response.id)
+                end
+
+                args[:profanity_filter] = true if prompt.gather.args[:profanity_filter]
+
+                twiml.record(**args)
+              when :speech
+                args = {
+                  action: ::Twilio::Rails::Engine.routes.url_helpers.phone_prompt_response_path(
+                    format: :xml,
+                    tree_name: tree.name,
+                    response_id: response.id
+                  ),
+                  input: "speech",
+                  timeout: prompt.gather.args[:timeout],
+                  action_on_empty_result: true,
+                  language: prompt.gather.args[:language].presence || "en-US",
+                  enhanced: !!prompt.gather.args[:enhanced],
+                }
+
+                args[:speech_timeout] = prompt.gather.args[:speech_timeout] if prompt.gather.args[:speech_timeout]
+                args[:speech_model] = prompt.gather.args[:speech_model] if prompt.gather.args[:speech_model].present?
+                args[:profanity_filter] = true if prompt.gather.args[:profanity_filter]
+
+                twiml.gather(**args)
+              when nil
+                twiml.redirect(::Twilio::Rails::Engine.routes.url_helpers.phone_prompt_response_path(
+                  format: :xml,
+                  tree_name: tree.name,
+                  response_id: response.id
+                ))
+              else
+                raise Twilio::Rails::Phone::InvalidTreeError, "unknown gather type #{prompt.gather.type.inspect}"
+              end
+            end
+
+            Twilio::Rails.config.logger.info("prompt_twiml: #{twiml_response.to_s}")
+            twiml_response.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/twiml/prompt_response_operation.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class PromptResponseOperation < Twilio::Rails::Phone::Twiml::BaseOperation
+          input :tree, accepts: Twilio::Rails::Phone::Tree, type: :keyword, required: true
+          input :response_id, accepts: Integer, type: :keyword, required: true
+          input :params, accepts: Hash, type: :keyword, required: true
+
+          def execute
+            return Twilio::Rails::Phone::Twiml::ErrorOperation.call(phone_call_id: phone_call.id, tree: tree) if phone_call.answering_machine?
+
+            response = phone_call.responses.find(response_id)
+            response = Twilio::Rails::Phone::UpdateResponseOperation.call(params: params, response_id: response.id, phone_call_id: phone_call.id)
+
+            prompt = tree.prompts[response.prompt_handle]
+            raise Twilio::Rails::Phone::InvalidTreeError, "cannot find #{ response.prompt_handle } in #{ tree.name }" unless prompt
+
+            after = prompt.after
+            after = Twilio::Rails::Phone::Tree::After.new(after.proc.call(response)) if after.proc
+
+            Twilio::Rails::Phone::Twiml::AfterOperation.call(phone_call_id: phone_call.id, tree: tree, after: after)
+          end
+        end
+      end
+    end
+  end
+end

data/app/operations/twilio/rails/phone/twiml/request_validation_failure_operation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+module Twilio
+  module Rails
+    module Phone
+      module Twiml
+        class RequestValidationFailureOperation < ::Twilio::Rails::ApplicationOperation
+          def execute
+            twiml = Twilio::TwiML::VoiceResponse.new
+            twiml.hangup
+            twiml.to_s
+          end
+        end
+      end
+    end
+  end
+end