@acms-subir/core 0.2.0 → 0.3.1

package/src/lib/booking/service.ts

@@ -0,0 +1,277 @@
+// Booking workflows shared by the public booking pages, the admin, the REST
+// API and agent tools, so every path validates, notifies and fires webhooks
+// the same way. Auto-confirm links confirm on the spot (and show on the
+// calendar immediately); the rest wait as "pending" for staff.
+import type { ContentRepository } from '../repo/types';
+import type { Booking, BookingLink, BookingStatus, CalEvent, Resource, Settings } from '../schema';
+import { loadFeed, expandVEvents } from '../calendar/ics';
+import { emitWebhook } from '../webhooks';
+import { parseFrom } from '../email/config';
+import { kickEmail } from '../email/service';
+import { manageUrl as manageUrlFor, eventUrl } from '../calendar/config';
+import { eventTimeZone, locationLine } from '../calendar/events';
+import { bookingEmail, whenText, type BookingEmail } from './emails';
+import { holdOf, isBookable, resourceZone, type AvailabilityContext, type Interval } from './availability';
+
+export interface FlowOptions {
+  origin: string;
+  locals?: unknown;
+  waitUntil?: (p: Promise<unknown>) => void;
+  now?: number;
+  idempotency?: { keyHash: string; requestHash: string };
+}
+
+export class BookingError extends Error {
+  constructor(public status: number, message: string) { super(message); }
+}
+
+const token = () => {
+  const bytes = crypto.getRandomValues(new Uint8Array(24));
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+
+// ---- availability context ------------------------------------------------
+
+const busyCache = new Map<string, { at: number; intervals: Interval[] }>();
+
+async function busyIntervals(resource: Resource, from: number, to: number, now: number): Promise<Interval[]> {
+  if (!resource.busyFeeds.length) return [];
+  const key = `${resource.id}:${resource.busyFeeds.join('|')}:${Math.floor(from / 86_400_000)}`;
+  const hit = busyCache.get(key);
+  if (hit && now - hit.at < 5 * 60_000) return hit.intervals;
+  const intervals: Interval[] = [];
+  await Promise.all(resource.busyFeeds.map(async (url) => {
+    try {
+      const feed = await loadFeed(url, now);
+      for (const e of expandVEvents(feed.vevents, feed.calTz, { displayTz: resource.timezone || 'UTC', now, windowStartMs: from, windowEndMs: to }, 0)) {
+        intervals.push({ start: e.start, end: e.end });
+      }
+    } catch { /* an unreachable busy feed must not block bookings */ }
+  }));
+  busyCache.set(key, { at: now, intervals });
+  if (busyCache.size > 50) busyCache.delete(busyCache.keys().next().value!);
+  return intervals;
+}
+
+export async function availabilityContext(
+  repo: ContentRepository,
+  resource: Resource,
+  link: BookingLink,
+  settings: Pick<Settings, 'timezone'>,
+  now = Date.now(),
+  ignoreBookingId?: string
+): Promise<AvailabilityContext> {
+  const to = now + (link.maxAdvance + 2) * 86_400_000;
+  const [bookings, busy] = await Promise.all([
+    repo.listBookings({ resourceId: resource.id, from: now - 86_400_000, to, statuses: ['pending', 'confirmed'] }),
+    busyIntervals(resource, now - 86_400_000, to, now),
+  ]);
+  return { resource, link, bookings, busy, siteTimezone: settings.timezone, now, ignoreBookingId };
+}
+
+// ---- notifications ---------------------------------------------------------
+
+async function describe(repo: ContentRepository, b: Booking, settings: Settings) {
+  if (b.kind === 'rsvp') {
+    const ev = b.eventId ? await repo.getEvent(b.eventId) : null;
+    const tz = ev ? eventTimeZone(ev, settings) : settings.timezone || 'UTC';
+    return {
+      resource: null, link: null, event: ev,
+      title: ev?.title ?? 'Event',
+      location: ev ? locationLine(ev.location) : '',
+      when: whenText(b, tz, settings, ev?.allDay),
+    };
+  }
+  const [resource, link] = await Promise.all([repo.getResource(b.resourceId), b.linkId ? repo.getBookingLink(b.linkId) : Promise.resolve(null)]);
+  const tz = resource ? resourceZone(resource, settings.timezone) : settings.timezone || 'UTC';
+  return {
+    resource, link, event: null as CalEvent | null,
+    title: [resource?.name, link?.name].filter(Boolean).join(' · ') || 'Booking',
+    location: resource?.name ?? '',
+    when: whenText(b, tz, settings, link?.mode === 'day'),
+  };
+}
+
+export function bookingJson(b: Booking, extra: { title?: string; resourceSlug?: string; linkSlug?: string } = {}) {
+  return {
+    id: b.id, kind: b.kind, status: b.status,
+    start: new Date(b.start).toISOString(), end: new Date(b.end).toISOString(),
+    resourceId: b.resourceId || null, linkId: b.linkId || null, eventId: b.eventId || null,
+    name: b.name, email: b.email, phone: b.phone, seats: b.seats, answers: b.answers,
+    source: b.source, createdAt: new Date(b.createdAt).toISOString(), ...extra,
+  };
+}
+
+export async function bookingMail(repo: ContentRepository, b: Booking, kind: BookingEmail, origin: string, from = '', snapshot?: { message?: string; eventTitle?: string; eventLocation?: string; eventAllDay?: number }) {
+  const settings = await repo.getSettings();
+  const d = await describe(repo,b,settings);
+  if (b.kind === 'rsvp' && !d.event && snapshot?.eventTitle) {
+    d.title = snapshot.eventTitle;
+    try { d.location = locationLine(JSON.parse(snapshot.eventLocation || '{}')); } catch { d.location = ''; }
+    d.when = whenText(b,b.timezone || settings.timezone || 'UTC',settings,!!snapshot.eventAllDay);
+  }
+  return bookingEmail(kind, { booking:b,resource:d.resource,link:d.link,title:d.title,location:d.location,when:d.when,
+    manageUrl:kind === 'staff-new' ? `${origin}/admin/calendar/bookings?b=${b.id}` : origin + manageUrlFor(b.manageToken),
+    siteTitle:settings.siteTitle,host:new URL(origin).host,organizer:parseFrom(from)?.email,message:snapshot?.message,
+    allDay:d.link?.mode==='day'||!!d.event?.allDay||(!d.event&&!!snapshot?.eventAllDay) });
+}
+async function notify(repo: ContentRepository, _b: Booking, _kinds: BookingEmail[], opts: FlowOptions, _message?: string) {
+  // Repository mutations already committed their outbox jobs atomically.
+  await kickEmail(repo,opts.locals,opts.waitUntil);
+}
+
+async function hook(repo: ContentRepository, type: 'booking.created' | 'booking.confirmed' | 'booking.declined' | 'booking.cancelled' | 'booking.rescheduled', b: Booking, opts: FlowOptions) {
+  const settings = await repo.getSettings();
+  const d = await describe(repo, b, settings);
+  await emitWebhook(repo, type, {
+    booking: bookingJson(b, { title: d.title, resourceSlug: d.resource?.slug, linkSlug: d.link?.slug }),
+    ...(d.event ? { eventUrl: opts.origin + eventUrl(d.event.slug) } : {}),
+  }, { waitUntil: opts.waitUntil }).catch(() => {});
+}
+
+// ---- validation --------------------------------------------------------------
+
+export interface BookerInput {
+  name: string;
+  email: string;
+  phone?: string;
+  answers?: Record<string, string>;
+}
+
+export function validateBooker(link: Pick<BookingLink, 'questions' | 'askPhone'> | null, input: BookerInput): { name: string; email: string; phone: string; answers: Record<string, string> } {
+  const name = input.name.trim().slice(0, 120);
+  const email = input.email.trim().toLowerCase().slice(0, 200);
+  if (!name) throw new BookingError(400, 'Please add your name.');
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) throw new BookingError(400, 'Please add a valid email address.');
+  const phone = (input.phone ?? '').trim().slice(0, 40);
+  const answers: Record<string, string> = {};
+  for (const q of link?.questions ?? []) {
+    const raw = (input.answers?.[q.id] ?? '').toString().trim().slice(0, 2000);
+    if (q.required && (!raw || (q.type === 'checkbox' && raw !== 'yes'))) throw new BookingError(400, `Please answer “${q.label}”.`);
+    if (!raw) continue;
+    if (q.type === 'select' && !q.options.includes(raw)) throw new BookingError(400, `Pick one of the options for “${q.label}”.`);
+    if (q.type === 'number' && Number.isNaN(Number(raw))) throw new BookingError(400, `“${q.label}” needs a number.`);
+    if (q.type === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw)) throw new BookingError(400, `“${q.label}” needs an email address.`);
+    answers[q.label] = q.type === 'checkbox' ? 'Yes' : raw;
+  }
+  return { name, email, phone, answers };
+}
+
+// ---- workflows ---------------------------------------------------------------
+
+export async function createResourceBooking(
+  repo: ContentRepository,
+  args: { resource: Resource; link: BookingLink; start: number; end: number; booker: BookerInput; source?: Booking['source']; status?: BookingStatus },
+  opts: FlowOptions
+): Promise<Booking> {
+  const { resource, link } = args;
+  if (!link.active) throw new BookingError(410, 'This booking link is turned off.');
+  const settings = await repo.getSettings();
+  const booker = validateBooker(link, args.booker);
+  // staff adding a booking by hand may ignore notice windows, never overlaps
+  const ctx = await availabilityContext(repo, resource, link, settings, opts.now ?? Date.now());
+  if (args.source !== 'admin' && !isBookable(ctx, args.start, args.end)) throw new BookingError(409, 'That time was just taken or isn’t available. Please pick another.');
+  const status: BookingStatus = args.status ?? (link.autoConfirm ? 'confirmed' : 'pending');
+  const b = await repo.createBooking({
+    kind: 'booking', resourceId: resource.id, linkId: link.id, eventId: '', status,
+    start: args.start, end: args.end, ...holdOf(link, args.start, args.end),
+    timezone: resourceZone(resource, settings.timezone), ...booker, seats: 1, notes: '',
+    manageToken: token(), source: args.source ?? 'web',
+  }, { idempotency: opts.idempotency });
+  if (!b) throw new BookingError(409, 'That time was just taken. Please pick another.');
+  await notify(repo, b, [status === 'confirmed' ? 'confirmed' : 'received', 'staff-new'], opts);
+  await hook(repo, 'booking.created', b, opts);
+  if (status === 'confirmed') await hook(repo, 'booking.confirmed', b, opts);
+  return b;
+}
+
+export async function createBlock(repo: ContentRepository, resource: Resource, start: number, end: number, note: string): Promise<Booking | null> {
+  if (end <= start) throw new BookingError(400, 'The block must end after it starts.');
+  return repo.createBooking({
+    kind: 'block', resourceId: resource.id, linkId: '', eventId: '', status: 'confirmed', start, end, holdStart: start, holdEnd: end,
+    timezone: resource.timezone, name: '', email: '', phone: '', seats: 1, answers: {}, notes: note.slice(0, 500), manageToken: '', source: 'admin',
+  });
+}
+
+export async function seatsTaken(repo: ContentRepository, eventId: string, start: number): Promise<number> {
+  const list = await repo.listBookings({ eventId, from: start - 1, to: start + 1, statuses: ['pending', 'confirmed'], kinds: ['rsvp'] });
+  return list.filter((b) => b.start === start).reduce((n, b) => n + b.seats, 0);
+}
+
+export async function createRsvp(
+  repo: ContentRepository,
+  args: { event: CalEvent; start: number; end: number; seats: number; booker: BookerInput; source?: Booking['source'] },
+  opts: FlowOptions
+): Promise<Booking> {
+  const e = args.event;
+  if (!e.rsvp.enabled) throw new BookingError(400, 'This event doesn’t take RSVPs.');
+  if (e.cancelled) throw new BookingError(410, 'This event is cancelled.');
+  if (args.end <= (opts.now ?? Date.now())) throw new BookingError(410, 'This event has already happened.');
+  const seats = Math.max(1, Math.min(e.rsvp.maxSeats || 1, Math.floor(args.seats) || 1));
+  const booker = validateBooker(null, args.booker);
+  const b = await repo.createBooking({
+    kind: 'rsvp', resourceId: '', linkId: '', eventId: e.id, status: e.rsvp.autoConfirm ? 'confirmed' : 'pending',
+    start: args.start, end: args.end, holdStart: args.start, holdEnd: args.end, timezone: e.timezone, ...booker, seats,
+    notes: '', manageToken: token(), source: args.source ?? 'web',
+  }, { capacity: e.rsvp.capacity, idempotency: opts.idempotency });
+  if (!b) throw new BookingError(409, e.rsvp.capacity ? 'Sorry — that’s more seats than are left.' : 'Couldn’t save your RSVP.');
+  await notify(repo, b, [b.status === 'confirmed' ? 'confirmed' : 'received'], opts);
+  await hook(repo, 'booking.created', b, opts);
+  if (b.status === 'confirmed') await hook(repo, 'booking.confirmed', b, opts);
+  return b;
+}
+
+const TRANSITIONS: Record<BookingStatus, BookingStatus[]> = {
+  pending: ['confirmed', 'declined', 'cancelled'],
+  confirmed: ['cancelled'],
+  declined: ['confirmed'],
+  cancelled: ['confirmed'],
+};
+
+export async function setBookingStatus(repo: ContentRepository, b: Booking, status: BookingStatus, opts: FlowOptions, message?: string): Promise<Booking> {
+  if (b.status === status) return b;
+  if (!TRANSITIONS[b.status].includes(status)) throw new BookingError(409, `A ${b.status} booking can’t become ${status}.`);
+  // re-confirming a declined/cancelled booking must re-check the slot
+  if (status === 'confirmed' && (b.status === 'declined' || b.status === 'cancelled') && b.kind !== 'rsvp') {
+    const clash = (await repo.listBookings({ resourceId: b.resourceId, from: b.holdStart, to: b.holdEnd, statuses: ['pending', 'confirmed'] }))
+      .some((x) => x.id !== b.id && x.kind !== 'rsvp' && x.holdStart < b.holdEnd && x.holdEnd > b.holdStart);
+    if (clash) throw new BookingError(409, 'That time has been booked since — it can’t be restored.');
+  }
+  await repo.updateBooking(b.id, { status, notificationMessage: message });
+  const next = (await repo.getBooking(b.id))!;
+  if (!next || next.status !== status) throw new BookingError(409, 'This booking changed. Refresh and try again.');
+  if (b.kind !== 'block') {
+    await notify(repo, next, [status === 'confirmed' ? 'confirmed' : status === 'declined' ? 'declined' : 'cancelled'], opts, message);
+    await hook(repo, status === 'confirmed' ? 'booking.confirmed' : status === 'declined' ? 'booking.declined' : 'booking.cancelled', next, opts);
+  }
+  return next;
+}
+
+export async function rescheduleBooking(repo: ContentRepository, b: Booking, start: number, end: number, opts: FlowOptions & { skipRules?: boolean }): Promise<Booking> {
+  if (b.kind !== 'booking') throw new BookingError(400, 'Only bookings can be moved.');
+  if (b.status !== 'pending' && b.status !== 'confirmed') throw new BookingError(409, 'Only active bookings can be moved.');
+  const [resource, link, settings] = await Promise.all([repo.getResource(b.resourceId), repo.getBookingLink(b.linkId), repo.getSettings()]);
+  if (!resource || !link) throw new BookingError(404, 'This booking’s room or link no longer exists.');
+  if (!opts.skipRules) {
+    const ctx = await availabilityContext(repo, resource, link, settings, opts.now ?? Date.now(), b.id);
+    if (!isBookable(ctx, start, end)) throw new BookingError(409, 'That time isn’t available.');
+  }
+  const ok = await repo.moveBooking(b.id, { start, end, ...holdOf(link, start, end) });
+  if (!ok) throw new BookingError(409, 'That time was just taken.');
+  const next = (await repo.getBooking(b.id))!;
+  await notify(repo, next, ['rescheduled'], opts);
+  await hook(repo, 'booking.rescheduled', next, opts);
+  return next;
+}
+
+// cron: reminders ~24h ahead (window catches up if a sweep was missed)
+export async function sendDueReminders(repo: ContentRepository, opts: FlowOptions): Promise<number> {
+  const now = opts.now ?? Date.now();
+  const due = await repo.listDueReminders(now + 60 * 60_000, now + 24 * 3600_000);
+  for (const b of due) {
+    await repo.email.enqueue({dedupe:`${b.id}:${b.notificationVersion}:reminder:${b.email}`,kind:'booking',recipient:b.email,
+      payload:JSON.stringify({bookingId:b.id,version:b.notificationVersion,kind:'reminder'}),configVersion:(await repo.email.config())?.version||0,expiresAt:b.start});
+  }
+  await kickEmail(repo,opts.locals,opts.waitUntil);
+  return due.length;
+}

package/src/lib/booking/view.ts

@@ -0,0 +1,54 @@
+// Display helpers for the public booking pages.
+import type { BookingLink, Resource, Settings } from '../schema';
+import { siteLocale } from '../dates';
+import { addDaysYmd, localMidnight, resourceZone, ymd, type Slot } from './availability';
+
+export function fmt(settings: Settings, tz: string) {
+  const locale = siteLocale(settings);
+  const f = (o: Intl.DateTimeFormatOptions) => {
+    try { return new Intl.DateTimeFormat(locale, { ...o, timeZone: tz }); }
+    catch { return new Intl.DateTimeFormat('en-US', { ...o, timeZone: 'UTC' }); }
+  };
+  return {
+    time: f({ hour: 'numeric', minute: '2-digit' }),
+    day: f({ weekday: 'short', month: 'short', day: 'numeric' }),
+    dayLong: f({ weekday: 'long', month: 'long', day: 'numeric' }),
+    month: f({ month: 'long', year: 'numeric' }),
+    dow: f({ weekday: 'narrow' }),
+    zone: f({ timeZoneName: 'long' }).formatToParts(Date.now()).find((p) => p.type === 'timeZoneName')?.value ?? tz,
+  };
+}
+
+export function slotLabel(s: Slot, link: BookingLink, f: ReturnType<typeof fmt>): string {
+  if (link.mode === 'day') return s.minutes === 1440 ? f.dayLong.format(s.start) : `${f.day.format(s.start)} – ${f.day.format(s.end - 1)}`;
+  if (link.mode === 'range') return `${f.time.format(s.start)} – ${f.time.format(s.end)}`;
+  return f.time.format(s.start);
+}
+
+export interface MonthCell { date: string; day: number; inMonth: boolean; open: boolean; past: boolean }
+
+// a Sunday-first month grid for YYYY-MM in the resource zone
+export function monthCells(month: string, open: Set<string>, today: string): MonthCell[] {
+  const [y, m] = month.split('-').map(Number);
+  const first = `${y}-${String(m).padStart(2, '0')}-01`;
+  const dow = new Date(Date.UTC(y, m - 1, 1)).getUTCDay();
+  const cells: MonthCell[] = [];
+  let date = addDaysYmd(first, -dow);
+  for (let i = 0; i < 42; i++, date = addDaysYmd(date, 1)) {
+    const [, mm, dd] = date.split('-').map(Number);
+    cells.push({ date, day: dd, inMonth: mm === m, open: open.has(date), past: date < today });
+  }
+  // drop a trailing week that belongs entirely to the next month
+  return cells.slice(35).every((c) => !c.inMonth) ? cells.slice(0, 35) : cells;
+}
+
+export function addMonths(month: string, n: number): string {
+  const [y, m] = month.split('-').map(Number);
+  const t = y * 12 + (m - 1) + n;
+  return `${Math.floor(t / 12)}-${String((t % 12) + 1).padStart(2, '0')}`;
+}
+
+export function todayIn(resource: Resource, settings: Settings, now: number) {
+  const tz = resourceZone(resource, settings.timezone);
+  return { tz, today: ymd(now, tz), midnight: localMidnight(ymd(now, tz), tz) };
+}

package/src/lib/calendar/agent-schema.ts

@@ -0,0 +1,48 @@
+// Agent / MCP tool inputs for events. Kept apart from lib/agent.ts so that
+// file can compose them into its discriminated union without an import cycle.
+import { z } from 'zod';
+
+const wall = z.string().regex(/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2})?$/, 'Use YYYY-MM-DD or YYYY-MM-DDTHH:mm (wall-clock time in the event timezone).');
+const eventFields = {
+  title: z.string().trim().min(1).max(300).optional(),
+  content: z.string().max(100_000).optional(),
+  excerpt: z.string().max(1000).optional(),
+  start: wall.optional(),
+  end: wall.optional(),
+  allDay: z.boolean().optional(),
+  timezone: z.string().max(80).optional(),
+  rrule: z.string().max(500).optional(),
+  location: z.object({ name: z.string().max(300).default(''), address: z.string().max(500).default(''), url: z.string().max(1000).default('') }).strict().optional(),
+  cta: z.object({ label: z.string().max(120).default(''), href: z.string().max(1000).default(''), style: z.enum(['primary', 'outline']).default('primary') }).strict().optional(),
+  calendars: z.array(z.string().max(100)).max(20).optional(),
+  tags: z.array(z.string().trim().min(1).max(100)).max(50).optional(),
+  cancelled: z.boolean().optional(),
+  seoTitle: z.string().max(300).optional(),
+  seoDesc: z.string().max(2000).optional(),
+};
+
+export const EventToolInputs = [
+  z.object({ tool: z.literal('list_events'), arguments: z.object({
+    scope: z.enum(['upcoming', 'past', 'all']).default('upcoming'),
+    calendar: z.string().optional(),
+    query: z.string().max(200).optional(),
+    offset: z.number().int().min(0).default(0),
+    limit: z.number().int().min(1).max(100).default(25),
+  }).strict() }).strict(),
+  z.object({ tool: z.literal('get_event'), arguments: z.object({ id: z.string().min(1) }).strict() }).strict(),
+  z.object({ tool: z.literal('list_calendars'), arguments: z.object({}).strict() }).strict(),
+  z.object({ tool: z.literal('create_event'), arguments: z.object({ ...eventFields, title: z.string().trim().min(1).max(300), start: wall, slug: z.string().max(300).optional() }).strict() }).strict(),
+  z.object({ tool: z.literal('update_event'), arguments: z.object({ ...eventFields, id: z.string().min(1) }).strict() }).strict(),
+  z.object({ tool: z.literal('publish_event'), arguments: z.object({ id: z.string().min(1) }).strict() }).strict(),
+] as const;
+
+export const EVENT_TOOL_NAMES = ['list_events', 'get_event', 'list_calendars', 'create_event', 'update_event', 'publish_event'] as const;
+
+export const EVENT_TOOL_DESCRIPTIONS: Record<(typeof EVENT_TOOL_NAMES)[number], string> = {
+  list_events: 'List events (drafts included) with their next date. scope: upcoming (default), past, all. Filter by calendar slug or a title search.',
+  get_event: 'Read one event including any pending draft. Times are wall-clock strings in the event timezone.',
+  list_calendars: 'List calendars (slug, name, visibility, kind). Use slugs in create_event/update_event "calendars".',
+  create_event: 'Create a DRAFT event. start/end are wall-clock "YYYY-MM-DDTHH:mm" (or "YYYY-MM-DD" with allDay) in the event timezone (site timezone when omitted). content is Markdown. rrule is an RFC 5545 rule like "FREQ=WEEKLY;BYDAY=TU". Never publishes.',
+  update_event: 'Update supplied event fields. Published/scheduled events stage a pending draft that goes live on publish/Update. calendars replaces the list.',
+  publish_event: 'Publish an event (applying any pending draft). Requires owner-enabled publishing permission.',
+};

package/src/lib/calendar/agent.ts

@@ -0,0 +1,136 @@
+// Agent / MCP tool runner for events. Same contract as the content tools:
+// drafts by default, live events stage edits, publishing needs the owner's
+// permission, content is Markdown sanitized to safe HTML.
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import type { CalEvent } from '../schema';
+import { slugify } from '../schema';
+import { ApiError } from '../api';
+import { renderAgentMarkdown } from '../agent';
+import { CALENDAR } from './config';
+import { EventToolInputs } from './agent-schema';
+import { featuredOccurrence, formatOccurrence, isValidTimeZone, normalizeEventTimes } from './events';
+import { mergeEventDraft } from '../drafts';
+import { eventChanged } from './hooks';
+import { eventToJson } from './api';
+import { siteLocale } from '../dates';
+
+export type EventToolInput = z.infer<(typeof EventToolInputs)[number]>;
+
+export interface AgentContext {
+  origin: string;
+  waitUntil?: (p: Promise<unknown>) => void;
+}
+
+const editUrl = (id: string) => `/admin/calendar/events/${id}`;
+
+async function resolveCalendars(repo: ContentRepository, slugs: string[] | undefined) {
+  if (slugs === undefined) return undefined;
+  const all = await repo.listCalendars();
+  return slugs.map((s) => {
+    const c = all.find((x) => x.slug === s || x.id === s);
+    if (!c) throw new ApiError(400, `Unknown calendar "${s}". Call list_calendars for valid slugs.`);
+    if (c.kind !== 'native') throw new ApiError(400, `"${s}" mirrors an external feed and can't hold events.`);
+    return c.id;
+  });
+}
+
+function checkLinks(a: { cta?: { href: string }; location?: { url: string }; timezone?: string }) {
+  if (a.cta?.href && !/^(https?:\/\/|\/(?!\/)|mailto:|tel:)/i.test(a.cta.href)) throw new ApiError(400, 'cta.href must start with https://, /, mailto: or tel:.');
+  if (a.location?.url && !/^https?:\/\//i.test(a.location.url)) throw new ApiError(400, 'location.url must start with https://.');
+  if (a.timezone && !isValidTimeZone(a.timezone)) throw new ApiError(400, `Unknown timezone "${a.timezone}".`);
+}
+
+export async function runEventTool(repo: ContentRepository, input: EventToolInput, allowPublish: boolean, ctx: AgentContext) {
+  if (!CALENDAR.enabled) throw new ApiError(404, 'The calendar module is disabled on this site.');
+  const settings = await repo.getSettings();
+  const calendars = await repo.listCalendars();
+  const calMap = new Map(calendars.map((c) => [c.id, c]));
+  const now = Date.now();
+  const summary = (e: CalEvent) => {
+    const o = featuredOccurrence(e, settings, now);
+    return {
+      id: e.id, title: e.title, slug: e.slug, status: e.status, cancelled: e.cancelled,
+      start: e.start, end: e.end, allDay: e.allDay, rrule: e.rrule,
+      next: o ? formatOccurrence(o, settings.timezone || 'UTC', siteLocale(settings)).range : '',
+      calendars: e.calendarIds.map((id) => calMap.get(id)?.slug).filter(Boolean),
+      hasPendingDraft: Boolean(e.draft), editUrl: editUrl(e.id),
+    };
+  };
+
+  switch (input.tool) {
+    case 'list_calendars':
+      return { calendars: calendars.map((c) => ({ id: c.id, slug: c.slug, name: c.name, kind: c.kind, visibility: c.visibility, color: c.color })) };
+    case 'list_events': {
+      const a = input.arguments;
+      const cal = a.calendar ? calendars.find((c) => c.slug === a.calendar) : null;
+      if (a.calendar && !cal) throw new ApiError(400, 'Unknown calendar.');
+      let rows = (await repo.listEvents()).map((e) => ({ e, o: featuredOccurrence(e, settings, now) }));
+      if (cal) rows = rows.filter((r) => r.e.calendarIds.includes(cal.id));
+      if (a.query) rows = rows.filter((r) => `${r.e.title} ${r.e.slug}`.toLowerCase().includes(a.query!.toLowerCase()));
+      if (a.scope !== 'all') rows = rows.filter((r) => (r.o ? r.o.end > now : true) === (a.scope === 'upcoming'));
+      rows.sort((x, y) => ((x.o?.start ?? 0) - (y.o?.start ?? 0)) * (a.scope === 'past' ? -1 : 1));
+      return { total: rows.length, offset: a.offset, items: rows.slice(a.offset, a.offset + a.limit).map((r) => summary(r.e)) };
+    }
+    case 'get_event': {
+      const e = await repo.getEvent(input.arguments.id);
+      if (!e) throw new ApiError(404, 'Event not found.');
+      return { ...eventToJson(mergeEventDraft(e), ctx.origin, calMap, settings.timezone), bodyHtml: mergeEventDraft(e).bodyHtml, hasPendingDraft: Boolean(e.draft), editUrl: editUrl(e.id) };
+    }
+    case 'create_event': {
+      const a = input.arguments;
+      checkLinks(a);
+      let times: { start: string; end: string };
+      try { times = normalizeEventTimes({ start: a.start, end: a.end, allDay: a.allDay ?? a.start.length === 10 }); }
+      catch (err) { throw new ApiError(400, err instanceof Error ? err.message : 'Invalid time.'); }
+      const base = slugify(a.slug || a.title);
+      let slug = base;
+      for (let n = 2; await repo.getEventBySlug(slug); n++) slug = `${base}-${n}`;
+      const e = await repo.createEvent({
+        title: a.title, slug, ...times, allDay: a.allDay ?? a.start.length === 10, timezone: a.timezone ?? '',
+        rrule: a.rrule ?? '', excerpt: a.excerpt ?? '', location: a.location, cta: a.cta, tags: a.tags,
+        cancelled: a.cancelled ?? false, seoTitle: a.seoTitle, seoDesc: a.seoDesc,
+        calendarIds: (await resolveCalendars(repo, a.calendars)) ?? [],
+        ...(a.content !== undefined ? { bodyHtml: renderAgentMarkdown(a.content) } : {}),
+      });
+      if (a.tags?.length) await repo.ensureTags(a.tags);
+      return { ...summary(e) };
+    }
+    case 'update_event': {
+      const { id, content, calendars: slugs, ...rest } = input.arguments;
+      checkLinks(rest);
+      const before = await repo.getEvent(id);
+      if (!before) throw new ApiError(404, 'Event not found.');
+      const data: Partial<CalEvent> = { ...rest };
+      if (content !== undefined) {
+        data.bodyHtml = renderAgentMarkdown(content);
+        data.bodyJson = '';
+      }
+      const calendarIds = await resolveCalendars(repo, slugs);
+      if (calendarIds) data.calendarIds = calendarIds;
+      if (data.start !== undefined || data.end !== undefined || data.allDay !== undefined) {
+        const merged = mergeEventDraft(before);
+        try {
+          const t = normalizeEventTimes({ start: data.start ?? merged.start, end: data.end ?? merged.end, allDay: data.allDay ?? merged.allDay });
+          data.start = t.start; data.end = t.end;
+        } catch (err) { throw new ApiError(400, err instanceof Error ? err.message : 'Invalid time.'); }
+      }
+      if (!Object.keys(data).length) throw new ApiError(400, 'Provide at least one field to update.');
+      const staged = before.status === 'published' || before.status === 'scheduled';
+      if (staged) await repo.saveEventDraft(id, data);
+      else await repo.updateEvent(id, data);
+      if (data.tags?.length) await repo.ensureTags(data.tags);
+      return { ...summary((await repo.getEvent(id))!), staged };
+    }
+    case 'publish_event': {
+      if (!allowPublish) throw new ApiError(403, 'Agent publishing is disabled. An owner can enable it in Settings.');
+      const before = await repo.getEvent(input.arguments.id);
+      if (!before) throw new ApiError(404, 'Event not found.');
+      if (before.draft) await repo.applyEventDraft(before.id);
+      await repo.updateEvent(before.id, { status: 'published', scheduledAt: null });
+      const after = (await repo.getEvent(before.id))!;
+      await eventChanged(repo, before, after, { origin: ctx.origin, waitUntil: ctx.waitUntil, applied: Boolean(before.draft) });
+      return { ...summary(after) };
+    }
+  }
+}

package/src/lib/calendar/api.ts

@@ -0,0 +1,81 @@
+// The public JSON shape of an event — one definition shared by the REST API,
+// webhook payloads and agent tools, so integrations see the same fields
+// everywhere. Drafts, internal ids of private calendars and staging data
+// never appear here.
+import type { CalEvent, Calendar } from '../schema';
+import { calendarFeedUrl, eventIcsUrl, eventUrl } from './config';
+import { describeRepeat } from './rrule';
+
+export interface EventJson {
+  id: string;
+  slug: string;
+  url: string;
+  icsUrl: string;
+  title: string;
+  excerpt: string;
+  status: string;
+  cancelled: boolean;
+  featured: boolean;
+  start: string;
+  end: string;
+  allDay: boolean;
+  timezone: string;
+  rrule: string;
+  repeats: string;
+  exdates: string[];
+  location: CalEvent['location'];
+  cta: CalEvent['cta'];
+  image: string;
+  imageAlt: string;
+  tags: string[];
+  calendars: { id: string; slug: string; name: string; color: string }[];
+  fields: Record<string, string>;
+  updatedAt: string;
+}
+
+const abs = (origin: string, path: string) => (/^https?:\/\//.test(path) ? path : origin + path);
+
+export function eventToJson(e: CalEvent, origin: string, calendars: Map<string, Calendar>, siteTz = ''): EventJson {
+  return {
+    id: e.id,
+    slug: e.slug,
+    url: abs(origin, eventUrl(e.slug)),
+    icsUrl: abs(origin, eventIcsUrl(e.slug)),
+    title: e.title,
+    excerpt: e.excerpt,
+    status: e.status,
+    cancelled: e.cancelled,
+    featured: e.featured,
+    start: e.start,
+    end: e.end,
+    allDay: e.allDay,
+    timezone: e.timezone || siteTz || 'UTC',
+    rrule: e.rrule,
+    repeats: describeRepeat(e.rrule, e.start),
+    exdates: e.exdates,
+    location: e.location,
+    cta: e.cta,
+    image: e.cover ? abs(origin, e.cover) : '',
+    imageAlt: e.coverAlt,
+    tags: e.tags.filter((t) => !t.startsWith('#')),
+    calendars: e.calendarIds
+      .map((id) => calendars.get(id))
+      .filter((c): c is Calendar => Boolean(c) && c!.visibility !== 'private')
+      .map((c) => ({ id: c.id, slug: c.slug, name: c.name, color: c.color })),
+    fields: e.fields,
+    updatedAt: new Date(e.updatedAt).toISOString(),
+  };
+}
+
+export function calendarToJson(c: Calendar, origin: string) {
+  return {
+    id: c.id,
+    slug: c.slug,
+    name: c.name,
+    color: c.color,
+    description: c.description,
+    kind: c.kind,
+    visibility: c.visibility,
+    feedUrl: c.visibility === 'public' || c.visibility === 'unlisted' ? abs(origin, calendarFeedUrl(c.slug)) : '',
+  };
+}