Metadata-Version: 2.4
Name: bangladeshi-parcel-tracker
Version: 1.2.0
Summary: A Python package for tracking parcels from Bangladeshi courier services
Home-page: https://github.com/mdminhazulhaque/bangladeshi-parcel-tracker
Author: Minhaz
Author-email: your.email@example.com
Project-URL: Bug Reports, https://github.com/mdminhazulhaque/bangladeshi-parcel-tracker/issues
Project-URL: Source, https://github.com/mdminhazulhaque/bangladeshi-parcel-tracker
Keywords: bangladesh parcel tracking courier redx steadfast pathao rokomari
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: click>=8.0.0
Requires-Dist: tabulate>=0.8.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Bangladeshi Parcel Tracker

A Python package for tracking parcels from various Bangladeshi courier services including Redx, Steadfast, Pathao, and Rokomari.

[![PyPI version](https://badge.fury.io/py/bangladeshi-parcel-tracker.svg)](https://badge.fury.io/py/bangladeshi-parcel-tracker)
[![Python versions](https://img.shields.io/pypi/pyversions/bangladeshi-parcel-tracker.svg)](https://pypi.org/project/bangladeshi-parcel-tracker/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🚚 Support for major Bangladeshi courier services
- 📦 Unified tracking interface across all providers
- ⏱️ Detailed timeline of parcel journey
- 🎯 Easy-to-use delivery status checking
- 🔄 Real-time tracking with live API integration
- 📊 Comprehensive tracking event data
- 🐍 Python 3.8+ support
- 🛠️ Command-line interface included

## Supported Courier Services

- **Redx** - Leading courier service in Bangladesh
- **Steadfast** - Reliable delivery solutions
- **Pathao** - Fast and efficient courier service  
- **Rokomari** - Book and product delivery specialist

## Installation

The package is available on PyPI. Install it using pip:

```bash
pip install bangladeshi-parcel-tracker
```

For development installation:

```bash
git clone https://github.com/yourusername/bangladeshi-parcel-tracker.git
cd bangladeshi-parcel-tracker
pip install -e .
```

## Quick Start

### Basic Usage

```python
from bangladeshi_parcel_tracker import RedxTracker, SteadfastTracker

# Track a Redx parcel
tracker = RedxTracker("RDX123456789")
events = tracker.track()

# Check if delivered
if tracker.is_delivered():
    print("Package has been delivered!")
else:
    print(f"Current status: {tracker.get_current_status().value}")

# Print timeline
for event in events:
    print(event)
```

### Using Different Providers

```python
from bangladeshi_parcel_tracker import (
    RedxTracker, SteadfastTracker, 
    PathaoTracker, RokomariTracker
)

tracking_number = "YOUR_TRACKING_NUMBER"

# For Pathao and Rokomari, you may need phone number
phone_number = "01700000000"  # Required for some providers

# Choose your provider
trackers = {
    'redx': RedxTracker(tracking_number),
    'steadfast': SteadfastTracker(tracking_number),
    'pathao': PathaoTracker(tracking_number, phone=phone_number),
    'rokomari': RokomariTracker(tracking_number, phone=phone_number)
}

for name, tracker in trackers.items():
    try:
        events = tracker.track()
        print(f"\\n{tracker.provider_name} Tracking:")
        print(f"Status: {tracker.get_current_status().value}")
        print(f"Delivered: {tracker.is_delivered()}")
        print(f"Last Update: {tracker.get_last_update()}")
        
        for event in events:
            print(f"  {event}")
            
    except Exception as e:
        print(f"Error tracking with {name}: {e}")
```

## Command Line Interface

The package includes a powerful CLI for tracking parcels from the terminal:

### Installation & Usage

After installing the package from pip, you can use the `bangladeshi-parcel-tracker` command:

```bash
# Basic usage
bangladeshi-parcel-tracker <provider> <tracking_number>

# Show help
bangladeshi-parcel-tracker --help

# Show version
bangladeshi-parcel-tracker --version
```

### CLI Examples

```bash
# Track with Redx (detailed timeline)
bangladeshi-parcel-tracker redx RDX123456789

# Track with Steadfast (status only)
bangladeshi-parcel-tracker steadfast SF987654321 --status-only

# Track with Pathao (JSON output) - requires phone number
bangladeshi-parcel-tracker pathao PA456789123 --phone 01700000000 --json

# Track with Rokomari (detailed timeline) - requires phone number
bangladeshi-parcel-tracker rokomari RK789123456 --phone 01700000000 --detailed
```

### CLI Options

- `--status-only`, `-s`: Show only the current delivery status
- `--detailed`, `-d`: Show detailed timeline with all events (default)
- `--json`, `-j`: Output results in JSON format
- `--phone`, `-p`: Phone number (required for Pathao and Rokomari)
- `--version`, `-v`: Show version information
- `--help`, `-h`: Show help message

### CLI Output Examples

**Status Only Output:**
```
📊 Tracking Status for RDX123456789
==================================================
Provider: Redx
Status: 🚛 Out For Delivery
Delivered: ❌ No
Last Update: 2025-01-15 15:45:00
```

**Detailed Timeline:**
```
📦 Detailed Tracking for SF987654321
============================================================
Provider: Steadfast
Current Status: ✅ Delivered
Delivered: ✅ Yes
Total Events: 4

📅 Timeline:
------------------------------------------------------------
 1. ⏳ [2025-01-15 08:00:00] Pending
    📍 Location: Steadfast Hub
    📝 Order received and processing

 2. 📦 [2025-01-15 10:30:00] Picked Up
    📍 Location: Pickup Point
    📝 Package collected from merchant

 3. 🚚 [2025-01-15 14:15:00] In Transit
    📍 Location: Transit Hub
    📝 Package in transit to destination

 4. ✅ [2025-01-15 16:00:00] Delivered
    📍 Location: Customer Address
    📝 Package delivered successfully
```

**JSON Output:**
```json
{
  "tracking_number": "PA456789123",
  "provider": "Pathao",
  "current_status": "in_transit",
  "is_delivered": false,
  "last_update": "2025-01-15T13:20:00",
  "total_events": 3,
  "events": [
    {
      "timestamp": "2025-01-15T09:15:00",
      "status": "pending",
      "location": "Pathao Warehouse",
      "description": "Parcel received at warehouse",
      "details": null
    }
  ]
}
```

## API Reference

### BaseTracker

All provider classes inherit from `BaseTracker` and implement these methods:

#### Properties
- `provider_name: str` - Name of the courier service
- `tracking_number: str` - The tracking/consignment number

#### Methods
- `track() -> List[TrackingEvent]` - Fetch tracking events
- `is_delivered() -> bool` - Check if parcel is delivered
- `get_current_status() -> TrackingStatus` - Get current tracking status
- `get_last_update() -> Optional[datetime]` - Get timestamp of last update
- `refresh() -> List[TrackingEvent]` - Force refresh tracking data

### TrackingEvent

Represents a single tracking event:

```python
@dataclass
class TrackingEvent:
    timestamp: datetime
    status: TrackingStatus
    location: Optional[str] = None
    description: Optional[str] = None
    details: Optional[str] = None
```

### TrackingStatus

Enumeration of possible tracking statuses:

- `PENDING` - Order received/processing
- `PICKED_UP` - Package picked up
- `IN_TRANSIT` - Package in transit
- `OUT_FOR_DELIVERY` - Out for delivery
- `DELIVERED` - Successfully delivered
- `RETURNED` - Returned to sender
- `CANCELLED` - Order cancelled
- `FAILED_DELIVERY` - Delivery attempt failed
- `UNKNOWN` - Status unknown

## Error Handling

The package provides a custom `TrackingError` exception:

```python
from bangladeshi_parcel_tracker import TrackingError

try:
    tracker = RedxTracker("INVALID123")
    events = tracker.track()
except TrackingError as e:
    print(f"Tracking failed: {e}")
    print(f"Provider: {e.provider}")
    print(f"Tracking Number: {e.tracking_number}")
```

## Development

### Setting up Development Environment

```bash
# Clone the repository
git clone https://github.com/yourusername/bangladeshi-parcel-tracker.git
cd bangladeshi-parcel-tracker

# Install in development mode
pip install -e .

# Format code
black src/
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

### Guidelines

1. Follow the existing code style (Black formatting)
2. Update documentation as needed
3. Ensure your changes work with the existing API structure

### Provider Implementation

To add a new courier service provider:

1. Create a new file in `src/bangladeshi_parcel_tracker/providers/`
2. Inherit from `BaseTracker`
3. Implement the `track()` method
4. Add provider to `__init__.py`

Example:

```python
from ..base import BaseTracker, TrackingEvent, TrackingStatus

class NewProviderTracker(BaseTracker):
    @property
    def provider_name(self) -> str:
        return "New Provider"
    
    def track(self) -> List[TrackingEvent]:
        # Implementation here
        pass
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Available on PyPI as `bangladeshi-parcel-tracker`
- Thanks to all Bangladeshi courier services for their tracking systems
- Built with ❤️ for the Bangladeshi developer community

## Disclaimer

This package is not officially affiliated with any of the courier services. It's an independent tool created to help developers integrate parcel tracking functionality into their applications.

The package uses publicly available tracking APIs and websites to fetch parcel information. Please use responsibly and respect the terms of service of each courier provider.
