@terreno/announcements 57.21.0 → 58.0.0-beta.1

package/CHANGELOG.md

@@ -20,6 +20,49 @@ Upgrade notes for consumer action live in [`mcp-server/src/docs/upgrades/`](mcp-
 
 Unreleased changes live in [`changelog/unreleased/`](changelog/unreleased/). Add one Markdown file per feature (see that directory's README) instead of editing this section.
 
+## [58.0.0-beta.1] - 2026-11-02
+
+Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.1.md`](mcp-server/src/docs/upgrades/58.0.0-beta.1.md).
+
+### Breaking
+
+- Terreno 58 targets Expo SDK 58 (`~58.0.14`), React Native `0.88.0`, and React `19.3.0`. `@terreno/ui` peers `react-native` `0.88.0`. Native catalog moves with the SDK: `react-native-gesture-handler` `~3.3.0`, `react-native-reanimated` `4.7.1` + `react-native-worklets` `0.13.0`, `react-native-screens` `~4.30.0`, `react-native-webview` `14.0.1`, `@sentry/react-native` `~8.28.0`, `@shopify/flash-list` `2.3.2`, `@shopify/react-native-skia` `2.14.0`. Rebuild dev clients and store binaries.
+- Expo Router 58: set `export const unstable_settings = {initialRouteName}` on the layout instead of passing `initialRouteName` to `<Slot>` / navigators. `SidebarNavigation` ignores the prop.
+- Expo Router 58 static rendering: a custom `app/+html.tsx` must render `headNodes` and `bodyNodes` from `useServerDocumentContext()` (`expo-router/html`), or exported pages ship without their JavaScript. `example-frontend` is updated.
+- React Native 0.88 generated types: type refs as `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance` (`Box.scrollRef`, `TextField.inputRef`, `Text` `ref`).
+- `create-terreno-app` scaffolds Expo `~58.0.14`, React Native `0.88.0`, and React `19.3.0`.
+- The Terreno 58 native module baseline lands in `example-frontend` and `demo`: `@stripe/stripe-react-native` 0.81.0, `react-native-purchases` and `react-native-purchases-ui` 10.12.2, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, and `expo-build-properties` (Android Kotlin 2.2.21 and `compileSdkVersion` 37 pins). Rebuild every dev client and store binary. `react-native-otp-verify` is left out because it does not support the New Architecture. The demo has a hidden **Native Modules** page that shows each module's version and whether the running binary links it. See the 58.0.0 upgrade note.
+- `TerrenoApp` turns HTTP rate limiting on by default. Omitting `rateLimit` now mounts the limiter with the memory store (auth 20 / 15 min, api 600 / 15 min). Pass `rateLimit: false` to turn it off. On Cloud Run pass `rateLimit: {trustProxy: 1}` so unauthenticated traffic keys by client IP. See the 58.0.0 upgrade note.
+- `@terreno/admin-frontend` no longer takes an RTK `api`. The `api` prop is removed from every admin component (`AdminProvider`, `AdminShellLayout`, `AdminHome`, `AdminModelList`, `AdminModelTable`, `AdminModelForm`, `AdminScreenRouter`, `ConfigurationScreen`, `DocumentStorageBrowser`, `ConsentHistory`, comms, jobs, org, consent, and announcement screens, and widget props), and admin hooks drop their `api` argument (`useAdminConfig(apiBase)`, `useAdminScripts(apiBase)`, `useAdminRoles(apiBase)`, `useConfigurationApi({basePath})`, `useDocumentStorageApi(basePath)`, `useConsentHistory(baseUrl)`, `useOrganizationsApi(basePath)`, `useCommsDashboardApi()`, `useJobsDashboardApi()`, and the `useAiObservability*Api()` hooks).
+- `useAdminApi(api, routePath, modelName)` is removed. Use `useAdminModelApi(routePath, modelName)`, which keeps the same hook names and calls the same `/admin/{routePath}` URLs through the admin fetch client. `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are gone; `@reduxjs/toolkit` and `react-redux` are no longer peers of admin-frontend.
+- `AdminProvider` is now the required auth binding for every admin request, including ObjectId and API-only model CRUD. Cookie SPAs pass `credentials="same-origin"`; embedded apps pass `apiOrigin` and `getAuthHeaders`. Product screens that reuse admin components wrap them in `AdminProvider`. See the 58.0.0 upgrade guide.
+- Removed the legacy RTK realtime path. Use `sync` on `modelRouter` with `@terreno/syncdb` for live collection updates. `RealtimeApp`, `SyncApp`, socket auth, `sync:delta`, and admin `admin:model.changed` events are unchanged. See the 58.0.0 upgrade note.
+- `@terreno/api`: `modelRouter` no longer accepts `realtime` (now a TypeScript error), and the change stream no longer emits the `sync` websocket event. Removed `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`, the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. Sockets no longer handle `subscribe:model`, `subscribe:document`, or `subscribe:query`.
+- `@terreno/rtk`: removed `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and the `RealtimeEvent` type. The rest of `@terreno/rtk` (including `useSocketConnection` and `useRealtimeDebug`) is removed in the same release; see `remove-rtk.md`.
+- Removed `@terreno/rtk` and every Redux dependency (`@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi`). `@terreno/rtk` is not published for 58. `@terreno/syncdb` is the only frontend data, request, and session layer. Follow `docs/how-to/migrate-rtk-to-syncdb.md`, which maps every removed export to its replacement, and the 58.0.0 upgrade note.
+- `@terreno/syncdb` adds `@terreno/syncdb/api` (`createApiClient`, `ApiError`), request hooks in `@terreno/syncdb/react` (`ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`), `@terreno/syncdb/config` (`baseUrl`, `baseWebsocketsUrl`, `appHeaders`), `@terreno/syncdb/auth` (`createBetterAuthClient`, `SessionProvider`, `useSession`, `jwtAuthAdapter`, `useJwtAuth`, token-expiry helpers), `@terreno/syncdb/flags` (`useFeatureFlags`, `useTerrenoFeatureFlags` on the sync socket), `@terreno/syncdb/app` (`useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools`), and `@terreno/syncdb/buildNumber`.
+- `terreno-syncdb-codegen --api-out` generates typed hooks for every non-synced OpenAPI operation (same names as the RTK codegen), replacing `@rtk-query/codegen-openapi`. `bun run sdk` writes `store/apiSdk.ts`.
+- `@terreno/ui` `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, and `useAcknowledgeAnnouncement` take a request `client` instead of an RTK `api`.
+- `GptHistory` (`gpt/histories`) and `McpServiceToken` (`mcp/service-tokens`, read-only) are synced collections with String ids. Run the `gptHistoryStringIdsMigration` (`@terreno/ai`) and `mcpServiceTokenStringIdsMigration` (`@terreno/api`) before deploying 58 frontends.
+- `create-terreno-app`, the `terreno_bootstrap` prompt, and the `terreno_generate_screen` tool scaffold apps without Redux or `@terreno/rtk`. The terreno-mcp-local `get_rtk_state` tool, the MCP resource `terreno://docs/rtk`, and `terreno state --slice rtk` are removed; use `get_syncdb_state` and `terreno state`.
+
+### Added
+
+- `DataTable` columns size themselves when `width` is omitted. Each auto column starts at the wider of its header and its content (sampled from at most 50 rows, measured with a canvas on web and estimated on native), clamped to 80–360px, and auto columns grow to fill the table's container. Columns that set `width` keep it. `DataTableColumn.width` is now optional.
+
+### Changed
+
+- The repository's agent rules now generate with rulesync 17 (up from 9). The root rule `.rulesync/rules/00-root.md` now generates `AGENTS.md`, which Devin and other AGENTS.md readers load, in place of `.devin/rules/00-root.md`. Never edit `AGENTS.md` by hand: edit the root rule and run `bun run rules`. The examples that existed only in the old hand-edited `AGENTS.md` (syncdb and RTK SDK usage) moved into the root rule, so `CLAUDE.md`, the Cursor root rule, and Copilot instructions get them too. Links in the root rule now resolve from the repository root. Generated Copilot hooks use the portable `command` field. Generated Copilot subagents no longer list `agent/runSubagent` as their only tool, so they get every default tool. Generated skills carry their `license`, `disable-model-invocation`, and Devin `triggers` frontmatter.
+- `@terreno/syncdb/auth` `SessionProvider`: `logout()` no longer clears the session before the server answers. The session stays in the state until `authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds), and then it is cleared. Meanwhile the new `isSigningOut` state (`useSession().isSigningOut`) is true; `isLoading` is left alone, so a navigator gated on it keeps its screen. Before, a login screen that opened at once could find the still-live session and sign the user straight back in. A sign-out that fails or times out checks the session first. A session that is still live, or a cookie or native session the server cannot be asked about, stays signed in, and `error` is set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."). A web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) now ends signed out even when the sign-out request fails. With `apisToReset` (57.17.0), `logout()` purges the cache when the session clears, not when it is dispatched: a purge at dispatch refetched every mounted screen mid-sign-out, and a refetch that could not reach the server answered 401 and signed the user out even though the sign-out failed. A failed sign-out keeps both the session and the cache. The global `auth/logout` action still purges at once (only the first of several in flight) and again when the session clears. A sign-in for another user that lands while a sign-out is in flight is kept; a sign-out that started signed out asks `getSession` first, so a restore of the session it revoked is cleared. Show `selectBetterAuthIsSigningOut` on the sign-out control and `selectBetterAuthError` after a failed sign-out.
+
+### Removed
+
+- `@terreno/ui` no longer exports the `Filter` and `FilterProps` aliases deprecated in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps` instead. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
+
+### Fixed
+
+- `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
+
 ## [57.21.0] - 2026-11-01
 
 Upgrade note: [`mcp-server/src/docs/upgrades/57.21.0.md`](mcp-server/src/docs/upgrades/57.21.0.md).

package/dist/announcementsApp.js

@@ -74,6 +74,40 @@ const requireVisibleAnnouncement = async ({ announcement, isStaff, matchAudience
     }
     return announcement;
 };
+/** `AnnouncementPublic`: the shape user-facing announcement routes return. */
+const announcementPublicOpenApiSchema = {
+    properties: {
+        body: { description: "Markdown body", type: "string" },
+        displayMode: { enum: ["modal", "banner", "feed"], type: "string" },
+        id: { type: "string" },
+        primaryAction: {
+            properties: { label: { type: "string" }, url: { type: "string" } },
+            required: ["label", "url"],
+            type: "object",
+        },
+        priority: { type: "number" },
+        publishedAt: { format: "date-time", type: "string" },
+        requiresAcknowledgement: { type: "boolean" },
+        title: { type: "string" },
+        version: { type: "number" },
+    },
+    required: [
+        "body",
+        "displayMode",
+        "id",
+        "priority",
+        "requiresAcknowledgement",
+        "title",
+        "version",
+    ],
+    type: "object",
+};
+const platformQueryParameter = {
+    enum: ["ios", "android", "web"],
+    type: "string",
+};
+const PLATFORM_QUERY_DESCRIPTION = "Client platform. Defaults from the User-Agent, then web.";
+const VERSION_QUERY_DESCRIPTION = "Client build number, compared with each announcement's minimum.";
 class AnnouncementsApp {
     options;
     constructor(options) {
@@ -205,8 +239,35 @@ class AnnouncementsApp {
             queryFields: ["status", "priority", "title"],
             sort: "-priority,-publishedAt",
         };
+        const routeOpenApi = openApi ? { openApi: openApi } : undefined;
+        // User routes: documentation only. Validation stays off; the handlers parse their own input.
+        const userRouteDocs = () => (0, api_1.createOpenApiBuilder)(routeOpenApi ?? {})
+            .withTags(["announcements"])
+            .withValidation({ enabled: false });
+        const recordedResponse = (field) => ({
+            data: { properties: { [field]: { type: "boolean" } }, required: [field], type: "object" },
+        });
         const userRouter = (0, express_1.Router)();
-        userRouter.get("/pending", (0, api_1.authenticateMiddleware)(), (0, api_1.asyncHandler)(async (req, res) => {
+        userRouter.get("/pending", (0, api_1.authenticateMiddleware)(), userRouteDocs()
+            .withSummary("Get the next announcement the current user should see")
+            .withQueryParameter("platform", platformQueryParameter, {
+            description: PLATFORM_QUERY_DESCRIPTION,
+        })
+            .withQueryParameter("version", { type: "integer" }, { description: VERSION_QUERY_DESCRIPTION })
+            .withResponse(200, {
+            data: {
+                properties: {
+                    current: { ...announcementPublicOpenApiSchema, nullable: true },
+                    remainingCount: {
+                        description: "Pending announcements after the current one",
+                        type: "number",
+                    },
+                },
+                required: ["current", "remainingCount"],
+                type: "object",
+            },
+        }, { required: ["data"] })
+            .build(), (0, api_1.asyncHandler)(async (req, res) => {
             const user = req.user;
             if (!user) {
                 throw new api_1.APIError({ status: 401, title: "Authentication required" });
@@ -250,7 +311,21 @@ class AnnouncementsApp {
             });
             return res.json({ data: { current, remainingCount } });
         }));
-        userRouter.get("/feed", (0, api_1.authenticateMiddleware)(), (0, api_1.asyncHandler)(async (req, res) => {
+        userRouter.get("/feed", (0, api_1.authenticateMiddleware)(), userRouteDocs()
+            .withSummary("List announcements visible to the current user")
+            .withQueryParameter("platform", platformQueryParameter, {
+            description: PLATFORM_QUERY_DESCRIPTION,
+        })
+            .withQueryParameter("version", { type: "integer" }, { description: VERSION_QUERY_DESCRIPTION })
+            .withQueryParameter("limit", { type: "integer" }, { description: "Page size, 1 to 100 (default 20)" })
+            .withQueryParameter("page", { type: "integer" }, { description: "Page number, from 1" })
+            .withResponse(200, {
+            data: { items: announcementPublicOpenApiSchema, type: "array" },
+            more: { description: "Whether a later page has more announcements", type: "boolean" },
+            page: { type: "number" },
+            total: { description: "Visible announcements across all pages", type: "number" },
+        }, { required: ["data", "more", "page", "total"] })
+            .build(), (0, api_1.asyncHandler)(async (req, res) => {
             const user = req.user;
             if (!user) {
                 throw new api_1.APIError({ status: 401, title: "Authentication required" });
@@ -291,11 +366,20 @@ class AnnouncementsApp {
                 .map((announcement) => (0, announcement_1.toAnnouncementPublic)(announcement, defaultAcknowledgementPolicy));
             return res.json({
                 data: pageItems,
+                more: start + limit < sorted.length,
                 page,
                 total: sorted.length,
             });
         }));
-        userRouter.post("/:id/acknowledge", (0, api_1.authenticateMiddleware)(), (0, api_1.asyncHandler)(async (req, res) => {
+        userRouter.post("/:id/acknowledge", (0, api_1.authenticateMiddleware)(), userRouteDocs()
+            .withSummary("Acknowledge an announcement for the current user")
+            .withPathParameter("id", { type: "string" }, { description: "Announcement id" })
+            .withQueryParameter("platform", platformQueryParameter, {
+            description: PLATFORM_QUERY_DESCRIPTION,
+        })
+            .withQueryParameter("version", { type: "integer" }, { description: VERSION_QUERY_DESCRIPTION })
+            .withResponse(200, recordedResponse("acknowledged"), { required: ["data"] })
+            .build(), (0, api_1.asyncHandler)(async (req, res) => {
             const user = req.user;
             if (!user) {
                 throw new api_1.APIError({ status: 401, title: "Authentication required" });
@@ -324,7 +408,16 @@ class AnnouncementsApp {
             }
             return res.json({ data: { acknowledged: true } });
         }));
-        userRouter.post("/:id/impression", (0, api_1.authenticateMiddleware)(), (0, api_1.asyncHandler)(async (req, res) => {
+        userRouter.post("/:id/impression", (0, api_1.authenticateMiddleware)(), userRouteDocs()
+            .withSummary("Record that the current user saw an announcement")
+            .withPathParameter("id", { type: "string" }, { description: "Announcement id" })
+            .withQueryParameter("platform", platformQueryParameter, {
+            description: "Used when the body has no platform. Defaults from the User-Agent.",
+        })
+            .withQueryParameter("version", { type: "integer" }, { description: VERSION_QUERY_DESCRIPTION })
+            .withRequestBody({ platform: platformQueryParameter }, { required: false })
+            .withResponse(200, recordedResponse("recorded"), { required: ["data"] })
+            .build(), (0, api_1.asyncHandler)(async (req, res) => {
             const user = req.user;
             if (!user) {
                 throw new api_1.APIError({ status: 401, title: "Authentication required" });
@@ -352,7 +445,19 @@ class AnnouncementsApp {
             });
             return res.json({ data: { recorded: true } });
         }));
-        userRouter.post("/:id/click", (0, api_1.authenticateMiddleware)(), (0, api_1.asyncHandler)(async (req, res) => {
+        userRouter.post("/:id/click", (0, api_1.authenticateMiddleware)(), userRouteDocs()
+            .withSummary("Record that the current user clicked an announcement's primary action")
+            .withPathParameter("id", { type: "string" }, { description: "Announcement id" })
+            .withQueryParameter("platform", platformQueryParameter, {
+            description: "Used when the body has no platform. Defaults from the User-Agent.",
+        })
+            .withQueryParameter("version", { type: "integer" }, { description: VERSION_QUERY_DESCRIPTION })
+            .withRequestBody({
+            action: { enum: ["primaryAction"], required: true, type: "string" },
+            platform: platformQueryParameter,
+        })
+            .withResponse(200, recordedResponse("recorded"), { required: ["data"] })
+            .build(), (0, api_1.asyncHandler)(async (req, res) => {
             const user = req.user;
             if (!user) {
                 throw new api_1.APIError({ status: 401, title: "Authentication required" });
@@ -386,7 +491,6 @@ class AnnouncementsApp {
             return res.json({ data: { recorded: true } });
         }));
         const adminRouter = (0, express_1.Router)();
-        const routeOpenApi = openApi ? { openApi: openApi } : undefined;
         adminRouter.get("/config", [
             (0, api_1.authenticateMiddleware)(),
             ...(routeOpenApi

package/package.json

@@ -4,14 +4,14 @@
     "url": "https://github.com/TerrenoLabs/terreno/issues"
   },
   "dependencies": {
-    "@terreno/api": "57.21.0",
+    "@terreno/api": "58.0.0-beta.1",
     "express": "^5.2.1",
     "luxon": "^3.7.2"
   },
   "description": "In-app product update announcements plugin for @terreno/api — part of Terreno, the batteries-included TypeScript framework for universal apps.",
   "devDependencies": {
     "@biomejs/biome": "^2.3.6",
-    "@terreno/test": "57.21.0",
+    "@terreno/test": "58.0.0-beta.1",
     "@types/bun": "^1.4.0",
     "@types/express": "^5.0.6",
     "@types/supertest": "^7.2.0",
@@ -55,5 +55,5 @@
     "typecheck": "tsc -p tsconfig.typecheck.json"
   },
   "types": "dist/index.d.ts",
-  "version": "57.21.0"
+  "version": "58.0.0-beta.1"
 }

package/src/announcementsApp.ts

@@ -9,6 +9,7 @@ import {
   type ModelRouterOptions,
   modelRouter,
   type OpenApiMiddleware,
+  type OpenApiSchemaProperty,
   type PermissionMethod,
   Permissions,
   type TerrenoPlugin,
@@ -141,6 +142,43 @@ const requireVisibleAnnouncement = async ({
   return announcement;
 };
 
+/** `AnnouncementPublic`: the shape user-facing announcement routes return. */
+const announcementPublicOpenApiSchema: OpenApiSchemaProperty = {
+  properties: {
+    body: {description: "Markdown body", type: "string"},
+    displayMode: {enum: ["modal", "banner", "feed"], type: "string"},
+    id: {type: "string"},
+    primaryAction: {
+      properties: {label: {type: "string"}, url: {type: "string"}},
+      required: ["label", "url"],
+      type: "object",
+    },
+    priority: {type: "number"},
+    publishedAt: {format: "date-time", type: "string"},
+    requiresAcknowledgement: {type: "boolean"},
+    title: {type: "string"},
+    version: {type: "number"},
+  },
+  required: [
+    "body",
+    "displayMode",
+    "id",
+    "priority",
+    "requiresAcknowledgement",
+    "title",
+    "version",
+  ],
+  type: "object",
+};
+
+const platformQueryParameter: OpenApiSchemaProperty = {
+  enum: ["ios", "android", "web"],
+  type: "string",
+};
+
+const PLATFORM_QUERY_DESCRIPTION = "Client platform. Defaults from the User-Agent, then web.";
+const VERSION_QUERY_DESCRIPTION = "Client build number, compared with each announcement's minimum.";
+
 export class AnnouncementsApp implements TerrenoPlugin {
   private options: AnnouncementsOptions;
 
@@ -283,11 +321,45 @@ export class AnnouncementsApp implements TerrenoPlugin {
       sort: "-priority,-publishedAt",
     };
 
+    const routeOpenApi = openApi ? {openApi: openApi as OpenApiMiddleware} : undefined;
+    // User routes: documentation only. Validation stays off; the handlers parse their own input.
+    const userRouteDocs = (): ReturnType<typeof createOpenApiBuilder> =>
+      createOpenApiBuilder(routeOpenApi ?? {})
+        .withTags(["announcements"])
+        .withValidation({enabled: false});
+    const recordedResponse = (field: string): Record<string, OpenApiSchemaProperty> => ({
+      data: {properties: {[field]: {type: "boolean"}}, required: [field], type: "object"},
+    });
+
     const userRouter = Router();
 
     userRouter.get(
       "/pending",
       authenticateMiddleware(),
+      userRouteDocs()
+        .withSummary("Get the next announcement the current user should see")
+        .withQueryParameter("platform", platformQueryParameter, {
+          description: PLATFORM_QUERY_DESCRIPTION,
+        })
+        .withQueryParameter("version", {type: "integer"}, {description: VERSION_QUERY_DESCRIPTION})
+        .withResponse(
+          200,
+          {
+            data: {
+              properties: {
+                current: {...announcementPublicOpenApiSchema, nullable: true},
+                remainingCount: {
+                  description: "Pending announcements after the current one",
+                  type: "number",
+                },
+              },
+              required: ["current", "remainingCount"],
+              type: "object",
+            },
+          },
+          {required: ["data"]}
+        )
+        .build(),
       asyncHandler(async (req: Request, res: Response) => {
         const user = req.user;
         if (!user) {
@@ -349,6 +421,29 @@ export class AnnouncementsApp implements TerrenoPlugin {
     userRouter.get(
       "/feed",
       authenticateMiddleware(),
+      userRouteDocs()
+        .withSummary("List announcements visible to the current user")
+        .withQueryParameter("platform", platformQueryParameter, {
+          description: PLATFORM_QUERY_DESCRIPTION,
+        })
+        .withQueryParameter("version", {type: "integer"}, {description: VERSION_QUERY_DESCRIPTION})
+        .withQueryParameter(
+          "limit",
+          {type: "integer"},
+          {description: "Page size, 1 to 100 (default 20)"}
+        )
+        .withQueryParameter("page", {type: "integer"}, {description: "Page number, from 1"})
+        .withResponse(
+          200,
+          {
+            data: {items: announcementPublicOpenApiSchema, type: "array"},
+            more: {description: "Whether a later page has more announcements", type: "boolean"},
+            page: {type: "number"},
+            total: {description: "Visible announcements across all pages", type: "number"},
+          },
+          {required: ["data", "more", "page", "total"]}
+        )
+        .build(),
       asyncHandler(async (req: Request, res: Response) => {
         const user = req.user;
         if (!user) {
@@ -397,6 +492,7 @@ export class AnnouncementsApp implements TerrenoPlugin {
 
         return res.json({
           data: pageItems,
+          more: start + limit < sorted.length,
           page,
           total: sorted.length,
         });
@@ -406,6 +502,15 @@ export class AnnouncementsApp implements TerrenoPlugin {
     userRouter.post(
       "/:id/acknowledge",
       authenticateMiddleware(),
+      userRouteDocs()
+        .withSummary("Acknowledge an announcement for the current user")
+        .withPathParameter("id", {type: "string"}, {description: "Announcement id"})
+        .withQueryParameter("platform", platformQueryParameter, {
+          description: PLATFORM_QUERY_DESCRIPTION,
+        })
+        .withQueryParameter("version", {type: "integer"}, {description: VERSION_QUERY_DESCRIPTION})
+        .withResponse(200, recordedResponse("acknowledged"), {required: ["data"]})
+        .build(),
       asyncHandler(async (req: Request, res: Response) => {
         const user = req.user;
         if (!user) {
@@ -444,6 +549,16 @@ export class AnnouncementsApp implements TerrenoPlugin {
     userRouter.post(
       "/:id/impression",
       authenticateMiddleware(),
+      userRouteDocs()
+        .withSummary("Record that the current user saw an announcement")
+        .withPathParameter("id", {type: "string"}, {description: "Announcement id"})
+        .withQueryParameter("platform", platformQueryParameter, {
+          description: "Used when the body has no platform. Defaults from the User-Agent.",
+        })
+        .withQueryParameter("version", {type: "integer"}, {description: VERSION_QUERY_DESCRIPTION})
+        .withRequestBody({platform: platformQueryParameter}, {required: false})
+        .withResponse(200, recordedResponse("recorded"), {required: ["data"]})
+        .build(),
       asyncHandler(async (req: Request, res: Response) => {
         const user = req.user;
         if (!user) {
@@ -480,6 +595,19 @@ export class AnnouncementsApp implements TerrenoPlugin {
     userRouter.post(
       "/:id/click",
       authenticateMiddleware(),
+      userRouteDocs()
+        .withSummary("Record that the current user clicked an announcement's primary action")
+        .withPathParameter("id", {type: "string"}, {description: "Announcement id"})
+        .withQueryParameter("platform", platformQueryParameter, {
+          description: "Used when the body has no platform. Defaults from the User-Agent.",
+        })
+        .withQueryParameter("version", {type: "integer"}, {description: VERSION_QUERY_DESCRIPTION})
+        .withRequestBody({
+          action: {enum: ["primaryAction"], required: true, type: "string"},
+          platform: platformQueryParameter,
+        })
+        .withResponse(200, recordedResponse("recorded"), {required: ["data"]})
+        .build(),
       asyncHandler(async (req: Request, res: Response) => {
         const user = req.user;
         if (!user) {
@@ -521,7 +649,6 @@ export class AnnouncementsApp implements TerrenoPlugin {
     );
 
     const adminRouter = Router();
-    const routeOpenApi = openApi ? {openApi: openApi as OpenApiMiddleware} : undefined;
 
     adminRouter.get(
       "/config",

package/src/tests/openApi.test.ts

@@ -0,0 +1,248 @@
+/** Verifies `/openapi.json` documents the user-facing announcement routes. */
+import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+import {TerrenoApp, type UserModel as UserModelType} from "@terreno/api";
+import {
+  authAsUser,
+  expectDocumentedResponse,
+  type OpenApiResponseSpec,
+  setupDb,
+  UserModel,
+} from "@terreno/api/testing";
+import type express from "express";
+import {DateTime} from "luxon";
+import supertest from "supertest";
+import {AnnouncementsApp} from "../announcementsApp";
+import {Announcement} from "../models/announcement";
+import {AnnouncementAcknowledgement} from "../models/announcementAcknowledgement";
+import {AnnouncementClickEvent} from "../models/announcementClickEvent";
+import {AnnouncementImpression} from "../models/announcementImpression";
+
+interface SchemaNode {
+  enum?: string[];
+  items?: SchemaNode;
+  nullable?: boolean;
+  properties?: Record<string, SchemaNode>;
+  required?: string[];
+  type?: string;
+}
+
+interface Operation {
+  parameters?: {in: string; name: string; schema: SchemaNode}[];
+  requestBody?: {content: Record<string, {schema: SchemaNode}>; required?: boolean};
+  responses: Record<string, {content?: Record<string, {schema: SchemaNode}>}>;
+  tags?: string[];
+}
+
+const buildApp = (): express.Application =>
+  new TerrenoApp({
+    rateLimit: false,
+    skipListen: true,
+    userModel: UserModel as unknown as UserModelType,
+  })
+    .register(new AnnouncementsApp())
+    .build();
+
+const response200 = (operation: Operation | undefined): SchemaNode | undefined =>
+  operation?.responses["200"]?.content?.["application/json"]?.schema;
+
+const parameterNames = (operation: Operation | undefined): string[] =>
+  (operation?.parameters ?? []).map((parameter) => `${parameter.in}:${parameter.name}`).sort();
+
+const clearAnnouncements = async (): Promise<void> => {
+  await Announcement.deleteMany({});
+  await AnnouncementAcknowledgement.deleteMany({});
+  await AnnouncementImpression.deleteMany({});
+  await AnnouncementClickEvent.deleteMany({});
+};
+
+describe("AnnouncementsApp OpenAPI", () => {
+  let app: express.Application;
+  let paths: Record<string, Record<string, Operation>>;
+
+  beforeEach(async () => {
+    await setupDb();
+    await clearAnnouncements();
+    app = buildApp();
+    const res = await supertest(app).get("/openapi.json").expect(200);
+    paths = res.body.paths;
+  });
+
+  afterEach(async () => {
+    await clearAnnouncements();
+  });
+
+  it("documents GET /announcements/pending", () => {
+    const operation = paths["/announcements/pending"]?.get;
+    expect(operation?.tags).toEqual(["announcements"]);
+    expect(parameterNames(operation)).toEqual(["query:platform", "query:version"]);
+    const body = response200(operation);
+    expect(body?.required).toEqual(["data"]);
+    const current = body?.properties?.data?.properties?.current;
+    expect(current?.nullable).toBe(true);
+    expect(current?.properties?.displayMode?.enum).toEqual(["modal", "banner", "feed"]);
+    expect(body?.properties?.data?.properties?.remainingCount?.type).toBe("number");
+  });
+
+  it("documents GET /announcements/feed with its pagination fields", () => {
+    const operation = paths["/announcements/feed"]?.get;
+    expect(parameterNames(operation)).toEqual([
+      "query:limit",
+      "query:page",
+      "query:platform",
+      "query:version",
+    ]);
+    const body = response200(operation);
+    expect(body?.required).toEqual(["data", "more", "page", "total"]);
+    expect(body?.properties?.more?.type).toBe("boolean");
+    expect(body?.properties?.data?.type).toBe("array");
+    expect(body?.properties?.data?.items?.properties?.id?.type).toBe("string");
+    expect(body?.properties?.data?.items?.nullable).toBeUndefined();
+  });
+
+  it("documents the acknowledge, impression, and click actions", () => {
+    const acknowledge = paths["/announcements/{id}/acknowledge"]?.post;
+    expect(parameterNames(acknowledge)).toEqual(["path:id", "query:platform", "query:version"]);
+    expect(acknowledge?.requestBody).toBeUndefined();
+    expect(response200(acknowledge)?.properties?.data?.properties?.acknowledged?.type).toBe(
+      "boolean"
+    );
+
+    const impression = paths["/announcements/{id}/impression"]?.post;
+    expect(parameterNames(impression)).toEqual(["path:id", "query:platform", "query:version"]);
+    expect(impression?.requestBody?.required).toBe(false);
+    expect(
+      impression?.requestBody?.content["application/json"]?.schema.properties?.platform?.enum
+    ).toEqual(["ios", "android", "web"]);
+    expect(response200(impression)?.properties?.data?.properties?.recorded?.type).toBe("boolean");
+
+    const click = paths["/announcements/{id}/click"]?.post;
+    const clickBody = click?.requestBody?.content["application/json"]?.schema;
+    expect(click?.requestBody?.required).toBe(true);
+    expect(clickBody?.required).toEqual(["action"]);
+    expect(clickBody?.properties?.action?.enum).toEqual(["primaryAction"]);
+    expect(response200(click)?.properties?.data?.required).toEqual(["recorded"]);
+  });
+
+  it("documents every field pending and feed return", async () => {
+    await Announcement.create({
+      body: "Body",
+      primaryAction: {label: "Open", url: "https://example.com"},
+      publishedAt: DateTime.utc().minus({minutes: 1}).toJSDate(),
+      status: "published",
+      title: "Documented",
+    });
+    const agent = await authAsUser(app, "notAdmin");
+    const announcementProperties = Object.keys(
+      response200(paths["/announcements/feed"]?.get)?.properties?.data?.items?.properties ?? {}
+    );
+
+    const pending = await agent.get("/announcements/pending?platform=web").expect(200);
+    expect(announcementProperties).toEqual(
+      expect.arrayContaining(Object.keys(pending.body.data.current))
+    );
+    const pendingDataFields = Object.keys(
+      response200(paths["/announcements/pending"]?.get)?.properties?.data?.properties ?? {}
+    );
+    expect(pendingDataFields).toEqual(expect.arrayContaining(Object.keys(pending.body.data)));
+
+    const feed = await agent.get("/announcements/feed?platform=web").expect(200);
+    expect(announcementProperties).toEqual(expect.arrayContaining(Object.keys(feed.body.data[0])));
+    const feedFields = Object.keys(
+      response200(paths["/announcements/feed"]?.get)?.properties ?? {}
+    );
+    expect([...feedFields, "requestId"]).toEqual(expect.arrayContaining(Object.keys(feed.body)));
+  });
+
+  it("returns bodies that match the documented schemas for every user route", async () => {
+    const spec = (await supertest(app).get("/openapi.json").expect(200))
+      .body as OpenApiResponseSpec;
+    const agent = await authAsUser(app, "notAdmin");
+    const empty = await agent.get("/announcements/pending?platform=web").expect(200);
+    expect(empty.body.data.current).toBeNull();
+    expectDocumentedResponse({
+      method: "get",
+      path: "/announcements/pending",
+      response: empty,
+      spec,
+    });
+
+    const publishedAt = DateTime.utc().minus({minutes: 1}).toJSDate();
+    const withAction = await Announcement.create({
+      acknowledgementPolicy: "required",
+      body: "Body",
+      primaryAction: {label: "Open", url: "https://example.com"},
+      publishedAt,
+      status: "published",
+      title: "With action",
+    });
+    await Announcement.create({body: "Body", publishedAt, status: "published", title: "Plain"});
+    const id = withAction._id.toString();
+
+    const pending = await agent.get("/announcements/pending?platform=web").expect(200);
+    expectDocumentedResponse({
+      method: "get",
+      path: "/announcements/pending",
+      response: pending,
+      spec,
+    });
+
+    const impression = await agent
+      .post(`/announcements/${id}/impression`)
+      .send({platform: "web"})
+      .expect(200);
+    expectDocumentedResponse({
+      method: "post",
+      path: "/announcements/{id}/impression",
+      response: impression,
+      spec,
+    });
+
+    const click = await agent
+      .post(`/announcements/${id}/click?platform=web`)
+      .send({action: "primaryAction"})
+      .expect(200);
+    expectDocumentedResponse({
+      method: "post",
+      path: "/announcements/{id}/click",
+      response: click,
+      spec,
+    });
+
+    const acknowledge = await agent
+      .post(`/announcements/${id}/acknowledge?platform=web`)
+      .expect(200);
+    expectDocumentedResponse({
+      method: "post",
+      path: "/announcements/{id}/acknowledge",
+      response: acknowledge,
+      spec,
+    });
+
+    for (const page of [1, 2]) {
+      const feed = await agent
+        .get(`/announcements/feed?platform=web&limit=1&page=${page}`)
+        .expect(200);
+      expectDocumentedResponse({method: "get", path: "/announcements/feed", response: feed, spec});
+    }
+  });
+
+  it("reports more on every feed page but the last so clients keep the list envelope", async () => {
+    const publishedAt = DateTime.utc().minus({minutes: 1}).toJSDate();
+    for (const title of ["One", "Two", "Three"]) {
+      await Announcement.create({body: "Body", publishedAt, status: "published", title});
+    }
+    const agent = await authAsUser(app, "notAdmin");
+
+    const pages: {count: number; more: boolean; total: number}[] = [];
+    for (const page of [1, 2, 3]) {
+      const res = await agent.get(`/announcements/feed?platform=web&limit=2&page=${page}`);
+      pages.push({count: res.body.data.length, more: res.body.more, total: res.body.total});
+    }
+
+    expect(pages).toEqual([
+      {count: 2, more: true, total: 3},
+      {count: 1, more: false, total: 3},
+      {count: 0, more: false, total: 3},
+    ]);
+  });
+});