reach-ruby 1.0.0

data/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+<!--
+We appreciate the effort for this pull request but before that please make sure you read the contribution guidelines, then fill out the blanks below.
+
+Please format the PR title appropriately based on the type of change:
+  <type>[!]: <description>
+Where <type> is one of: docs, chore, feat, fix, test, misc.
+Add a '!' after the type for breaking changes (e.g. feat!: new breaking feature).
+
+**All third-party contributors acknowledge that any contributions they provide will be made under the same open-source license that the open-source project is provided under.**
+
+Please enter each Issue number you are resolving in your PR after one of the following words [Fixes, Closes, Resolves]. This will auto-link these issues and close them when this PR is merged!
+e.g.
+Fixes #1
+Closes #2
+-->
+
+# Fixes #
+
+A short description of what this PR does.
+
+### Checklist
+- [x] I acknowledge that all my contributions will be made under the project's license
+- [ ] I have made a material change to the repo (functionality, testing, spelling, grammar)
+- [ ] I have read the [Contribution Guidelines](https://github.com/talkylabs/reach-ruby/blob/main/CONTRIBUTING.md) and my PR follows them
+- [ ] I have titled the PR appropriately
+- [ ] I have updated my branch with the main branch
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have added the necessary documentation about the functionality in the appropriate .md file
+- [ ] I have added inline documentation to the code I modified
+
+If you have questions, please create a GitHub Issue in this repository.

data/README.md

@@ -0,0 +1,237 @@
+# reach-ruby
+
+
+## Documentation
+
+The documentation for the Reach API can be found [here][apidocs].
+
+The individual releases [here][refdocs].
+
+## Versions
+
+`reach-ruby` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.
+
+### Supported Ruby Versions
+
+This library supports the following Ruby implementations:
+
+- Ruby 2.4
+- Ruby 2.5
+- Ruby 2.6
+- Ruby 2.7
+- Ruby 3.0
+- Ruby 3.1
+
+## Installation
+
+To install using [Bundler][bundler] grab the latest stable version:
+
+```ruby
+gem 'reach-ruby', '~> 1.0.0'
+```
+
+To manually install `reach-ruby` via [Rubygems][rubygems] simply gem install:
+
+```bash
+gem install reach-ruby -v 1.0.0
+```
+
+To build and install the development branch yourself from the latest source:
+
+```bash
+git clone git@github.com:talkylabs/reach-ruby.git
+cd reach-ruby
+make install
+```
+
+> **Info**
+> If the command line gives you an error message that says Permission Denied, try running the above commands with sudo.
+>
+> For example: `sudo gem install reach-ruby`
+
+### Test your installation
+
+To make sure the installation was successful, try sending yourself an SMS message, like this:
+
+```rb
+require "reach-ruby"
+
+# Your API user and key the web app
+apiUser = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+apiKey = "your_api_key"
+
+@client = Reach::REST::Client.new apiUser, apiKey
+message = @client.messaging.messaging_items.dispatch(
+  body: "Hello from Ruby",
+  dest: "+12345678901",  # Text this number
+  src: "+15005550006", # From a valid number
+)
+
+puts message.messageId
+```
+
+> **Warning**
+> It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production.
+
+## Usage
+
+### Authenticate the Client
+
+```ruby
+require 'reach-ruby'
+
+# Your API user and key the web app
+apiUser = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+apiKey = "your_api_key"
+
+# Initialize the Reach Client with your credentials
+@client = Reach::REST::Client.new apiUser, apiKey
+```
+
+### Send an SMS
+
+```ruby
+@client.messaging.messaging_items.dispatch(
+  src: '+14159341234',
+  dest: '+16105557069',
+  body: 'Hey there!'
+)
+```
+
+### List your SMS Messages
+
+```ruby
+@client.messaging.messaging_items.dispatch.list(limit: 20)
+```
+
+### Fetch a single SMS message by messageId
+
+```ruby
+# put the message sid you want to retrieve here:
+messageId = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+@client.messaging.messaging_items(messageId).fetch
+```
+
+### Iterate through records
+
+The library automatically handles paging for you. Collections, such as `messaging_items`, have `list` and stream methods that page under the hood. With both `list` and `stream`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`page_size`). The library will then handle the task for you.
+
+`list` eagerly fetches all records and returns them as a list, whereas `stream` returns an enumerator and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.
+
+
+```rb
+require 'reach-ruby'
+
+# Your API user and key the web app
+apiUser = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+apiKey = "your_api_key"
+
+@client = Reach::REST::Client.new(apiUser, apiKey)
+
+@client.messaging.messaging_items.list
+       .each do |msg|
+         puts msg.messageId
+       end
+```
+
+### Enable Debug logging
+
+In order to enable debug logging, pass in a 'logger' instance to the client with the level set to at least 'DEBUG'
+
+```ruby
+@client = Reach::REST::Client.new apiUser, apiKey
+myLogger = Logger.new(STDOUT)
+myLogger.level = Logger::DEBUG
+@client.logger = myLogger
+
+@client = Reach::REST::Client.new apiUser, apiKey
+myLogger = Logger.new('my_log.log')
+myLogger.level = Logger::DEBUG
+@client.logger = myLogger
+```
+
+### Handle Exceptions {#exceptions}
+
+If the Reach API returns a 400 or a 500 level HTTP response, the `reach-ruby`
+library will throw a `Reach::REST::RestError`. 400-level errors are normal
+during API operation (`“Invalid number”`, `“Cannot deliver SMS to that number”`,
+for example) and should be handled appropriately.
+
+```rb
+require 'reach-ruby'
+
+# Your API user and key the web app
+apiUser = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+apiKey = "your_api_key"
+
+@client = Reach::REST::Client.new apiUser, apiKey
+
+begin
+  messages = @client.messaging.messaging_items.list(limit: 20)
+rescue Reach::REST::RestError => e
+  puts e.message
+end
+```
+
+### Debug API requests
+
+To assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.
+
+For example, you can retrieve the status code of the last response like so:
+
+```ruby
+require 'rubygems' # Not necessary with ruby 1.9 but included for completeness
+require 'reach-ruby'
+
+# Your API user and key the web app
+apiUser = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+apiKey = "your_api_key"
+
+@client = Reach::REST::Client.new(apiUser, apiKey)
+
+@message = @client.messaging.messaging_items.dispatch(
+  dest: '+14158675309',
+  src: '+14258675310',
+  body: 'Ahoy!'
+)
+
+# Retrieve the status code of the last response from the HTTP client
+puts @client.http_client.last_response.status_code
+```
+
+### Customize your HTTP Client
+
+`reach-ruby` uses [Faraday][faraday] to make HTTP requests. You can tell `Reach::REST::Client` to use any of the Faraday adapters like so:
+
+```ruby
+@client.http_client.adapter = :typhoeus
+```
+
+To use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md).
+
+To apply customizations such as middleware, you can use the `configure_connection` method like so:
+
+```ruby
+@client.http_client.configure_connection do |faraday|
+  faraday.use SomeMiddleware
+end
+```
+
+
+
+## Docker Image
+
+The `Dockerfile` present in this repository and its respective `talkylabs/reach-ruby` Docker image are currently used by Us for testing purposes only.
+
+## Getting help
+
+If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!
+
+[apidocs]: https://www.reach.talkylabs.com/docs/api
+[refdocs]: https://talkylabs.github.io/reach-ruby
+[wiki]: https://github.com/talkylabs/reach-ruby/wiki
+[bundler]: https://bundler.io
+[rubygems]: https://rubygems.org
+[gem]: https://rubygems.org/gems/talkylabs
+[issues]: https://github.com/talkylabs/reach-ruby/issues
+[faraday]: https://github.com/lostisland/faraday

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler'
+Bundler.setup
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+desc 'Run all specs'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+task test: :spec

data/UPGRADE.md

@@ -0,0 +1,5 @@
+# Upgrade Guide
+
+_All `MINOR` and `MAJOR` version bumps will have upgrade notes
+posted here._
+

data/VERSIONS.md

@@ -0,0 +1,35 @@
+# Versioning Strategy
+
+`reach-ruby` uses a modified version of [Semantic Versioning][semver] for
+all changes to the helper library. It is strongly encouraged that you pin at
+least the major version and potentially the minor version to avoid pulling in
+breaking changes.
+
+Semantic Versions take the form of `MAJOR.MINOR.PATCH`
+
+When bugs are fixed in the library in a backwards-compatible way, the `PATCH`
+level will be incremented by one. When new features are added to the library
+in a backwards-compatible way, the `PATCH` level will be incremented by one.
+`PATCH` changes should _not_ break your code and are generally safe for upgrade.
+
+When a new large feature set comes online or a small breaking change is
+introduced, the `MINOR` version will be incremented by one and the `PATCH`
+version reset to zero. `MINOR` changes _may_ require some amount of manual code
+change for upgrade. These backwards-incompatible changes will generally be
+limited to a small number of function signature changes.
+
+The `MAJOR` version is used to indicate the family of technology represented by
+the helper library. Breaking changes that require extensive reworking of code
+will cause the `MAJOR` version to be incremented by one, and the `MINOR` and
+`PATCH` versions will be reset to zero. We understands that this can be very
+disruptive, so we will only introduce this type of breaking change when
+absolutely necessary. New `MAJOR` versions will be communicated in advance with
+`Release Candidates` and a schedule.
+
+## Supported Versions
+
+Only the current `MAJOR` version of `reach-ruby` is supported. New
+features, functionality, bug fixes, and security updates will only be added to
+the current `MAJOR` version.
+
+[semver]: https://semver.org

data/advanced-examples/custom-http-client.md

@@ -0,0 +1,166 @@
+# Custom HTTP Clients for the Reach Ruby Helper Library
+
+If you are working with the Reach Ruby Helper Library, and you need to be able to modify the HTTP requests that the library makes to the Reach servers, you’re in the right place. The most common need to alter the HTTP request is to connect and authenticate with an enterprise’s proxy server. We’ll provide sample code that you can drop right into your app to handle this use case.
+
+Connect and authenticate with a proxy server
+To connect and provide credentials to a proxy server that may be between your app and Reach, you need a way to modify the HTTP requests that the Reach helper library makes on your behalf to invoke the Reach REST API.
+
+The Reach Ruby helper library uses the [Faraday](https://rubygems.org/gems/faraday) gem under the hood to make the HTTP requests. The following example shows a typical request, without a custom `http_client`:
+
+```rb
+@client = Reach::REST::Client.new(username, auth_token)
+
+message = @client.messaging.messaging_items
+  .dispatch(
+    dest: "+15558675310",
+    body: "Hey there!",
+    src: "+15017122661",
+  )
+```
+
+Out of the box, the helper library is creating a default `Reach::Http::Client` for you, using the Reach credentials you provide. However, you can create your own `Reach::Http::Client`, and pass it to any Reach REST API resource action you want.
+
+Here’s an example of sending an SMS message with a custom client:
+
+```rb
+require "rubygems"
+require "reach-ruby"
+require "dotenv/load"
+
+# Custom HTTP Client
+require_relative "MyRequestClass"
+
+# Your username and Auth Token from the web application
+username = ENV["API_USER"]
+auth_token = ENV["API_KEY"]
+proxy_address = ENV["PROXY_ADDRESS"]
+proxy_protocol = ENV["PROXY_PROTOCOL"]
+proxy_port = ENV["PROXY_PORT"]
+
+my_request_client = MyRequestClass.new(proxy_protocol, proxy_address, proxy_port)
+
+@client = Reach::REST::Client.new(username, auth_token, my_request_client)
+
+message = @client.messaging.messaging_items
+  .dispatch(
+    dest: "+593978613041",
+    body: "RB This is the ship that made the Kesssssel Run in fourteen parsecs?",
+    src: "+13212855389",
+  )
+
+puts "Message SID: #{message.messageId}"
+```
+
+## Create your custom ReachRestClient
+
+When you take a closer look at the constructor for `Reach::Http::Client`, you see that this class provides it to the Reach helper library to make the necessary HTTP requests.
+
+## Call Reach through the proxy server
+
+Now that we understand how all the components fit together, we can create our own `http_client` that can connect through a proxy server. To make this reusable, here’s a class that you can use to create this `http_client` whenever you need one.
+
+```rb
+class MyRequestClass
+  attr_accessor :adapter
+  attr_reader :timeout, :last_response, :last_request
+
+  def initialize(proxy_prot = nil, proxy_addr = nil, proxy_port = nil, timeout: nil)
+    @proxy_prot = proxy_prot
+    @proxy_addr = proxy_addr
+    @proxy_port = proxy_port
+    @timeout = timeout
+    @adapter = Faraday.default_adapter
+  end
+
+  def _request(request)
+    @connection = Faraday.new(url: request.host + ":" + request.port.to_s, ssl: { verify: true }) do |f|
+      f.options.params_encoder = Faraday::FlatParamsEncoder
+      f.request :url_encoded
+      f.adapter @adapter
+      f.headers = request.headers
+      f.headers["ApiUser"] = request.auth[0]
+      f.headers["ApiKey"] = request.auth[1]
+      if @proxy_addr
+        f.proxy = "#{@proxy_prot}://#{@proxy_addr}:#{@proxy_port}"
+      end
+      f.options.open_timeout = request.timeout || @timeout
+      f.options.timeout = request.timeout || @timeout
+    end
+
+    @last_request = request
+    @last_response = nil
+    response = @connection.send(request.method.downcase.to_sym,
+                                request.url,
+                                request.method == "GET" ? request.params : request.data)
+
+    if response.body && !response.body.empty?
+      object = response.body
+    elsif response.status == 400
+      object = { message: "Bad request", code: 400 }.to_json
+    end
+
+    reach_response = Reach::Response.new(response.status, object, headers: response.headers)
+    @last_response = reach_response
+
+    reach_response
+  end
+
+  def request(host, port, method, url, params = {}, data = {}, headers = {}, auth = nil, timeout = nil)
+    request = Reach::Request.new(host, port, method, url, params, data, headers, auth, timeout)
+    _request(request)
+  end
+end
+```
+
+In this example, we are using some environment variables loaded at the program startup to retrieve various configuration settings:
+
+- Your Reach Api User and Api Key
+- A proxy address in the form of `http://127.0.0.1:8888`
+
+These settings are located in a file like `.env` like so:
+
+```env
+API_USER=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+API_KEY= your_auth_token
+
+HTTPS_PROXY=https://127.0.0.1:8888
+HTTP_PROXY=http://127.0.0.1:8888
+```
+
+Here’s the full console program that sends a text message and shows how it all can work together. It loads the `.env` file.
+
+```rb
+require "rubygems"
+require "reach-ruby"
+require "dotenv/load"
+
+# Custom HTTP Client
+require_relative "MyRequestClass"
+
+username = ENV["API_USER"]
+auth_token = ENV["API_KEY"]
+proxy_address = ENV["PROXY_ADDRESS"]
+proxy_protocol = ENV["PROXY_PROTOCOL"]
+proxy_port = ENV["PROXY_PORT"]
+
+my_request_client = MyRequestClass.new(proxy_protocol, proxy_address, proxy_port)
+
+@client = Reach::REST::Client.new(username, auth_token, my_request_client)
+
+message = @client.messaging.messaging_items
+  .dispatch(
+    dest: "+593978613041",
+    body: "RB This is the ship that made the Kesssssel Run in fourteen parsecs?",
+    src: "+13212855389",
+  )
+
+puts "Message SID: #{message.messageId}"
+```
+
+## What else can this technique be used for?
+
+Now that you know how to inject your own `http_client` into the Reach API request pipeline, you could use this technique to add custom HTTP headers and authorization to the requests (perhaps as required by an upstream proxy server).
+
+You could also implement your own `http_client` to mock the Reach API responses so your unit and integration tests can run quickly without the need to make a connection to Reach.
+
+We can’t wait to see what you build!

data/examples/examples.rb

@@ -0,0 +1,23 @@
+# examples version
+
+@username = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+@auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
+# set up a client
+@client = Reach::REST::Client.new(@username, @auth_token)
+
+################ SMS MESSAGES ################
+
+@client.messaging.messaging_items.list(sent_at: '2010-09-01').each do |message|
+  puts message.dateCreated
+end
+
+# print a particular sms message
+puts @client.messaging.messaging_items('SMXXXXXXXX').fetch.body
+
+# send an sms
+@client.messaging.messaging_items.dispatch(
+  src: '+14159341234',
+  dest: '+16105557069',
+  body: 'Hey there!'
+)
+

data/githooks/pre-commit

@@ -0,0 +1 @@
+make test

data/lib/rack/reach_webhook_authentication.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'rack/media_type'
+
+module Rack
+  # Middleware that authenticates webhooks from Reach using the request
+  # validator.
+  #
+  # The middleware takes an auth token with which to set up the request
+  # validator and any number of paths. When a path matches the incoming request
+  # path, the request will be checked for authentication.
+  #
+  # Example:
+  #
+  # require 'rack'
+  # use Rack::ReachWebhookAuthentication, ENV['REACH_TALKYLABS_API_KEY'], /\/messages/
+  #
+  # The above appends this middleware to the stack, using an auth token saved in
+  # the ENV and only against paths that match /\/messages/. If the request
+  # validates then it gets passed on to the action as normal. If the request
+  # doesn't validate then the middleware responds immediately with a 403 status.
+
+  class ReachWebhookAuthentication
+    # Rack's FORM_DATA_MEDIA_TYPES can be modified to taste, so we're slightly
+    # more conservative in what we consider form data.
+    FORM_URLENCODED_MEDIA_TYPE = Rack::MediaType.type('application/x-www-form-urlencoded')
+
+    def initialize(app, auth_token, *paths, &auth_token_lookup)
+      @app = app
+      @auth_token = auth_token
+      define_singleton_method(:get_auth_token, auth_token_lookup) if block_given?
+      @path_regex = Regexp.union(paths)
+    end
+
+    def call(env)
+      return @app.call(env) unless env['PATH_INFO'].match(@path_regex)
+      request = Rack::Request.new(env)
+      original_url = request.url
+      params = extract_params!(request)
+      auth_token = @auth_token || get_auth_token(params['ApiUser'])
+      validator = Reach::Security::RequestValidator.new(auth_token)
+      signature = env['HTTP_X_REACH_SIGNATURE'] || ''
+      if validator.validate(original_url, params, signature)
+        @app.call(env)
+      else
+        [
+          403,
+          { 'Content-Type' => 'text/plain' },
+          ['Reach Request Validation Failed.']
+        ]
+      end
+    end
+
+    # Extract the params from the the request that we can use to determine the
+    # signature. This _may_ modify the passed in request since it may read/rewind
+    # the body.
+    def extract_params!(request)
+      return {} unless request.post?
+
+      if request.media_type == FORM_URLENCODED_MEDIA_TYPE
+        request.POST
+      else
+        request.body.rewind
+        body = request.body.read
+        request.body.rewind
+        body
+      end
+    end
+
+    private :extract_params!
+  end
+end

data/lib/reach-ruby/framework/reach_response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Reach
+  class ReachResponse
+    attr_accessor :status_code, :body
+
+    # @deprecated Use 'Reach::Response' instead.
+    def initialize(status_code, body)
+      warn "'Reach::ReachResponse' has been deprecated. Use 'Reach::Response' instead."
+      response = Reach::Response.new(status_code, body)
+      @status_code = response.status_code
+      @body = response.body
+    end
+
+    def to_s
+      "[#{@status_code}] #{@body}"
+    end
+  end
+end

data/lib/reach-ruby/framework/request.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Reach
+  class Request
+    attr_reader :host, :port, :method, :url, :params, :data, :headers, :auth, :timeout
+
+    def initialize(host, port, method, url, params = {}, data = {}, headers = {}, auth = nil, timeout = nil)
+      @host = host
+      @port = port
+      @url = url
+      @method = method
+      @params = params
+      @data = data
+      @headers = headers
+      @auth = auth
+      @timeout = timeout
+    end
+
+    def to_s
+      auth = @auth.nil? ? '' : '(' + @auth.join(',') + ')'
+
+      params = ''
+      unless @params.nil? || @params.empty?
+        params = '?' + @params.each.map { |key, value| "#{CGI.escape(key)}=#{CGI.escape(value)}" }.join('&')
+      end
+
+      headers = ''
+      unless @headers.nil? || @headers.empty?
+        headers = "\n" + @headers.each.map { |key, value| "-H \"#{key}\": \"#{value}\"" }.join("\n")
+      end
+
+      data = ''
+      unless @data.nil? || @data.empty?
+        data = @method.equal?('GET') ? "\n -G" : "\n"
+        data += @data.each.map { |key, value| "-d \"#{key}\"=\"#{value}\"" }.join("\n")
+      end
+
+      "#{auth} #{@method} #{@url}#{params}#{data}#{headers}"
+    end
+  end
+end

data/lib/reach-ruby/framework/response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Reach
+  class Response
+    attr_accessor :status_code, :body, :headers
+
+    def initialize(status_code, body, headers: nil)
+      @status_code = status_code
+      body = '{}' if !body || body.empty?
+      @body = JSON.parse(body)
+      @headers = !headers ? {} : headers.to_hash
+    end
+
+    def to_s
+      "[#{status_code}] #{body}"
+    end
+  end
+end