@terreno/announcements 57.4.0

package/dist/pending.js

@@ -0,0 +1,242 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAnnouncementVisibleToUser = exports.selectPendingAnnouncements = exports.sortAnnouncementsForQueue = exports.isAnnouncementPendingForUser = exports.matchesPlatform = exports.isAnnouncementVisibleNow = exports.isInterruptDisplayMode = exports.passesMinBuildNumber = exports.parseQueryVersion = exports.matchAudienceByType = exports.resolveAudienceType = exports.resolveDisplayMode = exports.requiresAcknowledgementForAnnouncement = exports.resolveAcknowledgementPolicy = void 0;
+var luxon_1 = require("luxon");
+var resolveAcknowledgementPolicy = function (_a) {
+    var announcement = _a.announcement, _b = _a.defaultAcknowledgementPolicy, defaultAcknowledgementPolicy = _b === void 0 ? "dismiss-only" : _b;
+    if (announcement.acknowledgementPolicy) {
+        return announcement.acknowledgementPolicy;
+    }
+    var legacyRequiresAck = announcement.requiresAcknowledgement;
+    if (legacyRequiresAck === true) {
+        return "required";
+    }
+    return defaultAcknowledgementPolicy;
+};
+exports.resolveAcknowledgementPolicy = resolveAcknowledgementPolicy;
+var requiresAcknowledgementForAnnouncement = function (_a) {
+    var announcement = _a.announcement, _b = _a.defaultAcknowledgementPolicy, defaultAcknowledgementPolicy = _b === void 0 ? "dismiss-only" : _b;
+    var policy = (0, exports.resolveAcknowledgementPolicy)({ announcement: announcement, defaultAcknowledgementPolicy: defaultAcknowledgementPolicy });
+    return policy === "required";
+};
+exports.requiresAcknowledgementForAnnouncement = requiresAcknowledgementForAnnouncement;
+var resolveDisplayMode = function (announcement) {
+    var mode = announcement.displayMode;
+    if (mode === "modal" || mode === "banner" || mode === "feed") {
+        return mode;
+    }
+    return "modal";
+};
+exports.resolveDisplayMode = resolveDisplayMode;
+var resolveAudienceType = function (announcement) {
+    var audienceType = announcement.audienceType;
+    if (audienceType === "staff" || audienceType === "patient" || audienceType === "all") {
+        return audienceType;
+    }
+    return "all";
+};
+exports.resolveAudienceType = resolveAudienceType;
+var matchAudienceByType = function (_a) {
+    var announcement = _a.announcement, isStaff = _a.isStaff, user = _a.user;
+    var audienceType = (0, exports.resolveAudienceType)(announcement);
+    if (audienceType === "all") {
+        return true;
+    }
+    var staff = isStaff(user);
+    if (audienceType === "staff") {
+        return staff;
+    }
+    return !staff;
+};
+exports.matchAudienceByType = matchAudienceByType;
+var parseQueryVersion = function (raw) {
+    if (raw === undefined || raw === null || raw === "") {
+        return undefined;
+    }
+    var parsed = Number(raw);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
+        return undefined;
+    }
+    return parsed;
+};
+exports.parseQueryVersion = parseQueryVersion;
+var passesMinBuildNumber = function (_a) {
+    var announcement = _a.announcement, queryVersion = _a.queryVersion;
+    var minBuildNumber = announcement.minBuildNumber;
+    if (minBuildNumber === undefined || minBuildNumber === null || minBuildNumber === 0) {
+        return true;
+    }
+    if (queryVersion === undefined) {
+        return true;
+    }
+    return queryVersion >= minBuildNumber;
+};
+exports.passesMinBuildNumber = passesMinBuildNumber;
+var isInterruptDisplayMode = function (announcement) {
+    var displayMode = (0, exports.resolveDisplayMode)(announcement);
+    return displayMode === "modal" || displayMode === "banner";
+};
+exports.isInterruptDisplayMode = isInterruptDisplayMode;
+var isAnnouncementVisibleNow = function (_a) {
+    var announcement = _a.announcement, _b = _a.now, now = _b === void 0 ? luxon_1.DateTime.utc() : _b;
+    if (announcement.status !== "published") {
+        return false;
+    }
+    if (announcement.publishAt) {
+        var publishAt = luxon_1.DateTime.fromJSDate(announcement.publishAt);
+        if (publishAt > now) {
+            return false;
+        }
+    }
+    if (announcement.expiresAt) {
+        var expiresAt = luxon_1.DateTime.fromJSDate(announcement.expiresAt);
+        if (expiresAt <= now) {
+            return false;
+        }
+    }
+    return true;
+};
+exports.isAnnouncementVisibleNow = isAnnouncementVisibleNow;
+var matchesPlatform = function (_a) {
+    var _b;
+    var announcement = _a.announcement, platform = _a.platform;
+    var platforms = ((_b = announcement.platforms) === null || _b === void 0 ? void 0 : _b.length)
+        ? announcement.platforms
+        : ["ios", "android", "web"];
+    return platforms.includes(platform);
+};
+exports.matchesPlatform = matchesPlatform;
+var isAnnouncementPendingForUser = function (_a) {
+    var acknowledgements = _a.acknowledgements, announcement = _a.announcement, _b = _a.defaultAcknowledgementPolicy, defaultAcknowledgementPolicy = _b === void 0 ? "dismiss-only" : _b, impressions = _a.impressions;
+    var announcementId = announcement._id.toString();
+    var needsAck = (0, exports.requiresAcknowledgementForAnnouncement)({
+        announcement: announcement,
+        defaultAcknowledgementPolicy: defaultAcknowledgementPolicy,
+    });
+    if (needsAck) {
+        var hasAck = acknowledgements.some(function (ack) { return ack.announcementId === announcementId && ack.version === announcement.version; });
+        return !hasAck;
+    }
+    var hasImpression = impressions.some(function (impression) {
+        return impression.announcementId === announcementId && impression.version === announcement.version;
+    });
+    return !hasImpression;
+};
+exports.isAnnouncementPendingForUser = isAnnouncementPendingForUser;
+var sortAnnouncementsForQueue = function (announcements) {
+    return __spreadArray([], __read(announcements), false).sort(function (left, right) {
+        var _a, _b, _c, _d;
+        if (right.priority !== left.priority) {
+            return right.priority - left.priority;
+        }
+        var rightPublished = (_b = (_a = right.publishedAt) === null || _a === void 0 ? void 0 : _a.getTime()) !== null && _b !== void 0 ? _b : 0;
+        var leftPublished = (_d = (_c = left.publishedAt) === null || _c === void 0 ? void 0 : _c.getTime()) !== null && _d !== void 0 ? _d : 0;
+        return rightPublished - leftPublished;
+    });
+};
+exports.sortAnnouncementsForQueue = sortAnnouncementsForQueue;
+var selectPendingAnnouncements = function (_a) {
+    var acknowledgements = _a.acknowledgements, announcements = _a.announcements, _b = _a.defaultAcknowledgementPolicy, defaultAcknowledgementPolicy = _b === void 0 ? "dismiss-only" : _b, impressions = _a.impressions, now = _a.now, platform = _a.platform, queryVersion = _a.queryVersion;
+    var visible = announcements.filter(function (announcement) {
+        if (!(0, exports.isAnnouncementVisibleNow)({ announcement: announcement, now: now })) {
+            return false;
+        }
+        if (!(0, exports.matchesPlatform)({ announcement: announcement, platform: platform })) {
+            return false;
+        }
+        if (!(0, exports.isInterruptDisplayMode)(announcement)) {
+            return false;
+        }
+        if (!(0, exports.passesMinBuildNumber)({ announcement: announcement, queryVersion: queryVersion })) {
+            return false;
+        }
+        return (0, exports.isAnnouncementPendingForUser)({
+            acknowledgements: acknowledgements,
+            announcement: announcement,
+            defaultAcknowledgementPolicy: defaultAcknowledgementPolicy,
+            impressions: impressions,
+        });
+    });
+    return (0, exports.sortAnnouncementsForQueue)(visible);
+};
+exports.selectPendingAnnouncements = selectPendingAnnouncements;
+var isAnnouncementVisibleToUser = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
+    var announcement = _b.announcement, isStaff = _b.isStaff, matchAudience = _b.matchAudience, now = _b.now, platform = _b.platform, queryVersion = _b.queryVersion, user = _b.user;
+    return __generator(this, function (_c) {
+        if (!(0, exports.isAnnouncementVisibleNow)({ announcement: announcement, now: now })) {
+            return [2 /*return*/, false];
+        }
+        if (!(0, exports.matchesPlatform)({ announcement: announcement, platform: platform })) {
+            return [2 /*return*/, false];
+        }
+        if (!(0, exports.passesMinBuildNumber)({ announcement: announcement, queryVersion: queryVersion })) {
+            return [2 /*return*/, false];
+        }
+        if (!(0, exports.matchAudienceByType)({ announcement: announcement, isStaff: isStaff, user: user })) {
+            return [2 /*return*/, false];
+        }
+        return [2 /*return*/, matchAudience(user, announcement)];
+    });
+}); };
+exports.isAnnouncementVisibleToUser = isAnnouncementVisibleToUser;

package/dist/types.d.ts

@@ -0,0 +1,135 @@
+import type { PermissionMethod } from "@terreno/api";
+import type { Model, Types } from "mongoose";
+export type AnnouncementStatus = "draft" | "published" | "archived";
+export type AnnouncementPlatform = "ios" | "android" | "web";
+export type AnnouncementDisplayMode = "modal" | "banner" | "feed";
+export type AnnouncementAudienceType = "staff" | "patient" | "all";
+export type AcknowledgementPolicy = "required" | "dismiss-only";
+export interface AnnouncementPrimaryAction {
+    label: string;
+    url: string;
+}
+export interface AnnouncementDocument {
+    _id: Types.ObjectId;
+    title: string;
+    body: string;
+    status: AnnouncementStatus;
+    version: number;
+    priority: number;
+    acknowledgementPolicy?: AcknowledgementPolicy;
+    audience: unknown;
+    audienceType?: AnnouncementAudienceType;
+    displayMode?: AnnouncementDisplayMode;
+    minBuildNumber?: number;
+    publishAt?: Date;
+    expiresAt?: Date;
+    platforms: AnnouncementPlatform[];
+    primaryAction?: AnnouncementPrimaryAction;
+    publishedAt?: Date;
+    archivedAt?: Date;
+    created: Date;
+    updated: Date;
+}
+export type AnnouncementModel = Model<AnnouncementDocument>;
+export interface AnnouncementAcknowledgementDocument {
+    _id: Types.ObjectId;
+    userId: Types.ObjectId;
+    announcementId: Types.ObjectId;
+    version: number;
+    acknowledgedAt: Date;
+    created: Date;
+    updated: Date;
+}
+export type AnnouncementAcknowledgementModel = Model<AnnouncementAcknowledgementDocument>;
+export interface AnnouncementImpressionDocument {
+    _id: Types.ObjectId;
+    userId: Types.ObjectId;
+    announcementId: Types.ObjectId;
+    version: number;
+    viewedAt: Date;
+    platform?: AnnouncementPlatform;
+    created: Date;
+    updated: Date;
+}
+export type AnnouncementImpressionModel = Model<AnnouncementImpressionDocument>;
+export type AnnouncementClickAction = "primaryAction";
+export interface AnnouncementClickEventDocument {
+    _id: Types.ObjectId;
+    userId: Types.ObjectId;
+    announcementId: Types.ObjectId;
+    version: number;
+    action: AnnouncementClickAction;
+    clickedAt: Date;
+    platform?: AnnouncementPlatform;
+    created: Date;
+    updated: Date;
+}
+export type AnnouncementClickEventModel = Model<AnnouncementClickEventDocument>;
+export interface AnnouncementPublic {
+    id: string;
+    title: string;
+    body: string;
+    version: number;
+    priority: number;
+    displayMode: AnnouncementDisplayMode;
+    requiresAcknowledgement: boolean;
+    primaryAction?: AnnouncementPrimaryAction;
+    publishedAt?: string;
+}
+export type MatchAudienceFunction = (user: unknown, announcement: AnnouncementDocument) => boolean | Promise<boolean>;
+export interface AnnouncementsHelpOptions {
+    /** When true, registers GET /announcements/help/search and GET /announcements/help/:id for MCP and in-app help. */
+    enabled?: boolean;
+}
+export interface AnnouncementsOptions {
+    /** Permission methods for the aggregate admin overview. Defaults to IsAdmin. */
+    adminOverviewPermissions?: PermissionMethod<AnnouncementDocument>[];
+    basePath?: string;
+    defaultAcknowledgementPolicy?: AcknowledgementPolicy;
+    help?: AnnouncementsHelpOptions;
+    /** When omitted, staff targeting uses `user.admin === true`. */
+    isStaff?: (user: unknown) => boolean;
+    matchAudience?: MatchAudienceFunction;
+    permissions?: Partial<{
+        create: PermissionMethod<AnnouncementDocument>[];
+        delete: PermissionMethod<AnnouncementDocument>[];
+        list: PermissionMethod<AnnouncementDocument>[];
+        read: PermissionMethod<AnnouncementDocument>[];
+        update: PermissionMethod<AnnouncementDocument>[];
+    }>;
+}
+export interface AnnouncementOverviewMetrics {
+    impressions: number;
+    acknowledgements: number;
+    clicks: number;
+}
+export interface AnnouncementOverviewRow {
+    _id: string;
+    title: string;
+    status: AnnouncementStatus;
+    displayMode: AnnouncementDisplayMode;
+    audienceType: AnnouncementAudienceType;
+    acknowledgementPolicy: AcknowledgementPolicy;
+    priority: number;
+    version: number;
+    publishedAt?: string;
+    expiresAt?: string;
+    metrics: AnnouncementOverviewMetrics;
+}
+export interface AnnouncementOverviewTotals {
+    announcements: number;
+    published: number;
+    draft: number;
+    archived: number;
+    impressions: number;
+    acknowledgements: number;
+    clicks: number;
+}
+export interface AnnouncementOverviewResponse {
+    data: AnnouncementOverviewRow[];
+    totals: AnnouncementOverviewTotals;
+    page: number;
+    limit: number;
+    total: number;
+    more: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,57 @@
+{
+  "author": "Josh Gachnang",
+  "bugs": {
+    "url": "https://github.com/FlourishHealth/terreno/issues"
+  },
+  "dependencies": {
+    "@terreno/api": "57.4.0",
+    "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.4.0",
+    "@types/bun": "^1.4.0",
+    "@types/express": "^5.0.6",
+    "@types/supertest": "^7.2.0",
+    "chai": "^6.2.2",
+    "passport-local-mongoose": "^9.0.1",
+    "supertest": "^7.2.2",
+    "typescript": "~6.0.3"
+  },
+  "homepage": "https://github.com/FlourishHealth/terreno#readme",
+  "keywords": [
+    "announcements",
+    "api",
+    "changelog",
+    "express",
+    "terreno"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "name": "@terreno/announcements",
+  "peerDependencies": {
+    "mongoose": "^8.0.0 || ^9.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/FlourishHealth/terreno.git"
+  },
+  "scripts": {
+    "compile": "bun tsc",
+    "compile:watch": "bun tsc -w",
+    "dev": "bun tsc -w",
+    "lint": "biome check ./src",
+    "lint:fix": "biome check --write ./src",
+    "test": "bun test",
+    "test:agent": "AGENT=1 bun test --only-failures",
+    "test:ci": "bun test",
+    "test:coverage": "bun run ../scripts/check-coverage.ts"
+  },
+  "types": "dist/index.d.ts",
+  "version": "57.4.0"
+}