tcat 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85733c0ed940c2fad6b032f5fed76ddc64dfacba3b3789294d60c8937f90dfdc
-  data.tar.gz: 37fbf765f958b1111eb19e02eb0c7e9bfd7298a74f64971505aa238fd64ead3f
+  metadata.gz: 5ed5fe975474cdb30f8d660719b0a59d0ea5f1813b4e86433c95cd2ee82c795e
+  data.tar.gz: 025bf6aa6cfc46a4437d72e1d8abc966853606c1ba58b56ea5f6334a541b063e
 SHA512:
-  metadata.gz: 1ecf263b82fd1e236ed577d9d2be12e73b4a708b3e6e98ca3861817a82b3955c60acc2a5a389a2b8d925c298e0f46922e37f9000449718a40e5d80d2507be1c3
-  data.tar.gz: 19bbb76b59696fe11a330d625c371383cc5e01d42dab4314182987597dccc850bd3504cd3c50891fbcb77fbc286d01d3a315794dcba0801dca4b953409c2ad27
+  metadata.gz: b59a640cf706df074a2daa9bac89dfed2d96b1cfa1720278afe00b66ca8991cf64c096e4fca3701b05e7f43009b71f5f2e57186c902b339000d76db6098f4b13
+  data.tar.gz: 4d678f18e49855e6faf85ac8f4b0969f7c3c6d7d8a176686cd31ecc875e871a36ac3452a19dc9e5c7cd02ef559fdccf4e727085984c52d0066456f1b8b27302c

data/README.md

@@ -2,13 +2,30 @@
 
 A Ruby gem for tracking T-Cat (Taiwan Pelican Express) shipment status. Provides a simple and easy-to-use API interface.
 
+## ✨ Two Ways to Use Tcat
+
+### 1. Ruby Gem (This Repository)
+Perfect for Ruby/Rails applications with direct integration.
+
+### 2. Cloudflare Worker API
+Looking for a serverless solution? Check out **[worker/README.md](worker/README.md)**
+
+Benefits of the Worker version:
+- 🌍 Global edge deployment for faster queries worldwide
+- 🔒 Secure secret storage in environment variables
+- 🌐 HTTP API accessible from any platform (JavaScript, Python, cURL, etc.)
+- 💰 Cost-effective: 100K free requests/day
+- 📱 Perfect for frontend apps, mobile apps, or microservices
+
+---
+
 ## Features
 
-- Track shipment status
-- Secure encrypted requests
-- Simple API interface
-- Non-blocking HTTP requests
-- Comprehensive error handling
+- 📦 Track shipment status
+- 🔐 Secure encrypted requests
+- 🌐 Simple API interface
+- ⚡ Non-blocking HTTP requests
+- 🛡️ Comprehensive error handling
 
 ## Installation
 
@@ -30,40 +47,47 @@ Or install it yourself as:
 $ gem install tcat
 ```
 
-## Configuration
+## Usage
 
-Configure the gem before use:
+There are two ways to use this gem:
+
+1. **Direct API Access** - Query T-Cat API directly from your Ruby application
+2. **Cloudflare Worker** - Query through a Cloudflare Worker proxy (recommended for production)
+
+### Option 1: Direct API Access
+
+Configure the gem with your T-Cat API credentials:
 
 ```ruby
 Tcat.configure do |config|
   config.secret_string = 'your_secret_string'
   config.secret_key = 'your_secret_key'
 end
-```
-
-## Usage
 
-### Basic Usage
+# Two equivalent shapes — pick whichever fits your code:
 
-```ruby
-# Create a query instance
+# A) tracking number bound at construction (one-shot)
 query = Tcat::Query.new('your_tracking_number')
-
-# Get shipment status
 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
-# :collected   - Package collected
-# :in_transit  - In transit
-# :returned    - Return completed
-# :held        - Held at post office
-# :rescheduled - Delivery time rescheduled
-# :forwarding  - Being forwarded
-# :investigation - Under investigation
-# :rejected    - Delivery rejected
-# :returning   - In return process
-# :unknown     - Unknown status
+# :done           - Successfully delivered
+# :delivering     - Out for delivery
+# :collected      - Package collected
+# :in_transit     - In transit
+# :returned       - Return completed
+# :held           - Held at post office
+# :rescheduled    - Delivery time rescheduled
+# :forwarding     - Being forwarded
+# :investigation  - Under investigation
+# :rejected       - Delivery rejected
+# :returning      - In return process
+# :store_delivery - At convenience store for pickup
+# :unknown        - Unknown status
 
 # Get latest status details
 latest = query.latest_status
@@ -85,6 +109,84 @@ history.each do |item|
 end
 ```
 
+### Option 2: Via Cloudflare Worker (Recommended)
+
+The Worker approach is recommended for production because:
+- ✅ Secrets are stored securely in Cloudflare, not in your application
+- ✅ Faster response times via Cloudflare's edge network
+- ✅ No need to manage encryption in your Ruby app
+- ✅ Can be used by any language/platform (not just Ruby)
+
+First, deploy the Cloudflare Worker (see [worker/README.md](worker/README.md) for deployment instructions).
+
+Then use the WorkerClient in your Ruby application. You can pass the Worker
+URL (and optional Bearer token) directly, or configure them globally via
+`Tcat.configure`:
+
+```ruby
+# Option A: explicit per-instance arguments
+client = Tcat::WorkerClient.new(
+  'https://your-worker.workers.dev',
+  token: ENV['TCAT_WORKER_TOKEN']  # only needed when AUTH_TOKEN is set on the Worker
+)
+
+# Option B: global configuration, then construct without arguments
+Tcat.configure do |config|
+  config.worker_url   = 'https://your-worker.workers.dev'
+  config.worker_token = ENV['TCAT_WORKER_TOKEN']
+end
+client = Tcat::WorkerClient.new
+
+# Explicit args always override configuration:
+override = Tcat::WorkerClient.new('https://other.workers.dev', token: 'other-token')
+
+# Get shipment status (same API as Query)
+status = client.status_code('your_tracking_number')
+# => :delivering
+
+# Get latest status details
+latest = client.latest_status('your_tracking_number')
+if latest
+  puts "Status: #{latest.status}"         # e.g. "配送中"
+  puts "Status code: #{latest.status_code}" # e.g. :delivering
+  puts "Time: #{latest.time}"             # Time object
+  puts "Office: #{latest.office}"         # e.g. "台北營業所"
+end
+
+# Get full shipment history
+history = client.history('your_tracking_number')
+history.each do |item|
+  puts "Status: #{item.status}"
+  puts "Time: #{item.time}"
+  puts "Office: #{item.office}"
+  puts "---"
+end
+
+# Check if Worker is healthy
+if client.healthy?
+  puts "Worker is operational"
+end
+```
+
+**Custom timeout:**
+
+```ruby
+# Default timeout is 30 seconds
+client = Tcat::WorkerClient.new('https://your-worker.workers.dev', timeout: 60)
+```
+
+**Error handling:**
+
+```ruby
+begin
+  status = client.status_code('tracking_number')
+rescue Tcat::WorkerClient::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Tcat::WorkerClient::APIError => e
+  puts "API error: #{e.message}"
+end
+```
+
 ### Status Code Explanation
 
 - `:done` - Successfully delivered
@@ -98,20 +200,52 @@ end
 - `:investigation` - Package is under investigation (e.g., address change, rejection)
 - `:rejected` - Delivery was rejected
 - `:returning` - Package is in return process
+- `:store_delivery` - Handed over to a convenience store, awaiting recipient pickup
 - `:unknown` - Unknown status
 
-## Development
+## Cloudflare Worker
 
-1. Fork the project
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -am 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Create a Pull Request
+This repository includes a Cloudflare Worker implementation that provides an HTTP API for T-Cat tracking.
+
+### Features
+
+- 🌍 Deploy globally on Cloudflare's edge network
+- 🔒 Securely store API credentials as Worker secrets
+- 🚀 Fast response times from edge locations
+- 🌐 CORS enabled for frontend applications
+- 📱 Works with any programming language
+
+### Quick Start
+
+```bash
+cd worker
+npm install
+npm run dev  # Start local development server
+```
+
+For full deployment instructions, see [worker/README.md](worker/README.md) and [worker/DEPLOYMENT.md](worker/DEPLOYMENT.md).
+
+## Comparison: Direct API vs Worker
+
+| Feature | Direct API (`Query`) | Cloudflare Worker (`WorkerClient`) |
+|---------|---------------------|-----------------------------------|
+| Setup complexity | Low (just gem install) | Medium (requires Worker deployment) |
+| Security | Secrets in your app | Secrets in Cloudflare |
+| Performance | Direct to T-Cat API | Via Cloudflare edge |
+| Multi-platform | Ruby only | Any language/platform |
+| Cost | Free | Free tier available |
+| Best for | Simple scripts, internal tools | Production apps, public APIs |
+
+## Development
 
 ### Running Tests
 
 ```bash
+# Run all tests
 $ bundle exec rake spec
+
+# Run specific test file
+$ bundle exec rspec spec/tcat/worker_client_spec.rb
 ```
 
 ### Local Installation
@@ -124,12 +258,56 @@ $ bundle exec rake install
 
 Bug reports and pull requests are welcome.
 
+1. Fork the project
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -am 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Create a Pull Request
+
 ## License
 
 This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## 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
+- `Tcat::WorkerClient.new` now accepts no arguments when `worker_url` is set in configuration
+
+### 0.3.4
+
+- Bundled the 0.3.3 fixes for release on RubyGems
+
+### 0.3.3
+
+- Worker now subtracts the Taiwan UTC+8 offset when emitting ISO timestamps (previously every event was reported 8 hours later than reality)
+- Worker forwards only the `name=value` portion of `Set-Cookie` to the upstream `Cookie:` header (RFC 6265)
+- Worker rejects `/query` with HTTP 401 when `AUTH_TOKEN` is not configured (fail-closed)
+- 5xx responses no longer leak `error.message`; details are written to `console.error` (visible via `wrangler tail`)
+
+### 0.3.2
+
+- Added optional Bearer token auth to the Cloudflare Worker (`AUTH_TOKEN` secret)
+- `Tcat::WorkerClient` accepts a `token:` keyword arg that is sent as `Authorization: Bearer <token>`
+- Worker compares tokens in constant time; CORS allow-headers gain `Authorization`
+
+### 0.3.1
+
+- Tightened `tcat.gemspec` so the published gem no longer bundles the `worker/` subproject or dev-only configs
+
+### 0.3.0
+
+- Added `Tcat::WorkerClient` to query a Cloudflare Worker proxy instead of T-Cat directly
+- Added new status mapping: `:store_delivery` for `轉交超商配達` (handed over to convenience store)
+- Added the `worker/` Cloudflare Worker subproject (separate from the gem release)
+
 ### 0.2.2
 
 - Fixed status parsing to handle HTML tags in API responses

data/lib/tcat/configuration.rb

@@ -3,11 +3,18 @@
 module Tcat
   # Configuration class handles settings for Tcat
   class Configuration
+    # T-Cat API credentials (used by Tcat::Query)
     attr_accessor :secret_string, :secret_key
 
+    # Cloudflare Worker proxy settings (used by Tcat::WorkerClient)
+    # Both are optional; explicit constructor args take precedence.
+    attr_accessor :worker_url, :worker_token
+
     def initialize
       @secret_string = nil
       @secret_key = nil
+      @worker_url = nil
+      @worker_token = nil
     end
   end
 end

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,
@@ -193,7 +211,8 @@ module Tcat
       '搬家(調查處理中)' => :investigation,
       '拒收(調查處理中)' => :investigation,
       '拒收' => :rejected,
-      '客樂得貨物退回中' => :returning
+      '客樂得貨物退回中' => :returning,
+      '轉交超商配達' => :store_delivery
     }.freeze
 
     def parse_status_message(statuses)

data/lib/tcat/version.rb

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

data/lib/tcat/worker_client.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Tcat
+  # WorkerClient provides a simple interface to query T-Cat tracking via Cloudflare Worker
+  # This is an alternative to the direct Query class that goes through your deployed Worker
+  class WorkerClient
+    class WorkerError < StandardError; end
+    class NetworkError < WorkerError; end
+    class APIError < WorkerError; end
+
+    DeliveryItem = Struct.new(:status, :status_code, :time, :office, :last_update, keyword_init: true)
+
+    attr_reader :worker_url
+
+    # Initialize a new WorkerClient
+    # @param worker_url [String, nil] The URL of your deployed Cloudflare
+    #   Worker. Falls back to `Tcat.configuration.worker_url` when omitted.
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param token [String, nil] Bearer token sent in the Authorization
+    #   header when the Worker is configured with AUTH_TOKEN. Falls back to
+    #   `Tcat.configuration.worker_token` when omitted.
+    def initialize(worker_url = nil, timeout: 30, token: nil)
+      url = worker_url || Tcat.configuration.worker_url
+      raise ArgumentError, 'Worker URL must be configured' if url.nil? || url.empty?
+
+      @worker_url = url.chomp('/')
+      @timeout = timeout
+      @token = token || Tcat.configuration.worker_token
+      validate_url!
+    end
+
+    # Query a tracking number through the Worker
+    # @param tracking_number [String] The tracking number to query
+    # @return [Hash] Parsed response from the Worker
+    def query(tracking_number)
+      raise ArgumentError, 'Tracking number cannot be nil or empty' if tracking_number.nil? || tracking_number.empty?
+
+      uri = URI("#{@worker_url}/query")
+      uri.query = URI.encode_www_form(no: tracking_number)
+
+      response = make_request(uri)
+      parse_response(response)
+    rescue SocketError, Net::HTTPError => e
+      raise NetworkError, "Network error: #{e.message}"
+    rescue JSON::ParserError => e
+      raise APIError, "Invalid JSON response: #{e.message}"
+    end
+
+    # Get the current status code for a tracking number
+    # @param tracking_number [String] The tracking number to query
+    # @return [Symbol, nil] Status code symbol or nil if error
+    def status_code(tracking_number)
+      result = query(tracking_number)
+      result[:status_code]&.to_sym
+    rescue WorkerError => e
+      warn "Error getting status: #{e.message}" if $DEBUG
+      nil
+    end
+
+    # Get the complete delivery history
+    # @param tracking_number [String] The tracking number to query
+    # @return [Array<DeliveryItem>] Array of delivery history items
+    def history(tracking_number)
+      result = query(tracking_number)
+      items = result[:items] || []
+      items.map { |item| parse_delivery_item(item) }
+    rescue WorkerError => e
+      warn "Error getting history: #{e.message}" if $DEBUG
+      []
+    end
+
+    # Get the latest delivery status
+    # @param tracking_number [String] The tracking number to query
+    # @return [DeliveryItem, nil] Latest delivery item or nil
+    def latest_status(tracking_number)
+      result = query(tracking_number)
+      return nil unless result[:latest]
+
+      parse_delivery_item(result[:latest])
+    rescue WorkerError => e
+      warn "Error getting latest status: #{e.message}" if $DEBUG
+      nil
+    end
+
+    # Check if the Worker is healthy
+    # @return [Boolean] true if Worker responds to health check
+    def healthy?
+      uri = URI("#{@worker_url}/health")
+      response = make_request(uri)
+      data = JSON.parse(response.body, symbolize_names: true)
+      data[:status] == 'ok'
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def validate_url!
+      uri = URI.parse(@worker_url)
+      unless %w[http https].include?(uri.scheme)
+        raise ArgumentError, 'Invalid Worker URL: must be http or https'
+      end
+    rescue URI::InvalidURIError => e
+      raise ArgumentError, "Invalid Worker URL: #{e.message}"
+    end
+
+    def make_request(uri)
+      response = setup_http(uri).request(build_request(uri))
+      raise APIError, "HTTP #{response.code}: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+      response
+    end
+
+    def setup_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+      http
+    end
+
+    def build_request(uri)
+      request = Net::HTTP::Get.new(uri)
+      request['Accept'] = 'application/json'
+      request['Authorization'] = "Bearer #{@token}" if @token
+      request
+    end
+
+    def parse_response(response)
+      data = JSON.parse(response.body, symbolize_names: true)
+
+      if data[:status] == 'error'
+        raise APIError, data[:message] || 'Unknown error from Worker'
+      end
+
+      data
+    end
+
+    def parse_delivery_item(item)
+      DeliveryItem.new(
+        status: item[:status],
+        status_code: item[:status_code]&.to_sym,
+        time: parse_time(item[:time]),
+        office: item[:office],
+        last_update: parse_time(item[:last_update])
+      )
+    end
+
+    def parse_time(time_str)
+      return nil if time_str.nil? || time_str.empty?
+
+      Time.parse(time_str)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/tcat.rb

@@ -3,6 +3,7 @@
 require 'tcat/configuration'
 require_relative 'tcat/version'
 require_relative 'tcat/query'
+require_relative 'tcat/worker_client'
 
 # Tcat module provides functionality for tracking packages
 module Tcat

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tcat
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Zac
@@ -60,18 +60,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec"
-- ".rubocop.yml"
-- ".tool-versions"
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/tcat.rb
 - lib/tcat/configuration.rb
 - lib/tcat/encryption_service.rb
 - lib/tcat/http_client.rb
 - lib/tcat/query.rb
 - lib/tcat/version.rb
+- lib/tcat/worker_client.rb
 - sig/tcat.rbs
 homepage: https://rubygems.org/gems/tcat
 licenses:
@@ -92,7 +89,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A Ruby gem for tracking packages using the Tcat system.
 test_files: []

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,25 +0,0 @@
-AllCops:
-  TargetRubyVersion: 2.7
-  Exclude:
-    - 'bin/*'
-
-# Style/StringLiterals:
-#   Enabled: true
-#   EnforcedStyle: double_quotes
-
-# Style/StringLiteralsInInterpolation:
-#   Enabled: true
-#   EnforcedStyle: double_quotes
-
-Metrics/AbcSize:
-  Exclude:
-    - 'lib/tcat/query.rb'
-
-Metrics/MethodLength:
-  Exclude:
-    - 'lib/tcat/query.rb'
-
-Layout/LineLength:
-  Exclude:
-    - 'lib/tcat/query.rb'
-    - tcat.gemspec

data/.tool-versions

@@ -1 +0,0 @@
-ruby 3.3.8

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-
-require 'rubocop/rake_task'
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]