econt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 72d630d421e9bfb7d741ba051f81722c740f251fd6d50e2d66b98fb73d1aba4f
+  data.tar.gz: a1c465eaf16fecc9a83f114d0e5403de12e2af41d24b7a2381cde2a3d1968165
+SHA512:
+  metadata.gz: cc999dd5f5f08b1468d56444500a5b623a56a16a3f805757db5899a8365dbc56315ea9a5139d5f3768b54a076bcfe16735166030d4c5794c91efcd6808d26dbf
+  data.tar.gz: 553ef848b6016d4d1635dba09e8a7f27c0b6aca61ac3f974a31d62c9f47bfe34e2451d132a90dfc76477f0d5cd81e8363c735a7cd97a28e87fdae1072f603211

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+Release notes will start after the initial release.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,17 @@
+# Code of conduct
+
+Be respectful, constructive, and patient in project discussions. Harassment,
+discrimination, threats, publication of another person's private information,
+and intentionally disruptive behavior are not accepted.
+
+Maintainers may edit or remove comments, issues, pull requests, and other
+contributions that violate these expectations, and may temporarily or
+permanently restrict participation when necessary.
+
+Report conduct concerns through GitHub's private reporting facilities when
+available. If no private channel is available, open an issue asking the
+maintainer to establish one without including sensitive details.
+
+This is a small, volunteer-maintained project. Disagreement about a technical
+decision is welcome when it stays focused on the work and treats participants
+with respect.

data/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thank you for improving this community-maintained Econt client.
+
+## Support expectations
+
+Issues and pull requests are reviewed on a best-effort basis, usually on
+weekends. There is no guaranteed response time, service-level agreement, or
+commitment to implement feature requests. Focused pull requests for fixes and
+documented endpoints are welcome. The MIT license also permits you to fork and
+maintain behavior tailored to your application.
+
+Use GitHub Issues for reproducible bugs, documentation gaps, and focused feature
+proposals. Include the gem version, Ruby version, environment (demo or
+production), the service method, expected behavior, and a minimal sanitized
+example. Never include credentials, Authorization headers, real names, phone
+numbers, addresses, shipment numbers, or unredacted carrier responses.
+
+Security vulnerabilities belong in the private process described in
+[SECURITY.md](SECURITY.md), not in a public issue.
+
+## Pull requests
+
+1. Open an issue first for a public API change or a large addition.
+2. Keep changes focused and preserve Econt's documented casing at the HTTP
+   boundary while exposing snake_case Ruby APIs.
+3. Add request-payload and response-model specs.
+4. Update RBS and public documentation when the API changes.
+5. Run `bundle exec rake`, `bundle exec rbs validate`, and
+   `bin/package_smoke_test`.
+
+Normal tests must not contact Econt. Contract recordings are opt-in, must use
+the demo environment, and must be carefully scrubbed before they are proposed.
+Do not record state-changing label or courier operations without prior project
+discussion.
+
+By participating, you agree to follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Boyan Georgiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+# Econt
+
+A Ruby client for Econt's EEcont JSON API, with snake_case request keys,
+typed responses, Basic authentication, and configurable timeouts.
+
+Only JSON endpoints are supported; SOAP is not supported.
+
+Community maintained; not affiliated with or endorsed by Econt.
+See the [official API documentation](http://ee.econt.com/services/) for account
+access and required fields.
+
+## Installation
+
+Requires Ruby 3.3 or later; CI tests Ruby 3.3, 3.4, and 4.0.
+
+```bash
+bundle add econt
+```
+
+## Configuration
+
+```ruby
+Econt::Client.configure do |config|
+  config.username = ENV.fetch('ECONT_USERNAME')
+  config.password = ENV.fetch('ECONT_PASSWORD')
+  # Demo is the default. Use this URL for production:
+  config.base_url = 'http://ee.econt.com/services/'
+  config.open_timeout = 10
+  config.read_timeout = 30
+  config.write_timeout = 30
+end
+```
+
+**Transport warning:** Econt documents HTTP service endpoints. Basic credentials
+and shipment data are transmitted without TLS. Use a trusted server-side network
+path and assess this risk before production use; never call the API from browser
+code. Demo uses `http://demo.econt.com/ee/services/`, with separate credentials.
+The client does not replace documented URLs with HTTPS.
+
+### Rails initializer
+
+```ruby
+# config/initializers/econt.rb
+Econt::Client.configure do |config|
+  config.username = Rails.application.credentials.dig(:econt, :username)
+  config.password = Rails.application.credentials.dig(:econt, :password)
+  config.base_url = ENV.fetch('ECONT_BASE_URL', 'http://demo.econt.com/ee/services/')
+end
+```
+
+Debug logging is opt-in with `config.debug = true` and
+`config.debug_logger = Rails.logger`. Credentials are filtered; bodies are
+excluded by default. `config.debug_bodies = true` can expose personal and
+commercial data—use only for controlled local investigation.
+
+## Usage
+
+Requests use snake_case keys; responses expose snake_case readers and `to_h`.
+
+```ruby
+nomenclatures = Econt::Services::Nomenclatures::Nomenclatures.new
+cities = nomenclatures.get_cities(country_code: 'BGR')
+offices = nomenclatures.get_offices(country_code: 'BGR', city_id: cities.first.id)
+
+addresses = Econt::Services::Nomenclatures::Address.new
+result = addresses.validate_address(
+  city: { country: { code3: 'BGR' }, name: 'София', post_code: '1000' },
+  street: 'Витоша', num: '1'
+)
+result.validation_status
+result.address
+```
+
+### Labels and tracking
+
+```ruby
+labels = Econt::Services::Shipments::Label.new
+quote = labels.create_label(
+  mode: 'calculate',
+  label: {
+    sender_client: { name: 'Sender', phones: ['+359888000000'] },
+    sender_office_code: '1000',
+    receiver_client: { name: 'Receiver', phones: ['+359888000001'] },
+    receiver_office_code: '1000',
+    shipment_type: 'pack', pack_count: 1, weight: 1.2,
+    shipment_description: 'Artwork'
+  }
+)
+quote.label.total_price
+quote.label.currency
+
+shipments = Econt::Services::Shipments::Shipment.new
+statuses = shipments.get_shipment_statuses(shipment_numbers: ['1234567890123'])
+statuses.first.status
+```
+
+Label modes include `calculate`, `validate`, `create`, and single-label
+`calculate_with_block`. Creation and other mutations have real effects in the
+selected environment. Example office codes and payloads must be adapted to your
+account and shipment.
+
+See the [Ruby API reference](docs/API.md) for every service method, its parameters,
+return value, safety notes, and examples. The [endpoint matrix](docs/ENDPOINTS.md)
+maps these methods to carrier operations; see the
+[public API contract](docs/PUBLIC_API.md) for conversions and known limitations.
+
+## Error handling
+
+Transport and HTTP failures raise `Econt::Error`. Models and collections also
+expose `error?` and `error` for carrier errors returned in a response.
+
+Connection, timeout, and TLS failures use `Econt::ConnectionError`,
+`Econt::TimeoutError`, and `Econt::SSLError`, under `Econt::TransportError`.
+They have safe fixed messages; their original `cause` and `full_message` can
+contain private data. There are no automatic retries, especially for mutations.
+
+```ruby
+begin
+  result = labels.create_label(mode: 'validate', label: label_payload)
+  Rails.logger.warn(result.error.full_message) if result.error?
+rescue Econt::Error => error
+  Rails.logger.warn("Econt request failed (status=#{error.status.inspect})")
+  # Present an application-owned message; retry only when safe.
+end
+```
+
+Review carrier error contents before logging or displaying them to customers.
+
+## Versioning and support
+
+We follow [Semantic Versioning](https://semver.org/). Before 1.0, minor releases
+may change the public API incompatibly. From 1.0, incompatible changes to the
+documented API require a major release.
+
+There is no support SLA. Issues and PRs are reviewed best-effort, usually on
+weekends. Fixes with tests are welcome; the MIT license permits maintaining a
+fork. See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake
+```
+
+Offline tests cover request payloads and example-response mapping. See
+[response tests](docs/RESPONSE_TESTS.md) for their scope and limitations.
+Reviewed VCR recordings are replayed in CI with recording and network access
+disabled; missing recordings are not fetched automatically.
+
+To run the same credential-free replay locally:
+
+```bash
+ECONT_VCR_REPLAY=1 bundle exec rspec spec/recorded_contract_spec.rb
+```
+
+For deliberate demo recording, copy `.env.example` to `.env.test`, configure
+credentials, and run:
+
+```bash
+ECONT_LIVE_TESTS=1 bundle exec rspec spec/live
+```
+
+The create/delete/status lifecycle requires `ECONT_MUTATING_LIVE_TESTS=1` as
+well. Other unsafe mutations remain offline-tested. Review all recordings before
+committing; see [VCR policy and cleanup paths](docs/VCR.md) and
+[release instructions](docs/RELEASING.md).
+
+## License
+
+[MIT](LICENSE.txt).

data/SECURITY.md

@@ -0,0 +1,33 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Use GitHub's private vulnerability reporting for this repository when it is
+available. If it is not enabled, open a public issue containing only a request
+for a private contact channel—do not include exploit details, credentials,
+personal data, or carrier responses in that issue.
+
+Reports are reviewed on a best-effort basis, usually on weekends. This
+community project cannot promise a response or remediation deadline. Please do
+not publicly disclose an unresolved vulnerability before a private discussion
+has taken place.
+
+Only the latest released version receives security fixes. Pull requests are
+welcome after coordinated disclosure.
+
+## Econt transport limitation
+
+Econt documents its demo and production service URLs as HTTP endpoints using
+HTTP Basic authentication. Consequently, credentials and shipment data are not
+protected by TLS in transit. This gem preserves those documented URLs and does
+not claim to solve that carrier-side limitation.
+
+Run requests only from trusted server-side infrastructure and through a network
+path whose risks you accept. Never call Econt directly from browser code. Keep
+credentials out of source control, rotate them if exposed, and limit access to
+application logs and VCR cassettes.
+
+Debug mode filters the configured username, password, and Basic token. Request
+and response bodies are disabled by default because they may contain personal
+data. Enabling `debug_bodies` is an explicit decision to log that data and
+should be limited to short-lived local diagnosis.