@acms-subir/client 0.1.8 → 0.1.10

package/README.md

@@ -49,6 +49,7 @@ the cache and transport configuration with the original client.
 | `unregisterDevice(token)` | Opt out (idempotent) |
 | `pushTopics()` | Topics to offer as notification toggles |
 | `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 |
 | `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 |
@@ -140,12 +141,34 @@ await client.updateDevice(token, { topics: ['events'] });
 await client.unregisterDevice(token);
 ```
 
+## Live video
+
+`site.features.live` is true while the site's live video (Integrations → Live
+video) isn't off. `live()` returns the same snapshot the website shows:
+`status` (`live`, `upcoming` or `offline` for the "Watch our channel" fallback),
+`title`, `watchUrl`, an absolute `thumbUrl` (empty when there's none),
+`startedAt`, `expiresAt` and optional `channel` and `viewers`. Times are Unix
+milliseconds on the **server's** clock: keep `serverNow - Date.now()` as an
+offset, and stop treating a snapshot as current once `expiresAt` (when nonzero)
+passes on that clock, even if later requests fail. `display` carries the
+owner's choices (`style`: `poster`, `split` or `row`; `bar`, `header`, `dock`)
+so an app can follow the website. Poll about every 30 seconds while the app is
+in the foreground; `@acms-subir/native`'s `useLive()` does all of this. The
+"we're live" notification is the push topic `live`.
+
+```ts
+const { snapshot, serverNow } = await client.live();
+const offset = serverNow - Date.now();
+const current = snapshot && (!snapshot.expiresAt || snapshot.expiresAt > Date.now() + offset) ? snapshot : null;
+if (current?.status === 'live') console.log(`Live: ${current.title} → ${current.watchUrl}`);
+```
+
 ## Cache and headers
 
 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, booking results and errors are never cached.
+to disable it. Availability, live 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 } 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 } from './types.js';
 export { AcmsError, isAcmsError } from './errors.js';
 export type * from './types.js';
 export * from './editor.js';
@@ -164,6 +164,10 @@ export declare const endpoints: {
         readonly method: "POST";
         readonly path: "/forms/{id}/responses";
     };
+    readonly live: {
+        readonly method: "GET";
+        readonly path: "/live";
+    };
     readonly manageBooking: {
         readonly method: "GET";
         readonly path: "/bookings/manage";
@@ -236,6 +240,12 @@ export interface AcmsClient {
     pushTopics(o?: RequestOptions): Promise<PushTopics>;
     /** The links page: profile, socials and visible blocks. Requires `site.features.links`. */
     links(o?: RequestOptions): Promise<Links>;
+    /**
+     * The current broadcast (`snapshot`, or null), the server's clock (`serverNow`, ms) and the owner's
+     * display choices. Never cached. A live snapshot stops counting once `expiresAt` passes on the server's
+     * clock, even if later requests fail. Requires `site.features.live`.
+     */
+    live(o?: RequestOptions): Promise<LiveStatus>;
     /** 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. */

package/dist/index.js

@@ -15,6 +15,8 @@ export const endpoints = {
     unregisterDevice: { method: 'DELETE', path: '/devices/{token}' }, pushTopics: { method: 'GET', path: '/push/topics' },
     // 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)
+    live: { method: 'GET', path: '/live' },
     // 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' },
@@ -105,7 +107,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;
-        const cacheable = endpoint.method === 'GET' && name !== 'availability' && !extra.headers && cache;
+        // availability and live status are never served from the cache
+        const cacheable = endpoint.method === 'GET' && name !== 'availability' && name !== 'live' && !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';
@@ -274,6 +277,7 @@ export function createClient(options) {
         unregisterDevice: (token, o = {}) => request('unregisterDevice', o, {}, token),
         pushTopics: (o = {}) => request('pushTopics', o),
         links: (o = {}) => request('links', o),
+        live: (o = {}) => request('live', o),
         form: (id, o = {}) => request('form', o, {}, id),
         submitForm: (id, input, o = {}) => {
             const { idempotencyKey, ...body } = input;

package/dist/types.d.ts

@@ -25,6 +25,7 @@ export type Site = {
             "key": string;
             "name": string;
             "url": string;
+            "redirectFrom": Array<string>;
         }>;
         "calendar": boolean;
         "bookings": boolean;
@@ -33,6 +34,7 @@ export type Site = {
         "guestSignIn": boolean;
         "forms": boolean;
         "links": boolean;
+        "live": boolean;
     };
     "apiVersion": 1;
 };
@@ -49,6 +51,7 @@ export type Theme = {
             "accent": string;
             "panel": string;
             "soft": string;
+            "live": string;
         };
         "dark": {
             "bg": string;
@@ -58,6 +61,7 @@ export type Theme = {
             "accent": string;
             "panel": string;
             "soft": string;
+            "live": string;
         };
     };
     "fonts": {
@@ -804,6 +808,45 @@ export type PushTopics = {
         "kind": "general" | "collection" | "calendar";
     }>;
 };
+export type LiveSnapshot = {
+    "status": "live" | "upcoming" | "offline" | "unknown";
+    "source": "automatic" | "manual";
+    "provider": "youtube" | "twitch" | "facebook" | "other";
+    "id": string;
+    "title": string;
+    "watchUrl": string;
+    "embedId": string;
+    "startedAt": number;
+    "checkedAt": number;
+    "expiresAt": number;
+    "channel"?: string;
+    "viewers"?: number;
+    "thumbUrl": string;
+};
+export type LiveStatus = {
+    "snapshot": ({
+        "status": "live" | "upcoming" | "offline" | "unknown";
+        "source": "automatic" | "manual";
+        "provider": "youtube" | "twitch" | "facebook" | "other";
+        "id": string;
+        "title": string;
+        "watchUrl": string;
+        "embedId": string;
+        "startedAt": number;
+        "checkedAt": number;
+        "expiresAt": number;
+        "channel"?: string;
+        "viewers"?: number;
+        "thumbUrl": string;
+    }) | (null);
+    "serverNow": number;
+    "display": {
+        "style": "poster" | "split" | "row";
+        "bar": boolean;
+        "header": boolean;
+        "dock": boolean;
+    };
+};
 export type ApiErrorResponse = {
     "version": 1;
     "error": {
@@ -2312,3 +2355,4 @@ 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 LiveDisplay = LiveStatus["display"];

package/package.json

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