@de./types 1.0.0

package/src/aux/agent-rvs.ts

@@ -0,0 +1,596 @@
+import { Type, Static } from '@sinclair/typebox'
+import {
+	AgentProfileSchema,
+	AgentUpdateSchema
+} from './agents'
+import { RTLocationSchema } from '../geo'
+import {
+	APIResponseBaseSchema,
+	APIResponseDataSchemaFactory,
+	APIHeadersSchema,
+	APIErrorSchema
+} from '../api'
+
+// ─── Shared sub-schemas ──────────────────────────────────────────────────
+
+const PickupDropoffSchema = Type.Object({
+	lat: Type.Number(),
+	lng: Type.Number()
+})
+
+const DispatchOrderSummarySchema = Type.Object({
+	reference: Type.String(),
+	pickup: PickupDropoffSchema,
+	dropoff: PickupDropoffSchema
+})
+
+// ─── Agent Index (availability, info, update) ────────────────────────────
+
+export const AgentAvailabilityRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ availability: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		Type.Object({ message: Type.Optional(Type.String()) })
+	])
+}
+export type AgentAvailabilityValidation = {
+	params: Static<typeof AgentAvailabilityRVS.params>
+	response: Static<typeof AgentAvailabilityRVS.response>
+}
+
+export const AgentInfoRVS = {
+	headers: APIHeadersSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ agent: AgentProfileSchema })
+	])
+}
+export type AgentInfoValidation = {
+	response: Static<typeof AgentInfoRVS.response>
+}
+
+export const AgentUpdateRVS = {
+	headers: APIHeadersSchema,
+	body: AgentUpdateSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ agent: AgentProfileSchema })
+	])
+}
+export type AgentUpdateValidation = {
+	body: Static<typeof AgentUpdateRVS.body>
+	response: Static<typeof AgentUpdateRVS.response>
+}
+
+// ─── Agent Dispatch (respond, rate) ──────────────────────────────────────
+
+export const AgentDispatchRespondRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		offerId: Type.String({ minLength: 1 }),
+		decision: Type.Union([
+			Type.Literal('ACCEPT'),
+			Type.Literal('DECLINE')
+		]),
+		reason: Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		Type.Object({
+			message: Type.Optional(Type.String()),
+			data: Type.Optional(APIResponseDataSchemaFactory({
+				orders: Type.Array(DispatchOrderSummarySchema)
+			}))
+		})
+	])
+}
+export type AgentDispatchRespondValidation = {
+	body: Static<typeof AgentDispatchRespondRVS.body>
+	response: Static<typeof AgentDispatchRespondRVS.response>
+}
+
+export const AgentDispatchRateRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		reference: Type.String({ minLength: 1 }),
+		entityId: Type.String({ minLength: 1 }),
+		entityType: Type.Union([
+			Type.Literal('rider'),
+			Type.Literal('sender')
+		]),
+		rating: Type.Number({ minimum: 1, maximum: 5 })
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			entityId: Type.String(),
+			rating: Type.Number()
+		})
+	])
+}
+export type AgentDispatchRateValidation = {
+	body: Static<typeof AgentDispatchRateRVS.body>
+	response: Static<typeof AgentDispatchRateRVS.response>
+}
+
+// ─── Agent Navigation (location, nearby) ────────────────────────────────
+
+export const AgentLocationRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		lng: Type.Number({ minimum: -180, maximum: 180 }),
+		lat: Type.Number({ minimum: -90, maximum: 90 }),
+		heading: Type.Optional(Type.Number({ minimum: 0, maximum: 360 })),
+		altitude: Type.Optional(Type.Number()),
+		accuracy: Type.Optional(Type.Number({ minimum: 0 })),
+		speed: Type.Optional(Type.Number({ minimum: 0 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		Type.Object({ message: Type.Optional(Type.String()) })
+	])
+}
+export type AgentLocationValidation = {
+	body: Static<typeof AgentLocationRVS.body>
+	response: Static<typeof AgentLocationRVS.response>
+}
+
+export const AgentNearbyRVS = {
+	headers: APIHeadersSchema,
+	querystring: Type.Object({
+		type: Type.Optional(Type.Union([
+			Type.Literal('vehicle'),
+			Type.Literal('hub')
+		], { default: 'vehicle', description: 'Entity type to search for' })),
+		vehicleType: Type.Optional(Type.String({ description: 'Filter by vehicle type' })),
+		status: Type.Optional(Type.String({ description: 'Filter by status' })),
+		radius: Type.Optional(Type.Number({ minimum: 0.1, maximum: 100, default: 5, description: 'Search radius in km' })),
+		limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 20 }))
+	}),
+	body: Type.Object({
+		lat: Type.Number({ minimum: -90, maximum: 90 }),
+		lng: Type.Number({ minimum: -180, maximum: 180 }),
+		bounds: Type.Optional(Type.Object({
+			northEast: RTLocationSchema,
+			southWest: RTLocationSchema
+		}, { description: 'If provided, searches within bounds instead of radius' }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			nearby: Type.Array(Type.Any()),
+			count: Type.Number()
+		})
+	])
+}
+export type AgentNearbyValidation = {
+	querystring: Static<typeof AgentNearbyRVS.querystring>
+	body: Static<typeof AgentNearbyRVS.body>
+	response: Static<typeof AgentNearbyRVS.response>
+}
+
+// ─── Agent Consolidation (respond, handoffConfirm) ──────────────────────
+
+const ConsolidationOrderSummarySchema = Type.Object({
+	reference: Type.String(),
+	pickup: PickupDropoffSchema,
+	dropoff: PickupDropoffSchema
+})
+
+export const AgentConsolidationRespondRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		offerId: Type.String({ minLength: 1 }),
+		decision: Type.Union([
+			Type.Literal('ACCEPT'),
+			Type.Literal('DECLINE')
+		]),
+		reason: Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		Type.Object({
+			message: Type.Optional(Type.String()),
+			data: Type.Optional(APIResponseDataSchemaFactory({
+				orders: Type.Array(ConsolidationOrderSummarySchema)
+			}))
+		})
+	])
+}
+export type AgentConsolidationRespondValidation = {
+	body: Static<typeof AgentConsolidationRespondRVS.body>
+	response: Static<typeof AgentConsolidationRespondRVS.response>
+}
+
+export const AgentConsolidationHandoffRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		consolidationId: Type.String({ minLength: 1 }),
+		handoffCode: Type.Integer({ minimum: 1000, maximum: 9999 })
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		Type.Object({ message: Type.Optional(Type.String()) })
+	])
+}
+export type AgentConsolidationHandoffValidation = {
+	body: Static<typeof AgentConsolidationHandoffRVS.body>
+	response: Static<typeof AgentConsolidationHandoffRVS.response>
+}
+
+// ─── Agent Reallocation (respond) ────────────────────────────────────────
+
+export const AgentReallocationRespondRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		fromZoneId: Type.String({ minLength: 1 }),
+		toZoneId: Type.String({ minLength: 1 }),
+		decision: Type.Union([
+			Type.Literal('ACCEPT'),
+			Type.Literal('DECLINE')
+		])
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		Type.Object({
+			message: Type.Optional(Type.String()),
+			data: Type.Optional(APIResponseDataSchemaFactory({
+				zoneId: Type.String()
+			}))
+		})
+	])
+}
+export type AgentReallocationRespondValidation = {
+	body: Static<typeof AgentReallocationRespondRVS.body>
+	response: Static<typeof AgentReallocationRespondRVS.response>
+}
+
+// ─── Agent Vendor (originStatusReport, registerPoi, addPoiNote) ─────────
+
+export const AgentOriginStatusReportRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		senderId: Type.String({ description: 'Origin-party ID (matches senderId on the order)' }),
+		orderRef: Type.String({ description: 'Order reference for traceability' }),
+		status: Type.Union([
+			Type.Literal('READY', { description: 'Origin party present and order can proceed' }),
+			Type.Literal('UNAVAILABLE', { description: 'Origin party closed / not operating' }),
+			Type.Literal('PARTIAL', { description: 'Partial availability — item or substitution issue' })
+		]),
+		note: Type.Optional(Type.String({ maxLength: 300, description: 'Optional knowledge note saved to the graph node' }))
+	}),
+	response: APIResponseBaseSchema
+}
+export type AgentOriginStatusReportValidation = {
+	body: Static<typeof AgentOriginStatusReportRVS.body>
+	response: Static<typeof AgentOriginStatusReportRVS.response>
+}
+
+export const AgentRegisterPoiRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		externalId: Type.String({ description: "Consuming service's own identifier for this location" }),
+		lat: Type.Number(),
+		lng: Type.Number(),
+		name: Type.String({ maxLength: 150 }),
+		street1: Type.Optional(Type.String({ maxLength: 200 })),
+		city: Type.Optional(Type.String({ maxLength: 100 })),
+		agentNotes: Type.Optional(Type.Array(Type.String({ maxLength: 300 }), { description: 'Initial knowledge notes (hours, directions, rush times)' }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			nodeId: Type.String({ description: 'Rally Graph node ID for this POI' })
+		})
+	])
+}
+export type AgentRegisterPoiValidation = {
+	body: Static<typeof AgentRegisterPoiRVS.body>
+	response: Static<typeof AgentRegisterPoiRVS.response>
+}
+
+export const AgentAddPoiNoteRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		nodeId: Type.String({ description: 'Rally Graph node ID' }),
+		note: Type.String({ minLength: 3, maxLength: 300 })
+	}),
+	response: APIResponseBaseSchema
+}
+export type AgentAddPoiNoteValidation = {
+	body: Static<typeof AgentAddPoiNoteRVS.body>
+	response: Static<typeof AgentAddPoiNoteRVS.response>
+}
+
+// ─── Agent Orders — Delivery (list, get, accept, updateStatus, reportIssue) ─
+
+export const AgentDeliveryListRVS = {
+	headers: APIHeadersSchema,
+	querystring: Type.Object({
+		status: Type.Optional(Type.Union([
+			Type.Literal('pending'),
+			Type.Literal('active'),
+			Type.Literal('completed'),
+			Type.Literal('all')
+		], { default: 'active' })),
+		limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 20 })),
+		offset: Type.Optional(Type.Number({ minimum: 0, default: 0 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orders: Type.Array(Type.Any()),
+			total: Type.Number(),
+			limit: Type.Number(),
+			offset: Type.Number()
+		})
+	])
+}
+export type AgentDeliveryListValidation = {
+	querystring: Static<typeof AgentDeliveryListRVS.querystring>
+	response: Static<typeof AgentDeliveryListRVS.response>
+}
+
+export const AgentDeliveryGetRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			order: Type.Any(),
+			jrtoken: Type.Optional(Type.String({ description: 'Join Room Token for real-time tracking' }))
+		})
+	])
+}
+export type AgentDeliveryGetValidation = {
+	params: Static<typeof AgentDeliveryGetRVS.params>
+	response: Static<typeof AgentDeliveryGetRVS.response>
+}
+
+export const AgentDeliveryAcceptRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ order: Type.Any() })
+	])
+}
+export type AgentDeliveryAcceptValidation = {
+	params: Static<typeof AgentDeliveryAcceptRVS.params>
+	response: Static<typeof AgentDeliveryAcceptRVS.response>
+}
+
+export const AgentDeliveryUpdateStatusRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		stage: Type.String({ description: 'Order stage to update' }),
+		status: Type.String({ description: 'New status for the stage' }),
+		location: Type.Optional(Type.Object({
+			lng: Type.Number(),
+			lat: Type.Number(),
+			heading: Type.Optional(Type.Number()),
+			accuracy: Type.Optional(Type.Number())
+		})),
+		notes: Type.Optional(Type.String({ maxLength: 500 })),
+		evidence: Type.Optional(Type.Object({
+			photos: Type.Optional(Type.Array(Type.String())),
+			signature: Type.Optional(Type.String()),
+			recipientName: Type.Optional(Type.String())
+		}))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ order: Type.Any() })
+	])
+}
+export type AgentDeliveryUpdateStatusValidation = {
+	params: Static<typeof AgentDeliveryUpdateStatusRVS.params>
+	body: Static<typeof AgentDeliveryUpdateStatusRVS.body>
+	response: Static<typeof AgentDeliveryUpdateStatusRVS.response>
+}
+
+export const AgentDeliveryReportIssueRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		type: Type.Union([
+			Type.Literal('DELAY'),
+			Type.Literal('DAMAGE'),
+			Type.Literal('MISSING_ITEMS'),
+			Type.Literal('ADDRESS_ISSUE'),
+			Type.Literal('RECIPIENT_UNAVAILABLE'),
+			Type.Literal('VEHICLE_BREAKDOWN'),
+			Type.Literal('WEATHER'),
+			Type.Literal('OTHER')
+		]),
+		severity: Type.Union([
+			Type.Literal('LOW'),
+			Type.Literal('MEDIUM'),
+			Type.Literal('HIGH'),
+			Type.Literal('CRITICAL')
+		]),
+		description: Type.String({ minLength: 10, maxLength: 1000 }),
+		location: Type.Optional(Type.Object({
+			lng: Type.Number(),
+			lat: Type.Number()
+		})),
+		photos: Type.Optional(Type.Array(Type.String())),
+		requiresSupport: Type.Boolean({ default: false })
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			issue: Type.Object({
+				id: Type.String(),
+				reference: Type.String(),
+				status: Type.String()
+			})
+		})
+	])
+}
+export type AgentDeliveryReportIssueValidation = {
+	params: Static<typeof AgentDeliveryReportIssueRVS.params>
+	body: Static<typeof AgentDeliveryReportIssueRVS.body>
+	response: Static<typeof AgentDeliveryReportIssueRVS.response>
+}
+
+// ─── Agent Orders — Shipping (list, get, accept, updateStatus, reportIssue) ─
+// Identical schema shapes to Delivery — shared RVS
+
+export const AgentShippingListRVS = AgentDeliveryListRVS
+export const AgentShippingGetRVS = AgentDeliveryGetRVS
+export const AgentShippingAcceptRVS = AgentDeliveryAcceptRVS
+export const AgentShippingUpdateStatusRVS = AgentDeliveryUpdateStatusRVS
+export const AgentShippingReportIssueRVS = AgentDeliveryReportIssueRVS
+
+// ─── Agent Orders — Ride (list, get, accept, start, complete, cancel) ────
+
+export const AgentRideListRVS = {
+	headers: APIHeadersSchema,
+	querystring: Type.Object({
+		status: Type.Optional(Type.Union([
+			Type.Literal('pending'),
+			Type.Literal('active'),
+			Type.Literal('completed'),
+			Type.Literal('all')
+		], { default: 'active' })),
+		limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 20 })),
+		offset: Type.Optional(Type.Number({ minimum: 0, default: 0 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			rides: Type.Array(Type.Any()),
+			total: Type.Number(),
+			limit: Type.Number(),
+			offset: Type.Number()
+		})
+	])
+}
+export type AgentRideListValidation = {
+	querystring: Static<typeof AgentRideListRVS.querystring>
+	response: Static<typeof AgentRideListRVS.response>
+}
+
+export const AgentRideGetRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			ride: Type.Any(),
+			jrtoken: Type.Optional(Type.String({ description: 'Join Room Token for real-time tracking' }))
+		})
+	])
+}
+export type AgentRideGetValidation = {
+	params: Static<typeof AgentRideGetRVS.params>
+	response: Static<typeof AgentRideGetRVS.response>
+}
+
+export const AgentRideAcceptRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		estimatedArrival: Type.Number({ description: 'Estimated arrival time in minutes' }),
+		currentLocation: Type.Object({
+			lng: Type.Number(),
+			lat: Type.Number()
+		})
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ ride: Type.Any() })
+	])
+}
+export type AgentRideAcceptValidation = {
+	params: Static<typeof AgentRideAcceptRVS.params>
+	body: Static<typeof AgentRideAcceptRVS.body>
+	response: Static<typeof AgentRideAcceptRVS.response>
+}
+
+export const AgentRideStartRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		location: Type.Object({
+			lng: Type.Number(),
+			lat: Type.Number()
+		}),
+		odometerReading: Type.Optional(Type.Number()),
+		notes: Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ ride: Type.Any() })
+	])
+}
+export type AgentRideStartValidation = {
+	params: Static<typeof AgentRideStartRVS.params>
+	body: Static<typeof AgentRideStartRVS.body>
+	response: Static<typeof AgentRideStartRVS.response>
+}
+
+export const AgentRideCompleteRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		location: Type.Object({
+			lng: Type.Number(),
+			lat: Type.Number()
+		}),
+		odometerReading: Type.Optional(Type.Number()),
+		actualFare: Type.Optional(Type.Number()),
+		paymentMethod: Type.Optional(Type.Union([
+			Type.Literal('CASH'),
+			Type.Literal('CARD'),
+			Type.Literal('WALLET'),
+			Type.Literal('OTHER')
+		])),
+		notes: Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ ride: Type.Any() })
+	])
+}
+export type AgentRideCompleteValidation = {
+	params: Static<typeof AgentRideCompleteRVS.params>
+	body: Static<typeof AgentRideCompleteRVS.body>
+	response: Static<typeof AgentRideCompleteRVS.response>
+}
+
+export const AgentRideCancelRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		reason: Type.Union([
+			Type.Literal('PASSENGER_NO_SHOW'),
+			Type.Literal('VEHICLE_ISSUE'),
+			Type.Literal('EMERGENCY'),
+			Type.Literal('PASSENGER_REQUESTED'),
+			Type.Literal('UNSAFE_LOCATION'),
+			Type.Literal('OTHER')
+		]),
+		notes: Type.String({ minLength: 10, maxLength: 500 })
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ ride: Type.Any() })
+	])
+}
+export type AgentRideCancelValidation = {
+	params: Static<typeof AgentRideCancelRVS.params>
+	body: Static<typeof AgentRideCancelRVS.body>
+	response: Static<typeof AgentRideCancelRVS.response>
+}
+
+// ─── Shipping validation types (aliases to Delivery) ────────────────────
+
+export type AgentShippingListValidation = AgentDeliveryListValidation
+export type AgentShippingGetValidation = AgentDeliveryGetValidation
+export type AgentShippingAcceptValidation = AgentDeliveryAcceptValidation
+export type AgentShippingUpdateStatusValidation = AgentDeliveryUpdateStatusValidation
+export type AgentShippingReportIssueValidation = AgentDeliveryReportIssueValidation