netsuite-soap 2025.2.3

data/docs/usage.md

@@ -0,0 +1,149 @@
+# Usage
+
+## CRUD
+
+```ruby
+# get
+customer = NetSuite::Records::Customer.get(4)
+
+# get list
+customers = NetSuite::Records::Customer.get_list(list: [4, 5, 6])
+
+# add
+task = NetSuite::Records::Task.new(
+  title: 'Follow up',
+  assigned: NetSuite::Records::RecordRef.new(internal_id: 12345),
+  due_date: DateTime.now + 1,
+  message: 'Take care of this'
+)
+task.add
+
+# update
+task.update(message: 'New message')
+
+# delete
+task.delete
+
+# refresh after add
+task.refresh
+```
+
+## Search
+
+```ruby
+# basic
+search = NetSuite::Records::Customer.search(
+  basic: [
+    { field: 'companyName', operator: 'contains', value: 'Acme' }
+  ]
+)
+
+# with pagination
+search = NetSuite::Records::Customer.search(
+  criteria: {
+    basic: [{ field: 'isInactive', value: false }]
+  },
+  preferences: { page_size: 10 }
+)
+
+search.results_in_batches do |batch|
+  puts batch.map(&:internal_id)
+end
+
+# custom records
+NetSuite::Records::CustomRecord.search(
+  basic: [
+    {
+      field: 'recType',
+      operator: 'is',
+      value: NetSuite::Records::CustomRecordRef.new(internal_id: 10),
+    }
+  ]
+).results
+
+# saved search
+NetSuite::Records::Customer.search(
+  saved: 500,
+  basic: [
+    { field: 'entityId', operator: 'hasKeywords', value: 'Assumption' }
+  ]
+).results
+
+# joins
+NetSuite::Records::SalesOrder.search(
+  criteria: {
+    basic: [
+      { field: 'type', operator: 'anyOf', value: ['_salesOrder'] },
+      { field: 'status', operator: 'anyOf', value: ['_salesOrderPendingApproval'] },
+    ],
+    accountJoin: [
+      { field: 'internalId', operator: 'noneOf', value: [NetSuite::Records::Account.new(internal_id: 215)] }
+    ]
+  }
+)
+```
+
+## Custom records and fields
+
+```ruby
+# custom fields — you must set ALL custom fields, not just the ones you're updating
+contact = NetSuite::Records::Contact.get(12345)
+contact.custom_field_list.custentity_alistfield = { internal_id: 1 }
+contact.custom_field_list.custentity_abooleanfield = true
+contact.update(custom_field_list: contact.custom_field_list)
+
+# custom record get
+record = NetSuite::Records::CustomRecord.get(type_id: 10, internal_id: 100)
+
+# custom record add
+record = NetSuite::Records::CustomRecord.new
+record.rec_type = NetSuite::Records::CustomRecord.new(internal_id: 10)
+record.custom_field_list.custrecord_locationstate = "New Jersey"
+record.add
+```
+
+## Null fields
+
+```ruby
+invoice = NetSuite::Records::Invoice.get(12345)
+invoice.update(null_field_list: 'shipMethod')
+invoice.update(null_field_list: ['shipAddressList', 'shipMethod'])
+```
+
+## Files
+
+```ruby
+file = NetSuite::Records::File.new(
+  content: Base64.encode64(File.read('/path/to/file')),
+  name: 'Invoice.pdf',
+)
+file.add
+
+invoice = NetSuite::Records::Invoice.get(internal_id: 1)
+invoice.attach_file(NetSuite::Records::RecordRef.new(internal_id: file.internal_id))
+```
+
+## Select values
+
+```ruby
+NetSuite::Records::BaseRefList.get_select_value(
+  recordType: 'serviceSaleItem',
+  field: 'taxSchedule'
+)
+```
+
+## Deleted records
+
+```ruby
+response = NetSuite::Records::LotNumberedInventoryItem.get_deleted(
+  criteria: [
+    { field: 'type', operator: 'anyOf', value: 'lotNumberedInventoryItem' }
+  ]
+)
+```
+
+## Raw SOAP calls
+
+```ruby
+NetSuite::Configuration.connection.call :get_server_time
+```

data/lib/netsuite/actions/abstract_action.rb

@@ -0,0 +1,32 @@
+module NetSuite
+  module Actions
+    class AbstractAction
+      def request(credentials={})
+        NetSuite::Client.call(action_name, message: request_body, request_options: request_options, credentials: credentials, soap_header_extra_info: soap_header_extra_info)
+      end
+
+      protected
+
+      def action_name
+        raise NotImplementedError, 'Not implemented on abstract class'
+      end
+
+      def initialize
+        raise NotImplementedError, 'Not implemented on abstract class'
+      end
+
+      def request_body
+        raise NotImplementedError, 'Not implemented on abstract class'
+      end
+
+      def request_options
+        {}
+      end
+
+      def soap_header_extra_info
+        {}
+      end
+    end
+  end
+end
+  

data/lib/netsuite/actions/add.rb

@@ -0,0 +1,93 @@
+# https://system.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteTalkWebServices/add.html
+module NetSuite
+  module Actions
+    class Add < AbstractAction
+      include Support::Requests
+
+      def initialize(object = nil)
+        @object = object
+      end
+
+      private
+
+      # <soap:Body>
+      #   <platformMsgs:add>
+      #     <platformMsgs:record xsi:type="listRel:Customer">
+      #       <listRel:entityId>Shutter Fly</listRel:entityId>
+      #       <listRel:companyName>Shutter Fly, Inc</listRel:companyName>
+      #     </platformMsgs:record>
+      #   </platformMsgs:add>
+      # </soap:Body>
+
+      def request_body
+        hash = {
+          'platformMsgs:record' => {
+            :content! => @object.to_record,
+            '@xsi:type' => @object.record_type
+          }
+        }
+
+        if @object.respond_to?(:internal_id) && @object.internal_id
+          hash['platformMsgs:record']['@platformMsgs:internalId'] = @object.internal_id
+        end
+
+        if @object.respond_to?(:external_id) && @object.external_id
+          hash['platformMsgs:record']['@platformMsgs:externalId'] = @object.external_id
+        end
+
+        hash
+      end
+
+      def success?
+        @success ||= response_hash[:status][:@is_success] == 'true'
+      end
+
+      def response_body
+        @response_body ||= if response_hash[:base_ref].is_a?(Nori::StringIOFile)
+          { :@internal_id => Nokogiri::XML(@response.to_s).remove_namespaces!.at_xpath('//baseRef')[:internalId] }
+        else
+          response_hash[:base_ref]
+        end
+      end
+
+      def response_errors
+        if response_hash[:status] && response_hash[:status][:status_detail]
+          @response_errors ||= errors
+        end
+      end
+
+      def response_hash
+        @response_hash ||= @response.to_hash[:add_response][:write_response]
+      end
+
+      def action_name
+        :add
+      end
+
+      def errors
+        error_obj = response_hash[:status][:status_detail]
+        error_obj = [error_obj] if error_obj.class == Hash
+        error_obj.map do |error|
+          next if error.keys == [:after_submit_failed]
+          NetSuite::Error.new(error)
+        end.compact
+      end
+
+      module Support
+        def add(credentials={})
+          response = NetSuite::Actions::Add.call([self], credentials)
+
+          @errors = response.errors
+
+          if response.success?
+            @internal_id = response.body[:@internal_id]
+            true
+          else
+            false
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/netsuite/actions/async_add_list.rb

@@ -0,0 +1,74 @@
+# https://system.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteTalkWebServices/asyncAddList.html
+module NetSuite
+  module Actions
+    class AsyncAddList < AbstractAction
+      include Support::Requests
+      include AsyncResponse
+
+      MAX_RECORDS = 400
+
+      def initialize(*objects)
+        if objects.size > MAX_RECORDS
+          raise ArgumentError, "asyncAddList supports a maximum of #{MAX_RECORDS} records per request (#{objects.size} given)"
+        end
+        @objects = objects
+      end
+
+      private
+
+      def request_body
+        attrs = @objects.map do |o|
+          hash = o.to_record.merge({
+            '@xsi:type' => o.record_type
+          })
+
+          if o.respond_to?(:internal_id) && o.internal_id
+            hash['@internalId'] = o.internal_id
+          end
+
+          if o.respond_to?(:external_id) && o.external_id
+            hash['@externalId'] = o.external_id
+          end
+
+          hash
+        end
+
+        { 'record' => attrs }
+      end
+
+      def async_response_key
+        :async_add_list_response
+      end
+
+      def action_name
+        :async_add_list
+      end
+
+      module Support
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def async_add_list(records, credentials = {})
+            netsuite_records = records.map do |r|
+              if r.kind_of?(self)
+                r
+              else
+                self.new(r)
+              end
+            end
+
+            response = NetSuite::Actions::AsyncAddList.call(netsuite_records, credentials)
+
+            if response.success?
+              response.body
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netsuite/actions/async_delete_list.rb

@@ -0,0 +1,40 @@
+# https://system.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteTalkWebServices/asyncDeleteList.html
+module NetSuite
+  module Actions
+    class AsyncDeleteList < DeleteList
+      include AsyncResponse
+
+      private
+
+      MAX_RECORDS = 400
+
+      def initialize(klass, options = {})
+        list = options.is_a?(Hash) ? (options[:list] || []) : Array(options)
+        if list.size > MAX_RECORDS
+          raise ArgumentError, "asyncDeleteList supports a maximum of #{MAX_RECORDS} records per request (#{list.size} given)"
+        end
+        super
+      end
+
+      def async_response_key
+        :async_delete_list_response
+      end
+
+      def action_name
+        :async_delete_list
+      end
+
+      module Support
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def async_delete_list(options = { }, credentials={})
+            NetSuite::Actions::AsyncDeleteList.call([self, options], credentials)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netsuite/actions/async_get_list.rb

@@ -0,0 +1,46 @@
+# https://system.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteTalkWebServices/asyncGetList.html
+module NetSuite
+  module Actions
+    class AsyncGetList < GetList
+      include AsyncResponse
+
+      private
+
+      MAX_RECORDS = 2000
+
+      def initialize(klass, options = {})
+        list = options.is_a?(Hash) ? (options[:list] || []) : Array(options)
+        if list.size > MAX_RECORDS
+          raise ArgumentError, "asyncGetList supports a maximum of #{MAX_RECORDS} records per request (#{list.size} given)"
+        end
+        super
+      end
+
+      def async_response_key
+        :async_get_list_response
+      end
+
+      def action_name
+        :async_get_list
+      end
+
+      module Support
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def async_get_list(options = { }, credentials={})
+            response = NetSuite::Actions::AsyncGetList.call([self, options], credentials)
+
+            if response.success?
+              response.body
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netsuite/actions/async_initialize_list.rb

@@ -0,0 +1,85 @@
+# https://system.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteTalkWebServices/asyncInitializeList.html
+module NetSuite
+  module Actions
+    class AsyncInitializeList < AbstractAction
+      include Support::Requests
+      include AsyncResponse
+
+      def initialize(*entries)
+        @entries = entries
+      end
+
+      private
+
+      def request_body
+        initialize_records = @entries.map do |entry|
+          klass, object = normalize_entry(entry)
+
+          {
+            'platformCore:type'      => NetSuite::Support::Records.netsuite_type(klass),
+            'platformCore:reference' => {},
+            :attributes!             => {
+              'platformCore:reference' => {
+                'internalId' => object.internal_id,
+                :type        => NetSuite::Support::Records.netsuite_type(object)
+              }
+            }
+          }
+        end
+
+        {
+          'platformMsgs:initializeRecord' => initialize_records
+        }
+      end
+
+      def normalize_entry(entry)
+        case entry
+        when Array
+          entry
+        when Hash
+          klass = entry[:type] || entry[:klass] || entry[:record_type]
+          object = entry[:reference] || entry[:object]
+          [klass, object]
+        else
+          raise ArgumentError, "initialize list entries must be an Array or Hash"
+        end
+      end
+
+      def async_response_key
+        :async_initialize_list_response
+      end
+
+      def request_options
+        {
+          namespaces: {
+            'xmlns:platformMsgs'    => "urn:messages_#{NetSuite::Configuration.api_version}.platform.webservices.netsuite.com",
+            'xmlns:platformCore'    => "urn:core_#{NetSuite::Configuration.api_version}.platform.webservices.netsuite.com",
+            'xmlns:platformCoreTyp' => "urn:types.core_#{NetSuite::Configuration.api_version}.platform.webservices.netsuite.com",
+          }
+        }
+      end
+
+      def action_name
+        :async_initialize_list
+      end
+
+      module Support
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def async_initialize_list(records, credentials = {})
+            response = NetSuite::Actions::AsyncInitializeList.call(records, credentials)
+
+            if response.success?
+              response.body
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netsuite/actions/async_response.rb

@@ -0,0 +1,52 @@
+module NetSuite
+  module Actions
+    module AsyncResponse
+      private
+
+      def response_hash
+        @response_hash ||= begin
+          body = @response.body
+          if body.is_a?(Hash) && async_response_key && body[async_response_key]
+            body = body[async_response_key]
+          end
+          body.is_a?(Hash) ? (body[async_result_key] || body) : body
+        end
+      end
+
+      def response_body
+        @response_body ||= response_hash
+      end
+
+      def response_errors
+        if response_hash.is_a?(Hash) && response_hash[:status].is_a?(Hash) && response_hash[:status][:status_detail]
+          @response_errors ||= errors
+        end
+      end
+
+      def errors
+        error_obj = response_hash[:status][:status_detail]
+        error_obj = [error_obj] if error_obj.class == Hash
+        error_obj.map do |error|
+          NetSuite::Error.new(error)
+        end
+      end
+
+      def success?
+        return false unless response_hash.is_a?(Hash)
+
+        status = response_hash[:status]
+        return true unless status.is_a?(Hash) && status.key?(:@is_success)
+
+        status[:@is_success] == 'true'
+      end
+
+      def async_response_key
+        nil
+      end
+
+      def async_result_key
+        :async_status_result
+      end
+    end
+  end
+end

data/lib/netsuite/actions/async_search.rb

@@ -0,0 +1,36 @@
+# https://system.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteTalkWebServices/asyncSearch.html
+module NetSuite
+  module Actions
+    class AsyncSearch < Search
+      include AsyncResponse
+
+      private
+
+      def async_response_key
+        :async_search_response
+      end
+
+      def action_name
+        :async_search
+      end
+
+      module Support
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def async_search(options = { }, credentials={})
+            response = NetSuite::Actions::AsyncSearch.call([self, options], credentials)
+
+            if response.success?
+              response.body
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/netsuite/actions/async_update_list.rb

@@ -0,0 +1,53 @@
+# https://system.netsuite.com/help/helpcenter/en_US/Output/Help/SuiteCloudCustomizationScriptingWebServices/SuiteTalkWebServices/asyncUpdateList.html
+module NetSuite
+  module Actions
+    class AsyncUpdateList < UpdateList
+      include AsyncResponse
+
+      private
+
+      MAX_RECORDS = 200
+
+      def initialize(*objects)
+        if objects.size > MAX_RECORDS
+          raise ArgumentError, "asyncUpdateList supports a maximum of #{MAX_RECORDS} records per request (#{objects.size} given)"
+        end
+        super
+      end
+
+      def async_response_key
+        :async_update_list_response
+      end
+
+      def action_name
+        :async_update_list
+      end
+
+      module Support
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def async_update_list(records, credentials = {})
+            netsuite_records = records.map do |r|
+              if r.kind_of?(self)
+                r
+              else
+                self.new(r)
+              end
+            end
+
+            response = NetSuite::Actions::AsyncUpdateList.call(netsuite_records, credentials)
+
+            if response.success?
+              response.body
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end