// Public · Events — mounted at /api/v1/public/events by public/index.js. // // No group gate: this is the anonymous surface, and `siteMode` is applied per // route as it is everywhere else in this tier — during maintenance only an admin // with a valid session sees content. // // Declaration order: '/' is literal and precedes ':slug', and 'series/:slug' is // declared BEFORE ':slug' although it could not be shadowed by it (two segments // against one). It stays above so the relationship is visible to whoever adds // the next route here — and because the one route bug this feature has already // shipped was exactly a static/dynamic ranking surprise, one tier up in React // Router (see App.jsx's note above `events/:id`). const express = require('express') const ctrl = require('./events.controller') const siteMode = require('../../../middleware/siteMode') const { optionalAuth } = require('../../../auth/session.middleware') const eventsRouter = express.Router() eventsRouter.get( '/', // #swagger.tags = ['Public · Events'] // #swagger.summary = 'The public event calendar' // #swagger.description = 'Upcoming, live and recent events in a window, ascending by instant. An entry is one of two things and says which: a `run` is a materialised occurrence, and a `projected` entry is arithmetic past the materialisation horizon — a forecast, with nothing committed to it, which a client should draw as such. Instants are UTC and each entry carries the EVENT\'s own timezone, because a shard-local 8pm means the shard\'s evening to everyone reading it; the reader\'s own zone places the entry in a month grid. Rehearsals and unlisted events are absent. Defaults to now through 31 days out; the window may span at most 92 days.' // #swagger.parameters['from'] = { in: 'query', required: false, schema: { type: 'string', format: 'date-time' }, description: 'Window start (ISO). Defaults to now.' } // #swagger.parameters['to'] = { in: 'query', required: false, schema: { type: 'string', format: 'date-time' }, description: 'Window end (ISO). Defaults to 31 days after the start.' } // #swagger.parameters['seriesId'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Restrict to one arc.' } /* #swagger.responses[200] = { description: 'The calendar', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicEventCalendar" } } } } */ /* #swagger.responses[400] = { description: 'Bad window', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ siteMode, ctrl.getCalendar, ) eventsRouter.get( '/series/:slug', // #swagger.tags = ['Public · Events'] // #swagger.summary = 'One arc' // #swagger.description = 'A series and the listed events in it, in the order an editor arranged them. A series with no listed events answers 404 rather than an empty page: the arc is a label on its definitions, so a page for an empty one would publish the fact that an operator has named something they have not announced.' // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The series slug.' } /* #swagger.responses[200] = { description: 'The arc', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicEventSeries" } } } } */ /* #swagger.responses[404] = { description: 'No such arc, or nothing in it is listed', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ siteMode, ctrl.getSeries, ) eventsRouter.get( '/:slug', // #swagger.tags = ['Public · Events'] // #swagger.summary = 'One event' // #swagger.description = 'The storyline, the arc it belongs to, what is live, what is next, what happened recently, and a results table once one has been published. A draft, an archived definition and an unlisted one all answer 404, indistinguishable from a slug that never existed. The plan behind the event — phases, steps, actions and their params — is never published; a live run carries the LABEL of the phase it is in and nothing more, and `progress`: how its steps stand, each line a label with either `left` of `of` or a `percent`, in the words the steps\' modules chose. What a module shows may depend on who is reading, so sending a session is optional and may widen it.' // #swagger.parameters['slug'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'The event slug.' } // #swagger.parameters['run'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Which occurrence the results are about — what an announcement\'s link carries, so a mail about last Friday does not open next Friday\'s. A run that does not belong to this event is ignored rather than refused.' } // #swagger.security = [{}, { "cookieAuth": [] }, { "bearerAuth": [] }] /* #swagger.responses[200] = { description: 'The event', content: { "application/json": { schema: { $ref: "#/components/schemas/PublicEvent" } } } } */ /* #swagger.responses[404] = { description: 'No such public event', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */ siteMode, optionalAuth, ctrl.getEvent, ) module.exports = eventsRouter