quickRateLTL

Query multiple freight carriers and get consolidated rates in one API call.

Supports: XPO Logistics • TForce Freight • GLI Freight (20+ carriers)

Quick Start

1. Clone and install:

   git clone https://github.com/yourusername/quickRateLTL.git
   cd quickRateLTL
   npm install

2. Configure credentials:

   cp .env.example .env
   # Edit .env and add your API credentials (see instructions below)

3. Start development server:

   npm run dev

4. Test the API:

   curl -X POST http://localhost:3000/api/aggregate \
     -H "Content-Type: application/json" \
     -d '{
       "origin": {"city": "Portland", "state": "OR", "zip": "97201"},
       "destination": {"city": "Phoenix", "state": "AZ", "zip": "85001"},
       "shipDate": "2025-01-15",
       "freightClass": "85",
       "weights": {"numUnits": 1, "unitWeight": 500, "numPieces": 1}
     }'

5. Deploy to Vercel:

   • Push to GitHub
   • Import in Vercel
   • Add environment variables
   • Done!

Configuration

Required API Credentials

See .env.example for all configuration options.

XPO Logistics (OAuth2):

• XPO_BASE_URL - API endpoint
• XPO_CLIENT_BASIC - Base64-encoded credentials OR XPO_USERNAME + XPO_PASSWORD
• XPO_ACCOUNT_INST_ID - Your account ID
• Contact: LTLWebAPISupport@xpo.com

TForce Freight (Azure AD):

• TFORCE_CLIENT_ID - Azure AD app ID
• TFORCE_CLIENT_SECRET - Azure AD secret
• TFORCE_TOKEN_ENDPOINT - Azure tenant endpoint
• TFORCE_SCOPE - API scope
• Contact: TForce Freight support

GLI Freight (API Key):

• GLI_API_KEY - Your API key
• KV_* variables - Vercel KV/Redis for caching
• Contact: GLI support

Optional:

• DISCORD_WEBHOOK_URL - For error alerts (optional)

Setup Instructions

See detailed docs in ENVIRONMENT_VARIABLES.md for:

• How to obtain each credential
• Step-by-step configuration
• Security best practices

API Endpoints

Method	Endpoint	Purpose
POST	/api/aggregate	Get rates from all carriers
POST	/api/providers/xpo	XPO only
POST	/api/providers/tforce	TForce only
POST	/api/providers/gli	GLI only
GET	/api/health/providers	Check provider status
GET	/api/health/circuits	View circuit breaker status

Request body (shipment details):

{
  "origin": {"city": "Portland", "state": "OR", "zip": "97201"},
  "destination": {"city": "Phoenix", "state": "AZ", "zip": "85001"},
  "shipDate": "2025-01-15",
  "freightClass": "85",
  "weights": {"numUnits": 1, "unitWeight": 500, "numPieces": 1},
  "dimensions": {"length": 48, "width": 40, "height": 48},
  "accessorials": {"pickup": ["RESP"], "delivery": ["RESD"]},
  "providers": ["gli", "xpo", "tforce"]
}

See .ai/core/api-endpoints.md for complete API documentation.

Documentation

• Configuration: See ENVIRONMENT_VARIABLES.md
• Architecture & Design: See .ai/core/architecture.md (in repo)
• API Reference: See .ai/core/api-endpoints.md (in repo)
• Implementation Patterns: See .ai/patterns/README.md (in repo)
• Development Workflows: See .ai/workflows/README.md (in repo)

Development

npm run dev       # Start development server
npm run build     # Build for production
npm start         # Run production server
npm run lint      # Check code style
npm run typecheck # Check TypeScript types

Deployment

Vercel (Recommended)

1. Push code to GitHub
2. Go to https://vercel.com/new
3. Import your repository
4. Add environment variables (see .env.example)
5. Deploy!

Your app will be live at https://your-project.vercel.app

Health Check

curl https://your-project.vercel.app/api/health/providers

Should return provider status (healthy, degraded, or unhealthy).

Security

• All credentials stored in environment variables (never committed)
• OAuth2 tokens cached securely in memory with expiration
• Request timeouts protect against hanging requests
• Circuit breaker prevents cascading failures
• Structured logging with request IDs for debugging

Never commit: .env, .env.local, or any files with real credentials

License

MIT

---

Need help? Check the docs in .ai/ folder for detailed guides on configuration, API usage, and troubleshooting.