@justair/justair-library 7.4.0 → 7.5.0-alpha.45d4756

package/dist/constants/deviceTypes.d.ts

@@ -0,0 +1,8 @@
+export const DEVICE_TYPES: Readonly<{
+    MONITOR: "monitor";
+    SAMPLE_SITE: "sample-site";
+    LINKED_DEVICE: "linked-device";
+}>;
+export const DEVICE_TYPE_VALUES: readonly ("monitor" | "sample-site" | "linked-device")[];
+export function isAqiCapableDeviceType(deviceType: any): boolean;
+//# sourceMappingURL=deviceTypes.d.ts.map

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

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

package/dist/constants/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./pollutants.js";
 export * from "./alertLevels.js";
 export * from "./userNotifications.js";
+export * from "./deviceTypes.js";
 export * from "./timezones.js";
 export * from "./dataDownloads.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/constants/tests/deviceTypes.test.d.ts

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

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

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

package/dist/index.d.ts

@@ -103,6 +103,10 @@ import { PARAMETERS } from "./constants/pollutants.js";
 import { HEAVY_METALS } from "./constants/pollutants.js";
 import { ALERT_LEVEL_WEIGHTS } from "./constants/alertLevels.js";
 import { getAlertWeight } from "./constants/alertLevels.js";
+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 { splitName } from "./utils/splitName.js";
 import { DEFAULT_QUIET_HOURS } from "./utils/quietHours.js";
 import { DEFAULT_TIMEZONE } from "./constants/timezones.js";
@@ -113,5 +117,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, 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, 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":"AAoJA;;;iBAEC;yBApFwB,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;4BAmCT,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;sCA5CtF,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;oCAfF,8BAA8B;mCAsD3D,2BAA2B;8BAA3B,2BAA2B;gCAA3B,2BAA2B;mCAA3B,2BAA2B;+DAsB3B,mCAAmC;qCAAnC,mCAAmC;mEAAnC,mCAAmC;yEAAnC,mCAAmC;mEAAnC,mCAAmC;qEAAnC,mCAAmC;yEAAnC,mCAAmC;2EAAnC,mCAAmC;2BA/ED,2BAA2B;6BAA3B,2BAA2B;oCAChB,4BAA4B;+BAA5B,4BAA4B;0BAkBtD,sBAAsB;oCASzC,uBAAuB;iCA1BG,0BAA0B;mCA0BpD,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":"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"}

package/dist/models/monitorEpisodes.d.ts

@@ -1,8 +1,8 @@
 export const monitorEpisodesSchema: mongoose.Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
 }, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -10,8 +10,8 @@ export const monitorEpisodesSchema: mongoose.Schema<any, mongoose.Model<any, any
     endedAt?: NativeDate;
     peakStatus?: string;
 } & mongoose.DefaultTimestampProps, mongoose.Document<unknown, {}, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -23,8 +23,8 @@ export const monitorEpisodesSchema: mongoose.Schema<any, mongoose.Model<any, any
 }, Omit<mongoose.DefaultSchemaOptions, "timestamps"> & {
     timestamps: true;
 }> & Omit<{
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -38,8 +38,8 @@ export const monitorEpisodesSchema: mongoose.Schema<any, mongoose.Model<any, any
 }, "id"> & mongoose.HydratedDocumentOverrides<{
     id: string;
 }>, unknown, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -54,8 +54,8 @@ export const monitorEpisodesSchema: mongoose.Schema<any, mongoose.Model<any, any
     __v: number;
 }>;
 export const MonitorEpisode: mongoose.Model<{
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -65,8 +65,8 @@ export const MonitorEpisode: mongoose.Model<{
 } & mongoose.DefaultTimestampProps, {}, {}, {
     id: string;
 }, mongoose.Document<unknown, {}, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -78,8 +78,8 @@ export const MonitorEpisode: mongoose.Model<{
 }, {
     timestamps: true;
 }> & Omit<{
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -95,8 +95,8 @@ export const MonitorEpisode: mongoose.Model<{
 }>, mongoose.Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
     timestamps: true;
 }, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -104,8 +104,8 @@ export const MonitorEpisode: mongoose.Model<{
     endedAt?: NativeDate;
     peakStatus?: string;
 } & mongoose.DefaultTimestampProps, mongoose.Document<unknown, {}, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -117,8 +117,8 @@ export const MonitorEpisode: mongoose.Model<{
 }, Omit<mongoose.DefaultSchemaOptions, "timestamps"> & {
     timestamps: true;
 }> & Omit<{
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -132,8 +132,8 @@ export const MonitorEpisode: mongoose.Model<{
 }, "id"> & mongoose.HydratedDocumentOverrides<{
     id: string;
 }>, unknown, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;
@@ -147,8 +147,8 @@ export const MonitorEpisode: mongoose.Model<{
 } & {
     __v: number;
 }>, {
-    user: mongoose.Types.ObjectId;
     monitor: mongoose.Types.ObjectId;
+    user: mongoose.Types.ObjectId;
     open: boolean;
     startedAt: NativeDate;
     alertCount: number;

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

@@ -1 +1 @@
-{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AA2CA,8BAiFE;AA8BF,wBAAmD;AAlJnD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DAsBC"}
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AAkFA,8BA6GE;AAiCF,wBAAmD;AAvNnD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DAsBC"}

package/dist/utils/subscribedDevices.d.ts

@@ -0,0 +1,3 @@
+export function projectSubscribedMonitors(subscribedDevices: any, { resolveSiteMonitorIds }?: {}): Promise<any>;
+export function hasAqiCapableSubscription(subscribedDevices: any): any;
+//# sourceMappingURL=subscribedDevices.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscribedDevices.d.ts","sourceRoot":"","sources":["../../src/utils/subscribedDevices.js"],"names":[],"mappings":"AAyIO,gHAoBN;AAOM,uEAGuD"}

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

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

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

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

package/package.json

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

package/src/constants/deviceTypes.js

@@ -0,0 +1,44 @@
+// V2 device-type vocabulary — single source of truth (JA-3110 / JA-3335).
+//
+// Every device a user can see or subscribe to is exactly one of three things,
+// each backed by a different collection:
+//   monitor       — a standalone Monitors doc (siteId: null). Reports live AQI.
+//   sample-site   — a standalone SampleSites doc (siteId: null). Lab/filter
+//                   sample data only, no live AQI, so it can never trigger an
+//                   AQI alert.
+//   linked-device — a Sites doc joining one or more Monitors and/or one
+//                   SampleSite at a single physical location. Reports live AQI
+//                   when it links at least one monitor.
+//
+// Consumers: JustAirService fetchDevices/getDeviceById stamp these strings onto
+// every device response; JustAirUserService validates the subscribe body
+// against them and persists them in Users.subscribedDevices; JustAir-Client
+// passes back verbatim the value it received. Keep the string values
+// byte-identical to what the devices API emits — the FE does no mapping, and a
+// casing drift here is a silent 404 on subscribe.
+//
+// DO NOT rename these values: they are persisted in Users.subscribedDevices.
+
+// Frozen because every importer in a process gets this same instance — one
+// consumer reassigning a key, or calling .push()/.sort() on the values array,
+// would silently change the vocabulary (and the Users.subscribedDevices enum
+// derived from it) for every other consumer in that process. Matches
+// DATA_DOWNLOAD_TYPES in dataDownloads.js.
+export const DEVICE_TYPES = Object.freeze({
+  MONITOR: "monitor",
+  SAMPLE_SITE: "sample-site",
+  LINKED_DEVICE: "linked-device",
+});
+
+export const DEVICE_TYPE_VALUES = Object.freeze(Object.values(DEVICE_TYPES));
+
+// Whether a device of this type can ever report AQI, and therefore whether a
+// subscription to it can contribute to AQI alert delivery.
+//
+// Note the asymmetry: `sample-site` is unconditionally false, but a true result
+// for `linked-device` is necessary and NOT sufficient — a Site is only actually
+// AQI-capable when it links at least one monitor, which the type alone cannot
+// tell you. Callers must still check the Site's monitorIds.
+export const isAqiCapableDeviceType = (deviceType) =>
+  deviceType === DEVICE_TYPES.MONITOR ||
+  deviceType === DEVICE_TYPES.LINKED_DEVICE;

package/src/constants/index.js

@@ -10,5 +10,6 @@
 export * from "./pollutants.js";
 export * from "./alertLevels.js";
 export * from "./userNotifications.js";
+export * from "./deviceTypes.js";
 export * from "./timezones.js";
 export * from "./dataDownloads.js";

package/src/constants/tests/deviceTypes.test.js

@@ -0,0 +1,53 @@
+// Pins the device-type vocabulary shared across JustAirService (which stamps
+// deviceType onto every device response), JustAirUserService (which validates
+// the subscribe body and persists it), and JustAir-Client (which passes it
+// back verbatim). A casing drift in any value is a silent subscribe failure,
+// so the exact strings are asserted rather than derived.
+import * as barrel from '../index.js';
+import {
+  DEVICE_TYPES,
+  DEVICE_TYPE_VALUES,
+  isAqiCapableDeviceType,
+} from '../deviceTypes.js';
+
+test('barrel exports the device-type constants', () => {
+  expect(barrel.DEVICE_TYPES).toBe(DEVICE_TYPES);
+  expect(barrel.DEVICE_TYPE_VALUES).toBe(DEVICE_TYPE_VALUES);
+  expect(barrel.isAqiCapableDeviceType).toBe(isAqiCapableDeviceType);
+});
+
+test('DEVICE_TYPES values match the strings the devices API emits', () => {
+  expect(DEVICE_TYPES).toEqual({
+    MONITOR: 'monitor',
+    SAMPLE_SITE: 'sample-site',
+    LINKED_DEVICE: 'linked-device',
+  });
+});
+
+test('DEVICE_TYPE_VALUES covers every type exactly once', () => {
+  expect(DEVICE_TYPE_VALUES).toEqual(['monitor', 'sample-site', 'linked-device']);
+  expect(new Set(DEVICE_TYPE_VALUES).size).toBe(DEVICE_TYPE_VALUES.length);
+});
+
+test('the vocabulary is frozen so no consumer can mutate it for the others', () => {
+  expect(Object.isFrozen(DEVICE_TYPES)).toBe(true);
+  expect(Object.isFrozen(DEVICE_TYPE_VALUES)).toBe(true);
+});
+
+describe('isAqiCapableDeviceType', () => {
+  test('monitor and linked-device can report AQI', () => {
+    expect(isAqiCapableDeviceType('monitor')).toBe(true);
+    expect(isAqiCapableDeviceType('linked-device')).toBe(true);
+  });
+
+  test('sample-site never reports AQI, so it never alerts', () => {
+    expect(isAqiCapableDeviceType('sample-site')).toBe(false);
+  });
+
+  test('unknown and missing types are not AQI-capable', () => {
+    expect(isAqiCapableDeviceType('sampleSite')).toBe(false);
+    expect(isAqiCapableDeviceType(undefined)).toBe(false);
+    expect(isAqiCapableDeviceType(null)).toBe(false);
+    expect(isAqiCapableDeviceType('')).toBe(false);
+  });
+});

package/src/index.js

@@ -69,6 +69,11 @@ import { PARAMETERS, HEAVY_METALS } from "./constants/pollutants.js";
 import { ALERT_LEVEL_WEIGHTS, getAlertWeight } from "./constants/alertLevels.js";
 import { DEFAULT_TIMEZONE } from "./constants/timezones.js";
 import { DATA_DOWNLOAD_TYPES } from "./constants/dataDownloads.js";
+import {
+  DEVICE_TYPES,
+  DEVICE_TYPE_VALUES,
+  isAqiCapableDeviceType,
+} from "./constants/deviceTypes.js";
 import {
   monitorEpisodesSchema,
   MonitorEpisode,
@@ -95,6 +100,7 @@ import {
   resolveQuietHours,
 } from "./utils/quietHours.js";
 import { isValidIANATimezone } from "./utils/timezone.js";
+import { projectSubscribedMonitors } from "./utils/subscribedDevices.js";
 
 // Sites related imports
 import { sitesSchema, Sites } from "./models/sites.js";
@@ -259,6 +265,18 @@ export {
   // AQI alert-level hierarchy (single source of truth)
   ALERT_LEVEL_WEIGHTS,
   getAlertWeight,
+  // V2 device-type vocabulary (single source of truth) — JA-3110 / JA-3335
+  DEVICE_TYPES,
+  DEVICE_TYPE_VALUES,
+  isAqiCapableDeviceType,
+  // 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.
+  projectSubscribedMonitors,
   // Utilities
   splitName,
   // Quiet hours (JA-3054): shared validation + window evaluation

package/src/models/users.js

@@ -5,6 +5,7 @@ import {
   validateQuietHours,
   QUIET_HOURS_ERRORS,
 } from "../utils/quietHours.js";
+import { DEVICE_TYPE_VALUES } from "../constants/deviceTypes.js";
 
 const COOKIE_CONSENT_CATEGORIES = ["analytics_performance"];
 const COOKIE_CONSENT_VALUES = ["accept", "reject"];
@@ -41,6 +42,44 @@ const validateCookieConsent = (consent) => {
   return null;
 };
 
+// One entry in Users.subscribedDevices (JA-3110 / JA-3335). deviceId points
+// into a different collection per deviceType (Monitors / SampleSites / Sites),
+// so there is deliberately no `ref` to declare here.
+//
+// `_id: false` is load-bearing, not cosmetic: it makes the pair itself the
+// identity of an element, so `$addToSet` dedupes and re-subscribing is
+// idempotent. With per-subdocument _ids every push would cast to a brand-new
+// object, `$addToSet` would never match, and the array would accumulate a
+// duplicate on every click of the subscribe button.
+//
+// Note what that dedupe is keyed on: the whole PAIR, not the deviceId. One id
+// stored once as `monitor` and once as `linked-device` is two distinct entries
+// and both survive. A given deviceId must therefore never carry two types —
+// projectSubscribedMonitors would read the `monitor` row as a monitor id and
+// write a Site id into subscribedMonitors, which is precisely the polymorphic
+// id the subscribedMonitors/subscribedDevices split exists to keep out, and it
+// fails silently (the notification service just filters it away). Consumers on
+// the subscribe path should `$pull { deviceId }` before `$addToSet` so a
+// re-subscribe with a corrected type replaces the row instead of adding one.
+const subscribedDeviceSchema = mongoose.Schema(
+  {
+    deviceId: { type: mongoose.Types.ObjectId, required: true },
+    // `enum` and `required` are document validators: they run on
+    // create()/save(), NOT on the `$addToSet` query update the subscribe
+    // path uses — `runValidators` defaults to false there. So an
+    // updateOne can persist `sampleSite`, `Monitor`, or any other string
+    // with no error.
+    //
+    // This fails silently and loudly nowhere: a bad-cased value makes
+    // isAqiCapableDeviceType() return false, so a user who subscribed to a
+    // monitor just never receives AQI alerts. Consumers on the subscribe
+    // path MUST check the request body against DEVICE_TYPE_VALUES before
+    // writing (and/or pass `{ runValidators: true }` to the update).
+    deviceType: { type: String, enum: DEVICE_TYPE_VALUES, required: true },
+  },
+  { _id: false }
+);
+
 const usersSchema = mongoose.Schema(
   {
     name: String,
@@ -54,6 +93,34 @@ const usersSchema = mongoose.Schema(
     alertPhone: String,
     alertCount: { type: Number, default: 0 },
     subscribedMonitors: [{ type: mongoose.Types.ObjectId, ref: "Monitors" }],
+    // 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. A subscribed
+    // linked-device contributes the monitorIds of its Site to it; a subscribed
+    // sample-site contributes nothing, having no live AQI. The two must be
+    // written together on every subscribe/unsubscribe path.
+    //
+    // 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.
+    subscribedDevices: [subscribedDeviceSchema],
     currentAlertMode: {
       type: String,
       enum: [
@@ -151,6 +218,9 @@ usersSchema.pre("validate", function () {
 });
 
 usersSchema.index({ phone: 1 });
+// Supports the "is this user subscribed to device X?" lookup behind the V2
+// device-card subscribed state and the My Monitors map filter.
+usersSchema.index({ "subscribedDevices.deviceId": 1 });
 
 const Users = mongoose.model("Users", usersSchema);
 

package/src/utils/subscribedDevices.js

@@ -0,0 +1,168 @@
+// Subscribed devices (JA-3110 / JA-3335): the shared projection from
+// Users.subscribedDevices (source of truth, all three device types) to
+// Users.subscribedMonitors (monitor ids only, the AQI-alert audience).
+//
+// Single source of truth for every consumer that writes a subscription —
+// JustAirUserService recomputes on subscribe/unsubscribe, and any backfill or
+// repair script uses the same function. Pure: no DB, no logger, no clock. The
+// one thing it cannot know on its own is which monitors a Site links, so that
+// lookup is injected as `resolveSiteMonitorIds`.
+//
+// The rule, per JA-3110 AC "user will receive AQI notifications if the site
+// has an AQI":
+//
+//   monitor        → contributes its own deviceId
+//   linked-device  → contributes the monitorIds of its Site (none if the Site
+//                    links only a SampleSite, which is the sample-only case
+//                    JA-3110 adds)
+//   sample-site    → contributes nothing; no live AQI, so it can never trigger
+//                    an AQI alert
+//
+// Recompute-whole, not delta: callers pass the complete post-change
+// subscribedDevices array and overwrite subscribedMonitors with the result.
+// That makes unsubscribe fall out for free — a Site's monitors disappear from
+// the projection only when no other subscribed device still contributes them —
+// and makes the function idempotent, so a repair run over existing users is
+// safe to repeat.
+//
+// ---------------------------------------------------------------------------
+// PRECONDITION — do not overwrite subscribedMonitors before the backfill
+// ---------------------------------------------------------------------------
+// Every user who existed before this field shipped has a populated
+// subscribedMonitors and an empty or absent subscribedDevices (pinned by the
+// "reads pre-backfill users cleanly" case in models/tests/users.test.js). For
+// such a user this function correctly returns a projection of *nothing they
+// have migrated yet* — so a consumer that overwrites subscribedMonitors with
+// it on the user's next subscribe silently drops every monitor they were
+// already subscribed to, and their AQI alerts stop with no error anywhere.
+//
+// Callers MUST therefore do one of these, per user, and the ordering is not
+// optional:
+//   1. Backfill subscribedDevices from subscribedMonitors first (one
+//      { 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 module deliberately does NOT offer a `union: true` flag. A blanket
+// union is correct for subscribe and silently wrong for unsubscribe — it would
+// make removal a no-op — so the choice belongs at the call site, which knows
+// which operation it is performing. The backfill itself is consumer-side
+// (JustAirUserService owns the write path) and is not shipped in this library;
+// it needs its own ticket under JA-3110 before any consumer moves to
+// overwrite-always.
+//
+// ---------------------------------------------------------------------------
+// STALENESS — this is a write-path projection only
+// ---------------------------------------------------------------------------
+// The result is only as current as the last time a caller ran it. Nothing here
+// watches Sites: if a Site gains or loses a monitor after a user subscribed to
+// it, that user's subscribedMonitors stays as it was and their AQI audience is
+// wrong — a monitor added to a Site never alerts its existing subscribers, and
+// a removed one keeps alerting them, in both cases silently. Any code that
+// mutates Sites.monitorIds is therefore responsible for reprojecting the
+// 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";
+
+// Dedupe by string form, keep the caller's ObjectId instances. Two equal
+// ObjectIds are different object identities, so Set/includes on the raw values
+// would let a monitor through twice — once from a direct `monitor`
+// subscription and again from a Site that links it.
+//
+// Nullish ids are dropped rather than deduped. `Sites.monitorIds` is declared
+// `default: undefined` (models/sites.js), so a sample-only Site has no array at
+// all and the documented resolver shape can hand back `[undefined]`. Without
+// this guard `String(undefined)` becomes the key "undefined" and a null lands
+// in subscribedMonitors — exactly the polymorphic junk the field split exists
+// to keep out.
+const dedupeById = (ids) => {
+  const seen = new Set();
+  return ids.filter((id) => {
+    if (id === null || id === undefined) {
+      return false;
+    }
+    const key = String(id);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+};
+
+const isPlainObject = (value) =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+// Both selectors match on an exact DEVICE_TYPES value, so an entry whose
+// deviceType is outside the vocabulary contributes nothing. That is deliberate
+// rather than an error: `$addToSet` skips document validators (see the comment
+// on subscribedDeviceSchema in models/users.js), so a mis-cased `Monitor` can
+// already be persisted. Projecting it as "no AQI" keeps this function total,
+// and matches isAqiCapableDeviceType's answer for the same value.
+const directMonitorIds = (entries) =>
+  entries
+    .filter((entry) => entry.deviceType === DEVICE_TYPES.MONITOR)
+    .map((entry) => entry.deviceId);
+
+const linkedSiteIds = (entries) =>
+  entries
+    .filter((entry) => entry.deviceType === DEVICE_TYPES.LINKED_DEVICE)
+    .map((entry) => entry.deviceId);
+
+// 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
+// occurrence wins — but carries no meaning; treat the result as a set.
+//
+// `subscribedDevices` tolerates undefined/null: a user row written before this
+// field existed has no key at all on a `.lean()` read (pinned in
+// models/tests/users.test.js), and a projection over "no subscriptions" is an
+// empty audience, not a crash.
+//
+// `resolveSiteMonitorIds(siteIds)` is called at most once, with every
+// linked-device id at a time, and must resolve to the flat union of those
+// Sites' monitorIds (`Sites.find({ _id: { $in: siteIds } }, "monitorIds")`).
+// 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
+// nullish entries — Sites.monitorIds is `default: undefined`, so a sample-only
+// Site has no array — and they are filtered out here rather than trusted to
+// the caller.
+//
+// Read the PRECONDITION and STALENESS notes at the top of this file before
+// writing the result to Users.subscribedMonitors.
+export const projectSubscribedMonitors = async (
+  subscribedDevices,
+  { resolveSiteMonitorIds } = {}
+) => {
+  const entries = (subscribedDevices ?? []).filter(isPlainObject);
+  const direct = directMonitorIds(entries);
+  const siteIds = dedupeById(linkedSiteIds(entries));
+
+  if (siteIds.length === 0) {
+    return dedupeById(direct);
+  }
+
+  if (typeof resolveSiteMonitorIds !== "function") {
+    throw new TypeError(
+      "projectSubscribedMonitors requires resolveSiteMonitorIds when a linked-device is subscribed"
+    );
+  }
+
+  const siteMonitorIds = (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

@@ -0,0 +1,306 @@
+import mongoose from 'mongoose';
+import {
+  projectSubscribedMonitors,
+  hasAqiCapableSubscription,
+} from '../subscribedDevices.js';
+
+const oid = () => new mongoose.Types.ObjectId();
+
+// A resolver that records what it was asked for, so the tests can assert the
+// call shape (one batched call, or none at all) and not just the result.
+const recordingResolver = (byId) => {
+  const calls = [];
+  const resolve = async (siteIds) => {
+    calls.push(siteIds);
+    return siteIds.flatMap((id) => byId[String(id)] ?? []);
+  };
+  return { resolve, calls };
+};
+
+describe('projectSubscribedMonitors', () => {
+  test('a monitor subscription contributes its own id', async () => {
+    const monitorId = oid();
+
+    const result = await projectSubscribedMonitors([
+      { deviceId: monitorId, deviceType: 'monitor' },
+    ]);
+
+    expect(result).toEqual([monitorId]);
+  });
+
+  test('a sample-site subscription contributes nothing', async () => {
+    // The JA-3110 "Site with Sample" case: subscribable, never AQI-alerting.
+    const result = await projectSubscribedMonitors([
+      { deviceId: oid(), deviceType: 'sample-site' },
+    ]);
+
+    expect(result).toEqual([]);
+  });
+
+  test('a linked-device contributes the monitorIds of its Site', async () => {
+    const siteId = oid();
+    const [m1, m2] = [oid(), oid()];
+    const { resolve, calls } = recordingResolver({ [siteId]: [m1, m2] });
+
+    const result = await projectSubscribedMonitors(
+      [{ deviceId: siteId, deviceType: 'linked-device' }],
+      { resolveSiteMonitorIds: resolve },
+    );
+
+    expect(result).toEqual([m1, m2]);
+    expect(calls).toEqual([[siteId]]);
+  });
+
+  test('a linked-device whose Site links no monitor contributes nothing', async () => {
+    // Sample-only Site — the new JA-3110 case reached through a Site rather
+    // than a standalone SampleSite. Subscribing must not add an AQI audience.
+    const siteId = oid();
+    const { resolve } = recordingResolver({});
+
+    const result = await projectSubscribedMonitors(
+      [{ deviceId: siteId, deviceType: 'linked-device' }],
+      { resolveSiteMonitorIds: resolve },
+    );
+
+    expect(result).toEqual([]);
+  });
+
+  test('resolves every linked-device in one batched call', async () => {
+    const [siteA, siteB] = [oid(), oid()];
+    const [m1, m2] = [oid(), oid()];
+    const { resolve, calls } = recordingResolver({
+      [siteA]: [m1],
+      [siteB]: [m2],
+    });
+
+    const result = await projectSubscribedMonitors(
+      [
+        { deviceId: siteA, deviceType: 'linked-device' },
+        { deviceId: siteB, deviceType: 'linked-device' },
+      ],
+      { resolveSiteMonitorIds: resolve },
+    );
+
+    expect(result).toEqual([m1, m2]);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toEqual([siteA, siteB]);
+  });
+
+  test('does not call the resolver when no linked-device is subscribed', async () => {
+    const { resolve, calls } = recordingResolver({});
+
+    await projectSubscribedMonitors(
+      [
+        { deviceId: oid(), deviceType: 'monitor' },
+        { deviceId: oid(), deviceType: 'sample-site' },
+      ],
+      { resolveSiteMonitorIds: resolve },
+    );
+
+    expect(calls).toEqual([]);
+  });
+
+  test('omits the resolver entirely when nothing needs it', async () => {
+    const monitorId = oid();
+
+    await expect(
+      projectSubscribedMonitors([{ deviceId: monitorId, deviceType: 'monitor' }]),
+    ).resolves.toEqual([monitorId]);
+  });
+
+  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.
+    await expect(
+      projectSubscribedMonitors([{ deviceId: oid(), deviceType: 'linked-device' }]),
+    ).rejects.toThrow(/resolveSiteMonitorIds/);
+  });
+
+  test('dedupes a monitor reached both directly and through a Site', async () => {
+    const monitorId = oid();
+    const siteId = oid();
+    const { resolve } = recordingResolver({ [siteId]: [monitorId] });
+
+    const result = await projectSubscribedMonitors(
+      [
+        { deviceId: monitorId, deviceType: 'monitor' },
+        { deviceId: siteId, deviceType: 'linked-device' },
+      ],
+      { resolveSiteMonitorIds: resolve },
+    );
+
+    // Equal ObjectIds are distinct object identities, so this is the case a
+    // plain Set over the raw values would miss.
+    expect(result).toEqual([monitorId]);
+  });
+
+  test('dedupes repeated site ids before resolving them', async () => {
+    const siteId = oid();
+    const monitorId = oid();
+    const { resolve, calls } = recordingResolver({ [siteId]: [monitorId] });
+
+    const result = await projectSubscribedMonitors(
+      [
+        { deviceId: siteId, deviceType: 'linked-device' },
+        { deviceId: siteId, deviceType: 'linked-device' },
+      ],
+      { resolveSiteMonitorIds: resolve },
+    );
+
+    expect(calls[0]).toEqual([siteId]);
+    expect(result).toEqual([monitorId]);
+  });
+
+  test('drops nullish ids a resolver hands back for a sample-only Site', async () => {
+    // Sites.monitorIds is `default: undefined` (models/sites.js), so the
+    // documented resolver shape (Sites.find(..., 'monitorIds') + flatMap)
+    // returns [undefined] for a sample-only Site. Left in, that writes a null
+    // into subscribedMonitors — the polymorphic junk the field split prevents.
+    const siteId = new mongoose.Types.ObjectId();
+    const monitorId = new mongoose.Types.ObjectId();
+
+    const result = await projectSubscribedMonitors(
+      [{ deviceId: siteId, deviceType: 'linked-device' }],
+      { resolveSiteMonitorIds: async () => [undefined, monitorId, null] },
+    );
+
+    expect(result).toEqual([monitorId]);
+  });
+
+  test('returns an empty audience when every resolved id is nullish', async () => {
+    const result = await projectSubscribedMonitors(
+      [{ deviceId: new mongoose.Types.ObjectId(), deviceType: 'linked-device' }],
+      { resolveSiteMonitorIds: async () => [undefined, null] },
+    );
+
+    expect(result).toEqual([]);
+    // Not [null] and not ['undefined'] — nothing at all reaches the caller.
+    expect(result).toHaveLength(0);
+  });
+
+  test('a nullish deviceId on a monitor entry never reaches the projection', async () => {
+    const monitorId = new mongoose.Types.ObjectId();
+
+    const result = await projectSubscribedMonitors([
+      { deviceId: undefined, deviceType: 'monitor' },
+      { deviceId: monitorId, deviceType: 'monitor' },
+    ]);
+
+    expect(result).toEqual([monitorId]);
+  });
+
+  test('ignores an entry whose deviceType is outside the vocabulary', async () => {
+    // Reachable in production: $addToSet skips document validators, so a
+    // mis-cased 'Monitor' can already be stored. Project it as no-AQI, the
+    // same answer isAqiCapableDeviceType gives.
+    const result = await projectSubscribedMonitors([
+      { deviceId: oid(), deviceType: 'Monitor' },
+      { deviceId: oid(), deviceType: 'sampleSite' },
+    ]);
+
+    expect(result).toEqual([]);
+  });
+
+  test('treats a missing or empty subscribedDevices as an empty audience', async () => {
+    // A user row written before the field existed has no key at all on a
+    // .lean() read (pinned in models/tests/users.test.js).
+    await expect(projectSubscribedMonitors(undefined)).resolves.toEqual([]);
+    await expect(projectSubscribedMonitors(null)).resolves.toEqual([]);
+    await expect(projectSubscribedMonitors([])).resolves.toEqual([]);
+  });
+
+  test('does not mutate the array it is given', async () => {
+    const entries = [
+      { deviceId: oid(), deviceType: 'monitor' },
+      { deviceId: oid(), deviceType: 'sample-site' },
+    ];
+    const snapshot = [...entries];
+
+    await projectSubscribedMonitors(entries);
+
+    expect(entries).toEqual(snapshot);
+  });
+
+  test('is idempotent — reprojecting the same input gives the same output', async () => {
+    const siteId = oid();
+    const monitorId = oid();
+    const { resolve } = recordingResolver({ [siteId]: [monitorId] });
+    const entries = [
+      { deviceId: monitorId, deviceType: 'monitor' },
+      { deviceId: siteId, deviceType: 'linked-device' },
+    ];
+
+    const first = await projectSubscribedMonitors(entries, {
+      resolveSiteMonitorIds: resolve,
+    });
+    const second = await projectSubscribedMonitors(entries, {
+      resolveSiteMonitorIds: resolve,
+    });
+
+    expect(second).toEqual(first);
+  });
+
+  test('unsubscribing a Site drops only the monitors nothing else contributes', async () => {
+    // The recompute-whole contract: the caller removes the entry and
+    // reprojects, rather than diffing monitor ids by hand.
+    const [siteA, siteB] = [oid(), oid()];
+    const [shared, onlyA] = [oid(), oid()];
+    const { resolve } = recordingResolver({
+      [siteA]: [shared, onlyA],
+      [siteB]: [shared],
+    });
+
+    const subscribed = [
+      { deviceId: siteA, deviceType: 'linked-device' },
+      { deviceId: siteB, deviceType: 'linked-device' },
+    ];
+    const before = await projectSubscribedMonitors(subscribed, {
+      resolveSiteMonitorIds: resolve,
+    });
+    expect(before).toEqual([shared, onlyA]);
+
+    const after = await projectSubscribedMonitors(
+      subscribed.filter((entry) => String(entry.deviceId) !== String(siteA)),
+      { resolveSiteMonitorIds: resolve },
+    );
+
+    expect(after).toEqual([shared]);
+  });
+});
+
+// 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();
+  });
+});
+
+describe('hasAqiCapableSubscription', () => {
+  test('false when only sample-sites are subscribed', () => {
+    expect(
+      hasAqiCapableSubscription([{ deviceId: oid(), deviceType: 'sample-site' }]),
+    ).toBe(false);
+  });
+
+  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);
+  });
+
+  test('false for a missing, empty, or unrecognised array', () => {
+    expect(hasAqiCapableSubscription(undefined)).toBe(false);
+    expect(hasAqiCapableSubscription([])).toBe(false);
+    expect(hasAqiCapableSubscription([{ deviceType: 'Monitor' }])).toBe(false);
+  });
+});