A robust Node.js library for checking delivery status using Steadfast Courier API. Zero dependencies, enterprise-ready with retry logic and comprehensive error handling.
npm install steadfast-courier-sdkbash
npm install steadfast-courier-sdk
`
🚀 Quick Start
`javascript
import SteadfastCourier from 'steadfast-courier-sdk';
const courier = new SteadfastCourier('your-api-key', 'your-secret-key');
// Check delivery status
const status = await courier.checkStatusByCID('172005780');
console.log(status.delivery_status); // 'delivered', 'pending', etc.
`
📚 API Methods
| Method | Description | Example |
|--------|-------------|---------|
| checkStatusByCID(id) | Check by Consignment ID | await courier.checkStatusByCID('172005780') |
| checkStatusByInvoice(invoice) | Check by Invoice | await courier.checkStatusByInvoice('MC30-XL') |
| checkStatusByTrackingCode(code) | Check by Tracking Code | await courier.checkStatusByTrackingCode('SFR250909STC15E542BD') |
| checkBalance() | Check account balance | await courier.checkBalance() |
🔧 Full Example
`javascript
import SteadfastCourier from 'steadfast-courier-sdk';
const courier = new SteadfastCourier('your-api-key', 'your-secret-key');
try {
// Check multiple consignments
const ids = ['172005780', '172007475'];
for (const id of ids) {
const status = await courier.checkStatusByCID(id);
console.log(${id}: ${status.delivery_status});
}
// Check balance
const balance = await courier.checkBalance();
console.log(Balance: ${balance.current_balance} BDT);
} catch (error) {
console.error('Error:', error.message);
}
`
🔷 TypeScript Usage
Full TypeScript support with type definitions included:
`typescript
import SteadfastCourier, { DeliveryStatusResponse, BalanceResponse } from 'steadfast-courier-sdk';
const courier = new SteadfastCourier('your-api-key', 'your-secret-key');
// TypeScript automatically infers return types
const status: DeliveryStatusResponse = await courier.checkStatusByCID('172005780');
const balance: BalanceResponse = await courier.checkBalance();
// Type-safe error handling
try {
const result = await courier.checkStatusByInvoice('MC30-XL');
console.log(result.delivery_status); // TypeScript knows this property exists
} catch (error: unknown) {
if (error instanceof Error) {
console.error('API Error:', error.message);
}
}
`
$3
`typescript
interface DeliveryStatusResponse {
status: number;
delivery_status: string;
}
interface BalanceResponse {
status: number;
current_balance: number;
}
`
✨ Features
- 🚀 Zero dependencies - Only native Node.js modules
- 🔄 Auto-retry with exponential backoff
- 🛡️ Input validation and type conversion
- ⏱️ Timeout protection (30s)
- 🎯 Smart error handling with specific messages
- 📖 Full TypeScript support
- 🏢 Enterprise-ready
📋 Response Format
`javascript
// Status response
{
"status": 200,
"delivery_status": "delivered" // or "pending", "in_review", etc.
}
// Balance response
{
"status": 200,
"current_balance": 33551
}
`
📦 Delivery Status Values
| Status | Description |
|--------|-------------|
| pending | Consignment is not delivered or cancelled yet |
| delivered_approval_pending | Consignment is delivered but waiting for admin approval |
| partial_delivered_approval_pending | Consignment is delivered partially and waiting for admin approval |
| cancelled_approval_pending | Consignment is cancelled and waiting for admin approval |
| unknown_approval_pending | Unknown Pending status. Need contact with the support team |
| delivered | Consignment is delivered and balance added |
| partial_delivered | Consignment is partially delivered and balance added |
| cancelled | Consignment is cancelled and balance updated |
| hold | Consignment is held |
| in_review | Order is placed and waiting to be reviewed |
| unknown | Unknown status. Need contact with the support team |
🚨 Error Handling
The SDK throws descriptive errors for different scenarios:
`javascript
try {
await courier.checkStatusByCID('invalid');
} catch (error) {
console.log(error.message);
// "Failed to check status by CID: Not Found: Invalid consignment/invoice/tracking code"
}
``