Matiss/Final-Year-Project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(events): add phase3 motion API and realtime event docs

Browse Source
This commit is contained in:
Matiss Jurevics
2026-01-10 14:50:00 +00:00
parent aa8b278c46
commit dc65756db8
2 changed files with 138 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
Backend/docs/openapi.ts
View File

@@ -608,6 +608,132 @@ registry.registerPath({
},
});
registry.registerPath({
method: 'post',
path: '/events/motion/start',
summary: 'Camera device starts a motion event and notifies linked clients',
tags: ['Events'],
security: [{ bearerDeviceToken: [] }],
request: {
body: {
content: {
'application/json': {
schema: z.object({
title: z.string().optional(),
triggeredBy: z.string().optional(),
videoUrl: z.string().url().optional(),
}),
},
},
},
},
responses: {
201: {
description: 'Motion event started',
content: {
'application/json': {
schema: z.object({
message: z.string(),
event: z.object({
id: z.string().uuid(),
userId: z.string().uuid(),
deviceId: z.string().uuid().nullable(),
title: z.string().nullable(),
triggeredBy: z.string().nullable(),
status: z.string(),
startedAt: z.string().datetime(),
endedAt: z.string().datetime().nullable(),
videoUrl: z.string().nullable(),
createdAt: z.string().datetime(),
updatedAt: z.string().datetime(),
notifiedAt: z.string().datetime().nullable(),
}),
notifiedClients: z.number().int(),
}),
},
},
},
},
});
registry.registerPath({
method: 'post',
path: '/events/{eventId}/motion/end',
summary: 'Camera device ends a motion event and notifies linked clients',
tags: ['Events'],
security: [{ bearerDeviceToken: [] }],
request: {
params: z.object({ eventId: z.string().uuid() }),
body: {
content: {
'application/json': {
schema: z.object({
status: z.enum(['completed', 'cancelled', 'failed']).optional(),
videoUrl: z.string().url().optional(),
}),
},
},
},
},
responses: {
200: {
description: 'Motion event ended',
content: {
'application/json': {
schema: z.object({
message: z.string(),
event: z.object({
id: z.string().uuid(),
status: z.string(),
endedAt: z.string().datetime().nullable(),
updatedAt: z.string().datetime(),
}),
notifiedClients: z.number().int(),
}),
},
},
},
},
});
registry.registerPath({
method: 'get',
path: '/events',
summary: 'List events for authenticated user',
tags: ['Events'],
security: [{ cookieAuth: [] }],
request: {
query: z.object({
status: z.string().optional(),
limit: z.coerce.number().int().min(1).max(100).default(25),
}),
},
responses: {
200: {
description: 'User event list',
content: {
'application/json': {
schema: z.object({
count: z.number().int(),
events: z.array(
z.object({
id: z.string().uuid(),
status: z.string(),
startedAt: z.string().datetime(),
endedAt: z.string().datetime().nullable(),
deviceId: z.string().uuid().nullable(),
title: z.string().nullable(),
triggeredBy: z.string().nullable(),
videoUrl: z.string().nullable(),
}),
),
}),
},
},
},
},
});
export function buildOpenApiDocument() {
const generator = new OpenApiGeneratorV3(registry.definitions);
const document = generator.generateDocument({
@@ -625,6 +751,7 @@ export function buildOpenApiDocument() {
{ name: 'Devices', description: 'Device registration and heartbeat endpoints' },
{ name: 'Device Links', description: 'Client-camera authorization links' },
{ name: 'Commands', description: 'Realtime command dispatch and status' },
{ name: 'Events', description: 'Motion event lifecycle and user event history' },
],
});