@webdevarif/couriers

A universal courier service integration package with fraud checking capabilities for Steadfast and Pathao courier services.

Features

• 🚚 Steadfast Courier Integration - Complete API integration for Steadfast courier services
• 📦 Pathao Courier Integration - Full support for Pathao courier services
• 🛡️ Fraud Detection - Advanced fraud checking based on delivery history
• 📱 Phone Number Validation - Bangladeshi mobile number validation and sanitization
• 🔧 Configurable - Environment-based configuration management
• 📊 Risk Assessment - Comprehensive risk scoring and recommendations
• 🎯 TypeScript Support - Full TypeScript definitions included

Installation

npm install @webdevarif/couriers
# or
yarn add @webdevarif/couriers
# or
pnpm add @webdevarif/couriers

Environment Variables

Create a .env file with the following variables:

# Steadfast Configuration
STEADFAST_COURIER_BASE_URL=https://portal.steadfast.com.bd
STEADFAST_COURIER_API_KEY=your_api_key
STEADFAST_COURIER_SECRET_KEY=your_secret_key
STEADFAST_COURIER_TRACK_URL=https://track.steadfast.com.bd

# Pathao Configuration
PATHAO_COURIER_BASE_URL=https://api-hermes.pathao.com
PATHAO_COURIER_CLIENT_ID=your_client_id
PATHAO_COURIER_CLIENT_SECRET=your_client_secret
PATHAO_COURIER_USERNAME=your_username
PATHAO_COURIER_PASSWORD=your_password
PATHAO_COURIER_GRANT_TYPE=password

# General Configuration
COURIER_TIMEOUT=30000
COURIER_ENABLE_LOGGING=true

Quick Start

Basic Usage

import { CourierService } from '@webdevarif/couriers';

// Initialize the service
const courierService = new CourierService();

// Create a Steadfast order
const orderData = {
  invoice: 'INV-001',
  recipient_name: 'John Doe',
  recipient_phone: '01712345678',
  recipient_address: '123 Main Street, Dhanmondi',
  recipient_city: 'Dhaka',
  recipient_area: 'Dhanmondi',
  recipient_zone: 'Zone 1',
  delivery_type: '48',
  item_type: 'Electronics',
  item_quantity: 1,
  item_weight: 0.5,
  item_description: 'Smartphone',
  item_price: 25000
};

const result = await courierService.createSteadfastOrder(orderData);
console.log(result);

Fraud Checking

import { FraudCheckService } from '@webdevarif/couriers';

const fraudService = new FraudCheckService();

// Check for fraud
const fraudData = {
  phone: '01712345678',
  name: 'John Doe',
  address: '123 Main Street, Dhanmondi',
  city: 'Dhaka',
  area: 'Dhanmondi',
  zone: 'Zone 1'
};

const fraudResult = await fraudService.checkFraud(fraudData);
console.log(fraudResult.data?.riskLevel); // 'LOW', 'MEDIUM', 'HIGH', or 'CRITICAL'

Individual Services

import { SteadfastService, PathaoService } from '@webdevarif/couriers';

// Steadfast only
const steadfastService = new SteadfastService({
  baseUrl: 'https://portal.steadfast.com.bd',
  apiKey: 'your_api_key',
  secretKey: 'your_secret_key',
  timeout: 30000,
  enableLogging: true
});

// Pathao only
const pathaoService = new PathaoService({
  baseUrl: 'https://api-hermes.pathao.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  username: 'your_username',
  password: 'your_password',
  grantType: 'password',
  timeout: 30000,
  enableLogging: true
});

API Reference

CourierService

Main service class that provides access to all courier functionality.

Methods

• createSteadfastOrder(orderData) - Create a Steadfast order
• trackSteadfastOrder(consignmentId) - Track a Steadfast order
• checkSteadfastBalance() - Check Steadfast account balance
• createPathaoOrder(orderData) - Create a Pathao order
• trackPathaoOrder(consignmentId) - Track a Pathao order
• checkFraud(data) - Perform fraud check
• addDeliveryHistory(phone, isSuccessful, orderValue) - Update delivery history

FraudCheckService

Advanced fraud detection based on delivery history and patterns.

Methods

• checkFraud(data) - Analyze fraud risk
• addDeliveryHistory(history) - Add delivery history
• updateDeliveryHistory(phone, isSuccessful, orderValue) - Update history
• getDeliveryHistory(phone) - Get customer history
• getAllDeliveryHistory() - Get all history data

Risk Assessment

The fraud check system analyzes:

• Phone Number Validation - Format and validity checks
• Delivery History - Success and cancellation rates
• Order Patterns - Frequency and timing analysis
• Address Completeness - Location detail validation
• Risk Scoring - 0-100 scale with recommendations

Risk Levels

• LOW (0-24): Safe to process
• MEDIUM (25-49): Monitor closely
• HIGH (50-69): Require verification
• CRITICAL (70+): Block order

Error Handling

All methods return a ServiceResponse object:

interface ServiceResponse<T = any> {
  success: boolean;
  data?: T;
  error?: string;
  message?: string;
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, email [email protected] or create an issue on GitHub.