magentor 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Preston Stuteville
+
+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.rdoc

@@ -0,0 +1,45 @@
+= Magentor
+Simple wrapper for the Magento XMLRPC api
+
+Magento api documentation: http://www.magentocommerce.com/support/magento_core_api
+
+
+= Usage
+Setup your connection to magento
+
+  Magento::Base.connection = Magento::Connection.new({
+    :username => 'username', 
+    :api_key => 'api_key', 
+    :host => 'magento.example.org', 
+    :path => '/magento/api/xmlrpc', 
+    :port => '80'
+  })
+
+Then get down to business
+
+  Magento::Customer.list
+  Magento::Product.info(1).sku
+  customer = Magento::Customer.find(:first, {:email => 'example@magentor.ccc'})
+  customer.update_attributes({:firstname => 'duke', :lastname => 'magentor'})
+  customer.delete
+
+= License
+Copyright (c) 2010 Preston Stuteville
+
+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/Rakefile

@@ -0,0 +1,16 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name     = "magentor"
+    gemspec.summary  = "Ruby wrapper for the Magento xmlrpc api"
+    gemspec.email    = "preston.stuteville@gmail.com"
+    gemspec.homepage = "http://github.com/pstuteville/magentor"
+    gemspec.authors  = ["Preston Stuteville"]
+    
+    gemspec.has_rdoc = true
+    gemspec.rdoc_options = ["--main", "README.rdoc", "--inline-source", "--line-numbers"]
+    gemspec.extra_rdoc_files = ["README.rdoc"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/TODOS

@@ -0,0 +1,3 @@
+- Implement correct method signatures instead of passing *args to most api calls
+- Validation
+- Add more convenience methods to objects

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1 @@
+require 'magento'

data/lib/magento/base.rb

@@ -0,0 +1,55 @@
+# Base Magento model handles basic crud operations and stores connection to magento instance.
+# It has the following class attributes:
+#
+# * <tt>connection</tt>: the Magento::Connection to use
+# 
+# And the following instance attributes:
+# * <tt>attributes</tt>: the attributes of the magento object
+#
+module Magento
+  class Base
+    attr_accessor :attributes
+    class << self; attr_accessor :connection end
+    
+    module ClassMethods
+      # Uses the classes name and method to make an rpc call through connection
+      def commit(method, *args)
+        # TODO: need to catch errors sent back from magento and bubble them up appropriately
+        method = "#{to_s.split('::').last.underscore.downcase}.#{method}"
+        Magento::Base.connection.call(method, *args)
+      end
+    end
+    
+    module InstanceMethods
+      def initialize(attributes = {})
+        @attributes = attributes.dup
+      end
+      
+      # TODO: find out if the id naming is consistent
+      def id
+        @attributes["#{self.class.to_s.split('::').last.underscore.downcase}_id"]
+      end
+      
+      def id=(_id)
+        @attributes["#{self.class.to_s.split('::').last.underscore.downcase}_id"] = _id
+      end
+
+      def object_attributes=(new_attributes)
+        return if new_attributes.nil?
+        attributes = new_attributes.dup
+        attributes.stringify_keys!
+        attributes.each do |k, v|
+          send(k + "=", v)
+        end
+      end
+
+      def method_missing(method, *args)
+        return nil unless @attributes
+        @attributes[method.to_s]
+      end
+    end
+    
+    include InstanceMethods
+    extend ClassMethods
+  end
+end

data/lib/magento/category.rb

@@ -0,0 +1,215 @@
+module Magento
+  # http://www.magentocommerce.com/wiki/doc/webservices-api/api/catalog_category
+  # 100  Requested store view not found.
+  # 101  Requested website not found.
+  # 102  Category not exists.
+  # 103  Invalid data given. Details in error message.
+  # 104  Category not moved. Details in error message.
+  # 105  Category not deleted. Details in error message.
+  # 106  Requested product is not assigned to category.
+  class Category < Base
+    class << self
+      # catalog_category.create
+      # Create new category and return its id.
+      # 
+      # Return: int
+      # 
+      # Arguments:
+      # 
+      # int $parentId - ID of parent category
+      # array $categoryData - category data ( array(’attribute_code’⇒‘attribute_value’ )
+      # mixed $storeView - store view ID or code (optional)
+      def create(attributes)
+        id = commit("create", attributes)
+        record = new(attributes)
+        record.id = id
+        record
+      end
+
+      # catalog_category.info
+      # Retrieve category data
+      # 
+      # Return: array
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - category ID
+      # mixed $storeView - store view id or code (optional)
+      # array $attributes - return only specified attributes (optional)
+      def info(*args)
+        new(commit("info", *args))
+      end
+
+      # catalog_category.update
+      # Update category
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - ID of category for updating
+      # array $categoryData - category data ( array(’attribute_code’⇒‘attribute_value’ )
+      # mixed storeView - store view ID or code (optional)
+      def update(*args)
+        commit("update", *args)
+      end
+
+      # catalog_category.delete
+      # Delete category
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - category ID
+      def delete(*args)
+        commit("delete", *args)
+      end
+
+      # catalog_category.currentStore
+      # Set/Get current store view
+      # 
+      # Return: int
+      # 
+      # Arguments:
+      # 
+      # mixed storeView - Store view ID or code.
+      def current_store(*args)
+        commit("currentStore", *args)
+      end
+
+      # catalog_category.tree
+      # Retrieve hierarchical tree of categories.
+      # 
+      # Return: array
+      # 
+      # Arguments:
+      # 
+      # int parentId - parent category id (optional)
+      # mixed storeView - store view (optional)
+      def tree(*args)
+        commit("tree", *args)
+      end
+
+      # catalog_category.level
+      # Retrieve one level of categories by website/store view/parent category
+      # 
+      # Return: array
+      # 
+      # Arguments:
+      # 
+      # mixed website - website code or Id (optional)
+      # mixed storeView - store view code or Id (optional)
+      # mixed parentCategory - parent category Id (optional)
+      def level(*args)
+        commit("level", *args)
+      end
+
+      # catalog_category.move
+      # Move category in tree
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - category ID for moving
+      # int $parentId - new category parent
+      # int $afterId - category ID after what position it will be moved (optional)
+      # 
+      # NOTE Please make sure that you are not moving category to any of its own children. 
+      # There are no extra checks to prevent doing it through webservices API, and you won’t 
+      # be able to fix this from admin interface then
+      def move(*args)
+        commit("move", *args)
+      end
+
+      # catalog_category.assignedProducts
+      # Retrieve list of assigned products
+      # 
+      # Return: array
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - category ID
+      # mixed $store - store ID or code
+      def assigned_products(*args)
+        commit("assignedProducts", *args)
+      end
+
+      # catalog_category.assignProduct
+      # Assign product to category
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - category ID
+      # mixed $product - product ID or sku
+      # int $position - position of product in category (optional)
+      def assign_product(*args)
+        commit("assignProduct", *args)
+      end
+
+      # catalog_category.updateProduct
+      # Update assigned product
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - category ID
+      # mixed $product - product ID or sku
+      # int $position - position of product in category (optional)
+      def update_product(*args)
+        commit("updateProduct", *args)
+      end
+
+      # catalog_category.removeProduct
+      # Remove product assignment from category
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int $categoryId - category ID
+      # mixed $product - product ID or sku
+      def remove_product(*args)
+        commit("removeProduct", *args)
+      end
+      
+      def find_by_id(id)
+        info(id)
+      end
+    end
+    
+    def delete
+      self.class.delete(self.id)
+    end
+    
+    def update_attribute(name, value)
+      @attributes[name] = value
+      self.class.update(self.id, Hash[*[name.to_sym, value]])
+    end
+    
+    def update_attributes(attrs)
+      attrs.each_pair { |k, v| @attributes[k] = v }
+      self.class.update(self.id, attrs)
+    end
+    
+    def assigned_products(*args)
+      self.class.assigned_products(self.id, *args)
+    end
+
+    def assign_product(*args)
+      self.class.assign_product(self.id, *args)
+    end
+
+    def update_product(*args)
+      self.class.update_product(self.id, *args)
+    end
+
+    def remove_product(*args)
+      self.class.remove_product(self.id, *args)
+    end
+  end
+end

data/lib/magento/category_attribute.rb

@@ -0,0 +1,42 @@
+module Magento
+  # http://www.magentocommerce.com/wiki/doc/webservices-api/api/catalog_category_attribute
+  # 100  Requested store view not found.
+  # 101  Requested attribute not found.
+  class CategoryAttribute < Base
+    class << self
+      # catalog_category_attribute.list
+      # Retrieve category attributes
+      # 
+      # Return: array
+      def list
+        results = commit("list", nil)
+        results.collect do |result|
+          new(result)
+        end
+      end
+
+      # catalog_category_attribute.currentStore
+      # Set/Get current store view
+      # 
+      # Return: int
+      # 
+      # Arguments:
+      # 
+      # mixed storeView - Store view ID or code. (optional)
+      def current_store(*args)
+        commit("currentStore", *args)
+      end
+
+      # catalog_category_attribute.options
+      # Retrieve attribute options
+      # 
+      # Arguments:
+      # 
+      # attributeId - attribute id or code
+      # storeView - store view id or code
+      def options(*args)
+        commit("options", *args)
+      end
+    end
+  end
+end

data/lib/magento/connection.rb

@@ -0,0 +1,23 @@
+module Magento
+  class Connection 
+    attr_accessor :client, :config, :logger
+    def initialize(config = {})
+      @logger ||= Logger.new(STDOUT)
+      @config = config
+      self
+    end
+    
+    def connect
+      @client = XMLRPC::Client.new(config[:host], config[:path], config[:port])
+      @session = @client.call("login", config[:username], config[:api_key])
+    end
+    
+    def call(method = nil, *args)
+      @logger.debug "call: #{method}, #{args.inspect}"
+      connect
+      @client.call("call", @session, method, args)
+    rescue XMLRPC::FaultException => e
+      @logger.debug "exception: #{e.faultCode} -> #{e.faultString}"
+    end
+  end
+end

data/lib/magento/country.rb

@@ -0,0 +1,21 @@
+module Magento
+  # http://www.magentocommerce.com/wiki/doc/webservices-api/api/directory_country
+  class Country < Base
+    class << self
+      # directory_country.list
+      # Retrieve list of countries.
+      # 
+      # Return: array.
+      def list
+        results = commit("list", nil)
+        results.collect do |result|
+          new(result)
+        end
+      end
+      
+      def all
+        list
+      end
+    end
+  end
+end

data/lib/magento/customer.rb

@@ -0,0 +1,122 @@
+module Magento
+  # http://www.magentocommerce.com/wiki/doc/webservices-api/api/customer
+  # 100  Invalid customer data. Details in error message.
+  # 101  Invalid filters specified. Details in error message.
+  # 102  Customer does not exist.
+  # 103  Customer not deleted. Details in error message.
+  class Customer < Base
+    class << self
+      # customer.list
+      # Retrieve customers
+      # 
+      # Return: array
+      # 
+      # Arguments:
+      # 
+      # array filters - filters by customer attributes (optional)
+      # filter list - “updated_at”, “website_id”, “increment_id”, “lastname”, “group_id”, 
+      #   “firstname”, “created_in”, “customer_id”, “password_hash”, “store_id”, “email”, “created_at”
+      # 
+      # Note: password_hash will only match exactly with the same MD5 and salt as was used when 
+      # Magento stored the value. If you try to match with an unsalted MD5 hash, or any salt other 
+      # than what Magento used, it will not match. This is just a straight string comparison.
+      def list(*args)
+        results = commit("list", *args)
+        results.collect do |result|
+          new(result)
+        end
+      end
+
+      # customer.create
+      # Create customer
+      # 
+      # Return: int
+      # 
+      # Arguments:
+      # 
+      # array customerData - cutomer data (email, firstname, lastname, etc...)
+      def create(attributes)
+        id = commit("create", attributes)
+        record = new(attributes)
+        record.id = id
+        record
+      end
+    
+    
+      # customer.info
+      # Retrieve customer data
+      # 
+      # Return: array
+      # 
+      # Arguments:
+      # 
+      # int customerId - Customer ID.
+      # array attributes | string attribute (optional depending on version) - 
+      #   return only these attributes. Possible attributes are updated_at, increment_id, 
+      #   customer_id, created_at. The value, customer_id, is always returned.
+      def info(*args)
+        new(commit("info", *args))
+      end
+    
+      # customer.update
+      # Update customer data
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int customerId - customer ID
+      # array customerData - customer data (email, firstname, etc...)
+      def update(*args)
+        commit("update", *args)
+      end
+    
+    
+      # customer.delete
+      # Delete customer
+      # 
+      # Return: boolean
+      # 
+      # Arguments:
+      # 
+      # int customerId - customer ID.
+      def delete(*args)
+        commit("delete", *args)
+      end
+      
+      def find_by_id(id)
+        info(id)
+      end
+
+      def find(find_type, options = {})
+        filters = {}
+        options.each_pair { |k, v| filters[k] = {:eq => v} }
+        results = list(filters)
+        if find_type == :first
+          results.first
+        else
+          results
+        end
+      end
+
+      def all
+        list
+      end
+      
+    end
+    
+    def delete
+      self.class.delete(self.id)
+    end
+    
+    def update_attribute(name, value)
+      @attributes[name] = value
+      self.class.update(self.id, Hash[*[name.to_sym, value]])
+    end
+    
+    def update_attributes(attrs)
+      attrs.each_pair { |k, v| @attributes[k] = v }
+      self.class.update(self.id, attrs)
+    end
+  end
+end

data/lib/magento/customer_address.rb

@@ -0,0 +1,101 @@
+module Magento
+  # http://www.magentocommerce.com/wiki/doc/webservices-api/api/customer_address
+  # 100  Invalid address data. Details in error message.
+  # 101  Customer not exists.
+  # 102  Address not exists.
+  # 103  Address not deleted. Details in error message.
+  class CustomerAddress < Base
+    class << self
+       # customer_address.list
+        # Retrieve customer addresses
+        # 
+        # Return: array
+        # 
+        # Arguments:
+        # 
+        # int customerId - Customer Id
+        def list(*args)
+          results = commit("list", *args)
+          results.collect do |result|
+            new(result)
+          end
+        end
+
+        # customer_address.create
+        # Create customer address
+        # 
+        # Return: int
+        # 
+        # Arguments:
+        # 
+        # int customerId - customer ID
+        # array addressData - adress data (country, zip, city, etc...)
+        def create(attributes)
+          id = commit("create", attributes)
+          record = new(attributes)
+          record.id = id
+          record
+        end
+
+        # customer_address.info
+        # Retrieve customer address data
+        # 
+        # Return: array
+        # 
+        # Arguments:
+        # 
+        # int addressId - customer address ID
+        def info(*args)
+          new(commit("info", *args))
+        end
+
+        # customer_address.update
+        # Update customer address data
+        # 
+        # Return: boolean
+        # 
+        # Arguments:
+        # 
+        # int addressId - customer address ID
+        # array addressData - adress data (country, zip, city, etc...)
+        def update(*args)
+          commit("update", *args)
+        end
+
+        # customer_address.delete
+        # Delete customer address
+        # 
+        # Return: boolean
+        # 
+        # Arguments:
+        # 
+        # int addressId - customer address ID
+        def delete(*args)
+          commit("delete", *args)
+        end
+        
+        def find_by_id(id)
+          info(id)
+        end
+
+        def find_by_customer_id(id)
+          list(id)
+        end
+        
+    end
+
+    def delete
+      self.class.delete(self.id)
+    end
+    
+    def update_attribute(name, value)
+      @attributes[name] = value
+      self.class.update(self.id, Hash[*[name.to_sym, value]])
+    end
+    
+    def update_attributes(attrs)
+      attrs.each_pair { |k, v| @attributes[k] = v }
+      self.class.update(self.id, attrs)
+    end
+  end
+end

data/lib/magento/customer_group.rb

@@ -0,0 +1,17 @@
+module Magento
+  # http://www.magentocommerce.com/wiki/doc/webservices-api/api/customer_group
+  class CustomerGroup < Base
+    class << self
+      # customer_group.list
+      # Retrieve customer groups
+      # 
+      # Return: array
+      def list
+        results = commit("list", nil)
+        results.collect do |result|
+          new(result)
+        end
+      end
+    end
+  end
+end

data/lib/magento/inventory.rb

@@ -0,0 +1,4 @@
+module Magento
+  class Inventory < Base
+  end
+end