@acms-subir/client 0.1.18 → 0.1.20

package/README.md

@@ -49,18 +49,21 @@ language. Update the 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` |
-| `rsvpStatus(slug, { start })` | One event date's RSVP status: `open` or `reason` (`disabled`, `ended`, `closed` past the event's deadline, `cancelled`, `full`), `closesAt` (when RSVPs to the date close, or `null`: open until it ends), 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 |
+| `rsvpStatus(slug, { start })` | One event date's RSVP status: `open` or `reason` (`disabled`, `ended`, `closed` past the event's deadline, `cancelled`, `full`), `closesAt` (when RSVPs to the date close, or `null`: open until it ends), live `going`/`left` (held waitlist spots count as taken), `maxSeats` for one RSVP right now, `autoConfirm`, `waitlist` (`enabled`: a full date takes places in line; `waiting` people for `seats` seats; `maxSeats` for one place in line), 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; `waitlist: true` joins a full date's waitlist, status `waitlisted`), 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 |
-| `unregisterDevice(token)` | Opt out (idempotent) |
+| `unregisterDevice(token)` | Opt out (idempotent); also unlinks a staff test phone |
 | `pushTopics()` | Topics to offer as notification toggles, named in the client's language (built-in and the site's own, `kind: 'site'`) |
+| `linkStaffPhone(token, code)` | Staff only: link this registered device with the 6-digit code from the admin's Test phones, so it gets that person's test notifications; `{ linked, staff: { name } }`. A wrong, used or expired code is a 400, too many tries a 429; never retried |
+| `unlinkStaffPhone(token)` | Unlink it (idempotent); `{ linked: false, staff: null }` |
 | `links()` | The links page: profile, socials and visible blocks (`link`, `email`, `phone`, `contact`, `heading`, `text`, `spacer`, `live`, `embed`) |
 | `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 |
-| `manageBooking(token)`, `cancelBooking(token)` | The booker's own booking from its `manageToken`, and cancelling it; `can` says what is allowed |
+| `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 |
 | `bookingIcs(token)` | The booking as an iCalendar file (string) |
 | `requestGuestCode(email)`, `guestSignIn({ email, code, deviceName? })`, `guestBookings(guestToken, { when? })`, `guestSignOut(guestToken)` | Guest sign-in for "My bookings" |
@@ -128,6 +131,14 @@ if (status.open) {
   // 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);
+} else if (status.reason === 'full' && status.waitlist.enabled) {
+  // a place in line (status 'waitlisted', no seats); when a spot opens the site emails them and holds it
+  // for 24 hours: then manageBooking shows status 'offered' and holdUntil, and confirmBooking(token) takes it
+  const result = await client.book({
+    event: date.event.slug, start: date.start, seats: 2, name: 'Example Guest', email: 'guest@example.com', waitlist: true,
+    ...(status.form ? { formVersion: status.form.version } : {}), idempotencyKey: crypto.randomUUID(),
+  });
+  console.log(result.booking.status);
 }
 
 const controller = new AbortController();
@@ -142,7 +153,7 @@ 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
 `retryAfter`. One-shot writes (guest code requests and sign-in, cancelling and
-moving a booking, guest sign-out) are never repeated automatically: on a
+moving a booking, confirming a held spot, guest sign-out) are never repeated automatically: on a
 network error, check the state before trying again. Booking retries always
 reuse the same serialized body and UUID. By default each `book()` call creates
 a key using `crypto.randomUUID`, falling back to a Math.random UUID v4 where
@@ -172,6 +183,18 @@ await client.updateDevice(token, { topics: ['events'] });
 await client.unregisterDevice(token);
 ```
 
+Staff can link their own phone for test notifications ("Send test to my
+phone" in the admin): the admin's Test phones panel shows a one-time 6-digit
+code (10 minutes, single use) that the app sends with this phone's token.
+`device.staff` (from `registerDevice` and `updateDevice`) and the link
+response name who it's linked to (their name only), or `null`. Test pushes
+carry `data.test: true`.
+
+```ts
+const { staff } = await client.linkStaffPhone(token, '123456');  // { name: 'Ana López' }; 400 for a wrong, used or expired code
+await client.unlinkStaffPhone(token);                             // turning notifications off unlinks it too
+```
+
 ## Live video
 
 `site.features.live` is true while the site's live video (Integrations → Live

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, PushTopics, LiveStatus, Announcements, AnnouncementDetail, EventDetail } 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 } from './types.js';
 export { AcmsError, isAcmsError } from './errors.js';
 export type * from './types.js';
 export * from './editor.js';
@@ -169,6 +169,14 @@ export declare const endpoints: {
         readonly method: "GET";
         readonly path: "/push/topics";
     };
+    readonly linkStaffPhone: {
+        readonly method: "POST";
+        readonly path: "/devices/{token}/staff-link";
+    };
+    readonly unlinkStaffPhone: {
+        readonly method: "DELETE";
+        readonly path: "/devices/{token}/staff-link";
+    };
     readonly links: {
         readonly method: "GET";
         readonly path: "/links";
@@ -201,6 +209,10 @@ export declare const endpoints: {
         readonly method: "POST";
         readonly path: "/bookings/manage/cancel";
     };
+    readonly confirmBooking: {
+        readonly method: "POST";
+        readonly path: "/bookings/manage/confirm";
+    };
     readonly rescheduleAvailability: {
         readonly method: "GET";
         readonly path: "/bookings/manage/availability";
@@ -275,6 +287,14 @@ export interface AcmsClient {
     unregisterDevice(token: string, o?: RequestOptions): Promise<DeviceRemoved>;
     /** Topics the app can offer as notification toggles. */
     pushTopics(o?: RequestOptions): Promise<PushTopics>;
+    /**
+     * Staff only: link this registered device to the staff member whose one-time code (Admin → Test phones) it sends,
+     * so it gets their test notifications. `{ linked: true, staff: { name } }`. A wrong, used or expired code is a 400;
+     * too many tries a 429 (never retried). Sites without it (or with push off) answer 404.
+     */
+    linkStaffPhone(token: string, code: string, o?: RequestOptions): Promise<StaffLink>;
+    /** Unlink it (idempotent). Turning notifications off (`unregisterDevice`) unlinks it too. */
+    unlinkStaffPhone(token: string, o?: RequestOptions): Promise<StaffLink>;
     /** The links page: profile, socials and visible blocks. Requires `site.features.links`. */
     links(o?: RequestOptions): Promise<Links>;
     /**
@@ -295,7 +315,13 @@ export interface AcmsClient {
     }, o?: RequestOptions): Promise<FormReceipt>;
     /** 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. */
     cancelBooking(token: string, o?: RequestOptions): Promise<ManagedBooking>;
+    /**
+     * Take a spot an RSVP's waitlist offered (`booking.status` `offered`, `can.confirm`): confirmed, or
+     * pending when the event approves RSVPs. A spot past its `holdUntil` was released (410). Requires core 0.3.40.
+     */
+    confirmBooking(token: string, o?: RequestOptions): Promise<ManagedBooking>;
     /** Open times for moving the booking (its own time counts as free). */
     rescheduleAvailability(token: string, q?: ManageAvailabilityQuery, o?: RequestOptions): Promise<Availability>;
     rescheduleBooking(token: string, input: RescheduleInput, o?: RequestOptions): Promise<ManagedBooking>;

package/dist/index.js

@@ -15,6 +15,8 @@ export const endpoints = {
     // push notifications (only when the site enables push; 404 otherwise)
     registerDevice: { method: 'POST', path: '/devices' }, updateDevice: { method: 'PUT', path: '/devices/{token}' },
     unregisterDevice: { method: 'DELETE', path: '/devices/{token}' }, pushTopics: { method: 'GET', path: '/push/topics' },
+    // a staff member's own test phone (a one-time code from the admin's Test phones)
+    linkStaffPhone: { method: 'POST', path: '/devices/{token}/staff-link' }, unlinkStaffPhone: { method: 'DELETE', path: '/devices/{token}/staff-link' },
     // links page and forms (owner switches in Admin → Mobile app)
     links: { method: 'GET', path: '/links' }, form: { method: 'GET', path: '/forms/{id}' }, submitForm: { method: 'POST', path: '/forms/{id}/responses' },
     // live video status (404 while the site's live video is off)
@@ -23,6 +25,8 @@ export const endpoints = {
     announcements: { method: 'GET', path: '/announcements' }, announcement: { method: 'GET', path: '/announcements/{id}' },
     // 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
+    confirmBooking: { method: 'POST', path: '/bookings/manage/confirm' },
     rescheduleAvailability: { method: 'GET', path: '/bookings/manage/availability' }, rescheduleBooking: { method: 'POST', path: '/bookings/manage/reschedule' },
     bookingIcs: { method: 'GET', path: '/bookings/manage/ics' },
     // guest sign-in for "My bookings" (emailed code → guest token)
@@ -311,6 +315,8 @@ export function createClient(options) {
         updateDevice: (token, input, o = {}) => request('updateDevice', o, {}, token, input),
         unregisterDevice: (token, o = {}) => request('unregisterDevice', o, {}, token),
         pushTopics: (o = {}) => request('pushTopics', o),
+        linkStaffPhone: (token, code, o = {}) => request('linkStaffPhone', o, {}, token, { code }),
+        unlinkStaffPhone: (token, o = {}) => request('unlinkStaffPhone', o, {}, token),
         links: (o = {}) => request('links', o),
         live: (o = {}) => request('live', o),
         form: (id, o = {}) => request('form', o, {}, id),
@@ -320,6 +326,7 @@ export function createClient(options) {
         },
         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)),
         rescheduleAvailability: (token, q = {}, o = {}) => request('rescheduleAvailability', o, { from: q.from, days: q.days, minutes: q.minutes }, undefined, undefined, undefined, bookingAuth(token)),
         rescheduleBooking: (token, input, o = {}) => request('rescheduleBooking', o, {}, undefined, input, undefined, bookingAuth(token)),
         bookingIcs: (token, o = {}) => request('bookingIcs', o, {}, undefined, undefined, undefined, { ...bookingAuth(token), text: true }),

package/dist/types.d.ts

@@ -223,6 +223,7 @@ export type Event = {
         "maxSeats": number;
         "closesAt": string | null;
         "closeBefore": number;
+        "waitlist": boolean;
         "form"?: {
             "title": string;
             "intro": string;
@@ -315,6 +316,7 @@ export type Events = {
                 "maxSeats": number;
                 "closesAt": string | null;
                 "closeBefore": number;
+                "waitlist": boolean;
                 "form"?: {
                     "title": string;
                     "intro": string;
@@ -402,6 +404,7 @@ export type EventDetail = {
             "maxSeats": number;
             "closesAt": string | null;
             "closeBefore": number;
+            "waitlist": boolean;
             "form"?: {
                 "title": string;
                 "intro": string;
@@ -542,6 +545,7 @@ export type SearchResults = {
                 "maxSeats": number;
                 "closesAt": string | null;
                 "closeBefore": number;
+                "waitlist": boolean;
                 "form"?: {
                     "title": string;
                     "intro": string;
@@ -709,6 +713,12 @@ export type RsvpStatus = {
     "maxSeats": number;
     "autoConfirm": boolean;
     "closesAt": (string) | (null);
+    "waitlist": {
+        "enabled": boolean;
+        "waiting": number;
+        "seats": number;
+        "maxSeats": number;
+    };
     "form": ({
         "version": string;
         "title": string;
@@ -733,7 +743,7 @@ export type ManagedBooking = {
         "id": string;
         "reference": string;
         "kind": "booking" | "rsvp";
-        "status": "pending" | "confirmed" | "declined" | "cancelled";
+        "status": "pending" | "confirmed" | "declined" | "cancelled" | "waitlisted" | "offered" | "expired";
         "start": string;
         "end": string;
         "allDay": boolean;
@@ -746,6 +756,8 @@ export type ManagedBooking = {
             [key: string]: string;
         };
         "createdAt": string;
+        "position": (number) | (null);
+        "holdUntil": (string) | (null);
     };
     "title": string;
     "location": string;
@@ -768,6 +780,7 @@ export type ManagedBooking = {
     "can": {
         "cancel": boolean;
         "reschedule": boolean;
+        "confirm": boolean;
         "cutoffHours": number;
         "closed": boolean;
     };
@@ -794,7 +807,7 @@ export type GuestBookings = {
         "id": string;
         "reference": string;
         "kind": "booking" | "rsvp";
-        "status": "pending" | "confirmed" | "declined" | "cancelled";
+        "status": "pending" | "confirmed" | "declined" | "cancelled" | "waitlisted" | "offered" | "expired";
         "start": string;
         "end": string;
         "seats": number;
@@ -804,6 +817,7 @@ export type GuestBookings = {
         "can": {
             "cancel": boolean;
             "reschedule": boolean;
+            "confirm": boolean;
             "cutoffHours": number;
             "closed": boolean;
         };
@@ -881,7 +895,7 @@ export type BookingResult = {
     "booking": {
         "id": string;
         "kind": "booking" | "block" | "rsvp";
-        "status": "pending" | "confirmed" | "declined" | "cancelled";
+        "status": "pending" | "confirmed" | "declined" | "cancelled" | "waitlisted" | "offered" | "expired";
         "name": string;
         "email": string;
         "phone": string;
@@ -929,6 +943,9 @@ export type Device = {
     "channels": Array<string>;
     "registeredAt": string;
     "lastSeenAt": string;
+    "staff": ({
+        "name": string;
+    }) | (null);
 };
 export type DeviceRegistration = {
     "created": boolean;
@@ -940,12 +957,21 @@ export type DeviceRegistration = {
         "channels": Array<string>;
         "registeredAt": string;
         "lastSeenAt": string;
+        "staff": ({
+            "name": string;
+        }) | (null);
     };
 };
 export type DeviceRemoved = {
     "token": string;
     "deleted": true;
 };
+export type StaffLink = {
+    "linked": boolean;
+    "staff": ({
+        "name": string;
+    }) | (null);
+};
 export type PushTopics = {
     "locale": string | null;
     "topics": Array<{
@@ -1249,6 +1275,7 @@ export type EditorDocument = {
             "closesAt": string | null;
             "closeBefore": number;
             "notifyStaff": boolean;
+            "waitlist": boolean;
             "form"?: {
                 "title": string;
                 "intro": string;
@@ -1442,7 +1469,7 @@ export type EditorMediaList = {
 export type EditorBooking = {
     "id": string;
     "kind": "booking" | "block" | "rsvp";
-    "status": "pending" | "confirmed" | "declined" | "cancelled";
+    "status": "pending" | "confirmed" | "declined" | "cancelled" | "waitlisted" | "offered" | "expired";
     "name": string;
     "email": string;
     "phone": string;
@@ -1489,7 +1516,7 @@ export type EditorBookingList = {
     "items": Array<{
         "id": string;
         "kind": "booking" | "block" | "rsvp";
-        "status": "pending" | "confirmed" | "declined" | "cancelled";
+        "status": "pending" | "confirmed" | "declined" | "cancelled" | "waitlisted" | "offered" | "expired";
         "name": string;
         "email": string;
         "phone": string;
@@ -2084,6 +2111,7 @@ export type BookingInput = ({
     "event": string;
     "seats"?: number;
     "formVersion"?: string;
+    "waitlist"?: boolean;
 });
 export type DeviceInput = {
     "token": string;
@@ -2182,6 +2210,7 @@ export type EditorSaveInput = {
             "closesAt"?: (string) | (null);
             "closeBefore"?: number;
             "notifyStaff"?: boolean;
+            "waitlist"?: boolean;
             "form"?: {
                 "title"?: string;
                 "intro"?: string;
@@ -2221,7 +2250,7 @@ export type EditorMediaQuery = {
     "limit"?: number;
 };
 export type EditorBookingsQuery = {
-    "status"?: "active" | "pending" | "confirmed" | "declined" | "cancelled" | "all";
+    "status"?: "active" | "pending" | "confirmed" | "waitlist" | "waitlisted" | "offered" | "expired" | "declined" | "cancelled" | "all";
     "from"?: (undefined) | (string);
     "page"?: number;
     "limit"?: number;

package/package.json

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