@de./types 1.0.0

package/src/lsp/fleet/vehicle.ts

@@ -0,0 +1,381 @@
+import { Type, Static } from '@sinclair/typebox'
+import { ContextSchema } from '../../context'
+import { LSPServiceContextSchema } from '../..'
+import { ActionRecordSchema, DateTimeZoneSchema } from '../../time'
+import { DimensionsSchema, WeightSchema, VolumeSchema, DistanceSchema, MoneySchema } from '../../measure'
+import { AddressSchema, ContactsSchema } from '../../geo'
+import { EntityBaseSchema, EntityStatusSchema } from '../../entity'
+import {
+	APIHeadersSchema,
+	APIResponseBaseSchema,
+	APIResponseDataSchemaFactory
+} from '../../api'
+
+// Vehicle Type Schema
+export const VehicleTypeSchema = Type.Union([
+  // MICRO-MOBILITY
+  Type.Literal('BICYCLE'),
+  Type.Literal('E_BIKE'),
+  Type.Literal('SCOOTER'),
+  Type.Literal('E_SCOOTER'),
+  
+  // TWO/THREE-WHEELERS
+  Type.Literal('MOTORCYCLE'),
+  Type.Literal('RICKSHAW'),
+  Type.Literal('TRICYCLE'),
+  
+  // LIGHT VEHICLES
+  Type.Literal('CAR'),
+  Type.Literal('PICKUP_TRUCK'),
+  Type.Literal('VAN'),
+  Type.Literal('CARGO_VAN'),
+  
+  // PASSENGER TRANSPORT
+  Type.Literal('MINIBUS'),              // 8-20 passengers (Toyota Hiace)
+  Type.Literal('BUS'),                  // Standard city bus
+  Type.Literal('COACH'),                // Long-distance/charter bus
+  Type.Literal('ARTICULATED_BUS'),      // Bendy bus
+  Type.Literal('DOUBLE_DECKER_BUS'),
+  Type.Literal('TROLLEY'),              // Trotro-style minibus
+  
+  // LIGHT-MEDIUM TRUCKS
+  Type.Literal('TRUCK'),                // Generic truck
+  Type.Literal('BOX_TRUCK'),            // Straight truck/cube van
+  Type.Literal('FLATBED_TRUCK'),
+  Type.Literal('DUMP_TRUCK'),
+  Type.Literal('TOW_TRUCK'),
+  
+  // HEAVY TRUCKS
+  Type.Literal('TRACTOR_TRAILER'),      // Semi-truck with trailer
+  Type.Literal('SEMI_TRAILER'),         // Just the trailer
+  Type.Literal('CONTAINER_TRUCK'),
+  Type.Literal('TANKER_TRUCK'),
+  Type.Literal('REFRIGERATED_TRUCK'),   // Reefer truck
+  
+  // RAIL
+  Type.Literal('TRAIN'),                // Generic train
+  Type.Literal('FREIGHT_TRAIN'),
+  Type.Literal('PASSENGER_TRAIN'),
+  
+  // MARINE
+  Type.Literal('SHIP'),                 // Generic ship
+  Type.Literal('BARGE'),
+  Type.Literal('CONTAINER_SHIP'),
+  Type.Literal('TANKER_SHIP'),
+  Type.Literal('FERRY'),
+  
+  // AIRCRAFT
+  Type.Literal('CARGO_PLANE'),
+  Type.Literal('PASSENGER_PLANE'),
+  Type.Literal('HELICOPTER'),
+  Type.Literal('DRONE'),
+  
+  // SPECIALIZED/WAREHOUSE
+  Type.Literal('FORKLIFT'),
+  
+  // OTHER
+  Type.Literal('OTHER')
+])
+export const VehicleModeSchema = Type.Union([
+  // DRIVER/OPERATOR MODES
+  Type.Literal('MANUAL'),              // Human-driven/operated
+  Type.Literal('ASSISTED'),            // Driver assistance (cruise control, lane keep, etc.)
+  Type.Literal('SEMI_AUTONOMOUS'),     // Partial automation (Level 2-3)
+  Type.Literal('AUTONOMOUS'),          // Full self-driving (Level 4-5)
+  
+  // REMOTE OPERATION
+  Type.Literal('REMOTE_CONTROLLED'),   // Real-time remote operation
+  Type.Literal('TELEOPERATED'),        // Remote operation with delay tolerance
+  
+  // SPECIALIZED MODES
+  Type.Literal('PLATOONING'),          // Connected convoy/truck platooning
+  Type.Literal('GUIDED'),              // Track/rail/wire-guided (buses, trains)
+  
+  // POWER/PROPULSION
+  Type.Literal('ELECTRIC'),            // Battery electric
+  Type.Literal('HYBRID'),              // Hybrid electric
+  Type.Literal('HYDROGEN'),            // Hydrogen fuel cell
+  Type.Literal('ICE'),                 // Internal combustion engine
+  Type.Literal('PEDAL_POWERED'),       // Bicycle, rickshaw
+  Type.Literal('ANIMAL_POWERED'),      // Horse-drawn, etc.
+])
+
+// Vehicle Engine Schema
+export const VehicleEngineSchema = Type.Union([
+  // FOSSIL FUELS
+  Type.Literal('GASOLINE'),            // Petrol
+  Type.Literal('DIESEL'),
+  Type.Literal('NATURAL_GAS'),         // CNG/LNG
+  Type.Literal('LPG'),                 // Liquefied Petroleum Gas/Propane
+  Type.Literal('BIOFUEL'),             // Biodiesel, ethanol blends
+  
+  // ELECTRIC
+  Type.Literal('ELECTRIC'),            // Battery Electric Vehicle (BEV)
+  Type.Literal('HYBRID'),              // Hybrid Electric (HEV)
+  Type.Literal('PLUG_IN_HYBRID'),      // PHEV - can charge from grid
+  
+  // ALTERNATIVE
+  Type.Literal('HYDROGEN'),            // Hydrogen fuel cell
+  Type.Literal('SOLAR'),               // Solar-powered
+  
+  // NON-MOTORIZED
+  Type.Literal('PEDAL'),               // Human-powered (bicycles)
+  Type.Literal('ANIMAL'),              // Animal-powered (horses, donkeys)
+  Type.Literal('SAIL'),                // Wind-powered (sailing vessels)
+  
+  // OTHER
+  Type.Literal('OTHER'),
+  Type.Literal('UNKNOWN')
+])
+// Vehicle Condition Schema
+export const VehicleConditionSchema = Type.Union([
+  Type.Literal('EXCELLENT'),
+  Type.Literal('GOOD'),
+  Type.Literal('FAIR'),
+  Type.Literal('POOR')
+])
+// Vehicle Ownership Schema
+export const VehicleOwnershipSchema = Type.Union([
+  Type.Literal('OWNED'),
+  Type.Literal('RENTED'),
+  Type.Literal('LEASED')
+])
+export const VehicleOwnerSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Union([
+    Type.Literal('INDIVIDUAL'),
+    Type.Literal('COMPANY')
+  ]),
+  name: Type.String(),
+  contacts: ContactsSchema,
+  address: AddressSchema
+})
+
+// Vehicle Specs Schema
+export const VehicleSpecSchema = Type.Object({
+  mode: VehicleModeSchema,
+  engine: VehicleEngineSchema,
+  condition: VehicleConditionSchema,
+  VIN: Type.String({ 
+    minLength: 17, 
+    maxLength: 17,
+    pattern: '^[A-HJ-NPR-Z0-9]{17}$',
+    description: 'Vehicle Identification Number (17 characters)'
+  }),
+  brand: Type.String({ minLength: 1, maxLength: 50 }),
+  model: Type.String({ minLength: 1, maxLength: 50 }),
+  category: Type.String({ minLength: 1, maxLength: 30 }),
+  color: Type.String({ minLength: 1, maxLength: 30 }),
+  seats: Type.String({ minLength: 2 }),
+  
+  manufactured: Type.Number({ minimum: 1900, maximum: new Date().getFullYear() }),
+  registrationNumber: Type.String(),
+  mileage: Type.Optional(DistanceSchema),
+
+  maxWeightCapacity: WeightSchema,
+  maxVolumeCapacity: Type.Optional(VolumeSchema),
+  maxDimensionsCapacity: Type.Optional(DimensionsSchema),
+}, { additionalProperties: false })
+export const VehicleSpecUpdateSchema = Type.Partial(VehicleSpecSchema)
+
+export const VehicleIoTSchema = Type.Object({
+  device: Type.String({ minLength: 1, maxLength: 50 }),
+  mac: Type.String({ minLength: 1, maxLength: 50 }),
+  IMEI: Type.String({
+    pattern: '^[0-9]{15}$',
+    description: 'International Mobile Equipment Identity (15 digits)'
+  })
+}, { additionalProperties: false })
+export const VehicleIoTUpdateSchema = Type.Partial(VehicleIoTSchema)
+
+export const VehicleComplianceSchema = Type.Object({
+  insurance: Type.Object({
+    policyNumber: Type.String(),
+    provider: Type.String(),
+    coverageAmount: MoneySchema,
+    expiryDate: DateTimeZoneSchema,
+    status: Type.Union([
+      Type.Literal('ACTIVE'), 
+      Type.Literal('EXPIRED'), 
+      Type.Literal('SUSPENDED')
+    ])
+  }),
+
+  roadworthiness: Type.Object({
+    certificateNumber: Type.String(),
+    issuingAuthority: Type.String(),
+    issueDate: DateTimeZoneSchema,
+    expiryDate: DateTimeZoneSchema
+  }),
+
+  safetyInspection: Type.Object({
+    lastInspectionDate: DateTimeZoneSchema,
+    nextInspectionDate: DateTimeZoneSchema,
+    inspectorId: Type.String(),
+    status: Type.Union([
+      Type.Literal('PASSED'), 
+      Type.Literal('CONDITIONAL'), 
+      Type.Literal('FAILED')
+    ])
+  }),
+
+  maxPassengerCapacity: Type.Number({ minimum: 1 }),
+  accessibilityCompliant: Type.Boolean(),
+  emergencyEquipped: Type.Boolean(),
+
+  permits: Type.Array(Type.Object({
+    type: Type.String(),
+    number: Type.String(),
+    expiryDate: DateTimeZoneSchema
+  }))
+})
+export const VehicleComplianceUpdateSchema = Type.Partial(VehicleComplianceSchema)
+
+// Vehicle Schema
+export const VehicleSchema = Type.Composite([
+  EntityBaseSchema,
+  Type.Object({
+    type: VehicleTypeSchema,
+    context: ContextSchema,
+    service: Type.Optional(LSPServiceContextSchema),
+    fleetId: Type.String(),
+    specs: VehicleSpecSchema,
+    ownership: VehicleOwnershipSchema,
+    iot: Type.Optional(VehicleIoTSchema),
+    owners: Type.Optional(Type.Array(VehicleOwnerSchema)),
+    compliance: Type.Optional(VehicleComplianceSchema),
+    assignees: Type.Optional(Type.Array(Type.String())),
+    coverage: Type.Array(Type.String()),
+    lastRun: Type.Optional(DateTimeZoneSchema),
+    nextRun: Type.Optional(DateTimeZoneSchema),
+    added: ActionRecordSchema,
+    updated: Type.Optional(ActionRecordSchema)
+  }, { additionalProperties: false })
+])
+
+const OMIT_FIELDS = [
+  'context',
+  'id',
+  'service',
+  'fleetId',
+  'iot',
+  'compliance',
+  'static',
+  'assignees',
+  'coverage',
+  'lastRun',
+  'added',
+  'updated'
+]
+export const VehicleAddSchema = Type.Omit(VehicleSchema, OMIT_FIELDS)
+export const VehicleUpdateSchema = Type.Partial(VehicleAddSchema)
+
+// Generate TypeScript types from schemas
+export type VehicleCondition        = Static<typeof VehicleConditionSchema>
+export type VehicleEngine           = Static<typeof VehicleEngineSchema>
+export type VehicleType             = Static<typeof VehicleTypeSchema>
+export type VehicleSpec             = Static<typeof VehicleSpecSchema>
+export type VehicleSpecUpdate       = Static<typeof VehicleSpecUpdateSchema>
+export type VehicleIoT              = Static<typeof VehicleIoTSchema>
+export type VehicleIoTUpdate        = Static<typeof VehicleIoTUpdateSchema>
+export type VehicleCompliance       = Static<typeof VehicleComplianceSchema>
+export type VehicleComplianceUpdate = Static<typeof VehicleComplianceUpdateSchema>
+export type Vehicle                 = Static<typeof VehicleSchema>
+export type VehicleUpdate           = Static<typeof VehicleUpdateSchema>
+
+// ─── Request Validation Schemas ───────────────────────────────────────────────
+
+export const VehicleStatusUpdateBodySchema = Type.Object({
+	status: EntityStatusSchema,
+	reason: Type.Optional(Type.String({ maxLength: 500 }))
+})
+
+export const VehicleListQuerySchema = Type.Object({
+	status:    Type.Optional(EntityStatusSchema),
+	type:      Type.Optional(VehicleTypeSchema),
+	allocated: Type.Optional(Type.Boolean()),
+	fleetId:   Type.Optional(Type.String()),
+	limit:     Type.Optional(Type.Number({ minimum: 1, maximum: 200, default: 20 })),
+	offset:    Type.Optional(Type.Number({ minimum: 0, default: 0 }))
+})
+
+export const LSPVehicleAddRVS = {
+	headers:  APIHeadersSchema,
+	body:     VehicleAddSchema,
+	response: APIResponseDataSchemaFactory({ vehicleId: Type.String() })
+}
+
+export const LSPVehicleRetrieveRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	response: APIResponseDataSchemaFactory({ vehicle: VehicleSchema })
+}
+
+export const LSPVehicleListRVS = {
+	headers:     APIHeadersSchema,
+	querystring: VehicleListQuerySchema,
+	response: APIResponseDataSchemaFactory({
+		vehicles: Type.Array(VehicleSchema),
+		total:    Type.Number(),
+		limit:    Type.Number(),
+		offset:   Type.Number()
+	})
+}
+
+export const LSPVehicleUpdateStatusRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     VehicleStatusUpdateBodySchema,
+	response: APIResponseDataSchemaFactory({ vehicle: VehicleSchema })
+}
+
+export const LSPVehicleUpdateRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     VehicleUpdateSchema,
+	response: APIResponseDataSchemaFactory({ vehicle: VehicleSchema })
+}
+
+export const LSPVehicleUpdateSpecsRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     VehicleSpecUpdateSchema,
+	response: Type.Intersect([APIResponseBaseSchema, Type.Object({ specs: VehicleSpecSchema })])
+}
+
+export const LSPVehicleUpdateIoTRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     VehicleIoTUpdateSchema,
+	response: Type.Intersect([APIResponseBaseSchema, Type.Object({ iot: VehicleIoTSchema })])
+}
+
+export const LSPVehicleRemoveRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	response: APIResponseBaseSchema
+}
+
+export const LSPVehicleAllocateRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     LSPServiceContextSchema,
+	response: APIResponseBaseSchema
+}
+
+export const LSPVehicleDeallocateRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	response: APIResponseBaseSchema
+}
+
+export type LSPVehicleAddValidation          = { headers: Static<typeof LSPVehicleAddRVS.headers>, body: Static<typeof LSPVehicleAddRVS.body>, response: Static<typeof LSPVehicleAddRVS.response> }
+export type LSPVehicleRetrieveValidation     = { headers: Static<typeof LSPVehicleRetrieveRVS.headers>, params: Static<typeof LSPVehicleRetrieveRVS.params>, response: Static<typeof LSPVehicleRetrieveRVS.response> }
+export type LSPVehicleListValidation         = { headers: Static<typeof LSPVehicleListRVS.headers>, querystring: Static<typeof LSPVehicleListRVS.querystring>, response: Static<typeof LSPVehicleListRVS.response> }
+export type LSPVehicleUpdateStatusValidation = { headers: Static<typeof LSPVehicleUpdateStatusRVS.headers>, params: Static<typeof LSPVehicleUpdateStatusRVS.params>, body: Static<typeof LSPVehicleUpdateStatusRVS.body>, response: Static<typeof LSPVehicleUpdateStatusRVS.response> }
+export type LSPVehicleUpdateValidation       = { headers: Static<typeof LSPVehicleUpdateRVS.headers>, params: Static<typeof LSPVehicleUpdateRVS.params>, body: Static<typeof LSPVehicleUpdateRVS.body>, response: Static<typeof LSPVehicleUpdateRVS.response> }
+export type LSPVehicleUpdateSpecsValidation  = { headers: Static<typeof LSPVehicleUpdateSpecsRVS.headers>, params: Static<typeof LSPVehicleUpdateSpecsRVS.params>, body: Static<typeof LSPVehicleUpdateSpecsRVS.body>, response: Static<typeof LSPVehicleUpdateSpecsRVS.response> }
+export type LSPVehicleUpdateIoTValidation    = { headers: Static<typeof LSPVehicleUpdateIoTRVS.headers>, params: Static<typeof LSPVehicleUpdateIoTRVS.params>, body: Static<typeof LSPVehicleUpdateIoTRVS.body>, response: Static<typeof LSPVehicleUpdateIoTRVS.response> }
+export type LSPVehicleRemoveValidation       = { headers: Static<typeof LSPVehicleRemoveRVS.headers>, params: Static<typeof LSPVehicleRemoveRVS.params>, response: Static<typeof LSPVehicleRemoveRVS.response> }
+export type LSPVehicleAllocateValidation     = { headers: Static<typeof LSPVehicleAllocateRVS.headers>, params: Static<typeof LSPVehicleAllocateRVS.params>, body: Static<typeof LSPVehicleAllocateRVS.body>, response: Static<typeof LSPVehicleAllocateRVS.response> }
+export type LSPVehicleDeallocateValidation   = { headers: Static<typeof LSPVehicleDeallocateRVS.headers>, params: Static<typeof LSPVehicleDeallocateRVS.params>, response: Static<typeof LSPVehicleDeallocateRVS.response> }

package/src/lsp/graph.ts

@@ -0,0 +1,113 @@
+import { Type, Static } from '@sinclair/typebox'
+import { ContextSchema } from '../context'
+import { AddressSchema, CoordinatesSchema } from '../geo'
+
+export const GraphNodeTypeSchema = Type.Union([
+  Type.Literal('DELIVERY'),
+  Type.Literal('POI'),
+  Type.Literal('LANDMARK')
+])
+
+export const GraphPoiSchema = Type.Object({
+  externalId: Type.String(),
+  coordinates: CoordinatesSchema,
+  name: Type.String({ maxLength: 150 }),
+  street1: Type.Optional( Type.String({ maxLength: 200 }) ),
+  city: Type.Optional( Type.String({ maxLength: 100 }) ),
+  zoneId: Type.Optional(Type.String()),
+  agentNotes: Type.Optional( Type.Array( Type.String({ maxLength: 300 }) ) )
+})
+
+export const GraphNodeSchema = Type.Object({
+  id: Type.String(),
+  context: ContextSchema, // provenance — who contributed this node
+  coordinates: CoordinatesSchema, // [lat, lng] — app-layer convention
+  // [lng, lat] — GeoJSON
+  geoPoint: Type.Object({
+    type: Type.Literal('Point'),
+    coordinates: CoordinatesSchema
+  }),      
+  address: AddressSchema,
+  label: Type.String(),
+  deliveryCount: Type.Number(),
+  pickupCount: Type.Number(),
+  dropoffCount: Type.Number(),
+  isLandmark: Type.Boolean(),
+  zoneId: Type.Optional(Type.String()),
+  firstSeen: Type.Number(),
+  lastSeen: Type.Number(),
+  // Extended fields — present on poi and landmark nodes
+  nodeType: Type.Optional(GraphNodeTypeSchema),  // undefined treated as 'delivery' for backwards compatibility
+  externalId: Type.Optional(Type.String()),         // ID of the entity this node represents in the consuming service
+  aliases: Type.Optional(Type.Array(Type.String())),       // alternative names harvested from address free-text
+  agentNotes: Type.Optional(Type.Array(Type.String()))       // shared institutional knowledge contributed by agents (hours, directions, etc.)
+})
+
+export const GraphEdgeSchema = Type.Object({
+  id: Type.String(),
+  context: ContextSchema,                // provenance — who first observed this route
+  fromNodeId: Type.String(),
+  toNodeId: Type.String(),
+  sampleCount: Type.Number(),
+  avgDurationMs: Type.Number(),
+  avgDistanceKm: Type.Number(),
+  lastSeen: Type.Number()
+})
+
+export type GraphNodeType = Static<typeof GraphNodeTypeSchema>
+export type GraphPoi = Static<typeof GraphPoiSchema>
+export type GraphNode = Static<typeof GraphNodeSchema>
+export type GraphEdge = Static<typeof GraphEdgeSchema>
+
+// ─── Request Validation Schemas ───────────────────────────────────────────────
+
+import {
+	APIErrorSchema,
+	APIHeadersSchema,
+	APIResponseBaseSchema,
+	APIResponseDataSchemaFactory
+} from '../api'
+
+export const LSPGraphGetPoiRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ externalId: Type.String() }),
+	response: {
+		200:   APIResponseDataSchemaFactory({ node: GraphNodeSchema }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPGraphRegisterPoiRVS = {
+	headers:  APIHeadersSchema,
+	body:     GraphPoiSchema,
+	response: {
+		200:   APIResponseDataSchemaFactory({ nodeId: Type.String() }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPGraphNearestRVS = {
+	headers:     APIHeadersSchema,
+	querystring: Type.Object({
+		lat:      Type.Number({ description: 'Latitude of the search origin' }),
+		lng:      Type.Number({ description: 'Longitude of the search origin' }),
+		radiusKm: Type.Optional(Type.Number({ minimum: 0.05, maximum: 50, default: 0.5 }))
+	}),
+	response: {
+		200:   APIResponseDataSchemaFactory({ node: Type.Union([GraphNodeSchema, Type.Null()]) }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPGraphLandmarksRVS = {
+	headers:  APIHeadersSchema,
+	response: {
+		200:   APIResponseDataSchemaFactory({ landmarks: Type.Array(GraphNodeSchema), total: Type.Number() }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export type LSPGraphGetPoiValidation       = { params: Static<typeof LSPGraphGetPoiRVS.params>, response: Static<(typeof LSPGraphGetPoiRVS.response)[200]> }
+export type LSPGraphRegisterPoiValidation  = { body: Static<typeof LSPGraphRegisterPoiRVS.body>, response: Static<(typeof LSPGraphRegisterPoiRVS.response)[200]> }
+export type LSPGraphNearestValidation      = { querystring: Static<typeof LSPGraphNearestRVS.querystring>, response: Static<(typeof LSPGraphNearestRVS.response)[200]> }
+export type LSPGraphLandmarksValidation    = { response: Static<(typeof LSPGraphLandmarksRVS.response)[200]> }