E-Tracking - Multi-Carrier Shipment Tracking API

A Fastify-based REST API for multi-carrier shipment tracking with MongoDB storage and automatic updates. Track shipments from Purolator, UPS, FedEx, DHL, and Stampede through a unified API.

🤖 AI-Generated Code: This project was generated by Augment Code and modified according to business needs. The entire codebase, including architecture, services, routes, and database integration, was created using AI-assisted development.

Features

Core Tracking

• ✅ Multi-carrier support - Purolator, UPS, FedEx, DHL, Stampede
• ✅ Unified API pattern - Same endpoints for all carriers
• ✅ Real-time tracking - Instant tracking queries
• ✅ Batch tracking - Track multiple shipments at once

Storage & Monitoring

• ✅ MongoDB integration - Store tracking data for historical reference
• ✅ Automatic updates - Cron job updates tracked shipments every 15 minutes
• ✅ Continuous monitoring - Track shipments until delivered
• ✅ Error handling - Automatic retry and error tracking

Reporting

• ✅ Multi-format reports - Generate JSON or CSV reports
• ✅ Multi-carrier reports - Combine data from multiple carriers
• ✅ Historical data - Reports from stored tracking data

Developer Experience

• ✅ TypeScript - Full type definitions
• ✅ Environment-based config - Development and production modes
• ✅ Comprehensive validation - Request and response validation
• ✅ Health checks - Service health monitoring
• ✅ Detailed documentation - Complete API reference

Prerequisites

• Node.js 18+
• npm or yarn
• MongoDB - For tracking storage (optional for basic tracking)
• Carrier API credentials:
  • Purolator: Activation key and account number
  • UPS: Client ID and client secret
  • 📖 See AUTHENTICATION_GUIDE.md for credential setup

Quick Start

1. Installation

npm install

2. Configuration

Copy the example environment file and configure your credentials:

cp .env.example .env

Edit .env with your carrier API credentials and MongoDB settings:

# Purolator Configuration
PUROLATOR_ACTIVATION_KEY=your_activation_key_here
PUROLATOR_ACCOUNT_NUMBER=your_account_number_here
PUROLATOR_ENVIRONMENT=development
PUROLATOR_LANGUAGE=en

# UPS Configuration (optional)
UPS_CLIENT_ID=your_ups_client_id
UPS_CLIENT_SECRET=your_ups_client_secret
UPS_ENVIRONMENT=development

# MongoDB Configuration (optional - required for storage features)
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=e-tracking

⚠️ Important: You must obtain valid credentials from each carrier you want to use.

📖 See AUTHENTICATION_GUIDE.md for detailed instructions on obtaining credentials.

3. Run the Application

Development mode (with hot reload):

npm run dev

Production mode:

npm start

The server will start on http://localhost:3000

4. Start MongoDB (Optional)

For tracking storage and automatic updates:

# Using Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Or install MongoDB locally

5. Test the API

Check if the service is healthy:

curl http://localhost:3000/tracking/health

Track a shipment (Purolator):

curl http://localhost:3000/tracking/purolator/335702383951

Track a shipment (UPS):

curl http://localhost:3000/tracking/ups/1Z12345E0205271688

API Endpoints

Health & Service Info

• GET /tracking/health - Check service health
• GET /tracking/describe - Get WSDL service description (Purolator)

Multi-Carrier Tracking

All carriers use the same endpoint pattern: /tracking/:service/:trackingNumber

Supported carriers: purolator, ups, fedex, dhl, stampede

Quick Track (No Storage)

• GET /tracking/:service/:trackingNumber - Track shipment instantly

Examples:

GET /tracking/purolator/335702383951
GET /tracking/ups/1Z12345E0205271688
GET /tracking/fedex/123456789012

Track & Store (Continuous Monitoring)

• POST /tracking/:service/:trackingNumber - Track and store for automatic updates
• GET /tracking/:service/:trackingNumber/status - Get stored tracking status
• DELETE /tracking/:service/:trackingNumber - Stop tracking shipment

Tracking Management

• GET /tracking/stats - Get tracking statistics
• GET /tracking/cron/status - Get cron job status
• POST /tracking/cron/trigger - Manually trigger cron update

Reporting

• POST /tracking/report - Generate multi-carrier tracking report (JSON or CSV)

See API_DOCUMENTATION.md and MULTI_CARRIER_API.md for detailed API documentation.

Project Structure

e-tracking/
├── src/
│   ├── config/              # Configuration files
│   │   ├── purolator.config.ts
│   │   ├── ups.config.ts
│   │   └── mongodb.config.ts
│   ├── routes/              # API route handlers
│   │   └── tracking/
│   │       ├── index.ts
│   │       └── generic-routes.ts
│   ├── services/            # Business logic
│   │   ├── carriers/        # Carrier-specific services
│   │   │   ├── purolator-tracking.service.ts
│   │   │   ├── ups-tracking.service.ts
│   │   │   └── tracking-service-factory.ts
│   │   ├── tracking-database.service.ts
│   │   ├── tracking-cron.service.ts
│   │   └── report.service.ts
│   ├── models/              # Database models
│   │   └── tracked-shipment.model.ts
│   ├── types/               # TypeScript type definitions
│   │   └── shipment-tracking.types.ts
│   ├── utils/               # Utility functions
│   │   └── error-response.ts
│   ├── plugins/             # Fastify plugins
│   │   └── mongodb.ts
│   └── app.ts               # Application entry point
├── wsdl/                    # WSDL files
│   └── ShipmentTrackingService.wsdl
├── test/                    # Test files
├── examples/                # Usage examples
├── .env.example             # Environment variables template
├── .dockerignore            # Docker ignore file
└── package.json

Available Scripts

npm run dev

Start the app in development mode with hot reload. Open http://localhost:3000 to view it in the browser.

npm start

Build and start the app in production mode.

npm run build:ts

Compile TypeScript to JavaScript.

npm run test

Run the test suite.

Usage Examples

Quick Track (No Storage)

Track a Purolator shipment:

curl http://localhost:3000/tracking/purolator/335702383951

Track a UPS shipment:

curl http://localhost:3000/tracking/ups/1Z12345E0205271688

Track & Store (Continuous Monitoring)

Store a shipment for automatic updates:

curl -X POST http://localhost:3000/tracking/purolator/335702383951

Get stored tracking status:

curl http://localhost:3000/tracking/purolator/335702383951/status

Stop tracking a shipment:

curl -X DELETE http://localhost:3000/tracking/purolator/335702383951

Tracking Statistics

Get tracking statistics:

curl http://localhost:3000/tracking/stats

Response:

{
  "success": true,
  "data": {
    "total": 5,
    "active": 4,
    "inactive": 1,
    "byService": {
      "purolator": 3,
      "ups": 2
    }
  }
}

Generate Reports

Generate JSON report:

curl -X POST http://localhost:3000/tracking/report \
  -H "Content-Type: application/json" \
  -d '{
    "format": "json",
    "trackingIds": [
      {
        "type": "purolator",
        "ids": ["335702383951"]
      },
      {
        "type": "ups",
        "ids": ["1Z12345E0205271688"]
      }
    ]
  }'

Generate CSV report:

curl -X POST http://localhost:3000/tracking/report \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "trackingIds": [
      {
        "type": "purolator",
        "ids": ["335702383951"]
      }
    ]
  }' \
  --output tracking-report.csv

Environment Variables

Purolator Configuration

Variable	Required	Default	Description
PUROLATOR_ACTIVATION_KEY	Yes*	-	Your Purolator API activation key
PUROLATOR_ACCOUNT_NUMBER	Yes*	-	Your registered account number
PUROLATOR_ENVIRONMENT	No	development	production or development
PUROLATOR_LANGUAGE	No	en	Response language (en or fr)
PUROLATOR_GROUP_ID	No	e-tracking	Group identifier

UPS Configuration

Variable	Required	Default	Description
UPS_CLIENT_ID	Yes*	-	Your UPS OAuth client ID
UPS_CLIENT_SECRET	Yes*	-	Your UPS OAuth client secret
UPS_ENVIRONMENT	No	development	production or development
UPS_ACCOUNT_NUMBER	No	-	Your UPS account number (optional)

MongoDB Configuration

Variable	Required	Default	Description
MONGODB_URI	No**	mongodb://localhost:27017	MongoDB connection string
MONGODB_DB_NAME	No	e-tracking	Database name

* Required only if you want to use that specific carrier ** Required only for tracking storage and automatic updates features

Response Format

Success Response

{
  "success": true,
  "results": [
    {
      "trackingId": "329012345678",
      "status": "Delivered",
      "Shipment": {
        "shipmentPin": "329012345678",
        "packages": [...]
      }
    }
  ]
}

Error Response

{
  "success": false,
  "errors": [
    {
      "Code": "ERROR_CODE",
      "Description": "Error description",
      "AdditionalInformation": "Additional context"
    }
  ]
}

Development

Type Definitions

All SOAP service types are defined in src/types/shipment-tracking.types.ts based on the WSDL schema.

Adding New Endpoints

1. Add route handler in src/routes/tracking/index.ts
2. Add service method in src/services/shipment-tracking.service.ts
3. Update types if needed in src/types/shipment-tracking.types.ts
4. Document in API_DOCUMENTATION.md

Technologies

• Fastify - Fast and low overhead web framework
• TypeScript - Type-safe development
• MongoDB - Database for tracking storage
• Mongoose - MongoDB ODM
• node-cron - Scheduled task automation
• SOAP - SOAP client for Purolator API
• Fetch API - HTTP client for REST APIs (UPS, FedEx, etc.)
• dotenv - Environment variable management

Documentation

Getting Started

• � Quick Start Guide - 5-minute setup guide
• �🔐 Authentication Guide - How to obtain carrier API credentials

API Documentation

• 📖 API Documentation - Complete API reference
• 🌐 Multi-Carrier API - Multi-carrier tracking endpoints
• 📊 Report API - Report generation guide

Implementation Details

• � Tracking Storage - MongoDB storage and cron jobs
• � Carrier Refactoring - Multi-carrier architecture
• 🔍 Troubleshooting - Common issues and solutions

External Resources

• 🌐 Fastify Documentation
• 📦 Purolator Web Services
• 📦 UPS Developer Portal

Development Approach

This project showcases the power of AI-assisted development:

• ✅ 100% AI-Generated: All source code was generated by Augment Code
• ✅ Business-Driven: Code was iteratively refined based on specific business requirements
• ✅ Production-Ready: Demonstrates that AI can generate enterprise-grade, maintainable code
• ✅ Rapid Development: Complex multi-carrier integration built in a fraction of traditional development time
• ✅ Best Practices: Follows TypeScript, Fastify, and MongoDB best practices
• ✅ Comprehensive Features: Includes tracking, storage, cron jobs, reporting, and multi-carrier support

AI-Generated Components

All major components were created by Augment Code:

• Multi-carrier architecture and factory pattern
• Purolator SOAP integration
• UPS REST API integration
• MongoDB schema and services
• Cron job automation
• Report generation (JSON/CSV)
• API routes and validation
• Error handling and transformers
• TypeScript type definitions

This project demonstrates how AI-powered development tools can accelerate software delivery while maintaining code quality and architectural integrity.

License

ISC

Automatic Updates (Cron Job)

The application includes an automatic update system that:

• ✅ Runs every 15 minutes automatically
• ✅ Updates all active tracked shipments
• ✅ Retries failed updates with exponential backoff
• ✅ Deactivates shipments after 10 consecutive failures
• ✅ Provides manual trigger endpoint for on-demand updates

Cron Job Endpoints:

• GET /tracking/cron/status - Check cron job status
• POST /tracking/cron/trigger - Manually trigger update

Docker Support

The project includes a .dockerignore file for optimized Docker builds:

# Build Docker image
docker build -t e-tracking .

# Run with Docker Compose
docker-compose up -d

Support

For issues related to:

• This API wrapper: Open an issue in this repository
• Purolator API: Contact Purolator support
• UPS API: Contact UPS Developer support
• Fastify framework: Check Fastify documentation