@acms-subir/core 0.3.21 → 0.3.22

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @acms-subir/core
 
+## 0.3.22
+
+### Patch Changes
+
+- dc7206a: Add roles defined by the site: `acms({ roles: [{ key, label, summary?, admin?, home? }] })`, up to 10. They rank below Contributor in the order listed, so administrators can invite people to them, and they show on Team → Users and Team → Roles under "This site". A role with `admin: false` (the default) signs people in at `/admin/login` for the site's own pages only: every admin page, API, action, preview and editor-app check treats them as signed out, `/admin` sends them to the role's `home` (default: the My events pages, else `/`), and they get no public author page, don't appear in public search and aren't offered as post authors. A role with `admin: true` is staff and starts with only what an owner grants it on Team → Roles. A role the site later removes fails closed: people still holding it get no admin access and no permissions, and Team → Users marks them "No longer defined". The build fails with the fix in the message for a bad, duplicate or core role key, or a `home` inside `/admin` or `/api`. Sites without site roles see no change.
+
+  Add permissions defined by the site: `acms({ permissions: [{ key, label, description?, defaults?, sensitive? }] })`, up to 50, with dotted keys like `classes.manageAll` (the core namespaces are reserved). Owners turn them on and off per role in a "This site" area on Team → Roles, and site code checks them with `currentUser().can(key)`. A role without admin access can only hold site permissions and **Request events**; the other core permissions are greyed out for it on Team → Roles and refused if saved.
+
+  `/admin/login?return=` now accepts any page on the site, not only admin pages, so a "Sign in" link on `/classes` brings people back there. Other sites, the login, logout and app sign-in pages, `/api`, `/_actions` and `/account` are refused. Without `return`, staff go to `/admin` and everyone else to their role's home; people without admin access are never sent into the admin.
+
+  Add members' event requests ("My events"). With the calendar on, `acms({ members: { base?, notify? } })` (on by default, at `/members`) adds pages in the site's theme where members see the events they host and their requests, ask for a new event (it waits as a draft) and suggest changes to a live event they host (the event stays as it is until approved). Hosts can always cancel or restore a single date of their own events, at once. The new core permission **Request events** (`events.request`) is on by default for every site role; approving and declining needs **Publish content**. Staff answer requests from Calendar → Events, and the event editor shows the request and a Hosts picker. New requests and suggested changes are emailed to `members.notify`, or to the owners, and follow Settings → Email → Staff notifications; the member is emailed when a request is approved or declined, with staff's note. A file at the same path in the site's `src/pages/` replaces any one page, and `members: false` turns them all off. Events gain `hostIds` and `request`, which never appear in public output; migration 56 adds both columns.
+
+  `@acms-subir/core/server` adds `listMyEvents`, `listEventRequests`, `submitEventRequest`, `updateEventRequest`, `withdrawEventRequest`, `approveEventRequest`, `declineEventRequest`, `setHostedOccurrence`, a `hostedBy` option for `listEvents`, and the `EventRequestInput` and `Role` types, so a site can build its own request pages with the same rules. Unlike `cancelOccurrence`, the request functions check the person acting. `currentUser()` now returns anyone signed in, adds `staff`, and its `can()` covers site permissions. Run `acms docs server` for the guide and an example request page.
+
+  Editor apps: only staff roles get tokens, including a site role with `admin: true`. Moving someone to a role without admin access refuses their signed-in devices from the next request, and the app's sign-in page tells them their account can't use the app. Client and native types widen the editor's `role` from the five core roles to any string, and the native editor keeps stored sign-ins whose role is a site role.
+
+  Check site code that calls `currentUser()`: once a site defines roles without admin access, it also returns those people (with `staff: false`), where before it returned staff only. Code that treated any signed-in result as permission to change things should check `user.staff` or `user.can(...)` instead.
+
 ## 0.3.21
 
 ### Patch Changes

package/cli/migrations.generated.mjs

@@ -1059,6 +1059,12 @@ var MIGRATIONS = [
     `DROP TRIGGER content_version_events_update`,
     // [insert, delete, update]: only the update trigger names columns
     contentVersionTriggers("events", [...CONTENT_VERSION_COLUMNS.events, "cancelled_dates"])[2]
+  ] },
+  // event hosts and members' event requests (CalEvent.hostIds / .request);
+  // neither is public, so the content-version trigger stays as it is
+  { version: 56, statements: [
+    `ALTER TABLE events ADD COLUMN host_ids TEXT NOT NULL DEFAULT '[]'`,
+    `ALTER TABLE events ADD COLUMN request TEXT`
   ] }
 ];
 var CURRENT_CONTENT_VERSION_COLUMNS = {

package/docs/mobile.md

@@ -365,7 +365,7 @@ data on sign-out.
 
 | Hook | Gives you |
 | --- | --- |
-| `useAuth()` | `status` (`loading`/`signedOut`/`signingIn`/`signedIn`), `user`, `role`, `device`, `error`, `signedOutReason`, `signIn()`, `signOut()` |
+| `useAuth()` | `status` (`loading`/`signedOut`/`signingIn`/`signedIn`), `user`, `role` (a core role or a staff role the site defines, so any string), `device`, `error`, `signedOutReason`, `signIn()`, `signOut()` |
 | `useSiteInfo()` / `useMe()` | public site name + logo / the person, site features and `permissions` |
 | `useDocuments(query)` | infinite list (`kind`, `status`, `collection`, `q`); flat `items`, `total` |
 | `useCreateDocument()` | mutation: `{ kind, title, collection? \| start? }` |

package/docs/server.md

@@ -1,51 +1,80 @@
 # 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.
+actions. Use it to read events, find out who is signed in, cancel single dates of a
+repeating event, and run members' event requests. 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,
+  listMyEvents, listEventRequests, submitEventRequest, updateEventRequest,
+  withdrawEventRequest, approveEventRequest, declineEventRequest, setHostedOccurrence,
 } from '@acms-subir/core/server';
 ```
 
+These are primitives. Roles, permissions and the member pages are config
+(`acms({ roles, permissions, members })`, see [roles and
+permissions](../../../docs/roles-permissions.md)); this API is what the built-in pages
+use, so a site can replace any of them, or turn them all off, and keep the same rules.
+
 ## 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[]>
+listEvents(repo: Repo, opts?: { publishedOnly?: boolean; calendar?: string; hostedBy?: 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>
+cancelOccurrence(repo: Repo, eventId: string, occurrenceKey: string, ctx: WriteContext): Promise<CalEvent>
+restoreOccurrence(repo: Repo, eventId: string, occurrenceKey: string, ctx: WriteContext): Promise<CalEvent>
+
+// event requests: `who` is currentUser()'s result (anything with `id` and `can()` works)
+listMyEvents(repo: Repo, who: ServerUser | null): Promise<CalEvent[]>
+listEventRequests(repo: Repo, who: ServerUser | null): Promise<CalEvent[]>
+submitEventRequest(repo: Repo, who: ServerUser | null, input: EventRequestInput, ctx: WriteContext): Promise<CalEvent>
+updateEventRequest(repo: Repo, who: ServerUser | null, eventId: string, input: EventRequestInput, ctx: WriteContext): Promise<CalEvent>
+withdrawEventRequest(repo: Repo, who: ServerUser | null, eventId: string, ctx: WriteContext): Promise<{ deleted: boolean }>
+approveEventRequest(repo: Repo, who: ServerUser | null, eventId: string, ctx: WriteContext, seen?: number): Promise<CalEvent>
+declineEventRequest(repo: Repo, who: ServerUser | null, eventId: string, reply: string, ctx: WriteContext, seen?: number): Promise<CalEvent>
+setHostedOccurrence(repo: Repo, who: ServerUser | null, eventId: string, occurrenceKey: string, cancelled: boolean, ctx: WriteContext): Promise<CalEvent>
 
-interface ServerUser { id: string; email: string; name: string; role: Role; can(permission: string): boolean }
+type Role = 'owner' | 'administrator' | 'editor' | 'author' | 'contributor' | (string & {})
+interface ServerUser { id: string; email: string; name: string; role: Role; staff: boolean; can(permission: string): boolean }
 interface Occurrence { event: CalEvent; start: number; end: number; allDay: boolean; days: number; key: string; cancelled: boolean }
+interface WriteContext { url: URL; locals: unknown }
 ```
 
-The types `Repo`, `ServerUser`, `CalEvent`, `Occurrence`, `ListEventsOptions`,
-`OccurrenceWindow` and `WriteContext` are exported too.
+The types `Repo`, `Role`, `ServerUser`, `CalEvent`, `Occurrence`, `ListEventsOptions`,
+`OccurrenceWindow`, `WriteContext` and `EventRequestInput` 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.
+- **`currentUser(ctx)`**: the person signed in, or `null`: staff, and people in the
+  site's own roles who can't use the admin. 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 a core role or a key from `acms({ roles })`, e.g. `'host'`.
+  - `staff` is true for the core roles and site roles with `admin: true`: the people
+    who can use the admin. Everyone else is signed in for your pages only.
+  - `can(key)` checks a permission from Team → Roles: a core one (`'content.edit'`) or
+    one from `acms({ permissions })` (`'classes.manageAll'`). Unknown keys return
+    `false`. A role without admin access only ever holds site permissions and
+    `'events.request'`. Owners hold every permission. A role the site has since
+    removed holds none.
+  - A session from `ADMIN_PASSWORD` has `id: '__owner_env__'`, role `owner`, name
+    `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;
+  `calendar` (an id or slug) limits the list to one calendar. `hostedBy` (a user id)
+  limits it to events that person hosts (`event.hostIds`). 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)`,
@@ -72,7 +101,8 @@ people:
 | 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.
+> who is calling (`currentUser`, your own signed link, etc.) before you call them. The
+> event-request functions below are different: they check the person themselves.
 
 ## Occurrence keys
 
@@ -105,7 +135,18 @@ 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:
+Give hosts a role and give a few staff a permission to cancel any class:
+
+```js
+// astro.config.mjs
+acms({
+  roles: [{ key: 'host', label: 'Class host', home: '/classes' }],
+  permissions: [{ key: 'classes.manageAll', label: 'Cancel any class', defaults: ['administrator'] }],
+})
+```
+
+Staff pick each class's hosts in the event editor (Hosts), which fills
+`event.hostIds`. `src/actions/index.ts` in the site:
 
 ```ts
 import { defineAction, ActionError } from 'astro:actions';
@@ -121,8 +162,8 @@ export const server = {
       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);
+      // your rule: anyone given "Cancel any class", or a host of this event
+      const allowed = me && event && (me.can('classes.manageAll') || event.hostIds.includes(me.id));
       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 });
@@ -136,9 +177,147 @@ export const server = {
 };
 ```
 
+List a host's classes with `listEvents(repo, { hostedBy: me.id, publishedOnly: true })`.
 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`.
+Date.now() + 90 * 86_400_000 })` and pass `o.key` as `date`. If hosts are the only people
+who cancel, `setHostedOccurrence` (below) does the host check for you.
 
 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.
+
+## Event requests
+
+Members ask for events; staff approve them. A member is anyone whose role holds
+**Request events** (`events.request`), which every site role has by default. Each event
+carries:
+
+- `hostIds`: the people who host it. Staff set them in the event editor; a member who
+  asks for an event hosts it.
+- `request`: `null`, or `{ kind, state, by, at, note, reply, reviewedBy, reviewedAt }`.
+  `kind` is `'new'` (a draft waiting for approval) or `'changes'` (suggested changes to
+  a live event, staged in `event.draft`; the live event shows what it showed before).
+  `state` is `'pending'` or `'declined'`. `note` is the member's message to staff and
+  `reply` staff's answer when declining. Neither field is public.
+
+The functions take the person acting (`currentUser(ctx)`) and check them on every call:
+
+- **`listMyEvents(repo, who)`**: the events they host plus their own new requests,
+  soonest first, archived ones left out. Drafts are included. `[]` when `who` is `null`.
+- **`listEventRequests(repo, who)`**: requests waiting for staff, oldest first. Needs
+  `content.publish` (the same rule as approving them).
+- **`submitEventRequest(repo, who, input, ctx)`**: needs `events.request`. Creates a
+  draft event they host with a pending `'new'` request, and emails staff.
+- **`updateEventRequest(repo, who, eventId, input, ctx)`**: needs `events.request` and
+  to host the event. A request that isn't live yet is updated and sent again (a
+  declined one too). On a live event the changes are staged and wait for approval. A
+  description or place left as it was keeps whatever staff added (formatting, address,
+  map pin). While staff have unpublished edits of their own on the live event, it
+  answers 409 so the two never mix.
+- **`withdrawEventRequest(repo, who, eventId, ctx)`**: needs `events.request` and to
+  host the event. A new event their own request made, and that never went live, is
+  deleted (`{ deleted: true }`); a draft staff wrote stays. Suggested changes are dropped.
+- **`approveEventRequest(repo, who, eventId, ctx)`**: needs **Publish content**
+  (`content.publish`). A new event is published; suggested changes go live. The member
+  is emailed. Pass `seen`, the `request.at` of the version you showed staff, and it
+  answers 409 if the member changed the request since (so nothing is approved unseen).
+- **`declineEventRequest(repo, who, eventId, reply, ctx)`**: needs **Publish content**.
+  A new request stays a draft the member can edit and send again; suggested changes are
+  dropped. The member is emailed with `reply`. `seen` works as for approving.
+- **`setHostedOccurrence(repo, who, eventId, key, cancelled, ctx)`**: a host cancels
+  (`true`) or restores (`false`) one date of an event they host, at once. No permission
+  needed beyond being in `hostIds`. Same rules and errors as `cancelOccurrence`.
+
+`EventRequestInput` is what a member may fill in. Staff can change anything else in the
+admin.
+
+| field | |
+|---|---|
+| `title` | required, up to 200 characters |
+| `start`, `end?` | `YYYY-MM-DDTHH:mm` in the site's time zone (what `<input type="datetime-local">` sends), or `YYYY-MM-DD` with `allDay: true` |
+| `allDay?` | boolean |
+| `repeat?` | `''` (once), or `FREQ=DAILY`, `FREQ=WEEKLY` or `FREQ=MONTHLY` with an optional `;INTERVAL=n` and `;COUNT=n` |
+| `description?` | plain text, up to 5,000 characters; blank lines start new paragraphs. Stored escaped |
+| `where?` | the place, as text, up to 300 characters |
+| `calendarId?` | one of the site's own public calendars |
+| `fields?` | the site's custom event fields; private ones are ignored, and a select must use one of its options |
+| `note?` | a message for staff, up to 1,000 characters; never public |
+
+Errors carry a `status` and a message that is safe to show people:
+
+| status | when |
+|---|---|
+| 400 | bad input (no title, bad date or repeat, unknown calendar or option); nothing to withdraw |
+| 401 | `who` is `null` |
+| 403 | the role lacks `events.request` (members) or `content.publish` (approve, decline) |
+| 404 | the event doesn't exist or they don't host it (member functions) |
+| 409 | there's no pending request on the event: already answered or withdrawn (approve, decline) |
+| 429 | more than 20 requests or changes in an hour, or 20 requests already waiting |
+
+New requests and suggested changes are emailed to `acms({ members: { notify } })`, or to
+the owners who have an email address. Email needs Settings → Email set up; its **Staff
+notifications** switch also turns these off.
+
+### Built-in pages
+
+With the calendar on, `acms({ members })` adds "My events" in the site's theme:
+
+| path | page |
+|---|---|
+| `/members/events` | the events they host and their requests |
+| `/members/events/new` | the request form |
+| `/members/events/[id]` | one of their events and its request |
+
+`/members` itself redirects to `/members/events`.
+
+`members: { base: '/club' }` moves them. A file at the same path in your `src/pages/`
+replaces that one page. `members: false` removes them all; the functions above keep
+working. While the pages are on, site roles without admin access land on
+`/members/events` after signing in unless their role sets `home`.
+
+### Example: your own request page
+
+`src/pages/classes/new.astro`:
+
+```astro
+---
+import { getRepo, currentUser, submitEventRequest } from '@acms-subir/core/server';
+
+const me = await currentUser(Astro);
+if (!me) return Astro.redirect(`/admin/login?return=${encodeURIComponent(Astro.url.pathname)}`);
+if (!me.can('events.request')) return new Response('Your role can’t ask for classes.', { status: 403 });
+
+let error = '';
+if (Astro.request.method === 'POST') {
+  const form = await Astro.request.formData();
+  try {
+    await submitEventRequest(await getRepo(Astro.locals), me, {
+      title: String(form.get('title') ?? ''),
+      start: String(form.get('start') ?? ''),
+      repeat: form.get('weekly') ? 'FREQ=WEEKLY' : '',
+      where: String(form.get('where') ?? ''),
+      note: String(form.get('note') ?? ''),
+    }, { url: Astro.url, locals: Astro.locals });
+    return Astro.redirect('/classes/mine');
+  } catch (e) {
+    error = (e as Error).message;
+  }
+}
+---
+<!-- wrap in your own page layout -->
+<main>
+  <h1>Ask for a class</h1>
+  {error && <p role="alert">{error}</p>}
+  <form method="post">
+    <label>Title <input name="title" required /></label>
+    <label>Starts <input name="start" type="datetime-local" required /></label>
+    <label><input name="weekly" type="checkbox" /> Every week</label>
+    <label>Where <input name="where" /></label>
+    <label>Note for the team <textarea name="note"></textarea></label>
+    <button>Send request</button>
+  </form>
+</main>
+```
+
+`/classes/mine` would list `listMyEvents(repo, me)` and show `e.request?.state`
+(`'pending'`, `'declined'` with `e.request.reply`, or no request once approved).

package/integration.mjs

@@ -408,6 +408,97 @@ function resolveCalendar(calendar, contentBases, locales) {
   return resolved;
 }
 
+// Defaults + validation for acms({ roles, permissions, members }). Site roles
+// rank below Contributor in the order listed; `admin: false` (the default)
+// signs people in for the site's own pages only. Site permissions show on
+// Team → Roles under "This site" and answer user.can(key). Core keeps the
+// core role names and these permission namespaces for itself (kept in sync
+// with lib/permissions/catalog.ts by test/site-roles.test.ts).
+export const CORE_ROLE_KEYS = ['owner', 'administrator', 'editor', 'author', 'contributor'];
+export const CORE_PERMISSION_NAMESPACES = ['content', 'media', 'forms', 'site', 'schedule', 'events', 'team', 'integrations', 'services', 'data', 'roles'];
+const unknownKeys = (label, value, known) => {
+  const extra = Object.keys(value).filter((k) => !known.includes(k));
+  if (extra.length) throw new Error(`acms: unknown ${label} key${extra.length > 1 ? 's' : ''} ${extra.map((k) => `"${k}"`).join(', ')} — valid keys are ${known.join(', ')}`);
+};
+const isSitePath = (p) => typeof p === 'string' && p.startsWith('/') && !p.startsWith('//') && !/[\\\s\u0000-\u001f]/.test(p);
+const isAdminPath = (p) => /^\/(admin|api|_actions)(\/|$|\?|#)/.test(p);
+function resolveMembers(members, calendar) {
+  if (members === false) return { enabled: false, base: '/members', notify: [] };
+  if (members === undefined || members === true) members = {};
+  if (!members || typeof members !== 'object' || Array.isArray(members)) throw new Error('acms: members must be an object (or false to turn off the built-in member pages)');
+  unknownKeys('members', members, ['base', 'notify']);
+  // who hears about new event requests (default: the owners)
+  const notify = members.notify ?? [];
+  if (!Array.isArray(notify) || notify.length > 20 || notify.some((e) => typeof e !== 'string' || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e))) {
+    throw new Error('acms: members.notify must be a list of at most 20 email addresses');
+  }
+  const base = members.base ?? '/members';
+  if (typeof base !== 'string' || !/^\/[a-z0-9-]+(\/[a-z0-9-]+)*$/.test(base)) {
+    throw new Error(`acms: members.base must start with "/" and use lowercase letters, digits, and hyphens (no trailing slash) — got "${base}"`);
+  }
+  if (RESERVED_BASES.has(base) || base === '/account') throw new Error(`acms: members.base "${base}" collides with a built-in route — pick another path`);
+  // the built-in pages are "My events": they need the calendar
+  return { enabled: calendar.enabled, base, notify: notify.map((e) => e.trim().toLowerCase()) };
+}
+function resolveRoles(roles, members) {
+  if (roles === undefined) return [];
+  if (!Array.isArray(roles)) throw new Error('acms: roles must be an array of { key, label } objects');
+  if (roles.length > 10) throw new Error('acms: roles allows at most 10 site roles');
+  const keys = new Set();
+  return roles.map((r, i) => {
+    if (!r || typeof r !== 'object' || Array.isArray(r)) throw new Error(`acms: roles[${i}] must be an object`);
+    unknownKeys(`roles[${i}]`, r, ['key', 'label', 'summary', 'admin', 'home']);
+    const key = r.key;
+    if (typeof key !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(key)) {
+      throw new Error(`acms: roles[${i}].key must be 1–32 lowercase letters, digits, "_" or "-", starting with a letter — got "${key}"`);
+    }
+    if (CORE_ROLE_KEYS.includes(key)) throw new Error(`acms: roles[${i}].key "${key}" is a built-in role — pick another key`);
+    if (keys.has(key)) throw new Error(`acms: roles has two roles with the key "${key}"`);
+    keys.add(key);
+    if (typeof r.label !== 'string' || !r.label.trim() || r.label.length > 40) throw new Error(`acms: roles "${key}".label must be a name of 1–40 characters`);
+    const summary = r.summary ?? '';
+    if (typeof summary !== 'string' || summary.length > 160) throw new Error(`acms: roles "${key}".summary must be a string of at most 160 characters`);
+    const admin = r.admin ?? false;
+    if (typeof admin !== 'boolean') throw new Error(`acms: roles "${key}".admin must be true or false`);
+    // non-admin roles land on their home page after signing in: the member
+    // pages when they're on, else the site's home page
+    const home = r.home ?? (members.enabled ? `${members.base}/events` : '/');
+    if (!isSitePath(home) || isAdminPath(home)) throw new Error(`acms: roles "${key}".home must be a path on this site outside /admin and /api, like "/classes" — got "${home}"`);
+    return { key, label: r.label.trim(), summary: summary.trim(), admin, home };
+  });
+}
+function resolvePermissions(permissions, roles) {
+  if (permissions === undefined) return [];
+  if (!Array.isArray(permissions)) throw new Error('acms: permissions must be an array of { key, label } objects');
+  if (permissions.length > 50) throw new Error('acms: permissions allows at most 50 site permissions');
+  const roleKeys = ['administrator', 'editor', 'author', 'contributor', ...roles.map((r) => r.key)];
+  const keys = new Set();
+  return permissions.map((p, i) => {
+    if (!p || typeof p !== 'object' || Array.isArray(p)) throw new Error(`acms: permissions[${i}] must be an object`);
+    unknownKeys(`permissions[${i}]`, p, ['key', 'label', 'description', 'defaults', 'sensitive']);
+    const key = p.key;
+    if (typeof key !== 'string' || key.length > 64 || !/^[a-z][a-zA-Z0-9_-]*(\.[a-zA-Z0-9_-]+)+$/.test(key)) {
+      throw new Error(`acms: permissions[${i}].key must be dotted, like "classes.manageAll" — got "${key}"`);
+    }
+    const ns = key.split('.')[0];
+    if (CORE_PERMISSION_NAMESPACES.includes(ns)) throw new Error(`acms: permissions "${key}" uses "${ns}.", which is kept for built-in permissions — pick another prefix`);
+    if (keys.has(key)) throw new Error(`acms: permissions has two permissions with the key "${key}"`);
+    keys.add(key);
+    if (typeof p.label !== 'string' || !p.label.trim() || p.label.length > 80) throw new Error(`acms: permissions "${key}".label must be a name of 1–80 characters`);
+    const description = p.description ?? '';
+    if (typeof description !== 'string' || description.length > 240) throw new Error(`acms: permissions "${key}".description must be a string of at most 240 characters`);
+    const defaults = p.defaults ?? [];
+    if (!Array.isArray(defaults)) throw new Error(`acms: permissions "${key}".defaults must be an array of role keys`);
+    for (const role of defaults) {
+      if (role === 'owner') throw new Error(`acms: permissions "${key}".defaults lists "owner" — owners hold every permission already`);
+      if (!roleKeys.includes(role)) throw new Error(`acms: permissions "${key}".defaults lists "${role}" — use ${roleKeys.map((k) => `"${k}"`).join(', ')}`);
+    }
+    const sensitive = p.sensitive ?? false;
+    if (typeof sensitive !== 'boolean') throw new Error(`acms: permissions "${key}".sensitive must be true or false`);
+    return { key, label: p.label.trim(), description: description.trim(), defaults: [...new Set(defaults)], sensitive };
+  });
+}
+
 const semverLt = (a, b) => {
   const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
   for (let i = 0; i < 3; i++) { if ((pa[i] ?? 0) < (pb[i] ?? 0)) return true; if ((pa[i] ?? 0) > (pb[i] ?? 0)) return false; }
@@ -535,6 +626,27 @@ function acmsVitePlugin(userConfig) {
  *   change clears the cache (Workers Cache, or the Cloudflare zone when
  *   CLOUDFLARE_ZONE_ID + CLOUDFLARE_API_TOKEN are set). `memory: false` turns
  *   off the Node in-process API cache. `cache: false` turns all of it off.
+ * @param {Array<{key: string, label: string, summary?: string, admin?: boolean, home?: string}>} [options.roles]
+ *   Roles defined by the site, ranked below Contributor in the order listed
+ *   (administrators can invite people to them). `admin: false` (the default)
+ *   lets people sign in for the site's own pages (`currentUser()` returns
+ *   them) but keeps them out of the admin, its APIs, previews and the editor
+ *   app; `admin: true` makes the role staff with only the permissions an
+ *   owner grants on Team → Roles. `home` is where people in a role without
+ *   admin access land after signing in (default: the member pages, else '/');
+ *   staff always land in the admin.
+ * @param {Array<{key: string, label: string, description?: string, defaults?: string[], sensitive?: boolean}>} [options.permissions]
+ *   Permissions defined by the site, e.g. `{ key: 'classes.manageAll', label:
+ *   'Cancel any class', defaults: ['administrator'] }`. They show on Team →
+ *   Roles under "This site" and answer `currentUser().can(key)`. Owners hold
+ *   every permission; `defaults` lists the other roles that start with it.
+ * @param {false | {base?: string, notify?: string[]}} [options.members]
+ *   Built-in "My events" pages for signed-in members (default base
+ *   '/members', needs the calendar): the events they host, their event
+ *   requests and a request form. `false` turns the pages off (the server API
+ *   in @acms-subir/core/server still works, so a site can build its own); a
+ *   site file at the same path replaces any one page. `notify` lists who is
+ *   emailed about new event requests (default: the owners).
  * @returns {import('astro').AstroIntegration}
  */
 export default function acms(options = {}) {
@@ -548,6 +660,13 @@ export default function acms(options = {}) {
   const cache = resolveCache(options.cache);
   const mobile = resolveMobile(options.mobile);
   const calendar = resolveCalendar(options.calendar, contentBases, i18n.locales);
+  const members = resolveMembers(options.members, calendar);
+  if (members.enabled) {
+    const clash = [...contentBases.keys(), calendar.base, calendar.eventsBase, calendar.bookBase].find((b) => b === members.base);
+    if (clash) throw new Error(`acms: members.base "${members.base}" collides with another configured path — pick another`);
+  }
+  const roles = resolveRoles(options.roles, members);
+  const permissions = resolvePermissions(options.permissions, roles);
   const maps = resolveMaps(options.maps);
   const legal = { enabled: true, operatorName: '', contactEmail: '', updatedAt: '', ...(options.legal === false ? { enabled: false } : options.legal ?? {}) };
   if (typeof legal.enabled !== 'boolean' || ['operatorName','contactEmail','updatedAt'].some(k => typeof legal[k] !== 'string')) throw new Error('acms: invalid legal configuration');
@@ -569,6 +688,9 @@ export default function acms(options = {}) {
     calendar,
     maps,
     legal,
+    roles,
+    permissions,
+    members,
   };
   const routes = [...ROUTES,
     ['/api/v1/site', 'api/v1/site.ts'],
@@ -706,6 +828,17 @@ export default function acms(options = {}) {
     }
     routes.push(['/api/calendar/events/[id]', 'api/calendar/events/[id].ts']);
   }
+  // "My events" for signed-in members (acms({ members })): thin pages over
+  // lib/calendar/requests.ts. A site file at any of these paths replaces that
+  // page; `members: false` drops them all (members.enabled needs the calendar).
+  if (members.enabled) {
+    routes.push(
+      [members.base, 'members/index.ts'],
+      [`${members.base}/events`, 'members/events/index.astro'],
+      [`${members.base}/events/new`, 'members/events/new.astro'],
+      [`${members.base}/events/[id]`, 'members/events/[id].astro'],
+    );
+  }
   let cacheDir = '';
   return {
     name: 'acms',
@@ -715,7 +848,7 @@ export default function acms(options = {}) {
         if (config.root) {
           const discoveryDir = fileURLToPath(new URL('.astro/', config.root));
           mkdirSync(discoveryDir, {recursive:true});
-          writeFileSync(join(discoveryDir,'acms-project.json'), JSON.stringify({ themeApiVersion:1, collections:userConfig.content.collections, calendar:userConfig.calendar, mobile:userConfig.mobile ?? {} }));
+          writeFileSync(join(discoveryDir,'acms-project.json'), JSON.stringify({ themeApiVersion:1, collections:userConfig.content.collections, calendar:userConfig.calendar, mobile:userConfig.mobile ?? {}, roles:userConfig.roles, permissions:userConfig.permissions, members:userConfig.members }));
         }
         updateConfig({ vite: { plugins: [acmsVitePlugin(userConfig)] } });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.21",
+  "version": "0.3.22",
   "publishConfig": {
     "access": "public"
   },

package/src/actions/index.ts

@@ -10,6 +10,7 @@ import { getMediaStore } from '../lib/media/store';
 import { validateRequestSession } from '../lib/auth/request';
 import { accessFor } from '../lib/permissions/access';
 import { deniedMessage, type Permission } from '../lib/permissions/catalog';
+import { isStaffRole } from '../lib/roles';
 import { DocTranslations, LinksAvatarShape, LinksAvatarFit, LinksAvatarScale, LinkKind, parseConfig, slugify, widgetTypes, type WidgetType } from '../lib/schema';
 import { env } from '../lib/env';
 import { CONTENT, collectionUrl } from '../lib/content';
@@ -749,7 +750,8 @@ export const server = {
       handler: async (_input, ctx) => {
         await requireAdmin(ctx);
         const repo = await getRepo(ctx.locals);
-        return { users: await repo.listUsers() };
+        // the author picker: staff only (site roles without admin access don't write content)
+        return { users: (await repo.listUsers()).filter((u) => isStaffRole(u.role)) };
       },
     }),
   },

package/src/components/EmailSettings.tsx

@@ -477,7 +477,7 @@ export default function EmailSettings() {
           </label>
           <label className="ems-toggle">
             <input type="checkbox" checked={notify.staff} onChange={(e) => setNotify((n) => ({ ...n, staff: e.target.checked }))} />
-            <span>Staff notifications<small>Tell site staff about new booking requests</small></span>
+            <span>Staff notifications<small>Tell site staff about new booking and event requests</small></span>
           </label>
           {pwField(notify.pw, (v) => setNotify((n) => ({ ...n, pw: v })), 'pw-notify')}
           <div className="ems-actions">