tcat

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

• Fork the project
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -am 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• 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.2

• Fixed status parsing to handle HTML tags in API responses

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