@de./types 1.0.0

package/src/entity.ts

@@ -0,0 +1,154 @@
+import { Type, Static } from '@sinclair/typebox'
+import { RTLocationSchema } from './geo'
+import { DateTimeZoneSchema, WeekDaySchema } from './time'
+import { SeverityLevelSchema } from './measure'
+
+// ─── Entity types ─────────────────────────────────────────────────────────────
+
+export const EntityTypeSchema = Type.Union([
+	// Mobile
+	Type.Literal('moto'),
+	Type.Literal('car'),
+	Type.Literal('bike'),
+	Type.Literal('truck'),
+	Type.Literal('plane'),
+	Type.Literal('ship'),
+	// Static
+	Type.Literal('restaurant'),
+	Type.Literal('hotel'),
+	Type.Literal('store'),
+	Type.Literal('office'),
+	Type.Literal('warehouse')
+])
+export const EntityStatusSchema = Type.Union([
+	Type.Literal('INACTIVE'),
+	Type.Literal('ACTIVE'),
+	Type.Literal('AVAILABLE'),
+	Type.Literal('ON_DUTY'),
+	Type.Literal('OFF_DUTY'),
+	Type.Literal('BREAK'),
+	Type.Literal('OPENED'),
+	Type.Literal('CLOSED'),
+	Type.Literal('SUSPENDED'),
+	Type.Literal('MAINTENANCE'),
+	Type.Literal('EXPANSION'),
+	Type.Literal('UPGRADE'),
+	Type.Literal('DECOMMISSIONED')
+])
+export const EntityGradeSchema = Type.Union([
+	Type.Literal('1H'),
+	Type.Literal('2H'),
+	Type.Literal('3H')
+])
+export const EntityBaseSchema = Type.Object({
+	id:              Type.String(),
+	status:          EntityStatusSchema,
+	grade:           EntityGradeSchema,
+	static:          Type.Optional(Type.Boolean()),
+	currentLocation: Type.Optional(RTLocationSchema),
+	utilization:     Type.Optional(Type.Number({ minimum: 0, maximum: 100 }))
+})
+
+// ─── Ratings ──────────────────────────────────────────────────────────────────
+
+export const RatingSchema = Type.Object({
+	standard: Type.Optional(Type.Number({ minimum: 1, maximum: 5, description: 'Performance rating' })),
+	safety:   Type.Optional(Type.Number({ minimum: 0, maximum: 100, description: 'Safety score' }))
+})
+
+// ─── Operating hours ──────────────────────────────────────────────────────────
+
+export const OperatingModeSchema = Type.Union([
+	Type.Literal('24_7'),
+	Type.Literal('BUSINESS_HOURS'),
+	Type.Literal('EXTENDED_HOURS'),
+	Type.Literal('SCHEDULED'),
+	Type.Literal('ON_DEMAND')
+])
+export const OperatingHoursSchema = Type.Object({
+	dayOfWeek: WeekDaySchema,
+	openTime:  Type.String({ pattern: '^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$', description: '24h HH:MM' }),
+	closeTime: Type.String({ pattern: '^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$', description: '24h HH:MM' }),
+	isClosed:  Type.Optional(Type.Boolean())
+})
+
+// ─── Compliance ───────────────────────────────────────────────────────────────
+
+export const ComplianceSchema = Type.Union([
+	Type.Literal('hazmat-certified'),
+	Type.Literal('food-grade'),
+	Type.Literal('climate-controlled')
+])
+export const ComplianceFlagSchema = Type.Union([
+	Type.Literal('FDA'),
+	Type.Literal('GDP')
+])
+
+// ─── Alerts & subscriptions ───────────────────────────────────────────────────
+
+export const AlertSchema = Type.Object({
+	type:     Type.String(),
+	severity: SeverityLevelSchema,
+	message:  Type.String(),
+	datetime: DateTimeZoneSchema
+})
+// export const SubscriptionSchema = Type.Object({
+// 	status:   Type.String(),
+// 	package:  Type.String(),
+// 	history:  Type.Array(Type.Any()),
+// 	datetime: DateTimeZoneSchema
+// })
+
+// ─── Nearby search ────────────────────────────────────────────────────────────
+
+export const NearbySearchQuerySchema = Type.Object({
+	center:        RTLocationSchema,
+	type:          EntityTypeSchema,
+	status:        Type.Optional(EntityStatusSchema),
+	grade:         Type.Optional(EntityGradeSchema),
+	scale:         Type.Optional(Type.Number({ description: 'Radius in km' })),
+	maxResults:    Type.Optional(Type.Number()),
+	maxDistance:   Type.Optional(Type.Number()),
+	maxRetries:    Type.Optional(Type.Number()),
+	scaleMultiplier: Type.Optional(Type.Number())
+})
+export const NearbyWithinBoundsQuerySchema = Type.Object({
+	northEast:  RTLocationSchema,
+	southWest:  RTLocationSchema,
+	status:     Type.Optional(Type.Union([
+		Type.String(),
+		Type.Object({ $in: Type.Array(Type.String()) })
+	])),
+	grade:      Type.Optional(EntityGradeSchema),
+	maxResults: Type.Optional(Type.Number())
+})
+export const NearestVehicleQuerySchema = Type.Object({
+	center:      RTLocationSchema,
+	count:       Type.Optional(Type.Number()),
+	status:      Type.Optional(Type.Union([
+		Type.String(),
+		Type.Object({ $in: Type.Array(Type.String()) })
+	])),
+	grade:       Type.Optional(EntityGradeSchema),
+	maxDistance: Type.Optional(Type.Number())
+})
+export const NearbySearchResultsSchema = Type.Array(EntityBaseSchema)
+
+// ─── TypeScript types ─────────────────────────────────────────────────────────
+
+export type EntityType            = Static<typeof EntityTypeSchema>
+export type EntityStatus          = Static<typeof EntityStatusSchema>
+export type EntityGrade           = Static<typeof EntityGradeSchema>
+export type EntityBase            = Static<typeof EntityBaseSchema>
+export type Rating                = Static<typeof RatingSchema>
+export type OperatingMode         = Static<typeof OperatingModeSchema>
+export type OperatingHours        = Static<typeof OperatingHoursSchema>
+export type Compliance            = Static<typeof ComplianceSchema>
+export type ComplianceFlag        = Static<typeof ComplianceFlagSchema>
+export type Alert                 = Static<typeof AlertSchema>
+// export type Subscription          = Static<typeof SubscriptionSchema>
+export type NearbySearchQuery     = Static<typeof NearbySearchQuerySchema>
+export type NearbyWithinBoundsQuery = Static<typeof NearbyWithinBoundsQuerySchema>
+export type NearestVehicleQuery   = Static<typeof NearestVehicleQuerySchema>
+export type NearbySearchResults   = Static<typeof NearbySearchResultsSchema>
+

package/src/events.ts

@@ -0,0 +1,349 @@
+import { Type, Static } from '@sinclair/typebox'
+import { RTLocationSchema, CoordinatesSchema } from './geo'
+import { ContextSchema } from './context'
+import { OrderAssigneeSchema } from './order'
+import { DateTimeZoneSchema } from './time'
+import { DeliveryRallyClientSchema, DeliveryDispatchableOrderSchema } from './lsp/order/delivery'
+import { AgentIdSchema, ZoneIdSchema, OfferIdSchema, CPointIdSchema, ConsolidationOfferSchema, ConsolidationPointSchema } from './lsp/consolidation'
+
+// ─── Order tracking events ────────────────────────────────────────────────────
+
+export const OrderEventTypeSchema = Type.Union([
+	Type.Literal('order.created'),
+	Type.Literal('order.updated'),
+	Type.Literal('order.assigned'),
+	Type.Literal('order.dispatched'),
+	Type.Literal('order.completed'),
+	Type.Literal('order.cancelled'),
+	Type.Literal('order.location.changed'),
+	Type.Literal('order.process.changed'),
+	Type.Literal('order.stage.changed'),
+	Type.Literal('order.status.changed')
+])
+export const OrderTrackingEventSchema = Type.Object({
+	event:     OrderEventTypeSchema,
+	reference: Type.String(),
+	status:    Type.String(),
+	stage:     Type.String(),
+	process:   Type.String(),
+	timestamp: Type.Number(),
+	location:  Type.Optional(Type.Intersect([
+		RTLocationSchema,
+		Type.Object({ updatedAt: Type.Number() })
+	])),
+	assignee:  Type.Optional(OrderAssigneeSchema),
+	eta:       Type.Optional(Type.Number({ description: 'Estimated arrival timestamp' })),
+	metadata:  Type.Optional(Type.Record(Type.String(), Type.Any()))
+})
+
+// ─── Rally events ─────────────────────────────────────────────────────────────
+// Contract for the `RALLY_EVENT` socket.io channel: everything pushed to the
+// `{workspace}:rally` room by Rally sub-systems (Batch, Dispatch, Balance,
+// Zones, Consolidation) is one of the discriminated variants below. External
+// services (socket `utype: 'service'`) consume these. Payloads mirror exactly
+// what de.arch emits — do not reshape without a coordinated de.arch change.
+
+export const RallyEventTypeSchema = Type.Union([
+	Type.Literal('rally.dispatch.offer'),
+	Type.Literal('rally.consolidation.offer'),
+	Type.Literal('rally.handoff.instruction'),
+	Type.Literal('rally.reallocation.offer'),
+	Type.Literal('rally.eta.update'),
+	Type.Literal('rally.custody.transferred'),
+	Type.Literal('rally.custody.unconfirmed'),
+	Type.Literal('rally.route.assigned'),
+	Type.Literal('rally.agent.freed'),
+	Type.Literal('rally.zone.split'),
+	Type.Literal('rally.zone.merged'),
+	Type.Literal('rally.zone.dormant'),
+	Type.Literal('rally.swarm.assigned'),
+	Type.Literal('rally.pod.bucket.fired'),
+	Type.Literal('rally.pod.unavailable')
+])
+
+// Rider receives a fully sequenced multi-order route (Dispatch)
+export const RallyDispatchOfferPayloadSchema = Type.Object({
+	offerId: OfferIdSchema,
+	riderId: Type.String(),
+	expiresAt: Type.String({ description: 'ISO-8601 — offer expiry' }),
+	orders: Type.Array(Type.Intersect([
+		DeliveryDispatchableOrderSchema,
+		Type.Object({ estimatedPickupAt: Type.String({ description: 'ISO-8601' }) })
+	]))
+})
+
+// Mid-route consolidation proposal (Consolidation engine)
+export const RallyConsolidationOfferPayloadSchema = Type.Object({
+	offerId: OfferIdSchema,
+	offer: ConsolidationOfferSchema
+})
+
+// Handoff instruction — three emitter variants coexist (de.arch wins policy):
+// relay legs (cross-zone), scheduled meetups (LSP consolidation routes) and
+// the consolidation state adapter. Discriminate on the fields present.
+export const RallyHandoffRelayPayloadSchema = Type.Object({
+	consolidationId: Type.String(),
+	leg: Type.Union([ Type.Literal(1), Type.Literal(2) ]),
+	orderRefs: Type.Array(Type.String()),
+	riderId: Type.String(),
+	counterpartRiderId: Type.String(),
+	handoffPoint: Type.Object({
+		name: Type.String(),
+		coordinates: CoordinatesSchema,
+		radiusMeters: Type.Number()
+	}),
+	handoffCode: Type.String({ description: 'Shared 4-digit code exchanged physically at handoff' }),
+	estimatedArrivalAt: Type.String({ description: 'ISO-8601' }),
+	instructions: Type.String()
+})
+export const RallyHandoffMeetupPayloadSchema = Type.Object({
+	consolidationId: Type.String(),
+	leg: Type.Union([ Type.Literal(1), Type.Literal(2) ]),
+	orderRefs: Type.Array(Type.String()),
+	riderId: Type.String(),
+	counterpartRiderId: Type.Optional(Type.String({ description: 'Set on leg 2' })),
+	counterpartRiderIds: Type.Optional(Type.Array(Type.String(), { description: 'Set on leg 1' })),
+	cpointId: CPointIdSchema,
+	scheduledAt: Type.String({ description: 'ISO-8601' }),
+	instructions: Type.String()
+})
+export const RallyHandoffAdapterPayloadSchema = Type.Object({
+	offerId: OfferIdSchema,
+	agentId: AgentIdSchema,
+	cpoint: ConsolidationPointSchema,
+	arriveBy: DateTimeZoneSchema
+})
+export const RallyHandoffInstructionPayloadSchema = Type.Union([
+	RallyHandoffRelayPayloadSchema,
+	RallyHandoffMeetupPayloadSchema,
+	RallyHandoffAdapterPayloadSchema
+])
+
+// Rider asked to move to a higher-demand zone (Balance)
+export const RallyReallocationOfferPayloadSchema = Type.Object({
+	riderId: Type.String(),
+	fromZoneId: Type.String(),
+	fromZoneName: Type.String(),
+	toZoneId: Type.String(),
+	toZoneName: Type.String(),
+	reason: Type.String({ description: "e.g. 'HIGH_DEMAND'" }),
+	targetDemand: Type.Number(),
+	sourceSupply: Type.Number(),
+	targetPool: Type.String({ description: "Rider pool — 'ANY' when unrestricted" }),
+	expiresAt: Type.Number({ description: 'Unix ms' })
+})
+
+// Per-order ETA push (Dispatch) — `client` echoes the consuming service's own
+// order reference + branch id, which is how external services route the event
+export const RallyEtaUpdatePayloadSchema = Type.Object({
+	orderRef: Type.String(),
+	client: DeliveryRallyClientSchema,
+	eta: Type.String({ description: 'ISO-8601 — estimated delivery time' }),
+	riderLocation: CoordinatesSchema
+})
+
+// Custody lifecycle (Consolidation)
+export const RallyCustodyTransferredPayloadSchema = Type.Object({
+	consolidationId: Type.String(),
+	orderRefs: Type.Array(Type.String()),
+	leg2RiderId: Type.String(),
+	message: Type.String()
+})
+export const RallyCustodyUnconfirmedPayloadSchema = Type.Object({
+	orderRef: Type.String(),
+	reason: Type.String(),
+	severity: Type.Union([ Type.Literal('low'), Type.Literal('medium'), Type.Literal('critical') ])
+})
+
+// Route confirmed after a rider accepts a dispatch/consolidation offer
+export const RallyRouteAssignedPayloadSchema = Type.Object({
+	offerId: Type.String(),
+	riderId: Type.String(),
+	orders: Type.Array(Type.Pick(DeliveryDispatchableOrderSchema, [ 'reference', 'pickup', 'dropoff' ]))
+})
+
+// Reserved — declared in the contract but not yet emitted by de.arch
+// (internal AGENT_FREED events stay on the CONSOLIDATION_EVENT channel)
+export const RallyAgentFreedPayloadSchema = Type.Object({
+	agentId: AgentIdSchema,
+	zoneId: ZoneIdSchema,
+	availableAt: DateTimeZoneSchema
+})
+
+// Zone reshaping (Zones)
+export const RallyZoneSplitPayloadSchema = Type.Object({
+	parentZoneId: Type.String(),
+	zoneA: Type.Object({ id: Type.String(), name: Type.String() }),
+	zoneB: Type.Object({ id: Type.String(), name: Type.String() })
+})
+export const RallyZoneMergedPayloadSchema = Type.Object({
+	sourceZoneIds: Type.Array(Type.String()),
+	newZone: Type.Object({ id: Type.String(), name: Type.String() })
+})
+export const RallyZoneDormantPayloadSchema = Type.Object({
+	zoneId: Type.String(),
+	reason: Type.String()
+})
+
+// Swarm + pod signals (Batch/Dispatch)
+export const RallySwarmAssignedPayloadSchema = Type.Object({
+	riderId: Type.String(),
+	orderCount: Type.Number(),
+	pool: Type.Literal('SWARM')
+})
+export const RallyPodBucketFiredPayloadSchema = Type.Object({
+	podId: Type.Optional(Type.String()),
+	orderCount: Type.Number()
+})
+export const RallyPodUnavailablePayloadSchema = Type.Object({
+	podId: Type.String(),
+	orderRef: Type.String(),
+	zoneId: Type.String()
+})
+
+// Discriminated event union — switch on `type` to narrow `payload`
+export const RallyDispatchOfferEventSchema = Type.Object({
+	type: Type.Literal('rally.dispatch.offer'),
+	payload: RallyDispatchOfferPayloadSchema
+})
+export const RallyConsolidationOfferEventSchema = Type.Object({
+	type: Type.Literal('rally.consolidation.offer'),
+	payload: RallyConsolidationOfferPayloadSchema
+})
+export const RallyHandoffInstructionEventSchema = Type.Object({
+	type: Type.Literal('rally.handoff.instruction'),
+	payload: RallyHandoffInstructionPayloadSchema
+})
+export const RallyReallocationOfferEventSchema = Type.Object({
+	type: Type.Literal('rally.reallocation.offer'),
+	payload: RallyReallocationOfferPayloadSchema
+})
+export const RallyEtaUpdateEventSchema = Type.Object({
+	type: Type.Literal('rally.eta.update'),
+	payload: RallyEtaUpdatePayloadSchema
+})
+export const RallyCustodyTransferredEventSchema = Type.Object({
+	type: Type.Literal('rally.custody.transferred'),
+	payload: RallyCustodyTransferredPayloadSchema
+})
+export const RallyCustodyUnconfirmedEventSchema = Type.Object({
+	type: Type.Literal('rally.custody.unconfirmed'),
+	payload: RallyCustodyUnconfirmedPayloadSchema
+})
+export const RallyRouteAssignedEventSchema = Type.Object({
+	type: Type.Literal('rally.route.assigned'),
+	payload: RallyRouteAssignedPayloadSchema
+})
+export const RallyAgentFreedEventSchema = Type.Object({
+	type: Type.Literal('rally.agent.freed'),
+	payload: RallyAgentFreedPayloadSchema
+})
+export const RallyZoneSplitEventSchema = Type.Object({
+	type: Type.Literal('rally.zone.split'),
+	payload: RallyZoneSplitPayloadSchema
+})
+export const RallyZoneMergedEventSchema = Type.Object({
+	type: Type.Literal('rally.zone.merged'),
+	payload: RallyZoneMergedPayloadSchema
+})
+export const RallyZoneDormantEventSchema = Type.Object({
+	type: Type.Literal('rally.zone.dormant'),
+	payload: RallyZoneDormantPayloadSchema
+})
+export const RallySwarmAssignedEventSchema = Type.Object({
+	type: Type.Literal('rally.swarm.assigned'),
+	payload: RallySwarmAssignedPayloadSchema
+})
+export const RallyPodBucketFiredEventSchema = Type.Object({
+	type: Type.Literal('rally.pod.bucket.fired'),
+	payload: RallyPodBucketFiredPayloadSchema
+})
+export const RallyPodUnavailableEventSchema = Type.Object({
+	type: Type.Literal('rally.pod.unavailable'),
+	payload: RallyPodUnavailablePayloadSchema
+})
+
+export const RallyEventSchema = Type.Union([
+	RallyDispatchOfferEventSchema,
+	RallyConsolidationOfferEventSchema,
+	RallyHandoffInstructionEventSchema,
+	RallyReallocationOfferEventSchema,
+	RallyEtaUpdateEventSchema,
+	RallyCustodyTransferredEventSchema,
+	RallyCustodyUnconfirmedEventSchema,
+	RallyRouteAssignedEventSchema,
+	RallyAgentFreedEventSchema,
+	RallyZoneSplitEventSchema,
+	RallyZoneMergedEventSchema,
+	RallyZoneDormantEventSchema,
+	RallySwarmAssignedEventSchema,
+	RallyPodBucketFiredEventSchema,
+	RallyPodUnavailableEventSchema
+])
+
+// ─── Location update ──────────────────────────────────────────────────────────
+
+export const LocationUpdateEventSchema = Type.Object({
+	orderReference: Type.String(),
+	agentId:        Type.String(),
+	context:        ContextSchema,
+	location:       RTLocationSchema,
+	eta:            Type.Optional(Type.Number({ description: 'Estimated arrival timestamp' }))
+})
+
+// ─── Messaging ────────────────────────────────────────────────────────────────
+
+export const MessageEventSchema = Type.Object({
+	orderReference: Type.String(),
+	from: Type.Object({
+		id:    Type.String(),
+		utype: Type.String(),
+		name:  Type.Optional(Type.String())
+	}),
+	body:      Type.String(),
+	timestamp: Type.Number()
+})
+
+// ─── Route change ─────────────────────────────────────────────────────────────
+
+export const RouteChangeEventSchema = Type.Object({
+	orderReference: Type.String(),
+	agentId:        Type.String(),
+	route:          Type.Array(Type.Tuple([Type.Number(), Type.Number()])),
+	timestamp:      Type.Number()
+})
+
+// ─── Presence ─────────────────────────────────────────────────────────────────
+
+export const PresenceEventSchema = Type.Object({
+	utype:     Type.String(),
+	id:        Type.String(),
+	status:    Type.Union([Type.Literal('online'), Type.Literal('offline')]),
+	timestamp: Type.Number()
+})
+
+// ─── TypeScript types ─────────────────────────────────────────────────────────
+
+export type OrderEventType        = Static<typeof OrderEventTypeSchema>
+export type OrderTrackingEvent    = Static<typeof OrderTrackingEventSchema>
+export type RallyEventType        = Static<typeof RallyEventTypeSchema>
+export type RallyEvent            = Static<typeof RallyEventSchema>
+export type RallyDispatchOfferPayload = Static<typeof RallyDispatchOfferPayloadSchema>
+export type RallyConsolidationOfferPayload = Static<typeof RallyConsolidationOfferPayloadSchema>
+export type RallyHandoffInstructionPayload = Static<typeof RallyHandoffInstructionPayloadSchema>
+export type RallyReallocationOfferPayload = Static<typeof RallyReallocationOfferPayloadSchema>
+export type RallyEtaUpdatePayload = Static<typeof RallyEtaUpdatePayloadSchema>
+export type RallyCustodyTransferredPayload = Static<typeof RallyCustodyTransferredPayloadSchema>
+export type RallyCustodyUnconfirmedPayload = Static<typeof RallyCustodyUnconfirmedPayloadSchema>
+export type RallyRouteAssignedPayload = Static<typeof RallyRouteAssignedPayloadSchema>
+export type RallyAgentFreedPayload = Static<typeof RallyAgentFreedPayloadSchema>
+export type RallyZoneSplitPayload = Static<typeof RallyZoneSplitPayloadSchema>
+export type RallyZoneMergedPayload = Static<typeof RallyZoneMergedPayloadSchema>
+export type RallyZoneDormantPayload = Static<typeof RallyZoneDormantPayloadSchema>
+export type RallySwarmAssignedPayload = Static<typeof RallySwarmAssignedPayloadSchema>
+export type RallyPodBucketFiredPayload = Static<typeof RallyPodBucketFiredPayloadSchema>
+export type RallyPodUnavailablePayload = Static<typeof RallyPodUnavailablePayloadSchema>
+export type LocationUpdateEvent   = Static<typeof LocationUpdateEventSchema>
+export type MessageEvent          = Static<typeof MessageEventSchema>
+export type RouteChangeEvent      = Static<typeof RouteChangeEventSchema>
+export type PresenceEvent         = Static<typeof PresenceEventSchema>

package/src/faq.ts

@@ -0,0 +1,39 @@
+import { Type, Static } from '@sinclair/typebox'
+import { ActionRecordSchema } from './time'
+import { ContextSchema, GenericServiceContextSchema } from './context'
+
+// ─── FAQ ──────────────────────────────────────────────────────────────────────
+
+export const FAQDefinitionStatusSchema = Type.Union([
+	Type.Literal('ACTIVE'),
+	Type.Literal('ARCHIVED'),
+	Type.Literal('DEPRECATED')
+])
+
+export const FAQDefinitionSchema = Type.Object({
+	context:   ContextSchema,
+	reference: Type.String(),
+	question:  Type.String(),
+	answer:    Type.String(),
+	version:   Type.String({
+		pattern:     '^20\\d{2}\\.(0[1-9]|1[0-2])(?:\\.(0[1-9]|[12]\\d|3[01]))?$',
+		description: 'Date-based version format — 2024.01 or 2024.12.15'
+	}),
+	status:   FAQDefinitionStatusSchema,
+	contexts: Type.Optional(Type.Array(GenericServiceContextSchema)),
+	source:   Type.Optional(Type.String({ format: 'uri' })),
+	tags:     Type.Optional(Type.Array(Type.String())),
+	locked:   Type.Boolean(),
+	added:    ActionRecordSchema,
+	updated:  Type.Optional(ActionRecordSchema)
+}, { additionalProperties: false })
+
+export const FAQDefinitionUpdateSchema = Type.Partial(
+	Type.Omit(FAQDefinitionSchema, ['reference', 'context', 'contexts', 'added', 'updated'])
+)
+
+// ─── TypeScript types ─────────────────────────────────────────────────────────
+
+export type FAQDefinitionStatus           = Static<typeof FAQDefinitionStatusSchema>
+export type FAQDefinition       = Static<typeof FAQDefinitionSchema>
+export type FAQDefinitionUpdate = Static<typeof FAQDefinitionUpdateSchema>

package/src/geo.ts

@@ -0,0 +1,111 @@
+import { Type, Static } from '@sinclair/typebox'
+import { DistanceSchema } from './measure'
+import { DateTimeZoneSchema } from './time'
+
+// ─── Coordinates ──────────────────────────────────────────────────────────────
+//
+// De. uses two coordinate representations:
+//   Coordinates — [lat, lng] tuple, De. internal convention (NOT GeoJSON order)
+//   RTLocation  — { lng, lat, ... } object, used for realtime tracking & SDK
+
+export const LatLng = Type.Readonly(Type.Tuple(
+	[Type.Number(), Type.Number()],
+	{ description: '[latitude, longitude]', example: [5.6037, -0.1870] }
+))
+export const CoordinatesSchema = Type.Readonly(Type.Object({
+	lat: Type.Number({ example: 48.8566 }),
+	lng: Type.Number({ example: 2.3522 })
+}))
+
+export const RTLocationSchema = Type.Object({
+	lng: Type.Number({ example: 2.3522 }),
+	lat: Type.Number({ example: 48.8566 }),
+	heading:  Type.Optional(Type.Number({ minimum: 0, maximum: 360, description: 'Degrees clockwise from north' })),
+	altitude: Type.Optional(Type.Number({ example: 35 })),
+	accuracy: Type.Optional(Type.Number({ minimum: 0, description: 'Metres' })),
+	speed:    Type.Optional(Type.Number({ example: 42 })),
+	at:       Type.Optional(DateTimeZoneSchema)
+})
+
+export const LocationInputSchema = Type.Object({
+	landmarkText: Type.Optional(Type.String()),
+	coordinates:  Type.Optional(CoordinatesSchema),
+	city:         Type.Optional(Type.String()),
+	country:      Type.String(),
+	zip:          Type.Optional(Type.String())
+})
+
+// ─── Address ──────────────────────────────────────────────────────────────────
+
+export const AddressSchema = Type.Object({
+	name:             Type.String({ example: 'Headquarters' }),
+	street1:          Type.String({ example: '12 Rue de Rivoli' }),
+	street2:          Type.Optional(Type.String({ example: 'Floor 3' })),
+	city:             Type.String({ example: 'Paris' }),
+	state:            Type.String({ example: 'Île-de-France' }),
+	coordinates:      CoordinatesSchema,
+	geocode:          Type.Optional(Type.String()),
+	postalCode:       Type.Optional(Type.String({ example: '75001' })),
+	country:          Type.String({ description: 'ISO 3166-1 alpha-2', example: 'FR' }),
+	isHeadquarter:    Type.Optional(Type.Boolean()),
+	isResidential:    Type.Optional(Type.Boolean()),
+	addressValidated: Type.Optional(Type.Boolean())
+})
+
+export const ContactsSchema = Type.Object({
+	name:   Type.Optional(Type.String({ example: 'Jean Dupont' })),
+	emails: Type.Array(Type.String({ format: 'email', example: 'contact@example.com' })),
+	phones: Type.Array(Type.String({ example: '+33612345678' }))
+})
+
+export const CompanySchema = Type.Object({
+	type:           Type.String(),
+	registrationId: Type.String(),
+	name:           Type.String(),
+	hqCountry:      Type.String()
+})
+
+// ─── Bounding areas ───────────────────────────────────────────────────────────
+
+export const BoundingBoxSchema = Type.Object({
+	minLat: Type.Number(),
+	maxLat: Type.Number(),
+	minLng: Type.Number(),
+	maxLng: Type.Number()
+})
+
+export const PolygonalBoundarySchema = Type.Object({
+	type:        Type.Literal('POLYGON'),
+	geofence:    Type.Boolean(),
+	coordinates: Type.Array(Type.Array(CoordinatesSchema))
+})
+export const CircularBoundarySchema = Type.Object({
+	type:     Type.Literal('CIRCLE'),
+	center:   CoordinatesSchema,
+	radius:   DistanceSchema,
+	geofence: Type.Boolean()
+})
+export const CustomBoundarySchema = Type.Object({
+	type:        Type.Literal('CUSTOM'),
+	areas:       Type.Array(Type.String()),
+	description: Type.Optional(Type.String())
+})
+export const GeoBoundarySchema = Type.Union([
+	PolygonalBoundarySchema,
+	CircularBoundarySchema,
+	CustomBoundarySchema
+])
+
+// ─── TypeScript types ─────────────────────────────────────────────────────────
+
+export type Coordinates        = Static<typeof CoordinatesSchema>
+export type RTLocation         = Static<typeof RTLocationSchema>
+export type LocationInput      = Static<typeof LocationInputSchema>
+export type Address            = Static<typeof AddressSchema>
+export type Contacts           = Static<typeof ContactsSchema>
+export type Company            = Static<typeof CompanySchema>
+export type BoundingBox        = Static<typeof BoundingBoxSchema>
+export type PolygonalBoundary  = Static<typeof PolygonalBoundarySchema>
+export type CircularBoundary   = Static<typeof CircularBoundarySchema>
+export type CustomBoundary     = Static<typeof CustomBoundarySchema>
+export type GeoBoundary        = Static<typeof GeoBoundarySchema>