@de./types 1.0.0

package/src/realm/utilities.ts

@@ -0,0 +1,730 @@
+import { Type, Static } from '@sinclair/typebox'
+import { APIResponseBaseSchema, APIResponseDataSchemaFactory, APIHeadersSchema } from '../api'
+import { DurationSchema, DurationRangeSchema, DateTimeZoneSchema } from '../time'
+import { MoneySchema, DistanceSchema, WeightSchema, VolumeSchema, DimensionsSchema, ServiceLevelSchema, AccuracySchema, SourceSchema } from '../measure'
+import { CoordinatesSchema, LocationInputSchema } from '../geo'
+import { CoverageTransitModeSchema } from '../lsp/coverage'
+
+// ==========================================
+// Geographic Types
+// ==========================================
+
+export const PrecisionTierSchema = Type.Union([
+	Type.Literal('ESTIMATE'),
+	Type.Literal('STANDARD'),
+	Type.Literal('PRECISE')
+])
+
+export const DistanceCalculationRequestSchema = Type.Object({
+	origin: LocationInputSchema,
+	destination: LocationInputSchema,
+	mode: Type.Optional(CoverageTransitModeSchema),
+	precision: Type.Optional(PrecisionTierSchema)
+})
+
+export const DistanceCalculationResultSchema = Type.Object({
+	distance: DistanceSchema,
+	mode: CoverageTransitModeSchema,
+	route: Type.Optional(Type.Object({
+		waypoints: Type.Optional(Type.Array(CoordinatesSchema)), // [lat, lng][]
+		duration: Type.Optional(DurationSchema) // Minutes
+	})),
+	metadata: Type.Object({
+		accuracy: AccuracySchema,
+		confidence: Type.Number({ minimum: 0, maximum: 1 }),
+		dataSource: SourceSchema,
+		calculatedAt: Type.Number(),
+		disclaimer: Type.Optional(Type.String())
+	})
+})
+
+export const ServiceTypeSchema = Type.Union([
+	Type.Literal('DELIVERY'),
+	Type.Literal('PRICING'),
+	Type.Literal('COVERAGE')
+])
+export const ZoneAssignmentRequestSchema = Type.Object({
+	location: LocationInputSchema,
+	serviceType: Type.Optional(ServiceTypeSchema),
+	vehicleType: Type.Optional(Type.String()),  // VehicleType from fleet
+	includeRestrictions: Type.Optional(Type.Boolean())
+})
+
+export const ZoneAssignmentResultSchema = Type.Object({
+	zone: Type.Object({
+		id: Type.String(),
+		name: Type.String(),
+		type: Type.Union([
+			Type.Literal('URBAN'),
+			Type.Literal('SUBURBAN'),
+			Type.Literal('RURAL'),
+			Type.Literal('REMOTE'),
+			Type.Literal('METROPOLITAN')
+		])
+	}),
+	country: Type.String(),
+	region: Type.Optional(Type.String()),
+	pricingTier: Type.Optional(Type.Number({ minimum: 1 })),
+	serviceability: Type.Object({
+		delivery: Type.Boolean(),
+		sameDay: Type.Boolean(),
+		nextDay: Type.Boolean()
+	}),
+	restrictions: Type.Optional(Type.Object({
+		hasRestrictions: Type.Boolean(),
+		speedLimits: Type.Array(Type.Any()),
+		noGoZones: Type.Array(Type.Any()),
+		parkingRules: Type.Array(Type.Any()),
+		vehicleAllowed: Type.Boolean()
+	})),
+	metadata: Type.Object({
+		accuracy: AccuracySchema,
+		confidence: Type.Number({ minimum: 0, maximum: 1 }),
+		calculatedAt: Type.Number(),
+		dataSource: Type.Optional(Type.Union([
+			Type.Literal('LSP_COVERAGE'),
+			Type.Literal('ESTIMATE')
+		])),
+		carriers: Type.Optional(Type.Array(Type.String()))
+	})
+})
+
+// ==========================================
+// Pricing Types
+// ==========================================
+
+export const DeliveryFeesRequestSchema = Type.Object({
+	origin: LocationInputSchema,
+	destination: LocationInputSchema,
+	serviceLevel: ServiceLevelSchema,
+	weight: WeightSchema,
+	volume: Type.Optional(VolumeSchema),
+	dimensions: Type.Optional(DimensionsSchema),
+	declaredValue: Type.Optional(MoneySchema),
+	options: Type.Optional(Type.Object({
+		insurance: Type.Optional(Type.Boolean()),
+		signature: Type.Optional(Type.Boolean()),
+		tracking: Type.Optional(Type.Boolean()),
+		fragile: Type.Optional(Type.Boolean()),
+		hazmat: Type.Optional(Type.Boolean())
+	}))
+})
+
+export const DeliveryFeesResultSchema = Type.Object({
+	totalCost: MoneySchema,
+	breakdown: Type.Object({
+		baseFee: MoneySchema,
+		distanceFee: MoneySchema,
+		weightFee: MoneySchema,
+		serviceLevelFee: MoneySchema,
+		zoneFee: Type.Optional(MoneySchema),
+		fuelSurcharge: Type.Optional(MoneySchema),
+		insuranceFee: Type.Optional(MoneySchema),
+		additionalFees: Type.Optional(Type.Array(Type.Object({
+			name: Type.String(),
+			amount: MoneySchema
+		})))
+	}),
+	currency: Type.String(),
+	validUntil: Type.Number(),
+	metadata: Type.Object({
+		accuracy: AccuracySchema,
+		confidence: Type.Number({ minimum: 0, maximum: 1 }),
+		dataSource: SourceSchema,
+		calculatedAt: Type.Number(),
+		disclaimer: Type.String()
+	})
+})
+
+export const TransportFareRequestSchema = Type.Object({
+	origin: LocationInputSchema,
+	destination: LocationInputSchema,
+	transportMode: CoverageTransitModeSchema,
+	cargo: Type.Object({
+		weight: WeightSchema,
+		volume: Type.Optional(VolumeSchema),
+		dimensions: Type.Optional(DimensionsSchema),
+		type: Type.Optional(Type.Union([
+			Type.Literal('GENERAL'),
+			Type.Literal('REFRIGERATED'),
+			Type.Literal('HAZMAT'),
+			Type.Literal('OVERSIZED'),
+			Type.Literal('FRAGILE')
+		]))
+	}),
+	vehicleType: Type.Optional(Type.String()),
+	urgency: Type.Optional(Type.Union([
+		Type.Literal('STANDARD'),
+		Type.Literal('EXPRESS'),
+		Type.Literal('CRITICAL')
+	]))
+})
+
+export const TransportFareResultSchema = Type.Object({
+	totalCost: MoneySchema,
+	breakdown: Type.Object({
+		baseRate: MoneySchema,
+		distanceRate: MoneySchema,
+		weightRate: MoneySchema,
+		fuelSurcharge: MoneySchema,
+		tollFees: Type.Optional(MoneySchema),
+		handlingFees: Type.Optional(MoneySchema),
+		urgencyFee: Type.Optional(MoneySchema),
+		additionalCharges: Type.Optional(Type.Array(Type.Object({
+			name: Type.String(),
+			amount: MoneySchema
+		})))
+	}),
+	currency: Type.String(),
+	estimatedDuration: DurationRangeSchema,
+	validUntil: Type.Number(),
+	metadata: Type.Object({
+		accuracy: AccuracySchema,
+		confidence: Type.Number({ minimum: 0, maximum: 1 }),
+		dataSource: SourceSchema,
+		calculatedAt: Type.Number(),
+		disclaimer: Type.String()
+	})
+})
+
+export const CrossBorderFareRequestSchema = Type.Object({
+	origin: LocationInputSchema,
+	destination: LocationInputSchema,
+	shipment: Type.Object({
+		weight: WeightSchema,
+		declaredValue: MoneySchema,
+		hsCode: Type.Optional(Type.String()),
+		description: Type.String(),
+		quantity: Type.Number({ minimum: 1 })
+	}),
+	transportMode: CoverageTransitModeSchema,
+	incoterms: Type.Optional(Type.Union([
+		Type.Literal('EXW'),
+		Type.Literal('FCA'),
+		Type.Literal('CPT'),
+		Type.Literal('CIP'),
+		Type.Literal('DAP'),
+		Type.Literal('DPU'),
+		Type.Literal('DDP'),
+		Type.Literal('FAS'),
+		Type.Literal('FOB'),
+		Type.Literal('CFR'),
+		Type.Literal('CIF')
+	]))
+})
+
+export const CrossBorderFareResultSchema = Type.Object({
+	totalCost: MoneySchema,
+	breakdown: Type.Object({
+		transportFee: MoneySchema,
+		customsDuty: Type.Optional(MoneySchema),
+		vat: Type.Optional(MoneySchema),
+		importTax: Type.Optional(MoneySchema),
+		brokerageFee: Type.Optional(MoneySchema),
+		documentationFee: Type.Optional(MoneySchema),
+		inspectionFee: Type.Optional(MoneySchema),
+		borderCrossingFee: Type.Optional(MoneySchema),
+		additionalFees: Type.Optional(Type.Array(Type.Object({
+			name: Type.String(),
+			amount: MoneySchema
+		})))
+	}),
+	currency: Type.String(),
+	duties: Type.Optional(Type.Object({
+		rate: Type.Number({ description: 'percentage' }),
+		amount: MoneySchema,
+		hsCode: Type.Optional(Type.String())
+	})),
+	requiredDocuments: Type.Array(Type.String()),
+	estimatedClearanceTime: DurationRangeSchema, // Days
+	validUntil: Type.Number(),
+	metadata: Type.Object({
+		accuracy: AccuracySchema,
+		confidence: Type.Number({ minimum: 0, maximum: 1 }),
+		dataSource: SourceSchema,
+		calculatedAt: Type.Number(),
+		disclaimer: Type.String()
+	})
+})
+
+// ==========================================
+// Ride-Hailing Fare Types
+// ==========================================
+
+export const RideFareRequestSchema = Type.Object({
+	pickup: LocationInputSchema,
+	dropoff: LocationInputSchema,
+	vehicleClass: Type.Optional(Type.Union([
+		Type.Literal('ECONOMY'),
+		Type.Literal('STANDARD'),
+		Type.Literal('COMFORT'),
+		Type.Literal('PREMIUM'),
+		Type.Literal('LUXURY'),
+		Type.Literal('XL'),
+		Type.Literal('SUV')
+	])),
+	passengerCount: Type.Optional(Type.Number({ minimum: 1, maximum: 8 })),
+	requestTime: Type.Optional(Type.Number()),
+	includeNearbyDrivers: Type.Optional(Type.Boolean())
+})
+
+export const RideFareResultSchema = Type.Object({
+	estimatedFare: Type.Object({
+		baseFare: Type.Number(),
+		distanceFare: Type.Number(),
+		timeFare: Type.Number(),
+		surgeFare: Type.Number(),
+		bookingFee: Type.Number(),
+		totalBeforeSurge: Type.Number(),
+		totalAfterSurge: Type.Number(),
+		minimumFare: Type.Number(),
+		currency: Type.String()
+	}),
+	surgeInfo: Type.Object({
+		multiplier: Type.Number({ minimum: 1.0 }),
+		reason: Type.String(),
+		isActive: Type.Boolean()
+	}),
+	tripEstimate: Type.Object({
+		distance: DistanceSchema,
+		duration: DurationSchema,
+		durationConfidence: Type.Number({ minimum: 0, maximum: 1 })
+	}),
+	pickupEstimate: Type.Object({
+		eta: DurationSchema,
+		etaConfidence: Type.Number({ minimum: 0, maximum: 1 }),
+		nearbyDrivers: Type.Number({ minimum: 0 })
+	}),
+	vehicleClass: Type.String(),
+	validUntil: Type.Number(),
+	metadata: Type.Object({
+		accuracy: AccuracySchema,
+		confidence: Type.Number({ minimum: 0, maximum: 1 }),
+		dataSource: SourceSchema,
+		calculatedAt: Type.Number(),
+		disclaimer: Type.String()
+	})
+})
+
+// ==========================================
+// Temporal Types
+// ==========================================
+
+export const ETACalculationRequestSchema = Type.Object({
+	origin: LocationInputSchema,
+	destination: LocationInputSchema,
+	serviceLevel: ServiceLevelSchema,
+	transportMode: CoverageTransitModeSchema,
+	processingTime: Type.Optional(Type.Object({
+		warehouse: Type.Optional(DurationSchema), // Hours
+		customs: Type.Optional(DurationSchema)
+	})),
+	pickupTime: Type.Optional(DateTimeZoneSchema),
+	
+	// LSP Integration: Service processor context from order chain
+	processors: Type.Optional(Type.Object({
+		warehouse: Type.Optional(Type.Any({ description: 'Warehouse processor context' })),
+		carrier: Type.Optional(Type.Any({ description: 'Carrier processor context' })),
+		hub: Type.Optional(Type.Any({ description: 'Hub processor context' })),
+		broker: Type.Optional(Type.Any({ description: 'Customs broker processor context' }))
+	})),
+	
+	// Additional context for LSP spec lookups
+	itemCount: Type.Optional(Type.Number({ minimum: 1, description: 'Number of items for warehouse processing' })),
+	packageCount: Type.Optional(Type.Number({ minimum: 1, description: 'Number of packages for hub sorting' })),
+	hsCode: Type.Optional(Type.String({ description: 'Harmonized System code for customs' })),
+	
+	// Precision tier for distance/transit calculation
+	precision: Type.Optional(PrecisionTierSchema)
+})
+
+export const ETACalculationResultSchema = Type.Object({
+	estimatedDelivery: Type.Object({
+		earliest: DateTimeZoneSchema,
+		latest: DateTimeZoneSchema,
+		expected: DateTimeZoneSchema
+	}),
+	breakdown: Type.Object({
+		processingTime: Type.Intersect([
+			DurationSchema,
+			Type.Object({
+				dataSource: Type.Optional(Type.Union([
+					Type.Literal('LSP_SPECS'),
+					Type.Literal('ESTIMATE')
+				])),
+				confidence: Type.Optional(Type.Number({ minimum: 0, maximum: 1 }))
+			})
+		]),
+		transitTime: Type.Intersect([
+			DurationSchema,
+			Type.Object({
+				dataSource: Type.Optional(Type.Union([
+					Type.Literal('LSP_SPECS'),
+					Type.Literal('ESTIMATE'),
+					Type.Literal('EXTERNAL')
+				])),
+				confidence: Type.Optional(Type.Number({ minimum: 0, maximum: 1 }))
+			})
+		]),
+		hubTransfer: Type.Optional(Type.Intersect([
+			DurationSchema,
+			Type.Object({
+				dataSource: Type.Optional(Type.Union([
+					Type.Literal('LSP_SPECS'),
+					Type.Literal('ESTIMATE')
+				])),
+				confidence: Type.Optional(Type.Number({ minimum: 0, maximum: 1 }))
+			})
+		])),
+		customsClearance: Type.Optional(Type.Intersect([
+			DurationSchema,
+			Type.Object({
+				dataSource: Type.Optional(Type.Union([
+					Type.Literal('LSP_SPECS'),
+					Type.Literal('ESTIMATE')
+				])),
+				confidence: Type.Optional(Type.Number({ minimum: 0, maximum: 1 }))
+			})
+		])),
+		lastMileDelivery: DurationSchema,
+		bufferTime: DurationSchema
+	}),
+	confidence: Type.Object({
+		score: Type.Number({ minimum: 0, maximum: 100 }),
+		factors: Type.Array(Type.String())
+	}),
+	cutoffTime: Type.Optional(Type.Object({
+		nextAvailable: DateTimeZoneSchema,
+		serviceLevel: ServiceLevelSchema
+	})),
+	metadata: Type.Object({
+		accuracy: AccuracySchema,
+		calculatedAt: Type.Number(),
+		disclaimer: Type.String()
+	})
+})
+
+// ==========================================
+// Nearby Vehicle Search Types
+// ==========================================
+
+export const NearbySearchRequestSchema = Type.Object({
+	center: CoordinatesSchema,
+	scale: Type.Optional(Type.Number({ minimum: 0.1, description: 'Search radius in kilometers' })),
+	maxRetries: Type.Optional(Type.Number({ minimum: 0, maximum: 5 })),
+	maxResults: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+	maxDistance: Type.Optional(Type.Number({ minimum: 1000, description: 'Maximum search distance in meters' })),
+	status: Type.Optional(Type.Union([
+		Type.String(),
+		Type.Array(Type.String())
+	])),
+	vehicleType: Type.Optional(Type.String())
+})
+
+export const NearbyWithinBoundsRequestSchema = Type.Object({
+	northEast: CoordinatesSchema,
+	southWest: CoordinatesSchema,
+	status: Type.Optional(Type.Union([
+		Type.String(),
+		Type.Array(Type.String())
+	])),
+	vehicleType: Type.Optional(Type.String()),
+	maxResults: Type.Optional(Type.Number({ minimum: 1, maximum: 100 }))
+})
+
+export const NearestVehicleRequestSchema = Type.Object({
+	center: CoordinatesSchema,
+	count: Type.Optional(Type.Number({ minimum: 1, maximum: 50 })),
+	status: Type.Optional(Type.Union([
+		Type.String(),
+		Type.Array(Type.String())
+	])),
+	vehicleType: Type.Optional(Type.String()),
+	maxDistance: Type.Optional(Type.Number({ minimum: 1000 }))
+})
+
+export const NearbyVehicleResultSchema = Type.Object({
+	id: Type.String(),
+	type: Type.String(),
+	status: Type.String(),
+	location: CoordinatesSchema,
+	distance: Type.Optional(Type.Number({ description: 'Distance in meters' }))
+})
+
+export const NearbySearchResultSchema = Type.Object({
+	vehicles: Type.Array(NearbyVehicleResultSchema),
+	count: Type.Number(),
+	searchRadius: Type.Optional(Type.Number({ description: 'Actual search radius used in meters' })),
+	metadata: Type.Object({
+		searchCenter: CoordinatesSchema,
+		calculatedAt: Type.Number()
+	})
+})
+
+// ==========================================
+// Batch Distance Matrix Types
+// ==========================================
+
+export const BatchDistanceMatrixRequestSchema = Type.Object({
+	points: Type.Array(CoordinatesSchema, { minItems: 2, maxItems: 50 })
+})
+
+export const BatchDistanceMatrixEntrySchema = Type.Object({
+	i: Type.Number({ description: 'Index of first point' }),
+	j: Type.Number({ description: 'Index of second point' }),
+	distance: Type.Number({ description: 'Distance in kilometers' })
+})
+
+export const BatchDistanceMatrixResultSchema = Type.Object({
+	matrix: Type.Array(BatchDistanceMatrixEntrySchema),
+	unit: Type.Literal('km'),
+	calculatedAt: Type.Number()
+})
+
+// ==========================================
+// Savings Matrix Types (Clarke-Wright)
+// ==========================================
+
+export const SavingsMatrixRequestSchema = Type.Object({
+	depot: CoordinatesSchema,
+	dropoffs: Type.Array(CoordinatesSchema, { minItems: 2, maxItems: 50 })
+})
+
+export const SavingsEntrySchema = Type.Object({
+	i: Type.Number({ description: 'Index of first dropoff' }),
+	j: Type.Number({ description: 'Index of second dropoff' }),
+	savings: Type.Number({ description: 'Savings in kilometers if merged into one route' })
+})
+
+export const SavingsMatrixResultSchema = Type.Object({
+	savings: Type.Array(SavingsEntrySchema),
+	unit: Type.Literal('km'),
+	calculatedAt: Type.Number()
+})
+
+// ==========================================
+// Batch Geocoding Types
+// ==========================================
+
+export const BatchGeocodeRequestSchema = Type.Object({
+	locations: Type.Array(LocationInputSchema, { minItems: 1, maxItems: 25 })
+})
+
+export const BatchGeocodeEntrySchema = Type.Object({
+	index: Type.Number(),
+	location: LocationInputSchema,
+	coordinates: Type.Union([ CoordinatesSchema, Type.Null() ])
+})
+
+export const BatchGeocodeResultSchema = Type.Object({
+	results: Type.Array(BatchGeocodeEntrySchema),
+	resolvedCount: Type.Number({ minimum: 0 }),
+	calculatedAt: Type.Number()
+})
+
+// ==========================================
+// TypeScript Type Exports
+// ==========================================
+
+export type PrecisionTier = Static<typeof PrecisionTierSchema>
+export type DistanceCalculationRequest = Static<typeof DistanceCalculationRequestSchema>
+export type DistanceCalculationResult = Static<typeof DistanceCalculationResultSchema>
+export type ServiceType = Static<typeof ServiceTypeSchema>
+export type ZoneAssignmentRequest = Static<typeof ZoneAssignmentRequestSchema>
+export type ZoneAssignmentResult = Static<typeof ZoneAssignmentResultSchema>
+export type DeliveryFeesRequest = Static<typeof DeliveryFeesRequestSchema>
+export type DeliveryFeesResult = Static<typeof DeliveryFeesResultSchema>
+export type TransportFareRequest = Static<typeof TransportFareRequestSchema>
+export type TransportFareResult = Static<typeof TransportFareResultSchema>
+export type CrossBorderFareRequest = Static<typeof CrossBorderFareRequestSchema>
+export type CrossBorderFareResult = Static<typeof CrossBorderFareResultSchema>
+export type RideFareRequest = Static<typeof RideFareRequestSchema>
+export type RideFareResult = Static<typeof RideFareResultSchema>
+export type ETACalculationRequest = Static<typeof ETACalculationRequestSchema>
+export type ETACalculationResult = Static<typeof ETACalculationResultSchema>
+export type NearbySearchRequest = Static<typeof NearbySearchRequestSchema>
+export type NearbyWithinBoundsRequest = Static<typeof NearbyWithinBoundsRequestSchema>
+export type NearestVehicleRequest = Static<typeof NearestVehicleRequestSchema>
+export type NearbyVehicleResult = Static<typeof NearbyVehicleResultSchema>
+export type NearbySearchResult = Static<typeof NearbySearchResultSchema>
+export type BatchDistanceMatrixRequest = Static<typeof BatchDistanceMatrixRequestSchema>
+export type BatchDistanceMatrixResult = Static<typeof BatchDistanceMatrixResultSchema>
+export type SavingsMatrixRequest = Static<typeof SavingsMatrixRequestSchema>
+export type SavingsMatrixResult = Static<typeof SavingsMatrixResultSchema>
+export type BatchGeocodeRequest = Static<typeof BatchGeocodeRequestSchema>
+export type BatchGeocodeResult = Static<typeof BatchGeocodeResultSchema>
+
+// ─── Common Utilities RVS ─────────────────────────────────────────────────────
+
+export const UtilDistanceRVS = {
+	headers: APIHeadersSchema,
+	body: DistanceCalculationRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: DistanceCalculationResultSchema })
+	])
+}
+export type UtilDistanceValidation = {
+	body: Static<typeof UtilDistanceRVS.body>
+	response: Static<typeof UtilDistanceRVS.response>
+}
+
+export const UtilBatchDistanceMatrixRVS = {
+	headers: APIHeadersSchema,
+	body: BatchDistanceMatrixRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: BatchDistanceMatrixResultSchema })
+	])
+}
+export type UtilBatchDistanceMatrixValidation = {
+	body: Static<typeof UtilBatchDistanceMatrixRVS.body>
+	response: Static<typeof UtilBatchDistanceMatrixRVS.response>
+}
+
+export const UtilSavingsMatrixRVS = {
+	headers: APIHeadersSchema,
+	body: SavingsMatrixRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: SavingsMatrixResultSchema })
+	])
+}
+export type UtilSavingsMatrixValidation = {
+	body: Static<typeof UtilSavingsMatrixRVS.body>
+	response: Static<typeof UtilSavingsMatrixRVS.response>
+}
+
+export const UtilAssignZoneRVS = {
+	headers: APIHeadersSchema,
+	body: ZoneAssignmentRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: ZoneAssignmentResultSchema })
+	])
+}
+export type UtilAssignZoneValidation = {
+	body: Static<typeof UtilAssignZoneRVS.body>
+	response: Static<typeof UtilAssignZoneRVS.response>
+}
+
+export const UtilETARVS = {
+	headers: APIHeadersSchema,
+	body: ETACalculationRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: ETACalculationResultSchema })
+	])
+}
+export type UtilETAValidation = {
+	body: Static<typeof UtilETARVS.body>
+	response: Static<typeof UtilETARVS.response>
+}
+
+export const UtilBatchGeocodeRVS = {
+	headers: APIHeadersSchema,
+	body: BatchGeocodeRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: BatchGeocodeResultSchema })
+	])
+}
+export type UtilBatchGeocodeValidation = {
+	body: Static<typeof UtilBatchGeocodeRVS.body>
+	response: Static<typeof UtilBatchGeocodeRVS.response>
+}
+
+// ─── Fares RVS ────────────────────────────────────────────────────────────────
+
+export const UtilDeliveryFeesRVS = {
+	headers: APIHeadersSchema,
+	body: DeliveryFeesRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: DeliveryFeesResultSchema })
+	])
+}
+export type UtilDeliveryFeesValidation = {
+	body: Static<typeof UtilDeliveryFeesRVS.body>
+	response: Static<typeof UtilDeliveryFeesRVS.response>
+}
+
+export const UtilTransportFareRVS = {
+	headers: APIHeadersSchema,
+	body: TransportFareRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: TransportFareResultSchema })
+	])
+}
+export type UtilTransportFareValidation = {
+	body: Static<typeof UtilTransportFareRVS.body>
+	response: Static<typeof UtilTransportFareRVS.response>
+}
+
+export const UtilRideFareRVS = {
+	headers: APIHeadersSchema,
+	body: RideFareRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: RideFareResultSchema })
+	])
+}
+export type UtilRideFareValidation = {
+	body: Static<typeof UtilRideFareRVS.body>
+	response: Static<typeof UtilRideFareRVS.response>
+}
+
+export const UtilCrossBorderFareRVS = {
+	headers: APIHeadersSchema,
+	body: CrossBorderFareRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: CrossBorderFareResultSchema })
+	])
+}
+export type UtilCrossBorderFareValidation = {
+	body: Static<typeof UtilCrossBorderFareRVS.body>
+	response: Static<typeof UtilCrossBorderFareRVS.response>
+}
+
+// ─── Nearby RVS ───────────────────────────────────────────────────────────────
+
+export const UtilSearchNearbyRVS = {
+	headers: APIHeadersSchema,
+	body: NearbySearchRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: NearbySearchResultSchema })
+	])
+}
+export type UtilSearchNearbyValidation = {
+	body: Static<typeof UtilSearchNearbyRVS.body>
+	response: Static<typeof UtilSearchNearbyRVS.response>
+}
+
+export const UtilSearchInBoundsRVS = {
+	headers: APIHeadersSchema,
+	body: NearbyWithinBoundsRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: NearbySearchResultSchema })
+	])
+}
+export type UtilSearchInBoundsValidation = {
+	body: Static<typeof UtilSearchInBoundsRVS.body>
+	response: Static<typeof UtilSearchInBoundsRVS.response>
+}
+
+export const UtilFindNearestRVS = {
+	headers: APIHeadersSchema,
+	body: NearestVehicleRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ result: NearbySearchResultSchema })
+	])
+}
+export type UtilFindNearestValidation = {
+	body: Static<typeof UtilFindNearestRVS.body>
+	response: Static<typeof UtilFindNearestRVS.response>
+}