Shipping SDK

A unified Node.js SDK for integrating with multiple shipping companies (Hi-Express, Naqil) using a consistent API.

Installation

npm install @alihammad/shipping-sdk

Quick Start

import { ShippingSDK } from "@alihammad/shipping-sdk";

const sdk = new ShippingSDK();
sdk.init({
  company: "hi-express", // or "naqil"
  type: "staging", // or "production"
  apiKey: "YOUR_API_KEY",
});

// Create an order
const order = await sdk.orders.create({
  client_identifier: "OID-12345",
  customer_name: "John Doe",
  customer_phone: "0501234567",
  governance_id: 1,
  order_value: 150.0,
  delivery_address: "123 Main St, Riyadh",
  notes: "Deliver before 5 PM",
});

Initialization

Initialize the SDK with your preferred provider, environment (production or staging), and API key.

import { ShippingSDK } from "@alihammad/shipping-sdk";

const sdk = new ShippingSDK();

sdk.init({
  company: "hi-express", // or "naqil"
  type: "staging", // or "production"
  apiKey: "YOUR_API_KEY",
});

Configuration Options

• company: "hi-express" | "naqil" - The shipping company to integrate with
• type: "production" | "staging" - API environment
• apiKey: string - Your API key for the selected shipping company

Order Management

The SDK provides a unified orders handler that works consistently across all supported companies.

Create an Order

import { OrderType } from "@alihammad/shipping-sdk";

const newOrder: OrderType = {
  client_identifier: "OID-12345",
  customer_name: "John Doe",
  customer_phone: "0501234567",
  governance_id: 1,
  order_value: 150.0,
  delivery_address: "123 Main St, Riyadh",
  notes: "Deliver before 5 PM",
};

const result = await sdk.orders.create(newOrder);
console.log(result);

Get All Orders

const orders = await sdk.orders.getAll();

Get One Order

const order = await sdk.orders.getOne("order-id");

Update an Order

await sdk.orders.update("order-id", {
  ...newOrder,
  notes: "Updated instructions",
});

Delete an Order

await sdk.orders.delete("order-id");

Ticket Management (Hi-Express Only)

Hi-Express supports ticket management for handling delivery issues and customer support.

Create a Ticket

const ticket = await sdk.tickets.create({
  order_id: "order-identifier",
  title: "Delivery Issue",
  description: "Customer reported delivery problem",
});

Get All Tickets

const tickets = await sdk.tickets.getAll();

Get One Ticket

const ticket = await sdk.tickets.getOne("ticket-id");

Update a Ticket

await sdk.tickets.update("ticket-id", {
  ...ticket,
  description: "Updated ticket description",
});

Delete a Ticket

await sdk.tickets.delete("ticket-id");

Type Definitions

Order Types

Hi-Express Order Type

interface HiExpressOrderType {
  id?: number;
  order_id?: number;
  order_identifier?: string;
  client_identifier: string;
  customer_name: string;
  customer_phone: string;
  customer_secondary_phone?: string;
  governance_id: number;
  city_id?: number;
  order_value: number;
  delivery_address: string;
  notes: string;
  latitude?: string;
  longitude?: string;
  order_type_id?: number;
  airwaybill_number?: string;
  items?: HiExpressOrderItem[];
}

Naqil Order Type

interface NaqilOrderType {
  merchantLoginId: string;
  senderId: number;
  receiverName: string;
  receiverHp1: string;
  state: string;
  district: string;
  locationDetails: string;
  rmk: string;
  qty: number;
  receiptAmtIqd: number;
  productInfo: string;
  senderSystemCaseId: string | number;
  custReceiptNoOri?: string;
  longitude?: string;
  latitude?: string;
}

Ticket Type (Hi-Express)

interface HiExpressTicketType {
  id: number;
  order_id: number;
  order_identifier: string;
  client_identifier: string;
  order_status_type: string;
  title: string;
  ticket_status: string;
  description: string;
  responsible: null;
  created_by: string;
  created_at: string;
  attachment: null;
  ticket_category_id: number;
  ticket_category_name: string;
}

Supported Companies

Hi-Express (hi-express)

• Features: Orders, Tickets
• Authentication: API Key header
• Base URLs:
  • Production: https://api.hi-express.com
  • Staging: https://staging-api.hi-express.com

Naqil (naqil)

• Features: Orders
• Authentication: Bearer token
• Base URLs:
  • Production: https://api.naqil.com
  • Staging: https://staging-api.naqil.com

Error Handling

The SDK provides comprehensive error handling with custom error types:

try {
  const order = await sdk.orders.create(newOrder);
} catch (error) {
  if (error instanceof HiExpressError) {
    console.error("Hi-Express API Error:", error.message);
    console.error("Status Code:", error.statusCode);
  } else {
    console.error("Unexpected Error:", error.message);
  }
}

Architecture

The SDK uses a unified handler pipeline. Internally, it maps your standard OrderType to the specific payload format required by each shipping provider's API.

Handler Structure

• BaseOrderHandler: Common CRUD operations
• BaseHiExpressHandler: Hi-Express specific response handling
• HiExpressOrders: Hi-Express order implementation
• NaqilOrders: Naqil order implementation
• HiExpressTickets: Hi-Express ticket implementation

Development

Building

npm run build

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

# CI mode
npm run test:ci

Test Coverage

The SDK includes comprehensive unit tests with:

• 69.04% coverage on handlers
• 55.55% coverage on types
• 40/40 tests passing
• Integration tests for end-to-end workflows

Requirements

• Node.js: >=18
• TypeScript: >=5.0.0

License

ISC

Repository

GitHub Repository