nz_post_api 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79fc7d9823bc2ee076dd26982aad65e2ec9cd2354403ffd0afd6414f0a1b9f49
-  data.tar.gz: 22a970d9bba8db00bf083b2a586d024a1e8905c8430af12218bfce287926ebb1
+  metadata.gz: 959f7bc78fae9b31231d76977d9cbba085cf400a0f2c474a836aef47c05560d1
+  data.tar.gz: 8d588514158a3f0dc4e2b2b2157228cf4af180bd1fe74a20e8d3165f9fd077db
 SHA512:
-  metadata.gz: c6f21391ee069bcb2e08742f2b7c4e6aec58703063c5ed76c0e3bded858e6d4f6fa6180bafbaeb45178661997c826fcb8af40520532713f5e7d30c5e13acde78
-  data.tar.gz: f5c356b9498efcacfdc383b2f9333c936cfea3a1603cd724b3dccb812ae50c39176e18d847fc8e82f4c1b0b98e02590b1e68a8ba2fd434ddaa538b0c8ccd3cee
+  metadata.gz: 552186803f84a8dc134d297a5059d7ecbc1fd6d61ecc42cb823250c50765081efba4ddf1e6e9587a772de787e9378c37fa9b473d239c42ccb642099430e946c3
+  data.tar.gz: deadece3e518de6e102bafbba15f2c3a6ddf055a3a245365694a493160d4fde3ed9bce9d5ec332c8667fefce8e24b8e1827e84a8386681c123e31956b2e6af88

data/README.md

@@ -47,6 +47,20 @@ client = NzPostApi::Client.new(
 - `access_token` – Bearer token from `NzPostApi::Auth.fetch_token` (required)
 - `prod:` – Set to `true` for production (`https://api.nzpost.co.nz`), `false` for UAT (`https://api.uat.nzpost.co.nz`). Defaults to `false`.
 
+### Error Handling
+
+API request failures raise `NzPostApi::Error`. The error object exposes both HTTP status code and response body:
+
+```ruby
+begin
+  client.parcel_address.search(q: "Invalid")
+rescue NzPostApi::Error => error
+  puts error.message
+  puts error.response_http_code
+  puts error.response_body
+end
+```
+
 ### Parcel Address
 
 #### Search

data/lib/nz_post_api/auth.rb

@@ -20,7 +20,11 @@ module NzPostApi
       if response.success?
         JSON.parse(response.body)
       else
-        raise NzPostApi::Error, "Failed to fetch token: #{response.status} - #{response.body}"
+        raise NzPostApi::Error.new(
+          "Failed to fetch token: #{response.status} - #{response.body}",
+          response_http_code: response.status,
+          response_body: response.body
+        )
       end
     end
   end

data/lib/nz_post_api/resources/parcel_address.rb

@@ -17,7 +17,11 @@ module NzPostApi
         if response.success?
           response.body["addresses"].map { |addr| Objects::Address.new(addr) }
         else
-          raise NzPostApi::Error, "Failed to search addresses: #{response.status} - #{response.body}"
+          raise NzPostApi::Error.new(
+            "Failed to search addresses: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
         end
       end
     end

data/lib/nz_post_api/resources/parcel_label.rb

@@ -26,7 +26,11 @@ module NzPostApi
         if response.success?
           response.body
         else
-          raise NzPostApi::Error, "Failed to download label: #{response.status} - #{response.body}"
+          raise NzPostApi::Error.new(
+            "Failed to download label: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
         end
       end
 
@@ -36,7 +40,11 @@ module NzPostApi
         if response.success?
           Objects::Label.new(response.body)
         else
-          raise NzPostApi::Error, "Failed to create/get label: #{response.status} - #{response.body}"
+          raise NzPostApi::Error.new(
+            "Failed to create/get label: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
         end
       end
     end

data/lib/nz_post_api/resources/parcel_track.rb

@@ -17,7 +17,11 @@ module NzPostApi
         if response.success?
           Objects::ParcelTrack.new(response.body["results"])
         else
-          raise NzPostApi::Error, "Failed to track parcel: #{response.status} - #{response.body}"
+          raise NzPostApi::Error.new(
+            "Failed to track parcel: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
         end
       end
 
@@ -31,7 +35,11 @@ module NzPostApi
         if response.success?
           Objects::ParcelTrackSubscription.new(response.body)
         else
-          raise NzPostApi::Error, "Failed to subscribe to parcel: #{response.status} - #{response.body}"
+          raise NzPostApi::Error.new(
+            "Failed to subscribe to parcel: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
         end
       end
 
@@ -41,7 +49,11 @@ module NzPostApi
         if response.success?
           true
         else
-          raise NzPostApi::Error, "Failed to unsubscribe from parcel: #{response.status} - #{response.body}"
+          raise NzPostApi::Error.new(
+            "Failed to unsubscribe from parcel: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
         end
       end
     end

data/lib/nz_post_api/resources/shipping_option.rb

@@ -17,7 +17,11 @@ module NzPostApi
         if response.success?
           Objects::ShippingOption.new(response.body)
         else
-          raise NzPostApi::Error, "Failed to list options: #{response.status} - #{response.body}"
+          raise NzPostApi::Error.new(
+            "Failed to list options: #{response.status} - #{response.body}",
+            response_http_code: response.status,
+            response_body: response.body
+          )
         end
       end
     end

data/lib/nz_post_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NzPostApi
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/nz_post_api.rb

@@ -15,5 +15,13 @@ require_relative "nz_post_api/resources/shipping_option"
 require_relative "nz_post_api/resources/parcel_track"
 
 module NzPostApi
-  class Error < StandardError; end
+  class Error < StandardError
+    attr_reader :response_http_code, :response_body
+
+    def initialize(message = nil, response_http_code: nil, response_body: nil)
+      @response_http_code = response_http_code
+      @response_body = response_body
+      super(message)
+    end
+  end
 end

data/sig/nz_post_api.rbs

@@ -1,4 +1,9 @@
 module NzPostApi
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  class Error < ::StandardError
+    attr_reader response_http_code: Integer?
+    attr_reader response_body: untyped
+
+    def initialize: (?String message, ?response_http_code: Integer, ?response_body: untyped) -> void
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nz_post_api
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Andy Chong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-05 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday