@meith/plugin-calendar 0.23.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Harrison and the Meith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @meith/plugin-calendar
+
+A shared calendar: events the community can see, linked to the threads that
+discuss them.
+
+## What it adds
+
+- **A calendar page** at `/plugins/calendar`, and a navigation item: an
+  agenda grouped by month, each event with its date block, when it is, how
+  soon ("in 4 days", "next week"), and where. Readable by anyone who can
+  read the board, with a **Past** view for what has already happened.
+- **Events linked to threads.** An event can name a thread — paste the link
+  or the id — and the calendar links to the discussion.
+- **The event, shown in its thread.** A card above the first post says what
+  is scheduled and when, so somebody who arrives at the discussion sees the
+  event without going looking for it.
+- **A link, in the organiser's own words.** An event can carry one address
+  and the text to show for it — *Join online* for a video call, *Get
+  tickets* for a Meetup or GDG page. Only `http://` and `https://` are
+  accepted; anything else is refused rather than rendered, and the anchor
+  carries `nofollow ugc noopener noreferrer` like every other member-supplied
+  link on the board.
+- **An organiser roster**, under Admin → Plugins → Calendar.
+- **Add to your calendar** on every event — a `.ics` file the reader's own
+  calendar app understands. An event with no end is given an hour, and the
+  thread link travels with it as the event URL when the board knows its own
+  address.
+
+## Who may add an event
+
+By default, only the members on the organiser roster. An administrator adds
+them by username. Turning on **Any member may add an event** opens it to
+every signed-in member; guests never may.
+
+Removing an event is allowed to whoever added it, and to any organiser.
+
+This is a roster rather than a usergroup on purpose. `@meith/plugin-kit`
+gives a plugin no way to read a member's groups, and the board's own guard
+says why: group membership is the Authorizer's business, and a plugin never
+gets an `Actor` to ask with. A roster the plugin owns keeps the decision
+inside the plugin's own surface, where it belongs.
+
+In the downloaded `.ics`, the event's own link becomes the calendar entry's
+`URL` — it is the one a reader wants to act on from their calendar app — and
+the thread moves to the description. An event with no link of its own keeps
+the thread as its `URL`, as before.
+
+## What it stores
+
+Two tables in its own namespace: `plugin_calendar_event` and
+`plugin_calendar_organiser`. The link and its text are two columns added by
+a second migration rather than folded into the first, because the first has
+already been applied wherever the plugin runs and a migration that has run
+is never edited. The thread id is a plain column, not a foreign
+key — a plugin's schema may not reference the board's, so an event whose
+thread has since been deleted simply links to a thread that is not there,
+rather than blocking the deletion.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@meith/plugin-calendar",
+  "version": "0.23.0",
+  "description": "A shared calendar: events the community can see, linked to the threads that discuss them.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "plugins/calendar"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/plugin-kit": "^0.23.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.18"
+  }
+}

package/src/access.ts

@@ -0,0 +1,32 @@
+export type AddVerdict = 'allowed' | 'guest' | 'not-an-organiser'
+
+export interface CalendarConfig {
+  readonly anyMemberMayAdd: boolean
+}
+
+export function resolveCalendarConfig(
+  settings: Readonly<Record<string, string | number | boolean>>,
+): CalendarConfig {
+  return { anyMemberMayAdd: settings.any_member_may_add === true }
+}
+
+export function mayAdd(input: {
+  readonly userId: number | null
+  readonly config: CalendarConfig
+  readonly organisers: readonly number[]
+}): AddVerdict {
+  if (input.userId === null) return 'guest'
+  if (input.config.anyMemberMayAdd) return 'allowed'
+  return input.organisers.includes(input.userId) ? 'allowed' : 'not-an-organiser'
+}
+
+export function mayDelete(input: {
+  readonly userId: number | null
+  readonly createdByUserId: number | null
+  readonly config: CalendarConfig
+  readonly organisers: readonly number[]
+}): boolean {
+  if (input.userId === null) return false
+  if (input.createdByUserId === input.userId) return true
+  return input.organisers.includes(input.userId)
+}

package/src/definition.tsx

@@ -0,0 +1,98 @@
+import { definePlugin } from '@meith/plugin-kit'
+
+import {
+  handleAddOrganiser,
+  handleCreateEvent,
+  handleEventIcs,
+  handleRemoveOrganiser,
+} from './handlers'
+import en from './messages/en.json'
+import { CALENDAR_MIGRATIONS } from './schema'
+import { OrganisersPage } from './ui/admin'
+import { CalendarPage } from './ui/page'
+import { ThreadEventCard } from './ui/thread-card'
+
+export const ADD_RATE_LIMIT = { limit: 20, windowSeconds: 3600 }
+
+export const calendarPlugin = definePlugin({
+  key: 'calendar',
+  name: en['calendar.definition.name'],
+  nameKey: 'calendar.definition.name',
+  version: '0.22.0',
+  description: en['calendar.definition.description'],
+  descriptionKey: 'calendar.definition.description',
+  apiVersion: '0',
+
+  settings: [
+    {
+      key: 'any_member_may_add',
+      label: en['calendar.setting.anyMember.label'],
+      labelKey: 'calendar.setting.anyMember.label',
+      description: en['calendar.setting.anyMember.description'],
+      descriptionKey: 'calendar.setting.anyMember.description',
+      type: 'boolean',
+      default: false,
+    },
+  ],
+
+  migrations: CALENDAR_MIGRATIONS,
+
+  pages: [
+    {
+      path: '',
+      title: en['calendar.page.title'],
+      titleKey: 'calendar.page.title',
+      access: 'anonymous',
+      render: CalendarPage,
+    },
+  ],
+
+  navigation: [
+    {
+      key: 'calendar',
+      label: en['calendar.nav.label'],
+      labelKey: 'calendar.nav.label',
+      path: '',
+      audience: 'all',
+    },
+  ],
+
+  adminPages: [
+    {
+      path: 'organisers',
+      title: en['calendar.admin.organisers.title'],
+      titleKey: 'calendar.admin.organisers.title',
+      render: OrganisersPage,
+    },
+  ],
+
+  routes: [
+    {
+      path: 'events',
+      method: 'POST',
+      access: 'member',
+      rateLimit: ADD_RATE_LIMIT,
+      handler: handleCreateEvent,
+    },
+    {
+      path: 'events/ics',
+      method: 'GET',
+      access: 'anonymous',
+      handler: handleEventIcs,
+    },
+    {
+      path: 'organisers/add',
+      method: 'POST',
+      access: 'admin',
+      handler: handleAddOrganiser,
+    },
+    {
+      path: 'organisers/remove',
+      method: 'POST',
+      access: 'admin',
+      handler: handleRemoveOrganiser,
+    },
+  ],
+
+  contributions: [{ region: 'thread.header', render: ThreadEventCard }],
+})

package/src/events.ts

@@ -0,0 +1,249 @@
+export const MAX_TITLE = 120
+
+export const MAX_LOCATION = 120
+
+export const MAX_LINK_LABEL = 40
+
+export const MAX_LINK_URL = 500
+
+export const MAX_DURATION_HOURS = 24 * 14
+
+export interface EventDraft {
+  readonly title: string
+  readonly startsAt: Date
+  readonly endsAt: Date | null
+  readonly location: string
+  readonly threadId: number | null
+  readonly linkUrl: string
+  readonly linkLabel: string
+}
+
+export type DraftProblem =
+  | 'title-missing'
+  | 'title-too-long'
+  | 'location-too-long'
+  | 'starts-missing'
+  | 'ends-before-starts'
+  | 'too-long'
+  | 'link-not-a-url'
+  | 'link-too-long'
+  | 'link-label-too-long'
+  | 'link-label-without-link'
+
+export interface CalendarEvent {
+  readonly id: string
+  readonly title: string
+  readonly startsAt: Date
+  readonly endsAt: Date | null
+  readonly location: string
+  readonly threadId: number | null
+  readonly createdByUserId: number | null
+  readonly linkUrl: string
+  readonly linkLabel: string
+}
+
+export const DEFAULT_LINK_LABEL = 'calendar.event.linkFallback'
+
+export function safeLinkUrl(raw: string): string | null {
+  const trimmed = raw.trim()
+  if (trimmed === '' || trimmed.length > MAX_LINK_URL) return null
+
+  let parsed: URL
+  try {
+    parsed = new URL(trimmed)
+  } catch {
+    return null
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null
+  if (parsed.hostname === '') return null
+
+  return parsed.toString()
+}
+
+function parseDate(raw: string): Date | null {
+  const trimmed = raw.trim()
+  if (trimmed === '') return null
+
+  const parsed = new Date(trimmed)
+  return Number.isNaN(parsed.getTime()) ? null : parsed
+}
+
+export function parseThreadRef(raw: string): number | null {
+  const trimmed = raw.trim()
+  if (trimmed === '') return null
+
+  const fromUrl = /\/threads?\/(\d+)/.exec(trimmed)
+  const digits = fromUrl?.[1] ?? (/^\d+$/.test(trimmed) ? trimmed : null)
+  if (digits === null) return null
+
+  const id = Number(digits)
+  return Number.isSafeInteger(id) && id > 0 ? id : null
+}
+
+export function readDraft(form: Readonly<Record<string, string>>): {
+  readonly draft: EventDraft | null
+  readonly problems: readonly DraftProblem[]
+} {
+  const problems: DraftProblem[] = []
+
+  const title = (form.title ?? '').trim()
+  if (title === '') problems.push('title-missing')
+  else if (title.length > MAX_TITLE) problems.push('title-too-long')
+
+  const location = (form.location ?? '').trim()
+  if (location.length > MAX_LOCATION) problems.push('location-too-long')
+
+  const startsAt = parseDate(form.starts_at ?? '')
+  if (startsAt === null) problems.push('starts-missing')
+
+  const endsAt = parseDate(form.ends_at ?? '')
+  if (startsAt !== null && endsAt !== null) {
+    if (endsAt.getTime() <= startsAt.getTime()) problems.push('ends-before-starts')
+    else if (endsAt.getTime() - startsAt.getTime() > MAX_DURATION_HOURS * 3_600_000) {
+      problems.push('too-long')
+    }
+  }
+
+  const rawLink = (form.link ?? '').trim()
+  const linkLabel = (form.link_text ?? '').trim()
+  const linkUrl = rawLink === '' ? '' : (safeLinkUrl(rawLink) ?? '')
+
+  if (rawLink !== '' && linkUrl === '') {
+    problems.push(rawLink.length > MAX_LINK_URL ? 'link-too-long' : 'link-not-a-url')
+  }
+  if (linkLabel.length > MAX_LINK_LABEL) problems.push('link-label-too-long')
+  if (linkLabel !== '' && rawLink === '') problems.push('link-label-without-link')
+
+  if (problems.length > 0 || startsAt === null) return { draft: null, problems }
+
+  return {
+    draft: {
+      title,
+      startsAt,
+      endsAt,
+      location,
+      threadId: parseThreadRef(form.thread ?? ''),
+      linkUrl,
+      linkLabel,
+    },
+    problems: [],
+  }
+}
+
+export const DEFAULT_LOCALE = 'en-GB'
+
+const DATE_AND_TIME: Intl.DateTimeFormatOptions = {
+  dateStyle: 'medium',
+  timeStyle: 'short',
+  timeZone: 'UTC',
+}
+
+const TIME_ONLY: Intl.DateTimeFormatOptions = { timeStyle: 'short', timeZone: 'UTC' }
+
+function sameUtcDay(a: Date, b: Date): boolean {
+  return a.toISOString().slice(0, 10) === b.toISOString().slice(0, 10)
+}
+
+export function formatRange(
+  startsAt: Date,
+  endsAt: Date | null,
+  locale: string = DEFAULT_LOCALE,
+): string {
+  const start = new Intl.DateTimeFormat(locale, DATE_AND_TIME).format(startsAt)
+  if (endsAt === null) return start
+
+  const end = sameUtcDay(startsAt, endsAt)
+    ? new Intl.DateTimeFormat(locale, TIME_ONLY).format(endsAt)
+    : new Intl.DateTimeFormat(locale, DATE_AND_TIME).format(endsAt)
+
+  return `${start} — ${end}`
+}
+
+export interface DayParts {
+  readonly day: string
+  readonly weekday: string
+}
+
+export function dayParts(date: Date, locale: string = DEFAULT_LOCALE): DayParts {
+  return {
+    day: new Intl.DateTimeFormat(locale, { day: '2-digit', timeZone: 'UTC' }).format(date),
+    weekday: new Intl.DateTimeFormat(locale, { weekday: 'short', timeZone: 'UTC' })
+      .format(date)
+      .toUpperCase(),
+  }
+}
+
+export function monthKey(date: Date): string {
+  return date.toISOString().slice(0, 7)
+}
+
+export function monthLabel(date: Date, locale: string = DEFAULT_LOCALE): string {
+  return new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric', timeZone: 'UTC' })
+    .format(date)
+    .toUpperCase()
+}
+
+export interface EventMonth {
+  readonly key: string
+  readonly label: string
+  readonly events: readonly CalendarEvent[]
+}
+
+export function groupByMonth(
+  events: readonly CalendarEvent[],
+  locale: string = DEFAULT_LOCALE,
+): readonly EventMonth[] {
+  const months: EventMonth[] = []
+
+  for (const event of events) {
+    const key = monthKey(event.startsAt)
+    const last = months.at(-1)
+
+    if (last !== undefined && last.key === key) {
+      months[months.length - 1] = { ...last, events: [...last.events, event] }
+      continue
+    }
+    months.push({ key, label: monthLabel(event.startsAt, locale), events: [event] })
+  }
+
+  return months
+}
+
+function wholeDaysBetween(from: Date, to: Date): number {
+  const day = 86_400_000
+  const startOf = (date: Date) =>
+    Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate())
+  return Math.round((startOf(to) - startOf(from)) / day)
+}
+
+export function relativeHint(startsAt: Date, now: Date, locale: string = DEFAULT_LOCALE): string {
+  const days = wholeDaysBetween(now, startsAt)
+  const format = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+
+  if (Math.abs(days) < 7) return format.format(days, 'day')
+  if (Math.abs(days) < 31) return format.format(Math.trunc(days / 7), 'week')
+  return format.format(Math.trunc(days / 30), 'month')
+}
+
+export function isUpcoming(event: CalendarEvent, now: Date): boolean {
+  const finishes = event.endsAt ?? event.startsAt
+  return finishes.getTime() >= now.getTime()
+}
+
+export function pickThreadEvent(events: readonly CalendarEvent[], now: Date): CalendarEvent | null {
+  if (events.length === 0) return null
+
+  const upcoming = events.filter((event) => isUpcoming(event, now)).sort(byStart)
+  if (upcoming.length > 0) return upcoming[0] ?? null
+
+  return [...events].sort(byStart).at(-1) ?? null
+}
+
+export function byStart(a: CalendarEvent, b: CalendarEvent): number {
+  return a.startsAt.getTime() - b.startsAt.getTime()
+}
+
+export function eventHref(event: CalendarEvent): string | null {
+  return event.threadId === null ? null : `/thread/${event.threadId}`
+}

package/src/handlers.ts

@@ -0,0 +1,82 @@
+import type { PluginRequest, PluginResponse, PluginRuntimeContext } from '@meith/plugin-kit'
+
+import { mayAdd, resolveCalendarConfig } from './access'
+import { readDraft } from './events'
+import { ICS_CONTENT_TYPE, toIcs } from './ics'
+import { addOrganiser, createEvent, eventById, organiserIds, removeOrganiser } from './store'
+
+export const CALENDAR_PATH = '/plugins/calendar'
+
+function seeCalendar(): PluginResponse {
+  return { kind: 'redirect', to: CALENDAR_PATH }
+}
+
+function refused(status: number, message: string): PluginResponse {
+  return { kind: 'json', status, body: { error: message } }
+}
+
+export async function handleCreateEvent(
+  request: PluginRequest,
+  context: PluginRuntimeContext,
+): Promise<PluginResponse> {
+  const form = request.form
+  if (form === null) return refused(400, 'form-required')
+
+  const config = resolveCalendarConfig(context.settings)
+  const verdict = mayAdd({
+    userId: request.viewer.userId,
+    config,
+    organisers: await organiserIds(context.data),
+  })
+
+  if (verdict !== 'allowed') return refused(403, verdict)
+
+  const { draft, problems } = readDraft(form)
+  if (draft === null) return refused(400, problems.join(','))
+
+  await createEvent(context.data, draft, request.viewer.userId)
+  return seeCalendar()
+}
+
+export async function handleEventIcs(
+  request: PluginRequest,
+  context: PluginRuntimeContext,
+): Promise<PluginResponse> {
+  const id = request.query.id?.trim() ?? ''
+  if (!/^\d+$/.test(id)) return refused(400, 'id-required')
+
+  const event = await eventById(context.data, id)
+  if (event === null) return refused(404, 'no-such-event')
+
+  return {
+    kind: 'text',
+    body: toIcs(event, request.boardUrl, new Date()),
+    contentType: ICS_CONTENT_TYPE,
+  }
+}
+
+export async function handleAddOrganiser(
+  request: PluginRequest,
+  context: PluginRuntimeContext,
+): Promise<PluginResponse> {
+  const username = request.form?.username?.trim() ?? ''
+  if (username === '') return refused(400, 'username-required')
+
+  const member = await context.users.byUsername(username)
+  if (member === null) return refused(404, 'unknown-member')
+
+  await addOrganiser(context.data, member.userId, request.viewer.userId)
+  return { kind: 'redirect', to: '/admin/plugins/calendar/organisers' }
+}
+
+export async function handleRemoveOrganiser(
+  request: PluginRequest,
+  context: PluginRuntimeContext,
+): Promise<PluginResponse> {
+  const raw = request.form?.user_id?.trim() ?? ''
+  const userId = Number(raw)
+  if (!Number.isSafeInteger(userId) || userId <= 0) return refused(400, 'user-id-required')
+
+  await removeOrganiser(context.data, userId)
+  return { kind: 'redirect', to: '/admin/plugins/calendar/organisers' }
+}

package/src/ics.ts

@@ -0,0 +1,89 @@
+import { type CalendarEvent, eventHref } from './events'
+
+export const ICS_CONTENT_TYPE = `text/calendar; charset=utf-8`
+
+export const DEFAULT_DURATION_MINUTES = 60
+
+const PRODID = `PRODID:-//Meith//Calendar//EN`
+
+function stamp(date: Date): string {
+  return `${date.toISOString().replace(/[-:]/g, '').slice(0, 15)}Z`
+}
+
+function escapeText(value: string): string {
+  return value
+    .replace(/\\/g, '\\\\')
+    .replace(/;/g, '\\;')
+    .replace(/,/g, '\\,')
+    .replace(/\r?\n/g, '\\n')
+}
+
+export function fold(line: string): string {
+  if (line.length <= 75) return line
+
+  const parts: string[] = [line.slice(0, 75)]
+  let rest = line.slice(75)
+  while (rest.length > 74) {
+    parts.push(` ${rest.slice(0, 74)}`)
+    rest = rest.slice(74)
+  }
+  if (rest.length > 0) parts.push(` ${rest}`)
+  return parts.join('\r\n')
+}
+
+export function icsFileName(event: CalendarEvent): string {
+  const slug = event.title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 60)
+  return `${slug === '' ? 'event' : slug}.ics`
+}
+
+export function absoluteBase(boardUrl: string): string | null {
+  const trimmed = boardUrl.trim().replace(/\/+$/, '')
+  if (trimmed === '') return null
+
+  try {
+    const parsed = new URL(trimmed)
+    return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? trimmed : null
+  } catch {
+    return null
+  }
+}
+
+export function toIcs(event: CalendarEvent, boardUrl: string, now: Date): string {
+  const ends =
+    event.endsAt ?? new Date(event.startsAt.getTime() + DEFAULT_DURATION_MINUTES * 60_000)
+
+  const base = absoluteBase(boardUrl)
+  const host = base === null ? 'meith' : new URL(base).host
+
+  const href = eventHref(event)
+  const threadUrl = href === null || base === null ? null : `${base}${href}`
+
+  const hasOwnLink = event.linkUrl !== ''
+  const actionUrl = hasOwnLink ? event.linkUrl : threadUrl
+  const describedUrl = hasOwnLink ? threadUrl : null
+
+  const lines = [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    PRODID,
+    'CALSCALE:GREGORIAN',
+    'METHOD:PUBLISH',
+    'BEGIN:VEVENT',
+    `UID:calendar-${event.id}@${host}`,
+    `DTSTAMP:${stamp(now)}`,
+    `DTSTART:${stamp(event.startsAt)}`,
+    `DTEND:${stamp(ends)}`,
+    `SUMMARY:${escapeText(event.title)}`,
+    ...(event.location === '' ? [] : [`LOCATION:${escapeText(event.location)}`]),
+    ...(actionUrl === null ? [] : [`URL:${escapeText(actionUrl)}`]),
+    ...(describedUrl === null ? [] : [`DESCRIPTION:${escapeText(describedUrl)}`]),
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ]
+
+  return `${lines.map(fold).join('\r\n')}\r\n`
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { calendarPlugin, calendarPlugin as plugin } from './definition'
+export type { CalendarEvent, EventDraft } from './events'
+export { calendarMessages, calendarMessages as messages } from './messages'
+export { addOrganiser, createEvent } from './store'

package/src/messages/en.json

@@ -0,0 +1,32 @@
+{
+  "calendar.admin.organisers.add": "Add organiser",
+  "calendar.admin.organisers.empty": "Nobody is an organiser yet, so only the setting above decides who may add events.",
+  "calendar.admin.organisers.remove": "Remove",
+  "calendar.admin.organisers.title": "Organisers",
+  "calendar.admin.organisers.username": "Username",
+  "calendar.definition.description": "A shared calendar: events the community can see, linked to the threads that discuss them.",
+  "calendar.definition.name": "Calendar",
+  "calendar.error.notAnOrganiser": "Only an organiser may add an event to this calendar.",
+  "calendar.event.add": "Add event",
+  "calendar.event.discuss": "Discussion",
+  "calendar.event.download": "Add to your calendar",
+  "calendar.event.link": "Link",
+  "calendar.event.linkFallback": "Open link",
+  "calendar.event.linkHint": "An https:// address people should open — a video call, a ticket page.",
+  "calendar.event.linkText": "Link text",
+  "calendar.event.linkTextHint": "What the link should say — “Join online”, “Get tickets”.",
+  "calendar.event.location": "Location",
+  "calendar.event.starts": "Starts",
+  "calendar.event.thread": "Thread link or id",
+  "calendar.event.title": "Title",
+  "calendar.event.until": "Until",
+  "calendar.nav.label": "Calendar",
+  "calendar.page.empty": "Nothing is scheduled yet.",
+  "calendar.page.emptyPast": "Nothing has happened yet.",
+  "calendar.page.past": "Past",
+  "calendar.page.title": "Calendar",
+  "calendar.page.upcoming": "Upcoming",
+  "calendar.setting.anyMember.description": "When off, only the organisers named under Admin → Plugins → Calendar may add events.",
+  "calendar.setting.anyMember.label": "Any member may add an event",
+  "calendar.thread.card": "This thread discusses an event."
+}

package/src/messages/index.ts

@@ -0,0 +1,3 @@
+import en from './en.json'
+
+export const calendarMessages = { en }

package/src/schema.ts

@@ -0,0 +1,38 @@
+import type { PluginMigration } from '@meith/plugin-kit'
+
+export const CALENDAR_MIGRATIONS: readonly PluginMigration[] = [
+  {
+    id: '0001_events_and_organisers',
+    statements: [
+      `create table if not exists plugin_calendar_event (
+         id                  bigint generated by default as identity primary key,
+         title               text        not null,
+         starts_at           timestamptz not null,
+         ends_at             timestamptz,
+         location            text        not null default '',
+         thread_id           integer,
+         created_by_user_id  integer,
+         created_at          timestamptz not null default now()
+       )`,
+      `create index if not exists plugin_calendar_event_starts
+         on plugin_calendar_event (starts_at)`,
+      `create index if not exists plugin_calendar_event_thread
+         on plugin_calendar_event (thread_id)
+         where thread_id is not null`,
+      `create table if not exists plugin_calendar_organiser (
+         user_id            integer     not null primary key,
+         added_by_user_id   integer,
+         added_at           timestamptz not null default now()
+       )`,
+    ],
+  },
+  {
+    id: '0002_event_link',
+    statements: [
+      `alter table plugin_calendar_event
+         add column if not exists link_url text not null default ''`,
+      `alter table plugin_calendar_event
+         add column if not exists link_label text not null default ''`,
+    ],
+  },
+]

package/src/store.ts

@@ -0,0 +1,134 @@
+import type { PluginData } from '@meith/plugin-kit'
+
+import type { CalendarEvent, EventDraft } from './events'
+
+interface EventRow extends Record<string, unknown> {
+  readonly id: string | number
+  readonly title: string
+  readonly starts_at: Date | string
+  readonly ends_at: Date | string | null
+  readonly location: string
+  readonly thread_id: number | null
+  readonly created_by_user_id: number | null
+  readonly link_url: string | null
+  readonly link_label: string | null
+}
+
+function toEvent(row: EventRow): CalendarEvent {
+  return {
+    id: String(row.id),
+    title: row.title,
+    startsAt: new Date(row.starts_at),
+    endsAt: row.ends_at === null ? null : new Date(row.ends_at),
+    location: row.location,
+    threadId: row.thread_id,
+    createdByUserId: row.created_by_user_id,
+    linkUrl: row.link_url ?? '',
+    linkLabel: row.link_label ?? '',
+  }
+}
+
+const COLUMNS = `id, title, starts_at, ends_at, location, thread_id, created_by_user_id,
+                 link_url, link_label`
+
+export async function createEvent(
+  data: PluginData,
+  draft: EventDraft,
+  createdByUserId: number | null,
+): Promise<void> {
+  await data.query(
+    `insert into plugin_calendar_event
+       (title, starts_at, ends_at, location, thread_id, created_by_user_id, link_url, link_label)
+     values ($1, $2, $3, $4, $5, $6, $7, $8)`,
+    [
+      draft.title,
+      draft.startsAt,
+      draft.endsAt,
+      draft.location,
+      draft.threadId,
+      createdByUserId,
+      draft.linkUrl,
+      draft.linkLabel,
+    ],
+  )
+}
+
+export async function upcomingEvents(
+  data: PluginData,
+  limit: number,
+): Promise<readonly CalendarEvent[]> {
+  const rows = await data.query<EventRow>(
+    `select ${COLUMNS} from plugin_calendar_event
+      where coalesce(ends_at, starts_at) >= now()
+      order by starts_at
+      limit $1`,
+    [limit],
+  )
+  return rows.map(toEvent)
+}
+
+export async function pastEvents(
+  data: PluginData,
+  limit: number,
+): Promise<readonly CalendarEvent[]> {
+  const rows = await data.query<EventRow>(
+    `select ${COLUMNS} from plugin_calendar_event
+      where coalesce(ends_at, starts_at) < now()
+      order by starts_at desc
+      limit $1`,
+    [limit],
+  )
+  return rows.map(toEvent)
+}
+
+export async function eventById(data: PluginData, id: string): Promise<CalendarEvent | null> {
+  const row = await data.one<EventRow>(
+    `select ${COLUMNS} from plugin_calendar_event where id = $1`,
+    [id],
+  )
+  return row === null ? null : toEvent(row)
+}
+
+export const THREAD_EVENT_SCAN = 20
+
+export async function eventsForThread(
+  data: PluginData,
+  threadId: number,
+): Promise<readonly CalendarEvent[]> {
+  const rows = await data.query<EventRow>(
+    `select ${COLUMNS} from plugin_calendar_event
+      where thread_id = $1
+      order by starts_at desc
+      limit $2`,
+    [threadId, THREAD_EVENT_SCAN],
+  )
+  return rows.map(toEvent)
+}
+
+export async function deleteEvent(data: PluginData, id: string): Promise<void> {
+  await data.query(`delete from plugin_calendar_event where id = $1`, [id])
+}
+
+export async function organiserIds(data: PluginData): Promise<readonly number[]> {
+  const rows = await data.query<{ user_id: number }>(
+    `select user_id from plugin_calendar_organiser order by added_at`,
+  )
+  return rows.map((row) => Number(row.user_id))
+}
+
+export async function addOrganiser(
+  data: PluginData,
+  userId: number,
+  addedByUserId: number | null,
+): Promise<void> {
+  await data.query(
+    `insert into plugin_calendar_organiser (user_id, added_by_user_id)
+     values ($1, $2)
+     on conflict (user_id) do nothing`,
+    [userId, addedByUserId],
+  )
+}
+
+export async function removeOrganiser(data: PluginData, userId: number): Promise<void> {
+  await data.query(`delete from plugin_calendar_organiser where user_id = $1`, [userId])
+}

package/src/ui/admin.tsx

@@ -0,0 +1,57 @@
+import type { PluginAdminPageContext } from '@meith/plugin-kit'
+
+import en from '../messages/en.json'
+import { organiserIds } from '../store'
+
+function translated(context: PluginAdminPageContext, key: keyof typeof en): string {
+  return context.t.has(key) ? context.t.t(key) : en[key]
+}
+
+export async function OrganisersPage(context: PluginAdminPageContext) {
+  const ids = await organiserIds(context.data).catch(() => [] as readonly number[])
+
+  const named = await Promise.all(
+    ids.map(async (userId) => ({
+      userId,
+      username: (await context.users.byId(userId).catch(() => null))?.username ?? String(userId),
+    })),
+  )
+
+  return (
+    <div className="flex flex-col gap-4 text-sm">
+      {named.length === 0 ? (
+        <p className="text-muted-foreground">
+          {translated(context, 'calendar.admin.organisers.empty')}
+        </p>
+      ) : (
+        <ul className="flex flex-col gap-1">
+          {named.map((organiser) => (
+            <li key={organiser.userId} className="flex items-center justify-between gap-3">
+              <span>{organiser.username}</span>
+              <form method="post" action="/admin/api/plugins/calendar/organisers/remove">
+                <input type="hidden" name="user_id" value={organiser.userId} />
+                <button type="submit" className="rounded border px-2 py-0.5 text-xs">
+                  {translated(context, 'calendar.admin.organisers.remove')}
+                </button>
+              </form>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <form
+        method="post"
+        action="/admin/api/plugins/calendar/organisers/add"
+        className="flex items-end gap-2"
+      >
+        <label className="flex flex-col gap-1">
+          {translated(context, 'calendar.admin.organisers.username')}
+          <input name="username" required className="rounded border p-1" />
+        </label>
+        <button type="submit" className="rounded border px-3 py-1">
+          {translated(context, 'calendar.admin.organisers.add')}
+        </button>
+      </form>
+    </div>
+  )
+}

package/src/ui/event-link.tsx

@@ -0,0 +1,20 @@
+import type { CalendarEvent } from '../events'
+
+export const EXTERNAL_REL = 'nofollow ugc noopener noreferrer'
+
+export function EventLink({ event, label }: { event: CalendarEvent; label: string }) {
+  if (event.linkUrl === '') return null
+
+  return (
+    <p className="text-sm">
+      <a
+        className="underline underline-offset-2"
+        href={event.linkUrl}
+        rel={EXTERNAL_REL}
+        target="_blank"
+      >
+        {event.linkLabel === '' ? label : event.linkLabel}
+      </a>
+    </p>
+  )
+}

package/src/ui/page.tsx

@@ -0,0 +1,221 @@
+import type { PluginPageContext } from '@meith/plugin-kit'
+
+import { mayAdd, resolveCalendarConfig } from '../access'
+import {
+  type CalendarEvent,
+  dayParts,
+  eventHref,
+  formatRange,
+  groupByMonth,
+  relativeHint,
+} from '../events'
+import en from '../messages/en.json'
+import { organiserIds, pastEvents, upcomingEvents } from '../store'
+import { EventLink } from './event-link'
+
+export const UPCOMING_LIMIT = 50
+
+export const PAST_LIMIT = 30
+
+function translated(context: PluginPageContext, key: keyof typeof en): string {
+  return context.t.has(key) ? context.t.t(key) : en[key]
+}
+
+function DateBlock({ event, locale }: { event: CalendarEvent; locale: string }) {
+  const { day, weekday } = dayParts(event.startsAt, locale)
+
+  return (
+    <div className="bg-muted text-foreground flex h-14 w-14 shrink-0 flex-col items-center justify-center rounded-md border">
+      <span className="text-lg font-semibold leading-none tabular-nums">{day}</span>
+      <span className="text-muted-foreground mt-1 text-[0.625rem] font-medium tracking-widest">
+        {weekday}
+      </span>
+    </div>
+  )
+}
+
+function EventRow({
+  event,
+  locale,
+  now,
+  context,
+}: {
+  event: CalendarEvent
+  locale: string
+  now: Date
+  context: PluginPageContext
+}) {
+  const href = eventHref(event)
+
+  return (
+    <li className="flex items-start gap-4 py-4 first:pt-0 last:pb-0">
+      <DateBlock event={event} locale={locale} />
+
+      <div className="flex min-w-0 flex-col gap-1">
+        <p className="font-semibold leading-tight">{event.title}</p>
+
+        <p className="text-muted-foreground text-sm">
+          <time dateTime={event.startsAt.toISOString()}>
+            {formatRange(event.startsAt, event.endsAt, locale)}
+          </time>
+          {event.location !== '' && <span> · {event.location}</span>}
+        </p>
+
+        <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
+          <span className="text-muted-foreground">{relativeHint(event.startsAt, now, locale)}</span>
+          {href !== null && (
+            <a className="underline underline-offset-2" href={href}>
+              {translated(context, 'calendar.event.discuss')}
+            </a>
+          )}
+          <a
+            className="underline underline-offset-2"
+            href={`/api/plugins/calendar/events/ics?id=${event.id}`}
+          >
+            {translated(context, 'calendar.event.download')}
+          </a>
+        </p>
+
+        <EventLink event={event} label={translated(context, 'calendar.event.linkFallback')} />
+      </div>
+    </li>
+  )
+}
+
+function Agenda({
+  events,
+  locale,
+  now,
+  context,
+}: {
+  events: readonly CalendarEvent[]
+  locale: string
+  now: Date
+  context: PluginPageContext
+}) {
+  return (
+    <div className="flex flex-col gap-6">
+      {groupByMonth(events, locale).map((month) => (
+        <section key={month.key} className="bg-card flex flex-col gap-3 rounded-md border p-4">
+          <h2 className="text-muted-foreground text-xs font-semibold tracking-widest">
+            {month.label}
+          </h2>
+          <ul className="divide-border divide-y">
+            {month.events.map((event) => (
+              <EventRow key={event.id} event={event} locale={locale} now={now} context={context} />
+            ))}
+          </ul>
+        </section>
+      ))}
+    </div>
+  )
+}
+
+function AddForm({ context }: { context: PluginPageContext }) {
+  return (
+    <form
+      method="post"
+      action="/api/plugins/calendar/events"
+      className="bg-card flex flex-col gap-3 rounded-md border p-4"
+    >
+      <h2 className="font-semibold">{translated(context, 'calendar.event.add')}</h2>
+
+      <div className="grid gap-3 sm:grid-cols-2">
+        <label className="flex flex-col gap-1 text-sm sm:col-span-2">
+          {translated(context, 'calendar.event.title')}
+          <input name="title" required maxLength={120} className="rounded border p-1.5" />
+        </label>
+        <label className="flex flex-col gap-1 text-sm">
+          {translated(context, 'calendar.event.starts')}
+          <input name="starts_at" type="datetime-local" required className="rounded border p-1.5" />
+        </label>
+        <label className="flex flex-col gap-1 text-sm">
+          {translated(context, 'calendar.event.until')}
+          <input name="ends_at" type="datetime-local" className="rounded border p-1.5" />
+        </label>
+        <label className="flex flex-col gap-1 text-sm">
+          {translated(context, 'calendar.event.location')}
+          <input name="location" maxLength={120} className="rounded border p-1.5" />
+        </label>
+        <label className="flex flex-col gap-1 text-sm">
+          {translated(context, 'calendar.event.thread')}
+          <input name="thread" className="rounded border p-1.5" />
+        </label>
+        <label className="flex flex-col gap-1 text-sm">
+          {translated(context, 'calendar.event.link')}
+          <input
+            name="link"
+            type="url"
+            maxLength={500}
+            placeholder="https://"
+            className="rounded border p-1.5"
+          />
+          <span className="text-muted-foreground text-xs">
+            {translated(context, 'calendar.event.linkHint')}
+          </span>
+        </label>
+        <label className="flex flex-col gap-1 text-sm">
+          {translated(context, 'calendar.event.linkText')}
+          <input name="link_text" maxLength={40} className="rounded border p-1.5" />
+          <span className="text-muted-foreground text-xs">
+            {translated(context, 'calendar.event.linkTextHint')}
+          </span>
+        </label>
+      </div>
+
+      <button type="submit" className="bg-muted self-start rounded border px-3 py-1.5 text-sm">
+        {translated(context, 'calendar.event.add')}
+      </button>
+    </form>
+  )
+}
+
+export async function CalendarPage(context: PluginPageContext) {
+  const config = resolveCalendarConfig(context.settings)
+  const showingPast = context.query.show === 'past'
+  const now = new Date()
+
+  const [events, organisers] = await Promise.all([
+    (showingPast
+      ? pastEvents(context.data, PAST_LIMIT)
+      : upcomingEvents(context.data, UPCOMING_LIMIT)
+    ).catch(() => [] as readonly CalendarEvent[]),
+    organiserIds(context.data).catch(() => [] as readonly number[]),
+  ])
+
+  const verdict = mayAdd({ userId: context.viewer.userId, config, organisers })
+
+  return (
+    <div className="flex flex-col gap-6">
+      <nav className="flex gap-4 text-sm">
+        <a
+          className={showingPast ? 'underline underline-offset-2' : 'font-semibold'}
+          href="/plugins/calendar"
+        >
+          {translated(context, 'calendar.page.upcoming')}
+        </a>
+        <a
+          className={showingPast ? 'font-semibold' : 'underline underline-offset-2'}
+          href="/plugins/calendar?show=past"
+        >
+          {translated(context, 'calendar.page.past')}
+        </a>
+      </nav>
+
+      {events.length === 0 ? (
+        <p className="text-muted-foreground text-sm">
+          {translated(context, showingPast ? 'calendar.page.emptyPast' : 'calendar.page.empty')}
+        </p>
+      ) : (
+        <Agenda events={events} locale={context.locale} now={now} context={context} />
+      )}
+
+      {!showingPast && verdict === 'allowed' && <AddForm context={context} />}
+      {!showingPast && verdict === 'not-an-organiser' && (
+        <p className="text-muted-foreground text-sm">
+          {translated(context, 'calendar.error.notAnOrganiser')}
+        </p>
+      )}
+    </div>
+  )
+}

package/src/ui/thread-card.tsx

@@ -0,0 +1,36 @@
+import type { PluginRegionContext, PluginRuntimeContext } from '@meith/plugin-kit'
+
+import { type CalendarEvent, formatRange, pickThreadEvent } from '../events'
+import en from '../messages/en.json'
+import { eventsForThread } from '../store'
+import { EventLink } from './event-link'
+
+export async function ThreadEventCard(context: PluginRegionContext) {
+  if (context.subjectId === null) return null
+
+  let event: CalendarEvent | null = null
+  try {
+    const runtime = (await context.runtime()) as PluginRuntimeContext
+    event = pickThreadEvent(await eventsForThread(runtime.data, context.subjectId), new Date())
+  } catch {
+    return null
+  }
+
+  if (event === null) return null
+
+  return (
+    <section className="rounded-md border border-border bg-card p-3 text-sm" data-plugin="calendar">
+      <p className="text-xs uppercase tracking-wide text-muted-foreground">
+        {en['calendar.thread.card']}
+      </p>
+      <p className="font-semibold">{event.title}</p>
+      <p className="text-muted-foreground">
+        <time dateTime={event.startsAt.toISOString()}>
+          {formatRange(event.startsAt, event.endsAt)}
+        </time>
+        {event.location !== '' && <span> · {event.location}</span>}
+      </p>
+      <EventLink event={event} label={en['calendar.event.linkFallback']} />
+    </section>
+  )
+}