tcat 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: ac88c04a17a00b5b457a86bcf3bad081ac0fb48886351c1033fd1b89e2ebe399
4
- data.tar.gz: 4adfbb15946f3f42b2b655911f2501824e401aa08d22635aafb01cb73f9adb85
3
+ metadata.gz: a18e5eb9e8c06ea5d7aea3fdd3cee1141f591757f77689480d423fb78af85986
4
+ data.tar.gz: 7c3c3618e8da45617b6ea86d6bfa8a91abfe4427373b2fe7ba53a44d53bee76f
5
5
  SHA512:
6
- metadata.gz: 34d8e04435756d743116aa0da37132d5c7f695a6f835690d4f616cba78aaacf15c1661c8e6802524c903b0dcaaf0f89ee9803d654b702865c2cdd438b90426d4
7
- data.tar.gz: fb274000955f0ba2f3f68d2d6564fbd930656f792993b7be394861afb1c6df2d76f0ccffb7ef6b68dd3b4d646da9a8a8c7b58250db85bfe420c5ea0643c77828
6
+ metadata.gz: 7d8a6ee4c3d39970e3d01b4c2247cd645e85d60c29056ac690b6b3bfe37f54c58fb21bff561c0705f8e43bac868348f5834213a037b2f20ed2103620cab36882
7
+ data.tar.gz: b0c803de7bc9e57e5c85cc2784ca944a1a434d1d25b87b30395f972e04ffa6753841f9f6bb96fe0cda165ebfd56ca9f9cbefca8afba34b2e25af4b7044c05852
data/README.md CHANGED
@@ -50,30 +50,54 @@ end
50
50
  query = Tcat::Query.new('your_tracking_number')
51
51
 
52
52
  # Get shipment status
53
- status = query.perform
54
-
55
- # Status will be one of the following:
53
+ status = query.status_code
54
+ # Returns one of the following:
56
55
  # :done - Successfully delivered
57
56
  # :delivering - Out for delivery
58
57
  # :collected - Package collected
59
58
  # :in_transit - In transit
59
+ # :returned - Return completed
60
+ # :held - Held at post office
61
+ # :forwarding - Being forwarded
62
+ # :investigation - Under investigation
63
+ # :rejected - Delivery rejected
64
+ # :returning - In return process
60
65
  # :unknown - Unknown status
61
- ```
62
66
 
63
- ### Error Handling
67
+ # Get latest status details
68
+ latest = query.latest_status
69
+ if latest
70
+ puts "Status: #{latest.status}" # e.g. "Successfully delivered"
71
+ puts "Status code: #{latest.status_code}" # e.g. :done
72
+ puts "Time: #{latest.time}" # Time object
73
+ puts "Office: #{latest.office}" # e.g. "Tainan office"
74
+ puts "Last update: #{latest.last_update}" # Time object
75
+ end
64
76
 
65
- ```ruby
66
- begin
67
- status = query.perform
68
- rescue Tcat::HttpClient::RequestError => e
69
- puts "Network request error: #{e.message}"
70
- rescue Tcat::EncryptionService::EncryptionError => e
71
- puts "Encryption error: #{e.message}"
72
- rescue StandardError => e
73
- puts "Other error: #{e.message}"
77
+ # Get full shipment history
78
+ history = query.history
79
+ history.each do |item|
80
+ puts "Status: #{item.status}"
81
+ puts "Time: #{item.time}"
82
+ puts "Office: #{item.office}"
83
+ puts "---"
74
84
  end
75
85
  ```
76
86
 
87
+ ### Status Code Explanation
88
+
89
+ - `:done` - Successfully delivered
90
+ - `:delivering` - Out for delivery
91
+ - `:collected` - Package collected
92
+ - `:in_transit` - In transit
93
+ - `:returned` - Return completed
94
+ - `:held` - Package is being held at post office
95
+ - `:forwarding` - Package is being forwarded
96
+ - `:investigation` - Package is under investigation (e.g., address change, rejection)
97
+ - `:rejected` - Delivery was rejected
98
+ - `:returning` - Package is in return process
99
+ - `:unknown` - Unknown status
100
+
77
101
  ## Development
78
102
 
79
103
  1. Fork the project
@@ -104,6 +128,21 @@ This gem is available as open source under the terms of the [MIT License](https:
104
128
 
105
129
  ## Changelog
106
130
 
131
+ ### 0.1.7
132
+
133
+ - Improved method naming, removed get_ prefix
134
+ - Added `latest_status` method to get latest status details
135
+ - Added `history` method to get full shipment history
136
+ - Used `DeliveryItem` struct to provide more complete shipment information
137
+ - Improved error handling and logging
138
+ - Supported UTF-8 encoding
139
+
140
+ ### 0.1.6
141
+
142
+ - Refactored query parsing method
143
+ - Improved error handling
144
+ - Added test coverage
145
+
107
146
  ### 0.1.5 (2024-01-11)
108
147
 
109
148
  - Refactored HTTP request handling with new HttpClient class
data/lib/tcat/query.rb CHANGED
@@ -9,6 +9,8 @@ require_relative 'encryption_service'
9
9
  module Tcat
10
10
  # Query class handles making requests to the Tcat system
11
11
  class Query
12
+ DeliveryItem = Struct.new(:status, :status_code, :time, :office, :last_update, keyword_init: true)
13
+
12
14
  def initialize(tracking_number)
13
15
  @secret_string = Tcat.configuration.secret_string
14
16
  @secret_key = Tcat.configuration.secret_key
@@ -19,14 +21,38 @@ module Tcat
19
21
  @encryption_service = EncryptionService.new(@secret_key)
20
22
  end
21
23
 
22
- def perform
24
+ # Get current delivery status code
25
+ # @return [Symbol] Status code (:done, :delivering, :collected, :in_transit, :unknown)
26
+ def status_code
23
27
  response_body = @http_client.post(data)
24
- parse_response(response_body) if response_body
28
+ parse_status_code(response_body) if response_body
25
29
  rescue HttpClient::RequestError => e
26
30
  # Log error or handle it appropriately
27
31
  nil
28
32
  end
29
33
 
34
+ # Get complete delivery history
35
+ # @return [Array<DeliveryItem>] Array of delivery status items, sorted by time (newest first)
36
+ def history
37
+ response_body = @http_client.post(data)
38
+ if response_body
39
+ result = Ox.load(response_body, mode: :hash, with_cdata: true)
40
+ return [] if result.dig(:Result, :Status) != '0'
41
+ extract_delivery_history(result)
42
+ end
43
+ rescue StandardError => e
44
+ Rails.logger.error("Error getting delivery history: #{e.message}")
45
+ []
46
+ end
47
+
48
+ # Get latest delivery status with details
49
+ # @return [DeliveryItem, nil] Latest delivery status or nil if no history
50
+ def latest_status
51
+ items = history
52
+ return nil if items.empty?
53
+ items.first
54
+ end
55
+
30
56
  private
31
57
 
32
58
  def validate_secrets!
@@ -63,7 +89,7 @@ module Tcat
63
89
  raise "Failed to generate secret: #{e.message}"
64
90
  end
65
91
 
66
- def parse_response(xml)
92
+ def parse_status_code(xml)
67
93
  begin
68
94
  result = Ox.load(xml, mode: :hash, with_cdata: true)
69
95
  return :error unless result.dig(:Result, :Status) == '0'
@@ -78,6 +104,49 @@ module Tcat
78
104
  end
79
105
  end
80
106
 
107
+ def extract_delivery_history(result)
108
+ items = result.dig(:Result, :Content, :Item)
109
+ case items
110
+ when Hash
111
+ [parse_delivery_item(items)]
112
+ when Array
113
+ items.map { |item| parse_delivery_item(item) }
114
+ else
115
+ []
116
+ end.compact.sort_by(&:time).reverse
117
+ rescue StandardError => e
118
+ Rails.logger.error("Error parsing delivery history: #{e.message}")
119
+ []
120
+ end
121
+
122
+ def parse_delivery_item(item)
123
+ return nil unless item[:Status] && item[:Time]
124
+
125
+ DeliveryItem.new(
126
+ status: item[:Status].to_s.force_encoding('UTF-8'),
127
+ status_code: parse_status_message([item[:Status].to_s.force_encoding('UTF-8')]),
128
+ time: parse_time(item[:Time]),
129
+ office: item[:Office].to_s.force_encoding('UTF-8'),
130
+ last_update: parse_last_update(item[:LastUPDateTime])
131
+ )
132
+ end
133
+
134
+ def parse_time(time_str)
135
+ return nil unless time_str
136
+
137
+ Time.strptime(time_str.to_s, '%Y/%m/%d %H:%M')
138
+ rescue
139
+ nil
140
+ end
141
+
142
+ def parse_last_update(datetime_str)
143
+ return nil unless datetime_str
144
+
145
+ Time.strptime(datetime_str.to_s, '%Y%m%d%H%M%S')
146
+ rescue
147
+ nil
148
+ end
149
+
81
150
  def extract_delivery_statuses(items)
82
151
  case items
83
152
  when Hash
@@ -93,7 +162,14 @@ module Tcat
93
162
  '順利送達' => :done,
94
163
  '配送中' => :delivering,
95
164
  '已集貨' => :collected,
96
- '轉運中' => :in_transit
165
+ '轉運中' => :in_transit,
166
+ '退貨完成' => :returned,
167
+ '暫置營業所保管中' => :held,
168
+ '轉寄配送中' => :forwarding,
169
+ '搬家(調查處理中)' => :investigation,
170
+ '拒收(調查處理中)' => :investigation,
171
+ '拒收' => :rejected,
172
+ '客樂得貨物退回中' => :returning
97
173
  }.freeze
98
174
 
99
175
  def parse_status_message(statuses)
data/lib/tcat/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Tcat
4
- VERSION = '0.1.6'
4
+ VERSION = '0.1.8'
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: tcat
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.6
4
+ version: 0.1.8
5
5
  platform: ruby
6
6
  authors:
7
7
  - Zac
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2024-11-19 00:00:00.000000000 Z
11
+ date: 2024-11-24 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: ox