Tcat

A Ruby gem for tracking T-Cat (Taiwan Pelican Express) shipment status. Provides a simple and easy-to-use API interface.

Features

  • Track shipment status
  • Secure encrypted requests
  • Simple API interface
  • Non-blocking HTTP requests
  • Comprehensive error handling

Installation

Add this line to your application's Gemfile:

gem 'tcat'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install tcat

Configuration

Configure the gem before use:

Tcat.configure do |config|
  config.secret_string = 'your_secret_string'
  config.secret_key = 'your_secret_key'
end

Usage

Basic Usage

# Create a query instance
query = Tcat::Query.new('your_tracking_number')

# Get shipment status
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
# :rescheduled - Delivery time rescheduled
# :forwarding  - Being forwarded
# :investigation - Under investigation
# :rejected    - Delivery rejected
# :returning   - In return process
# :unknown     - Unknown status

# 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

# 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
  • :rescheduled - Delivery time rescheduled
  • :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
  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

Running Tests

$ bundle exec rake spec

Local Installation

$ bundle exec rake install

Contributing

Bug reports and pull requests are welcome.

License

This gem is available as open source under the terms of the MIT License.

Changelog

0.2.1

  • Updated base64 gem dependency to ~> 0.3
  • Code formatting improvements

0.2.0

  • Fixed SSL certificate verification issues with T-Cat API
  • Added session initialization to obtain cookies before queries
  • Added cookie management for maintaining session state
  • Added new status code mappings: :rescheduled (另約時間) and :held (暫置營業所)
  • Removed Rails.logger dependency for better standalone gem compatibility
  • Added base64 gem dependency for Ruby 3.4+ compatibility
  • Updated HTTP headers to match latest BlackCat iOS app (version 3)
  • Improved error handling with better debug output

0.1.9

  • Updated User-Agent and API version

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

  • Refactored HTTP request handling with new HttpClient class
  • Refactored encryption logic with new EncryptionService class
  • Improved error handling
  • Updated documentation