@justair/justair-library 7.3.0-alpha.e85bbda → 7.3.0

package/dist/constants/dataDownloads.d.ts

@@ -1,2 +1,2 @@
-export const DATA_DOWNLOAD_TYPES: string[];
+export const DATA_DOWNLOAD_TYPES: readonly string[];
 //# sourceMappingURL=dataDownloads.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataDownloads.d.ts","sourceRoot":"","sources":["../../src/constants/dataDownloads.js"],"names":[],"mappings":"AAeA,2CAAqD"}
+{"version":3,"file":"dataDownloads.d.ts","sourceRoot":"","sources":["../../src/constants/dataDownloads.js"],"names":[],"mappings":"AAkBA,oDAAoE"}

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

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

package/dist/index.d.ts

@@ -97,6 +97,8 @@ import { validateDateOrder as validateDataDownloadDateOrder } from "./utils/data
 import { validateMaxDateRange as validateDataDownloadMaxDateRange } from "./utils/dataDownloadValidation.js";
 import { validateDownloadEmail as validateDataDownloadEmail } from "./utils/dataDownloadValidation.js";
 import { normalizeDownloadEmail as normalizeDataDownloadEmail } from "./utils/dataDownloadValidation.js";
+import { validateDownloadTimezone as validateDataDownloadTimezone } from "./utils/dataDownloadValidation.js";
+import { normalizeDownloadTimezone as normalizeDataDownloadTimezone } from "./utils/dataDownloadValidation.js";
 import { PARAMETERS } from "./constants/pollutants.js";
 import { HEAVY_METALS } from "./constants/pollutants.js";
 import { ALERT_LEVEL_WEIGHTS } from "./constants/alertLevels.js";
@@ -111,5 +113,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, 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, 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":"AAkJA;;;iBAEC;yBAlFwB,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;+DAoB3B,mCAAmC;qCAAnC,mCAAmC;mEAAnC,mCAAmC;yEAAnC,mCAAmC;mEAAnC,mCAAmC;qEAAnC,mCAAmC;2BA7ED,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":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"dataDownloads.d.ts","sourceRoot":"","sources":["../../src/models/dataDownloads.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DE;AAqDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAA0E;AAY1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIE;qBA/JmB,UAAU"}
+{"version":3,"file":"dataDownloads.d.ts","sourceRoot":"","sources":["../../src/models/dataDownloads.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DE;AA2DF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAA0E;AAY1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIE;qBAtKmB,UAAU"}

package/dist/utils/dataDownloadValidation.d.ts

@@ -18,4 +18,9 @@ export function validateDownloadEmail({ email }?: {}): {
     code: "invalid_email";
     message: string;
 }[];
+export function normalizeDownloadTimezone(value: any): any;
+export function validateDownloadTimezone({ timezone }?: {}): {
+    code: "invalid_timezone";
+    message: string;
+}[];
 //# sourceMappingURL=dataDownloadValidation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"dataDownloadValidation.d.ts","sourceRoot":"","sources":["../../src/utils/dataDownloadValidation.js"],"names":[],"mappings":"AAUA,gCAAiC;AAUjC;;;;;GAKG;AAmBI;;;IAcN;AAIM;;;IAcN;AAgBM,wDAMN;AAIM;;;IAqBN"}
+{"version":3,"file":"dataDownloadValidation.d.ts","sourceRoot":"","sources":["../../src/utils/dataDownloadValidation.js"],"names":[],"mappings":"AAYA,gCAAiC;AAUjC;;;;;GAKG;AAmBI;;;IAcN;AAIM;;;IAcN;AAgBM,wDAMN;AAIM;;;IAqBN;AAOM,2DAWN;AAOM;;;IAaN"}

package/package.json

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

package/src/constants/dataDownloads.js

@@ -13,4 +13,7 @@
 // as a third type — add it here and register its discriminator in
 // models/dataDownloads.js, so no consumer has to hardcode the string.
 
-export const DATA_DOWNLOAD_TYPES = ["AQI", "Sample"];
+// Frozen because every importer in a process gets this same instance — one
+// consumer calling .sort() or .push() would silently reorder the picker for
+// all of them. Matches DATA_DOWNLOAD_ERRORS in dataDownloadValidation.js.
+export const DATA_DOWNLOAD_TYPES = Object.freeze(["AQI", "Sample"]);

package/src/constants/timezones.js

@@ -3,4 +3,10 @@
 // Originally lived in utils/quietHours.js (JA-3054); moved here once a
 // second, unrelated domain (dataDownloads.js, JA-3080) needed it too.
 
+// Deliberately no DOWNLOAD_TIMEZONES / TIMEZONE_OPTIONS list here. The
+// download modal's "Set Timezone" dropdown offers display labels ("Eastern
+// Standard Time (EST)") over IANA values, and labels are a view concern:
+// this library has no i18n and no view layer, so a label map would drift from
+// design the first time the copy changed. The validator accepts any zone Intl
+// accepts (utils/timezone.js), so the consumer owns which subset it offers.
 export const DEFAULT_TIMEZONE = "America/New_York";

package/src/index.js

@@ -142,6 +142,8 @@ import {
   validateMaxDateRange as validateDataDownloadMaxDateRange,
   validateDownloadEmail as validateDataDownloadEmail,
   normalizeDownloadEmail as normalizeDataDownloadEmail,
+  validateDownloadTimezone as validateDataDownloadTimezone,
+  normalizeDownloadTimezone as normalizeDataDownloadTimezone,
 } from "./utils/dataDownloadValidation.js";
 
 export function createLoggerInstance({ DATADOG_API_KEY, APPLICATION_NAME }) {
@@ -249,6 +251,8 @@ export {
   validateDataDownloadMaxDateRange,
   validateDataDownloadEmail,
   normalizeDataDownloadEmail,
+  validateDataDownloadTimezone,
+  normalizeDataDownloadTimezone,
   // Pollutant constants
   PARAMETERS,
   HEAVY_METALS,

package/src/models/dataDownloads.js

@@ -1,13 +1,14 @@
 import mongoose from "mongoose";
 import { DATA_DOWNLOAD_TYPES } from "../constants/dataDownloads.js";
 import { DEFAULT_TIMEZONE } from "../constants/timezones.js";
-import { isValidIANATimezone } from "../utils/timezone.js";
 import {
   DATA_DOWNLOAD_ERRORS,
   validateDateOrder,
   validateMaxDateRange,
   validateDownloadEmail,
   normalizeDownloadEmail,
+  validateDownloadTimezone,
+  normalizeDownloadTimezone,
 } from "../utils/dataDownloadValidation.js";
 
 // DataDownloads — one doc per data download request (JA-3080). Written by
@@ -30,10 +31,10 @@ const dataDownloadSchema = new 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.
+    // `default` only applies to `undefined`, not `null` or "", so both of the
+    // other "didn't pick one" shapes (a JSON body's null, an untouched HTML
+    // <select>'s empty string) are 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.
@@ -42,9 +43,9 @@ const dataDownloadSchema = new mongoose.Schema(
       type: String,
       trim: true,
       default: DEFAULT_TIMEZONE,
-      set: (value) => (value === null ? DEFAULT_TIMEZONE : value),
+      set: normalizeDownloadTimezone,
       validate: {
-        validator: isValidIANATimezone,
+        validator: (value) => validateDownloadTimezone({ timezone: value }).length === 0,
         message: "timezone must be a valid IANA timezone identifier",
         type: DATA_DOWNLOAD_ERRORS.INVALID_TIMEZONE,
       },
@@ -93,6 +94,12 @@ const dataDownloadSchema = new mongoose.Schema(
 //
 // Passes the error code as invalidate()'s `kind` so a caught ValidationError
 // can be classified via err.errors.<path>.kind, not by message wording.
+//
+// Same caveat the `timezone` field carries: pre('validate') never runs on a
+// query update, so a `$set` of dateRangeStart/dateRangeEnd can persist a
+// reversed or over-length range even with { runValidators: true }. Deliberate
+// — the rules are cross-field, and query updates have no full document to
+// check. Writers should go through create()/save(); readers must still defend.
 dataDownloadSchema.pre("validate", function () {
   const rangeErrors = validateDateOrder({ start: this.dateRangeStart, end: this.dateRangeEnd });
   for (const error of rangeErrors) {

package/src/utils/dataDownloadValidation.js

@@ -1,10 +1,12 @@
 // Data download validation (JA-3080/JA-3245): the shared field and cross-field
 // rules for a DataDownloads document — date range order, the AQI-only length
-// cap, and the optional email. Pure functions, no DB, no clock reads. Same
-// shape as quietHours.js's cross-field validator.
+// cap, the optional email, and the timezone. 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.
+import { isValidIANATimezone } from "./timezone.js";
+import { DEFAULT_TIMEZONE } from "../constants/timezones.js";
 
 // Messaging only ("range cannot exceed 31 days"). validateMaxDateRange is the
 // sole authority on the enforced bound; don't rebuild the cap from this.
@@ -122,3 +124,41 @@ export const validateDownloadEmail = ({ email } = {}) => {
     },
   ];
 };
+
+// Every shape of "didn't pick one" resolves to the default, mirroring
+// normalizeDownloadEmail's blank-collapses-to-null contract. An untouched HTML
+// <select> posts "" and a JSON body usually carries null, so treating only one
+// of them as unset rejects a download for a field the user never touched.
+// `undefined` passes through so the schema's own `default` still applies.
+export const normalizeDownloadTimezone = (value) => {
+  if (value === undefined) {
+    return value;
+  }
+  if (value === null) {
+    return DEFAULT_TIMEZONE;
+  }
+  if (typeof value === "string" && value.trim() === "") {
+    return DEFAULT_TIMEZONE;
+  }
+  return value;
+};
+
+// Returns { code, message }[]; empty = valid. Anything normalizeDownloadTimezone
+// resolves to the default is valid here too, so a consumer pre-validating a
+// request body accepts exactly what the model stores. isValidIANATimezone alone
+// rejects null and "", which would fail a request the model saves happily —
+// the write-path/read-path split the email rules exist to avoid.
+export const validateDownloadTimezone = ({ timezone } = {}) => {
+  if (normalizeDownloadTimezone(timezone) !== timezone) {
+    return [];
+  }
+  if (timezone === undefined || isValidIANATimezone(timezone)) {
+    return [];
+  }
+  return [
+    {
+      code: DATA_DOWNLOAD_ERRORS.INVALID_TIMEZONE,
+      message: "timezone must be a valid IANA timezone identifier",
+    },
+  ];
+};

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

@@ -4,8 +4,11 @@ import {
   validateDateOrder,
   validateMaxDateRange,
   validateDownloadEmail,
+  validateDownloadTimezone,
+  normalizeDownloadTimezone,
   normalizeDownloadEmail,
 } from "../dataDownloadValidation.js";
+import { DEFAULT_TIMEZONE } from "../../constants/timezones.js";
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 const HOUR_MS = 60 * 60 * 1000;
@@ -155,3 +158,56 @@ describe("validateDownloadEmail (email is optional — JA-3080)", () => {
     ]);
   });
 });
+
+describe("validateDownloadTimezone", () => {
+  test.each(["America/New_York", "America/Detroit", "UTC", "Asia/Tokyo"])(
+    "accepts %s",
+    (timezone) => {
+      expect(validateDownloadTimezone({ timezone })).toEqual([]);
+    }
+  );
+
+  // The schema setter resolves both to DEFAULT_TIMEZONE, so a consumer
+  // pre-validating a request body must accept what the model stores.
+  // An untouched <select> posts "", a JSON body usually carries null. Both mean
+  // "didn't pick one", so both must validate the way the setter resolves them.
+  test.each([null, undefined, "", "   "])(
+    "treats %p as valid (the setter fills the default)",
+    (timezone) => {
+      expect(validateDownloadTimezone({ timezone })).toEqual([]);
+    }
+  );
+
+  test("accepts a call with no argument at all", () => {
+    expect(validateDownloadTimezone()).toEqual([]);
+  });
+
+  test.each(["America/Fake_City", "Not/A_Zone", 5, {}])(
+    "flags %p with INVALID_TIMEZONE",
+    (timezone) => {
+      expect(validateDownloadTimezone({ timezone })).toEqual([
+        expect.objectContaining({ code: DATA_DOWNLOAD_ERRORS.INVALID_TIMEZONE }),
+      ]);
+    }
+  );
+});
+
+describe("normalizeDownloadTimezone", () => {
+  test.each([null, "", "   "])("resolves %p to the default", (value) => {
+    expect(normalizeDownloadTimezone(value)).toBe(DEFAULT_TIMEZONE);
+  });
+
+  // Passes through so the schema's own `default` still applies.
+  test("leaves undefined alone", () => {
+    expect(normalizeDownloadTimezone(undefined)).toBeUndefined();
+  });
+
+  test("leaves a real zone untouched", () => {
+    expect(normalizeDownloadTimezone("Asia/Tokyo")).toBe("Asia/Tokyo");
+  });
+
+  // Validation, not normalization, is what rejects these.
+  test.each(["Not/A_Zone", 5])("leaves invalid input %p for the validator", (value) => {
+    expect(normalizeDownloadTimezone(value)).toBe(value);
+  });
+});