twilio_base 1.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c311949da93145ded13db202755e0c1be16b7af64759759bd2882c50c5bc76be
+  data.tar.gz: fea72528cca59bf1615562756d6acd1fd1da0bf6b0c5ac8a646c87927f390cd0
+SHA512:
+  metadata.gz: 8115059638c69209438993dc9e3657235e196dcfd2fa8ae5ff1aa963bfa61e3213923eb59f848a3030f48488be36650dc51cbe2d76745e46931b2bbf25890c34
+  data.tar.gz: 1b17190e135f6e3012e8311fe11e3d55439cb53c24a9293e79afa0c681c16e4efc11db722f79b2d85054595ad2283a6dcd34d9358ce3e1ca690f29737ed5ce21

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.byebug_history
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/twilio_base_dummy/config/database.yml
+/spec/twilio_base_dummy/log/
+/spec/twilio_base_dummy/tmp/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,82 @@
+AllCops:
+  TargetRubyVersion: 2.3
+  Exclude:
+    - 'spec/twilio_base_dummy/db/**/*'
+    - 'vendor/**/*'
+
+Layout/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/ExtraSpacing:
+  Exclude:
+    - 'bin/*'
+
+Layout/IndentFirstArgument:
+  EnforcedStyle: consistent
+
+Layout/IndentFirstArrayElement:
+  EnforcedStyle: consistent
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Metrics/AbcSize:
+  Exclude:
+    - 'spec/support/twilio_base/responses/twiml.rb'
+    - 'spec/support/twilio_base/fake/helpers.rb'
+
+Metrics/LineLength:
+  Max: 80
+  Exclude:
+    - 'spec/twilio_base_dummy/config/**/*'
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - './spec/**/*'
+    - 'twilio_base.gemspec'
+
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+Style/BlockComments:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Style/Documentation:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/HashSyntax:
+  Exclude:
+    - 'Rakefile'
+    - 'lib/tasks/*.rake'
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/MixinUsage:
+  Exclude:
+    - 'spec/twilio_base_dummy/bin/*'
+
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    '%':  ()
+    '%i': '[]'
+    '%q': ()
+    '%Q': ()
+    '%r': '{}'
+    '%s': ()
+    '%w': '[]'
+    '%W': '[]'
+    '%x': ()
+
+Style/StringLiterals:
+  Exclude:
+    - 'bin/*'
+    - 'spec/support/twilio_base/responses/twiml.rb'
+    - 'spec/support/twilio_base/routers/voice/task_router_spec.rb'

data/.ruby-version

@@ -0,0 +1 @@
+2.5.1

data/.tool-versions

@@ -0,0 +1 @@
+ruby 2.5.1

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+ruby '2.5.1'
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in twilio_base.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,142 @@
+# TwilioBase
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/twilio_base`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'twilio_base'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install twilio_base
+
+
+## Migrations
+The gem has a migration to create a global config to store the various sids required from a Twilio environment (either an existing environment or one created via the engine). To install the migration in your host app use `bin/rails twilio_base:install:migrations` and then run migrations as usual.
+
+## Protocols & Routing
+Consistency in approach is a key goal of this library. `Protocols` and `Routers`
+are designed to facilitate consistency in how we handle outbound voice
+communications from any application.
+
+### Protocols
+Protocols allow you to specify `sip` or `pstn` as a protocol for initiating
+outbound voice calls. You can also rely on `default` if you wish to set a
+default method for the application as a whole.
+
+#### PSTN
+```ruby
+TwilioBase::Protocols::Voice::Pstn.new(params: {}, to: '+447755747275')
+```
+
+#### SIP
+
+In order to use SIP, you must specify some SIP Session Border Controller (SBC)
+settings using the `SIP_ENDPOINTS` ENV var e.g.
+
+```ruby
+{
+ sbc_one: ['123@abc.net', '345@abc.net'],
+ sbc_two: ['123@asdf.net', '345@asdf.net']
+}
+```
+
+```ruby
+TwilioBase::Protocols::Voice::Sip.new(
+  params: {
+    sbc_provider: :sbc_one
+  },
+  to: '+447755747275'
+  )
+```
+
+#### Default
+```ruby
+TwilioBase::Protocols::Voice::Default.new(params: {}, to: '+447755747275')
+```
+The default will be determined by the `VOICE_PROTOCOL` ENV var.
+
+#### Options
+
+| Option | Details | Required |
+|--------|---------|----------|
+| `action_url` | A url, which will receive actions from the outbound call. | No |
+| `action_url_attributes` | A hash of attributes to append to the action_url as parameters. | No |
+| `status_callback_url` | A url, which will receive callbacks associated with the outbound call. | No |
+| `timeout` | The length of time, in seconds, that the call will ring for before timing out. | No |
+| `sbc_provider` | The SIP Session Border Controller that you would like a call to deliver to. The protocol will load balance across any endpoints associated with a given SBC. | SIP only |
+| `sip_endpoint` | The SIP address that you would like a call to deliver to. | SIP only |
+| `wait_url` | A url , which points to an audio file that will be played if the call is put on hold. | No |
+
+N.B. When using `sip` you must either specify a valid `sbc_provider` or a
+`sip_endpoint` in the parameters when initialising the protocol.
+
+### Routers
+Routers allow us to specify a preferred option for routing an outbound call,
+either by direct dial or task router. A router accepts a `Protocol` to generate
+the correct Twiml.
+
+#### Direct Dial
+```ruby
+TwilioBase::Routers::Voice::DirectDial.new(protocol: protocol).route
+```
+
+#### Task Router
+```ruby
+TwilioBase::Routers::Voice::TaskRouter.new(protocol: protocol).route
+```
+
+#### Default
+```ruby
+TwilioBase::Routers::Voice::Default.new(protocol: protocol).route
+```
+
+The default will be determined by the `ROUTING_METHOD` ENV var.
+
+## Testing
+
+The Twilio api is completely represented by a series of fake classes that can be used in your test suite.  To enable them to be used in your host app's specs add the following to your rails_helper:
+
+### Fakes
+
+```ruby
+Dir[Pathname(Gem::Specification.find_by_name('twilio_base').gem_dir)
+  .join('spec', 'support', 'twilio_base', 'fake', '**', '*.rb')]
+  .each { |f| require f }
+
+Twilio::REST::Client = TwilioBase::Override::Fake::Clients::Rest
+```
+
+You can then refer to the fake classes in test via TwilioBase::Fake...
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/DVELP/twilio_base. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## Code of Conduct
+
+Everyone interacting in the TwilioBase project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/DVELP/twilio_base/blob/master/CODE_OF_CONDUCT.md).
+
+<br></br>
+[![DVELP
+logo](https://raw.githubusercontent.com/DVELP/cookbook/master/assets/dvelp-logo.png
+'DVELP logo')](http://dvelp.co.uk)
+
+TwilioBase was created and is maintained by DVELP Ltd.
+

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+APP_RAKEFILE = File.expand_path('spec/twilio_base_dummy/Rakefile', __dir__)
+
+load 'rails/tasks/engine.rake'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/app/controllers/twilio_base/base_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  class BaseController < ApplicationController
+    before_action :validate_request
+    before_action :force_request_format
+
+    include ActionController::MimeResponds
+
+    private
+
+    def validate_request
+      request_verification_service =
+        TwilioBase::RequestVerificationService.new(
+          Twilio::Security::RequestValidator.new(
+            ENV.fetch('TWILIO_AUTH_TOKEN')
+          )
+        )
+
+      unless request_verification_service.verify(
+        uri: request.original_url,
+        env: request.env
+      )
+        render head :ok, status: :unauthorized && return
+      end
+    end
+
+    def force_request_format
+      request.format = :xml unless params[:format]
+    end
+  end
+end

data/app/models/twilio_base/global_config.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  class GlobalConfig < ActiveRecord::Base; end
+end

data/app/services/twilio_base/api_key.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  class ApiKey
+    FRIENDLY_NAME = 'front-end key'
+
+    class << self
+      include TwilioBase::Clients
+
+      def create
+        rest_client.new_keys.create(friendly_name: FRIENDLY_NAME)
+      end
+    end
+  end
+end

data/app/services/twilio_base/application.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  class Application
+    class << self
+      include TwilioBase::Clients
+
+      def create(attributes)
+        applications_client.create(
+          attributes
+        )
+      end
+
+      def find(sid)
+        applications_client(sid).fetch
+      end
+
+      private
+
+      def applications_client(sid = nil)
+        if sid
+          rest_client.api.v2010.account.applications(sid)
+        else
+          rest_client.api.v2010.account.applications
+        end
+      end
+    end
+  end
+end

data/app/services/twilio_base/clients.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  module Clients
+    ACCOUNT_SID = ENV.fetch('TWILIO_ACCOUNT_SID')
+    AUTH_TOKEN = ENV.fetch('TWILIO_AUTH_TOKEN')
+
+    delegate :api_key_sid, to: :config
+    delegate :api_key_secret, to: :config
+    delegate :application_sid, to: :config
+    delegate :chat_service_sid, to: :config
+    delegate :phone_number, to: :config
+    delegate :sync_service_sid, to: :config
+    delegate :workflow_sid, to: :config
+    delegate :workspace_sid, to: :config
+
+    def config
+      @config ||= TwilioBase::GlobalConfig.first
+    end
+
+    def chat_client
+      @chat_client ||= Twilio::ChatClient.new(
+        account_sid: ACCOUNT_SID, auth_token: AUTH_TOKEN
+      )
+    end
+
+    def sms_client
+      @sms_client ||= TwilioBase::Clients::Sms.new(
+        account_sid: ACCOUNT_SID, auth_token: AUTH_TOKEN
+      )
+    end
+
+    def rest_client
+      @rest_client ||= Twilio::REST::Client.new(ACCOUNT_SID, AUTH_TOKEN)
+    end
+  end
+end

data/app/services/twilio_base/phone_number.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  class PhoneNumber
+    COUNTRY_CODE = ENV.fetch('COUNTRY_CODE')
+
+    class << self
+      include TwilioBase::Clients
+
+      def find_or_create(phone_number)
+        phone_number ? find(phone_number) : create
+      end
+
+      private
+
+      def find(phone_number)
+        incoming_phone_numbers.list(phone_number: phone_number).first
+      end
+
+      def create
+        number = available_numbers.first.phone_number
+        purchase_number(number)
+      end
+
+      def available_numbers
+        rest_client.api.available_phone_numbers(COUNTRY_CODE).local.list(
+          sms_enabled: true
+        )
+      end
+
+      def purchase_number(number)
+        incoming_phone_numbers.create(phone_number: number)
+      end
+
+      def incoming_phone_numbers
+        rest_client.api.incoming_phone_numbers
+      end
+    end
+  end
+end

data/app/services/twilio_base/protocols/voice/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  module Protocols
+    module Voice
+      class Base
+        include ::Helpers::Protocols
+
+        ANONYMOUS_NUMBER = '+266696687'
+        STATUS_CALLBACK_EVENTS = %w[initiated ringing answered completed].freeze
+
+        def initialize(params: {}, to:)
+          self.params = params
+          self.to = to
+
+          raise 'To cannot be blank' if to.blank?
+        end
+
+        def action_url
+          params[:action_url]
+        end
+
+        def action_url_attributes
+          { endpoint: to }
+        end
+
+        def caller_uuid
+          mpoa.presence || ANONYMOUS_NUMBER
+        end
+
+        def endpoint
+          to
+        end
+
+        def name
+          :number
+        end
+
+        def status_callback_events
+          STATUS_CALLBACK_EVENTS.join(' ')
+        end
+
+        def status_callback_url
+          params[:status_callback_url]
+        end
+
+        def timeout
+          params[:timeout]
+        end
+
+        def wait_url
+          params[:wait_url]
+        end
+
+        private
+
+        attr_accessor :params, :to
+
+        def mpoa
+          extract_mpoa(params[:caller_uuid])
+        end
+      end
+    end
+  end
+end

data/app/services/twilio_base/protocols/voice/pstn.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  module Protocols
+    module Voice
+      class Pstn < Base
+        def name
+          :number
+        end
+      end
+    end
+  end
+end

data/app/services/twilio_base/protocols/voice/sip.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  module Protocols
+    module Voice
+      class Sip < Base
+        def endpoint
+          "sip:#{sip_endpoint}?#{parsed_headers}"
+        end
+
+        def name
+          :sip
+        end
+
+        private
+
+        def parsed_headers
+          hash = headers.each_with_object({}) do |(k, v), obj|
+            key = "X-#{k.to_s.camelize}"
+            value = v.presence || '-'
+
+            obj[key] = value
+          end
+
+          Addressable::URI.new(query_values: hash).query
+        end
+
+        def headers
+          params[:headers].is_a?(Hash) ? params[:headers] : {}
+        end
+
+        def sip_endpoint
+          sip_whip
+        end
+
+        def sip_whip
+          @sip_whip ||= sip_endpoints.sample.to_s.strip
+        end
+
+        def sip_endpoints
+          value = Array(to)
+
+          value.flat_map { |v| v.split(',') }
+        end
+      end
+    end
+  end
+end

data/app/services/twilio_base/protocols/voice.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  module Protocols
+    module Voice
+      module Default
+        module_function
+
+        def init(params: {}, protocol: nil, to:)
+          protocol ||= ENV.fetch('VOICE_PROTOCOL')
+          klass = {
+            'pstn' => Protocols::Voice::Pstn,
+            'sip' => Protocols::Voice::Sip
+          }.fetch(protocol.to_s, Protocols::Voice::Pstn)
+
+          klass.new(
+            params: params,
+            to: to
+          )
+        end
+      end
+    end
+  end
+end

data/app/services/twilio_base/request_verification_service.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  class RequestVerificationService
+    attr_accessor :validator
+
+    def initialize(validator)
+      self.validator = validator
+    end
+
+    def verify(uri:, env:)
+      params = if env['REQUEST_METHOD'] == 'POST'
+                 env['rack.request.form_hash']
+               else
+                 env['rack.request.query_hash']
+               end
+      signature = env['HTTP_X_TWILIO_SIGNATURE']
+      signature.present? && validator.validate(uri, params, signature)
+    end
+  end
+end

data/app/services/twilio_base/routers/voice/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module TwilioBase
+  module Routers
+    module Voice
+      class Base
+        include Rails.application.routes.url_helpers
+
+        def initialize(protocol:)
+          self.protocol = protocol
+        end
+
+        def route
+          yield_response = yield if block_given?
+
+          (yield_response || voice_response).dial(dial_attribues) do |dial|
+            dial.public_send(
+              protocol.name,
+              protocol.endpoint,
+              status_callback_event: protocol.status_callback_events,
+              status_callback: protocol.status_callback_url
+            )
+          end.to_s
+        end
+
+        private
+
+        attr_accessor :protocol
+
+        def voice_response
+          @voice_response ||= Twilio::TwiML::VoiceResponse.new
+        end
+
+        def dial_attribues
+          {
+            action: protocol.action_url,
+            caller_id: protocol.caller_uuid,
+            timeout: protocol.timeout
+          }
+        end
+      end
+    end
+  end
+end