@acms-subir/client 0.1.12 → 0.1.14

package/README.md

@@ -25,7 +25,10 @@ const english = client.withLocale('en');
 hosting prefix. All methods return **unwrapped `data`**; `openapi()` returns the
 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.
+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.
 
 | Method | Options / behavior |
 | --- | --- |
@@ -44,12 +47,13 @@ the cache and transport configuration with the original client.
 | `availability(opts)` | Required `resource`, `link`; optional `from`, `days`, `minutes` |
 | `book(opts)` | Resource booking or RSVP input, optional `idempotencyKey` |
 | `openapi()` | Raw OpenAPI document |
-| `registerDevice({ token, platform, locale?, topics? })` | Register or refresh an Expo push token (call on every app start); `{ created, device }` |
-| `updateDevice(token, { topics?, locale? })` | Change a device's topics or language |
+| `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) |
 | `pushTopics()` | Topics to offer as notification toggles, named in the client's language (built-in and the site's own, `kind: 'site'`) |
 | `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 |
 | `rescheduleAvailability(token, { from?, days?, minutes? })`, `rescheduleBooking(token, { start, minutes? })` | Open times for moving it (its own time counts as free), then the move |

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 } 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, 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';
@@ -44,6 +44,11 @@ export interface SearchOptions extends RequestOptions {
     /** Matches per group, 1–20; default 5. */
     limit?: number;
 }
+export interface AnnouncementOptions extends ListOptions {
+    kind?: 'event' | 'registration' | 'help' | 'info' | 'urgent';
+    /** Only the banners (pinned), urgent first. */
+    pinned?: boolean;
+}
 export interface AvailabilityOptions extends RequestOptions {
     resource: string;
     link: string;
@@ -168,6 +173,14 @@ export declare const endpoints: {
         readonly method: "GET";
         readonly path: "/live";
     };
+    readonly announcements: {
+        readonly method: "GET";
+        readonly path: "/announcements";
+    };
+    readonly announcement: {
+        readonly method: "GET";
+        readonly path: "/announcements/{id}";
+    };
     readonly manageBooking: {
         readonly method: "GET";
         readonly path: "/bookings/manage";
@@ -246,6 +259,10 @@ export interface AcmsClient {
      * clock, even if later requests fail. Requires `site.features.live`.
      */
     live(o?: RequestOptions): Promise<LiveStatus>;
+    /** Announcements up right now, newest first (`pinned: true`: only the banners, urgent first). Requires `site.features.announcements`. */
+    announcements(o?: AnnouncementOptions): Promise<Announcements>;
+    /** One announcement that is up; 404 once it came down. */
+    announcement(id: string, o?: RequestOptions): Promise<AnnouncementDetail>;
     /** A published form's questions. 410 when it stopped accepting responses. Requires `site.features.forms`. */
     form(id: string, o?: RequestOptions): Promise<Form>;
     /** Send answers (checkbox groups as arrays). Retries reuse the same Idempotency-Key, so they never duplicate. */
@@ -278,5 +295,6 @@ export interface AcmsClient {
         pages(o?: ListOptions): AsyncGenerator<ContentList['items'][number]>;
         events(o?: EventOptions): AsyncGenerator<Events['occurrences'][number]>;
         resources(o?: ListOptions): AsyncGenerator<Resource>;
+        announcements(o?: AnnouncementOptions): AsyncGenerator<Announcements['announcements'][number]>;
     };
 }

package/dist/index.js

@@ -17,6 +17,8 @@ export const endpoints = {
     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)
     live: { method: 'GET', path: '/live' },
+    // announcements (404 unless the site turns them on)
+    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' },
     rescheduleAvailability: { method: 'GET', path: '/bookings/manage/availability' }, rescheduleBooking: { method: 'POST', path: '/bookings/manage/reschedule' },
@@ -26,7 +28,9 @@ 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']);
+const localized = new Set(['home', 'page', 'content', 'contentById', 'search', 'events', '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() {
     if (globalThis.crypto?.randomUUID)
         return globalThis.crypto.randomUUID();
@@ -98,7 +102,7 @@ export function createClient(options) {
             if (v !== undefined)
                 url.searchParams.set(k, String(v));
         const locale = opts.locale ?? options.locale;
-        if (localized.has(name) && locale !== undefined)
+        if (localized.has(name) && locale !== undefined && !extra.noLocale)
             url.searchParams.set('locale', locale);
         const controller = new AbortController();
         const abort = () => controller.abort(new AcmsError(0, 'aborted', 'Request aborted.', undefined, undefined, key));
@@ -178,6 +182,9 @@ export function createClient(options) {
                     }
                     throw new AcmsError(res.status, res.ok ? 'invalid_response' : 'http_error', `HTTP ${res.status}: expected a JSON response.`, retryAfter, undefined, key);
                 }
+                // a site older than the client: unlocalized words beat no site info at all
+                if (res.status === 400 && lateLocalized.has(name) && url.searchParams.has('locale') && /locale/i.test(JSON.stringify(json?.error ?? '')))
+                    return await request(name, opts, query, param, payload, key, { ...extra, noLocale: true });
                 if (!res.ok)
                     throw new AcmsError(res.status, json?.error?.code ?? 'http_error', json?.error?.message ?? `HTTP ${res.status}`, retryAfter, json?.error?.issues, key);
                 if (name !== 'openapi' && (json?.version !== 1 || !Object.prototype.hasOwnProperty.call(json, 'data')))
@@ -225,19 +232,22 @@ export function createClient(options) {
     const pages = (o = {}) => content({ ...o, kind: 'page' });
     const events = (o = {}) => request('events', o, { ...paging(o), from: o.from, to: o.to, calendar: o.calendar, tag: o.tag, excludeTag: o.excludeTag, q: o.q });
     const resources = (o = {}) => request('resources', o, paging(o));
+    const announcements = (o = {}) => request('announcements', o, { ...paging(o), kind: o.kind, pinned: o.pinned ? 'true' : undefined });
     const paginate = {
         content: (o = {}) => iterate(content, 'items', o),
         posts: (o = {}) => iterate(posts, 'items', o),
         pages: (o = {}) => iterate(pages, 'items', o),
         events: (o = {}) => iterate(events, 'occurrences', o),
         resources: (o = {}) => iterate(resources, 'resources', o),
+        announcements: (o = {}) => iterate(announcements, 'announcements', o),
     };
     return {
         site: (o = {}) => request('site', o),
         theme: (o = {}) => request('theme', o),
         home: (o = {}) => request('home', o),
         page: (slug, o = {}) => request('page', o, {}, slug),
-        content, posts, pages, events, resources, paginate,
+        content, posts, pages, events, resources, announcements, paginate,
+        announcement: (id, o = {}) => request('announcement', o, {}, id),
         async search(q, o = {}) {
             const query = q.trim();
             // blank input (an emptied search box) needs no round trip

package/dist/types.d.ts

@@ -35,6 +35,7 @@ export type Site = {
         "forms": boolean;
         "links": boolean;
         "live": boolean;
+        "announcements": boolean;
     };
     "legal": {
         "privacy": string | null;
@@ -787,6 +788,7 @@ export type Device = {
     "platform": "ios" | "android";
     "locale": string | null;
     "topics": Array<string>;
+    "channels": Array<string>;
     "registeredAt": string;
     "lastSeenAt": string;
 };
@@ -797,6 +799,7 @@ export type DeviceRegistration = {
         "platform": "ios" | "android";
         "locale": string | null;
         "topics": Array<string>;
+        "channels": Array<string>;
         "registeredAt": string;
         "lastSeenAt": string;
     };
@@ -814,6 +817,69 @@ export type PushTopics = {
         "description"?: string;
     }>;
 };
+export type Announcement = {
+    "id": string;
+    "kind": "event" | "registration" | "help" | "info" | "urgent";
+    "kindLabel": string;
+    "title": string;
+    "message": string;
+    "details": string;
+    "button": ({
+        "label": string;
+        "url": string;
+    }) | (null);
+    "url": string | null;
+    "pinned": boolean;
+    "urgent": boolean;
+    "publishedAt": string;
+    "showUntil": (string) | (null);
+    "translated": boolean;
+};
+export type Announcements = {
+    "locale": string | null;
+    "announcements": Array<{
+        "id": string;
+        "kind": "event" | "registration" | "help" | "info" | "urgent";
+        "kindLabel": string;
+        "title": string;
+        "message": string;
+        "details": string;
+        "button": ({
+            "label": string;
+            "url": string;
+        }) | (null);
+        "url": string | null;
+        "pinned": boolean;
+        "urgent": boolean;
+        "publishedAt": string;
+        "showUntil": (string) | (null);
+        "translated": boolean;
+    }>;
+    "pagination": {
+        "page": number;
+        "limit": number;
+        "nextPage": (number) | (null);
+    };
+};
+export type AnnouncementDetail = {
+    "id": string;
+    "kind": "event" | "registration" | "help" | "info" | "urgent";
+    "kindLabel": string;
+    "title": string;
+    "message": string;
+    "details": string;
+    "button": ({
+        "label": string;
+        "url": string;
+    }) | (null);
+    "url": string | null;
+    "pinned": boolean;
+    "urgent": boolean;
+    "publishedAt": string;
+    "showUntil": (string) | (null);
+    "translated": boolean;
+    "locale": string | null;
+};
 export type LiveSnapshot = {
     "status": "live" | "upcoming" | "offline" | "unknown";
     "source": "automatic" | "manual";
@@ -1881,10 +1947,12 @@ export type DeviceInput = {
     "platform": "ios" | "android";
     "locale"?: string;
     "topics"?: Array<string>;
+    "channels"?: Array<string>;
 };
 export type DeviceUpdate = {
     "locale"?: string;
     "topics"?: Array<string>;
+    "channels"?: Array<string>;
 };
 export type EditorCreateInput = ({
     "kind": "post";

package/package.json

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