@acms-subir/core 0.3.28 → 0.3.29

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @acms-subir/core
 
+## 0.3.29
+
+### Patch Changes
+
+- da0382f: Apps can show live video. `GET /api/v1/live` returns the snapshot the website's live placements use: `snapshot` (or `null`), `serverNow`, and the owner's "How it looks" choices as `display` (`style`, `bar`, `header`, `dock`), so an app can follow the website's live bar and header switches. The thumbnail URL is absolute. The route is `no-store` with no ETag, so a shared cache never serves a stale "live", and it has the same CORS and read limit as the other v1 routes. While live video is off it answers 404, and `/api/v1/site` reports `features.live: false`. `/api/v1/theme` adds `live` to both palettes: the website's own `--live` color for that scheme, readable on its background. The OpenAPI document describes `/live` with a `LiveStatus` schema.
+
+  "We're live" push notifications, with push on. **Mobile app → Automatic notifications** has a new rule, **We go live**, off by default. When live video detects a broadcast, phones on the new `live` topic get "We're live" in their language (English, Spanish, French, German or Portuguese) with the broadcast title, and the tap opens the stream. Each broadcast is announced once, keyed `live:<provider>:<id>` in the push ledger, so a stream that drops and comes back, or a server restart, never sends it twice. A broadcast first seen more than 20 minutes after it started isn't announced, and neither is a second one within 3 hours (a stream restarted as a new broadcast). On **Integrations → Live video**, a manual link gets a **Notify app users** checkbox. It sends once per link, and a YouTube video that was already announced isn't announced again.
+
+  `/api/v1/push/topics` lists `live` ("Live video") while live video isn't off, and devices may keep it while it's off. The topic only reaches devices that choose it. Turning the rule on, or upgrading, never subscribes devices that registered before, as App Store guidelines 4.5.3 and 4.5.4 and Mexico's data protection law expect. Apps should offer it with a one-time prompt. `acms mobile doctor` counts a Live video section as native with `@acms-subir/native` 0.1.5 or later.
+
 ## 0.3.28
 
 ### Patch Changes

package/cli/mobile-doctor.mjs

@@ -298,7 +298,10 @@ async function doctorApp(app, flags, ctx) {
     const all = [...texts.values()].join('\n');
     const fallbackOff = !deps['react-native-webview'] || /webSectionFallback=\{\s*false\s*\}/.test(all);
     const partlyOff = /webFallback=\{\s*false\s*\}/.test(all);
-    const web = [...used.keys()].filter((t) => !registry.has(t) && !library[t]).sort();
+    // built-in sections the native package renders itself (not in the section library), by the version that added them
+    const nativeAt = (min) => { const v = versions.native?.match(/^(\d+)\.(\d+)\.(\d+)/)?.slice(1).map(Number); const m = min.split('.').map(Number); return !!v && (v[0] - m[0] || v[1] - m[1] || v[2] - m[2]) >= 0; };
+    const builtIn = new Set(nativeAt('0.1.5') ? ['live'] : []);
+    const web = [...used.keys()].filter((t) => !registry.has(t) && !library[t] && !builtIn.has(t)).sort();
     const where = (t) => `${t} (${[...new Set(used.get(t))].join(', ')})`;
     const checked = pages.filter((p) => p.r.status === 200).map((p) => p.slug);
     if (!web.length) c.pass('sections', 'Section coverage', `All ${used.size} section types on ${checked.join(', ')} render natively.`);

package/docs/live-video.md

@@ -68,6 +68,16 @@ All placements share the same status. Changing credentials or live mode takes ef
 
 Player mode loads the official platform iframe only after a visitor clicks. Autoplay is off. The external watch link stays available when playback is blocked. Twitch requires HTTPS, the embedding hostname in `parent`, and at least 400×300 pixels; narrow slots use a watch link. YouTube embeds preserve an origin referrer. The compact links card never embeds a player. Cross-domain embedding of an entire ACMS site may require additional Twitch parent domains and is not configured automatically. See [Twitch embeds](https://dev.twitch.tv/docs/embed/video-and-clips/) and [YouTube players](https://developers.google.com/youtube/iframe_api_reference).
 
+## In the app
+
+Apps built with `@acms-subir/native` show the same status (see [mobile](mobile.md) and [the API](../../../docs/mobile-api-v1.md#live-video)):
+
+- **Status.** `GET /api/v1/live` returns the public snapshot with an absolute thumbnail URL, the server's clock and the owner's **How it looks** choices (`style`, `bar`, `header`, `dock`). It is never cached and answers 404 while live video is **Off**; `site.features.live` tells apps whether to ask. App requests read the stored snapshot, so more phones don't use more YouTube or Twitch quota.
+- **Hook and card.** `useLive()` checks every 30 seconds while the app is in the foreground and again when it comes back. It drops an expired "live" on time even without a connection, using the same rule as the website. `<LiveCard>` renders the poster, split or row layout (the owner's card style unless the app picks one) with the theme's live color (`/api/v1/theme` → `colors.light.live` / `colors.dark.live`). Taps open the broadcast in YouTube, Twitch or the browser. A **Live video** section on a page renders natively; there is no in-app player.
+- **Signals.** The website's **live bar**, **header marker** and **floating card** switches arrive as `display.bar`, `display.header` and `display.dock`, so an app's own bar or tab badge can follow them.
+- **"We're live" notifications** (with push on, `acms({ mobile: { push: true } })`). In **Mobile app → Automatic notifications**, turn on **We go live**. When live video detects a broadcast, phones that turned on the **Live video** topic get "We're live" (in their language) with the broadcast title. Tapping it opens the stream. It is sent once per broadcast, never again when the stream flickers or the server restarts. It is skipped if the broadcast was first seen more than 20 minutes after it started (for example, a connection turned on mid-service), and if another live notice went out in the last 3 hours (a stream restarted as a new broadcast). A **manual** link notifies only when you tick **Notify app users** while saving it, once per link. A YouTube video already announced isn't announced again.
+- **Consent.** The `live` topic reaches only phones that chose it. Turning the feature on never subscribes people who installed the app earlier. The app should ask them once, which App Store rules (4.5.3, 4.5.4) and Mexico's data protection law expect.
+
 ## Manual, off, fallback and outages
 
 **Manual** accepts an HTTPS watch URL and a bounded expiry of up to 12 hours (UI default: four hours). It overrides automatic detection until it expires; automatic detection then resumes. **End manual link now** resumes automatic immediately. **Off** hides every placement; turn off individual provider connections too if you want to stop their background checks.

package/docs/mobile.md

@@ -113,7 +113,7 @@ Read the app's `AGENTS.md` too: it holds the same rules, next to the code.
 
 | Hook | For |
 | --- | --- |
-| `useSite()` | name, menu, languages, features (`calendar`, `bookings`, `blog`, `search`, `bookingChanges`, `guestSignIn`, `forms`, `links`) |
+| `useSite()` | name, menu, languages, features (`calendar`, `bookings`, `blog`, `search`, `bookingChanges`, `guestSignIn`, `forms`, `links`, `live`) |
 | `usePage(slug)` | a published page: `mode` (`sections`/`content`), `sections`, `body.html`; 404 when missing |
 | `usePosts({ collection, limit, q })` / `usePost(slug)` | posts (infinite: `items`, `fetchNextPage`); `q` gives ranked search matches |
 | `useSearch(text, { types, collection, limit })` | site-wide search: `data.posts`, `data.pages`, `data.events` (each with `snippet.text` + `snippet.highlights`), `data.more`; debounced, blank text fetches nothing |
@@ -122,13 +122,14 @@ Read the app's `AGENTS.md` too: it holds the same rules, next to the code.
 | `useManagedBooking(token)` / `useCancelBooking` / `useRescheduleBooking` / `useRescheduleAvailability` | the booker's own booking (from `book()`'s `manageToken`): `can.cancel`, `can.reschedule`, `can.closed` (change cutoff passed: show "Contact us") |
 | `useGuest()` / `useMyBookings({ when })` | guest sign-in with an emailed code, then every booking made with that email; check `features.guestSignIn` |
 | `useLinks()` / `useForm(id)` / `useSubmitForm(id)` | the links page; published forms and sending answers; check `features.links` / `features.forms` |
+| `useLive()` | live video: `snapshot`, `status` (`live`/`upcoming`/`offline`), `isLive`, localized `view` text, the owner's `display` choices (`style`, `bar`, `header`, `dock`). Polls every 30 s only in the foreground, rechecks on resume, drops an expired "live" even offline; idle while `features.live` is false. Render `<LiveCard>` / `<LiveTag>` |
 | `useResources()` / `useAvailability({ resource, link })` / `useBooking()` | bookings |
 | `useLocale()`, `useTheme()`, `useLayout()`, `useRefresh()`, `useOpenLink()` | language, tokens, layout, refresh, links |
 | `usePushRegistration({ topics })` / `usePushTopics()` / `useNotificationTaps()` | push notifications (see Push notifications) |
 | `useAcms()` | the typed client (e.g. `calendars()`) for your own `useQuery` |
 
 Components: `<Sections>`, `<RichText html>`, `<EventDate start end allDay timezone>`,
-`<Button>`, `<ErrorView error retry>`, `<GenericSection>`. Full reference:
+`<Button>`, `<ErrorView error retry>`, `<GenericSection>`, `<LiveCard layout>`, `<LiveTag>`. Full reference:
 `@acms-subir/native` README; API contract: the site's `docs/mobile-api-v1.md`
 and `<site>/api/v1/openapi.json`.
 
@@ -269,8 +270,8 @@ keyed by `locale`.
 ## Push notifications
 
 Optional; the owner sends them from **Admin → Mobile app** (manual messages
-plus automatic ones: new post, new event, "starting soon"). The app only
-registers and chooses topics; it never sends.
+plus automatic ones: new post, new event, "starting soon", "we're live"). The
+app only registers and chooses topics; it never sends.
 
 1. Site: `acms({ mobile: { push: true } })` in `astro.config.mjs` (off by
    default; `/api/v1/devices` and `/api/v1/push/topics` 404 until then).
@@ -291,6 +292,26 @@ reader's language when a translation exists. Test on a real device (simulators
 get no push); doctor checks the plugin, the project id and that the site has
 push on.
 
+**Consent (App Store, US and Mexico).** Apple's guidelines (4.5.3, 4.5.4,
+5.1.2(i)) don't allow unsolicited push messages or requiring notifications, and
+they need in-app consent and an in-app way to opt out of anything promotional.
+Mexico's data law (LFPDPPP) also asks for free, specific, informed consent, so
+a pre-ticked choice doesn't count. So:
+
+- A new topic (for example `live`) never reaches existing devices by itself.
+  To offer it to people who installed the app before it existed, show a
+  one-time in-app prompt ("Get notified when we're live?") and call
+  `setTopics([...topics, 'live'])` only on yes. Remember that you asked
+  (AsyncStorage), and don't ask again.
+- Starting topics for new installs (`usePushRegistration({ topics })`) are
+  fine once the person has allowed notifications from your explained prompt.
+  List the topics they'll get on that screen.
+- Keep a Notifications screen with a switch per topic (`usePushTopics()`) and
+  an "Off" (`unregister()`). The app must work fully with notifications off.
+- Describe push notifications in the app's privacy policy (aviso de privacidad
+  in Mexico) and App Privacy answers. The site stores only the Expo token,
+  platform, language and topics, with no name or email.
+
 ## Editor apps (staff sign-in)
 
 A second, separate Expo app for the people who run the site: owners and

package/integration.mjs

@@ -714,6 +714,8 @@ export default function acms(options = {}) {
     ['/api/v1/content', 'api/v1/content/index.ts'],
     ['/api/v1/content/[id]', 'api/v1/content/[id].ts'],
     ['/api/v1/links', 'api/v1/links.ts'],
+    // live video status (404 while Integrations → Live video is off)
+    ['/api/v1/live', 'api/v1/live.ts'],
     ['/api/v1/forms/[id]', 'api/v1/forms/[id]/index.ts'],
     ['/api/v1/forms/[id]/responses', 'api/v1/forms/[id]/responses.ts'],
   ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.28",
+  "version": "0.3.29",
   "publishConfig": {
     "access": "public"
   },

package/src/components/LiveManager.tsx

@@ -18,6 +18,8 @@ interface ConnForm { clientId: string; clientSecret: string; channelInput: strin
 interface ConfigForm {
   mode: Mode; primary: Provider; fallbackUrl: string; showUpcoming: boolean;
   watchUrl: string; title: string; hours: string; display: Display; dirty: boolean;
+  /** "Notify app users" for this save only; never remembered */
+  notify: boolean;
 }
 type Display = LiveConfig['display'];
 
@@ -79,6 +81,7 @@ const toConfigForm = (c: LiveConfig, now: number): ConfigForm => ({
   hours: c.mode === 'manual' && c.manual.until > now ? 'keep' : '4',
   display: c.display,
   dirty: false,
+  notify: false,
 });
 
 function rel(ts: number, now: number) {
@@ -256,13 +259,15 @@ export default function LiveManager() {
     }
     await run('config', async () => {
       try {
-        const s = await api<LiveAdminState>({ action: 'saveConfig', config: configBody(f) });
+        const notify = f.mode === 'manual' && f.notify && state.push;
+        const s = await api<LiveAdminState & { notified?: { recipients: number } | null; notifyError?: string }>({ action: 'saveConfig', config: configBody(f), notify });
         adopt(s, { config: true });
+        const told = !notify ? '' : s.notifyError ? '' : s.notified ? ` Notified ${s.notified.recipients.toLocaleString()} app user${s.notified.recipients === 1 ? '' : 's'}.` : ' App users were already notified about this link.';
         setCfgMsg({
-          ok: s.config.mode === 'manual' ? `Saved. Your link shows until ${fullTime(s.config.manual.until)}.`
+          ok: s.config.mode === 'manual' ? `Saved. Your link shows until ${fullTime(s.config.manual.until)}.${told}`
             : s.config.mode === 'automatic' ? 'Saved. Your site will show broadcasts from your connected channels.'
             : 'Saved. Live video is hidden on your site.',
-          err: '',
+          err: s.notifyError ?? '',
         });
       } catch (err) {
         setCfgMsg({ ok: '', err: errText(err) });
@@ -815,6 +820,12 @@ export default function LiveManager() {
                   </select>
                 </label>
               </div>
+              {state.push && (
+                <label className="check-row">
+                  <input type="checkbox" checked={cfg.notify} onChange={(e) => setCfgField('notify', e.target.checked)} />
+                  <span>Notify app users <span className="hint">(sends “We’re live” once to phones that turned on Live video notifications in your app)</span></span>
+                </label>
+              )}
             </fieldset>
           )}
 

package/src/components/MobileApp.tsx

@@ -35,7 +35,7 @@ function ago(ms: number, now: number) {
     : d.toLocaleDateString([], { month: 'short', day: 'numeric', ...(d.getFullYear() !== new Date(now).getFullYear() ? { year: 'numeric' } : {}) });
 }
 
-const SOURCE: Record<PushNotification['source'], string> = { manual: 'Sent by', post: 'New post', event: 'New event', soon: 'Starting soon' };
+const SOURCE: Record<PushNotification['source'], string> = { manual: 'Sent by', post: 'New post', event: 'New event', soon: 'Starting soon', live: 'We’re live' };
 
 export default function MobileApp() {
   const [state, setState] = useState<AdminPushState | null>(null);
@@ -279,7 +279,7 @@ function Automatic({ state, setState }: { state: AdminPushState; setState: (s: A
     <section className="card card-pad" aria-labelledby="ma-auto-h">
       <header className="ma-head">
         <h2 id="ma-auto-h">Automatic notifications</h2>
-        <p>Sent once, when something goes live for the first time. Edits never notify again.</p>
+        <p>Sent once, when something is published for the first time or a broadcast starts. Edits never notify again.</p>
       </header>
       <div className="ma-rules">
         <div className="ma-rule">
@@ -309,6 +309,15 @@ function Automatic({ state, setState }: { state: AdminPushState; setState: (s: A
             </div>
           </>
         )}
+        <div className="ma-rule">
+          <div className="ma-rule-head"><b>We go live</b><small>“We’re live” and the broadcast title, opens the stream. Once per broadcast, not when it was found more than 20 minutes after it started, and at most once every 3 hours.</small></div>
+          <div className="ma-choices">
+            <label className="ma-check"><input type="checkbox" checked={auto.live.enabled} onChange={() => setAuto({ ...auto, live: { enabled: !auto.live.enabled } })} /><span>When live video detects a broadcast</span></label>
+          </div>
+          <p className="hint">{state.liveMode === 'off'
+            ? <>Live video is off. Turn it on in <a href="/admin/live">Integrations → Live video</a> first.</>
+            : 'Only phones that turned on Live video notifications in the app get it. Manual links notify only when you tick “Notify app users” on the link.'}</p>
+        </div>
       </div>
       {msg.err && <p className="flash error" role="alert">{msg.err}</p>}
       <div className="form-actions">

package/src/lib/live/service.ts

@@ -2,6 +2,7 @@ import { ApiError } from '../api';
 import type { ContentRepository } from '../repo/types';
 import { encrypt, decrypt, encryptionReady, hash, randomToken } from './crypto';
 import { channels, detect, exchangeGoogleCode, ProviderError, revoke, twitchLogin } from './providers';
+import { PUSH } from '../push/config';
 import { LiveConfig, type Connection, type Credentials, type Provider, type LiveAdminState, type LiveSnapshot, type PublicLiveSnapshot } from './types';
 
 export function canonicalOrigin(siteUrl: string, requestUrl: URL) {
@@ -67,7 +68,7 @@ export async function adminState(repo:ContentRepository,url:URL,locals?:unknown)
     let authorized=false;try{const s=decrypt<Credentials>(c.encrypted,c.provider,locals);authorized=c.provider==='twitch'?!!s.clientSecret:!!s.refreshToken;}catch{/* needs reconnect */}
     const {encrypted,lease,leaseUntil,snapshot,upcoming,...visible}=c;
     return {...visible,hasSecret:!!encrypted,authorized,broadcastStatus:snapshot&&snapshot.expiresAt>Date.now()?snapshot.status:'unknown'};
-  }),callbackUrl:`${origin}/api/live/oauth/youtube/callback`,encryptionReady:encryptionReady(locals),scheduler:{lastAt,healthy:lastAt>Date.now()-180_000},snapshot:effectiveSnapshot(settings.live,connections)};
+  }),callbackUrl:`${origin}/api/live/oauth/youtube/callback`,encryptionReady:encryptionReady(locals),scheduler:{lastAt,healthy:lastAt>Date.now()-180_000},snapshot:effectiveSnapshot(settings.live,connections),push:PUSH.enabled};
 }
 const providerError=(error:unknown)=>error instanceof ProviderError?error:error instanceof ApiError?new ProviderError('auth',error.message):new ProviderError('unavailable','The provider returned an unexpected response. Try the connection test again.');
 export async function syncConnection(repo:ContentRepository,provider:Provider,locals?:unknown,force=false):Promise<boolean> {

package/src/lib/live/types.ts

@@ -48,5 +48,7 @@ export interface LiveAdminState {
   config: LiveConfig; connections: PublicConnection[]; callbackUrl: string;
   encryptionReady: boolean; scheduler: { lastAt: number; healthy: boolean };
   snapshot: LiveSnapshot | null;
+  /** push notifications are on (acms({ mobile: { push } })): manual links can notify app users */
+  push: boolean;
 }
 export const emptySnapshot = (provider: Provider, now: number): LiveSnapshot => ({ status: 'offline', source: 'automatic', provider, id: '', title: '', watchUrl: '', embedId: '', startedAt: 0, checkedAt: now, expiresAt: now + 120_000 });

package/src/lib/mobile/live.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { ApiError } from '../api';
+import type { ContentRepository } from '../repo/types';
+import { siteOrigin } from '../seo';
+import { effectiveSnapshot, publicSnapshot } from '../live/service';
+import { queryParams } from './http';
+
+// Live video for apps: the website's public snapshot (/api/live/status) with
+// an absolute thumbnail URL, plus the owner's "How it looks" choices so apps
+// can follow them. Served no-store: a cached "live" would outlive the stream.
+
+export async function getLive(repo: ContentRepository, url: URL) {
+  z.object({}).strict().parse(queryParams(url));
+  const [settings, connections] = await Promise.all([repo.getSettings(), repo.live.list()]);
+  const config = settings.live;
+  if (config.mode === 'off') throw new ApiError(404, 'This feature is disabled.');
+  const origin = siteOrigin(settings, url);
+  const s = publicSnapshot(effectiveSnapshot(config, connections), config);
+  const { style, bar, header, dock } = config.display;
+  return {
+    snapshot: s && { ...s, thumbUrl: s.thumbUrl && new URL(s.thumbUrl, origin).href },
+    serverNow: Date.now(),
+    display: { style, bar, header, dock },
+  };
+}

package/src/lib/mobile/openapi.ts

@@ -50,6 +50,7 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     ['/availability', 'Current availability; requires bookings', availabilityQuery, ref('Availability'), false],
     ['/push/topics', 'Topics an app can offer as notification toggles; requires push', empty, ref('PushTopics')],
     ['/links', 'The links page: profile, socials and visible blocks in order (owner switch: links)', empty, ref('Links')],
+    ['/live', 'Live video status: the current broadcast (or null), server time and the owner’s display choices; never cached; 404 while live video is off', empty, ref('LiveStatus'), false],
     ['/forms/{id}', 'A published form’s questions; 410 when it stopped accepting responses (owner switch: forms)', empty, ref('Form')],
     ['/openapi.json', 'OpenAPI 3.1 document (no v1 envelope)', empty, { type: 'object', required: ['openapi', 'info', 'paths', 'components'] }],
   ];

package/src/lib/mobile/schemas.ts

@@ -4,11 +4,11 @@ import { CalEvent, Booking, Calendar, BookingQuestion, LinksAvatarShape, LinksAv
 const str = z.string(), bool = z.boolean(), strings = z.array(str);
 const date = str.datetime(), locale = str.nullable();
 export const Pagination = z.object({ page: z.number().int(), limit: z.number().int(), nextPage: z.number().int().nullable() });
-const Palette = z.object({ bg: str, ink: str, muted: str, line: str, accent: str, panel: str, soft: str });
+const Palette = z.object({ bg: str, ink: str, muted: str, line: str, accent: str, panel: str, soft: str, live: str });
 export const Site = z.object({
   name: str, description: str, logo: str, logoDark: str, icon: str, menu: z.array(z.object({ label: str, href: str })),
   languages: z.object({ default: locale, locales: z.array(z.object({ code: str, name: str })) }),
-  features: z.object({ blog: z.array(z.object({ key: str, name: str, url: str, redirectFrom: strings })), calendar: bool, bookings: bool, search: bool, bookingChanges: bool, guestSignIn: bool, forms: bool, links: bool }), apiVersion: z.literal(1),
+  features: z.object({ blog: z.array(z.object({ key: str, name: str, url: str, redirectFrom: strings })), calendar: bool, bookings: bool, search: bool, bookingChanges: bool, guestSignIn: bool, forms: bool, links: bool, live: bool }), apiVersion: z.literal(1),
 });
 export const Theme = z.object({
   id: str, name: str, scheme: z.enum(['auto', 'light', 'dark']), colors: z.object({ light: Palette, dark: Palette }),
@@ -105,6 +105,17 @@ export const Device = z.object({
 export const DeviceRegistration = z.object({ created: bool, device: Device });
 export const DeviceRemoved = z.object({ token: str, deleted: z.literal(true) });
 export const PushTopics = z.object({ topics: z.array(z.object({ id: str, label: str, kind: z.enum(['general', 'collection', 'calendar']) })) });
+// times are Unix milliseconds (as on the website); compare them with serverNow, not the device clock
+const ms = z.number().int();
+export const LiveSnapshot = z.object({
+  status: z.enum(['live', 'upcoming', 'offline', 'unknown']), source: z.enum(['automatic', 'manual']), provider: z.enum(['youtube', 'twitch', 'facebook', 'other']),
+  id: str, title: str, watchUrl: str, embedId: str, startedAt: ms, checkedAt: ms, expiresAt: ms,
+  channel: str.optional(), viewers: z.number().int().optional(), thumbUrl: str,
+});
+export const LiveStatus = z.object({
+  snapshot: LiveSnapshot.nullable(), serverNow: ms,
+  display: z.object({ style: z.enum(['poster', 'split', 'row']), bar: bool, header: bool, dock: bool }),
+});
 export const Error = z.object({ version: z.literal(1), error: z.object({
   code: z.enum(['invalid_request', 'unauthorized', 'forbidden', 'not_found', 'method_not_allowed', 'conflict', 'gone', 'payload_too_large', 'unsupported_media_type', 'rate_limited', 'upstream_error', 'internal_error']),
   message: str, issues: z.array(z.object({ path: z.array(z.union([str, z.number()])), message: str })).optional(),

package/src/lib/mobile/site.ts

@@ -6,7 +6,7 @@ import { CALENDAR, bookingsEnabled } from '../calendar/config';
 import { SEARCH } from '../search-config';
 import { siteOrigin } from '../seo';
 import { resolveDesign } from '../theme';
-import { darkPalette } from '../themeTokens';
+import { darkPalette, liveColor } from '../themeTokens';
 import { safeUrl } from './content';
 import { queryParams } from './http';
 import { guestSignInReady } from './guest';
@@ -35,6 +35,8 @@ export async function getSite(repo: ContentRepository, url: URL, _id = '', local
       // Admin → Mobile app → App access
       bookingChanges: CALENDAR.enabled && settings.mobileAccess.bookingChanges, guestSignIn: await guestSignInReady(repo, locals),
       forms: settings.mobileAccess.forms, links: settings.mobileAccess.links,
+      // Integrations → Live video; GET /api/v1/live answers 404 while it's off
+      live: settings.live.mode !== 'off',
     },
     apiVersion: 1,
   };
@@ -42,9 +44,11 @@ export async function getSite(repo: ContentRepository, url: URL, _id = '', local
 export async function getThemeTokens(repo: ContentRepository, url: URL) {
   z.object({}).strict().parse(queryParams(url));
   const { theme, tokens: t } = resolveDesign(await repo.getSettings());
+  const light = { bg: t.bg, ink: t.ink, muted: t.muted, line: t.line, accent: t.accent, panel: t.panel, soft: t.soft }, dark = darkPalette(t);
   return {
     id: theme.slug, name: theme.name, scheme: t.scheme,
-    colors: { light: { bg: t.bg, ink: t.ink, muted: t.muted, line: t.line, accent: t.accent, panel: t.panel, soft: t.soft }, dark: darkPalette(t) },
+    // live: the live-video marker color the website uses (--live)
+    colors: { light: { ...light, live: liveColor(t, light, false) }, dark: { ...dark, live: liveColor(t, dark, true) } },
     fonts: { heading: t.headingFont, body: t.bodyFont, mono: t.monoFont }, radius: t.radius,
   };
 }

package/src/lib/push/api.ts

@@ -108,6 +108,8 @@ export async function adminPushState(repo: ContentRepository, url: URL, locals?:
     stats, topics, auto: settings.push.auto, links, log,
     collections: Object.entries(CONTENT.collections).map(([key, c]) => ({ key, label: c.plural })),
     calendarEnabled: CALENDAR.enabled,
+    // "we're live" needs live video on (Integrations → Live video)
+    liveMode: settings.live.mode,
     calendars: calendars.filter((c) => c.visibility === 'public').map((c) => ({ id: c.id, slug: c.slug, name: c.name, color: c.color })),
     expo: { accessToken: Boolean(expo.accessToken), customEndpoint: expo.base !== EXPO_PUSH_BASE },
   };
@@ -150,6 +152,7 @@ export async function adminPushAction(repo: ContentRepository, input: z.infer<ty
         newPost: { collections: [...new Set(input.auto.newPost.collections)].filter((k) => collections.has(k)) },
         newEvent: { calendars: CALENDAR.enabled ? cals(input.auto.newEvent.calendars) : [] },
         startingSoon: { calendars: CALENDAR.enabled ? cals(input.auto.startingSoon.calendars) : [], minutes: input.auto.startingSoon.minutes },
+        live: { enabled: input.auto.live?.enabled === true },
       };
       await repo.updateSettings({ push: { auto } });
       return { auto };

package/src/lib/push/service.ts

@@ -1,5 +1,5 @@
 // Push notifications: topics, audiences, the Expo sender pipeline, automatic
-// notices (first publish of a post/event, "starting soon") and receipts.
+// notices (first publish of a post/event, "starting soon", "we're live") and receipts.
 import type { ContentRepository } from '../repo/types';
 import type { CalEvent, Calendar, Post, Settings } from '../schema';
 import { CONTENT, collectionUrl } from '../content';
@@ -8,6 +8,8 @@ import { eventIsListed, eventTimeZone, expandEvents } from '../calendar/events';
 import { I18N } from '../i18n';
 import { localizeDoc } from '../translations';
 import { localizedUrl } from '../mobile/locale';
+import { effectiveSnapshot } from '../live/service';
+import type { LiveSnapshot } from '../live/types';
 import { PUSH } from './config';
 import { expoOptions, fetchReceipts, isGone, sendMessages, type ExpoMessage, type ExpoOptions } from './expo';
 import type { PushNotification, PushSource, PushTopic } from './types';
@@ -22,8 +24,11 @@ export const RECEIPT_DELAY = 15 * MINUTE;
 
 /**
  * Topics an app can offer as toggles. `news` = every new post, `events` = every
- * new event. Per-collection and per-calendar topics appear once there is more
- * than one of them (a single one would just repeat news/events).
+ * new event, `live` = "we're live" (while live video isn't off). Per-collection
+ * and per-calendar topics appear once there is more than one of them (a single
+ * one would just repeat news/events). Devices only get the topics they (or the
+ * app, at their first registration) choose: a new topic never reaches existing
+ * devices on its own.
  */
 export async function pushTopics(repo: ContentRepository): Promise<PushTopic[]> {
   const collections = Object.entries(CONTENT.collections);
@@ -34,12 +39,13 @@ export async function pushTopics(repo: ContentRepository): Promise<PushTopic[]>
     const calendars = (await repo.listCalendars()).filter((c) => c.visibility === 'public');
     if (calendars.length > 1) out.push(...calendars.map((c): PushTopic => ({ id: `calendar:${c.slug}`, label: c.name, kind: 'calendar' })));
   }
+  if ((await repo.getSettings()).live.mode !== 'off') out.push({ id: 'live', label: 'Live video', kind: 'general' });
   return out;
 }
 
-/** Every topic a device may subscribe to (listed or not). */
+/** Every topic a device may subscribe to (listed or not). `live` stays valid while live video is off, so a saved choice survives. */
 export async function knownTopics(repo: ContentRepository): Promise<Set<string>> {
-  const set = new Set(['news', ...Object.keys(CONTENT.collections).map((k) => `collection:${k}`)]);
+  const set = new Set(['news', 'live', ...Object.keys(CONTENT.collections).map((k) => `collection:${k}`)]);
   if (CALENDAR.enabled) {
     set.add('events');
     for (const c of await repo.listCalendars()) if (c.visibility === 'public') set.add(`calendar:${c.slug}`);
@@ -57,12 +63,12 @@ export function deviceLocale(raw: string): string | null {
   return match && match !== I18N.defaultLocale ? match : null;
 }
 
-const STRINGS: Record<string, { startsIn: (m: number) => string; now: string }> = {
-  en: { startsIn: (m) => `Starts in ${m} min`, now: 'Starting now' },
-  es: { startsIn: (m) => `Empieza en ${m} min`, now: 'Empieza ahora' },
-  fr: { startsIn: (m) => `Commence dans ${m} min`, now: 'Commence maintenant' },
-  de: { startsIn: (m) => `Beginnt in ${m} Min.`, now: 'Beginnt jetzt' },
-  pt: { startsIn: (m) => `Começa em ${m} min`, now: 'Começa agora' },
+const STRINGS: Record<string, { startsIn: (m: number) => string; now: string; live: string }> = {
+  en: { startsIn: (m) => `Starts in ${m} min`, now: 'Starting now', live: 'We’re live' },
+  es: { startsIn: (m) => `Empieza en ${m} min`, now: 'Empieza ahora', live: 'Estamos en vivo' },
+  fr: { startsIn: (m) => `Commence dans ${m} min`, now: 'Commence maintenant', live: 'Nous sommes en direct' },
+  de: { startsIn: (m) => `Beginnt in ${m} Min.`, now: 'Beginnt jetzt', live: 'Wir sind live' },
+  pt: { startsIn: (m) => `Começa em ${m} min`, now: 'Começa agora', live: 'Estamos ao vivo' },
 };
 export const pushStrings = (locale: string) => STRINGS[locale.split('-')[0]] ?? STRINGS.en;
 
@@ -289,13 +295,96 @@ export async function checkPushReceipts(repo: ContentRepository, opts: PushRunOp
   return done.length;
 }
 
-/** Scheduler entry: queue, starting soon, receipts and retention. Disabled → queued notices are skipped. */
+// ---- live video ------------------------------------------------------------------
+
+/** A broadcast first seen this long after it started (connection turned on mid-service, scheduler down) is not announced. */
+export const LIVE_LATE_AFTER = 20 * MINUTE;
+/** At most one automatic "we're live" notice in this window: a stream that drops and restarts as a new broadcast never notifies twice. */
+export const LIVE_COOLDOWN = 3 * HOUR;
+
+/**
+ * The ledger key: one notice per broadcast. YouTube video ids are the same
+ * whether detected or pasted as a manual link, so the two never both notify;
+ * other manual links count once per link expiry.
+ */
+export function liveKey(s: Pick<LiveSnapshot, 'source' | 'provider' | 'id' | 'expiresAt'>): string {
+  if (s.source === 'manual' && s.provider !== 'youtube') return `live:manual:${s.expiresAt}`;
+  return `live:${s.provider}:${s.id}`;
+}
+
+/** "We're live": localized title, the broadcast title as the body, and the watch link (apps open it outside the app). */
+export function liveNotice(s: LiveSnapshot, settings: Settings): SendInput {
+  // a manual link keeps its default title "We’re live": don't say it twice
+  const body = clip(s.title && s.title !== STRINGS.en.live ? s.title : settings.siteTitle, 240);
+  const words = (locale: string): Composed => ({ title: pushStrings(locale).live, body, url: s.watchUrl });
+  return { ...words(displayLocale(settings)), audience: ['live'], source: 'live', sourceKey: liveKey(s),
+    data: { kind: 'live', provider: s.provider, id: s.id }, localize: (l) => words(l) };
+}
+
+async function announceLive(repo: ContentRepository, s: LiveSnapshot, settings: Settings, key: string, run: PushRunOptions & { now: number }) {
+  try {
+    const n = await sendNotification(repo, liveNotice(s, settings), run);
+    await repo.push.markQueue(key, 'sent', n.id, run.now);
+    return n;
+  } catch (e) {
+    await repo.push.markQueue(key, 'failed', null, run.now).catch(() => {});
+    throw e;
+  }
+}
+
+/**
+ * Automatic "we're live" (Mobile app → automatic notifications): runs after
+ * the scheduler's live check. Each detected broadcast is claimed once in the
+ * push ledger, so a stream that flickers offline and back, or a restart, can't
+ * send it twice. Late detections and restarts inside the cooldown are skipped.
+ */
+export async function sendLiveNotice(repo: ContentRepository, opts: PushRunOptions = {}): Promise<number> {
+  if (!PUSH.enabled) return 0;
+  const now = opts.now ?? Date.now();
+  const [settings, connections] = await Promise.all([repo.getSettings(), repo.live.list()]);
+  if (!settings.push.auto.live.enabled) return 0;
+  const s = effectiveSnapshot(settings.live, connections, now);
+  if (s?.status !== 'live' || s.source !== 'automatic' || !s.id) return 0;
+  const key = liveKey(s);
+  if (!(await repo.push.claimKey(key, 'live', s.id, s.startedAt || null, now))) return 0;
+  const late = s.startedAt > 0 && now - s.startedAt > LIVE_LATE_AFTER;
+  if (late || (await repo.push.lastSent('live')) > now - LIVE_COOLDOWN) {
+    await repo.push.markQueue(key, 'skipped', null, now);
+    return 0;
+  }
+  try {
+    await announceLive(repo, s, settings, key, { ...opts, now, origin: opts.origin ?? siteOriginOf(settings, opts.fallbackOrigin) });
+    return 1;
+  } catch (e) {
+    console.error('acms push: live notification failed', e);
+    return 0;
+  }
+}
+
+/**
+ * "Notify app users" on a manual link (Integrations → Live video): one notice
+ * for the active manual link, sent right away. Saving the same link again
+ * (or a YouTube video already announced) sends nothing. Null when nothing was sent.
+ */
+export async function sendManualLiveNotice(repo: ContentRepository, opts: PushRunOptions = {}): Promise<PushNotification | null> {
+  if (!PUSH.enabled) return null;
+  const now = opts.now ?? Date.now();
+  const settings = await repo.getSettings();
+  const s = effectiveSnapshot(settings.live, [], now);
+  if (s?.source !== 'manual' || s.status !== 'live') return null;
+  const key = liveKey(s);
+  if (!(await repo.push.claimKey(key, 'live', s.id, null, now))) return null;
+  return announceLive(repo, s, settings, key, { ...opts, now, origin: opts.origin ?? siteOriginOf(settings, opts.fallbackOrigin) });
+}
+
+/** Scheduler entry: queue, starting soon, we're live, receipts and retention. Disabled → queued notices are skipped. */
 export async function runPushJobs(repo: ContentRepository, opts: PushRunOptions = {}): Promise<number> {
   const now = opts.now ?? Date.now();
   if (!PUSH.enabled) { await repo.push.skipPending(now); return 0; }
   const run = { ...opts, now };
   let count = await processPushQueue(repo, run);
   count += await sendStartingSoon(repo, run);
+  count += await sendLiveNotice(repo, run);
   count += await checkPushReceipts(repo, run);
   await repo.push.purge(now, now - PUSH.retentionDays * DAY);
   return count;

package/src/lib/push/store.ts

@@ -128,16 +128,20 @@ export class PushStore {
     await this.run('UPDATE push_queue SET status=?, notification_id=?, updated_at=? WHERE key=?', [status, notificationId, now, key]);
   }
   async skipPending(now: number) { await this.run(`UPDATE push_queue SET status='skipped', updated_at=? WHERE status='pending'`, [now]); }
+  /** When a notice of this kind last went out (0 = never). */
+  async lastSent(kind: PushQueueRow['kind']): Promise<number> {
+    return Number((await this.all(`SELECT MAX(updated_at) AS at FROM push_queue WHERE kind=? AND status='sent'`, [kind]))[0]?.at ?? 0);
+  }
   async queueStatus(key: string) { return (await this.all('SELECT status FROM push_queue WHERE key=?', [key]))[0]?.status as string | undefined; }
 
   // ---- retention ----
-  /** Devices not seen since `devicesBefore`, log rows older than a year, expired tickets and old occurrence keys. */
+  /** Devices not seen since `devicesBefore`, log rows older than a year, expired tickets, and old occurrence and broadcast keys. */
   async purge(now: number, devicesBefore: number): Promise<number> {
     const gone = await this.all('DELETE FROM push_devices WHERE last_seen_at<? RETURNING id', [devicesBefore]);
     await (await this.driver()).batch([
       { sql: 'DELETE FROM push_notifications WHERE created_at<?', args: [now - 365 * 86400000] },
       { sql: 'DELETE FROM push_tickets WHERE created_at<?', args: [now - 86400000] },
-      { sql: `DELETE FROM push_queue WHERE kind='soon' AND updated_at<?`, args: [now - 30 * 86400000] },
+      { sql: `DELETE FROM push_queue WHERE kind IN ('soon','live') AND updated_at<?`, args: [now - 30 * 86400000] },
     ]);
     return gone.length;
   }

package/src/lib/push/types.ts

@@ -9,6 +9,8 @@ export const PushAuto = z.object({
   newEvent: z.object({ calendars: keys.default([]) }).default({}),
   /** "starting soon" reminders, sent `minutes` before each occurrence */
   startingSoon: z.object({ calendars: keys.default([]), minutes: z.number().int().min(5).max(1440).default(30) }).default({}),
+  /** "We're live": once per broadcast that live video detects, to devices on the `live` topic */
+  live: z.object({ enabled: z.boolean().default(false) }).default({}),
 });
 export type PushAuto = z.infer<typeof PushAuto>;
 export const PushSettings = z.object({ auto: PushAuto.default({}) });
@@ -19,7 +21,7 @@ export interface PushDevice {
   id: string; token: string; platform: PushPlatform; locale: string; topics: string[];
   createdAt: number; updatedAt: number; lastSeenAt: number;
 }
-export type PushSource = 'manual' | 'post' | 'event' | 'soon';
+export type PushSource = 'manual' | 'post' | 'event' | 'soon' | 'live';
 export interface PushNotification {
   id: string; title: string; body: string; url: string;
   /** ['*'] = everyone */
@@ -31,7 +33,7 @@ export interface PushNotification {
   removed: number;
   error: string; author: string; createdAt: number; finishedAt: number | null;
 }
-export interface PushQueueRow { key: string; kind: 'post' | 'event' | 'soon'; docId: string; occurrence: number | null; status: string; createdAt: number }
+export interface PushQueueRow { key: string; kind: 'post' | 'event' | 'soon' | 'live'; docId: string; occurrence: number | null; status: string; createdAt: number }
 export interface PushTopic { id: string; label: string; kind: 'general' | 'collection' | 'calendar' }
 export interface PushStats {
   devices: number;

package/src/lib/themeTokens.ts

@@ -138,16 +138,20 @@ export function paletteVars(p: Palette, t: ThemeTokens, dark: boolean): string[]
     `--btn:${t.button === 'accent' ? 'var(--accent)' : 'var(--ink)'}`, `--btn-ink:${btnInk}`,
     `--code-bg:${dark ? '#0d0e11' : '#1b1c21'}`,
     `--success:${dark ? '#5cc98e' : '#127442'}`, `--danger:${dark ? '#f07b7b' : '#b42f2f'}`, `--warning:${dark ? '#e3b456' : '#8a5f0a'}`,
-    ...liveVars(dark ? t.dark?.live || (t.live ? ensureContrast(t.live, p.bg, 3, '#ffffff') : '#ff5a4e') : t.live || '#d42f25', p.bg),
+    ...liveVars(liveColor(t, p, dark)),
     `--sh-1:${s1}`, `--sh-2:${s2}`, `--sh-3:${s3}`,
     `color-scheme:${dark ? 'dark' : 'light'}`,
   ];
 }
 
 // The live signal color stays visible on the canvas (3:1, it's a marker, not
-// body text) and gets whichever text color reads on it.
-function liveVars(live: string, bg: string): string[] {
-  const c = ensureContrast(live, bg, 3);
+// body text). The app API sends the same value as colors.<scheme>.live.
+export function liveColor(t: ThemeTokens, p: Palette, dark: boolean): string {
+  const raw = dark ? t.dark?.live || (t.live ? ensureContrast(t.live, p.bg, 3, '#ffffff') : '#ff5a4e') : t.live || '#d42f25';
+  return ensureContrast(raw, p.bg, 3);
+}
+// …and gets whichever text color reads on it.
+function liveVars(c: string): string[] {
   const on = contrast('#ffffff', c) >= 4.5 || contrast('#ffffff', c) >= contrast('#111214', c) ? '#ffffff' : '#111214';
   return [`--live:${c}`, `--live-on:${on}`];
 }

package/src/pages/api/live/settings.ts

@@ -6,6 +6,7 @@ import { requestSessionBinding } from '../../../lib/auth/request';
 import { Provider } from '../../../lib/live/types';
 import { adminState, beginOAuth, disconnect, saveConnection, syncConnection, validateConfig } from '../../../lib/live/service';
 import { requirePermission } from '../../../lib/permissions/access';
+import { sendManualLiveNotice } from '../../../lib/push/service';
 const Input=z.discriminatedUnion('action',[
   z.object({action:z.literal('saveConnection'),provider:Provider,clientId:z.string().trim().min(1).max(200),clientSecret:z.string().trim().max(8192).default(''),channelInput:z.string().trim().max(2048).default(''),googleStatus:z.enum(['testing','production']).default('testing')}).strict(),
   z.object({action:z.literal('test'),provider:Provider}).strict(),
@@ -13,7 +14,8 @@ const Input=z.discriminatedUnion('action',[
   z.object({action:z.literal('enable'),provider:Provider,enabled:z.boolean()}).strict(),
   z.object({action:z.literal('authorize'),provider:z.literal('youtube')}).strict(),
   z.object({action:z.literal('disconnect'),provider:Provider}).strict(),
-  z.object({action:z.literal('saveConfig'),config:z.unknown()}).strict(),
+  // notify: "Notify app users" on a manual link (sends once per link; needs push)
+  z.object({action:z.literal('saveConfig'),config:z.unknown(),notify:z.boolean().default(false)}).strict(),
 ]);
 export const GET:APIRoute=async({request,cookies,locals,url})=>{
   try{const repo=await getRepo(locals);await requirePermission(request, cookies, repo, 'services.manage');return json(await adminState(repo,url,locals));}catch(e){return apiError(e);}
@@ -29,7 +31,14 @@ export const POST:APIRoute=async({request,cookies,locals,url})=>{
       case 'test':await syncConnection(repo,input.provider,locals,true);break;
       case 'authorize':return json({authorizationUrl:await beginOAuth(repo,await requestSessionBinding(request,cookies,locals),url,locals)});
       case 'disconnect':await disconnect(repo,input.provider,locals);break;
-      case 'saveConfig':await repo.updateSettings({live:validateConfig(input.config)});break;
+      case 'saveConfig':{
+        await repo.updateSettings({live:validateConfig(input.config)});
+        if(!input.notify)break;
+        // the link is saved either way; report whether the notice went out
+        let notified:{recipients:number}|null=null,notifyError='';
+        try{const n=await sendManualLiveNotice(repo,{locals,fallbackOrigin:url.origin});notified=n&&{recipients:n.recipients};}catch{notifyError='Saved, but the notification could not be sent. Try again from Mobile app.';}
+        return json({...await adminState(repo,url,locals),notified,notifyError});
+      }
       case 'selectChannel':{
         const conn=await repo.live.get(input.provider);const selected=conn?.channels.find(c=>c.id===input.channelId);
         if(!conn||!selected)throw new ApiError(400,'Choose a channel from the authorized account.');

package/src/pages/api/v1/live.ts

@@ -0,0 +1,8 @@
+import { getLive } from '../../../lib/mobile/live';
+import { readRoute } from '../../../lib/mobile/route';
+import { methodNotAllowed } from '../../../lib/mobile/http';
+export { preflight as OPTIONS } from '../../../lib/mobile/http';
+// no-store: the status changes by the minute and must never be served stale
+export const GET = readRoute(getLive, false);
+export const HEAD = GET;
+export const ALL = () => methodNotAllowed();

package/src/styles/mobile-app.css

@@ -74,6 +74,7 @@
 .ma-rule:first-child { border-top: 0; padding-top: 0; }
 .ma-rule-head b { display: block; font-size: 13.5px; }
 .ma-rule-head small { display: block; color: var(--muted); font-size: 12px; margin-top: 1px; }
+.ma-rule .hint { margin: 8px 0 0; }
 .ma-choices { display: flex; flex-wrap: wrap; gap: 4px 18px; margin-top: 8px; }
 .ma-check { display: inline-flex; align-items: center; gap: 8px; min-height: 30px; font-size: 13px; color: var(--text-2); cursor: pointer; }
 .ma-check input { accent-color: var(--accent); width: 15px; height: 15px; margin: 0; }