aftalk 0.1.0

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,69 @@
+[![Build](https://circleci.com/gh/thriveglobal/aftalk.svg?&style=shield&circle-token=ade67468e07185e650dc6ba100127bce34bd10b5)](https://circleci.com/gh/thriveglobal/aftalk)
+[![Maintainability](https://api.codeclimate.com/v1/badges/8d84a0d4fc06f1c49cd8/maintainability)](https://codeclimate.com/github/thriveglobal/aftalk/maintainability)
+
+# aftalk
+
+A Ruby wrapper for [Africa's Talking](https://africastalking.com) telephony services.
+
+Currently the only endpoint supported is the `/messaging` POST endpoint that allows you to send SMS messages. Support for other endpoints is planned for future releases.
+
+## Installation
+
+Add 
+
+> `gem "aftalk"`
+ 
+to your `Gemfile` and run
+ 
+> `$ bundle`
+
+or install manually by running
+
+> `gem install aftalk`.
+
+## Configuration
+
+Africa's Talking needs a username and an API key to authenticate your requests. You can also toggle sandbox mode, which causes the gem to hit AF's sandbox host instead of the live API. (**Note: Use of sandbox mode requires that you provide the username `sandbox`.** This is not well documented.)
+
+There are two ways to configure these options.
+
+### Set environment variables
+
+The first way to configure `aftalk` is by setting environment variables. You can do this by creating a file called `.env` in your project root and adding content like this to it:
+
+```txt
+AFRICAS_TALKING_API_KEY=abc123
+AFRICAS_TALKING_USER_NAME=sandbox
+AFRICAS_TALKING_SANDBOX=true
+``` 
+
+Replace the values with your own data. Sandbox mode will be activated if any value whatsoever is provided for `AFRICAS_TALKING_SANDBOX`. If you don't want to use sandbox mode, don't set this variable at all.
+
+### Use `AfTalk::Configuration`
+
+You can also configure this data in Ruby code as follows:
+
+```ruby
+AfTalk::Configuration.configure do |config|
+  config.api_key = "abc123"
+  config.sandbox = true
+  config.user_name = "sandbox"
+end
+```
+
+Make sure this code runs before you try to use the API.
+
+## Usage
+
+To send an SMS:
+
+```ruby
+phone_number = "+15555555555"
+message = "Hello, world!"
+
+AfTalk.send_message(
+  to: phone_number,
+  message: message,
+)
+```
+The `send_message` method requires `to` and `message` parameters, but also supports all optional parameters supported by the API. For a full list, see [the API docs](http://docs.africastalking.com/sms/sending/). 

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/africas_talking_api.gemspec

@@ -0,0 +1,27 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "aftalk/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "aftalk"
+  spec.version       = AfTalk::VERSION
+  spec.email         = ["techadmin@thriveglobal.com"]
+  spec.summary       = "API wrapper for Africa's Talking services"
+  spec.description   = <<-DESC
+    A Ruby wrapper for Africa's Talking telephony services (https://africastalking.com)
+  DESC
+  spec.homepage      = "https://github.com/thriveglobal/africas_talking_api"
+  spec.license       = "MIT"
+  spec.authors       = ["Thrive Global Engineering Team"]
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_dependency "dotenv", "~>2.2"
+  spec.add_dependency "faraday", "~> 0.13"
+  spec.add_dependency "faraday_middleware", "~> 0.12"
+  spec.add_development_dependency "rake", "~> 12"
+  spec.add_development_dependency "rspec", "~> 3.7"
+  spec.add_development_dependency "rspec_junit_formatter", "~> 0.3"
+  spec.add_development_dependency "vcr", "~> 3.0"
+end

data/lib/aftalk.rb

@@ -0,0 +1,13 @@
+require "dotenv"
+Dotenv.load
+
+APP_PATH = File.expand_path("../", __FILE__) + "/aftalk"
+
+module AfTalk
+  autoload(:Response, "#{APP_PATH}/response.rb")
+  autoload(:Client, "#{APP_PATH}/client.rb")
+
+  extend AfTalk::Client
+end
+
+Dir["#{APP_PATH}/**/*.rb"].each { |file| require file }

data/lib/aftalk/client.rb

@@ -0,0 +1,20 @@
+module AfTalk
+  module Client
+    def send_message(to:, message:, **options)
+      messaging_params = { to: to, message: message }.merge(options)
+      response = post("/messaging", messaging_params)
+
+      AfTalk::SendMessageResponse.new(response)
+    end
+
+    private
+
+    def post(endpoint, **options)
+      request.post(endpoint, options)
+    end
+
+    def request
+      AfTalk::Request
+    end
+  end
+end

data/lib/aftalk/configuration.rb

@@ -0,0 +1,37 @@
+module AfTalk
+  class Configuration
+    DEFAULT_VERSION = "version1".freeze
+
+    class << self
+      attr_writer :api_key, :sandbox, :user_name
+
+      def configure
+        yield self
+        connection.clear
+        self
+      end
+
+      def version
+        DEFAULT_VERSION
+      end
+
+      def api_key
+        @api_key || ENV["AFRICAS_TALKING_API_KEY"]
+      end
+
+      def sandbox
+        @sandbox || ENV["AFRICAS_TALKING_SANDBOX"]
+      end
+
+      def user_name
+        @user_name || ENV["AFRICAS_TALKING_USER_NAME"]
+      end
+
+      private
+
+      def connection
+        AfTalk::Connection
+      end
+    end
+  end
+end

data/lib/aftalk/connection.rb

@@ -0,0 +1,37 @@
+require "faraday"
+require "faraday_middleware"
+
+module AfTalk
+  class Connection
+    URL = "https://api.africastalking.com".freeze
+    SANDBOX_URL = "https://api.sandbox.africastalking.com".freeze
+
+    def self.build
+      @_connection ||= new.build
+    end
+
+    def self.clear
+      @_connection = nil
+    end
+
+    def build
+      Faraday.new(
+        url: api_url,
+        headers: { apiKey: AfTalk::Configuration.api_key,
+                   accept: "application/json" },
+      ) do |connection|
+        connection.request :url_encoded
+        connection.response :json,
+                            content_type: /\bjson$/,
+                            parser_options: { symbolize_names: true }
+        connection.adapter Faraday.default_adapter
+      end
+    end
+
+    private
+
+    def api_url
+      ENV["AFRICAS_TALKING_SANDBOX"] ? SANDBOX_URL : URL
+    end
+  end
+end

data/lib/aftalk/exceptions.rb

@@ -0,0 +1,5 @@
+module AfTalk
+  class Error < StandardError; end
+  class NoApiKeyError < Error; end
+  class ResponseFormatError < Error; end
+end

data/lib/aftalk/request.rb

@@ -0,0 +1,41 @@
+module AfTalk
+  class Request
+    def self.get(path, **options)
+      new.get(path, options)
+    end
+
+    def self.post(path, **options)
+      new.post(path, options)
+    end
+
+    def get(path, **options)
+      connection.get(complete_path(path), complete_options(options))
+    end
+
+    def post(path, **options)
+      connection.post(complete_path(path), complete_options(options))
+    end
+
+    private
+
+    def complete_options(options)
+      default_options.merge(options)
+    end
+
+    def complete_path(path)
+      "/#{configuration.version}#{path}"
+    end
+
+    def configuration
+      AfTalk::Configuration
+    end
+
+    def connection
+      AfTalk::Connection.build
+    end
+
+    def default_options
+      { username: configuration.user_name }
+    end
+  end
+end

data/lib/aftalk/response.rb

@@ -0,0 +1,26 @@
+module AfTalk
+  class Response
+    SUCCESS_STATUSES = [200, 201].freeze
+    JSON_CONTENT = /\bjson$/
+
+    attr_reader :body, :error_message, :status
+
+    def initialize(response)
+      @status = response.status
+      body = response.body
+
+      if success?
+        @body = body
+      else
+        @error_message = body
+        @body = { error: body }
+      end
+    end
+
+    private
+
+    def success?
+      SUCCESS_STATUSES.include?(status)
+    end
+  end
+end

data/lib/aftalk/responses/send_message_response.rb

@@ -0,0 +1,21 @@
+module AfTalk
+  class SendMessageResponse < Response
+    attr_reader :message, :recipients
+
+    def initialize(response)
+      super(response)
+      if success?
+        @message = body_data[:Message]
+        @recipients = body_data[:Recipients].map do |recipient|
+          SmsMessageStatus.new(recipient)
+        end
+      end
+    end
+
+    private
+
+    def body_data
+      body[:SMSMessageData]
+    end
+  end
+end

data/lib/aftalk/sms_message_status.rb

@@ -0,0 +1,12 @@
+module AfTalk
+  class SmsMessageStatus
+    attr_reader :cost, :message_id, :number, :status
+
+    def initialize(opts = {})
+      @cost = opts[:cost]
+      @message_id = opts[:messageId]
+      @number = opts[:number]
+      @status = opts[:status]
+    end
+  end
+end

data/lib/aftalk/version.rb

@@ -0,0 +1,3 @@
+module AfTalk
+  VERSION = "0.1.0".freeze
+end

data/spec/aftalk_spec.rb

@@ -0,0 +1,7 @@
+require "spec_helper"
+
+describe AfTalk do
+  it "is a module" do
+    expect(described_class).to be_a_kind_of(Module)
+  end
+end

data/spec/integration/send_message_spec.rb

@@ -0,0 +1,25 @@
+require "spec_helper"
+
+describe AfTalk do
+  describe "#send_message" do
+    let(:options) do
+      { to: "+14125554563", message: "Hello World!", foo: "bar" }
+    end
+
+    it "produces a send message response object" do
+      VCR.use_cassette("aftalk/messaging/send_message") do
+        response = described_class.send_message(options)
+        recipient = response.recipients.first
+
+        expect(response.error_message).to be_nil
+        expect(response.status).to eq(201)
+        expect(response.message).to be
+
+        expect(recipient.cost).to be
+        expect(recipient.message_id).to be
+        expect(recipient.number).to eq(options[:to])
+        expect(recipient.status).to eq("Success")
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+require "rspec"
+require "aftalk"
+require "vcr"
+
+current_path = File.expand_path("../", __FILE__)
+Dir["#{current_path}/support/**/*.rb"].each { |file| require file }
+
+VCR.configure do |config|
+  config.cassette_library_dir = "spec/support/vcr_cassettes"
+  config.hook_into :faraday
+  config.configure_rspec_metadata!
+  config.allow_http_connections_when_no_cassette = false
+  config.default_cassette_options = { record: :new_episodes }
+end
+
+RSpec.configure do |config|
+  config.before :each do
+    AfTalk::Connection.clear
+  end
+end

data/spec/support/env_vars.rb

@@ -0,0 +1,13 @@
+module EnvVars
+  def stub_env_vars(vars)
+    allow(ENV).to receive(:[]).and_call_original
+
+    vars.each do |key, val|
+      allow(ENV).to receive(:[]).with(key).and_return(val)
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include EnvVars
+end

data/spec/unit/client_spec.rb

@@ -0,0 +1,46 @@
+require "spec_helper"
+
+describe AfTalk::Client do
+  subject do
+    class ExampleKlass
+      extend AfTalk::Client
+    end
+    ExampleKlass
+  end
+
+  before(:all) { reset_config }
+
+  describe "#send_message" do
+    let(:options) {
+      { to: "+14125554563", message: "Hello World!", foo: "bar" }
+    }
+    let(:response) { double(headers: { "content-type" => "application/json" }) }
+
+    context "with all required options" do
+      it "it instantiates a send message response" do
+        allow(AfTalk::Request).to receive(:post).
+          with("/messaging", options).
+          and_return(response)
+        allow(AfTalk::SendMessageResponse).to receive(:new).with(response)
+
+        subject.send_message(options)
+
+        expect(AfTalk::SendMessageResponse).to have_received(:new).with(response)
+      end
+    end
+
+    context "without some required options" do
+      let(:options) { {} }
+
+      it "raises a missing options error" do
+        expect { subject.send_message(options) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+
+  def reset_config
+    config = AfTalk::Configuration
+    config.api_key = nil
+    config.user_name = nil
+  end
+end