xednese 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 381d98d8d9e52c8f4ad3136d50780e79eca43d75
-  data.tar.gz: a3e8b964f56061bafe0ce6bc8401f92d3f557f58
+  metadata.gz: 847dade493b0ea06b341f02631f96df1fb5b9ba8
+  data.tar.gz: b5993ebab4f9baf48c75d71bf78599d8ad65dc27
 SHA512:
-  metadata.gz: efb4d2396b366aa322791529f947d6b2409ea1c98323b8cbdb138dadc368f962c0b029a871e572ef6540d387a245891c771ddc833c842887f69c6876be73650f
-  data.tar.gz: 87d1652e6ed3033da2e2ba1df223d3e82ed52b7259d3fefa73a97b98ca4bf0625ffa03e7a18eef58174452df8e989f5f7138be7caa24adc158bea47d4866d1df
+  metadata.gz: 3b92a2320ed4c2fe49c93df492ecdbb00b72fc483c82a6eaf2d6b569a1fbf43e6bd659443510d62ed18c29492b6c99bd8e390a86a98ec4da1caa8125d0cd8395
+  data.tar.gz: 5cb5ade70cee76dcb0d52074f75d52607490fb4b6ce4519972d790c1622d6a6677c0d2ab2c16c52defe5a29261323c7aad67cee9cf5abc4b96d3d593aaa07f72

data/Gemfile

@@ -1,9 +1,10 @@
 source 'https://rubygems.org'
 
 gem 'seq', '~> 0.2.0'
-gem 'serialisable', '~> 0.0.0'
+gem 'serialisable', '~> 0.1.0'
 gem 'nokogiri', '~> 1.6'
 
 gem 'rake', '~> 10.1'
 gem 'minitest', '~> 5.2'
 gem 'mocha', '~> 1.0'
+gem 'webmock', '~> 1.17'

data/README.md

@@ -3,11 +3,30 @@
 ``` ruby
 require 'xednese'
 
-esendex = Esendex.new('me@company.com', 'password', 'account reference')
-p esendex.messages.sent.first.body
+esendex = Esendex.new('me@company.com', 'password')
+p esendex.messages.sent.first.summary
 #=> "..."
 
-response = esendex.dispatcher.send('Hey guys', '445275XXX')
+account = esendex.account("EX0000")
+response = account.dispatcher.send('Hey guys', '445275XXX')
 p response.message_headers.map(&:id)
 #=> ["..."]
 ```
+
+Xednese is a client library for interacting with the
+[Esendex REST API][exapi]. It is currently under active development and should
+not be considered stable enough for general use.
+
+
+## Running locally
+
+Clone the repo, then to get the run the tests:
+
+``` bash
+$ gen install bundler
+$ bundle install
+$ bundle exec rake
+...
+```
+
+[exapi]: developers.esendex.com/APIs/REST-API/

data/Rakefile

@@ -1,9 +1,15 @@
 require 'rake/testtask'
 
-Rake::TestTask.new(:test) do |t|
+Rake::TestTask.new(:spec) do |t|
   t.libs << 'lib' << 'spec'
   t.pattern = 'spec/**/*_spec.rb'
   t.verbose = true
 end
 
-task :default => :test
+Rake::TestTask.new(:acceptance) do |t|
+  t.libs << 'lib' << 'scenarios'
+  t.pattern = 'scenarios/*/*.rb'
+  t.verbose = true
+end
+
+task :default => [:spec, :acceptance]

data/bin/xednese

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+require 'xednese'
+require 'pry'
+
+if ARGV.size != 2
+  abort "Usage: xednese <username> <password>"
+end
+
+esendex = Esendex.new(ARGV.first, ARGV.last)
+
+puts <<EOS
+xednese: Call methods on 'esendex'; CTRL-D to exit.
+EOS
+
+binding.pry quiet: true, prompt: Pry::SIMPLE_PROMPT

data/lib/xednese.rb

@@ -1,3 +1,4 @@
+require 'forwardable'
 require 'net/http'
 require 'nokogiri'
 require 'seq/paged'
@@ -7,39 +8,65 @@ require 'time'
 require_relative 'xednese/version'
 require_relative 'xednese/client'
 
+require_relative 'xednese/requests/account'
+require_relative 'xednese/requests/batch'
 require_relative 'xednese/requests/messages'
 
 require_relative 'xednese/responses/parser'
 require_relative 'xednese/responses/account'
 require_relative 'xednese/responses/accounts'
+require_relative 'xednese/responses/status'
+require_relative 'xednese/responses/batch'
+require_relative 'xednese/responses/batches'
 require_relative 'xednese/responses/message_dispatcher_headers'
 require_relative 'xednese/responses/message_header'
 require_relative 'xednese/responses/message_headers'
 
+require_relative 'xednese/account'
 require_relative 'xednese/accounts'
-require_relative 'xednese/dispatcher'
+require_relative 'xednese/batch'
+require_relative 'xednese/batches'
 require_relative 'xednese/messages'
 require_relative 'xednese/users'
 
+require_relative 'xednese/account/dispatcher'
+require_relative 'xednese/account/messages'
+
 class Esendex
-  Credentials = Struct.new(:username, :password, :account_reference)
+  Credentials = Struct.new(:username, :password)
 
-  def initialize(username, password, account_reference)
-    @credentials = Credentials.new(username, password, account_reference)
+  # @param username [String]
+  # @param password [String]
+  def initialize(username, password)
+    @credentials = Credentials.new(username, password)
   end
 
-  def account
-    Accounts.new(@credentials)
+  # @param reference [String]
+  # @return [Account]
+  # @see http://developers.esendex.com/APIs/REST-API/accounts
+  def account(reference)
+    accounts.find {|a| a.reference == reference }
   end
 
-  def dispatcher
-    Dispatcher.new(@credentials)
+  # @return [Accounts]
+  # @see http://developers.esendex.com/APIs/REST-API/accounts
+  def accounts
+    Accounts.new(@credentials)
   end
 
-  def user
+  # @return [Users]
+  def users
     Users.new(@credentials)
   end
 
+  # @return [Batches]
+  # @see http://developers.esendex.com/APIs/REST-API/messagebatches
+  def batches
+    Batches.new(@credentials)
+  end
+
+  # @return [Messages]
+  # @see http://developers.esendex.com/APIs/REST-API/messageheaders
   def messages
     Messages.new(@credentials)
   end

data/lib/xednese/account.rb

@@ -0,0 +1,37 @@
+class Esendex
+
+  class Account
+    def initialize(credentials, response)
+      @credentials = credentials
+      @response = response
+    end
+
+    # @return [Dispatcher]
+    # @see http://developers.esendex.com/APIs/REST-API/messagedispatcher
+    def dispatcher
+      Dispatcher.new(@credentials, reference)
+    end
+
+    # @return [Messages]
+    def messages
+      Messages.new(@credentials, reference)
+    end
+
+    extend Forwardable
+
+    def_delegators :@response, :id, :reference, :address, :type,
+                   :messages_remaining, :expires_on, :role
+
+    def label
+      @label || @response.label
+    end
+
+    def label=(value)
+      request = Requests::Account.new(label: value)
+
+      Client.put(@credentials, "v1.0/accounts/#{id}", request) do |code, body|
+        @label = value
+      end
+    end
+  end
+end

data/lib/xednese/account/dispatcher.rb

@@ -0,0 +1,30 @@
+class Esendex
+  class Account
+    class Dispatcher
+
+      # @see Esendex::Account#dispatcher
+      # @api private
+      def initialize(credentials, reference)
+        @credentials = credentials
+        @reference = reference
+      end
+
+      # Sends a message to a single recipient.
+      # @param body [String] the message body
+      # @param to [String] the number to send to
+      # @return [Responses::MessageDispatcherHeaders]
+      def send(body, to)
+        args = {
+          account_reference: @reference,
+          messages: [{to: to, body: body}]
+        }
+
+        messages = Requests::Messages.new(args)
+
+        Client.post(@credentials, 'v1.0/messagedispatcher', messages) do |code, body|
+          Responses::MessageDispatcherHeaders.deserialise(body)
+        end
+      end
+    end
+  end
+end

data/lib/xednese/account/messages.rb

@@ -0,0 +1,47 @@
+class Esendex
+  class Account
+    class Messages
+      PAGE_COUNT = 25
+
+      # @see Esendex::Account#messages
+      # @api private
+      def initialize(credentials, reference)
+        @credentials = credentials
+        @reference = reference
+      end
+
+      # @return [Enumerable<Responses::MessageHeader>] an Enumerable that
+      #   iterates over all sent messages. Requests are made for fixed size
+      #   pages when required.
+      def sent
+        Seq::Paged.new do |page|
+          params = {
+            startIndex: PAGE_COUNT * page,
+            count: PAGE_COUNT,
+            accountReference: @reference
+          }
+
+          Client.get(@credentials, 'v1.0/messageheaders', params) do |status, data|
+            Responses::MessageHeaders.deserialise(data).message_headers
+          end
+        end
+      end
+
+      # @return [Enumerable<Responses::MessageHeader>] an Enumerable that
+      #   iterates over all received messages. Requests are made for fixed size
+      #   pages when required.
+      def received
+        Seq::Paged.new do |page|
+          params = {
+            startIndex: PAGE_COUNT * page,
+            count: PAGE_COUNT
+          }
+
+          Client.get(@credentials, "v1.0/inbox/#{@reference}/messages", params) do |status, data|
+            Responses::MessageHeaders.deserialise(data).message_headers
+          end
+        end
+      end
+    end
+  end
+end

data/lib/xednese/accounts.rb

@@ -1,24 +1,32 @@
 class Esendex
+
+  # Provides methods for working with Accounts. An Accounts instance is an
+  # Enumerable, and will only make requests when needed.
   class Accounts
+
+    # @see Esendex#accounts
+    # @api private
     def initialize(credentials)
       @credentials = credentials
     end
 
-    def reference
-      @credentials.account_reference
-    end
-
+    # @yield [Account] Calls the provided block with each account the user has
+    #   access to
     def each(&block)
       Client.get(@credentials, 'v1.0/accounts') {|status, data|
-        Responses::Accounts.deserialise(data).accounts
+        Responses::Accounts.deserialise(data).accounts.map do |account|
+          Account.new(@credentials, account)
+        end
       }.each(&block)
     end
 
     include Enumerable
 
+    # @param id [String] the id of the account to return
+    # @return [Account] Returns the account with the given id.
     def get(id)
       Client.get(@credentials, "v1.0/accounts/#{id}") do |status, data|
-        Responses::Account.deserialise(data)
+        Account.new @credentials, Responses::Account.deserialise(data)
       end
     end
   end

data/lib/xednese/batch.rb

@@ -0,0 +1,68 @@
+class Esendex
+  class Batch
+    PAGE_COUNT = 25
+
+    # @see Esendex#batches
+    # @api private
+    def initialize(credentials, response)
+      @credentials = credentials
+      @response = response
+    end
+
+    extend Forwardable
+
+    def_delegators :@response, :id, :created_at, :batch_size,
+                   :persisted_batch_size, :account_reference, :created_by
+
+    def status
+      s = @response.status
+
+      [:acknowledged,
+       :authorisation_failed,
+       :connecting,
+       :delivered,
+       :failed,
+       :partially_delivered,
+       :rejected,
+       :scheduled,
+       :sent,
+       :submitted,
+       :validity_period_expired,
+       :cancelled].find do |type|
+        s.send(type) == 1
+      end
+    end
+
+    def name
+      @name || @response.name
+    end
+
+    def name=(value)
+      request = Requests::Batch.new(name: value)
+
+      Client.put(@credentials, "v1.1/messagebatches/#{id}", request) do |status, data|
+        @name = value
+      end
+    end
+
+    def cancel!
+      Client.delete(@credentials, "v1.1/messagebatches/#{id}/schedule")
+    end
+
+    # @return [Enumerable<Responses::MessageHeader>] an Enumerable that iterates
+    #   over all messages in the batch. Requests are made for fixed size pages
+    #   when required.
+    def messages
+      Seq::Paged.new do |page|
+        params = {
+          startIndex: PAGE_COUNT * page,
+          count: PAGE_COUNT
+        }
+
+        Client.get(@credentials, "v1.0/messagebatches/#{id}/messages", params) do |status, data|
+          Responses::MessageHeaders.deserialise(data).message_headers
+        end
+      end
+    end
+  end
+end

data/lib/xednese/batches.rb

@@ -0,0 +1,33 @@
+class Esendex
+
+  # Provides methods for working with message batches. A Batches instance is
+  # Enumerable, and will only make requests when needed.
+  class Batches
+
+    # @see Esendex#batches
+    # @api private
+    def initialize(credentials)
+      @credentials = credentials
+    end
+
+    # @yield [Batch] Calls the provided block with each batch the user has
+    # access to
+    def each(&block)
+      Client.get(@credentials, 'v1.1/messagebatches') {|status, data|
+        Responses::Batches.deserialise(data).batches.map do |batch|
+          Batch.new(@credentials, batch)
+        end
+      }.each(&block)
+    end
+
+    include Enumerable
+
+    # @param id [String] the id of the batch to return
+    # @return [Batch] Returns the batch with the given id.
+    def get(id)
+      Client.get(@credentials, "v1.1/messagebatches/#{id}") do |status, data|
+        Batch.new @credentials, Responses::Batch.deserialise(data)
+      end
+    end
+  end
+end

data/lib/xednese/client.rb

@@ -1,9 +1,18 @@
 class Esendex
+
+  # Client is a wrapper for Net::HTTP for calling through to the Esendex REST
+  # API.
   class Client
     ROOT = URI('https://api.esendex.com/')
     USER_AGENT = "ruby/xednese-#{VERSION}"
     CONTENT_TYPE = "application/xml"
 
+    # @param credentials [Credentials]
+    # @param path [String] Path to GET (after the api.esendex.com/ part)
+    # @param args [Hash] An optional hash of query parameters to be appended to
+    #   the url.
+    #
+    # @return [Integer, String] Returns the status code and the response body.
     def self.get(credentials, path, args={})
       uri = url(path)
       uri.query = URI.encode_www_form(args)
@@ -14,6 +23,26 @@ class Esendex
       block_given? ? yield(code, body) : [code, body]
     end
 
+    # @param credentials [Credentials]
+    # @param path [String] Path to DELETE
+    #
+    # @return [Integer, String] Returns the status code and the response body.
+    def self.delete(credentials, path)
+      uri = url(path)
+      request = Net::HTTP::Delete.new(uri)
+
+      code, body = execute(credentials, request)
+
+      block_given? ? yield(code, body) : [code, body]
+    end
+
+    # @param credentials [Credentials]
+    # @param path [String] Path to POST to
+    # @param object [#serialise] The object that represents the content to be
+    #   posted. This must be an object with a method #serialise that returns a
+    #   string of xml.
+    #
+    # @return [Integer, String] Returns the status code and the response body.
     def self.post(credentials, path, object)
       request = Net::HTTP::Post.new(url(path))
       request.body = object.serialise
@@ -24,6 +53,23 @@ class Esendex
       block_given? ? yield(code, body) : [code, body]
     end
 
+    # @param credentials [Credentials]
+    # @param path [String] Path to PUT to
+    # @param object [#serialise] The object that represents the content to be
+    #   posted. This must be an object with a method #serialise that returns a
+    #   string of xml.
+    #
+    # @return [Integer, String] Returns the status code and the response body.
+    def self.put(credentials, path, object)
+      request = Net::HTTP::Put.new(url(path))
+      request.body = object.serialise
+      request.content_type = CONTENT_TYPE
+
+      code, body = execute(credentials, request)
+
+      block_given? ? yield(code, body) : [code, body]
+    end
+
     private
 
     def self.url(path)