Steadfast Courier SDK

A robust Node.js library for Steadfast Courier API. Zero dependencies, enterprise-ready with retry logic and comprehensive error handling.

📦 Installation

npm install steadfast-courier-sdk

🚀 Quick Start

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

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:

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);
  }
}

TypeScript Interface Definitions

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

// 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:

try {
  await courier.checkStatusByCID('invalid');
} catch (error) {
  console.log(error.message);
  // "Failed to check status by CID: Not Found: Invalid consignment/invoice/tracking code"
}

📄 License

MIT © Sadman Sakib

🤝 Contributing

Issues and pull requests are welcome!