sk-api 1.0.0

data/.gitignore

@@ -0,0 +1,3 @@
+nbproject/*
+coverage/*
+rdoc/*

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Georg Leciejewski
+
+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/Manifest

@@ -0,0 +1,30 @@
+MIT-LICENSE
+README.rdoc
+Rakefile
+init.rb
+lib/activeresource_patches/README
+lib/activeresource_patches/base.rb
+lib/activeresource_patches/validations.rb
+lib/resources/address.rb
+lib/resources/base.rb
+lib/resources/client.rb
+lib/resources/credit_note.rb
+lib/resources/line_item.rb
+lib/sk_api.rb
+lib/utils/field_map.rb
+lib/utils/serializer.rb
+lib/version.rb
+nbproject/private/private.properties
+nbproject/project.properties
+nbproject/project.xml
+spec/resources/client_spec.rb
+spec/resources/credit_note_spec.rb
+spec/spec_helper.rb
+spec/utils/field_map_spec.rb
+tasks/sk_api_tasks.rake
+vendor/jsonschema-1.0.0/README.rdoc
+vendor/jsonschema-1.0.0/Rakefile
+vendor/jsonschema-1.0.0/lib/jsonschema.rb
+vendor/jsonschema-1.0.0/ruby-jsonschema.gemspec
+vendor/jsonschema-1.0.0/test/jsonschema_test.rb
+Manifest

data/README.rdoc

@@ -0,0 +1,42 @@
+= SalesKing Api
+
+This plugin is used internally by SalesKing to deliver the API and 
+can be used externally as an API client.
+
+The SalesKing API client uses ActiveResource, ,with some little build in 
+fixes due to json parsing. For now it only supports JSON, XML comes later.
+
+To be able to use the API you must have an SalesKing account and API access. 
+Than you can start writing your own middelware-stack.
+
+== Upcomming
+
+The code is used in production, but still there is a lot to come, so if you 
+try to use it please tell us, so we can give you API access and support.
+
+With the rails 3.0 release we are going to pack this code as gem for 
+easier delivery & bundling
+
+== Example
+
+	client = SkApi::Resources::Client.new(:last_name=>'Eder')
+	client.first_name = "Meister"
+	client.save
+
+For more take a look into the specs.
+
+== Salesking API Resources
+
+Right now there are only two resources available: 
+
+* clients
+* credit_notes
+
+== Tests
+
+To run the test you must insert some credentials into the spec helper. 
+We will gladly provide you with a test account on one of our development 
+systems.
+
+
+Copyright (c) 2009, 2010 Georg Leciejewski, released under the MIT license

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sk-api"
+    gem.summary = %Q{Interact with SalesKing}
+    gem.description = %Q{Interact with SalesKing}
+    gem.email = "gl@salesking.eu"
+    gem.homepage = "http://github.com/salesking/sk-api"
+    gem.authors = ["Georg Leciejewski"]
+    gem.add_development_dependency "rspec", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+desc 'Default: run specs.'
+task :default => :spec
+
+spec_files = Rake::FileList["spec/**/*_spec.rb"]
+
+desc "Run specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = spec_files
+  t.spec_opts = ["-c"]
+end
+
+desc "Generate code coverage"
+Spec::Rake::SpecTask.new(:coverage) do |t|
+  t.spec_files = spec_files
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec,/var/lib/gems']
+end
+
+desc 'Generate sk-api documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SalesKing-Api'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/init.rb

@@ -0,0 +1 @@
+require "#{File.dirname(__FILE__)}/lib/sk_api"

data/lib/activeresource_patches/README

@@ -0,0 +1,3 @@
+Patches for activerecord as long as the 3.0 version is not out
+
+* parse error from json response

data/lib/activeresource_patches/base.rb

@@ -0,0 +1,23 @@
+module ActiveResource
+  # Overridden methods to suit SalesKing.
+  # Some changes might be kicked when AR 3.0 is out
+  class Base
+
+    # override encode because json is also returned nested by SalesKing
+    def encode(options={})
+      case self.class.format
+        when ActiveResource::Formats[:xml]
+          self.class.format.encode(attributes, {:root => self.class.element_name}.merge(options))
+        else # json also nested
+          self.class.format.encode( {self.class.element_name => attributes}, options)
+      end
+    end
+
+    # override ARes method to parse only the client part
+    def load_attributes_from_response(response)
+      if response['Content-Length'] != "0" && response.body.strip.size > 0
+        load( self.class.format.decode(response.body)[self.class.element_name] )
+      end
+    end
+  end
+end

data/lib/activeresource_patches/validations.rb

@@ -0,0 +1,30 @@
+module ActiveResource
+   
+  module Validations
+    # Validate a resource and save (POST) it to the remote web service.
+    def save_with_validation
+      save_without_validation
+      true
+    rescue ResourceInvalid => error
+      case error.response['Content-Type']
+      when /xml/ #PATCH
+        errors.from_xml(error.response.body)
+      when /json/ #PATCH
+        errors.from_json(error.response.body)
+      end
+      false
+    end   
+  end
+
+  class Errors
+
+    # Patched cause we dont need no attribute name magic .. and its just simpler
+    def from_array(messages)
+      clear
+      messages.each do |msg|
+        add msg[0], msg[1]
+      end
+    end
+  end #Errors
+
+end

data/lib/resources/address.rb

@@ -0,0 +1,35 @@
+module SKApi
+  module Resources
+    class Address < SKApi::Resources::Base
+
+      def save
+        save_with_validation
+      end    
+      
+      def self.schema
+        { "type" => "object",
+        "properties" => SKApi::Resources::Address.schema_props}
+      end
+
+      def self.schema_props
+        {
+           "id"       => {"type" => "string", "identity" => true, "readonly" => true},
+           "address1" => {"type" => "string", "optional" => true},
+           "address2" => {"type" => "string", "optional" => true},
+           "city"     => {"type" => "string", "optional" => true},
+           "country"  => {"type" => "string", "optional" => true},
+           "state"    => {"type" => "string", "optional" => true},
+           "zip"      => {"type" => "string", "optional" => true},
+           "pobox"    => {"type" => "string", "optional" => true},
+           "long"     => {"type" => "string", "optional" => true},
+           "lat"      => {"type" => "string", "optional" => true},
+           "address_type" => {"type" => "string", "optional" => true},
+           "created_at"   => {"type" => "string", "format" =>"date-time", "readonly"=> true},
+           "updated_at"   => {"type" => "string", "format" =>"date-time", "readonly"=> true},
+
+         }
+      end
+
+    end
+  end
+end

data/lib/resources/base.rb

@@ -0,0 +1,24 @@
+module SKApi
+  module Resources
+
+    class Base < ActiveResource::Base
+      include SKApi::Utils::Serializer
+      self.format = :json # bug in AR must be set here
+      
+      def initialize(attributes = {})
+        # json comes in nested {client={data}
+        attr = attributes[self.class.element_name] || attributes
+        super(attr)
+      end
+
+      # Define the connection to be used when talking to a salesking server
+      def self.set_connection(opts)
+        self.site = opts[:site]        #"http://demo.salesking.local:3000/api/"
+        self.user = opts[:user]        # "demo@salesking.eu"
+        self.password = opts[:password]   #"demo"
+        self.format = opts[:format].to_sym    #:json
+      end
+
+    end
+  end
+end

data/lib/resources/client.rb

@@ -0,0 +1,62 @@
+module SKApi
+  module Resources
+    class Client < SKApi::Resources::Base
+
+      def save
+#        validate_schema
+        save_with_validation
+      end
+
+      # not realy stable yet
+      def validate_schema
+        json = self.to_json
+        obj = Rufus::Json.decode(json)
+        JSON::Schema.validate(obj,  SKApi::Resources::Client.schema)
+      end
+
+      def self.schema
+        { "type" => "object",
+        "properties" => SKApi::Resources::Client.schema_props}
+      end
+
+      def self.schema_props
+       {
+           "id"           => {"type" => "string", "identity" => true , "readonly" => true},
+           "number"       => {"type" => "string", "optional" => true},
+           "organisation" => {"type" => "string"},
+           "first_name"   => {"type" => "string", "optional" => true},
+           "last_name"    => {"type" => "string", "optional" => true},
+           "title"        => {"type" => "string", "optional" => true},
+           "position"     => {"type" => "string", "optional" => true},
+           "gender"       => {"type" => "string", "enum" => ["male", "female"] , "optional" => true},
+           "email"        => {"type" => "string", "optional" => true},
+           "birthday"     => {"type" => "string", "format" =>"date", "optional" => true},
+           "url"          => {"type" => "string", "optional" => true},
+           "phone_fax"    => {"type" => "string", "optional" => true},
+           "phone_mobile" => {"type" => "string", "optional" => true},
+           "phone_office" => {"type" => "string", "optional" => true},
+           "phone_home"   => {"type" => "string", "optional" => true},
+           "bank_owner"   => {"type" => "string", "optional" => true},
+           "bank_name"    => {"type" => "string", "optional" => true},
+           "bank_number"  => {"type" => "string", "optional" => true},
+           "bank_account_number" => {"type" => "string", "optional" => true},
+           "bank_iban"      => {"type" => "string", "optional" => true},
+           "bank_swift"     => {"type" => "string", "optional" => true},
+           "vat_number"     => {"type" => "string", "optional" => true},
+           "tax_number"     => {"type" => "string", "optional" => true},
+           "tag_list"       => {"type" => "string", "optional" => true},
+           "cash_discount"  => {"type" => "number", "optional" => true},
+           "due_days"       => {"type" => "integer", "optional" => true},
+           "payment_method" => {"type" => "string", "enum" => ["draft", "open", "closed"], "optional" => true},
+           "sending_method" => {"type" => "string", "enum" => ["draft", "open", "closed"], "optional" => true},
+           "lock_version"   => {"type" => "integer", "readonly" => true, "optional" => true},
+           "created_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true},
+           "updated_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true},
+           "address_field"  => {"type" => "string", "optional" => true, "readonly" => true},
+           "addresses"      => {"type" => "array"},
+         }
+      end #schema_props
+
+    end #Client
+  end #Resources
+end #SKApi

data/lib/resources/credit_note.rb

@@ -0,0 +1,49 @@
+module SKApi
+  module Resources
+    class CreditNote < SKApi::Resources::Base
+
+      def save
+        save_with_validation
+      end
+
+      ##########################################################################
+      # Class methods
+      ##########################################################################
+
+      def self.schema
+        { "type" => "object",
+          "properties" => SKApi::Resources::CreditNote.schema_props}
+      end
+
+      def self.schema_props
+        {
+           "id"             => {"type" => "string", "identity" => true, "optional" => true, "readonly" => true},
+           "number"         => {"type" => "string", "optional" => true},
+           "date"           => {"type" => "string", "format" =>"date", "optional" => true},
+           "due_days"       => {"type" => "integer", "optional" => true},
+           "title"          => {"type" => "string", "optional" => true},
+           "status"         => {"type" => "string", "enum" => ["draft", "open", "closed"], "default" =>"draft", "optional" => true},
+           "payment_method" => {"type" => "string", "enum" => ["cash", "bank_transfer", "credit_card", "paypal", "direct_debit", "cheque"], "optional" => true},
+           "due_date"       => {"type" => "string", "format" =>"date", "optional" => true},
+           "notes_before"   => {"type" => "string", "optional" => true},
+           "notes_after"    => {"type" => "string", "optional" => true},
+           "price_total"    => {"type" => "number", "optional" => true, "readonly" => true},
+           "price_tax"      => {"type" => "number", "optional" => true, "readonly" => true},
+           "created_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly"=> true},
+           "updated_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly"=> true},
+           "address_field"  => {"type" => "string", "optional" => true, "readonly" => true},
+           "lock_version"   => {"type" => "integer", "optional" => true, "readonly" => true},
+           "client_id"      => {"type" => "string"},
+           "client"         => {"type" => "object", "properties" => SKApi::Resources::Client.schema_props, "optional" => true, "readonly" => true},
+           "line_items"     => {"type" => "array","properties" => SKApi::Resources::LineItem.schema_props, "optional" => true,},
+         }
+      end
+
+      def self.api_links
+        #internal links on fields=> id => salesking.eu/clients/4567.json
+      #external links to actions and related objects => invoeis => salesking.eu/clients/4567/invoices.json
+        [:edit, :destroy, :copy, :print, :show, :payments, :payment_new]
+      end
+    end
+  end
+end

data/lib/resources/line_item.rb

@@ -0,0 +1,32 @@
+module SKApi
+  module Resources
+    class LineItem < SKApi::Resources::Base
+
+      def save
+        save_with_validation
+      end
+
+      def self.schema
+        { "type" => "object",
+        "properties" => SKApi::Resources::LineItem.schema_props}
+      end
+
+      def self.schema_props
+       {
+           "id"             => {"type" => "string", "identity" => true , "readonly" => true},
+           "position"       => {"type" => "integer"},
+           "product_id"     => {"type" => "string", "optional" => true},
+           "quantity"       => {"type" => "number"},
+           "quantity_unit"  => {"type" => "string", "optional" => true},
+           "name"           => {"type" => "string", "optional" => true},
+           "description"    => {"type" => "string", "optional" => true},
+           "price_single"   => {"type" => "number"},
+           "discount"       => {"type" => "number", "optional" => true},
+           "tax"            => {"type" => "number", "optional" => true},
+           "created_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true},
+           "updated_at"     => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true}
+         }
+      end
+    end
+  end
+end

data/lib/resources/product.rb

@@ -0,0 +1,43 @@
+module SKApi
+  module Resources
+    class Product < SKApi::Resources::Base
+
+      def save
+#        validate_schema
+        save_with_validation
+      end
+
+      # not realy stable yet
+      def validate_schema
+        json = self.to_json
+        obj = Rufus::Json.decode(json)
+        JSON::Schema.validate(obj,  SKApi::Resources::Product.schema)
+      end
+
+      def self.schema
+        { "type" => "object",
+        "properties" => SKApi::Resources::Product.schema_props}
+      end
+
+      def self.schema_props
+       {
+#	category
+#	template_id
+           "id"           => {"type" => "string", "identity" => true , "readonly" => true},
+           "number"       => {"type" => "string", "optional" => true},
+           "name"         => {"type" => "string"},
+           "description"  => {"type" => "string", "optional" => true},
+           "price"        => {"type" => "number"},
+           "tax"          => {"type" => "number", "optional" => true},
+           "quantity_unit"=> {"type" => "string", "optional" => true},
+           "tag_list"     => {"type" => "string", "optional" => true},
+           "lock_version" => {"type" => "integer", "readonly" => true, "optional" => true},
+           "published_at" => {"type" => "string", "format" =>"date", "optional" => true},
+           "created_at"   => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true},
+           "updated_at"   => {"type" => "string", "format" =>"date-time", "optional" => true, "readonly" => true},
+         }
+      end #schema_props
+
+    end #Product
+  end #Resources
+end #SKApi

data/lib/sk_api.rb

@@ -0,0 +1,30 @@
+# external
+require 'active_resource'
+unless RUBY_PLATFORM =~ /java/
+  require 'yajl'
+  require 'rufus-json'
+
+  Rufus::Json.backend = :yajl
+else
+  require 'json'
+  require 'rufus-json'
+
+  Rufus::Json.backend = :json
+end
+
+#vendored
+require File.dirname(__FILE__) + '/../vendor/jsonschema-1.0.0/lib/jsonschema'
+
+# utilities
+require File.dirname(__FILE__) + '/utils/field_map'
+require File.dirname(__FILE__) + '/utils/serializer'
+
+#resources
+require File.dirname(__FILE__) + '/activeresource_patches/validations'
+require File.dirname(__FILE__) + '/activeresource_patches/base'
+require File.dirname(__FILE__) + '/resources/base'
+require File.dirname(__FILE__) + '/resources/product'
+require File.dirname(__FILE__) + '/resources/client'
+require File.dirname(__FILE__) + '/resources/address'
+require File.dirname(__FILE__) + '/resources/credit_note'
+require File.dirname(__FILE__) + '/resources/line_item'

data/lib/utils/field_map.rb

@@ -0,0 +1,114 @@
+module SKApi
+  module Utils
+    # Provide methods for mapping the fields of a remote object to local object
+    # The class holds two objects (f.ex. a remote and a local object) and works 
+    # with a hash which maps the fields between those two.
+    # If you use such a mapping both of your objects MUST respond to the method
+    # names passed in the mapping-table(hash)
+    #
+    # When an object is updated you can check the #log for changes
+    # ==== Example
+    #
+    #  contact_map = {
+    #     :loc_key => :name,
+    #     :rem_key => :firstname,
+    #     :obj => 'Stanza::SalesKing::Mapping::ContactTrans',
+    #     :loc_trans=>:set_local_name,
+    #     :rem_trans=> :set_remote_name
+    #   }
+    #   map = SKApi::Utils::FieldMap.new(@local_user, @remote_user, contact_map)
+    #   map.update_remote #Does not save! only sets the field values on the remote object
+    #   
+    # ==== Mapping Hash Explanation
+    #   
+    #  {
+    #    :loc_key => :name,               => Local fieldname    #
+    #    :rem_key => :firstname,          => remote fieldname
+    #    :obj => 'ATransitionClass',      => The class which hold the following Transition methods as Class.methods
+    #    :loc_trans=>:set_local_name,     =>  Method called when local field is updated
+    #    :rem_trans=> :set_remote_name    =>  Method called when remote field is update
+    #  }
+    class FieldMap
+
+      # The local object
+      attr_accessor :loc_obj
+      # The remote object
+      attr_accessor :rem_obj
+      # <Hash{Symbol=>Symbol, Symbol=>{Hash} }>::the field mapping
+      attr_accessor :fields
+      # the outdated fields
+      attr_reader :outdated
+      # <Array[String]>::log field changes
+      attr_reader :log
+
+      # Takes a local and remote object which should respond to function defined
+      # in the mapping hash
+      def initialize(loc_obj, rem_obj, fields)
+        @loc_obj = loc_obj
+        @rem_obj = rem_obj
+        @fields = fields
+        @log = []
+      end
+
+      # check if the any of the fields are outdated
+      # populates self.outdated array with outdated fields
+      # ==== Returns
+      # <Boolean>:: false if not outdated
+      def outdated?
+        @outdated = []
+        fields.each do |fld|
+          if fld[:trans]
+            # SomeTransferObject.remote_tranfer_function(remote_obj_data)
+            virtual_local_val  = fld[:trans][:obj].constantize.send( fld[:trans][:rem_trans], loc_obj.send( fld[:loc_key] ) )
+            @outdated << fld if virtual_local_val != rem_obj.send( fld[:rem_key] )
+          else
+            @outdated << fld if rem_obj.send( fld[:rem_key] ) != loc_obj.send( fld[:loc_key] )
+          end          
+        end
+        !@outdated.empty?
+      end
+
+      # update all local outdated fields wit hvcalues from remote object
+      def update_local_outdated
+        update_local(@outdated) if outdated?
+      end
+      # update all remote outdated fields wit hvalues from local object
+      def update_remote_outdated
+        update_remote(@outdated) if outdated?
+      end
+
+      # update all local fields with values from remote
+      def update_local(field=nil)
+        flds = field ? ( field.is_a?(Array) ? field : [field] ) : fields
+        flds.each do |fld|
+          old_val = loc_obj.send(fld[:loc_key]) rescue 'empty'
+          new_val = if fld[:trans] #call transfer function
+                      fld[:trans][:obj].constantize.send( fld[:trans][:loc_trans], rem_object.send( fld[:rem_key] ) )
+                    else # lookup directly on local object
+                      rem_obj.send(fld[:rem_key])
+                    end
+          loc_obj.send( "#{fld[:loc_key]}=", new_val )
+          # write to log
+          log << "local: #{fld[:loc_key]} was: #{old_val} updated from remote: #{fld[:rem_key]} with value: #{new_val}"
+        end
+      end
+
+      # Update all or given remote fields with the value of the local fields
+      # 
+      def update_remote(field=nil)
+        flds = field ? ( field.is_a?(Array) ? field : [field] ) : fields
+        flds.each do |fld|
+          old_val = rem_obj.send(fld[:rem_key]) rescue 'empty'# rember for log
+          new_val = if fld[:trans] #call transfer function
+                      fld[:trans][:obj].constantize.send( fld[:trans][:rem_trans], loc_obj.send( fld[:loc_key] ) )
+                    else # lookup directly on local object
+                      loc_obj.send( fld[:loc_key] )
+                    end
+          rem_obj.send( "#{fld[:rem_key]}=" , new_val )
+          log << "remote: #{fld[:rem_key]} was: #{old_val} updated from local: #{fld[:loc_key]} with value: #{new_val}"
+        end
+      end
+
+    end # FieldMapping
+  end # Utils
+end #SKApi