@terreno/announcements 57.4.0

package/src/overview.ts

@@ -0,0 +1,228 @@
+import type {PipelineStage, Types} from "mongoose";
+import {Announcement} from "./models/announcement";
+import {AnnouncementAcknowledgement} from "./models/announcementAcknowledgement";
+import {AnnouncementClickEvent} from "./models/announcementClickEvent";
+import {AnnouncementImpression} from "./models/announcementImpression";
+import {resolveAcknowledgementPolicy, resolveAudienceType, resolveDisplayMode} from "./pending";
+import type {
+  AcknowledgementPolicy,
+  AnnouncementDocument,
+  AnnouncementOverviewMetrics,
+  AnnouncementOverviewResponse,
+  AnnouncementOverviewRow,
+  AnnouncementOverviewTotals,
+} from "./types";
+
+const NOT_DELETED = {deleted: {$ne: true}} as const;
+
+export interface OverviewPagination {
+  limit: number;
+  page: number;
+}
+
+export const parseOverviewPagination = (query: {
+  limit?: unknown;
+  page?: unknown;
+}): OverviewPagination => {
+  const parsedLimit = Number(query.limit ?? 20);
+  const parsedPage = Number(query.page ?? 1);
+  const limit = Number.isFinite(parsedLimit)
+    ? Math.min(Math.max(Math.trunc(parsedLimit), 1), 100)
+    : 20;
+  const page = Number.isFinite(parsedPage) ? Math.max(Math.trunc(parsedPage), 1) : 1;
+  return {limit, page};
+};
+
+interface MetricCountRow {
+  _id: Types.ObjectId;
+  count: number;
+}
+
+const countEventTotals = async (): Promise<{
+  acknowledgements: number;
+  clicks: number;
+  impressions: number;
+}> => {
+  const [impressionRows, acknowledgementRows, clickRows] = await Promise.all([
+    AnnouncementImpression.aggregate<{count: number}>([{$match: NOT_DELETED}, {$count: "count"}]),
+    AnnouncementAcknowledgement.aggregate<{count: number}>([
+      {$match: NOT_DELETED},
+      {$count: "count"},
+    ]),
+    AnnouncementClickEvent.aggregate<{count: number}>([{$match: NOT_DELETED}, {$count: "count"}]),
+  ]);
+
+  return {
+    acknowledgements: acknowledgementRows[0]?.count ?? 0,
+    clicks: clickRows[0]?.count ?? 0,
+    impressions: impressionRows[0]?.count ?? 0,
+  };
+};
+
+const countMetricsByAnnouncement = async (
+  announcementIds: Types.ObjectId[]
+): Promise<Map<string, AnnouncementOverviewMetrics>> => {
+  const metrics = new Map<string, AnnouncementOverviewMetrics>();
+  for (const id of announcementIds) {
+    metrics.set(id.toString(), {acknowledgements: 0, clicks: 0, impressions: 0});
+  }
+
+  if (announcementIds.length === 0) {
+    return metrics;
+  }
+
+  const matchByAnnouncement: PipelineStage.Match = {
+    $match: {
+      ...NOT_DELETED,
+      announcementId: {$in: announcementIds},
+    },
+  };
+
+  const [impressionCounts, acknowledgementCounts, clickCounts] = await Promise.all([
+    AnnouncementImpression.aggregate<MetricCountRow>([
+      matchByAnnouncement,
+      {$group: {_id: "$announcementId", count: {$sum: 1}}},
+    ]),
+    AnnouncementAcknowledgement.aggregate<MetricCountRow>([
+      matchByAnnouncement,
+      {$group: {_id: "$announcementId", count: {$sum: 1}}},
+    ]),
+    AnnouncementClickEvent.aggregate<MetricCountRow>([
+      matchByAnnouncement,
+      {$group: {_id: "$announcementId", count: {$sum: 1}}},
+    ]),
+  ]);
+
+  for (const row of impressionCounts) {
+    const existing = metrics.get(row._id.toString()) ?? {
+      acknowledgements: 0,
+      clicks: 0,
+      impressions: 0,
+    };
+    existing.impressions = row.count;
+    metrics.set(row._id.toString(), existing);
+  }
+
+  for (const row of acknowledgementCounts) {
+    const existing = metrics.get(row._id.toString()) ?? {
+      acknowledgements: 0,
+      clicks: 0,
+      impressions: 0,
+    };
+    existing.acknowledgements = row.count;
+    metrics.set(row._id.toString(), existing);
+  }
+
+  for (const row of clickCounts) {
+    const existing = metrics.get(row._id.toString()) ?? {
+      acknowledgements: 0,
+      clicks: 0,
+      impressions: 0,
+    };
+    existing.clicks = row.count;
+    metrics.set(row._id.toString(), existing);
+  }
+
+  return metrics;
+};
+
+const toOverviewRow = ({
+  announcement,
+  defaultAcknowledgementPolicy,
+  metrics,
+}: {
+  announcement: AnnouncementDocument;
+  defaultAcknowledgementPolicy: AcknowledgementPolicy;
+  metrics: AnnouncementOverviewMetrics;
+}): AnnouncementOverviewRow => ({
+  _id: announcement._id.toString(),
+  acknowledgementPolicy: resolveAcknowledgementPolicy({
+    announcement,
+    defaultAcknowledgementPolicy,
+  }),
+  audienceType: resolveAudienceType(announcement),
+  displayMode: resolveDisplayMode(announcement),
+  expiresAt: announcement.expiresAt?.toISOString(),
+  metrics,
+  priority: announcement.priority,
+  publishedAt: announcement.publishedAt?.toISOString(),
+  status: announcement.status,
+  title: announcement.title,
+  version: announcement.version,
+});
+
+export const fetchAnnouncementOverview = async ({
+  defaultAcknowledgementPolicy,
+  limit,
+  page,
+}: {
+  defaultAcknowledgementPolicy: AcknowledgementPolicy;
+  limit: number;
+  page: number;
+}): Promise<AnnouncementOverviewResponse> => {
+  const skip = (page - 1) * limit;
+
+  const [facetResult, eventTotals] = await Promise.all([
+    Announcement.aggregate<{
+      paginated: AnnouncementDocument[];
+      statusCounts: Array<{_id: AnnouncementDocument["status"]; count: number}>;
+      totalCount: Array<{count: number}>;
+    }>([
+      {$match: NOT_DELETED},
+      {
+        $facet: {
+          paginated: [
+            // biome-ignore assist/source/useSortedKeys: MongoDB applies sort keys in insertion order
+            {$sort: {priority: -1, publishedAt: -1, _id: -1}},
+            {$skip: skip},
+            {$limit: limit},
+          ],
+          statusCounts: [{$group: {_id: "$status", count: {$sum: 1}}}],
+          totalCount: [{$count: "count"}],
+        },
+      },
+    ]),
+    countEventTotals(),
+  ]);
+
+  const facet = facetResult[0];
+  const paginated = facet?.paginated ?? [];
+  const total = facet?.totalCount[0]?.count ?? 0;
+  const statusCounts = facet?.statusCounts ?? [];
+
+  const statusCountMap = new Map(statusCounts.map((row) => [row._id, row.count]));
+  const totals: AnnouncementOverviewTotals = {
+    acknowledgements: eventTotals.acknowledgements,
+    announcements: total,
+    archived: statusCountMap.get("archived") ?? 0,
+    clicks: eventTotals.clicks,
+    draft: statusCountMap.get("draft") ?? 0,
+    impressions: eventTotals.impressions,
+    published: statusCountMap.get("published") ?? 0,
+  };
+
+  const metricsByAnnouncement = await countMetricsByAnnouncement(
+    paginated.map((announcement) => announcement._id)
+  );
+
+  const data = paginated.map((announcement) =>
+    toOverviewRow({
+      announcement,
+      defaultAcknowledgementPolicy,
+      metrics: metricsByAnnouncement.get(announcement._id.toString()) ?? {
+        acknowledgements: 0,
+        clicks: 0,
+        impressions: 0,
+      },
+    })
+  );
+
+  return {
+    data,
+    limit,
+    more: skip + data.length < total,
+    page,
+    total,
+    totals,
+  };
+};

package/src/pending.ts

@@ -0,0 +1,286 @@
+import {DateTime} from "luxon";
+import type {
+  AcknowledgementPolicy,
+  AnnouncementAudienceType,
+  AnnouncementDisplayMode,
+  AnnouncementDocument,
+  AnnouncementPlatform,
+} from "./types";
+
+export interface AnnouncementAckState {
+  announcementId: string;
+  version: number;
+}
+
+export interface AnnouncementImpressionState {
+  announcementId: string;
+  version: number;
+}
+
+type AnnouncementWithLegacyAck = AnnouncementDocument & {
+  requiresAcknowledgement?: boolean;
+};
+
+export const resolveAcknowledgementPolicy = ({
+  announcement,
+  defaultAcknowledgementPolicy = "dismiss-only",
+}: {
+  announcement: AnnouncementDocument;
+  defaultAcknowledgementPolicy?: AcknowledgementPolicy;
+}): AcknowledgementPolicy => {
+  if (announcement.acknowledgementPolicy) {
+    return announcement.acknowledgementPolicy;
+  }
+
+  const legacyRequiresAck = (announcement as AnnouncementWithLegacyAck).requiresAcknowledgement;
+  if (legacyRequiresAck === true) {
+    return "required";
+  }
+
+  return defaultAcknowledgementPolicy;
+};
+
+export const requiresAcknowledgementForAnnouncement = ({
+  announcement,
+  defaultAcknowledgementPolicy = "dismiss-only",
+}: {
+  announcement: AnnouncementDocument;
+  defaultAcknowledgementPolicy?: AcknowledgementPolicy;
+}): boolean => {
+  const policy = resolveAcknowledgementPolicy({announcement, defaultAcknowledgementPolicy});
+  return policy === "required";
+};
+
+export const resolveDisplayMode = (announcement: AnnouncementDocument): AnnouncementDisplayMode => {
+  const mode = announcement.displayMode;
+  if (mode === "modal" || mode === "banner" || mode === "feed") {
+    return mode;
+  }
+  return "modal";
+};
+
+export const resolveAudienceType = (
+  announcement: AnnouncementDocument
+): AnnouncementAudienceType => {
+  const audienceType = announcement.audienceType;
+  if (audienceType === "staff" || audienceType === "patient" || audienceType === "all") {
+    return audienceType;
+  }
+  return "all";
+};
+
+export const matchAudienceByType = ({
+  announcement,
+  isStaff,
+  user,
+}: {
+  announcement: AnnouncementDocument;
+  isStaff: (user: unknown) => boolean;
+  user: unknown;
+}): boolean => {
+  const audienceType = resolveAudienceType(announcement);
+  if (audienceType === "all") {
+    return true;
+  }
+
+  const staff = isStaff(user);
+  if (audienceType === "staff") {
+    return staff;
+  }
+
+  return !staff;
+};
+
+export const parseQueryVersion = (raw: unknown): number | undefined => {
+  if (raw === undefined || raw === null || raw === "") {
+    return undefined;
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+    return undefined;
+  }
+
+  return parsed;
+};
+
+export const passesMinBuildNumber = ({
+  announcement,
+  queryVersion,
+}: {
+  announcement: AnnouncementDocument;
+  queryVersion?: number;
+}): boolean => {
+  const minBuildNumber = announcement.minBuildNumber;
+  if (minBuildNumber === undefined || minBuildNumber === null || minBuildNumber === 0) {
+    return true;
+  }
+
+  if (queryVersion === undefined) {
+    return true;
+  }
+
+  return queryVersion >= minBuildNumber;
+};
+
+export const isInterruptDisplayMode = (announcement: AnnouncementDocument): boolean => {
+  const displayMode = resolveDisplayMode(announcement);
+  return displayMode === "modal" || displayMode === "banner";
+};
+
+export const isAnnouncementVisibleNow = ({
+  announcement,
+  now = DateTime.utc(),
+}: {
+  announcement: AnnouncementDocument;
+  now?: DateTime;
+}): boolean => {
+  if (announcement.status !== "published") {
+    return false;
+  }
+
+  if (announcement.publishAt) {
+    const publishAt = DateTime.fromJSDate(announcement.publishAt);
+    if (publishAt > now) {
+      return false;
+    }
+  }
+
+  if (announcement.expiresAt) {
+    const expiresAt = DateTime.fromJSDate(announcement.expiresAt);
+    if (expiresAt <= now) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+export const matchesPlatform = ({
+  announcement,
+  platform,
+}: {
+  announcement: AnnouncementDocument;
+  platform: AnnouncementPlatform;
+}): boolean => {
+  const platforms = announcement.platforms?.length
+    ? announcement.platforms
+    : (["ios", "android", "web"] as AnnouncementPlatform[]);
+  return platforms.includes(platform);
+};
+
+export const isAnnouncementPendingForUser = ({
+  acknowledgements,
+  announcement,
+  defaultAcknowledgementPolicy = "dismiss-only",
+  impressions,
+}: {
+  acknowledgements: AnnouncementAckState[];
+  announcement: AnnouncementDocument;
+  defaultAcknowledgementPolicy?: AcknowledgementPolicy;
+  impressions: AnnouncementImpressionState[];
+}): boolean => {
+  const announcementId = announcement._id.toString();
+  const needsAck = requiresAcknowledgementForAnnouncement({
+    announcement,
+    defaultAcknowledgementPolicy,
+  });
+
+  if (needsAck) {
+    const hasAck = acknowledgements.some(
+      (ack) => ack.announcementId === announcementId && ack.version === announcement.version
+    );
+    return !hasAck;
+  }
+
+  const hasImpression = impressions.some(
+    (impression) =>
+      impression.announcementId === announcementId && impression.version === announcement.version
+  );
+  return !hasImpression;
+};
+
+export const sortAnnouncementsForQueue = (
+  announcements: AnnouncementDocument[]
+): AnnouncementDocument[] =>
+  [...announcements].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 selectPendingAnnouncements = ({
+  acknowledgements,
+  announcements,
+  defaultAcknowledgementPolicy = "dismiss-only",
+  impressions,
+  now,
+  platform,
+  queryVersion,
+}: {
+  acknowledgements: AnnouncementAckState[];
+  announcements: AnnouncementDocument[];
+  defaultAcknowledgementPolicy?: AcknowledgementPolicy;
+  impressions: AnnouncementImpressionState[];
+  now?: DateTime;
+  platform: AnnouncementPlatform;
+  queryVersion?: number;
+}): AnnouncementDocument[] => {
+  const visible = announcements.filter((announcement) => {
+    if (!isAnnouncementVisibleNow({announcement, now})) {
+      return false;
+    }
+    if (!matchesPlatform({announcement, platform})) {
+      return false;
+    }
+    if (!isInterruptDisplayMode(announcement)) {
+      return false;
+    }
+    if (!passesMinBuildNumber({announcement, queryVersion})) {
+      return false;
+    }
+    return isAnnouncementPendingForUser({
+      acknowledgements,
+      announcement,
+      defaultAcknowledgementPolicy,
+      impressions,
+    });
+  });
+
+  return sortAnnouncementsForQueue(visible);
+};
+
+export const isAnnouncementVisibleToUser = async ({
+  announcement,
+  isStaff,
+  matchAudience,
+  now,
+  platform,
+  queryVersion,
+  user,
+}: {
+  announcement: AnnouncementDocument;
+  isStaff: (user: unknown) => boolean;
+  matchAudience: (user: unknown, announcement: AnnouncementDocument) => boolean | Promise<boolean>;
+  now?: DateTime;
+  platform: AnnouncementPlatform;
+  queryVersion?: number;
+  user: unknown;
+}): Promise<boolean> => {
+  if (!isAnnouncementVisibleNow({announcement, now})) {
+    return false;
+  }
+  if (!matchesPlatform({announcement, platform})) {
+    return false;
+  }
+  if (!passesMinBuildNumber({announcement, queryVersion})) {
+    return false;
+  }
+  if (!matchAudienceByType({announcement, isStaff, user})) {
+    return false;
+  }
+  return matchAudience(user, announcement);
+};