speedy-bg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e50b937c817d5bb0981e3770b754f29284563afc4a1fb03a8075d58aa5b35457
+  data.tar.gz: 26124b19bcf347557b8984339f233888c3fc184d84cec9b76286c8cf16432abe
+SHA512:
+  metadata.gz: 0fcab4968a5a29fdd217aab2cd46ac35d005cab551425ba02919858b82220b9fe430e15383d81bca2a3378eb295ac68ea439c0e50fb679e5bd40ac35bffa76f6
+  data.tar.gz: 57c3db953357f44a177560ee3dba248f89422beb42df64e2866c606a7b0d03ead3976db547a843ae158f7d8aceda74b9c8eae543f438aeb388394ab70c855f87

data/CHANGELOG.md

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

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[the repository maintainer's private GitHub contact][maintainer]. Do not use a
+public issue for conduct reports.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+[maintainer]: https://github.com/BoyanGeorgiev96

data/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Thanks for helping improve `speedy-bg`. This is an independent community
+project and is not supported by Speedy AD.
+
+## Support scope
+
+Use GitHub issues for reproducible bugs, documentation corrections, and focused
+feature proposals. Include the gem version, Ruby version, endpoint name,
+expected behavior, actual behavior, and a minimal sanitized example. Never post
+credentials, unredacted request or response bodies, customer details, shipment
+numbers, or contract-specific data.
+
+Maintenance is best-effort and generally reviewed on weekends. There is no
+guaranteed response time, endpoint coverage, compatibility with undocumented
+carrier behavior, or commercial support. Pull requests for fixes are welcome.
+Users are also free to fork the MIT-licensed project and maintain behavior that
+is outside this project's scope.
+
+Security reports must follow [SECURITY.md](SECURITY.md), not the public issue
+tracker.
+
+## Development
+
+Use a currently supported Ruby version, then install dependencies and run:
+
+```bash
+bundle install
+bundle exec rake
+bundle exec rbs validate
+```
+
+Do not make live carrier requests in the normal test suite. Add deterministic
+Faraday test-adapter examples for request serialization, response casting, and
+errors. Contract recordings are opt-in, must use read-only operations unless a
+cleanup plan has been agreed, and must be reviewed for authentication and
+personal data before committing them.
+
+## Pull requests
+
+- Keep changes focused and explain the public API impact.
+- Add or update tests for behavior changes.
+- Update the README, RBS declarations, and schema notes when public behavior
+  changes.
+- Preserve Ruby 3.3, 3.4, and 4.0 compatibility.
+- Confirm `bundle exec rake`, `bundle exec rbs validate`, and the package smoke
+  test pass.
+
+By contributing, you agree that your contribution is licensed under the MIT
+License included in this repository.
+
+## Releasing
+
+The `Release to RubyGems` workflow is manual and its `publish` confirmation is
+disabled by default, so it never runs during ordinary CI. To release, select
+the existing `vVERSION` tag matching the gemspec when dispatching the workflow
+and enable the confirmation. Dispatching from a branch or a mismatched tag
+fails the version check. It uses RubyGems Trusted Publishing and does not read a
+long-lived API key from repository secrets.
+
+Before the first release, the owner must configure a pending trusted publisher
+for the `speedy-bg` gem on RubyGems.org. It must identify this repository,
+`.github/workflows/release.yml`, and the GitHub `release` environment. The
+repository variable `RUBYGEMS_TRUSTED_PUBLISHING_ENABLED` must then be set to
+`true`. Until both the publisher and this gate are configured, the release job
+is skipped safely. Normal CI also checks that any pushed `v*` tag exactly
+matches the gemspec version.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 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,150 @@
+# Speedy for Ruby
+
+A community Ruby client for the Speedy Bulgaria REST API. Not affiliated with,
+endorsed by, or maintained by Speedy AD. Supports Ruby 3.3, 3.4, and 4.0.
+
+## Installation
+
+```bash
+bundle add speedy-bg
+```
+
+The package is `speedy-bg`; the namespace is `Speedy`. Bundler loads it
+automatically, or use `require "speedy"` explicitly.
+
+## Configuration
+
+Configure once at application boot. The default URL is `https://api.speedy.bg/v1/`.
+
+```ruby
+Speedy::Client.configure do |config|
+  config.username = ENV.fetch("SPEEDY_USERNAME")
+  config.password = ENV.fetch("SPEEDY_PASSWORD")
+  config.language = "BG"
+  config.client_system_id = Integer(ENV["SPEEDY_CLIENT_SYSTEM_ID"], 10, exception: false)
+  config.open_timeout = 10
+  config.read_timeout = 30
+  config.write_timeout = 30
+end
+```
+
+For Rails, place configuration in `config/initializers/speedy.rb` and read
+credentials from Rails credentials instead:
+
+```ruby
+Speedy::Client.configure do |config|
+  config.username = Rails.application.credentials.dig(:speedy, :username)
+  config.password = Rails.application.credentials.dig(:speedy, :password)
+  config.client_system_id = Rails.application.credentials.dig(:speedy, :client_system_id)
+  config.language = I18n.default_locale.to_s.upcase
+end
+```
+
+`config.debug = true` logs headers and request/status lines, not bodies.
+`config.debug_bodies = true` opts into body logging. Configured credentials are
+always filtered, but bodies may expose customer data; protect those logs.
+
+## Usage
+
+Request arguments and response readers use `snake_case`; API `camelCase` and
+acronyms are converted automatically.
+
+```ruby
+client = Speedy::Client.instance
+site = client.find_sites(country_id: 100, name: "София").first
+offices = client.find_offices(site_id: site.id)
+
+calculations = client.calculate_delivery_fee(
+  recipient: { pickup_office_id: offices.first.id },
+  service: { service_ids: [505] },
+  content: { parcels_count: 1, total_weight: 0.1 },
+  payment: { courier_service_payer: "SENDER" }
+)
+price = calculations.first.price.total
+
+tracking = client.track_shipments(
+  parcels: [{ id: "700000001001" }], last_operation_only: true
+)
+latest_operation = tracking.first.operations.first
+```
+
+JSON endpoints return typed models or collections. Unknown response fields are
+retained in models and `to_h`; missing documented fields return `nil`.
+`print_labels_pdf` and `print_voucher` return raw PDF/ZPL bytes;
+`print_labels` returns a typed extended-label response.
+
+### Errors
+
+HTTP and transport failures raise `Speedy::Error` or a subclass.
+`Speedy::TransportError` covers `ConnectionError`, `TimeoutError`, and `SSLError`;
+its `status` is `nil` and its `cause` retains the original exception.
+Errors inside successful HTTP responses remain on models or collections:
+
+```ruby
+begin
+  result = client.calculate_delivery_fee(**attributes)
+  warn result.error.full_message if result.error?
+rescue Speedy::Error => error
+  warn "Speedy request failed: status=#{error.status.inspect}"
+end
+```
+
+Inspect individual results for per-item errors too. Do not log submitted
+shipment attributes or unsanitized API error messages containing customer data.
+Transport messages are safe summaries; the original `cause` and `full_message`
+may contain private data. Requests are not automatically retried, and a timeout
+does not prove that a mutation failed. See the [error reference](docs/API.md#errors).
+
+## API coverage
+
+See the [method reference and examples](docs/API.md) for every public endpoint
+method, its arguments, return type, and mutation warnings.
+
+Calculation, shipment management, printing, tracking, courier services, pickup,
+clients/contracts, payouts, location lookups and CSV exports, and validation are
+implemented. Some operations require account permissions. Tracking-file URLs
+are returned without downloading them.
+
+See [response contracts](docs/RESPONSE_CONTRACTS.md) for endpoint coverage and
+example-response tests, and [schema notes](docs/schema-notes.md) for unresolved
+response shapes and the address-search schemas with no documented HTTP route.
+
+## Development and contract tests
+
+```bash
+bundle install
+bundle exec rake
+bundle exec rbs -r date -I sig validate
+bundle exec rake yard # Generates browsable documentation in doc/index.html
+```
+
+Normal tests do not contact Speedy. CI also replays committed VCR recordings
+with recording and network access disabled, without loading `.env` files:
+
+```bash
+SPEEDY_VCR_REPLAY=1 bundle exec rspec spec/recorded_contract_spec.rb
+```
+
+For opt-in recording, copy
+`.env.example` to `.env`, set test-account credentials and applicable
+`SPEEDY_CONTRACT_*` values, then run:
+
+```bash
+SPEEDY_LIVE_TESTS=1 bundle exec rspec spec/live
+```
+
+Shipment mutations require `SPEEDY_MUTATING_LIVE_TESTS=1` as well and have explicit
+cleanup. Printing tests use existing printable identifiers; documents are
+replaced completely before recording. Review every cassette before committing.
+See [VCR policy](docs/VCR.md) for gates, redaction, and cleanup limits.
+
+## Versioning and support
+
+This gem follows [Semantic Versioning 2.0.0](https://semver.org/). Before 1.0,
+minor releases may break the public API. From 1.0, incompatible changes to
+documented methods, arguments, models, return types, or errors require a major release.
+
+Issues and focused fix PRs are welcome. Maintenance is best-effort, generally
+reviewed on weekends; no response time or ongoing support is guaranteed.
+See [contributing](CONTRIBUTING.md) and [security reporting](SECURITY.md).
+MIT licensed; you are free to fork and adapt the client.

data/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+## Supported versions
+
+Until a stable release exists, security fixes are made on the latest released
+version and the default branch only. After 1.0, the latest minor line will be
+the supported line unless a release announcement says otherwise.
+
+## Reporting a vulnerability
+
+Do not open a public issue for suspected vulnerabilities or exposed secrets.
+Use GitHub's private vulnerability reporting for this repository. If that
+facility is unavailable, contact the maintainer privately through the contact
+details on the repository owner's GitHub profile.
+
+Include a description, affected versions, reproduction steps, impact, and any
+suggested mitigation. Remove real credentials and customer or shipment data.
+Reports are handled on a best-effort basis; the project cannot promise a
+response or remediation deadline.
+
+## Integration responsibilities
+
+The gem sends carrier credentials and may process names, phone numbers,
+addresses, shipment contents, and financial information. Applications must
+protect credentials, restrict log access, choose appropriate retention, and
+comply with applicable privacy requirements. Debug response bodies are disabled
+by default. Enabling body logging is an explicit application decision and
+should not be used in production. Configured credentials remain filtered even
+when body logging is enabled.