@acms-subir/core 0.3.9 → 0.3.10

package/src/lib/mobile/openapi.ts

@@ -5,6 +5,10 @@ import { contentQuery, contentDetailQuery } from './content';
 import { eventsQuery, availabilityQuery } from './calendar';
 import { bookingInput } from './bookings';
 import { pagesQuery } from './pages';
+import { searchQuery } from './search';
+import { manageAvailabilityQuery, rescheduleInput } from './manage';
+import { formResponseInput } from './forms';
+import { codeInput, tokenInput, myBookingsQuery } from './guest';
 import { deviceInput, deviceUpdate } from '../push/api';
 import { pageQuery, queryParams } from './http';
 import * as schemas from './schemas';
@@ -24,7 +28,7 @@ const readHeaders = {
 };
 const errors = Object.fromEntries([400, 404, 405, 429, 500].map(status => [status, {
   description: status === 429 ? 'Read limit exceeded (300/minute/client address).' : 'Request failed.', content: media(ref('Error')),
-  ...(status === 429 ? { headers: { 'Retry-After': { schema: { type: 'string', const: '60' } } } } : {}),
+  ...(status === 429 ? { headers: { 'Retry-After': { description: 'Seconds to wait: 60 for per-minute limits, longer for hourly, daily and lockout limits.', schema: { type: 'string' } } } } : {}),
 }]));
 function parameters(query: z.AnyZodObject) {
   return Object.entries(query.shape).map(([name, schema]) => ({ name, in: 'query', required: !(schema as z.ZodTypeAny).isOptional(), schema: jsonSchema(schema as z.ZodTypeAny) }));
@@ -37,13 +41,16 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     ['/theme', 'Active Design tokens including overrides', empty, ref('Theme')],
     ['/pages/home', 'Published home page and resolved sections', pagesQuery, ref('Page')],
     ['/pages/{slug}', 'Published page and resolved sections (slug may contain slashes)', pagesQuery, ref('Page')],
-    ['/content', 'Published content in the requested language', contentQuery, jsonSchema(z.object({ locale: z.string().nullable(), items: z.array(schemas.ContentSummary), pagination: schemas.Pagination }))],
+    ['/content', 'Published content in the requested language; q (requires search) returns ranked matches, posts before pages, up to 200 per kind', contentQuery, jsonSchema(z.object({ locale: z.string().nullable(), items: z.array(schemas.ContentSummary), pagination: schemas.Pagination }))],
     ['/content/{id}', 'Published content detail', contentDetailQuery, ref('Content')],
+    ['/search', 'Ranked matches across posts, pages and events (top limit per group); requires search', searchQuery, ref('SearchResults')],
     ['/events', 'Public event occurrences; requires calendar', eventsQuery, ref('Events')],
     ['/calendars', 'Public calendars; requires calendar', empty, ref('Calendars')],
     ['/resources', 'Public resources and booking links; requires bookings', z.object(pageQuery).strict(), ref('Resources')],
     ['/availability', 'Current availability; requires bookings', availabilityQuery, ref('Availability'), false],
     ['/push/topics', 'Topics an app can offer as notification toggles; requires push', empty, ref('PushTopics')],
+    ['/links', 'The links page: profile, socials and visible blocks in order (owner switch: links)', empty, ref('Links')],
+    ['/forms/{id}', 'A published form’s questions; 410 when it stopped accepting responses (owner switch: forms)', empty, ref('Form')],
     ['/openapi.json', 'OpenAPI 3.1 document (no v1 envelope)', empty, { type: 'object', required: ['openapi', 'info', 'paths', 'components'] }],
   ];
   for (const [path, summary, query, schema, cache = true] of reads) {
@@ -72,6 +79,35 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     },
     options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } },
   };
+  // private reads and writes: no-store, credential in a header, never the URL
+  const bookingToken = { name: 'Booking-Token', in: 'header', required: true, description: 'The booking’s private token (manageToken from POST /bookings or GET /guest/bookings). Unknown tokens count against the caller: 20 misses in 10 minutes locks the address out for a while.', schema: { type: 'string' } };
+  const priv = (summary: string, response: unknown, o: { query?: z.AnyZodObject; body?: z.ZodTypeAny; header?: unknown; guest?: boolean; status?: number; description?: string; write?: boolean } = {}) => ({
+    summary, ...(o.description ? { description: o.description } : {}),
+    ...(o.guest ? { security: [{ guestToken: [] }] } : {}),
+    parameters: [...(o.query ? parameters(o.query) : []), ...(o.header ? [o.header] : [])],
+    ...(o.body ? { requestBody: { required: true, content: media(jsonSchema(o.body)) } } : {}),
+    responses: { ...errors, ...(o.write ? Object.fromEntries([409, 410, 413, 415].map(code => [code, { description: 'Request rejected.', content: media(ref('Error')) }])) : {}),
+      ...(o.guest ? { 401: { description: 'Missing, expired or signed-out guest token: sign in again.', content: media(ref('Error')) } } : {}),
+      [o.status ?? 200]: { description: 'Success.', headers: { 'Cache-Control': { schema: { type: 'string', const: 'no-store' } } }, content: media(envelope(response)) } },
+  });
+  const cors = { options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } } };
+  const manageNote = 'Requires the calendar and the owner switch bookingChanges. Same rules and emails as the booking’s web page; a booking type’s change cutoff closes guest changes that many hours before the start.';
+  paths['/api/v1/bookings/manage'] = { get: priv('The booker’s own booking: status, time, place, what they may still change', ref('ManagedBooking'), { header: bookingToken, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/cancel'] = { post: priv('Cancel the booking (repeating is harmless)', ref('ManagedBooking'), { header: bookingToken, write: true, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/availability'] = { get: priv('Open times for moving the booking (its own time counts as free)', ref('Availability'), { header: bookingToken, query: manageAvailabilityQuery, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/reschedule'] = { post: priv('Move the booking to a new start (room bookings, not RSVPs)', ref('ManagedBooking'), { header: bookingToken, body: rescheduleInput, write: true, description: manageNote }), ...cors };
+  paths['/api/v1/bookings/manage/ics'] = { get: { summary: 'Calendar file for the booking (text/calendar, no v1 envelope)', parameters: [bookingToken],
+    responses: { ...errors, 200: { description: 'An iCalendar file.', content: { 'text/calendar': { schema: { type: 'string' } } } } } }, ...cors };
+  paths['/api/v1/forms/{id}/responses'] = { post: { ...priv('Send a response to a published form', ref('FormReceipt'), { body: formResponseInput, write: true, status: 201,
+    description: 'Same validation as the web form. Idempotency-Key (UUID v4) is the response id: retries never duplicate. 10 responses per address per form per minute, plus the owner’s daily ceiling per form (429). version from GET /forms/{id}: a changed form answers 409. Leave website empty (spam trap).' }),
+    parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }, { name: 'Idempotency-Key', in: 'header', required: true, schema: { type: 'string', format: 'uuid' } }] }, ...cors };
+  const guestNote = 'Guest sign-in needs the calendar, working email, EMAIL_ENCRYPTION_KEY and the owner switch guestSignIn (site.features.guestSignIn); 404 otherwise.';
+  paths['/api/v1/guest/code'] = { post: priv('Email a 6-digit sign-in code (always answers the same, whether or not the address has bookings)', ref('GuestCodeSent'), { body: codeInput, write: true, status: 202,
+    description: `${guestNote} Codes last 10 minutes; a new request voids the old code. 3 codes per address and 20 per client address per 15 minutes.` }), ...cors };
+  paths['/api/v1/guest/token'] = { post: priv('Trade email + code for a guest token for this device', ref('GuestToken'), { body: tokenInput, write: true,
+    description: `${guestNote} 5 tries per code; 30 failures per client address in 10 minutes locks it out. Keep the token in secure storage; it ends after 90 days unused.` }), ...cors };
+  paths['/api/v1/guest/bookings'] = { get: priv('Bookings and RSVPs made with the signed-in email (upcoming or past)', ref('GuestBookings'), { query: myBookingsQuery, guest: true, description: guestNote }), ...cors };
+  paths['/api/v1/guest/revoke'] = { post: priv('Sign this device out', ref('GuestSignedOut'), { guest: true, write: true }), ...cors };
   const writeErrors = { ...errors, 429: { ...errors[429], description: 'Write limit exceeded (20/minute/client address).' },
     ...Object.fromEntries([413, 415].map(code => [code, { description: 'Request rejected.', content: media(ref('Error')) }])) };
   const noStore = { 'Cache-Control': { schema: { type: 'string', const: 'no-store' } } };
@@ -101,11 +137,11 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
   };
   Object.assign(paths, editorPaths(jsonSchema));
   return {
-    openapi: '3.1.0', info: { title: 'ACMS Mobile API', version: '1.0.0', description: 'Public API: no authentication. Disabled modules are not registered. Unknown or duplicate query parameters are rejected. locale selects translated words with main-language fallback; unknown locales return 400. Editor API (tag Editor): /api/v1/auth/* and /api/v1/admin/*, registered only when acms({ mobile: { editor } }) is configured; staff sign in through the browser (OAuth 2.0 authorization code + PKCE) and send the device access token as a Bearer header. Cookies never authenticate it.' },
+    openapi: '3.1.0', info: { title: 'ACMS Mobile API', version: '1.0.0', description: 'Public API: no authentication, except a booking’s own routes (/bookings/manage/*: its private token in the Booking-Token header) and guest sign-in (/guest/*: a guest token from an emailed code). Owner switches in Admin → Mobile app turn app features off (404). Disabled modules are not registered. Unknown or duplicate query parameters are rejected. locale selects translated words with main-language fallback; unknown locales return 400. Editor API (tag Editor): /api/v1/auth/* and /api/v1/admin/*, registered only when acms({ mobile: { editor } }) is configured; staff sign in through the browser (OAuth 2.0 authorization code + PKCE) and send the device access token as a Bearer header. Cookies never authenticate it.' },
     tags: [{ name: 'Public', description: 'Visitor apps: no authentication.' }, { name: 'Editor', description: 'Editor apps: device sign-in and the admin API.' }],
     paths, components: {
       schemas: Object.fromEntries([...Object.entries(schemas), ...Object.entries(editorSchemas)].map(([name, schema]) => [name, jsonSchema(schema as z.ZodTypeAny)])),
-      securitySchemes: editorSecuritySchemes,
+      securitySchemes: { ...editorSecuritySchemes, guestToken: { type: 'http', scheme: 'bearer', bearerFormat: 'acms_guest_…', description: 'Guest token from POST /api/v1/guest/token. Reads that email’s bookings only.' } },
     },
   };
 }

package/src/lib/mobile/route.ts

@@ -2,14 +2,14 @@ import type { APIRoute } from 'astro';
 import type { ContentRepository } from '../repo/types';
 import { getRepo } from '../repo';
 import { limitRequest, failure, publicResponse, response } from './http';
-export function readRoute(load: (repo: ContentRepository, url: URL, id: string) => Promise<unknown>, cache = true, raw = false): APIRoute {
+export function readRoute(load: (repo: ContentRepository, url: URL, id: string, locals: unknown) => Promise<unknown>, cache = true, raw = false): APIRoute {
   return async context => {
     try {
       const repo = await getRepo(context.locals);
       let address = 'unknown';
       try { address = context.clientAddress || address; } catch { /* adapters without a client address share a bucket */ }
       await limitRequest(repo, address);
-      const data = await load(repo, context.url, context.params.id ?? context.params.slug ?? '');
+      const data = await load(repo, context.url, context.params.id ?? context.params.slug ?? '', context.locals);
       const res = cache ? await publicResponse(context.request, data, raw) : response(data);
       return context.request.method === 'HEAD' ? new Response(null, { status: res.status, headers: res.headers }) : res;
     } catch (error) {
@@ -18,3 +18,25 @@ export function readRoute(load: (repo: ContentRepository, url: URL, id: string)
     }
   };
 }
+
+export interface PublicContext { repo: ContentRepository; request: Request; url: URL; address: string; params: Record<string, string | undefined>; locals: unknown }
+/**
+ * A private or write route on the public API: rate limited per client
+ * address (reads 300/min, writes 20/min), never cached, v1 envelope.
+ * Handlers may return a Response (files, custom status).
+ */
+export function privateRoute(handler: (c: PublicContext) => Promise<unknown>, opts: { write?: boolean; status?: number } = {}): APIRoute {
+  return async context => {
+    try {
+      const repo = await getRepo(context.locals);
+      let address = 'unknown';
+      try { address = context.clientAddress || address; } catch { /* adapters without a client address share a bucket */ }
+      await limitRequest(repo, address, opts.write);
+      const data = await handler({ repo, request: context.request, url: context.url, address, params: context.params, locals: context.locals });
+      if (data instanceof Response) return data;
+      return response(data, opts.status ?? 200);
+    } catch (error) {
+      return failure(error);
+    }
+  };
+}

package/src/lib/mobile/schemas.ts

@@ -8,7 +8,7 @@ const Palette = z.object({ bg: str, ink: str, muted: str, line: str, accent: str
 export const Site = z.object({
   name: str, description: str, logo: str, logoDark: str, icon: str, menu: z.array(z.object({ label: str, href: str })),
   languages: z.object({ default: locale, locales: z.array(z.object({ code: str, name: str })) }),
-  features: z.object({ blog: z.array(z.object({ key: str, name: str, url: str })), calendar: bool, bookings: bool, search: bool }), apiVersion: z.literal(1),
+  features: z.object({ blog: z.array(z.object({ key: str, name: str, url: str })), calendar: bool, bookings: bool, search: bool, bookingChanges: bool, guestSignIn: bool, forms: bool, links: bool }), apiVersion: z.literal(1),
 });
 export const Theme = z.object({
   id: str, name: str, scheme: z.enum(['auto', 'light', 'dark']), colors: z.object({ light: Palette, dark: Palette }),
@@ -35,6 +35,57 @@ export const Event = CalEvent.pick({
 export const Events = z.object({ locale, timezone: str, from: date, to: date, pagination: Pagination,
   occurrences: z.array(z.object({ id: str, start: date, end: date, allDay: bool, event: Event })),
 });
+const Snippet = z.object({ text: str, highlights: z.array(z.object({ start: z.number().int(), end: z.number().int() })) });
+const ContentHit = ContentSummary.extend({ snippet: Snippet });
+export const SearchResults = z.object({ locale, query: str,
+  posts: z.array(ContentHit), pages: z.array(ContentHit),
+  events: z.array(z.object({ snippet: Snippet, occurrence: z.object({ start: date, end: date, allDay: bool }).nullable(), event: Event })),
+  more: z.object({ posts: bool, pages: bool, events: bool }),
+});
+const Icon = z.object({ type: z.enum(['svg', 'image', 'emoji']), value: str }).nullable();
+const ButtonStyle = { color: str.nullable(), textColor: str.nullable() };
+export const Links = z.object({
+  name: str, bio: str, avatar: str, url: str,
+  socials: z.array(z.object({ label: str, url: str, iconPath: str.nullable() })),
+  items: z.array(z.discriminatedUnion('kind', [
+    z.object({ id: str, kind: z.literal('link'), label: str, url: str, destination: str, icon: Icon, ...ButtonStyle }),
+    z.object({ id: str, kind: z.literal('email'), label: str, url: str, icon: Icon, ...ButtonStyle }),
+    z.object({ id: str, kind: z.literal('phone'), label: str, url: str, icon: Icon, ...ButtonStyle }),
+    z.object({ id: str, kind: z.literal('contact'), label: str, icon: Icon, ...ButtonStyle, contact: z.object({ firstName: str, lastName: str, organization: str, phone: str, email: str, url: str }) }),
+    z.object({ id: str, kind: z.literal('heading'), label: str }),
+    z.object({ id: str, kind: z.literal('text'), text: str }),
+    z.object({ id: str, kind: z.literal('spacer'), size: z.enum(['s', 'm', 'l']) }),
+    z.object({ id: str, kind: z.literal('live') }),
+    z.object({ id: str, kind: z.literal('embed'), url: str }),
+  ])),
+});
+export const Form = z.object({
+  id: str, version: str, title: str, intro: str, submitLabel: str, confirmation: str,
+  fields: z.array(z.object({
+    id: str, type: z.enum(['text', 'textarea', 'email', 'phone', 'number', 'select', 'checkbox', 'date', 'radio', 'checkboxes', 'url', 'consent', 'heading']),
+    label: str, required: bool, help: str, options: strings, placeholder: str, width: z.enum(['full', 'half']), allowOther: bool,
+  })),
+});
+export const FormReceipt = z.object({ received: z.literal(true), confirmation: str });
+const GuestChanges = z.object({ cancel: bool, reschedule: bool, cutoffHours: z.number().int(), closed: bool });
+export const ManagedBooking = z.object({
+  booking: z.object({
+    id: str, reference: str, kind: z.enum(['booking', 'rsvp']), status: z.enum(['pending', 'confirmed', 'declined', 'cancelled']),
+    start: date, end: date, allDay: bool, timezone: str, seats: z.number().int(), name: str, email: str, phone: str, answers: z.record(str), createdAt: date,
+  }),
+  title: str, location: str,
+  resource: z.object({ slug: str, name: str }).nullable(),
+  link: z.object({ slug: str, name: str, mode: z.enum(['slots', 'range', 'day']), lengths: z.array(z.number()) }).nullable(),
+  event: z.object({ slug: str, title: str, url: str }).nullable(),
+  manageUrl: str, can: GuestChanges,
+});
+export const GuestCodeSent = z.object({ sent: z.literal(true), expiresInMinutes: z.number().int() });
+export const GuestToken = z.object({ accessToken: str, tokenType: z.literal('Bearer'), email: str, idleDays: z.number().int() });
+export const GuestBookings = z.object({ email: str, pagination: Pagination, items: z.array(z.object({
+  id: str, reference: str, kind: z.enum(['booking', 'rsvp']), status: z.enum(['pending', 'confirmed', 'declined', 'cancelled']),
+  start: date, end: date, seats: z.number().int(), title: str, manageToken: str, manageUrl: str, can: GuestChanges,
+})) });
+export const GuestSignedOut = z.object({ signedOut: z.literal(true) });
 export const Calendars = z.object({ calendars: z.array(Calendar.pick({ id: true, slug: true, name: true, color: true, description: true, kind: true, visibility: true }).extend({ feedUrl: str })) });
 export const Resources = z.object({ pagination: Pagination, resources: z.array(z.object({
   id: str, slug: str, name: str, kind: str, description: str, capacity: z.number(), amenities: strings, photo: str, timezone: str, url: str,

package/src/lib/mobile/search.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import { CONTENT } from '../content';
+import { normalizePageLocale } from '../i18n';
+import { siteOrigin } from '../seo';
+import { SEARCH } from '../search-config';
+import { CALENDAR } from '../calendar/config';
+import { eventIsListed, featuredOccurrence } from '../calendar/events';
+import { localizeDoc } from '../translations';
+import { ApiError } from '../api';
+import { contentDto } from './content';
+import { publicEventDto } from './calendar';
+import { queryParams } from './http';
+import { localeQuery, mobileLocale } from './locale';
+
+// One query across posts, pages and events for an app's search screen: the
+// same FTS index and ranking as the website's search box. Each group holds
+// the top `limit` matches; `more` says a group has further matches, which
+// apps page through with /content?q= (or /events?q=, date-ordered in a window,
+// matching the same index plus title/excerpt/location).
+
+const TYPES = ['post', 'page', 'event'] as const;
+export const searchQuery = z.object({
+  q: z.string().trim().min(1).max(100),
+  types: z.string().max(40).optional()
+    .transform((v, ctx) => {
+      const list = v ? v.split(',').map((t) => t.trim()).filter(Boolean) : [...TYPES];
+      const bad = list.find((t) => !(TYPES as readonly string[]).includes(t));
+      if (bad) { ctx.addIssue({ code: 'custom', message: 'Use a comma-separated list of post, page and event.' }); return z.NEVER; }
+      return list as (typeof TYPES)[number][];
+    }),
+  collection: z.string().min(1).max(80).optional(),
+  limit: z.coerce.number().int().min(1).max(20).default(5),
+  locale: localeQuery,
+}).strict();
+
+const MARK = /<mark>(.*?)<\/mark>/g;
+const decode = (s: string) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+/** The repo's safe-HTML snippet as plain text plus the matched ranges. */
+export function plainSnippet(html: string) {
+  let text = '';
+  const highlights: { start: number; end: number }[] = [];
+  let last = 0;
+  for (const m of html.matchAll(MARK)) {
+    text += decode(html.slice(last, m.index));
+    const start = text.length;
+    text += decode(m[1]);
+    highlights.push({ start, end: text.length });
+    last = m.index! + m[0].length;
+  }
+  return { text: text + decode(html.slice(last)), highlights };
+}
+
+export async function search(repo: ContentRepository, url: URL) {
+  if (!SEARCH.enabled) throw new ApiError(404, 'This feature is disabled.');
+  const q = searchQuery.parse(queryParams(url));
+  if (q.collection && !Object.hasOwn(CONTENT.collections, q.collection)) throw new ApiError(400, 'Unknown collection.');
+  const locale = mobileLocale(q.locale);
+  const [found, settings, calendars] = await Promise.all([
+    repo.searchPublished(q.q, { locale: normalizePageLocale(locale ?? ''), limit: q.limit + 1, collections: q.collection ? [q.collection] : Object.keys(CONTENT.collections) }),
+    repo.getSettings(), repo.listCalendars(),
+  ]);
+  const origin = siteOrigin(settings, url);
+  const want = new Set(q.types);
+  const posts = want.has('post') ? found.posts : [];
+  // a collection narrows the search to that collection's posts
+  const pages = want.has('page') && !q.collection ? found.pages : [];
+  const all = new Map(calendars.map((c) => [c.id, c]));
+  const listed = new Map(calendars.filter((c) => c.visibility === 'public').map((c) => [c.id, c]));
+  let events = want.has('event') && CALENDAR.enabled && !q.collection ? found.events.filter(({ doc }) => eventIsListed(doc, all)) : [];
+  // the index ranks before visibility is known: if unlisted events filled the
+  // first batch, look deeper once (the repo's 200-row cap) for listed ones
+  if (want.has('event') && CALENDAR.enabled && !q.collection && events.length <= q.limit && found.events.length >= q.limit + 1) {
+    const deeper = await repo.searchPublished(q.q, { locale: normalizePageLocale(locale ?? ''), limit: 200, collections: [] });
+    events = deeper.events.filter(({ doc }) => eventIsListed(doc, all));
+  }
+  const now = Date.now();
+  const iso = (n: number) => new Date(n).toISOString();
+  return {
+    locale, query: q.q,
+    posts: posts.slice(0, q.limit).map(({ doc, snippet }) => ({ ...contentDto(doc, 'post', origin, false, locale), snippet: plainSnippet(snippet) })),
+    pages: pages.slice(0, q.limit).map(({ doc, snippet }) => ({ ...contentDto(doc, 'page', origin, false, locale), snippet: plainSnippet(snippet) })),
+    events: events.slice(0, q.limit).map(({ doc, snippet }) => {
+      const e = localizeDoc(doc, locale ?? undefined);
+      const o = featuredOccurrence(e, settings, now);
+      return {
+        snippet: plainSnippet(snippet),
+        // the next occurrence, or the latest one when the event is over
+        occurrence: o ? { start: iso(o.start), end: iso(o.end), allDay: o.allDay } : null,
+        event: publicEventDto(e, origin, listed, settings.timezone, locale),
+      };
+    }),
+    more: { posts: posts.length > q.limit, pages: pages.length > q.limit, events: events.length > q.limit },
+  };
+}

package/src/lib/mobile/site.ts

@@ -9,8 +9,9 @@ import { resolveDesign } from '../theme';
 import { darkPalette } from '../themeTokens';
 import { safeUrl } from './content';
 import { queryParams } from './http';
+import { guestSignInReady } from './guest';
 
-export async function getSite(repo: ContentRepository, url: URL) {
+export async function getSite(repo: ContentRepository, url: URL, _id = '', locals?: unknown) {
   z.object({}).strict().parse(queryParams(url));
   const [settings, nav, pages] = await Promise.all([repo.getSettings(), repo.listNavItems(), repo.listPages()]);
   const origin = siteOrigin(settings, url);
@@ -26,7 +27,12 @@ export async function getSite(repo: ContentRepository, url: URL) {
     logo: safeUrl(settings.siteLogo, origin), logoDark: safeUrl(settings.siteLogoDark, origin), icon: safeUrl(settings.siteFavicon, origin),
     menu: menu.map(n => ({ label: n.label, href: safeUrl(n.url, origin, true) })),
     languages: { default: I18N.defaultLocale || null, locales: I18N.locales.map(code => ({ code, name: localeName(code, true) })) },
-    features: { blog: Object.entries(CONTENT.collections).map(([key, c]) => ({ key, name: c.plural, url: safeUrl(c.base, origin) })), calendar: CALENDAR.enabled, bookings: bookingsEnabled(), search: SEARCH.enabled },
+    features: {
+      blog: Object.entries(CONTENT.collections).map(([key, c]) => ({ key, name: c.plural, url: safeUrl(c.base, origin) })), calendar: CALENDAR.enabled, bookings: bookingsEnabled(), search: SEARCH.enabled,
+      // Admin → Mobile app → App access
+      bookingChanges: CALENDAR.enabled && settings.mobileAccess.bookingChanges, guestSignIn: await guestSignInReady(repo, locals),
+      forms: settings.mobileAccess.forms, links: settings.mobileAccess.links,
+    },
     apiVersion: 1,
   };
 }

package/src/lib/monitoring.ts

@@ -0,0 +1,171 @@
+import type { ContentRepository } from './repo/types';
+import type { Monitoring } from './schema';
+import { resolveConfig, runtimeValue } from './email/config';
+import { z } from 'zod';
+import { ApiError } from './api';
+import { fetchPublicUrl } from './net';
+
+// Uptime monitoring with Uptime Kuma: a public health check Kuma polls
+// (GET /api/health), a heartbeat the scheduler pushes to a Kuma push monitor
+// after every run, and a reader for a Kuma status page (Settings → Monitoring).
+
+/** the scheduler runs every minute; three missed runs means it stopped */
+export const SCHEDULER_STALE_MS = 3 * 60_000;
+/** queued mail this far past its send time means the queue is stuck */
+const EMAIL_STUCK_MS = 15 * 60_000;
+const CACHE_MS = 10_000;
+
+export type CheckState = 'ok' | 'down' | 'stalled' | 'stuck' | 'off';
+export interface HealthReport {
+  /** down: the site can't do its job (503); degraded: email is stuck (200) */
+  status: 'ok' | 'degraded' | 'down';
+  checks: { database: CheckState; scheduler: CheckState; email: CheckState };
+  checkedAt: string;
+}
+
+let cached: { at: number; report: HealthReport } | null = null;
+/** test hook */
+export const resetHealthCache = () => { cached = null; };
+
+export async function healthReport(repo: ContentRepository, locals?: unknown, now = Date.now()): Promise<HealthReport> {
+  if (cached && now - cached.at < CACHE_MS) return cached.report;
+  const checks: HealthReport['checks'] = { database: 'down', scheduler: 'stalled', email: 'off' };
+  try {
+    await repo.getSettings();
+    checks.database = 'ok';
+    const run = await repo.email.schedulerStatus();
+    checks.scheduler = run && now - run.finishedAt < SCHEDULER_STALE_MS ? 'ok' : 'stalled';
+    const email = resolveConfig(await repo.email.config(), locals);
+    if (!email.error && email.provider !== 'none' && email.config.enabled) checks.email = await repo.email.stuckJobs(now - EMAIL_STUCK_MS) > 0 ? 'stuck' : 'ok';
+  } catch { /* whatever didn't answer stays failed */ }
+  const status = checks.database !== 'ok' || checks.scheduler !== 'ok' ? 'down' : checks.email === 'stuck' ? 'degraded' : 'ok';
+  const report: HealthReport = { status, checks, checkedAt: new Date(now).toISOString() };
+  cached = { at: now, report };
+  return report;
+}
+
+// ---- scheduler heartbeat ----------------------------------------------------
+
+const PUSH = /^https?:\/\/[^/?#\s]+(?:\/[^?#\s]*)?\/api\/push\/[A-Za-z0-9_-]{4,100}$/;
+/** a Kuma push URL without its query (Kuma shows "?status=up&msg=OK&ping=" after it) */
+export function normalizePushUrl(raw: string): string | null {
+  const url = raw.trim().split('?')[0].replace(/\/+$/, '');
+  return url === '' ? '' : PUSH.test(url) ? url : null;
+}
+/** UPTIME_PUSH_URL wins over the admin setting */
+export function pushUrlFor(monitoring: Partial<Monitoring> | undefined, locals?: unknown) {
+  return normalizePushUrl(runtimeValue('UPTIME_PUSH_URL', locals)) || normalizePushUrl(monitoring?.pushUrl ?? '') || '';
+}
+
+/**
+ * Tells the Kuma push monitor the scheduler ran (status=down names the
+ * failed jobs). Never throws and gives up after 5 s: a slow or missing Kuma
+ * must not affect the site.
+ */
+export async function pushHeartbeat(url: string, report: { ok: boolean; startedAt: number; finishedAt: number; jobs: Record<string, { ok: boolean }> }, message?: string) {
+  if (!url) return false;
+  const failed = Object.entries(report.jobs).filter(([, j]) => !j.ok).map(([name]) => name);
+  const q = new URLSearchParams({
+    status: report.ok ? 'up' : 'down',
+    msg: message ?? (report.ok ? `${Object.keys(report.jobs).length} jobs ok` : `failed: ${failed.join(', ')}`),
+    ping: String(Math.max(0, report.finishedAt - report.startedAt)),
+  });
+  try {
+    const res = await fetch(`${url}?${q}`, { signal: AbortSignal.timeout(5000), headers: { 'User-Agent': 'acms-scheduler' } });
+    const body = await res.json().catch(() => null) as { ok?: boolean } | null;
+    return res.ok && body?.ok !== false;
+  } catch { return false; }
+}
+
+// ---- status page (admin card) -----------------------------------------------
+
+/** https://kuma.example/status/my-site → { origin, slug } */
+export function parseStatusPage(raw: string): { origin: string; slug: string } | null {
+  try {
+    const u = new URL(raw.trim());
+    const m = /^\/status\/([A-Za-z0-9_-]{1,100})\/?$/.exec(u.pathname);
+    return /^https?:$/.test(u.protocol) && m ? { origin: u.origin, slug: m[1] } : null;
+  } catch { return null; }
+}
+
+export interface MonitorStatus { id: number; name: string; status: 'up' | 'down' | 'pending' | 'maintenance' | 'unknown'; since: string | null; uptime24h: number | null; message: string; recent: ('up' | 'down' | 'pending' | 'maintenance')[] }
+const STATES = ['down', 'up', 'pending', 'maintenance'] as const;
+// Kuma writes "2026-10-03 12:00:00" in UTC without a zone
+const iso = (t: string) => { const n = Date.parse(/[zZ]|[+-]\d\d:?\d\d$/.test(t) ? t : `${t.replace(' ', 'T')}Z`); return Number.isFinite(n) ? new Date(n).toISOString() : null; };
+let pageCache: { key: string; at: number; data: MonitorStatus[] } | null = null;
+
+/** the monitors on a public Kuma status page with their latest beats (cached 60 s) */
+export async function readStatusPage(raw: string, now = Date.now()): Promise<MonitorStatus[] | null> {
+  const page = parseStatusPage(raw);
+  if (!page) return null;
+  if (pageCache && pageCache.key === raw && now - pageCache.at < 60_000) return pageCache.data;
+  const get = async (path: string) => {
+    const r = await fetchPublicUrl(`${page.origin}${path}`, { accept: 'application/json', userAgent: 'acms-monitoring', timeoutMs: 6000 });
+    return r && r.res.ok ? await r.res.json().catch(() => null) : null;
+  };
+  const [info, beats] = await Promise.all([get(`/api/status-page/${page.slug}`), get(`/api/status-page/heartbeat/${page.slug}`)]);
+  if (!info || !beats) return null;
+  const monitors = ((info.publicGroupList ?? []) as { monitorList?: { id: number; name: string }[] }[]).flatMap((g) => g.monitorList ?? []);
+  const data = monitors.map((m): MonitorStatus => {
+    const list = ((beats.heartbeatList?.[m.id] ?? []) as { status: number; time: string; msg?: string }[]).slice(-30);
+    const last = list[list.length - 1];
+    const state = (n: number) => STATES[n] ?? 'pending';
+    // when the current state began, if the change is among the recent beats
+    // (all beats alike: it began before them, so the duration is unknown)
+    let since: string | null = null;
+    if (last) { let i = list.length - 1; while (i > 0 && list[i - 1].status === last.status) i--; if (i > 0) since = iso(list[i].time); }
+    const uptime = beats.uptimeList?.[`${m.id}_24`];
+    return {
+      id: m.id, name: m.name, status: last ? state(last.status) : 'unknown', since,
+      uptime24h: typeof uptime === 'number' ? uptime : null, message: last?.msg ?? '', recent: list.map((b) => state(b.status)),
+    };
+  });
+  pageCache = { key: raw, at: now, data };
+  return data;
+}
+
+// ---- Settings → Monitoring (owner) --------------------------------------------
+
+/** "https://kuma.example/api/push/Xk29…": enough to recognise, not to use */
+const masked = (url: string) => (url ? url.replace(/(\/api\/push\/)(.{4}).*$/, '$1$2…') : '');
+export async function monitoringState(repo: ContentRepository, locals?: unknown) {
+  const settings = await repo.getSettings();
+  const m = settings.monitoring;
+  const fromEnv = !!normalizePushUrl(runtimeValue('UPTIME_PUSH_URL', locals));
+  const run = await repo.email.schedulerStatus();
+  const monitors = m.statusPage ? await readStatusPage(m.statusPage) : null;
+  return {
+    pushUrl: masked(pushUrlFor(m, locals)), pushFromEnv: fromEnv, statusPage: m.statusPage,
+    // null with a statusPage set: Kuma didn't answer or the page doesn't exist
+    monitors, lastRun: run ? new Date(run.finishedAt).toISOString() : null,
+    health: await healthReport(repo, locals),
+  };
+}
+export type MonitoringState = Awaited<ReturnType<typeof monitoringState>>;
+
+export const MonitoringInput = z.discriminatedUnion('action', [
+  z.object({ action: z.literal('save'), pushUrl: z.string().max(500).optional(), statusPage: z.string().max(500).optional() }).strict(),
+  z.object({ action: z.literal('test') }).strict(),
+]);
+export async function monitoringAction(repo: ContentRepository, input: z.infer<typeof MonitoringInput>, locals?: unknown) {
+  const settings = await repo.getSettings();
+  if (input.action === 'test') {
+    const url = pushUrlFor(settings.monitoring, locals);
+    if (!url) throw new ApiError(400, 'Add the push URL first.');
+    const now = Date.now();
+    if (!await pushHeartbeat(url, { ok: true, startedAt: now, finishedAt: now, jobs: {} }, 'Test from ACMS admin')) throw new ApiError(502, 'Kuma didn’t accept the test. Check the push URL and that the monitor is active.');
+    return;
+  }
+  const next = { ...settings.monitoring };
+  if (input.pushUrl !== undefined) {
+    const url = normalizePushUrl(input.pushUrl);
+    if (url === null) throw new ApiError(400, 'Paste the push URL from the Kuma push monitor (…/api/push/…).');
+    next.pushUrl = url;
+  }
+  if (input.statusPage !== undefined) {
+    const page = input.statusPage.trim();
+    if (page && !parseStatusPage(page)) throw new ApiError(400, 'Paste the status page address (…/status/your-page).');
+    next.statusPage = page;
+  }
+  await repo.updateSettings({ monitoring: next });
+}

package/src/lib/repo/migrations.ts

@@ -526,6 +526,34 @@ export const MIGRATIONS: Migration[] = [
     `CREATE TABLE form_submissions (id TEXT PRIMARY KEY, form_id TEXT NOT NULL, response TEXT NOT NULL, created_at INTEGER NOT NULL)`,
     `CREATE INDEX form_submissions_form_created ON form_submissions(form_id, created_at)`,
   ] },
+  // app access: owner switches + limits, per-link guest change cutoff, and
+  // guest sign-in (emailed codes → per-device tokens; secrets stored hashed)
+  { version: 45, statements: [
+    `ALTER TABLE settings ADD COLUMN mobile_access TEXT NOT NULL DEFAULT '{}'`,
+    `ALTER TABLE booking_links ADD COLUMN change_cutoff INTEGER NOT NULL DEFAULT 0`,
+    `CREATE TABLE guest_codes (email TEXT PRIMARY KEY, code_hash TEXT NOT NULL, attempts INTEGER NOT NULL DEFAULT 0, expires_at INTEGER NOT NULL, created_at INTEGER NOT NULL)`,
+    `CREATE TABLE guest_sessions (id TEXT PRIMARY KEY, token_hash TEXT NOT NULL UNIQUE, email TEXT NOT NULL, device_name TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, last_seen_at INTEGER NOT NULL)`,
+    `CREATE INDEX guest_sessions_email ON guest_sessions(email)`,
+    `CREATE INDEX bookings_email ON bookings(email)`,
+  ] },
+  // links page revision for whole-page saves (staff app): triggers bump it on
+  // every content change, whichever path made it (web admin, API, restore);
+  // click counts don't. revision_checks makes a stale save fail inside its
+  // own batch (CHECK fails → the whole batch rolls back).
+  { version: 46, statements: [
+    `ALTER TABLE settings ADD COLUMN links_revision INTEGER NOT NULL DEFAULT 0`,
+    `CREATE TABLE revision_checks (expected INTEGER NOT NULL, actual INTEGER NOT NULL CHECK (expected = actual))`,
+    `CREATE TRIGGER links_revision_insert AFTER INSERT ON links BEGIN UPDATE settings SET links_revision = links_revision + 1 WHERE id = 1; END`,
+    `CREATE TRIGGER links_revision_delete AFTER DELETE ON links BEGIN UPDATE settings SET links_revision = links_revision + 1 WHERE id = 1; END`,
+    `CREATE TRIGGER links_revision_update AFTER UPDATE OF kind, label, url, icon, html, meta, ord ON links BEGIN UPDATE settings SET links_revision = links_revision + 1 WHERE id = 1; END`,
+    `CREATE TRIGGER links_revision_profile AFTER UPDATE OF links_name, links_bio, links_avatar ON settings
+      WHEN OLD.links_name IS NOT NEW.links_name OR OLD.links_bio IS NOT NEW.links_bio OR OLD.links_avatar IS NOT NEW.links_avatar
+      BEGIN UPDATE settings SET links_revision = links_revision + 1 WHERE id = 1; END`,
+  ] },
+  // Settings → Monitoring: Uptime Kuma push URL + status page
+  { version: 47, statements: [
+    `ALTER TABLE settings ADD COLUMN monitoring TEXT NOT NULL DEFAULT '{}'`,
+  ] },
 ];
 
 export const LATEST_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;