@justair/justair-library 7.2.0-alpha.29d5ea3 → 7.2.0-alpha.4a114f2

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

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

package/dist/index.d.ts

@@ -90,13 +90,8 @@ 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 } from "./utils/dataDownloadRange.js";
-import { MAX_RANGE_MS } from "./utils/dataDownloadRange.js";
+import { MAX_RANGE_DAYS as DATA_DOWNLOAD_MAX_RANGE_DAYS } from "./utils/dataDownloadRange.js";
 import { DATA_DOWNLOAD_ERRORS } from "./utils/dataDownloadRange.js";
-import { validateDateOrder } from "./utils/dataDownloadRange.js";
-import { validateMaxDateRange } from "./utils/dataDownloadRange.js";
-import { validateDownloadEmail } from "./utils/dataDownloadRange.js";
-import { normalizeDownloadEmail } 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";
@@ -111,5 +106,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, dataDownloadSchema, DataDownloads, AqiDataDownload, SampleDataDownload, MAX_RANGE_DAYS, MAX_RANGE_MS, DATA_DOWNLOAD_ERRORS, validateDateOrder, validateMaxDateRange, validateDownloadEmail, normalizeDownloadEmail, 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":"AAsIA;;;iBAEC;yBAtEwB,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;+BAS3B,8BAA8B;6BAA9B,8BAA8B;qCAA9B,8BAA8B;kCAA9B,8BAA8B;qCAA9B,8BAA8B;sCAA9B,8BAA8B;uCAA9B,8BAA8B;2BAjEI,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"}
+{"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.map

@@ -1 +1 @@
-{"version":3,"file":"dataDownloads.d.ts","sourceRoot":"","sources":["../../src/models/dataDownloads.js"],"names":[],"mappings":"AAqBA,qCAmCE;AAoEF,gCAA0E;AAO1E,kCAEG;AAEH,qCAIE"}
+{"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/utils/dataDownloadRange.d.ts

@@ -1,5 +1,4 @@
 export const MAX_RANGE_DAYS: 31;
-export const MAX_RANGE_MS: number;
 export const DATA_DOWNLOAD_ERRORS: Readonly<{
     END_BEFORE_START: "end_before_start";
     RANGE_TOO_LONG: "range_too_long";

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

@@ -1 +1 @@
-{"version":3,"file":"dataDownloadRange.d.ts","sourceRoot":"","sources":["../../src/utils/dataDownloadRange.js"],"names":[],"mappings":"AAmBA,gCAAiC;AAMjC,kCAAkF;AAKlF;;;;GAIG;AA0BI;;;IAcN;AAMM;;;IAcN;AASM,wDAC0D;AAK1D;;;IAUN"}
+{"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/package.json

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

package/src/constants/timezones.js

@@ -1,7 +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 — see
-// CLAUDE.md's "Note on constants placement".
+// second, unrelated domain (dataDownloads.js, JA-3080) needed it too.
 
 export const DEFAULT_TIMEZONE = "America/New_York";

package/src/index.js

@@ -123,13 +123,11 @@ import {
   SampleDataDownload,
 } from "./models/dataDownloads.js";
 import {
-  MAX_RANGE_DAYS,
-  MAX_RANGE_MS,
+  // 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,
-  validateDateOrder,
-  validateMaxDateRange,
-  validateDownloadEmail,
-  normalizeDownloadEmail,
 } from "./utils/dataDownloadRange.js";
 
 export function createLoggerInstance({ DATADOG_API_KEY, APPLICATION_NAME }) {
@@ -230,13 +228,8 @@ export {
   DataDownloads,
   AqiDataDownload,
   SampleDataDownload,
-  MAX_RANGE_DAYS,
-  MAX_RANGE_MS,
+  DATA_DOWNLOAD_MAX_RANGE_DAYS,
   DATA_DOWNLOAD_ERRORS,
-  validateDateOrder,
-  validateMaxDateRange,
-  validateDownloadEmail,
-  normalizeDownloadEmail,
   // Pollutant constants
   PARAMETERS,
   HEAVY_METALS,

package/src/models/dataDownloads.js

@@ -2,6 +2,7 @@ import mongoose from "mongoose";
 import { DEFAULT_TIMEZONE } from "../constants/timezones.js";
 import { isValidIANATimezone } from "../utils/timezone.js";
 import {
+  DATA_DOWNLOAD_ERRORS,
   validateDateOrder,
   validateMaxDateRange,
   validateDownloadEmail,
@@ -28,26 +29,38 @@ const dataDownloadSchema = mongoose.Schema(
     },
     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 },
-    // Format validation is delegated to validateDownloadEmail in the
-    // pre('validate') hook below, not an inline schema validator, so this
-    // and JA-3081's intake endpoint (validating the request body before a
-    // document exists) can never enforce two different email rules. See
-    // dataDownloadRange.js.
+    // 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,
+      },
     },
   },
   {
@@ -56,28 +69,18 @@ const dataDownloadSchema = mongoose.Schema(
   }
 );
 
-// Cross-field rule (quiet-hours shape, CLAUDE.md): delegated to
-// validateDateOrder so this schema and JA-3081's write-path validation can
-// never drift. Applies to every kind — the 31-day cap is AQI-only and lives
-// on AqiDataDownload's own schema below, not here. Lives in pre('validate')
-// so create()/save() can't persist an invalid range even if a caller
-// forgets to check.
+// 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.
 //
-// Email is validated here too (not an inline schema validator) for the same
-// shared-module reason. Both hooks pass the DATA_DOWNLOAD_ERRORS code as
-// invalidate()'s `kind` argument, not just the message, so a caught
-// ValidationError can be classified via err.errors.<path>.kind without
-// string-matching wording that's free to change.
+// 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);
   }
-
-  const emailErrors = validateDownloadEmail({ email: this.email });
-  for (const error of emailErrors) {
-    this.invalidate("email", error.message, this.email, error.code);
-  }
 });
 
 // Org-level admin screen lists a given org's downloads, most recent first,
@@ -85,16 +88,11 @@ dataDownloadSchema.pre("validate", function () {
 dataDownloadSchema.index({ orgId: 1, downloadedAt: -1 });
 
 const aqiDataDownloadSchema = new mongoose.Schema({
-  // Figma's download modal (node 4748:16300) titles the AQI variant
-  // "Download Data for: {Site Name}". Resolve that label via
-  // monitorId -> Monitors.monitorCode, NOT a Monitors -> Sites.name join:
-  // Monitors don't carry their own name and monitorCode is JustAirService's
-  // existing human-readable identifier for a monitor (already used in
-  // admin views and Slack alerts), whereas Monitors.siteId is not
-  // guaranteed set — it's only populated for monitors created through
-  // POST /devices's "linked device" flow, not plain POST /monitors — so a
-  // Sites join would render blank for a meaningful share of monitors.
-  // JA-3246/JA-3081 should populate this via monitorId, not siteId.
+  // 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",
@@ -124,11 +122,10 @@ sampleDataDownloadSchema.index({ siteId: 1, downloadedAt: -1 });
 
 const DataDownloads = mongoose.model("DataDownloads", dataDownloadSchema);
 
-// Discriminator model names are namespaced (matches userNotifications.js's
-// aqi_alert/device_offline/weekly_digest) — "AQI"/"Sample" as bare mongoose
-// model-registry keys would collide with any consuming service's own models
-// of those names. { value } keeps the persisted dataType exactly what
-// JA-3245 specifies regardless of the registry name.
+// 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",
 });

package/src/utils/dataDownloadRange.js

@@ -1,29 +1,18 @@
 // Data download date range validation (JA-3080/JA-3245): shared cross-field
-// rules for the requested range on a DataDownloads document. Single source
-// of truth for every consumer — this library's schema enforces these on
-// write, JustAirService's intake endpoint (JA-3081) validates the same
-// request shape before ever constructing a document. Pure functions, no DB,
-// no clock reads. Same shape as quietHours.js's cross-field validator.
+// 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 —
-// Sample downloads have no range limit. Compose the one(s) that apply to
-// the kind being validated; don't call validateMaxDateRange for Sample.
+// start applies to every download kind, but the 31-day cap is AQI-only.
 
-// Display/messaging only ("range cannot exceed 31 days"). NOT the enforced
-// bound — a consumer clamping a date picker with
-// `MAX_RANGE_DAYS * 24 * 60 * 60 * 1000` builds a stricter cap than the one
-// actually enforced (see MAX_RANGE_MS below) and would reject the exact
-// DST-crossing range the grace exists to allow. Import MAX_RANGE_MS instead
-// for anything that needs the real bound; validateMaxDateRange is the sole
-// authority either way.
+// 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. Allow it rather than rejecting a range the
-// product spec (Figma) explicitly promises as valid. This, not
-// MAX_RANGE_DAYS, is the number validateMaxDateRange actually enforces.
-export const MAX_RANGE_MS = MAX_RANGE_DAYS * 24 * 60 * 60 * 1000 + 60 * 60 * 1000;
+// 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
@@ -34,15 +23,10 @@ export const DATA_DOWNLOAD_ERRORS = Object.freeze({
   INVALID_EMAIL: "invalid_email",
 });
 
-// Coerces both ends through `new Date(...)` before comparing/subtracting: a
-// JSON request body (JA-3081's intake endpoint) hands these functions raw
-// strings, not Date instances, and comparing/subtracting un-coerced strings
-// silently produces NaN (`NaN > x` is always false) — the caps would never
-// fire for exactly the caller these functions exist to serve. An unparsable
-// value coerces to an Invalid Date (NaN time); format validation is the
-// schema/type layer's job, not a cross-field rule's, so that's treated the
-// same as "not this validator's concern" and returns null rather than
-// throwing or reporting a spurious range error.
+// 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;
@@ -55,9 +39,7 @@ const toTimes = (start, end) => {
   return { startTime, endTime };
 };
 
-// Returns an array of { code, message } errors; empty array = valid. Applies
-// to every download kind (AQI and Sample) — the Figma "31 days" cap is
-// AQI-only and is NOT enforced here, see validateMaxDateRange.
+// Returns { code, message }[]; empty = valid. Applies to every download kind.
 export const validateDateOrder = ({ start, end } = {}) => {
   const times = toTimes(start, end);
   if (!times) {
@@ -74,10 +56,8 @@ export const validateDateOrder = ({ start, end } = {}) => {
   return [];
 };
 
-// Returns an array of { code, message } errors; empty array = valid. AQI
-// downloads only — Sample downloads have no range limit. Assumes the caller
-// has already confirmed order via validateDateOrder (a reversed range isn't
-// re-reported here as "too long").
+// 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) {
@@ -96,17 +76,13 @@ export const validateMaxDateRange = ({ start, end } = {}) => {
 
 const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
-// Email is optional (JA-3080) — a blank form field means "not sharing my
-// email", not "invalid email". Both the schema (as a Mongoose `set`) and
-// JA-3081's intake endpoint (before ever constructing a document) need this
-// same "blank string collapses to null" rule, so it lives here rather than
-// only on the schema.
+// 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 an array of { code, message } errors; empty array = valid. null/
-// undefined is valid — call normalizeDownloadEmail first so a blank string
-// reaches this as null instead of failing the pattern check.
+// 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 [];

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

@@ -1,6 +1,5 @@
 import {
   MAX_RANGE_DAYS,
-  MAX_RANGE_MS,
   DATA_DOWNLOAD_ERRORS,
   validateDateOrder,
   validateMaxDateRange,
@@ -12,14 +11,6 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 const HOUR_MS = 60 * 60 * 1000;
 const start = new Date("2026-01-01T00:00:00.000Z");
 
-// S1: MAX_RANGE_DAYS alone under-describes the enforced bound. A consumer
-// needing the real cap (e.g. to clamp a date picker) should import
-// MAX_RANGE_MS directly rather than recomputing MAX_RANGE_DAYS * 24h and
-// silently building a stricter limit than validateMaxDateRange enforces.
-test("MAX_RANGE_MS is MAX_RANGE_DAYS plus the 1-hour DST grace, not a plain day-to-ms conversion", () => {
-  expect(MAX_RANGE_MS).toBe(MAX_RANGE_DAYS * DAY_MS + HOUR_MS);
-});
-
 describe("validateDateOrder (applies to every download kind)", () => {
   test("returns no errors when start/end are missing", () => {
     expect(validateDateOrder({})).toEqual([]);