vend 0.0.4

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+doc/*
+.rvmrc

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+gem 'rake'
+
+# Specify your gem's dependencies in vend.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,8 @@
+= Vend API Gem
+
+This gem provides access to Vend's REST API.
+
+== Vend API Documentation
+
+At the time of writing, this is located at
+https://docs.google.com/document/pub?id=13JiV6771UcrkmawFRxzvVl3tf5PGSTBH56RYy0-5cps

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/gem_tasks"
+
+require 'rubygems'
+require 'rspec/core/rake_task'
+require 'rake/rdoctask'
+
+Dir.glob('lib/tasks/*.rake').each { |r| import r }
+
+task :default => [:spec]
+
+desc "Run RSpec tests"
+RSpec::Core::RakeTask.new(:spec)
+
+Rake::RDocTask.new(:doc) do |rd|
+  rd.main       = 'README.rdoc'
+  rd.rdoc_dir   = 'doc'
+  rd.rdoc_files.include('README.rdoc', 'lib/**/*.rb')
+end

data/example.rb

@@ -0,0 +1,51 @@
+require './lib/vend'
+require 'log4r'
+
+STORE = ARGV[0]
+USERNAME = ARGV[1]
+PASSWORD = ARGV[2]
+
+unless STORE and USERNAME and PASSWORD
+  $stderr.puts "Usage: example.rb store username password"
+  exit 1
+end
+
+client = Vend::Client.new(STORE, USERNAME, PASSWORD)
+
+logger = Log4r::Logger.new 'vend'
+logger.outputters = Log4r::Outputter.stdout
+client.http_client.logger = client.logger = logger
+
+# puts client.request('products', :method => :put, :body => '{"foo":"bar"}')
+
+# puts "###### Products ######"
+# client.Product.all.each do |product|
+#   puts product.name
+# end
+#
+# puts "###### Customers ######"
+# client.Customer.all.each do |customer|
+#   puts "#{customer.name} (#{customer.customer_code})"
+# end
+#
+# puts "###### Creating a Customer ######"
+# response = client.request('customers', :method => :post, :body => '{"customer_code":"foo"}')
+# puts response
+#
+# puts "###### Finding a Customer by name ######"
+# response = client.Customer.find_by_name('Foo')
+# puts response.inspect
+#
+# puts "###### Finding a Customer by email ######"
+# response = client.Customer.find_by_email('foo@example.com')
+# puts response.inspect
+#
+# puts "###### Outlets ######"
+# client.Outlet.all.each do |outlet|
+#   puts outlet.name
+# end
+#
+# puts "###### Payment Types ######"
+# client.PaymentType.all.each do |payment_type|
+#   puts payment_type.name
+# end

data/lib/vend.rb

@@ -0,0 +1,24 @@
+$: << File.expand_path(File.dirname(__FILE__))
+require 'active_support/inflector'
+
+require 'vend/exception'
+require 'vend/null_logger'
+require 'vend/logable'
+require 'vend/pagination_info'
+require 'vend/scope'
+require 'vend/resource_collection'
+require 'vend/base_factory'
+require 'vend/base'
+
+require 'vend/resource/outlet'
+require 'vend/resource/product'
+require 'vend/resource/customer'
+require 'vend/resource/payment_type'
+require 'vend/resource/register'
+require 'vend/resource/register_sale'
+require 'vend/resource/register_sale_product'
+require 'vend/resource/tax'
+require 'vend/resource/user'
+
+require 'vend/http_client'
+require 'vend/client'

data/lib/vend/base.rb

@@ -0,0 +1,200 @@
+module Vend
+
+  # This Base class provides the basic mapping between Vend::Resource subclasses
+  # and the HTTP endpoints in the Vend API.
+  #
+  # Not all CRUD actions are available for every resource, and at current there
+  # is no PUT endpoint and hence no update action
+  class Base
+
+    # Reference to the Vend::Client client object providing the HTTP interface to the
+    # API
+    attr_reader :client
+
+    # Hash of attributes for this instance. Represents the data returned from
+    # the Vend API
+    attr_accessor :attrs
+
+    def initialize(client, options = {}) #:nodoc:
+      @client = client
+      @attrs = options[:attrs] || {}
+    end
+
+    def self.cast_attribute(attribute_name, type)
+      attribute_casts[attribute_name] = type
+    end
+
+    def self.attribute_casts
+      @attribute_casts ||= {}
+    end
+    # Returns the endpoint name for the resource, used in API urls when making
+    # requests.
+    def self.endpoint_name
+      self.name.split('::').last.underscore
+    end
+
+    # Returns the endpoint name for a collection of this resource
+    def self.collection_name
+      endpoint_name.pluralize
+    end
+
+    def singular_name
+      self.class.singular_name(id)
+    end
+
+    def self.singular_name(id)
+      "#{collection_name}/#{id}"
+    end
+
+    # Returns a collection containing all of the specified resource objects.
+    # Will paginate.
+    def self.all(client)
+      initialize_collection(client, collection_name)
+    end
+
+    # Returns the list of URL parameter scopes that are available for this
+    # resource.  For example, if the resource accepted URLs like:
+    #
+    #   /api/resources/since/YYYY-MM-DD HH:MM:SS/outlet_id/abc-1234-def
+    #
+    # this method would return [:since, :outlet_id]
+    def self.available_scopes
+      @available_scopes ||= []
+    end
+
+    def self.accepts_scope?(scope_name)
+      available_scopes.include?(scope_name)
+    end
+
+    # Creates a class method that allows access to a filtered collection of
+    # resources on the API.  For example:
+    #
+    #   class MyResource << Vend::Base
+    #     url_scope :since
+    #   end
+    #
+    # Will create a class method:
+    #
+    #   client.MyResource.since(argument)
+    #
+    # That will call the following URL on the Vend API:
+    #
+    #   /api/my_resources/since/:argument
+    #
+    # And return the corresponding collection of resources
+    def self.url_scope(method_name)
+      (class << self ; self ; end).instance_eval do
+        define_method(method_name) do |client, arg|
+          initialize_collection(client, collection_name).scope(method_name, arg)
+        end
+      end
+      available_scopes << method_name
+    end
+    
+    def self.findable_by(field, options = {})
+      
+      (class << self ; self ; end).instance_eval do
+        define_method("find_by_#{field}") do |client, *args|
+          search(client, options[:as] || field, *args)
+        end
+      end
+    end
+    # Sends a search request to the API and initializes a collection of Resources
+    # from the response.
+    # This method is only used internally by find_by_field methods.
+    def self.search(client, field, query)
+      initialize_collection(
+        client, collection_name,  :url_params => { field.to_sym => query }
+      )
+    end
+
+    # Builds a new instance of the described resource using the specified
+    # attributes.
+    def self.build(client, attrs)
+      self.new(client, :attrs => attrs)
+    end
+
+    # Builds a collection of instances from a JSON response
+    def self.build_from_json(client, json)
+      json[collection_name].map do |attrs|
+        self.build(client, attrs)
+      end
+    end
+
+    # Initializes a single object from a JSON response.
+    # Assumes the response is a JSON array with a single item.
+    def self.initialize_singular(client, json)
+      self.build(client, json[collection_name].first)
+    end
+
+    # Will initialize a collection of Resources from the APIs JSON Response.
+    def self.initialize_collection(client, endpoint, args = {})
+      ResourceCollection.new(client, self, endpoint, args)
+    end
+
+
+    # Attempts to pull a singular object from Vend through the singular GET
+    # endpoint.
+    def self.find(client, id)
+      response = client.request(singular_name(id))
+      initialize_singular(client, response)
+    end
+
+    # Whether or not this resource can be paginated, false by default.
+    # Override this method in specific classes to enable pagination for that
+    # resource.
+    def self.paginates?
+      false
+    end
+
+    # Overrides respond_to? to query the attrs hash for the key before
+    # proxying it to the object
+    def respond_to?(method_name)
+      if attrs.keys.include? method_name.to_s
+        true
+      else
+        super(method_name)
+      end
+    end
+
+    # Overrides method_missing to query the attrs hash for the value stored
+    # at the specified key before proxying it to the object
+    def method_missing(method_name, *args, &block)
+      if attrs.keys.include? method_name.to_s
+        attribute_value_for(method_name)
+      else
+        super(method_name)
+      end
+    end
+
+    # Attempts to delete the resource. If an exception is thrown by delete!,
+    # it is caught and false is returned (typically when the resource is not
+    # a type which can be deleted).
+    def delete
+      delete!
+    rescue Vend::Resource::IllegalAction
+      false
+    end
+
+    # Attempts to delete there resource. Will throw an exception when the attempt
+    # fails, otherwise will return true.
+    def delete!
+      raise(Vend::Resource::IllegalAction,
+            "#{self.class.name} has no unique ID") unless attrs['id']
+      client.request(singular_name, :method => :delete)
+      true
+    end
+
+    protected
+    def attribute_value_for(attribute_name)
+      if self.class.attribute_casts.has_key? attribute_name
+        case self.class.attribute_casts[attribute_name].to_s
+        when "Float"
+          return attrs[attribute_name.to_s].to_f
+        end
+      else
+        attrs[attribute_name.to_s]
+      end
+    end
+  end
+end

data/lib/vend/base_factory.rb

@@ -0,0 +1,34 @@
+module Vend
+
+  class BaseFactory
+
+    attr_reader :client, :target_class
+
+    def initialize(client, target_class)
+      @target_class = target_class
+      @client = client
+    end
+
+    # The main point of this factory class is to proxy methods to the target
+    # class and prepend client to the argument list.
+    def method_missing(method_name, *args, &block)
+      args.unshift(client)
+      target_class.send(method_name, *args, &block)
+    end
+
+    def respond_to?(method_name)
+      return true if target_class.respond_to?(method_name)
+      super(method_name)
+    end
+
+    ## Generates find_by_field methods which call a search on the target class
+    #def self.findable_by(field, options = {})
+    #  url_param = options[:as] || field
+    #  define_method "find_by_#{field.to_s}" do |*args|
+    #    target_class.send(:search, @client, url_param, *args)
+    #  end
+    #end
+
+  end
+
+end

data/lib/vend/client.rb

@@ -0,0 +1,82 @@
+require 'forwardable'
+
+module Vend #:nodoc:
+
+  # Main access point which allows resources within the Vend gem to
+  # make HTTP requests to the Vend API.
+  #
+  # Client must be initialized with:
+  #   * a store url (e.g. the storeurl portion of http://storeurl.vendhq.com/),
+  #   * a valid username and password
+  #
+  class Client
+
+    DEFAULT_OPTIONS = {}
+
+    extend Forwardable
+    def_delegator :http_client, :request
+
+    include Logable
+
+    # The store url for this client
+    attr_accessor :store, :username, :password
+    attr_reader :options
+
+    def initialize(store, username, password, options = {}) #:nodoc:
+      @store = store
+      @username = username
+      @password = password
+      @options = DEFAULT_OPTIONS.merge(options)
+    end
+
+    def Product #:nodoc:
+      Vend::BaseFactory.new(self, Resource::Product)
+    end
+
+    def Outlet #:nodoc:
+      Vend::BaseFactory.new(self, Resource::Outlet)
+    end
+
+    def Customer #:nodoc:
+      Vend::BaseFactory.new(self, Resource::Customer)
+    end
+
+    def PaymentType #:nodoc:
+      Vend::BaseFactory.new(self, Resource::PaymentType)
+    end
+
+    def Register #:nodoc:
+      Vend::BaseFactory.new(self, Resource::Register)
+    end
+
+    def RegisterSale #:nodoc:
+      Vend::BaseFactory.new(self, Resource::RegisterSale)
+    end
+
+    def Tax #:nodoc:
+      Vend::BaseFactory.new(self, Resource::Tax)
+    end
+
+    def User #:nodoc:
+      Vend::BaseFactory.new(self, Resource::User)
+    end
+
+    # Returns the base API url for the client.
+    # E.g. for the store 'foo', it returns https://foo.vendhq.com/api/
+    def base_url
+      "https://#{@store}.vendhq.com/api/"
+    end
+
+    def http_client
+      @http_client ||= HttpClient.new(http_client_options)
+    end
+
+    def http_client_options
+      options.merge(
+        :base_url => base_url, :username => username, :password => password
+      )
+    end
+
+  end
+
+end

data/lib/vend/exception.rb

@@ -0,0 +1,35 @@
+require 'forwardable'
+
+module Vend
+  module Resource
+    # Raised when the action being performed is not possible or applicable to
+    # the resource under the current conditions
+    class IllegalAction < StandardError; end
+
+    # Raised when the response from the API is not able to be interpreted
+    # in a useful way by the Gem (E.g. Parsing errors for non-JSON responses)
+    class InvalidResponse < StandardError; end
+  end
+
+  # Raised when the specified endpoint does not exist in the API. (Indicated
+  # by the response being a redirect to the signin page)
+  class InvalidRequest < StandardError; end
+
+  # This exception is thrown when a 401 Unauthorized response is received
+  # from the Vend API
+  class Unauthorized < StandardError; end
+
+  # Nonspecific HTTP error which is usually thrown when a non 2xx response
+  # is received.
+  class HTTPError < StandardError
+    extend Forwardable
+
+    delegate [:message, :code] => :response
+
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+    end
+  end
+end