netsuite-soap 2025.2.3

data/HISTORY.md

@@ -0,0 +1,171 @@
+## Unreleased
+
+## v2025.2.3
+
+### Added
+* Publish to RubyGems.org as `netsuite-soap` (gem name changed from `netsuite`)
+* RubyGems.org is now the recommended install source; GitHub Packages remains available
+
+## v2025.2.2
+
+### Added
+* `GetAll` action spec with fixtures (`Currency` success/error + class method coverage)
+
+### Fixed
+* Search action no longer leaks `:preferences` key into criteria iteration when both `saved:` and `preferences:` options are passed together
+* Move `refresh_spec.rb` to `spec/netsuite/support/` (matches `Support::Records` mixin where `#refresh` lives)
+
+### Breaking Changes
+* **Ruby**: Requires Ruby 3.4.x (`~> 3.4`). CI matrix updated to Ruby 3.4 only.
+
+## v2025.2.0
+
+### Added
+* Asynchronous bulk SOAP operations: submit → poll → fetch pattern via `CheckAsyncStatus` and `GetAsyncResult`
+* `AsyncAddList` action (up to 400 records per job); record classes can declare `actions :async_add_list`
+* `AsyncUpdateList` (up to 200 records), `AsyncUpsertList` (up to 200), `AsyncDeleteList` (up to 400), `AsyncGetList` (up to 2000)
+* `AsyncSearch` and `AsyncInitializeList` actions
+* `AsyncResponse` mixin for async action response parsing (`asyncStatusResult` / `asyncResult` envelope shape)
+* README section "Async bulk operations" with submit/poll/fetch example and per-operation limits
+* SOAP 2025.2 WSDL/XSD fixtures under `spec/support/fixtures/soap/v2025_2_0/` for Savon specs
+
+### Fixed
+* README: correct `multi_tentant!` → `multi_tenant!` in Multi-Tenancy example
+
+### Breaking Changes
+* **API version**: Only `api_version '2025_2'` is supported (NetSuite SOAP 2025.2 is the final endpoint; SOAP removed 2028.2). Other versions raise `ConfigurationError`.
+* **Ruby**: Requires Ruby 3.1.0 or later (Gemfile `ruby '>= 3.1.0'`).
+* **Removed**: `NetSuite::Actions::Login` and `login` action (no longer used by the client).
+
+## v0.9.4
+
+### Added
+* Add `get_deleted` action to `CustomerCategory` (#595)
+* Add `get_deleted` action to `Customer` (#605)
+
+### Fixed
+* Revert recent proxy changes which breaks proxy usage by @andrewdicken-stripe in https://github.com/NetSweet/netsuite/pull/579
+
+## v0.9.3
+
+### Added
+* Create abstract action parent class by @andrewdicken-stripe in https://github.com/NetSweet/netsuite/pull/568
+
+### Fixed
+* Add department, klass and location EstimateItem/record_refs by @nickdufresne in https://github.com/NetSweet/netsuite/pull/572
+* Invoice shipping_tax_code should be a record_ref by @stevewoodcock in https://github.com/NetSweet/netsuite/pull/573
+* dont crash if suitetalk returns empty <platformCore:searchRowList/> by @ericcj in https://github.com/NetSweet/netsuite/pull/574
+* Add :klass field to record VendorReturnAuthorizationItem & VendorReturnAuthorization by @shubhrathasetty in https://github.com/NetSweet/netsuite/pull/576
+* Optionally pass in `proxy` parameter to Savon by @dbecker-stripe in https://github.com/NetSweet/netsuite/pull/548
+
+## v0.9.2
+
+### Fixed
+
+* Update rspec requirement from ~> 3.11.0 to ~> 3.12.0 by @dependabot in https://github.com/NetSweet/netsuite/pull/567
+* [Adding UK country mapping](https://github.com/NetSweet/netsuite/commit/5fe96ed28fb8341b6926e169cf50d817632b5b8d)
+
+### Breaking Changes
+
+* [remove country mapping hack for old API versions](https://github.com/NetSweet/netsuite/commit/a0357f0a9e08eb3a4a80f1d1e7a37f95bcb17d4f)
+
+## v0.9.1
+
+### Added
+* Add `Configuration#multi_tenant!` for opting into multi-tentant support where configuration/caching is per-thread (#556)
+
+### Fixed
+* Avoid Savon version `2.13.0` to prevent generating invalid envelopes. (#558, #563)
+* Retry on `HTTPI::SSLError` and `HTTPI::TimeoutError` in backoff (#566)
+
+### Breaking Changes
+* Update default API version to 2016_2 from 2015_1 when `api_version` is not explicitly set (#554)
+
+## 0.9.0
+
+### Added
+
+* Update `Customer` record fields/record refs for 2021.2. (#535)
+The following were moved from `fields` to `record_refs`: `buying_reason`, `buying_time_frame`, `campaign_category`, `image`, `opening_balance_account`, `pref_cc_processor`, `representing_subsidiary`, `sales_group`, `sales_readiness`
+The following were removed as `fields` since their sublist class is not yet implemented: `download_list`, `group_pricing_list`, `item_pricing_list`
+* Add search-only fields to `Customer` (#535)
+* Add `attach_file` action to `Customer` records (#544)
+* Add `update` action to `File` records (#544)
+* Expose `errors` after calls to `delete` action (#545)
+* Add `update_list` action where missing on supported item records (#546)
+* Add `proxy` attribute to `NetSuite::Configuration` to set a proxy used by the savon client (#547)
+
+### Fixed
+* Ignore `after_submit_failed` status details (>= 2018.2) when collating errors in add action (#550)
+* Add `NullFieldList` to `SalesOrder` (#552)
+* Add thread safety to NetSuite configuration and utilities (#549)
+
+### Breaking Changes
+* Rename `CustomerSubscriptionsList` to `SubscriptionsList` and `CustomerSubscription` to `Subscription` to match NetSuite naming (#535)
+
+## 0.8.12
+
+### Added
+
+* Add NullFieldList record (to credit memos and invoices) (#529)
+* Add `get_deleted` action to item records (#530)
+* Add `get_deleted` action to Employee records (#531)
+* Remove monkey patched `lower_camelcase` method on String (#533)
+
+## 0.8.11
+
+### Added
+
+* Update ServiceResaleItem record fields/record refs for 2021.2. `item_options_list`, `presentation_item_list`, `site_category_list`, `translations_list` were all removed as fields as the are not simple fields, they require special classes. (#500)
+* Dependabot to CI
+* CI run for Ruby 3.0 & 3.1
+* Add CI run for an environment with and without `tzinfo` installed
+* Update NonInventorySaleItem record fields/record refs for 2021.2. `item_options_list`, `presentation_item_list`, `product_feed_list`, `site_category_list`, `translations_list` were all removed as fields as the are not simple fields, they require special classes. (#503)
+* Implement MatrixOptionList#to_record (#504)
+* Update ItemVendor record fields/record refs for 2021.1. `vendor` is now a record_ref instead of a field. (#505)
+* Update InventoryItem record fields/record refs for 2021.2. `member_list` was removed as a field as it doesn't belong to InventoryItem. (#506)
+* Update LotNumberedInventoryItem record fields/record refs for 2021.2. (#507)
+* Update NonInventoryResaleItem record fields/record refs for 2021.2. `item_options_list`, `presentation_item_list`, `product_feed_list`, `site_category_list`, `translations_list` were all removed as fields as the are not simple fields, they require special classes. (#508)
+* Add `attach_file` action for Invoice and SalesOrder. (#509)
+* Add ItemOptionCustomField recrd (#512)
+* Add Ship Address to Return Authorization (#525)
+* Support translations records (#516)
+
+### Fixed
+
+* Fix "undefined method `[]` for #<Nori::StringIOFile>" when adding File (#495)
+* Moved definition of `search_joins` attribute from records to search action. The attribute was removed for AssemblyComponent, SerializedInventoryItemLocation, and WorkOrderItem as they don't offer the search action. (#511)
+* Consider externalId in search criteria when using RecordRef as value (#517)
+* Retry http client error subclasses
+* Add upsert list action for cash sales (#523)
+
+## 0.8.10
+
+### Added
+
+* Update Estimate record fields/record refs for 2021.2. `balance`, `bill_address`, `bill_is_residential`, and `is_multi_ship_to` were all removed as fields as either being incorrect, outdated, or a search-only field. (#496)
+
+### Fixed
+
+* Savon 2.12 supported
+
+## 0.8.9
+
+### Fixed
+
+* Fixed issue where search only fields could be specified when an existing field exists. https://github.com/NetSweet/netsuite/pull/488
+
+## 0.8.8
+
+### Added
+
+* Adding serialized assembly item to get_item
+* Add CostCategory record (#482)
+* Introduce search only fields (#483)
+
+### Fixed
+
+* Fix accessing custom field values returned in advanced search results (#480)
+* Fixing bug where single-selection custom multi select fields would incorrectly be parsed 3377c971d0cb727d81f4b4bc6e30edfbdfaccfd1
+* Fixed some field definitions on serialized assembly item
+* Properly extract external_id from advanced search results (#478)

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2026 Robert DeLanghe
+
+MIT License
+
+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.md

@@ -0,0 +1,87 @@
+[![Ruby](https://github.com/bdelanghe/netsuite/actions/workflows/main.yml/badge.svg)](https://github.com/bdelanghe/netsuite/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/netsuite-soap.svg)](https://rubygems.org/gems/netsuite-soap)
+[![GitHub Package](https://img.shields.io/badge/github-packages-blue?logo=github)](https://github.com/bdelanghe/netsuite/packages)
+![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/bdelanghe/netsuite/badges/coverage.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby Version](https://img.shields.io/badge/ruby-~%3E%203.4-red)](https://github.com/bdelanghe/netsuite/blob/main/netsuite.gemspec)
+
+# netsuite
+
+Ruby gem for the NetSuite SuiteTalk SOAP API (v2025.2) with async bulk operations. Maintained fork of [NetSweet/netsuite](https://github.com/NetSweet/netsuite).
+
+## Status
+
+This gem targets **SOAP 2025.2** — the final supported endpoint. SOAP is removed from NetSuite in 2028.2. This gem exists to bridge existing integrations through that timeline; it is not for new projects.
+
+| Release | What happens |
+|---------|-------------|
+| **2025.2** | Last planned SOAP endpoint |
+| **2027.1** | Only 2025.2 supported |
+| **2028.2** | SOAP removed entirely |
+
+New integrations should use [SuiteTalk REST Web Services](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_1540391670.html) with OAuth 2.0.
+
+## Install
+
+### RubyGems.org (recommended)
+
+```ruby
+# Gemfile
+gem "netsuite-soap"
+```
+
+Or from the command line:
+
+```shell
+gem install netsuite-soap
+```
+
+### GitHub Packages
+
+```ruby
+# Gemfile
+source "https://rubygems.pkg.github.com/bdelanghe" do
+  gem "netsuite"
+end
+```
+
+Or from the command line:
+
+```shell
+gem install netsuite --source "https://rubygems.pkg.github.com/bdelanghe"
+```
+
+Requires Ruby 3.4.
+
+## Quick start
+
+```ruby
+NetSuite.configure do
+  reset!
+  account       ENV['NETSUITE_ACCOUNT']
+  api_version   '2025_2'
+  consumer_key     ENV['NETSUITE_CONSUMER_KEY']
+  consumer_secret  ENV['NETSUITE_CONSUMER_SECRET']
+  token_id         ENV['NETSUITE_TOKEN_ID']
+  token_secret     ENV['NETSUITE_TOKEN_SECRET']
+end
+
+customer = NetSuite::Records::Customer.get(4)
+```
+
+See [docs/configuration.md](docs/configuration.md) for all options (WSDL, sandbox, multi-tenancy, logging).
+
+## Async bulk operations
+
+For large operations, submit a job and poll for results rather than waiting on a single long-running request. See [docs/async.md](docs/async.md).
+
+## Documentation
+
+- [Configuration](docs/configuration.md) — WSDL, auth, sandbox, multi-tenancy
+- [Async bulk operations](docs/async.md) — submit/poll/fetch pattern, available operations
+- [Usage](docs/usage.md) — CRUD, search, custom records, null fields, files
+- [Contributing](docs/contributing.md) — Testing, development setup
+
+## Credits
+
+Based on [NetSweet/netsuite](https://github.com/NetSweet/netsuite). Thanks to the original contributors.

data/Rakefile

@@ -0,0 +1,130 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run specs'
+RSpec::Core::RakeTask.new do |t|
+  # t.pattern = './spec/**/*_spec.rb'
+end
+
+namespace :fixtures do
+  # Sources:
+  #   https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_3892701016.html
+  #   https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N3413913.html
+  # SOAP is deprecated — 2025.2 is the last planned endpoint (removed in 2028.2).
+  WSDL_VERSIONS = {
+    # Final endpoint — all integrations should target this
+    'v2025_2_0' => { status: :final },
+    # Supported
+    'v2025_1_0' => { status: :supported },
+    'v2024_2_0' => { status: :supported },
+    'v2024_1_0' => { status: :supported },
+    'v2023_2_0' => { status: :supported },
+    'v2023_1_0' => { status: :supported },
+    'v2022_2_0' => { status: :supported },
+    # Unsupported but still available
+    'v2022_1_0' => { status: :unsupported },
+    'v2021_2_0' => { status: :unsupported },
+    'v2021_1_0' => { status: :unsupported },
+    'v2020_2_0' => { status: :unsupported },
+    'v2020_1_0' => { status: :unsupported },
+    'v2019_2_0' => { status: :unsupported },
+    'v2019_1_0' => { status: :unsupported },
+    'v2018_2_0' => { status: :unsupported }
+  }.freeze
+
+  BASE_URL      = 'https://webservices.netsuite.com'.freeze
+  DOWNLOAD_BASE = 'https://content.netsuite.com/download'.freeze
+
+  def wsdl_url(version)
+    "#{BASE_URL}/wsdl/#{version}/netsuite.wsdl"
+  end
+
+  def zip_url(version)
+    "#{DOWNLOAD_BASE}/WSDL_#{version}.zip"
+  end
+
+  desc 'Download WSDL fixtures and all referenced XSD schemas for spec use. ' \
+       'Set VERSION=v2025_2_0 to fetch a single version. ' \
+       'Set WSDL_SOURCE=<dir> to copy from a local directory instead of downloading.'
+  task :wsdl do
+    require 'open-uri'
+    require 'fileutils'
+    require 'rexml/document'
+    require 'tmpdir'
+    require 'uri'
+    require 'zip'
+
+    fixtures_root = File.join('spec', 'support', 'fixtures')
+    local_source  = ENV['WSDL_SOURCE']
+
+    versions = if ENV['VERSION']
+      WSDL_VERSIONS.slice(ENV['VERSION']).tap do |v|
+        abort "Unknown VERSION '#{ENV['VERSION']}'. Available: #{WSDL_VERSIONS.keys.join(', ')}" if v.empty?
+      end
+    else
+      WSDL_VERSIONS
+    end
+
+    versions.each_key do |version|
+      soap_root = File.join(fixtures_root, 'soap', version)
+
+      if local_source
+        install_from_dir(local_source, soap_root)
+      else
+        install_from_zip(zip_url(version), soap_root)
+      end
+    end
+  end
+
+  # Install from the official NetSuite zip (https://content.netsuite.com/download/WSDL_<version>.zip).
+  # The zip contains a flat directory of files with dotted naming: <category>.<file>.xsd
+  def install_from_zip(url, soap_root)
+    Dir.mktmpdir do |tmp|
+      zip_path = File.join(tmp, 'wsdl.zip')
+      puts "Downloading #{url}"
+      URI.open(url) { |f| File.binwrite(zip_path, f.read) }
+
+      puts "Extracting to #{soap_root}"
+      Zip::File.open(zip_path) do |zip|
+        zip.each do |entry|
+          next if entry.directory?
+          install_entry(entry.name, entry.get_input_stream.read, soap_root)
+        end
+      end
+    end
+  end
+
+  # Copy from a pre-extracted local directory (flat dotted naming convention).
+  def install_from_dir(source_dir, soap_root)
+    Dir[File.join(source_dir, '*')].each do |src|
+      install_entry(File.basename(src), File.binread(src), soap_root)
+    end
+  end
+
+  # Route a single flat filename to its structured destination.
+  # netsuite.wsdl             -> wsdl/netsuite.wsdl
+  # platform.core.xsd         -> xsd/platform/core.xsd
+  # transactions.sales.xsd    -> xsd/transactions/sales.xsd
+  def install_entry(filename, content, soap_root)
+    dest = if filename == 'netsuite.wsdl'
+      File.join(soap_root, 'wsdl', 'netsuite.wsdl')
+    else
+      category, rest = filename.split('.', 2)
+      File.join(soap_root, 'xsd', category, rest)
+    end
+
+    FileUtils.mkdir_p(File.dirname(dest))
+    File.binwrite(dest, content)
+    puts "  #{filename} -> #{dest}"
+  end
+end
+
+desc 'Generate code coverage'
+RSpec::Core::RakeTask.new(:coverage) do |t|
+  t.rcov = true
+  t.rcov_opts = ['--exclude', '/gems/,spec']
+end

data/docs/async.md

@@ -0,0 +1,46 @@
+# Async bulk operations
+
+For large operations, submit a job and poll for results rather than waiting on a single long-running request.
+
+## Pattern
+
+```ruby
+# 1. Submit
+records = 100.times.map { |i| NetSuite::Records::Customer.new(entity_id: "Bulk-#{i}") }
+result  = NetSuite::Records::Customer.async_add_list(records)
+job_id  = result[:job_id]
+
+# 2. Poll
+status = NetSuite::Actions::CheckAsyncStatus.call([job_id])
+sleep 2 until %w[finished failed].include?(status.body[:status])
+
+# 3. Fetch (page_index is 1-based)
+response = NetSuite::Actions::GetAsyncResult.call([job_id, 1])
+```
+
+## Available operations
+
+| Operation | Max records |
+|-----------|------------|
+| `AsyncAddList` | 400 |
+| `AsyncDeleteList` | 400 |
+| `AsyncGetList` | 2000 |
+| `AsyncUpdateList` | 200 |
+| `AsyncUpsertList` | 200 |
+| `AsyncSearch` | — |
+| `AsyncInitializeList` | — |
+
+## Enabling on a record class
+
+Record classes opt in via the `actions` DSL:
+
+```ruby
+actions :add, :async_add_list, :update, :async_update_list
+```
+
+## Response shape
+
+- `async_add_list` / `async_update_list` / `async_upsert_list` — `response.body[:write_response_list]`
+- `async_delete_list` — `response.body[:delete_response_list]`
+- `async_get_list` — `response.body[:read_response_list]`
+- `async_search` — `response.body[:search_result]`

data/docs/configuration.md

@@ -0,0 +1,88 @@
+# Configuration
+
+## Token Based Authentication (recommended)
+
+```ruby
+NetSuite.configure do
+  reset!
+
+  account       ENV['NETSUITE_ACCOUNT']
+  api_version   '2025_2'
+
+  consumer_key     ENV['NETSUITE_CONSUMER_KEY']
+  consumer_secret  ENV['NETSUITE_CONSUMER_SECRET']
+  token_id         ENV['NETSUITE_TOKEN_ID']
+  token_secret     ENV['NETSUITE_TOKEN_SECRET']
+end
+```
+
+## WSDL and datacenter
+
+This gem targets SOAP 2025.2 only. The WSDL defaults to the production URL for v2025_2_0.
+
+```ruby
+NetSuite.configure do
+  reset!
+  api_version '2025_2'
+
+  # explicit WSDL URL (sandbox, specific datacenter, etc.)
+  wsdl "https://webservices.sandbox.netsuite.com/wsdl/v2025_2_0/netsuite.wsdl"
+
+  # or set just the domain and let the gem build the URL
+  wsdl_domain "webservices.na2.netsuite.com"
+end
+```
+
+## All options
+
+```ruby
+NetSuite.configure do
+  reset!
+
+  api_version   '2025_2'
+  account       '12345'
+
+  # auth (use TBA above instead)
+  email         'email@domain.com'
+  password      'password'
+  role          1111
+
+  # WSDL
+  wsdl          "https://webservices.netsuite.com/wsdl/v2025_2_0/netsuite.wsdl"
+  wsdl_domain   "webservices.na2.netsuite.com"
+
+  # timeouts
+  read_timeout  100_000
+
+  # logging
+  log           File.join(Rails.root, 'log/netsuite.log')
+  # log_level   :debug
+
+  # ignore read-only fields
+  soap_header   'platformMsgs:preferences' => {
+    'platformMsgs:ignoreReadOnlyFields' => true,
+  }
+end
+```
+
+Some configuration options mutate others. See `lib/netsuite/configuration.rb` for details.
+
+## Multi-tenancy
+
+For multiple NetSuite accounts in separate threads:
+
+```ruby
+# main thread
+NetSuite.configure do
+  multi_tenant!
+end
+
+# each child thread
+NetSuite.configure do
+  reset!
+  account ENV['NETSUITE_ACCOUNT']
+  # rest of config...
+end
+```
+
+`multi_tenant!` is not affected by `reset!`.

data/docs/contributing.md

@@ -0,0 +1,36 @@
+# Contributing
+
+## Setup
+
+```shell
+git clone https://github.com/bdelanghe/netsuite.git
+cd netsuite
+bundle install
+```
+
+## Tests
+
+```shell
+bundle exec rspec
+```
+
+Integration tests (live NetSuite calls) are opt-in:
+
+```shell
+NETSUITE_INTEGRATION=true bundle exec rspec
+```
+
+Coverage report:
+
+```shell
+COVERAGE=true bundle exec rspec
+```
+
+## Adding a new action
+
+1. Create `lib/netsuite/actions/my_action.rb` inheriting `AbstractAction`
+2. For async actions, `include AsyncResponse`
+3. Register in `lib/netsuite/support/actions.rb`
+4. Add autoload in `lib/netsuite.rb`
+5. Add XML fixture in `spec/support/fixtures/my_action/`
+6. Write spec in `spec/netsuite/actions/my_action_spec.rb`