@acms-subir/client 0.1.14 → 0.1.16

package/README.md

@@ -27,8 +27,11 @@ raw document. Every method accepts `locale` and `signal` in its options object.
 Locale is sent only for routes that support translations. `withLocale` shares
 the cache and transport configuration with the original client. `site()` and
 `pushTopics()` take a language since core 0.3.32; an older site rejects it, so
-the client asks once more without it and gets the main language. Update the
-site before shipping an app build with a newer client.
+the client asks once more without it and gets the main language. `book()`
+sends the client's `locale` in its body, so the booking's emails (and the links
+in them) speak the app's language; a site before core 0.3.38 refuses that field,
+so the client books once more without it, with the same key, in the site's main
+language. Update the site before shipping an app build with a newer client.
 
 | Method | Options / behavior |
 | --- | --- |
@@ -45,7 +48,8 @@ site before shipping an app build with a newer client.
 | `calendars()` | Public calendars |
 | `resources(opts)`, `resource(slug, opts)` | Public resources; slug lookup scans list pages |
 | `availability(opts)` | Required `resource`, `link`; optional `from`, `days`, `minutes` |
-| `book(opts)` | Resource booking or RSVP input, optional `idempotencyKey` |
+| `rsvpStatus(slug, { start })` | One event date's RSVP status: `open` or `reason` (`disabled`, `ended`, `cancelled`, `full`), live `going`/`left`, `maxSeats` for one RSVP right now, `autoConfirm`, and `form` (questions and `version`, or `null`). `start` is the occurrence's start exactly as `events()` returns it (a UTC ISO string such as `2026-10-05T14:00:00.000Z`). Never cached |
+| `book(opts)` | Resource booking or RSVP input (`RsvpInput` for an RSVP), optional `idempotencyKey`; sends the client's `locale` (or `opts.locale`) for its emails |
 | `openapi()` | Raw OpenAPI document |
 | `registerDevice({ token, platform, locale?, topics?, channels? })` | Register or refresh an Expo push token (call on every app start); `{ created, device }`. `channels`: Android channels the app created (e.g. `['urgent']`) |
 | `updateDevice(token, { topics?, locale?, channels? })` | Change a device's topics, language or channels |
@@ -87,6 +91,8 @@ server results or provide snapshot consistency; deduplicate IDs in your app.
 ## Bookings, errors and cancellation
 
 ```ts
+import type { RsvpInput } from '@acms-subir/client';
+
 // Persist a UUID v4 with this booking intent before submitting; reuse it until
 // the outcome is known. Use your platform's secure UUID/storage facilities.
 const idempotencyKey = crypto.randomUUID();
@@ -103,6 +109,25 @@ try {
   }
 }
 
+// RSVP to one date of an event (needs only the calendar: site.features.rsvp)
+const { occurrences } = await client.events({ q: 'supper' });
+const date = occurrences[0];
+const status = await client.rsvpStatus(date.event.slug, { start: date.start });
+if (status.open) {
+  const rsvp: RsvpInput = {
+    event: date.event.slug, start: date.start, seats: 2, name: 'Example Guest', email: 'guest@example.com',
+    // field id → answer; checkbox groups send a list
+    answers: { meal: 'Vegetarian', help: ['Setup', 'Music'] },
+    // required when the event asks questions: a changed form answers 409, so read the status again
+    ...(status.form ? { formVersion: status.form.version } : {}),
+  };
+  const result = await client.book({ ...rsvp, idempotencyKey: crypto.randomUUID() });
+  // pending when the organiser approves RSVPs; status.form?.confirmation is the thank-you text.
+  // result.manageToken changes or cancels it later (manageBooking, cancelBooking), like the email's link:
+  // keep it in secure storage only.
+  console.log(result.booking.status);
+}
+
 const controller = new AbortController();
 const pending = client.home({ signal: controller.signal });
 controller.abort();
@@ -172,7 +197,7 @@ if (current?.status === 'live') console.log(`Live: ${current.title} → ${curren
 ETag revalidation defaults to an in-memory URL-keyed cache. Each read contacts
 the server with `If-None-Match`; a 304 reuses the saved data. This is not an
 offline fallback. Treat returned cached objects as immutable. Use `cache: false`
-to disable it. Availability, live status, booking results and errors are never cached.
+to disable it. Availability, live status, RSVP status, booking results and errors are never cached.
 Responses without an ETag or with `no-store` invalidate an older entry.
 
 ```ts

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, Device, DeviceInput, DeviceUpdate, DeviceRegistration, DeviceRemoved, PushTopics, LiveStatus, Announcements, AnnouncementDetail } 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, PushTopics, LiveStatus, Announcements, AnnouncementDetail } from './types.js';
 export { AcmsError, isAcmsError } from './errors.js';
 export type * from './types.js';
 export * from './editor.js';
@@ -56,6 +56,10 @@ export interface AvailabilityOptions extends RequestOptions {
     days?: number;
     minutes?: number;
 }
+/** `start`: the occurrence's start exactly as `events()` returns it, a UTC ISO string such as `'2026-10-05T14:00:00.000Z'`. */
+export interface RsvpStatusOptions extends RequestOptions {
+    start: string;
+}
 export type BookOptions = BookingInput & RequestOptions & {
     idempotencyKey?: string;
 };
@@ -125,6 +129,10 @@ export declare const endpoints: {
         readonly method: "GET";
         readonly path: "/calendars";
     };
+    readonly rsvpStatus: {
+        readonly method: "GET";
+        readonly path: "/events/{slug}/rsvp";
+    };
     readonly resources: {
         readonly method: "GET";
         readonly path: "/resources";
@@ -241,6 +249,13 @@ export interface AcmsClient {
     resources(o?: ListOptions): Promise<Resources>;
     resource(slug: string, o?: RequestOptions): Promise<Resource>;
     availability(o: AvailabilityOptions): Promise<Availability>;
+    /**
+     * One date's RSVP status: `open` (or `reason`: disabled, ended, cancelled, full), live `going`/`left`,
+     * `maxSeats` for one RSVP right now, and `form` (questions and `version`, or null). Never cached.
+     * RSVP with `book({ event, start, seats, name, email, answers, formVersion: form.version })`.
+     */
+    rsvpStatus(slug: string, o: RsvpStatusOptions): Promise<RsvpStatus>;
+    /** A room booking or an RSVP. Sends the client's `locale` (or `o.locale`), so its emails and links speak it. */
     book(o: BookOptions): Promise<BookingResult>;
     openapi(o?: RequestOptions): Promise<OpenApiDocument>;
     /** Register or refresh this device's Expo push token. Call on every app start. Requires push on the site. */

package/dist/index.js

@@ -8,6 +8,8 @@ export const endpoints = {
     content: { method: 'GET', path: '/content' }, contentById: { method: 'GET', path: '/content/{id}' },
     search: { method: 'GET', path: '/search' },
     events: { method: 'GET', path: '/events' }, calendars: { method: 'GET', path: '/calendars' },
+    // an event date's RSVP status: live seats and questions (never cached); RSVP with book()
+    rsvpStatus: { method: 'GET', path: '/events/{slug}/rsvp' },
     resources: { method: 'GET', path: '/resources' }, availability: { method: 'GET', path: '/availability' },
     book: { method: 'POST', path: '/bookings' }, openapi: { method: 'GET', path: '/openapi.json' },
     // push notifications (only when the site enables push; 404 otherwise)
@@ -28,7 +30,7 @@ export const endpoints = {
     guestBookings: { method: 'GET', path: '/guest/bookings' }, guestSignOut: { method: 'POST', path: '/guest/revoke' },
 };
 // site: its legal links; pushTopics: topic names
-const localized = new Set(['home', 'page', 'content', 'contentById', 'search', 'events', 'site', 'pushTopics', 'announcements', 'announcement']);
+const localized = new Set(['home', 'page', 'content', 'contentById', 'search', 'events', 'rsvpStatus', 'site', 'pushTopics', 'announcements', 'announcement']);
 // localized since core 0.3.32; older sites answer ?locale= with a 400, so ask them again without it
 const lateLocalized = new Set(['site', 'pushTopics']);
 function uuid() {
@@ -112,8 +114,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 and live status are never served from the cache
-        const cacheable = endpoint.method === 'GET' && name !== 'availability' && name !== 'live' && !extra.headers && cache;
+        // availability, live status and RSVP seats are never served from the cache
+        const cacheable = endpoint.method === 'GET' && name !== 'availability' && name !== 'live' && name !== 'rsvpStatus' && !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';
@@ -277,10 +279,23 @@ export function createClient(options) {
         },
         calendars: (o = {}) => request('calendars', o),
         availability: (o) => request('availability', o, { resource: o.resource, link: o.link, from: o.from, days: o.days, minutes: o.minutes }),
-        book: (o) => {
-            const { locale, signal, idempotencyKey, ...body } = o;
+        rsvpStatus: (slug, o) => request('rsvpStatus', o, { start: o.start }, slug),
+        async book(o) {
+            const { locale = options.locale, signal, idempotencyKey, ...body } = o;
             const key = idempotencyKey ?? defaultHeaders.get('Idempotency-Key') ?? uuid();
-            return request('book', { locale, signal }, {}, undefined, body, key);
+            // the client's language rides in the body: the booking's emails and links speak it
+            if (locale === undefined)
+                return request('book', { signal }, {}, undefined, body, key);
+            try {
+                return await request('book', { signal }, {}, undefined, { ...body, locale }, key);
+            }
+            catch (error) {
+                // sites before core 0.3.38 refuse the field (and one the site doesn't have): book without it, in
+                // the site's main language. A refused request doesn't use up the key.
+                if (!(error instanceof AcmsError) || error.status !== 400 || !/locale/i.test(JSON.stringify([error.message, error.issues ?? []])))
+                    throw error;
+                return request('book', { signal }, {}, undefined, body, key);
+            }
         },
         openapi: (o = {}) => request('openapi', o),
         registerDevice: (input, o = {}) => request('registerDevice', o, {}, undefined, input),

package/dist/types.d.ts

@@ -29,6 +29,7 @@ export type Site = {
         }>;
         "calendar": boolean;
         "bookings": boolean;
+        "rsvp": boolean;
         "search": boolean;
         "bookingChanges": boolean;
         "guestSignIn": boolean;
@@ -250,6 +251,9 @@ export type Event = {
         "name": string;
         "color": string;
     }>;
+    "notify": {
+        "changes": Array<string>;
+    };
 };
 export type Events = {
     "locale": string | null;
@@ -337,6 +341,9 @@ export type Events = {
                 "name": string;
                 "color": string;
             }>;
+            "notify": {
+                "changes": Array<string>;
+            };
         };
     }>;
 };
@@ -473,6 +480,9 @@ export type SearchResults = {
                 "name": string;
                 "color": string;
             }>;
+            "notify": {
+                "changes": Array<string>;
+            };
         };
     }>;
     "more": {
@@ -591,6 +601,40 @@ export type FormReceipt = {
     "received": true;
     "confirmation": string;
 };
+export type RsvpStatus = {
+    "event": {
+        "id": string;
+        "slug": string;
+        "title": string;
+    };
+    "start": string;
+    "end": string;
+    "open": boolean;
+    "reason": ("disabled" | "ended" | "cancelled" | "full") | (null);
+    "going": number;
+    "left": (number) | (null);
+    "capacity": number;
+    "maxSeats": number;
+    "autoConfirm": boolean;
+    "form": ({
+        "version": string;
+        "title": string;
+        "intro": string;
+        "submitLabel": string;
+        "confirmation": string;
+        "fields": Array<{
+            "id": string;
+            "type": "text" | "textarea" | "email" | "phone" | "number" | "select" | "checkbox" | "date" | "radio" | "checkboxes" | "url" | "consent" | "heading";
+            "label": string;
+            "required": boolean;
+            "help": string;
+            "options": Array<string>;
+            "placeholder": string;
+            "width": "full" | "half";
+            "allowOther": boolean;
+        }>;
+    }) | (null);
+};
 export type ManagedBooking = {
     "booking": {
         "id": string;
@@ -634,6 +678,7 @@ export type ManagedBooking = {
         "cutoffHours": number;
         "closed": boolean;
     };
+    "confirmation": string | null;
 };
 export type GuestCodeSent = {
     "sent": true;
@@ -774,7 +819,7 @@ export type BookingResult = {
                 [key: string]: string;
             };
         };
-        "source": "web" | "admin" | "api" | "agent";
+        "source": "web" | "app" | "admin" | "api" | "agent";
         "start": string;
         "end": string;
         "resourceId": string | null;
@@ -1332,7 +1377,7 @@ export type EditorBooking = {
             [key: string]: string;
         };
     };
-    "source": "web" | "admin" | "api" | "agent";
+    "source": "web" | "app" | "admin" | "api" | "agent";
     "notes": string;
     "start": string;
     "end": string;
@@ -1379,7 +1424,7 @@ export type EditorBookingList = {
                 [key: string]: string;
             };
         };
-        "source": "web" | "admin" | "api" | "agent";
+        "source": "web" | "app" | "admin" | "api" | "agent";
         "notes": string;
         "start": string;
         "end": string;
@@ -1924,22 +1969,24 @@ export type BookingInput = ({
     "name": string;
     "email": string;
     "phone"?: string;
+    "answers"?: {
+        [key: string]: (string) | (Array<string>);
+    };
+    "locale"?: string;
     "resource": string;
     "link": string;
     "minutes"?: number;
-    "answers"?: {
-        [key: string]: string;
-    };
 }) | ({
     "start": string;
     "name": string;
     "email": string;
     "phone"?: string;
-    "event": string;
-    "seats"?: number;
     "answers"?: {
-        [key: string]: string;
+        [key: string]: (string) | (Array<string>);
     };
+    "locale"?: string;
+    "event": string;
+    "seats"?: number;
     "formVersion"?: string;
 });
 export type DeviceInput = {
@@ -2429,4 +2476,8 @@ export type SearchEventHit = SearchResults["events"][number];
 export type LinkItem = Links["items"][number];
 export type FormField = Form["fields"][number];
 export type GuestBooking = GuestBookings["items"][number];
+export type RsvpInput = Extract<BookingInput, {
+    "event": string;
+}>;
+export type RsvpForm = NonNullable<RsvpStatus["form"]>;
 export type LiveDisplay = LiveStatus["display"];

package/package.json

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