tabletcommand-location 2.4.1 → 2.4.3

package/.claude/worktrees/sc-36275/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "tabletcommand-location",
+  "version": "2.4.3",
+  "description": "Tablet Command Location",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "gulp build",
+    "lint": "eslint src",
+    "test": "type-coverage && tsx --test --test-concurrency=1 --test-reporter=spec src/test/*.ts"
+  },
+  "author": "Joe Goeman <joe@tabletcommand.com>",
+  "license": "UNLICENSED",
+  "types": "definitions/index.d.ts",
+  "dependencies": {
+    "debug": "^4.4.3",
+    "lodash": "~4.18.1",
+    "tabletcommand-backend-models": "~7.4.112"
+  },
+  "peerDependencies": {
+    "mongoose": "^8.24.1"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.6",
+    "@eslint/js": "^9.39.5",
+    "@types/chai": "^5.2.3",
+    "@types/debug": "^4.1.13",
+    "@types/express": "^4.17.25",
+    "@types/lodash": "^4.17.25",
+    "@types/node": "^24.13.3",
+    "@typescript-eslint/eslint-plugin": "^8.69.0",
+    "@typescript-eslint/parser": "^8.69.0",
+    "chai": "^6.2.2",
+    "cspell": "^10.2.0",
+    "del": "^8.0.1",
+    "eslint": "^9.39.5",
+    "eslint-plugin-promise": "^7.3.0",
+    "eslint-plugin-security": "^4.0.1",
+    "globals": "^17.11.0",
+    "gulp": "^5.0.1",
+    "gulp-execa": "^8.0.1",
+    "mongoose": "^8.24.4",
+    "neostandard": "^0.13.0",
+    "tsx": "^4.23.13",
+    "type-coverage": "^2.30.1",
+    "typescript": "~5.9.3"
+  },
+  "typeCoverage": {
+    "atLeast": 99.3,
+    "ignoreCatch": true,
+    "ignoreFiles": [
+      "src/test/**/*.ts"
+    ]
+  }
+}

package/.claude/worktrees/sc-36275/src/audience.ts

@@ -0,0 +1,54 @@
+import {
+  AccountIndustry,
+} from "tabletcommand-backend-models";
+
+export type AvlAudienceKind = "always" | "near" | "geo";
+
+export interface AvlNearArea {
+  /** Radius around an anchor incident. Per-pair — deliberately not a shared constant. */
+  radiusMeters: number;
+}
+
+export type AvlAudienceEntry =
+  | { kind: "always" }
+  | { kind: "near"; area: AvlNearArea }   // area required exactly when near
+  | { kind: "geo" };                      // geometry comes from the OWNER's shareAVL.area
+
+/** owner industry -> reader industry -> entry, or null for denied. Every pair present. */
+export type AvlAudienceMatrix = Record<AccountIndustry, Record<AccountIndustry, AvlAudienceEntry | null>>;
+
+const ALWAYS: AvlAudienceEntry = { kind: "always" };
+// eslint-ignore-next-line
+// const GEO: AvlAudienceEntry = { kind: "geo" };
+const DENY = null;
+const NEAR: AvlAudienceEntry = { kind: "near", area: { radiusMeters: 5000 } }; // 5km ~ 3.1mi
+
+export const AVL_AUDIENCE_MATRIX: AvlAudienceMatrix = {
+  //  owner => reader
+  [AccountIndustry.Fire]: {
+    [AccountIndustry.Fire]: ALWAYS,
+    [AccountIndustry.Law]: ALWAYS,
+    [AccountIndustry.Campus]: DENY,
+    [AccountIndustry.Utility]: NEAR,
+  },
+  [AccountIndustry.Law]: {
+    [AccountIndustry.Fire]: NEAR,
+    [AccountIndustry.Law]: ALWAYS,
+    [AccountIndustry.Campus]: DENY,
+    [AccountIndustry.Utility]: DENY,
+  },
+  [AccountIndustry.Campus]: {
+    [AccountIndustry.Fire]: ALWAYS,
+    [AccountIndustry.Law]: ALWAYS,
+    [AccountIndustry.Campus]: DENY,   // deliberate — see above
+    [AccountIndustry.Utility]: DENY,
+  },
+  [AccountIndustry.Utility]: {
+    [AccountIndustry.Fire]: NEAR,
+    [AccountIndustry.Law]: DENY,
+    [AccountIndustry.Campus]: DENY,
+    [AccountIndustry.Utility]: ALWAYS,
+  },
+};
+
+// Unused/Incomplete

package/.claude/worktrees/sc-36275/src/index.ts

@@ -0,0 +1,81 @@
+import locationModule from "./location";
+import storeModule from "./store";
+import {
+  DepartmentModel,
+  LocationModel,
+  CADVehicleModel,
+  DeviceMappingModel,
+  Department,
+} from "tabletcommand-backend-models";
+import _ from "lodash";
+import {
+  LocationKindType,
+  LocationPayload,
+  LocationSource,
+  LocationVisibility,
+} from "./types";
+
+// Export types to external projects
+export {
+  LocationKindType,
+  LocationPayload,
+  LocationSource,
+  LocationVisibility,
+};
+
+// When used externally
+// import { query } from "tabletcommand-location";
+// query.adminListLocations({ departmentId, movedAt });
+export * as query from "./query";
+
+export function lib(
+  departmentModel: DepartmentModel,
+  locationModel: LocationModel,
+  cadVehicleModel: CADVehicleModel,
+  deviceMappingModel: DeviceMappingModel
+) {
+  const store = storeModule(departmentModel, locationModel, cadVehicleModel, deviceMappingModel);
+  const location = locationModule(store);
+
+  async function processLocations(department: Partial<Department>, items: LocationPayload[] | null | undefined) {
+    const atDate = new Date();
+    try {
+      if (_.isUndefined(items) || _.isNull(items)) {
+        return [];
+      }
+      if (_.isObject(items) && !_.isArray(items)) {
+        items = [items];
+      }
+      const result = await location.processItems(department, items, atDate);
+      return result;
+    } catch (err) {
+      console.log("err processLocations: ", err);
+      throw err;
+    }
+  }
+
+  async function processLocationsDeviceMapping(department: Partial<Department>, items: LocationPayload[] | null | undefined) {
+    const atDate = new Date();
+    try {
+      if (_.isUndefined(items) || _.isNull(items)) {
+        return [];
+      }
+      if (_.isObject(items) && !_.isArray(items)) {
+        items = [items];
+      }
+      const result = await location.processItemsDeviceMappingGeotab(department, items, atDate);
+      return result;
+    } catch (err) {
+      console.log("err processLocations: ", err);
+      throw err;
+    }
+  }
+
+  return {
+    processLocations,
+    processLocationsDeviceMapping,
+  };
+}
+
+export default lib;
+export type LibModule = ReturnType<typeof lib>;

package/.claude/worktrees/sc-36275/src/location.ts

@@ -0,0 +1,315 @@
+import _ from "lodash";
+import {
+  AccountIndustry,
+  Department,
+  Location,
+  CADVehicle,
+  LocationKindType,
+  LocationVisibility,
+} from "tabletcommand-backend-models";
+import {
+  LocationPayload,
+  DecodedLocation,
+} from "./types";
+import debugModule from "debug";
+import { StoreModule } from "./store";
+
+export function location(store: StoreModule) {
+  const debug = debugModule("tabletcommand-location:location");
+
+  function decodeLocation(item: LocationPayload, department: Partial<Department>, atDate: Date, deviceType: string): DecodedLocation {
+    let latitude = 0;
+    let longitude = 0;
+
+    if (_.isFinite(parseFloat(item.latitude.toString()))) {
+      latitude = parseFloat(item.latitude.toString());
+    }
+
+    if (_.isFinite(parseFloat(item.longitude.toString()))) {
+      longitude = parseFloat(item.longitude.toString());
+    }
+
+    if (!_.isString(item.radioName)) {
+      item.radioName = "";
+    }
+
+    if (!_.isString(item.vehicleId)) {
+      item.vehicleId = "";
+    }
+
+    const now = atDate.valueOf() / 1000.0;
+    // Don't save provided AVL time if it's more than 30s in the future
+    const futureTimeLimit = now + 30;
+    // If present, replace the modified unix date with the one provided by the CAD
+    let movedAtUnix = now;
+    if (_.isString(item.avlTime) && _.trim(item.avlTime) !== "") {
+      const checkISODate = (new Date(item.avlTime).valueOf()) / 1000.0;
+      const cadUnixTime = _.isNaN(checkISODate) && _.isString(item.avlTime) ? parseFloat(item.avlTime) : checkISODate;
+
+      if (_.isFinite(cadUnixTime) && cadUnixTime <= futureTimeLimit) {
+        movedAtUnix = cadUnixTime;
+      }
+    }
+
+    // Originally always was this fake id, but now can override these values
+    // If overridden then we use the values on the record instead of the fake userId
+    let userId = `${item.radioName}-${item.vehicleId}`; // Fake user id radioName - vehicleId
+    if (_.isString(item.userId) && _.trim(item.userId) !== "") {
+      userId = item.userId;
+    }
+    let session = userId;
+    if (_.isString(item.session) && _.trim(item.session) !== "") {
+      session = item.session;
+    }
+    let username = item.radioName;
+    if (_.isString(item.username) && _.trim(item.username) !== "") {
+      username = item.username;
+    }
+
+    let sharingEnabled = false;
+    let opAreaName = "";
+    let opAreaCode = "";
+    let deptState = "";
+    let locationStaleMinutes = 31 * 24 * 60; // 31d
+
+    if (_.isObject(department) && _.isObject(department.shareAVL)) {
+      sharingEnabled = department.shareAVL.enabled && department.accountType === "production";
+      opAreaName = department.shareAVL.opAreaName || "";
+      opAreaCode = department.shareAVL.opAreaCode || "";
+    }
+
+    if (_.isObject(department)) {
+      if (_.isObject(department.addressDetails) && _.isString(department.addressDetails.state)) {
+        deptState = department.addressDetails.state || "";
+      }
+      if (_.isNumber(department.locationStaleMinutes) && _.isFinite(department.locationStaleMinutes) && department.locationStaleMinutes > 0) {
+        locationStaleMinutes = department.locationStaleMinutes;
+      }
+    }
+    const deleteAfterDate = new Date(atDate.valueOf() + 1000 * 60 * locationStaleMinutes);
+    const personnelUUID = _.isString(item.personnelUUID) ? item.personnelUUID : "";
+    const transponderUUID = _.isString(item.transponderUUID) ? item.transponderUUID : "";
+    const industry: AccountIndustry = department?.industry ?? AccountIndustry.Fire; // If not set, fallback to fire
+
+    const cadAVL: Partial<Location> = {
+      device_type: deviceType,
+      source: item.source,
+      kindType: item.kindType,
+      locationGeoJSON: {
+        type: "Point",
+        coordinates: [longitude, latitude]
+      },
+      deleteAfterDate,
+      modified: atDate,
+      movedAt: new Date(movedAtUnix * 1000),
+      active: true,
+      username,
+      userId,
+      departmentId: String(department._id),
+      session,
+      version: 2,
+      shared: sharingEnabled,
+      sendToCAD: false,
+      opAreaName,
+      opAreaCode,
+      state: deptState,
+      visibility: [], // will be updated after .active is set
+      personnelUUID,
+      transponderUUID,
+      industry,
+    };
+
+    if (_.isNumber(item.speed)) {
+      const speed = item.speed;
+      cadAVL.speed = speed;
+    }
+
+    if (_.isNumber(item.heading) && item.heading >= 0 && item.heading <= 360) {
+      const heading = item.heading;
+      cadAVL.heading = heading;
+    }
+
+    if (_.isNumber(item.altitude)) {
+      const altitude = item.altitude;
+      cadAVL.altitude = altitude;
+    }
+
+    if (_.isString(item.kind)) {
+      cadAVL.kind = item.kind;
+    }
+    if (_.isString(item.type)) {
+      cadAVL.type = item.type;
+    }
+    if (_.isString(item.locationType)) {
+      cadAVL.locationType = item.locationType;
+    }
+    if (_.isObject(item.kindColor) &&
+      _.isString(item.kindColor.background) && item.kindColor.background !== "" &&
+      _.isString(item.kindColor.text) && item.kindColor.text !== "") {
+      cadAVL.kindColor = item.kindColor;
+      cadAVL.kindColorChangedAt = atDate;
+    }
+
+    const hasCoordinate = Math.abs(latitude) > 0.01 || Math.abs(longitude) > 0.01;
+    const validCoordinate = Math.abs(latitude) < 90 && Math.abs(longitude) < 180;
+    const hasVehicle = _.isString(item.vehicleId) && _.trim(item.vehicleId).length > 0;
+    const hasRadioName = _.isString(item.radioName) && _.trim(item.radioName).length > 0;
+    const isValid = hasCoordinate && validCoordinate && (hasVehicle || hasRadioName);
+
+    return {
+      cadAVL,
+      isValid,
+    };
+  }
+
+  async function processVehicle(item: LocationPayload, department: Partial<Department>, atDate: Date) {
+    const departmentId = String(department._id);
+    // need function to validate the item (As concerns vehicleId and radioName)
+    const isBidirectionalException = department.cadBidirectionalException || false;
+    // Determine if vehicle is active or not
+    const cadItem = await store.getVehicle(item, departmentId);
+    if (!_.isObject(cadItem) &&
+      department.cadOneWayVehiclesEnabled &&
+      (department.cadBidirectionalEnabled !== true || isBidirectionalException)) {
+      const vehicleItem: Partial<CADVehicle> = {
+        departmentId,
+        modifiedDate: atDate.valueOf() / 1000.0,
+        modified: atDate,
+        radioName: item.radioName,
+        vehicleId: item.vehicleId,
+        source: item.source,
+      };
+      await store.updateVehicle(vehicleItem, departmentId);
+    }
+    return cadItem;
+  }
+
+  // Returns true when the item is a person location and was fully handled here
+  // Returns false if trying to handle vehicle item
+  async function processPersonItem(decoded: DecodedLocation, item: LocationPayload, atDate: Date): Promise<boolean> {
+    const isPerson = decoded.cadAVL.kindType === LocationKindType.Person ||
+      decoded.cadAVL.locationType === LocationKindType.Person;
+    if (!isPerson) {
+      return false;
+    }
+    const hasPersonnelUUID = _.isString(decoded.cadAVL.personnelUUID) && decoded.cadAVL.personnelUUID !== "";
+    const hasTransponderUUID = _.isString(decoded.cadAVL.transponderUUID) && decoded.cadAVL.transponderUUID !== "";
+    if (!hasPersonnelUUID && !hasTransponderUUID) {
+      // A person Location with neither personnelUUID nor transponderUUID
+      // would leak into the vehicle sync endpoints (they filter on
+      // personnelUUID: "") so to process person must have one or other
+      debug(`skipping person location without personnelUUID/transponderUUID: ${JSON.stringify(item)}`);
+      return true;
+    }
+    // Person records: no CAD vehicle, always active/visible, never shared or CAD.
+    // Stamp kindType so records classified by locationType alone still match
+    // the person feed query (kindType: "person")
+    decoded.cadAVL.kindType = LocationKindType.Person;
+    decoded.cadAVL.active = true;
+    decoded.cadAVL.shared = false;
+    decoded.cadAVL.sendToCAD = false;
+    decoded.cadAVL.visibility = [LocationVisibility.Visible];
+    await store.updateLocation(decoded.cadAVL, atDate);
+    return true;
+  }
+
+  async function processItems(department: Partial<Department>, items: LocationPayload[], atDate: Date) {
+    for (const item of items) {
+      const decoded = decodeLocation(item, department, atDate, "cad");
+      debug(`processCADVehicleLocation item: ${JSON.stringify(item)} d:${JSON.stringify(department)} at: ${atDate.toISOString()}.`);
+      if (!decoded.isValid) {
+        // Skip only the invalid item, not the rest of the batch
+        continue;
+      }
+
+      if (await processPersonItem(decoded, item, atDate)) {
+        continue;
+      }
+
+      let active = true;
+      const cadItem = await processVehicle(item, department, atDate);
+
+      if (_.isObject(cadItem)) {
+        if (_.isBoolean(cadItem.mapHidden)) {
+          active = !cadItem.mapHidden;
+        }
+      }
+      // TODO: add support for location .kindType
+
+      decoded.cadAVL.active = active;
+      // Calculate .visibility after .active is set
+      const visibility: LocationVisibility[] = [
+        active ? LocationVisibility.Visible : LocationVisibility.Hidden,
+      ];
+      if (decoded.cadAVL.shared) {
+        visibility.push(LocationVisibility.Shared);
+      }
+      decoded.cadAVL.visibility = visibility;
+      await store.updateLocation(decoded.cadAVL, atDate);
+    }
+  }
+
+  async function processItemsDeviceMappingGeotab(department: Partial<Department>, items: LocationPayload[], atDate: Date) {
+    const departmentId = String(department._id);
+    for (const item of items) {
+      // TODO: may need to break decodeLocation out separately for device mapping, but works right now
+      const decoded = decodeLocation(item, department, atDate, "geotab");
+      debug(`processItemsDeviceMappingGeotab item: ${JSON.stringify(item)} d:${JSON.stringify(department)} at: ${atDate.toISOString()}.`);
+      if (!decoded.isValid) {
+        // Skip only the invalid item, not the rest of the batch
+        // This is actually a fix for vehicle processing as well
+        continue;
+      }
+
+      // Defensive code technically we shouldn't be getting here with person
+      // But it would still be valid to use this with a person so added the logic
+      if (await processPersonItem(decoded, item, atDate)) {
+        continue;
+      }
+
+      let active = true;
+      let locationToCAD = false;
+      const deviceMapping = await store.getDeviceMappingGeotab(item, departmentId);
+
+      if (_.isObject(deviceMapping)) {
+        if (_.isBoolean(deviceMapping.mapHidden)) {
+          active = !deviceMapping.mapHidden;
+        }
+        if (_.isBoolean(deviceMapping.locationToCAD)) {
+          locationToCAD = true;
+        }
+        if (_.isString(deviceMapping.mapId) && deviceMapping.mapId.trim() !== "") {
+          const radioName = deviceMapping.mapId;
+          const userId = `${radioName}-${item.vehicleId}`; // Fake user id radioName - vehicleId
+          decoded.cadAVL.username = radioName;
+          decoded.cadAVL.userId = userId;
+          decoded.cadAVL.session = userId;
+        }
+      }
+      // TODO: add support for location .kindType
+      decoded.cadAVL.active = active;
+      // Calculate .visibility after .active is set
+      const visibility: LocationVisibility[] = [
+        active ? LocationVisibility.Visible : LocationVisibility.Hidden,
+      ];
+      if (decoded.cadAVL.shared) {
+        visibility.push(LocationVisibility.Shared);
+      }
+      if (locationToCAD) {
+        decoded.cadAVL.sendToCAD = true;
+        visibility.push(LocationVisibility.CAD);
+      }
+      decoded.cadAVL.visibility = visibility;
+      await store.updateLocation(decoded.cadAVL, atDate);
+    }
+  }
+
+  return {
+    processVehicle,
+    processItems,
+    processItemsDeviceMappingGeotab,
+  };
+}
+
+export default location;
+export type LocationModule = ReturnType<typeof location>;