nz_post_api 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd7725f76d54c6a212beecd45f4ffc568ae7b0ab010d69ecf0f92d3dcbe57149
-  data.tar.gz: 7298abe8f2dae29e17f9525839b405e5c88a6be22f9072021002cdc1e3a8c957
+  metadata.gz: e8ec46eab576b5d457acc5ba5476a9b31140871f1a67018946abe82e72e6bd6e
+  data.tar.gz: e21a327af35cebc7933043c19546a7496b7ff079f07166e24d790a0320d0112c
 SHA512:
-  metadata.gz: 233660b133767bfc37a494719f344be5882d5d1093cbd92fc51b835e25481e0ba2d31ac4f5f4991622a9d3f3cae389350580e635bb99e35f55fdd4bce2efad9e
-  data.tar.gz: '08319bcd20474c2bccbc4f69b14bb57ccbe648e9ef95c186b3bc719067259baa4e8e7bd8840acfdd62d79d7564d0283e986be1cafe1cb87eb3f3775892a85070'
+  metadata.gz: 34298ff6a6da402e7eeb864b725d536ff1379db1105e7fc97d8a39e0de961775ff0fa6ab99202cee7a5fa834e5af57025987ccfcb712d05230937bfb7c50be5f
+  data.tar.gz: c28df5d11dee6594d65da67e00261b972c1bdf87d73d4ecae3d033f6791929fbc13db0d536eb42bf5c3c7683fba2c4fd34c4b97c1f707d8e8a3be43175f6911b

data/AGENTS.md

@@ -15,6 +15,7 @@ This project is a Ruby gem wrapper for the NZ Post API.
 2.  Implement the test case.
 3.  Implement the code to pass the test.
 4.  Refactor.
+5.  **Documentation**: Update README.md if there are any changes to the public API or configuration.
 
 ## API Documentation
 

data/README.md

@@ -31,12 +31,26 @@ 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, initialize the client with the access token.
+Then, configure the gem and initialize the client.
 
 ```ruby
-client = NzPostApi::Client.new(client_id: "YOUR_CLIENT_ID", access_token: access_token)
+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
 ```
 
+### Configuration
+
+By default, the gem uses the UAT environment. Configuration options:
+
+- `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)
+
 ### Parcel Address
 
 #### Search
@@ -59,6 +73,10 @@ end
 
 Create a new parcel label.
 
+- **NZ Post rates**: To use your own NZ Post rates, include `account_number` and `site_code` in the payload.
+- **Notification endpoint**: The `notification_endpoint` is a webhook URL. NZ Post will send HTTP requests to this endpoint when the parcel label status is updated.
+- **Service codes** (in `parcel_details`): `CPOLP` is Overnight Returns (supports pickup); `EROLE` is Economy Returns (only drop off, the pickup address street must have the prefix "PO Box" or "Private Bag" followed by digits).
+
 ```ruby
 label_client = client.parcel_label
 

data/lib/nz_post_api/auth.rb

@@ -2,17 +2,20 @@
 
 require "faraday"
 require "json"
+require "uri"
 
 module NzPostApi
   class Auth
     TOKEN_URL = "https://oauth.nzpost.co.nz/as/token.oauth2"
 
     def self.fetch_token(client_id, client_secret)
-      response = Faraday.post(TOKEN_URL, {
+      params = {
         client_id: client_id,
         client_secret: client_secret,
         grant_type: "client_credentials"
-      })
+      }
+      url_with_params = "#{TOKEN_URL}?#{URI.encode_www_form(params)}"
+      response = Faraday.post(url_with_params, nil)
 
       if response.success?
         JSON.parse(response.body)

data/lib/nz_post_api/client.rb

@@ -4,11 +4,15 @@ require "faraday"
 
 module NzPostApi
   class Client
-    attr_reader :client_id, :access_token
+    def initialize
+    end
+
+    def client_id
+      NzPostApi.configuration.client_id
+    end
 
-    def initialize(client_id:, access_token:)
-      @client_id = client_id
-      @access_token = access_token
+    def access_token
+      NzPostApi.configuration.access_token
     end
 
     def connection

data/lib/nz_post_api/configuration.rb

@@ -0,0 +1,21 @@
+# 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

data/lib/nz_post_api/resources/parcel_address.rb

@@ -3,14 +3,16 @@
 module NzPostApi
   module Resources
     class ParcelAddress
-      BASE_URL = "https://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/addresses"
+      def base_url
+        "#{NzPostApi.configuration.base_url}/parceladdress/2.0/domestic/addresses"
+      end
 
       def initialize(client)
         @client = client
       end
 
       def search(q:, count: 10)
-        response = @client.connection.get(BASE_URL, { q: q, count: count })
+        response = @client.connection.get(base_url, { q: q, count: count })
 
         if response.success?
           response.body["addresses"].map { |addr| Objects::Address.new(addr) }

data/lib/nz_post_api/resources/parcel_label.rb

@@ -3,24 +3,26 @@
 module NzPostApi
   module Resources
     class ParcelLabel
-      BASE_URL = "https://api.uat.nzpost.co.nz/parcellabel/v3/labels"
+      def base_url
+        "#{NzPostApi.configuration.base_url}/parcellabel/v3/labels"
+      end
 
       def initialize(client)
         @client = client
       end
 
       def create(payload)
-        response = @client.connection.post(BASE_URL, payload)
+        response = @client.connection.post(base_url, payload)
         handle_response(response)
       end
 
       def status(consignment_id)
-        response = @client.connection.get("#{BASE_URL}/#{consignment_id}/status")
+        response = @client.connection.get("#{base_url}/#{consignment_id}/status")
         handle_response(response)
       end
 
       def download(consignment_id, format: "PDF")
-        response = @client.connection.get("#{BASE_URL}/#{consignment_id}", { format: format })
+        response = @client.connection.get("#{base_url}/#{consignment_id}", { format: format })
         if response.success?
           response.body
         else

data/lib/nz_post_api/resources/parcel_track.rb

@@ -3,14 +3,16 @@
 module NzPostApi
   module Resources
     class ParcelTrack
-      BASE_URL = "https://api.uat.nzpost.co.nz/parceltrack/3.0/parcels"
+      def base_url
+        "#{NzPostApi.configuration.base_url}/parceltrack/3.0/parcels"
+      end
 
       def initialize(client)
         @client = client
       end
 
       def track(tracking_reference)
-        response = @client.connection.get("#{BASE_URL}/#{tracking_reference}")
+        response = @client.connection.get("#{base_url}/#{tracking_reference}")
 
         if response.success?
           Objects::ParcelTrack.new(response.body["results"])
@@ -24,7 +26,7 @@ module NzPostApi
           tracking_reference: tracking_reference,
           notification_endpoint: notification_endpoint
         }
-        response = @client.connection.post("#{BASE_URL.sub('parcels', 'subscription/webhook/')}", payload)
+        response = @client.connection.post("#{base_url.sub('parcels', 'subscription/webhook/')}", payload)
 
         if response.success?
           Objects::ParcelTrackSubscription.new(response.body)
@@ -34,7 +36,7 @@ module NzPostApi
       end
 
       def unsubscribe(subscription_guid:)
-        response = @client.connection.delete("#{BASE_URL.sub('parcels', 'subscription/webhook')}/#{subscription_guid}")
+        response = @client.connection.delete("#{base_url.sub('parcels', 'subscription/webhook')}/#{subscription_guid}")
 
         if response.success?
           true

data/lib/nz_post_api/resources/shipping_option.rb

@@ -3,14 +3,16 @@
 module NzPostApi
   module Resources
     class ShippingOption
-      BASE_URL = "https://api.uat.nzpost.co.nz/shippingoptions/2.0/domestic"
+      def base_url
+        "#{NzPostApi.configuration.base_url}/shippingoptions/2.0/domestic"
+      end
 
       def initialize(client)
         @client = client
       end
 
       def list(params = {})
-        response = @client.connection.get(BASE_URL, params)
+        response = @client.connection.get(base_url, params)
 
         if response.success?
           Objects::ShippingOption.new(response.body)

data/lib/nz_post_api/version.rb

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

data/lib/nz_post_api.rb

@@ -1,6 +1,7 @@
 # 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,5 +17,14 @@ require_relative "nz_post_api/resources/parcel_track"
 
 module NzPostApi
   class Error < StandardError; end
-  # Your code goes here...
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nz_post_api
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andy Chong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-02 00:00:00.000000000 Z
+date: 2026-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -70,6 +70,7 @@ 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