pratka 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '04085d85f88834e2907d322efdcf9ab8ccf3588514a5d362c19223f4cd22a790'
+  data.tar.gz: ff5582b3d13b92cad8e7fc36de4abd1f44462c67a58ea62031b66628aafedc04
+SHA512:
+  metadata.gz: 47c29ce1d7858648f126d8f498c65232f7481e389049b469015dde5aa411a5cd83163dec1117426b97793cbb8fd5d7a146555e5617425c730e6ba52c30c05036
+  data.tar.gz: ee5af3f162ba6c5f5a6a893e096e4bfb41bef64a72f30f43ae305ffd152daa2f21a883317dff79b7b03186f117e2c49e728fae76a730fc5bcb745a83d20343ee

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-10-07
+
+Initial release, with Speedy as the first supported courier.
+
+### Added
+
+- `Pratka::Speedy.configure` for global settings: `base_url`, `language`, `country_id`, `read_timeout`, `open_timeout`
+- `Pratka::Speedy::Client` with username/password authentication
+- Location lookups: `fetch_offices`, `fetch_cities`, `fetch_countries`, `fetch_complexes`, `fetch_streets`
+- `calculate` returns price and delivery deadline for one or more services
+- `create_shipment`
+- `print_label` returns raw PDF or ZPL bytes
+- `fetch_payment_details` returns shipment payouts for a date range
+- `track` returns the operation history for up to 10 parcels
+- Error classes under `Pratka::Speedy`: `TimeoutError`, `ConnectionError`, `HTTPError` (with `status` and `body`), `APIError` (with `code`, `context`, `id`)
+- Validation of required params, which treats blank values as missing
+- Supports Ruby 3.3+ and JRuby
+
+[Unreleased]: https://github.com/tripplesteel/pratka/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tripplesteel/pratka/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Stilqn Bairski
+
+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,460 @@
+# Pratka
+
+Ruby client for Bulgarian courier APIs. Supported couriers:
+
+- [Econt](https://www.econt.com/developers/soap-json-api.html), [Econt API Models](https://ee.econt.com/services/Shipments/) (Work in progress)
+- [Speedy](https://api.speedy.bg/api/docs/)
+
+I built this because I mainly work on Ruby/JRuby on Rails e-shops that integrate with Speedy and Econt, and I kept copying the same API code from project to project. With Pratka, each project can call the courier APIs directly. I'm starting with the endpoints we use most. If you need one that isn't implemented yet, feel free to [open an issue](https://github.com/tripplesteel/pratka/issues).
+
+## Installation
+
+Requires Ruby 3.3 or newer
+
+```ruby
+gem "pratka"
+```
+
+or
+
+```bash
+bundle add pratka
+```
+
+## Speedy
+
+### Setup
+`Pratka::Speedy` works without any configuration. Add the gem, create a `Pratka::Speedy::Client` with your credentials, and you're ready. To override the defaults, set any of `base_url`, `language`, `country_id`, `read_timeout` and `open_timeout`:
+
+```ruby
+Pratka::Speedy.configure do |c|
+  c.base_url = ENV["SPEEDY_BASE_URL"] # Defaults to "https://api.speedy.bg/v1/"
+  c.language = ENV["SPEEDY_LANGUAGE"] # "BG" or "EN". Anything else falls back to "BG"
+  c.country_id = 100                  # Defaults to 100 (Bulgaria)
+  c.read_timeout = 60                 # Seconds. Defaults to 30. nil waits forever
+  c.open_timeout = 10                 # Seconds. Defaults to 10. nil waits forever
+end
+```
+
+### Client initialization
+
+```ruby
+client = Pratka::Speedy::Client.new(
+  username: ENV["SPEEDY_USERNAME"],
+  password: ENV["SPEEDY_PASSWORD"],
+  language: "EN", # Optional. Defaults to the configured language
+  country_id: 100 # Optional. Defaults to the configured country_id
+)
+```
+
+Credentials go on the client, not the global configuration, so you can run several Speedy accounts side by side
+
+### API methods
+
+#### Fetch Speedy offices
+
+It's scoped automatically to client's country
+
+```ruby
+client.fetch_offices
+```
+
+Allowed options:
+- `site_id` - Site ID. Limits the search scope in the set of offices for specified site. If omitted - all country offices are searched
+- `site_name` - Filters the results by office site name prefix or part of it
+- `name` - Search term for office name. Filters the results by office name prefix or part of site name
+- `limit` - The number of records to return in response. All records are returned if this parameter is omitted
+- `office_type` - array of ["OFFICE", "APT"]
+- `office_features` - array of ["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"]
+
+Returns the parsed JSON response. Values keep their JSON types, so IDs are `Integer`, coordinates are `Float` and flags are `true`/`false`
+
+Example response:
+
+```ruby
+{"offices" =>
+  [{"id" => 1,
+    "name" => "ПЛОВДИВ – СКЛАД ЮГ",
+    "nameEn" => "PLOVDIV - WAREHOUSE SOUTH",
+    "siteId" => 56784,
+    "address" =>
+     {"countryId" => 100,
+      "siteId" => 56784,
+      "siteType" => "гр.",
+      "siteName" => "Пловдив",
+      "postCode" => "4000",
+      "streetId" => 10621,
+      "streetType" => "ул.",
+      "streetName" => "Кукленско шосе",
+      "streetNo" => "15",
+      "x" => 24.761268,
+      "y" => 42.120139,
+      "fullAddressString" => "гр. Пловдив ул. Кукленско шосе No 15",
+      "siteAddressString" => "гр. Пловдив",
+      "localAddressString" => "ул. Кукленско шосе No 15"},
+    "workingTimeFrom" => "08:30",
+    "workingTimeTo" => "19:30",
+    "workingTimeHalfFrom" => "08:30",
+    "workingTimeHalfTo" => "14:30",
+    "workingTimeDayOffFrom" => "00:00",
+    "workingTimeDayOffTo" => "00:00",
+    "sameDayDepartureCutoff" => "19:30",
+    "sameDayDepartureCutoffHalf" => "14:30",
+    "sameDayDepartureCutoffDayOff" => "19:00",
+    "maxParcelDimensions" => {"width" => 240, "height" => 240, "depth" => 600},
+    "maxParcelWeight" => 1200.0,
+    "type" => "OFFICE",
+    "nearbyOfficeId" => 836,
+    "workingTimeSchedule" =>
+     [{"date" => "2026-10-06",
+       "workingTimeFrom" => "08:30",
+       "workingTimeTo" => "19:30",
+       "sameDayDepartureCutoff" => "19:30",
+       "standardSchedule" => true}],
+    "validFrom" => "2000-01-01",
+    "validTo" => "3000-01-01",
+    "cargoTypesAllowed" => ["PALLET", "PARCEL", "TYRE"],
+    "pickUpAllowed" => true,
+    "dropOffAllowed" => true,
+    "routingInformation" =>
+     {"tour" => {"number" => 10706, "officeId" => 1, "ramp" => "07", "cell" => "06"},
+      "officeId" => 1,
+      "hubId" => 1,
+      "priority" => 2},
+    "cardPaymentAllowed" => true,
+    "cashPaymentAllowed" => true,
+    "palletOffice" => true
+  }]
+}
+```
+
+#### Fetch Speedy cities
+```ruby
+client.fetch_cities
+```
+
+Returns the cities for the client's `country_id`, which defaults to the configured `country_id` (100, Bulgaria). Use a client with a different `country_id` to fetch another country's cities
+
+Speedy serves this endpoint as CSV, so every value is a `String` and empty fields are `nil`. Convert IDs before comparing them with JSON responses. For example, an office's `"siteId" => 56784` matches a city's `"id" => "56784"`
+
+Example response:
+
+```ruby
+[{"id" => "14",
+  "countryId" => "100",
+  "mainSiteId" => "0",
+  "type" => "с.",
+  "typeEn" => "s.",
+  "name" => "Абланица",
+  "nameEn" => "Ablanitsa",
+  "municipality" => "Хаджидимово",
+  "municipalityEn" => "Hadzhidimovo",
+  "region" => "Благоевград",
+  "regionEn" => "Blagoevgrad",
+  "postCode" => "2932",
+  "addressNomenclature" => "0",
+  "x" => "23.934398",
+  "y" => "41.536921",
+  "servingDays" => "1111100",
+  "servingOfficeId" => "130",
+  "servingHubOfficeId" => "13"
+}]
+```
+
+#### Fetch Speedy countries
+```ruby
+client.fetch_countries
+```
+
+Speedy serves this endpoint as CSV, so every value is a `String` and empty fields are `nil`. Booleans come back as `"true"` and `"false"`
+
+Example response:
+
+```ruby
+[{"id" => "36",
+  "name" => "Австралия",
+  "nameEn" => "Australia",
+  "isoAlpha2" => "AU",
+  "isoAlpha3" => "AUS",
+  "postCodeFormats" => "NNNN",
+  "requireState" => "false",
+  "addressType" => "2",
+  "currencyCode" => nil,
+  "defaultOfficeId" => "900",
+  "streetTypes" => nil,
+  "streetTypesEn" => nil,
+  "complexTypes" => nil,
+  "complexTypesEn" => nil,
+  "siteNomen" => "0"
+}]
+```
+
+#### Fetch complexes
+
+```ruby
+client.fetch_complexes(site_id: 881)
+```
+
+Allowed options:
+- `site_id` (Mandatory) - Site ID
+- `name` - Search term for complex name. Filters the results by complex name prefix or part of complex name
+
+Returns the parsed JSON response
+
+Example response:
+
+```ruby
+{"complexes" =>
+  [{"id" => 16182,
+    "siteId" => 881,
+    "actualId" => 0,
+    "type" => "",
+    "typeEn" => "",
+    "name" => "Магерови колиби",
+    "nameEn" => "Magerovi kolibi"}]}
+```
+
+#### Fetch streets
+```ruby
+client.fetch_streets(site_id: 36124)
+```
+
+Allowed options:
+- `site_id` (Mandatory) - Site ID
+- `name` - Filters the results by street name
+
+Returns the parsed JSON response
+
+Example response:
+
+```ruby
+{"streets" =>
+  [{"id" => 156597,
+    "actualId" => 0,
+    "siteId" => 36124,
+    "type" => "ул.",
+    "typeEn" => "ul.",
+    "name" => "Алеко Константинов",
+    "nameEn" => "Aleko Konstantinov"}
+  ]
+}
+```
+
+#### Print label
+
+```ruby
+client.print_label(paper_size: "A4", parcels: [{ parcel: { id: "123" } }])
+```
+
+Allowed options:
+- `paper_size` (Mandatory) - Paper size of the label
+- `parcels` (Mandatory) - Array of hashes. Example: [ { parcel: { id: "speedy_tracking_number" } } ]
+- `format` - Allowed values are `pdf` or `zpl`. Defaults to `pdf`
+- `printer_name` - Name of the printer
+- `dpi` - Allowed values are `dpi203` or `dpi300`. Defaults to `dpi203`
+- `sender_copy` - Allowed values are `NONE`, `ON_SAME_PAGE`, `ON_SINGLE_PAGE`. Defaults to `NONE`
+
+Returns raw PDF or ZPL bytes if the request is successful and the parcel exists
+
+If the parcels don't exist in Speedy, `print_label` raises `Pratka::Speedy::Error` with the message `Speedy returned an empty label; check the parcel IDs`
+
+If you send empty parcels, `print_label` raises `ArgumentError` with the message `Missing params: parcels`
+
+#### Fetch payment details
+
+```ruby
+client.fetch_payment_details(from_date: Time.new(2026, 10, 1), to_date: Time.now, include_details: true)
+```
+
+Allowed options:
+- `from_date` (Mandatory) - Start of the period
+- `to_date` (Mandatory) - End of the period
+- `include_details` - Include per-shipment payout details. Defaults to `false`
+
+Dates accept `Date`, `DateTime`, `Time` or a string. The client sends `Date`, `DateTime` and `Time` as `yyyy-MM-dd'T'HH:mm:ssZ`, for example `"2026-10-01T09:00:00+0300"`. A `Date` has no time or zone, so it becomes midnight UTC. Strings are sent as they are
+
+Returns the parsed JSON response. `details` is filled only when `include_details` is `true`
+
+Example response:
+
+```ruby
+{"payouts" =>
+  [{"date" => "2026-10-03",
+    "docId" => 123456789,
+    "docType" => "POSTAL_MONEY_TRANSFER", # or "CASH"
+    "paymentType" => "BANK",              # or "CASH"
+    "payee" => "Example Ltd",
+    "currency" => "BGN",
+    "amount" => 59.9,
+    "details" =>
+     [{"lineNo" => 1,
+       "shipmentId" => "61234567890",
+       "pickupDate" => "2026-09-30",
+       "primaryShipmentPickupDate" => nil,
+       "deliveryDate" => "2026-10-01",
+       "sender" => "Example Ltd",
+       "recipient" => "Ivan Ivanov",
+       "note" => "",
+       "ref1" => "ORDER-1001",
+       "ref2" => "",
+       "currency" => "BGN",
+       "order" => 1001,
+       "amount" => 59.9}]
+  }]
+}
+```
+
+#### Create shipment
+
+```ruby
+client.create_shipment(
+  recipient: {
+    phone1: { number: "0899445566" },
+    clientName: "Ivan Ivanov",
+    privatePerson: true,
+    pickupOfficeId: 77
+  },
+  service: { serviceId: 505, autoAdjustPickupDate: true },
+  content: { parcelsCount: 1, totalWeight: 0.6, contents: "Mobile phone", package: "BOX" },
+  payment: { courierServicePayer: "RECIPIENT" },
+  shipment_note: "Fragile"
+)
+```
+
+Allowed options:
+- `recipient` (Mandatory) - [ShipmentRecipient](https://api.speedy.bg/api/docs/#href-ds-shipment-recipient). The recipient and the delivery place
+- `service` (Mandatory) - [ShipmentService](https://api.speedy.bg/api/docs/#href-ds-shipment-service). The service level, pickup date and additional services
+- `content` (Mandatory) - [ShipmentContent](https://api.speedy.bg/api/docs/#href-ds-shipment-content). Parcel count, weight, size and contents
+- `payment` (Mandatory) - [ShipmentPayment](https://api.speedy.bg/api/docs/#href-ds-shipment-payment). Who pays for what
+- `sender` - [ShipmentSender](https://api.speedy.bg/api/docs/#href-ds-shipment-sender). The sender and the pickup place. If omitted, the logged-in user is the sender
+- `shipment_note` - Customer's note for the shipment
+
+Returns the parsed JSON response. Use the parcel `id` values with `print_label`. Speedy returns `price` only if your account can view shipment amounts, and `deliveryDeadline` only when it knows one
+Example response:
+
+```ruby
+{"id" => "299999990",
+ "parcels" => [{"seqNo" => 1, "id" => "299999990"}],
+ "pickupDate" => "2026-10-07",
+ "price" =>
+  {"amount" => 5.5,
+   "vat" => 1.1,
+   "total" => 6.6,
+   "currency" => "BGN"},
+ "deliveryDeadline" => "2026-10-08T19:00:00+03:00"
+}
+```
+
+#### Calculate
+
+```ruby
+client.calculate(
+  recipient: { privatePerson: true, pickupOfficeId: 77 },
+  service: { serviceIds: [505, 412], autoAdjustPickupDate: true },
+  content: { parcelsCount: 1, totalWeight: 0.6 },
+  payment: { courierServicePayer: "RECIPIENT" }
+)
+```
+
+Allowed options:
+- `recipient` (Mandatory) - [CalculationRecipient](https://api.speedy.bg/api/docs/#href-ds-calculation-recipient). The delivery place
+- `service` (Mandatory) - [CalculationService](https://api.speedy.bg/api/docs/#href-ds-calculation-service). The service IDs to price, the pickup date and additional services
+- `content` (Mandatory) - [CalculationContent](https://api.speedy.bg/api/docs/#href-ds-calculation-content). Parcel count and weight, or a list of parcels
+- `payment` (Mandatory) - [ShipmentPayment](https://api.speedy.bg/api/docs/#href-ds-shipment-payment). Who pays for what
+- `sender` - [CalculationSender](https://api.speedy.bg/api/docs/#href-ds-calculation-sender). The pickup place. If omitted, the logged-in user's location is used
+
+Returns the parsed JSON response with one calculation per service ID. Speedy returns `price` only if your account can view shipment amounts, and `deliveryDeadline` only when it knows one
+
+A service Speedy can't price for this destination comes back with its own `error` object instead of a price. `calculate` doesn't raise for it, so check each calculation
+
+Example response:
+
+```ruby
+{"calculations" =>
+  [{"serviceId" => 505,
+    "additionalServices" => {},
+    "price" =>
+     {"amount" => 5.5,
+      "vat" => 1.1,
+      "total" => 6.6,
+      "currency" => "BGN"},
+    "pickupDate" => "2026-10-07",
+    "deliveryDeadline" => "2026-10-08T19:00:00+03:00"},
+   {"serviceId" => 412,
+    "error" =>
+     {"context" => "service.serviceIds",
+      "message" => "Service is not allowed for this destination",
+      "id" => "EE-1234",
+      "code" => 1}}]
+}
+```
+
+#### Track
+
+```ruby
+client.track(parcels: [{ id: "299999990" }, { ref: "ORDER-1001" }], last_operation_only: true)
+```
+
+Allowed options:
+- `parcels` (Mandatory) - Array of [TrackShipmentParcelRef](https://api.speedy.bg/api/docs/#href-ds-track-shipment-parcel-ref), at most 10. Each parcel needs one of `id`, `ref`, `fullBarcode` or `externalCarrierParcelNumber`. `ref` matches the `ref1` and `ref2` fields of a parcel or shipment
+- `last_operation_only` - Return only the latest operation per parcel. Defaults to `false`
+
+Returns the parsed JSON response with one tracked parcel per matched parcel. A `ref` can match up to 10 parcels. Operation codes are listed in [Appendix 1](https://api.speedy.bg/api/docs/#href-appendix1-track-and-trace-codes) of the Speedy docs
+
+A parcel Speedy can't find comes back with its own `error` object instead of operations. `track` doesn't raise for it, so check each parcel
+
+Speedy asks clients to send at most 10 parcels per request and plans to enforce that limit. `track` enforces it already, so if you send more than 10 parcels it raises `ArgumentError` with the message `Speedy tracks at most 10 parcels per call`. Split larger lists into batches, for example with `each_slice(10)`
+
+Example response:
+
+```ruby
+{"parcels" =>
+  [{"parcelId" => "299999990",
+    "operations" =>
+     [{"dateTime" => "2026-10-08T11:42:10+0300",
+       "operationCode" => -14,
+       "description" => "Delivered",
+       "place" => "SOFIA",
+       "consignee" => "Ivan Ivanov"}]}]
+}
+```
+
+### Errors
+
+Every network and API failure raises a subclass of `Pratka::Speedy::Error`, which inherits from `Pratka::Error`
+
+| Error | Raised when | Extra attributes |
+| --- | --- | --- |
+| `Pratka::Speedy::TimeoutError` | The connection or read times out | |
+| `Pratka::Speedy::ConnectionError` | DNS, socket or SSL failure | |
+| `Pratka::Speedy::HTTPError` | Speedy returns a non-2xx status | `status`, `body` |
+| `Pratka::Speedy::APIError` | Speedy returns 2xx with an `error` object in the body | `code`, `context`, `id` |
+| `Pratka::Speedy::Error` | The response is malformed, has invalid JSON, or has an unexpected format | |
+
+Bad arguments raise `ArgumentError` before any request is sent, for example an unknown option or a missing `site_id`
+
+```ruby
+begin
+  client.fetch_streets(site_id: 36124, name: "Алеко")
+rescue Pratka::Speedy::APIError => e
+  logger.warn("Speedy rejected the request: #{e.message} (code #{e.code})")
+rescue Pratka::Speedy::TimeoutError, Pratka::Speedy::ConnectionError
+  retry_later
+rescue Pratka::Speedy::Error => e
+  logger.error("Speedy failed: #{e.message}")
+end
+```
+
+## Development
+
+```bash
+bin/setup          # install dependencies
+bundle exec rake   # run specs and RuboCop
+bin/console        # IRB session with the gem loaded
+```
+
+To release a new version, update `lib/pratka/version.rb` and `CHANGELOG.md`, then run `bundle exec rake release`. That task tags the commit, pushes the tag and publishes the gem to [rubygems.org](https://rubygems.org)
+
+## License
+
+[MIT](LICENSE.txt)

data/lib/pratka/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pratka
+  class Error < StandardError; end
+end

data/lib/pratka/speedy/client.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Pratka
+  module Speedy
+    # Authenticated client for the Speedy courier API
+    class Client
+      OFFICES_ENDPOINT = "location/office"
+      OFFICES_PARAMS = {
+        site_id: :siteId,
+        site_name: :siteName,
+        name: :name,
+        limit: :limit,
+        office_type: :officeType,
+        office_features: :officeFeatures
+      }.freeze
+
+      CITIES_ENDPOINT = "location/site/csv" # Speedy wants to add Country ID at the end of the endpoint. Example location/site/csv/100
+      COUNTRIES_ENDPOINT = "location/country/csv"
+
+      COMPLEX_ENDPOINT = "location/complex"
+      COMPLEX_PARAMS = { site_id: :siteId, name: :name }.freeze
+
+      STREET_ENDPOINT = "location/street"
+      STREET_PARAMS = { site_id: :siteId, name: :name }.freeze
+
+      PRINT_ENDPOINT = "print"
+      PRINT_PARAMS = {
+        format: :format,
+        paper_size: :paperSize,
+        printer_name: :printerName,
+        dpi: :dpi,
+        sender_copy: :additionalWaybillSenderCopy,
+        parcels: :parcels
+      }.freeze
+
+      PAYMENTS_ENDPOINT = "payments"
+      PAYMENTS_PARAMS = {
+        from_date: :fromDate,
+        to_date: :toDate,
+        include_details: :includeDetails
+      }.freeze
+
+      CREATE_SHIPMENT_ENDPOINT = "shipment"
+      SHIPMENT_PARAMS = {
+        sender: :sender,
+        recipient: :recipient,
+        service: :service,
+        content: :content,
+        payment: :payment,
+        shipment_note: :shipmentNote
+      }.freeze
+
+      CALCULATION_ENDPOINT = "calculate"
+      CALCULATION_PARAMS = {
+        sender: :sender,
+        recipient: :recipient,
+        service: :service,
+        content: :content,
+        payment: :payment
+      }.freeze
+
+      TRACK_ENDPOINT = "track"
+      TRACK_PARAMS = { parcels: :parcels, last_operation_only: :lastOperationOnly }.freeze
+
+      # Speedy recommends 10 parcels per request and plans to enforce it
+
+      TRACK_MAX_PARCELS = 10
+
+      def initialize(username:, password:, language: nil, country_id: Speedy.configuration.country_id)
+        @username = username
+        @password = password
+        @language = decide_language(language)
+        @country_id = country_id
+      end
+
+      # Fetch all offices from Speedy
+      # Allowed params:
+      # site_id - Site id. Limits the search scope in the set of offices for specified site. If omitted - all country offices are searched
+      # site_name - Filters the results by office site name prefix or part of it
+      # name - Search term for office name. Filters the results by office name prefix or part of site name
+      # limit - The number of records to return in response. All records are returned if this parameter is omitted
+      # office_type - array of ["OFFICE", "APT"]
+      # office_features - array of ["CARD_PAYMENT", "CASH_PAYMENT", "DROP_OFF", "PICK_UP", "CARGO_TYPE_PARCEL", "CARGO_TYPE_PALLET", "CARGO_TYPE_TYRE"][]
+      # Returns the parsed JSON response
+      def fetch_offices(**options)
+        call(OFFICES_ENDPOINT, map_params(options, OFFICES_PARAMS).merge(countryId: @country_id))
+      end
+
+      # Fetch all cities available in Speedy
+      # Returns the parsed array of hashes
+      def fetch_cities
+        fetch_csv("#{CITIES_ENDPOINT}/#{@country_id}")
+      end
+
+      # Fetch all countries available in Speedy
+      # Returns the parsed array of hashes
+      def fetch_countries
+        fetch_csv(COUNTRIES_ENDPOINT)
+      end
+
+      # List all complexes in Speedy
+      # Allowed params:
+      # site_id - (Mandatory)
+      # name - Search term for complex name. Filters the results by complex name prefix or part of complex name
+      def fetch_complexes(**options)
+        call(COMPLEX_ENDPOINT, map_params(options, COMPLEX_PARAMS, required: [:site_id]))
+      end
+
+      # List all streets in Speedy
+      # Allowed params:
+      # site_id - (Mandatory)
+      # name - Search term for street name. Filters the results by street name prefix or part of street name
+      def fetch_streets(**options)
+        call(STREET_ENDPOINT, map_params(options, STREET_PARAMS, required: [:site_id]))
+      end
+
+      # Print label for your parcels. Returns raw PDF or ZPL bytes
+      # Allowed params:
+      # paper_size - (Mandatory)
+      # parcels - (Mandatory) - Array of hashes. Example: [ { "parcel" => { id: 'speedy_tracking_number' } } ]
+      # format - Allowed values are `pdf` or `zpl`. Default one is `pdf`
+      # printer_name
+      # dpi - Allowed values are `dpi203` or `dpi300`. Default one is `dpi203`
+      # sender_copy - Allowed values are `NONE`, `ON_SAME_PAGE`, `ON_SINGLE_PAGE`. Default one is `NONE`
+      def print_label(**options)
+        label = call(PRINT_ENDPOINT, map_params(options, PRINT_PARAMS, required: %i[paper_size parcels]))
+        raise Error, "Speedy returned an empty label; check the parcel IDs" unless label.is_a?(String) && !label.empty?
+
+        # HTTP labels every body UTF-8; labels are binary
+
+        label.b
+      end
+
+      # Fetch shipment payouts for a period
+      # Allowed params:
+      # from_date - (Mandatory) Date, DateTime, Time or a "yyyy-MM-ddTHH:mm:ss+zzzz" string
+      # to_date - (Mandatory) Date, DateTime, Time or a "yyyy-MM-ddTHH:mm:ss+zzzz" string
+      # include_details - Include per-shipment payout details. Default one is false
+      def fetch_payment_details(**options)
+        params = map_params(options, PAYMENTS_PARAMS, required: %i[from_date to_date])
+        params[:fromDate] = format_datetime(params[:fromDate])
+        params[:toDate] = format_datetime(params[:toDate])
+
+        call(PAYMENTS_ENDPOINT, params)
+      end
+
+      # Create shipment
+      # [Create Shipment Request (CreateShipmentRequest)](https://api.speedy.bg/api/docs/#href-create-shipment-req)
+      # Allowed params:
+      # sender - ShipmentSender - Defines the sender of the shipment and shipment's pickup place. If not specified, the logged user is considered as a sender
+      # recipient (Mandatory) - ShipmentRecipient - Defines the recipient of the shipment and shipment’s delivery place
+      # service (Mandatory) - ShipmentService - Defines shipment service level agreement
+      # content (Mandatory) - ShipmentContent - Defines shipment’s content - number of parcels, weight, size, etc
+      # payment (Mandatory) - ShipmentPayment - Defines who-pays-what in shipment and other payment parameters
+      # shipment_note - String - Customer’s note associated with the shipment
+      def create_shipment(**options)
+        call(CREATE_SHIPMENT_ENDPOINT, map_params(options, SHIPMENT_PARAMS, required: %i[recipient service content payment]))
+      end
+
+      # Calculate shipment price and delivery deadline for one or more services
+      # [Calculation Request (CalculationRequest)](https://api.speedy.bg/api/docs/#href-calculation-req)
+      # Allowed params:
+      # sender - CalculationSender - Defines the pickup place. If not specified, the logged user's location is used
+      # recipient (Mandatory) - CalculationRecipient - Defines the delivery place
+      # service (Mandatory) - CalculationService - Defines the service ids to price and the pickup date
+      # content (Mandatory) - CalculationContent - Defines number of parcels, weight, etc
+      # payment (Mandatory) - ShipmentPayment - Defines who-pays-what in shipment
+      # Returns one calculation per service id. Each calculation carries its own error if Speedy can't price that service
+      def calculate(**options)
+        call(CALCULATION_ENDPOINT, map_params(options, CALCULATION_PARAMS, required: %i[recipient service content payment]))
+      end
+
+      # Track parcels and return their operation history
+      # [Track Request (TrackRequest)](https://api.speedy.bg/api/docs/#href-track-req)
+      # Allowed params:
+      # parcels (Mandatory) - TrackShipmentParcelRef[] - Up to 10 parcels. Each needs one of id, ref, fullBarcode or externalCarrierParcelNumber
+      # last_operation_only - Boolean - Return only the latest operation per parcel. Default one is false
+      # Returns one tracked parcel per matched parcel. A ref can match up to 10. Each tracked parcel carries its own error if Speedy can't track it
+      def track(**options)
+        params = map_params(options, TRACK_PARAMS, required: [:parcels])
+        raise ArgumentError, "Speedy tracks at most #{TRACK_MAX_PARCELS} parcels per call" if params[:parcels].size > TRACK_MAX_PARCELS
+
+        call(TRACK_ENDPOINT, params)
+      end
+
+      private
+
+      def call(endpoint, data = {})
+        http.call(endpoint, data)
+      end
+
+      def map_params(options, mapping, required: [])
+        unknown = options.keys - mapping.keys
+        raise ArgumentError, "Unknown params: #{unknown.join(", ")}" if unknown.any?
+
+        missing = required.select { |key| blank?(options[key]) }
+        raise ArgumentError, "Missing params: #{missing.join(", ")}" if missing.any?
+
+        options.transform_keys(mapping)
+      end
+
+      def blank?(value)
+        value = value.strip if value.respond_to?(:strip)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+
+      # Speedy wants yyyy-MM-dd'T'HH:mm:ssZ, where Z is an offset like +0300. A Date becomes midnight UTC
+      def format_datetime(value)
+        value.respond_to?(:strftime) ? value.strftime("%Y-%m-%dT%H:%M:%S%z") : value
+      end
+
+      def fetch_csv(endpoint)
+        result = call(endpoint)
+        raise Error, "Expected CSV from #{endpoint}, got #{result.class}" unless result.is_a?(String)
+
+        CSV.parse(result.delete_prefix("").strip, headers: true).map(&:to_h)
+      end
+
+      def http
+        @http ||= HTTP.new(@username, @password, @language)
+      end
+
+      def decide_language(language)
+        return language if ["BG", "EN"].include?(language)
+
+        Speedy.configuration.language
+      end
+    end
+  end
+end

data/lib/pratka/speedy/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pratka
+  module Speedy
+    class Configuration
+      attr_writer :base_url, :language, :country_id
+      attr_accessor :read_timeout, :open_timeout
+
+      DEFAULT_BASE_URL = "https://api.speedy.bg/v1/"
+      DEFAULT_LANGUAGE = "BG"
+      DEFAULT_COUNTRY_ID = 100
+      DEFAULT_READ_TIMEOUT = 30
+      DEFAULT_OPEN_TIMEOUT = 10
+
+      def initialize
+        @base_url = DEFAULT_BASE_URL
+        @language = DEFAULT_LANGUAGE
+        @country_id = DEFAULT_COUNTRY_ID
+        @read_timeout = DEFAULT_READ_TIMEOUT
+        @open_timeout = DEFAULT_OPEN_TIMEOUT
+      end
+
+      def base_url
+        Util::StringHelper.nil_or_value(@base_url) || DEFAULT_BASE_URL
+      end
+
+      def language
+        return @language if ["BG", "EN"].include?(@language)
+
+        DEFAULT_LANGUAGE
+      end
+
+      def country_id
+        Util::StringHelper.nil_or_value(@country_id) || DEFAULT_COUNTRY_ID
+      end
+    end
+  end
+end

data/lib/pratka/speedy/errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Pratka
+  module Speedy
+    class Error < Pratka::Error; end
+    class TimeoutError < Error; end
+    class ConnectionError < Error; end
+
+    class HTTPError < Error
+      attr_reader :status, :body
+
+      def initialize(status, body)
+        @status = status
+        @body = body
+        super(build_message)
+      end
+
+      private
+
+      # The body often holds the only explanation, e.g. a request parsing error on a 400
+      def build_message
+        detail = @body.to_s.gsub(/\s+/, " ").strip
+        return "Speedy returned HTTP #{@status}" if detail.empty?
+
+        detail = "#{detail[0, 200]}..." if detail.length > 200
+        "Speedy returned HTTP #{@status}: #{detail}"
+      end
+    end
+
+    class APIError < Error
+      attr_reader :code, :context, :id
+
+      def initialize(error)
+        error = { "message" => error.to_s } unless error.is_a?(Hash)
+
+        @code = error["code"]
+        @context = error["context"]
+        @id = error["id"]
+        super(error["message"] || "Speedy API error")
+      end
+    end
+  end
+end

data/lib/pratka/speedy/http.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+
+module Pratka
+  module Speedy
+    # Net::HTTP class to handle requests to the Speedy API
+    class HTTP
+      def initialize(username, password, language)
+        @username = username
+        @password = password
+        @language = language
+      end
+
+      # Each call opens a fresh connection and closes it when the block exits
+      def call(endpoint, data)
+        response = Net::HTTP.start(base_uri.host, base_uri.port, **connection_options) do |http|
+          http.request(build_request(endpoint, data))
+        end
+        body = (+response.body.to_s).force_encoding(Encoding::UTF_8)
+
+        raise HTTPError.new(response.code.to_i, body) unless response.is_a?(Net::HTTPSuccess)
+        return body unless json?(response)
+
+        parsed = JSON.parse(body)
+        raise APIError.new(parsed["error"]) if parsed.is_a?(Hash) && parsed["error"]
+
+        parsed
+      rescue Timeout::Error => e
+        raise TimeoutError, e.message
+      rescue SocketError, SystemCallError, OpenSSL::SSL::SSLError, EOFError => e
+        raise ConnectionError, e.message
+      rescue Net::HTTPBadResponse, Zlib::Error => e
+        raise Error, "Malformed response from Speedy: #{e.message}"
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON from Speedy: #{e.message}"
+      end
+
+      private
+
+      def json?(response)
+        response.content_type.to_s.include?("json")
+      end
+
+      # Speedy wants credentials in its data payload
+      def data_with_credentials(data)
+        { userName: @username, password: @password, language: @language }.merge(data)
+      end
+
+      def base_uri
+        @base_uri ||= URI(safe_base_url)
+      end
+
+      def safe_base_url
+        url = Speedy.configuration.base_url
+        url.end_with?("/") ? url : "#{url}/"
+      end
+
+      def connection_options
+        {
+          use_ssl: base_uri.scheme == "https",
+          read_timeout: Speedy.configuration.read_timeout,
+          open_timeout: Speedy.configuration.open_timeout
+        }
+      end
+
+      def build_request(endpoint, data)
+        req = Net::HTTP::Post.new(base_uri.path + endpoint, "Content-Type" => "application/json")
+        req.body = data_with_credentials(data).to_json
+
+        req
+      end
+    end
+  end
+end

data/lib/pratka/speedy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "speedy/errors"
+require_relative "speedy/configuration"
+require_relative "speedy/client"
+require_relative "speedy/http"
+
+module Pratka
+  module Speedy
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+    end
+  end
+end

data/lib/pratka/util/string_helper.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pratka
+  module Util
+    module StringHelper
+      class << self
+        def nil_or_value(value)
+          (value.nil? || value.to_s.strip.empty?) ? nil : value
+        end
+
+        def present?(value)
+          !(value.nil? || value.to_s.strip.empty?)
+        end
+      end
+    end
+  end
+end

data/lib/pratka/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pratka
+  VERSION = "0.1.0"
+end

data/lib/pratka.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "pratka/util/string_helper"
+require_relative "pratka/version"
+require_relative "pratka/error"
+require_relative "pratka/speedy"
+
+module Pratka
+end

data/sig/pratka.rbs

@@ -0,0 +1,4 @@
+module Pratka
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: pratka
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stilqn Bairski
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+description: One Ruby interface for shipping, tracking and office lookup across Bulgarian
+  couriers.
+email:
+- steelbairski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/pratka.rb
+- lib/pratka/error.rb
+- lib/pratka/speedy.rb
+- lib/pratka/speedy/client.rb
+- lib/pratka/speedy/configuration.rb
+- lib/pratka/speedy/errors.rb
+- lib/pratka/speedy/http.rb
+- lib/pratka/util/string_helper.rb
+- lib/pratka/version.rb
+- sig/pratka.rbs
+homepage: https://github.com/tripplesteel/pratka
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tripplesteel/pratka
+  changelog_uri: https://github.com/tripplesteel/pratka/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tripplesteel/pratka/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.22
+specification_version: 4
+summary: Ruby client for Bulgarian courier APIs (Speedy).
+test_files: []