@terreno/announcements 57.4.0

package/src/help.ts

@@ -0,0 +1,98 @@
+import {requiresAcknowledgementForAnnouncement} from "./pending";
+import type {AcknowledgementPolicy, AnnouncementDocument, AnnouncementStatus} from "./types";
+
+export interface AnnouncementHelpSummary {
+  archivedAt?: string;
+  excerpt: string;
+  id: string;
+  publishedAt?: string;
+  status: AnnouncementStatus;
+  title: string;
+  version: number;
+}
+
+export interface AnnouncementHelpDetail {
+  archivedAt?: string;
+  body: string;
+  expiresAt?: string;
+  id: string;
+  platforms: AnnouncementDocument["platforms"];
+  primaryAction?: AnnouncementDocument["primaryAction"];
+  priority: number;
+  publishAt?: string;
+  publishedAt?: string;
+  requiresAcknowledgement: boolean;
+  status: AnnouncementStatus;
+  title: string;
+  version: number;
+}
+
+export const buildHelpStatusFilter = (includeArchived: boolean): AnnouncementStatus[] => {
+  if (includeArchived) {
+    return ["published", "archived"];
+  }
+  return ["published"];
+};
+
+export const excerptBody = (body: string, maxLength = 240): string => {
+  const normalized = body.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  return `${normalized.slice(0, maxLength)}…`;
+};
+
+const matchesSingleQuery = (
+  doc: Pick<AnnouncementDocument, "body" | "title">,
+  query: string
+): boolean => {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return true;
+  }
+  const haystack = `${doc.title}\n${doc.body}`.toLowerCase();
+  return haystack.includes(normalized);
+};
+
+export const matchesHelpQueries = (
+  doc: Pick<AnnouncementDocument, "body" | "title">,
+  queries: string[]
+): boolean => {
+  const activeQueries = queries.map((query) => query.trim()).filter(Boolean);
+  if (activeQueries.length === 0) {
+    return true;
+  }
+  return activeQueries.some((query) => matchesSingleQuery(doc, query));
+};
+
+export const toHelpSummary = (doc: AnnouncementDocument): AnnouncementHelpSummary => ({
+  archivedAt: doc.archivedAt?.toISOString(),
+  excerpt: excerptBody(doc.body),
+  id: doc._id.toString(),
+  publishedAt: doc.publishedAt?.toISOString(),
+  status: doc.status,
+  title: doc.title,
+  version: doc.version,
+});
+
+export const toHelpDetail = (
+  doc: AnnouncementDocument,
+  defaultAcknowledgementPolicy: AcknowledgementPolicy = "dismiss-only"
+): AnnouncementHelpDetail => ({
+  archivedAt: doc.archivedAt?.toISOString(),
+  body: doc.body,
+  expiresAt: doc.expiresAt?.toISOString(),
+  id: doc._id.toString(),
+  platforms: doc.platforms,
+  primaryAction: doc.primaryAction,
+  priority: doc.priority,
+  publishAt: doc.publishAt?.toISOString(),
+  publishedAt: doc.publishedAt?.toISOString(),
+  requiresAcknowledgement: requiresAcknowledgementForAnnouncement({
+    announcement: doc,
+    defaultAcknowledgementPolicy,
+  }),
+  status: doc.status,
+  title: doc.title,
+  version: doc.version,
+});

package/src/helpRoutes.ts

@@ -0,0 +1,160 @@
+import {APIError, asyncHandler, authenticateMiddleware} from "@terreno/api";
+import {type Request, type Response, Router} from "express";
+import {buildHelpStatusFilter, matchesHelpQueries, toHelpDetail, toHelpSummary} from "./help";
+import {Announcement} from "./models/announcement";
+import {
+  isAnnouncementVisibleNow,
+  matchAudienceByType,
+  parseQueryVersion,
+  passesMinBuildNumber,
+} from "./pending";
+import type {AcknowledgementPolicy, AnnouncementDocument, MatchAudienceFunction} from "./types";
+
+const defaultIsStaff = (user: unknown): boolean => (user as {admin?: boolean}).admin === true;
+
+const parseHelpQueries = (req: Request): string[] => {
+  const raw = req.query.q;
+  if (typeof raw === "string" && raw.trim()) {
+    return [raw.trim()];
+  }
+  if (Array.isArray(raw)) {
+    return raw.filter(
+      (value): value is string => typeof value === "string" && value.trim().length > 0
+    );
+  }
+  return [];
+};
+
+const parseIncludeArchived = (req: Request): boolean => {
+  const raw = req.query.includeArchived;
+  if (raw === "true" || raw === "1") {
+    return true;
+  }
+  return false;
+};
+
+const parseLimit = (req: Request): number => {
+  const parsed = Number(req.query.limit ?? 10);
+  return Math.min(Math.max(parsed, 1), 50);
+};
+
+const isAnnouncementHelpVisible = (announcement: AnnouncementDocument): boolean => {
+  if (announcement.status === "archived") {
+    return true;
+  }
+  return isAnnouncementVisibleNow({announcement});
+};
+
+const sortHelpResults = (docs: AnnouncementDocument[]): AnnouncementDocument[] => {
+  return [...docs].sort((left, right) => {
+    if (right.priority !== left.priority) {
+      return right.priority - left.priority;
+    }
+    const rightPublished = right.publishedAt?.getTime() ?? 0;
+    const leftPublished = left.publishedAt?.getTime() ?? 0;
+    return rightPublished - leftPublished;
+  });
+};
+
+export const registerAnnouncementHelpRoutes = ({
+  app,
+  basePath,
+  defaultAcknowledgementPolicy = "dismiss-only",
+  isStaff = defaultIsStaff,
+  matchAudience,
+}: {
+  app: import("express").Application;
+  basePath: string;
+  defaultAcknowledgementPolicy?: AcknowledgementPolicy;
+  isStaff?: (user: unknown) => boolean;
+  matchAudience?: MatchAudienceFunction;
+}): void => {
+  const audienceMatcher = matchAudience ?? (() => true);
+
+  const matchesAnnouncementAudience = async (
+    user: unknown,
+    announcement: AnnouncementDocument
+  ): Promise<boolean> => {
+    if (!matchAudienceByType({announcement, isStaff, user})) {
+      return false;
+    }
+    return audienceMatcher(user, announcement);
+  };
+  const router = Router();
+
+  router.get(
+    "/help/search",
+    authenticateMiddleware(),
+    asyncHandler(async (req: Request, res: Response) => {
+      const user = req.user;
+      if (!user) {
+        throw new APIError({status: 401, title: "Authentication required"});
+      }
+
+      const queries = parseHelpQueries(req);
+      const includeArchived = parseIncludeArchived(req);
+      const limit = parseLimit(req);
+      const queryVersion = parseQueryVersion(req.query.version);
+      const statuses = buildHelpStatusFilter(includeArchived);
+
+      const candidates = (await Announcement.find({status: {$in: statuses}}).lean()) as Array<
+        AnnouncementDocument & {requiresAcknowledgement?: boolean}
+      >;
+      const matched: AnnouncementDocument[] = [];
+      for (const doc of candidates) {
+        if (!isAnnouncementHelpVisible(doc)) {
+          continue;
+        }
+        if (!passesMinBuildNumber({announcement: doc, queryVersion})) {
+          continue;
+        }
+        const matchesAudience = await matchesAnnouncementAudience(user, doc);
+        if (!matchesAudience) {
+          continue;
+        }
+        if (!matchesHelpQueries(doc, queries)) {
+          continue;
+        }
+        matched.push(doc);
+      }
+
+      const page = sortHelpResults(matched).slice(0, limit).map(toHelpSummary);
+
+      return res.json({data: page, total: matched.length});
+    })
+  );
+
+  router.get(
+    "/help/:id",
+    authenticateMiddleware(),
+    asyncHandler(async (req: Request, res: Response) => {
+      const user = req.user;
+      if (!user) {
+        throw new APIError({status: 401, title: "Authentication required"});
+      }
+
+      const includeArchived = parseIncludeArchived(req);
+      const queryVersion = parseQueryVersion(req.query.version);
+      const statuses = buildHelpStatusFilter(includeArchived);
+      const announcement = (await Announcement.findById(req.params.id).lean()) as
+        | (AnnouncementDocument & {requiresAcknowledgement?: boolean})
+        | null;
+      if (!announcement || !statuses.includes(announcement.status)) {
+        throw new APIError({status: 404, title: "Update note not found"});
+      }
+      if (!isAnnouncementHelpVisible(announcement)) {
+        throw new APIError({status: 404, title: "Update note not found"});
+      }
+      if (!passesMinBuildNumber({announcement, queryVersion})) {
+        throw new APIError({status: 404, title: "Update note not found"});
+      }
+      const matchesAudience = await matchesAnnouncementAudience(user, announcement);
+      if (!matchesAudience) {
+        throw new APIError({status: 404, title: "Update note not found"});
+      }
+      return res.json({data: toHelpDetail(announcement, defaultAcknowledgementPolicy)});
+    })
+  );
+
+  app.use(basePath, router);
+};

package/src/index.ts

@@ -0,0 +1,45 @@
+export {AnnouncementsApp} from "./announcementsApp";
+export type {AnnouncementHelpDetail, AnnouncementHelpSummary} from "./help";
+export {
+  buildHelpStatusFilter,
+  excerptBody,
+  matchesHelpQueries,
+  toHelpDetail,
+  toHelpSummary,
+} from "./help";
+export {Announcement, toAnnouncementPublic} from "./models/announcement";
+export {AnnouncementAcknowledgement} from "./models/announcementAcknowledgement";
+export {AnnouncementClickEvent} from "./models/announcementClickEvent";
+export {AnnouncementImpression} from "./models/announcementImpression";
+export {
+  isAnnouncementPendingForUser,
+  isAnnouncementVisibleNow,
+  isAnnouncementVisibleToUser,
+  isInterruptDisplayMode,
+  matchAudienceByType,
+  parseQueryVersion,
+  passesMinBuildNumber,
+  requiresAcknowledgementForAnnouncement,
+  resolveAcknowledgementPolicy,
+  resolveAudienceType,
+  resolveDisplayMode,
+  selectPendingAnnouncements,
+  sortAnnouncementsForQueue,
+} from "./pending";
+export type {
+  AcknowledgementPolicy,
+  AnnouncementAudienceType,
+  AnnouncementClickAction,
+  AnnouncementDisplayMode,
+  AnnouncementDocument,
+  AnnouncementOverviewMetrics,
+  AnnouncementOverviewResponse,
+  AnnouncementOverviewRow,
+  AnnouncementOverviewTotals,
+  AnnouncementPlatform,
+  AnnouncementPrimaryAction,
+  AnnouncementPublic,
+  AnnouncementsHelpOptions,
+  AnnouncementsOptions,
+  MatchAudienceFunction,
+} from "./types";

package/src/models/announcement.ts

@@ -0,0 +1,189 @@
+import {
+  APIError,
+  createdUpdatedPlugin,
+  findExactlyOne,
+  findOneOrNone,
+  isDeletedPlugin,
+} from "@terreno/api";
+import mongoose from "mongoose";
+import {requiresAcknowledgementForAnnouncement, resolveDisplayMode} from "../pending";
+import type {
+  AcknowledgementPolicy,
+  AnnouncementDocument,
+  AnnouncementModel,
+  AnnouncementPlatform,
+  AnnouncementPrimaryAction,
+  AnnouncementPublic,
+} from "../types";
+
+const ALL_PLATFORMS: AnnouncementPlatform[] = ["ios", "android", "web"];
+
+const announcementSchema = new mongoose.Schema<AnnouncementDocument, AnnouncementModel>(
+  {
+    acknowledgementPolicy: {
+      description:
+        "Whether users must acknowledge (required) or may dismiss with an impression only (dismiss-only). Omitted values resolve from the plugin defaultAcknowledgementPolicy at read time.",
+      enum: ["required", "dismiss-only"],
+      type: String,
+    },
+    archivedAt: {
+      description: "When the announcement was archived",
+      type: Date,
+    },
+    audience: {
+      default: {},
+      description: "Opaque targeting metadata consumed by matchAudience callback",
+      type: mongoose.Schema.Types.Mixed,
+    },
+    audienceType: {
+      default: "all",
+      description:
+        "First-class audience targeting: staff, patient, or all. Composed with matchAudience via matchAudienceByType.",
+      enum: ["staff", "patient", "all"],
+      type: String,
+    },
+    body: {
+      description: "Markdown body shown in the announcement modal",
+      required: true,
+      trim: true,
+      type: String,
+    },
+    displayMode: {
+      default: "modal",
+      description:
+        "Where the announcement appears: blocking modal, non-blocking banner, or feed-only changelog entry",
+      enum: ["modal", "banner", "feed"],
+      type: String,
+    },
+    expiresAt: {
+      description: "Optional expiry — hidden from pending/feed after this time",
+      type: Date,
+    },
+    minBuildNumber: {
+      description:
+        "Optional minimum client build number. Hidden from pending, feed, and help when query version is a finite integer below this value",
+      min: 1,
+      type: Number,
+    },
+    platforms: {
+      default: ALL_PLATFORMS,
+      description: "Platforms that should receive this announcement",
+      enum: ALL_PLATFORMS,
+      type: [String],
+    },
+    primaryAction: {
+      label: {
+        description: "Button label for optional primary action",
+        type: String,
+      },
+      url: {
+        description: "Deep link or external URL opened by the primary action button",
+        type: String,
+      },
+    },
+    priority: {
+      default: 0,
+      description: "Higher priority announcements appear first in the modal queue",
+      type: Number,
+    },
+    publishAt: {
+      description: "Optional scheduled publish time — hidden until this instant",
+      type: Date,
+    },
+    publishedAt: {
+      description: "When the announcement was first published",
+      type: Date,
+    },
+    status: {
+      default: "draft",
+      description: "Lifecycle status: draft, published, or archived",
+      enum: ["draft", "published", "archived"],
+      required: true,
+      type: String,
+    },
+    title: {
+      description: "Announcement title shown in modal and changelog feed",
+      required: true,
+      trim: true,
+      type: String,
+    },
+    version: {
+      default: 1,
+      description: "Content version — increments when published title/body changes",
+      min: 1,
+      type: Number,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+announcementSchema.plugin(createdUpdatedPlugin);
+announcementSchema.plugin(isDeletedPlugin);
+announcementSchema.plugin(findExactlyOne);
+announcementSchema.plugin(findOneOrNone);
+
+announcementSchema.index({publishAt: 1, status: 1});
+announcementSchema.index({priority: -1, publishedAt: -1, status: 1});
+
+announcementSchema.pre("save", async function bumpVersionOnPublishedEdit() {
+  if (this.isNew) {
+    return;
+  }
+  if (this.status !== "published") {
+    return;
+  }
+  if (!this.isModified("title") && !this.isModified("body")) {
+    return;
+  }
+
+  const previous = await Announcement.findById(this._id).select("title body status version");
+  if (previous?.status !== "published") {
+    return;
+  }
+  if (previous.title === this.title && previous.body === this.body) {
+    return;
+  }
+
+  this.version = (previous.version ?? 1) + 1;
+});
+
+announcementSchema.pre("validate", function validatePrimaryAction() {
+  const action = this.primaryAction as AnnouncementPrimaryAction | undefined;
+  if (!action) {
+    return;
+  }
+  const hasLabel = Boolean(action.label?.trim());
+  const hasUrl = Boolean(action.url?.trim());
+  if (!hasLabel && !hasUrl) {
+    this.primaryAction = undefined;
+    return;
+  }
+  if (!hasLabel || !hasUrl) {
+    throw new APIError({
+      status: 400,
+      title: "primaryAction requires both label and url when provided",
+    });
+  }
+});
+
+export const Announcement =
+  (mongoose.models.Announcement as AnnouncementModel) ??
+  mongoose.model<AnnouncementDocument, AnnouncementModel>("Announcement", announcementSchema);
+
+export const toAnnouncementPublic = (
+  doc: AnnouncementDocument,
+  defaultAcknowledgementPolicy: AcknowledgementPolicy = "dismiss-only"
+): AnnouncementPublic => ({
+  body: doc.body,
+  displayMode: resolveDisplayMode(doc),
+  id: doc._id.toString(),
+  primaryAction: doc.primaryAction,
+  priority: doc.priority,
+  publishedAt: doc.publishedAt?.toISOString(),
+  requiresAcknowledgement: requiresAcknowledgementForAnnouncement({
+    announcement: doc,
+    defaultAcknowledgementPolicy,
+  }),
+  title: doc.title,
+  version: doc.version,
+});

package/src/models/announcementAcknowledgement.ts

@@ -0,0 +1,50 @@
+import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "@terreno/api";
+import mongoose from "mongoose";
+import type {AnnouncementAcknowledgementDocument, AnnouncementAcknowledgementModel} from "../types";
+
+const announcementAcknowledgementSchema = new mongoose.Schema<
+  AnnouncementAcknowledgementDocument,
+  AnnouncementAcknowledgementModel
+>(
+  {
+    acknowledgedAt: {
+      description: "When the user acknowledged this announcement version",
+      required: true,
+      type: Date,
+    },
+    announcementId: {
+      description: "Announcement that was acknowledged",
+      index: true,
+      ref: "Announcement",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    userId: {
+      description: "User who acknowledged the announcement",
+      index: true,
+      ref: "User",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    version: {
+      description: "Announcement version acknowledged by the user",
+      required: true,
+      type: Number,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+announcementAcknowledgementSchema.plugin(createdUpdatedPlugin);
+announcementAcknowledgementSchema.plugin(isDeletedPlugin);
+announcementAcknowledgementSchema.plugin(findExactlyOne);
+announcementAcknowledgementSchema.plugin(findOneOrNone);
+
+announcementAcknowledgementSchema.index({announcementId: 1, userId: 1, version: 1}, {unique: true});
+
+export const AnnouncementAcknowledgement =
+  (mongoose.models.AnnouncementAcknowledgement as AnnouncementAcknowledgementModel) ??
+  mongoose.model<AnnouncementAcknowledgementDocument, AnnouncementAcknowledgementModel>(
+    "AnnouncementAcknowledgement",
+    announcementAcknowledgementSchema
+  );

package/src/models/announcementClickEvent.ts

@@ -0,0 +1,68 @@
+import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "@terreno/api";
+import mongoose from "mongoose";
+import type {
+  AnnouncementClickAction,
+  AnnouncementClickEventDocument,
+  AnnouncementClickEventModel,
+} from "../types";
+
+const announcementClickEventSchema = new mongoose.Schema<
+  AnnouncementClickEventDocument,
+  AnnouncementClickEventModel
+>(
+  {
+    action: {
+      description: "Which announcement action the user clicked",
+      enum: ["primaryAction"],
+      required: true,
+      type: String,
+    },
+    announcementId: {
+      description: "Announcement whose primary action was clicked",
+      index: true,
+      ref: "Announcement",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    clickedAt: {
+      description: "When the primary action was clicked",
+      required: true,
+      type: Date,
+    },
+    platform: {
+      description: "Client platform where the click occurred",
+      enum: ["ios", "android", "web"],
+      type: String,
+    },
+    userId: {
+      description: "User who clicked the announcement action",
+      index: true,
+      ref: "User",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    version: {
+      description: "Announcement version at click time",
+      required: true,
+      type: Number,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+announcementClickEventSchema.plugin(createdUpdatedPlugin);
+announcementClickEventSchema.plugin(isDeletedPlugin);
+announcementClickEventSchema.plugin(findExactlyOne);
+announcementClickEventSchema.plugin(findOneOrNone);
+
+announcementClickEventSchema.index({announcementId: 1, clickedAt: -1});
+
+export const AnnouncementClickEvent =
+  (mongoose.models.AnnouncementClickEvent as AnnouncementClickEventModel) ??
+  mongoose.model<AnnouncementClickEventDocument, AnnouncementClickEventModel>(
+    "AnnouncementClickEvent",
+    announcementClickEventSchema
+  );
+
+export const isValidClickAction = (value: unknown): value is AnnouncementClickAction =>
+  value === "primaryAction";

package/src/models/announcementImpression.ts

@@ -0,0 +1,62 @@
+import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "@terreno/api";
+import mongoose from "mongoose";
+import type {
+  AnnouncementImpressionDocument,
+  AnnouncementImpressionModel,
+  AnnouncementPlatform,
+} from "../types";
+
+const announcementImpressionSchema = new mongoose.Schema<
+  AnnouncementImpressionDocument,
+  AnnouncementImpressionModel
+>(
+  {
+    announcementId: {
+      description: "Announcement that was viewed",
+      index: true,
+      ref: "Announcement",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    platform: {
+      description: "Client platform where the impression occurred",
+      enum: ["ios", "android", "web"],
+      type: String,
+    },
+    userId: {
+      description: "User who viewed the announcement",
+      index: true,
+      ref: "User",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    version: {
+      description: "Announcement version viewed by the user",
+      required: true,
+      type: Number,
+    },
+    viewedAt: {
+      description: "When the announcement was viewed",
+      required: true,
+      type: Date,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+announcementImpressionSchema.plugin(createdUpdatedPlugin);
+announcementImpressionSchema.plugin(isDeletedPlugin);
+announcementImpressionSchema.plugin(findExactlyOne);
+announcementImpressionSchema.plugin(findOneOrNone);
+
+announcementImpressionSchema.index({announcementId: 1, viewedAt: -1});
+
+export const AnnouncementImpression =
+  (mongoose.models.AnnouncementImpression as AnnouncementImpressionModel) ??
+  mongoose.model<AnnouncementImpressionDocument, AnnouncementImpressionModel>(
+    "AnnouncementImpression",
+    announcementImpressionSchema
+  );
+
+export const isValidPlatform = (value: unknown): value is AnnouncementPlatform =>
+  value === "ios" || value === "android" || value === "web";