@acms-subir/core 0.2.0 → 0.3.1

package/src/pages/api/calendar/docs.ts

@@ -0,0 +1,66 @@
+import type { APIRoute } from 'astro';
+import { CALENDAR } from '../../../lib/calendar/config';
+
+// Human-readable reference for the calendar + bookings API (plain text, so
+// it reads in a browser, curl, or pasted into an AI assistant).
+export const GET: APIRoute = ({ url }) => {
+  const o = url.origin;
+  const b = CALENDAR.bookings;
+  const text = `# Calendar${b ? ' & bookings' : ''} API
+
+Base: ${o}
+Auth: public reads need no key. Everything else: Authorization: Bearer <key>
+Create keys in the admin: Team → API & webhooks. The agent key works too (all permissions).
+All endpoints send CORS headers, so browsers on other sites can call them.
+Times: ISO 8601. Event fields start/end are wall-clock in the event timezone ("2026-10-03T11:00", or "2026-10-03" when allDay).
+Errors: { "error": "message" } with 400 invalid · 401 no/invalid key · 403 missing permission · 404 not found · 409 conflict (slot taken).
+
+## Events
+
+GET  /api/calendar/events?from=YYYY-MM-DD&to=YYYY-MM-DD&calendar=<slug>&q=<text>&limit=200
+     → { timezone, from, to, occurrences: [{ id, start, end, allDay, event }] }  (repeats expanded)
+GET  /api/calendar/events?expand=0      → { events: [...] }  (rules, not instances)
+GET  /api/calendar/events/<id|slug>
+POST /api/calendar/events                (events:write) → creates a DRAFT
+     { "title": "Fall Festival", "start": "2026-10-03T11:00", "end": "2026-10-03T16:00",
+       "content": "Markdown…", "excerpt": "…", "location": { "name": "Back lawn", "address": "…", "url": "" },
+       "cta": { "label": "Volunteer", "href": "https://…", "style": "primary" },
+       "rrule": "FREQ=WEEKLY;BYDAY=TU", "calendars": ["community"], "tags": ["family"], "publish": false }
+PATCH  /api/calendar/events/<id|slug>    (events:write) same fields; live events stage edits unless "publish": true
+DELETE /api/calendar/events/<id|slug>    (events:write)
+GET  /api/calendar/calendars             → calendars + subscribe feed URLs
+
+Feeds (paste into Google / Apple / Outlook):
+  ${o}${CALENDAR.base}.ics · ${o}${CALENDAR.base}/<slug>.ics · ${o}${CALENDAR.eventsBase}/<slug>.ics
+${b ? `
+## Bookings
+
+GET  /api/calendar/resources             → resources, their links (rules, lengths, questions, autoConfirm)
+GET  /api/calendar/availability?resource=<slug>&link=<slug>&from=YYYY-MM-DD&days=7[&minutes=360]
+     → { timezone, mode, lengths, autoConfirm, days: [{ date, slots: [{ start, end, minutes }] }] }
+POST /api/calendar/bookings              (no key needed — same rules as the booking page)
+     { "resource": "fellowship-hall", "link": "event", "start": "2026-10-17T16:00:00Z", "minutes": 360,
+       "name": "Maria Delgado", "email": "maria@example.com", "phone": "", "answers": { "Expected guests": "60" } }
+     RSVP to an event occurrence: { "event": "<slug>", "start": "<occurrence ISO>", "seats": 2, "name": "…", "email": "…" }
+     → 201 { booking, manageToken }  status "confirmed" (auto-confirm links) or "pending" (approval)
+     → 409 if the time was just taken
+GET   /api/calendar/bookings?status=pending&resource=<slug>&from=…&to=…   (bookings:read)
+GET   /api/calendar/bookings/<id>                                        (bookings:read)
+PATCH /api/calendar/bookings/<id> { "status": "confirmed" | "declined" | "cancelled", "start": "<ISO>", "notes": "…", "message": "…" }  (bookings:write)
+Guests manage their own booking at ${o}${CALENDAR.bookBase}/manage/<manageToken>.
+` : ''}
+## Webhooks
+
+Full webhook reference (including posts, pages, design, media and restores): /api/webhooks/docs
+
+Add endpoints in Team → API & webhooks. Events: event.published, event.updated, event.unpublished, event.deleted${b ? ', booking.created, booking.confirmed, booking.declined, booking.cancelled, booking.rescheduled' : ''}.
+Each POST has headers X-Acms-Event, X-Acms-Delivery, X-Acms-Timestamp and
+X-Acms-Signature: sha256=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>.
+Body: { "id", "type", "createdAt", "data": { ... } }. Failed deliveries retry after 1, 10 and 60 minutes.
+
+## MCP / agent tools
+
+${o}/api/mcp and ${o}/api/agent expose list_events, get_event, list_calendars, create_event, update_event, publish_event${b ? ', list_resources, check_availability, list_bookings, create_booking, update_booking' : ''}.
+`;
+  return new Response(text, { headers: { 'Content-Type': 'text/plain; charset=utf-8', 'Access-Control-Allow-Origin': '*' } });
+};

package/src/pages/api/calendar/events/[id].ts

@@ -0,0 +1,63 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../../lib/repo';
+import { ApiError, json, readJson } from '../../../../lib/api';
+import { authenticate, hasScope, requireScope } from '../../../../lib/api-keys';
+import { siteOrigin } from '../../../../lib/seo';
+import { CALENDAR } from '../../../../lib/calendar/config';
+import { eventIsPublic } from '../../../../lib/calendar/events';
+import { eventToJson } from '../../../../lib/calendar/api';
+import { runAgentTool } from '../../../../lib/agent';
+import { eventDeleted } from '../../../../lib/calendar/hooks';
+import { mergeEventDraft } from '../../../../lib/drafts';
+import { waitUntilFrom } from '../../../../lib/webhooks';
+import { fail, preflight, withCors } from '../../../../lib/calendar/http';
+
+// One event by id or slug.
+//   GET    → public events for anyone; drafts/private with events:read
+//   PATCH  → events:write; body like create; live events stage a pending
+//            draft unless "publish": true (applies it and publishes)
+//   DELETE → events:write
+export const OPTIONS: APIRoute = preflight;
+
+async function find(repo: Awaited<ReturnType<typeof getRepo>>, key: string) {
+  return (await repo.getEvent(key)) ?? (await repo.getEventBySlug(key));
+}
+
+export const GET: APIRoute = async ({ request, locals, url, params }) => {
+  try {
+    if (!CALENDAR.enabled) throw new ApiError(404, 'The calendar module is disabled.');
+    const repo = await getRepo(locals);
+    const [e, settings, calendars, who] = await Promise.all([find(repo, params.id!), repo.getSettings(), repo.listCalendars(), authenticate(request, repo)]);
+    const map = new Map(calendars.map((c) => [c.id, c]));
+    const full = who ? hasScope(who, 'events:read') : false;
+    if (!e || (!full && !eventIsPublic(e, map))) throw new ApiError(404, 'Event not found.');
+    const view = full ? mergeEventDraft(e) : e;
+    return withCors(json({ event: { ...eventToJson(view, siteOrigin(settings, url), map, settings.timezone), ...(full ? { hasPendingDraft: Boolean(e.draft), bodyHtml: view.bodyHtml } : {}) } }));
+  } catch (err) { return fail(err); }
+};
+
+export const PATCH: APIRoute = async ({ request, locals, url, params }) => {
+  try {
+    const repo = await getRepo(locals);
+    await requireScope(request, repo, 'events:write');
+    const e = await find(repo, params.id!);
+    if (!e) throw new ApiError(404, 'Event not found.');
+    const { publish, ...body } = (await readJson(request)) as Record<string, unknown>;
+    const ctx = { origin: siteOrigin(await repo.getSettings(), url), waitUntil: waitUntilFrom(locals) };
+    if (Object.keys(body).length) await runAgentTool(repo, { tool: 'update_event', arguments: { ...body, id: e.id } }, true, ctx);
+    if (publish === true) await runAgentTool(repo, { tool: 'publish_event', arguments: { id: e.id } }, true, ctx);
+    return withCors(json(await runAgentTool(repo, { tool: 'get_event', arguments: { id: e.id } }, true, ctx)));
+  } catch (err) { return fail(err); }
+};
+
+export const DELETE: APIRoute = async ({ request, locals, params }) => {
+  try {
+    const repo = await getRepo(locals);
+    await requireScope(request, repo, 'events:write');
+    const e = await find(repo, params.id!);
+    if (!e) throw new ApiError(404, 'Event not found.');
+    await repo.deleteEvent(e.id);
+    await eventDeleted(repo, e, { waitUntil: waitUntilFrom(locals) });
+    return withCors(json({ deleted: e.id }));
+  } catch (err) { return fail(err); }
+};

package/src/pages/api/calendar/events/index.ts

@@ -0,0 +1,112 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../../lib/repo';
+import { ApiError, apiError, json } from '../../../../lib/api';
+import { authenticate, hasScope } from '../../../../lib/api-keys';
+import { siteOrigin } from '../../../../lib/seo';
+import { CALENDAR } from '../../../../lib/calendar/config';
+import { eventIsListed, eventIsPublic, expandEvents, parseWall } from '../../../../lib/calendar/events';
+import { eventToJson } from '../../../../lib/calendar/api';
+import { zonedToUtc } from '../../../../lib/calendar/ics';
+import { isoWithOffset } from '../../../../lib/calendar/seo';
+import { eventTimeZone } from '../../../../lib/calendar/events';
+import { requireScope } from '../../../../lib/api-keys';
+import { readJson } from '../../../../lib/api';
+import { runAgentTool } from '../../../../lib/agent';
+import { waitUntilFrom } from '../../../../lib/webhooks';
+import { fail } from '../../../../lib/calendar/http';
+
+// Public read API for other sites, apps and lobby screens.
+//   GET /api/calendar/events?from=2026-10-01&to=2026-10-31&calendar=youth&q=night
+//   → { timezone, from, to, occurrences: [{ id, start, end, allDay, event }] }
+//   GET /api/calendar/events?expand=0 → { events: [...] } (rules, not instances)
+// Anonymous callers see public calendars (and an unlisted one when asked by
+// slug). A key with events:read also sees private calendars.
+const CORS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+};
+const withCors = (res: Response) => {
+  for (const [k, v] of Object.entries(CORS)) res.headers.set(k, v);
+  return res;
+};
+
+export const OPTIONS: APIRoute = () => new Response(null, { status: 204, headers: CORS });
+
+export const GET: APIRoute = async ({ request, locals, url }) => {
+  try {
+    if (!CALENDAR.enabled) throw new ApiError(404, 'The calendar module is disabled.');
+    const repo = await getRepo(locals);
+    const principal = await authenticate(request, repo);
+    if (request.headers.get('authorization') && !principal) throw new ApiError(401, 'Invalid API key.');
+    const full = principal ? hasScope(principal, 'events:read') : false;
+    const [settings, calendars, published] = await Promise.all([repo.getSettings(), repo.listCalendars(), repo.listPublishedEvents()]);
+    const tz = settings.timezone || 'UTC';
+    const map = new Map(calendars.map((c) => [c.id, c]));
+    const origin = siteOrigin(settings, url);
+
+    const slug = url.searchParams.get('calendar');
+    const cal = slug ? calendars.find((c) => c.slug === slug) : null;
+    if (slug && (!cal || (cal.visibility === 'private' && !full))) throw new ApiError(404, 'Unknown calendar.');
+    const q = (url.searchParams.get('q') ?? '').trim().toLowerCase();
+    let events = published.filter((e) => {
+      if (cal) return e.calendarIds.includes(cal.id) && (full || eventIsPublic(e, map));
+      return full ? true : eventIsListed(e, map);
+    });
+    if (q) events = events.filter((e) => `${e.title} ${e.excerpt} ${e.location.name}`.toLowerCase().includes(q));
+
+    if (url.searchParams.get('expand') === '0') {
+      return withCors(json({ timezone: tz, events: events.map((e) => eventToJson(e, origin, map, settings.timezone)) }));
+    }
+    const day = (param: string, fallback: number) => {
+      const w = parseWall(url.searchParams.get(param) ?? '');
+      return w ? zonedToUtc(w.y, w.m, w.d, 0, 0, 0, tz) : fallback;
+    };
+    const now = Date.now();
+    const from = day('from', now);
+    const to = Math.min(day('to', from + 90 * 86_400_000), from + 400 * 86_400_000);
+    if (to <= from) throw new ApiError(400, '"to" must be after "from".');
+    const limit = Math.min(1000, Math.max(1, Number(url.searchParams.get('limit')) || 200));
+    const occ = expandEvents(events, settings, { displayTz: tz, now, windowStartMs: from, windowEndMs: to }).slice(0, limit);
+    const cache = new Map<string, ReturnType<typeof eventToJson>>();
+    const toJson = (id: string) => {
+      if (!cache.has(id)) cache.set(id, eventToJson(events.find((e) => e.id === id)!, origin, map, settings.timezone));
+      return cache.get(id)!;
+    };
+    return withCors(json({
+      timezone: tz,
+      from: new Date(from).toISOString(),
+      to: new Date(to).toISOString(),
+      occurrences: occ.map((o) => {
+        const etz = eventTimeZone(o.event, settings);
+        return {
+          id: `${o.event.id}:${o.start}`,
+          start: o.allDay ? isoWithOffset(o.start, etz).slice(0, 10) : isoWithOffset(o.start, etz),
+          end: o.allDay ? isoWithOffset(o.end - 86_400_000, etz).slice(0, 10) : isoWithOffset(o.end, etz),
+          allDay: o.allDay,
+          event: toJson(o.event.id),
+        };
+      }),
+    }));
+  } catch (error) {
+    return withCors(apiError(error));
+  }
+};
+
+// POST /api/calendar/events (events:write) — creates a DRAFT from the same
+// fields as the create_event agent tool (title, start, end, allDay, timezone,
+// rrule, content (Markdown), excerpt, location, cta, calendars, tags…).
+// "publish": true publishes it in the same call.
+export const POST: APIRoute = async ({ request, locals, url }) => {
+  try {
+    const repo = await getRepo(locals);
+    await requireScope(request, repo, 'events:write');
+    const { publish, ...body } = (await readJson(request)) as Record<string, unknown>;
+    const ctx = { origin: siteOrigin(await repo.getSettings(), url), waitUntil: waitUntilFrom(locals) };
+    const created = (await runAgentTool(repo, { tool: 'create_event', arguments: body }, true, ctx)) as { id: string };
+    if (publish === true) await runAgentTool(repo, { tool: 'publish_event', arguments: { id: created.id } }, true, ctx);
+    return withCors(json(await runAgentTool(repo, { tool: 'get_event', arguments: { id: created.id } }, true, ctx), 201));
+  } catch (err) {
+    return fail(err);
+  }
+};

package/src/pages/api/calendar/resources.ts

@@ -0,0 +1,34 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { ApiError, json } from '../../../lib/api';
+import { authenticate, hasScope } from '../../../lib/api-keys';
+import { siteOrigin } from '../../../lib/seo';
+import { bookingLinkUrl, bookingsEnabled, resourceUrl } from '../../../lib/calendar/config';
+import { describeLink, linkLengths } from '../../../lib/booking/availability';
+import { fail, preflight, withCors } from '../../../lib/calendar/http';
+
+// GET /api/calendar/resources → public resources and their public links
+// (a resources:read key adds unlisted ones and switched-off links).
+export const OPTIONS: APIRoute = preflight;
+
+export const GET: APIRoute = async ({ request, locals, url }) => {
+  try {
+    if (!bookingsEnabled()) throw new ApiError(404, 'Bookings are disabled.');
+    const repo = await getRepo(locals);
+    const who = await authenticate(request, repo);
+    const full = who ? hasScope(who, 'resources:read') : false;
+    const [settings, resources, links] = await Promise.all([repo.getSettings(), repo.listResources(), repo.listBookingLinks()]);
+    const origin = siteOrigin(settings, url);
+    return withCors(json({
+      resources: resources.filter((r) => full || r.visibility === 'public').map((r) => ({
+        id: r.id, slug: r.slug, name: r.name, kind: r.kind, description: r.description, capacity: r.capacity, amenities: r.amenities,
+        photo: r.photo ? new URL(r.photo, origin).href : '', timezone: r.timezone || settings.timezone || 'UTC', url: origin + resourceUrl(r.slug),
+        links: links.filter((l) => l.resourceId === r.id && (full || (l.active && l.visibility === 'public'))).map((l) => ({
+          id: l.id, slug: l.slug, name: l.name, description: l.description, mode: l.mode, lengths: linkLengths(l), rules: describeLink(l),
+          autoConfirm: l.autoConfirm, url: origin + bookingLinkUrl(r.slug, l.slug),
+          questions: l.questions.map((q) => ({ id: q.id, label: q.label, type: q.type, required: q.required, options: q.options })),
+        })),
+      })),
+    }));
+  } catch (err) { return fail(err); }
+};

package/src/pages/api/design/capabilities.ts

@@ -0,0 +1,10 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { apiError, json } from '../../../lib/api';
+import { DESIGN_SCOPES, designIdentity } from '../../../lib/design-service';
+export const GET: APIRoute = async ({request,cookies,locals}) => {
+  try {
+    const identity = await designIdentity(request,cookies,await getRepo(locals),DESIGN_SCOPES);
+    return json({version:1,themeApiVersion:1,scopes:identity.scopes,capabilities:{design:true,media:true,revisionRequired:true,codeUpload:false},endpoints:{design:'/api/design',media:'/api/design/media'}});
+  } catch(error) { return apiError(error); }
+};

package/src/pages/api/design/index.ts

@@ -0,0 +1,58 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { apiError, ApiError, json, readJson } from '../../../lib/api';
+import { DesignRequest, designIdentity, publicDesign, validateSectionDesign, validateDesignValues } from '../../../lib/design-service';
+import { listThemes, getTheme } from '../../../lib/theme';
+import { diffDesign, summarizeChanges } from '../../../lib/designDiff';
+import { pickDesignDraft, shareEpoch } from '../../../lib/drafts';
+import { createDesignToken } from '../../../lib/preview';
+import { ThemeTokens } from '../../../theme-sdk/contract.mjs';
+import type { ContentRepository } from '../../../lib/repo/types';
+
+async function state(repo:ContentRepository, scopes: string[]) {
+  const [s,nav,pages,versions]=await Promise.all([repo.getSettings(),repo.listNavItems(),repo.listPages(),repo.listDesignVersions()]);
+  return {revision:s.designRevision,live:{...publicDesign(s),navItems:nav.map(({id,label,url,area})=>({id,label,url,area}))},draft:s.draftDesign,
+    changes:diffDesign(s,nav,s.draftDesign),scopes,
+    themes:listThemes().map(t=>({slug:t.slug,name:t.name,version:t.version,sections:t.sections})),
+    pages:pages.map(p=>({id:p.id,title:p.title,slug:p.slug,isHome:p.isHome})),
+    versions:versions.map(({snapshot,...v})=>v), audit:await repo.listDesignAudit()};
+}
+export const GET:APIRoute=async({request,cookies,locals})=>{
+  try {const repo=await getRepo(locals);const id=await designIdentity(request,cookies,repo,'design:read');return json(await state(repo,id.scopes));} catch(e){return apiError(e);}
+};
+export const POST:APIRoute=async({request,cookies,locals})=>{
+  try {
+    const repo=await getRepo(locals), input=DesignRequest.parse(await readJson(request,500_000));
+    const identity=await designIdentity(request,cookies,repo,input.operation==='publish'?'design:publish':'design:write-draft');
+    const current=await repo.getSettings();
+    if(current.designRevision!==input.revision)throw new ApiError(409,'Design changed. Pull the latest revision before saving.');
+    if(input.operation==='stage') {
+      validateDesignValues(input.patch);
+      const draft={...current.draftDesign,...input.patch};
+      if(input.patch.activeTheme && !listThemes().some(t=>t.slug===input.patch.activeTheme))throw new ApiError(400,'Theme is not installed. Install locally, build and deploy its code first.');
+      const theme=getTheme(String(draft.activeTheme??current.activeTheme));
+      ThemeTokens.parse({...theme.tokens,...draft.designOverrides as object});
+      const pageIds=new Set((await repo.listPages()).map(p=>p.id));
+      if(input.patch.sectionPages && Object.keys(input.patch.sectionPages).some(id=>!pageIds.has(id)))throw new ApiError(400,'A section layout refers to a missing page.');
+      await repo.setDesignDraft(draft,input.revision,identity.actor);
+    } else if(input.operation==='publish') {
+      const settings={...current,...pickDesignDraft(current.draftDesign??{})};
+      validateSectionDesign(settings,getTheme(settings.activeTheme));
+      await repo.applyDesignDraft({expectedRevision:input.revision,author:identity.actor,summary:summarizeChanges(diffDesign(current,await repo.listNavItems(),current.draftDesign))});
+    } else if(input.operation==='discard') await repo.setDesignDraft(null,input.revision,identity.actor);
+    else if(input.operation==='restore') {
+      const version=await repo.getDesignVersion(input.id);if(!version)throw new ApiError(404,'Version not found.');
+      await repo.setDesignDraft({...version.snapshot,shareEpoch:crypto.randomUUID()},input.revision,identity.actor);
+    } else {
+      if(!current.draftDesign)throw new ApiError(409,'There is no draft to share.');
+      if(input.operation==='revoke')await repo.setDesignDraft({...current.draftDesign,shareEpoch:crypto.randomUUID()},input.revision,identity.actor);
+      else {
+        if(shareEpoch(current.draftDesign)==='legacy-disabled')throw new ApiError(409,'Save the draft before sharing.');
+        const {token,expiresAt}=createDesignToken(shareEpoch(current.draftDesign),input.days*86400000);
+        return json({url:`${new URL(request.url).origin}/?preview=${token}`,expiresAt,revision:input.revision});
+      }
+    }
+    // Write-only credentials receive no private content inventory.
+    return json({ok:true,revision:(await repo.getSettings()).designRevision});
+  }catch(e){return apiError(e);}
+};

package/src/pages/api/design/keys.ts

@@ -0,0 +1,24 @@
+import type { APIRoute } from 'astro';
+import { z } from 'zod';
+import { getRepo } from '../../../lib/repo';
+import { apiError, json, readJson, requireSession, ApiError } from '../../../lib/api';
+import { DESIGN_SCOPES } from '../../../lib/design-service';
+import { generateAgentKey } from '../../../lib/ai-config';
+export const ALL:APIRoute=async({request,cookies,locals})=>{
+  try {
+    const repo=await getRepo(locals);await requireSession(request,cookies,repo,true);
+    if(request.method==='GET')return json({keys:(await repo.listApiKeys()).filter(k=>k.scopes.some(s=>DESIGN_SCOPES.includes(s as typeof DESIGN_SCOPES[number])))});
+    if(request.method==='POST') {
+      const input=z.object({name:z.string().min(1).max(100),scopes:z.array(z.enum(DESIGN_SCOPES)).min(1)}).strict().parse(await readJson(request,10000));
+      const {token,keyHash,keyPrefix}=generateAgentKey();
+      const key=await repo.createApiKey({name:input.name,scopes:input.scopes,keyHash,prefix:keyPrefix});return json({key,token},201);
+    }
+    if(request.method==='DELETE') {
+      const {id}=z.object({id:z.string()}).strict().parse(await readJson(request,10000));
+      const key=(await repo.listApiKeys()).find(k=>k.id===id);
+      if(!key||!key.scopes.some(s=>DESIGN_SCOPES.includes(s as typeof DESIGN_SCOPES[number])))throw new ApiError(404,'Design key not found.');
+      await repo.deleteApiKey(id);return json({ok:true});
+    }
+    throw new ApiError(405,'Method not allowed.');
+  }catch(e){return apiError(e);}
+};

package/src/pages/api/design/media.ts

@@ -0,0 +1,32 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { getMediaStore } from '../../../lib/media/store';
+import { apiError, ApiError, json } from '../../../lib/api';
+import { designIdentity } from '../../../lib/design-service';
+export const GET:APIRoute=async({request,cookies,locals})=>{
+  try{const repo=await getRepo(locals);await designIdentity(request,cookies,repo,'media:read');return json({media:await repo.listMedia()});}catch(e){return apiError(e);}
+};
+export const POST:APIRoute=async({request,cookies,locals})=>{
+  try {
+    const repo=await getRepo(locals);await designIdentity(request,cookies,repo,'media:write');
+    const mime=request.headers.get('content-type')??'',ext=({'image/png':'png','image/jpeg':'jpg','image/webp':'webp','image/gif':'gif'} as Record<string,string>)[mime];
+    if(!ext)throw new ApiError(415,'Upload a compressed PNG, JPEG, WebP or GIF image.');
+    const cap=10*1024*1024;
+    if(Number(request.headers.get('content-length'))>cap)throw new ApiError(413,'Image exceeds 10 MB.');
+    const reader=request.body?.getReader();if(!reader)throw new ApiError(400,'Image body required.');
+    const chunks:Uint8Array[]=[];let size=0;
+    try{for(;;){const {done,value}=await reader.read();if(done)break;size+=value.length;if(size>cap){await reader.cancel();throw new ApiError(413,'Image exceeds 10 MB.');}chunks.push(value);}}finally{reader.releaseLock();}
+    if(!size)throw new ApiError(400,'Image body required.');
+    const bytes=new Uint8Array(size);let offset=0;for(const chunk of chunks){bytes.set(chunk,offset);offset+=chunk.length;}
+    const starts = (...values:number[]) => values.every((v,i)=>bytes[i]===v);
+    const ascii = (start:number,end:number) => new TextDecoder().decode(bytes.slice(start,end));
+    const matches = mime==='image/png' ? starts(137,80,78,71,13,10,26,10) : mime==='image/jpeg' ? starts(255,216,255) : mime==='image/webp' ? ascii(0,4)==='RIFF' && ascii(8,12)==='WEBP' : ['GIF87a','GIF89a'].includes(ascii(0,6));
+    if(!matches)throw new ApiError(415,'Image bytes do not match the declared format.');
+    const id=crypto.randomUUID(),key=`${id}/original.${ext}`,store=getMediaStore(locals);
+    await store.put(key,bytes.buffer,mime);
+    let media;
+    try { media=await repo.createMedia({id,key,filename:(request.headers.get('x-filename')||`image.${ext}`).slice(0,200),mime,width:0,height:0,size,alt:(request.headers.get('x-alt')??'').slice(0,2000),variants:[]});
+    } catch(error) { await store.delete(key).catch(()=>{}); throw error; }
+    return json({media},201);
+  }catch(e){return apiError(e);}
+};

package/src/pages/api/email/run.ts

@@ -0,0 +1,11 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { authorizedRunner } from '../../../lib/ops';
+import { runScheduledTasks } from '../../../lib/scheduler';
+export const POST: APIRoute = async ({ request, locals }) => {
+  if (!authorizedRunner(request, locals)) return new Response('Unauthorized', { status: 401, headers: { 'Cache-Control': 'no-store' } });
+  try {
+    const report = await runScheduledTasks(await getRepo(locals), locals);
+    return Response.json({ ...report, accepted: report.jobs.email.count ?? 0 }, { status: report.ok ? 200 : 503, headers: { 'Cache-Control': 'no-store' } });
+  } catch { return Response.json({ ok: false }, { status: 503, headers: { 'Cache-Control': 'no-store' } }); }
+};

package/src/pages/api/email/settings.ts

@@ -0,0 +1,61 @@
+import type { APIRoute } from 'astro';
+import { z } from 'zod';
+import { getRepo } from '../../../lib/repo';
+import { ApiError, apiError, json, readJson, requireSession } from '../../../lib/api';
+import { validateSession, SESSION_COOKIE } from '../../../lib/auth';
+import { reauthenticate } from '../../../lib/email/accounts';
+import { decrypt, encrypt, encryptionAvailable, resolveConfig, runtimeValue } from '../../../lib/email/config';
+import { dispatchEmail } from '../../../lib/email/service';
+import type { ContentRepository } from '../../../lib/repo/types';
+import type { Credentials, PublicEmailSettings } from '../../../lib/email/types';
+const Config = z.object({provider:z.enum(['auto','none','resend','mailgun','ses','cloudflare']),source:z.enum(['env','encrypted']),from:z.string().trim().max(320),replyTo:z.string().trim().max(320),domain:z.string().trim().max(253),region:z.string().trim().max(40),configurationSet:z.string().trim().max(200),snsTopicArn:z.string().trim().max(300),enabled:z.boolean(),reminders:z.boolean(),staffNotifications:z.boolean()}).strict();
+const Secrets = z.object({apiKey:z.string().max(4096).optional(),webhookSecret:z.string().max(4096).optional(),accessKeyId:z.string().max(256).optional(),secretAccessKey:z.string().max(4096).optional(),sessionToken:z.string().max(8192).optional()}).strict();
+const Input = z.discriminatedUnion('action',[
+  z.object({action:z.literal('save'),config:Config,credentials:Secrets.default({}),reauthPassword:z.string().max(1024)}).strict(),
+  z.object({action:z.literal('test'),to:z.string().trim().email().max(254)}).strict(),
+  z.object({action:z.literal('retry'),id:z.string().max(100)}).strict(),
+]);
+export async function publicSettings(repo:ContentRepository,locals?:unknown):Promise<PublicEmailSettings> {
+  const record=await repo.email.config(),c=resolveConfig(record,locals);
+  return {version:c.version,config:c.config,provider:c.provider,configured:!c.error&&c.provider!=='none'&&c.config.enabled&&encryptionAvailable(locals),error:c.error||(!encryptionAvailable(locals)?'Configure EMAIL_ENCRYPTION_KEY for protected email delivery.':''),encryptionAvailable:encryptionAvailable(locals),environmentLocked:!!runtimeValue('EMAIL_PROVIDER',locals),credentialFields:Object.entries(c.credentials).filter(([,v])=>!!v).map(([k])=>k),activity:(await repo.email.list()).map(({payload,lease,fingerprint,rendered,...safe})=>safe),heartbeat:await repo.email.heartbeat()};
+}
+export const GET:APIRoute=async({request,cookies,locals})=>{
+  try{const repo=await getRepo(locals);await requireSession(request,cookies,repo,true);return json(await publicSettings(repo,locals));}catch(e){return apiError(e);}
+};
+export const POST:APIRoute=async({request,cookies,locals})=>{
+  try{
+    const repo=await getRepo(locals);await requireSession(request,cookies,repo,true);
+    const userId=(await validateSession(cookies.get(SESSION_COOKIE)?.value,repo))!;
+    const input=Input.parse(await readJson(request,20000));
+    if(input.action==='save'){
+      if(!await repo.email.rateLimit(`reauth:${userId}`,10,10*60000))throw new ApiError(429,'Too many attempts. Try again later.');
+      if(!await reauthenticate(repo,userId,input.reauthPassword))throw new ApiError(403,'Your current password is required to change email settings.');
+      const current=await repo.email.config();
+      if(runtimeValue('EMAIL_PROVIDER',locals)&&(input.config.provider!==runtimeValue('EMAIL_PROVIDER',locals)||input.config.source!=='env'))throw new ApiError(400,'Provider is managed by EMAIL_PROVIDER in the deployment environment.');
+      let encrypted='';
+      if(input.config.source==='encrypted'){
+        if(!encryptionAvailable(locals))throw new ApiError(400,'Configure EMAIL_ENCRYPTION_KEY before saving credentials.');
+        const saved=current?.config.provider===input.config.provider&&current.encrypted?decrypt<Credentials>(current.encrypted,'credentials',locals):{};
+        const credentials={...saved,...Object.fromEntries(Object.entries(input.credentials).filter(([,v])=>!!v?.trim()).map(([k,v])=>[k,v!.trim()]))};
+        encrypted=encrypt(credentials,'credentials',locals);
+      }
+      const candidate={version:0,config:input.config,encrypted,createdAt:Date.now()};
+      const c=resolveConfig(candidate,locals);
+      if(input.config.enabled&&input.config.provider!=='none'&&c.error)throw new ApiError(400,c.error);
+      await repo.email.saveConfig(input.config,encrypted);
+      return json(await publicSettings(repo,locals));
+    }
+    if(!await repo.email.rateLimit(`email-action:${userId}`,10,60000))throw new ApiError(429,'Please wait before another email action.');
+    if(input.action==='retry'){
+      if(!await repo.email.retry(input.id))throw new ApiError(409,'This email cannot safely be retried. Check its status or issue a fresh account link.');
+      await dispatchEmail(repo,locals,1);return json({message:'Retry queued.'});
+    }
+    const c=resolveConfig(await repo.email.config(),locals);
+    if(c.error||c.provider==='none'||!c.config.enabled)throw new ApiError(400,c.error||'Email is disabled.');
+    const id=crypto.randomUUID();
+    await repo.email.enqueue({id,dedupe:`test:${id}`,kind:'test',recipient:input.to,payload:'{}',configVersion:c.version,expiresAt:Date.now()+3600000});
+    await dispatchEmail(repo,locals,5);
+    const job=await repo.email.get(id);
+    return json({message:job?.state==='accepted'?'Test accepted by the provider. Delivery has not yet been confirmed.':`Test status: ${job?.state || 'queued'}. ${job?.error||''}`});
+  }catch(e){return apiError(e);}
+};

package/src/pages/api/email/webhooks/[provider].ts

@@ -0,0 +1,4 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../../lib/repo';
+import { receiveEmailWebhook } from '../../../../lib/email/webhooks';
+export const POST:APIRoute=async({request,params,locals})=>receiveEmailWebhook(request,params.provider||'',await getRepo(locals),locals);

package/src/pages/api/live/oauth/youtube/callback.ts

@@ -0,0 +1,19 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../../../lib/repo';
+import { ApiError } from '../../../../../lib/api';
+import { validateSession, SESSION_COOKIE, OWNER_ENV } from '../../../../../lib/auth';
+import { finishOAuth } from '../../../../../lib/live/service';
+export const GET:APIRoute=async({cookies,locals,url})=>{
+  const headers={'Cache-Control':'no-store','Referrer-Policy':'no-referrer'};
+  try{
+    const repo=await getRepo(locals),session=cookies.get(SESSION_COOKIE)?.value;
+    // OAuth is intentionally a cross-site GET. Session-bound, one-use state provides CSRF protection.
+    const user=await validateSession(session,repo);
+    if(!session||!user||user!==OWNER_ENV&&(await repo.getUser(user))?.role!=='owner')throw new ApiError(403,'Sign in as the site owner and start authorization again.');
+    await finishOAuth(repo,session,url,locals);
+    return new Response(null,{status:303,headers:{...headers,Location:'/admin/live?live=connected'}});
+  }catch{
+    // Never reflect callback codes, tokens or provider error bodies into an HTML page or URL.
+    return new Response(null,{status:303,headers:{...headers,Location:'/admin/live?live=error'}});
+  }
+};

package/src/pages/api/live/settings.ts

@@ -0,0 +1,45 @@
+import type { APIRoute } from 'astro';
+import { z } from 'zod';
+import { getRepo } from '../../../lib/repo';
+import { ApiError, apiError, json, readJson, requireSession } from '../../../lib/api';
+import { SESSION_COOKIE } from '../../../lib/auth';
+import { Provider } from '../../../lib/live/types';
+import { adminState, beginOAuth, disconnect, saveConnection, syncConnection, validateConfig } from '../../../lib/live/service';
+const Input=z.discriminatedUnion('action',[
+  z.object({action:z.literal('saveConnection'),provider:Provider,clientId:z.string().trim().min(1).max(200),clientSecret:z.string().trim().max(8192).default(''),channelInput:z.string().trim().max(2048).default(''),googleStatus:z.enum(['testing','production']).default('testing')}).strict(),
+  z.object({action:z.literal('test'),provider:Provider}).strict(),
+  z.object({action:z.literal('selectChannel'),provider:z.literal('youtube'),channelId:z.string().min(1).max(200)}).strict(),
+  z.object({action:z.literal('enable'),provider:Provider,enabled:z.boolean()}).strict(),
+  z.object({action:z.literal('authorize'),provider:z.literal('youtube')}).strict(),
+  z.object({action:z.literal('disconnect'),provider:Provider}).strict(),
+  z.object({action:z.literal('saveConfig'),config:z.unknown()}).strict(),
+]);
+export const GET:APIRoute=async({request,cookies,locals,url})=>{
+  try{const repo=await getRepo(locals);await requireSession(request,cookies,repo,true);return json(await adminState(repo,url,locals));}catch(e){return apiError(e);}
+};
+export const POST:APIRoute=async({request,cookies,locals,url})=>{
+  try{
+    const repo=await getRepo(locals);await requireSession(request,cookies,repo,true);
+    // Browser-based credential changes must originate at this site.
+    if(request.headers.get('origin')!==url.origin)throw new ApiError(403,'Submit changes from this site’s admin.');
+    const input=Input.parse(await readJson(request,24_000));
+    switch(input.action){
+      case 'saveConnection':await saveConnection(repo,input,locals);break;
+      case 'test':await syncConnection(repo,input.provider,locals,true);break;
+      case 'authorize':return json({authorizationUrl:await beginOAuth(repo,cookies.get(SESSION_COOKIE)!.value,url,locals)});
+      case 'disconnect':await disconnect(repo,input.provider,locals);break;
+      case 'saveConfig':await repo.updateSettings({live:validateConfig(input.config)});break;
+      case 'selectChannel':{
+        const conn=await repo.live.get(input.provider);const selected=conn?.channels.find(c=>c.id===input.channelId);
+        if(!conn||!selected)throw new ApiError(400,'Choose a channel from the authorized account.');
+        if(!await repo.live.patch(input.provider,{channelId:selected.id,channelName:selected.name,snapshot:null,upcoming:null,upcomingCheckedAt:0,testedAt:0,enabled:false,lastAttemptAt:0},conn.revision))throw new ApiError(409,'Connection changed; reload and try again.');break;
+      }
+      case 'enable':{
+        const conn=await repo.live.get(input.provider);if(!conn)throw new ApiError(404,'Connection not found.');
+        if(input.enabled&&(!conn.testedAt||conn.testedAt<Date.now()-600_000||conn.error||!conn.channelId))throw new ApiError(400,'Run a successful connection test before enabling automatic checks.');
+        if(!await repo.live.patch(input.provider,{enabled:input.enabled,nextAt:0,...(!input.enabled?{snapshot:null,upcoming:null,upcomingCheckedAt:0}:{})},conn.revision))throw new ApiError(409,'Connection changed; reload and try again.');break;
+      }
+    }
+    return json(await adminState(repo,url,locals));
+  }catch(e){return apiError(e);}
+};

package/src/pages/api/live/status.ts

@@ -0,0 +1,7 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { json, apiError } from '../../../lib/api';
+import { publicState } from '../../../lib/live/service';
+export const GET:APIRoute=async({locals})=>{
+  try{return json({snapshot:await publicState(await getRepo(locals)),serverNow:Date.now()});}catch(e){return apiError(e);}
+};

package/src/pages/api/live/thumb.ts

@@ -0,0 +1,48 @@
+import type { APIRoute } from 'astro';
+import { getRepo } from '../../../lib/repo';
+import { readResponseBytes } from '../../../lib/api';
+import { liveState, thumbSource } from '../../../lib/live/service';
+
+// Same-site proxy for the current broadcast's preview image, so visitors
+// never contact YouTube or Twitch until they choose to play. The upstream URL
+// comes only from the current snapshot (fixed hosts, validated ids); the
+// query string is just a cache version.
+const MAX_BYTES = 1_500_000;
+const TYPES = new Set(['image/jpeg', 'image/png', 'image/webp']);
+let cached: { src: string; at: number; type: string; body: Uint8Array } | null = null;
+
+const missing = () => new Response(null, { status: 404, headers: { 'Cache-Control': 'public, max-age=30' } });
+
+export const GET: APIRoute = async ({ locals }) => {
+  try {
+    const { config, snapshot } = await liveState(await getRepo(locals));
+    const src = config.mode !== 'off' && config.display.thumbnail ? thumbSource(snapshot) : '';
+    if (!src) return missing();
+    if (cached?.src !== src || cached.at < Date.now() - 60_000) {
+      // YouTube serves _live stills only while broadcasting; fall back to the
+      // regular still (e.g. manual links to an ended stream).
+      const candidates = [src, src.replace('hqdefault_live', 'hqdefault')].filter((v, i, a) => a.indexOf(v) === i);
+      let found: typeof cached = null;
+      for (const url of candidates) {
+        // Twitch redirects to a placeholder when offline; treat that as missing.
+        const r = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(8_000) });
+        const type = (r.headers.get('content-type') ?? '').split(';')[0].trim();
+        if (r.status !== 200 || !TYPES.has(type)) { await r.body?.cancel(); continue; }
+        found = { src, at: Date.now(), type, body: await readResponseBytes(r, MAX_BYTES) };
+        break;
+      }
+      if (!found) return missing();
+      cached = found;
+    }
+    return new Response(cached.body, {
+      headers: {
+        'Content-Type': cached.type,
+        'Cache-Control': 'public, max-age=60',
+        'X-Content-Type-Options': 'nosniff',
+        'Content-Security-Policy': "default-src 'none'",
+      },
+    });
+  } catch {
+    return missing();
+  }
+};