@justair/justair-library 7.1.0 → 7.2.0-alpha.4a114f2

package/dist/constants/index.d.ts

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

package/dist/constants/timezones.d.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_TIMEZONE: "America/New_York";
+//# sourceMappingURL=timezones.d.ts.map

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

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

package/dist/index.d.ts

@@ -86,19 +86,25 @@ import { AccountNotification } from "./models/userNotifications.js";
 import { NOTIFICATION_KINDS } from "./models/userNotifications.js";
 import { NOTIFICATION_CHANNELS } from "./models/userNotifications.js";
 import { DELIVERY_STATUSES } from "./models/userNotifications.js";
+import { dataDownloadSchema } from "./models/dataDownloads.js";
+import { DataDownloads } from "./models/dataDownloads.js";
+import { AqiDataDownload } from "./models/dataDownloads.js";
+import { SampleDataDownload } from "./models/dataDownloads.js";
+import { MAX_RANGE_DAYS as DATA_DOWNLOAD_MAX_RANGE_DAYS } from "./utils/dataDownloadRange.js";
+import { DATA_DOWNLOAD_ERRORS } from "./utils/dataDownloadRange.js";
 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 { splitName } from "./utils/splitName.js";
 import { DEFAULT_QUIET_HOURS } from "./utils/quietHours.js";
-import { DEFAULT_TIMEZONE } from "./utils/quietHours.js";
+import { DEFAULT_TIMEZONE } from "./constants/timezones.js";
 import { QUIET_HOURS_ERRORS } from "./utils/quietHours.js";
 import { isValidTimeString } from "./utils/quietHours.js";
-import { isValidIANATimezone } from "./utils/quietHours.js";
+import { isValidIANATimezone } from "./utils/timezone.js";
 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, 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, dataDownloadSchema, DataDownloads, AqiDataDownload, SampleDataDownload, DATA_DOWNLOAD_MAX_RANGE_DAYS, DATA_DOWNLOAD_ERRORS, PARAMETERS, HEAVY_METALS, ALERT_LEVEL_WEIGHTS, getAlertWeight, 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":"AAuHA;;;iBAEC;yBAvDwB,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;4BAkCT,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;2BAhBG,2BAA2B;6BAA3B,2BAA2B;oCAChB,4BAA4B;+BAA5B,4BAA4B;0BAgBtD,sBAAsB;oCAWzC,uBAAuB;iCAAvB,uBAAuB;mCAAvB,uBAAuB;kCAAvB,uBAAuB;oCAAvB,uBAAuB;mCAAvB,uBAAuB;+BAAvB,uBAAuB;gCAAvB,uBAAuB;kCAAvB,uBAAuB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAoIA;;;iBAEC;yBApEwB,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;4BAkCT,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;mCAuC/B,2BAA2B;8BAA3B,2BAA2B;gCAA3B,2BAA2B;mCAA3B,2BAA2B;+DAO3B,8BAA8B;qCAA9B,8BAA8B;2BA/DI,2BAA2B;6BAA3B,2BAA2B;oCAChB,4BAA4B;+BAA5B,4BAA4B;0BAiBtD,sBAAsB;oCASzC,uBAAuB;iCAzBG,0BAA0B;mCAyBpD,uBAAuB;kCAAvB,uBAAuB;oCACM,qBAAqB;mCADlD,uBAAuB;+BAAvB,uBAAuB;gCAAvB,uBAAuB;kCAAvB,uBAAuB"}

package/dist/models/dataDownloads.d.ts

@@ -0,0 +1,5 @@
+export const dataDownloadSchema: any;
+export const DataDownloads: any;
+export const AqiDataDownload: any;
+export const SampleDataDownload: any;
+//# sourceMappingURL=dataDownloads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataDownloads.d.ts","sourceRoot":"","sources":["../../src/models/dataDownloads.js"],"names":[],"mappings":"AAsBA,qCA+CE;AAqDF,gCAA0E;AAM1E,kCAEG;AAEH,qCAIE"}

package/dist/models/tests/dataDownloads.test.d.ts

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

package/dist/models/tests/dataDownloads.test.d.ts.map

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

package/dist/utils/dataDownloadRange.d.ts

@@ -0,0 +1,20 @@
+export const MAX_RANGE_DAYS: 31;
+export const DATA_DOWNLOAD_ERRORS: Readonly<{
+    END_BEFORE_START: "end_before_start";
+    RANGE_TOO_LONG: "range_too_long";
+    INVALID_EMAIL: "invalid_email";
+}>;
+export function validateDateOrder({ start, end }?: {}): {
+    code: "end_before_start";
+    message: string;
+}[];
+export function validateMaxDateRange({ start, end }?: {}): {
+    code: "range_too_long";
+    message: string;
+}[];
+export function normalizeDownloadEmail(value: any): any;
+export function validateDownloadEmail({ email }?: {}): {
+    code: "invalid_email";
+    message: string;
+}[];
+//# sourceMappingURL=dataDownloadRange.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataDownloadRange.d.ts","sourceRoot":"","sources":["../../src/utils/dataDownloadRange.js"],"names":[],"mappings":"AASA,gCAAiC;AAUjC;;;;GAIG;AAmBI;;;IAcN;AAIM;;;IAcN;AAMM,wDAC0D;AAI1D;;;IAUN"}

package/dist/utils/quietHours.d.ts

@@ -2,14 +2,12 @@ export const DEFAULT_QUIET_HOURS: Readonly<{
     start: "22:00";
     end: "07:00";
 }>;
-export const DEFAULT_TIMEZONE: "America/New_York";
 export const QUIET_HOURS_ERRORS: Readonly<{
     HALF_PAIR: "half_pair";
     FORMAT: "format";
     EQUAL_PAIR: "equal_pair";
 }>;
 export function isValidTimeString(value: any): boolean;
-export function isValidIANATimezone(timeZone: any): boolean;
 export function validateQuietHours({ start, end }?: {}): {
     code: "half_pair";
     message: string;
@@ -30,4 +28,7 @@ export function resolveQuietHours(user: any): {
     timezone: string;
     warnings: string[];
 };
+import { DEFAULT_TIMEZONE } from "../constants/timezones.js";
+import { isValidIANATimezone } from "./timezone.js";
+export { DEFAULT_TIMEZONE, isValidIANATimezone };
 //# sourceMappingURL=quietHours.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"quietHours.d.ts","sourceRoot":"","sources":["../../src/utils/quietHours.js"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH,kDAAmD;AAKnD;;;;GAIG;AAuBI,uDACgD;AAEhD,4DAUN;AAOM;;;;;;;;;KAsCN;AASM,iEASN;AAKM,uEAaN;AAeM;;;;;;;EA6CN"}
+{"version":3,"file":"quietHours.d.ts","sourceRoot":"","sources":["../../src/utils/quietHours.js"],"names":[],"mappings":"AA0BA;;;GAGG;AAKH;;;;GAIG;AAII,uDACgD;AAOhD;;;;;;;;;KAsCN;AASM,iEASN;AAKM,uEAaN;AAeM;;;;;;;EA6CN;iCAtKgC,2BAA2B;oCACV,eAAe"}

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

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

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

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

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

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

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

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

package/dist/utils/timezone.d.ts

@@ -0,0 +1,3 @@
+export function getFormatter(timeZone: any): any;
+export function isValidIANATimezone(timeZone: any): boolean;
+//# sourceMappingURL=timezone.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../../src/utils/timezone.js"],"names":[],"mappings":"AAaO,iDAYN;AAEM,4DAUN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justair/justair-library",
-  "version": "7.1.0",
+  "version": "7.2.0-alpha.4a114f2",
   "description": "JustAir Internal Library",
   "main": "src/index.js",
   "type": "module",

package/src/constants/index.js

@@ -10,3 +10,4 @@
 export * from "./pollutants.js";
 export * from "./alertLevels.js";
 export * from "./userNotifications.js";
+export * from "./timezones.js";

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

@@ -6,6 +6,7 @@
 import * as barrel from '../index.js';
 import { PARAMETERS, HEAVY_METALS } from '../pollutants.js';
 import { ALERT_LEVEL_WEIGHTS, getAlertWeight } from '../alertLevels.js';
+import { DEFAULT_TIMEZONE } from '../timezones.js';
 
 test('barrel re-exports PARAMETERS and HEAVY_METALS unchanged (identity, not copies)', () => {
   expect(barrel.PARAMETERS).toBe(PARAMETERS);
@@ -44,3 +45,8 @@ test('unknown and legacy statuses fall back to the Good weight (never alert, nev
   expect(getAlertWeight(null)).toBe(1);
   expect(getAlertWeight('')).toBe(1);
 });
+
+test('barrel exports DEFAULT_TIMEZONE (browser-safe, no Mongoose)', () => {
+  expect(barrel.DEFAULT_TIMEZONE).toBe(DEFAULT_TIMEZONE);
+  expect(DEFAULT_TIMEZONE).toBe('America/New_York');
+});

package/src/constants/timezones.js

@@ -0,0 +1,6 @@
+// Mongoose-free timezone defaults, so a browser-safe consumer (e.g.
+// JustAir-Client) can use the same default other domains store server-side.
+// Originally lived in utils/quietHours.js (JA-3054); moved here once a
+// second, unrelated domain (dataDownloads.js, JA-3080) needed it too.
+
+export const DEFAULT_TIMEZONE = "America/New_York";

package/src/index.js

@@ -67,6 +67,7 @@ import Database from "./config/db.js"; // Import the new Database class
 import CustomLogger from "./config/logger.js";
 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 {
   monitorEpisodesSchema,
   MonitorEpisode,
@@ -85,15 +86,14 @@ import {
 import { splitName } from "./utils/splitName.js";
 import {
   DEFAULT_QUIET_HOURS,
-  DEFAULT_TIMEZONE,
   QUIET_HOURS_ERRORS,
   isValidTimeString,
-  isValidIANATimezone,
   validateQuietHours,
   getZoneMinutes,
   isInQuietWindow,
   resolveQuietHours,
 } from "./utils/quietHours.js";
+import { isValidIANATimezone } from "./utils/timezone.js";
 
 // Sites related imports
 import { sitesSchema, Sites } from "./models/sites.js";
@@ -116,6 +116,19 @@ import {
   sampleParameterReferenceConcentrations,
 } from "./models/samples.js";
 import { passwordResetTokenSchema, PasswordResetToken } from "./models/passwordResetToken.js";
+import {
+  dataDownloadSchema,
+  DataDownloads,
+  AqiDataDownload,
+  SampleDataDownload,
+} from "./models/dataDownloads.js";
+import {
+  // Renamed at the barrel only: the root export namespace is shared by every
+  // consuming service, so a bare MAX_RANGE_DAYS gives no hint it's specific to
+  // data downloads. Module-internal name is unchanged.
+  MAX_RANGE_DAYS as DATA_DOWNLOAD_MAX_RANGE_DAYS,
+  DATA_DOWNLOAD_ERRORS,
+} from "./utils/dataDownloadRange.js";
 
 export function createLoggerInstance({ DATADOG_API_KEY, APPLICATION_NAME }) {
   return new CustomLogger({ DATADOG_API_KEY, APPLICATION_NAME });
@@ -210,6 +223,13 @@ export {
   NOTIFICATION_KINDS,
   NOTIFICATION_CHANNELS,
   DELIVERY_STATUSES,
+  // Data downloads (JA-3080)
+  dataDownloadSchema,
+  DataDownloads,
+  AqiDataDownload,
+  SampleDataDownload,
+  DATA_DOWNLOAD_MAX_RANGE_DAYS,
+  DATA_DOWNLOAD_ERRORS,
   // Pollutant constants
   PARAMETERS,
   HEAVY_METALS,

package/src/models/dataDownloads.js

@@ -0,0 +1,139 @@
+import mongoose from "mongoose";
+import { DEFAULT_TIMEZONE } from "../constants/timezones.js";
+import { isValidIANATimezone } from "../utils/timezone.js";
+import {
+  DATA_DOWNLOAD_ERRORS,
+  validateDateOrder,
+  validateMaxDateRange,
+  validateDownloadEmail,
+  normalizeDownloadEmail,
+} from "../utils/dataDownloadRange.js";
+
+// DataDownloads — one doc per data download request (JA-3080). Written by
+// JustAirService on download (JA-3081); read by the org-level admin
+// communication screen. AQI downloads are monitor-scoped, Sample downloads
+// are site-scoped (samples.js keys samples to SampleSites, not Monitors) —
+// modeled as discriminators per CLAUDE.md's multi-kind pattern rather than
+// a flat schema with a monitorId/siteId pair that's nullable either way.
+//
+// The base model permits a kind-less document (create() without `dataType`)
+// — same property `userNotifications.js`'s base model has. Write through
+// AqiDataDownload/SampleDataDownload, not DataDownloads, so every stored
+// document has the ref field the admin screen needs to render it.
+const dataDownloadSchema = mongoose.Schema(
+  {
+    orgId: {
+      type: mongoose.Types.ObjectId,
+      ref: "Organizations",
+      required: [true, "orgId is required"],
+    },
+    dateRangeStart: { type: Date, required: [true, "dateRangeStart is required"] },
+    dateRangeEnd: { type: Date, required: [true, "dateRangeEnd is required"] },
+    // `default` only applies to `undefined`, not `null`, so an explicit
+    // `timezone: null` (the normal shape of "didn't pick one" in a JSON body)
+    // is coerced in a setter — setters run on query updates, the pre('validate')
+    // hook below does not.
+    //
+    // This guarantees less than "always valid": `runValidators` defaults to
+    // false on query updates, so an updateOne can still persist a bad zone.
+    // Readers feeding this to Intl.DateTimeFormat must still defend.
+    timezone: {
+      type: String,
+      default: DEFAULT_TIMEZONE,
+      set: (value) => (value === null ? DEFAULT_TIMEZONE : value),
+      validate: {
+        validator: isValidIANATimezone,
+        message: "timezone must be a valid IANA timezone identifier",
+      },
+    },
+    downloadedAt: { type: Date, required: true, default: Date.now },
+    // Per-field validator rather than a pre('validate') hook, so it still
+    // applies on updateOne()/findOneAndUpdate() with { runValidators: true }.
+    // `type` surfaces as ValidatorError.kind, keeping the stable-code contract.
+    email: {
+      type: String,
+      trim: true,
+      lowercase: true,
+      default: null,
+      set: normalizeDownloadEmail,
+      validate: {
+        validator: (value) => validateDownloadEmail({ email: value }).length === 0,
+        message: "email must be a valid email address",
+        type: DATA_DOWNLOAD_ERRORS.INVALID_EMAIL,
+      },
+    },
+  },
+  {
+    timestamps: true,
+    discriminatorKey: "dataType",
+  }
+);
+
+// Cross-field rule (quiet-hours shape, CLAUDE.md). Applies to every kind; the
+// 31-day cap is AQI-only and lives on AqiDataDownload below. Only genuinely
+// cross-field rules belong here — per-field rules stay on their fields, since
+// pre('validate') hooks don't run on query updates.
+//
+// Passes the error code as invalidate()'s `kind` so a caught ValidationError
+// can be classified via err.errors.<path>.kind, not by message wording.
+dataDownloadSchema.pre("validate", function () {
+  const rangeErrors = validateDateOrder({ start: this.dateRangeStart, end: this.dateRangeEnd });
+  for (const error of rangeErrors) {
+    this.invalidate("dateRangeEnd", error.message, this.dateRangeEnd, error.code);
+  }
+});
+
+// Org-level admin screen lists a given org's downloads, most recent first,
+// by the domain-meaningful "date of the download" (JA-3080), not createdAt.
+dataDownloadSchema.index({ orgId: 1, downloadedAt: -1 });
+
+const aqiDataDownloadSchema = new mongoose.Schema({
+  // Figma's download modal titles the AQI variant "Download Data for:
+  // {Site Name}". Resolve that label via monitorId -> Monitors.monitorCode,
+  // not a Monitors -> Sites.name join: Monitors.siteId is only populated by
+  // POST /devices's linked-device flow, so a Sites join renders blank for a
+  // meaningful share of monitors.
+  monitorId: {
+    type: mongoose.Types.ObjectId,
+    ref: "Monitors",
+    required: [true, "monitorId is required"],
+  },
+});
+aqiDataDownloadSchema.index({ monitorId: 1, downloadedAt: -1 });
+
+// AQI-only: the 31-day cap does not apply to Sample downloads. Mongoose
+// merges base + discriminator schema hooks by default (mergeHooks), so this
+// runs alongside (not instead of) the base's validateDateOrder check above.
+aqiDataDownloadSchema.pre("validate", function () {
+  const errors = validateMaxDateRange({ start: this.dateRangeStart, end: this.dateRangeEnd });
+  for (const error of errors) {
+    this.invalidate("dateRangeEnd", error.message, this.dateRangeEnd, error.code);
+  }
+});
+
+const sampleDataDownloadSchema = new mongoose.Schema({
+  siteId: {
+    type: mongoose.Types.ObjectId,
+    ref: "SampleSites",
+    required: [true, "siteId is required"],
+  },
+});
+sampleDataDownloadSchema.index({ siteId: 1, downloadedAt: -1 });
+
+const DataDownloads = mongoose.model("DataDownloads", dataDownloadSchema);
+
+// Registry names are namespaced (matches userNotifications.js): bare "AQI" /
+// "Sample" model-registry keys would collide with a consuming service's own
+// models of those names. { value } keeps the persisted dataType as JA-3245
+// specifies regardless of the registry name.
+const AqiDataDownload = DataDownloads.discriminator("AqiDataDownload", aqiDataDownloadSchema, {
+  value: "AQI",
+});
+
+const SampleDataDownload = DataDownloads.discriminator(
+  "SampleDataDownload",
+  sampleDataDownloadSchema,
+  { value: "Sample" }
+);
+
+export { dataDownloadSchema, DataDownloads, AqiDataDownload, SampleDataDownload };

package/src/utils/dataDownloadRange.js

@@ -0,0 +1,96 @@
+// Data download date range validation (JA-3080/JA-3245): shared cross-field
+// rules for the requested range on a DataDownloads document. Pure functions,
+// no DB, no clock reads. Same shape as quietHours.js's cross-field validator.
+//
+// Two separate rules, deliberately not one function: end-must-not-precede-
+// start applies to every download kind, but the 31-day cap is AQI-only.
+
+// Messaging only ("range cannot exceed 31 days"). validateMaxDateRange is the
+// sole authority on the enforced bound; don't rebuild the cap from this.
+export const MAX_RANGE_DAYS = 31;
+
+// DST slack: a calendar-accurate 31-day span crossing a fall-back transition
+// is 745 (not 744) hours long, so allow the extra hour rather than rejecting
+// a range the product spec promises as valid.
+const MAX_RANGE_MS = MAX_RANGE_DAYS * 24 * 60 * 60 * 1000 + 60 * 60 * 1000;
+
+// Stable error codes for validateDateOrder/validateMaxDateRange/
+// validateDownloadEmail. Consumers filter on `code` — never on message
+// wording, which is free to change.
+export const DATA_DOWNLOAD_ERRORS = Object.freeze({
+  END_BEFORE_START: "end_before_start",
+  RANGE_TOO_LONG: "range_too_long",
+  INVALID_EMAIL: "invalid_email",
+});
+
+// Coerces both ends through `new Date(...)`: a JSON request body hands these
+// raw strings, and comparing un-coerced strings silently produces NaN, so the
+// caps would never fire. Unparsable input returns null — format validation is
+// the schema layer's job, not a cross-field rule's.
+const toTimes = (start, end) => {
+  if (!start || !end) {
+    return null;
+  }
+  const startTime = new Date(start).getTime();
+  const endTime = new Date(end).getTime();
+  if (Number.isNaN(startTime) || Number.isNaN(endTime)) {
+    return null;
+  }
+  return { startTime, endTime };
+};
+
+// Returns { code, message }[]; empty = valid. Applies to every download kind.
+export const validateDateOrder = ({ start, end } = {}) => {
+  const times = toTimes(start, end);
+  if (!times) {
+    return [];
+  }
+  if (times.endTime < times.startTime) {
+    return [
+      {
+        code: DATA_DOWNLOAD_ERRORS.END_BEFORE_START,
+        message: "dateRangeEnd must not be before dateRangeStart",
+      },
+    ];
+  }
+  return [];
+};
+
+// Returns { code, message }[]; empty = valid. AQI only — Sample downloads have
+// no range limit. Assumes order was already checked by validateDateOrder.
+export const validateMaxDateRange = ({ start, end } = {}) => {
+  const times = toTimes(start, end);
+  if (!times || times.endTime < times.startTime) {
+    return [];
+  }
+  if (times.endTime - times.startTime > MAX_RANGE_MS) {
+    return [
+      {
+        code: DATA_DOWNLOAD_ERRORS.RANGE_TOO_LONG,
+        message: `date range cannot exceed ${MAX_RANGE_DAYS} days`,
+      },
+    ];
+  }
+  return [];
+};
+
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// Email is optional (JA-3080): a blank form field means "not sharing my email",
+// not "invalid email", so a blank string collapses to null.
+export const normalizeDownloadEmail = (value) =>
+  typeof value === "string" && value.trim() === "" ? null : value;
+
+// Returns { code, message }[]; empty = valid. null/undefined is valid — call
+// normalizeDownloadEmail first so a blank string arrives as null.
+export const validateDownloadEmail = ({ email } = {}) => {
+  if (email === null || email === undefined || EMAIL_PATTERN.test(email)) {
+    return [];
+  }
+  return [
+    {
+      code: DATA_DOWNLOAD_ERRORS.INVALID_EMAIL,
+      message: "email must be a valid email address",
+    },
+  ];
+};

package/src/utils/quietHours.js

@@ -16,13 +16,19 @@
 // Boundary rule: start is inclusive, end is exclusive — a 22:00–07:00 user
 // is suppressed at 22:00 sharp and receives alerts again at 07:00 sharp.
 
+import { DEFAULT_TIMEZONE } from "../constants/timezones.js";
+import { getFormatter, isValidIANATimezone } from "./timezone.js";
+
+// Re-exported for existing backend imports — canonical definitions now live
+// in src/constants/timezones.js (Mongoose-free, browser-safe) and
+// ./timezone.js (generic IANA checks, nothing quiet-hours-specific).
+export { DEFAULT_TIMEZONE, isValidIANATimezone };
+
 export const DEFAULT_QUIET_HOURS = Object.freeze({
   start: "22:00",
   end: "07:00",
 });
 
-export const DEFAULT_TIMEZONE = "America/New_York";
-
 // Stable error codes for validateQuietHours. Consumers filter on `code`
 // (e.g. the users schema pre-validate hook re-attaches only cross-field
 // errors) — never on message wording, which is free to change.
@@ -34,40 +40,9 @@ export const QUIET_HOURS_ERRORS = Object.freeze({
 
 const HHMM_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/;
 
-// Formatter construction is the expensive part of Intl (~ms); formatToParts
-// on a cached formatter is cheap. The cache also makes validation and
-// evaluation share one authority: a timezone is valid iff Intl accepts it.
-const formatterCache = new Map();
-
-const getFormatter = (timeZone) => {
-  let formatter = formatterCache.get(timeZone);
-  if (formatter === undefined) {
-    formatter = new Intl.DateTimeFormat("en-US", {
-      timeZone,
-      hourCycle: "h23",
-      hour: "2-digit",
-      minute: "2-digit",
-    });
-    formatterCache.set(timeZone, formatter);
-  }
-  return formatter;
-};
-
 export const isValidTimeString = (value) =>
   typeof value === "string" && HHMM_PATTERN.test(value);
 
-export const isValidIANATimezone = (timeZone) => {
-  if (typeof timeZone !== "string" || timeZone.trim() === "") {
-    return false;
-  }
-  try {
-    getFormatter(timeZone);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
 // Returns an array of { code, message } errors; empty array = valid. Codes
 // come from QUIET_HOURS_ERRORS and are the stable API — messages are
 // human-facing and may be reworded freely. Valid states are exactly two:

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

@@ -0,0 +1,133 @@
+import {
+  MAX_RANGE_DAYS,
+  DATA_DOWNLOAD_ERRORS,
+  validateDateOrder,
+  validateMaxDateRange,
+  validateDownloadEmail,
+  normalizeDownloadEmail,
+} from "../dataDownloadRange.js";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const start = new Date("2026-01-01T00:00:00.000Z");
+
+describe("validateDateOrder (applies to every download kind)", () => {
+  test("returns no errors when start/end are missing", () => {
+    expect(validateDateOrder({})).toEqual([]);
+    expect(validateDateOrder({ start })).toEqual([]);
+    expect(validateDateOrder({ end: start })).toEqual([]);
+  });
+
+  test("returns no errors for a valid order", () => {
+    const end = new Date(start.getTime() + DAY_MS);
+    expect(validateDateOrder({ start, end })).toEqual([]);
+  });
+
+  test("flags end before start with END_BEFORE_START", () => {
+    const end = new Date(start.getTime() - DAY_MS);
+    expect(validateDateOrder({ start, end })).toEqual([
+      expect.objectContaining({ code: DATA_DOWNLOAD_ERRORS.END_BEFORE_START }),
+    ]);
+  });
+
+  test("does not flag a range far longer than MAX_RANGE_DAYS — that's validateMaxDateRange's job", () => {
+    const end = new Date(start.getTime() + 365 * DAY_MS);
+    expect(validateDateOrder({ start, end })).toEqual([]);
+  });
+
+  // JA-3081's intake endpoint hands this raw JSON request-body strings, not
+  // Date instances — must not silently misjudge order via NaN-producing
+  // string arithmetic (see dataDownloadRange.js's toTimes coercion comment).
+  test("flags end before start given as raw date strings", () => {
+    expect(
+      validateDateOrder({ start: "2026-05-01", end: "2026-01-01" })
+    ).toEqual([expect.objectContaining({ code: DATA_DOWNLOAD_ERRORS.END_BEFORE_START })]);
+  });
+
+  test("returns no errors for an unparsable date value", () => {
+    expect(validateDateOrder({ start: "not-a-date", end: start })).toEqual([]);
+  });
+});
+
+describe("validateMaxDateRange (AQI only — Sample downloads have no cap)", () => {
+  test("returns no errors when start/end are missing", () => {
+    expect(validateMaxDateRange({})).toEqual([]);
+  });
+
+  test("accepts exactly MAX_RANGE_DAYS", () => {
+    const end = new Date(start.getTime() + MAX_RANGE_DAYS * DAY_MS);
+    expect(validateMaxDateRange({ start, end })).toEqual([]);
+  });
+
+  // The +1h grace exists so a calendar-accurate 31-day span crossing a DST
+  // fall-back transition (745 real hours, not 744) still validates — see
+  // dataDownloadRange.js's MAX_RANGE_MS comment.
+  test("accepts MAX_RANGE_DAYS plus the 1-hour DST grace", () => {
+    const end = new Date(start.getTime() + MAX_RANGE_DAYS * DAY_MS + HOUR_MS);
+    expect(validateMaxDateRange({ start, end })).toEqual([]);
+  });
+
+  test("flags a range longer than MAX_RANGE_DAYS plus the DST grace with RANGE_TOO_LONG", () => {
+    const end = new Date(start.getTime() + MAX_RANGE_DAYS * DAY_MS + HOUR_MS + 1);
+    expect(validateMaxDateRange({ start, end })).toEqual([
+      expect.objectContaining({ code: DATA_DOWNLOAD_ERRORS.RANGE_TOO_LONG }),
+    ]);
+  });
+
+  test("flags a too-long range given as raw date strings (JSON request-body shape)", () => {
+    expect(
+      validateMaxDateRange({ start: "2026-01-01", end: "2027-06-01" })
+    ).toEqual([expect.objectContaining({ code: DATA_DOWNLOAD_ERRORS.RANGE_TOO_LONG })]);
+  });
+
+  test("does not re-report a reversed range as RANGE_TOO_LONG — validateDateOrder owns that", () => {
+    const end = new Date(start.getTime() - DAY_MS);
+    expect(validateMaxDateRange({ start, end })).toEqual([]);
+  });
+
+  test("returns no errors for an unparsable date value", () => {
+    expect(validateMaxDateRange({ start: "not-a-date", end: start })).toEqual([]);
+  });
+});
+
+describe("normalizeDownloadEmail (blank means 'not shared', not invalid)", () => {
+  test("collapses an empty or whitespace-only string to null", () => {
+    expect(normalizeDownloadEmail("")).toBeNull();
+    expect(normalizeDownloadEmail("   ")).toBeNull();
+  });
+
+  test("passes through a non-blank string unchanged", () => {
+    expect(normalizeDownloadEmail("someone@example.com")).toBe("someone@example.com");
+  });
+
+  test("passes through non-string values unchanged — not this function's job to type-check", () => {
+    expect(normalizeDownloadEmail(null)).toBeNull();
+    expect(normalizeDownloadEmail(undefined)).toBeUndefined();
+  });
+});
+
+describe("validateDownloadEmail (email is optional — JA-3080)", () => {
+  test("returns no errors when email is null or undefined", () => {
+    expect(validateDownloadEmail({})).toEqual([]);
+    expect(validateDownloadEmail({ email: null })).toEqual([]);
+    expect(validateDownloadEmail({ email: undefined })).toEqual([]);
+  });
+
+  test("returns no errors for a well-formed email", () => {
+    expect(validateDownloadEmail({ email: "someone@example.com" })).toEqual([]);
+  });
+
+  test("flags a malformed email with INVALID_EMAIL", () => {
+    expect(validateDownloadEmail({ email: "not an email" })).toEqual([
+      expect.objectContaining({ code: DATA_DOWNLOAD_ERRORS.INVALID_EMAIL }),
+    ]);
+  });
+
+  // Caller is expected to run normalizeDownloadEmail first — an un-normalized
+  // blank string is not the same as null and should still fail the pattern.
+  test("flags a blank string that hasn't been normalized to null yet", () => {
+    expect(validateDownloadEmail({ email: "   " })).toEqual([
+      expect.objectContaining({ code: DATA_DOWNLOAD_ERRORS.INVALID_EMAIL }),
+    ]);
+  });
+});

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

@@ -0,0 +1,45 @@
+import { getFormatter, isValidIANATimezone } from '../timezone.js';
+
+describe('isValidIANATimezone', () => {
+  test.each([
+    'America/New_York',
+    'America/Detroit',
+    'America/Los_Angeles',
+    'UTC',
+    'Asia/Tokyo',
+  ])('accepts %s', (tz) => {
+    expect(isValidIANATimezone(tz)).toBe(true);
+  });
+
+  test.each([
+    'America/Fake_City',
+    'Not/A_Zone',
+    'EST GMT',
+    '',
+    '   ',
+  ])('rejects %p', (tz) => {
+    expect(isValidIANATimezone(tz)).toBe(false);
+  });
+
+  test.each([null, undefined, 5, {}])('rejects non-string %p', (tz) => {
+    expect(isValidIANATimezone(tz)).toBe(false);
+  });
+});
+
+describe('getFormatter', () => {
+  test('returns a formatter that renders wall-clock time in the given zone', () => {
+    const formatter = getFormatter('UTC');
+    const parts = formatter.formatToParts(new Date('2026-01-01T13:45:00.000Z'));
+    const hour = parts.find((p) => p.type === 'hour').value;
+    const minute = parts.find((p) => p.type === 'minute').value;
+    expect(`${hour}:${minute}`).toBe('13:45');
+  });
+
+  test('caches the formatter instance per timezone', () => {
+    expect(getFormatter('America/New_York')).toBe(getFormatter('America/New_York'));
+  });
+
+  test('throws for an invalid timezone — isValidIANATimezone exists to guard this', () => {
+    expect(() => getFormatter('Not/A_Zone')).toThrow();
+  });
+});

package/src/utils/timezone.js

@@ -0,0 +1,38 @@
+// Generic IANA timezone utilities. No quiet-hours domain logic here (unlike
+// quietHours.js, which imports isValidIANATimezone from this file) so that
+// other consumers of the timezone vocabulary — e.g. dataDownloads.js's
+// `timezone` field (JA-3245) — don't have to reach into an unrelated
+// domain's module to validate one. Re-exported from quietHours.js so
+// existing imports (including the library barrel) keep working.
+
+// Formatter construction is the expensive part of Intl (~ms); formatToParts
+// on a cached formatter is cheap. The cache also makes validation and
+// zone-minute lookups (quietHours.js's getZoneMinutes) share one authority:
+// a timezone is valid iff Intl accepts it.
+const formatterCache = new Map();
+
+export const getFormatter = (timeZone) => {
+  let formatter = formatterCache.get(timeZone);
+  if (formatter === undefined) {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hourCycle: "h23",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+    formatterCache.set(timeZone, formatter);
+  }
+  return formatter;
+};
+
+export const isValidIANATimezone = (timeZone) => {
+  if (typeof timeZone !== "string" || timeZone.trim() === "") {
+    return false;
+  }
+  try {
+    getFormatter(timeZone);
+    return true;
+  } catch {
+    return false;
+  }
+};