ns_connector 0.0.6

data/Gemfile

@@ -0,0 +1,13 @@
+source 'http://rubygems.org'
+source 'http://packages.anchor.net.au/gems/'
+
+group :development do
+	gem 'rspec'
+	gem 'webmock'
+	gem 'rake'
+	gem 'jeweler'
+	gem 'bundler'
+	gem 'rdoc'
+	gem 'pry-debugger'
+	gem 'guard-rspec'
+end

data/Gemfile.lock

@@ -0,0 +1,80 @@
+GEM
+  remote: http://rubygems.org/
+  remote: http://packages.anchor.net.au/gems/
+  specs:
+    addressable (2.3.4)
+    coderay (1.0.9)
+    columnize (0.3.6)
+    crack (0.3.2)
+    debugger (1.5.0)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.2.0)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.2.0)
+    diff-lcs (1.2.4)
+    ffi (1.8.1)
+    formatador (0.2.4)
+    git (1.2.5)
+    guard (1.8.0)
+      formatador (>= 0.2.4)
+      listen (>= 1.0.0)
+      lumberjack (>= 1.0.2)
+      pry (>= 0.9.10)
+      thor (>= 0.14.6)
+    guard-rspec (3.0.1)
+      guard (>= 1.8)
+      rspec (~> 2.13)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.8.0)
+    listen (1.1.4)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+      rb-kqueue (>= 0.2)
+    lumberjack (1.0.3)
+    method_source (0.8.1)
+    pry (0.9.12.2)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    pry-debugger (0.2.2)
+      debugger (~> 1.3)
+      pry (~> 0.9.10)
+    rake (10.0.4)
+    rb-fsevent (0.9.3)
+    rb-inotify (0.9.0)
+      ffi (>= 0.5.0)
+    rb-kqueue (0.2.0)
+      ffi (>= 0.5.0)
+    rdoc (4.0.1)
+      json (~> 1.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    slop (3.4.5)
+    thor (0.18.1)
+    webmock (1.11.0)
+      addressable (>= 2.2.7)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  guard-rspec
+  jeweler
+  pry-debugger
+  rake
+  rdoc
+  rspec
+  webmock

data/Guardfile

@@ -0,0 +1,9 @@
+guard :rspec do
+	watch(%r{^spec/.+_spec\.rb$})
+	watch(%r{^lib/ns_connector/(.+)\.rb$}){ |m| 
+		puts "#{m[1]}"
+		"spec/#{m[1]}_spec.rb" 
+	}
+	watch('spec/spec_helper.rb'){ "spec" }
+end
+

data/HACKING

@@ -0,0 +1,31 @@
+Install your bundle:
+
+	bundle install
+
+Run guard:
+
+	bundle exec guard
+
+Or, run the tests manually:
+
+	bundle exec rspec
+
+* The restlet lives in support/restlet.rb
+* There are basic conformance tests for it in support/
+* You'll want a config in a file somewhere:
+
+	$ cat tmp/ns_config 
+	{
+		:account_id => '1234',
+		:email => 'email@site.com',
+		:password => 'secret',
+		:role => '5678',
+		:restlet_url => 'https://rest.netsuite.com/app/site/hosting/restlet.nl?script=setme&deploy=setme'
+		:valid_customer_id => 1234 # A test customer record for conformance tests
+	}
+
+* All of the development scripts and conformance tests are run the same way,
+  something like:
+
+	scripts/test_shell "$(cat tmp/ns_config)"
+

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (C) 2013 Christian Marie
+
+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,191 @@
+= NSConnector intro 
+This library provides an interface to NetSuite via RESTlets, i.e. SuiteScript .
+This appears to be a quicker and more reliable way of interfacing with NetSuite
+records than the SOAP API. 
+
+How is this different to the other netsuite connector gems out there?
+
+* Basically, it uses a javascript RESTlet to communicate as opposed to the SOAP
+  API, so it's completely different and exposes a separate API.
+* It's not built around auto generated WSDL which can make it easier to design
+  a usable API.
+* It can be concurrent, so it at least has the potential to scale. You can only
+  make one request at a time per user using the SOAP API. 
+* It's quicker. Not sure why, but the SOAP API is horrendously slow sometimes,
+  RESTlets seem to be quicker, for now.
+
+== Features
+* No dependencies
+* Read write for supported types
+* Flexible searching
+* Multithreaded chunked searching for retrieving large datasets
+* ActiveRecord (vaguely) alike interface
+* Read only sublist support.
+* Attaching and detaching records 
+* Invoice PDF generation.
+
+== Supported NetSuite types
+It's pretty trivial to add a new one yourself. These have been tested to work:
+* Contact
+* Customer
+* Invoice
+
+== Installation
+Install the RESTlet:
+  function post(request) {
+    func = eval(request.code);
+    return func(request);
+  }
+
+That's the whole RESTlet. Deploy it to NetSuite, ensuring that the POST
+function is set to 'post'. Note the 'External URL' when deploying it, that is
+what you will use in the configuration below.
+
+== Configuration
+The configuration is stored 'globally' via NSConnector::Config#set_config!
+
+An example config:
+  NSConnector::Config.set_config!({
+    :account_id  => '123',
+    :email       => 'email@site',
+    :password    => "password",
+    :role        => '456',
+    :restlet_url => 'https://netsuite/restlet',
+  })
+=== Options
+==== :account_id (mandatory)
+TODO: Document how to find an account ID.
+
+==== :email (mandatory)
+The email address you log into the NetSuite web site with that matches the
+account_id.
+
+==== :password (mandatory)
+Hopefully a secret.
+
+==== :role (mandatory)
+Can be found in your cookie when logged in, or deep within the jungle of the
+user interface.
+TODO: Document the perilous journey through the jungle.
+
+==== :use_threads (optional)
+A bool, set to false to turn off threading when retrieving large result sets.
+By default we try to split these result sets up into manageable chunks. If you
+turn this off, they will still be split up, but only one chunk will be
+retrieved at a time.
+
+==== :no_threads (optional)
+An integer, the number of threads to use. By default, 4.
+
+== CRUD usage
+Every supported type supports full CRUD via the same standard interface
+Check the SuiteScript Records Browser [1] for avaliable fields.
+
+=== Creating
+To create a record, simply instantiate a new class of that kind and call
+.save!  on it.
+
+Calling .save! will re-load the saved Record from NetSuite with any other
+changes that NetSuite's internal logic may have made.
+
+Example:
+
+  include NSConnector
+
+  c = Contact.new(:firstname => 'name')
+  => <#NSConnector::Contact:nil>
+
+  c.fields
+  => [fields...]
+  
+  c.lastname = 'abc'
+  => 'abc'
+
+  c.save!
+  => true
+
+  c.lastname
+  => 'Abc'
+
+=== Reading
+You can find by any field or by internalId.
+Example:
+
+  include NSConnector
+
+  # Search by any internal field ID, returns an array of Contacts
+  Contact.search_by('entityId', 42)
+  => [<#NSConnector::Contact:12>]
+
+  # Fetch one Contact by internalId
+  Contact.find(12)
+  => <#NSConnector::Contact:12>
+
+  # Fetch all Contacts, this will take a while. (Request will be broken
+  # up into smaller ones and spread across multiple threads).
+  Contact.all
+  => [rather large array of NSConnector::Contact]
+
+You can also perform more complex searces.
+Example:
+  Contact.advanced_search([
+    ['email', 'contains', '@'],
+    ['entityId', 'lessthanorequalto', '1000']
+  ])
+  => [<#NSConnector::Contact:12>, <#NS...]
+
+At any time you can check which fields are avaliable in both the class and
+instances:
+  Contact.fields
+  Contact.new.fields
+You can also access the raw data store to more easily see what the object
+contains with:
+  Contact.find(1234).store
+==== SubLists
+SubLists are exposed differently by the backend API, but that's pretty
+transparent to us, simply access them as a read only array:
+  Contact.addressbook.first.city
+You can see which sublists are avaliable to an object via the sublists
+accessor:
+  Contact.sublists
+  Customer.new.sublists
+
+=== Updating
+Updating records is much like creating new ones. Simply:
+1. Grab the record (see Reading).
+  c = Contact.find(12)
+2. Update the record to your liking.
+  c.lastname = 'newname'
+3. Save the record (see Creating)
+  c.save!
+  => true
+
+=== Deleting
+Deletion can be done by ID or Record.
+Example:
+
+1. By ID
+  Contact.delete!(42)
+  => true
+2. By Record
+  c = Contact.find(42)
+  c.delete!
+  
+=== Troubleshooting note:
+Should you run into an error something like:
+
+NSConnector::Restlet::RuntimeError: Failed to parse response from Restlet as
+JSON (): A JSON text must at least contain two octets!
+
+It may just be that your user is being denied access, in which case netsuite
+seems to believes it is a good idea to simply send a blank response.
+
+
+== Development notes
+See HACKING in the repo
+
+== License
+MIT
+
+== References
+[1] {SuiteScript Records Browser}[https://system.netsuite.com/help/helpcenter/en_US/RecordsBrowser/2013_1/index.html]

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'bundler'
+begin
+	Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+	warn e.message
+	warn "Run `bundle install` to install missing gems"
+	exit e.status_code
+end
+
+require 'rdoc/task'
+require 'jeweler'
+require 'rspec/core/rake_task'
+
+Jeweler::Tasks.new do |gem|
+	gem.name = "ns_connector"
+	gem.homepage = ""
+	gem.summary = "An interface to NetSuite records via RESTlets."
+	gem.description = "This library provides an interface to NetSuite via"\
+		"'RESTlets'. This appears to be a quicker and more reliable"\
+		"way of interfacing with NetSuite records than the SOAP API."
+	gem.authors = ["Christian Marie <pingu@anchor.com.au>"]
+	gem.license = 'MIT'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+task :default => :test
+RSpec::Core::RakeTask.new :test 
+
+task :deploy_to_hopper => [:build, :rdoc, :test] do
+	`scp pkg/ns_connector-$(cat VERSION).gem packages@hopper.engineroom.anchor.net.au:public_html/gems/gems/`
+	`ssh packages@hopper.engineroom.anchor.net.au "cd /home/packages/public_html/gems && make"`
+	if $?.to_i == 0 then
+		 puts "Deploy to hopper successful"
+	else
+	       raise RuntimeError, "Deploy failed :("
+	end
+end
+
+Rake::RDocTask.new do |rd|
+	rd.main = "README.rdoc"
+	rd.title = 'NSConnector documentation'
+	rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+	`scp -r html/* packages@hopper.engineroom.anchor.net.au:public_html/gems/docs/ns_connector/`
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.6

data/lib/ns_connector.rb

@@ -0,0 +1,4 @@
+module NSConnector
+end
+
+require 'ns_connector/resources'

data/lib/ns_connector/attaching.rb

@@ -0,0 +1,42 @@
+# Provide attach! and detach! methods
+module NSConnector::Attaching
+	# Attach any number of ids to klass
+	# Arguments:: 
+	#   klass:: target class to attach to, i.e. Contact
+	#   attachee_id:: internal id of the record to make the attach(s) to
+	#   ids:: array of target ids
+	#   attributes:: optional attributes for the attach, i.e. {:role => -5}
+	def attach!(klass, attachee_id, ids, attributes = nil)
+		unless ids.kind_of?(Array) then
+			raise ::ArgumentError, 
+				'Expected ids to be an array'
+		end
+		NSConnector::Restlet.execute!(
+			:action => 'attach',
+			:type_id => type_id,
+			:target_type_id => klass.type_id,
+			:attachee_id => attachee_id,
+			:attributes => attributes,
+			:data => ids
+		)
+	end
+
+	# Unattach any number of ids to klass
+	# Arguments:: 
+	#   klass:: target class to detach from, i.e. Contact
+	#   attachee_id:: internal id of the record to make the detach(s) from
+	#   ids:: array of target class ids 
+	def detach!(klass, attachee_id, ids)
+		unless ids.kind_of?(Array) then
+			raise ::ArgumentError, 
+				'Expected ids to be an array'
+		end
+		NSConnector::Restlet.execute!(
+			:action => 'detach',
+			:type_id => type_id,
+			:target_type_id => klass.type_id,
+			:attachee_id => attachee_id,
+			:data => ids
+		)
+	end
+end

data/lib/ns_connector/chunked_searching.rb

@@ -0,0 +1,111 @@
+# Provide threaded and non-threaded chunked searching
+module NSConnector::ChunkedSearching
+	# Retrieve a single chunk, this makes one HTTP connection
+	# Raises:: NSConnector::Errors::EndChunking when there's no more chunks
+	# Returns:: Resource objects
+	def grab_chunk(filters, chunk)
+		NSConnector::Restlet.execute!(
+			:action => 'search',
+			:type_id => type_id,
+			:data => {
+				:filters => filters,
+				:chunk => chunk,
+			}
+		).map do |upstream_store|
+			self.new(upstream_store)
+		end
+	end
+
+	# The basic logic here is, given four threads we have four workers,
+	# those workers keep eating chunks of data specified by the master.
+	# When a worker recieves a EndChunking error, it flags done as true and
+	# everyone wraps up thier work. Pretty simple.
+	def threaded_search_by_chunks(filters)
+		require 'thread'
+		threads = NSConnector::Config[:no_threads].to_i
+		if threads < 1 then
+			raise NSConnector::Config::ArgumentError, 
+				"Need more than #{threads} threads"
+		end
+
+		# We bother pre-populating the queue here because locking is
+		# super expensive, on my build of ruby at least.
+		queue = Queue.new
+		(threads - 1).times do |i|
+			queue << i
+		end
+
+		mutex = Mutex.new
+
+		workers = []
+		results = []
+		current_chunk = threads - 1
+		done = false
+
+		# Workers
+		threads.times do
+			workers << Thread.new do
+				until done
+					begin
+						# Avoid a deadlock by popping
+						# off -1 to exit
+						chunk = queue.pop 
+						break if chunk == -1
+
+						result = grab_chunk(
+							filters, chunk
+						)
+					rescue NSConnector::Errors::EndChunking
+						done = true
+						break
+					end
+
+					mutex.synchronize do
+						results += result
+					end
+				end
+			end
+		end
+
+		# Master
+		until done
+			if queue.empty? then
+				queue << current_chunk
+				current_chunk += 1
+			end
+		end
+
+		threads.times do 
+			queue << -1
+		end
+
+		workers.each do |worker|
+			worker.join
+		end
+
+		return results
+	end
+
+	# Just keep grabbing incremental chunks till we're told to stop.
+	def normal_search_by_chunks(filters)
+		results = []
+		chunk = 0
+		while true
+			begin
+				results += grab_chunk(filters, chunk)
+				chunk += 1
+			end
+		end
+	rescue NSConnector::Errors::EndChunking
+		return results
+	end
+
+	# Search by requesting chunks
+	def search_by_chunks filters
+		if NSConnector::Config[:use_threads] then
+			return threaded_search_by_chunks(filters)
+		else
+			return normal_search_by_chunks(filters)
+		end
+	end
+end