tcat 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac88c04a17a00b5b457a86bcf3bad081ac0fb48886351c1033fd1b89e2ebe399
-  data.tar.gz: 4adfbb15946f3f42b2b655911f2501824e401aa08d22635aafb01cb73f9adb85
+  metadata.gz: a18e5eb9e8c06ea5d7aea3fdd3cee1141f591757f77689480d423fb78af85986
+  data.tar.gz: 7c3c3618e8da45617b6ea86d6bfa8a91abfe4427373b2fe7ba53a44d53bee76f
 SHA512:
-  metadata.gz: 34d8e04435756d743116aa0da37132d5c7f695a6f835690d4f616cba78aaacf15c1661c8e6802524c903b0dcaaf0f89ee9803d654b702865c2cdd438b90426d4
-  data.tar.gz: fb274000955f0ba2f3f68d2d6564fbd930656f792993b7be394861afb1c6df2d76f0ccffb7ef6b68dd3b4d646da9a8a8c7b58250db85bfe420c5ea0643c77828
+  metadata.gz: 7d8a6ee4c3d39970e3d01b4c2247cd645e85d60c29056ac690b6b3bfe37f54c58fb21bff561c0705f8e43bac868348f5834213a037b2f20ed2103620cab36882
+  data.tar.gz: b0c803de7bc9e57e5c85cc2784ca944a1a434d1d25b87b30395f972e04ffa6753841f9f6bb96fe0cda165ebfd56ca9f9cbefca8afba34b2e25af4b7044c05852

data/README.md

@@ -50,30 +50,54 @@ 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
+# :returned    - Return completed
+# :held        - Held at post office
+# :forwarding  - Being forwarded
+# :investigation - Under investigation
+# :rejected    - Delivery rejected
+# :returning   - In return process
 # :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
+- `:returned` - Return completed
+- `:held` - Package is being held at post office
+- `:forwarding` - Package is being forwarded
+- `:investigation` - Package is under investigation (e.g., address change, rejection)
+- `:rejected` - Delivery was rejected
+- `:returning` - Package is in return process
+- `:unknown` - Unknown status
+
 ## Development
 
 1. Fork the project
@@ -104,6 +128,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
@@ -93,7 +162,14 @@ module Tcat
       '順利送達' => :done,
       '配送中' => :delivering,
       '已集貨' => :collected,
-      '轉運中' => :in_transit
+      '轉運中' => :in_transit,
+      '退貨完成' => :returned,
+      '暫置營業所保管中' => :held,
+      '轉寄配送中' => :forwarding,
+      '搬家(調查處理中)' => :investigation,
+      '拒收(調查處理中)' => :investigation,
+      '拒收' => :rejected,
+      '客樂得貨物退回中' => :returning
     }.freeze
 
     def parse_status_message(statuses)

data/lib/tcat/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcat
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Zac
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-11-19 00:00:00.000000000 Z
+date: 2024-11-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ox