@justair/justair-library 6.13.0 → 6.14.0-alpha.3432ed7

package/dist/index.d.ts

@@ -91,5 +91,14 @@ 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";
-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 };
+import { DEFAULT_QUIET_HOURS } from "./utils/quietHours.js";
+import { DEFAULT_TIMEZONE } from "./utils/quietHours.js";
+import { QUIET_HOURS_ERRORS } from "./utils/quietHours.js";
+import { isValidTimeString } from "./utils/quietHours.js";
+import { isValidIANATimezone } from "./utils/quietHours.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 };
 //# 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":"AA4GA;;;iBAEC;yBA5CwB,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;4BAuBT,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;sCAlCtF,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"}
+{"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AAqCA,8BAiDE;AAIF,wBAAmD;AAxFnD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DAsBC"}
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/models/users.js"],"names":[],"mappings":"AA2CA,8BAiFE;AA2BF,wBAAmD;AA/InD,iDAA4D;AAC5D,6CAAmD;AAUnD,4DAsBC"}

package/dist/utils/quietHours.d.ts

@@ -0,0 +1,33 @@
+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;
+}[] | ({
+    code: "format";
+    message: string;
+} | {
+    code: "equal_pair";
+    message: string;
+})[];
+export function getZoneMinutes(date: any, timeZone: any): number;
+export function isInQuietWindow(minutesNow: any, window: any): boolean;
+export function resolveQuietHours(user: any): {
+    window: Readonly<{
+        start: "22:00";
+        end: "07:00";
+    }>;
+    timezone: string;
+    warnings: string[];
+};
+//# sourceMappingURL=quietHours.d.ts.map

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

@@ -0,0 +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"}

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

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

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

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

package/package.json

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

package/src/index.js

@@ -83,6 +83,17 @@ import {
   DELIVERY_STATUSES,
 } from "./models/userNotifications.js";
 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";
 
 // Sites related imports
 import { sitesSchema, Sites } from "./models/sites.js";
@@ -207,4 +218,14 @@ export {
   getAlertWeight,
   // Utilities
   splitName,
+  // Quiet hours (JA-3054): shared validation + window evaluation
+  DEFAULT_QUIET_HOURS,
+  DEFAULT_TIMEZONE,
+  QUIET_HOURS_ERRORS,
+  isValidTimeString,
+  isValidIANATimezone,
+  validateQuietHours,
+  getZoneMinutes,
+  isInQuietWindow,
+  resolveQuietHours,
 };

package/src/models/users.js

@@ -1,4 +1,10 @@
 import mongoose from "mongoose";
+import {
+  isValidTimeString,
+  isValidIANATimezone,
+  validateQuietHours,
+  QUIET_HOURS_ERRORS,
+} from "../utils/quietHours.js";
 
 const COOKIE_CONSENT_CATEGORIES = ["analytics_performance"];
 const COOKIE_CONSENT_VALUES = ["accept", "reject"];
@@ -80,12 +86,67 @@ const usersSchema = mongoose.Schema(
       default: "Good",
     },
     cookie_consent: cookieConsentSchemaDefinition,
+    // Quiet hours (JA-3054): null = platform defaults apply (22:00–07:00
+    // America/New_York, see utils/quietHours.js). Pair rule: start/end are
+    // always both set or both null — enforced here at document validation
+    // (field validators + the pre-validate hook below), so create()/save()
+    // cannot persist an invalid window even if a consumer skips
+    // validateQuietHours. Query updates ($set via updateOne/findOneAndUpdate)
+    // bypass document validation, so readers still defend with
+    // resolveQuietHours.
+    quietHoursStart: {
+      type: String,
+      default: null,
+      validate: {
+        validator: (value) => value === null || isValidTimeString(value),
+        message: "quietHoursStart must be a time string in HH:mm format",
+      },
+    },
+    quietHoursEnd: {
+      type: String,
+      default: null,
+      validate: {
+        validator: (value) => value === null || isValidTimeString(value),
+        message: "quietHoursEnd must be a time string in HH:mm format",
+      },
+    },
+    timezone: {
+      type: String,
+      default: null,
+      validate: {
+        validator: (value) => value === null || isValidIANATimezone(value),
+        message: "timezone must be a valid IANA timezone identifier",
+      },
+    },
   },
   {
     timestamps: true,
   }
 );
 
+// Cross-field quiet-hours rules (both-or-neither, start ≠ end) delegated to
+// validateQuietHours so the schema and the standalone validator can never
+// drift. Field-format errors are reported by the per-field validators above;
+// this hook re-attaches only the cross-field codes those can't see (they
+// need both fields). Allowlist on stable codes — never on message wording.
+const CROSS_FIELD_QUIET_HOURS_CODES = new Set([
+  QUIET_HOURS_ERRORS.HALF_PAIR,
+  QUIET_HOURS_ERRORS.EQUAL_PAIR,
+]);
+
+usersSchema.pre("validate", function (next) {
+  const errors = validateQuietHours({
+    start: this.quietHoursStart,
+    end: this.quietHoursEnd,
+  });
+  for (const error of errors) {
+    if (CROSS_FIELD_QUIET_HOURS_CODES.has(error.code)) {
+      this.invalidate("quietHoursStart", error.message);
+    }
+  }
+  next();
+});
+
 usersSchema.index({ phone: 1 });
 
 const Users = mongoose.model("Users", usersSchema);

package/src/utils/quietHours.js

@@ -0,0 +1,210 @@
+// Quiet hours (JA-3054): shared validation + evaluation for per-user
+// notification quiet windows. Single source of truth for every consumer —
+// JustAirUserService validates writes with it, JustAirNotificationService
+// evaluates suppression with it. Pure functions only: no logger, no clock
+// reads — callers pass `now` in and log any returned warnings themselves.
+//
+// A window is two "HH:mm" wall-clock strings evaluated in the user's IANA
+// timezone. `start > end` means the window crosses midnight:
+//
+//   same-day window  09:00–17:00        midnight-crossing  22:00–07:00
+//   00:00      09:00      17:00  24:00  00:00     07:00        22:00  24:00
+//   |----------|##########|------|      |#########|------------|######|
+//              [start      end)                    end)         [start
+//   in-window: start <= m < end         in-window: m >= start OR m < end
+//
+// 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.
+
+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.
+export const QUIET_HOURS_ERRORS = Object.freeze({
+  HALF_PAIR: "half_pair",
+  FORMAT: "format",
+  EQUAL_PAIR: "equal_pair",
+});
+
+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:
+// both null/undefined (defaults apply) or both well-formed and distinct.
+// Everything else is rejected so no ambiguous window is ever stored.
+export const validateQuietHours = ({ start, end } = {}) => {
+  const startUnset = start === null || start === undefined;
+  const endUnset = end === null || end === undefined;
+
+  if (startUnset && endUnset) {
+    return [];
+  }
+  if (startUnset || endUnset) {
+    return [
+      {
+        code: QUIET_HOURS_ERRORS.HALF_PAIR,
+        message:
+          "quietHoursStart and quietHoursEnd must be provided together (or both null to use the default window)",
+      },
+    ];
+  }
+
+  const errors = [];
+  if (!isValidTimeString(start)) {
+    errors.push({
+      code: QUIET_HOURS_ERRORS.FORMAT,
+      message: "quietHoursStart must be a time string in HH:mm format",
+    });
+  }
+  if (!isValidTimeString(end)) {
+    errors.push({
+      code: QUIET_HOURS_ERRORS.FORMAT,
+      message: "quietHoursEnd must be a time string in HH:mm format",
+    });
+  }
+  if (errors.length === 0 && start === end) {
+    errors.push({
+      code: QUIET_HOURS_ERRORS.EQUAL_PAIR,
+      message:
+        "quietHoursStart and quietHoursEnd must differ (set both to null to disable a custom window)",
+    });
+  }
+  return errors;
+};
+
+const timeToMinutes = (value) => {
+  const [hours, minutes] = value.split(":");
+  return Number(hours) * 60 + Number(minutes);
+};
+
+// Minutes since local midnight in `timeZone` at instant `date`. Throws on an
+// invalid timezone — resolve with resolveQuietHours/isValidIANATimezone first.
+export const getZoneMinutes = (date, timeZone) => {
+  const parts = getFormatter(timeZone).formatToParts(date);
+  let hours = 0;
+  let minutes = 0;
+  for (const part of parts) {
+    if (part.type === "hour") hours = Number(part.value);
+    else if (part.type === "minute") minutes = Number(part.value);
+  }
+  return hours * 60 + minutes;
+};
+
+// `minutesNow` from getZoneMinutes; `window` of "HH:mm" strings or null.
+// Null window (or an equal pair, which resolveQuietHours flags) → never
+// suppressed. See the file-header diagram for the two window shapes.
+export const isInQuietWindow = (minutesNow, window) => {
+  if (!window || !isValidTimeString(window.start) || !isValidTimeString(window.end)) {
+    return false;
+  }
+  const start = timeToMinutes(window.start);
+  const end = timeToMinutes(window.end);
+  if (start === end) {
+    return false;
+  }
+  if (start < end) {
+    return minutesNow >= start && minutesNow < end;
+  }
+  return minutesNow >= start || minutesNow < end;
+};
+
+// Resolves a user's stored fields into an evaluable { window, timezone },
+// never throwing on corrupt data (JA-3020 D16). Fallback semantics:
+//   - fields null/undefined          → defaults, no warning (the normal case)
+//   - invalid timezone               → DEFAULT_TIMEZONE + warning
+//   - half-set or malformed pair     → DEFAULT_QUIET_HOURS + warning (corrupt
+//     data keeps the protective default; a malformed-AND-identical pair like
+//     "25:00"/"25:00" is classified FORMAT by the validator and lands here)
+//   - well-formed equal pair         → window: null (no suppression) + warning
+//     (JA-3020 D11 — ambiguous intent must never become "always quiet")
+// Branching consumes the validator's stable error codes — never re-derives
+// the classification from the raw values.
+// Callers log `warnings` (once per run, not per user) and evaluate with
+// isInQuietWindow(getZoneMinutes(now, timezone), window).
+export const resolveQuietHours = (user) => {
+  const { quietHoursStart, quietHoursEnd, timezone } = user ?? {};
+  const warnings = [];
+
+  let resolvedTimezone = DEFAULT_TIMEZONE;
+  if (timezone !== null && timezone !== undefined) {
+    if (isValidIANATimezone(timezone)) {
+      resolvedTimezone = timezone;
+    } else {
+      warnings.push(
+        `invalid stored timezone "${timezone}" — falling back to ${DEFAULT_TIMEZONE}`
+      );
+    }
+  }
+
+  const startUnset = quietHoursStart === null || quietHoursStart === undefined;
+  const endUnset = quietHoursEnd === null || quietHoursEnd === undefined;
+
+  let window = DEFAULT_QUIET_HOURS;
+  if (!startUnset || !endUnset) {
+    const errors = validateQuietHours({
+      start: quietHoursStart,
+      end: quietHoursEnd,
+    });
+    if (errors.length === 0) {
+      window = { start: quietHoursStart, end: quietHoursEnd };
+    } else if (
+      errors.some((e) => e.code === QUIET_HOURS_ERRORS.EQUAL_PAIR)
+    ) {
+      window = null;
+      warnings.push(
+        `stored quiet hours are an equal pair ("${quietHoursStart}") — treating as no suppression`
+      );
+    } else {
+      warnings.push(
+        `stored quiet hours are invalid (start: ${JSON.stringify(
+          quietHoursStart
+        )}, end: ${JSON.stringify(
+          quietHoursEnd
+        )}) — falling back to the default window`
+      );
+    }
+  }
+
+  return { window, timezone: resolvedTimezone, warnings };
+};

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

@@ -0,0 +1,386 @@
+import {
+  DEFAULT_QUIET_HOURS,
+  DEFAULT_TIMEZONE,
+  QUIET_HOURS_ERRORS,
+  isValidTimeString,
+  isValidIANATimezone,
+  validateQuietHours,
+  getZoneMinutes,
+  isInQuietWindow,
+  resolveQuietHours,
+} from '../quietHours.js';
+
+describe('constants', () => {
+  test('defaults match the JA-3020 contract (22:00–07:00 America/New_York)', () => {
+    expect(DEFAULT_QUIET_HOURS).toEqual({ start: '22:00', end: '07:00' });
+    expect(DEFAULT_TIMEZONE).toBe('America/New_York');
+  });
+
+  test('DEFAULT_QUIET_HOURS is frozen', () => {
+    expect(Object.isFrozen(DEFAULT_QUIET_HOURS)).toBe(true);
+  });
+});
+
+describe('isValidTimeString', () => {
+  test.each(['00:00', '07:00', '09:30', '23:59', '13:05'])(
+    'accepts %s',
+    (value) => {
+      expect(isValidTimeString(value)).toBe(true);
+    }
+  );
+
+  test.each([
+    ['24:00', 'hour out of range'],
+    ['07:60', 'minute out of range'],
+    ['7:30', 'missing leading zero'],
+    ['9:5', 'single digits'],
+    ['0730', 'no separator'],
+    ['07:30:00', 'seconds included'],
+    ['', 'empty string'],
+    ['ten pm', 'words'],
+  ])('rejects %s (%s)', (value) => {
+    expect(isValidTimeString(value)).toBe(false);
+  });
+
+  test.each([null, undefined, 730, { start: '07:30' }])(
+    'rejects non-string %p',
+    (value) => {
+      expect(isValidTimeString(value)).toBe(false);
+    }
+  );
+});
+
+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('validateQuietHours', () => {
+  test('accepts both fields null (defaults apply)', () => {
+    expect(validateQuietHours({ start: null, end: null })).toEqual([]);
+  });
+
+  test('accepts both fields undefined / missing object', () => {
+    expect(validateQuietHours({})).toEqual([]);
+    expect(validateQuietHours()).toEqual([]);
+  });
+
+  test('accepts a well-formed distinct pair', () => {
+    expect(validateQuietHours({ start: '22:00', end: '07:00' })).toEqual([]);
+    expect(validateQuietHours({ start: '09:00', end: '17:00' })).toEqual([]);
+  });
+
+  test('rejects a half-set pair (start only) with a stable code', () => {
+    const errors = validateQuietHours({ start: '22:00', end: null });
+    expect(errors).toHaveLength(1);
+    expect(errors[0].code).toBe(QUIET_HOURS_ERRORS.HALF_PAIR);
+    expect(errors[0].message).toMatch(/together/);
+  });
+
+  test('rejects a half-set pair (end only) with a stable code', () => {
+    const errors = validateQuietHours({ start: undefined, end: '07:00' });
+    expect(errors).toHaveLength(1);
+    expect(errors[0].code).toBe(QUIET_HOURS_ERRORS.HALF_PAIR);
+    expect(errors[0].message).toMatch(/together/);
+  });
+
+  test('rejects malformed times, reporting each field with the format code', () => {
+    const errors = validateQuietHours({ start: '25:00', end: '7pm' });
+    expect(errors).toHaveLength(2);
+    expect(errors.every((e) => e.code === QUIET_HOURS_ERRORS.FORMAT)).toBe(true);
+    expect(errors[0].message).toMatch(/quietHoursStart/);
+    expect(errors[1].message).toMatch(/quietHoursEnd/);
+  });
+
+  test('rejects an equal pair with a stable code (JA-3020 D11)', () => {
+    const errors = validateQuietHours({ start: '22:00', end: '22:00' });
+    expect(errors).toHaveLength(1);
+    expect(errors[0].code).toBe(QUIET_HOURS_ERRORS.EQUAL_PAIR);
+    expect(errors[0].message).toMatch(/differ/);
+  });
+
+  test('error codes are frozen shared vocabulary', () => {
+    expect(Object.isFrozen(QUIET_HOURS_ERRORS)).toBe(true);
+    expect(QUIET_HOURS_ERRORS).toEqual({
+      HALF_PAIR: 'half_pair',
+      FORMAT: 'format',
+      EQUAL_PAIR: 'equal_pair',
+    });
+  });
+});
+
+describe('getZoneMinutes', () => {
+  test('converts UTC instants to New York wall-clock minutes (EST, winter)', () => {
+    // 2026-01-15 15:30 UTC = 10:30 EST (UTC-5)
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 0, 15, 15, 30)), 'America/New_York')
+    ).toBe(10 * 60 + 30);
+  });
+
+  test('converts UTC instants to New York wall-clock minutes (EDT, summer)', () => {
+    // 2026-07-15 15:30 UTC = 11:30 EDT (UTC-4)
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 6, 15, 15, 30)), 'America/New_York')
+    ).toBe(11 * 60 + 30);
+  });
+
+  test('handles local midnight as 0 minutes (h23, not 24)', () => {
+    // 2026-01-15 05:00 UTC = 00:00 EST
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 0, 15, 5, 0)), 'America/New_York')
+    ).toBe(0);
+  });
+
+  test('DST spring-forward: the 02:xx hour does not exist (2026-03-08)', () => {
+    // 06:59 UTC = 01:59 EST, one minute later 07:00 UTC = 03:00 EDT
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 2, 8, 6, 59)), 'America/New_York')
+    ).toBe(1 * 60 + 59);
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 2, 8, 7, 0)), 'America/New_York')
+    ).toBe(3 * 60);
+  });
+
+  test('DST fall-back: 01:30 wall-clock occurs twice (2026-11-01)', () => {
+    // 05:30 UTC = 01:30 EDT and 06:30 UTC = 01:30 EST — same wall clock
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 10, 1, 5, 30)), 'America/New_York')
+    ).toBe(1 * 60 + 30);
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 10, 1, 6, 30)), 'America/New_York')
+    ).toBe(1 * 60 + 30);
+  });
+
+  test('UTC zone is a passthrough of the instant wall clock', () => {
+    expect(
+      getZoneMinutes(new Date(Date.UTC(2026, 6, 15, 15, 30)), 'UTC')
+    ).toBe(15 * 60 + 30);
+  });
+
+  test('throws on an invalid timezone (callers resolve first)', () => {
+    expect(() =>
+      getZoneMinutes(new Date(), 'America/Fake_City')
+    ).toThrow();
+  });
+});
+
+describe('isInQuietWindow', () => {
+  const minutes = (hhmm) => {
+    const [h, m] = hhmm.split(':');
+    return Number(h) * 60 + Number(m);
+  };
+
+  describe('same-day window 09:00–17:00', () => {
+    const window = { start: '09:00', end: '17:00' };
+
+    test.each(['09:00', '12:00', '16:59'])('%s is inside', (time) => {
+      expect(isInQuietWindow(minutes(time), window)).toBe(true);
+    });
+
+    test.each(['08:59', '17:00', '22:00', '00:00'])('%s is outside', (time) => {
+      expect(isInQuietWindow(minutes(time), window)).toBe(false);
+    });
+  });
+
+  describe('midnight-crossing window 22:00–07:00 (the default shape)', () => {
+    const window = { start: '22:00', end: '07:00' };
+
+    test.each(['22:00', '23:59', '00:00', '03:00', '06:59'])(
+      '%s is inside',
+      (time) => {
+        expect(isInQuietWindow(minutes(time), window)).toBe(true);
+      }
+    );
+
+    test.each(['21:59', '07:00', '12:00', '17:35'])('%s is outside', (time) => {
+      expect(isInQuietWindow(minutes(time), window)).toBe(false);
+    });
+  });
+
+  test('null or malformed window never suppresses', () => {
+    expect(isInQuietWindow(0, null)).toBe(false);
+    expect(isInQuietWindow(0, undefined)).toBe(false);
+    expect(isInQuietWindow(0, {})).toBe(false);
+    expect(isInQuietWindow(0, { start: '22:00', end: 'bad' })).toBe(false);
+  });
+
+  test('equal pair never suppresses (defensive, JA-3020 D11)', () => {
+    expect(isInQuietWindow(minutes('22:00'), { start: '22:00', end: '22:00' })).toBe(
+      false
+    );
+  });
+});
+
+describe('resolveQuietHours', () => {
+  test('all fields null → defaults with no warnings (every legacy user)', () => {
+    const resolved = resolveQuietHours({
+      quietHoursStart: null,
+      quietHoursEnd: null,
+      timezone: null,
+    });
+    expect(resolved).toEqual({
+      window: DEFAULT_QUIET_HOURS,
+      timezone: DEFAULT_TIMEZONE,
+      warnings: [],
+    });
+  });
+
+  test('fields absent entirely → defaults with no warnings', () => {
+    expect(resolveQuietHours({})).toEqual({
+      window: DEFAULT_QUIET_HOURS,
+      timezone: DEFAULT_TIMEZONE,
+      warnings: [],
+    });
+  });
+
+  test('null or undefined user → defaults, never throws', () => {
+    expect(resolveQuietHours(null)).toEqual({
+      window: DEFAULT_QUIET_HOURS,
+      timezone: DEFAULT_TIMEZONE,
+      warnings: [],
+    });
+    expect(resolveQuietHours(undefined).window).toEqual(DEFAULT_QUIET_HOURS);
+  });
+
+  test('valid custom fields are used verbatim', () => {
+    const resolved = resolveQuietHours({
+      quietHoursStart: '23:00',
+      quietHoursEnd: '06:30',
+      timezone: 'America/Detroit',
+    });
+    expect(resolved).toEqual({
+      window: { start: '23:00', end: '06:30' },
+      timezone: 'America/Detroit',
+      warnings: [],
+    });
+  });
+
+  test('timezone set, hours unset → default window in THEIR zone (D5 matrix)', () => {
+    const resolved = resolveQuietHours({ timezone: 'America/Los_Angeles' });
+    expect(resolved.window).toEqual(DEFAULT_QUIET_HOURS);
+    expect(resolved.timezone).toBe('America/Los_Angeles');
+    expect(resolved.warnings).toEqual([]);
+  });
+
+  test('hours set, timezone unset → custom window in the default zone (D5 matrix)', () => {
+    const resolved = resolveQuietHours({
+      quietHoursStart: '23:00',
+      quietHoursEnd: '05:00',
+    });
+    expect(resolved.window).toEqual({ start: '23:00', end: '05:00' });
+    expect(resolved.timezone).toBe(DEFAULT_TIMEZONE);
+    expect(resolved.warnings).toEqual([]);
+  });
+
+  test('invalid stored timezone → default zone + warning', () => {
+    const resolved = resolveQuietHours({ timezone: 'America/Fake_City' });
+    expect(resolved.timezone).toBe(DEFAULT_TIMEZONE);
+    expect(resolved.warnings).toHaveLength(1);
+    expect(resolved.warnings[0]).toMatch(/invalid stored timezone/);
+  });
+
+  test('half-set stored pair → default window + warning (D16)', () => {
+    const resolved = resolveQuietHours({ quietHoursStart: '22:00' });
+    expect(resolved.window).toEqual(DEFAULT_QUIET_HOURS);
+    expect(resolved.warnings).toHaveLength(1);
+    expect(resolved.warnings[0]).toMatch(/invalid/);
+  });
+
+  test('malformed stored pair → default window + warning (D16)', () => {
+    const resolved = resolveQuietHours({
+      quietHoursStart: '25:00',
+      quietHoursEnd: '07:00',
+    });
+    expect(resolved.window).toEqual(DEFAULT_QUIET_HOURS);
+    expect(resolved.warnings).toHaveLength(1);
+  });
+
+  test('stored equal pair → NO suppression + warning, never "always quiet" (D11)', () => {
+    const resolved = resolveQuietHours({
+      quietHoursStart: '22:00',
+      quietHoursEnd: '22:00',
+    });
+    expect(resolved.window).toBeNull();
+    expect(resolved.warnings).toHaveLength(1);
+    expect(resolved.warnings[0]).toMatch(/equal pair/);
+    expect(isInQuietWindow(0, resolved.window)).toBe(false);
+  });
+
+  test('malformed-AND-identical pair is corrupt data, not an equal pair — default window + invalid warning', () => {
+    const resolved = resolveQuietHours({
+      quietHoursStart: '25:00',
+      quietHoursEnd: '25:00',
+    });
+    // FORMAT classification wins: the user keeps the protective default
+    // window instead of losing suppression entirely.
+    expect(resolved.window).toEqual(DEFAULT_QUIET_HOURS);
+    expect(resolved.warnings).toHaveLength(1);
+    expect(resolved.warnings[0]).toMatch(/invalid/);
+    expect(resolved.warnings[0]).not.toMatch(/equal pair/);
+  });
+
+  test('corrupt window and corrupt timezone warn independently', () => {
+    const resolved = resolveQuietHours({
+      quietHoursStart: 'bad',
+      quietHoursEnd: '07:00',
+      timezone: 'Nope/Nope',
+    });
+    expect(resolved.window).toEqual(DEFAULT_QUIET_HOURS);
+    expect(resolved.timezone).toBe(DEFAULT_TIMEZONE);
+    expect(resolved.warnings).toHaveLength(2);
+  });
+});
+
+describe('end-to-end: resolve + zone minutes + window (the cron gate path)', () => {
+  test('legacy user is suppressed at 3am ET and alertable at noon ET', () => {
+    const { window, timezone } = resolveQuietHours({});
+    // 2026-07-15 07:00 UTC = 03:00 EDT
+    const night = getZoneMinutes(new Date(Date.UTC(2026, 6, 15, 7, 0)), timezone);
+    // 2026-07-15 16:00 UTC = 12:00 EDT
+    const noon = getZoneMinutes(new Date(Date.UTC(2026, 6, 15, 16, 0)), timezone);
+    expect(isInQuietWindow(night, window)).toBe(true);
+    expect(isInQuietWindow(noon, window)).toBe(false);
+  });
+
+  test('legacy user default window is DST-stable at the ET wall clock (winter)', () => {
+    const { window, timezone } = resolveQuietHours({});
+    // 2026-01-15 08:00 UTC = 03:00 EST — still inside 22:00–07:00
+    const night = getZoneMinutes(new Date(Date.UTC(2026, 0, 15, 8, 0)), timezone);
+    expect(isInQuietWindow(night, window)).toBe(true);
+  });
+
+  test('Detroit user with a custom 23:00–06:00 window gets a 22:30 local alert', () => {
+    const { window, timezone } = resolveQuietHours({
+      quietHoursStart: '23:00',
+      quietHoursEnd: '06:00',
+      timezone: 'America/Detroit',
+    });
+    // 2026-07-16 02:30 UTC = 22:30 EDT in Detroit — before their window opens
+    const at2230 = getZoneMinutes(new Date(Date.UTC(2026, 6, 16, 2, 30)), timezone);
+    expect(isInQuietWindow(at2230, window)).toBe(false);
+    // 2026-07-16 03:30 UTC = 23:30 EDT — inside
+    const at2330 = getZoneMinutes(new Date(Date.UTC(2026, 6, 16, 3, 30)), timezone);
+    expect(isInQuietWindow(at2330, window)).toBe(true);
+  });
+});