econt 0.1.0

data/docs/API.md

@@ -0,0 +1,571 @@
+# Ruby API reference
+
+This gem supports Econt's JSON endpoints only, not SOAP.
+
+Every public service method is listed below. Configure `Econt::Client` first
+(see the [README](../README.md#configuration)); constructing a service does not
+send a request. Services share the configured client by default, or accept
+`new(client: configured_client)` for a separately configured `Econt::Client`.
+
+## Receivers and method index
+
+| Receiver | Class | Methods |
+| --- | --- | --- |
+| `nomenclatures` | `Econt::Services::Nomenclatures::Nomenclatures` | [get_countries](#get_countries), [get_cities](#get_cities), [get_regions](#get_regions), [get_offices](#get_offices), [get_streets](#get_streets), [get_quarters](#get_quarters) |
+| `addresses` | `Econt::Services::Nomenclatures::Address` | [validate_address](#validate_address), [address_service_times](#address_service_times), [get_nearest_offices](#get_nearest_offices) |
+| `labels` | `Econt::Services::Shipments::Label` | [create_label](#create_label), [create_labels](#create_labels), [delete_labels](#delete_labels), [update_label](#update_label), [check_possible_shipment_editions](#check_possible_shipment_editions), [update_labels](#update_labels), [grouping](#grouping), [grouping_cancelation](#grouping_cancelation) |
+| `shipments` | `Econt::Services::Shipments::Shipment` | [request_courier](#request_courier), [get_shipment_statuses](#get_shipment_statuses), [get_request_courier_status](#get_request_courier_status), [get_my_awb](#get_my_awb), [set_itu_code](#set_itu_code) |
+| `profiles` | `Econt::Services::Profile::Profile` | [get_client_profiles](#get_client_profiles), [create_cd_agreement](#create_cd_agreement) |
+| `reports` | `Econt::Services::PaymentReport::PaymentReport` | [payment_report](#payment_report) |
+| `logistics` | `Econt::Services::ThreeWayLogistics::ThreeWayLogistics` | [three_way_logistics](#three_way_logistics) |
+
+```ruby
+nomenclatures = Econt::Services::Nomenclatures::Nomenclatures.new
+addresses = Econt::Services::Nomenclatures::Address.new
+labels = Econt::Services::Shipments::Label.new
+shipments = Econt::Services::Shipments::Shipment.new
+profiles = Econt::Services::Profile::Profile.new
+reports = Econt::Services::PaymentReport::PaymentReport.new
+logistics = Econt::Services::ThreeWayLogistics::ThreeWayLogistics.new
+```
+
+## How to use the reference
+
+Signatures show Ruby defaults, not carrier requirements: an optional `nil`
+or empty array does **not** mean the API accepts an incomplete request. Supply
+the business fields required by the [official EEcont documentation](http://ee.econt.com/services/).
+Nested hashes use snake_case except the legacy three-way logistics operation.
+
+Examples are independent snippets, not a script to execute wholesale.
+`address_payload`, `label_payload`, `updated_label_payload`,
+`courier_payload`, `cd_pay_options_payload`, and `logistics_payload` are
+application-owned hashes. Identifiers must belong to your account.
+Dates and office/city IDs are illustrative; replace them before making requests.
+
+Typed results expose snake_case readers and `to_h`. Collections are enumerable,
+so use `each`, `first`, and `to_a`. Check `error?` on the result **and**
+individual batch elements. HTTP failures raise `Econt::Error`. Connection,
+timeout, and TLS failures raise `Econt::ConnectionError`, `Econt::TimeoutError`,
+and `Econt::SSLError`, all subclasses of `Econt::TransportError < Econt::Error`.
+Catch `Econt::Error` at your application's boundary. Parsing and programming
+exceptions are not reclassified. The client never retries automatically; a
+mutation timeout does not prove it failed.
+
+```ruby
+begin
+  result = labels.create_label(label: label_payload, mode: 'validate')
+  if result.error?
+    # Handle result.error without exposing private carrier data.
+  else
+    result.label.to_h
+  end
+rescue Econt::Error => error
+  # Record a safe diagnostic and decide whether reconciliation is needed.
+end
+```
+
+Transport exception messages are fixed diagnostics without adapter details.
+Their `cause` preserves the original Faraday exception; `cause`, backtraces,
+and `full_message` may contain credentials, URLs, or personal data. Do not log
+those blindly. Without an HTTP response, `status` and `error` are `nil`.
+
+Mutations affect the selected environment. Read [cleanup limitations](VCR.md)
+before using them. `calculate_with_block` reserves a label number; it is not
+equivalent to a read-only quote. No example promises deletion or cancellation
+will succeed after processing has started.
+
+## Methods
+
+### get_countries
+
+`nomenclatures.get_countries`
+
+List countries available for delivery.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Nomenclatures::Country>`.
+
+No arguments.
+
+```ruby
+countries = nomenclatures.get_countries
+```
+
+### get_cities
+
+`nomenclatures.get_cities(country_code:)`
+
+List cities for a country.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Nomenclatures::City>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `country_code` | `String` | ISO country code, such as BGR. |
+
+```ruby
+cities = nomenclatures.get_cities(country_code: 'BGR')
+```
+
+### get_regions
+
+`nomenclatures.get_regions(country_code:, language: nil)`
+
+Fetch cities and derive unique, sorted region names; this is a local helper, not a separate endpoint.
+
+Safety: **Read**. Returns `Array<String>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `country_code` | `String` | Country code. |
+| `language` | `String, nil` | Only en selects English names; nil and other values select native names. |
+
+This helper returns an ordinary array of names, not a model or collection. It
+performs one `get_cities` request. HTTP/transport exceptions propagate, but an
+embedded carrier error can yield an empty array. Use `get_cities` directly when
+you need to distinguish that from a country with no regions.
+
+```ruby
+regions = nomenclatures.get_regions(country_code: 'BGR', language: 'en')
+```
+
+### get_offices
+
+`nomenclatures.get_offices(country_code:, city_id: nil, show_cargo_receptions: nil, show_lc: nil, serving_receptions: nil)`
+
+List offices with optional city and reception filters.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Nomenclatures::Office>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `country_code` | `String` | Country code. |
+| `city_id` | `Integer, nil` | City identifier. |
+| `show_cargo_receptions` | `Boolean, nil` | Include cargo receptions. |
+| `show_lc` | `Boolean, nil` | Carrier LC filter. |
+| `serving_receptions` | `Boolean, nil` | Carrier serving-reception filter. |
+
+```ruby
+offices = nomenclatures.get_offices(country_code: 'BGR', city_id: 41)
+```
+
+### get_streets
+
+`nomenclatures.get_streets(city_id: nil)`
+
+List streets, optionally restricted to a city.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Nomenclatures::Street>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `city_id` | `Integer, nil` | City identifier. |
+
+```ruby
+streets = nomenclatures.get_streets(city_id: 41)
+```
+
+### get_quarters
+
+`nomenclatures.get_quarters(city_id: nil)`
+
+List quarters, optionally restricted to a city.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Nomenclatures::Quarter>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `city_id` | `Integer, nil` | City identifier. |
+
+```ruby
+quarters = nomenclatures.get_quarters(city_id: 41)
+```
+
+### validate_address
+
+`addresses.validate_address(address)`
+
+Validate and normalize an address.
+
+Safety: **Read**. Returns `Econt::Models::Nomenclatures::AddressValidationResponse`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `address` | `Hash, Econt::Models::Nomenclatures::Address` | Address fields; the argument is positional. |
+
+```ruby
+validation = addresses.validate_address(city: { id: 41 }, street: 'Витоша', num: '1')
+```
+
+### address_service_times
+
+`addresses.address_service_times(city:, address:, date:, shipment_type:)`
+
+Look up address service availability for a date and shipment type.
+
+Safety: **Read**. Returns `Econt::Models::Nomenclatures::AddressServiceTimesResponse`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `city` | `Hash` | City fields. |
+| `address` | `Hash` | Address fields. |
+| `date` | `String` | Requested service date in the carrier format. |
+| `shipment_type` | `String` | Carrier shipment type, such as pack. |
+
+```ruby
+times = addresses.address_service_times(
+  city: { id: 41 }, address: address_payload,
+  date: '2026-10-12', shipment_type: 'pack'
+)
+```
+
+### get_nearest_offices
+
+`addresses.get_nearest_offices(address:, shipment_type:)`
+
+Find offices near an address for a shipment type.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Nomenclatures::Office>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `address` | `Hash` | Address fields. |
+| `shipment_type` | `String` | Carrier shipment type. |
+
+```ruby
+offices = addresses.get_nearest_offices(address: address_payload, shipment_type: 'pack')
+```
+
+### create_label
+
+`labels.create_label(label: nil, request_courier_time_from: nil, request_courier_time_to: nil, mode: nil)`
+
+Calculate, validate, or create one shipping label.
+
+Safety: **Conditional mutation**. Returns `Econt::Models::Shipments::CreateLabelResultElement`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `label` | `Hash, nil` | Shipping-label payload. |
+| `request_courier_time_from` | `String, nil` | Requested courier window start. |
+| `request_courier_time_to` | `String, nil` | Requested courier window end. |
+| `mode` | `String, nil` | calculate or validate are non-mutating; create and calculate_with_block have effects. Always choose explicitly. |
+
+The result contains `label` (a `ShippingLabel`), including prices and PDF URLs when supplied by the carrier. Use `mode: 'create'` only deliberately; `mode: 'calculate_with_block'` can reserve a number. Courier window arguments may request collection. PDF URLs are carrier-hosted; this method does not download them.
+
+```ruby
+quote = labels.create_label(label: label_payload, mode: 'calculate')
+```
+
+### create_labels
+
+`labels.create_labels(labels: [], run_async_and_email_result_to: nil, mode: nil)`
+
+Calculate, validate, or create a batch of labels.
+
+Safety: **Conditional mutation**. Returns `Econt::Collection<Econt::Models::Shipments::CreateLabelResultElement>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `labels` | `Array<Hash>` | Shipping-label payloads. |
+| `run_async_and_email_result_to` | `String, nil` | Email address for asynchronous results; the returned data may differ. |
+| `mode` | `String, nil` | Choose calculate, validate, or create explicitly. |
+
+Each item is a `CreateLabelResultElement`; inspect its `error?` before reading `label`. Use synchronous requests when you need the immediate batch result. Asynchronous email behavior is not independently contract-verified.
+
+```ruby
+quotes = labels.create_labels(labels: [label_payload], mode: 'calculate')
+```
+
+### delete_labels
+
+`labels.delete_labels(shipment_numbers: [])`
+
+Delete selected labels when allowed by carrier state and account permissions.
+
+Safety: **Mutation**. Returns `Econt::Collection<Econt::Models::Shipments::DeleteLabelsResultElement>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `shipment_numbers` | `Array<String>` | Numbers of labels owned by your account. |
+
+Inspect every `DeleteLabelsResultElement` and reconcile via `shipments.get_shipment_statuses`; a successful HTTP response alone does not prove every label was deleted.
+
+```ruby
+deleted = labels.delete_labels(shipment_numbers: [shipment_number])
+```
+
+### update_label
+
+`labels.update_label(label: nil, request_courier_time_from: nil, request_courier_time_to: nil, destroy: nil, payment_addition_price: nil, payment_instruction: nil)`
+
+Update or destroy an existing label.
+
+Safety: **Mutation**. Returns `Econt::Models::Shipments::UpdateLabelResponse`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `label` | `Hash, nil` | Existing label with its shipment number and requested changes. |
+| `request_courier_time_from` | `String, nil` | Courier window start. |
+| `request_courier_time_to` | `String, nil` | Courier window end. |
+| `destroy` | `Boolean, nil` | Whether to destroy the label. |
+| `payment_addition_price` | `Hash, nil` | PaymentAdditionPrice fields. |
+| `payment_instruction` | `Hash, nil` | PaymentInstruction fields. |
+
+```ruby
+updated = labels.update_label(label: updated_label_payload, destroy: false)
+```
+
+### check_possible_shipment_editions
+
+`labels.check_possible_shipment_editions(shipment_nums: [])`
+
+Check which edits are permitted for existing shipments.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Shipments::CheckPossibleShipmentEditionsResultElement>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `shipment_nums` | `Array<Integer>` | Shipment numbers in the carrier field type. |
+
+```ruby
+editions = labels.check_possible_shipment_editions(shipment_nums: [1234567890123])
+```
+
+### update_labels
+
+`labels.update_labels(labels: [])`
+
+Update several existing labels.
+
+Safety: **Mutation**. Returns `Econt::Collection<Econt::Models::Shipments::UpdateLabelsResultElement>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `labels` | `Array<Hash>` | Existing labels and requested changes. |
+
+Each item exposes optional `labels` (an `UpdateLabelResponse`) and `error`. The unusual plural reader matches the carrier contract.
+
+```ruby
+updated = labels.update_labels(labels: [updated_label_payload])
+```
+
+### grouping
+
+`labels.grouping(labels: [])`
+
+Group existing labels into a group label.
+
+Safety: **Mutation**. Returns `Econt::Models::Shipments::ShipmentStatus`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `labels` | `Array<Integer>` | Shipment numbers to group. |
+
+`labels` contains integer shipment numbers, not shipping-label hashes. Grouping cleanup is carrier-state dependent.
+
+```ruby
+group = labels.grouping(labels: [1234567890123, 1234567890124])
+```
+
+### grouping_cancelation
+
+`labels.grouping_cancelation(group_label: nil)`
+
+Cancel an existing group label.
+
+Safety: **Mutation**. Returns `Econt::Models::Shipments::StatusResponse`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `group_label` | `Integer, nil` | Group-label shipment number. |
+
+The Ruby spelling preserves the carrier operation `groupingCancelation`.
+
+```ruby
+result = labels.grouping_cancelation(group_label: group_label_number)
+```
+
+### request_courier
+
+`shipments.request_courier(**attributes)`
+
+Book a courier collection; pass the documented request fields as keywords.
+
+Safety: **Mutation**. Returns `Econt::Models::Shipments::RequestCourierResponse`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `attributes` | `Hash` | Courier payload as keywords: request_time_from, request_time_to, shipment_type, shipment_pack_count, shipment_weight, sender_client, sender_agent, sender_address, attach_shipments, pack12, cargo_vehicle_options. |
+
+```ruby
+booking = shipments.request_courier(**courier_payload)
+```
+
+### get_shipment_statuses
+
+`shipments.get_shipment_statuses(shipment_numbers: [])`
+
+Read shipment status, tracking events, and label information.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Shipments::ShipmentStatusResultElement>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `shipment_numbers` | `Array<String>` | Shipment numbers to query. |
+
+Each item exposes `status` (a `ShipmentStatus`) and an optional error. Read `statuses.first.status` only after checking both collection and item errors.
+
+```ruby
+statuses = shipments.get_shipment_statuses(shipment_numbers: [shipment_number])
+```
+
+### get_request_courier_status
+
+`shipments.get_request_courier_status(request_courier_ids: [])`
+
+Read the status of courier collection requests.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Shipments::RequestCourierStatusResultElement>`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `request_courier_ids` | `Array<Integer>` | Courier request identifiers. |
+
+```ruby
+statuses = shipments.get_request_courier_status(request_courier_ids: [courier_request_id])
+```
+
+### get_my_awb
+
+`shipments.get_my_awb(date_from: nil, date_to: nil, page: nil, side: nil)`
+
+List account waybills using optional date, page, and side filters.
+
+Safety: **Read**. Returns `Econt::Models::Shipments::GetMyAwbResponse`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `date_from` | `String, nil` | Start date in carrier format. |
+| `date_to` | `String, nil` | End date in carrier format. |
+| `page` | `Integer, nil` | Requested page. |
+| `side` | `String, nil` | Carrier side filter; see getMyAWB documentation for allowed values. |
+
+```ruby
+waybills = shipments.get_my_awb(date_from: '2026-10-01', date_to: '2026-10-12', page: 1)
+```
+
+### set_itu_code
+
+`shipments.set_itu_code(awb_barcode:, truck_reg_num:, itu_code:)`
+
+Assign ITU transport metadata to a waybill.
+
+Safety: **Mutation**. Returns `Faraday::Response`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `awb_barcode` | `String` | Waybill barcode. |
+| `truck_reg_num` | `String` | Truck registration number. |
+| `itu_code` | `String` | ITU code; sent with the carrier spelling ITU_code. |
+
+This operation returns the raw Faraday response, unlike typed endpoints. Inspect `response.body`; no `error?` reader is provided.
+
+```ruby
+response = shipments.set_itu_code(
+  awb_barcode: shipment_number, truck_reg_num: truck_registration, itu_code: itu_code
+)
+response.body
+```
+
+### get_client_profiles
+
+`profiles.get_client_profiles`
+
+Read account client profiles and payment settings.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::Profile::ProfilesResponseElement>`.
+
+No arguments.
+
+Each item is a `ProfilesResponseElement`; account-specific profiles are nested in its documented readers.
+
+```ruby
+clients = profiles.get_client_profiles
+```
+
+### create_cd_agreement
+
+`profiles.create_cd_agreement(cd_pay_options:)`
+
+Create a cash-on-delivery payment agreement.
+
+Safety: **Mutation**. Returns `Econt::Models::Profile::CDPayOptions`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `cd_pay_options` | `Hash` | CDPayOptions payload; account eligibility is carrier-controlled. |
+
+```ruby
+agreement = profiles.create_cd_agreement(cd_pay_options: cd_pay_options_payload)
+```
+
+### payment_report
+
+`reports.payment_report(date_to: nil, date_from: nil)`
+
+Read payment reports for an optional date range.
+
+Safety: **Read**. Returns `Econt::Collection<Econt::Models::PaymentReport::PaymentReportRow>, Econt::Models::PaymentReport::PaymentReportRow`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `date_to` | `String, nil` | End date in carrier format. |
+| `date_from` | `String, nil` | Start date in carrier format. |
+
+The reviewed demo `PaymentReportRows` envelope returns a collection. The documented bare-row response returns one row; the example normalizes both to an array.
+
+```ruby
+rows = reports.payment_report(date_from: '2026-10-01', date_to: '2026-10-12')
+rows = rows.is_a?(Econt::Collection) ? rows.to_a : [rows]
+```
+
+### three_way_logistics
+
+`logistics.three_way_logistics(**attributes)`
+
+Submit a three-way logistics request using legacy snake_case fields without camelCase conversion.
+
+Safety: **Mutation**. Returns `Econt::Models::ThreeWayLogistics::ThreeWayLogisticsResponse`.
+
+| Parameter | Type | Meaning |
+| --- | --- | --- |
+| `attributes` | `Hash` | Legacy request fields as keywords; see ThreeWayLogisticsRequest for available field names. |
+
+Request fields retain legacy snake_case on the wire. See `Econt::Models::ThreeWayLogistics::ThreeWayLogisticsRequest` for declared field names. The response contract has no authoritative successful fields, so the typed response currently has no data readers. Do not infer successful fulfillment from an empty model.
+
+```ruby
+result = logistics.three_way_logistics(**logistics_payload)
+```
+
+## Payload and model details
+
+For nested request fields, consult the corresponding operation and model on the
+[official service index](http://ee.econt.com/services/): `ShippingLabel`,
+`Address`, `ClientProfile`, `CDPayOptions`, `PaymentInstruction`,
+`PaymentAdditionPrice`, and `ThreeWayLogisticsRequest`.
+The gem forwards supplied request fields; it does not perform full business validation.
+
+Generate a searchable local method reference directly from
+the source comments:
+
+```bash
+bundle install
+bundle exec rake yard
+open doc/index.html
+```
+
+Generated HTML lives in ignored `doc/`; Markdown lives in this repository and
+is included in the gem. No GitHub wiki or hosted documentation is required.
+YARD is a development dependency only. See [public API decisions](PUBLIC_API.md)
+for coercion and response limitations, and [endpoint coverage](ENDPOINTS.md) for
+the Ruby-to-carrier operation mapping.

data/docs/ENDPOINTS.md

@@ -0,0 +1,42 @@
+# Supported endpoints
+
+All service operations use HTTP `POST`. Model names below omit the
+`Econt::Models` namespace; collections are `Econt::Collection` instances.
+
+| Area | Ruby method | Econt operation | Return value |
+| --- | --- | --- | --- |
+| Nomenclatures | `get_countries` | `getCountries` | collection of `Country` |
+| Nomenclatures | `get_cities` | `getCities` | collection of `City` |
+| Nomenclatures | `get_offices` | `getOffices` | collection of `Office` |
+| Nomenclatures | `get_streets` | `getStreets` | collection of `Street` |
+| Nomenclatures | `get_quarters` | `getQuarters` | collection of `Quarter` |
+| Address | `validate_address` | `validateAddress` | `AddressValidationResponse` |
+| Address | `address_service_times` | `addressServiceTimes` | `AddressServiceTimesResponse` |
+| Address | `get_nearest_offices` | `getNearestOffices` | collection of `Office` |
+| Labels | `create_label` | `createLabel` | `CreateLabelResultElement` |
+| Labels | `create_labels` | `createLabels` | collection of results |
+| Labels | `delete_labels` | `deleteLabels` | collection of results |
+| Labels | `update_label` | `updateLabel` | `UpdateLabelResponse` |
+| Labels | `check_possible_shipment_editions` | `checkPossibleShipmentEditions` | collection of results |
+| Labels | `update_labels` | `updateLabels` | collection of results |
+| Labels | `grouping` | `grouping` | `ShipmentStatus` |
+| Labels | `grouping_cancelation` | `groupingCancelation` | `StatusResponse` |
+| Shipments | `request_courier` | `requestCourier` | `RequestCourierResponse` |
+| Shipments | `get_shipment_statuses` | `getShipmentStatuses` | collection of results |
+| Shipments | `get_request_courier_status` | `getRequestCourierStatus` | collection of results |
+| Shipments | `get_my_awb` | `getMyAWB` | `GetMyAwbResponse` |
+| Shipments | `set_itu_code` | `setITUCode` | raw documented response |
+| Profile | `get_client_profiles` | `getClientProfiles` | collection of profiles |
+| Profile | `create_cd_agreement` | `createCDAgreement` | `CDPayOptions` |
+| Payment reports | `payment_report` | `PaymentReport` | collection of `PaymentReportRow`; bare row also supported |
+| Three-way logistics | `three_way_logistics` | `threeWayLogistics` | empty typed response |
+
+`get_regions(country_code:, language: nil)` is a local helper, not an Econt
+endpoint. It calls `get_cities` and returns unique, sorted region names (English
+when `language: 'en'`).
+
+The spelling of `PaymentReport`, `getMyAWB`, `groupingCancelation`, and
+`setITUCode` follows Econt's published operation names. Every listed operation
+has offline example-response coverage; that is not equivalent to live contract
+verification. See [response tests](RESPONSE_TESTS.md), [VCR coverage](VCR.md), and
+[public API limitations](PUBLIC_API.md).

data/docs/PUBLIC_API.md

@@ -0,0 +1,81 @@
+# Public API contract
+
+This document records the compatibility decisions intended to remain stable
+once the gem reaches version 1.0. The official EEcont documentation remains the
+authority for required business fields and carrier behavior.
+
+## Request and response conventions
+
+- Only JSON endpoints are supported; SOAP is outside this gem's scope.
+- Public service methods accept snake_case Ruby keywords and hashes. The
+  middleware converts request keys to Econt's documented JSON casing.
+- Responses are typed `Econt::Model` instances or `Econt::Collection` objects,
+  as listed in the [Ruby API reference](API.md). Model readers use snake_case.
+- Declared scalar fields are coerced to the documented primitive Ruby type.
+  Dates and date-times become `Date` and `DateTime` when parsing succeeds.
+- Missing optional fields return `nil`. Unknown response fields are ignored so
+  an additive carrier response does not unexpectedly expand the gem's public
+  model API. A new gem release can expose a documented field deliberately.
+- `to_h` returns snake_case symbol keys. `to_json` converts keys back to Econt's
+  request casing.
+- `Econt::Collection` is enumerable and exposes `to_a`, `size`, `length`, and
+  `count`; it is intentionally not an `Array` subclass.
+
+Request parameters remain hashes because Econt's label and courier requests are
+large, nested, and frequently revised. Responses are models because stable
+readers, coercion, and nested types provide useful guarantees without forcing
+callers to construct a very large request object graph.
+
+## Errors
+
+Transport failures and non-success HTTP statuses raise `Econt::Error`. Its
+`status` contains the HTTP status when available, and `error` contains a typed
+`Econt::Models::Error` when Econt returned one.
+
+`Econt::TransportError < Econt::Error` is the common parent of
+`ConnectionError`, `TimeoutError`, and `SSLError`. These wrap only Faraday's
+connection, timeout, and TLS exceptions; parsing and programming errors retain
+their original types. The original exception is preserved as `cause`, while
+the wrapper message is a fixed safe diagnostic. No response means `status` and
+`error` are `nil`. Causes, backtraces, and `full_message` may expose sensitive
+adapter details, so scrub them before logging. No request is retried
+automatically; reconcile mutations before deciding to retry.
+
+Some Econt operations return an error object within an otherwise successful
+response. Models and collections therefore expose `error?` and `error`. This is
+kept separate from HTTP exceptions because it matches the carrier contract and
+allows batch operations to contain both successful and failed elements.
+
+## Documented response decisions
+
+- `update_labels` returns a collection of `UpdateLabelsResultElement`. Econt
+  explicitly documents each element as optional `error` plus optional `labels`,
+  where `labels` is an `UpdateLabelResponse`. The unusual plural field name is
+  retained instead of inventing a singular alias.
+- `PreviousShipment#shipment_number` is an `Integer`, because Econt documents
+  that particular field as `int`, even though most other shipment-number fields
+  are strings. The inconsistency is intentionally represented rather than
+  normalized.
+- `payment_report` returns a collection of `PaymentReportRow` when the response
+  contains `PaymentReportRows`, as seen in the reviewed demo recording. A null
+  envelope produces an empty collection. The OpenAPI schema instead describes a
+  bare row; that shape remains supported and returns one `PaymentReportRow`.
+- `three_way_logistics` returns `ThreeWayLogisticsResponse`, currently an empty
+  typed model. Econt documents request fields but no successful response fields.
+  The gem does not invent undocumented readers.
+
+Three-way logistics should be checked against demo responses before the 1.0 API
+is frozen. If its actual response differs, correct the model during the pre-1.0
+series and record the evidence in a scrubbed contract test.
+
+## Compatibility policy
+
+The gem follows [Semantic Versioning 2.0.0](https://semver.org/). During the
+pre-1.0 series, minor versions may refine or correct the public contract as
+real carrier responses are verified. These changes must still be documented.
+
+After 1.0, removing or renaming public methods, changing accepted keywords, or
+changing documented return types requires a new major version. Adding endpoint
+methods, optional model readers, or new error subclasses is normally backward
+compatible. Carrier-side behavior outside the gem's control is documented but
+cannot be covered by semantic-version guarantees.