Pathao Courier SDK

A modern, type-safe TypeScript SDK for the Pathao Courier Merchant API with comprehensive webhook support.

Features

✅ Full TypeScript Support - Complete type definitions for all API endpoints
✅ OAuth 2.0 Authentication - Automatic token management and refresh
✅ Webhook Handling - Built-in webhook handlers for Express, Fastify, and generic frameworks
✅ Input Validation - Automatic validation of request parameters
✅ Error Handling - Custom error classes with detailed error messages
✅ Framework Agnostic - Works with any Node.js framework
✅ Tree-shakeable - Optimized for bundle size
✅ Well Documented - Comprehensive documentation and examples

Installation

# npm
npm install pathao-courier

# yarn
yarn add pathao-courier

# pnpm
pnpm add pathao-courier

⚠️ TypeScript Configuration Required

If you're using TypeScript and importing from 'pathao-courier/webhooks', you must update your tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node16" // or "nodenext" or "bundler"
  }
}

Without this, you'll get: Cannot find module 'pathao-courier/webhooks'

See TypeScript Support section for more details.

Quick Start

Basic Usage

import { PathaoClient } from 'pathao-courier';

// Initialize the client
const client = new PathaoClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  username: 'your-email@example.com',
  password: 'your-password',
  environment: 'sandbox', // or 'production'
});

// Create a store
const store = await client.stores.create({
  name: 'My Store',
  contact_name: 'John Doe',
  contact_number: '01712345678',
  address: 'House 123, Road 4, Sector 10, Uttara, Dhaka-1230, Bangladesh',
  city_id: 1,
  zone_id: 298,
  area_id: 37,
});

// Create an order
const order = await client.orders.create({
  store_id: 123456,
  merchant_order_id: 'ORD-12345',
  recipient_name: 'Jane Smith',
  recipient_phone: '01787654321',
  recipient_address: 'House 456, Road 8, Dhanmondi, Dhaka-1205, Bangladesh',
  delivery_type: 48, // Normal Delivery
  item_type: 2, // Parcel
  item_quantity: 1,
  item_weight: 0.5,
  amount_to_collect: 1000,
});

console.log(`Order created: ${order.data.consignment_id}`);

// Get order info
const orderInfo = await client.orders.getInfo(order.data.consignment_id);
console.log(`Status: ${orderInfo.data.order_status}`);

// Calculate price
const price = await client.pricing.calculate({
  store_id: 123456,
  item_type: 2,
  delivery_type: 48,
  item_weight: 0.5,
  recipient_city: 1,
  recipient_zone: 298,
});
console.log(`Delivery fee: ${price.data.final_price} BDT`);

API Reference

Complete API Methods Table

Service	Method	Description	Parameters	Returns
Stores	`create`	Create a new store	`CreateStoreRequest`	`CreateStoreResponse`
	`list`	Get list of stores	-	`StoreListResponse`
Orders	`create`	Create a single order	`CreateOrderRequest`	`CreateOrderResponse`
	`createBulk`	Create multiple orders	`BulkOrderRequest`	`BulkOrderResponse`
	`getInfo`	Get order info by consignment ID	`consignmentId: string`	`OrderInfoResponse`
Locations	`getCities`	Get list of all cities	-	`CityListResponse`
	`getZones`	Get zones for a city	`cityId: number`	`ZoneListResponse`
	`getAreas`	Get areas for a zone	`zoneId: number`	`AreaListResponse`
Pricing	`calculate`	Calculate delivery price	`PriceCalculationRequest`	`PriceCalculationResponse`

Webhook Utilities Table

Utility	Description	Framework	Returns
`PathaoWebhookHandler`	Main webhook handler class	Any	Class instance
`createPathaoExpressWebhookHandler`	Express.js middleware for webhooks	Express	`(req, res, next) => Promise<void>`
`createPathaoFastifyWebhookHandler`	Fastify route handler for webhooks	Fastify	`(req, reply) => Promise<void>`
`createPathaoGenericWebhookHandler`	Generic handler for any framework	Any	`(req, res) => Promise<void>`

Webhook Handler Methods

Method	Description	Parameters	Returns
`handle`	Process webhook payload	`body: unknown, authHeader?: string`	`Promise<WebhookResponse>`
`express`	Get Express middleware handler	-	Express middleware
`fastify`	Get Fastify route handler	-	Fastify handler
`generic`	Get generic framework handler	-	Generic handler
`onOrderCreated`	Set handler for order.created webhooks	`handler: (payload) => void`	`this`
`onOrderDelivered`	Set handler for order.delivered webhooks	`handler: (payload) => void`	`this`
`on`	Listen to webhook events (EventEmitter)	`event: PathaoWebhookEvent, listener`	`this`

Error Classes Table

Error Class	Description	Properties
`PathaoError`	Base error class for all Pathao errors	`message: string, statusCode?: number, code?: string`
`PathaoApiError`	API request/response errors	`message: string, statusCode: number, response?: unknown`
`PathaoValidationError`	Input validation errors	`message: string, field?: string`
`PathaoAuthError`	Authentication errors	`message: string`
`PathaoWebhookError`	Webhook processing errors	`message: string`

Type Definitions & Enums

Category	Name	Description
Enums	`PathaoWebhookEvent`	Webhook event names (`WEBHOOK`, `ORDER_CREATED`, `ORDER_DELIVERED`, etc., `ERROR`)
	`DeliveryType`	Delivery type values (`Normal = 48`, `OnDemand = 12`)
	`ItemType`	Item type values (`Document = 1`, `Parcel = 2`)
Request Types	`CreateStoreRequest`	Store creation request payload
	`CreateOrderRequest`	Order creation request payload
	`BulkOrderRequest`	Bulk order creation payload
	`PriceCalculationRequest`	Price calculation request payload
Response Types	`CreateStoreResponse`	Store creation response
	`CreateOrderResponse`	Order creation response
	`OrderInfoResponse`	Order info response
	`WebhookResponse`	Webhook processing response
Webhook Types	`OrderCreatedWebhook`	Order created webhook payload
	`OrderDeliveredWebhook`	Order delivered webhook payload
	`WebhookPayload`	Union type for all webhook payloads

Validation Utilities

Function	Description	Parameters	Throws
`validateStoreName`	Validate store name (3-50 chars)	`name: string`	`PathaoValidationError`
`validateContactName`	Validate contact name (3-50 chars)	`name: string`	`PathaoValidationError`
`validatePhoneNumber`	Validate phone number (11 digits)	`phone: string, fieldName?: string`	`PathaoValidationError`
`validateRecipientName`	Validate recipient name (3-100 chars)	`name: string`	`PathaoValidationError`
`validateRecipientAddress`	Validate recipient address (10-220 chars)	`address: string`	`PathaoValidationError`
`validateItemWeight`	Validate item weight (0.5-10 kg)	`weight: number \| string`	`PathaoValidationError`
`validateItemQuantity`	Validate item quantity (positive integer)	`quantity: number`	`PathaoValidationError`
`validateAmountToCollect`	Validate amount to collect (non-negative)	`amount: number`	`PathaoValidationError`

API Reference

Stores

Create Store

const store = await client.stores.create({
  name: 'My Store', // Required: 3-50 characters
  contact_name: 'John Doe', // Required: 3-50 characters
  contact_number: '01712345678', // Required: 11 digits
  secondary_contact: '01512345678', // Optional: 11 digits
  otp_number: '01712345678', // Optional: 11 digits
  address: 'House 123, Road 4, Sector 10, Uttara, Dhaka-1230, Bangladesh', // Required: 15-120 characters
  city_id: 1, // Required
  zone_id: 298, // Required
  area_id: 37, // Required
});

List Stores

const stores = await client.stores.list();
console.log(`Total stores: ${stores.data.total}`);

Orders

Create Single Order

const order = await client.orders.create({
  store_id: 123456, // Required
  merchant_order_id: 'ORD-12345', // Optional
  recipient_name: 'Jane Smith', // Required: 3-100 characters
  recipient_phone: '01787654321', // Required: 11 digits
  recipient_secondary_phone: '01587654321', // Optional: 11 digits
  recipient_address: 'House 456, Road 8, Dhanmondi, Dhaka-1205, Bangladesh', // Required: 10-220 characters
  recipient_city: 1, // Optional (auto-detected if not provided)
  recipient_zone: 298, // Optional (auto-detected if not provided)
  recipient_area: 37, // Optional (auto-detected if not provided)
  delivery_type: 48, // Required: 48 = Normal, 12 = On Demand
  item_type: 2, // Required: 1 = Document, 2 = Parcel
  special_instruction: 'Handle with care', // Optional
  item_quantity: 1, // Required: positive integer
  item_weight: 0.5, // Required: 0.5-10 kg
  item_description: 'Electronics', // Optional
  amount_to_collect: 1000, // Required: non-negative integer
});

Create Bulk Orders

const orders = await client.orders.createBulk({
  orders: [
    {
      store_id: 123456,
      recipient_name: 'John Doe',
      recipient_phone: '01712345678',
      recipient_address: '123 Main St, Dhaka',
      delivery_type: 48,
      item_type: 2,
      item_quantity: 1,
      item_weight: 0.5,
      amount_to_collect: 1000,
    },
    {
      store_id: 123456,
      recipient_name: 'Jane Smith',
      recipient_phone: '01787654321',
      recipient_address: '456 Oak Ave, Dhaka',
      delivery_type: 48,
      item_type: 2,
      item_quantity: 1,
      item_weight: 0.5,
      amount_to_collect: 2000,
    },
  ],
});

Get Order Info

const orderInfo = await client.orders.getInfo('DL121224VS8TTJ');
console.log(`Status: ${orderInfo.data.order_status}`);

Locations

Get Cities

const cities = await client.locations.getCities();
console.log(`Available cities: ${cities.data.data.length}`);

Get Zones

const zones = await client.locations.getZones(1); // City ID
console.log(`Available zones: ${zones.data.data.length}`);

Get Areas

const areas = await client.locations.getAreas(298); // Zone ID
console.log(`Available areas: ${areas.data.data.length}`);

Pricing

Calculate Price

const price = await client.pricing.calculate({
  store_id: 123456,
  item_type: 2, // Parcel
  delivery_type: 48, // Normal Delivery
  item_weight: 0.5, // kg
  recipient_city: 1,
  recipient_zone: 298,
});

console.log(`Delivery fee: ${price.data.final_price} BDT`);
console.log(`Base price: ${price.data.price} BDT`);
console.log(`Discount: ${price.data.discount} BDT`);

Webhook Integration

The SDK provides comprehensive webhook handling utilities to help you build webhook endpoints quickly.

Express.js Example

Recommended: Use handler instance directly

import express from 'express';
import { PathaoWebhookHandler, PathaoWebhookEvent } from 'pathao-courier/webhooks';

const app = express();
app.use(express.json());

// Create handler instance and set up callbacks
const webhookHandler = new PathaoWebhookHandler({
  webhookSecret: 'your-webhook-secret',
  integrationSecret: 'f3992ecc-59da-4cbe-a049-a13da2018d51', // For test responses
});

webhookHandler.onOrderCreated(async (payload) => {
  console.log('Order created:', payload);
  // Handle order creation
  // e.g., update database, send notification, etc.
});

webhookHandler.onOrderDelivered(async (payload) => {
  console.log('Order delivered:', payload);
  // Handle delivery completion
});

// Use the handler directly as Express route handler
app.post('/pathao-webhook', webhookHandler.express());

Alternative: Using adapter function

import express from 'express';
import { createPathaoExpressWebhookHandler } from 'pathao-courier/webhooks';

const app = express();
app.use(express.json());

const webhookHandler = createPathaoExpressWebhookHandler({
  webhookSecret: 'your-webhook-secret',
});

app.post('/pathao-webhook', webhookHandler);

Fastify Example

Recommended: Use handler instance directly

import Fastify from 'fastify';
import { PathaoWebhookHandler } from 'pathao-courier/webhooks';

const fastify = Fastify();

// Create handler instance and set up callbacks
const webhookHandler = new PathaoWebhookHandler({
  webhookSecret: 'your-webhook-secret',
});

webhookHandler.onOrderDelivered(async (payload) => {
  console.log('Order delivered:', payload);
});

// Use the handler directly as Fastify route handler
fastify.post('/pathao-webhook', webhookHandler.fastify());

Alternative: Using adapter function

import Fastify from 'fastify';
import { createPathaoFastifyWebhookHandler } from 'pathao-courier/webhooks';

const fastify = Fastify();

const webhookHandler = createPathaoFastifyWebhookHandler({
  webhookSecret: 'your-webhook-secret',
});

fastify.post('/pathao-webhook', webhookHandler);

Generic Framework Example

Recommended: Use handler instance directly

import { PathaoWebhookHandler } from 'pathao-courier/webhooks';

// Create handler instance and set up callbacks
const webhookHandler = new PathaoWebhookHandler({
  webhookSecret: 'your-webhook-secret',
});

webhookHandler.onOrderDelivered(async (payload) => {
  console.log('Order delivered:', payload);
});

// Use with any framework
app.post('/pathao-webhook', async (req, res) => {
  await webhookHandler.generic()(req, res);
});

Manual Webhook Handling

import { PathaoWebhookHandler, PathaoWebhookEvent } from 'pathao-courier/webhooks';

const handler = new PathaoWebhookHandler({
  webhookSecret: 'your-webhook-secret',
});

// Set up event listeners using PathaoWebhookEvent enum
handler.on(PathaoWebhookEvent.WEBHOOK, (payload) => {
  console.log('Received webhook:', payload);
});

handler.on(PathaoWebhookEvent.ORDER_CREATED, (payload) => {
  console.log('Order created:', payload);
});

handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {
  console.log('Order delivered:', payload);
});

handler.on(PathaoWebhookEvent.ERROR, (error) => {
  console.error('Webhook error:', error);
});

// Process webhook
const result = await handler.handle(request.body, request.headers['x-pathao-signature']);

if (result.status === 'success') {
  // Webhook processed successfully
} else {
  // Handle error
  console.error(result.message);
}

Webhook Events

The PathaoWebhookHandler emits events that you can listen to using the PathaoWebhookEvent enum:

PathaoWebhookEvent.WEBHOOK - Emitted for any Pathao webhook payload after successful parsing and authentication
PathaoWebhookEvent.ORDER_CREATED - Emitted when an order is created
PathaoWebhookEvent.ORDER_DELIVERED - Emitted when an order is delivered
PathaoWebhookEvent.ORDER_PICKED - Emitted when an order is picked up
PathaoWebhookEvent.STORE_CREATED - Emitted when a store is created
PathaoWebhookEvent.ERROR - Emitted when an error occurs during webhook processing

import { PathaoWebhookHandler, PathaoWebhookEvent } from 'pathao-courier/webhooks';

const handler = new PathaoWebhookHandler({ webhookSecret: 'your-webhook-secret' });

// Listen to all webhooks
handler.on(PathaoWebhookEvent.WEBHOOK, (payload) => {
  console.log('Any Pathao webhook received:', payload);
});

// Listen to specific webhook types
handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {
  // payload is typed as OrderDeliveredWebhook
  console.log('Consignment ID:', payload.consignment_id);
  console.log('Collected Amount:', payload.collected_amount);
});

// Handle errors
handler.on(PathaoWebhookEvent.ERROR, (error) => {
  console.error('Pathao webhook processing error:', error);
});

Webhook Payload Types

The SDK provides TypeScript types for webhook payloads:

import type {
  OrderCreatedWebhook,
  OrderDeliveredWebhook,
  WebhookPayload,
} from 'pathao-courier';

// Type-safe webhook handling
handler.onOrderDelivered((payload: OrderDeliveredWebhook) => {
  // payload is fully typed
  console.log(payload.consignment_id);
  console.log(payload.collected_amount);
  console.log(payload.event); // Type: "order.delivered"
});

Token Management

The SDK automatically manages OAuth 2.0 tokens, including automatic refresh. You can optionally provide callbacks for custom token storage:

import { PathaoClient } from 'pathao-courier';
import type { StoredToken } from 'pathao-courier';

// Custom token storage
const client = new PathaoClient({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  username: 'your-email@example.com',
  password: 'your-password',
  environment: 'sandbox',
  onTokenUpdate: async (token: StoredToken) => {
    // Save token to database
    await db.saveToken(token);
  },
  onTokenLoad: async (): Promise<StoredToken | null> => {
    // Load token from database
    return await db.loadToken();
  },
});

Error Handling

The SDK provides custom error classes for better error handling:

import {
  PathaoError,
  PathaoApiError,
  PathaoValidationError,
  PathaoAuthError,
  PathaoWebhookError,
} from 'pathao-courier';

try {
  await client.orders.create(orderData);
} catch (error) {
  if (error instanceof PathaoValidationError) {
    console.error('Validation error:', error.message);
    console.error('Field:', error.field);
  } else if (error instanceof PathaoApiError) {
    console.error('API error:', error.message);
    console.error('Status code:', error.statusCode);
  } else if (error instanceof PathaoAuthError) {
    console.error('Authentication error:', error.message);
  } else if (error instanceof PathaoError) {
    console.error('Pathao error:', error.message);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions.

Module Resolution

If you encounter module resolution errors when importing from 'pathao-courier/webhooks', ensure your tsconfig.json uses one of these moduleResolution settings:

"node16" (recommended for Node.js projects)
"nodenext" (recommended for modern Node.js projects)
"bundler" (recommended for bundler-based projects)

Example tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node16"
    // ... other options
  }
}

Type Definitions

The SDK provides full type definitions:

import type {
  CreateOrderRequest,
  CreateOrderResponse,
  OrderInfoResponse,
  WebhookPayload,
} from 'pathao-courier';

// All types are exported and available
const orderRequest: CreateOrderRequest = {
  // TypeScript will autocomplete and validate
};

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint
npm run lint

# Format code
npm run format

# Generate documentation
npm run docs

License

MIT

Support

For API documentation and support, please visit the Pathao Courier Portal.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/workflows		.github/workflows
scripts		scripts
src		src
tests/unit		tests/unit
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
blueprint.md		blueprint.md
package-lock.json		package-lock.json
package.json		package.json
pathao-courier-1.0.0.tgz		pathao-courier-1.0.0.tgz
pathaodocs.md		pathaodocs.md
pathaowebhook.md		pathaowebhook.md
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Pathao Courier SDK

Features

Installation

⚠️ TypeScript Configuration Required

Quick Start

Basic Usage

API Reference

Complete API Methods Table

Webhook Utilities Table

Webhook Handler Methods

Error Classes Table

Type Definitions & Enums

Validation Utilities

API Reference

Stores

Create Store

List Stores

Orders

Create Single Order

Create Bulk Orders

Get Order Info

Locations

Get Cities

Get Zones

Get Areas

Pricing

Calculate Price

Webhook Integration

Express.js Example

Fastify Example

Generic Framework Example

Manual Webhook Handling

Webhook Events

Webhook Payload Types

Token Management

Error Handling

TypeScript Support

Module Resolution

Type Definitions

Development

License

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages