@justair/justair-library 7.5.0-alpha.c25c5a2 → 7.5.0-alpha.d0806df

package/dist/constants/deviceTypes.d.ts

@@ -5,4 +5,10 @@ export const DEVICE_TYPES: Readonly<{
 }>;
 export const DEVICE_TYPE_VALUES: readonly ("monitor" | "sample-site" | "linked-device")[];
 export function isAqiCapableDeviceType(deviceType: any): boolean;
+/**
+ * The device-type vocabulary as a type, so consumers get autocomplete and a
+ * compile error on a mis-cased value like "sampleSite" — the exact bug the
+ * runtime comments in utils/subscribedDevices.js warn about at length.
+ */
+export type DeviceType = (typeof DEVICE_TYPES)[keyof typeof DEVICE_TYPES];
 //# sourceMappingURL=deviceTypes.d.ts.map

package/dist/constants/deviceTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deviceTypes.d.ts","sourceRoot":"","sources":["../../src/constants/deviceTypes.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AAEH,0FAA6E;AAStE,iEAEoC"}
+{"version":3,"file":"deviceTypes.d.ts","sourceRoot":"","sources":["../../src/constants/deviceTypes.js"],"names":[],"mappings":"AA0BA;;;;GAIG;AAEH,0FAA6E;AAiBtE,iEAEoC;;;;;;yBAZ9B,CAAA,OAAO,YAAY,EAAC,MAAM,OAAO,YAAY,CAAC"}

package/dist/index.d.ts

@@ -107,6 +107,7 @@ import { DEVICE_TYPES } from "./constants/deviceTypes.js";
 import { DEVICE_TYPE_VALUES } from "./constants/deviceTypes.js";
 import { isAqiCapableDeviceType } from "./constants/deviceTypes.js";
 import { projectSubscribedMonitors } from "./utils/subscribedDevices.js";
+import { SUBSCRIBED_DEVICES_ERRORS } from "./utils/subscribedDevices.js";
 import { splitName } from "./utils/splitName.js";
 import { DEFAULT_QUIET_HOURS } from "./utils/quietHours.js";
 import { DEFAULT_TIMEZONE } from "./constants/timezones.js";
@@ -117,5 +118,5 @@ import { validateQuietHours } from "./utils/quietHours.js";
 import { getZoneMinutes } from "./utils/quietHours.js";
 import { isInQuietWindow } from "./utils/quietHours.js";
 import { resolveQuietHours } from "./utils/quietHours.js";
-export { Database, adminSchema, Admin, configurationsSchema, Configurations, measurementsSchema, Measurements, monitorRequestsSchema, MonitorRequests, monitorsSchema, Monitors, organizationsSchema, Organizations, usersSchema, Users, COOKIE_CONSENT_CATEGORIES, COOKIE_CONSENT_VALUES, validateCookieConsent, eventsSchema, Events, lightMonitorSchema, LightMonitors, monitorSuppliersSchema, MonitorSuppliers, contextsSchema, Contexts, parametersSchema, Parameters, announcementSchema, Announcements, jobsSchema, Jobs, apiKeySchema, ApiKey, UsageMetrics, usageMetricsSchema, Audit, auditSchema, EventsAudit, eventsAuditSchema, MonitorAudit, monitorAuditSchema, parametersEnum, deploymentTypesEnum, AlertsAudit, Alerts, alertsSchema, alertsAuditSchema, Features, featuresSchema, dataCompletenessSchema, DataCompleteness, networkMetricsSchema, NetworkMetrics, rateOfChangeSchema, RateOfChange, changeStreamCheckpointsSchema, ChangeStreamCheckpoints, sitesSchema, Sites, sampleSitesSchema, SampleSites, sampleSiteAuditSchema, SampleSiteAudit, sampleParametersEnum, samplesSchema, Samples, samplesAuditSchema, SamplesAudit, sampleParameterReferenceConcentrations, passwordResetTokenSchema, PasswordResetToken, monitorEpisodesSchema, MonitorEpisode, userNotificationsSchema, UserNotification, AqiAlertNotification, DeviceOfflineNotification, WeeklyDigestNotification, AccountNotification, NOTIFICATION_KINDS, NOTIFICATION_CHANNELS, DELIVERY_STATUSES, DATA_DOWNLOAD_TYPES, dataDownloadSchema, DataDownloads, AqiDataDownload, SampleDataDownload, DATA_DOWNLOAD_MAX_RANGE_DAYS, DATA_DOWNLOAD_ERRORS, validateDataDownloadDateOrder, validateDataDownloadMaxDateRange, validateDataDownloadEmail, normalizeDataDownloadEmail, validateDataDownloadTimezone, normalizeDataDownloadTimezone, PARAMETERS, HEAVY_METALS, ALERT_LEVEL_WEIGHTS, getAlertWeight, DEVICE_TYPES, DEVICE_TYPE_VALUES, isAqiCapableDeviceType, projectSubscribedMonitors, splitName, DEFAULT_QUIET_HOURS, DEFAULT_TIMEZONE, QUIET_HOURS_ERRORS, isValidTimeString, isValidIANATimezone, validateQuietHours, getZoneMinutes, isInQuietWindow, resolveQuietHours };
+export { Database, adminSchema, Admin, configurationsSchema, Configurations, measurementsSchema, Measurements, monitorRequestsSchema, MonitorRequests, monitorsSchema, Monitors, organizationsSchema, Organizations, usersSchema, Users, COOKIE_CONSENT_CATEGORIES, COOKIE_CONSENT_VALUES, validateCookieConsent, eventsSchema, Events, lightMonitorSchema, LightMonitors, monitorSuppliersSchema, MonitorSuppliers, contextsSchema, Contexts, parametersSchema, Parameters, announcementSchema, Announcements, jobsSchema, Jobs, apiKeySchema, ApiKey, UsageMetrics, usageMetricsSchema, Audit, auditSchema, EventsAudit, eventsAuditSchema, MonitorAudit, monitorAuditSchema, parametersEnum, deploymentTypesEnum, AlertsAudit, Alerts, alertsSchema, alertsAuditSchema, Features, featuresSchema, dataCompletenessSchema, DataCompleteness, networkMetricsSchema, NetworkMetrics, rateOfChangeSchema, RateOfChange, changeStreamCheckpointsSchema, ChangeStreamCheckpoints, sitesSchema, Sites, sampleSitesSchema, SampleSites, sampleSiteAuditSchema, SampleSiteAudit, sampleParametersEnum, samplesSchema, Samples, samplesAuditSchema, SamplesAudit, sampleParameterReferenceConcentrations, passwordResetTokenSchema, PasswordResetToken, monitorEpisodesSchema, MonitorEpisode, userNotificationsSchema, UserNotification, AqiAlertNotification, DeviceOfflineNotification, WeeklyDigestNotification, AccountNotification, NOTIFICATION_KINDS, NOTIFICATION_CHANNELS, DELIVERY_STATUSES, DATA_DOWNLOAD_TYPES, dataDownloadSchema, DataDownloads, AqiDataDownload, SampleDataDownload, DATA_DOWNLOAD_MAX_RANGE_DAYS, DATA_DOWNLOAD_ERRORS, validateDataDownloadDateOrder, validateDataDownloadMaxDateRange, validateDataDownloadEmail, normalizeDataDownloadEmail, validateDataDownloadTimezone, normalizeDataDownloadTimezone, PARAMETERS, HEAVY_METALS, ALERT_LEVEL_WEIGHTS, getAlertWeight, DEVICE_TYPES, DEVICE_TYPE_VALUES, isAqiCapableDeviceType, projectSubscribedMonitors, SUBSCRIBED_DEVICES_ERRORS, splitName, DEFAULT_QUIET_HOURS, DEFAULT_TIMEZONE, QUIET_HOURS_ERRORS, isValidTimeString, isValidIANATimezone, validateQuietHours, getZoneMinutes, isInQuietWindow, resolveQuietHours };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AA0JA;;;iBAEC;yBA1FwB,oBAAoB;qBADxB,gBAAgB;4BAjEF,mBAAmB;sBAAnB,mBAAmB;qCAI/C,4BAA4B;+BAA5B,4BAA4B;mCAM5B,0BAA0B;6BAA1B,0BAA0B;sCAI1B,6BAA6B;gCAA7B,6BAA6B;+BAQ7B,sBAAsB;yBAAtB,sBAAsB;oCACsB,2BAA2B;8BAA3B,2BAA2B;4BAcvE,mBAAmB;sBAAnB,mBAAmB;0CAAnB,mBAAmB;sCAAnB,mBAAmB;sCAAnB,mBAAmB;6BAMnB,oBAAoB;uBAApB,oBAAoB;mCAnBuB,2BAA2B;8BAA3B,2BAA2B;uCAItE,8BAA8B;iCAA9B,8BAA8B;+BACI,sBAAsB;yBAAtB,sBAAsB;iCAClB,wBAAwB;2BAAxB,wBAAwB;mCAcnB,2BAA2B;8BAA3B,2BAA2B;2BAC5C,kBAAkB;qBAAlB,kBAAkB;6BACd,oBAAoB;uBAApB,oBAAoB;6BACR,0BAA0B;mCAA1B,0BAA0B;sBArCpE,0BAA0B;4BAA1B,0BAA0B;4BAiC1B,oBAAoB;kCAApB,oBAAoB;6BArBpB,sBAAsB;mCAAtB,sBAAsB;+BAAtB,sBAAsB;oCAAtB,sBAAsB;4BA+BtB,oBAAoB;uBAApB,oBAAoB;6BAApB,oBAAoB;kCAApB,oBAAoB;yBACc,sBAAsB;+BAAtB,sBAAsB;uCAIxD,8BAA8B;iCAA9B,8BAA8B;qCACgB,4BAA4B;+BAA5B,4BAA4B;mCAChC,0BAA0B;6BAA1B,0BAA0B;8CAIpE,qCAAqC;wCAArC,qCAAqC;4BAyCT,mBAAmB;sBAAnB,mBAAmB;kCAS/C,yBAAyB;4BAAzB,yBAAyB;sCAAzB,yBAAyB;gCAAzB,yBAAyB;qCAAzB,yBAAyB;8BASzB,qBAAqB;wBAArB,qBAAqB;mCAArB,qBAAqB;6BAArB,qBAAqB;uDAArB,qBAAqB;yCACiC,gCAAgC;mCAAhC,gCAAgC;sCA7CtF,6BAA6B;+BAA7B,6BAA6B;wCAW7B,+BAA+B;iCAA/B,+BAA+B;qCAA/B,+BAA+B;0CAA/B,+BAA+B;yCAA/B,+BAA+B;oCAA/B,+BAA+B;mCAA/B,+BAA+B;sCAA/B,+BAA+B;kCAA/B,+BAA+B;oCApBF,8BAA8B;mCA4D3D,2BAA2B;8BAA3B,2BAA2B;gCAA3B,2BAA2B;mCAA3B,2BAA2B;+DAsB3B,mCAAmC;qCAAnC,mCAAmC;mEAAnC,mCAAmC;yEAAnC,mCAAmC;mEAAnC,mCAAmC;qEAAnC,mCAAmC;yEAAnC,mCAAmC;2EAAnC,mCAAmC;2BArFD,2BAA2B;6BAA3B,2BAA2B;oCAChB,4BAA4B;+BAA5B,4BAA4B;6BAOzE,4BAA4B;mCAA5B,4BAA4B;uCAA5B,4BAA4B;0CA2BO,8BAA8B;0BAX9C,sBAAsB;oCASzC,uBAAuB;iCA/BG,0BAA0B;mCA+BpD,uBAAuB;kCAAvB,uBAAuB;oCACM,qBAAqB;mCADlD,uBAAuB;+BAAvB,uBAAuB;gCAAvB,uBAAuB;kCAAvB,uBAAuB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AA6JA;;;iBAEC;yBA7FwB,oBAAoB;qBADxB,gBAAgB;4BAjEF,mBAAmB;sBAAnB,mBAAmB;qCAI/C,4BAA4B;+BAA5B,4BAA4B;mCAM5B,0BAA0B;6BAA1B,0BAA0B;sCAI1B,6BAA6B;gCAA7B,6BAA6B;+BAQ7B,sBAAsB;yBAAtB,sBAAsB;oCACsB,2BAA2B;8BAA3B,2BAA2B;4BAcvE,mBAAmB;sBAAnB,mBAAmB;0CAAnB,mBAAmB;sCAAnB,mBAAmB;sCAAnB,mBAAmB;6BAMnB,oBAAoB;uBAApB,oBAAoB;mCAnBuB,2BAA2B;8BAA3B,2BAA2B;uCAItE,8BAA8B;iCAA9B,8BAA8B;+BACI,sBAAsB;yBAAtB,sBAAsB;iCAClB,wBAAwB;2BAAxB,wBAAwB;mCAcnB,2BAA2B;8BAA3B,2BAA2B;2BAC5C,kBAAkB;qBAAlB,kBAAkB;6BACd,oBAAoB;uBAApB,oBAAoB;6BACR,0BAA0B;mCAA1B,0BAA0B;sBArCpE,0BAA0B;4BAA1B,0BAA0B;4BAiC1B,oBAAoB;kCAApB,oBAAoB;6BArBpB,sBAAsB;mCAAtB,sBAAsB;+BAAtB,sBAAsB;oCAAtB,sBAAsB;4BA+BtB,oBAAoB;uBAApB,oBAAoB;6BAApB,oBAAoB;kCAApB,oBAAoB;yBACc,sBAAsB;+BAAtB,sBAAsB;uCAIxD,8BAA8B;iCAA9B,8BAA8B;qCACgB,4BAA4B;+BAA5B,4BAA4B;mCAChC,0BAA0B;6BAA1B,0BAA0B;8CAIpE,qCAAqC;wCAArC,qCAAqC;4BA4CT,mBAAmB;sBAAnB,mBAAmB;kCAS/C,yBAAyB;4BAAzB,yBAAyB;sCAAzB,yBAAyB;gCAAzB,yBAAyB;qCAAzB,yBAAyB;8BASzB,qBAAqB;wBAArB,qBAAqB;mCAArB,qBAAqB;6BAArB,qBAAqB;uDAArB,qBAAqB;yCACiC,gCAAgC;mCAAhC,gCAAgC;sCAhDtF,6BAA6B;+BAA7B,6BAA6B;wCAW7B,+BAA+B;iCAA/B,+BAA+B;qCAA/B,+BAA+B;0CAA/B,+BAA+B;yCAA/B,+BAA+B;oCAA/B,+BAA+B;mCAA/B,+BAA+B;sCAA/B,+BAA+B;kCAA/B,+BAA+B;oCApBF,8BAA8B;mCA+D3D,2BAA2B;8BAA3B,2BAA2B;gCAA3B,2BAA2B;mCAA3B,2BAA2B;+DAsB3B,mCAAmC;qCAAnC,mCAAmC;mEAAnC,mCAAmC;yEAAnC,mCAAmC;mEAAnC,mCAAmC;qEAAnC,mCAAmC;yEAAnC,mCAAmC;2EAAnC,mCAAmC;2BAxFD,2BAA2B;6BAA3B,2BAA2B;oCAChB,4BAA4B;+BAA5B,4BAA4B;6BAOzE,4BAA4B;mCAA5B,4BAA4B;uCAA5B,4BAA4B;0CA8B5B,8BAA8B;0CAA9B,8BAA8B;0BAdX,sBAAsB;oCASzC,uBAAuB;iCA/BG,0BAA0B;mCA+BpD,uBAAuB;kCAAvB,uBAAuB;oCACM,qBAAqB;mCADlD,uBAAuB;+BAAvB,uBAAuB;gCAAvB,uBAAuB;kCAAvB,uBAAuB"}

package/dist/models/users.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AAyFA,8BA6GE;AAiCF,wBAAmD;AA9NnD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DAsBC"}
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AAyFA,8BAgGE;AAiCF,wBAAmD;AAjNnD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DAsBC"}

package/dist/utils/subscribedDevices.d.ts

@@ -1,8 +1,13 @@
+export const SUBSCRIBED_DEVICES_ERRORS: Readonly<{
+    MISSING_SITE_RESOLVER: "missing_site_resolver";
+    RESOLVER_RETURNED_NON_ARRAY: "resolver_returned_non_array";
+    RESOLVER_RETURNED_NESTED_ARRAYS: "resolver_returned_nested_arrays";
+    RESOLVER_RETURNED_DOCUMENTS: "resolver_returned_documents";
+}>;
 export function projectSubscribedMonitors(subscribedDevices?: Array<{
     deviceId: import("mongoose").Types.ObjectId;
-    deviceType: string;
+    deviceType: import("../constants/deviceTypes.js").DeviceType;
 }>, { resolveSiteMonitorIds }?: {
     resolveSiteMonitorIds?: (siteIds: import("mongoose").Types.ObjectId[]) => Promise<Array<import("mongoose").Types.ObjectId | null | undefined>>;
 }): Promise<import("mongoose").Types.ObjectId[]>;
-export function hasAqiCapableSubscription(subscribedDevices: any): any;
 //# sourceMappingURL=subscribedDevices.d.ts.map

package/dist/utils/subscribedDevices.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscribedDevices.d.ts","sourceRoot":"","sources":["../../src/utils/subscribedDevices.js"],"names":[],"mappings":"AA6JO,8DALI,KAAK,CAAC;IAAE,QAAQ,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,8BAC1E;IAAE,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,KAC7E,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAA;CAAE,GAC9D,OAAO,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAsBxD;AAOM,uEAGuD"}
+{"version":3,"file":"subscribedDevices.d.ts","sourceRoot":"","sources":["../../src/utils/subscribedDevices.js"],"names":[],"mappings":"AAqFA;;;;;GAKG;AA4II,8DANI,KAAK,CAAC;IAAE,QAAQ,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC;IAC1D,UAAU,EAAE,OAAO,6BAA6B,EAAE,UAAU,CAAA;CAAE,CAAC,8BACzD;IAAE,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,KAC7E,OAAO,CAAC,KAAK,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAA;CAAE,GAC9D,OAAO,CAAC,OAAO,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CA0BxD"}

package/dist/utils/tests/subscribedDevicesBarrel.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=subscribedDevicesBarrel.test.d.ts.map

package/dist/utils/tests/subscribedDevicesBarrel.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscribedDevicesBarrel.test.d.ts","sourceRoot":"","sources":["../../../src/utils/tests/subscribedDevicesBarrel.test.js"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justair/justair-library",
-  "version": "7.5.0-alpha.c25c5a2",
+  "version": "7.5.0-alpha.d0806df",
   "description": "JustAir Internal Library",
   "main": "src/index.js",
   "type": "module",

package/src/constants/deviceTypes.js

@@ -32,6 +32,14 @@ export const DEVICE_TYPES = Object.freeze({
 
 export const DEVICE_TYPE_VALUES = Object.freeze(Object.values(DEVICE_TYPES));
 
+/**
+ * The device-type vocabulary as a type, so consumers get autocomplete and a
+ * compile error on a mis-cased value like "sampleSite" — the exact bug the
+ * runtime comments in utils/subscribedDevices.js warn about at length.
+ *
+ * @typedef {typeof DEVICE_TYPES[keyof typeof DEVICE_TYPES]} DeviceType
+ */
+
 // Whether a device of this type can ever report AQI, and therefore whether a
 // subscription to it can contribute to AQI alert delivery.
 //

package/src/index.js

@@ -100,7 +100,10 @@ import {
   resolveQuietHours,
 } from "./utils/quietHours.js";
 import { isValidIANATimezone } from "./utils/timezone.js";
-import { projectSubscribedMonitors } from "./utils/subscribedDevices.js";
+import {
+  projectSubscribedMonitors,
+  SUBSCRIBED_DEVICES_ERRORS,
+} from "./utils/subscribedDevices.js";
 
 // Sites related imports
 import { sitesSchema, Sites } from "./models/sites.js";
@@ -272,11 +275,11 @@ export {
   // subscribedDevices → subscribedMonitors projection (JA-3110 / JA-3335).
   // Every consumer that writes a subscription recomputes the AQI audience with
   // this instead of re-implementing the per-device-type rule.
-  //
-  // hasAqiCapableSubscription is deliberately NOT re-exported here: nothing
-  // consumes it yet, and an export cannot be withdrawn without a major bump.
-  // It stays module-internal until a consumer needs it.
+  // SUBSCRIBED_DEVICES_ERRORS is the stable `err.code` vocabulary for the
+  // errors projectSubscribedMonitors throws; consumers branch on it rather
+  // than on message wording.
   projectSubscribedMonitors,
+  SUBSCRIBED_DEVICES_ERRORS,
   // Utilities
   splitName,
   // Quiet hours (JA-3054): shared validation + window evaluation

package/src/models/users.js

@@ -103,30 +103,17 @@ const usersSchema = mongoose.Schema(
     // Subscribed devices (JA-3110 / JA-3335) — the source of truth for what the
     // user has added to "My Monitors", across all three device types.
     //
-    // Relationship to subscribedMonitors above: that array stays monitor ids
-    // ONLY, and is the AQI-alert projection of this one. The two must be
-    // written together on every subscribe/unsubscribe path. What each device
-    // type contributes to the projection is specified once, in the header of
-    // src/utils/subscribedDevices.js — read it there, not from a summary here.
+    // subscribedMonitors above is its derived AQI-alert projection (monitor ids
+    // only). The two must be written together on every subscribe and
+    // unsubscribe path, using `projectSubscribedMonitors` rather than a
+    // per-consumer reimplementation. It is deliberately not a schema validator:
+    // the projection needs a Site lookup, which the schema has no business
+    // doing.
     //
-    // Do not re-implement that rule per consumer: recompute the projection with
-    // `projectSubscribedMonitors` from src/utils/subscribedDevices.js (exported
-    // from src/index.js). It is deliberately not a schema validator — a
-    // projection is a write-path computation and needs a Site lookup, which the
-    // schema has no business doing.
-    //
-    // Writing subscribedMonitors has a hard precondition (a blanket overwrite
-    // drops the subscriptions of any user who predates this field) and a known
-    // staleness gap. Both are specified once, in the PRECONDITION and STALENESS
-    // notes at the top of src/utils/subscribedDevices.js — read them there
-    // rather than trusting a summary here.
-    //
-    // Why the split matters: JustAirNotificationService reads subscribedMonitors
-    // and drops ids that do not resolve to a Monitor (statusAlerts.js
-    // `.filter(monitor => monitor)`). Writing a Site or SampleSite id in there
-    // therefore throws no error — it silently delivers no alerts. Keeping the
-    // polymorphic ids in their own field preserves that invariant for every
-    // library consumer.
+    // Everything else — the per-device-type rule, the backfill PRECONDITION,
+    // the STALENESS gap, and why the field is split at all — is specified once,
+    // in the header of src/utils/subscribedDevices.js. Read it there; it is
+    // deliberately not summarised here.
     subscribedDevices: [subscribedDeviceSchema],
     currentAlertMode: {
       type: String,

package/src/utils/subscribedDevices.js

@@ -42,11 +42,20 @@
 //      { deviceId, deviceType: "monitor" } entry per existing id), then
 //      overwrite freely. This is the target state.
 //   2. Until that backfill has run for the user, union the projection with the
-//      existing subscribedMonitors instead of overwriting. THIS IS
-//      SUBSCRIBE-ONLY. A union can only ever add ids, so using it for an
-//      unsubscribe makes the removal a silent no-op. There is deliberately no
-//      third option: an unsubscribe on a user who predates subscribedDevices
-//      MUST run the per-user backfill in option 1 first, and only then
+//      existing subscribedMonitors instead of overwriting — AND write the
+//      per-user backfill in the same update, one
+//      { deviceId, deviceType: "monitor" } entry per id already in
+//      subscribedMonitors, alongside the device being subscribed. Both halves
+//      are required. Unioning without backfilling leaves a user who looks
+//      migrated (subscribedDevices is non-empty) but is not, so the obvious
+//      "has this user been backfilled?" check answers yes and the next
+//      unsubscribe overwrites subscribedMonitors with a projection missing
+//      every monitor they had before. A half-migrated user must never exist.
+//
+//      This path is also SUBSCRIBE-ONLY. A union can only ever add ids, so
+//      using it for an unsubscribe makes the removal a silent no-op. There is
+//      deliberately no third option: an unsubscribe on a user who predates
+//      subscribedDevices MUST be preceded by the backfill, and only then
 //      overwrite. Removing a subscription is not correct any other way.
 //
 // This module deliberately does NOT offer a `union: true` flag. A blanket
@@ -69,10 +78,17 @@
 // affected subscribers. That reprojection is not implemented anywhere yet and
 // needs a follow-up ticket under JA-3110.
 
-import {
-  DEVICE_TYPES,
-  isAqiCapableDeviceType,
-} from "../constants/deviceTypes.js";
+import { DEVICE_TYPES } from "../constants/deviceTypes.js";
+
+// Stable error codes thrown by this module. Consumers filter on `err.code`
+// — never on message wording, which is free to change. Same contract as
+// QUIET_HOURS_ERRORS in utils/quietHours.js.
+export const SUBSCRIBED_DEVICES_ERRORS = Object.freeze({
+  MISSING_SITE_RESOLVER: "missing_site_resolver",
+  RESOLVER_RETURNED_NON_ARRAY: "resolver_returned_non_array",
+  RESOLVER_RETURNED_NESTED_ARRAYS: "resolver_returned_nested_arrays",
+  RESOLVER_RETURNED_DOCUMENTS: "resolver_returned_documents",
+});
 
 // Dedupe by string form, keep the caller's ObjectId instances. Two equal
 // ObjectIds are different object identities, so Set/includes on the raw values
@@ -119,6 +135,60 @@ const linkedSiteIds = (entries) =>
     .filter((entry) => entry.deviceType === DEVICE_TYPES.LINKED_DEVICE)
     .map((entry) => entry.deviceId);
 
+// The resolver is consumer-supplied, so its return is the one input this
+// module cannot check at the type boundary. Validate it rather than trust it:
+// both bad shapes below would otherwise corrupt subscribedMonitors silently,
+// and silent is the failure mode this whole field split exists to avoid.
+// Nullish stays tolerated — a consumer whose Sites resolved to nothing may
+// legitimately return nothing.
+const validateResolvedSiteMonitorIds = (resolved) => {
+  if (resolved === null || resolved === undefined) {
+    return [];
+  }
+
+  if (!Array.isArray(resolved)) {
+    const error = new TypeError(
+      "resolveSiteMonitorIds must resolve to an array of monitor ids"
+    );
+    error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NON_ARRAY;
+    throw error;
+  }
+
+  // `.map` instead of `.flatMap` yields [[m1, m2]]. An array is not a plain
+  // object, so the document check below never sees it, and it fails
+  // inconsistently downstream: one monitor per Site casts back to the id and
+  // silently works, two throws a CastError at write time, far from the cause.
+  if (resolved.some(Array.isArray)) {
+    const error = new TypeError(
+      "resolveSiteMonitorIds must resolve to a flat array of monitor ids"
+    );
+    error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NESTED_ARRAYS;
+    throw error;
+  }
+
+  // Discriminating a document from an id without importing mongoose: test for
+  // what only an id has. `toHexString` is on ObjectId (mongoose-patched or raw
+  // bson) and on nothing a Sites query returns, hydrated or lean.
+  //
+  // Deliberately not keyed on `_id`, which is wrong in both directions: every
+  // ObjectId appears to carry one (mongoose defines `_id` on ObjectId.prototype
+  // as a self-reference), and a lean read that projects it away
+  // (`Sites.find(..., "monitorIds -_id").lean()`) carries none.
+  if (
+    resolved.some(
+      (id) => isPlainObject(id) && typeof id.toHexString !== "function"
+    )
+  ) {
+    const error = new TypeError(
+      "resolveSiteMonitorIds must resolve to monitor ids, not Site documents"
+    );
+    error.code = SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS;
+    throw error;
+  }
+
+  return resolved;
+};
+
 // Returns the monitor ids that should be stored in Users.subscribedMonitors for
 // the given subscribedDevices array. Order is deterministic — direct `monitor`
 // subscriptions in array order, then Site-derived ids in resolver order, first
@@ -136,10 +206,12 @@ const linkedSiteIds = (entries) =>
 //   const sites = await Sites.find({ _id: { $in: siteIds } }, "monitorIds").lean();
 //   return sites.flatMap((site) => site.monitorIds ?? []);
 //
-// Returning the documents is the easy mistake and it fails silently: dedupeById
-// only drops nullish, so each Site doc survives, mongoose casts it to its own
-// _id on write, and subscribedMonitors fills with Site ids — exactly the
-// polymorphic id this field split exists to keep out.
+// Returning the documents is the easy mistake, so it is rejected rather than
+// merely documented: the return is validated and a document-shaped entry
+// throws RESOLVER_RETURNED_DOCUMENTS, as a non-array return throws
+// RESOLVER_RETURNED_NON_ARRAY. Left unchecked it would fail silently — each
+// Site doc casts to its own _id on write and subscribedMonitors fills with
+// Site ids, exactly the polymorphic id this field split exists to keep out.
 //
 // It is not called at all when nothing is subscribed to a linked-device, so a
 // consumer that only handles monitors pays no query. A resolver may return
@@ -150,7 +222,8 @@ const linkedSiteIds = (entries) =>
 // Read the PRECONDITION and STALENESS notes at the top of this file before
 // writing the result to Users.subscribedMonitors.
 /**
- * @param {Array<{ deviceId: import("mongoose").Types.ObjectId, deviceType: string }>} [subscribedDevices]
+ * @param {Array<{ deviceId: import("mongoose").Types.ObjectId,
+ *   deviceType: import("../constants/deviceTypes.js").DeviceType }>} [subscribedDevices]
  * @param {{ resolveSiteMonitorIds?: (siteIds: import("mongoose").Types.ObjectId[]) =>
  *   Promise<Array<import("mongoose").Types.ObjectId | null | undefined>> }} [options]
  * @returns {Promise<import("mongoose").Types.ObjectId[]>}
@@ -168,21 +241,15 @@ export const projectSubscribedMonitors = async (
   }
 
   if (typeof resolveSiteMonitorIds !== "function") {
-    throw new TypeError(
+    const error = new TypeError(
       "projectSubscribedMonitors requires resolveSiteMonitorIds when a linked-device is subscribed"
     );
+    error.code = SUBSCRIBED_DEVICES_ERRORS.MISSING_SITE_RESOLVER;
+    throw error;
   }
 
-  const siteMonitorIds = (await resolveSiteMonitorIds(siteIds)) ?? [];
+  const siteMonitorIds = validateResolvedSiteMonitorIds(
+    await resolveSiteMonitorIds(siteIds)
+  );
   return dedupeById([...direct, ...siteMonitorIds]);
 };
-
-// Whether a subscribedDevices array can produce any AQI audience at all,
-// without resolving Sites. `false` is certain (nothing subscribed can ever
-// alert); `true` only means a linked-device is present and its Site still has
-// to be checked — the same necessary-but-not-sufficient asymmetry as
-// isAqiCapableDeviceType.
-export const hasAqiCapableSubscription = (subscribedDevices) =>
-  (subscribedDevices ?? [])
-    .filter(isPlainObject)
-    .some((entry) => isAqiCapableDeviceType(entry.deviceType));

package/src/utils/tests/subscribedDevices.test.js

@@ -1,7 +1,12 @@
 import mongoose from 'mongoose';
+import { Users } from '../../models/users.js';
+import {
+  DEVICE_TYPE_VALUES,
+  isAqiCapableDeviceType,
+} from '../../constants/deviceTypes.js';
 import {
   projectSubscribedMonitors,
-  hasAqiCapableSubscription,
+  SUBSCRIBED_DEVICES_ERRORS,
 } from '../subscribedDevices.js';
 
 const oid = () => new mongoose.Types.ObjectId();
@@ -111,9 +116,104 @@ describe('projectSubscribedMonitors', () => {
   test('throws when a linked-device is subscribed and no resolver is injected', async () => {
     // Loud on the one input it genuinely cannot project alone, rather than
     // silently returning a short audience and dropping real alerts.
+    // The `code` is the contract consumers branch on; the message is not.
     await expect(
       projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }]),
-    ).rejects.toThrow(/resolveSiteMonitorIds/);
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.MISSING_SITE_RESOLVER,
+    });
+  });
+
+  test('rejects a resolver that returns Site documents rather than monitor ids', async () => {
+    // The silent-corruption case: without this guard each doc survives
+    // dedupeById and casts to its own _id on write, filling subscribedMonitors
+    // with Site ids that the notification service then quietly drops.
+    const siteId = oid();
+    await expect(
+      projectSubscribedMonitors([{ deviceId: siteId, deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => [{ _id: siteId, monitorIds: [oid()] }],
+      }),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS,
+    });
+  });
+
+  test('rejects a resolver that returns nested arrays (.map instead of .flatMap)', async () => {
+    const siteId = oid();
+    await expect(
+      projectSubscribedMonitors([{ deviceId: siteId, deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => [[oid(), oid()]],
+      }),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NESTED_ARRAYS,
+    });
+  });
+
+  test('rejects a lean Site read that projected _id away', async () => {
+    // The `_id`-based discriminator missed this: `Sites.find(..., "monitorIds
+    // -_id").lean()` yields objects carrying no _id at all, which would
+    // otherwise key as "[object Object]" in dedupeById and land in
+    // subscribedMonitors as junk.
+    await expect(
+      projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => [{ monitorIds: [oid()] }],
+      }),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS,
+    });
+  });
+
+  test('rejects a hydrated Site document (the forgot-.lean() case)', async () => {
+    // The likeliest real-world shape of this mistake. A throwaway model keeps
+    // this file off the real Sites schema; hydration needs no connection.
+    const HydratedSite = mongoose.model(
+      'SubscribedDevicesProbeSite',
+      new mongoose.Schema({ monitorIds: [mongoose.Schema.Types.ObjectId] }),
+    );
+
+    await expect(
+      projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => [new HydratedSite({ monitorIds: [oid()] })],
+      }),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_DOCUMENTS,
+    });
+  });
+
+  test('does not mistake ordinary ObjectIds for documents', async () => {
+    // Regression guard for the discriminator: an id has `toHexString`, a Site
+    // document does not. Keying on `_id` instead gets it wrong both ways —
+    // mongoose defines `_id` on ObjectId.prototype as a self-reference, so a
+    // naive "has _id" check rejects every legitimate resolver result.
+    const siteId = oid();
+    const monitorId = oid();
+
+    expect(monitorId._id).toBe(monitorId);
+    await expect(
+      projectSubscribedMonitors([{ deviceId: siteId, deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => [monitorId],
+      }),
+    ).resolves.toEqual([monitorId]);
+  });
+
+  test('rejects a resolver that does not return an array', async () => {
+    await expect(
+      projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => oid(),
+      }),
+    ).rejects.toMatchObject({
+      code: SUBSCRIBED_DEVICES_ERRORS.RESOLVER_RETURNED_NON_ARRAY,
+    });
+  });
+
+  test('still tolerates a resolver that returns nothing', async () => {
+    // Distinct from the two rejections above: resolving to nothing is a real
+    // state (a sample-only Site links no monitors), not a consumer mistake.
+    await expect(
+      projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }], {
+        resolveSiteMonitorIds: async () => undefined,
+      }),
+    ).resolves.toEqual([]);
   });
 
   test('dedupes a monitor reached both directly and through a Site', async () => {
@@ -268,39 +368,48 @@ describe('projectSubscribedMonitors', () => {
   });
 });
 
-// Pins the export-contract decision, not behaviour: src/index.js is the public
-// surface of this package and an export there cannot be withdrawn without a
-// major bump. projectSubscribedMonitors is the sanctioned consumer entry point;
-// hasAqiCapableSubscription has no caller yet, so it stays module-internal
-// until one exists. Flipping either line is a deliberate contract change.
-describe('barrel surface', () => {
-  test('exports projectSubscribedMonitors and withholds hasAqiCapableSubscription', async () => {
-    const barrel = await import('../../index.js');
-
-    expect(barrel.projectSubscribedMonitors).toBe(projectSubscribedMonitors);
-    expect(barrel.hasAqiCapableSubscription).toBeUndefined();
-  });
-});
+// Two encodings of "which device types can produce AQI" exist: the predicate
+// isAqiCapableDeviceType, and the selectors inside projectSubscribedMonitors.
+// Nothing structural keeps them in step, so a fourth type added to one and not
+// the other would report as AQI-capable while contributing no audience — the
+// silent failure this module exists to prevent. This pins them together.
+// Every other case here passes plain object literals, but the real call site
+// hands in user.subscribedDevices — a mongoose DocumentArray of subdocuments,
+// which has to survive the isPlainObject filter. If it ever stopped doing so
+// every entry would be dropped and the projection would return an empty
+// audience with no error. Hydration needs no connection, so this stays DB-free.
+describe('accepts real mongoose subdocuments, not just object literals', () => {
+  test('projects a hydrated user.subscribedDevices the same as plain objects', async () => {
+    const monitorId = oid();
+    const siteId = oid();
+    const siteMonitorId = oid();
 
-describe('hasAqiCapableSubscription', () => {
-  test('false when only sample-sites are subscribed', () => {
-    expect(
-      hasAqiCapableSubscription([{ deviceId: oid(), deviceType: 'sample-site' }]),
-    ).toBe(false);
-  });
+    const user = new Users({
+      subscribedDevices: [
+        { deviceId: monitorId, deviceType: 'monitor' },
+        { deviceId: siteId, deviceType: 'linked-device' },
+        { deviceId: oid(), deviceType: 'sample-site' },
+      ],
+    });
 
-  test('true for a monitor, and for a linked-device pending its Site check', () => {
-    expect(
-      hasAqiCapableSubscription([{ deviceId: oid(), deviceType: 'monitor' }]),
-    ).toBe(true);
-    expect(
-      hasAqiCapableSubscription([{ deviceId: oid(), deviceType: 'linked-device' }]),
-    ).toBe(true);
+    await expect(
+      projectSubscribedMonitors(user.subscribedDevices, {
+        resolveSiteMonitorIds: async () => [siteMonitorId],
+      }),
+    ).resolves.toEqual([monitorId, siteMonitorId]);
   });
+});
+
+describe('isAqiCapableDeviceType agrees with the projection', () => {
+  test.each(DEVICE_TYPE_VALUES)('%s', async (deviceType) => {
+    const deviceId = oid();
+    const projected = await projectSubscribedMonitors(
+      [{ deviceId, deviceType }],
+      // Resolves as though the id were a Site linking exactly one monitor, so
+      // a linked-device yields an audience and a sample-site still yields none.
+      { resolveSiteMonitorIds: async () => [oid()] },
+    );
 
-  test('false for a missing, empty, or unrecognised array', () => {
-    expect(hasAqiCapableSubscription(undefined)).toBe(false);
-    expect(hasAqiCapableSubscription([])).toBe(false);
-    expect(hasAqiCapableSubscription([{ deviceType: 'Monitor' }])).toBe(false);
+    expect(projected.length > 0).toBe(isAqiCapableDeviceType(deviceType));
   });
 });

package/src/utils/tests/subscribedDevicesBarrel.test.js

@@ -0,0 +1,38 @@
+// Pins the public export surface for the subscribedDevices module, kept in its
+// own file because asserting on the root barrel imports src/index.js, which
+// registers every mongoose model. Mixing that into the pure unit tests would
+// make them fail whenever any unrelated model failed to load. Same shape as
+// constants/tests/constantsBarrel.test.js.
+//
+// src/index.js is the published surface of this package, so an export here
+// cannot be withdrawn without a major bump. Flipping either assertion is a
+// deliberate contract change, not a test fix.
+import {
+  projectSubscribedMonitors,
+  SUBSCRIBED_DEVICES_ERRORS,
+} from '../subscribedDevices.js';
+import {
+  DEVICE_TYPES,
+  DEVICE_TYPE_VALUES,
+  isAqiCapableDeviceType,
+} from '../../constants/deviceTypes.js';
+
+test('barrel re-exports the subscribedDevices surface unchanged (identity, not copies)', async () => {
+  const barrel = await import('../../index.js');
+
+  expect(barrel.projectSubscribedMonitors).toBe(projectSubscribedMonitors);
+  expect(barrel.SUBSCRIBED_DEVICES_ERRORS).toBe(SUBSCRIBED_DEVICES_ERRORS);
+});
+
+// constants/tests/deviceTypes.test.js pins these on the `./constants` barrel;
+// the root barrel re-exports them through a separate hand-written import and
+// export pair, so a dropped line there publishes cleanly and only fails at
+// runtime inside a consuming service. Pinned here rather than there because
+// this is the file that already carries the root-barrel dependency.
+test('barrel re-exports the device-type vocabulary unchanged (identity, not copies)', async () => {
+  const barrel = await import('../../index.js');
+
+  expect(barrel.DEVICE_TYPES).toBe(DEVICE_TYPES);
+  expect(barrel.DEVICE_TYPE_VALUES).toBe(DEVICE_TYPE_VALUES);
+  expect(barrel.isAqiCapableDeviceType).toBe(isAqiCapableDeviceType);
+});