nz_post_api 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0448e4e338c37344fa3fa6ab4d945d881da9dd3792cfe313f5606f557d8b2cb
-  data.tar.gz: b7185609015910d3c29d1035d49ab84de2232b9954843cf68984ab8cedb0e17d
+  metadata.gz: db4c2d341925855b00d54c677d88820dfcb183e16bf3a92e12c284bbdc665f80
+  data.tar.gz: 6ffccabb911d0b5683984b45c75b5aea2392771452794c0572a65bae0fea8350
 SHA512:
-  metadata.gz: 6ea8af8a2e7996843a7717d717a967906347b34f78b05ff7aa06f53f433f51ede93c4a26daab9c6a0d566e801c5c005608739951d626b567609998971e0df394
-  data.tar.gz: acfdac12a138c5961411c03673b28223f7516fd8603756bab64387d5673b189a8d9eb79cd36829b8e154dc4ee70e8c5e347cf6aecf55af64895676c65f21f85b
+  metadata.gz: 4d66466023a5ae7a3d341218fe006cf25d022747bfc7dbf08be4a2026629982507cba8837b884609c68f1b11a3ca270484c13b50f4e43fb02e72683420ada83b
+  data.tar.gz: 2dac646484e52891d15da15f731625fb28a8fc1a389f54b2f3b66302f5f9b4f111fc8a5727a6ae516c90d51dba0c659944d67c3804a79290c4a4cec4e884a5b2

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

@@ -37,6 +37,16 @@ Then, initialize the client with the access token.
 client = NzPostApi::Client.new(client_id: "YOUR_CLIENT_ID", access_token: access_token)
 ```
 
+### Configuration
+
+By default, the gem uses the UAT environment. To use the production environment, configure the gem as follows:
+
+```ruby
+NzPostApi.configure do |config|
+  config.prod = true # set to true for production, defaults to false (UAT)
+end
+```
+
 ### Parcel Address
 
 #### Search
@@ -168,7 +178,7 @@ file.unlink # deletes the temp file
 
 List available shipping options based on package details.
 
-```ruby
+````ruby
 shipping_client = client.shipping_options
 
 params = {
@@ -182,10 +192,56 @@ params = {
 
 response = shipping_client.list(params)
 response.services.each do |service|
+  puts service.service_code
   puts service.service_code
   puts service.description
 end
 
+### Parcel Track
+
+#### Track Parcel
+
+Retrieve tracking events for a parcel.
+
+```ruby
+track_client = client.parcel_track
+tracking = track_client.track("TRACKING_NUMBER")
+
+puts tracking.tracking_reference
+tracking.tracking_events.each do |event|
+  puts "#{event.event_datetime}: #{event.event_description}"
+end
+```
+
+#### Subscribe to Updates
+
+Subscribe to tracking updates for a parcel via webhook.
+
+```ruby
+track_client = client.parcel_track
+subscription = track_client.subscribe(
+  tracking_reference: "TRACKING_NUMBER",
+  notification_endpoint: "https://my.endpoint.com/nz_post_tracking"
+)
+
+puts subscription.subscription_guid
+```
+
+#### Unsubscribe
+
+Unsubscribe from tracking updates.
+
+```ruby
+track_client = client.parcel_track
+success = track_client.unsubscribe(subscription_guid: "SUBSCRIPTION_GUID")
+
+if success
+  puts "Unsubscribed successfully"
+else
+  puts "Failed to unsubscribe"
+end
+````
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -203,4 +259,7 @@ 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/client.rb

@@ -32,5 +32,9 @@ module NzPostApi
     def shipping_options
       Resources::ShippingOption.new(self)
     end
+
+    def parcel_track
+      Resources::ParcelTrack.new(self)
+    end
   end
 end

data/lib/nz_post_api/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module NzPostApi
+  class Configuration
+    attr_accessor :prod
+
+    def initialize
+      @prod = false
+    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/objects/parcel_track.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module NzPostApi
+  module Objects
+    class ParcelTrack < Base
+    end
+  end
+end

data/lib/nz_post_api/objects/parcel_track_subscription.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module NzPostApi
+  module Objects
+    class ParcelTrackSubscription < Base
+    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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module NzPostApi
+  module Resources
+    class ParcelTrack
+      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}")
+
+        if response.success?
+          Objects::ParcelTrack.new(response.body["results"])
+        else
+          raise NzPostApi::Error, "Failed to track parcel: #{response.status} - #{response.body}"
+        end
+      end
+
+      def subscribe(tracking_reference:, notification_endpoint:)
+        payload = {
+          tracking_reference: tracking_reference,
+          notification_endpoint: notification_endpoint
+        }
+        response = @client.connection.post("#{base_url.sub('parcels', 'subscription/webhook/')}", payload)
+
+        if response.success?
+          Objects::ParcelTrackSubscription.new(response.body)
+        else
+          raise NzPostApi::Error, "Failed to subscribe to parcel: #{response.status} - #{response.body}"
+        end
+      end
+
+      def unsubscribe(subscription_guid:)
+        response = @client.connection.delete("#{base_url.sub('parcels', 'subscription/webhook')}/#{subscription_guid}")
+
+        if response.success?
+          true
+        else
+          raise NzPostApi::Error, "Failed to unsubscribe from parcel: #{response.status} - #{response.body}"
+        end
+      end
+    end
+  end
+end

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.2.0"
+  VERSION = "0.4.0"
 end

data/lib/nz_post_api.rb

@@ -1,17 +1,30 @@
 # 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"
 require_relative "nz_post_api/objects/shipping_option"
+require_relative "nz_post_api/objects/parcel_track"
+require_relative "nz_post_api/objects/parcel_track_subscription"
 require_relative "nz_post_api/auth"
 require_relative "nz_post_api/client"
 require_relative "nz_post_api/resources/parcel_address"
 require_relative "nz_post_api/resources/parcel_label"
 require_relative "nz_post_api/resources/shipping_option"
+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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nz_post_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andy Chong
@@ -70,12 +70,16 @@ 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
+- lib/nz_post_api/objects/parcel_track.rb
+- lib/nz_post_api/objects/parcel_track_subscription.rb
 - lib/nz_post_api/objects/shipping_option.rb
 - lib/nz_post_api/resources/parcel_address.rb
 - lib/nz_post_api/resources/parcel_label.rb
+- lib/nz_post_api/resources/parcel_track.rb
 - lib/nz_post_api/resources/shipping_option.rb
 - lib/nz_post_api/version.rb
 - sig/nz_post_api.rbs