feat(environment): add opt-in module, settings surface, API, and nightly fetch

Add the opt-in Environment module (default off), its Settings surface (home
location search, travel overrides, backfill, with Open-Meteo attribution), the
gated API routes (overview, home, geocode, travel CRUD, backfill), the nightly
pg-boss fetch job with a lookback window plus on-demand backfill, the query
keys, six-locale strings, and the regenerated OpenAPI. The module performs an
outbound weather fetch tied to a coarse location, so it ships dark and the user
turns it on deliberately; off means no job, no row, no egress.
This commit is contained in:
Marc-André Bombeck committed 2026-06-28 16:58:52 +02:00
1 parent cdee3e3efc
commit 088cad6c64
30 files changed
+1537 -2

No files matched your search

@@ -83,6 +83,7 @@ function moduleMap(
insights: true,
medications: true,
doctorReport: true,
environment: true,
mcp: true,
};
return { ...base, ...overrides };
+185
View File
@@ -0,0 +1,185 @@
/**
* v1.25 (W-ENV) — nightly environmental-context fetch.
*
* For every account with the environmental-context module enabled AND a home
* location set, fetch the daily weather/daylight for the recent uncovered days
* and upsert into `EnvironmentContext`. A daily discovery tick (empty payload)
* fans out one per-user job; the per-user job resolves each day's location
* (travel override → home) and fetches a lookback window so the archive feed's
* settling lag (a few days) is absorbed and any day missed across worker
* reboots is re-attempted. The same handler also serves the on-demand backfill
* (an explicit `{ userId, startDate, endDate }` payload from the settings
* surface).
*
* Opt-in + privacy: the discovery filter requires both the module flag and a
* home location, so a disabled account never triggers an outbound fetch. Egress
* runs through `safeFetch` inside the Open-Meteo client. Recurring → pg-boss
* (never a CLI script; the prod image strips `tsx`).
*/
import { prisma } from "@/lib/db";
import type { PgBoss } from "pg-boss";
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { isModuleEnabled } from "@/lib/modules/gate";
import {
ENVIRONMENT_LOOKBACK_DAYS,
ENVIRONMENT_MAX_BACKFILL_DAYS,
fetchAndStoreEnvironment,
utcDayKey,
} from "@/lib/environment/service";
import { recordError } from "@/lib/jobs/worker-status";
import { workerLog } from "./reminder/shared";
export const ENVIRONMENT_FETCH_QUEUE = "environment-fetch";
/** Daily 02:10 Europe/Berlin — early, before the 02:30+ maintenance window so
* the night's weather rows exist before any briefing/insight pre-gen reads. */
export const ENVIRONMENT_FETCH_CRON = "10 2 * * *";
export const ENVIRONMENT_FETCH_CONCURRENCY = 1;
const MS_PER_DAY = 24 * 60 * 60 * 1000;
/**
* Per-user fetch payload. An empty payload (no `userId`) is the daily discovery
* tick. `startDate`/`endDate` (YYYY-MM-DD) drive the on-demand backfill; omitted
* ⇒ the default lookback window ending today.
*/
export interface EnvironmentFetchPayload {
userId?: string;
startDate?: string;
endDate?: string;
}
/** Resolve the date range for a per-user run (explicit range, else lookback). */
function resolveRange(payload: EnvironmentFetchPayload): {
startDate: string;
endDate: string;
} {
const today = new Date();
const endDate = payload.endDate ?? utcDayKey(today);
const startDate =
payload.startDate ??
utcDayKey(
new Date(today.getTime() - ENVIRONMENT_LOOKBACK_DAYS * MS_PER_DAY),
);
return { startDate, endDate };
}
/**
* Request-side enqueue for a single account: a default-lookback refresh (after
* the user sets/changes their home, so weather appears without waiting for the
* nightly tick) or an explicit-range backfill. No-ops cleanly when no global
* boss is bound (e.g. a web-only deployment) — the nightly cron still covers it.
* The lookback variant is singleton-coalesced per user; an explicit backfill
* range is NOT coalesced so it always runs.
*/
export async function enqueueEnvironmentFetch(
payload: EnvironmentFetchPayload & { userId: string },
): Promise<boolean> {
const boss = getGlobalBoss();
if (!boss) return false;
const options =
payload.startDate || payload.endDate
? undefined
: { singletonKey: `environment-fetch:${payload.userId}` };
await boss.send(ENVIRONMENT_FETCH_QUEUE, payload, options);
return true;
}
/**
* Discovery fan-out: enqueue one per-user fetch job for every account with the
* module on and a home location set. Idempotent (singletonKey-coalesced per
* user). Returns counts for the worker log.
*/
export async function enqueueEnvironmentFetchDiscovery(
boss: PgBoss,
): Promise<{ enqueued: number; skipped: number }> {
// Candidate set: a home location is required for any non-override day, so an
// account without one cannot produce a row. The per-candidate module check
// then enforces the opt-in flag + operator availability.
const candidates = await prisma.user.findMany({
where: { homeLat: { not: null }, homeLon: { not: null } },
select: { id: true },
});
let enqueued = 0;
let skipped = 0;
for (const { id } of candidates) {
if (!(await isModuleEnabled(id, "environment"))) {
skipped += 1;
continue;
}
await boss.send(
ENVIRONMENT_FETCH_QUEUE,
{ userId: id } satisfies EnvironmentFetchPayload,
{ singletonKey: `environment-fetch:${id}` },
);
enqueued += 1;
}
return { enqueued, skipped };
}
/**
* The queue handler. Empty payload ⇒ discovery fan-out; a `userId` payload ⇒
* fetch + upsert for that user across the resolved range. Re-checks the module
* gate on the per-user path so a backfill enqueued just before the user
* disabled the module is a no-op.
*/
export async function handleEnvironmentFetch(
boss: PgBoss,
payload: EnvironmentFetchPayload,
): Promise<void> {
if (!payload.userId) {
const { enqueued, skipped } = await enqueueEnvironmentFetchDiscovery(boss);
workerLog(
"info",
`[environment-fetch] discovery enqueued=${enqueued} skipped=${skipped}`,
);
return;
}
const userId = payload.userId;
if (!(await isModuleEnabled(userId, "environment"))) {
workerLog(
"info",
`[environment-fetch] user=${userId} module disabled — skipping`,
);
return;
}
const { startDate, endDate } = resolveRange(payload);
// Clamp the span so a crafted backfill can never fan out an unbounded range.
const span = enumerateSpanDays(startDate, endDate);
if (span > ENVIRONMENT_MAX_BACKFILL_DAYS) {
workerLog(
"error",
`[environment-fetch] user=${userId} range ${startDate}..${endDate} (${span}d) exceeds cap — skipping`,
);
return;
}
try {
const result = await fetchAndStoreEnvironment({
userId,
startDate,
endDate,
});
workerLog(
"info",
`[environment-fetch] user=${userId} ${startDate}..${endDate} stored=${result.stored} skipped=${result.skipped} fetches=${result.fetches}`,
);
} catch (err) {
recordError();
workerLog("error", `[environment-fetch] user=${userId} failed`, err);
throw err;
}
}
function enumerateSpanDays(start: string, end: string): number {
const [sy, sm, sd] = start.split("-").map(Number);
const [ey, em, ed] = end.split("-").map(Number);
const days = Math.round(
(Date.UTC(ey, em - 1, ed) - Date.UTC(sy, sm - 1, sd)) / MS_PER_DAY,
);
return days + 1;
}
@@ -75,6 +75,13 @@ import {
handleEncryptionKeyRotate,
type EncryptionKeyRotatePayload,
} from "@/lib/jobs/encryption-key-rotate";
import {
ENVIRONMENT_FETCH_QUEUE,
ENVIRONMENT_FETCH_CRON,
ENVIRONMENT_FETCH_CONCURRENCY,
handleEnvironmentFetch,
type EnvironmentFetchPayload,
} from "@/lib/jobs/environment-fetch";
import { recordError } from "@/lib/jobs/worker-status";
import { workerLog, BOOT_BACKFILL_STAGGER_SECONDS } from "./shared";
import { createAndSchedule, type ScheduleEntry } from "./registrar-shared";
@@ -216,6 +223,12 @@ const MCP_TOKEN_CLEANUP_CRON = "0 4 * * *";
const MED_NOTES_ENCRYPTION_BACKFILL_CRON = "5 4 * * *";
const allQueues = [
// v1.25 (W-ENV) — nightly environmental-context fetch. A daily discovery tick
// fans out one per-user job per opted-in account with a home location; the
// queue also serves the on-demand backfill from the Environment settings
// surface. Without this entry pg-boss never provisions it and both the cron
// and the backfill button silently no-op.
ENVIRONMENT_FETCH_QUEUE,
DATA_BACKUP_QUEUE,
RATE_LIMIT_CLEANUP_QUEUE,
IDEMPOTENCY_CLEANUP_QUEUE,
@@ -277,6 +290,9 @@ const allQueues = [
];
const schedules: ScheduleEntry[] = [
// v1.25 (W-ENV) — daily 02:10 Europe/Berlin discovery tick (empty payload)
// that fans out one per-user environment fetch per opted-in account.
[ENVIRONMENT_FETCH_QUEUE, ENVIRONMENT_FETCH_CRON],
[DATA_BACKUP_QUEUE, DATA_BACKUP_CRON],
[RATE_LIMIT_CLEANUP_QUEUE, RATE_LIMIT_CLEANUP_CRON],
[IDEMPOTENCY_CLEANUP_QUEUE, IDEMPOTENCY_CLEANUP_CRON],
@@ -601,6 +617,20 @@ export async function registerMaintenanceQueues(
},
);
// v1.25 (W-ENV) — nightly environment fetch. The daily discovery tick (empty
// payload) fans out one per-user job per opted-in account; the queue also
// serves the on-demand backfill payloads from the settings surface. Serial
// concurrency so the staggered outbound fetches never crowd the request pool.
await boss.work<EnvironmentFetchPayload>(
ENVIRONMENT_FETCH_QUEUE,
{ localConcurrency: ENVIRONMENT_FETCH_CONCURRENCY },
async (jobs) => {
for (const job of jobs) {
await handleEnvironmentFetch(boss, job.data);
}
},
);
return allQueues;
}
+7 -2
View File
@@ -352,10 +352,15 @@ describe("resolveModuleEnabled — mcp module (opt-in, default-OFF)", () => {
});
describe("registry — opt-in marker", () => {
it("marks only the mcp module opt-in (every other module is default-on)", () => {
it("marks the mcp + environment modules opt-in (every other module is default-on)", () => {
expect(isOptInModule("mcp")).toBe(true);
// v1.25 (W-ENV) — the environmental-context module is opt-in too: it
// performs an outbound weather fetch tied to a coarse location, so it ships
// dark like the remote MCP endpoint.
expect(isOptInModule("environment")).toBe(true);
const optIn = new Set(["mcp", "environment"]);
for (const key of MODULE_KEYS) {
if (key === "mcp") continue;
if (optIn.has(key)) continue;
expect(isOptInModule(key)).toBe(false);
}
});
+17
View File
@@ -115,6 +115,12 @@ export const MODULE_KEYS = [
// re-enabling finds the rows intact.
"medications",
"doctorReport",
// v1.25.0 (W-ENV) — environmental-context module. Like `mcp`, it is OPT-IN
// (off by default): it performs an outbound weather fetch tied to where the
// user physically is (a coarse home / travel location), so opt-in is the
// right privacy default. With it off no job runs, no row is written, and no
// egress happens. The `optIn` marker inverts the per-user default.
"environment",
// v1.22.0 — the remote Model Context Protocol endpoint (`/mcp`). Unlike
// every other module this is OPT-IN (off by default): it exposes a new
// external-assistant attack surface, so it ships dark and the operator /
@@ -256,6 +262,17 @@ export const MODULE_REGISTRY: Readonly<Record<ModuleKey, ModuleDefinition>> =
descriptionKey: "modules.doctorReport.description",
category: "export",
},
environment: {
key: "environment",
labelKey: "modules.environment.label",
descriptionKey: "modules.environment.description",
category: "device",
// Off by default: performs an outbound weather fetch tied to a coarse
// location, so it ships dark and the user turns it on deliberately. The
// home location + travel overrides + backfill live on the dedicated
// Environment settings surface (rendered when the module is on).
optIn: true,
},
mcp: {
key: "mcp",
labelKey: "modules.mcp.label",
+16
View File
@@ -0,0 +1,16 @@
/**
* Query keys — environmental-context module (v1.25, W-ENV). The overview
* (home + travel overrides + stored-day summary) and the geocoding search.
* Part of the centralized factory; aggregated in `./index.ts`.
*/
export const environmentKeys = {
/**
* `environment()` is the root prefix every environment write (set home, add /
* remove a travel override, trigger a backfill) invalidates through, so the
* settings surface repaints in lockstep.
*/
environment: () => ["environment"] as const,
/** Geocoding search results for a query string (cached per query). */
environmentGeocode: (query: string) =>
["environment", "geocode", query] as const,
};
+2
View File
@@ -21,6 +21,7 @@ import { coachKeys } from "./coach";
import { familyHistoryKeys } from "./family-history";
import { cycleKeys } from "./cycle";
import { dashboardKeys } from "./dashboard";
import { environmentKeys } from "./environment";
import { illnessKeys } from "./illness";
import { insightsKeys } from "./insights";
import { integrationKeys } from "./integrations";
@@ -52,6 +53,7 @@ export const queryKeys = {
...mentalHealthKeys,
...allergyKeys,
...familyHistoryKeys,
...environmentKeys,
};
/**
+70
View File
@@ -0,0 +1,70 @@
/**
* v1.25 (W-ENV) — environmental-context request validation.
*
* The home location, the travel overrides, and the backfill span. Coordinates
* are bounded to valid lat/lon; the labels are length-capped plaintext (a city
* name, never a quasi-identifier). Dates are strict YYYY-MM-DD. The shared
* shapes are reused by the OpenAPI registry so the wire contract stays
* single-source.
*/
import { z } from "zod/v4";
/** Strict YYYY-MM-DD calendar day. */
export const dayStringSchema = z
.string()
.regex(/^\d{4}-\d{2}-\d{2}$/, "Expected a YYYY-MM-DD date");
const latSchema = z.number().gte(-90).lte(90);
const lonSchema = z.number().gte(-180).lte(180);
const labelSchema = z.string().trim().min(1).max(200);
/** A coarse home location set in settings (city-level granularity). */
export const homeLocationSchema = z
.object({
lat: latSchema,
lon: lonSchema,
label: labelSchema,
/** IANA timezone (anchors the stored day-key). */
timezone: z.string().trim().min(1).max(64),
})
.strict();
export type HomeLocationInput = z.infer<typeof homeLocationSchema>;
/** A manual travel override covering an inclusive date range. */
export const travelLocationSchema = z
.object({
startDate: dayStringSchema,
endDate: dayStringSchema,
lat: latSchema,
lon: lonSchema,
label: labelSchema,
})
.strict()
.refine((v) => v.startDate <= v.endDate, {
message: "startDate must be on or before endDate",
path: ["endDate"],
});
export type TravelLocationInput = z.infer<typeof travelLocationSchema>;
/** A backfill request: fetch + store the environment rows over a date range. */
export const environmentBackfillSchema = z
.object({
startDate: dayStringSchema,
endDate: dayStringSchema,
})
.strict()
.refine((v) => v.startDate <= v.endDate, {
message: "startDate must be on or before endDate",
path: ["endDate"],
});
export type EnvironmentBackfillInput = z.infer<
typeof environmentBackfillSchema
>;
/** Geocoding search query (`?q=`). */
export const geocodeQuerySchema = z
.object({ q: z.string().trim().min(1).max(120) })
.strict();