tcat 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f40a1e40fc125273e5928860f2afa18f22ad88a22a2b02d63f441b9197b0153d
-  data.tar.gz: 6e9d0c2f7bf65f9cc81a9764761092b76dce77faedc57836f3d9f4866b327b00
+  metadata.gz: 5ed5fe975474cdb30f8d660719b0a59d0ea5f1813b4e86433c95cd2ee82c795e
+  data.tar.gz: 025bf6aa6cfc46a4437d72e1d8abc966853606c1ba58b56ea5f6334a541b063e
 SHA512:
-  metadata.gz: c402bffc3cc32eb481d930958107d08e278b362390cc4d6f62bbe9b8357ebc5501e74dfce68ca1326040a32ef9bc51274b8853c9b57e6cd7b0b98ca19c52cbf4
-  data.tar.gz: 83fb6ec4ec1e9731fbd7d8fc0288221676afd14904101c3063304ae687cb54cc83112a9baf28eb616251d3618452976e0e7bc6ba284ef49d3a49d20b19a4b6e9
+  metadata.gz: b59a640cf706df074a2daa9bac89dfed2d96b1cfa1720278afe00b66ca8991cf64c096e4fca3701b05e7f43009b71f5f2e57186c902b339000d76db6098f4b13
+  data.tar.gz: 4d678f18e49855e6faf85ac8f4b0969f7c3c6d7d8a176686cd31ecc875e871a36ac3452a19dc9e5c7cd02ef559fdccf4e727085984c52d0066456f1b8b27302c

data/README.md

@@ -64,11 +64,16 @@ Tcat.configure do |config|
   config.secret_key = 'your_secret_key'
 end
 
-# Create a query instance
-query = Tcat::Query.new('your_tracking_number')
+# Two equivalent shapes — pick whichever fits your code:
 
-# Get shipment status
+# A) tracking number bound at construction (one-shot)
+query = Tcat::Query.new('your_tracking_number')
 status = query.status_code
+
+# B) tracking number per call (reuse one client for many lookups,
+#    matches Tcat::WorkerClient's shape)
+query = Tcat::Query.new
+status = query.status_code('your_tracking_number')
 # Returns one of the following:
 # :done           - Successfully delivered
 # :delivering     - Out for delivery
@@ -265,6 +270,12 @@ This gem is available as open source under the terms of the [MIT License](https:
 
 ## Changelog
 
+### 0.4.0
+
+- `Tcat::Query#status_code`, `#history`, `#latest_status` now accept an optional tracking-number argument, mirroring `Tcat::WorkerClient`'s shape
+- `Tcat::Query.new` may be called without a tracking number for stateless reuse: `Tcat::Query.new.status_code('1234567890')`
+- Existing one-shot construction (`Tcat::Query.new(tn).status_code`) is still supported
+
 ### 0.3.5
 
 - Added optional `worker_url` and `worker_token` to `Tcat.configure`; explicit `Tcat::WorkerClient.new(url, token:)` arguments still take precedence

data/lib/tcat/query.rb

@@ -11,7 +11,11 @@ module Tcat
   class Query
     DeliveryItem = Struct.new(:status, :status_code, :time, :office, :last_update, keyword_init: true)
 
-    def initialize(tracking_number)
+    # @param tracking_number [String, nil] Default tracking number used when
+    #   the per-call methods are invoked without an explicit argument. Pass nil
+    #   to construct a stateless client and supply the tracking number on each
+    #   call (matching Tcat::WorkerClient's shape).
+    def initialize(tracking_number = nil)
       @secret_string = Tcat.configuration.secret_string
       @secret_key = Tcat.configuration.secret_key
       validate_secrets!
@@ -25,22 +29,27 @@ module Tcat
     end
 
     # Get current delivery status code
+    # @param tracking_number [String, nil] Overrides the constructor value.
     # @return [Symbol] Status code (:done, :delivering, :collected, :in_transit, :unknown)
-    def status_code
-      response_body = @http_client.post(data)
+    def status_code(tracking_number = nil)
+      tn = resolve_tracking_number(tracking_number)
+      response_body = @http_client.post(data(tn))
       parse_status_code(response_body) if response_body
-    rescue HttpClient::RequestError => e
+    rescue HttpClient::RequestError
       # Log error or handle it appropriately
       nil
     end
 
     # Get complete delivery history
+    # @param tracking_number [String, nil] Overrides the constructor value.
     # @return [Array<DeliveryItem>] Array of delivery status items, sorted by time (newest first)
-    def history
-      response_body = @http_client.post(data)
+    def history(tracking_number = nil)
+      tn = resolve_tracking_number(tracking_number)
+      response_body = @http_client.post(data(tn))
       if response_body
         result = Ox.load(response_body, mode: :hash, with_cdata: true)
         return [] if result.dig(:Result, :Status) != '0'
+
         extract_delivery_history(result)
       end
     rescue StandardError => e
@@ -49,10 +58,12 @@ module Tcat
     end
 
     # Get latest delivery status with details
+    # @param tracking_number [String, nil] Overrides the constructor value.
     # @return [DeliveryItem, nil] Latest delivery status or nil if no history
-    def latest_status
-      items = history
+    def latest_status(tracking_number = nil)
+      items = history(tracking_number)
       return nil if items.empty?
+
       items.first
     end
 
@@ -75,9 +86,16 @@ module Tcat
       warn e.backtrace.first(5).join("\n") if $DEBUG
     end
 
-    def data
+    def resolve_tracking_number(arg)
+      tn = arg || @tracking_number
+      raise ArgumentError, 'tracking number required' if tn.nil? || tn.to_s.empty?
+
+      tn
+    end
+
+    def data(tracking_number)
       {
-        ConsignmentNo: @tracking_number,
+        ConsignmentNo: tracking_number,
         f: 5,
         isForeign: 'N',
         secret: generate_secret,

data/lib/tcat/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tcat
-  VERSION = '0.3.5'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tcat
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.0
 platform: ruby
 authors:
 - Zac