econt 0.1.0

data/lib/econt/models/shipments/return_instruction_params.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ReturnInstructionParams < Econt::Model
+        field :return_parcel_destination, type: :string
+        field :return_parcel_is_document, type: :boolean
+        field :return_parcel_is_empty_pallet, type: :boolean
+        field :empty_pallet_euro, type: :integer
+        field :empty_pallet80, type: :integer
+        field :empty_pallet100, type: :integer
+        field :empty_pallet120, type: :integer
+
+        alias empty_pallet_80 empty_pallet80
+        alias empty_pallet_80= empty_pallet80=
+        alias empty_pallet_100 empty_pallet100
+        alias empty_pallet_100= empty_pallet100=
+        alias empty_pallet_120 empty_pallet120
+        alias empty_pallet_120= empty_pallet120=
+        field :days_until_return, type: :integer
+        field :return_parcel_payment_side, type: :string
+        field :return_parcel_receiver_client, type: Econt::Models::Profile::ClientProfile
+        field :return_parcel_receiver_agent, type: Econt::Models::Profile::ClientProfile
+        field :return_parcel_receiver_office_code, type: :string
+        field :return_parcel_receiver_address, type: Econt::Models::Nomenclatures::Address
+        field :print_return_parcel, type: :boolean
+        field :reject_action, type: :string
+        field :reject_instruction, type: :string
+        field :reject_contact, type: :string
+        field :reject_return_client, type: Econt::Models::Profile::ClientProfile
+        field :reject_return_agent, type: Econt::Models::Profile::ClientProfile
+        field :reject_return_office_code, type: :string
+        field :reject_return_address, type: Econt::Models::Nomenclatures::Address
+        field :reject_original_parcel_pay_side, type: :string
+        field :reject_return_parcel_pay_side, type: :string
+        field :signature_documents, type: :boolean
+        field :signature_pen_color, type: :string
+        field :signature_count, type: :integer
+        field :signature_page_numbers, type: :string
+        field :signature_other_instructions, type: :string
+        field :execute_if_rejected_without_review, type: :boolean
+        field :use_return_address_for_instruction, type: :boolean
+        field :execute_if_not_taken, type: :integer
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/shipment_edition_response_element.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ShipmentEditionResponseElement < Econt::Model
+        field :shipment_num, type: :integer
+        field :edition_num, type: :integer
+        field :edition_type, type: :string
+        field :edition_error, type: :string
+        field :price, type: :string
+        field :currency, type: :string
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/shipment_status.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ShipmentStatus < Econt::Model
+        field :shipment_number, type: :string
+        field :storage_office_name, type: :string
+        field :storage_person_name, type: :string
+        field :created_time, type: :datetime
+        field :send_time, type: :datetime
+        field :delivery_time, type: :datetime
+        field :shipment_type, type: :string
+        field :pack_count, type: :integer
+        field :shipment_description, type: :string
+        field :weight, type: :float
+        field :sender_delivery_type, type: :string
+        field :sender_client, type: Econt::Models::Profile::ClientProfile
+        field :sender_agent, type: Econt::Models::Profile::ClientProfile
+        field :sender_office_code, type: :string
+        field :sender_address, type: Econt::Models::Nomenclatures::Address
+        field :receiver_delivery_type, type: :string
+        field :receiver_client, type: Econt::Models::Profile::ClientProfile
+        field :receiver_agent, type: Econt::Models::Profile::ClientProfile
+        field :receiver_office_code, type: :string
+        field :receiver_address, type: Econt::Models::Nomenclatures::Address
+        field :hub_code, type: :string
+        field :hub_name, type: :string
+        field :hub_name_en, type: :string
+        field :cd_collected_amount, type: :float
+        field :cd_collected_currency, type: :string
+        field :cd_collected_time, type: :datetime
+        field :cd_paid_amount, type: :float
+        field :cd_paid_currency, type: :string
+        field :cd_paid_time, type: :datetime
+        field :total_price, type: :float
+        field :currency, type: :string
+        field :discount_percent, type: :float
+        field :discount_amount, type: :float
+        field :discount_description, type: :string
+        field :sender_due_amount, type: :float
+        field :receiver_due_amount, type: :float
+        field :other_due_amount, type: :float
+        field :delivery_attempt_count, type: :integer
+        field :previous_shipment_number, type: :string
+        field :services, type: :array, of: Econt::Models::Shipments::ShipmentStatusService
+        field :last_processed_instruction, type: :string
+        field :next_shipments, type: :array, of: Econt::Models::Shipments::NextShipmentElement
+        field :tracking_events, type: :array, of: Econt::Models::Shipments::ShipmentTrackingEvent
+        field :pdf_url, type: :string
+        field :expected_delivery_date, type: :date
+        field :return_shipment_url, type: :string
+        field :reject_original_parcel_pay_side, type: :string
+        field :reject_return_parcel_pay_side, type: :string
+        field :shipment_edition, type: Econt::Models::Shipments::ShipmentEditionResponseElement
+        field :previous_shipment, type: Econt::Models::Shipments::PreviousShipment
+        field :warnings, type: :string
+        field :short_delivery_status, type: :string
+        field :short_delivery_status_en, type: :string
+        field :routing_code, type: :string
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/shipment_status_result_element.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ShipmentStatusResultElement < Econt::Model
+        collection_key :shipment_statuses
+
+        field :status, type: Econt::Models::Shipments::ShipmentStatus
+        field :error, type: Econt::Models::Error
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/shipment_status_service.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ShipmentStatusService < Econt::Model
+        field :type, type: :string
+        field :description, type: :string
+        field :count, type: :float
+        field :payment_side, type: :string
+        field :price, type: :float
+        field :currency, type: :string
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/shipment_tracking_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ShipmentTrackingEvent < Econt::Model
+        field :is_receipt, type: :boolean
+        field :destination_type, type: :string
+        field :destination_details, type: :string
+        field :destination_details_en, type: :string
+        field :office_name, type: :string
+        field :office_name_en, type: :string
+        field :city_name, type: :string
+        field :city_name_en, type: :string
+        field :country_code, type: :string
+        field :office_code, type: :string
+        field :time, type: :datetime
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/shipping_label.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ShippingLabel < Econt::Model
+        field :shipment_number, type: :string
+        field :previous_shipment_number, type: :string
+        field :previous_shipment_receiver_phone, type: :string
+        field :sender_client, type: Econt::Models::Profile::ClientProfile
+        field :sender_agent, type: Econt::Models::Profile::ClientProfile
+        field :sender_address, type: Econt::Models::Nomenclatures::Address
+        field :sender_office_code, type: :string
+        field :email_on_delivery, type: :string
+        field :sms_on_delivery, type: :string
+        field :receiver_client, type: Econt::Models::Profile::ClientProfile
+        field :receiver_agent, type: Econt::Models::Profile::ClientProfile
+        field :receiver_address, type: Econt::Models::Nomenclatures::Address
+        field :receiver_office_code, type: :string
+        field :receiver_provider_id, type: :integer
+        field :receiver_bic, type: :string
+        field :receiver_iban, type: :string
+        field :envelope_numbers, type: :array, of: :string
+        field :pack_count, type: :integer
+        field :packs, type: :array, of: Econt::Models::Shipments::PackElement
+        field :shipment_type, type: :string
+        field :weight, type: :float
+        field :size_under_60cm, type: :boolean
+        field :shipment_dimensions_l, type: :float
+        field :shipment_dimensions_w, type: :float
+        field :shipment_dimensions_h, type: :float
+        field :shipment_description, type: :string
+        field :order_number, type: :string
+        field :send_date, type: :date
+        field :holiday_delivery_day, type: :string
+        field :keep_upright, type: :boolean
+        field :services, type: Econt::Models::Shipments::ShippingLabelServices
+        field :instructions, type: :array, of: Econt::Models::Shipments::Instruction
+        field :pay_after_accept, type: :boolean
+        field :pay_after_test, type: :boolean
+        field :packing_list_type, type: :string
+        field :packing_list, type: :array, of: Econt::Models::Shipments::PackingListElement
+        field :partial_delivery, type: :boolean
+        field :payment_sender_method, type: :string
+        field :payment_receiver_method, type: :string
+        field :payment_receiver_amount, type: :float
+        field :payment_receiver_amount_is_percent, type: :boolean
+        field :payment_other_client_number, type: :string
+        field :payment_other_amount, type: :float
+        field :payment_other_amount_is_percent, type: :boolean
+        field :mediator, type: :string
+        field :payment_token, type: :string
+        field :customs_list, type: :array, of: Econt::Models::Shipments::CustomsListElement
+        field :customs_invoice, type: :string
+        field :cargo_vehicle_options, type: Econt::Models::Shipments::CargoVehicleOptions
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/shipping_label_services.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class ShippingLabelServices < Econt::Model
+        field :priority_time_from, type: :string
+        field :priority_time_to, type: :string
+        field :delivery_receipt, type: :boolean
+        field :digital_receipt, type: :boolean
+        field :goods_receipt, type: :boolean
+        field :two_way_shipment, type: :boolean
+        field :delivery_to_floor, type: :boolean
+        field :pack5, type: :integer
+        field :pack6, type: :integer
+        field :pack8, type: :integer
+        field :pack9, type: :integer
+        field :pack10, type: :integer
+        field :pack12, type: :integer
+        field :refrigerated_pack, type: :integer
+        field :declared_value_amount, type: :float
+        field :declared_value_currency, type: :string
+        field :money_transfer_amount, type: :float
+        field :express_money_transfer, type: :boolean
+        field :cd_amount, type: :float
+        field :cd_type, type: :string
+        field :cd_currency, type: :string
+        field :cd_pay_options_template, type: :string
+        field :cd_pay_options, type: Econt::Models::Profile::CDPayOptions
+        field :invoice_before_pay_cd, type: :boolean
+        field :sms_notification, type: :boolean
+        field :invoice_num, type: :string
+        field :money_transfer_currency, type: :string
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/status_response.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class StatusResponse < Econt::Model
+        field :status, type: :string
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/update_label_response.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class UpdateLabelResponse < Econt::Model
+        field :label, type: Econt::Models::Shipments::ShipmentStatus
+      end
+    end
+  end
+end

data/lib/econt/models/shipments/update_labels_result_element.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module Shipments
+      class UpdateLabelsResultElement < Econt::Model
+        collection_key :results
+
+        field :error, type: Econt::Models::Error
+        field :labels, type: Econt::Models::Shipments::UpdateLabelResponse
+      end
+    end
+  end
+end

data/lib/econt/models/three_way_logistics/three_way_logistics.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module ThreeWayLogistics
+      # Request fields use the API's legacy snake_case names.
+      class ThreeWayLogisticsRequest < Econt::Model
+        field :requester_name, type: :string
+        field :requester_phone, type: :string
+        field :requester_email, type: :string
+        field :requester_company_name, type: :string
+        field :requester_username, type: :string
+        field :supplier_company_name, type: :string
+        field :supplier_contact_person, type: :string
+        field :supplier_phone, type: :string
+        field :supplier_city, type: :string
+        field :supplier_address, type: :string
+        field :supplier_date_for_visit, type: :string
+        field :supplier_time_for_visit, type: :string
+        field :receiver_name, type: :string
+        field :receiver_company_name, type: :string
+        field :receiver_phone, type: :string
+        field :receiver_email, type: :string
+        field :description_shipment_description, type: :string
+        field :description_shipment_count, type: :string
+        field :description_shipment_weight, type: :string
+        field :description_additional_instructions, type: :string
+        field :description_payment_sum_to_supplier, type: :string
+        field :delivery_details_city, type: :string
+        field :delivery_details_address, type: :string
+        field :delivery_details_office, type: :string
+        field :dc, type: :string
+        field :dccp, type: :string
+        field :email_on_delivery, type: :string
+        field :invoice_before_pay, type: :string
+        field :preview, type: :string
+        field :test, type: :string
+        field :payment_delivery_and_return_by_me, type: :string
+        field :payment_return_by_me, type: :string
+        field :payment_delivery_by_requester, type: :string
+        field :payment_delivery_by_receiver, type: :string
+        field :oc_sum, type: :string
+        field :cd_sum, type: :string
+        field :priority_delivery_time_before, type: :string
+        field :priority_delivery_time_after, type: :string
+        field :priority_delivery_time_in, type: :string
+      end
+    end
+  end
+end

data/lib/econt/models/three_way_logistics/three_way_logistics_response.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Econt
+  module Models
+    module ThreeWayLogistics
+      # Econt documents a successful response as an object without properties.
+      class ThreeWayLogisticsResponse < Econt::Model
+      end
+    end
+  end
+end

data/lib/econt/resource_attributes.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module Econt
+  module ResourceAttributes
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def fields
+        @fields ||= {}
+      end
+
+      def field(name, opts = {})
+        fields[name] = opts
+
+        define_method(name) do
+          coerce_field_value(@attributes[name], opts)
+        end
+
+        define_method("#{name}=") do |value|
+          @attributes[name] = coerce_field_value(value, opts)
+        end
+      end
+    end
+
+    private
+
+    def coerce_field_value(value, options)
+      return nil if value.nil?
+
+      case options[:type]
+      when :integer then value.to_i
+      when :string then value.to_s
+      when :boolean then value == true || value.to_s.casecmp('true').zero?
+      when :float, :double then value.to_f
+      when :date then parse_temporal(value, Date)
+      when :datetime then parse_temporal(value, DateTime)
+      when :array then coerce_array(value, options[:of])
+      when Class then value.is_a?(options[:type]) ? value : options[:type].new(value)
+      else value
+      end
+    end
+
+    def coerce_array(value, item_type)
+      values = Array(value)
+      return values if item_type.nil?
+
+      values.map { |item| coerce_array_item(item, item_type) }
+    end
+
+    def coerce_array_item(value, type)
+      return value if type.is_a?(Class) && value.is_a?(type)
+      return type.new(value) if type.is_a?(Class)
+
+      coerce_field_value(value, type: type)
+    end
+
+    def parse_temporal(value, type)
+      return value if value.is_a?(type)
+
+      type.parse(value.to_s)
+    rescue ArgumentError
+      value
+    end
+  end
+end

data/lib/econt/service_resource.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Econt
+  class ServiceResource
+    attr_reader :client
+
+    class << self
+      def resource_type(value = name.split('::').last)
+        @resource_type = value
+      end
+    end
+
+    def initialize(client: Econt::Client.instance)
+      @client = client || raise('Econt::Client is not configured. Call `Econt::Client.configure` first.')
+    end
+
+    def resource_url
+      "#{service_url}/#{self.class.resource_type}Service"
+    end
+
+    ERROR_MESSAGES = {
+      400 => 'Your request was malformed.',
+      401 => 'You did not supply valid authentication credentials.',
+      403 => 'You are not allowed to perform that action.',
+      404 => 'No results were found for your request.',
+      429 => 'Your request exceeded the API rate limit.',
+      500 => 'We were unable to perform the request due to server-side problems.',
+      503 => 'You have been rate-limited for sending more than 20 requests per second.'
+    }.freeze
+
+    private
+
+    def get(url, params: {}, headers: {})
+      response_for(execute_request { client.connection.get(url_for(url), params, headers) })
+    end
+
+    def post(url, body: {}, headers: {})
+      response_for(execute_request { client.connection.post(url_for(url), body, headers) })
+    end
+
+    def post_raw(url, body:, headers: {})
+      json_headers = { 'Content-Type' => 'application/json' }.merge(headers)
+      json_body = JSON.generate(body)
+      response_for(execute_request { client.connection.post(url_for(url), json_body, json_headers) })
+    end
+
+    def patch(url, body:, headers: {})
+      response_for(execute_request { client.connection.patch(url_for(url), body, headers) })
+    end
+
+    def put(url, body:, headers: {})
+      response_for(execute_request { client.connection.put(url_for(url), body, headers) })
+    end
+
+    def delete(url, params: {}, headers: {})
+      response_for(execute_request { client.connection.delete(url_for(url), params, headers) })
+    end
+
+    def execute_request
+      yield
+    rescue Faraday::ConnectionFailed => e
+      raise Econt::ConnectionError.new('Econt API connection failed.'), cause: e
+    rescue Faraday::TimeoutError => e
+      raise Econt::TimeoutError.new('Econt API request timed out.'), cause: e
+    rescue Faraday::SSLError => e
+      raise Econt::SSLError.new('Econt API TLS connection failed.'), cause: e
+    end
+
+    def url_for(url, format = 'json')
+      "#{resource_url}.#{url}.#{format}"
+    end
+
+    def response_for(response)
+      error = error_from(response.body)
+      raise Error.new(error: error, status: response.status) if error && server_error?(response)
+      return response if error
+
+      error_message = ERROR_MESSAGES[response.status]
+      raise Error.new(error_message, status: response.status) if error_message
+      raise Error.new(status: response.status) unless successful_response?(response)
+
+      response
+    end
+
+    def collection(response, model)
+      model.collection(response.body)
+    end
+
+    def resource(response, model, key: nil)
+      model.build(response.body, key: key)
+    end
+
+    def error_from(body)
+      Econt::Models::Error.build_from(body)
+    end
+
+    def successful_response?(response)
+      response.status.to_i.between?(200, 299)
+    end
+
+    def server_error?(response)
+      response.status.to_i.between?(500, 599)
+    end
+  end
+end

data/lib/econt/services/nomenclatures/address.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Econt
+  module Services
+    module Nomenclatures
+      class Address < Econt::ServiceResource
+        include Econt::Services::Nomenclatures
+
+        resource_type 'Address'
+
+        # POST /services/Nomenclatures/AddressService.validateAddress.json(.soap?wsdl)
+        # Validate and normalize an address.
+        # @note Read. Does not change shipment state.
+        # @param address [Hash, Econt::Models::Nomenclatures::Address] Address fields; the argument is positional.
+        # @return [Econt::Models::Nomenclatures::AddressValidationResponse]
+        #   Check #error? before using data.
+        # @raise [Econt::Error] On HTTP failure.
+        # @raise [Econt::TransportError] On connection, timeout, or TLS failure; inspect its subclass.
+        # @see file:docs/API.md#validate_address Ruby usage and parameters
+        # @example After configuring Econt::Client
+        #   addresses = Econt::Services::Nomenclatures::Address.new
+        #   validation = addresses.validate_address(city: { id: 41 }, street: 'Витоша', num: '1')
+        def validate_address(address)
+          address = address_to_hash(address)
+          response = post('validateAddress', body: { address: address })
+          resource(response, Econt::Models::Nomenclatures::AddressValidationResponse)
+        end
+
+        # POST /services/Nomenclatures/AddressService.addressServiceTimes.json(.soap?wsdl)
+        # Look up address service availability for a date and shipment type.
+        # @note Read. Does not change shipment state.
+        # @param city [Hash] City fields.
+        # @param address [Hash] Address fields.
+        # @param date [String] Requested service date in the carrier format.
+        # @param shipment_type [String] Carrier shipment type, such as pack.
+        # @return [Econt::Models::Nomenclatures::AddressServiceTimesResponse]
+        #   Check #error? before using data.
+        # @raise [Econt::Error] On HTTP failure.
+        # @raise [Econt::TransportError] On connection, timeout, or TLS failure; inspect its subclass.
+        # @see file:docs/API.md#address_service_times Ruby usage and parameters
+        # @example After configuring Econt::Client
+        #   addresses = Econt::Services::Nomenclatures::Address.new
+        #   times = addresses.address_service_times(
+        #     city: { id: 41 }, address: address_payload,
+        #     date: '2026-10-12', shipment_type: 'pack'
+        #   )
+        def address_service_times(city:, address:, date:, shipment_type:)
+          response = post('addressServiceTimes', body: {
+                            city: city,
+                            address: address,
+                            date: date,
+                            shipment_type: shipment_type
+                          })
+          resource(response, Econt::Models::Nomenclatures::AddressServiceTimesResponse)
+        end
+
+        # POST /services/Nomenclatures/AddressService.getNearestOffices.json(.soap?wsdl)
+        # Find offices near an address for a shipment type.
+        # @note Read. Does not change shipment state.
+        # @param address [Hash] Address fields.
+        # @param shipment_type [String] Carrier shipment type.
+        # @return [Econt::Collection<Econt::Models::Nomenclatures::Office>]
+        #   Check #error? before using data.
+        # @raise [Econt::Error] On HTTP failure.
+        # @raise [Econt::TransportError] On connection, timeout, or TLS failure; inspect its subclass.
+        # @see file:docs/API.md#get_nearest_offices Ruby usage and parameters
+        # @example After configuring Econt::Client
+        #   addresses = Econt::Services::Nomenclatures::Address.new
+        #   offices = addresses.get_nearest_offices(address: address_payload, shipment_type: 'pack')
+        def get_nearest_offices(address:, shipment_type:)
+          response = post('getNearestOffices', body: { address: address, shipment_type: shipment_type })
+          collection(response, Econt::Models::Nomenclatures::Office)
+        end
+
+        private
+
+        def address_to_hash(address)
+          if address.is_a?(Econt::Models::Nomenclatures::Address)
+            address.to_h
+          else
+            Econt::Models::Nomenclatures::Address.new(address).to_h
+          end
+        end
+      end
+    end
+  end
+end