@acms-subir/core 0.3.31 → 0.3.32

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @acms-subir/core
 
+## 0.3.32
+
+### Patch Changes
+
+- f1c7635: Sites can add their own push topics, and topic names come in the app's language.
+
+  - **Site topics.** `acms({ mobile: { push: { topics: [{ id: 'help', label: { en: 'Help needed', es: 'Se necesita ayuda' }, description?: … }] } } })`. A single string is used for every language. They're listed after the built-in topics with `kind: 'site'` (and their `description`), devices may choose them, and staff send to them from Admin → Mobile app. Ids are lowercase letters, numbers, `-` and `_`. `news`, `events` and `live` are reserved, and there can be up to 20. Like every topic, they never reach devices that didn't choose them.
+  - **Names in the app's language.** `GET /api/v1/push/topics?locale=es` names the built-in topics in that language (News/Noticias, Events/Eventos, Live video/Video en vivo; also French, German and Portuguese) and uses the site's words for its own. Missing words fall back to the main language, and the response says which `locale` it used.
+  - **Legal links in the app's language.** `GET /api/v1/site?locale=es` returns `legal.privacy` / `legal.terms` for the Spanish pages (`/es/privacy`), so apps no longer add `/es` themselves.
+
+  Unknown locales return 400 on both routes, as on other localized routes.
+
 ## 0.3.31
 
 ### Patch Changes

package/docs/mobile.md

@@ -125,7 +125,7 @@ Read the app's `AGENTS.md` too: it holds the same rules, next to the code.
 | `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) |
+| `usePushRegistration({ topics })` / `usePushTopics()` / `useNewPushTopics()` / `useNotificationTaps()` | push notifications (see Push notifications); topic names come in the app's language |
 | `useAcms()` | the typed client (e.g. `calendars()`) for your own `useQuery` |
 
 Components: `<Sections>`, `<RichText html>`, `<EventDate start end allDay timezone>`,
@@ -301,8 +301,10 @@ 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.
+  `setTopics([...topics, 'live'])` only on yes. `useNewPushTopics({ baseline })`
+  lists the topics added since the person last saw the list (pass `baseline`:
+  the topic ids your older app version offered) and `markSeen()` remembers
+  the answer on the device, so you ask once.
 - 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.

package/integration.mjs

@@ -595,10 +595,13 @@ function acmsVitePlugin(userConfig) {
  *   Home page content per language is authored in /admin as a normal page
  *   marked "home" with that language selected. Omit for monolingual sites —
  *   nothing changes.
- * @param {{ios?: {teamId: string, bundleId: string, paths?: string[]}, android?: {package: string, sha256CertFingerprints: string[]}, push?: boolean | {enabled?: boolean, retentionDays?: number}, editor?: {redirectUris: string[], name?: string, accessTokenMinutes?: number, refreshTokenDays?: number}}} [options.mobile]
+ * @param {{ios?: {teamId: string, bundleId: string, paths?: string[]}, android?: {package: string, sha256CertFingerprints: string[]}, push?: boolean | {enabled?: boolean, retentionDays?: number, topics?: Array<{id: string, label: string | Record<string, string>, description?: string | Record<string, string>}>}, editor?: {redirectUris: string[], name?: string, accessTokenMinutes?: number, refreshTokenDays?: number}}} [options.mobile]
  *   Optional iOS Universal Links and Android App Links associations, and push
  *   notifications for the site's own Expo apps (`push: true`; off by default):
- *   /api/v1/devices, /api/v1/push/topics and Admin → Mobile app. `editor:
+ *   /api/v1/devices, /api/v1/push/topics and Admin → Mobile app. `topics` adds
+ *   the site's own topics (e.g. `{ id: 'help', label: { en: 'Help needed', es:
+ *   'Se necesita ayuda' } }`): apps offer them, staff send to them; they never
+ *   reach devices that didn't choose them. `editor:
  *   { redirectUris, name? }` turns on editor apps: staff sign in through the
  *   browser (/admin/app-auth, OAuth 2.0 + PKCE; only the listed redirect URIs
  *   receive codes) and edit through the bearer-token /api/v1/admin/* API.

package/package.json

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

package/src/lib/mobile/config.mjs

@@ -1,5 +1,17 @@
 import { z } from 'zod';
 
+// words in each site language ({ en: 'Help needed', es: 'Se necesita ayuda' }), or one string for all
+const words = (max) => z.union([z.string().trim().min(1).max(max), z.record(z.string().regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/, 'Use language codes such as en or es-MX.'), z.string().trim().min(1).max(max))
+  .refine((o) => Object.keys(o).length > 0, 'Give at least one language.')]);
+const RESERVED_TOPICS = new Set(['news', 'events', 'live']);
+// a topic the site adds (registrations, help…): offered in the app, sent to from Admin → Mobile app
+const SiteTopic = z.object({
+  id: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,39}$/, 'Use lowercase letters, numbers, - and _ (up to 40), e.g. help or registrations.')
+    .refine((id) => !RESERVED_TOPICS.has(id), 'news, events and live are built-in topics.'),
+  label: words(60),
+  description: words(200).optional(),
+}).strict();
+
 export const MobileConfig = z.object({
   ios: z.object({
     teamId: z.string().regex(/^[A-Z0-9]{10}$/, 'Use a 10-character Apple team ID.'),
@@ -15,6 +27,7 @@ export const MobileConfig = z.object({
   push: z.union([z.boolean(), z.object({
     enabled: z.boolean().default(true),
     retentionDays: z.number().int().min(30).max(730).default(270),
+    topics: z.array(SiteTopic).max(20).refine((ts) => new Set(ts.map((t) => t.id)).size === ts.length, 'Each topic id once.').default([]),
   }).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.
@@ -52,8 +65,11 @@ 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 },
+  const options = typeof push === 'object' ? push : { enabled: push === true, retentionDays: 270, topics: [] };
+  // one string = every language ('*')
+  const all = (w) => (w === undefined ? {} : typeof w === 'string' ? { '*': w } : w);
+  const topics = options.topics.map((t) => ({ id: t.id, label: all(t.label), description: all(t.description) }));
+  return { ...rest, push: { enabled: options.enabled, retentionDays: options.retentionDays, topics },
     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/locale.ts

@@ -3,6 +3,8 @@ import { ApiError } from '../api';
 import { I18N, localePath } from '../i18n';
 
 export const localeQuery = z.string().min(1).max(35).optional();
+/** routes whose only option is the language (/site, /push/topics) */
+export const localeOnlyQuery = z.object({ locale: localeQuery }).strict();
 export function mobileLocale(value?: string) {
   if (value && !I18N.locales.includes(value)) throw new ApiError(400, 'Unknown locale.');
   return value ?? (I18N.defaultLocale || null);

package/src/lib/mobile/openapi.ts

@@ -10,6 +10,7 @@ import { manageAvailabilityQuery, rescheduleInput } from './manage';
 import { formResponseInput } from './forms';
 import { codeInput, tokenInput, myBookingsQuery } from './guest';
 import { deviceInput, deviceUpdate } from '../push/api';
+import { localeOnlyQuery } from './locale';
 import { pageQuery, queryParams } from './http';
 import * as schemas from './schemas';
 import { editorPaths, editorSchemas, editorSecuritySchemes } from '../editor/openapi';
@@ -37,7 +38,7 @@ 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')],
+    ['/site', 'Site identity, navigation, languages, features and legal links (locale: links in that language)', localeOnlyQuery, 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')],
@@ -48,7 +49,7 @@ export async function getOpenApi(_repo: ContentRepository, url: URL) {
     ['/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')],
+    ['/push/topics', 'Topics an app can offer as notification toggles, named in the requested language; requires push', localeOnlyQuery, 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')],

package/src/lib/mobile/schemas.ts

@@ -105,7 +105,7 @@ 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']) })) });
+export const PushTopics = z.object({ locale, topics: z.array(z.object({ id: str, label: str, kind: z.enum(['general', 'collection', 'calendar', 'site']), description: str.optional() })) });
 // 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({

package/src/lib/mobile/site.ts

@@ -9,14 +9,16 @@ import { resolveDesign } from '../theme';
 import { darkPalette, liveColor } from '../themeTokens';
 import { safeUrl } from './content';
 import { queryParams } from './http';
+import { localeOnlyQuery, localizedUrl, mobileLocale } from './locale';
 import { guestSignInReady } from './guest';
 import { LEGAL } from '../legal/config';
 
 export async function getSite(repo: ContentRepository, url: URL, _id = '', locals?: unknown) {
-  z.object({}).strict().parse(queryParams(url));
+  // locale: the legal links point at that language's pages (/es/privacy)
+  const locale = mobileLocale(localeOnlyQuery.parse(queryParams(url)).locale);
   const [settings, nav, pages] = await Promise.all([repo.getSettings(), repo.listNavItems(), repo.listPages()]);
   // the privacy notice and terms: the standard pages, or published pages at those slugs
-  const legalUrl = (slug: 'privacy' | 'terms') => (LEGAL.enabled || pages.some(p => p.status === 'published' && p.slug === slug) ? `${siteOrigin(settings, url)}/${slug}` : null);
+  const legalUrl = (slug: 'privacy' | 'terms') => (LEGAL.enabled || pages.some(p => p.status === 'published' && p.slug === slug) ? localizedUrl(`${siteOrigin(settings, url)}/${slug}`, siteOrigin(settings, url), locale) : null);
   const origin = siteOrigin(settings, url);
   const bases = new Set(Object.values(CONTENT.collections).map(c => c.base));
   const header = nav.filter(n => n.area === 'header').sort((a, b) => a.order - b.order);
@@ -41,7 +43,7 @@ export async function getSite(repo: ContentRepository, url: URL, _id = '', local
       // Integrations → Live video; GET /api/v1/live answers 404 while it's off
       live: settings.live.mode !== 'off',
     },
-    // in another site language, add /<code> after the origin, like every other page
+    // in the requested language (?locale=es → /es/privacy)
     legal: { privacy: legalUrl('privacy'), terms: legalUrl('terms') },
     apiVersion: 1,
   };

package/src/lib/push/api.ts

@@ -8,6 +8,7 @@ import { CONTENT, collectionUrl } from '../content';
 import { CALENDAR, eventUrl } from '../calendar/config';
 import { eventIsListed } from '../calendar/events';
 import { queryParams } from '../mobile/http';
+import { localeOnlyQuery, mobileLocale } from '../mobile/locale';
 import { EXPO_PUSH_BASE, PUSH, requirePush } from './config';
 import { expoOptions } from './expo';
 import { knownTopics, pushTopics, sendNotification, siteOriginOf, type PushRunOptions } from './service';
@@ -72,8 +73,8 @@ export async function unregisterDevice(repo: ContentRepository, rawToken: string
 }
 export async function listPushTopics(repo: ContentRepository, url: URL) {
   requirePush();
-  z.object({}).strict().parse(queryParams(url));
-  return { topics: await pushTopics(repo) };
+  const locale = mobileLocale(localeOnlyQuery.parse(queryParams(url)).locale);
+  return { locale, topics: await pushTopics(repo, locale) };
 }
 
 // ---- admin -------------------------------------------------------------------

package/src/lib/push/config.ts

@@ -1,5 +1,5 @@
 // Push notifications config, set per project via the integration:
-//   acms({ mobile: { push: true } })  or  { push: { enabled: true, retentionDays: 270 } }
+//   acms({ mobile: { push: true } })  or  { push: { enabled: true, retentionDays: 270, topics: [...] } }
 // Off by default. When off, the device/topic endpoints and the admin Mobile
 // app page are not registered at all (like other disabled modules), and the
 // scheduler just marks any queued automatic notifications as skipped.
@@ -10,6 +10,8 @@ import { ApiError } from '../api';
 export const PUSH = {
   enabled: userConfig.mobile?.push?.enabled === true,
   retentionDays: userConfig.mobile?.push?.retentionDays ?? 270,
+  /** topics the site adds (config mobile.push.topics); labels per language, '*' = every language */
+  topics: [...(userConfig.mobile?.push?.topics ?? [])] as Array<{ id: string; label: Record<string, string>; description: Record<string, string> }>,
 };
 
 export function requirePush() {

package/src/lib/push/service.ts

@@ -22,30 +22,51 @@ export const RECEIPT_DELAY = 15 * MINUTE;
 
 // ---- topics ------------------------------------------------------------------
 
+// names of the built-in topics; other languages show English
+const TOPIC_WORDS: Record<string, { news: string; events: string; live: string }> = {
+  en: { news: 'News', events: 'Events', live: 'Live video' },
+  es: { news: 'Noticias', events: 'Eventos', live: 'Video en vivo' },
+  fr: { news: 'Actualités', events: 'Événements', live: 'Vidéo en direct' },
+  de: { news: 'Neuigkeiten', events: 'Veranstaltungen', live: 'Live-Video' },
+  pt: { news: 'Notícias', events: 'Eventos', live: 'Vídeo ao vivo' },
+};
+/** A site topic's words in a language: exact code, its base ("es-MX" → "es"), every language ('*'), the site's main language, then any. */
+export function topicWords(words: Record<string, string>, locale: string): string {
+  const base = locale.toLowerCase().split('-')[0];
+  return words[locale] ?? words[base] ?? words['*'] ?? (I18N.defaultLocale ? words[I18N.defaultLocale] : undefined) ?? Object.values(words)[0] ?? '';
+}
+
 /**
- * Topics an app can offer as toggles. `news` = every new post, `events` = every
- * 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.
+ * Topics an app can offer as toggles, named in `locale` (default: the site's
+ * main language). `news` = every new post, `events` = every new event, `live` =
+ * "we're live" (while live video isn't off), then the site's own topics
+ * (acms({ mobile: { push: { topics } } })). 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[]> {
+export async function pushTopics(repo: ContentRepository, locale?: string | null): Promise<PushTopic[]> {
+  const lang = locale || I18N.defaultLocale || (await repo.getSettings()).locale || 'en';
+  const w = TOPIC_WORDS[lang.toLowerCase().split('-')[0]] ?? TOPIC_WORDS.en;
   const collections = Object.entries(CONTENT.collections);
-  const out: PushTopic[] = [{ id: 'news', label: 'News', kind: 'general' }];
+  const out: PushTopic[] = [{ id: 'news', label: w.news, kind: 'general' }];
   if (collections.length > 1) out.push(...collections.map(([key, c]): PushTopic => ({ id: `collection:${key}`, label: c.plural, kind: 'collection' })));
   if (CALENDAR.enabled) {
-    out.push({ id: 'events', label: 'Events', kind: 'general' });
+    out.push({ id: 'events', label: w.events, kind: 'general' });
     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' });
+  if ((await repo.getSettings()).live.mode !== 'off') out.push({ id: 'live', label: w.live, kind: 'general' });
+  for (const t of PUSH.topics) {
+    const description = topicWords(t.description, lang);
+    out.push({ id: t.id, label: topicWords(t.label, lang), kind: 'site', ...(description ? { description } : {}) });
+  }
   return out;
 }
 
 /** 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', 'live', ...Object.keys(CONTENT.collections).map((k) => `collection:${k}`)]);
+  const set = new Set(['news', 'live', ...Object.keys(CONTENT.collections).map((k) => `collection:${k}`), ...PUSH.topics.map((t) => t.id)]);
   if (CALENDAR.enabled) {
     set.add('events');
     for (const c of await repo.listCalendars()) if (c.visibility === 'public') set.add(`calendar:${c.slug}`);

package/src/lib/push/types.ts

@@ -34,7 +34,7 @@ export interface PushNotification {
   error: string; author: string; createdAt: number; finishedAt: number | null;
 }
 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 PushTopic { id: string; label: string; kind: 'general' | 'collection' | 'calendar' | 'site'; description?: string }
 export interface PushStats {
   devices: number;
   platforms: Record<PushPlatform, number>;

package/src/virtual.d.ts

@@ -14,7 +14,7 @@ declare module 'virtual:acms-config' {
     };
     // resolved by integration.mjs; empty locales = i18n not configured
     i18n: { locales: string[]; defaultLocale: string };
-    mobile?: { ios?: { teamId: string; bundleId: string; paths: string[] }; android?: { package: string; sha256CertFingerprints: string[] }; push?: { enabled: boolean; retentionDays: number }; editor?: { enabled: boolean; name: string; redirectUris: string[]; accessTokenMinutes: number; refreshTokenDays: number } };
+    mobile?: { ios?: { teamId: string; bundleId: string; paths: string[] }; android?: { package: string; sha256CertFingerprints: string[] }; push?: { enabled: boolean; retentionDays: number; topics?: Array<{ id: string; label: Record<string, string>; description: Record<string, string> }> }; editor?: { enabled: boolean; name: string; redirectUris: string[]; accessTokenMinutes: number; refreshTokenDays: number } };
     search?: { enabled: boolean };
     // resolved by integration.mjs; '' = pick from the environment (lib/maps/config.ts)
     maps?: { provider: '' | 'geoapify' | 'google' | 'mapbox' | 'locationiq' | 'stadia' | 'photon' | 'nominatim' | 'pelias' };