tcat 0.4.1 → 0.5.0

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: 588b8dd9b49b05b35d28384cb85c3bc4e87b38852a04c3da8ce5b35ce59739bc
4
- data.tar.gz: cd704ade306674058f6fd4c8de240d7570f54dba29ad7e1dfe30afb3b0119d40
3
+ metadata.gz: 33e61c6fc0aacf1483c733be09bc431229c1dec02978c3b3c95dbc7c8ab575fd
4
+ data.tar.gz: 668037fd822a935f4e46730008303e87675a98e0befe51b435011b84e074ff03
5
5
  SHA512:
6
- metadata.gz: 8617ad7c2b5bec16c3d7c94fd39175b45417a869feb6a74f0a1fab3590860c44d4a7e61a49b908982ae65f4b856504de3e61c9f96ba082c0ef0736cf936a59ca
7
- data.tar.gz: '059ea7b7711cae4a2d146a23470016048edfb6e5c5d8951822ba17be8bd792355b1f9d29a73cc1b40e604884b332ac1548e453fb66f3cc22cff6c43198c510c7'
6
+ metadata.gz: bd31d9873c4514a00e7ab7a29c4c499deee41cfeb69f52a573a631e67a1456ffc24b65f2d782b47d76aa9612b74d0757dfe7af084ae6d72a97ee403a8df0a39e
7
+ data.tar.gz: 05ba7daac7c9257ae4a5cc9f2db70789334e216a551b4b4d8a8c3ab79ba29f1cc4f06991a5220d6de7c84f8986250d963d23976133189566f672d9c6acd1d746
data/CHANGELOG.md ADDED
@@ -0,0 +1,102 @@
1
+ # Changelog
2
+
3
+ ## 0.5.0
4
+
5
+ - **Breaking:** requires Ruby >= 3.3 (CI covers 3.3, 3.4 and 4.0)
6
+ - **Breaking:** removed the unused `Tcat::Error` constant (it was never raised)
7
+ - `Tcat::Query#status_code` now reflects the newest event; previously an earlier status (e.g. `配送中`) could mask the current one (e.g. `轉交超商配達`, `客樂得貨物退回中`)
8
+ - `Tcat::Query` parses T-Cat timestamps as Taiwan time (UTC+8) regardless of the host time zone
9
+ - `Tcat::Query` no longer drops the whole history when an item has no `<Office>`
10
+ - `Tcat::WorkerClient` wraps timeouts, refused connections and SSL errors in `NetworkError`, so `status_code`/`history`/`latest_status` return `nil`/`[]` as documented
11
+ - Worker: forwards every session cookie, uses `crypto.getRandomValues`, and times out upstream requests after 10s
12
+
13
+ ## 0.4.1
14
+
15
+ - Security hardening: `Tcat::Query` now uses `SecureRandom` (CSPRNG) instead of `rand` for the per-request freshness component embedded in the encrypted `secret` payload
16
+ - Encryption: `Tcat::EncryptionService` explicitly disables OpenSSL's built-in cipher padding so the manually applied PKCS#7 padding cannot be double-applied if the cipher pipeline ever changes
17
+ - `Tcat::WorkerClient` warns when `worker_url` uses `http://` against a non-localhost host so a misconfigured deployment cannot silently leak the Bearer token over plaintext
18
+ - Worker: added `[observability.logs]` (`enabled = false`, `invocation_logs = true`) to `wrangler.toml`
19
+
20
+ ## 0.4.0
21
+
22
+ - `Tcat::Query#status_code`, `#history`, `#latest_status` now accept an optional tracking-number argument, mirroring `Tcat::WorkerClient`'s shape
23
+ - `Tcat::Query.new` may be called without a tracking number for stateless reuse: `Tcat::Query.new.status_code('1234567890')`
24
+ - Existing one-shot construction (`Tcat::Query.new(tn).status_code`) is still supported
25
+
26
+ ## 0.3.5
27
+
28
+ - Added optional `worker_url` and `worker_token` to `Tcat.configure`; explicit `Tcat::WorkerClient.new(url, token:)` arguments still take precedence
29
+ - `Tcat::WorkerClient.new` now accepts no arguments when `worker_url` is set in configuration
30
+
31
+ ## 0.3.4
32
+
33
+ - Bundled the 0.3.3 fixes for release on RubyGems
34
+
35
+ ## 0.3.3
36
+
37
+ - Worker now subtracts the Taiwan UTC+8 offset when emitting ISO timestamps (previously every event was reported 8 hours later than reality)
38
+ - Worker forwards only the `name=value` portion of `Set-Cookie` to the upstream `Cookie:` header (RFC 6265)
39
+ - Worker rejects `/query` with HTTP 401 when `AUTH_TOKEN` is not configured (fail-closed)
40
+ - 5xx responses no longer leak `error.message`; details are written to `console.error` (visible via `wrangler tail`)
41
+
42
+ ## 0.3.2
43
+
44
+ - Added optional Bearer token auth to the Cloudflare Worker (`AUTH_TOKEN` secret)
45
+ - `Tcat::WorkerClient` accepts a `token:` keyword arg that is sent as `Authorization: Bearer <token>`
46
+ - Worker compares tokens in constant time; CORS allow-headers gain `Authorization`
47
+
48
+ ## 0.3.1
49
+
50
+ - Tightened `tcat.gemspec` so the published gem no longer bundles the `worker/` subproject or dev-only configs
51
+
52
+ ## 0.3.0
53
+
54
+ - Added `Tcat::WorkerClient` to query a Cloudflare Worker proxy instead of T-Cat directly
55
+ - Added new status mapping: `:store_delivery` for `轉交超商配達` (handed over to convenience store)
56
+ - Added the `worker/` Cloudflare Worker subproject (separate from the gem release)
57
+
58
+ ## 0.2.2
59
+
60
+ - Fixed status parsing to handle HTML tags in API responses
61
+
62
+ ## 0.2.1
63
+
64
+ - Updated base64 gem dependency to ~> 0.3
65
+ - Code formatting improvements
66
+
67
+ ## 0.2.0
68
+
69
+ - Fixed SSL certificate verification issues with T-Cat API
70
+ - Added session initialization to obtain cookies before queries
71
+ - Added cookie management for maintaining session state
72
+ - Added new status code mappings: `:rescheduled` (另約時間) and `:held` (暫置營業所)
73
+ - Removed Rails.logger dependency for better standalone gem compatibility
74
+ - Added base64 gem dependency for Ruby 3.4+ compatibility
75
+ - Updated HTTP headers to match latest BlackCat iOS app (version 3)
76
+ - Improved error handling with better debug output
77
+
78
+ ## 0.1.9
79
+
80
+ - Updated User-Agent and API version
81
+
82
+ ## 0.1.7
83
+
84
+ - Improved method naming, removed get_ prefix
85
+ - Added `latest_status` method to get latest status details
86
+ - Added `history` method to get full shipment history
87
+ - Used `DeliveryItem` struct to provide more complete shipment information
88
+ - Improved error handling and logging
89
+ - Supported UTF-8 encoding
90
+
91
+ ## 0.1.6
92
+
93
+ - Refactored query parsing method
94
+ - Improved error handling
95
+ - Added test coverage
96
+
97
+ ## 0.1.5
98
+
99
+ - Refactored HTTP request handling with new HttpClient class
100
+ - Refactored encryption logic with new EncryptionService class
101
+ - Improved error handling
102
+ - Updated documentation
data/README.md CHANGED
@@ -88,6 +88,8 @@ status = query.status_code('your_tracking_number')
88
88
  # :returning - In return process
89
89
  # :store_delivery - At convenience store for pickup
90
90
  # :unknown - Unknown status
91
+ # :error - T-Cat returned an error response (Query only)
92
+ # nil - Request failed
91
93
 
92
94
  # Get latest status details
93
95
  latest = query.latest_status
@@ -177,9 +179,12 @@ client = Tcat::WorkerClient.new('https://your-worker.workers.dev', timeout: 60)
177
179
 
178
180
  **Error handling:**
179
181
 
182
+ `status_code`, `history` and `latest_status` swallow errors and return `nil` / `[]`.
183
+ Use `query` when you need the exception:
184
+
180
185
  ```ruby
181
186
  begin
182
- status = client.status_code('tracking_number')
187
+ result = client.query('tracking_number')
183
188
  rescue Tcat::WorkerClient::NetworkError => e
184
189
  puts "Network error: #{e.message}"
185
190
  rescue Tcat::WorkerClient::APIError => e
@@ -270,93 +275,4 @@ This gem is available as open source under the terms of the [MIT License](https:
270
275
 
271
276
  ## Changelog
272
277
 
273
- ### 0.4.1
274
-
275
- - Security hardening: `Tcat::Query` now uses `SecureRandom` (CSPRNG) instead of `rand` for the per-request freshness component embedded in the encrypted `secret` payload
276
- - Encryption: `Tcat::EncryptionService` explicitly disables OpenSSL's built-in cipher padding so the manually applied PKCS#7 padding cannot be double-applied if the cipher pipeline ever changes
277
- - `Tcat::WorkerClient` warns when `worker_url` uses `http://` against a non-localhost host so a misconfigured deployment cannot silently leak the Bearer token over plaintext
278
- - Worker: added `[observability.logs]` (`enabled = false`, `invocation_logs = true`) to `wrangler.toml`
279
-
280
- ### 0.4.0
281
-
282
- - `Tcat::Query#status_code`, `#history`, `#latest_status` now accept an optional tracking-number argument, mirroring `Tcat::WorkerClient`'s shape
283
- - `Tcat::Query.new` may be called without a tracking number for stateless reuse: `Tcat::Query.new.status_code('1234567890')`
284
- - Existing one-shot construction (`Tcat::Query.new(tn).status_code`) is still supported
285
-
286
- ### 0.3.5
287
-
288
- - Added optional `worker_url` and `worker_token` to `Tcat.configure`; explicit `Tcat::WorkerClient.new(url, token:)` arguments still take precedence
289
- - `Tcat::WorkerClient.new` now accepts no arguments when `worker_url` is set in configuration
290
-
291
- ### 0.3.4
292
-
293
- - Bundled the 0.3.3 fixes for release on RubyGems
294
-
295
- ### 0.3.3
296
-
297
- - Worker now subtracts the Taiwan UTC+8 offset when emitting ISO timestamps (previously every event was reported 8 hours later than reality)
298
- - Worker forwards only the `name=value` portion of `Set-Cookie` to the upstream `Cookie:` header (RFC 6265)
299
- - Worker rejects `/query` with HTTP 401 when `AUTH_TOKEN` is not configured (fail-closed)
300
- - 5xx responses no longer leak `error.message`; details are written to `console.error` (visible via `wrangler tail`)
301
-
302
- ### 0.3.2
303
-
304
- - Added optional Bearer token auth to the Cloudflare Worker (`AUTH_TOKEN` secret)
305
- - `Tcat::WorkerClient` accepts a `token:` keyword arg that is sent as `Authorization: Bearer <token>`
306
- - Worker compares tokens in constant time; CORS allow-headers gain `Authorization`
307
-
308
- ### 0.3.1
309
-
310
- - Tightened `tcat.gemspec` so the published gem no longer bundles the `worker/` subproject or dev-only configs
311
-
312
- ### 0.3.0
313
-
314
- - Added `Tcat::WorkerClient` to query a Cloudflare Worker proxy instead of T-Cat directly
315
- - Added new status mapping: `:store_delivery` for `轉交超商配達` (handed over to convenience store)
316
- - Added the `worker/` Cloudflare Worker subproject (separate from the gem release)
317
-
318
- ### 0.2.2
319
-
320
- - Fixed status parsing to handle HTML tags in API responses
321
-
322
- ### 0.2.1
323
-
324
- - Updated base64 gem dependency to ~> 0.3
325
- - Code formatting improvements
326
-
327
- ### 0.2.0
328
-
329
- - Fixed SSL certificate verification issues with T-Cat API
330
- - Added session initialization to obtain cookies before queries
331
- - Added cookie management for maintaining session state
332
- - Added new status code mappings: `:rescheduled` (另約時間) and `:held` (暫置營業所)
333
- - Removed Rails.logger dependency for better standalone gem compatibility
334
- - Added base64 gem dependency for Ruby 3.4+ compatibility
335
- - Updated HTTP headers to match latest BlackCat iOS app (version 3)
336
- - Improved error handling with better debug output
337
-
338
- ### 0.1.9
339
-
340
- - Updated User-Agent and API version
341
-
342
- ### 0.1.7
343
-
344
- - Improved method naming, removed get_ prefix
345
- - Added `latest_status` method to get latest status details
346
- - Added `history` method to get full shipment history
347
- - Used `DeliveryItem` struct to provide more complete shipment information
348
- - Improved error handling and logging
349
- - Supported UTF-8 encoding
350
-
351
- ### 0.1.6
352
-
353
- - Refactored query parsing method
354
- - Improved error handling
355
- - Added test coverage
356
-
357
- ### 0.1.5
358
-
359
- - Refactored HTTP request handling with new HttpClient class
360
- - Refactored encryption logic with new EncryptionService class
361
- - Improved error handling
362
- - Updated documentation
278
+ See [CHANGELOG.md](CHANGELOG.md).
data/lib/tcat/query.rb CHANGED
@@ -1,7 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'net/http'
4
- require 'base64'
5
3
  require 'securerandom'
6
4
  require 'ox'
7
5
  require_relative 'http_client'
@@ -37,7 +35,6 @@ module Tcat
37
35
  response_body = @http_client.post(data(tn))
38
36
  parse_status_code(response_body) if response_body
39
37
  rescue HttpClient::RequestError
40
- # Log error or handle it appropriately
41
38
  nil
42
39
  end
43
40
 
@@ -120,7 +117,6 @@ module Tcat
120
117
  def generate_secret
121
118
  @encryption_service.encrypt(source_string)
122
119
  rescue EncryptionService::EncryptionError => e
123
- # Log error or handle it appropriately
124
120
  raise "Failed to generate secret: #{e.message}"
125
121
  end
126
122
 
@@ -129,10 +125,9 @@ module Tcat
129
125
  result = Ox.load(xml, mode: :hash, with_cdata: true)
130
126
  return :error unless result.dig(:Result, :Status) == '0'
131
127
 
132
- delivery_items = result.dig(:Result, :Content, :Item)
133
- delivery_statuses = extract_delivery_statuses(delivery_items)
134
-
135
- parse_status_message(delivery_statuses.uniq)
128
+ # The newest event is the current state; matching across the whole
129
+ # history let early events (e.g. 配送中) mask later ones (e.g. 轉交超商配達).
130
+ extract_delivery_history(result).first&.status_code || :unknown
136
131
  rescue StandardError => e
137
132
  warn "Error parsing T-Cat response: #{e.message}" if $DEBUG
138
133
  :error
@@ -148,7 +143,7 @@ module Tcat
148
143
  items.map { |item| parse_delivery_item(item) }
149
144
  else
150
145
  []
151
- end.compact.sort_by(&:time).reverse
146
+ end.compact.sort_by { |item| item.time || Time.at(0) }.reverse
152
147
  rescue StandardError => e
153
148
  warn "Error parsing delivery history: #{e.message}" if $DEBUG
154
149
  []
@@ -161,9 +156,9 @@ module Tcat
161
156
 
162
157
  DeliveryItem.new(
163
158
  status: status_text,
164
- status_code: parse_status_message([status_text]),
159
+ status_code: STATUS_MAPPINGS.fetch(status_text, :unknown),
165
160
  time: parse_time(item[:Time]),
166
- office: item[:Office].to_s.force_encoding('UTF-8'),
161
+ office: item[:Office].to_s.dup.force_encoding('UTF-8'),
167
162
  last_update: parse_last_update(item[:LastUPDateTime])
168
163
  )
169
164
  end
@@ -171,7 +166,7 @@ module Tcat
171
166
  def parse_time(time_str)
172
167
  return nil unless time_str
173
168
 
174
- Time.strptime(time_str.to_s, '%Y/%m/%d %H:%M')
169
+ Time.strptime("#{time_str} #{TAIWAN_OFFSET}", '%Y/%m/%d %H:%M %z')
175
170
  rescue
176
171
  nil
177
172
  end
@@ -179,27 +174,18 @@ module Tcat
179
174
  def parse_last_update(datetime_str)
180
175
  return nil unless datetime_str
181
176
 
182
- Time.strptime(datetime_str.to_s, '%Y%m%d%H%M%S')
177
+ Time.strptime("#{datetime_str} #{TAIWAN_OFFSET}", '%Y%m%d%H%M%S %z')
183
178
  rescue
184
179
  nil
185
180
  end
186
181
 
187
- def extract_delivery_statuses(items)
188
- statuses = case items
189
- when Hash
190
- [items[:Status].force_encoding('UTF-8')]
191
- when Array
192
- items.map { |item| item[:Status].force_encoding('UTF-8') }
193
- else
194
- []
195
- end
196
- statuses.map { |status| strip_html_tags(status) }
197
- end
198
-
199
182
  def strip_html_tags(text)
200
183
  text.gsub(/<[^>]+>/, '').strip
201
184
  end
202
185
 
186
+ # T-Cat reports times in Taiwan local time regardless of the host's TZ.
187
+ TAIWAN_OFFSET = '+0800'
188
+
203
189
  STATUS_MAPPINGS = {
204
190
  '順利送達' => :done,
205
191
  '配送中' => :delivering,
@@ -216,12 +202,5 @@ module Tcat
216
202
  '客樂得貨物退回中' => :returning,
217
203
  '轉交超商配達' => :store_delivery
218
204
  }.freeze
219
-
220
- def parse_status_message(statuses)
221
- STATUS_MAPPINGS.each do |status_text, status_symbol|
222
- return status_symbol if statuses.include?(status_text)
223
- end
224
- :unknown
225
- end
226
205
  end
227
206
  end
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.4.1'
4
+ VERSION = '0.5.0'
5
5
  end
@@ -2,6 +2,7 @@
2
2
 
3
3
  require 'net/http'
4
4
  require 'json'
5
+ require 'openssl'
5
6
  require 'uri'
6
7
 
7
8
  module Tcat
@@ -44,7 +45,8 @@ module Tcat
44
45
 
45
46
  response = make_request(uri)
46
47
  parse_response(response)
47
- rescue SocketError, Net::HTTPError => e
48
+ rescue SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPError => e
49
+ # SystemCallError: ECONNREFUSED/ECONNRESET; Timeout::Error: Net::OpenTimeout/ReadTimeout
48
50
  raise NetworkError, "Network error: #{e.message}"
49
51
  rescue JSON::ParserError => e
50
52
  raise APIError, "Invalid JSON response: #{e.message}"
data/lib/tcat.rb CHANGED
@@ -22,7 +22,4 @@ module Tcat
22
22
  def self.reset
23
23
  @configuration = Configuration.new
24
24
  end
25
-
26
- class Error < StandardError; end
27
- # Your code goes here...
28
25
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: tcat
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.1
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Zac
@@ -60,6 +60,7 @@ executables: []
60
60
  extensions: []
61
61
  extra_rdoc_files: []
62
62
  files:
63
+ - CHANGELOG.md
63
64
  - LICENSE.txt
64
65
  - README.md
65
66
  - lib/tcat.rb
@@ -75,6 +76,7 @@ licenses:
75
76
  - MIT
76
77
  metadata:
77
78
  homepage_uri: https://rubygems.org/gems/tcat
79
+ changelog_uri: https://github.com/7a6163/tcat/blob/main/CHANGELOG.md
78
80
  rdoc_options: []
79
81
  require_paths:
80
82
  - lib
@@ -82,14 +84,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
82
84
  requirements:
83
85
  - - ">="
84
86
  - !ruby/object:Gem::Version
85
- version: 2.7.0
87
+ version: 3.3.0
86
88
  required_rubygems_version: !ruby/object:Gem::Requirement
87
89
  requirements:
88
90
  - - ">="
89
91
  - !ruby/object:Gem::Version
90
92
  version: '0'
91
93
  requirements: []
92
- rubygems_version: 4.0.6
94
+ rubygems_version: 4.0.20
93
95
  specification_version: 4
94
96
  summary: A Ruby gem for tracking packages using the Tcat system.
95
97
  test_files: []