cin7_core_api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c48f34c3de3d21ac9674e0bb133a3b9a16158ae0eb5087fcaafdf8e8543f794
-  data.tar.gz: e452799a7aa9ebf7b988d7146df5f01cc0f23c8be9c8213cda495dff6549653d
+  metadata.gz: bebb9103f8de0eff128f3225cb97eeacca8137b6501f09051858053e79443cf6
+  data.tar.gz: 27a765beb403a6279b6d74d25952688b304252e3308b22b47ada21f46c920401
 SHA512:
-  metadata.gz: 0acaa3e83cfd47241d741a4fee553505f558ef091ae971e1f1a8753de40e510b89b03ea17bfc1d2aba60932261d1eddbfbbb20f8deb3d962b566261844bfca99
-  data.tar.gz: fbd694cb6d780b6c718540e02ab0ee6f923f2c33b93ffc65243ff6293453c438dc15b20903e3f8027fa1a3aaa4770931fa9995481ae7b623ef9ff22c9b7d8093
+  metadata.gz: d007332b45d5a02e5810eabd256b24c77156e34fd737c3d68cf671608a9a149978380b21c9398be56d72430fa0ad3beaf28d56015c404b564a3bb838d98f1cb1
+  data.tar.gz: 3be8c44fc59d964e1fea08eede44326e6a38eff0885f7426c11986f23a383901c6215181b1fcca04f17306c667e2ce300336661e24e72e4d3a55d3f93529d5aa

data/CHANGELOG.md

@@ -1,8 +1,17 @@
 # Changelog
 
-## [Unreleased]
+## [0.3.0] - 2026-10-02
 
-### 0.2.0 (release preparation)
+- 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.
+- Preserve callback identity when another webhook subscription has credentials matching this subscription's URL components; continue filtering secrets throughout free text.
+
+## [0.2.0] - 2026-09-29
 
 - Add explicit sale update/undo, order, invoice, payment, sale manual-journal, standalone journal, tax-rule and webhook operations while preserving existing read methods.
 - Send JSON payloads without rounding amounts or FX rates; distinguish parent sale IDs, document task IDs, payment IDs and webhook IDs.

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", github: "PostCo/cin7_core_api", ref: "<reviewed-full-commit-sha>"
+gem "cin7_core_api", "0.3.0"
 ```
 
 Then run:
@@ -20,7 +20,39 @@ bundle install
 
 Ruby 3.3 or newer is required.
 
-The `0.2.0` source is prepared for review; this README does not assert that it has been published. Pin a reviewed source commit until a release is available.
+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
 
@@ -253,7 +285,23 @@ mise exec -- bundle exec standardrb --cache false $(git ls-files '*.rb' '*.gemsp
 mise exec -- bundle exec rake build
 ```
 
-Stage intended new source/spec files before using the tracked-file lint command. CI tests Ruby 3.3 and 3.4. Specs use Faraday's test adapter and do not verify live accounting behavior. Inspect the built gem's file list before release: the gemspec packages only `lib/**/*.rb`, README, changelog and license. Preserve untracked research files. Publication and push require a separate release decision; RubyGems MFA remains required.
+Stage intended new source/spec files before using the tracked-file lint command. CI tests Ruby 3.3 and 3.4. Specs use Faraday's test adapter and do not verify live accounting behavior. Inspect the built gem's file list before release: the gemspec packages only `lib/**/*.rb`, README, changelog and license. Preserve untracked research files.
+
+## 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.
+
+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.
+
+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.
+
+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.
+
+The manual fallback is `bundle exec rake release` from a clean, merged checkout. Tests and Standard run before Bundler's tag/push/publish steps. The main-branch ancestry guard belongs to the GitHub workflow; the manual command does not enforce it. Manual publishing still uses your RubyGems credentials and applicable MFA.
 
 ## CIN7 references
 

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

@@ -2,6 +2,7 @@
 
 require "faraday"
 require "json"
+require "zlib"
 
 module Cin7CoreAPI
   class Connection
@@ -61,12 +62,10 @@ module Cin7CoreAPI
       context = {request_method: method, request_path: redactor.filter(path.split("?").first)}
       write = method != :get
 
-      raw_response = @http.run_request(method, path, body, nil) do |request|
-        request.params.update(params)
-      end
+      raw_response = dispatch(method, path, body, params, context, write: write)
       parsed_body, valid_json = parse_body(raw_response.body)
       values = {"headers" => normalized_headers(raw_response.headers), "body" => parsed_body}
-      sanitized = redactor.with_sensitive_values(values).filter(values)
+      sanitized = redactor.with_sensitive_values(values).filter(values, callback_redactor: redactor)
       response = Response.new(status: raw_response.status, headers: sanitized.fetch("headers"), body: sanitized.fetch("body"))
 
       raise_for_status!(response, context, write: write)
@@ -75,7 +74,13 @@ module Cin7CoreAPI
       end
 
       response
-    rescue Faraday::Error => error
+    end
+
+    def dispatch(method, path, body, params, context, write:)
+      @http.run_request(method, path, body, nil) do |request|
+        request.params.update(params)
+      end
+    rescue Faraday::Error, Zlib::Error => error
       # 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
     end
@@ -87,11 +92,32 @@ module Cin7CoreAPI
     def parse_body(body)
       return [nil, true] if body.nil? || body.empty?
 
-      [JSON.parse(body), true]
+      # JSON is UTF-8 even when the adapter labels its bytes as binary. Reject
+      # malformed success bodies, but keep rejection details safe to redact.
+      body = body.dup.force_encoding(Encoding::UTF_8)
+      return [body.scrub, false] unless body.valid_encoding?
+
+      parsed = JSON.parse(body)
+      # Some JSON parsers accept lone low-surrogate escapes and produce invalid
+      # strings. Do not expose or regex-filter partially decoded credentials.
+      valid_utf8?(parsed) ? [parsed, true] : [Redactor::FILTERED, false]
     rescue JSON::ParserError
       [body, false]
     end
 
+    def valid_utf8?(value)
+      case value
+      when Hash
+        value.all? { |key, entry| valid_utf8?(key) && valid_utf8?(entry) }
+      when Array
+        value.all? { |entry| valid_utf8?(entry) }
+      when String
+        value.valid_encoding?
+      else
+        true
+      end
+    end
+
     def raise_for_status!(response, context, write:)
       return if response.success?
 

data/lib/cin7_core_api/redactor.rb

@@ -18,7 +18,7 @@ module Cin7CoreAPI
       self.class.new(@secrets + sensitive_values(value))
     end
 
-    def filter(value)
+    def filter(value, callback_redactor: self)
       case value
       when Hash
         value.each_with_object({}) do |(key, entry), result|
@@ -26,16 +26,18 @@ module Cin7CoreAPI
           result[key.to_s] = if sensitive_key?(key) || external_headers?(key)
             FILTERED
           elsif callback_url?(key) && entry.is_a?(String)
-            filter_url(entry)
+            # Another subscription's credentials may equal this callback's
+            # integration ID or host label. Scope URL filtering to this record.
+            callback_redactor.with_sensitive_values(value).filter_url(entry)
           elsif structured_identifier?(key, entry)
             # Short header values must not corrupt identifiers or schema enums.
             @secrets.include?(entry) ? FILTERED : entry.dup
           else
-            filter(entry)
+            filter(entry, callback_redactor: callback_redactor)
           end
         end
       when Array
-        value.map { |entry| filter(entry) }
+        value.map { |entry| filter(entry, callback_redactor: callback_redactor) }
       when String
         filter_string(value)
       else
@@ -126,6 +128,8 @@ module Cin7CoreAPI
       []
     end
 
+    protected
+
     def filter_url(value)
       return FILTERED if @secrets.include?(value)
 
@@ -145,6 +149,8 @@ module Cin7CoreAPI
       FILTERED
     end
 
+    private
+
     def filter_authority(authority, host)
       _, separator, host_port = authority.rpartition("@")
       filtered_host = filter_url_component(host)

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.0"
+  VERSION = "0.3.0"
 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.0
+  version: 0.3.0
 platform: ruby
 authors:
 - PostCo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-01 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