@acms-subir/client 0.1.24 → 0.1.25

package/README.md

@@ -63,6 +63,7 @@ language. Update the site before shipping an app build with a newer client.
 | `live()` | Live video: the current broadcast (`snapshot` or `null`), `serverNow` and the owner's `display` choices. Never cached; 404 while `site.features.live` is false |
 | `announcements({ kind?, pinned?, page?, limit? })`, `announcement(id)`, `paginate.announcements()` | Announcements up right now in the client's language, newest first (`pinned: true`: the banners, urgent first); 404 while `site.features.announcements` is false |
 | `form(id)`, `submitForm(id, { answers, version?, idempotencyKey? })` | A published form's questions; send answers (checkbox groups as arrays). Each call makes one key; retries reuse it |
+| `requestOptions()`, `submitRequest(input, { idempotencyKey? })` | Event requests without an account: what the form offers (`open`, `types`, `rooms`, `replyTime`, `notice`, `phone`, `timezone`; never cached), and asking for a new event or a change (`{ id }`). 404 while `site.features.requests` is false. See Event requests below |
 | `manageBooking(token)`, `cancelBooking(token)` | The booker's own booking from its `manageToken`, and cancelling it (or leaving a waitlist, or releasing a held spot); `can` says what is allowed. A waitlisted RSVP has `booking.position` (its place in line), an offered one `booking.holdUntil` |
 | `confirmBooking(token)` | Take a spot the waitlist offered (`can.confirm`): `confirmed`, or `pending` when RSVPs need approval. 410 once `holdUntil` passed. Core 0.3.40 or later |
 | `rescheduleAvailability(token, { from?, days?, minutes? })`, `rescheduleBooking(token, { start, minutes? })` | Open times for moving it (its own time counts as free), then the move |
@@ -149,7 +150,7 @@ await pending.catch(() => {});
 ```
 
 Requests that are safe to repeat (GET, PUT, DELETE, device registration, and
-POSTs with an Idempotency-Key: bookings and form responses) retry network
+POSTs with an Idempotency-Key: bookings, form responses and event requests) retry network
 failures, 5xx and 429 responses at most twice (three attempts total), with
 250/500ms backoff and at least the server's `Retry-After` delay (seconds or HTTP
 date). A wait that would outlast `timeoutMs` throws the 429 straight away, with
@@ -170,6 +171,52 @@ booking must be retried with its existing key. `AcmsError` exposes `status`,
 `aborted`, or `invalid_response`; non-JSON HTTP errors use `http_error`.
 Convenience lookups apply the timeout separately to each underlying request.
 
+## Event requests
+
+A site can take event requests from people
+without an account (`acms({ requests: true })`, so `site.features.requests`
+is true; staff answer them in Calendar → Requests). Someone asks for
+something new, or for a change to an event, and gives a name, an email and
+optionally a phone. Nothing goes on the calendar until staff approve it.
+
+```ts
+import type { RequestInput } from '@acms-subir/client';
+
+const options = await client.requestOptions();
+// { open, types: [{ id, label }], rooms: [{ slug, name, color }], replyTime: '3 days', notice, phone, timezone }
+if (!options.open) {
+  // say "We aren't taking requests here right now." and show options.phone; keep the screen itself reachable
+}
+const ask: RequestInput = {
+  kind: 'new', type: options.types[0]?.id, title: 'Guitar workshop',
+  // the site's wall clock (options.timezone), in the future; the end may be just HH:mm on the same day
+  start: '2026-11-07T18:00', end: '20:00',
+  repeat: 'weekly',                       // 'once' (default), 'weekly', or 'other' with repeatText
+  rooms: ['fellowship-hall'],             // slugs from options.rooms, or roomsUnsure: true
+  people: 12, message: 'We bring our own chairs.',
+  name: 'Example Guest', email: 'guest@example.com', phone: '555 0100',
+};
+const { id } = await client.submitRequest(ask, { idempotencyKey: crypto.randomUUID() });
+
+// a change to a public event: one date of it (YYYY-MM-DD, the site's day), or leave date out for every date
+await client.submitRequest({ kind: 'change', event: 'fall-fair', date: '2026-11-08', message: 'Could it start at 10?', name: 'Example Guest', email: 'guest@example.com' });
+```
+
+- Check whether a room looks free first with `roomFree({ room, start, end })`
+  (needs bookings on the site; the times there take a zone, so convert the
+  wall-clock times with `options.timezone`).
+- Keep one Idempotency-Key per request and reuse it for retries: a retry
+  answers the same `{ id }`, and the same key with other details is a 409
+  `changed`. Each call without `idempotencyKey` makes a new one.
+- The client's `locale` (or `input.locale`) goes in the body, so the emails
+  about the request speak the app's language.
+- A refusal is an `AcmsError` whose `code` says why: `closed` (409, requests
+  closed meanwhile), a field (400: `title`, `type`, `start`, `end`, `past`,
+  `far`, `repeat`, `room`, `people`, `event`, `date`, `what` (the change's
+  message), `name`, `email`, `phone`), `changed` (409), or `busy` / `full`
+  (429, with `retryAfter`). 10 requests a minute per address, plus the
+  site's daily cap.
+
 ## Push notifications
 
 Available when the site enables push (`acms({ mobile: { push: true } })`);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { Site, Theme, Page, Content, Post, ContentList, SearchResults, Links, Form, FormReceipt, FormResponseInput, ManagedBooking, RescheduleInput, ManageAvailabilityQuery, GuestCodeSent, GuestToken, GuestBookings, GuestBookingsQuery, GuestSignedOut, Events, Event, Calendars, Resources, Resource, Availability, BookingInput, BookingResult, RsvpStatus, Device, DeviceInput, DeviceUpdate, DeviceRegistration, DeviceRemoved, StaffLink, PushTopics, LiveStatus, Announcements, AnnouncementDetail, EventDetail, RoomFree } from './types.js';
+import type { Site, Theme, Page, Content, Post, ContentList, SearchResults, Links, Form, FormReceipt, FormResponseInput, ManagedBooking, RescheduleInput, ManageAvailabilityQuery, GuestCodeSent, GuestToken, GuestBookings, GuestBookingsQuery, GuestSignedOut, Events, Event, Calendars, Resources, Resource, Availability, BookingInput, BookingResult, RsvpStatus, Device, DeviceInput, DeviceUpdate, DeviceRegistration, DeviceRemoved, StaffLink, PushTopics, LiveStatus, Announcements, AnnouncementDetail, EventDetail, RoomFree, EventRequestOptions, RequestReceipt } from './types.js';
 export { AcmsError, isAcmsError } from './errors.js';
 export type * from './types.js';
 export * from './editor.js';
@@ -72,6 +72,44 @@ export interface RoomFreeOptions extends RequestOptions {
 export type BookOptions = BookingInput & RequestOptions & {
     idempotencyKey?: string;
 };
+/** Who's asking. `locale`: the language for the emails about it (default: the client's). */
+interface RequestAsker {
+    name: string;
+    email: string;
+    phone?: string;
+    locale?: string;
+}
+/** Ask for a new event. Times are the site's wall clock (`requestOptions().timezone`). */
+export interface NewEventRequest extends RequestAsker {
+    kind: 'new';
+    /** One of `requestOptions().types` (an `id`); required when the site lists any. */
+    type?: string;
+    title: string;
+    /** `YYYY-MM-DDTHH:mm`, in the future. */
+    start: string;
+    /** `YYYY-MM-DDTHH:mm`, or `HH:mm`: the start's day, or the next when it's before the start (20:00 → 01:00); within a day. */
+    end: string;
+    /** Default `once`; `other` needs `repeatText` ("every other Tuesday"). */
+    repeat?: 'once' | 'weekly' | 'other';
+    repeatText?: string;
+    /** Room slugs from `requestOptions().rooms`, or `roomsUnsure: true`. */
+    rooms?: string[];
+    roomsUnsure?: boolean;
+    people?: number | null;
+    /** Anything else they want staff to know. */
+    message?: string;
+}
+/** Ask for a change to a public event. */
+export interface ChangeRequest extends RequestAsker {
+    kind: 'change';
+    /** The event's slug. */
+    event: string;
+    /** One of its dates (`YYYY-MM-DD`, the site's day); leave it out for every date. */
+    date?: string;
+    /** What should change. */
+    message: string;
+}
+export type RequestInput = NewEventRequest | ChangeRequest;
 export interface ApiResponse<T> {
     version: 1;
     data: T;
@@ -214,6 +252,14 @@ export declare const endpoints: {
         readonly method: "GET";
         readonly path: "/announcements/{id}";
     };
+    readonly requestOptions: {
+        readonly method: "GET";
+        readonly path: "/requests/options";
+    };
+    readonly submitRequest: {
+        readonly method: "POST";
+        readonly path: "/requests";
+    };
     readonly manageBooking: {
         readonly method: "GET";
         readonly path: "/bookings/manage";
@@ -335,6 +381,20 @@ export interface AcmsClient {
     submitForm(id: string, input: FormResponseInput & {
         idempotencyKey?: string;
     }, o?: RequestOptions): Promise<FormReceipt>;
+    /**
+     * What the event request form offers (`site.features.requests`): `open` (false: say so, show `phone`, and keep
+     * the screen reachable), `types` and `rooms` to choose from, the site's `replyTime` and `notice` in the client's language,
+     * and its `timezone` (the times in a request are its wall clock). Never cached; 404 while the site has requests off.
+     */
+    requestOptions(o?: RequestOptions): Promise<EventRequestOptions>;
+    /**
+     * Ask for a new event or a change to one, without an account: `{ id }`. Retries reuse the same Idempotency-Key, so they
+     * never send twice; the same key with other details is a 409 `changed`. Refusals carry a `code` (`closed`, `title`,
+     * `start`, `email`, `busy`, …). Sends the client's `locale` (or `o.locale`), so the emails about it speak it.
+     */
+    submitRequest(input: RequestInput, o?: RequestOptions & {
+        idempotencyKey?: string;
+    }): Promise<RequestReceipt>;
     /** The booker's own booking, from its private token (`manageToken`). Never cached. Requires `site.features.bookingChanges`. */
     manageBooking(token: string, o?: RequestOptions): Promise<ManagedBooking>;
     /** Cancel it; for an RSVP on a waitlist, leave the line or release a held spot. */

package/dist/index.js

@@ -25,6 +25,8 @@ export const endpoints = {
     live: { method: 'GET', path: '/live' },
     // announcements (404 unless the site turns them on)
     announcements: { method: 'GET', path: '/announcements' }, announcement: { method: 'GET', path: '/announcements/{id}' },
+    // event requests without an account (404 unless the site turns them on): what the form offers (never cached), and sending one
+    requestOptions: { method: 'GET', path: '/requests/options' }, submitRequest: { method: 'POST', path: '/requests' },
     // the booker's own booking: its private token goes in the Booking-Token header
     manageBooking: { method: 'GET', path: '/bookings/manage' }, cancelBooking: { method: 'POST', path: '/bookings/manage/cancel' },
     // take a spot an RSVP's waitlist offered
@@ -36,8 +38,9 @@ export const endpoints = {
     guestBookings: { method: 'GET', path: '/guest/bookings' }, guestSignOut: { method: 'POST', path: '/guest/revoke' },
 };
 // site: its legal links; pushTopics: topic names; form: its questions;
-// submitForm: the receipt's thank-you (any site ignores it on that POST)
-const localized = new Set(['home', 'page', 'content', 'contentById', 'search', 'events', 'rsvpStatus', 'site', 'pushTopics', 'announcements', 'announcement', 'eventDetail', 'form', 'submitForm']);
+// submitForm: the receipt's thank-you (any site ignores it on that POST);
+// requestOptions: the kinds and the site's words
+const localized = new Set(['home', 'page', 'content', 'contentById', 'search', 'events', 'rsvpStatus', 'site', 'pushTopics', 'announcements', 'announcement', 'eventDetail', 'form', 'submitForm', 'requestOptions']);
 // localized later (site, pushTopics: core 0.3.32; form: with form
 // translations); older sites answer ?locale= with a 400, so ask them again without it
 const lateLocalized = new Set(['site', 'pushTopics', 'form']);
@@ -122,8 +125,8 @@ export function createClient(options) {
             opts.signal?.addEventListener('abort', abort, { once: true });
         const timer = setTimeout(() => controller.abort(new AcmsError(0, 'timeout', 'Request timed out.', undefined, undefined, key)), timeoutMs);
         const signal = controller.signal;
-        // availability, live status and RSVP seats are never served from the cache
-        const cacheable = endpoint.method === 'GET' && name !== 'availability' && name !== 'live' && name !== 'rsvpStatus' && name !== 'roomFree' && !extra.headers && cache;
+        // availability, live status, RSVP seats, free rooms and whether requests are open are never served from the cache
+        const cacheable = endpoint.method === 'GET' && name !== 'availability' && name !== 'live' && name !== 'rsvpStatus' && name !== 'roomFree' && name !== 'requestOptions' && !extra.headers && cache;
         // only replay what the server treats as repeatable: a lost reply to a code
         // exchange or a move must not run it twice
         const replayable = endpoint.method !== 'POST' || !!key || name === 'registerDevice';
@@ -331,6 +334,13 @@ export function createClient(options) {
             const { idempotencyKey, ...body } = input;
             return request('submitForm', o, {}, id, body, idempotencyKey ?? uuid());
         },
+        requestOptions: (o = {}) => request('requestOptions', o),
+        submitRequest: (input, o = {}) => {
+            const { idempotencyKey, signal } = o;
+            // the language rides in the body: the emails about it speak it
+            const locale = input.locale ?? o.locale ?? options.locale;
+            return request('submitRequest', { signal }, {}, undefined, locale === undefined ? input : { ...input, locale }, idempotencyKey ?? uuid());
+        },
         manageBooking: (token, o = {}) => request('manageBooking', o, {}, undefined, undefined, undefined, bookingAuth(token)),
         cancelBooking: (token, o = {}) => request('cancelBooking', o, {}, undefined, undefined, undefined, bookingAuth(token)),
         confirmBooking: (token, o = {}) => request('confirmBooking', o, {}, undefined, undefined, undefined, bookingAuth(token)),

package/dist/types.d.ts

@@ -37,6 +37,7 @@ export type Site = {
         "links": boolean;
         "live": boolean;
         "announcements": boolean;
+        "requests": boolean;
     };
     "legal": {
         "privacy": string | null;
@@ -1292,10 +1293,34 @@ export type LiveStatus = {
         "dock": boolean;
     };
 };
+export type EventRequestOptions = {
+    "open": boolean;
+    "types": Array<{
+        "id": string;
+        "label": string;
+    }>;
+    "rooms": Array<{
+        "slug": string;
+        "name": string;
+        "color": string;
+    }>;
+    "replyTime": string;
+    "notice": string;
+    "phone": string;
+    "timezone": string;
+    "events": Array<{
+        "slug": string;
+        "title": string;
+        "dates": Array<string>;
+    }>;
+};
+export type RequestReceipt = {
+    "id": string;
+};
 export type ApiErrorResponse = {
     "version": 1;
     "error": {
-        "code": "invalid_request" | "unauthorized" | "forbidden" | "not_found" | "method_not_allowed" | "conflict" | "duplicate" | "gone" | "payload_too_large" | "unsupported_media_type" | "rate_limited" | "upstream_error" | "internal_error";
+        "code": "invalid_request" | "unauthorized" | "forbidden" | "not_found" | "method_not_allowed" | "conflict" | "duplicate" | "gone" | "payload_too_large" | "unsupported_media_type" | "rate_limited" | "upstream_error" | "internal_error" | "closed" | "trap" | "busy" | "full" | "changed" | "title" | "type" | "start" | "end" | "past" | "far" | "repeat" | "room" | "people" | "event" | "date" | "what" | "name" | "email" | "phone";
         "message": string;
         "issues"?: Array<{
             "path": Array<string | number>;
@@ -2864,6 +2889,26 @@ export type FormResponseInput = {
     "version"?: string;
     "website"?: string;
 };
+export type RequestFields = {
+    "kind": "new" | "change";
+    "type"?: string;
+    "title"?: string;
+    "start"?: string;
+    "end"?: string;
+    "repeat"?: "once" | "weekly" | "other";
+    "repeatText"?: string;
+    "rooms"?: Array<string>;
+    "roomsUnsure"?: boolean;
+    "people"?: (number) | (null);
+    "event"?: string;
+    "date"?: string;
+    "message"?: string;
+    "name": string;
+    "email": string;
+    "phone"?: string;
+    "locale"?: string;
+    "website"?: string;
+};
 export type RescheduleInput = {
     "start": string;
     "minutes"?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/client",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Typed, dependency-free client for the ACMS public mobile API.",
   "type": "module",
   "license": "MIT",