essential 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7fef856a4598b665b03c68baaf34c34eb79a8d8d
+  data.tar.gz: 81c1e44539dfbe8b6dc59dd7f61165640247a2a7
+SHA512:
+  metadata.gz: 2f81a83c772e1190736131d8c99444538b1451b2ce609625e4528474584e992eb78f9d2cb45ab0067ddedb15e3a8dafede902da1c3233cba1db48b0c3233d803
+  data.tar.gz: 061610d3b785a2d8ee7d9dffa12605b93c9da1a59c6401b6668a170f420c534727a2480e3519b175450272160a3fe47d4f3c9e057003213572a11e5cd37da373

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    essential (0.1.0)
+      rest-client (~> 1.8)
+
+GEM
+  remote: http://www.rubygems.org/
+  specs:
+    domain_name (0.5.20160128)
+      unf (>= 0.0.5, < 1.0.0)
+    http-cookie (1.0.2)
+      domain_name (~> 0.5)
+    mime-types (2.99.1)
+    minitest (5.8.4)
+    netrc (0.11.0)
+    rake (10.5.0)
+    rest-client (1.8.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  essential!
+  minitest (~> 5.8.4)
+  rake
+
+BUNDLED WITH
+   1.11.2

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2016- Essential Platform Services, Inc. (https://essential.to)
+
+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,107 @@
+# essential-ruby
+
+## Quick Start
+
+```ruby
+require 'essential'
+
+Essential.sid = ENV['ESSENTIAL_SID']
+Essential.token = ENV['ESSENTIAL_TOKEN']
+
+default_channel = Essential::Messaging::Channel.list.first
+
+message = default_channel.messages.create(
+  subscriber: '2065551212',
+  body: "Hello there."
+)
+puts message.sid
+
+```
+
+## Usage
+
+### Initial Setup
+
+```ruby
+require 'essential'
+# Essential.api_base = 'http://127.0.0.1:3000'
+Essential.sid = ENV['ESSENTIAL_SID']
+Essential.token = ENV['ESSENTIAL_TOKEN']
+
+```
+
+### Account
+
+```ruby
+account = Essential::Account.retrieve
+```
+
+### Channels
+
+```ruby
+account.channels.map{|ch| {ch.sid => ch.name}}.reduce(&:merge)
+# => {"ch_p03Gjl8Uzn0RkZSpHXHnrw"=>"default", "ch_QsbrYCSo2m0sShMLOlZqtw"=>"yradnoces"}
+channel = Essential::Messaging::Channel.retrieve('ch_p03Gjl8Uzn0RkZSpHXHnrw')
+channel.update(name: 'default', onreceived_url: 'http:/api.example.com/hook')
+```
+
+### Subscribers
+
+```ruby
+channel = Essential::Messaging::Channel.list.first
+
+# create a subscriber
+subscriber = channel.subscribers.create(phone_number: '2065551212')
+puts subscriber.sid
+# => sub_WfnIr-f-7FBMFr4nVKkMdg
+
+# unsubscribe
+subscriber.unsubscribe
+
+# re-subscribe
+subscriber = channel.subscribers.create(phone_number: '2065551212')
+puts subscriber.sid
+# => sub_WfnIr-f-7FBMFr4nVKkMdg
+```
+
+### Messages
+
+```ruby
+# This example magically finds the correct channel
+# by either using an existing subscriber, or falling
+# back on the channel named 'default'.
+message = Essential::Messaging::Message.create(
+  subscriber: '2065551212',
+  body: 'magic channel'
+)
+
+# Here we specify a subscriber explicitly
+message = Essential::Messaging::Message.create(
+  subscriber: 'sub_pDTv7LSV-R-AzL7oEpBfoQ',
+  body: 'subscriber by sid'
+)
+
+# Here we specify a channel
+message = Essential::Messaging::Message.create(
+  subscriber: '2065551212',
+  channel: 'yradnoces',
+  body: 'explicit channel'
+)
+```
+
+### Properties
+
+```ruby
+subscriber = channel.subscribers.create(phone_number: '2065551212')
+
+# set new properties
+subscriber.properties.create(name: 'external_id', value: 1234)
+subscriber.properties.create(name: 'name', value: 'Brendan Ribera')
+subscriber.properties.create(name: 'state', value: 'WA')
+
+# print them
+puts JSON.pretty_generate(subscriber.properties.as_json)
+
+# update one
+subscriber.properties.create(name: 'name', value: 'Nabnerb Arebir')
+```

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = "test/**/*_test.rb"
+end

data/essential.gemspec

@@ -0,0 +1,26 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+require 'essential/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'essential'
+  s.version     = Essential::VERSION
+  s.date        = '2016-04-06'
+  s.summary     = 'Essential Ruby Library'
+  s.description = 'A GEM for interacting with the Essential.to service.'
+  s.authors     = ['Brendan Ribera']
+  s.email       = 'brendan@madronavl.com'
+  s.homepage    = 'http://github.com/madrona-labs/essential-ruby'
+  s.license     = 'MIT'
+
+  s.add_dependency('rest-client', '~> 1.8')
+
+  s.add_development_dependency('rake', '~> 10.5')
+  s.add_development_dependency('minitest', '~> 5.8')
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+  # s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+
+  s.require_paths = ['lib']
+end

data/lib/essential.rb

@@ -0,0 +1,32 @@
+require 'json'
+require 'rest-client'
+require 'set'
+require 'uri'
+
+require 'essential/version'
+require 'essential/client'
+
+# Resources
+require 'essential/resource'
+require 'essential/resource/paginator_proxy'
+
+# Top-level Resources
+require 'essential/account'
+
+# Messaging Resources
+require 'essential/messaging/message'
+require 'essential/messaging/property'
+require 'essential/messaging/transport'
+require 'essential/messaging/subscriber'
+require 'essential/messaging/channel'
+
+module Essential
+  @api_base = 'https://api.essential.to'
+  @utc_offset = nil
+
+  class << self
+    attr_accessor :api_base, :sid, :token, :utc_offset
+  end
+
+  include Client
+end

data/lib/essential/account.rb

@@ -0,0 +1,56 @@
+module Essential
+  class Account < Resource
+    include Essential::Resource::Update
+
+    attr_property :name, :token, :unsubscribed_send_raises, :created_at, :updated_at
+    attr_schema created_at: Time, updated_at: Time
+
+    def self.retrieve(opts={}, headers: {})
+      me = self.new(headers: headers)
+      me.fetch
+      me
+    end
+
+    def self.url
+      "/v2/account"
+    end
+
+    def self.api_status(params: {}, headers: @headers)
+      # permitted:
+      # :start_date, :end_date
+      resp = self.request(
+        :get,
+        url: '/v2/account/analytics/api_status',
+        params: params,
+        headers: headers
+      )
+      JSON.parse(resp)
+    end
+
+    def initialize(sid: nil, headers: nil)
+      sid ||= Essential.sid
+
+      super(sid: sid, headers: headers)
+    end
+
+    def url
+      self.class.url
+    end
+
+    def channels
+      Essential::Resource::PaginatorProxy.new(Essential::Messaging::Channel, headers: @headers)
+    end
+
+    def subscribers
+      Essential::Resource::PaginatorProxy.new(Essential::Messaging::Subscriber, headers: @headers)
+    end
+
+    def transports
+      Essential::Resource::PaginatorProxy.new(Essential::Messaging::Transport, headers: @headers)
+    end
+
+    def messages
+      Essential::Resource::PaginatorProxy.new(Essential::Messaging::Message, headers: @headers)
+    end
+  end
+end

data/lib/essential/client.rb

@@ -0,0 +1,65 @@
+require 'essential/errors/api_error'
+
+module Essential
+  module Client
+    module ClassMethods
+      def request(method, url, sid: nil, token: nil, params: {}, headers: {})
+        # GET -> :get, etc
+        method = method.to_s.downcase.to_sym
+
+        sid   ||= self.sid
+        token ||= self.token
+
+        uri = URI.join(self. api_base, url)
+
+        headers = {
+          'Content-Type' => 'application/json',
+          'Accept'       => 'application/json',
+          'User-Agent'   => user_agent(),
+        }.merge(headers || {})
+
+        case method
+        when :get, :delete
+          uri.query = URI.encode_www_form(params) if params && params.any?
+        else
+          payload = params.to_json
+        end
+
+        opts = {
+          method: method,
+          url: uri.to_s,
+          user: sid,
+          password: token,
+          timeout: 10,      # TODO config
+          open_timeout: 10, # TODO: config
+          headers: headers,
+          payload: payload
+        }
+
+        if $debug
+          puts format('%s %s', method.to_s.upcase, uri)
+          puts format('opts: %s', JSON.pretty_generate(opts))
+        end
+
+        begin
+          response = RestClient::Request.execute(opts)
+        rescue StandardError => e
+          raise Essential::APIError.from_exception(e)
+        end
+
+        response
+      end
+
+      protected
+
+      def user_agent
+        format('Essential Ruby (%s)', Essential::VERSION)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+  end
+end

data/lib/essential/errors/api_error.rb

@@ -0,0 +1,54 @@
+module Essential
+  class APIError < StandardError
+    private_class_method :new
+
+    attr_reader :http_status, :body
+    attr_reader :type, :message, :code, :params
+
+    def self.from_exception(e)
+      case e
+      # when SocketError
+      # when NoMethodError
+      when RestClient::ExceptionWithResponse
+        new(
+          http_status: e.http_code,
+          body: e.http_body
+        )
+      when RestClient::Exception
+        new(http_status: e.http_code)
+      # when Errno::ECONNREFUSED
+      else
+        raise e
+      end
+    end
+
+    def initialize(http_status: nil, body: nil)
+      @http_status = http_status
+
+      if body
+        begin
+          @body = JSON.parse(body)
+          if @body.key?('error')
+            error    = @body['error']
+            @type    = error['type']
+            @message = error['message']
+            @code    = error['code']
+            @params  = error['params']
+          end
+        rescue JSON::ParserError
+          @body = body
+        end
+      end
+    end
+
+    def to_s
+      parts = []
+      parts << format('<%s>', self.http_status)
+      parts << self.type
+      parts << self.message if self.message
+      parts << self.params.to_json if self.params
+      parts.join(' - ')
+    end
+
+  end
+end

data/lib/essential/messaging/channel.rb

@@ -0,0 +1,36 @@
+module Essential::Messaging
+  class Channel < Essential::Resource
+    extend Essential::Resource::List
+    include Essential::Resource::Update
+
+    attr_property :name, :onreceived_url, :created_at, :updated_at
+    attr_schema created_at: Time, updated_at: Time
+
+    attr_relation account_sid: 'Essential::Account'
+
+    def transports
+      Essential::Resource::PaginatorProxy.new(
+        Transport,
+        params: {channel: self.sid},
+        headers: @headers
+      )
+    end
+
+    def subscribers
+      Essential::Resource::PaginatorProxy.new(
+        Subscriber,
+        params: {channel: self.sid},
+        headers: @headers
+      )
+    end
+
+    def messages
+      Essential::Resource::PaginatorProxy.new(
+        Message,
+        params: {channel: self.sid},
+        headers: @headers
+      )
+    end
+
+  end
+end