Steadfast Courier SDK

Node.js SDK for Steadfast Courier API - Bangladesh's courier service.

Installation

``bash
npm install steadfast-courier
`

Quick Start

`typescript
import { SteadFast } from 'steadfast-courier';

const client = new SteadFast({
apiKey: 'your-api-key',
secretKey: 'your-secret-key',
});

const order = await client.createOrder({
invoice: 'INV-001',
recipient_name: 'John Doe',
recipient_phone: '01712345678',
recipient_address: 'Dhaka, Bangladesh',
cod_amount: 500,
});
`

API Reference

$3

`typescript
new SteadFast(config: SteadFastConfig)
`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| apiKey | string | Yes | Your Steadfast API key |
| secretKey | string | Yes | Your Steadfast secret key |
| baseUrl | string | No | Custom API base URL (default: https://portal.packzy.com/api/v1) |

---

$3

#### createOrder(order: OrderData): Promise

Create a single delivery order.

`typescript
const response = await client.createOrder({
invoice: 'INV-001',
recipient_name: 'John Doe',
recipient_phone: '01712345678',
recipient_address: 'House 1, Road 1, Dhanmondi, Dhaka',
cod_amount: 1500,
// Optional fields
alternative_phone: '01812345678',
recipient_email: 'john@example.com',
note: 'Call before delivery',
item_description: '2x T-Shirt',
delivery_type: 0, // 0 = Home Delivery, 1 = Point Delivery
});

console.log(response.consignment?.tracking_code);
`

OrderData Fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| invoice | string | Yes | Your unique invoice/order ID |
| recipient_name | string | Yes | Customer name |
| recipient_phone | string | Yes | Customer phone (11 digits) |
| recipient_address | string | Yes | Full delivery address |
| cod_amount | number | Yes | Cash on delivery amount |
| alternative_phone | string | No | Alternative contact number |
| recipient_email | string | No | Customer email |
| note | string | No | Delivery instructions |
| item_description | string | No | Package contents description |
| deliver_within | string | No | Expected delivery timeframe |
| total_lot | number | No | Number of packages |
| delivery_type | 0 \| 1 | No | 0 = Home, 1 = Point delivery |

---

#### createBulkOrders(orders: OrderData[]): Promise

Create multiple orders at once (max 500 per request).

`typescript
const orders = [
{
invoice: 'INV-001',
recipient_name: 'John Doe',
recipient_phone: '01712345678',
recipient_address: 'Dhaka',
cod_amount: 500,
},
{
invoice: 'INV-002',
recipient_name: 'Jane Doe',
recipient_phone: '01812345678',
recipient_address: 'Chittagong',
cod_amount: 750,
},
];

const responses = await client.createBulkOrders(orders);

responses.forEach((res) => {
if (res.status === 'success') {
console.log(${res.invoice}: ${res.tracking_code});
} else {
console.log(${res.invoice} failed: ${res.message});
}
});
`

---

$3

#### getStatusByConsignmentId(id: number): Promise

`typescript
const status = await client.getStatusByConsignmentId(123456);
console.log(status.delivery_status);
`

#### getStatusByInvoice(invoice: string): Promise

`typescript
const status = await client.getStatusByInvoice('INV-001');
console.log(status.delivery_status);
`

#### getStatusByTrackingCode(code: string): Promise

`typescript
const status = await client.getStatusByTrackingCode('SF123456789');
console.log(status.delivery_status);
`

#### getTrackingUrl(trackingCode: string): string

Get the public tracking URL for a shipment.

`typescript
const url = client.getTrackingUrl('SF123456789');
console.log(url); // https://steadfast.com.bd/t/SF123456789
`

---

Delivery Status Values:

| Status | Description |
|--------|-------------|
| pending | Order received, not yet picked up |
| in_review | Under review |
| hold | On hold |
| cancelled | Cancelled |
| delivered | Successfully delivered |
| partial_delivered | Partially delivered |
| unknown | Unknown status |

---

$3

#### getBalance(): Promise

Get current account balance.

`typescript
const balance = await client.getBalance();
console.log(Balance: ${balance.current_balance} BDT);
`

---

$3

#### getPayments(): Promise

Get all payment records.

`typescript
const payments = await client.getPayments();
payments.forEach((p) => {
console.log(Payment #${p.id}: ${p.amount} BDT (${p.status}));
});
`

#### getPayment(id: number): Promise

Get payment details with associated consignments.

`typescript
const payment = await client.getPayment(123);
console.log(Amount: ${payment.amount} BDT);
console.log(Method: ${payment.method});
payment.consignments?.forEach((c) => {
console.log(- ${c.invoice}: ${c.cod_amount} BDT);
});
`

---

$3

#### getPoliceStations(): Promise

Get list of police stations for address reference.

`typescript
const stations = await client.getPoliceStations();
stations.forEach((s) => {
console.log(${s.name} - ${s.district}, ${s.division});
});
`

---

$3

#### fraudCheck(phone: string): Promise

Check customer's delivery history and reliability score.

`typescript
const check = await client.fraudCheck('01712345678');

console.log(Total Orders: ${check.total_parcels});
console.log(Delivered: ${check.total_delivered});
console.log(Cancelled: ${check.total_cancelled});
console.log(Success Rate: ${check.success_ratio}%);
console.log(Fraud Reports: ${check.total_fraud_reports.length});
`

---

$3

#### createReturnRequest(data: ReturnRequestData): Promise

Create a return request. Must provide at least one identifier.

`typescript
const returnReq = await client.createReturnRequest({
consignment_id: 123456,
// OR invoice: 'INV-001',
// OR tracking_code: 'SF123456789',
reason: 'Customer refused delivery',
status: 'pending',
});
`

Status Values: pending | approved | processing | completed | cancelled

#### getReturnRequest(id: number): Promise

`typescript
const returnReq = await client.getReturnRequest(123);
console.log(returnReq.status);
`

#### getAllReturnRequests(): Promise

`typescript
const returns = await client.getAllReturnRequests();
returns.forEach((r) => console.log(${r.id}: ${r.status}));
`

---

$3

Steadfast sends webhook notifications for order status updates.

#### SteadFast.parseWebhook(body: unknown): WebhookPayload | null

Parse and validate incoming webhook payload.

`typescript
import { SteadFast } from 'steadfast-courier';

// Express.js example
app.post('/webhook/steadfast', (req, res) => {
const payload = SteadFast.parseWebhook(req.body);

if (!payload) {
return res.status(400).send('Invalid payload');
}

console.log(Order ${payload.invoice} is now ${payload.status});

// Handle status updates
switch (payload.status_type) {
case 'delivered':
// Mark order as delivered
break;
case 'cancelled':
// Handle cancellation
break;
}

res.sendStatus(200);
});
`

WebhookPayload Fields:

| Field | Type | Description |
|-------|------|-------------|
| consignment_id | number | Steadfast consignment ID |
| tracking_code | string | Tracking code |
| invoice | string | Your invoice ID |
| status | string | Status message |
| status_type | string | Status category (see below) |
| updated_at | string | Update timestamp |
| cod_amount | number | COD amount (optional) |
| delivery_fee | number | Delivery fee (optional) |
| note | string | Notes (optional) |

Status Types:

| Type | Description |
|------|-------------|
| pending | Order is pending |
| delivered_approval_pending | Delivered, awaiting approval |
| partial_delivered_approval_pending | Partially delivered, awaiting approval |
| cancelled_approval_pending | Cancelled, awaiting approval |
| delivered | Confirmed delivered |
| partial_delivered | Confirmed partial delivery |
| cancelled | Confirmed cancelled |
| hold | On hold |
| in_review | Under review |
| unknown | Unknown status |

---

Error Handling

All methods throw SteadFastError on failure.

`typescript
import { SteadFast, SteadFastError } from 'steadfast-courier';

try {
await client.createOrder(orderData);
} catch (error) {
if (error instanceof SteadFastError) {
console.error(Error: ${error.message});
console.error(Status Code: ${error.statusCode});
console.error(Response:, error.response);
}
}
`

---

Validation Utilities

Validate inputs before making API calls.

`typescript
import { validate } from 'steadfast-courier';

// Validate Bangladesh phone number (01XXXXXXXXX)
validate.phone('01712345678'); // true
validate.phone('1234567890'); // false

// Validate invoice
validate.invoice('INV-001'); // true
validate.invoice(''); // false

// Validate COD amount
validate.codAmount(500); // true
validate.codAmount(-10); // false

// Validate entire order - returns array of errors
const errors = validate.order({
invoice: 'INV-001',
recipient_name: 'John',
recipient_phone: '01712345678',
recipient_address: 'Dhaka',
cod_amount: 500,
});

if (errors.length > 0) {
console.log('Validation errors:', errors);
}
`

---

TypeScript

All types are exported:

`typescript
import type {
SteadFastConfig,
OrderData,
OrderResponse,
BulkOrderResponse,
Consignment,
StatusResponse,
BalanceResponse,
FraudCheckResponse,
ReturnRequestData,
ReturnRequest,
Payment,
PaymentConsignment,
PoliceStation,
WebhookPayload,
} from 'steadfast-courier';
``

---

License

MIT