cin7_core_api 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 237cda18aeb79904a6fed79dc9deaa53240aff6d45f659d0163f14188af06126
-  data.tar.gz: 3ba7316e959ec28916abb55e3036e0550d68ce626be3c0ac08fc80eda8a8bfb8
+  metadata.gz: f21c5a07972b89e6cd344f6db539ce6dee6cdd5734dc69bff3a9c1f410f0ec4a
+  data.tar.gz: 5ab77af8749ea07602cbe26bc0fee753f20e2f7145f83e9c6ff009399f9c79f3
 SHA512:
-  metadata.gz: caff2995e25a658cd0aaf75513389850a0347a8aa4fc0f38ee3b99015a2e02a9bccd758edecedb4187f06fbd2360bb25ae6ce944a10b1a7fc6fc454f1c02910c
-  data.tar.gz: 932d8ea1d610710377946799c1224e099b3e4d6b5cf6b99d5ac32b01e28d7a07cb7bdd563291246430126f01e07f295dd8a1d70d235708ea8a8ed2f527d0b563
+  metadata.gz: c7a38afa25859861feb348204718c98a8711a196461f73f9f7e9e14208dddac1a5b66f786b6bfdd8a1f77dd9b7e15bdc5c03a7d2a00f76ca03e74cc33c0951a7
+  data.tar.gz: ce282fe173d4d3c43e0be08ad1efd497d19b0115c9420a4f9289a12e0093566c0bb34209888335493b69b149f2e10b127840d77b7476de5301844a6f9fb07eab

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.3.1] - 2026-10-20
+
+- Name the error Faraday wraps in transport failure messages, such as `Faraday::ConnectionFailed caused by Zlib::DataError` for a corrupt gzip response under faraday-net_http 3.5 and `Faraday::TimeoutError caused by Net::ReadTimeout` for a read timeout on any adapter version.
+
+## [0.3.0] - 2026-10-02
+
+- Add explicit credit-note creation/undo and Advanced Sale fulfilment, pick, pack and shipment resources with readback and distinct POST/PUT semantics.
+- Add sale-header creation plus product, stock availability and carrier reads so sandbox preparation uses resource methods throughout.
+- Preserve caller-supplied task IDs, monetary values, restock and shipment collections; do not select eligibility, append lines or restore inventory implicitly.
+
 ## [0.2.1] - 2026-10-02
 
 - Keep decompression failures and malformed UTF-8 responses, including invalid decoded JSON strings, inside the sanitized error contract, preserving uncertain-write recovery without retries.

data/README.md

@@ -9,7 +9,7 @@ Version `0.2.0` adds explicit payment, order, invoice, journal, and webhook oper
 Add the gem to your Gemfile:
 
 ```ruby
-gem "cin7_core_api", "0.2.1"
+gem "cin7_core_api", "0.3.0"
 ```
 
 Then run:
@@ -22,6 +22,38 @@ Ruby 3.3 or newer is required.
 
 Version `0.2.1` adds response-decoding safety and callback-identity fixes. Published `0.2.0` remains unchanged. Check RubyGems for publication availability; to evaluate a reviewed source before publication, pin its full commit SHA from this repository.
 
+Version `0.3.0` adds the explicit native correction and sandbox preparation resources below. It includes the `0.2.1` safety fixes.
+
+## Native correction and sandbox preparation
+
+These methods use the same sanitized errors and never retry. Payloads use Cin7 String field names. `sale_id:` identifies the parent sale; `task_id:` identifies the particular credit-note or fulfilment task.
+
+| Resource method | HTTP contract |
+| --- | --- |
+| `sales.create(payload:)` | POST `sale`; create a header with caller-selected customer, sale type and options |
+| `credit_notes.create(payload:)` | POST `sale/creditnote`; explicit `SaleID` and `TaskID` |
+| `credit_notes.undo(task_id:)` | DELETE `sale/creditnote` with `TaskID` and `Void=false` |
+| `fulfilments.for_sale(sale_id:, include_product_info: false)` | GET `sale/fulfilment`; preserve its `Fulfilments` response collection |
+| `fulfilments.create(payload:)` | POST `sale/fulfilment`; explicit `SaleID` |
+| `fulfilments.undo(task_id:)` | DELETE `sale/fulfilment` with `TaskID` and `Void=false` |
+| `picks.for_task(task_id:, include_product_info: false)` | GET `sale/fulfilment/pick` |
+| `packs.for_task(task_id:, include_product_info: false)` | GET `sale/fulfilment/pack` |
+| `shipments.for_task(task_id:)` | GET `sale/fulfilment/ship` |
+| `picks.create/update(payload:)` | POST/PUT `sale/fulfilment/pick`; explicit `TaskID` |
+| `packs.create/update(payload:)` | POST/PUT `sale/fulfilment/pack`; explicit `TaskID` |
+| `shipments.create/update(payload:)` | POST/PUT `sale/fulfilment/ship`; explicit `TaskID` |
+| `products.list(**filters)` | GET `product`; supports documented product discovery filters |
+| `product_availability.list(**filters)` | GET `ref/productavailability`; `page`, `limit`, `id`, `name`, `sku`, `location`, `batch`, `category` |
+| `carriers.list(**filters)` | GET `ref/carrier`; `page`, `limit`, `carrier_id`, `description` |
+
+Cin7 documents credit-note **POST**, not PUT. Use `create` for an explicit new task or a draft/not-available task; it does not overwrite an authorised note by itself. For a new note, the caller may supply the documented empty GUID `TaskID`; the gem never chooses or inserts it. Forward complete `Lines`, `AdditionalCharges` and `Restock` collections deliberately.
+
+The provider's credit-note DELETE eligibility is unusually narrow and duplicated in its Blueprint: Advanced Sale with credit-note `TaskID = SaleID`. Its applicability to connector-created secondary notes is unproven. Exposing `undo` does not establish that a particular paid, taxed or restocked note can be rebuilt safely. The caller must inspect state, preserve payouts and inventory ownership, check the actual rejection/readback and recover uncertain outcomes before proceeding.
+
+Fulfilment `create` can convert a Simple Sale to Advanced Sale. Pack and shipment **POST may append lines**, while **PUT replaces** eligible draft/not-available documents. Shipment PUT must include all required packed boxes. The caller must preserve quantities, locations, batches, boxes and shipment identity and verify inventory after any restoration. The gem does not authorise a previously fulfilled sale correction or run pick/pack/ship automatically.
+
+The `products` filters are `id`, `page`, `limit`, `name`, `sku`, `modified_since`, `include_deprecated`, `include_bom`, `include_suppliers`, `include_movements`, `include_attachments`, `include_reorder_levels`, and `include_custom_prices`. Nil filters are omitted, boolean false is retained, and unsupported filters fail before dispatch.
+
 ## Authentication
 
 Create a client using the Account ID and API Application Key from CIN7 Core's API setup page:
@@ -257,15 +289,15 @@ Stage intended new source/spec files before using the tracked-file lint command.
 
 ## Releasing
 
-Publishing a GitHub release triggers `.github/workflows/release.yml`. It requires the tagged commit to be part of `main`, verifies the tag matches `v<VERSION>`, runs tests and lint, builds the gem, and publishes that exact version to RubyGems. Draft releases and ordinary branch pushes do not publish gems.
+Publishing a GitHub release triggers `.github/workflows/release.yml`. Its `test` job runs tests and lint without publishing rights. The `publish` job then requires the tagged commit to be part of `main`, verifies the tag matches `v<VERSION>`, builds the gem with plain `gem build`, and publishes that exact version to RubyGems. `publish` holds the RubyGems token, so it never installs gems or runs Bundler; keep it that way. It waits for a required reviewer to approve the `release` environment, which accepts only `v*` tags. Draft releases and ordinary branch pushes do not publish gems.
 
-One-time setup: in the `cin7_core_api` gem's RubyGems **Trusted publishers** settings, register repository owner `PostCo`, repository `cin7_core_api`, workflow filename `release.yml`, and environment `release`. Use the same `release` environment in GitHub. [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) uses GitHub OIDC, so no long-lived API key or interactive MFA code is needed in CI. Signing in locally does not configure this trust relationship.
+One-time setup: in the `cin7_core_api` gem's RubyGems **Trusted publishers** settings, register repository owner `PostCo`, repository `cin7_core_api`, workflow filename `release.yml`, and environment `release`. Use the same `release` environment in GitHub, with a required reviewer and a `v*` tag deployment rule. [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) uses GitHub OIDC, so no long-lived API key or interactive MFA code is needed in CI. Signing in locally does not configure this trust relationship.
 
 For each new version:
 
 1. Update `lib/cin7_core_api/version.rb` and `CHANGELOG.md`, review the PR, and merge it into `main`.
 2. Create and publish a GitHub release at that merged commit, with a tag such as `v0.2.1` matching the gem version.
-3. Check the **Publish gem** workflow and verify the version is available on RubyGems before updating application dependencies.
+3. Approve the **Publish gem** workflow's `release` deployment once `test` passes, then verify the version is available on RubyGems before updating application dependencies.
 
 The manually published `0.2.0` already exists. Do not republish it; this workflow is for subsequent versions. A failed attempt to publish an existing version does not replace that version. If a workflow is rerun after a partial success, check RubyGems first.
 

data/lib/cin7_core_api/client.rb

@@ -89,6 +89,34 @@ module Cin7CoreAPI
       @webhooks ||= Resources::Webhooks.new(connection)
     end
 
+    def fulfilments
+      @fulfilments ||= Resources::Fulfilments.new(connection)
+    end
+
+    def picks
+      @picks ||= Resources::Picks.new(connection)
+    end
+
+    def packs
+      @packs ||= Resources::Packs.new(connection)
+    end
+
+    def shipments
+      @shipments ||= Resources::Shipments.new(connection)
+    end
+
+    def products
+      @products ||= Resources::Products.new(connection)
+    end
+
+    def product_availability
+      @product_availability ||= Resources::ProductAvailability.new(connection)
+    end
+
+    def carriers
+      @carriers ||= Resources::Carriers.new(connection)
+    end
+
     def inspect
       "#<#{self.class}>"
     end

data/lib/cin7_core_api/connection.rb

@@ -81,8 +81,10 @@ module Cin7CoreAPI
         request.params.update(params)
       end
     rescue Faraday::Error, Zlib::Error => error
+      wrapped = error.wrapped_exception if error.is_a?(Faraday::Error)
+      failure = [error.class, wrapped&.class].compact.join(" caused by ")
       # Faraday exceptions can retain the entire authenticated request in their cause.
-      raise TransportError.new("CIN7 Core transport failed (#{error.class})", ambiguous: write, **context), cause: nil
+      raise TransportError.new("CIN7 Core transport failed (#{failure})", ambiguous: write, **context), cause: nil
     end
 
     def normalized_headers(headers)

data/lib/cin7_core_api/resources/carriers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Carriers < Base
+      PARAMETERS = {page: "Page", limit: "Limit", carrier_id: "CarrierID", description: "Description"}.freeze
+
+      def list(**filters)
+        get("ref/carrier", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/credit_notes.rb

@@ -29,6 +29,16 @@ module Cin7CoreAPI
         require_parameter!(:sale_id, sale_id)
         get("sale/creditnote", params: options.merge(sale_id: sale_id), parameter_map: FOR_SALE_PARAMETERS)
       end
+
+      def create(payload:)
+        validate_payload!(payload, "SaleID", "TaskID")
+        connection.post("sale/creditnote", payload: payload)
+      end
+
+      def undo(task_id:)
+        require_parameter!(:task_id, task_id)
+        connection.delete("sale/creditnote", params: {"TaskID" => task_id, "Void" => false})
+      end
     end
   end
 end

data/lib/cin7_core_api/resources/fulfilments.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Fulfilments < Base
+      PARAMETERS = {sale_id: "SaleID", include_product_info: "IncludeProductInfo"}.freeze
+
+      def for_sale(sale_id:, **options)
+        require_parameter!(:sale_id, sale_id)
+        get("sale/fulfilment", params: options.merge(sale_id: sale_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "SaleID")
+        connection.post("sale/fulfilment", payload: payload)
+      end
+
+      def undo(task_id:)
+        require_parameter!(:task_id, task_id)
+        connection.delete("sale/fulfilment", params: {"TaskID" => task_id, "Void" => false})
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/packs.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Packs < Base
+      PARAMETERS = {task_id: "TaskID", include_product_info: "IncludeProductInfo"}.freeze
+
+      def for_task(task_id:, **options)
+        require_parameter!(:task_id, task_id)
+        get("sale/fulfilment/pack", params: options.merge(task_id: task_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.post("sale/fulfilment/pack", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.put("sale/fulfilment/pack", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/picks.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Picks < Base
+      PARAMETERS = {task_id: "TaskID", include_product_info: "IncludeProductInfo"}.freeze
+
+      def for_task(task_id:, **options)
+        require_parameter!(:task_id, task_id)
+        get("sale/fulfilment/pick", params: options.merge(task_id: task_id), parameter_map: PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.post("sale/fulfilment/pick", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.put("sale/fulfilment/pick", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/product_availability.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class ProductAvailability < Base
+      PARAMETERS = {
+        page: "Page", limit: "Limit", id: "ID", name: "Name", sku: "Sku",
+        location: "Location", batch: "Batch", category: "Category"
+      }.freeze
+
+      def list(**filters)
+        get("ref/productavailability", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/products.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Products < Base
+      PARAMETERS = {
+        id: "ID", page: "Page", limit: "Limit", name: "Name", sku: "Sku", modified_since: "ModifiedSince",
+        include_deprecated: "IncludeDeprecated", include_bom: "IncludeBOM", include_suppliers: "IncludeSuppliers",
+        include_movements: "IncludeMovements", include_attachments: "IncludeAttachments",
+        include_reorder_levels: "IncludeReorderLevels", include_custom_prices: "IncludeCustomPrices"
+      }.freeze
+
+      def list(**filters)
+        get("product", params: filters, parameter_map: PARAMETERS)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/resources/sales.rb

@@ -41,6 +41,11 @@ module Cin7CoreAPI
         get("sale", params: options.merge(id: id), parameter_map: RETRIEVE_PARAMETERS)
       end
 
+      def create(payload:)
+        validate_payload!(payload)
+        connection.post("sale", payload: payload)
+      end
+
       def update(payload:)
         validate_payload!(payload, "ID")
         connection.put("sale", payload: payload)

data/lib/cin7_core_api/resources/shipments.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Cin7CoreAPI
+  module Resources
+    class Shipments < Base
+      def for_task(task_id:)
+        require_parameter!(:task_id, task_id)
+        get("sale/fulfilment/ship", params: {task_id: task_id}, parameter_map: {task_id: "TaskID"})
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.post("sale/fulfilment/ship", payload: payload)
+      end
+
+      def update(payload:)
+        validate_payload!(payload, "TaskID")
+        connection.put("sale/fulfilment/ship", payload: payload)
+      end
+    end
+  end
+end

data/lib/cin7_core_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cin7CoreAPI
-  VERSION = "0.2.1"
+  VERSION = "0.3.1"
 end

data/lib/cin7_core_api.rb

@@ -21,6 +21,13 @@ require_relative "cin7_core_api/resources/manual_journals"
 require_relative "cin7_core_api/resources/journals"
 require_relative "cin7_core_api/resources/tax_rules"
 require_relative "cin7_core_api/resources/webhooks"
+require_relative "cin7_core_api/resources/fulfilments"
+require_relative "cin7_core_api/resources/picks"
+require_relative "cin7_core_api/resources/packs"
+require_relative "cin7_core_api/resources/shipments"
+require_relative "cin7_core_api/resources/products"
+require_relative "cin7_core_api/resources/product_availability"
+require_relative "cin7_core_api/resources/carriers"
 require_relative "cin7_core_api/client"
 
 module Cin7CoreAPI

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cin7_core_api
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - PostCo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -123,17 +123,24 @@ files:
 - lib/cin7_core_api/resources/accounts.rb
 - lib/cin7_core_api/resources/bank_accounts.rb
 - lib/cin7_core_api/resources/base.rb
+- lib/cin7_core_api/resources/carriers.rb
 - lib/cin7_core_api/resources/credit_notes.rb
 - lib/cin7_core_api/resources/customer_credits.rb
 - lib/cin7_core_api/resources/customers.rb
+- lib/cin7_core_api/resources/fulfilments.rb
 - lib/cin7_core_api/resources/invoices.rb
 - lib/cin7_core_api/resources/journals.rb
 - lib/cin7_core_api/resources/locations.rb
 - lib/cin7_core_api/resources/manual_journals.rb
 - lib/cin7_core_api/resources/me.rb
 - lib/cin7_core_api/resources/orders.rb
+- lib/cin7_core_api/resources/packs.rb
 - lib/cin7_core_api/resources/payments.rb
+- lib/cin7_core_api/resources/picks.rb
+- lib/cin7_core_api/resources/product_availability.rb
+- lib/cin7_core_api/resources/products.rb
 - lib/cin7_core_api/resources/sales.rb
+- lib/cin7_core_api/resources/shipments.rb
 - lib/cin7_core_api/resources/tax_rules.rb
 - lib/cin7_core_api/resources/webhooks.rb
 - lib/cin7_core_api/response.rb