@acms-subir/core 0.3.3-next.20260929113209 → 0.3.3

package/src/lib/mobile/config.mjs

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+
+export const MobileConfig = z.object({
+  ios: z.object({
+    teamId: z.string().regex(/^[A-Z0-9]{10}$/, 'Use a 10-character Apple team ID.'),
+    bundleId: z.string().regex(/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/, 'Use a bundle ID such as com.example.app.'),
+    paths: z.array(z.string().min(1).max(2000).refine(p => /^(?:NOT )?(?:\*|\/[^\r\n]*)$/.test(p), 'Use an absolute path or *, optionally prefixed with NOT.')).max(100).default(['*']),
+  }).strict().optional(),
+  android: z.object({
+    package: z.string().regex(/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+$/, 'Use an Android package such as com.example.app.'),
+    sha256CertFingerprints: z.array(z.string().regex(/^(?:[A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}$/, 'Use a colon-separated SHA-256 certificate fingerprint.').transform(s => s.toUpperCase())).min(1),
+  }).strict().optional(),
+  // Push notifications to the site's own Expo apps. Off unless configured:
+  // true, or { enabled, retentionDays } (devices not seen for that many days are removed).
+  push: z.union([z.boolean(), z.object({
+    enabled: z.boolean().default(true),
+    retentionDays: z.number().int().min(30).max(730).default(270),
+  }).strict()]).optional(),
+  // Editor apps (staff sign in through the browser, OAuth 2.0 + PKCE). Off
+  // unless redirect URIs are listed: only these exact URIs receive codes.
+  editor: z.object({
+    name: z.string().trim().min(1).max(80).optional(),
+    redirectUris: z.array(z.string().max(500).superRefine((uri, ctx) => {
+      const problem = redirectUriProblem(uri);
+      if (problem) ctx.addIssue({ code: z.ZodIssueCode.custom, message: problem });
+    })).min(1).max(20),
+    accessTokenMinutes: z.number().int().min(5).max(24 * 60).default(60),
+    refreshTokenDays: z.number().int().min(1).max(365).default(90),
+  }).strict().optional(),
+}).strict();
+
+const BLOCKED_SCHEMES = new Set(['javascript', 'data', 'vbscript', 'file', 'about', 'blob', 'filesystem', 'ftp', 'ws', 'wss', 'mailto', 'tel', 'sms', 'intent', 'chrome', 'view-source']);
+/** why a redirect URI can't be allowed, or '' (custom scheme, https, or http loopback per RFC 8252) */
+export function redirectUriProblem(uri) {
+  let url;
+  try { url = new URL(uri); } catch { return 'Use an absolute URI such as com.example.staff://auth or https://example.com/app/auth.'; }
+  const scheme = url.protocol.slice(0, -1).toLowerCase();
+  if (url.hash || uri.includes('#')) return 'Redirect URIs cannot contain a fragment.';
+  if (url.username || url.password) return 'Redirect URIs cannot contain credentials.';
+  if (BLOCKED_SCHEMES.has(scheme)) return `The ${scheme}: scheme cannot receive sign-in codes.`;
+  if (scheme === 'http') {
+    const host = url.hostname.replace(/^\[|\]$/g, '');
+    if (!['127.0.0.1', '::1', 'localhost'].includes(host)) return 'http:// is only allowed for loopback addresses (127.0.0.1, [::1], localhost); use https:// or an app scheme.';
+    return '';
+  }
+  if (scheme === 'https') return url.hostname ? '' : 'https:// redirect URIs need a host.';
+  if (!/^[a-z][a-z0-9+.-]*$/.test(scheme)) return 'Invalid URI scheme.';
+  return '';
+}
+
+export function resolveMobile(value) {
+  const result = MobileConfig.safeParse(value === undefined ? {} : value);
+  if (!result.success) throw new Error(`acms: ${result.error.issues.map(i => `mobile.${i.path.join('.')}: ${i.message}`).join('; ')}`);
+  const { push, editor, ...rest } = result.data;
+  const options = typeof push === 'object' ? push : { enabled: push === true, retentionDays: 270 };
+  return { ...rest, push: { enabled: options.enabled, retentionDays: options.retentionDays },
+    editor: editor ? { enabled: true, name: editor.name ?? '', redirectUris: [...new Set(editor.redirectUris)], accessTokenMinutes: editor.accessTokenMinutes, refreshTokenDays: editor.refreshTokenDays }
+      : { enabled: false, name: '', redirectUris: [], accessTokenMinutes: 60, refreshTokenDays: 90 } };
+}

package/src/lib/mobile/content.ts

@@ -10,10 +10,12 @@ import { renderMarkdown } from '../markdown';
 import { blocksToHtml } from '../blocksToHtml';
 import { ApiError } from '../api';
 import { pageQuery, queryParams } from './http';
+import { localizeDoc } from '../translations';
+import { localeQuery, mobileLocale, localizedUrl } from './locale';
 
 export const contentQuery = z.object({
   ...pageQuery, kind: z.enum(['post', 'page']).optional(),
-  collection: z.string().min(1).max(80).optional(), locale: z.string().min(1).max(35).optional(),
+  collection: z.string().min(1).max(80).optional(), locale: localeQuery,
 }).strict();
 export function safeUrl(value: string, origin: string, link = false): string {
   if (!value) return '';
@@ -22,7 +24,7 @@ export function safeUrl(value: string, origin: string, link = false): string {
     return (['http:', 'https:', ...(link ? ['mailto:', 'tel:'] : [])].includes(url.protocol) && !url.username && !url.password) ? url.href : '';
   } catch { return ''; }
 }
-export function mobileHtml(html: string, origin: string) {
+export function mobileHtml(html: string, origin: string, locale: string | null = null) {
   return sanitizeHtml(html, {
     allowedTags: [...sanitizeHtml.defaults.allowedTags, 'img'],
     allowedAttributes: { a: ['href', 'title'], img: ['src', 'alt', 'title', 'width', 'height'], th: ['colspan', 'rowspan'], td: ['colspan', 'rowspan'] },
@@ -30,20 +32,21 @@ export function mobileHtml(html: string, origin: string) {
     allowedSchemesByTag: { img: ['https', 'http'] },
     allowProtocolRelative: false,
     transformTags: {
-      a: (_tag, attrs) => ({ tagName: 'a', attribs: { ...attrs, href: safeUrl(attrs.href ?? '', origin, true) } }),
+      a: (_tag, attrs) => ({ tagName: 'a', attribs: { ...attrs, href: localizedUrl(safeUrl(attrs.href ?? '', origin, true), origin, locale) } }),
       img: (_tag, attrs) => ({ tagName: 'img', attribs: { ...attrs, src: safeUrl(attrs.src ?? '', origin) } }),
     },
   });
 }
 const iso = (n: number | null) => n === null ? null : new Date(n).toISOString();
-function dto(doc: Page | Post, kind: 'page' | 'post', origin: string, detail: boolean) {
+export function contentDto(raw: Page | Post, kind: 'page' | 'post', origin: string, detail: boolean, locale: string | null) {
+  const doc = localizeDoc(raw, locale ?? undefined);
   const post = kind === 'post' ? doc as Post : null;
   const page = kind === 'page' ? doc as Page : null;
   const result = {
     id: doc.id, kind, slug: doc.slug, title: doc.title,
     collection: post?.collection ?? null,
-    locale: page?.locale || I18N.defaultLocale || null,
-    url: safeUrl(post ? collectionUrl(post.collection, post.slug) : page!.isHome ? localeHomeUrl(page!.locale) : `/${page!.slug}`, origin),
+    locale,
+    url: localizedUrl(safeUrl(post ? collectionUrl(post.collection, post.slug) : page!.isHome ? localeHomeUrl(page!.locale) : `/${page!.slug}`, origin), origin, locale),
     excerpt: post?.excerpt ?? page!.seoDesc,
     tags: post ? publicTags(post.tags) : [],
     image: post ? safeUrl(post.cover, origin) : '', imageAlt: post?.coverAlt ?? '',
@@ -53,7 +56,7 @@ function dto(doc: Page | Post, kind: 'page' | 'post', origin: string, detail: bo
   if (!detail) return result;
   // An intentionally empty canonical editor body must not revive legacy text.
   const html = doc.bodyJson ? doc.bodyHtml : doc.bodyHtml || (post ? renderMarkdown(post.body) : blocksToHtml(page!.blocks));
-  return { ...result, content: { format: 'sanitized-html' as const, html: mobileHtml(html, result.url), dynamicWidgets: 'website-only' as const } };
+  return { ...result, content: { format: 'sanitized-html' as const, html: mobileHtml(html, result.url, locale), dynamicWidgets: 'website-only' as const } };
 }
 function visible(doc: Page | Post, kind: 'page' | 'post') {
   return doc.status === 'published' && (kind === 'page' || Object.hasOwn(CONTENT.collections, (doc as Post).collection));
@@ -62,17 +65,19 @@ export async function listContent(repo: ContentRepository, url: URL) {
   const q = contentQuery.parse(queryParams(url));
   if (q.collection && !Object.hasOwn(CONTENT.collections, q.collection)) throw new ApiError(400, 'Unknown collection.');
   if (q.collection && q.kind === 'page') throw new ApiError(400, 'Pages do not belong to post collections.');
-  if (q.locale && !I18N.locales.includes(q.locale)) throw new ApiError(400, 'Unknown locale.');
+  const locale = mobileLocale(q.locale);
   const origin = siteOrigin(await repo.getSettings(), url);
-  const rows = await repo.listPublicContent({ ...q, collections: Object.keys(CONTENT.collections), defaultLocale: I18N.defaultLocale });
+  const rows = await repo.listPublicContent({ ...q, locale: undefined, collections: Object.keys(CONTENT.collections), defaultLocale: I18N.defaultLocale });
   const items = await Promise.all(rows.slice(0, q.limit).map(async (r) => {
     const doc = r.kind === 'post' ? await repo.getPost(r.id) : await repo.getPage(r.id);
-    return doc && visible(doc, r.kind) ? dto(doc, r.kind, origin, false) : null;
+    return doc && visible(doc, r.kind) ? contentDto(doc, r.kind, origin, false, locale) : null;
   }));
-  return { items: items.filter((x) => x !== null), pagination: { page: q.page, limit: q.limit, nextPage: rows.length > q.limit ? q.page + 1 : null } };
+  return { locale, items: items.filter((x) => x !== null), pagination: { page: q.page, limit: q.limit, nextPage: rows.length > q.limit ? q.page + 1 : null } };
 }
+export const contentDetailQuery = z.object({ kind: z.enum(['post', 'page']).optional(), locale: localeQuery }).strict();
 export async function getContent(repo: ContentRepository, url: URL, id: string) {
-  const q = z.object({ kind: z.enum(['post', 'page']).optional() }).strict().parse(queryParams(url));
+  const q = contentDetailQuery.parse(queryParams(url));
+  const locale = mobileLocale(q.locale);
   // IDs are UUIDs, but restored databases may contain arbitrary legacy IDs.
   if (!id || id.length > 200) throw new ApiError(404, 'Content not found.');
   const post = q.kind === 'page' ? null : await repo.getPost(id);
@@ -81,5 +86,5 @@ export async function getContent(repo: ContentRepository, url: URL, id: string)
   const kind = post ? 'post' : 'page';
   const doc = post ?? page;
   if (!doc || !visible(doc, kind)) throw new ApiError(404, 'Content not found.');
-  return dto(doc, kind, siteOrigin(await repo.getSettings(), url), true);
+  return contentDto(doc, kind, siteOrigin(await repo.getSettings(), url), true, locale);
 }

package/src/lib/mobile/embed.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import { ApiError } from '../api';
+import { getTheme } from '../theme';
+import { wallNow } from '../sections';
+import { I18N } from '../i18n';
+import { localeQuery, mobileLocale } from './locale';
+import { queryParams } from './http';
+import { publishedPage, visibleSection } from './pages';
+
+// One published section as its own chrome-less document, for apps that have
+// no native component for it (GET /embed/section/<page|home>/<sectionId>).
+// The same visitor rules as the website and /api/v1/pages apply: a hidden,
+// off-schedule, invalid or unknown section is a 404, never a preview.
+
+export const embedQuery = z.object({ locale: localeQuery, scheme: z.enum(['light', 'dark']).optional() }).strict();
+
+export interface EmbedSection {
+  /** The page to hand to ThemeSections (the language's own home when it has one). */
+  page: NonNullable<Awaited<ReturnType<ContentRepository['getPage']>>>;
+  /** Settings whose layout for that page holds only the requested section. */
+  settings: Awaited<ReturnType<ContentRepository['getSettings']>>;
+  sectionId: string;
+  type: string;
+  /** Language to render in (the site default when none was asked for). */
+  locale: string;
+  scheme?: 'light' | 'dark';
+}
+
+export async function embedSection(repo: ContentRepository, url: URL, path: string, now = Date.now()): Promise<EmbedSection> {
+  const q = embedQuery.safeParse(queryParams(url));
+  if (!q.success) throw new ApiError(400, 'Invalid request parameters.');
+  const locale = mobileLocale(q.data.locale);
+  const parts = path.split('/').filter(Boolean);
+  const sectionId = parts.pop() ?? '';
+  const slug = parts.join('/');
+  if (!slug || !sectionId || path.length > 600) throw new ApiError(404, 'Section not found.');
+  const settings = await repo.getSettings();
+  const page = await publishedPage(repo, settings, slug, locale).catch(() => { throw new ApiError(404, 'Section not found.'); });
+  const layout = settings.sectionPages[page.id];
+  const stored = layout?.mode === 'sections' ? layout.sections.find((s) => s.id === sectionId) : undefined;
+  const section = stored && visibleSection(getTheme(settings.activeTheme), stored, wallNow(settings.timezone || 'UTC', now));
+  if (!layout || !stored || !section) throw new ApiError(404, 'Section not found.');
+  return {
+    page, sectionId, type: section.type, scheme: q.data.scheme,
+    locale: locale ?? I18N.defaultLocale ?? '',
+    settings: { ...settings, sectionPages: { ...settings.sectionPages, [page.id]: { ...layout, mode: 'sections', sections: [stored] } } },
+  };
+}
+
+/**
+ * Reports the section's height and hands link taps to the app instead of
+ * navigating: React Native WebView (window.ReactNativeWebView) or, on the
+ * web, the parent window of the iframe. Messages carry only public data.
+ */
+export function embedBridgeScript(sectionId: string): string {
+  return `(function () {
+  var id = ${JSON.stringify(sectionId).replace(/</g, '\\u003c')};
+  var post = function (msg) {
+    msg.acmsSection = id;
+    if (window.ReactNativeWebView) window.ReactNativeWebView.postMessage(JSON.stringify(msg));
+    else if (window.parent !== window) window.parent.postMessage(msg, '*');
+  };
+  var root = document.getElementById('acms-embed');
+  var last = 0;
+  var send = function () {
+    var h = Math.ceil(root.getBoundingClientRect().height);
+    if (h !== last) { last = h; post({ type: 'height', height: h }); }
+  };
+  document.addEventListener('click', function (e) {
+    var a = e.target && e.target.closest ? e.target.closest('a[href]') : null;
+    if (!a) return;
+    var raw = a.getAttribute('href') || '';
+    if (!raw || raw.charAt(0) === '#') return;
+    e.preventDefault();
+    post({ type: 'navigate', href: a.href });
+  }, true);
+  if (window.ResizeObserver) new ResizeObserver(send).observe(root);
+  window.addEventListener('load', send);
+  document.addEventListener('toggle', send, true);
+  send();
+})();`;
+}

package/src/lib/mobile/http.ts

@@ -6,8 +6,9 @@ import type { ContentRepository } from '../repo/types';
 
 const headers = {
   'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, HEAD, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Idempotency-Key, If-None-Match',
+  'Access-Control-Allow-Methods': 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS',
+  // Authorization carries editor-app bearer tokens; no route reads cookies
+  'Access-Control-Allow-Headers': 'Authorization, Content-Type, Idempotency-Key, If-None-Match',
   'Access-Control-Expose-Headers': 'ETag, Retry-After, Idempotency-Replayed',
   'X-Content-Type-Options': 'nosniff',
   'Cache-Control': 'no-store',
@@ -18,8 +19,8 @@ export const response = (data: unknown, status = 200, extra: HeadersInit = {}) =
   new Headers(extra).forEach((value, key) => h.set(key, value));
   return Response.json({ version: 1, data }, { status, headers: h });
 };
-export async function publicResponse(request: Request, data: unknown) {
-  const res = response(data);
+export async function publicResponse(request: Request, data: unknown, raw = false) {
+  const res = raw ? Response.json(data, { headers }) : response(data);
   const etag = `"${await sha256Hex(await res.clone().text())}"`;
   res.headers.set('ETag', etag);
   // Revalidate even fresh-looking content: unpublishing must take effect.
@@ -29,12 +30,13 @@ export async function publicResponse(request: Request, data: unknown) {
 }
 export function failure(error: unknown) {
   const status = error instanceof ApiError || error instanceof BookingError ? error.status : error instanceof z.ZodError ? 400 : 500;
-  const codes: Record<number, string> = { 400: 'invalid_request', 404: 'not_found', 405: 'method_not_allowed', 409: 'conflict', 410: 'gone', 413: 'payload_too_large', 415: 'unsupported_media_type', 429: 'rate_limited' };
+  const codes: Record<number, string> = { 400: 'invalid_request', 401: 'unauthorized', 403: 'forbidden', 404: 'not_found', 405: 'method_not_allowed', 409: 'conflict', 410: 'gone', 413: 'payload_too_large', 415: 'unsupported_media_type', 429: 'rate_limited', 502: 'upstream_error' };
   return Response.json({ version: 1, error: {
     code: codes[status] ?? 'internal_error',
     message: status === 500 ? 'Request failed. Please try again.' : error instanceof z.ZodError ? 'Invalid request parameters.' : (error as Error).message,
     ...(error instanceof z.ZodError ? { issues: error.issues.map(({ path, message }) => ({ path, message })) } : {}),
-  } }, { status, headers: { ...headers, ...(status === 429 ? { 'Retry-After': '60' } : {}) } });
+  } }, { status, headers: { ...headers, ...(status === 429 ? { 'Retry-After': '60' } : {}),
+    ...(status === 401 ? { 'WWW-Authenticate': 'Bearer realm="acms", error="invalid_token"' } : {}) } });
 }
 export async function limitRequest(repo: ContentRepository, address: string, write = false) {
   const key = `mobile:${write ? 'write' : 'read'}:${await sha256Hex(address)}`;

package/src/lib/mobile/locale.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { ApiError } from '../api';
+import { I18N, localePath } from '../i18n';
+
+export const localeQuery = z.string().min(1).max(35).optional();
+export function mobileLocale(value?: string) {
+  if (value && !I18N.locales.includes(value)) throw new ApiError(400, 'Unknown locale.');
+  return value ?? (I18N.defaultLocale || null);
+}
+export function localizedUrl(value: string, origin: string, locale: string | null) {
+  if (!value || !locale) return value;
+  try {
+    const url = new URL(value, origin);
+    if (url.origin !== new URL(origin).origin || /^\/(?:_|(?:media|api|admin|go)(?:\/|$))|\.[a-z0-9]+$/i.test(url.pathname)) return value;
+    url.pathname = localePath(url.pathname, locale);
+    return url.href;
+  } catch { return value; }
+}

package/src/lib/mobile/openapi.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import type { ContentRepository } from '../repo/types';
+import { contentQuery, contentDetailQuery } from './content';
+import { eventsQuery, availabilityQuery } from './calendar';
+import { bookingInput } from './bookings';
+import { pagesQuery } from './pages';
+import { deviceInput, deviceUpdate } from '../push/api';
+import { pageQuery, queryParams } from './http';
+import * as schemas from './schemas';
+import { editorPaths, editorSchemas, editorSecuritySchemes } from '../editor/openapi';
+
+const jsonSchema = (schema: z.ZodTypeAny) => {
+  const { $schema, ...json } = zodToJsonSchema(schema, { $refStrategy: 'none', target: 'jsonSchema7' });
+  return json;
+};
+const ref = (name: string) => ({ $ref: `#/components/schemas/${name}` });
+const media = (schema: unknown) => ({ 'application/json': { schema } });
+const envelope = (schema: unknown) => ({ type: 'object', required: ['version', 'data'], properties: { version: { const: 1 }, data: schema } });
+const empty = z.object({}).strict();
+const readHeaders = {
+  ETag: { schema: { type: 'string' } }, 'Cache-Control': { schema: { type: 'string' } },
+  'Access-Control-Allow-Origin': { schema: { type: 'string', const: '*' } },
+};
+const errors = Object.fromEntries([400, 404, 405, 429, 500].map(status => [status, {
+  description: status === 429 ? 'Read limit exceeded (300/minute/client address).' : 'Request failed.', content: media(ref('Error')),
+  ...(status === 429 ? { headers: { 'Retry-After': { schema: { type: 'string', const: '60' } } } } : {}),
+}]));
+function parameters(query: z.AnyZodObject) {
+  return Object.entries(query.shape).map(([name, schema]) => ({ name, in: 'query', required: !(schema as z.ZodTypeAny).isOptional(), schema: jsonSchema(schema as z.ZodTypeAny) }));
+}
+export async function getOpenApi(_repo: ContentRepository, url: URL) {
+  empty.parse(queryParams(url));
+  const paths: Record<string, unknown> = {};
+  const reads: [string, string, z.AnyZodObject, unknown, boolean?][] = [
+    ['/site', 'Site identity, navigation, languages and features', empty, ref('Site')],
+    ['/theme', 'Active Design tokens including overrides', empty, ref('Theme')],
+    ['/pages/home', 'Published home page and resolved sections', pagesQuery, ref('Page')],
+    ['/pages/{slug}', 'Published page and resolved sections (slug may contain slashes)', pagesQuery, ref('Page')],
+    ['/content', 'Published content in the requested language', contentQuery, jsonSchema(z.object({ locale: z.string().nullable(), items: z.array(schemas.ContentSummary), pagination: schemas.Pagination }))],
+    ['/content/{id}', 'Published content detail', contentDetailQuery, ref('Content')],
+    ['/events', 'Public event occurrences; requires calendar', eventsQuery, ref('Events')],
+    ['/calendars', 'Public calendars; requires calendar', empty, ref('Calendars')],
+    ['/resources', 'Public resources and booking links; requires bookings', z.object(pageQuery).strict(), ref('Resources')],
+    ['/availability', 'Current availability; requires bookings', availabilityQuery, ref('Availability'), false],
+    ['/push/topics', 'Topics an app can offer as notification toggles; requires push', empty, ref('PushTopics')],
+    ['/openapi.json', 'OpenAPI 3.1 document (no v1 envelope)', empty, { type: 'object', required: ['openapi', 'info', 'paths', 'components'] }],
+  ];
+  for (const [path, summary, query, schema, cache = true] of reads) {
+    const params: unknown[] = parameters(query);
+    for (const match of path.matchAll(/\{(\w+)\}/g)) params.push({ name: match[1], in: 'path', required: true, schema: { type: 'string' } });
+    if (cache) params.push({ name: 'If-None-Match', in: 'header', schema: { type: 'string' } });
+    const responses = { ...errors, 200: { description: 'Success.', headers: readHeaders, content: media(path === '/openapi.json' ? schema : envelope(schema)) },
+      ...(cache ? { 304: { description: 'Unchanged (no body).', headers: readHeaders } } : {}),
+    };
+    paths[`/api/v1${path}`] = {
+      get: { summary, parameters: params, responses },
+      head: { summary: `Headers for ${summary}`, parameters: params, responses: Object.fromEntries(Object.entries(responses).map(([code, res]) => { const { content, ...headersOnly } = res as { content?: unknown }; return [code, headersOnly]; })) },
+      options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body. Allows GET, HEAD and OPTIONS without credentials.' } } },
+    };
+  }
+  paths['/api/v1/bookings'] = {
+    post: {
+      summary: 'Create a guest booking or replay an existing request; requires bookings',
+      description: '20 attempts/minute/client address. JSON body up to 50,000 bytes. Responses use no-store. Reuse a random UUID v4 once per booking intent.',
+      parameters: [{ name: 'Idempotency-Key', in: 'header', required: true, schema: { type: 'string', format: 'uuid', pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$' } }],
+      requestBody: { required: true, content: media(jsonSchema(bookingInput)) },
+      responses: { ...errors,
+        ...Object.fromEntries([409, 410, 413, 415].map(code => [code, { description: 'Booking request rejected.', content: media(ref('Error')) }])),
+        ...Object.fromEntries([200, 201].map(code => [code, { description: code === 201 ? 'Created.' : 'Idempotent replay.', content: media(envelope(ref('BookingResult'))), headers: { 'Idempotency-Replayed': { schema: { type: 'string', enum: [String(code === 200)] } }, 'Cache-Control': { schema: { type: 'string', const: 'no-store' } } } }])),
+      },
+    },
+    options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } },
+  };
+  const writeErrors = { ...errors, 429: { ...errors[429], description: 'Write limit exceeded (20/minute/client address).' },
+    ...Object.fromEntries([413, 415].map(code => [code, { description: 'Request rejected.', content: media(ref('Error')) }])) };
+  const noStore = { 'Cache-Control': { schema: { type: 'string', const: 'no-store' } } };
+  const tokenParam = { name: 'token', in: 'path', required: true, description: 'The Expo push token, URL-encoded.', schema: { type: 'string' } };
+  const pushNote = 'Requires push (acms({ mobile: { push: true } })); 404 when off. JSON body up to 8,000 bytes. Topic ids come from GET /api/v1/push/topics; unknown ids return 400.';
+  paths['/api/v1/devices'] = {
+    post: {
+      summary: 'Register or refresh this device for push notifications; requires push',
+      description: `${pushNote} Call on every app start: it refreshes lastSeenAt (devices unseen for the retention period, default 270 days, are removed). topics replaces the device's topics; omit it to keep them. Stores the token, platform, language and topics only.`,
+      requestBody: { required: true, content: media(jsonSchema(deviceInput)) },
+      responses: { ...writeErrors, ...Object.fromEntries([200, 201].map(code => [code, { description: code === 201 ? 'Registered.' : 'Refreshed.', headers: noStore, content: media(envelope(ref('DeviceRegistration'))) }])) },
+    },
+    options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } },
+  };
+  paths['/api/v1/devices/{token}'] = {
+    put: {
+      summary: 'Change a registered device’s topics or language; requires push', description: pushNote,
+      parameters: [tokenParam], requestBody: { required: true, content: media(jsonSchema(deviceUpdate)) },
+      responses: { ...writeErrors, 200: { description: 'Updated.', headers: noStore, content: media(envelope(ref('Device'))) } },
+    },
+    delete: {
+      summary: 'Opt this device out of push notifications (idempotent); requires push', description: 'Removes the token. Unknown tokens also succeed.',
+      parameters: [tokenParam],
+      responses: { ...writeErrors, 200: { description: 'Removed.', headers: noStore, content: media(envelope(ref('DeviceRemoved'))) } },
+    },
+    options: { summary: 'Public CORS preflight', responses: { 204: { description: 'No body.' } } },
+  };
+  Object.assign(paths, editorPaths(jsonSchema));
+  return {
+    openapi: '3.1.0', info: { title: 'ACMS Mobile API', version: '1.0.0', description: 'Public API: no authentication. Disabled modules are not registered. Unknown or duplicate query parameters are rejected. locale selects translated words with main-language fallback; unknown locales return 400. Editor API (tag Editor): /api/v1/auth/* and /api/v1/admin/*, registered only when acms({ mobile: { editor } }) is configured; staff sign in through the browser (OAuth 2.0 authorization code + PKCE) and send the device access token as a Bearer header. Cookies never authenticate it.' },
+    tags: [{ name: 'Public', description: 'Visitor apps: no authentication.' }, { name: 'Editor', description: 'Editor apps: device sign-in and the admin API.' }],
+    paths, components: {
+      schemas: Object.fromEntries([...Object.entries(schemas), ...Object.entries(editorSchemas)].map(([name, schema]) => [name, jsonSchema(schema as z.ZodTypeAny)])),
+      securitySchemes: editorSecuritySchemes,
+    },
+  };
+}

package/src/lib/mobile/pages.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import type { Page, Settings } from '../schema';
+import { ApiError } from '../api';
+import { getTheme } from '../theme';
+import { migrateSection, resolveSectionData, wallNow } from '../sections';
+import { sectionIssues } from '../../theme-sdk/contract.mjs';
+import { localizeData, scheduledVisible } from '../../theme-sdk/fields.mjs';
+import { isExtraLocale, localizeDoc } from '../translations';
+import { siteOrigin } from '../seo';
+import { blocksToHtml } from '../blocksToHtml';
+import { contentDto, mobileHtml, safeUrl } from './content';
+import { localeQuery, mobileLocale } from './locale';
+import { queryParams } from './http';
+
+type Theme = ReturnType<typeof getTheme>;
+type StoredSection = NonNullable<Settings['sectionPages'][string]>['sections'][number];
+/** The website's visitor rules: known type, not hidden, inside its schedule, valid main-language data. */
+export function visibleSection(theme: Theme, stored: StoredSection, nowWall: string) {
+  const section = migrateSection(theme, stored);
+  const def = theme.sections[section.type];
+  if (!def || section.hidden || !scheduledVisible(section, nowWall) || sectionIssues({ mode: 'sections', sections: [section] }, theme.sections).length) return null;
+  return section;
+}
+
+export const pagesQuery = z.object({ locale: localeQuery }).strict();
+export async function pageSections(repo: ContentRepository, page: Page, settings: Settings, locale: string | null, now = Date.now()) {
+  const layout = settings.sectionPages[page.id];
+  if (layout?.mode !== 'sections') return [];
+  const theme = getTheme(settings.activeTheme);
+  const localized = isExtraLocale(locale);
+  const view = localized ? { ...settings, locale } : settings;
+  const nowWall = wallNow(settings.timezone || 'UTC', now);
+  const sections = await Promise.all(layout.sections.map(async stored => {
+    const section = visibleSection(theme, stored, nowWall);
+    const def = section && theme.sections[section.type];
+    if (!section || !def) return null;
+    // Validate the main language before overlaying translated words, as on the website.
+    const words = localized && section.translations?.[locale] ? localizeData(def, section.data, section.translations[locale]) : section.data;
+    return { id: section.id, type: section.type, variant: section.variant, data: await resolveSectionData(def, words, { repo, settings: view, now }) };
+  }));
+  return sections.filter(s => s !== null);
+}
+/** A published page by slug; "home" is the homepage (or a language's own legacy home). */
+export async function publishedPage(repo: ContentRepository, settings: Settings, slug: string, locale: string | null) {
+  let raw = slug === 'home' ? await repo.getHomePage() : await repo.getPageBySlug(slug);
+  if (slug === 'home' && isExtraLocale(locale)) {
+    const translated = raw && settings.sectionPages[raw.id]?.sections.some(s => s.translations?.[locale]);
+    const separate = translated ? null : await repo.getHomePage(locale);
+    if (separate?.status === 'published') raw = separate;
+  }
+  if (!raw || raw.status !== 'published') throw new ApiError(404, 'Page not found.');
+  return raw;
+}
+export async function getPage(repo: ContentRepository, url: URL, slug: string) {
+  const q = pagesQuery.parse(queryParams(url));
+  const locale = mobileLocale(q.locale);
+  if (!slug || slug.length > 500) throw new ApiError(404, 'Page not found.');
+  const settings = await repo.getSettings();
+  const raw = await publishedPage(repo, settings, slug, locale);
+  const page = localizeDoc(raw, locale ?? undefined);
+  const origin = siteOrigin(settings, url);
+  const summary = contentDto(raw, 'page', origin, false, locale);
+  const html = page.bodyJson ? page.bodyHtml : page.bodyHtml || blocksToHtml(page.blocks);
+  return {
+    ...summary, body: { format: 'sanitized-html' as const, html: mobileHtml(html, summary.url, locale) },
+    cover: safeUrl(settings.siteCover, origin), seo: { title: page.seoTitle || page.title, description: page.seoDesc },
+    mode: settings.sectionPages[page.id]?.mode === 'sections' ? 'sections' as const : 'content' as const,
+    sections: await pageSections(repo, raw, settings, locale),
+  };
+}

package/src/lib/mobile/route.ts

@@ -2,15 +2,15 @@ import type { APIRoute } from 'astro';
 import type { ContentRepository } from '../repo/types';
 import { getRepo } from '../repo';
 import { limitRequest, failure, publicResponse, response } from './http';
-export function readRoute(load: (repo: ContentRepository, url: URL, id: string) => Promise<unknown>, cache = true): APIRoute {
+export function readRoute(load: (repo: ContentRepository, url: URL, id: string) => Promise<unknown>, cache = true, raw = false): APIRoute {
   return async context => {
     try {
       const repo = await getRepo(context.locals);
       let address = 'unknown';
       try { address = context.clientAddress || address; } catch { /* adapters without a client address share a bucket */ }
       await limitRequest(repo, address);
-      const data = await load(repo, context.url, context.params.id ?? '');
-      const res = cache ? await publicResponse(context.request, data) : response(data);
+      const data = await load(repo, context.url, context.params.id ?? context.params.slug ?? '');
+      const res = cache ? await publicResponse(context.request, data, raw) : response(data);
       return context.request.method === 'HEAD' ? new Response(null, { status: res.status, headers: res.headers }) : res;
     } catch (error) {
       const res = failure(error);

package/src/lib/mobile/schemas.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { CalEvent, Booking, Calendar, BookingQuestion } from '../schema';
+
+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 });
+export const Site = z.object({
+  name: str, description: str, logo: 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 })), calendar: bool, bookings: bool, search: 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 }),
+  fonts: z.object({ heading: str, body: str, mono: str }), radius: z.enum(['sharp', 'soft', 'round', 'smooth']),
+});
+export const Section = z.object({ id: str, type: str, variant: str, data: z.record(z.unknown()) });
+export const ContentSummary = z.object({
+  id: str, kind: z.enum(['post', 'page']), slug: str, title: str, collection: str.nullable(), locale, url: str,
+  excerpt: str, tags: strings, image: str, imageAlt: str, publishedAt: date.nullable(), createdAt: date, updatedAt: date,
+});
+export const Html = z.object({ format: z.literal('sanitized-html'), html: str });
+export const Content = ContentSummary.extend({ content: Html.extend({ dynamicWidgets: z.literal('website-only') }) });
+export const Post = Content.extend({ kind: z.literal('post'), collection: str });
+export const Page = ContentSummary.extend({
+  kind: z.literal('page'), body: Html, cover: str, seo: z.object({ title: str, description: str }),
+  mode: z.enum(['content', 'sections']), sections: z.array(Section),
+});
+export const Event = CalEvent.pick({
+  id: true, slug: true, title: true, excerpt: true, status: true, cancelled: true, featured: true, start: true, end: true,
+  allDay: true, timezone: true, rrule: true, exdates: true, location: true, cta: true, tags: true, fields: true,
+}).extend({ url: str, icsUrl: str, repeats: str, image: str, imageAlt: str, updatedAt: date,
+  calendars: z.array(z.object({ id: str, slug: str, name: str, color: str })),
+});
+export const Events = z.object({ locale, timezone: str, from: date, to: date, pagination: Pagination,
+  occurrences: z.array(z.object({ id: str, start: date, end: date, allDay: bool, event: Event })),
+});
+export const Calendars = z.object({ calendars: z.array(Calendar.pick({ id: true, slug: true, name: true, color: true, description: true, kind: true, visibility: true }).extend({ feedUrl: str })) });
+export const Resources = z.object({ pagination: Pagination, resources: z.array(z.object({
+  id: str, slug: str, name: str, kind: str, description: str, capacity: z.number(), amenities: strings, photo: str, timezone: str, url: str,
+  links: z.array(z.object({ id: str, slug: str, name: str, description: str, mode: z.enum(['slots', 'day', 'range']), lengths: z.array(z.number()), rules: str,
+    askPhone: bool, autoConfirm: bool, url: str, questions: z.array(BookingQuestion.omit({ help: true })),
+  })),
+})) });
+export const Availability = z.object({ timezone: str, mode: z.enum(['slots', 'day', 'range']), lengths: z.array(z.number()), autoConfirm: bool,
+  days: z.array(z.object({ date: str, slots: z.array(z.object({ start: date, end: date, minutes: z.number() })) })),
+});
+export const BookingResult = z.object({ manageToken: str, booking: Booking.pick({
+  id: true, kind: true, status: true, name: true, email: true, phone: true, seats: true, answers: true, source: true,
+}).extend({ start: date, end: date, resourceId: str.nullable(), linkId: str.nullable(), eventId: str.nullable(), createdAt: date }) });
+export const Device = z.object({
+  token: str, platform: z.enum(['ios', 'android']), locale: str.nullable(), topics: strings, registeredAt: date, lastSeenAt: date,
+});
+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']) })) });
+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

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { ContentRepository } from '../repo/types';
+import { CONTENT } from '../content';
+import { I18N, localeName } from '../i18n';
+import { CALENDAR, bookingsEnabled } from '../calendar/config';
+import { SEARCH } from '../search-config';
+import { siteOrigin } from '../seo';
+import { resolveDesign } from '../theme';
+import { darkPalette } from '../themeTokens';
+import { safeUrl } from './content';
+import { queryParams } from './http';
+
+export async function getSite(repo: ContentRepository, url: URL) {
+  z.object({}).strict().parse(queryParams(url));
+  const [settings, nav, pages] = await Promise.all([repo.getSettings(), repo.listNavItems(), repo.listPages()]);
+  const origin = siteOrigin(settings, url);
+  const header = nav.filter(n => n.area === 'header').sort((a, b) => a.order - b.order);
+  const menu = header.length ? header : [
+    { label: 'Home', url: '/' },
+    ...pages.filter(p => p.status === 'published' && !p.isHome).map(p => ({ label: p.title, url: `/${p.slug}` })),
+    ...Object.values(CONTENT.collections).map(c => ({ label: c.plural, url: c.base })),
+    { label: 'Links', url: '/links' },
+  ];
+  return {
+    name: settings.siteTitle, description: settings.tagline,
+    logo: safeUrl(settings.siteLogo, origin), icon: safeUrl(settings.siteFavicon, origin),
+    menu: menu.map(n => ({ label: n.label, href: safeUrl(n.url, origin, true) })),
+    languages: { default: I18N.defaultLocale || null, locales: I18N.locales.map(code => ({ code, name: localeName(code, true) })) },
+    features: { blog: Object.entries(CONTENT.collections).map(([key, c]) => ({ key, name: c.plural, url: safeUrl(c.base, origin) })), calendar: CALENDAR.enabled, bookings: bookingsEnabled(), search: SEARCH.enabled },
+    apiVersion: 1,
+  };
+}
+export async function getThemeTokens(repo: ContentRepository, url: URL) {
+  z.object({}).strict().parse(queryParams(url));
+  const { theme, tokens: t } = resolveDesign(await repo.getSettings());
+  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) },
+    fonts: { heading: t.headingFont, body: t.bodyFont, mono: t.monoFont }, radius: t.radius,
+  };
+}