Files
HealthLog/src/lib/environment/air-quality-contract.ts
T
Marc-André Bombeck 3c98d95a40 feat(environment): air quality, pollen and UV per day, locations sealed at rest
Fetch the Open-Meteo air-quality feed (CAMS, domains=auto) with the weather:
17 hourly variables folded into local days by fixed rules (means and maxima
only with 18 of 24 hours, ozone as the highest 8-hour running mean, UV only
with the midday hours), a value the feed did not cover stored as null, never
as zero. Requests are cut into 90-day chunks, newest first, and chunks before
mid 2022 ask for the eight pollutant and index variables only. An air-quality
failure never costs the weather row; the day stays unfetched and the nightly
gap fill (up to 90 days per account, newest first) asks for it again.

Every Open-Meteo request asks an instance-wide budget kept in Postgres first
(500 a minute, 4000 an hour, 8000 a day, weighted by the hosted pricing
rule). A refused request is not sent and the run ends as done with
budget_blocked. OPENMETEO_AIR_QUALITY_URL and ENVIRONMENT_AIR_QUALITY_DISABLED
are honoured; the account switch lives on PATCH /api/environment/preferences.

The home, each dated location period and each stored day keep their coarse
location sealed as one value under healthlog/environment-location/v1. The
writers write the sealed value only, the readers open it and fall back to the
readable columns for rows the free-text encryption backfill has not reached,
and the backfill now seals all three and clears the readable columns. The
backup carries the location readable in a portable file and sealed in a
disaster-recovery file; a restore seals either under the receiving key.

Three correlation channels join the environment family (PM2.5, the ozone
8-hour high, the day's highest pollen count), read through the averaged
same-day window and left empty while air quality is off. The Coach and MCP
gain get_environment: module-gated, clamped to the lookback limit, no
coordinate or place name anywhere, with provenance and the attribution
lines. The settings section gets the switch, the coverage and the newest
day's values; the dashboard shows a quiet chip on a day with high pollen,
a warm night or very poor air. Copernicus and Open-Meteo are credited next
to the values.
2026-10-08 10:02:39 +02:00

85 lines
3.0 KiB
TypeScript

/**
* The air-quality day and its attributions (v1.42, #615).
*
* One `EnvironmentContext` row carries, beside the weather, the day's air
* quality, pollen and UV from the Open-Meteo air-quality API (CAMS models).
* This is the shape every reader agrees on: the environment overview, the
* Coach and MCP read, and the day view. Every value is nullable, because a
* partial feed stores what it has and a day the feed never covered is
* absent, not zero.
*/
/** One local day of air quality, as stored and as served. */
export interface AirQualityDay {
/** Daily apparent ("feels-like") maximum, °C. */
apparentMax: number | null;
/** PM2.5 daily mean and hourly maximum, µg/m³. */
pm25Mean: number | null;
pm25Max: number | null;
/** PM10 daily mean, µg/m³. */
pm10Mean: number | null;
/** NO2, SO2 and CO daily means, µg/m³. */
no2Mean: number | null;
so2Mean: number | null;
coMean: number | null;
/** Ozone, highest 8-hour running mean of the day, µg/m³. */
o3Max8h: number | null;
/** European and US air-quality index, daily maximum. */
eaqiMax: number | null;
usaqiMax: number | null;
/** UV index, daily maximum. */
uvIndexMax: number | null;
/** Saharan dust (µg/m³) and aerosol optical depth, daily maximum. */
dustMax: number | null;
aodMax: number | null;
/** Pollen daily maxima, grains/m³; Europe only. */
pollenAlderMax: number | null;
pollenBirchMax: number | null;
pollenGrassMax: number | null;
pollenMugwortMax: number | null;
pollenOliveMax: number | null;
pollenRagweedMax: number | null;
/** Which model domain served the day, e.g. `cams_europe`. */
aqDomain: string | null;
/** Hourly samples the day was aggregated from. */
aqHours: number | null;
/** When the air-quality part was fetched, ISO-8601; null = not yet. */
aqFetchedAt: string | null;
}
/** Who the values come from, shown wherever they are shown. */
export const AIR_QUALITY_ATTRIBUTIONS = [
{
key: "cams",
name: "Copernicus Atmosphere Monitoring Service (CAMS)",
url: "https://atmosphere.copernicus.eu/",
},
{
key: "open-meteo",
name: "Open-Meteo",
url: "https://open-meteo.com/",
},
] as const;
/**
* The attribution lines, in display order, for wherever environment values
* are shown (settings, the Coach and MCP read, the docs). The weather line
* always; the two air-quality lines when air-quality values are part of what
* is shown. "Contains modified" because hourly values are folded into days
* here (the Copernicus licence asks for that wording on derived data); the
* year is the newest year the shown values come from.
*/
export function environmentAttributionLines(args: {
airQuality: boolean;
year: number;
}): string[] {
const lines = ["Weather data by Open-Meteo.com (CC BY 4.0)"];
if (args.airQuality) {
lines.push(
"Air quality data by Open-Meteo.com (CC BY 4.0)",
`Contains modified Copernicus Atmosphere Monitoring Service information ${args.year}`,
);
}
return lines;
}