De. Utilities

Smart Calculation Engines for Logistics Operations

Essential utilities for fare calculation, distance estimation, zone assignment, and service discovery. Use internally in your code or consume via REST APIs with LSP integration and intelligent fallback.

What are De. Utilities?

De. Utilities are production-ready calculation engines for logistics operations. They handle fare estimation, distance calculation, zone assignment, and service discovery with LSP database integration and intelligent fallback mechanisms.

Key Capabilities:

Fare Calculation - Delivery fees, transport fares, ride-hailing, and cross-border shipping with customs/duties
Distance & ETA - Multi-modal distance calculation and arrival time estimation
Zone Management - Geographic zone assignment for service area determination
Service Discovery - Real-time nearby vehicle search with geospatial queries
Dual Interface - Use as internal functions or consume via REST APIs

Perfect for: E-commerce checkout flows, logistics cost estimation, route planning, customs clearance, fleet management

Why De. Utilities?

The Problem

Traditional logistics applications require complex, hardcoded calculation logic:

typescript

// ❌ Traditional approach: Hardcoded, unmaintainable
async function calculateShippingCost(order) {
  // Hardcoded distance calculation
  const distance = Math.sqrt(
    Math.pow(order.destination.lat - warehouse.lat, 2) +
    Math.pow(order.destination.lng - warehouse.lng, 2)
  ) * 111.32 // Rough km conversion
  
  // Hardcoded pricing logic
  let baseFee = 5.00
  if (distance > 50) baseFee += 10.00
  if (order.weight > 5) baseFee += order.weight * 1.50
  
  // No LSP integration, no real-time pricing
  return { total: baseFee, currency: 'USD' }
}

Problems:

🔴 Inaccurate distance calculations (straight-line vs. road distance)
🔴 Hardcoded pricing that doesn't reflect market rates
🔴 No LSP integration for real pricing data
🔴 Manual customs/duty calculations prone to errors
🔴 No fallback when data unavailable
🔴 Duplicate logic across applications

The Solution

De. Utilities provide intelligent, LSP-integrated calculations:

typescript

// ✅ The De. Utilities way: LSP-integrated, accurate
import { calculateTransportFare } from '@dedot/sdk'

const fare = await client.realm.utilities.transport.calculate({
  origin: { country: 'NG', city: 'Lagos', coordinates: [6.5244, 3.3792] },
  destination: { country: 'NG', city: 'Abuja', coordinates: [9.0765, 7.3986] },
  transportMode: 'ROAD',
  vehicleType: 'CONTAINER_TRUCK',
  cargo: { weight: { value: 5000, unit: 'kg' } }
})

// Returns LSP-integrated pricing with intelligent fallback
// {
//   baseFare: 150000,
//   distanceFare: 45000,
//   fuelSurcharge: 12000,
//   totalFare: 207000,
//   currency: 'NGN',
//   metadata: { dataSource: 'LSP', confidence: 0.92 }
// }

Benefits:

✅ Accurate multi-modal distance calculation (road, air, sea, rail)
✅ Real-time LSP pricing integration
✅ Automatic customs/duty/tax calculations
✅ Intelligent fallback to industry rates
✅ Confidence scoring and metadata
✅ Use internally or via REST APIs

Production-Ready Utilities

Delivery Fees Calculator

Calculate last-mile delivery costs with LSP carrier pricing, service levels, and fuel surcharges

Learn more →

Transport Fare Calculator

Multi-modal freight pricing with fleet capabilities, vehicle availability, and LSP integration

Learn more →

Ride-Hailing Fare

Real-time ride pricing with surge calculation, nearby driver search, and 7 vehicle classes

Learn more →

Cross-Border Fare

International shipping with customs duties, VAT/GST, clearance times, and HS code lookup

Learn more →

Distance Calculator

Accurate distance calculation for road, air, sea, and rail with route optimization

Learn more →

Zone Assignment

Geographic zone determination for service area coverage and routing decisions

Learn more →

Nearby Vehicle Search

Geospatial search for available vehicles, drivers, and fleet resources with 2dsphere indexes

Learn more →

ETA Calculator

Arrival time estimation with traffic patterns, route optimization, and historical data

Learn more →

Delivery Fees Calculator

Calculate last-mile delivery costs with LSP integration.

Features:

LSP carrier capability and pricing queries
Service level pricing (SAME_DAY, NEXT_DAY, STANDARD, EXPRESS)
Fuel surcharge and seasonal adjustments
Weight-based tiered pricing
Zone-based calculation with fallback

Use Cases:

E-commerce checkout shipping estimates
Order cost calculation before placement
Carrier comparison and selection
Customer delivery quote generation

Quick Example

typescript

import { DeClient } from '@dedot/sdk'

const client = new DeClient({ apiKey: 'your-key', workspace: 'your-workspace' })

// Calculate delivery fee
const result = await client.realm.utilities.delivery.calculate({
  origin: { country: 'NG', city: 'Lagos' },
  destination: { country: 'NG', city: 'Abuja' },
  serviceLevel: 'NEXT_DAY',
  weight: { value: 5, unit: 'kg' },
  dimensions: { length: 30, width: 20, height: 15, unit: 'cm' }
})

console.log(`Delivery Cost: ${result.totalFee} ${result.currency}`)
console.log(`Confidence: ${result.metadata.confidence * 100}%`)

API Endpoint: POST /api/realm/utilities/fares/delivery

Transport Fare Calculator

Multi-modal freight pricing with fleet capabilities.

Features:

LSP fleet capability and vehicle availability queries
Multi-modal support (ROAD, AIR, SEA, RAIL)
Vehicle type pricing (trucks, containers, cargo planes)
Fuel surcharge and distance-based calculation
Urgency-based pricing (URGENT, STANDARD, ECONOMY)

Use Cases:

Freight quote generation
Multi-modal transport cost comparison
Shipment cost forecasting
Carrier contract pricing validation

Quick Example

typescript

// Calculate transport fare
const fare = await client.realm.utilities.transport.calculate({
  origin: { country: 'NG', city: 'Lagos', coordinates: [6.5244, 3.3792] },
  destination: { country: 'NG', city: 'Kano', coordinates: [12.0022, 8.5920] },
  transportMode: 'ROAD',
  vehicleType: 'CONTAINER_TRUCK',
  cargo: {
    weight: { value: 5000, unit: 'kg' },
    volume: { value: 20, unit: 'm3' }
  },
  urgency: 'STANDARD'
})

console.log('Transport Fare:', {
  baseFare: fare.baseFare,
  distanceFare: fare.distanceFare,
  fuelSurcharge: fare.fuelSurcharge,
  total: fare.totalFare,
  distance: `${fare.distance.kilometer} km`,
  dataSource: fare.metadata.dataSource // 'LSP' or 'FALLBACK'
})

API Endpoint: POST /api/realm/utilities/fares/transport

Ride-Hailing Fare

Real-time ride pricing with surge and nearby drivers.

Features:

7 vehicle classes (ECONOMY, STANDARD, COMFORT, PREMIUM, LUXURY, XL, SUV)
Real-time surge pricing based on time and demand
Nearby driver search with geospatial queries
Pickup ETA from nearest driver
Trip duration and distance estimation
LSP pricing integration with fallback

Use Cases:

Ride-hailing app pricing
Corporate transport cost estimation
Airport/hotel shuttle pricing
On-demand passenger transport

Quick Example

typescript

// Calculate ride fare
const rideFare = await client.realm.utilities.ride.calculate({
  pickup: { 
    country: 'GH', 
    city: 'Accra', 
    coordinates: [5.6037, -0.1870] 
  },
  dropoff: { 
    country: 'GH', 
    coordinates: [5.6500, -0.2000] 
  },
  vehicleClass: 'ECONOMY',
  passengerCount: 2,
  includeNearbyDrivers: true
})

console.log('Ride Estimate:', {
  fare: `${rideFare.estimatedFare.totalAfterSurge} ${rideFare.estimatedFare.currency}`,
  surge: `${rideFare.surgeInfo.multiplier}x - ${rideFare.surgeInfo.reason}`,
  pickupETA: `${rideFare.pickupEstimate.eta.minute} min`,
  nearbyDrivers: rideFare.pickupEstimate.nearbyDrivers,
  tripDuration: `${rideFare.tripEstimate.duration.minute} min`,
  distance: `${rideFare.tripEstimate.distance.kilometer} km`
})

API Endpoint: POST /api/realm/utilities/fares/ride

Surge Multipliers:

Peak hours (7-9 AM, 5-7 PM): 1.5x
Weekend nights (Fri-Sat 10 PM-2 AM): 1.8x
Late night (2-5 AM): 1.3x
Normal hours: 1.0x

Cross-Border Fare

International shipping with customs and duties.

Features:

LSP customs regulations and tax rules integration
Automatic duty calculation by HS code
VAT/GST calculation by destination country
Import taxes and levies
Required documents determination
Clearance time estimation
Brokerage, inspection, and border crossing fees

Use Cases:

International e-commerce shipping
Import/export cost estimation
Customs clearance quotes
Trade compliance planning

Quick Example

typescript

// Calculate cross-border fare
const crossBorder = await client.realm.utilities.crossborder.calculate({
  origin: { country: 'US', city: 'Los Angeles' },
  destination: { country: 'NG', city: 'Lagos' },
  shipment: {
    weight: { value: 100, unit: 'kg' },
    declaredValue: { amount: 5000, currency: 'USD' },
    hsCode: '8517.12', // Electronics
    description: 'Mobile phones',
    quantity: 50
  },
  transportMode: 'SEA',
  incoterms: 'CIF'
})

console.log('Cross-Border Cost:', {
  total: `${crossBorder.totalCost.amount} ${crossBorder.totalCost.currency}`,
  breakdown: {
    transport: crossBorder.breakdown.transportFee.amount,
    customs: crossBorder.breakdown.customsDuty?.amount,
    vat: crossBorder.breakdown.vat?.amount,
    brokerage: crossBorder.breakdown.brokerageFee.amount
  },
  clearanceTime: `${crossBorder.estimatedClearanceTime.min.day}-${crossBorder.estimatedClearanceTime.max.day} days`,
  documents: crossBorder.requiredDocuments
})

API Endpoint: POST /api/realm/utilities/fares/crossborder

Supported Countries:

Customs data: 50+ countries with HS code lookup
VAT/GST rates: GB, DE, FR, ES, IT, US, NG, KE, GH, ZA, and more
Duty rates: Industry-standard rates by product category

Distance Calculator

Accurate multi-modal distance calculation.

Features:

Multi-modal support (ROAD, AIR, SEA, RAIL)
Great circle distance for air/sea
Road distance with route optimization
Coordinate-based or address-based input
Distance in kilometers and miles

Use Cases:

Route planning
Delivery radius calculation
Service area determination
Fare calculation input

Quick Example

typescript

// Calculate distance
const distance = await client.realm.utilities.distance.calculate({
  origin: {
    country: 'NG',
    city: 'Lagos',
    coordinates: [6.5244, 3.3792]
  },
  destination: {
    country: 'NG',
    city: 'Abuja',
    coordinates: [9.0765, 7.3986]
  },
  mode: 'ROAD'
})

console.log(`Distance: ${distance.distance.value} km`)

API Endpoint: POST /api/realm/utilities/distance

Zone Assignment

Geographic zone determination for service areas.

Features:

Point-in-polygon zone detection
Service type-specific zones (DELIVERY, WAREHOUSE, TERMINAL)
Hierarchical zone structure
Fallback to nearest zone

Use Cases:

Service area coverage checks
Zone-based pricing
Warehouse territory assignment
Delivery route optimization

Quick Example

typescript

// Assign zone
const zone = await client.realm.utilities.zone.assign({
  location: {
    country: 'NG',
    city: 'Lagos',
    coordinates: [6.5244, 3.3792]
  },
  serviceType: 'DELIVERY'
})

console.log('Zone:', zone.zone.name)
console.log('Coverage:', zone.coverage)

API Endpoint: POST /api/realm/utilities/zone

Nearby Vehicle Search

Geospatial search for available vehicles.

Features:

MongoDB 2dsphere geospatial indexes
Radius search with automatic expansion
Bounding box search
Nearest N vehicles
Vehicle type filtering
Status filtering (AVAILABLE, BUSY, OFFLINE)

Use Cases:

Ride-hailing driver matching
Fleet dispatch optimization
Vehicle availability checks
Service coverage validation

Quick Example

typescript

// Search nearby vehicles
const nearby = await client.realm.utilities.nearby.search({
  location: { lat: 5.6037, lng: -0.1870 },
  radius: 5000, // 5km
  vehicleType: 'SEDAN',
  status: 'AVAILABLE',
  limit: 10
})

console.log(`Found ${nearby.count} vehicles`)
nearby.vehicles.forEach(v => {
  console.log(`${v.id}: ${v.distance}m away`)
})

API Endpoints:

POST /api/realm/utilities/nearby/search - Radius search
POST /api/realm/utilities/nearby/bounds - Bounding box search
POST /api/realm/utilities/nearby/nearest - Nearest N vehicles

ETA Calculator

Arrival time estimation with traffic patterns.

Features:

Multi-modal ETA calculation
Traffic pattern integration
Historical data analysis
Route optimization
Time window estimation

Use Cases:

Delivery time promises
Pickup scheduling
Route planning
Customer notifications

Quick Example

typescript

// Calculate ETA
const eta = await client.realm.utilities.eta.calculate({
  origin: { coordinates: [6.5244, 3.3792] },
  destination: { coordinates: [9.0765, 7.3986] },
  mode: 'ROAD',
  departureTime: Date.now()
})

console.log(`ETA: ${eta.estimatedArrival}`)
console.log(`Duration: ${eta.duration.minute} minutes`)

API Endpoint: POST /api/realm/utilities/eta

Dual Interface: Internal + API

All utilities support both internal function calls and REST API consumption:

Internal Usage (SDK)

typescript

import { calculateDeliveryFees } from '@dedot/sdk'

// Direct function call - full TypeScript support
const result = await calculateDeliveryFees({
  origin: { country: 'NG', city: 'Lagos' },
  destination: { country: 'NG', city: 'Abuja' },
  serviceLevel: 'NEXT_DAY',
  weight: { value: 5, unit: 'kg' }
}, App) // Pass Fastify instance for LSP access

External Usage (REST API)

bash

curl -X POST https://api.dedot.app/realm/utilities/fares/delivery \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "country": "NG", "city": "Lagos" },
    "destination": { "country": "NG", "city": "Abuja" },
    "serviceLevel": "NEXT_DAY",
    "weight": { "value": 5, "unit": "kg" }
  }'

Benefits:

Internal: Direct access, no network overhead, full LSP integration
External: Language-agnostic, webhook-compatible, cached responses

LSP Integration & Fallback

All utilities query LSP databases for real-time data and fall back gracefully:

LSP Data Sources

Delivery Fees:

capabilities collection - Carrier transport capabilities
pricing collection - Pricing rules, fuel surcharge, seasonal adjustments

Transport Fare:

capabilities collection - Fleet capabilities by transport mode
vehicles collection - Available vehicles by type
pricing collection - Freight pricing rules

Ride-Hailing:

pricing collection - Ride pricing rules by vehicle class
vehicles collection - Nearby driver availability
demand_analytics collection - Surge multiplier data (optional)

Cross-Border:

customs_regulations collection - Duty rates by HS code (future)
tax_regulations collection - VAT/GST rates (future)
compliance_rules collection - Required documents (future)
clearance_metrics collection - Historical clearance times (future)

Fallback Strategy

When LSP data unavailable, utilities use industry-standard rates:

typescript

// Always returns valid result
const fare = await calculateTransportFare(request, App)

// Check data source
if (fare.metadata.dataSource === 'LSP') {
  console.log('Using real LSP pricing')
} else if (fare.metadata.dataSource === 'FALLBACK') {
  console.log('Using industry-standard rates')
} else {
  console.log('Hybrid: Partial LSP data + fallback')
}

// Confidence score indicates reliability
console.log(`Confidence: ${fare.metadata.confidence * 100}%`)

Confidence Levels:

0.90-1.00: LSP data with high accuracy
0.70-0.89: LSP data with some fallback
0.50-0.69: Mostly fallback with limited LSP data
<0.50: Full fallback, industry estimates

When to Use De. Utilities

✅ Ideal Use Cases

E-commerce Checkout Flows

Real-time shipping cost calculation
Multi-carrier comparison
International shipping with customs
Delivery time estimation

Logistics Cost Estimation

Freight quote generation
Transport cost forecasting
Budget planning and analysis
Contract pricing validation

Fleet & Dispatch Management

Nearby vehicle search
Ride-hailing pricing
Route optimization input
Service coverage validation

International Trade

Customs duty estimation
Import/export cost calculation
HS code-based pricing
Clearance documentation

❌ When NOT to Use

Simple Fixed-Price Scenarios

Flat-rate shipping (no calculation needed)
Hardcoded pricing tables
Direct database lookups

Real-Time Sub-Second Requirements

Microsecond-level response needed
In-memory calculations preferred

Single-Provider, No Integration

No LSP database available
Static pricing never changes
No fallback logic needed

Getting Started

Ready to start using De. Utilities?

De. Utilities

Smart Calculation Engines for Logistics Operations

What are De. Utilities?

Why De. Utilities? ​

The Problem ​

The Solution ​

Production-Ready Utilities ​

Delivery Fees Calculator

Transport Fare Calculator

Ride-Hailing Fare

Cross-Border Fare

Distance Calculator

Zone Assignment

Nearby Vehicle Search

ETA Calculator

Delivery Fees Calculator ​

Quick Example ​

Transport Fare Calculator ​

Quick Example ​

Ride-Hailing Fare ​

Quick Example ​

Cross-Border Fare ​

Quick Example ​

Distance Calculator ​

Quick Example ​

Zone Assignment ​

Quick Example ​

Nearby Vehicle Search ​

Quick Example ​

ETA Calculator ​

Quick Example ​

Dual Interface: Internal + API ​

Internal Usage (SDK) ​

External Usage (REST API) ​

LSP Integration & Fallback ​

LSP Data Sources ​

Fallback Strategy ​

When to Use De. Utilities ​

✅ Ideal Use Cases ​

❌ When NOT to Use ​

Getting Started ​

Why De. Utilities?

The Problem

The Solution

Production-Ready Utilities

Delivery Fees Calculator

Quick Example

Transport Fare Calculator

Quick Example

Ride-Hailing Fare

Quick Example

Cross-Border Fare

Quick Example

Distance Calculator

Quick Example

Zone Assignment

Quick Example

Nearby Vehicle Search

Quick Example

ETA Calculator

Quick Example

Dual Interface: Internal + API

Internal Usage (SDK)

External Usage (REST API)

LSP Integration & Fallback

LSP Data Sources

Fallback Strategy

When to Use De. Utilities

✅ Ideal Use Cases

❌ When NOT to Use

Getting Started