@terreno/announcements 57.7.0 → 57.9.0

package/src/announcementsApp.ts

@@ -19,7 +19,7 @@ import type {Model} from "mongoose";
 import {registerAnnouncementHelpRoutes} from "./helpRoutes";
 import {Announcement, toAnnouncementPublic} from "./models/announcement";
 import {AnnouncementAcknowledgement} from "./models/announcementAcknowledgement";
-import {AnnouncementClickEvent, isValidClickAction} from "./models/announcementClickEvent";
+import {AnnouncementClickEvent} from "./models/announcementClickEvent";
 import {AnnouncementImpression, isValidPlatform} from "./models/announcementImpression";
 import {fetchAnnouncementOverview, parseOverviewPagination} from "./overview";
 import {
@@ -31,6 +31,17 @@ import {
   passesMinBuildNumber,
   selectPendingAnnouncements,
 } from "./pending";
+import {
+  announcementReleaseImportSchema,
+  importAnnouncementRelease,
+  requireAnnouncementUploadAccess,
+} from "./releaseImport";
+import {
+  announcementClickBodySchema,
+  announcementClickPlatformSchema,
+  announcementImpressionBodySchema,
+  parseAnnouncementBody,
+} from "./requestBodies";
 import type {
   AcknowledgementPolicy,
   AnnouncementDocument,
@@ -96,16 +107,6 @@ const hasPrimaryAction = (announcement: AnnouncementDocument): boolean => {
   return Boolean(label && url);
 };
 
-const resolveClickPlatform = (req: Request, bodyPlatform: unknown): AnnouncementPlatform => {
-  if (bodyPlatform !== undefined && bodyPlatform !== null) {
-    if (!isValidPlatform(bodyPlatform)) {
-      throw new APIError({status: 400, title: "Invalid platform"});
-    }
-    return bodyPlatform;
-  }
-  return parsePlatform(req);
-};
-
 const requireVisibleAnnouncement = async ({
   announcement,
   isStaff,
@@ -254,6 +255,22 @@ export class AnnouncementsApp implements TerrenoPlugin {
 
     const routerOptions: ModelRouterOptions<AnnouncementDocument> = {
       ...(openApi ? {openApi: openApi as OpenApiMiddleware} : {}),
+      collectionActions: {
+        "import-release": {
+          allowAnonymous: true,
+          body: announcementReleaseImportSchema,
+          description:
+            "Idempotently create or update a release pack. Defaults to drafts; set publish=true to publish.",
+          handler: async ({body, req}) => {
+            requireAnnouncementUploadAccess({req, uploadToken: this.options.uploadToken});
+            return importAnnouncementRelease({input: body});
+          },
+          method: "POST",
+          permissions: [Permissions.IsAny],
+          summary: "Import a product release announcement pack",
+          tag: "announcements",
+        },
+      },
       permissions: {
         create: [Permissions.IsAdmin],
         delete: [Permissions.IsAdmin],
@@ -434,8 +451,11 @@ export class AnnouncementsApp implements TerrenoPlugin {
         }
 
         const userId = getUserId(user as {_id?: unknown; id?: string});
-        const bodyPlatform = (req.body as {platform?: unknown})?.platform;
-        const platform = isValidPlatform(bodyPlatform) ? bodyPlatform : parsePlatform(req);
+        const body = parseAnnouncementBody({
+          body: req.body,
+          schema: announcementImpressionBodySchema,
+        });
+        const platform = body.platform ?? parsePlatform(req);
         const announcement = await requireVisibleAnnouncement({
           announcement: await Announcement.findById(req.params.id),
           isStaff,
@@ -467,8 +487,11 @@ export class AnnouncementsApp implements TerrenoPlugin {
         }
 
         const userId = getUserId(user as {_id?: unknown; id?: string});
-        const body = req.body as {action?: unknown; platform?: unknown};
-        const platform = resolveClickPlatform(req, body.platform);
+        const {platform: bodyPlatform} = parseAnnouncementBody({
+          body: req.body,
+          schema: announcementClickPlatformSchema,
+        });
+        const platform = bodyPlatform ?? parsePlatform(req);
         const announcement = await requireVisibleAnnouncement({
           announcement: await Announcement.findById(req.params.id),
           isStaff,
@@ -478,9 +501,7 @@ export class AnnouncementsApp implements TerrenoPlugin {
           user,
         });
 
-        if (!isValidClickAction(body.action)) {
-          throw new APIError({status: 400, title: "Invalid click action"});
-        }
+        const body = parseAnnouncementBody({body: req.body, schema: announcementClickBodySchema});
 
         if (!hasPrimaryAction(announcement)) {
           throw new APIError({status: 400, title: "Announcement has no primary action"});

package/src/index.ts

@@ -26,6 +26,16 @@ export {
   selectPendingAnnouncements,
   sortAnnouncementsForQueue,
 } from "./pending";
+export type {
+  AnnouncementReleaseImportInput,
+  AnnouncementReleaseImportResult,
+  AnnouncementReleaseItemInput,
+} from "./releaseImport";
+export {
+  announcementReleaseImportSchema,
+  importAnnouncementRelease,
+  requireAnnouncementUploadAccess,
+} from "./releaseImport";
 export type {
   AcknowledgementPolicy,
   AnnouncementAudienceType,
@@ -39,6 +49,7 @@ export type {
   AnnouncementPlatform,
   AnnouncementPrimaryAction,
   AnnouncementPublic,
+  AnnouncementRelease,
   AnnouncementsHelpOptions,
   AnnouncementsOptions,
   MatchAudienceFunction,

package/src/models/announcement.ts

@@ -3,6 +3,7 @@ import {
   createdUpdatedPlugin,
   findExactlyOne,
   findOneOrNone,
+  findOneOrNoneFor,
   isDeletedPlugin,
 } from "@terreno/api";
 import mongoose from "mongoose";
@@ -94,6 +95,33 @@ const announcementSchema = new mongoose.Schema<AnnouncementDocument, Announcemen
       description: "When the announcement was first published",
       type: Date,
     },
+    release: {
+      buildNumber: {
+        description: "Client build number associated with the imported product release",
+        min: 1,
+        type: Number,
+      },
+      channel: {
+        description: "Release channel associated with the imported announcement",
+        trim: true,
+        type: String,
+      },
+      product: {
+        description: "Product identifier associated with the imported announcement",
+        trim: true,
+        type: String,
+      },
+      version: {
+        description: "User-facing product version associated with the imported announcement",
+        trim: true,
+        type: String,
+      },
+    },
+    releaseSlug: {
+      description: "Stable announcement identifier within an imported product release",
+      trim: true,
+      type: String,
+    },
     status: {
       default: "draft",
       description: "Lifecycle status: draft, published, or archived",
@@ -124,6 +152,18 @@ announcementSchema.plugin(findOneOrNone);
 
 announcementSchema.index({publishAt: 1, status: 1});
 announcementSchema.index({priority: -1, publishedAt: -1, status: 1});
+announcementSchema.index(
+  {"release.channel": 1, "release.product": 1, "release.version": 1, releaseSlug: 1},
+  {
+    partialFilterExpression: {
+      "release.channel": {$type: "string"},
+      "release.product": {$type: "string"},
+      "release.version": {$type: "string"},
+      releaseSlug: {$type: "string"},
+    },
+    unique: true,
+  }
+);
 
 announcementSchema.pre("save", async function bumpVersionOnPublishedEdit() {
   if (this.isNew) {
@@ -136,7 +176,12 @@ announcementSchema.pre("save", async function bumpVersionOnPublishedEdit() {
     return;
   }
 
-  const previous = await Announcement.findById(this._id).select("title body status version");
+  // A restored import clears `deleted` on this document while the stored row is still
+  // soft-deleted, so the default filter would hide the version being edited.
+  const previous = await findOneOrNoneFor(Announcement, {
+    _id: this._id,
+    deleted: {$in: [true, false]},
+  });
   if (previous?.status !== "published") {
     return;
   }

package/src/models/announcementClickEvent.ts

@@ -1,10 +1,6 @@
 import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "@terreno/api";
 import mongoose from "mongoose";
-import type {
-  AnnouncementClickAction,
-  AnnouncementClickEventDocument,
-  AnnouncementClickEventModel,
-} from "../types";
+import type {AnnouncementClickEventDocument, AnnouncementClickEventModel} from "../types";
 
 const announcementClickEventSchema = new mongoose.Schema<
   AnnouncementClickEventDocument,
@@ -64,6 +60,3 @@ export const AnnouncementClickEvent =
     announcementClickEventSchema,
     "announcementclickevents"
   );
-
-export const isValidClickAction = (value: unknown): value is AnnouncementClickAction =>
-  value === "primaryAction";

package/src/releaseImport.ts

@@ -0,0 +1,258 @@
+import {timingSafeEqual} from "node:crypto";
+import {APIError, findOneOrNoneFor, z} from "@terreno/api";
+import type {Request} from "express";
+import {DateTime} from "luxon";
+import {Announcement} from "./models/announcement";
+import {announcementPlatformSchema, parseAnnouncementBody} from "./requestBodies";
+import type {AnnouncementDocument, AnnouncementRelease} from "./types";
+
+const announcementDefaultsSchema = z
+  .object({
+    acknowledgementPolicy: z.enum(["required", "dismiss-only"]).optional(),
+    audience: z.unknown().optional(),
+    audienceType: z.enum(["staff", "patient", "all"]).optional(),
+    displayMode: z.enum(["modal", "banner", "feed"]).optional(),
+    expiresAt: z.string().datetime().optional(),
+    minBuildNumber: z.number().int().positive().optional(),
+    platforms: z.array(announcementPlatformSchema).min(1).optional(),
+    priority: z.number().optional(),
+    publishAt: z.string().datetime().optional(),
+  })
+  .strict();
+
+export const announcementReleaseImportSchema = z
+  .object({
+    announcements: z
+      .array(
+        announcementDefaultsSchema.extend({
+          body: z.string().min(1),
+          primaryAction: z
+            .object({
+              label: z.string().min(1),
+              url: z.string().url(),
+            })
+            .strict()
+            .optional(),
+          slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+          title: z.string().min(1),
+        })
+      )
+      .min(1)
+      .max(100),
+    defaults: announcementDefaultsSchema.optional(),
+    publish: z.boolean().default(false),
+    release: z
+      .object({
+        buildNumber: z.number().int().positive().optional(),
+        channel: z.string().min(1).default("production"),
+        product: z.string().min(1),
+        version: z.string().min(1),
+      })
+      .strict(),
+  })
+  .strict()
+  .superRefine((input, context) => {
+    const seenSlugs = new Set<string>();
+    for (const [index, item] of input.announcements.entries()) {
+      if (seenSlugs.has(item.slug)) {
+        context.addIssue({
+          code: "custom",
+          message: "Release announcement slugs must be unique",
+          path: ["announcements", index, "slug"],
+        });
+      }
+      seenSlugs.add(item.slug);
+    }
+  });
+
+type AnnouncementDefaultsInput = z.output<typeof announcementDefaultsSchema>;
+
+export type AnnouncementReleaseImportInput = z.output<typeof announcementReleaseImportSchema>;
+
+export type AnnouncementReleaseItemInput = AnnouncementReleaseImportInput["announcements"][number];
+
+export interface AnnouncementReleaseImportResult {
+  created: number;
+  published: number;
+  unchanged: number;
+  updated: number;
+  announcements: Array<{
+    id: string;
+    slug: string;
+    status: "draft" | "published" | "archived";
+    version: number;
+  }>;
+}
+
+const safeTokenEquals = ({expected, provided}: {expected: string; provided: string}): boolean => {
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  const providedBuffer = Buffer.from(provided, "utf8");
+  if (expectedBuffer.length !== providedBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(expectedBuffer, providedBuffer);
+};
+
+const readBearerToken = (req: Request): string | undefined => {
+  const authorization = req.get("authorization");
+  if (!authorization?.startsWith("Bearer ")) {
+    return undefined;
+  }
+  return authorization.slice("Bearer ".length);
+};
+
+export const requireAnnouncementUploadAccess = ({
+  req,
+  uploadToken,
+}: {
+  req: Request;
+  uploadToken?: string;
+}): void => {
+  if ((req.user as {admin?: boolean} | undefined)?.admin) {
+    return;
+  }
+  const providedToken = readBearerToken(req);
+  if (!uploadToken || !providedToken) {
+    throw new APIError({status: 401, title: "Announcement upload authentication required"});
+  }
+  if (!safeTokenEquals({expected: uploadToken, provided: providedToken})) {
+    throw new APIError({status: 401, title: "Invalid announcement upload token"});
+  }
+};
+
+const parseOptionalDate = (value?: string): Date | undefined => {
+  if (!value) {
+    return undefined;
+  }
+  return DateTime.fromISO(value, {setZone: true}).toJSDate();
+};
+
+const applyImportedValues = ({
+  announcement,
+  defaults,
+  item,
+  publish,
+  release,
+}: {
+  announcement: AnnouncementDocument;
+  defaults?: AnnouncementDefaultsInput;
+  item: AnnouncementReleaseItemInput;
+  publish: boolean;
+  release: AnnouncementRelease;
+}): void => {
+  const merged = {...defaults, ...item};
+  announcement.acknowledgementPolicy = merged.acknowledgementPolicy;
+  announcement.audience = merged.audience ?? {};
+  announcement.audienceType = merged.audienceType ?? "all";
+  announcement.body = item.body;
+  announcement.displayMode = merged.displayMode ?? "feed";
+  announcement.expiresAt = parseOptionalDate(merged.expiresAt);
+  announcement.minBuildNumber = merged.minBuildNumber ?? release.buildNumber;
+  announcement.platforms = merged.platforms ?? ["ios", "android", "web"];
+  announcement.primaryAction = item.primaryAction;
+  announcement.priority = merged.priority ?? 0;
+  announcement.publishAt = parseOptionalDate(merged.publishAt);
+  announcement.release = release;
+  announcement.releaseSlug = item.slug;
+  announcement.title = item.title;
+  if (!publish) {
+    return;
+  }
+  announcement.archivedAt = undefined;
+  announcement.publishedAt ??= DateTime.utc().toJSDate();
+  announcement.status = "published";
+};
+
+const snapshotImportedValues = (announcement: AnnouncementDocument): string =>
+  JSON.stringify({
+    acknowledgementPolicy: announcement.acknowledgementPolicy,
+    archivedAt: announcement.archivedAt,
+    audience: announcement.audience,
+    audienceType: announcement.audienceType,
+    body: announcement.body,
+    deleted: announcement.deleted,
+    displayMode: announcement.displayMode,
+    expiresAt: announcement.expiresAt,
+    minBuildNumber: announcement.minBuildNumber,
+    platforms: announcement.platforms,
+    primaryAction: announcement.primaryAction,
+    priority: announcement.priority,
+    publishAt: announcement.publishAt,
+    publishedAt: announcement.publishedAt,
+    release: announcement.release,
+    releaseSlug: announcement.releaseSlug,
+    status: announcement.status,
+    title: announcement.title,
+  });
+
+export const importAnnouncementRelease = async ({
+  input: rawInput,
+}: {
+  input: unknown;
+}): Promise<AnnouncementReleaseImportResult> => {
+  const input = parseAnnouncementBody({body: rawInput, schema: announcementReleaseImportSchema});
+
+  const result: AnnouncementReleaseImportResult = {
+    announcements: [],
+    created: 0,
+    published: 0,
+    unchanged: 0,
+    updated: 0,
+  };
+
+  for (const item of input.announcements) {
+    const existing = await findOneOrNoneFor(Announcement, {
+      deleted: {$in: [true, false]},
+      "release.channel": input.release.channel,
+      "release.product": input.release.product,
+      "release.version": input.release.version,
+      releaseSlug: item.slug,
+    });
+    const announcement =
+      existing ??
+      new Announcement({
+        audience: {},
+        body: item.body,
+        priority: 0,
+        release: input.release,
+        releaseSlug: item.slug,
+        status: "draft",
+        title: item.title,
+        version: 1,
+      });
+    const wasCreated = announcement.isNew;
+    const previousValues = snapshotImportedValues(announcement);
+
+    announcement.deleted = false;
+    applyImportedValues({
+      announcement,
+      defaults: input.defaults,
+      item,
+      publish: input.publish,
+      release: input.release,
+    });
+    const hasChanges = wasCreated || previousValues !== snapshotImportedValues(announcement);
+    if (hasChanges) {
+      await announcement.save();
+    }
+
+    if (wasCreated) {
+      result.created += 1;
+    } else if (hasChanges) {
+      result.updated += 1;
+    } else {
+      result.unchanged += 1;
+    }
+    if (input.publish && announcement.status === "published") {
+      result.published += 1;
+    }
+    result.announcements.push({
+      id: announcement._id.toString(),
+      slug: item.slug,
+      status: announcement.status,
+      version: announcement.version,
+    });
+  }
+
+  return result;
+};

package/src/requestBodies.ts

@@ -0,0 +1,50 @@
+import {ValidationError, z} from "@terreno/api";
+
+export const announcementPlatformSchema = z.enum(["ios", "android", "web"]);
+
+export const announcementImpressionBodySchema = z
+  .object({
+    platform: announcementPlatformSchema.optional(),
+  })
+  .strict();
+
+export const announcementClickBodySchema = z
+  .object({
+    action: z.literal("primaryAction"),
+    platform: announcementPlatformSchema.optional(),
+  })
+  .strict();
+
+// Visibility checks need the platform before the rest of the click body is validated, so hidden
+// announcements return 404 regardless of the action.
+export const announcementClickPlatformSchema = announcementClickBodySchema
+  .pick({platform: true})
+  .loose();
+
+const toFieldErrors = (error: z.ZodError): Record<string, string> => {
+  const fields: Record<string, string> = {};
+  for (const issue of error.issues) {
+    const key = issue.path.length > 0 ? issue.path.join(".") : "body";
+    fields[key] ??= issue.message;
+  }
+  return fields;
+};
+
+export const parseAnnouncementBody = <TSchema extends z.ZodType>({
+  body,
+  schema,
+}: {
+  body: unknown;
+  schema: TSchema;
+}): z.output<TSchema> => {
+  const parsed = schema.safeParse(body ?? {});
+  if (!parsed.success) {
+    throw new ValidationError({
+      code: "announcement-body-validation-failed",
+      detail: "The request body did not match the announcement schema",
+      fields: toFieldErrors(parsed.error),
+      title: "Validation failed",
+    });
+  }
+  return parsed.data;
+};