@acms-subir/core 0.3.19 → 0.3.20

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @acms-subir/core
 
+## 0.3.20
+
+### Patch Changes
+
+- 531c632: Cancel a single date of a repeating event. The new `cancelledDates` event field stores occurrence keys in the same wall-clock format as `exdates` (`YYYY-MM-DDTHH:mm` in the event's timezone, or `YYYY-MM-DD` for all-day events). A cancelled date stays on the calendar struck through as "Cancelled", and the room it holds becomes bookable for that slot. RSVPs for it close. The event page, cards, sections, `/api/v1/events`, `/api/calendar/events` and the app mark that occurrence `cancelled`. ICS feeds add a `RECURRENCE-ID` override with `STATUS:CANCELLED`, and webhook payloads include `cancelledDates`. The admin Schedule adds "Cancel this date" and "Restore this date" on an occurrence. Moving a series moves its cancelled dates too. After a time or rule edit, keys that no longer match an occurrence are ignored. Migration 55 adds the column (default `[]`) to existing databases.
+
+  Add `@acms-subir/core/server`, a small, documented API for site code: `getRepo`, `currentUser`, `listEvents`, `getEvent`, `listOccurrences`, `cancelOccurrence` and `restoreOccurrence`. `currentUser` works on public pages, including Clerk sessions. The cancel and restore functions apply at once, keep unpublished admin edits staged, are idempotent and do no authorization; callers must check access first. Run `acms docs server` for the guide and an example action.
+
+  Add private custom event fields: `calendar.eventFields: [{ key, label, type, private: true }]`. Private values are stored, editable in the admin and returned by `@acms-subir/core/server`. They are left out of the event page, theme templates and helpers, `/api/v1/events`, `/api/calendar/events` (except for API keys with `events:read`), webhooks, ICS and search. Public event JSON now carries only configured, non-private custom fields.
+
+  Client types add `cancelled` to event occurrences and `cancelledDates` to events.
+
+  Not included yet, but each would be a small addition to `@acms-subir/core/server`: signed links (core already signs sessions with HMAC), sending an email through the site's configured provider (the email queue already exists), and a `Site.astro` layout export (the layout already exists). Rate limiting would take more work, because the current limiter only covers sign-in.
+
 ## 0.3.19
 
 ### Patch Changes

package/cli/main.mjs

@@ -10,7 +10,7 @@ import { addMobile, mobileCommand, listApps } from './mobile.mjs';
 import { mobileDoctor, renderDoctor } from './mobile-doctor.mjs';
 import { monitorCommand, renderMonitor } from './monitor.mjs';
 const HELP=`acms — ACMS project, theme and agent tools
-Discovery: inspect | schema theme | docs theme | docs sections | docs mobile | docs sync
+Discovery: inspect | schema theme | docs theme | docs sections | docs mobile | docs sync | docs server
            agent init [--mobile]   write .agents/skills (theme; mobile when an app exists)
 Check:  check [--build]   validate every project theme, refresh section types,
                           report sections without a native app version
@@ -139,6 +139,7 @@ export async function main() {
     else if(cmd==='docs'&&sub==='sections')data={markdown:await readFile(resolve(CORE,'docs/sections.md'),'utf8')};
     else if(cmd==='docs'&&sub==='mobile')data={markdown:await readFile(resolve(CORE,'docs/mobile.md'),'utf8')};
     else if(cmd==='docs'&&sub==='sync')data={markdown:await readFile(resolve(CORE,'docs/environment-sync.md'),'utf8')};
+    else if(cmd==='docs'&&sub==='server')data={markdown:await readFile(resolve(CORE,'docs/server.md'),'utf8')};
     else if(cmd==='section')data=await sectionCommand(sub,rest,flags);
     else if(cmd==='check') {
       const p=await project(),themes=(await listLocalThemes(p)).filter(t=>t.origin==='project');
@@ -147,7 +148,7 @@ export async function main() {
     }
     else if(cmd==='agent'&&sub==='init')data=await agentInit(flags);
     else if(cmd==='inspect') {
-      const p=await project();data={coreVersion:p.version,themeApiVersion:1,project:p.pkg.name,targets:{cloudflare:await exists('wrangler.jsonc')||await exists('wrangler.toml'),docker:await exists('Dockerfile')},themes:await listLocalThemes(p),capabilities:['theme-schema','theme-create','theme-check','theme-dev','theme-pack','scoped-design-api','editable-sections','section-library','section-types','page-presets','mobile-apps','mobile-editor-apps','mobile-recipes','mobile-docs','mobile-doctor','monitor-kuma','migrate'],mobileApps:await mobileApps(),configuration:await readJson(resolve(p.cwd,'.astro/acms-project.json')).catch(()=>({source:'Run astro sync or dev to discover configured collections.',collections:null}))};
+      const p=await project();data={coreVersion:p.version,themeApiVersion:1,project:p.pkg.name,targets:{cloudflare:await exists('wrangler.jsonc')||await exists('wrangler.toml'),docker:await exists('Dockerfile')},themes:await listLocalThemes(p),capabilities:['theme-schema','theme-create','theme-check','theme-dev','theme-pack','scoped-design-api','editable-sections','section-library','section-types','page-presets','mobile-apps','mobile-editor-apps','mobile-recipes','mobile-docs','mobile-doctor','monitor-kuma','migrate','server-api'],mobileApps:await mobileApps(),configuration:await readJson(resolve(p.cwd,'.astro/acms-project.json')).catch(()=>({source:'Run astro sync or dev to discover configured collections.',collections:null}))};
     } else if(cmd==='theme')data=await themeCommand(sub,rest,flags);
     else if(['site','design','content','media'].includes(cmd))data=await remoteCommand(cmd,sub,rest,flags);
     else fail('USAGE','Unknown command.',[],['Run acms --help']);

package/cli/migrations.generated.mjs

@@ -1052,9 +1052,20 @@ var MIGRATIONS = [
       BEGIN UPDATE settings SET links_revision = links_revision + 1 WHERE id = 1; END`,
     `DROP TRIGGER content_version_settings_update`,
     ...contentVersionTriggers("settings", [...CONTENT_VERSION_COLUMNS.settings, "links_verified", "links_avatar_shape", "links_avatar_fit", "links_avatar_scale"])
+  ] },
+  // one cancelled date of a repeating event (CalEvent.cancelledDates)
+  { version: 55, statements: [
+    `ALTER TABLE events ADD COLUMN cancelled_dates TEXT NOT NULL DEFAULT '[]'`,
+    `DROP TRIGGER content_version_events_update`,
+    // [insert, delete, update]: only the update trigger names columns
+    contentVersionTriggers("events", [...CONTENT_VERSION_COLUMNS.events, "cancelled_dates"])[2]
   ] }
 ];
-var CURRENT_CONTENT_VERSION_COLUMNS = { ...CONTENT_VERSION_COLUMNS, settings: [...CONTENT_VERSION_COLUMNS.settings, "links_verified", "links_avatar_shape", "links_avatar_fit", "links_avatar_scale"] };
+var CURRENT_CONTENT_VERSION_COLUMNS = {
+  ...CONTENT_VERSION_COLUMNS,
+  settings: [...CONTENT_VERSION_COLUMNS.settings, "links_verified", "links_avatar_shape", "links_avatar_fit", "links_avatar_scale"],
+  events: [...CONTENT_VERSION_COLUMNS.events, "cancelled_dates"]
+};
 var LATEST_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
 
 // src/lib/repo/migrate-runner.ts

package/docs/server.md

@@ -0,0 +1,144 @@
+# Site server code: `@acms-subir/core/server`
+
+A small, stable API for code in your site's own `src/`: Astro pages, endpoints and
+actions. Use it to read events, find out who is signed in, and cancel single dates of
+a repeating event. It is a public contract: these functions keep their signatures
+across minor versions. Import only from `@acms-subir/core/server`. Deep imports into
+`src/lib` are blocked by the package's exports map and can change at any time.
+
+```ts
+import {
+  getRepo, currentUser,
+  listEvents, getEvent, listOccurrences,
+  cancelOccurrence, restoreOccurrence,
+} from '@acms-subir/core/server';
+```
+
+## Signatures
+
+```ts
+getRepo(locals: unknown): Promise<Repo>
+currentUser(ctx: { request: Request; cookies: AstroCookies; locals: unknown }): Promise<ServerUser | null>
+listEvents(repo: Repo, opts?: { publishedOnly?: boolean; calendar?: string }): Promise<CalEvent[]>
+getEvent(repo: Repo, id: string): Promise<CalEvent | null>
+listOccurrences(repo: Repo, w: { eventId?: string; from: Date | number; to: Date | number }): Promise<Occurrence[]>
+cancelOccurrence(repo: Repo, eventId: string, occurrenceKey: string, ctx: { url: URL; locals: unknown }): Promise<CalEvent>
+restoreOccurrence(repo: Repo, eventId: string, occurrenceKey: string, ctx: { url: URL; locals: unknown }): Promise<CalEvent>
+
+interface ServerUser { id: string; email: string; name: string; role: Role; can(permission: string): boolean }
+interface Occurrence { event: CalEvent; start: number; end: number; allDay: boolean; days: number; key: string; cancelled: boolean }
+```
+
+The types `Repo`, `ServerUser`, `CalEvent`, `Occurrence`, `ListEventsOptions`,
+`OccurrenceWindow` and `WriteContext` are exported too.
+
+- **`getRepo(locals)`**: the site's content store for this request. Pass `Astro.locals`
+  (or the endpoint/action's `locals`). `Repo` is an opaque handle; pass it to the other
+  functions.
+- **`currentUser(ctx)`**: the person signed in to the admin, or `null`. It works on any
+  page, public ones included. With Clerk sign-in, a signed-in browser sends the
+  `__session` cookie and is resolved everywhere except `/media`, `/embed` and
+  `/api/v1`. `role` is their ACMS role. `can('content.edit')` checks a permission from
+  Team → Roles; unknown permission keys return `false`. A session from
+  `ADMIN_PASSWORD` has `id: '__owner_env__'`, role `owner` and an empty `email`.
+  A page that reads `currentUser` is personal, so don't let a shared cache keep it. A
+  request with a session cookie is never cached publicly.
+- **`listEvents(repo, opts)`**: events by first start date, earliest first. By default,
+  every status except archived. `publishedOnly: true` returns only published events.
+  `calendar` (an id or slug) limits the list to one calendar. Values are the live ones;
+  unpublished edits staged in the admin are not merged in.
+- **`getEvent(repo, id)`**: one event, or `null`.
+- **`listOccurrences(repo, { eventId?, from, to })`**: occurrences in `[from, to)`,
+  soonest first, for one event or all non-archived events. The window can be up to 400
+  days. Each occurrence has its `key` (below) and `cancelled`, which is true when the
+  whole event or just that date is cancelled. Drafts are included, so check
+  `o.event.status` before showing anything publicly.
+- **`cancelOccurrence(repo, eventId, key, { url, locals })`**: cancels one date of a
+  repeating event. The change applies immediately, even on a published event, and
+  leaves any unpublished admin edits on that event as they are. That date stays listed,
+  struck through as "Cancelled". The room it holds becomes bookable for that slot. The
+  event page, `/api/v1/events`, `/api/calendar/events`, the app and the ICS feeds show
+  it as cancelled, and the `event.updated` webhook fires. Calling it again for a date
+  that's already cancelled does nothing.
+- **`restoreOccurrence(...)`**: undoes `cancelOccurrence` for that date. Also
+  idempotent.
+
+Both write functions throw an `Error` with a `status` and a message that is safe to show
+people:
+
+| status | when |
+|---|---|
+| 404 | the event doesn't exist |
+| 400 | the event doesn't repeat; the key isn't one of its dates (wrong format, not generated by the rule, skipped, or the series moved); the date has started or passed |
+
+> **They do no authorization.** Anyone who can reach your code can cancel a date. Check
+> who is calling (`currentUser`, your own signed link, etc.) before you call them.
+
+## Occurrence keys
+
+An occurrence key is the occurrence's start as **wall-clock time**, in the same format
+as the event's `start` and `exdates`:
+
+- timed events: `YYYY-MM-DDTHH:mm` in the event's own timezone (the site timezone when
+  the event has none), e.g. `2030-01-09T19:00`
+- all-day events: `YYYY-MM-DD`, e.g. `2030-01-09`
+
+Take keys from `listOccurrences` (`o.key`) rather than building them by hand. Cancelled
+keys are stored on the event as `cancelledDates`. If the series is later moved to
+another day (the admin's drag-to-move), its cancelled dates move with it. If its time
+or rule is edited instead, keys that no longer match an occurrence are ignored, not an
+error.
+
+## Private event fields
+
+A custom field can be private:
+
+```js
+acms({ calendar: { eventFields: [{ key: 'host_email', label: 'Host email', type: 'text', private: true }] } })
+```
+
+Private values are saved and editable in the admin (marked "private" there) and
+returned by this API (`event.fields.host_email`). They never appear in public output:
+the event page and theme event templates, `/api/v1/events` and the app, the
+`/api/calendar/events` API (API keys with `events:read` excepted), webhooks, ICS feeds,
+search, or the events that theme helpers and sections receive.
+
+## Example: let a class's host cancel one week
+
+`src/actions/index.ts` in the site:
+
+```ts
+import { defineAction, ActionError } from 'astro:actions';
+import { z } from 'astro:schema';
+import { server as acmsActions } from '@acms-subir/core/actions';
+import { getRepo, currentUser, getEvent, cancelOccurrence } from '@acms-subir/core/server';
+
+export const server = {
+  ...acmsActions,
+  cancelClassDate: defineAction({
+    input: z.object({ eventId: z.string(), date: z.string() }),
+    handler: async ({ eventId, date }, ctx) => {
+      const repo = await getRepo(ctx.locals);
+      const event = await getEvent(repo, eventId);
+      const me = await currentUser(ctx);
+      // your rule: staff who can edit content, or the host named on the event
+      const allowed = me && (me.can('content.edit') || me.email === event?.fields.host_email);
+      if (!allowed) throw new ActionError({ code: 'FORBIDDEN', message: 'You can’t cancel this class.' });
+      try {
+        const updated = await cancelOccurrence(repo, eventId, date, { url: ctx.url, locals: ctx.locals });
+        return { cancelledDates: updated.cancelledDates };
+      } catch (e) {
+        const status = (e as { status?: number }).status;
+        throw new ActionError({ code: status === 404 ? 'NOT_FOUND' : 'BAD_REQUEST', message: (e as Error).message });
+      }
+    },
+  }),
+};
+```
+
+Show the dates to choose from with `listOccurrences(repo, { eventId, from: Date.now(), to:
+Date.now() + 90 * 86_400_000 })` and pass `o.key` as `date`.
+
+Writes made in an action or another non-GET request also clear the site's shared cache
+and send pending notifications once the request finishes. The core middleware does this
+for every route, including yours.

package/integration.mjs

@@ -400,7 +400,9 @@ function resolveCalendar(calendar, contentBases, locales) {
     }
     const label = f.label ?? key.charAt(0).toUpperCase() + key.slice(1).replace(/_/g, ' ');
     if (typeof label !== 'string') throw new Error(`acms: calendar.eventFields "${key}".label must be a string`);
-    resolved.eventFields.push({ key, label, type, options });
+    const isPrivate = f.private ?? false;
+    if (typeof isPrivate !== 'boolean') throw new Error(`acms: calendar.eventFields "${key}".private must be true or false`);
+    resolved.eventFields.push({ key, label, type, options, private: isPrivate });
   }
   if (resolved.eventFields.length > 30) throw new Error('acms: calendar.eventFields allows at most 30 fields');
   return resolved;
@@ -505,13 +507,16 @@ function acmsVitePlugin(userConfig) {
  *   search (/api/v1/search and /api/v1/content?q=), and
  *   the header search modal. On by default — set `enabled: false` to remove
  *   all three.
- * @param {false | {enabled?: boolean, base?: string, eventsBase?: string, defaultView?: 'month' | 'week' | 'list', eventFields?: Array<{key: string, label?: string, type?: 'text' | 'textarea' | 'number' | 'url' | 'select', options?: string[]}>}} [options.calendar]
+ * @param {false | {enabled?: boolean, base?: string, eventsBase?: string, defaultView?: 'month' | 'week' | 'list', eventFields?: Array<{key: string, label?: string, type?: 'text' | 'textarea' | 'number' | 'url' | 'select', options?: string[], private?: boolean}>}} [options.calendar]
  *   Calendar module: the main calendar page at `base` (default '/calendar')
  *   with subscribe feeds (`<base>.ics`, `<base>/<slug>.ics`), event pages at
  *   `eventsBase` (default '/events'), a public JSON API under /api/calendar,
  *   embeds, and the admin Calendar section. `eventFields` adds custom fields
  *   to every event (edited in the event sidebar, exposed to templates and the
- *   API). On by default — `calendar: false` removes all of it.
+ *   API). `private: true` keeps a field's values out of every public output
+ *   (event page, APIs, webhooks, app, feeds); site code reads them through
+ *   @acms-subir/core/server. On by default — `calendar: false` removes all
+ *   of it.
  * @param {{provider?: 'geoapify' | 'google' | 'mapbox' | 'locationiq' | 'stadia' | 'photon' | 'nominatim' | 'pelias'}} [options.maps]
  *   Maps for events (bring your own provider): address suggestions in the
  *   event editor and a static map image on event pages. Set MAPS_API_KEY

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "publishConfig": {
     "access": "public"
   },
@@ -31,6 +31,7 @@
     ".": "./integration.mjs",
     "./package.json": "./package.json",
     "./actions": "./src/actions/index.ts",
+    "./server": "./src/server/index.ts",
     "./theme": "./src/theme-sdk/index.ts",
     "./theme/schema": "./src/theme-sdk/contract.mjs",
     "./theme/components/LiveCard.astro": "./src/components/LiveCard.astro",

package/src/actions/index.ts

@@ -29,7 +29,7 @@ import { loadFeed } from '../lib/calendar/ics';
 import { NATIVE_ALL } from '../lib/calendar/render';
 import { collectViewEvents } from '../lib/calendar/data';
 import { loadBoard } from '../lib/calendar/board';
-import { duplicateEvent, moveOccurrence, moveSeries, quickCreate, undoMove } from '../lib/calendar/schedule';
+import { cancelOccurrence, duplicateEvent, moveOccurrence, moveSeries, quickCreate, restoreOccurrence, undoMove } from '../lib/calendar/schedule';
 import { waitUntilFrom } from '../lib/webhooks';
 import { eventChanged, eventDeleted } from '../lib/calendar/hooks';
 import { siteOrigin } from '../lib/seo';
@@ -1147,6 +1147,18 @@ export const server = {
         try { await undoMove(repo, undo, await publishHooks(ctx)); return { ok: true }; } catch (e) { asActionError(e); }
       },
     }),
+    // Schedule: cancel (or restore) one date of a repeating event, at once
+    cancelDate: defineAction({
+      input: z.object({ id: z.string(), occurrence: z.string().max(20), restore: z.boolean().default(false) }),
+      handler: async ({ id, occurrence, restore }, ctx) => {
+        await requireCan(ctx, 'content.edit');
+        const repo = await getRepo(ctx.locals);
+        try {
+          const e = await (restore ? restoreOccurrence : cancelOccurrence)(repo, id, occurrence, await publishHooks(ctx));
+          return { id: e.id, cancelledDates: e.cancelledDates };
+        } catch (e) { asActionError(e); }
+      },
+    }),
     duplicate: defineAction({
       input: z.object({ id: z.string() }),
       handler: async ({ id }, ctx) => {

package/src/components/EventPage.astro

@@ -18,13 +18,15 @@ interface Props {
   settings: Settings;
   calendars: Calendar[];
   html: string;
-  upcoming: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'>[];
+  upcoming: (Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'> & { cancelled?: boolean })[];
   origin: string;
   preview?: boolean;
   // RSVP state when the event takes RSVPs (null otherwise)
   rsvp?: { going: number; left: number | null; maxSeats: number; error: string; open: boolean; formHtml?: string; fieldsHtml?: string; values?: { name: string; email: string; seats: string } } | null;
 }
 const { event: e, occurrence: o, settings, calendars, html, upcoming, origin, preview = false, rsvp = null } = Astro.props;
+// the whole event, or just this date of a repeating one
+const cancelled = e.cancelled || Boolean(o.cancelled);
 const image = eventImage(e, settings);
 const tz = eventTimeZone(e, settings);
 const locale = siteLocale(settings);
@@ -47,7 +49,7 @@ const showMap = loc.showMap !== false && Boolean(loc.mapImage) && typeof loc.lat
 const directions = showMap ? safeHref(directionsUrl(loc)) : '';
 const mapCredit = showMap ? mapAttribution(loc.mapImage) : '';
 const mapLabel = loc.name || loc.address || 'the location';
-const fieldRows = CALENDAR.eventFields.filter((fd) => e.fields[fd.key]).map((fd) => ({ label: fd.label, value: e.fields[fd.key], type: fd.type }));
+const fieldRows = CALENDAR.eventFields.filter((fd) => !fd.private && e.fields[fd.key]).map((fd) => ({ label: fd.label, value: e.fields[fd.key], type: fd.type }));
 const visibleTags = e.tags.filter((t) => !t.startsWith('#'));
 const I = {
   pin: 'M12 22s7-7 7-12a7 7 0 0 0-14 0c0 5 7 12 7 12zM12 12.5a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5z',
@@ -61,7 +63,7 @@ const I = {
 const online = /zoom\.us|meet\.google|teams\.microsoft|webex|whereby|jit\.si/i.test(e.location.url);
 ---
 
-<article class={`pc-ev-page${e.cancelled ? ' is-cancelled' : ''}`}>
+<article class={`pc-ev-page${cancelled ? ' is-cancelled' : ''}`}>
   {preview && <p class="pc-ev-preview">Preview — only you can see this {e.status === 'published' ? 'version' : 'draft'}.</p>}
   {image.src && (
     <figure class="pc-ev-hero"><img src={image.src} alt={image.alt} /></figure>
@@ -78,6 +80,7 @@ const online = /zoom\.us|meet\.google|teams\.microsoft|webex|whereby|jit\.si/i.t
       )}
       <h1 class="pc-ev-title">{e.title}</h1>
       {e.cancelled && <p class="pc-ev-cancelled"><b>This event is cancelled.</b> It stays listed so nobody is left wondering.</p>}
+      {!e.cancelled && cancelled && <p class="pc-ev-cancelled"><b>Cancelled on {f.date}.</b> Other dates go ahead as usual.</p>}
       {e.excerpt && <p class="pc-ev-lede">{e.excerpt}</p>}
       <div class="pc-ev-body post-content" set:html={html} />
     </div>
@@ -149,7 +152,7 @@ const online = /zoom\.us|meet\.google|teams\.microsoft|webex|whereby|jit\.si/i.t
             </details>
           ) : <p class="pc-ev-full">{rsvp.open ? 'This event is full.' : 'RSVPs are closed.'}</p>}
         </div>
-      ) : e.cta.label && ctaHref && !e.cancelled && (
+      ) : e.cta.label && ctaHref && !cancelled && (
         <a class={`pc-ev-cta${e.cta.style === 'outline' ? ' is-outline' : ''}`} href={ctaHref}>{e.cta.label}</a>
       )}
       <details class="pc-ev-add">

package/src/components/calendar/CalendarBoard.tsx

@@ -180,7 +180,7 @@ export default function CalendarBoard(props: Props) {
     setDraft({
       key: '__draft', kind: 'event', id: '', title: d.title, startDay: d.day, endDay: d.endDay, allDay: d.allDay || d.endDay > d.day,
       startMin: d.startMin, endMin: d.endMin, time: d.allDay ? '' : shortTime(d.startMin), range: '', color, calendarId: d.calendarId,
-      calendarName: '', status: 'draft', recurring: false, repeat: '', rooms: [], roomsHeld: false, occurrence: '', cancelled: false, location: '', edited: false, url: '',
+      calendarName: '', status: 'draft', recurring: false, repeat: '', rooms: [], roomsHeld: false, occurrence: '', cancelled: false, dateCancelled: false, location: '', edited: false, url: '',
     });
   };
 
@@ -235,6 +235,13 @@ export default function CalendarBoard(props: Props) {
     if (r.error || !r.data) { setToast({ text: r.error?.message ?? 'Couldn’t duplicate.', error: true }); return; }
     location.href = `/admin/calendar/events/${r.data.id}`;
   }
+  async function cancelDate(it: BoardItem, restore: boolean) {
+    const r = await actions.events.cancelDate({ id: it.id, occurrence: it.occurrence, restore });
+    setPeek(null);
+    if (r.error) { setToast({ text: r.error.message, error: true }); return; }
+    setToast({ text: `${restore ? 'Restored' : 'Cancelled'} “${it.title}” on ${dayLabel(it.startDay)}` });
+    await refresh();
+  }
   async function remove(it: BoardItem) {
     if (!confirm(it.recurring ? `Delete “${it.title}” and every repeat?` : `Delete “${it.title}”?`)) return;
     const r = await actions.events.delete({ id: it.id });
@@ -470,12 +477,14 @@ export default function CalendarBoard(props: Props) {
             {it.rooms.length > 0 && <li>{it.roomsHeld ? 'Holds' : 'Will hold once published:'} {it.rooms.join(', ')}</li>}
             {statusWord(it) && <li>{statusWord(it)}{it.edited ? ' · has unpublished changes' : ''}</li>}
             {!statusWord(it) && it.edited && <li>Has unpublished changes</li>}
-            {it.cancelled && <li>Cancelled</li>}
+            {it.cancelled && <li>{it.dateCancelled ? 'This date is cancelled' : 'Cancelled'}</li>}
           </ul>
           <div className="sch-peek-actions">
             {it.kind === 'event' && <>
               <a className="btn sm primary" href={`/admin/calendar/events/${it.id}`}>Edit</a>
               <button type="button" className="btn sm" onClick={() => duplicate(it)}>Duplicate</button>
+              {it.recurring && it.dateCancelled && <button type="button" className="btn sm" onClick={() => cancelDate(it, true)}>Restore this date</button>}
+              {it.recurring && !it.cancelled && <button type="button" className="btn sm" onClick={() => cancelDate(it, false)}>Cancel this date</button>}
               {it.url && <a className="btn sm ghost" href={it.url} target="_blank" rel="noopener">View ↗</a>}
               <button type="button" className="btn sm ghost danger" onClick={() => remove(it)}>Delete</button>
             </>}

package/src/components/editor/event/OrganizeCard.tsx

@@ -53,7 +53,7 @@ export function OrganizeCard({ meta, onChange, calendars, fields, tags }: Props)
           const set = (v: string) => onChange({ fields: { ...meta.fields, [f.key]: v } });
           return (
             <label key={f.key} className="pe-field">
-              <span>{f.label}</span>
+              <span>{f.label}{f.private && <small title="Saved with the event but never shown on the site, in feeds or in the app"> · private</small>}</span>
               {f.type === 'select' ? (
                 <select value={value} onChange={(e) => set(e.target.value)}>
                   <option value="">—</option>

package/src/lib/booking/holds.ts

@@ -1,8 +1,8 @@
 // Rooms held by events. An event that lists rooms/people in roomHold makes
 // them unbookable while it happens (± setup/cleanup) or for the whole day.
 // Holds are computed from events every time — never stored as bookings — so
-// moving, repeating, skipping a date, cancelling or deleting the event frees
-// or moves the room automatically. availabilityContext() adds these to its
+// moving, repeating, skipping a date, cancelling the event or one of its
+// dates, or deleting it frees or moves the room automatically. availabilityContext() adds these to its
 // busy list, so every booking path (pages, embeds, app, API, agent) obeys.
 import type { ContentRepository } from '../repo/types';
 import type { Booking, CalEvent, Resource, Settings } from '../schema';
@@ -55,6 +55,8 @@ export function holdsFromEvents(
   const pad = 2 * DAY;
   const occurrences = expandEvents(holding, settings, { displayTz: settings.timezone || 'UTC', now: from, windowStartMs: from - pad, windowEndMs: to + pad });
   for (const o of occurrences) {
+    // a cancelled date frees the room for that slot only
+    if (o.cancelled) continue;
     const h = o.event.roomHold;
     for (const resourceId of h.resourceIds) {
       if (opts.resourceId && resourceId !== opts.resourceId) continue;

package/src/lib/booking/service.ts

@@ -10,7 +10,7 @@ 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 { eventTimeZone, locationLine, occurrenceKey } from '../calendar/events';
 import { bookingEmail, whenText, type BookingEmail } from './emails';
 import { holdOf, isBookable, resourceZone, spanEnd, type AvailabilityContext, type Interval } from './availability';
 import { decideStatus, linkApproval } from './approval';
@@ -267,6 +267,9 @@ export async function createRsvp(
   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.');
+  if (e.cancelledDates?.length && e.cancelledDates.includes(occurrenceKey(e, args.start, await repo.getSettings()))) {
+    throw new BookingError(410, 'This date is cancelled.');
+  }
   const seats = Math.max(1, Math.min(e.rsvp.maxSeats || 1, Math.floor(args.seats) || 1));
   const booker = validateBooker(null, args.booker);
   await checkEmailCap(repo, booker.email, args.source, await repo.getSettings(), opts.now);

package/src/lib/calendar/agent.ts

@@ -110,7 +110,7 @@ export async function runEventTool(repo: ContentRepository, input: EventToolInpu
     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) };
+      return { ...eventToJson(mergeEventDraft(e), ctx.origin, calMap, settings.timezone, { includePrivate: true }), bodyHtml: mergeEventDraft(e).bodyHtml, hasPendingDraft: Boolean(e.draft), editUrl: editUrl(e.id) };
     }
     case 'create_event': {
       const a = input.arguments;

package/src/lib/calendar/api.ts

@@ -1,9 +1,10 @@
 // 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.
+// everywhere. Drafts, internal ids of private calendars, staging data and
+// private custom fields (unless a staff caller asks for them) never appear
+// here.
 import type { CalEvent, Calendar } from '../schema';
-import { calendarFeedUrl, eventIcsUrl, eventUrl } from './config';
+import { calendarFeedUrl, eventIcsUrl, eventUrl, publicEventFields } from './config';
 import { describeRepeat } from './rrule';
 
 export interface EventJson {
@@ -23,6 +24,7 @@ export interface EventJson {
   rrule: string;
   repeats: string;
   exdates: string[];
+  cancelledDates: string[];
   location: CalEvent['location'];
   cta: CalEvent['cta'];
   rsvp?: CalEvent['rsvp'];
@@ -36,7 +38,7 @@ export interface EventJson {
 
 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 {
+export function eventToJson(e: CalEvent, origin: string, calendars: Map<string, Calendar>, siteTz = '', opts: { includePrivate?: boolean } = {}): EventJson {
   return {
     id: e.id,
     slug: e.slug,
@@ -54,6 +56,7 @@ export function eventToJson(e: CalEvent, origin: string, calendars: Map<string,
     rrule: e.rrule,
     repeats: describeRepeat(e.rrule, e.start),
     exdates: e.exdates,
+    cancelledDates: e.cancelledDates ?? [],
     location: e.location,
     cta: e.cta,
     rsvp: e.rsvp,
@@ -64,7 +67,7 @@ export function eventToJson(e: CalEvent, origin: string, calendars: Map<string,
       .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,
+    fields: opts.includePrivate ? e.fields : publicEventFields(e.fields),
     updatedAt: new Date(e.updatedAt).toISOString(),
   };
 }

package/src/lib/calendar/board.ts

@@ -5,7 +5,7 @@
 import type { ContentRepository } from '../repo/types';
 import type { CalEvent, Settings } from '../schema';
 import { collectViewEvents } from './data';
-import { eventTimeZone, safeColor } from './events';
+import { occurrenceKey, safeColor } from './events';
 import { tzParts, zonedToUtc } from './ics';
 import { addDays, isIsoDay, type GridItem, type Iso } from './grid';
 import { bookingsEnabled } from './config';
@@ -32,6 +32,8 @@ export interface BoardItem extends GridItem {
   // this occurrence's start as wall time in the event's own zone (for exdates)
   occurrence: string;
   cancelled: boolean;
+  // just this date is cancelled (Restore brings it back)
+  dateCancelled: boolean;
   location: string;
   edited: boolean; // live event with unpublished changes
   url: string; // public URL ('' when none)
@@ -102,11 +104,7 @@ export async function loadBoard(repo: ContentRepository, settings: Settings, fro
     const startDay = s.day;
     const endDay = allDay ? addDays(startDay, Math.max(1, v.days) - 1) : en.day < s.day ? s.day : en.day;
     const cal = e ? e.calendarIds.map((id) => calById.get(id)).find(Boolean) : calendars.find((c) => c.name === v.calendarName && c.kind === 'feed');
-    let occurrence = '';
-    if (e) {
-      const p = tzParts(v.start, eventTimeZone(e, settings));
-      occurrence = allDay ? isoOf(p) : `${isoOf(p)}T${pad(p.hh)}:${pad(p.mm)}`;
-    }
+    const occurrence = e ? occurrenceKey(e, v.start, settings, tz) : '';
     items.push({
       key: e ? `e:${e.id}:${v.start}` : `f:${cal?.id ?? ''}:${v.start}:${v.title}`,
       kind: e ? 'event' : 'feed',
@@ -127,6 +125,7 @@ export async function loadBoard(repo: ContentRepository, settings: Settings, fro
       roomsHeld: e ? holdsRooms(e) : false,
       occurrence,
       cancelled: Boolean(v.cancelled),
+      dateCancelled: Boolean(e && !e.cancelled && (e.cancelledDates ?? []).includes(occurrence)),
       location: v.location,
       edited: Boolean(e?.draft),
       url: e?.status === 'published' ? v.url ?? '' : '',
@@ -157,7 +156,7 @@ export async function loadBoard(repo: ContentRepository, settings: Settings, fro
         calendarId: `res:${b.resourceId}`,
         calendarName: r?.name ?? '',
         status: b.status as BoardStatus,
-        recurring: false, repeat: '', rooms: [], roomsHeld: false, occurrence: '', cancelled: false,
+        recurring: false, repeat: '', rooms: [], roomsHeld: false, occurrence: '', cancelled: false, dateCancelled: false,
         location: r?.name ?? '', edited: false, url: '',
       });
     }

package/src/lib/calendar/cards.ts

@@ -26,11 +26,13 @@ const esc = (s: string) =>
 export const safeHref = (h: string) => (/^(https?:\/\/|\/(?!\/)|mailto:|tel:|#)/i.test(h.trim()) ? h.trim() : '');
 
 export function eventCardHtml(
-  o: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'>,
+  o: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'> & { cancelled?: boolean },
   settings: Settings,
   opts: { showImage: boolean; showCta?: boolean; href?: string; heading?: 'h2' | 'h3' }
 ): string {
   const e: CalEvent = o.event;
+  // the whole event, or just this date
+  const cancelled = e.cancelled || Boolean(o.cancelled);
   const tz = settings.timezone || 'UTC';
   const f = formatOccurrence(o, tz, siteLocale(settings));
   const href = opts.href ?? eventUrl(e.slug);
@@ -46,12 +48,12 @@ export function eventCardHtml(
   const loc = locationLine(e.location);
   const ctaHref = safeHref(e.cta.href);
   const cta =
-    opts.showCta && e.cta.label && ctaHref && !e.cancelled
+    opts.showCta && e.cta.label && ctaHref && !cancelled
       ? `<a class="pc-ev-cta${e.cta.style === 'outline' ? ' is-outline' : ''}" href="${esc(ctaHref)}">${esc(e.cta.label)}</a>`
       : '';
   return (
-    `<article class="pc-ev-card${e.cancelled ? ' is-cancelled' : ''}">${media}<div class="pc-ev-card-body">` +
-    `<div class="pc-ev-card-when">${e.cancelled ? '<span class="pc-ev-flag">Cancelled</span> ' : ''}${esc(when)}</div>` +
+    `<article class="pc-ev-card${cancelled ? ' is-cancelled' : ''}">${media}<div class="pc-ev-card-body">` +
+    `<div class="pc-ev-card-when">${cancelled ? '<span class="pc-ev-flag">Cancelled</span> ' : ''}${esc(when)}</div>` +
     `<${h} class="pc-ev-card-title"><a href="${esc(href)}">${esc(e.title || 'Untitled event')}</a></${h}>` +
     (e.excerpt ? `<p class="pc-ev-card-excerpt">${esc(e.excerpt)}</p>` : '') +
     (loc ? `<div class="pc-ev-card-loc">${esc(loc)}</div>` : '') +
@@ -72,11 +74,11 @@ export async function upcomingEvents(
     displayTz: tz, now, windowStartMs: now, windowEndMs: now + (opts.horizonDays ?? 400) * 86_400_000,
   }, { audience: 'public', calendarIds: opts.calendarIds, includeFeeds: false });
   const seen = new Set<string>();
-  const out: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days'>[] = [];
+  const out: Pick<Occurrence, 'event' | 'start' | 'end' | 'allDay' | 'days' | 'cancelled'>[] = [];
   for (const v of events) {
     if (!v.event || v.end <= now || seen.has(v.event.id)) continue;
     seen.add(v.event.id);
-    out.push({ event: v.event, start: v.start, end: v.end, allDay: v.allDay, days: v.days });
+    out.push({ event: v.event, start: v.start, end: v.end, allDay: v.allDay, days: v.days, cancelled: Boolean(v.cancelled) });
     if (out.length >= opts.limit) break;
   }
   return out;

package/src/lib/calendar/config.ts

@@ -13,6 +13,9 @@ export interface EventFieldConfig {
   label: string;
   type: EventFieldType;
   options: string[];
+  // stored and editable in the admin, returned by @acms-subir/core/server,
+  // but never in public output (event page, APIs, webhooks, app, feeds)
+  private: boolean;
 }
 
 export interface CalendarConfig {
@@ -43,6 +46,15 @@ const FALLBACK: CalendarConfig = {
 
 export const CALENDAR: CalendarConfig = { ...FALLBACK, ...(userConfig.calendar ?? {}) };
 
+/** only the event's values for configured, non-private fields */
+export function publicEventFields(fields: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(CALENDAR.eventFields.filter((f) => !f.private && Object.hasOwn(fields, f.key)).map((f) => [f.key, fields[f.key]]));
+}
+/** the event as visitors may see it: private field values removed */
+export function withoutPrivateFields<T extends { fields: Record<string, string> }>(e: T): T {
+  return { ...e, fields: publicEventFields(e.fields) };
+}
+
 export const eventUrl = (slug: string) => `${CALENDAR.eventsBase}/${slug}`;
 export const eventIcsUrl = (slug: string) => `${CALENDAR.eventsBase}/${slug}.ics`;
 export const calendarPageUrl = (slug?: string) => (slug ? `${CALENDAR.base}?cal=${encodeURIComponent(slug)}` : CALENDAR.base);