tcat 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac88c04a17a00b5b457a86bcf3bad081ac0fb48886351c1033fd1b89e2ebe399
-  data.tar.gz: 4adfbb15946f3f42b2b655911f2501824e401aa08d22635aafb01cb73f9adb85
+  metadata.gz: 30282cc204d33385f1c2ad59b0c48a46e1365b6094bc2d0673b1f75b95f4ee40
+  data.tar.gz: 02b5cc602a18a28411a89c330d99af2a62fc61cdb0b21db6c29c5ce9c6fafd58
 SHA512:
-  metadata.gz: 34d8e04435756d743116aa0da37132d5c7f695a6f835690d4f616cba78aaacf15c1661c8e6802524c903b0dcaaf0f89ee9803d654b702865c2cdd438b90426d4
-  data.tar.gz: fb274000955f0ba2f3f68d2d6564fbd930656f792993b7be394861afb1c6df2d76f0ccffb7ef6b68dd3b4d646da9a8a8c7b58250db85bfe420c5ea0643c77828
+  metadata.gz: 0a319a1f8fb97586fffd1154107b0c3e75994a669301061afaf6f53a9aa065a8a2f522d2b3173d7391fc1cdadbb011549b6120a32f1b4bb004e2a29b4c850ed9
+  data.tar.gz: fc47408a9feeaddf3cf2ec956940bf3a0835f4824faa1c6ca0c41a315dcd4e04efb171e1fc05e9c84685a17f355d0db680e557c9806ce2370e984f38ab3526af

data/README.md

@@ -50,30 +50,42 @@ end
 query = Tcat::Query.new('your_tracking_number')
 
 # Get shipment status
-status = query.perform
-
-# Status will be one of the following:
+status = query.status_code
+# Returns one of the following:
 # :done        - Successfully delivered
 # :delivering  - Out for delivery
 # :collected   - Package collected
 # :in_transit  - In transit
 # :unknown     - Unknown status
-```
 
-### Error Handling
+# Get latest status details
+latest = query.latest_status
+if latest
+  puts "Status: #{latest.status}"         # e.g. "Successfully delivered"
+  puts "Status code: #{latest.status_code}" # e.g. :done
+  puts "Time: #{latest.time}"           # Time object
+  puts "Office: #{latest.office}"       # e.g. "Tainan office"
+  puts "Last update: #{latest.last_update}" # Time object
+end
 
-```ruby
-begin
-  status = query.perform
-rescue Tcat::HttpClient::RequestError => e
-  puts "Network request error: #{e.message}"
-rescue Tcat::EncryptionService::EncryptionError => e
-  puts "Encryption error: #{e.message}"
-rescue StandardError => e
-  puts "Other error: #{e.message}"
+# Get full shipment history
+history = query.history
+history.each do |item|
+  puts "Status: #{item.status}"
+  puts "Time: #{item.time}"
+  puts "Office: #{item.office}"
+  puts "---"
 end
 ```
 
+### Status Code Explanation
+
+- `:done` - Successfully delivered
+- `:delivering` - Out for delivery
+- `:collected` - Package collected
+- `:in_transit` - In transit
+- `:unknown` - Unknown status
+
 ## Development
 
 1. Fork the project
@@ -104,6 +116,21 @@ This gem is available as open source under the terms of the [MIT License](https:
 
 ## Changelog
 
+### 0.1.7
+
+- Improved method naming, removed get_ prefix
+- Added `latest_status` method to get latest status details
+- Added `history` method to get full shipment history
+- Used `DeliveryItem` struct to provide more complete shipment information
+- Improved error handling and logging
+- Supported UTF-8 encoding
+
+### 0.1.6
+
+- Refactored query parsing method
+- Improved error handling
+- Added test coverage
+
 ### 0.1.5 (2024-01-11)
 
 - Refactored HTTP request handling with new HttpClient class

data/lib/tcat/query.rb

@@ -9,6 +9,8 @@ require_relative 'encryption_service'
 module Tcat
   # Query class handles making requests to the Tcat system
   class Query
+    DeliveryItem = Struct.new(:status, :status_code, :time, :office, :last_update, keyword_init: true)
+
     def initialize(tracking_number)
       @secret_string = Tcat.configuration.secret_string
       @secret_key = Tcat.configuration.secret_key
@@ -19,14 +21,38 @@ module Tcat
       @encryption_service = EncryptionService.new(@secret_key)
     end
 
-    def perform
+    # Get current delivery status code
+    # @return [Symbol] Status code (:done, :delivering, :collected, :in_transit, :unknown)
+    def status_code
       response_body = @http_client.post(data)
-      parse_response(response_body) if response_body
+      parse_status_code(response_body) if response_body
     rescue HttpClient::RequestError => e
       # Log error or handle it appropriately
       nil
     end
 
+    # Get complete delivery history
+    # @return [Array<DeliveryItem>] Array of delivery status items, sorted by time (newest first)
+    def history
+      response_body = @http_client.post(data)
+      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
+      Rails.logger.error("Error getting delivery history: #{e.message}")
+      []
+    end
+
+    # Get latest delivery status with details
+    # @return [DeliveryItem, nil] Latest delivery status or nil if no history
+    def latest_status
+      items = history
+      return nil if items.empty?
+      items.first
+    end
+
     private
 
     def validate_secrets!
@@ -63,7 +89,7 @@ module Tcat
       raise "Failed to generate secret: #{e.message}"
     end
 
-    def parse_response(xml)
+    def parse_status_code(xml)
       begin
         result = Ox.load(xml, mode: :hash, with_cdata: true)
         return :error unless result.dig(:Result, :Status) == '0'
@@ -78,6 +104,49 @@ module Tcat
       end
     end
 
+    def extract_delivery_history(result)
+      items = result.dig(:Result, :Content, :Item)
+      case items
+      when Hash
+        [parse_delivery_item(items)]
+      when Array
+        items.map { |item| parse_delivery_item(item) }
+      else
+        []
+      end.compact.sort_by(&:time).reverse
+    rescue StandardError => e
+      Rails.logger.error("Error parsing delivery history: #{e.message}")
+      []
+    end
+
+    def parse_delivery_item(item)
+      return nil unless item[:Status] && item[:Time]
+
+      DeliveryItem.new(
+        status: item[:Status].to_s.force_encoding('UTF-8'),
+        status_code: parse_status_message([item[:Status].to_s.force_encoding('UTF-8')]),
+        time: parse_time(item[:Time]),
+        office: item[:Office].to_s.force_encoding('UTF-8'),
+        last_update: parse_last_update(item[:LastUPDateTime])
+      )
+    end
+
+    def parse_time(time_str)
+      return nil unless time_str
+
+      Time.strptime(time_str.to_s, '%Y/%m/%d %H:%M')
+    rescue
+      nil
+    end
+
+    def parse_last_update(datetime_str)
+      return nil unless datetime_str
+
+      Time.strptime(datetime_str.to_s, '%Y%m%d%H%M%S')
+    rescue
+      nil
+    end
+
     def extract_delivery_statuses(items)
       case items
       when Hash

data/lib/tcat/version.rb

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

metadata

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