tabletcommand-backend-models 7.4.105 → 7.4.107

package/src/test/mock.ts

@@ -996,6 +996,34 @@ export default function mockModule(dependencies: { mongoose: Mongoose; }) {
       expireAt: new Date("2025-12-12T01:02:03.000Z"),
       referer: "tabletcommand.com",
     },
+    watchDutySync: {
+      lastModifiedAt: new Date("2025-11-11T04:05:06.000Z"),
+    },
+  };
+
+  const watchDutyEvent = {
+    watchDutyId: 123456,
+    name: "Line Fire",
+    description: "Vegetation fire off Highway 38",
+    geoEventType: "wildfire",
+    locationGeoJSON: {
+      type: "Point",
+      coordinates: [-117.1234, 34.1234],
+    },
+    address: "Highway 38, Angelus Oaks, CA",
+    isPrescribed: false,
+    areaSquareMeters: 5060594,
+    containment: 42,
+    evacuationOrders: "Zone A, Zone B",
+    evacuationWarnings: "Zone C",
+    evacuationAdvisories: "Zone D",
+    evacuationShelterInPlace: "Zone E",
+    regions: [
+      { name: "San Bernardino County", state: "CA" },
+    ],
+    active: true,
+    watchDutyCreatedAt: new Date("2025-08-01T10:00:00.000Z"),
+    watchDutyModifiedAt: new Date("2025-08-02T11:00:00.000Z"),
   };
 
   const audioStreamAuthentication = {
@@ -1682,5 +1710,6 @@ export default function mockModule(dependencies: { mongoose: Mongoose; }) {
     userDevice,
     userRegistration,
     validationReport,
+    watchDutyEvent,
   };
 }

package/src/test/tracker-responder.ts

@@ -0,0 +1,144 @@
+import { assert } from "chai";
+import { describe, it, beforeEach, afterEach } from "node:test";
+import * as m from "../index";
+import * as config from "./config";
+import mockModule from "./mock";
+
+describe("TrackerResponder", function() {
+  let models: m.BackendModels, mongoose: m.MongooseModule;
+  beforeEach(async function() {
+    const c = await m.connect(config.url);
+    models = c.models;
+    mongoose = c.mongoose;
+
+    const mock = mockModule({
+      mongoose
+    });
+    await mock.beforeEach();
+    await models.TrackerResponder.deleteMany({});
+  });
+  afterEach(async function() {
+    await mongoose.disconnect();
+  });
+
+  it("is saved with defaults", async function() {
+    const item = new models.TrackerResponder({
+      departmentId: "d1",
+      mac: "aa:bb:cc:dd:ee:01",
+    });
+    const sut = await item.save();
+
+    assert.isNotNull(sut._id);
+    assert.equal(sut.departmentId, "d1");
+    assert.equal(sut.mac, "AA:BB:CC:DD:EE:01");
+    assert.isTrue(sut.uuid !== "");
+    assert.equal(sut.trackerPersonnelId, "");
+    assert.equal(sut.personnelName, "");
+    assert.equal(sut.friendlyName, "");
+    assert.equal(sut.displayName, "");
+    assert.equal(sut.seatPosition, "");
+    assert.equal(sut.personnelUUID, "");
+    assert.equal(sut.assignedBy, "");
+    assert.isNull(sut.assignedAt);
+    assert.isTrue(sut.active);
+    assert.equal(sut.source, "");
+    assert.instanceOf(sut.createdAt, Date);
+    assert.instanceOf(sut.modified, Date);
+  });
+
+  it("persists vendor and user-owned fields", async function() {
+    const item = new models.TrackerResponder({
+      departmentId: "d1",
+      mac: "AA:BB:CC:DD:EE:02",
+      trackerPersonnelId: "12345",
+      personnelName: "Fire Hose 1",
+      friendlyName: "FH-1",
+      displayName: "Engine 1 Nozzle",
+      seatPosition: "Fire Hose 1",
+      personnelUUID: "pk-uuid-1",
+      assignedBy: "user-1",
+      assignedAt: new Date("2026-07-23T00:00:00.000Z"),
+      source: "TXRX",
+    });
+    const sut = await item.save();
+
+    assert.equal(sut.trackerPersonnelId, "12345");
+    assert.equal(sut.personnelName, "Fire Hose 1");
+    assert.equal(sut.friendlyName, "FH-1");
+    assert.equal(sut.displayName, "Engine 1 Nozzle");
+    assert.equal(sut.seatPosition, "Fire Hose 1");
+    assert.equal(sut.personnelUUID, "pk-uuid-1");
+    assert.equal(sut.assignedBy, "user-1");
+    assert.equal(sut.assignedAt?.toISOString(), "2026-07-23T00:00:00.000Z");
+    assert.equal(sut.source, "TXRX");
+  });
+
+  it("enforces unique (departmentId, mac)", async function() {
+    await models.TrackerResponder.createIndexes();
+
+    await new models.TrackerResponder({
+      departmentId: "d1",
+      mac: "AA:BB:CC:DD:EE:03",
+    }).save();
+
+    // Same MAC in another department is allowed
+    const other = await new models.TrackerResponder({
+      departmentId: "d2",
+      mac: "AA:BB:CC:DD:EE:03",
+    }).save();
+    assert.isNotNull(other._id);
+
+    try {
+      await new models.TrackerResponder({
+        departmentId: "d1",
+        mac: "aa:bb:cc:dd:ee:03",
+      }).save();
+      assert.isFalse(true, "Expecting duplicate (departmentId, mac) to fail.");
+    } catch (error) {
+      assert.match((error as Error).message, /E11000/);
+    }
+  });
+
+  it("enforces unique (departmentId, uuid)", async function() {
+    await models.TrackerResponder.createIndexes();
+
+    const first = await new models.TrackerResponder({
+      departmentId: "d1",
+      mac: "AA:BB:CC:DD:EE:04",
+    }).save();
+
+    // Same uuid in another department is allowed
+    const other = await new models.TrackerResponder({
+      departmentId: "d2",
+      mac: "AA:BB:CC:DD:EE:04",
+      uuid: first.uuid,
+    }).save();
+    assert.isNotNull(other._id);
+
+    try {
+      await new models.TrackerResponder({
+        departmentId: "d1",
+        mac: "AA:BB:CC:DD:EE:05",
+        uuid: first.uuid,
+      }).save();
+      assert.isFalse(true, "Expecting duplicate (departmentId, uuid) to fail.");
+    } catch (error) {
+      assert.match((error as Error).message, /E11000/);
+    }
+  });
+
+  it("rejects an empty or null uuid", async function() {
+    for (const uuid of ["", null]) {
+      try {
+        await new models.TrackerResponder({
+          departmentId: "d1",
+          mac: "AA:BB:CC:DD:EE:06",
+          uuid,
+        }).save();
+        assert.isFalse(true, `Expecting uuid ${JSON.stringify(uuid)} to fail validation.`);
+      } catch (error) {
+        assert.match((error as Error).message, /uuid.*required/i);
+      }
+    }
+  });
+});

package/src/test/watchduty-event.ts

@@ -0,0 +1,163 @@
+import { assert } from "chai";
+import { describe, it, beforeEach, afterEach } from "node:test";
+import * as m from "../index";
+import * as config from "./config";
+import mockModule from "./mock";
+
+describe("WatchDutyEvent", function() {
+  let models: m.BackendModels, mongoose: m.MongooseModule;
+  let testItem: ReturnType<typeof mockModule>["watchDutyEvent"];
+
+  beforeEach(async function() {
+    const c = await m.connect(config.url);
+    models = c.models;
+    mongoose = c.mongoose;
+    testItem = mockModule({ mongoose }).watchDutyEvent;
+    await models.WatchDutyEvent.syncIndexes();
+  });
+  afterEach(async function() {
+    await models.WatchDutyEvent.deleteMany({});
+    await mongoose.disconnect();
+  });
+
+  it("is saved and reads back every field", async function() {
+    const sut = await new models.WatchDutyEvent(testItem).save();
+
+    assert.isNotNull(sut._id);
+    assert.equal(sut.watchDutyId, testItem.watchDutyId);
+    assert.equal(sut.name, testItem.name);
+    assert.equal(sut.description, testItem.description);
+    assert.equal(sut.geoEventType, testItem.geoEventType);
+    assert.equal(sut.locationGeoJSON?.type, "Point");
+    assert.equal(sut.locationGeoJSON?.coordinates[0], testItem.locationGeoJSON.coordinates[0]);
+    assert.equal(sut.locationGeoJSON?.coordinates[1], testItem.locationGeoJSON.coordinates[1]);
+    assert.equal(sut.address, testItem.address);
+    assert.isFalse(sut.isPrescribed);
+    assert.equal(sut.areaSquareMeters, testItem.areaSquareMeters);
+    assert.equal(sut.containment, testItem.containment);
+    assert.equal(sut.evacuationOrders, testItem.evacuationOrders);
+    assert.equal(sut.evacuationWarnings, testItem.evacuationWarnings);
+    assert.equal(sut.evacuationAdvisories, testItem.evacuationAdvisories);
+    assert.equal(sut.evacuationShelterInPlace, testItem.evacuationShelterInPlace);
+    assert.equal(sut.regions.length, 1);
+    assert.equal(sut.regions[0]?.name, testItem.regions[0]?.name);
+    assert.equal(sut.regions[0]?.state, testItem.regions[0]?.state);
+    assert.isTrue(sut.active);
+    assert.equal(sut.watchDutyCreatedAt.toISOString(), testItem.watchDutyCreatedAt.toISOString());
+    assert.equal(sut.watchDutyModifiedAt.toISOString(), testItem.watchDutyModifiedAt.toISOString());
+    assert.instanceOf(sut.created, Date);
+    assert.instanceOf(sut.modified, Date);
+  });
+
+  it("defaults optional fields", async function() {
+    const sut = await new models.WatchDutyEvent({
+      watchDutyId: 654321,
+      watchDutyCreatedAt: new Date(),
+      watchDutyModifiedAt: new Date(),
+    }).save();
+
+    assert.equal(sut.name, "");
+    assert.equal(sut.description, "");
+    assert.equal(sut.geoEventType, "");
+    assert.isNull(sut.locationGeoJSON);
+    assert.equal(sut.address, "");
+    assert.isFalse(sut.isPrescribed);
+    assert.isNull(sut.areaSquareMeters);
+    assert.isNull(sut.containment);
+    assert.equal(sut.evacuationOrders, "");
+    assert.equal(sut.evacuationWarnings, "");
+    assert.equal(sut.evacuationAdvisories, "");
+    assert.equal(sut.evacuationShelterInPlace, "");
+    assert.deepEqual(sut.regions, []);
+    assert.isTrue(sut.active);
+    assert.instanceOf(sut.created, Date);
+    assert.instanceOf(sut.modified, Date);
+  });
+
+  // timestamps defaults createdAt to true, which would store an undeclared createdAt field.
+  it("stores no timestamp field outside the schema", async function() {
+    await new models.WatchDutyEvent({
+      watchDutyId: 333,
+      watchDutyCreatedAt: new Date(),
+      watchDutyModifiedAt: new Date(),
+    }).save();
+
+    const raw = await models.WatchDutyEvent.collection.findOne({ watchDutyId: 333 });
+    assert.isNotNull(raw);
+    assert.notProperty(raw, "createdAt");
+    assert.notProperty(raw, "updatedAt");
+    assert.property(raw, "created");
+    assert.property(raw, "modified");
+  });
+
+  // The retention sweep deletes inactive events by `modified`, and the cron upserts through
+  // findOneAndUpdate, which skips the schema default. Only the timestamps option keeps the
+  // field current.
+  it("advances modified on findOneAndUpdate", async function() {
+    const staleDate = new Date("2020-01-02T03:04:05.000Z");
+    await new models.WatchDutyEvent({
+      watchDutyId: 222,
+      watchDutyCreatedAt: new Date(),
+      watchDutyModifiedAt: new Date(),
+    }).save();
+    await models.WatchDutyEvent.collection.updateOne({
+      watchDutyId: 222,
+    }, {
+      $set: {
+        modified: staleDate,
+      },
+    });
+
+    const updated = await models.WatchDutyEvent.findOneAndUpdate({
+      watchDutyId: 222,
+    }, {
+      $set: {
+        active: false,
+      },
+    }, {
+      new: true,
+    });
+
+    assert.isNotNull(updated);
+    assert.isFalse(updated?.active);
+    assert.isAbove(Number(updated?.modified), Number(staleDate));
+  });
+
+  it("enforces a unique watchDutyId index", async function() {
+    await new models.WatchDutyEvent({
+      watchDutyId: 111,
+      watchDutyCreatedAt: new Date(),
+      watchDutyModifiedAt: new Date(),
+    }).save();
+
+    let thrownError: unknown = null;
+    try {
+      await new models.WatchDutyEvent({
+        watchDutyId: 111,
+        watchDutyCreatedAt: new Date(),
+        watchDutyModifiedAt: new Date(),
+      }).save();
+    } catch (e) {
+      thrownError = e;
+    }
+
+    assert.isNotNull(thrownError, "expected duplicate watchDutyId to be rejected");
+    assert.equal((thrownError as { code?: number }).code, 11000);
+    assert.include(String((thrownError as Error).message), "E11000");
+  });
+
+  it("requires watchDutyId", async function() {
+    let thrownError: unknown = null;
+    try {
+      await new models.WatchDutyEvent({
+        watchDutyCreatedAt: new Date(),
+        watchDutyModifiedAt: new Date(),
+      }).save();
+    } catch (e) {
+      thrownError = e;
+    }
+
+    assert.isNotNull(thrownError, "expected missing watchDutyId to be rejected");
+    assert.include(String((thrownError as Error).message), "watchDutyId");
+  });
+});

package/src/types/department.ts

@@ -205,6 +205,10 @@ export interface SomewearType {
   enabled: boolean
 }
 
+export interface PersonnelWebhookType {
+  enabled: boolean
+}
+
 export interface SkytracConfigType {
   enabled: boolean
   licenseKey: string,
@@ -546,6 +550,11 @@ export type AccountConfigurationZonehaven = {
   fadeZoomLevel: number,
 };
 
+export type AccountConfigurationWatchDuty = {
+  enabled: boolean,
+  visible: boolean,
+};
+
 export type ManagedIncidentPriorityItem = {
   title: string,
   color: ColorSchemaType,
@@ -667,6 +676,7 @@ export interface DepartmentType {
   orientationMarkerColor: ColorSchemaType,
   partialApiKey: string,
   personnelStaffingEnabled: boolean,
+  personnelWebhook: PersonnelWebhookType,
   pubNubV3: PubNubTokenSchemaType,
   remoteLoggingEnabled: boolean,
   reportNumberEnabled: boolean,
@@ -705,4 +715,5 @@ export interface DepartmentType {
   webhook: WebhookConfigType,
   wsFeed: WSFeedConfigType,
   zonehaven: AccountConfigurationZonehaven,
+  watchDuty: AccountConfigurationWatchDuty,
 }

package/src/types/global-settings.ts

@@ -12,10 +12,18 @@ export type ZonehavenTokenType = {
   referer: string | null,
 };
 
+// Incremental pull cursor for the Watch Duty events cron. One Watch Duty account feeds every
+// department, so the cursor is global. The cron holds it back when a fetch is incomplete, which
+// is why it is stored and not derived from the events themselves.
+export type WatchDutySyncType = {
+  lastModifiedAt: Date | null,
+};
+
 export interface GlobalSettingsType {
   _id: Types.ObjectId,
   name: "global",
   arcgisApiKey: ArcGISKeyType,
   zonehavenToken: ZonehavenTokenType,
+  watchDutySync: WatchDutySyncType,
   updatedAt: Date,
 }

package/src/types/location.ts

@@ -40,6 +40,7 @@ export interface LocationType {
   username: string,
   uuid: string,
   personnelUUID: string,
+  transponderUUID: string,
   version: number,
   visibility: string[],
 }

package/src/types/tracker-responder.ts

@@ -0,0 +1,28 @@
+import { Types } from "mongoose";
+
+export interface TrackerResponderType {
+  _id: Types.ObjectId,
+  departmentId: string,
+  // Transponder MAC address, normalized uppercase. Unique per department.
+  mac: string,
+  // Stable identity carried by Location.transponderUUID.
+  uuid: string,
+  // Vendor personnelId verbatim (not a PersonnelKnown reference).
+  trackerPersonnelId: string,
+  // Vendor-owned names, taken verbatim from the TXRX webhook body.
+  personnelName: string,
+  friendlyName: string,
+  // User-owned display name, editable on our end (eventually via iOS);
+  // the webhook never touches this.
+  displayName: string,
+  seatPosition: string,
+  // "" = unassigned, otherwise PersonnelKnown.uuid.
+  personnelUUID: string,
+  assignedBy: string,
+  // null while unassigned
+  assignedAt: Date | null,
+  active: boolean,
+  source: string,
+  createdAt: Date,
+  modified: Date,
+}

package/src/types/watchduty-event.ts

@@ -0,0 +1,36 @@
+import { Types } from "mongoose";
+import { GeoPoint } from "./geojson";
+
+export interface WatchDutyRegionType {
+  name: string,
+  state: string,
+}
+
+export interface WatchDutyEventType {
+  _id: Types.ObjectId,
+  watchDutyId: number,
+  name: string,
+  description: string,
+  geoEventType: string,
+  // Null when Watch Duty reports no usable lat/lng. The event is still stored, it just cannot
+  // be drawn.
+  locationGeoJSON: GeoPoint | null,
+  address: string,
+  isPrescribed: boolean,
+  // Watch Duty reports the burned area in acres. It is converted on the way in.
+  areaSquareMeters: number | null,
+  // Percent of the fire perimeter contained, 0 to 100.
+  containment: number | null,
+  evacuationOrders: string,
+  evacuationWarnings: string,
+  evacuationAdvisories: string,
+  evacuationShelterInPlace: string,
+  regions: WatchDutyRegionType[],
+  active: boolean,
+  // Watch Duty's own timestamps. `created` and `modified` are ours, and mean the first and the
+  // last time we wrote the record.
+  watchDutyCreatedAt: Date,
+  watchDutyModifiedAt: Date,
+  created: Date,
+  modified: Date,
+}