gemagent 0.0.1.pre

data/CONTRIBUTORS

@@ -0,0 +1 @@
+Ryan Stenhouse <ryan@ryanstenhouse.eu>

data/HACKING

@@ -0,0 +1,8 @@
+The process for accepting patches is as follows:
+
+1. Fork the repository
+2. Make your changes (bonus points for feature branches)
+3. Have some tests for your changes
+4. Submit a pull request
+
+Do not change the version number in the GemSpec.

data/LICENCE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Ryan Stenhouse and CONTRIBUTORS
+
+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,43 @@
+Gemagent
+========
+
+By Ryan Stenhouse http://ryanstenhouse.eu 
+
+What is it?
+-----------
+
+Gemagent is a purely Standard Ruby implementation of a consumer of 
+the FreeAgent Central API.
+
+The goal of this project was not to build a 'fast' API consumer, but
+instead to build a 'correct' one. All published API features of the
+FreeAgent application are implemented.
+
+If it's fast, it's a bonus!
+
+Installation
+------------
+
+Install via rubygems:
+
+    $  gem install gemagent
+
+It requires OpenSSL in order to create the HTTPS connection to the
+FreeAgent API.
+
+Extension
+---------
+
+The main purpose of this gem was to allow me to become more familiar 
+with the FreeAgent API and to shake out some cobwebs when it came to
+my knowledge of Ruby's Standard Library.
+
+Because of this, some parts (like local data storage) are sub-optimal.
+
+I have, however, build some abstraction on top of the data storage, 
+HTTP requests and XML parsing to allow for some or all of these
+components to be replaced at a later date. 
+
+See the documentation online for more information.
+
+

data/example/example.rb

@@ -0,0 +1,13 @@
+# GemAgent API Interface
+# Ryan Stenhouse, 20 January 2011
+
+# Longhand representation of connecting to the FreeAgent API
+#
+ga = GemAgent::NetHttpConnection.new 'you.freeagentcentral.com', GemAgent::HttpBasicAuthentication.new('username','password')
+ga.verify # => { :user_id => 1, :permission_level => 8, :company_type => UK_LIMITED }
+
+# Sexy sugary version of the above.
+#
+GemAgent::Api.connect 'you.freeagentcentral.com', 'username', 'password' do |api|
+  api.verify # => { :user_id => 1, :permission_level => 8, :company_type => UK_LIMITED }
+end

data/gemagent.gemspec

@@ -0,0 +1,25 @@
+summary = "GemAgent is a clean and light way to interact with the FreeAgent API. " 
+description = <<-TXT
+  GemAgent lets users of FreeAgent Central's online accounting software
+  to interact with the API simply and cleanly by only using functionality
+  provided by Ruby's Standard Library.
+TXT
+
+Gem::Specification.new do |spec|
+  spec.name = "gemagent"
+  spec.version = '0.0.1.pre'
+  spec.platform = Gem::Platform::RUBY
+  spec.files =  Dir.glob("{bin,lib,.}/**/**/*") +
+                      ["gemagent.rb","README.md","HACKING",'LICENCE','CONTRIBUTORS', "gemagent.gemspec"]
+  spec.require_path = "lib"
+  spec.required_ruby_version = '>= 1.8.4'
+  spec.required_rubygems_version = ">= 1.3.0"
+  spec.test_files = Dir[ "test/*_test.rb" ]
+  spec.has_rdoc = false
+  spec.author = "Ryan Stenhouse"
+  spec.email = "ryan@ryanstenhouse.eu"
+  spec.rubyforge_project = "gemagemt"  
+  spec.homepage = "http://ryanstenhouse.eu"
+  spec.summary = summary
+  spec.description = description
+end

data/gemagent.rb

@@ -0,0 +1,8 @@
+GEMAGENT_ROOT = File.expand_path(File.dirname(__FILE__))
+require GEMAGENT_ROOT + '/lib/connection.rb'
+require GEMAGENT_ROOT + '/lib/authentication.rb'
+require GEMAGENT_ROOT + '/lib/api_classes.rb'
+require GEMAGENT_ROOT + '/lib/api_handler.rb'
+
+module GemAgent
+end

data/lib/api_classes.rb

@@ -0,0 +1,36 @@
+require "rexml/document"
+
+module GemAgent
+  module Api
+    
+    def self.connect(freeagent_url, username, password, connection = GemAgent::NetHttpConnection, 
+                                                        authenticator = GemAgent::HttpBasicAuthentication, 
+                                                        api_version = GemAgent::ApiHandler)
+      if !block_given?
+        raise "I need to have a block" and return
+      end
+      api = connection.new(freeagent_url, authenticator.new(username, password), api_version)
+      yield api
+    end
+    
+    class ApiBase
+      def method
+        'GET'
+      end
+    
+      def path
+      end
+      
+      def expected_status
+        '200'
+      end
+      
+    end
+  
+    class Verify < ApiBase
+      def path 
+        '/verify'
+      end
+    end  
+  end
+end

data/lib/api_handler.rb

@@ -0,0 +1,28 @@
+require File.dirname(__FILE__) + '/api_classes.rb'
+module GemAgent
+  class ApiHandler
+    
+    def initialize(connection)
+      @connection = connection
+    end
+    
+    def verify
+      verify = GemAgent::Api::Verify.new
+      response = @connection.send_request(verify)
+      unless response.has_error?
+        {
+          :company_type     => response.headers['company-type'],
+          :user_id          => response.headers['user-id'].to_i,
+          :permission_level => response.headers['user-permission-level'].to_i
+        }
+      else
+        {
+          :error          => response.headers[:error],
+          :body           => response.body,
+          :company_type   => 'ERROR'
+        }
+      end
+    end
+    
+  end
+end

data/lib/authentication.rb

@@ -0,0 +1,23 @@
+module GemAgent
+  class ApiAuthentication
+    def authenticate_for(obj)
+    end
+  end
+  
+  class HttpBasicAuthentication < ApiAuthentication
+    
+    def initialize(username, password)
+      @username = username
+      @password = password
+    end
+    
+    def authenticate_for(obj)
+      if obj.respond_to?(:basic_auth)
+        obj.basic_auth @username, @password
+      else
+        raise "Can't do basic authentication with this, I expect a NetHTTP request"
+      end
+    end
+    
+  end
+end

data/lib/connection.rb

@@ -0,0 +1,116 @@
+require 'net/https'
+require 'uri'
+  
+module GemAgent
+  
+  # ConnectionMethod implements the basic interface all child 
+  # classes must implement to allow connection to the FreeAgent
+  # API.
+  #
+  class ConnectionMethod
+    
+    attr_reader :freeagent_url
+    attr_reader :api
+    attr_reader :authenticator
+    
+    @@method_map = {}
+    
+    def initialize(freeagent_url, authenticator, api_handler = GemAgent::ApiHandler)
+      @freeagent_url = freeagent_url
+      @authenticator = authenticator
+      @api = api_handler.new(self)
+    end
+    
+    def send_request(request)
+      raise "Subclasses of ConnectionMethod must implement their own send_request method"
+    end
+    
+    def wrap_response(response)
+      raise "Subclasses of ConnectionMethod must implement their own wrap_response method"
+    end
+    
+    # Proxies all undefined method to the API handler
+    # associated with the connection.
+    #
+    def method_missing(method, *args)
+      unless args.empty?
+        @api.send(method, args)
+      else
+        @api.send(method) 
+      end
+    end
+  end
+  
+  # The ResponseWrapper is used to present a consistant way
+  # for the various API classes to process messages returned
+  # by the API server.
+  #
+  # If you write your own ConnectionMethod subclass, ensure that
+  # your send_request method returns a ResponseWrapper correctly
+  # set with the correct values for headers and body.
+  #
+  class ResponseWrapper 
+    attr_reader :headers, :body
+    def initialize(headers, body)
+      @headers = headers
+      @body = body
+    end
+    
+    def has_error?
+      !headers[:error].nil?
+    end
+  end
+  
+  # NetHttpConnection is the default method to connect to the
+  # FreeAgent API. It uses the Standard  Ruby library net/http
+  # to create an SSL connection to the FreeAgent server specified
+  # by +@freeagent_url+ and authenticates your request with the
+  # ApiAuthentication subclass you pass thorugh as +authenticator+.
+  #
+  # The last last optional value takes a API Handler class, which
+  # defaults to the standard one which ships with this gem.
+  #
+  class NetHttpConnection < ConnectionMethod
+    
+    @@method_map =  {
+                      'GET'     =>  Net::HTTP::Get,
+                      'POST'    =>  Net::HTTP::Post,
+                      'PUT'     =>  Net::HTTP::Put,
+                      'DELETE'  =>  Net::HTTP::Delete
+                    }
+                    
+    # Sends the +request+ to +@freeagent_url+ over HTTPS. The class
+    # instance variable +@@method_map+ maps each HTTP verb required
+    # to the correct class for instantiation.
+    #                
+    def send_request(request)
+      https = Net::HTTP.new(@freeagent_url, Net::HTTP.https_default_port) 
+      https.use_ssl = true
+      https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      req = @@method_map[request.method].new(request.path)
+      req['content-type'] = 'application/xml'
+      req['accept'] = 'application/xml'
+      authenticator.authenticate_for req
+      resp = nil
+      https.start do |http|
+        resp = http.request(req)
+      end
+      if resp.code == request.expected_status
+        wrap_response(resp)
+      else
+        ResponseWrapper.new({ :error => resp.code, :status => resp.code }, resp.body)
+      end
+    end
+    
+    # Wraps the response from net/http in a ResponseWrapper object
+    # so the API classes are able to work with it to do their work.
+    #
+    def wrap_response(response)
+      headers = {}
+      response.each_header { |k,v| headers[k] = v }
+      ResponseWrapper.new(headers, response.body)
+    end
+    
+  end
+    
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification 
+name: gemagent
+version: !ruby/object:Gem::Version 
+  hash: 961915968
+  prerelease: 6
+  segments: 
+  - 0
+  - 0
+  - 1
+  - pre
+  version: 0.0.1.pre
+platform: ruby
+authors: 
+- Ryan Stenhouse
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-29 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: "  GemAgent lets users of FreeAgent Central's online accounting software\n  to interact with the API simply and cleanly by only using functionality\n  provided by Ruby's Standard Library.\n"
+email: ryan@ryanstenhouse.eu
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/api_classes.rb
+- lib/api_handler.rb
+- lib/authentication.rb
+- lib/connection.rb
+- ./CONTRIBUTORS
+- ./example/example.rb
+- ./gemagent.gemspec
+- ./gemagent.rb
+- ./HACKING
+- ./lib/api_classes.rb
+- ./lib/api_handler.rb
+- ./lib/authentication.rb
+- ./lib/connection.rb
+- ./LICENCE
+- ./README.md
+- gemagent.rb
+- README.md
+- HACKING
+- LICENCE
+- CONTRIBUTORS
+- gemagent.gemspec
+has_rdoc: true
+homepage: http://ryanstenhouse.eu
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 63
+      segments: 
+      - 1
+      - 8
+      - 4
+      version: 1.8.4
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 27
+      segments: 
+      - 1
+      - 3
+      - 0
+      version: 1.3.0
+requirements: []
+
+rubyforge_project: gemagemt
+rubygems_version: 1.6.1
+signing_key: 
+specification_version: 3
+summary: GemAgent is a clean and light way to interact with the FreeAgent API.
+test_files: []
+