ns_connector 0.0.6

data/lib/ns_connector/config.rb

@@ -0,0 +1,66 @@
+# A 'global' config.
+#
+# Being global, we are restricted to connecting to one NetSuite upstream URL
+# per ruby process.
+class NSConnector::Config
+	@@options = {}
+	ArgumentError = Class.new(Exception)
+	DEFAULT = {
+		:use_threads => true,
+		:no_threads => 4
+	}
+
+	class << self
+		# Read a key stored in @@options: Config[:key]
+		def [](key)
+			key = key.to_sym
+			val = @@options[key]
+
+			val.nil? ? DEFAULT[key] : val
+		end
+
+		# Write a key stored in @@options: Config[:key] = 1
+		def []=(key, value)
+			@@options[key.to_sym] = value
+		end
+
+		# Overwrite the current 'global' config with +options+
+		def set_config! options
+			@@options = {}
+			options.each do |k,v|
+				@@options[k.to_sym] = v
+			end
+		end
+
+		# Check if the current config is valid.
+		# Returns:
+		# true:: if all required keys are supplied
+		# Raises:
+		# ArgumentError:: if any keys are missing
+		def check_valid!
+			unless @@options then
+				raise NSConnector::Config::ArgumentError,
+					'Need a configuration set. '\
+					'See: NSConnector::Config.set_config!'
+			end
+
+			required = [
+				:account_id, 
+				:email,
+				:password,
+				:role,
+				:restlet_url
+			]
+
+			missing_keys = (required - @@options.keys)
+			unless missing_keys.empty?
+				raise NSConnector::Config::ArgumentError, 
+					'Missing configuration key(s): '\
+					"#{missing_keys.join(', ')}"
+			end
+
+			# All good
+			return true
+		end
+	end
+end

data/lib/ns_connector/errors.rb

@@ -0,0 +1,79 @@
+# A collection of useful, catchable, and usually netsuite related errors.
+#
+# For a list of errors that can be returned and conditions for returning said
+# errors, see #try_handle_response!
+module NSConnector::Errors
+	# Parent class to encapsulate all successfully parsed JSON netsuite
+	# error responses. 
+	class NSError < Exception
+		def initialize netsuite_error
+			@netsuite_error = netsuite_error
+		end
+
+		# Returns the error code from the JSON returned by netsuite.
+		# Something like: "RCRD_DSNT_EXIST"
+		def code
+			@netsuite_error['code']
+		end
+
+		# Takes the error message straight out of the netsuite
+		# response. Usually makes some sense.
+		def message
+			@netsuite_error['message']
+		end
+	end
+
+	# Not found
+	NotFound = Class.new(NSError)
+	# Some field has a unique constraint on it which has a duplicate
+	Conflict = Class.new(NSError)
+	# Usually a search run on an invalid field
+	InvalidSearchFilter = Class.new(NSError)
+
+	# Internal use 
+	BeginChunking = Class.new(NSError)
+	# Internal use 
+	EndChunking   = Class.new(NSError)
+
+	# Unknown errors should still have a #code and #message that is useful.
+	# They are raised when we got a JSON error response from NetSuite that
+	# we simply don't cater explicitly for.
+	Unknown = Class.new(NSError)
+
+	# Complete garbage received
+	WTF = Class.new(RuntimeError)
+
+	# Try and make a HTTP response from netsuite a nice error.
+	# Arguments:: A Net::HTTP response, should be a 400
+	# Raises::
+	#   NSConnector::Errors::NotFound:: on a RCRD_DSNT_EXIST
+	#   NSConnector::Errors::InvalidSearchFilter:: on a
+	#   	SSS_INVALID_SRCH_FILTER
+	#   NSConnector::Errors::Conflict:: on a *_ALREADY_EXISTS
+	#   NSConnector::Errors::Unknown:: on any unhandled but parseable error
+	#   NSConnector::Errors::WTF:: on complete garbage from netsuite 
+	# 
+	# Returns:: Shouldn't return
+	def self.try_handle_response! response
+		error = JSON.parse(response.body)['error']
+		case error['code']
+		when 'RCRD_DSNT_EXIST'
+			raise NotFound, error
+		when 'SSS_INVALID_SRCH_FILTER'
+			raise InvalidSearchFilter, error
+		when /_ALREADY_EXISTS$/
+			raise Conflict, error
+		else
+			case error['message']
+			when 'CHUNKY_MONKEY'
+				raise BeginChunking, error
+			when 'NO_MORE_CHUNKS'
+				raise EndChunking, error
+			end
+			raise Unknown, error
+		end
+	rescue JSON::ParserError
+		raise WTF, 'Unparseable response, expecting JSON. '\
+			"HTTP #{response.code}: \n#{response.body}"
+	end
+end

data/lib/ns_connector/field_store.rb

@@ -0,0 +1,19 @@
+# Provides a method create_store_store_accessors! to make keys fields
+# accessible in @store
+module NSConnector::FieldStore
+	# Given fields of ['name'], we want to define a name= and a name
+	# method to retrieve and set the key 'name' in our @store
+	def create_store_accessors!
+		fields.each do |field|
+			self.class.class_eval do 
+				define_method field do
+					@store[field.to_s]
+				end
+
+				define_method "#{field}=" do |value|
+					@store[field.to_s] = value
+				end
+			end
+		end
+	end
+end

data/lib/ns_connector/hash.rb

@@ -0,0 +1,11 @@
+class Hash # :nodoc:
+	# Turn all our keys into strings. Good for our @stores as they use
+	# strings from keys seeing as anything coming from JSON has strings for
+	# keys
+	def stringify_keys!
+		keys.each do |key|
+			self[key.to_s] = delete(key)
+		end
+		self
+	end
+end

data/lib/ns_connector/resource.rb

@@ -0,0 +1,288 @@
+require 'ns_connector/restlet'
+require 'ns_connector/errors'
+require 'ns_connector/chunked_searching'
+require 'ns_connector/field_store'
+require 'ns_connector/hash'
+require 'ns_connector/sublist'
+require 'ns_connector/sublist_item'
+require 'ns_connector/attaching'
+
+# This is a 'meta' class that all our useful NetSuite classes inherit from,
+# overriding what they may need to. For example:
+# 	class Contact < Resource
+# 	        # The NetSuite internal id for the object. 
+#         	@type_id = 'contact'
+# 	end
+class NSConnector::Resource
+	include NSConnector::FieldStore
+	extend NSConnector::ChunkedSearching
+	extend NSConnector::Attaching
+
+	attr_accessor :store
+
+	def initialize upstream_store=nil, in_netsuite=false
+		upstream_store.stringify_keys! if upstream_store
+
+		@store = (upstream_store || {})
+		@sublist_store = {}
+
+		# This is set so that we can tell wether we need to create an
+		# entirely new netstuite object, or we are modifying an
+		# existing one.
+		@in_netsuite = in_netsuite
+
+		check_id10t_errors!
+		create_store_accessors!
+		create_sublist_accessors!
+	end
+
+	# Just so I don't forget to define certain things.
+	def check_id10t_errors!
+		unless fields then
+			raise ::ArgumentError,
+				"Inherited class #{self.class} needs to "\
+				"define @fields class instance variable"
+		end
+		# Type doesn't matter
+		unless fields.include? 'id' or fields.include? :id
+			raise ::ArgumentError,
+				"Inherited class #{self.class} must define "\
+				"an 'id' field"
+		end
+		unless type_id then
+			raise ::ArgumentError,
+				"Inherited class #{self.class} needs to "\
+				"define @type_id class instance variable"
+		end
+		unless sublists then
+			raise ::ArgumentError,
+				"Inherited class #{self.class} needs to "\
+				"define @sublists class instance variable"
+		end
+	end
+
+	# Retrieve class's internal id, e.g. 'contact' for a Contact Resource
+	def type_id
+		self.class.type_id
+	end
+
+	# List of all fields for class
+	def fields
+		self.class.fields
+	end
+
+	# List of all sublists for class
+	def sublists
+		self.class.sublists
+	end
+
+	# Attach ids on target klass to this record
+	# Arguments::
+	#   klass:: Target class to attach to, e.g. Contact
+	#   ids:: Array of ids to attach
+	#   attributes:: Optional attributes for attach, e.g. {:role => -5}
+	# Example::
+	# 	contact.attach!(Customer, [1198], {:role => 1})
+	def attach!(klass, ids, attributes=nil)
+		raise ::ArgumentError, 'Need an id to attach!' unless id
+		self.class.attach!(klass, id, ids, attributes)
+	end
+
+	# Detach ids on target klass to this record
+	# Arguments::
+	#   klass:: Target class to detach from, i.e. Contact
+	#   ids:: Array of ids to detach
+	def detach!(klass, ids)
+		raise ::ArgumentError, 'Need an id to detach!' unless id
+		self.class.detach!(klass, id, ids)
+	end
+
+	# Format an object like: '#<NSConnector::PseudoResource:1>'
+	def inspect
+		"#<NSConnector::#{self.class}:#{id.inspect}>"
+	end
+
+	# Is this resource already in NetSuite?
+	# Returns:: 
+	#   true:: if this resource has been retrieved from netsuite,
+	#   false:: if it is a new resource being created for the first time.
+	def in_netsuite?
+		@in_netsuite
+	end
+
+	# Save ourself to NetSuite.
+	#
+	# Raises:: NSConnector::Errors various errors if something explodes
+	# Returns:: true
+	def save!
+		@store = NSConnector::Restlet.execute!(
+			:action => in_netsuite? ? 'update' : 'create',
+			:type_id => type_id,
+			:fields => fields,
+			:data => @store
+		)
+		# If we got this far, we're definitely in NetSuite
+		@in_netsuite = true
+
+		return true
+	end
+
+	# Delete ourself from NetSuite
+	#
+	# Returns::
+	#   true:: If object deleted
+	#   false:: If object was not deleted as it never existed
+	def delete!
+		return false unless in_netsuite? 
+		fail 'Sanity check: resource should have an ID' unless id
+		self.class.delete!(id)
+
+		# We set our :id to nil as we don't have one anymore and it
+		# allows us to call save on our newly deleted record, in case
+		# we wanted to undelete or something crazy like that.
+		@store[:id] = nil
+		@in_netsuite = false
+
+		return true
+	end
+
+	class << self
+		# Provides accessibility to class instance variables
+		attr_reader :type_id
+		attr_reader :fields
+		attr_reader :sublists
+
+		# Delete a single ID from NetSuite
+		#
+		# Returns:: Nothing useful
+		# Raises:: Relevant exceptions on failure
+		def delete! id
+			NSConnector::Restlet.execute!(
+				:action => 'delete',
+				:type_id => type_id,
+				:data => {'id' => Integer(id)}
+			)
+		end
+
+		# Retrieve a single resource from NetSuite with +id+
+		def find id
+			self.new(
+				NSConnector::Restlet.execute!(
+					:action => 'retrieve',
+					:type_id => type_id,
+					:fields => fields,
+					:data => {'id' => Integer(id)}
+				),
+				true
+			)
+		end
+
+		# Retrieve all records, will most likely become a chunked
+		# search due to size
+		def all
+			advanced_search([])
+		end
+
+		# Perform a search by field, with value matching exactly
+		def search_by field, value
+			advanced_search([[field, nil, 'is', value]])
+		end
+
+		# Perform a flexible search. It is assumed you kind of know
+		# what you're doing here and create a filter (a SuiteScript
+		# nlobjSearchFilter)
+		# Example::
+		# 	Resource.advanced_search([
+		# 		['type_id', nil, 'greaterthan', 1000],
+		# 		['email', nil, 'contains', '@'],
+		# 		[...]
+		#	])
+		# Arguments::
+		#   +filters+:: An array of netsuite 'filters' see: +Filters+
+		#
+		# Filters::
+		#   A filter is simply an array that is sent as arguments to
+		#   the netsuite function +nlobjSearchFilter+
+		#
+		#   It often takes the form of:
+		#   	[field, join record type or nil, operator, value]
+		#
+		#   i.e:
+		#   	['internalid', nil, 'is', customer_id]
+		#
+		# Returns::
+		#   An array of +Resources+
+		def advanced_search filters
+			unless filters.is_a? Array
+				raise ::ArgumentError,
+					'Expected an Array of filters'
+			end
+
+			return NSConnector::Restlet.execute!(
+					:action => 'search',
+					:type_id => type_id,
+					:fields => fields,
+					:data => {:filters => filters}
+			).map do |upstream_store|
+				self.new(upstream_store, true)
+			end
+		rescue NSConnector::Errors::BeginChunking
+			# Result set is too large, we have to ask for
+			# it in offsets. Note that if the result set
+			# changes between requests say, at the
+			# beginning, we are going to get odd behaviour.
+			# Better than nothing, though.
+			#
+			# For this function, see:
+			# ns_connector/chunked_searching.rb
+			return search_by_chunks(filters)
+		end
+
+		# Quicker and more flexible than a normal search as it doesn't
+		# return whole objects, just the search columns specified as an
+		# array of arrays.
+		#
+		# Arguments::
+		# columns:: Array of requested colums, e.g.:
+		# 	[['role'], ['entityId', 'customer']] 
+		# filters:: Array of filters, same as #advanced_search, e.g.:
+		# 	[['entityId', 'customer', 'is', '296']]
+		# Returns:: Array of result columns, in an array. So an array
+		#   of arrays.
+		def raw_search columns, filters
+			return NSConnector::Restlet.execute!(
+					:action => 'raw_search',
+					:type_id => type_id,
+					:fields => fields,
+					:data => {
+						:columns => columns,
+						:filters => filters
+					}
+			)
+		end
+	end
+
+	private
+	# Given a sublist of {:addressbook => ['fields']} we want a method
+	# addressbook that looks up the sublist if we have an ID, otherwise
+	# returns an empty array.
+	def create_sublist_accessors!
+		sublists.each do |sublist_name, fields|
+			self.class.class_eval do
+				define_method sublist_name do
+					# We are an object in netsuite,
+					# we might just have sublist
+					# items already. So we check.
+					@sublist_store[sublist_name] ||= \
+						NSConnector::SubList.fetch(
+							self,
+							sublist_name,
+							fields
+						) if in_netsuite?
+
+					@sublist_store[sublist_name] ||= []
+				end
+			end
+		end
+	end
+end