pratka 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04085d85f88834e2907d322efdcf9ab8ccf3588514a5d362c19223f4cd22a790'
-  data.tar.gz: ff5582b3d13b92cad8e7fc36de4abd1f44462c67a58ea62031b66628aafedc04
+  metadata.gz: 7940c2073d0fbeec909b2f5f545729474e26f1113c4d9dd154046ae7f8e7780f
+  data.tar.gz: 58293d9ab43d5addb4e84208bff655d76db9fd84c14a74acb43d50cd3376c6ba
 SHA512:
-  metadata.gz: 47c29ce1d7858648f126d8f498c65232f7481e389049b469015dde5aa411a5cd83163dec1117426b97793cbb8fd5d7a146555e5617425c730e6ba52c30c05036
-  data.tar.gz: ee5af3f162ba6c5f5a6a893e096e4bfb41bef64a72f30f43ae305ffd152daa2f21a883317dff79b7b03186f117e2c49e728fae76a730fc5bcb745a83d20343ee
+  metadata.gz: fe7b5484ea064bc9ff8dc3e42b31fe24c6bfcab9231c7f6e35140beba7b7dd2a2c43c85f4087e52af6684167aa80c093ab0f6386f3b167293523ad1b079b1e02
+  data.tar.gz: 7e1b7237afd97ef8d001e861953b55b7e6bb6c55888f22f4a285c5db531475b9d3f9103e806c83cb39950e8d9e89ed31da15fcb46fc2d10a532662b0128a4cea

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-12
+
+### Changed
+
+- Invalid params raise `Pratka::Speedy::InvalidParamsError` instead of `ArgumentError`, so `rescue Pratka::Error` covers every failure
+
+## [0.1.1] - 2026-10-08
+
+### Added
+
+- `fetch_shipment_info` returns full details of existing shipments
+
+[0.1.1]: https://github.com/tripplesteel/pratka/releases/tag/v0.1.1
+
 ## [0.1.0] - 2026-10-07
 
 Initial release, with Speedy as the first supported courier.
@@ -18,5 +32,4 @@ Initial release, with Speedy as the first supported courier.
 - 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/README.md

@@ -258,7 +258,7 @@ 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`
+If you send empty parcels, `print_label` raises `Pratka::Speedy::InvalidParamsError` with the message `Missing params: parcels`
 
 #### Fetch payment details
 
@@ -345,6 +345,30 @@ Example response:
 }
 ```
 
+#### Fetch shipment info
+
+```ruby
+client.fetch_shipment_info(shipment_ids: ["299999990", "299999991"])
+```
+
+Allowed options:
+- `shipment_ids` (Mandatory) - Array of shipment ids
+
+Returns the parsed JSON response with one [Shipment](https://api.speedy.bg/api/docs/#href-ds-shipment) per id. Each shipment has its sender, recipient, service, content, payment, price and delivery details, plus `ref1`, `ref2`, `returnShipmentId` and `redirectShipmentId` when set
+
+Example response:
+
+```ruby
+{"shipments" =>
+  [{"id" => "299999990",
+    "ref1" => "ORDER-1001",
+    "service" => {"serviceId" => 505, "pickupDate" => "2026-10-08"},
+    "content" => {"parcelsCount" => 1, "totalWeight" => 1.5, "contents" => "Books"},
+    "price" => {"amount" => 6.2, "vat" => 1.24, "total" => 7.44, "currency" => "BGN"},
+    "delivery" => {"deliveryDeadline" => "2026-10-09T19:00:00+0300"}}]
+}
+```
+
 #### Calculate
 
 ```ruby
@@ -403,7 +427,7 @@ Returns the parsed JSON response with one tracked parcel per matched parcel. A `
 
 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)`
+Speedy enforces 10 parcels limit per request. If you send more than 10 parcels it raises `Pratka::Speedy::InvalidParamsError` with the message `Speedy tracks at most 10 parcels per call`. Split larger lists into batches, for example with `each_slice(10)`
 
 Example response:
 
@@ -421,18 +445,17 @@ Example response:
 
 ### Errors
 
-Every network and API failure raises a subclass of `Pratka::Speedy::Error`, which inherits from `Pratka::Error`
+Every failure raises a subclass of `Pratka::Speedy::Error`, which inherits from `Pratka::Error`, so `rescue Pratka::Error` covers them all
 
 | Error | Raised when | Extra attributes |
 | --- | --- | --- |
+| `Pratka::Speedy::InvalidParamsError` | A param is unknown, missing or over a limit. Raised before any request is sent | |
 | `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: "Алеко")

data/lib/pratka/speedy/client.rb

@@ -61,11 +61,13 @@ module Pratka
         payment: :payment
       }.freeze
 
+      SHIPMENT_INFO_ENDPOINT = "shipment/info"
+      SHIPMENT_INFO_PARAMS = { shipment_ids: :shipmentIds }.freeze
+
       TRACK_ENDPOINT = "track"
       TRACK_PARAMS = { parcels: :parcels, last_operation_only: :lastOperationOnly }.freeze
 
-      # Speedy recommends 10 parcels per request and plans to enforce it
-
+      # Speedy allows up to 10 parcels per request
       TRACK_MAX_PARCELS = 10
 
       def initialize(username:, password:, language: nil, country_id: Speedy.configuration.country_id)
@@ -159,6 +161,15 @@ module Pratka
         call(CREATE_SHIPMENT_ENDPOINT, map_params(options, SHIPMENT_PARAMS, required: %i[recipient service content payment]))
       end
 
+      # Fetch full details of existing shipments
+      # [Shipment Information Request (ShipmentInformationRequest)](https://api.speedy.bg/api/docs/#href-shipment-info-req)
+      # Allowed params:
+      # shipment_ids (Mandatory) - String[] - Shipment ids
+      # Returns one Shipment per id with its sender, recipient, service, content, payment, price and delivery
+      def fetch_shipment_info(**options)
+        call(SHIPMENT_INFO_ENDPOINT, map_params(options, SHIPMENT_INFO_PARAMS, required: [:shipment_ids]))
+      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:
@@ -180,7 +191,7 @@ module Pratka
       # 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
+        raise InvalidParamsError, "Speedy tracks at most #{TRACK_MAX_PARCELS} parcels per call" if params[:parcels].size > TRACK_MAX_PARCELS
 
         call(TRACK_ENDPOINT, params)
       end
@@ -193,10 +204,10 @@ module Pratka
 
       def map_params(options, mapping, required: [])
         unknown = options.keys - mapping.keys
-        raise ArgumentError, "Unknown params: #{unknown.join(", ")}" if unknown.any?
+        raise InvalidParamsError, "Unknown params: #{unknown.join(", ")}" if unknown.any?
 
         missing = required.select { |key| blank?(options[key]) }
-        raise ArgumentError, "Missing params: #{missing.join(", ")}" if missing.any?
+        raise InvalidParamsError, "Missing params: #{missing.join(", ")}" if missing.any?
 
         options.transform_keys(mapping)
       end

data/lib/pratka/speedy/errors.rb

@@ -7,6 +7,7 @@ module Pratka
     class Error < Pratka::Error; end
     class TimeoutError < Error; end
     class ConnectionError < Error; end
+    class InvalidParamsError < Error; end
 
     class HTTPError < Error
       attr_reader :status, :body

data/lib/pratka/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pratka
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Stilqn Bairski