npm package: @some19ice/nigeria-geo-logistics
Description: Logistics utilities for Nigerian e-commerce - shipping zones, classifications, and postal codes
Author: Nigeria Geo Contributors
Latest version: 0.1.4

# @some19ice/nigeria-geo-logistics

Comprehensive logistics utilities for Nigerian e-commerce - shipping zones, LGA classifications, and postal codes for all 774 Local Government Areas.

## Installation

```bash
npm install @some19ice/nigeria-geo-logistics @some19ice/nigeria-geo-core
# or
pnpm add @some19ice/nigeria-geo-logistics @some19ice/nigeria-geo-core
```

## Features

- ✅ **Complete LGA Classifications** - Urban, semi-urban, rural, and riverine classifications for all 774 LGAs
- ✅ **Full Postal Code Coverage** - NIPOST postal codes for all Nigerian LGAs
- ✅ **Smart Shipping Zones** - 5-zone shipping calculation based on origin, destination, and terrain
- ✅ **Special Handling Detection** - Automatic identification of riverine areas requiring water transport
- ✅ **Type-Safe** - Full TypeScript support with comprehensive types

## Usage

### LGA Classifications

```typescript
import {
  getLGAClassification,
  isUrban,
  isSemiUrban,
  isRural,
  isRiverine,
  getLGAsByClassification,
  getClassificationCounts,
  requiresSpecialHandling,
} from '@some19ice/nigeria-geo-logistics';

// Get classification for any LGA
getLGAClassification('ikeja');    // 'urban'
getLGAClassification('ikorodu');  // 'semi-urban'
getLGAClassification('kuje');     // 'rural'
getLGAClassification('bonny');    // 'riverine'

// Boolean helpers
isUrban('ikeja');       // true
isSemiUrban('ikorodu'); // true
isRural('kuje');        // true
isRiverine('bonny');    // true

// Check if special handling is required (water transport)
requiresSpecialHandling('bonny'); // true
requiresSpecialHandling('ikeja'); // false

// Get all LGAs by classification
const urbanLGAs = getLGAsByClassification('urban');
// ['ikeja', 'lagos-island', 'kano-municipal', ...]

const riverineLGAs = getLGAsByClassification('riverine');
// ['bonny', 'brass', 'degema', 'southern-ijaw', ...]

// Get counts per classification
const counts = getClassificationCounts();
// { urban: 45, 'semi-urban': 180, rural: 520, riverine: 29 }
```

### Postal Codes

```typescript
import {
  getPostalCode,
  getStatePostalPrefix,
  isValidPostalCodeFormat,
  getLGAByPostalCode,
  getPostalCodesByState,
  getLGAsWithPostalCodes,
  getPostalCodesCount,
} from '@some19ice/nigeria-geo-logistics';

// Get postal code for any LGA
getPostalCode('ikeja');                   // '100001'
getPostalCode('municipal-area-council');  // '900001' (Abuja)
getPostalCode('kano-municipal');          // '700001'
getPostalCode('port-harcourt');           // '500001'

// Get state postal prefix
getStatePostalPrefix('lagos'); // '100'
getStatePostalPrefix('kano');  // '700'
getStatePostalPrefix('fct');   // '900'

// Validate postal code format (6 digits)
isValidPostalCodeFormat('100001'); // true
isValidPostalCodeFormat('12345');  // false (5 digits)

// Find LGA by postal code
getLGAByPostalCode('100001'); // 'ikeja'

// Get all postal codes in a state
const lagosPostalCodes = getPostalCodesByState('lagos');
// { ikeja: '100001', 'lagos-island': '101001', ... }

// Get coverage stats
getPostalCodesCount(); // 774
```

### Shipping Zones

```typescript
import {
  getShippingZone,
  getSimpleZone,
} from '@some19ice/nigeria-geo-logistics';

// Full shipping zone calculation
const zone = getShippingZone('lagos', 'ikeja', 'rivers', 'bonny');
// {
//   zone: 5,
//   originClassification: 'urban',
//   destinationClassification: 'riverine',
//   specialHandling: true,
//   reason: 'Distant region, riverine destination - maximum zone'
// }

// Same state delivery
const local = getShippingZone('lagos', 'ikeja', 'lagos', 'eti-osa');
// { zone: 1, specialHandling: false, reason: 'Same state delivery' }

// Same state but riverine
const riverine = getShippingZone('rivers', 'port-harcourt', 'rivers', 'bonny');
// { zone: 3, specialHandling: true, reason: 'Same state, but riverine destination requires water transport' }

// Simple zone calculation (by states only)
getSimpleZone('lagos', 'lagos'); // 1 (same state)
getSimpleZone('lagos', 'ogun');  // 2 (same region)
getSimpleZone('lagos', 'edo');   // 3 (adjacent region)
getSimpleZone('lagos', 'borno'); // 4 (distant region)
```

## API Reference

### Classifications

| Function | Description |
|----------|-------------|
| `getLGAClassification(lgaId)` | Returns `'urban'`, `'semi-urban'`, `'rural'`, or `'riverine'` |
| `isUrban(lgaId)` | Check if LGA is urban |
| `isSemiUrban(lgaId)` | Check if LGA is semi-urban |
| `isRural(lgaId)` | Check if LGA is rural |
| `isRiverine(lgaId)` | Check if LGA is riverine (water transport required) |
| `getLGAsByClassification(type)` | Get all LGA IDs with given classification |
| `getClassificationCounts()` | Get count of LGAs per classification |
| `requiresSpecialHandling(lgaId)` | Check if special handling is needed |
| `getClassifiedCount()` | Get total number of classified LGAs |

### Postal Codes

| Function | Description |
|----------|-------------|
| `getPostalCode(lgaId)` | Get 6-digit NIPOST postal code |
| `getStatePostalPrefix(stateId)` | Get 3-digit state prefix |
| `isValidPostalCodeFormat(code)` | Validate postal code format |
| `getLGAByPostalCode(code)` | Find LGA by postal code |
| `getPostalCodesByState(stateId)` | Get all postal codes in a state |
| `getLGAsWithPostalCodes()` | Get all LGA IDs with postal codes |
| `getPostalCodesCount()` | Get total postal codes count |

### Shipping Zones

| Function | Description |
|----------|-------------|
| `getShippingZone(originState, originLGA, destState, destLGA)` | Full zone calculation with details |
| `getSimpleZone(originState, destState)` | Simple zone by states only |

## Shipping Zone Guide

| Zone | Description | Examples |
|------|-------------|----------|
| **1** | Same state, urban | Lagos → Lagos |
| **2** | Same state rural, OR same region urban | Lagos → Ogun |
| **3** | Same region rural, OR adjacent region urban, OR same state riverine | Lagos → Edo |
| **4** | Adjacent region rural, OR distant region urban | Lagos → Rivers |
| **5** | Distant region rural/riverine | Lagos → Borno, Any → Bonny |

## Classification Criteria

| Type | Description | Characteristics |
|------|-------------|-----------------|
| **Urban** | Major cities | State capitals, commercial centers, full logistics infrastructure |
| **Semi-urban** | Secondary cities | Growing suburbs, university towns, moderate infrastructure |
| **Rural** | Agricultural areas | Remote areas, limited road access, extended delivery times |
| **Riverine** | Water-access areas | Niger Delta, islands, requires boat/water transport |

## State Postal Prefixes

| Prefix | States |
|--------|--------|
| 100-109 | Lagos |
| 110-119 | Ogun |
| 200-209 | Oyo |
| 300-319 | Edo |
| 400-419 | Enugu |
| 500-519 | Rivers |
| 700-719 | Kano |
| 800-819 | Kaduna |
| 900-909 | FCT (Abuja) |

## Data Sources

Classification and postal code data are derived from:
- **NIPOST** (Nigerian Postal Service) official postal codes
- **National Population Commission** urbanization data
- **National Bureau of Statistics** demographic classifications
- **Geographic research** on riverine/coastal areas in Niger Delta

## License

MIT