econt 0.1.0

data/docs/RELEASING.md

@@ -0,0 +1,35 @@
+# Releasing
+
+Ordinary pushes and pull requests only test and package the gem. They never
+publish it.
+
+The manual `Release gem` workflow is intentionally gated by all of the
+following:
+
+1. Select an existing `vVERSION` tag when dispatching the workflow.
+2. The tag must exactly match `Econt::VERSION`.
+3. Type `publish` into the confirmation input.
+4. Set the repository variable `RUBYGEMS_TRUSTED_PUBLISHING_ENABLED` to `true`.
+5. Configure the `release` GitHub environment and a RubyGems pending trusted
+   publisher for this repository and workflow.
+
+Until those repository-side settings exist, the publish job is skipped rather
+than failing normal CI. Trusted Publishing uses GitHub OIDC; no long-lived
+RubyGems API key belongs in repository secrets.
+
+Before creating a tag, run:
+
+```bash
+bundle exec rake
+bundle exec rbs -r date -I sig validate
+bin/package_smoke_test
+bin/check_release_tag v0.1.0
+```
+
+Then inspect the built gem contents and confirm README examples against the
+demo environment using sanitized contract recordings. Publishing is irreversible,
+so do not reuse a released version number.
+
+The package smoke test uses dependencies installed by `bundle install`, including
+project-local Bundler caches. Its final subprocess disables Bundler and loads the
+built gem from a temporary installation outside the source checkout.

data/docs/RESPONSE_TESTS.md

@@ -0,0 +1,46 @@
+# Offline response property contracts
+
+The endpoint response specs exercise all 25 documented API endpoints through
+the real client transport, request middleware and service result mapping, with
+WebMock returning synthetic JSON. No carrier requests are made.
+
+`spec/fixtures/examples/response_schemas.json` is a 2026-10-11 snapshot of the
+schema and endpoint response definitions from
+[the official OpenAPI document](https://ee.econt.com/services/openapi.yaml).
+Descriptions are omitted; property names, types, formats and references are
+retained. These are schema-derived examples, not recorded live responses.
+Each endpoint has its own `responses/<endpoint>/success.json` and
+`responses/<endpoint>/null_scalars.json` under `spec/fixtures/examples/`.
+The checked-in payloads populate every optional documented field, nested object
+and array with synthetic values independently of the gem's field declarations.
+The error payload is shared in `responses/error.json`. Different scalar
+values help detect accidental assignments between fields.
+Every endpoint also receives a synthetic documented HTTP 400 error, with a
+nested inner error and both populated and empty primitive arrays.
+
+The recursive assertion in `spec/support/response_properties.rb` independently
+derives snake_case reader names and compares each raw camelCase property with
+the value obtained through `public_send`. It checks array sizes and each nested
+element, including false, zero and nil. ISO dates and date-times are compared
+against Date and DateTime values based on the documentation's format, not the
+model's declared field types. Unsupported temporal representations, including
+numeric epochs without an authoritative unit, retain their raw value.
+
+Collection envelopes and single-resource wrappers are explicitly unwrapped
+according to the public service return contract. Three-way logistics documents
+an empty object, so its contract verifies an empty response model rather than
+inventing properties. `set_itu_code` deliberately returns a Faraday response;
+its empty raw body is compared directly. Raw hashes never count as evidence
+that nested dot access works. Unknown response fields continue to be ignored,
+as documented in PUBLIC_API.md, and have a separate compatibility regression.
+
+`get_regions` is a helper derived from `get_cities`, not an additional API
+endpoint. A manifest assertion requires every directly exposed service endpoint
+to appear in the examples, so adding an endpoint requires a response contract.
+The existing VCR specs remain complementary evidence of actual API behavior.
+
+Run these offline contracts with:
+
+```sh
+bundle exec rspec spec/endpoint_response_properties_spec.rb spec/response_properties_spec.rb
+```

data/docs/VCR.md

@@ -0,0 +1,144 @@
+# VCR contract testing
+
+The opt-in contract suite records real demo responses. Normal tests never
+contact Econt. CI replays every reviewed cassette through the public service
+methods, without loading `.env` files or needing credentials:
+
+```bash
+ECONT_VCR_REPLAY=1 bundle exec rspec spec/recorded_contract_spec.rb
+```
+
+Replay uses VCR `record: :none` and a request firewall: missing or unmatched
+interactions fail instead of contacting Econt, even if recording options are
+overridden. WebMock also disables network connections. The replay spec is
+separate from the opt-in recording suite, so account-specific recording settings
+cannot silently skip CI coverage.
+
+Each endpoint has an independent cassette so a failed recording can be removed
+and retried without discarding unrelated evidence.
+
+The historical client-profile recording had whole address objects replaced with
+strings by an earlier scrubber. Those slots are now empty objects, preserving
+their counts and valid model shape; their nested address properties are not
+live-verified by this cassette. New recordings retain nested structure and redact
+only sensitive scalar values. Replay compares every present documented field,
+not optional absent fields or undocumented fields intentionally ignored by models.
+
+## Read-only coverage
+
+The suite covers nomenclatures, address validation and service lookup, client
+profiles, label calculation and validation modes, payment reports, AWB history,
+and optional shipment/courier-status reads. Account-specific identifiers are
+supplied through `.env` and their recordings are structurally sanitized.
+
+Offline request-shape specs exercise every explicit public keyword at least
+once. Large nested label and logistics hashes use generic serialization, so
+representative documented fields and model casting are tested without trying
+every possible field combination. Live contracts use the smallest meaningful
+payload for each server behavior; they are not a parameter-permutation suite.
+
+## Coverage policy
+
+| Endpoint kind | Contract approach |
+| --- | --- |
+| Nomenclatures and address queries | Recorded directly, one cassette per endpoint |
+| Profiles, reports, AWB, shipment, and courier-status reads | Recorded with dedicated demo fixtures and structural response redaction |
+| Single label `validate`/`calculate` and bulk label `validate` modes | Recorded because these modes do not create shipments |
+| Label creation/update/deletion/grouping, courier requests, ITU, CDA, and three-way logistics | Excluded from the read-only suite; use the lifecycle pattern below |
+
+## Mutating endpoints
+
+VCR does not make a mutating operation safe: the first recording is still a
+real request. Projects that contract-test creation or updates normally use a
+dedicated demo account and record a complete scenario in one cassette:
+
+1. create a uniquely identifiable fixture;
+2. exercise the update or action being tested;
+3. query the result;
+4. delete or cancel the fixture in an `ensure` cleanup block; and
+5. confirm the cleanup response before accepting the cassette.
+
+Recording is a manual maintenance operation, never a normal CI action. CI only
+replays reviewed cassettes with network access disabled. Identifiers,
+credentials, names, phones, addresses, payment data, cookies, and tokens must
+be scrubbed while preserving the JSON scalar types expected by model casting.
+If an API offers no reliable cleanup, prefer a provider sandbox reset, a
+pre-provisioned disposable fixture, or an offline request-shape test instead of
+recording the mutation.
+
+Never re-record all cassettes automatically. Delete only the cassette being
+refreshed, inspect the diff, verify cleanup through a status request, and scan the
+result for secrets and personal data before committing it.
+
+## Reviewed mutation example
+
+`spec/live/label_mutation_contract_spec.rb` implements the lifecycle above for
+label creation. It creates a synthetic office-delivery label, deletes it in an
+`ensure` block, and then calls `getShipmentStatuses` to verify that Econt
+recorded a `canceled` tracking event. All three interactions are stored in
+`econt_demo/label_create_and_delete.yml`; the generated description and
+shipment number are filtered.
+
+The example requires an additional, deliberate opt-in:
+
+```bash
+ECONT_LIVE_TESTS=1 ECONT_MUTATING_LIVE_TESTS=1 \
+  bundle exec rspec spec/live/label_mutation_contract_spec.rb
+```
+
+Econt retains the cancelled label in status history. The example therefore
+fails unless the final response contains a tracking event whose destination
+type is `canceled`.
+
+## Mutation cleanup inventory
+
+Cleanup cancels disposable labels; it does not erase their historical records.
+The inventory is based on the documented
+[LabelService and ShipmentService](https://ee.econt.com/services/Shipments/),
+[ProfileService](https://ee.econt.com/services/Profile/), and
+[ThreeWayLogisticsService](https://ee.econt.com/services/ThreeWayLogistics/).
+
+### Clear cleanup paths for disposable, uncollected labels
+
+| Endpoint | Scenario and cleanup | Recording status |
+| --- | --- | --- |
+| Create label and delete labels | Create without courier-request times, delete, query the `canceled` tracking event | Existing demo recording verifies cleanup |
+
+The verified example lives in `spec/live/label_mutation_contract_spec.rb`.
+Cleanup runs in `ensure`; deletion errors or a missing cancellation event fail
+the example. If creation times out before returning an identifier, account
+reconciliation is required before retrying.
+
+Update-label and batch-create mutation specs were removed after the demo API
+acknowledged the same `deleteLabels` operation but continued to report `prepared`
+through six subsequent status reads. Their cleanup call used the same endpoint
+and shipment-number array payload as the verified example. The differing status
+responses are a demo API inconsistency; the recordings do not establish why it
+occurs or independently confirm cancellation for those scenarios.
+
+### Suggested cleanup with uncertain effectiveness
+
+| Endpoint/action | Suggested path | What remains unverified |
+| --- | --- | --- |
+| Update label | Update only a fresh disposable label, delete all returned numbers, query cancellation | Deletion was acknowledged, but six status reads remained `prepared`; the live spec was removed |
+| Create labels synchronously | Collect all successful batch identifiers, delete each, query cancellation | Deletion was acknowledged for both labels, but six status reads remained `prepared`; the live spec was removed |
+| Bulk update labels | Create disposable labels, make non-financial edits, delete every original and replacement number | The nested success model is typed, but batch edition side effects and replacement-number behavior still need live verification before automating cleanup |
+| Grouping | Group only fresh disposable labels, call `groupingCancelation`, then delete the original labels and any surviving group label | There is an explicit undo endpoint, but status values, restoration of members, and group-label deletion behavior are not clearly documented |
+| Grouping cancellation | Run only as the undo of a disposable group | No guarantee that cancellation erases the group or restores every member exactly |
+| Set ITU code | Apply only to a fresh disposable label, then delete that label | Deletion is not documented to reverse code registration; no documented code-unset operation |
+| Courier request, including times on label creation/update | Delete attached disposable labels and arrange cancellation of the courier request with the carrier | Deleting labels is not documented to cancel the request or courier visit; no courier-request cancellation endpoint is exposed |
+| `updateLabel` with `destroy: true` | Carrier-confirmed procedure using disposable fixtures | The flag has no sufficient documented semantics to treat it as a reliable cleanup or rollback operation |
+
+These are proposals without live mutation specs. Obtain a confirmed cleanup
+contract before recording them; querying a status alone is not undo.
+
+### No obvious API cleanup path
+
+| Endpoint/action | Missing inverse |
+| --- | --- |
+| Create COD agreement (`createCDAgreement`) | No agreement revoke/delete endpoint in the published service |
+| Three-way logistics | No documented undo for the complete logistics operation; deleting one generated label would not establish rollback of all side effects |
+| Label payment blocking, payment instructions, or financial editions | No general payment-release/refund/edition-rollback endpoint; deleting a label does not establish financial rollback |
+
+These require carrier-managed reset or explicitly disposable pre-provisioned
+fixtures. They remain covered offline rather than by automatic live mutations.

data/lib/econt/camel_case_middleware.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Econt
+  class CamelCaseMiddleware < Faraday::Middleware
+    DEFAULT_ACRONYMS = {
+      'aps' => 'APS',
+      'awb' => 'AWB',
+      'bic' => 'BIC',
+      'egn' => 'EGN',
+      'eu' => 'EU',
+      'id' => 'ID',
+      'iban' => 'IBAN',
+      'itu' => 'ITU',
+      'lc' => 'LC',
+      'mps' => 'MPS',
+      'url' => 'URL'
+    }.freeze
+
+    def initialize(app, acronyms: {}, replace_defaults: false)
+      super(app)
+      @acronyms =
+        if acronyms.nil?
+          {}
+        elsif replace_defaults
+          acronyms.transform_keys(&:to_s)
+        else
+          DEFAULT_ACRONYMS.merge(acronyms.transform_keys(&:to_s))
+        end
+      # value (UPPER) -> lowercase key
+      @acronym_reverse = @acronyms.each_with_object({}) { |(k, v), h| h[v] = k }
+    end
+
+    def call(env)
+      env.body = deep_transform_keys(env.body) { |key| to_camel_case(key) } if transformable?(env.body)
+      @app.call(env)
+    end
+
+    def on_complete(env)
+      return unless transformable?(env.body)
+
+      env.body = deep_transform_keys(env.body) { |key| to_snake_case(key) }
+    end
+
+    private
+
+    # snake_case -> camelCase (request)
+    def to_camel_case(key)
+      parts = key.to_s.split('_')
+      return key.to_s if parts.empty?
+
+      first = parts.shift
+      first + parts.map { |p| @acronyms.fetch(p, p.capitalize) }.join
+    end
+
+    # camelCase/PascalCase/acronyms -> snake_case (response) with acronym support
+    def to_snake_case(key)
+      str = key.to_s
+      # Protect acronyms (longest first)
+      @acronym_reverse.keys.sort_by { |x| -x.length }.each do |acro|
+        str = str.gsub(/#{acro}(?=[A-Z]|$)/) { "_#{@acronym_reverse[acro]}_" }
+      end
+      str = str
+            .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .downcase
+      str.gsub(/__+/, '_').sub(/^_/, '').sub(/_$/, '')
+    end
+
+    def deep_transform_keys(obj, &)
+      case obj
+      when Econt::Model
+        deep_transform_keys(obj.to_h, &)
+      when Array
+        obj.map { |item| deep_transform_keys(item, &) }
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[yield(k)] = deep_transform_keys(v, &) }
+      else
+        obj
+      end
+    end
+
+    def transformable?(object)
+      object.is_a?(Hash) || object.is_a?(Array)
+    end
+  end
+end

data/lib/econt/client.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'base64'
+require 'logger'
+
+module Econt
+  class Client
+    class << self
+      attr_reader :instance
+
+      def configure
+        @instance ||= new
+        yield(@instance) if block_given?
+        @instance.setup_connection!
+      end
+
+      def connection
+        instance&.connection || raise('Econt::Client is not configured. Call Econt::Client.configure first.')
+      end
+    end
+
+    attr_accessor :username, :password, :base_url, :adapter,
+                  :acronyms, :replace_acronym_defaults,
+                  :debug, :debug_bodies, :debug_logger,
+                  :open_timeout, :read_timeout, :write_timeout
+
+    def initialize
+      @base_url = 'http://demo.econt.com/ee/services/' # Default to demo
+      @adapter = Faraday.default_adapter
+      @acronyms = {} # nil to disable, {} to keep defaults
+      @replace_acronym_defaults = false
+      @debug = false
+      @debug_bodies = false
+      @debug_logger = nil
+      @open_timeout = 30
+      @read_timeout = 30
+      @write_timeout = 30
+    end
+
+    def add_acronyms(hash)
+      @acronyms = (@acronyms || {}).merge(hash.transform_keys(&:to_s))
+    end
+
+    def setup_connection!
+      validate_credentials!
+
+      @connection = Faraday.new(base_url) do |conn|
+        configure_timeouts(conn)
+        conn.use Econt::CamelCaseMiddleware,
+                 acronyms: @acronyms,
+                 replace_defaults: @replace_acronym_defaults
+        conn.request :json
+        conn.response :json, content_type: 'application/json'
+        configure_debug_logging(conn) if debug
+        conn.adapter adapter
+        configure_headers(conn)
+      end
+    end
+
+    def connection
+      @connection || raise('Connection is not initialized. Call Econt::Client.configure first.')
+    end
+
+    private
+
+    def configure_debug_logging(connection)
+      connection.response :logger,
+                          debug_logger || Logger.new($stdout),
+                          headers: true,
+                          bodies: debug_bodies do |formatter|
+        formatter.filter(encoded_credentials, '<ECONT_BASIC_TOKEN>')
+        formatter.filter(username.to_s, '<ECONT_USERNAME>')
+        formatter.filter(password.to_s, '<ECONT_PASSWORD>')
+      end
+    end
+
+    def configure_timeouts(connection)
+      connection.options.open_timeout = open_timeout
+      connection.options.timeout = read_timeout
+      connection.options.write_timeout = write_timeout if connection.options.respond_to?(:write_timeout=)
+    end
+
+    def configure_headers(connection)
+      connection.headers['Authorization'] = "Basic #{encoded_credentials}"
+      connection.headers['User-Agent'] = "EcontRubyClient/#{Econt::VERSION}"
+    end
+
+    def validate_credentials!
+      creds_missing = [username, password].any? { |credential| credential.to_s.empty? }
+      raise 'Username and password must be set' if creds_missing
+    end
+
+    def encoded_credentials
+      Base64.strict_encode64("#{username}:#{password}")
+    end
+  end
+end

data/lib/econt/collection.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Econt
+  class Collection < MetaResource
+    include Enumerable
+
+    def initialize(source, model:, key:)
+      @model = model
+      @key = key
+      @error = Econt::Models::Error.build_from(source)
+      @items = build_items(source)
+      super()
+    end
+
+    attr_reader :error
+
+    def error?
+      !error.nil?
+    end
+
+    def each(&)
+      @items.each(&)
+    end
+
+    def to_a
+      @items
+    end
+
+    def size
+      @items.size
+    end
+
+    def empty?
+      @items.empty?
+    end
+
+    alias length size
+    alias count size
+
+    private
+
+    def build_items(source)
+      extract_raw_items(source).map do |item|
+        item.is_a?(@model) ? item : @model.new(item)
+      end
+    end
+
+    def extract_raw_items(source)
+      case source
+      when Hash
+        Econt::Util.underscore_keys(source)[@key.to_s] || []
+      when Array
+        source
+      else
+        []
+      end
+    end
+  end
+end

data/lib/econt/error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Econt
+  class Error < StandardError
+    attr_reader :error, :status
+
+    def initialize(message = nil, error: nil, status: nil)
+      @error = error
+      @status = status
+
+      super(message || error_message || status_message || self.class.name)
+    end
+
+    private
+
+    def error_message
+      return unless error.respond_to?(:full_message)
+
+      message = error.full_message
+      message unless message.to_s.strip.empty?
+    end
+
+    def status_message
+      return if status.nil?
+
+      "Econt API request failed with status #{status}."
+    end
+  end
+
+  # A request failed before a usable HTTP response was available.
+  # The original adapter exception is retained as #cause and may contain secrets.
+  class TransportError < Error; end
+
+  # The client could not establish or maintain a connection.
+  class ConnectionError < TransportError; end
+
+  # The configured connection or request deadline was exceeded.
+  class TimeoutError < TransportError; end
+
+  # TLS negotiation or certificate verification failed.
+  class SSLError < TransportError; end
+end

data/lib/econt/meta_resource.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Econt
+  class MetaResource
+  end
+end

data/lib/econt/model.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Econt
+  class Model
+    include Econt::ResourceAttributes
+    include Econt::Util
+
+    class << self
+      def collection_key(value = nil)
+        return @collection_key || Econt::Util.pluralize(name).to_sym unless value
+
+        @collection_key = value
+      end
+
+      def collection(source)
+        Econt::Collection.new(source, model: self, key: collection_key)
+      end
+
+      def build(source, key: nil)
+        data = extract_source(source, key)
+        new(data.is_a?(Hash) ? data : {})
+      end
+
+      private
+
+      def extract_source(source, key)
+        case source
+        when Hash
+          normalized = Econt::Util.underscore_keys(source)
+          if key && normalized.key?(key.to_s)
+            normalized[key.to_s]
+          else
+            source
+          end
+        else
+          source
+        end
+      end
+    end
+
+    def initialize(attributes = {})
+      @attributes = {}
+      @error = Econt::Models::Error.build_from(attributes) unless is_a?(Econt::Models::Error)
+      apply_attributes(attributes)
+      self.error = @error if @error && respond_to?(:error=)
+    end
+
+    attr_reader :error
+
+    def error?
+      !error.nil?
+    end
+
+    def method_missing(method_name, *args, &)
+      if @attributes.key?(method_name)
+        @attributes[method_name]
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @attributes.key?(method_name) || super
+    end
+
+    def to_h
+      deep_to_h(@attributes)
+    end
+
+    def to_json(*)
+      camelize_keys(to_h).to_json(*)
+    end
+
+    def apply_attributes(new_attributes)
+      underscore_keys(new_attributes).each do |key, value|
+        send("#{key}=", value) if respond_to?("#{key}=")
+      end
+    end
+
+    private
+
+    def deep_to_h(value)
+      case value
+      when Econt::Model
+        value.to_h
+      when Hash
+        value.transform_values { |item| deep_to_h(item) }
+      when Array
+        value.map { |item| deep_to_h(item) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/econt/models/error.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    class Error < Econt::Model
+      field :type, type: :string
+      field :message, type: :string
+      field :fields, type: :array, of: :string
+      field :inner_errors, type: :array, of: Econt::Models::Error
+
+      class << self
+        def build_from(source)
+          return unless error_body?(source)
+
+          new(source)
+        end
+
+        def error_body?(source)
+          return false unless source.is_a?(Hash)
+
+          key?(source, :type) && (key?(source, :fields) || key?(source, :inner_errors))
+        end
+
+        private
+
+        def key?(hash, key)
+          hash.key?(key) || hash.key?(Econt::Util.camel_case(key.to_s))
+        end
+      end
+
+      def fields
+        Array(@attributes[:fields])
+      end
+
+      def inner_errors
+        Array(@attributes[:inner_errors]).map do |error|
+          error.is_a?(Econt::Models::Error) ? error : Econt::Models::Error.new(error)
+        end
+      end
+
+      def messages
+        [
+          message,
+          *inner_errors.flat_map(&:messages)
+        ].reject { |value| value.to_s.strip.empty? }
+      end
+
+      def full_message
+        messages.join(' ')
+      end
+    end
+  end
+end

data/lib/econt/models/hosted_file.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    class HostedFile < Econt::Model
+      field :id, type: :integer
+      field :filename, type: :string
+      field :mime_type, type: :string
+      field :url, type: :string
+      field :content, type: :string
+    end
+  end
+end