@acms-subir/core 0.3.28 → 0.3.30

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @acms-subir/core
 
+## 0.3.30
+
+### Patch Changes
+
+- aeaed2c: YouTube **Authorize** (Integrations → Live video) now finishes on sites that use a Clerk development instance. Before, Google's redirect back to `/api/live/oauth/youtube/callback` was always signed out there: development instances set `__client_uat` as `SameSite=Strict`, so the browser drops it from the cross-site return, Clerk answers with a handshake, and the page showed "YouTube authorization didn't finish". The same thing could happen on production when the owner spent more than about a minute on Google's screens and the session token lapsed.
+
+  The callback no longer checks the sign-in. It attaches Google's code, encrypted, to its one-use pending state for up to two minutes. Only the first return counts. It then sends the owner to `/admin/live?live=finish`, where a lapsed sign-in renews like on any admin page. That page finishes with a same-origin request (the new `finishAuthorize` action on `/api/live/settings`, gated like every other owner action), and only the session that started authorization can finish it. The code never appears in a URL again, and nothing changes in Google's setup: the redirect URI is the same. No migration.
+
+## 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

@@ -28,7 +28,7 @@ ACMS obtains an app token with the client-credentials flow and checks Get Stream
 4. Save the Client ID and Client Secret in ACMS, then choose **Authorize YouTube**. Approve YouTube read-only access using the correct Google/Brand channel identity.
 5. Confirm the available channel, test, and turn the connection on. Selecting another channel requires a new test. A typed channel ID cannot override the authorized identity.
 
-The authorization-code flow uses session-bound, one-use state and PKCE. Access/refresh tokens stay encrypted on the server. ACMS lists active broadcasts, filters to the selected channel and public `live` broadcasts, and checks public video visibility/embedding permission. Private, unlisted and test broadcasts are excluded. Multiple current broadcasts use the latest actual start time with a stable ID tie-break. See [liveBroadcasts.list](https://developers.google.com/youtube/v3/live/docs/liveBroadcasts/list) and [server OAuth](https://developers.google.com/identity/protocols/oauth2/web-server).
+The authorization-code flow uses session-bound, one-use state and PKCE. Google's redirect back is a cross-site request that may arrive without a usable sign-in (a Clerk development instance withholds its `SameSite=Strict` cookie, and a session token can lapse while the owner is on Google's screens). It doesn't need one: it only attaches the code, encrypted, to its pending state for up to two minutes, then sends the owner to `/admin/live?live=finish`. That page finishes with a same-origin request from the signed-in session that began authorization; no other session can finish it, and the code never appears in a URL again. Access/refresh tokens stay encrypted on the server. ACMS lists active broadcasts, filters to the selected channel and public `live` broadcasts, and checks public video visibility/embedding permission. Private, unlisted and test broadcasts are excluded. Multiple current broadcasts use the latest actual start time with a stable ID tie-break. See [liveBroadcasts.list](https://developers.google.com/youtube/v3/live/docs/liveBroadcasts/list) and [server OAuth](https://developers.google.com/identity/protocols/oauth2/web-server).
 
 External OAuth apps left in **Testing** receive refresh tokens for YouTube scopes that expire after seven days. The UI's Testing/Production choice is owner-reported; ACMS cannot verify the app's publishing status. Follow Google's applicable publishing and verification requirements before relying on a long-running connection. A revoked or expired grant requires reauthorization. See [Google token expiration](https://developers.google.com/identity/protocols/oauth2#expiration).
 
@@ -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.30",
   "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) {
@@ -164,11 +167,23 @@ export default function LiveManager() {
     }
   }
 
+  // Google sent the owner back (?live=finish): the callback parked the code; finish it with this
+  // signed-in session (a same-origin POST, so a lapsed sign-in renews on this page first)
+  async function finishAuthorize() {
+    try {
+      adopt(await api<LiveAdminState>({ action: 'finishAuthorize', provider: 'youtube' }));
+      setPageMsg({ ok: 'YouTube is authorized. Confirm your channel below, then test the connection.', err: '' });
+    } catch (e) {
+      setPageMsg({ ok: '', err: `YouTube authorization didn’t finish: ${errText(e)} Try Authorize again.` });
+      await load();
+    }
+  }
+
   useEffect(() => {
     const q = new URLSearchParams(location.search);
     const r = q.get('live');
-    if (r === 'connected') {
-      setPageMsg({ ok: 'YouTube is authorized. Confirm your channel below, then test the connection.', err: '' });
+    if (r === 'finish') {
+      setPageMsg({ ok: 'Finishing YouTube authorization…', err: '' });
     } else if (r === 'error') {
       setPageMsg({ ok: '', err: 'YouTube authorization didn’t finish. Check that the redirect URI in Google matches exactly, then try Authorize again.' });
     }
@@ -179,7 +194,7 @@ export default function LiveManager() {
       const qs = q.toString();
       history.replaceState(history.state, '', location.pathname + (qs ? `?${qs}` : '') + location.hash);
     }
-    void load();
+    void (r === 'finish' ? finishAuthorize() : load());
     const tick = setInterval(() => setNow(Date.now()), 30_000);
     return () => clearInterval(tick);
   }, []);
@@ -256,13 +271,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 +832,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> {
@@ -140,15 +141,32 @@ export async function beginOAuth(repo:ContentRepository,session:string,url:URL,l
   const params={client_id:conn.clientId,redirect_uri:callbackUrl,response_type:'code',scope:'https://www.googleapis.com/auth/youtube.readonly',access_type:'offline',prompt:'consent select_account',state,code_challenge:Buffer.from(hash(verifier),'hex').toString('base64url'),code_challenge_method:'S256'};
   Object.entries(params).forEach(([k,v])=>auth.searchParams.set(k,v));return auth.href;
 }
-export async function finishOAuth(repo:ContentRepository,session:string,url:URL,locals?:unknown) {
+type PendingOAuth={verifier:string;callbackUrl:string;code?:string};
+// Google sends the browser back with a cross-site GET, which often carries no usable sign-in: a
+// Clerk development instance withholds its SameSite=Strict cookie, and a session token can expire
+// while the owner is on Google's screens. So the callback only parks the code on its pending state
+// (found by the state value, which only Google's redirect carries); the signed-in admin page then
+// finishes it with a same-origin POST bound to the session that began it.
+export async function receiveOAuthCallback(repo:ContentRepository,url:URL,locals?:unknown) {
   const state=url.searchParams.get('state')??'';
   if(!/^[\w-]{43}$/.test(state))throw new ApiError(400,'Invalid OAuth state. Start authorization again.');
-  const stored=await repo.live.consumeState(hash(state),hash(session),Date.now());
-  const conn=await repo.live.get('youtube');
-  if(!stored||!conn||stored.revision!==conn.revision)throw new ApiError(400,'Authorization expired or the connection changed. Start again.');
   if(url.searchParams.has('error'))throw new ApiError(400,'YouTube authorization was not completed. Try again and approve read-only access.');
   const code=url.searchParams.get('code');if(!code||code.length>8192)throw new ApiError(400,'Missing authorization code.');
-  const {verifier,callbackUrl}=decrypt<{verifier:string;callbackUrl:string}>(stored.encrypted,'oauth',locals);
+  const now=Date.now(),stored=await repo.live.pendingState(hash(state),now);
+  if(!stored)throw new ApiError(400,'Authorization expired. Start again.');
+  const pending=decrypt<PendingOAuth>(stored.encrypted,'oauth',locals);
+  if(pending.code)throw new ApiError(409,'This authorization already came back. Start again.');
+  if(new URL(pending.callbackUrl).origin!==url.origin)throw new ApiError(400,'The callback origin does not match the saved site.');
+  // the admin page finishes within seconds; a parked code doesn't wait around
+  if(!await repo.live.attachCode(hash(state),stored.encrypted,encrypt({...pending,code},'oauth',locals),Math.min(stored.expiresAt,now+120_000),now))throw new ApiError(409,'This authorization already came back. Start again.');
+}
+/** Exchanges the parked code for tokens. `url` is the signed-in admin request (same origin as the callback). */
+export async function finishOAuth(repo:ContentRepository,session:string,url:URL,locals?:unknown) {
+  const rows=session?await repo.live.consumeSessionStates(hash(session),Date.now()):[];
+  const stored=rows.map(r=>({...r,...decrypt<PendingOAuth>(r.encrypted,'oauth',locals)})).find(r=>r.code);
+  const conn=await repo.live.get('youtube');
+  if(!stored||!conn||stored.revision!==conn.revision)throw new ApiError(400,'Authorization expired or the connection changed. Start again.');
+  const {verifier,callbackUrl,code}=stored as Required<typeof stored>;
   if(new URL(callbackUrl).origin!==url.origin)throw new ApiError(400,'The callback origin does not match the saved site.');
   const old=decrypt<Credentials>(conn.encrypted,'youtube',locals);
   try{

package/src/lib/live/store.ts

@@ -40,9 +40,19 @@ export class LiveStore {
   async state(hash: string, sessionHash: string, revision: number, encrypted: string, expiresAt: number) {
     await (await this.driver()).batch([{sql:'DELETE FROM live_oauth_states WHERE expires_at<? OR session_hash=?',args:[Date.now(),sessionHash]}, {sql:'INSERT INTO live_oauth_states (hash,session_hash,revision,encrypted,expires_at) VALUES (?,?,?,?,?)',args:[hash,sessionHash,revision,encrypted,expiresAt]}]);
   }
-  async consumeState(hash: string, sessionHash: string, now: number) {
-    const rows = await (await this.driver()).all('DELETE FROM live_oauth_states WHERE hash=? AND session_hash=? AND expires_at>? RETURNING revision,encrypted', [hash,sessionHash,now]);
-    return rows[0] ? {revision:Number(rows[0].revision),encrypted:String(rows[0].encrypted)} : null;
+  // Google's redirect finds its pending state by the state value alone (it often arrives without a
+  // usable sign-in); only the signed-in admin who began it can finish it (consumeSessionStates).
+  async pendingState(hash: string, now: number) {
+    const rows = await (await this.driver()).all('SELECT encrypted,expires_at FROM live_oauth_states WHERE hash=? AND expires_at>?', [hash,now]);
+    return rows[0] ? {encrypted:String(rows[0].encrypted),expiresAt:Number(rows[0].expires_at)} : null;
+  }
+  /** Swaps in the payload with Google's code. Compare-and-swap on the old ciphertext: only the first callback counts. */
+  async attachCode(hash: string, before: string, after: string, expiresAt: number, now: number) {
+    return (await (await this.driver()).all('UPDATE live_oauth_states SET encrypted=?,expires_at=? WHERE hash=? AND encrypted=? AND expires_at>? RETURNING hash', [after,expiresAt,hash,before,now])).length > 0;
+  }
+  async consumeSessionStates(sessionHash: string, now: number) {
+    const rows = await (await this.driver()).all('DELETE FROM live_oauth_states WHERE session_hash=? AND expires_at>? RETURNING revision,encrypted', [sessionHash,now]);
+    return rows.map(r => ({revision:Number(r.revision),encrypted:String(r.encrypted)}));
   }
   async heartbeat(now: number) { await (await this.driver()).run('UPDATE live_health SET last_at=? WHERE id=1',[now]); }
   async lastHeartbeat() { return Number((await (await this.driver()).all('SELECT last_at FROM live_health WHERE id=1'))[0]?.last_at ?? 0); }

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/oauth/youtube/callback.ts

@@ -1,18 +1,15 @@
 import type { APIRoute } from 'astro';
 import { getRepo } from '../../../../../lib/repo';
-import { ApiError } from '../../../../../lib/api';
-import { requestSessionBinding } from '../../../../../lib/auth/request';
-import { accessFor } from '../../../../../lib/permissions/access';
-import { finishOAuth } from '../../../../../lib/live/service';
-export const GET:APIRoute=async({request,cookies,locals,url})=>{
+import { receiveOAuthCallback } from '../../../../../lib/live/service';
+// Google's redirect back is a cross-site GET that may carry no usable sign-in (Clerk development
+// instances, a session token that expired on Google's screens), so it doesn't check one: it parks
+// the code on its one-use pending state, and the signed-in admin page finishes with a same-origin
+// POST (finishAuthorize) bound to the session that began it. The code never enters a URL again.
+export const GET:APIRoute=async({locals,url})=>{
   const headers={'Cache-Control':'no-store','Referrer-Policy':'no-referrer'};
   try{
-    const repo=await getRepo(locals),session=await requestSessionBinding(request,cookies,locals);
-    // OAuth is intentionally a cross-site GET. Session-bound, one-use state provides CSRF protection.
-    const access=await accessFor(request,cookies,repo);
-    if(!session||!access?.can('services.manage'))throw new ApiError(403,'Sign in as someone who manages connected services and start authorization again.');
-    await finishOAuth(repo,session,url,locals);
-    return new Response(null,{status:303,headers:{...headers,Location:'/admin/live?live=connected'}});
+    await receiveOAuthCallback(await getRepo(locals),url,locals);
+    return new Response(null,{status:303,headers:{...headers,Location:'/admin/live?live=finish'}});
   }catch{
     // Never reflect callback codes, tokens or provider error bodies into an HTML page or URL.
     return new Response(null,{status:303,headers:{...headers,Location:'/admin/live?live=error'}});

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

@@ -4,16 +4,20 @@ import { getRepo } from '../../../lib/repo';
 import { ApiError, apiError, json, readJson } from '../../../lib/api';
 import { requestSessionBinding } from '../../../lib/auth/request';
 import { Provider } from '../../../lib/live/types';
-import { adminState, beginOAuth, disconnect, saveConnection, syncConnection, validateConfig } from '../../../lib/live/service';
+import { adminState, beginOAuth, disconnect, finishOAuth, 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(),
   z.object({action:z.literal('selectChannel'),provider:z.literal('youtube'),channelId:z.string().min(1).max(200)}).strict(),
   z.object({action:z.literal('enable'),provider:Provider,enabled:z.boolean()}).strict(),
   z.object({action:z.literal('authorize'),provider:z.literal('youtube')}).strict(),
+  // after Google's redirect (?live=finish): exchange the parked code for this signed-in session
+  z.object({action:z.literal('finishAuthorize'),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);}
@@ -28,8 +32,16 @@ export const POST:APIRoute=async({request,cookies,locals,url})=>{
       case 'saveConnection':await saveConnection(repo,input,locals);break;
       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 'finishAuthorize':await finishOAuth(repo,await requestSessionBinding(request,cookies,locals),url,locals);break;
       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; }