nz_post_api 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8ec46eab576b5d457acc5ba5476a9b31140871f1a67018946abe82e72e6bd6e
-  data.tar.gz: e21a327af35cebc7933043c19546a7496b7ff079f07166e24d790a0320d0112c
+  metadata.gz: 959f7bc78fae9b31231d76977d9cbba085cf400a0f2c474a836aef47c05560d1
+  data.tar.gz: 8d588514158a3f0dc4e2b2b2157228cf4af180bd1fe74a20e8d3165f9fd077db
 SHA512:
-  metadata.gz: 34298ff6a6da402e7eeb864b725d536ff1379db1105e7fc97d8a39e0de961775ff0fa6ab99202cee7a5fa834e5af57025987ccfcb712d05230937bfb7c50be5f
-  data.tar.gz: c28df5d11dee6594d65da67e00261b972c1bdf87d73d4ecae3d033f6791929fbc13db0d536eb42bf5c3c7683fba2c4fd34c4b97c1f707d8e8a3be43175f6911b
+  metadata.gz: 552186803f84a8dc134d297a5059d7ecbc1fd6d61ecc42cb823250c50765081efba4ddf1e6e9587a772de787e9378c37fa9b473d239c42ccb642099430e946c3
+  data.tar.gz: deadece3e518de6e102bafbba15f2c3a6ddf055a3a245365694a493160d4fde3ed9bce9d5ec332c8667fefce8e24b8e1827e84a8386681c123e31956b2e6af88

data/README.md

@@ -31,25 +31,35 @@ expires_in = token_response["expires_in"]
 > [!IMPORTANT]
 > The access token expires after a certain period (indicated by `expires_in`). It is highly recommended to cache the `access_token` and reuse it until it expires to avoid unnecessary API calls and potential rate limiting.
 
-Then, configure the gem and initialize the client.
+Then, initialize the client with your credentials:
 
 ```ruby
-NzPostApi.configure do |config|
-  config.client_id = "YOUR_CLIENT_ID"
-  config.access_token = access_token
-  config.prod = true # set to true for production, defaults to false (UAT)
-end
-
-client = NzPostApi::Client.new
+client = NzPostApi::Client.new(
+  "YOUR_CLIENT_ID",
+  access_token,
+  prod: true  # set to true for production, false for UAT (default)
+)
 ```
 
-### Configuration
+**Client constructor:**
 
-By default, the gem uses the UAT environment. Configuration options:
+- `client_id` – Your NZ Post API client ID (required)
+- `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`.
 
-- `client_id` – Your NZ Post API client ID (required for API calls)
-- `access_token` – Bearer token from `NzPostApi::Auth.fetch_token` (required for API calls)
-- `prod` – Set to `true` for production, `false` for UAT (default)
+### 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
 
@@ -267,7 +277,3 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the NzPostApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/nz_post_api/blob/main/CODE_OF_CONDUCT.md).
-
-```
-
-```

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/client.rb

@@ -4,23 +4,26 @@ require "faraday"
 
 module NzPostApi
   class Client
-    def initialize
+    def initialize(client_id, access_token, prod: false)
+      @client_id = client_id
+      @access_token = access_token
+      @prod = prod
     end
 
-    def client_id
-      NzPostApi.configuration.client_id
-    end
-
-    def access_token
-      NzPostApi.configuration.access_token
+    def base_url
+      if @prod
+        "https://api.nzpost.co.nz"
+      else
+        "https://api.uat.nzpost.co.nz"
+      end
     end
 
     def connection
       @connection ||= Faraday.new do |f|
         f.request :json
         f.response :json
-        f.headers["client_id"] = client_id
-        f.headers["Authorization"] = "Bearer #{access_token}"
+        f.headers["client_id"] = @client_id
+        f.headers["Authorization"] = "Bearer #{@access_token}"
         f.headers["Content-Type"] = "application/json"
       end
     end

data/lib/nz_post_api/resources/parcel_address.rb

@@ -4,7 +4,7 @@ module NzPostApi
   module Resources
     class ParcelAddress
       def base_url
-        "#{NzPostApi.configuration.base_url}/parceladdress/2.0/domestic/addresses"
+        "#{@client.base_url}/parceladdress/2.0/domestic/addresses"
       end
 
       def initialize(client)
@@ -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

@@ -4,7 +4,7 @@ module NzPostApi
   module Resources
     class ParcelLabel
       def base_url
-        "#{NzPostApi.configuration.base_url}/parcellabel/v3/labels"
+        "#{@client.base_url}/parcellabel/v3/labels"
       end
 
       def initialize(client)
@@ -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

@@ -4,7 +4,7 @@ module NzPostApi
   module Resources
     class ParcelTrack
       def base_url
-        "#{NzPostApi.configuration.base_url}/parceltrack/3.0/parcels"
+        "#{@client.base_url}/parceltrack/3.0/parcels"
       end
 
       def initialize(client)
@@ -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

@@ -4,7 +4,7 @@ module NzPostApi
   module Resources
     class ShippingOption
       def base_url
-        "#{NzPostApi.configuration.base_url}/shippingoptions/2.0/domestic"
+        "#{@client.base_url}/shippingoptions/2.0/domestic"
       end
 
       def initialize(client)
@@ -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.5.0"
+  VERSION = "0.7.0"
 end

data/lib/nz_post_api.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "nz_post_api/version"
-require_relative "nz_post_api/configuration"
 require_relative "nz_post_api/objects/base"
 require_relative "nz_post_api/objects/address"
 require_relative "nz_post_api/objects/label"
@@ -16,15 +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
 
-  class << self
-    def configuration
-      @configuration ||= Configuration.new
-    end
-
-    def configure
-      yield(configuration)
+    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.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Andy Chong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-03 00:00:00.000000000 Z
+date: 2026-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -70,7 +70,6 @@ files:
 - lib/nz_post_api.rb
 - lib/nz_post_api/auth.rb
 - lib/nz_post_api/client.rb
-- lib/nz_post_api/configuration.rb
 - lib/nz_post_api/objects/address.rb
 - lib/nz_post_api/objects/base.rb
 - lib/nz_post_api/objects/label.rb

data/lib/nz_post_api/configuration.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module NzPostApi
-  class Configuration
-    attr_accessor :prod, :client_id, :access_token
-
-    def initialize
-      @prod = false
-      @client_id = nil
-      @access_token = nil
-    end
-
-    def base_url
-      if @prod
-        "https://api.nzpost.co.nz"
-      else
-        "https://api.uat.nzpost.co.nz"
-      end
-    end
-  end
-end