@acms-subir/core 0.3.0 → 0.3.2

package/src/components/ThemeSections.astro

@@ -1,4 +1,5 @@
 ---
+import LiveCard from './LiveCard.astro';
 import type { Page, Settings } from '../lib/schema';
 import { getTheme } from '../lib/theme';
 import { getRepo } from '../lib/repo';
@@ -32,7 +33,7 @@ const sections = await Promise.all(layout.sections.map(async (section) => {
 <div class="acms-sections">
   {sections.filter(s => !s.hidden && !s.invalid).map(({ id, type, variant, data, Template, posts }) => (
     <section id={`section-${id}`} class:list={['acms-section', `section-${type}`, `variant-${variant}`]}>
-      {type === 'page-content' ? (page.bodyHtml ? <article class="page-body" set:html={bodyHtml} /> : <WidgetRenderer pageId={page.id} blocks={page.blocks} />) : Template ? <Template data={data} variant={variant} settings={settings} page={page} /> : (
+      {type === 'live' && !Template ? <LiveCard display={variant} /> : type === 'page-content' ? (page.bodyHtml ? <article class="page-body" set:html={bodyHtml} /> : <WidgetRenderer pageId={page.id} blocks={page.blocks} />) : Template ? <Template data={data} variant={variant} settings={settings} page={page} /> : (
         <>
           <div class="section-copy">
             {data.heading && <h2>{String(data.heading)}</h2>}

package/src/components/WidgetRenderer.astro

@@ -1,4 +1,5 @@
 ---
+import LiveCard from './LiveCard.astro';
 import { parseConfig, type WidgetInstance, type WidgetType } from '../lib/schema';
 import { renderMarkdown } from '../lib/markdown';
 
@@ -21,6 +22,8 @@ const items = blocks.flatMap((b) => {
 
 {items.map(({ block, config }) => {
   switch (block.type) {
+    case 'live':
+      return <LiveCard display={config.display} />;
     case 'hero':
       return (
         <section class={`w-hero ${config.align}`}>

package/src/components/editor/extensions/cards.tsx

@@ -3,6 +3,9 @@ import { NodeViewWrapper, NodeViewContent, ReactNodeViewRenderer } from '@tiptap
 import type { NodeViewProps } from '@tiptap/react';
 import { useState } from 'react';
 import { cleanEventName } from '../../../lib/analytics';
+import { detectEmbed } from '../../../lib/embeds';
+
+export { detectEmbed, type EmbedInfo } from '../../../lib/embeds';
 
 // Card nodes shared by the post editor. renderHTML emits the public markup
 // (`.pc-*` classes, styled in src/styles/cards.css); parseHTML round-trips it
@@ -129,44 +132,6 @@ function ImageCardView({ node, updateAttributes, deleteNode, selected }: NodeVie
 
 // ---- embed ----------------------------------------------------------------
 
-export interface EmbedInfo {
-  provider: string;
-  embedSrc: string;
-  aspect: boolean; // true → 16:9, false → fixed height
-}
-
-export function detectEmbed(raw: string): EmbedInfo | null {
-  let url: URL;
-  try {
-    url = new URL(raw.trim());
-  } catch {
-    return null;
-  }
-  const host = url.hostname.replace(/^www\./, '');
-  if (host === 'youtube.com' || host === 'm.youtube.com' || host === 'youtu.be' || host === 'youtube-nocookie.com') {
-    const id =
-      host === 'youtu.be'
-        ? url.pathname.slice(1).split('/')[0]
-        : url.pathname.startsWith('/shorts/') || url.pathname.startsWith('/embed/')
-          ? url.pathname.split('/')[2]
-          : url.searchParams.get('v');
-    if (id) return { provider: 'youtube', embedSrc: `https://www.youtube-nocookie.com/embed/${id}`, aspect: true };
-  }
-  if (host === 'vimeo.com' || host === 'player.vimeo.com') {
-    const id = url.pathname.split('/').filter(Boolean).pop();
-    if (id && /^\d+$/.test(id)) return { provider: 'vimeo', embedSrc: `https://player.vimeo.com/video/${id}`, aspect: true };
-  }
-  if (host === 'loom.com' && url.pathname.startsWith('/share/')) {
-    return { provider: 'loom', embedSrc: `https://www.loom.com/embed/${url.pathname.split('/')[2]}`, aspect: true };
-  }
-  if (host === 'codepen.io' && url.pathname.includes('/pen/')) {
-    return { provider: 'codepen', embedSrc: raw.replace('/pen/', '/embed/'), aspect: false };
-  }
-  if (url.protocol === 'https:') {
-    return { provider: 'iframe', embedSrc: raw, aspect: false };
-  }
-  return null;
-}
 
 export const EmbedCard = Node.create({
   name: 'embedCard',

package/src/components/editor/extensions/mediaCards.tsx

@@ -40,6 +40,8 @@ export const FileCard = Node.create({
     return [
       {
         tag: 'a.pc-filecard',
+        // outrank the Link mark's a[href] rule, or the card reloads as a plain link
+        priority: 60,
         getAttrs: (el) => {
           const e = el as HTMLElement;
           return {
@@ -288,6 +290,8 @@ export const BookmarkCard = Node.create({
     return [
       {
         tag: 'a.pc-bookmark',
+        // outrank the Link mark's a[href] rule, or the card reloads as a plain link
+        priority: 60,
         getAttrs: (el) => {
           const e = el as HTMLElement;
           return {

package/src/layouts/Admin.astro

@@ -115,7 +115,6 @@ const groups: { id: string; label: string; items: Item[] }[] = [
               ]
             : []),
           { key: 'calendar:calendars', label: 'Calendars', href: '/admin/calendar/calendars', icon: icons.calendars, count: null },
-          { key: 'calendar:integrations', label: 'API & webhooks', href: '/admin/calendar/integrations', icon: icons.plug, count: null },
         ],
       }]
     : []),
@@ -134,6 +133,7 @@ const groups: { id: string; label: string; items: Item[] }[] = [
     items: [
       { key: 'users', label: 'Users', href: '/admin/users', icon: icons.users, count: null },
       { key: 'ai', label: 'Document import', href: '/admin/ai', icon: icons.posts, count: null },
+      { key: 'integrations', label: 'API & webhooks', href: '/admin/integrations', icon: icons.plug, count: null },
       { key: 'settings', label: 'Settings', href: '/admin/settings', icon: icons.settings, count: null },
     ],
   },

package/src/layouts/Site.astro

@@ -16,6 +16,7 @@ import { analyticsHead, analyticsBody } from '../lib/analytics';
 import { socialIconPath, socialIconSvg } from '../lib/socialIcons';
 import '../styles/site.css';
 import '../styles/cards.css';
+import '../styles/live.css';
 
 interface Props {
   title?: string;
@@ -117,6 +118,9 @@ const htmlLang = reqLocale || siteLang(settings);
 // search modal chrome: strings follow the document language, the form's
 // no-JS fallback goes to the (locale-prefixed) /search page
 const showSearch = !bare && SEARCH.enabled;
+// site-wide live signals: rendered hidden, shown by the shared status poller
+// only while a broadcast is live, so pages keep their normal caching
+const liveSignals = !bare && settings.live.mode !== 'off' ? settings.live.display : null;
 const searchT = searchStrings(htmlLang.slice(0, 2));
 const searchAction = reqLocale && reqLocale !== I18N.defaultLocale ? `/${reqLocale}/search` : '/search';
 // columns footer: brand + tagline + socials, the footer nav, and a "Read"
@@ -204,6 +208,14 @@ const homeJsonLd =
     {settings.headCode && <Fragment set:html={settings.headCode} />}
   </head>
   <body>
+    {liveSignals?.bar && (
+      <div class="pc-live-bar" data-live-bar hidden role="status">
+        <span class="pc-live-mark">Live now</span>
+        <span class="pc-live-bar-title" data-live-bar-title></span>
+        <a data-live-bar-watch href="#">Watch →</a>
+        <button type="button" class="pc-live-x" aria-label="Dismiss live notice">✕</button>
+      </div>
+    )}
     {showAnnouncement && (
       <div class="announcement-bar" data-ann-key={ann.dismissible ? annKey : undefined} hidden={ann.dismissible || undefined}>
         {annLink ? <a href={annLink}>{ann.text}</a> : <span>{ann.text}</span>}
@@ -246,6 +258,7 @@ const homeJsonLd =
             ))}
           </nav>
           <div class="site-tools">
+            {liveSignals?.header && <a class="site-live" data-live-header href="#" hidden>Live</a>}
             {showSearch && (
               <a class="pc-search-trigger" href={searchAction} data-search-open aria-label={searchT.label}>
                 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" aria-hidden="true"><circle cx="11" cy="11" r="7" /><path d="m20 20-3.6-3.6" /></svg>
@@ -598,6 +611,21 @@ const homeJsonLd =
         </div>
       </footer>
     )}
+    {liveSignals?.dock && (
+      <div class="pc-live-dock" data-live-dock hidden>
+        <a href="#">
+          <span class="pc-live-dock-thumb"><img alt="" decoding="async" hidden /></span>
+          <span><span class="pc-live-mark">Live</span><b data-live-dock-title></b></span>
+        </a>
+        <button type="button" class="pc-live-x" aria-label="Dismiss live player">✕</button>
+      </div>
+    )}
+    <script>
+      // no-op unless the owner enabled a site-wide live signal above
+      import { mountLiveSignals } from '../lib/live/signals';
+      mountLiveSignals();
+      document.addEventListener('astro:page-load', mountLiveSignals);
+    </script>
     {analyticsBodyHtml && <Fragment set:html={analyticsBodyHtml} />}
     {settings.footerCode && <Fragment set:html={settings.footerCode} />}
   </body>

package/src/lib/api.ts

@@ -18,6 +18,11 @@ export async function readJson(request: Request, maxBytes = 300_000): Promise<un
   return readResponseJson(request, maxBytes);
 }
 export async function readResponseJson(source: Request | Response, maxBytes: number): Promise<unknown> {
+  const bytes = await readResponseBytes(source, maxBytes);
+  try { return JSON.parse(new TextDecoder().decode(bytes)); }
+  catch { throw new ApiError(400, 'Body must be valid JSON.'); }
+}
+export async function readResponseBytes(source: Request | Response, maxBytes: number): Promise<Uint8Array> {
   if (Number(source.headers.get('content-length')) > maxBytes) throw new ApiError(413, 'Payload too large.');
   const reader = source.body?.getReader();
   if (!reader) throw new ApiError(400, 'JSON body is required.');
@@ -35,8 +40,7 @@ export async function readResponseJson(source: Request | Response, maxBytes: num
   const bytes = new Uint8Array(length);
   let offset = 0;
   for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.length; }
-  try { return JSON.parse(new TextDecoder().decode(bytes)); }
-  catch { throw new ApiError(400, 'Body must be valid JSON.'); }
+  return bytes;
 }
 export async function requireSession(
   request: Request, cookies: { get(name: string): { value: string } | undefined }, repo: ContentRepository, ownerOnly = false,

package/src/lib/backup/content.ts

@@ -28,7 +28,7 @@ export async function exportContent(repo: ContentRepository, now = Date.now()) {
   ]);
   return {
     format: 'acms-backup' as const, version: 5, exportedAt: new Date(now).toISOString(),
-    settings: { ...settings, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false } },
+    settings: { ...settings, live: { ...settings.live, mode: 'off' as const, manual: { watchUrl: '', title: 'We’re live', until: 0 } }, ai: { ...settings.ai, enabled: false, encryptedKey: '' }, agent: { ...settings.agent, enabled: false, keyHash: '', keyPrefix: '', allowPublish: false } },
     pages, posts, media, links, tags, navItems, users, redirects,
     calendars: calendars.map(c => ({ ...c, feedToken: '' })), events,
     resources: resources.map(r => ({ ...r, feedToken: '' })), bookingLinks, ...bookingState,

package/src/lib/embeds.ts

@@ -0,0 +1,50 @@
+// Embeddable-URL detection shared by the editor's embed card (paste →
+// card) and the importers (a Ghost/WordPress embed → embedCard markup).
+export interface EmbedInfo {
+  provider: string;
+  embedSrc: string;
+  aspect: boolean; // true → 16:9, false → fixed height
+}
+
+export function detectEmbed(raw: string): EmbedInfo | null {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  const host = url.hostname.replace(/^www\./, '');
+  if (host === 'youtube.com' || host === 'm.youtube.com' || host === 'youtu.be' || host === 'youtube-nocookie.com') {
+    const id =
+      host === 'youtu.be'
+        ? url.pathname.slice(1).split('/')[0]
+        : url.pathname.startsWith('/shorts/') || url.pathname.startsWith('/embed/') || url.pathname.startsWith('/live/')
+          ? url.pathname.split('/')[2]
+          : url.searchParams.get('v');
+    // keep a start offset (?start=90, ?t=1h2m3s) — sermon and talk links
+    // usually point into the middle of a stream
+    const start = youtubeStart(url.searchParams.get('start') ?? url.searchParams.get('t'));
+    if (id) return { provider: 'youtube', embedSrc: `https://www.youtube-nocookie.com/embed/${id}${start ? `?start=${start}` : ''}`, aspect: true };
+  }
+  if (host === 'vimeo.com' || host === 'player.vimeo.com') {
+    const id = url.pathname.split('/').filter(Boolean).pop();
+    if (id && /^\d+$/.test(id)) return { provider: 'vimeo', embedSrc: `https://player.vimeo.com/video/${id}`, aspect: true };
+  }
+  if (host === 'loom.com' && url.pathname.startsWith('/share/')) {
+    return { provider: 'loom', embedSrc: `https://www.loom.com/embed/${url.pathname.split('/')[2]}`, aspect: true };
+  }
+  if (host === 'codepen.io' && url.pathname.includes('/pen/')) {
+    return { provider: 'codepen', embedSrc: raw.replace('/pen/', '/embed/'), aspect: false };
+  }
+  if (url.protocol === 'https:') {
+    return { provider: 'iframe', embedSrc: raw, aspect: false };
+  }
+  return null;
+}
+
+function youtubeStart(raw: string | null): number {
+  if (!raw) return 0;
+  if (/^\d+s?$/.test(raw)) return parseInt(raw, 10);
+  const m = raw.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/);
+  return m ? Number(m[1] ?? 0) * 3600 + Number(m[2] ?? 0) * 60 + Number(m[3] ?? 0) : 0;
+}

package/src/lib/live/client.ts

@@ -0,0 +1,88 @@
+import type { PublicLiveSnapshot } from './types';
+
+// One status poller per page, shared by every live surface (cards, the live
+// bar, header marker, dock). Subscribers are tied to an element and dropped
+// once it leaves the DOM (view transitions swap the body).
+//
+// It also mirrors the state onto <html data-live="live|upcoming"> so themes
+// can style anything (an avatar ring, a nav item) without extra markup.
+
+type Listener = (s: PublicLiveSnapshot | null, serverNow: number) => void;
+
+let snapshot: PublicLiveSnapshot | null = null;
+let offset = 0;
+let loaded = false;
+let pending = false;
+let timers: ReturnType<typeof setInterval>[] = [];
+const listeners = new Map<Listener, Element>();
+
+export const serverNow = () => Date.now() + offset;
+
+// a successful observation stops counting as live once it expires, even if
+// every later refresh fails; expiresAt 0 = no expiry (offline fallback)
+function current(): PublicLiveSnapshot | null {
+  if (snapshot && snapshot.expiresAt > 0 && snapshot.expiresAt <= serverNow()) return null;
+  return snapshot;
+}
+
+let shown: PublicLiveSnapshot | null | undefined;
+function emit(force = false) {
+  const s = current();
+  if (!force && s === shown) return;
+  shown = s;
+  const status = s?.status === 'live' || s?.status === 'upcoming' ? s.status : '';
+  if (status) document.documentElement.dataset.live = status;
+  else delete document.documentElement.dataset.live;
+  for (const [fn, el] of listeners) {
+    if (!el.isConnected) { listeners.delete(fn); continue; }
+    fn(s, serverNow());
+  }
+}
+
+async function refresh() {
+  if (pending || document.hidden || !listeners.size) return;
+  pending = true;
+  try {
+    const r = await fetch('/api/live/status', { cache: 'no-store', signal: AbortSignal.timeout(10_000) });
+    if (!r.ok) return;
+    const data = await r.json();
+    if (typeof data.serverNow !== 'number' || !('snapshot' in data)) return;
+    offset = data.serverNow - Date.now();
+    snapshot = data.snapshot;
+    loaded = true;
+    emit(true);
+  } catch {
+    /* keep the last snapshot only until it expires */
+  } finally {
+    pending = false;
+  }
+}
+
+function start() {
+  if (timers.length) return;
+  timers = [
+    setInterval(() => {
+      if (![...listeners.values()].some((el) => el.isConnected)) return;
+      emit();
+    }, 1000),
+    setInterval(refresh, 30_000),
+  ];
+  document.addEventListener('visibilitychange', () => { if (!document.hidden) void refresh(); });
+  window.addEventListener('focus', () => void refresh());
+}
+
+// `initial` is the server-rendered state (live cards embed it); without it the
+// first subscriber triggers a fetch.
+export function subscribeLive(el: Element, fn: Listener, initial?: { snapshot: PublicLiveSnapshot | null; serverNow: number }) {
+  if (initial && !loaded) {
+    offset = initial.serverNow - Date.now();
+    snapshot = initial.snapshot;
+    loaded = true;
+  }
+  listeners.set(fn, el);
+  start();
+  if (loaded) emit(true);
+  else void refresh();
+}
+
+export const currentLive = current;

package/src/lib/live/crypto.ts

@@ -0,0 +1,28 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import { env } from '../env';
+import { ApiError } from '../api';
+function key(locals?: unknown) {
+  const runtime = (locals as { runtime?: { env?: Record<string, unknown> } } | undefined)?.runtime?.env;
+  const secret = String(runtime?.LIVE_ENCRYPTION_KEY || env('LIVE_ENCRYPTION_KEY') || runtime?.SESSION_SECRET || env('SESSION_SECRET'));
+  if (secret.length < 32) throw new ApiError(503, 'Set LIVE_ENCRYPTION_KEY or SESSION_SECRET to at least 32 random characters on your host before storing live credentials.');
+  return createHash('sha256').update(`acms:live:v1:${secret}`).digest();
+}
+export const hash = (value: string) => createHash('sha256').update(value).digest('hex');
+export const randomToken = () => randomBytes(32).toString('base64url');
+export function encryptionReady(locals?: unknown) { try { key(locals); return true; } catch { return false; } }
+export function encrypt(value: unknown, context: string, locals?: unknown) {
+  const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', key(locals), iv);
+  cipher.setAAD(Buffer.from(`acms:live:${context}`));
+  const data = Buffer.concat([cipher.update(JSON.stringify(value), 'utf8'), cipher.final()]);
+  return [iv, cipher.getAuthTag(), data].map(v => v.toString('base64url')).join('.');
+}
+export function decrypt<T>(encrypted: string, context: string, locals?: unknown): T {
+  try {
+    const parts = encrypted.split('.');
+    if (parts.length !== 3) throw new Error();
+    const [iv, tag, data] = parts.map(v => Buffer.from(v, 'base64url'));
+    const cipher = createDecipheriv('aes-256-gcm', key(locals), iv);
+    cipher.setAAD(Buffer.from(`acms:live:${context}`)); cipher.setAuthTag(tag);
+    return JSON.parse(Buffer.concat([cipher.update(data), cipher.final()]).toString('utf8'));
+  } catch { throw new ApiError(503, 'Saved live credentials cannot be decrypted. Re-enter the credentials and reconnect.'); }
+}

package/src/lib/live/migration.ts

@@ -0,0 +1,15 @@
+export const LIVE_MIGRATION = { version: 34, statements: [
+  `ALTER TABLE settings ADD COLUMN live TEXT NOT NULL DEFAULT '{}'`,
+  `CREATE TABLE live_connections (
+    provider TEXT PRIMARY KEY CHECK(provider IN ('youtube','twitch')),
+    client_id TEXT NOT NULL, channel_input TEXT NOT NULL DEFAULT '', channel_id TEXT NOT NULL DEFAULT '', channel_name TEXT NOT NULL DEFAULT '',
+    encrypted TEXT NOT NULL, enabled INTEGER NOT NULL DEFAULT 0, revision INTEGER NOT NULL DEFAULT 1,
+    channels TEXT NOT NULL DEFAULT '[]', google_status TEXT NOT NULL DEFAULT 'testing', tested_at INTEGER NOT NULL DEFAULT 0,
+    checked_at INTEGER NOT NULL DEFAULT 0, last_attempt_at INTEGER NOT NULL DEFAULT 0, next_at INTEGER NOT NULL DEFAULT 0,
+    failures INTEGER NOT NULL DEFAULT 0, error TEXT NOT NULL DEFAULT '', lease TEXT NOT NULL DEFAULT '', lease_until INTEGER NOT NULL DEFAULT 0,
+    snapshot TEXT, upcoming TEXT, upcoming_checked_at INTEGER NOT NULL DEFAULT 0
+  )`,
+  `CREATE TABLE live_oauth_states (hash TEXT PRIMARY KEY, session_hash TEXT NOT NULL, revision INTEGER NOT NULL, encrypted TEXT NOT NULL, expires_at INTEGER NOT NULL)`,
+  `CREATE TABLE live_health (id INTEGER PRIMARY KEY CHECK(id=1), last_at INTEGER NOT NULL DEFAULT 0)`,
+  `INSERT INTO live_health (id) VALUES (1)`,
+] };

package/src/lib/live/providers.ts

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+import { readResponseJson } from '../api';
+import { emptySnapshot, type Channel, type Connection, type Credentials, type LiveSnapshot, type Provider } from './types';
+
+export class ProviderError extends Error {
+  constructor(public code: 'auth' | 'quota' | 'unavailable' | 'channel' | 'invalid', message: string, public retryAfter = 0) { super(message); }
+}
+const tokenSchema = z.object({ access_token: z.string().min(1).max(8192), expires_in: z.number().positive(), refresh_token: z.string().max(8192).optional(), scope: z.union([z.string(),z.array(z.string()).transform(v=>v.join(' '))]).optional() });
+const idText = z.string().max(200);
+const ytItem = z.object({ id: idText, snippet: z.object({ channelId: idText.optional(), title: z.string().max(1000), actualStartTime: z.string().optional(), scheduledStartTime: z.string().optional() }), status: z.object({ lifeCycleStatus: z.string().optional(), privacyStatus: z.string().optional() }).optional() });
+const ytPage = z.object({ items: z.array(ytItem).max(50), nextPageToken: z.string().max(1000).optional() });
+const twitchPage = z.object({ data: z.array(z.object({ id: idText, user_id: idText, user_login: idText, user_name: idText.optional(), title: z.string().max(1000), type: z.string(), started_at: z.string(), viewer_count: z.number().int().nonnegative().optional() })).max(100) });
+
+async function request(url: string | URL, init: RequestInit, signal: AbortSignal): Promise<unknown> {
+  try {
+    const r = await fetch(url, { ...init, redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]) });
+    const body = await readResponseJson(r, 512_000).catch(() => null);
+    if (!r.ok) {
+      const detail = z.object({ error: z.union([z.string(), z.object({ errors: z.array(z.object({ reason: z.string() })).optional() })]).optional() }).safeParse(body);
+      const error = detail.success ? detail.data.error : undefined;
+      const quota = r.status === 429 || (typeof error === 'object' && error.errors?.some(e => ['quotaExceeded','dailyLimitExceeded','rateLimitExceeded','userRateLimitExceeded'].includes(e.reason)));
+      if (quota) {
+        const header = r.headers.get('retry-after');
+        const seconds = header && /^\d+$/.test(header) ? Number(header) : header ? (Date.parse(header)-Date.now())/1000 : 0;
+        const reset = Number(r.headers.get('ratelimit-reset') || 0)*1000-Date.now();
+        throw new ProviderError('quota', 'Provider quota or rate limit reached. Check your developer console; automatic checks will retry later.', Math.min(86400_000, Math.max(60_000,Number.isFinite(seconds)?seconds*1000:0,Number.isFinite(reset)?reset:0)));
+      }
+      if (r.status === 401 || r.status === 403 || error === 'invalid_grant' || error === 'invalid_client') throw new ProviderError('auth', 'Access was rejected. Check the saved credentials and authorize again if required.');
+      throw new ProviderError('unavailable', `The provider could not complete the check (HTTP ${r.status}).`);
+    }
+    if (!body) throw new ProviderError('unavailable', 'The provider returned an invalid response.');
+    return body;
+  } catch (e) {
+    if (e instanceof ProviderError) throw e;
+    throw new ProviderError('unavailable', 'The provider did not respond in time. Automatic checks will retry.');
+  }
+}
+const google = (path: string, params: Record<string,string>) => {
+  const url = new URL(`https://www.googleapis.com/youtube/v3/${path}`);
+  Object.entries(params).forEach(([k,v]) => url.searchParams.set(k,v)); return url;
+};
+const bearer = (token: string) => ({ Authorization: `Bearer ${token}` });
+async function validateTwitchToken(clientId: string, creds: Credentials, signal: AbortSignal) {
+  const token = z.object({ client_id: z.string(), expires_in: z.number().nonnegative() }).parse(
+    await request('https://id.twitch.tv/oauth2/validate', { headers: bearer(creds.accessToken!) }, signal),
+  );
+  if (token.client_id !== clientId || token.expires_in <= 60) throw new ProviderError('auth', 'The Twitch token needs renewal.');
+  creds.tokenValidatedAt = Date.now();
+  creds.tokenExpiresAt = Date.now() + token.expires_in * 1000;
+}
+async function getToken(provider: Provider, clientId: string, creds: Credentials, signal: AbortSignal) {
+  if (creds.accessToken && (creds.tokenExpiresAt ?? 0) > Date.now()+60_000) {
+    if (provider !== 'twitch' || (creds.tokenValidatedAt ?? 0) > Date.now()-3600_000) return;
+    try { await validateTwitchToken(clientId, creds, signal); return; }
+    catch (error) {
+      if (!(error instanceof ProviderError) || error.code !== 'auth') throw error;
+      creds.accessToken = ''; creds.tokenExpiresAt = 0;
+    }
+  }
+  const body = new URLSearchParams({ client_id:clientId,client_secret:creds.clientSecret });
+  if (provider === 'twitch') body.set('grant_type','client_credentials');
+  else {
+    if (!creds.refreshToken) throw new ProviderError('auth', 'Authorize YouTube before testing this connection.');
+    body.set('grant_type','refresh_token'); body.set('refresh_token',creds.refreshToken);
+  }
+  // Twitch returns scope as an array on some flows; the client-credentials flow needs neither scope nor refresh token.
+  const data = await request(provider === 'twitch' ? 'https://id.twitch.tv/oauth2/token' : 'https://oauth2.googleapis.com/token', { method:'POST',body },signal);
+  const token = tokenSchema.parse(data);
+  creds.accessToken = token.access_token; creds.tokenExpiresAt = Date.now()+token.expires_in*1000;
+  if (token.refresh_token) creds.refreshToken = token.refresh_token;
+  if (provider === 'twitch') await validateTwitchToken(clientId, creds, signal);
+}
+async function authenticated<T>(conn: Connection, creds: Credentials, signal: AbortSignal, run: () => Promise<T>) {
+  await getToken(conn.provider,conn.clientId,creds,signal);
+  try { return await run(); }
+  catch (e) {
+    if (!(e instanceof ProviderError) || e.code !== 'auth') throw e;
+    creds.accessToken=''; creds.tokenExpiresAt=0;
+    await getToken(conn.provider,conn.clientId,creds,signal);
+    return run(); // One retry, never an unbounded token loop.
+  }
+}
+export function twitchLogin(value: string) {
+  let login = value.trim().toLowerCase();
+  if (/^https?:/i.test(login)) {
+    try { const u=new URL(login); if (u.protocol !== 'https:' || !['twitch.tv','www.twitch.tv'].includes(u.hostname) || u.username || u.password || u.search || u.hash) throw new Error(); login=u.pathname.replace(/^\/|\/$/g,''); }
+    catch { throw new ProviderError('channel','Enter a Twitch channel username or its HTTPS channel URL.'); }
+  }
+  if (!/^[a-z0-9_]{1,25}$/.test(login)) throw new ProviderError('channel','Enter a Twitch channel username or its HTTPS channel URL.');
+  return login;
+}
+export async function channels(conn: Connection, creds: Credentials, signal: AbortSignal): Promise<Channel[]> {
+  return authenticated(conn,creds,signal,async () => {
+    if (conn.provider === 'twitch') {
+      const u=new URL('https://api.twitch.tv/helix/users'); u.searchParams.set('login',twitchLogin(conn.channelInput));
+      const data=z.object({data:z.array(z.object({id:idText,display_name:idText})).max(100)}).parse(await request(u,{headers:{...bearer(creds.accessToken!), 'Client-Id':conn.clientId}},signal));
+      if (!data.data.length) throw new ProviderError('channel','That Twitch channel was not found. Check the username.');
+      return data.data.map(c => ({id:c.id,name:c.display_name}));
+    }
+    const result:Channel[]=[]; let page='';
+    for(let i=0;i<5;i++) {
+      const data=z.object({items:z.array(z.object({id:idText,snippet:z.object({title:idText})})).max(50).default([]),nextPageToken:z.string().optional()}).parse(await request(google('channels',{part:'snippet',mine:'true',maxResults:'50',...(page?{pageToken:page}:{})}),{headers:bearer(creds.accessToken!)},signal));
+      result.push(...data.items.map(c=>({id:c.id,name:c.snippet.title}))); page=data.nextPageToken??''; if (!page) return result;
+    }
+    throw new ProviderError('unavailable','Too many channel results. Connect a Google account with the intended channel identity.');
+  });
+}
+export async function exchangeGoogleCode(clientId:string,clientSecret:string,code:string,verifier:string,callbackUrl:string,signal:AbortSignal):Promise<Credentials> {
+  const token=tokenSchema.parse(await request('https://oauth2.googleapis.com/token',{method:'POST',body:new URLSearchParams({client_id:clientId,client_secret:clientSecret,code,code_verifier:verifier,redirect_uri:callbackUrl,grant_type:'authorization_code'})},signal));
+  if (!token.refresh_token) throw new ProviderError('auth','Google did not provide offline access. Reconnect and approve the read-only permission.');
+  if (!token.scope?.split(' ').includes('https://www.googleapis.com/auth/youtube.readonly')) throw new ProviderError('auth','YouTube read-only permission is required. Reconnect and approve that permission.');
+  return {clientSecret,accessToken:token.access_token,refreshToken:token.refresh_token,tokenExpiresAt:Date.now()+token.expires_in*1000,callbackUrl};
+}
+export async function revoke(provider:Provider,clientId:string,creds:Credentials) {
+  const token=provider==='youtube' ? creds.refreshToken||creds.accessToken : creds.accessToken;
+  if (!token) return;
+  const url=provider==='youtube'?'https://oauth2.googleapis.com/revoke':'https://id.twitch.tv/oauth2/revoke';
+  const body=new URLSearchParams({token,...(provider==='twitch'?{client_id:clientId}:{})});
+  // Revocation is best effort; disconnect always removes local credentials.
+  try { await fetch(url,{method:'POST',body,redirect:'error',signal:AbortSignal.timeout(5_000)}); } catch { /* no provider details in logs */ }
+}
+export async function detect(conn:Connection,creds:Credentials,signal:AbortSignal,upcoming=false):Promise<LiveSnapshot> {
+  return authenticated(conn,creds,signal,async()=>{
+    const now=Date.now();
+    if (!conn.channelId) throw new ProviderError('channel','Choose and test a channel before enabling automatic checks.');
+    if(conn.provider==='twitch') {
+      const u=new URL('https://api.twitch.tv/helix/streams');u.searchParams.set('user_id',conn.channelId);
+      const data=twitchPage.parse(await request(u,{headers:{...bearer(creds.accessToken!), 'Client-Id':conn.clientId}},signal));
+      const stream=data.data.find(s=>s.user_id===conn.channelId&&s.type==='live');
+      if(!stream) return emptySnapshot('twitch',now);
+      const login=twitchLogin(stream.user_login);
+      return {...emptySnapshot('twitch',now),status:'live',id:stream.id,title:stream.title,watchUrl:`https://www.twitch.tv/${login}`,embedId:login,startedAt:Date.parse(stream.started_at)||0,channel:stream.user_name||conn.channelName,viewers:stream.viewer_count};
+    }
+    const found:z.infer<typeof ytItem>[]=[]; let page='';
+    for(let i=0;i<5;i++) {
+      const data=ytPage.parse(await request(google('liveBroadcasts',{part:'snippet,status,contentDetails',broadcastStatus:upcoming?'upcoming':'active',broadcastType:'all',maxResults:'50',...(page?{pageToken:page}:{})}),{headers:bearer(creds.accessToken!)},signal));
+      found.push(...data.items.filter(v=>v.snippet.channelId===conn.channelId && v.status?.privacyStatus==='public' && (upcoming?['created','ready'].includes(v.status?.lifeCycleStatus??''):v.status?.lifeCycleStatus==='live') && /^[\w-]{11}$/.test(v.id)));
+      page=data.nextPageToken??'';if(!page)break;
+      if(i===4)throw new ProviderError('unavailable','Broadcast results exceeded the safe check limit. Narrow the connected channel.');
+    }
+    const start=(v:z.infer<typeof ytItem>)=>Date.parse((upcoming?v.snippet.scheduledStartTime:v.snippet.actualStartTime)??'')||0;
+    found.sort((a,b)=>(upcoming?start(a)-start(b):start(b)-start(a))||a.id.localeCompare(b.id));
+    const item=found[0];if(!item)return emptySnapshot('youtube',now);
+    // Recheck public video visibility and embedding permission before publishing OAuth-derived data.
+    // liveStreamingDetails rides along in the same 1-unit call for the viewer count.
+    const video=z.object({items:z.array(z.object({id:idText,status:z.object({privacyStatus:z.string(),embeddable:z.boolean().optional()}),liveStreamingDetails:z.object({concurrentViewers:z.string().max(20).optional()}).optional()})).default([])}).parse(await request(google('videos',{part:'status,liveStreamingDetails',id:item.id}),{headers:bearer(creds.accessToken!)},signal));
+    const visible=video.items.find(v=>v.id===item.id&&v.status.privacyStatus==='public');
+    if(!visible)return emptySnapshot('youtube',now);
+    const viewers=upcoming?'':visible.liveStreamingDetails?.concurrentViewers?.match(/^\d{1,12}$/)?.[0];
+    return {...emptySnapshot('youtube',now),status:upcoming?'upcoming':'live',id:item.id,title:item.snippet.title,watchUrl:`https://www.youtube.com/watch?v=${item.id}`,embedId:visible.status.embeddable?item.id:'',startedAt:start(item),channel:conn.channelName,...(viewers?{viewers:Number(viewers)}:{})};
+  });
+}