@ph-itdev/ph-order-processor

Order processing utilities for Philippine e-commerce and warehouse systems.

Installation

npm install @ph-itdev/ph-order-processor

Features

• Order Status Management - Status transitions, Filipino-friendly labels, order number generation
• Pricing Utilities - Line item calculations, discounts, installments, Philippine peso formatting
• Shipping Calculations - Weight-based fees, Philippine shipping zones, delivery estimates
• Payment Processing - Payment references, COD fees, digital payment detection
• Tax Calculations - VAT (12%), withholding tax, percentage tax, BIR references

Usage

Order Status

import { Status, getNextStatuses, canTransition, getStatusLabel, generateOrderNumber } from '@ph-itdev/ph-order-processor/order-status';

// Get next valid statuses
const nextStatuses = getNextStatuses(Status.PENDING); // [CONFIRMED, CANCELLED]

// Check if transition is valid
canTransition(Status.PENDING, Status.CONFIRMED); // true
canTransition(Status.PENDING, Status.SHIPPED); // false

// Get Filipino-friendly label
getStatusLabel(Status.PENDING); // "Naghihintay (Pending)"

// Generate order number
const orderNum = generateOrderNumber('WH01', 1, new Date(2026, 5, 24));
// "ORD-WH01-20260624-000001"

Pricing

import { calculateLineItem, calculateOrderTotal, applyDiscount, calculateInstallment, formatPrice } from '@ph-itdev/ph-order-processor/pricing';

// Calculate line item with discount and tax
const item = calculateLineItem(2, 500, { discountPercent: 10, taxRate: 12 });
// { quantity: 2, unitPrice: 500, subtotal: 1000, discount: 100, tax: 108, total: 1008 }

// Apply discount
const discounted = applyDiscount(1000, { type: 'percentage', value: 15 }); // 850

// Calculate installment
const installment = calculateInstallment(12000, 12, 5);
// { monthlyPayment: 1050, totalPayment: 12600, totalInterest: 600, months: 12 }

// Format as Philippine peso
formatPrice(1234.56); // "₱1,234.56"

Shipping

import { calculateShippingFee, estimateDeliveryDays, calculateVolumetricWeight, getShippingZones } from '@ph-itdev/ph-order-processor/shipping';

// Calculate shipping fee
const fee = calculateShippingFee(2, { zone: 'LUZON', serviceType: 'express' });

// Estimate delivery days
const days = estimateDeliveryDays('NCR', 'VISAYAS'); // 3

// Calculate volumetric weight (in cm)
const volWeight = calculateVolumetricWeight(50, 40, 30); // 12 kg

// Get Philippine shipping zones
const zones = getShippingZones(); // [{ code: 'NCR', name: 'National Capital Region', ... }, ...]

Payment

import { PaymentMethod, generatePaymentReference, calculateCodFee, isDigitalPayment } from '@ph-itdev/ph-order-processor/payment';

// Generate payment reference
const ref = generatePaymentReference(PaymentMethod.GCASH, 'ORD-WH01-000001');
// "GCASH-ORD-WH01-000001"

// Calculate COD fee
const codFee = calculateCodFee(1000, PaymentMethod.GCASH); // 35

// Check if digital payment
isDigitalPayment(PaymentMethod.GCASH); // true
isDigitalPayment(PaymentMethod.CASH); // false

Tax

import { calculateVAT, calculateWithholdingTax, calculatePercentageTax, generateBIRReference } from '@ph-itdev/ph-order-processor/tax';

// Calculate 12% VAT
const vat = calculateVAT(1000); // 120

// Calculate withholding tax
const cwt = calculateWithholdingTax(10000, 'professional'); // 1000

// Calculate percentage tax (3% for non-VAT)
const pt = calculatePercentageTax(10000); // 300

// Generate BIR reference
const birRef = generateBIRReference('INV', new Date(2026, 5, 24), 1);
// "INV-20260624-00001"

API Reference

Order Status

• Status - Enum with PENDING, CONFIRMED, PROCESSING, PACKED, SHIPPED, DELIVERED, CANCELLED, RETURNED
• getNextStatuses(current: Status): Status[] - Get valid next statuses
• canTransition(from: Status, to: Status): boolean - Check if transition is valid
• getStatusLabel(status: Status): string - Get Filipino-friendly label
• generateOrderNumber(warehouseCode: string, sequence: number, date?: Date): string - Generate order number

Pricing

• calculateLineItem(quantity, unitPrice, options?): LineItemResult - Calculate line item
• calculateOrderTotal(items): OrderTotal - Calculate order total
• applyDiscount(amount, discount): number - Apply discount
• calculateInstallment(total, months, interestRate?): InstallmentResult - Calculate installment
• formatPrice(amount): string - Format as Philippine peso

Shipping

• calculateShippingFee(weight, options?): number - Calculate shipping fee
• estimateDeliveryDays(originZone, destZone): number - Estimate delivery days
• calculateVolumetricWeight(length, width, height): number - Calculate volumetric weight
• getShippingZones(): ShippingZone[] - Get Philippine shipping zones

Payment

• PaymentMethod - Enum with CASH, GCASH, MAYA, BANK_TRANSFER, CREDIT_CARD, COD
• generatePaymentReference(method, orderId): string - Generate payment reference
• calculateCodFee(amount, method?): number - Calculate COD fee
• isDigitalPayment(method): boolean - Check if digital payment

Tax

• calculateVAT(amount): number - Calculate 12% VAT
• calculateWithholdingTax(amount, category?): number - Calculate withholding tax
• calculatePercentageTax(amount): number - Calculate 3% percentage tax
• generateBIRReference(prefix, date, sequence): string - Generate BIR reference

License

MIT