@de./types 1.0.0

package/src/aux/agents.ts

@@ -0,0 +1,542 @@
+import { Type, Static } from '@sinclair/typebox'
+import { ContextSchema } from '../context'
+import { ActionRecordSchema, DurationSchema, WeekDaySchema, TimeSchema, DateTimeZoneSchema } from '../time'
+import { DistanceSchema, CurrencySchema, WeightSchema, VolumeSchema } from '../measure'
+import { ContactsSchema, AddressSchema, RTLocationSchema, CoordinatesSchema } from '../geo'
+import { EntityGradeSchema, EntityBaseSchema, EntityStatusSchema, OperatingHoursSchema, OperatingModeSchema, RatingSchema } from '../entity'
+import {
+	APIErrorSchema,
+	APIHeadersSchema,
+	APIResponseBaseSchema,
+	APIResponseDataSchemaFactory
+} from '../api'
+
+export const AgentTypeSchema = Type.Union([
+  Type.Literal('DRIVER'),
+  Type.Literal('RIDER'),
+  Type.Literal('PILOTE'),
+  Type.Literal('CAPITAIN')
+])
+export const AgentLicenseViolationSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Union([
+    Type.Literal('SPEEDING'),
+    Type.Literal('RECKLESS_DRIVING'),
+    Type.Literal('DUI_DWI'),
+    Type.Literal('DISTRACTED_DRIVING'),
+    Type.Literal('HOURS_OF_SERVICE'),
+    Type.Literal('VEHICLE_INSPECTION'),
+    Type.Literal('WEIGHT_VIOLATION'),
+    Type.Literal('HAZMAT_VIOLATION'),
+    Type.Literal('LOG_BOOK_VIOLATION'),
+    Type.Literal('EQUIPMENT_VIOLATION'),
+    Type.Literal('DOCUMENTATION'),
+    Type.Literal('OTHER')
+  ]),
+  severity: Type.Union([
+    Type.Literal('MINOR'),
+    Type.Literal('MAJOR'),
+    Type.Literal('SEVERE'),
+    Type.Literal('OUT_OF_SERVICE')
+  ]),
+  date: Type.Number(),
+  location: Type.Optional(Type.String()),
+  description: Type.String({ maxLength: 500 }),
+  fineAmount: Type.Optional(Type.Number()),
+  points: Type.Optional(Type.Number()),
+  status: Type.Union([
+    Type.Literal('PENDING'),
+    Type.Literal('PAID'),
+    Type.Literal('CONTESTED'),
+    Type.Literal('DISMISSED'),
+    Type.Literal('RESOLVED')
+  ]),
+  impactOnOperations: Type.Object({
+    suspendLicense: Type.Boolean(),
+    restrictOperations: Type.Boolean(),
+    requiresTraining: Type.Boolean(),
+    affectsInsurance: Type.Boolean()
+  }),
+  resolution: Type.Optional(Type.Object({
+    date: Type.Number(),
+    method: Type.String(),
+    notes: Type.Optional(Type.String())
+  })),
+  recorded: ActionRecordSchema
+})
+export const AgentLicenseSchema = Type.Object({
+  type: Type.Union([
+    Type.Literal('REGULAR'),
+    Type.Literal('CDL_A'),
+    Type.Literal('CDL_B'),
+    Type.Literal('CDL_C'),
+    Type.Literal('MOTORCYCLE'),
+    Type.Literal('COMMERCIAL_PILOT'),
+    Type.Literal('CHAUFFEUR'),
+    Type.Literal('HAZMAT'),
+    Type.Literal('PASSENGER_TRANSPORT')
+  ]),
+  number: Type.String({
+    minLength: 5,
+    maxLength: 50,
+    description: 'Driver license or professional license number'
+  }),
+  issuingAuthority: Type.String({ description: 'State/Country that issued license' }),
+  issueDate: DateTimeZoneSchema,
+  expiry: DateTimeZoneSchema,
+  
+  // License status and restrictions
+  status: Type.Union([
+    Type.Literal('ACTIVE'),
+    Type.Literal('SUSPENDED'),
+    Type.Literal('REVOKED'),
+    Type.Literal('EXPIRED'),
+    Type.Literal('PROVISIONAL')
+  ]),
+  restrictions: Type.Array(Type.Union([
+    Type.Literal('CORRECTIVE_LENSES'),
+    Type.Literal('DAYLIGHT_ONLY'),
+    Type.Literal('NO_INTERSTATE'),
+    Type.Literal('AUTOMATIC_TRANSMISSION'),
+    Type.Literal('HEARING_AID'),
+    Type.Literal('PROSTHETIC_AID'),
+    Type.Literal('VEHICLE_SPECIFIC')
+  ])),
+  endorsements: Type.Array(Type.Union([
+    Type.Literal('PASSENGER'),
+    Type.Literal('SCHOOL_BUS'),
+    Type.Literal('HAZMAT'),
+    Type.Literal('TANK_VEHICLE'),
+    Type.Literal('DOUBLE_TRIPLE'),
+    Type.Literal('MOTORCYCLE')
+  ])),
+  
+  // Compliance tracking
+  medicalCertification: Type.Optional(Type.Object({
+    number: Type.String(),
+    expiry: Type.Number(),
+    restrictions: Type.Array(Type.String())
+  })),
+  renewalHistory: Type.Array(Type.Object({
+    date: Type.Number(),
+    previousExpiry: Type.Number(),
+    renewalType: Type.Union([
+      Type.Literal('STANDARD'),
+      Type.Literal('EARLY'),
+      Type.Literal('LATE'),
+      Type.Literal('REINSTATEMENT')
+    ])
+  })),
+  violations: Type.Array(AgentLicenseViolationSchema),
+  
+  // Point system tracking
+  points: Type.Object({
+    current: Type.Number({ minimum: 0 }),
+    lifetime: Type.Number({ minimum: 0 }),
+    lastReset: Type.Optional(Type.Number())
+  }),
+  // Verification and documentation
+  verification: Type.Object({
+    verified: Type.Boolean(),
+    by: Type.Optional(Type.String()),
+    at: DateTimeZoneSchema,
+    documentUrl: Type.Optional(Type.String()),
+    nextVerificationDue: Type.Optional(Type.Number())
+  }),
+  
+  added: ActionRecordSchema,
+  updated: Type.Optional(ActionRecordSchema)
+})
+export const AgentWalletSchema = Type.Object({
+  balance: Type.Number(),
+  earnings: Type.Optional(Type.Number()),
+  currency: CurrencySchema,
+  paymentOptions: Type.Object({
+    method: Type.String(),
+    accountNumber: Type.String(),
+    schedules: Type.Array(Type.Object({
+      day: Type.Optional(WeekDaySchema),
+      time: Type.Optional(TimeSchema)
+    }))
+  })
+})
+export const Agent2VehicleBindingSchema = Type.Object({
+  vid: Type.String(), // Vehicle ID
+  status: Type.Union([
+    Type.Literal('PENDING'),
+    Type.Literal('BINDED'),
+    Type.Literal('UNBINDED'),
+  ]),
+  isOwner: Type.Boolean(),
+  terms: Type.Array(Type.String()),
+  assigned: ActionRecordSchema,
+  confirmed: Type.Optional(ActionRecordSchema)
+})
+export const AgentCommunicationSchema = Type.Object({
+  languages: Type.Array(Type.String()),
+  notificationPreferences: Type.Object({
+    sms: Type.Boolean(),
+    email: Type.Boolean(),
+    push: Type.Boolean(),
+    calls: Type.Boolean()
+  }),
+  emergencyContact: ContactsSchema
+})
+export const AgentBackgroundCheckSchema = Type.Object({
+  status: Type.Union([
+    Type.Literal('PENDING'),
+    Type.Literal('APPROVED'),
+    Type.Literal('REJECTED'),
+    Type.Literal('EXPIRED')
+  ]),
+  completedAt: Type.Optional(Type.Number()),
+  expiryDate: Type.Optional(Type.Number()),
+  checkTypes: Type.Array(Type.Union([
+    Type.Literal('CRIMINAL'),
+    Type.Literal('DRIVING_RECORD'),
+    Type.Literal('EMPLOYMENT'),
+    Type.Literal('DRUG_TEST')
+  ]))
+})
+export const AgentTrainingStatusSchema = Type.Union([
+  Type.Literal('PENDING'),
+  Type.Literal('COMPLETED'),
+  Type.Literal('EXPIRED')
+])
+export const AgentTrainingSchema = Type.Object({
+  type: AgentTypeSchema,
+  status: AgentTrainingStatusSchema,
+  required: Type.Boolean(),
+  nextTrainingDue: Type.Optional(DateTimeZoneSchema),
+  courses: Type.Array(Type.Object({
+    id: Type.String(),
+    status: AgentTrainingStatusSchema,
+    completed: Type.Optional(DateTimeZoneSchema),
+    certificateUrl: Type.Optional(Type.String()),
+    expiry: Type.Optional(DateTimeZoneSchema)
+  })),
+  completed: Type.Optional(DateTimeZoneSchema),
+  expiry: Type.Optional(DateTimeZoneSchema)
+})
+export const AgentMedicalSchema = Type.Object({
+  fitnessForDuty: Type.Boolean(),
+  lastMedicalExam: Type.Optional(DateTimeZoneSchema),
+  nextExamDue: Type.Optional(DateTimeZoneSchema),
+  restrictions: Type.Array(Type.String()),
+  emergencyMedicalInfo: Type.Optional(Type.String())
+})
+export const AgentShiftsSchema = Type.Object({
+  current: Type.Optional(Type.String()),
+  preferred: Type.Array(Type.String()),
+  assignedRoutes: Type.Array(Type.String()),
+  routePreferences: Type.Array(Type.String())
+})
+
+// ---------------------------------------------------------------------------
+// Rally sub-document — stamped on RIDER agents by the Rally dispatch engine
+// ---------------------------------------------------------------------------
+export const AgentRallySchema = Type.Object({
+  zoneId: Type.Optional(Type.String({ description: 'Rally zone this agent is currently assigned to' })),
+  available: Type.Optional(Type.Boolean({ description: 'True when agent is in the active dispatch pool' })),
+  agentRole: Type.Optional(Type.String({ description: 'Agent capability role set by the consuming service (e.g. SHOPPER, DRIVER). Absent = unrestricted.' })),
+})
+export const AgentRallyStatusSchema = Type.Union([
+  Type.Literal('IDLE'),
+  Type.Literal('IN_TRANSIT'),
+  Type.Literal('DELIVERING'),
+  Type.Literal('AT_CONSOLIDATION_POINT'),
+  Type.Literal('CONSOLIDATING'),
+  Type.Literal('OFFLINE'),
+  Type.Literal('EMERGENCY')
+])
+
+export const AgentCommittedWaypointSchema = Type.Object({
+  position: CoordinatesSchema,
+  orderId: Type.Optional(Type.String()),
+  eta: DateTimeZoneSchema,
+  stopType: Type.Union([
+    Type.Literal('PICKUP'),
+    Type.Literal('BOARDING'),
+    Type.Literal('DELIVERY'),
+    Type.Literal('DROPOFF'),
+    Type.Literal('CONSOLIDATION_POINT'),
+    Type.Literal('DEPOT')
+  ])
+})
+export const AgentSnapshotSchema = Type.Object({
+  agentId: Type.String(),
+  position: RTLocationSchema,
+  status: AgentRallyStatusSchema,
+  committedWaypoints: Type.Array(AgentCommittedWaypointSchema),
+  packagesInCustody: Type.Array(Type.String()),
+  capacityRemaining: Type.Object({
+    weight: WeightSchema, // Kg
+    volume: VolumeSchema // cbm
+  }),
+  sessionNackCount: Type.Number({ minimum: 0 }), // resets each shift
+  cooldownUntil: Type.Optional(DateTimeZoneSchema), // no offers before this
+  slaSlack: Type.Optional(DurationSchema), // slack to tightest in-custody SLA (ms)
+  at: DateTimeZoneSchema
+})
+
+// Agent Schema (extends EntitySpecs)
+export const AgentSchema = Type.Composite([
+  EntityBaseSchema,
+  Type.Object({
+    type: AgentTypeSchema,
+    context: ContextSchema,
+    bio: Type.String({ maxLength: 1000 }),
+    contacts: ContactsSchema,
+    address: Type.Optional(AddressSchema),
+    license: AgentLicenseSchema,
+    vehicles: Type.Array(Agent2VehicleBindingSchema),
+    certifications: Type.Array(Type.Union([
+      Type.Literal('HAZMAT'),
+      Type.Literal('PASSENGER'),
+      Type.Literal('SCHOOL_BUS'),
+      Type.Literal('DOUBLE_TRIPLE'),
+      Type.Literal('TANK_VEHICLE'),
+      Type.Literal('DANGEROUS_GOODS'),
+      Type.Literal('FIRST_AID')
+    ])),
+    base: Type.String({ description: 'Hub or facility ID' }),
+    experience: DurationSchema, // Years
+    communication: AgentCommunicationSchema,
+    wallet: AgentWalletSchema,
+    rating: RatingSchema,
+    workingMode: OperatingModeSchema,
+    workingHours: Type.Optional(OperatingHoursSchema),
+    shifts: Type.Optional(AgentShiftsSchema),
+    medical: Type.Optional(AgentMedicalSchema),
+    training: Type.Optional(Type.Array(AgentTrainingSchema)),
+    backgroundCheck: Type.Optional(Type.Array(AgentBackgroundCheckSchema)),
+    // Rally fields — present on RIDER agents only
+    rally: Type.Optional(AgentRallySchema),
+    added: ActionRecordSchema,
+    updated: Type.Optional(ActionRecordSchema)
+  })
+])
+export const AgentProfileSchema = Type.Omit(AgentSchema, [
+  'context',
+  'license',
+  'vehicles',
+  'certifications',
+  'wallet',
+  'base', 'rating',
+  'workingHours',
+  'workingMode',
+  'shifts',
+  'medical',
+  'training',
+  'backgroundCheck',
+  'added', 'updated'
+], { additionalProperties: false })
+export const AgentUpdateSchema = Type.Partial(Type.Omit(AgentSchema, ['id', 'context', 'vehicles', 'wallet', 'rating', 'added', 'updated']))
+
+// Generate TypeScript type from schema
+export type Agent = Static<typeof AgentSchema>
+export type AgentProfile = Static<typeof AgentProfileSchema>
+export type AgentUpdate = Static<typeof AgentUpdateSchema>
+export type AgentLicense = Static<typeof AgentLicenseSchema>
+export type AgentWallet = Static<typeof AgentWalletSchema>
+export type Agent2VehicleBinding = Static<typeof Agent2VehicleBindingSchema>
+export type AgentTraining = Static<typeof AgentTrainingSchema>
+export type AgentCommunication = Static<typeof AgentCommunicationSchema>
+export type AgentBackgroundCheck = Static<typeof AgentBackgroundCheckSchema>
+export type AgentMedical = Static<typeof AgentMedicalSchema>
+export type AgentShifts = Static<typeof AgentShiftsSchema>
+
+// Additional utility schemas for agent management
+export const AgentStatusUpdateSchema = Type.Object({
+  agentId: Type.String(),
+  status: Type.Union([
+    Type.Literal('ACTIVE'),
+    Type.Literal('BUSY'),
+    Type.Literal('CLOSED'),
+    Type.Literal('SUSPENDED')
+  ]),
+  reason: Type.Optional(Type.String({ maxLength: 200 })),
+  updatedBy: Type.String(),
+  timestamp: Type.Number()
+})
+
+export const AgentLocationUpdateSchema = Type.Object({
+  agentId: Type.String(),
+  location: Type.Object({
+    lng: Type.Number(),
+    lat: Type.Number(),
+    heading: Type.Optional(Type.Number()),
+    altitude: Type.Optional(Type.Number()),
+    accuracy: Type.Optional(Type.Number())
+  }),
+  timestamp: Type.Number()
+})
+
+export const AgentPerformanceSchema = Type.Object({
+  agentId: Type.String(),
+  period: Type.Object({
+    start: Type.Number(),
+    end: Type.Number()
+  }),
+  metrics: Type.Object({
+    totalOrders: Type.Number({ minimum: 0 }),
+    completedOrders: Type.Number({ minimum: 0 }),
+    cancelledOrders: Type.Number({ minimum: 0 }),
+    averageRating: Type.Number({ minimum: 1, maximum: 5 }),
+    totalDistance: DistanceSchema, // Kilometers
+    averageDeliveryTime: DurationSchema, // Minutes
+    onTimeDeliveryRate: Type.Number({ minimum: 0, maximum: 100, description: 'Percentage' }),
+    customerComplaints: Type.Number({ minimum: 0 }),
+    activeHours: Type.Number({ minimum: 0, description: 'Hours worked' })
+  }),
+  rankings: Type.Optional(Type.Object({
+    overallRank: Type.Number({ minimum: 1 }),
+    categoryRanks: Type.Optional(Type.Record(Type.String(), Type.Number({ minimum: 1 }))),
+    totalAgents: Type.Number({ minimum: 1 })
+  }))
+})
+
+export const AgentAvailabilitySchema = Type.Object({
+  agentId: Type.String(),
+  available: Type.Boolean(),
+  currentOrder: Type.Optional(Type.String({ description: 'Current order reference' })),
+  estimatedFreeTime: Type.Optional(Type.Number({ description: 'Minutes until available' })),
+  workingHours: Type.Object({
+    start: Type.String({ 
+      pattern: '^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$',
+      description: '24h format, e.g. "08:00"'
+    }),
+    end: Type.String({ 
+      pattern: '^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$',
+      description: '24h format, e.g. "17:00"'
+    }),
+    timezone: Type.String({ description: 'IANA timezone' })
+  }),
+  breakSchedule: Type.Optional(Type.Array(Type.Object({
+    start: Type.String(),
+    end: Type.String(),
+    type: Type.Union([
+      Type.Literal('LUNCH'),
+      Type.Literal('REST'),
+      Type.Literal('MAINTENANCE')
+    ])
+  })))
+})
+
+export const AgentQuerySchema = Type.Object({
+  contextId: Type.Optional(Type.String()),
+  status: Type.Optional(Type.Array(Type.Union([
+    Type.Literal('ACTIVE'),
+    Type.Literal('BUSY'),
+    Type.Literal('CLOSED'),
+    Type.Literal('SUSPENDED')
+  ]))),
+  grade: Type.Optional(Type.Array(EntityGradeSchema)),
+  minRating: Type.Optional(Type.Number({ minimum: 1, maximum: 5 })),
+  hasVehicle: Type.Optional(Type.Boolean()),
+  available: Type.Optional(Type.Boolean()),
+  agentRole: Type.Optional(Type.String({ description: 'Filter agents by their Rally dispatch role (e.g. SHOPPER, DRIVER)' })),
+  nearLocation: Type.Optional(Type.Object({
+    lat: Type.Number(),
+    lng: Type.Number(),
+    radius: Type.Number({ minimum: 0.1, maximum: 100, description: 'Radius in kilometers' })
+  })),
+  limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100 })),
+  offset: Type.Optional(Type.Number({ minimum: 0 }))
+})
+
+export type AgentRally              = Static<typeof AgentRallySchema>
+export type AgentRallyStatus        = Static<typeof AgentRallyStatusSchema>
+export type AgentCommittedWaypoint  = Static<typeof AgentCommittedWaypointSchema>
+export type AgentSnapshot           = Static<typeof AgentSnapshotSchema>
+export type AgentStatusUpdate       = Static<typeof AgentStatusUpdateSchema>
+export type AgentLocationUpdate     = Static<typeof AgentLocationUpdateSchema>
+export type AgentPerformance        = Static<typeof AgentPerformanceSchema>
+export type AgentAvailability       = Static<typeof AgentAvailabilitySchema>
+export type AgentQuery              = Static<typeof AgentQuerySchema>
+
+// ─── Request Validation Schemas ───────────────────────────────────────────────
+
+export const AgentRetrieveQuerySchema = Type.Object({
+	verbose: Type.Optional(Type.Boolean())
+})
+
+export const AgentListQuerySchema = Type.Object({
+	status: Type.Optional(EntityStatusSchema),
+	limit:  Type.Optional(Type.Number({ minimum: 1, maximum: 200, default: 20 })),
+	offset: Type.Optional(Type.Number({ minimum: 0, default: 0 }))
+})
+
+export const AgentAssignVehicleBodySchema = Type.Omit(Agent2VehicleBindingSchema, ['status', 'assigned', 'confirmed'])
+
+export const AgentUnassignVehicleBodySchema = Type.Object({ vid: Type.String() })
+
+export const LSPAgentRetrieveRVS = {
+	headers:     APIHeadersSchema,
+	params:      Type.Object({ id: Type.String() }),
+	querystring: AgentRetrieveQuerySchema,
+	response: {
+		200:   APIResponseDataSchemaFactory({ agent: AgentProfileSchema }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPAgentListRVS = {
+	headers:     APIHeadersSchema,
+	querystring: AgentListQuerySchema,
+	response: {
+		200:   APIResponseDataSchemaFactory({
+			agents: Type.Array(AgentProfileSchema),
+			total:  Type.Number(),
+			limit:  Type.Number(),
+			offset: Type.Number()
+		}),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPAgentUpdateRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     AgentUpdateSchema,
+	response: {
+		200:   APIResponseDataSchemaFactory({ agent: AgentProfileSchema }),
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPAgentAssignVehicleRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     AgentAssignVehicleBodySchema,
+	response: {
+		200:   APIResponseBaseSchema,
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPAgentUnassignVehicleRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	body:     AgentUnassignVehicleBodySchema,
+	response: {
+		200:   APIResponseBaseSchema,
+		'4XX': APIErrorSchema
+	}
+}
+
+export const LSPAgentRemoveRVS = {
+	headers:  APIHeadersSchema,
+	params:   Type.Object({ id: Type.String() }),
+	response: {
+		200:   APIResponseBaseSchema,
+		'4XX': APIErrorSchema
+	}
+}
+
+export type LSPAgentRetrieveValidation        = { params: Static<typeof LSPAgentRetrieveRVS.params>, querystring: Static<typeof LSPAgentRetrieveRVS.querystring>, response: Static<(typeof LSPAgentRetrieveRVS.response)[200]> }
+export type LSPAgentListValidation            = { querystring: Static<typeof LSPAgentListRVS.querystring>, response: Static<(typeof LSPAgentListRVS.response)[200]> }
+export type LSPAgentUpdateValidation          = { params: Static<typeof LSPAgentUpdateRVS.params>, body: Static<typeof LSPAgentUpdateRVS.body>, response: Static<(typeof LSPAgentUpdateRVS.response)[200]> }
+export type LSPAgentAssignVehicleValidation   = { params: Static<typeof LSPAgentAssignVehicleRVS.params>, body: Static<typeof LSPAgentAssignVehicleRVS.body>, response: Static<(typeof LSPAgentAssignVehicleRVS.response)[200]> }
+export type LSPAgentUnassignVehicleValidation = { params: Static<typeof LSPAgentUnassignVehicleRVS.params>, body: Static<typeof LSPAgentUnassignVehicleRVS.body>, response: Static<(typeof LSPAgentUnassignVehicleRVS.response)[200]> }
+export type LSPAgentRemoveValidation          = { params: Static<typeof LSPAgentRemoveRVS.params>, response: Static<(typeof LSPAgentRemoveRVS.response)[200]> }