@venulog/phasing-engine-schemas 0.7.6-alpha.0 → 0.8.0-alpha.0

package/dist/simulation.js

@@ -0,0 +1,231 @@
+import { z } from './zod.js';
+import { SimulationMode, SimulationStatus } from './enums/simulationMode.js';
+import { createSuccessResponseSchema, createMessageDataResponseSchema } from './common.js';
+// ============================================================================
+// Enums as Zod schemas
+// ============================================================================
+export const simulationModeSchema = z.enum([
+    SimulationMode.ENTRY,
+    SimulationMode.EXIT,
+    SimulationMode.BOTH
+]);
+export const simulationStatusSchema = z.enum([
+    SimulationStatus.RUNNING,
+    SimulationStatus.STOPPED,
+    SimulationStatus.COMPLETED
+]);
+// ============================================================================
+// Start Simulation Request
+// ============================================================================
+export const startSimulationBodySchema = z
+    .object({
+    event_id: z.number().int().positive().openapi({
+        description: 'Event ID to simulate',
+        example: 1
+    }),
+    booking_ids: z
+        .array(z.number().int().positive())
+        .optional()
+        .openapi({
+        description: 'Specific booking IDs to simulate. If omitted, simulates all active bookings.',
+        example: [123, 124, 125]
+    }),
+    speed_kmh: z.number().min(5).max(50).default(20).openapi({
+        description: 'Simulated vehicle speed in km/h',
+        example: 20
+    }),
+    update_interval_ms: z.number().int().min(500).max(5000).default(1000).openapi({
+        description: 'Position update interval in milliseconds',
+        example: 1000
+    }),
+    mode: simulationModeSchema.default(SimulationMode.BOTH).openapi({
+        description: 'Which movements to simulate',
+        example: 'both'
+    })
+})
+    .openapi('StartSimulationBody');
+// ============================================================================
+// Start Simulation Response
+// ============================================================================
+export const startSimulationDataSchema = z
+    .object({
+    session_id: z.string().uuid().openapi({
+        description: 'Simulation session UUID',
+        example: '550e8400-e29b-41d4-a716-446655440000'
+    }),
+    event_id: z.number().int().positive().openapi({
+        description: 'Event ID',
+        example: 1
+    }),
+    booking_ids: z.array(z.number().int().positive()).openapi({
+        description: 'Booking IDs being simulated',
+        example: [123, 124, 125]
+    }),
+    speed_kmh: z.number().openapi({
+        description: 'Simulation speed',
+        example: 20
+    }),
+    update_interval_ms: z.number().int().openapi({
+        description: 'Update interval',
+        example: 1000
+    }),
+    mode: simulationModeSchema.openapi({
+        description: 'Simulation mode'
+    }),
+    started_at: z.string().datetime().openapi({
+        description: 'When simulation started',
+        example: '2026-01-04T12:34:56Z'
+    })
+})
+    .openapi('StartSimulationData');
+export const startSimulationResponseSchema = createMessageDataResponseSchema(startSimulationDataSchema, 'StartSimulationResponse', 'Simulation started successfully', 'Simulation session details');
+// ============================================================================
+// Stop Simulation Request
+// ============================================================================
+export const stopSimulationBodySchema = z
+    .object({
+    session_id: z.string().uuid().optional().openapi({
+        description: 'Specific session to stop. If omitted, stops all sessions for event.',
+        example: '550e8400-e29b-41d4-a716-446655440000'
+    }),
+    event_id: z.number().int().positive().optional().openapi({
+        description: 'Stop all simulations for this event',
+        example: 1
+    })
+})
+    .refine((data) => data.session_id || data.event_id, {
+    message: 'Either session_id or event_id must be provided'
+})
+    .openapi('StopSimulationBody');
+// ============================================================================
+// Stop Simulation Response
+// ============================================================================
+export const stopSimulationDataSchema = z
+    .object({
+    sessions_stopped: z.number().int().min(0).openapi({
+        description: 'Number of sessions stopped',
+        example: 1
+    }),
+    session_ids: z.array(z.string().uuid()).openapi({
+        description: 'IDs of stopped sessions',
+        example: ['550e8400-e29b-41d4-a716-446655440000']
+    })
+})
+    .openapi('StopSimulationData');
+export const stopSimulationResponseSchema = createMessageDataResponseSchema(stopSimulationDataSchema, 'StopSimulationResponse', 'Simulation stopped successfully', 'Stopped session details');
+// ============================================================================
+// Simulation Session (for status display)
+// ============================================================================
+export const simulationSessionSchema = z
+    .object({
+    id: z.string().uuid().openapi({
+        description: 'Session UUID'
+    }),
+    event_id: z.number().int().positive().openapi({
+        description: 'Event ID'
+    }),
+    speed_kmh: z.number().openapi({
+        description: 'Simulation speed'
+    }),
+    update_interval_ms: z.number().int().openapi({
+        description: 'Update interval'
+    }),
+    mode: simulationModeSchema.openapi({
+        description: 'Simulation mode'
+    }),
+    booking_ids: z.array(z.number().int().positive()).openapi({
+        description: 'Bookings being simulated'
+    }),
+    status: simulationStatusSchema.openapi({
+        description: 'Current status'
+    }),
+    started_at: z.string().datetime().openapi({
+        description: 'Start time'
+    }),
+    stopped_at: z.string().datetime().nullable().openapi({
+        description: 'Stop time (if stopped)'
+    }),
+    positions_generated: z.number().int().min(0).openapi({
+        description: 'Number of position updates generated'
+    })
+})
+    .openapi('SimulationSession');
+// ============================================================================
+// Get Simulation Status Query
+// ============================================================================
+export const getSimulationStatusQuerySchema = z
+    .object({
+    event_id: z
+        .string()
+        .transform((val) => parseInt(val, 10))
+        .pipe(z.number().int().positive())
+        .optional()
+        .openapi({
+        description: 'Filter by event ID',
+        example: '1'
+    }),
+    include_completed: z
+        .string()
+        .optional()
+        .default('false')
+        .transform((val) => val === 'true')
+        .openapi({
+        description: 'Include completed sessions',
+        example: 'false'
+    })
+})
+    .openapi('GetSimulationStatusQuery');
+// ============================================================================
+// Get Simulation Status Response
+// ============================================================================
+export const simulationStatusDataSchema = z
+    .object({
+    active: z.boolean().openapi({
+        description: 'Whether any simulations are running',
+        example: true
+    }),
+    sessions: z.array(simulationSessionSchema).openapi({
+        description: 'List of simulation sessions'
+    }),
+    total_active: z.number().int().min(0).openapi({
+        description: 'Total number of active sessions',
+        example: 2
+    })
+})
+    .openapi('SimulationStatusData');
+export const getSimulationStatusResponseSchema = createSuccessResponseSchema(simulationStatusDataSchema, 'GetSimulationStatusResponse', 'Simulation status');
+// ============================================================================
+// Path Point (for path calculation)
+// ============================================================================
+export const pathPointSchema = z
+    .object({
+    x: z.number().min(0).max(100).openapi({
+        description: 'X coordinate on site plan (0-100%)'
+    }),
+    y: z.number().min(0).max(100).openapi({
+        description: 'Y coordinate on site plan (0-100%)'
+    }),
+    distance_from_start: z.number().min(0).openapi({
+        description: 'Distance from path start in meters'
+    })
+})
+    .openapi('PathPoint');
+// ============================================================================
+// Simulated Path
+// ============================================================================
+export const simulatedPathSchema = z
+    .object({
+    booking_id: z.number().int().positive().openapi({
+        description: 'Booking ID'
+    }),
+    points: z.array(pathPointSchema).openapi({
+        description: 'Path waypoints'
+    }),
+    total_distance: z.number().min(0).openapi({
+        description: 'Total path distance in meters'
+    }),
+    estimated_duration: z.number().min(0).openapi({
+        description: 'Estimated duration in seconds at configured speed'
+    })
+})
+    .openapi('SimulatedPath');

package/dist/vehiclePosition.d.ts

@@ -0,0 +1,216 @@
+import { z } from './zod.js';
+import { PositionSource } from './enums/positionSource.js';
+import { VehicleState } from './enums/vehicleState.js';
+import { VehicleType } from './enums/vehicleType.js';
+export declare const positionSourceSchema: z.ZodEnum<{
+    gps: PositionSource.GPS;
+    simulated: PositionSource.SIMULATED;
+    inferred: PositionSource.INFERRED;
+    manual: PositionSource.MANUAL;
+}>;
+export declare const vehicleStateSchema: z.ZodEnum<{
+    booked: VehicleState.BOOKED;
+    approaching: VehicleState.APPROACHING;
+    at_gate: VehicleState.AT_GATE;
+    entering: VehicleState.ENTERING;
+    parked: VehicleState.PARKED;
+    departing: VehicleState.DEPARTING;
+    at_exit: VehicleState.AT_EXIT;
+    exited: VehicleState.EXITED;
+    historical: VehicleState.HISTORICAL;
+}>;
+export declare const sitePlanPositionSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    heading: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SitePlanPosition = z.infer<typeof sitePlanPositionSchema>;
+export declare const gpsCoordinatesSchema: z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+}, z.core.$strip>;
+export type GpsCoordinates = z.infer<typeof gpsCoordinatesSchema>;
+export declare const reportPositionBodySchema: z.ZodObject<{
+    booking_id: z.ZodNumber;
+    access_token: z.ZodString;
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    heading: z.ZodOptional<z.ZodNumber>;
+    speed_kmh: z.ZodOptional<z.ZodNumber>;
+    accuracy_meters: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReportPositionBody = z.infer<typeof reportPositionBodySchema>;
+export declare const reportPositionDataSchema: z.ZodObject<{
+    position_id: z.ZodString;
+    received_at: z.ZodString;
+    site_plan_position: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        heading: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReportPositionData = z.infer<typeof reportPositionDataSchema>;
+export declare const reportPositionResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    data: z.ZodObject<{
+        position_id: z.ZodString;
+        received_at: z.ZodString;
+        site_plan_position: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            heading: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ReportPositionResponse = z.infer<typeof reportPositionResponseSchema>;
+export declare const vehiclePositionSchema: z.ZodObject<{
+    booking_id: z.ZodNumber;
+    license_plate: z.ZodString;
+    vehicle_type: z.ZodEnum<{
+        PL: VehicleType.PL;
+        VUL: VehicleType.VUL;
+        VL: VehicleType.VL;
+    }>;
+    company_name: z.ZodString;
+    stand_number: z.ZodOptional<z.ZodString>;
+    state: z.ZodEnum<{
+        booked: VehicleState.BOOKED;
+        approaching: VehicleState.APPROACHING;
+        at_gate: VehicleState.AT_GATE;
+        entering: VehicleState.ENTERING;
+        parked: VehicleState.PARKED;
+        departing: VehicleState.DEPARTING;
+        at_exit: VehicleState.AT_EXIT;
+        exited: VehicleState.EXITED;
+        historical: VehicleState.HISTORICAL;
+    }>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        heading: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    speed_kmh: z.ZodOptional<z.ZodNumber>;
+    parking_area_id: z.ZodOptional<z.ZodNumber>;
+    parking_area_name: z.ZodOptional<z.ZodString>;
+    entry_time: z.ZodNullable<z.ZodString>;
+    last_updated: z.ZodString;
+    source: z.ZodEnum<{
+        gps: PositionSource.GPS;
+        simulated: PositionSource.SIMULATED;
+        inferred: PositionSource.INFERRED;
+        manual: PositionSource.MANUAL;
+    }>;
+}, z.core.$strip>;
+export type VehiclePosition = z.infer<typeof vehiclePositionSchema>;
+export declare const getVehiclePositionsQuerySchema: z.ZodObject<{
+    since: z.ZodOptional<z.ZodString>;
+    include_historical: z.ZodPipe<z.ZodDefault<z.ZodOptional<z.ZodString>>, z.ZodTransform<boolean, string>>;
+    state: z.ZodOptional<z.ZodEnum<{
+        booked: VehicleState.BOOKED;
+        approaching: VehicleState.APPROACHING;
+        at_gate: VehicleState.AT_GATE;
+        entering: VehicleState.ENTERING;
+        parked: VehicleState.PARKED;
+        departing: VehicleState.DEPARTING;
+        at_exit: VehicleState.AT_EXIT;
+        exited: VehicleState.EXITED;
+        historical: VehicleState.HISTORICAL;
+    }>>;
+}, z.core.$strip>;
+export type GetVehiclePositionsQuery = z.infer<typeof getVehiclePositionsQuerySchema>;
+export declare const vehiclePositionsDataSchema: z.ZodObject<{
+    event_id: z.ZodNumber;
+    positions: z.ZodArray<z.ZodObject<{
+        booking_id: z.ZodNumber;
+        license_plate: z.ZodString;
+        vehicle_type: z.ZodEnum<{
+            PL: VehicleType.PL;
+            VUL: VehicleType.VUL;
+            VL: VehicleType.VL;
+        }>;
+        company_name: z.ZodString;
+        stand_number: z.ZodOptional<z.ZodString>;
+        state: z.ZodEnum<{
+            booked: VehicleState.BOOKED;
+            approaching: VehicleState.APPROACHING;
+            at_gate: VehicleState.AT_GATE;
+            entering: VehicleState.ENTERING;
+            parked: VehicleState.PARKED;
+            departing: VehicleState.DEPARTING;
+            at_exit: VehicleState.AT_EXIT;
+            exited: VehicleState.EXITED;
+            historical: VehicleState.HISTORICAL;
+        }>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            heading: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+        speed_kmh: z.ZodOptional<z.ZodNumber>;
+        parking_area_id: z.ZodOptional<z.ZodNumber>;
+        parking_area_name: z.ZodOptional<z.ZodString>;
+        entry_time: z.ZodNullable<z.ZodString>;
+        last_updated: z.ZodString;
+        source: z.ZodEnum<{
+            gps: PositionSource.GPS;
+            simulated: PositionSource.SIMULATED;
+            inferred: PositionSource.INFERRED;
+            manual: PositionSource.MANUAL;
+        }>;
+    }, z.core.$strip>>;
+    total_count: z.ZodNumber;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type VehiclePositionsData = z.infer<typeof vehiclePositionsDataSchema>;
+export declare const getVehiclePositionsResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    data: z.ZodObject<{
+        event_id: z.ZodNumber;
+        positions: z.ZodArray<z.ZodObject<{
+            booking_id: z.ZodNumber;
+            license_plate: z.ZodString;
+            vehicle_type: z.ZodEnum<{
+                PL: VehicleType.PL;
+                VUL: VehicleType.VUL;
+                VL: VehicleType.VL;
+            }>;
+            company_name: z.ZodString;
+            stand_number: z.ZodOptional<z.ZodString>;
+            state: z.ZodEnum<{
+                booked: VehicleState.BOOKED;
+                approaching: VehicleState.APPROACHING;
+                at_gate: VehicleState.AT_GATE;
+                entering: VehicleState.ENTERING;
+                parked: VehicleState.PARKED;
+                departing: VehicleState.DEPARTING;
+                at_exit: VehicleState.AT_EXIT;
+                exited: VehicleState.EXITED;
+                historical: VehicleState.HISTORICAL;
+            }>;
+            position: z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+                heading: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+            speed_kmh: z.ZodOptional<z.ZodNumber>;
+            parking_area_id: z.ZodOptional<z.ZodNumber>;
+            parking_area_name: z.ZodOptional<z.ZodString>;
+            entry_time: z.ZodNullable<z.ZodString>;
+            last_updated: z.ZodString;
+            source: z.ZodEnum<{
+                gps: PositionSource.GPS;
+                simulated: PositionSource.SIMULATED;
+                inferred: PositionSource.INFERRED;
+                manual: PositionSource.MANUAL;
+            }>;
+        }, z.core.$strip>>;
+        total_count: z.ZodNumber;
+        timestamp: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type GetVehiclePositionsResponse = z.infer<typeof getVehiclePositionsResponseSchema>;
+export declare const eventIdParamsSchema: z.ZodObject<{
+    eventId: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber>;
+}, z.core.$strip>;
+export type EventIdParams = z.infer<typeof eventIdParamsSchema>;

package/dist/vehiclePosition.js

@@ -0,0 +1,237 @@
+import { z } from './zod.js';
+import { PositionSource } from './enums/positionSource.js';
+import { VehicleState } from './enums/vehicleState.js';
+import { VehicleType } from './enums/vehicleType.js';
+import { createSuccessResponseSchema } from './common.js';
+// ============================================================================
+// Enums as Zod schemas
+// ============================================================================
+export const positionSourceSchema = z.enum([
+    PositionSource.GPS,
+    PositionSource.SIMULATED,
+    PositionSource.INFERRED,
+    PositionSource.MANUAL
+]);
+export const vehicleStateSchema = z.enum([
+    VehicleState.BOOKED,
+    VehicleState.APPROACHING,
+    VehicleState.AT_GATE,
+    VehicleState.ENTERING,
+    VehicleState.PARKED,
+    VehicleState.DEPARTING,
+    VehicleState.AT_EXIT,
+    VehicleState.EXITED,
+    VehicleState.HISTORICAL
+]);
+// ============================================================================
+// Site Plan Position Schema (0-100% coordinates)
+// ============================================================================
+export const sitePlanPositionSchema = z
+    .object({
+    x: z.number().min(0).max(100).openapi({
+        description: 'X coordinate on site plan (0-100%)',
+        example: 45.5
+    }),
+    y: z.number().min(0).max(100).openapi({
+        description: 'Y coordinate on site plan (0-100%)',
+        example: 32.8
+    }),
+    heading: z.number().min(0).max(360).optional().openapi({
+        description: 'Direction of travel in degrees (0-360)',
+        example: 90
+    })
+})
+    .openapi('SitePlanPosition');
+// ============================================================================
+// GPS Coordinates Schema
+// ============================================================================
+export const gpsCoordinatesSchema = z
+    .object({
+    latitude: z.number().min(-90).max(90).openapi({
+        description: 'Latitude coordinate',
+        example: 48.8566
+    }),
+    longitude: z.number().min(-180).max(180).openapi({
+        description: 'Longitude coordinate',
+        example: 2.3522
+    })
+})
+    .openapi('GpsCoordinates');
+// ============================================================================
+// Report Position Request (from Mobile App)
+// ============================================================================
+export const reportPositionBodySchema = z
+    .object({
+    booking_id: z.number().int().positive().openapi({
+        description: 'ID of the parking booking',
+        example: 123
+    }),
+    access_token: z.string().min(1).openapi({
+        description: 'JWT access token from booking',
+        example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+    }),
+    latitude: z.number().min(-90).max(90).openapi({
+        description: 'GPS latitude',
+        example: 48.8566
+    }),
+    longitude: z.number().min(-180).max(180).openapi({
+        description: 'GPS longitude',
+        example: 2.3522
+    }),
+    heading: z.number().min(0).max(360).optional().openapi({
+        description: 'Direction of travel in degrees',
+        example: 90
+    }),
+    speed_kmh: z.number().min(0).max(200).optional().openapi({
+        description: 'Speed in km/h',
+        example: 15
+    }),
+    accuracy_meters: z.number().min(0).optional().openapi({
+        description: 'GPS accuracy in meters',
+        example: 5.2
+    }),
+    timestamp: z.string().datetime().optional().openapi({
+        description: 'ISO 8601 timestamp of the position reading',
+        example: '2026-01-04T12:34:56Z'
+    })
+})
+    .openapi('ReportPositionBody');
+// ============================================================================
+// Report Position Response
+// ============================================================================
+export const reportPositionDataSchema = z
+    .object({
+    position_id: z.string().uuid().openapi({
+        description: 'UUID of the created position record',
+        example: '550e8400-e29b-41d4-a716-446655440000'
+    }),
+    received_at: z.string().datetime().openapi({
+        description: 'Server timestamp when position was received',
+        example: '2026-01-04T12:34:56Z'
+    }),
+    site_plan_position: sitePlanPositionSchema.optional().openapi({
+        description: 'Converted position on site plan (if within venue bounds)'
+    })
+})
+    .openapi('ReportPositionData');
+export const reportPositionResponseSchema = createSuccessResponseSchema(reportPositionDataSchema, 'ReportPositionResponse', 'Position report result');
+// ============================================================================
+// Vehicle Position (for Command Center display)
+// ============================================================================
+export const vehiclePositionSchema = z
+    .object({
+    booking_id: z.number().int().positive().openapi({
+        description: 'ID of the parking booking',
+        example: 123
+    }),
+    license_plate: z.string().openapi({
+        description: 'Vehicle license plate',
+        example: 'AB-123-CD'
+    }),
+    vehicle_type: z.enum([VehicleType.PL, VehicleType.VUL, VehicleType.VL]).openapi({
+        description: 'Type of vehicle',
+        example: 'PL'
+    }),
+    company_name: z.string().openapi({
+        description: 'Company name',
+        example: 'ACME Transport'
+    }),
+    stand_number: z.string().optional().openapi({
+        description: 'Exhibition stand number',
+        example: 'H4-23'
+    }),
+    state: vehicleStateSchema.openapi({
+        description: 'Current vehicle state',
+        example: 'parked'
+    }),
+    position: sitePlanPositionSchema.openapi({
+        description: 'Position on site plan'
+    }),
+    speed_kmh: z.number().min(0).optional().openapi({
+        description: 'Current speed in km/h',
+        example: 0
+    }),
+    parking_area_id: z.number().int().positive().optional().openapi({
+        description: 'ID of assigned parking area',
+        example: 5
+    }),
+    parking_area_name: z.string().optional().openapi({
+        description: 'Name of assigned parking area',
+        example: 'Zone A'
+    }),
+    entry_time: z.string().datetime().nullable().openapi({
+        description: 'Time vehicle entered venue',
+        example: '2026-01-04T10:30:00Z'
+    }),
+    last_updated: z.string().datetime().openapi({
+        description: 'Last position update timestamp',
+        example: '2026-01-04T12:34:56Z'
+    }),
+    source: positionSourceSchema.openapi({
+        description: 'How the position was obtained',
+        example: 'gps'
+    })
+})
+    .openapi('VehiclePosition');
+// ============================================================================
+// Get Vehicle Positions Query
+// ============================================================================
+export const getVehiclePositionsQuerySchema = z
+    .object({
+    since: z.string().datetime().optional().openapi({
+        description: 'Only return positions updated after this time',
+        example: '2026-01-04T12:00:00Z'
+    }),
+    include_historical: z
+        .string()
+        .optional()
+        .default('false')
+        .transform((val) => val === 'true')
+        .openapi({
+        description: 'Include recently exited vehicles',
+        example: 'false'
+    }),
+    state: vehicleStateSchema.optional().openapi({
+        description: 'Filter by vehicle state',
+        example: 'parked'
+    })
+})
+    .openapi('GetVehiclePositionsQuery');
+// ============================================================================
+// Get Vehicle Positions Response
+// ============================================================================
+export const vehiclePositionsDataSchema = z
+    .object({
+    event_id: z.number().int().positive().openapi({
+        description: 'Event ID',
+        example: 1
+    }),
+    positions: z.array(vehiclePositionSchema).openapi({
+        description: 'List of vehicle positions'
+    }),
+    total_count: z.number().int().min(0).openapi({
+        description: 'Total number of positions returned',
+        example: 15
+    }),
+    timestamp: z.string().datetime().openapi({
+        description: 'Server timestamp',
+        example: '2026-01-04T12:34:56Z'
+    })
+})
+    .openapi('VehiclePositionsData');
+export const getVehiclePositionsResponseSchema = createSuccessResponseSchema(vehiclePositionsDataSchema, 'GetVehiclePositionsResponse', 'Vehicle positions for an event');
+// ============================================================================
+// Path Parameters
+// ============================================================================
+export const eventIdParamsSchema = z
+    .object({
+    eventId: z
+        .string()
+        .transform((val) => parseInt(val, 10))
+        .pipe(z.number().int().positive())
+        .openapi({
+        description: 'Event ID',
+        example: '1'
+    })
+})
+    .openapi('EventIdParams');