src/ops-packages.ts

Functions

Imports

It imports src/env.ts, src/github/client.ts, src/log.ts, src/ops-types/sites.ts, src/store-guards.ts, src/time.ts. Imported by src/controls-perform.ts, src/controls-plan.ts, src/job-fact-check.ts, src/ops-feed.ts, src/portal-packages.ts, src/shared-code.ts, src/watcher-gather.ts, src/watcher.ts.

Source

1import type { Env } from "./env";
2import { ghFetch } from "./github/client";
3import type { OpsPackageConfig, PackageSnapshot, PortalPackageHistory } from "./ops-types/sites";
4import { auditStatement } from "./store-guards";
5import { logEvent } from "./log";
6import { DAY_MS } from "./time";
7
8// The packages Capsid Portal watches (job_c6e4ab939a54). Ruled 2026-09-29: "Portal monitoring is optional and configured per install; packages panel
9// approved". Configured like the sites (src/ops-sites.ts): rows in D1 (ops_packages,
10// migrations/0028) edited in the Portal's Settings view through the same preview and
11// perform. With no row, the watcher reads nothing for packages and the Portal hides the
12// Packages view.
13//
14// Every source below was checked against its own documentation on 2026-09-30, and the
15// response shapes against the live endpoints:
16//   registry.npmjs.org/<name> with Accept: application/vnd.npm.install-v1+json, the
17//     abbreviated document: dist-tags, versions, modified; no time object
18//     (github.com/npm/registry, docs/responses/package-metadata.md).
19//   api.npmjs.org/downloads/point/{last-week,last-month}/<name> and
20//     /downloads/range/<start>:<end>/<name>: "at most 18 months of data" per query
21//     (the API moves a longer range's start forward rather than refusing it), counted
22//     "daily after UTC midnight", nothing before 2015-01-10. A package npm has no counts
23//     for yet answers 404 "not found", which is zero, not a failure. /versions/<name>/
24//     last-week is per version for the last 7 days and nothing else
25//     (docs/download-counts.md). No rate limit is published for either host; npm has
26//     said anonymous callers may see 429.
27//   api.deps.dev/v3/systems/npm/packages/<name> for the default version, then
28//     /v3alpha/.../versions/<v>:dependents: counts of "distinct packages known to depend
29//     on a given package version, either directly or indirectly", "indicative of
30//     relative popularity rather than precisely accurate", and an alpha endpoint that
31//     "may change". It returns counts, not a list: no documented public API lists an
32//     npm package's dependents, and GitHub has no API for "Used by". So the panel links
33//     to npmjs.com's and deps.dev's pages for the list rather than inventing one.
34//   GitHub, through the App: stars and open_issues_count from /repos/<o>/<r> (which
35//     counts pull requests as issues, so the open pull requests are subtracted), open
36//     pull requests from /pulls?state=open (one page of 100: more is reported as 100
37//     and marked capped), the latest release from /releases/latest (404 when none).
38
39const PACKAGE_ROWS_LIMIT = 50;
40const FETCH_TIMEOUT_MS = 8000;
41const USER_AGENT = "capsid-watcher (packages; https://github.com/DrDustinEdwards/capsid)";
42// Under npm's 18-month cap on one range query, so no query is silently shortened.
43const RANGE_CHUNK_DAYS = 540;
44const NPM_FIRST_DAY = "2015-01-10";
45// The daily history is fetched on demand and kept this long.
46const HISTORY_TTL_SECONDS = 6 * 60 * 60;
47export const historyKey = (name: string) => `packages:history:v1:${name}`;
48
49export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
50
51// ---- Configuration ----------------------------------------------------------------------
52
53interface PackageRow {
54  name: string;
55  registry: string;
56  repo: string | null;
57  formerly: string | null;
58  revision: number;
59  updated_at: string;
60}
61
62const PACKAGE_COLUMNS = "name, registry, repo, formerly, revision, updated_at";
63
64function configFrom(row: PackageRow): OpsPackageConfig {
65  return { name: row.name, registry: "npm", repo: row.repo, formerly: row.formerly, revision: row.revision, updated_at: row.updated_at };
66}
67
68/** Every configured package, by name. */
69export async function readPackageConfig(db: D1Database): Promise<OpsPackageConfig[]> {
70  const { results } = await db.prepare(`SELECT ${PACKAGE_COLUMNS} FROM ops_packages ORDER BY name LIMIT ?1`).bind(PACKAGE_ROWS_LIMIT).all<PackageRow>();
71  return (results ?? []).map(configFrom);
72}
73
74/** One row, or null. */
75export async function readPackageRow(db: D1Database, name: string): Promise<OpsPackageConfig | null> {
76  const row = await db.prepare(`SELECT ${PACKAGE_COLUMNS} FROM ops_packages WHERE name = ?1`).bind(name).first<PackageRow>();
77  return row ? configFrom(row) : null;
78}
79
80export interface PackageInput {
81  name: string;
82  repo: string | null;
83  formerly: string | null;
84}
85
86// npm's rules for a new name: at most 214 characters, lowercase, URL-safe, a scope only
87// as @scope/name, and no leading dot or underscore.
88const UNSCOPED = /^[a-z0-9-~][a-z0-9-._~]*$/;
89const SCOPED = /^@[a-z0-9-~][a-z0-9-._~]*\/[a-z0-9-~][a-z0-9-._~]*$/;
90const REPO_SHAPE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\/[A-Za-z0-9._-]{1,100}$/;
91
92function nameRefusal(field: string, value: string): string | null {
93  if (value.length > 214) return `${field} is longer than npm's 214 characters.`;
94  if (!UNSCOPED.test(value) && !SCOPED.test(value)) return `${field} '${value}' is not an npm package name: lowercase letters, digits and - . _ ~, or @scope/name.`;
95  return null;
96}
97
98export type ValidatedPackage = { ok: true; pkg: PackageInput } | { ok: false; refusal: string };
99
100export function validatePackage(p: Record<string, string | undefined>): ValidatedPackage {
101  const name = (p.name ?? "").trim();
102  if (!name) return { ok: false, refusal: "a package needs its npm name." };
103  const bad = nameRefusal("the name", name);
104  if (bad) return { ok: false, refusal: bad };
105  const repo = (p.repo ?? "").trim() || null;
106  if (repo !== null && !REPO_SHAPE.test(repo)) return { ok: false, refusal: `the repository '${repo}' is not owner/name on GitHub.` };
107  const formerly = (p.formerly ?? "").trim() || null;
108  if (formerly !== null) {
109    const badFormer = nameRefusal("the former name", formerly);
110    if (badFormer) return { ok: false, refusal: badFormer };
111    if (formerly === name) return { ok: false, refusal: "the former name is the name itself." };
112  }
113  return { ok: true, pkg: { name, repo, formerly } };
114}
115
116export function describePackage(p: PackageInput): string {
117  return `npm "${p.name}"${p.repo ? `, repository ${p.repo}` : ", no repository"}${p.formerly ? `, formerly "${p.formerly}"` : ""}`;
118}
119
120export type PackageResult = { ok: true; pkg: OpsPackageConfig } | { ok: false; refusal: string };
121
122/** Add a row. A package already configured is refused, not replaced. */
123export async function addPackage(db: D1Database, actor: string, p: PackageInput): Promise<PackageResult> {
124  const won = await db
125    .prepare("INSERT INTO ops_packages (name, repo, formerly) VALUES (?1, ?2, ?3) ON CONFLICT(name) DO NOTHING RETURNING name")
126    .bind(p.name, p.repo, p.formerly)
127    .first<{ name: string }>();
128  if (!won) return { ok: false, refusal: `${p.name} is already configured. Edit it instead.` };
129  const after = await readPackageRow(db, p.name);
130  if (!after) return { ok: false, refusal: `${p.name} was added and then removed before it could be read back.` };
131  await db.batch([auditStatement(db, actor, "ops-package-added", null, null, { after })]);
132  return { ok: true, pkg: after };
133}
134
135/** Replace a row's fields, only if it is still at `revision`. */
136export async function editPackage(db: D1Database, actor: string, p: PackageInput, revision: number): Promise<PackageResult> {
137  const before = await readPackageRow(db, p.name);
138  if (!before) return { ok: false, refusal: `${p.name} is not configured. Add it instead.` };
139  const won = await db
140    .prepare(
141      `UPDATE ops_packages SET repo = ?3, formerly = ?4, revision = revision + 1, updated_at = datetime('now')
142       WHERE name = ?1 AND revision = ?2 RETURNING revision`
143    )
144    .bind(p.name, revision, p.repo, p.formerly)
145    .first<{ revision: number }>();
146  if (!won) return { ok: false, refusal: `${p.name} changed since the preview (it is at revision ${before.revision}, the preview read ${revision}). Preview again.` };
147  const after = await readPackageRow(db, p.name);
148  if (!after) return { ok: false, refusal: `${p.name} was edited and then removed before it could be read back.` };
149  await db.batch([auditStatement(db, actor, "ops-package-edited", null, null, { before, after })]);
150  // A changed name source makes the cached history wrong; the next view refetches.
151  return { ok: true, pkg: after };
152}
153
154/** Remove a row, only if it is still at `revision`. Its weekly rows stay, as history. */
155export async function removePackage(db: D1Database, actor: string, name: string, revision: number): Promise<PackageResult> {
156  const before = await readPackageRow(db, name);
157  if (!before) return { ok: false, refusal: `${name} is not configured.` };
158  const won = await db.prepare("DELETE FROM ops_packages WHERE name = ?1 AND revision = ?2 RETURNING name").bind(name, revision).first<{ name: string }>();
159  if (!won) return { ok: false, refusal: `${name} changed since the preview (it is at revision ${before.revision}, the preview read ${revision}). Preview again.` };
160  await db.batch([auditStatement(db, actor, "ops-package-removed", null, null, { before })]);
161  return { ok: true, pkg: before };
162}
163
164// ---- Reading a package, once per watcher pass ------------------------------------------
165
166// A scoped name travels in a path with its slash escaped, which the registry and the
167// per-version endpoint require and the download counts accept.
168const pathName = (name: string) => name.replace("/", "%2F");
169
170type Got = { ok: true; status: number; json: unknown } | { ok: false; status: number | null; reason: string };
171
172async function getJson(fetchImpl: FetchLike, url: string, accept = "application/json"): Promise<Got> {
173  try {
174    const res = await fetchImpl(url, { headers: { "User-Agent": USER_AGENT, Accept: accept }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
175    if (!res.ok) {
176      await res.body?.cancel();
177      return { ok: false, status: res.status, reason: `${new URL(url).host} answered ${res.status}` };
178    }
179    return { ok: true, status: res.status, json: await res.json() };
180  } catch (err) {
181    return { ok: false, status: null, reason: `${new URL(url).host} could not be read: ${(err instanceof Error ? err.message : String(err)).slice(0, 160)}` };
182  }
183}
184
185const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
186
187/** The versions npm has published for `name`, or null when npm has no such package. A
188 *  failed read throws, so a caller cannot read it as "not published". For a blocked
189 *  job's "check: npm <name>@<version>" line (src/manual-steps.ts) and the job body fact
190 *  check (src/job-fact-check.ts). */
191export async function npmVersions(fetchImpl: FetchLike, name: string): Promise<string[] | null> {
192  const got = await getJson(fetchImpl, `https://registry.npmjs.org/${pathName(name)}`, "application/vnd.npm.install-v1+json");
193  if (!got.ok) {
194    if (got.status === 404) return null;
195    throw new Error(got.reason);
196  }
197  return Object.keys((got.json as { versions?: Record<string, unknown> }).versions ?? {});
198}
199
200// Also read by the Shared code view (src/shared-code.ts), for each shared package that is
201// not private, so it can say whether the version in the repo has reached npm.
202export async function readNpm(fetchImpl: FetchLike, name: string): Promise<PackageSnapshot["npm"]> {
203  const got = await getJson(fetchImpl, `https://registry.npmjs.org/${pathName(name)}`, "application/vnd.npm.install-v1+json");
204  if (!got.ok) return got.status === 404 ? { state: "none", reason: `npm has no package ${name}` } : { state: "error", reason: got.reason };
205  const doc = got.json as { "dist-tags"?: Record<string, unknown>; versions?: Record<string, unknown>; modified?: unknown };
206  const tags = Object.fromEntries(Object.entries(doc["dist-tags"] ?? {}).filter((e): e is [string, string] => typeof e[1] === "string"));
207  return {
208    state: "ok",
209    latest: tags.latest ?? null,
210    dist_tags: tags,
211    versions: Object.keys(doc.versions ?? {}).length,
212    modified: typeof doc.modified === "string" ? doc.modified : null,
213  };
214}
215
216async function readDownloads(fetchImpl: FetchLike, name: string): Promise<PackageSnapshot["downloads"]> {
217  const point = async (period: string) => {
218    const got = await getJson(fetchImpl, `https://api.npmjs.org/downloads/point/${period}/${name}`);
219    // No counts yet is zero downloads, not a failure (npm answers 404 "not found").
220    if (!got.ok) return got.status === 404 ? { downloads: 0, end: null } : got.reason;
221    const body = got.json as { downloads?: unknown; end?: unknown };
222    const downloads = num(body.downloads);
223    return downloads === null ? `api.npmjs.org sent no count for ${period}` : { downloads, end: typeof body.end === "string" ? body.end : null };
224  };
225  const week = await point("last-week");
226  if (typeof week === "string") return { state: "error", reason: week };
227  const month = await point("last-month");
228  if (typeof month === "string") return { state: "error", reason: month };
229  const byVersion: Record<string, number> = {};
230  const versions = await getJson(fetchImpl, `https://api.npmjs.org/versions/${pathName(name)}/last-week`);
231  if (versions.ok) {
232    for (const [v, n] of Object.entries((versions.json as { downloads?: Record<string, unknown> }).downloads ?? {})) {
233      const count = num(n);
234      if (count !== null) byVersion[v] = count;
235    }
236  } else if (versions.status !== 404) {
237    return { state: "error", reason: versions.reason };
238  }
239  return { state: "ok", last_week: week.downloads, last_month: month.downloads, through: week.end ?? month.end, by_version_last_week: byVersion };
240}
241
242async function readDependents(fetchImpl: FetchLike, name: string): Promise<PackageSnapshot["dependents"]> {
243  const pkg = await getJson(fetchImpl, `https://api.deps.dev/v3/systems/npm/packages/${encodeURIComponent(name)}`);
244  if (!pkg.ok) return pkg.status === 404 ? { state: "none", reason: `deps.dev has no record of ${name} yet` } : { state: "error", reason: pkg.reason };
245  const versions = (pkg.json as { versions?: Array<{ versionKey?: { version?: unknown }; isDefault?: unknown }> }).versions ?? [];
246  const chosen = versions.find((v) => v.isDefault === true)?.versionKey?.version;
247  if (typeof chosen !== "string") return { state: "none", reason: `deps.dev names no default version of ${name}` };
248  const got = await getJson(fetchImpl, `https://api.deps.dev/v3alpha/systems/npm/packages/${encodeURIComponent(name)}/versions/${encodeURIComponent(chosen)}:dependents`);
249  // deps.dev answers 404 "dependents not found" for a version nothing depends on.
250  if (!got.ok) return got.status === 404 ? { state: "none", reason: `deps.dev knows no package that depends on ${name}@${chosen}` } : { state: "error", reason: got.reason };
251  const c = got.json as { dependentCount?: unknown; directDependentCount?: unknown; indirectDependentCount?: unknown };
252  const total = num(c.dependentCount);
253  if (total === null) return { state: "error", reason: "deps.dev sent no dependentCount" };
254  return { state: "ok", version: chosen, direct: num(c.directDependentCount) ?? 0, indirect: num(c.indirectDependentCount) ?? 0, total };
255}
256
257async function ghJson(env: Env, owner: string, repo: string, path: string): Promise<Got> {
258  try {
259    const res = await ghFetch(env, owner, repo, path);
260    if (!res.ok) {
261      await res.body?.cancel();
262      return { ok: false, status: res.status, reason: `GitHub answered ${res.status} for ${path}` };
263    }
264    return { ok: true, status: res.status, json: await res.json() };
265  } catch (err) {
266    return { ok: false, status: null, reason: `GitHub could not be read: ${(err instanceof Error ? err.message : String(err)).slice(0, 160)}` };
267  }
268}
269
270async function readGithub(env: Env, repo: string | null): Promise<PackageSnapshot["github"]> {
271  if (!repo) return { state: "none", reason: "no repository is configured for this package" };
272  const [owner, name] = repo.split("/");
273  const r = await ghJson(env, owner, name, `/repos/${owner}/${name}`);
274  if (!r.ok) return { state: "error", reason: r.reason };
275  const info = r.json as { stargazers_count?: unknown; open_issues_count?: unknown };
276  const pulls = await ghJson(env, owner, name, `/repos/${owner}/${name}/pulls?state=open&per_page=100`);
277  if (!pulls.ok) return { state: "error", reason: pulls.reason };
278  const openPrs = Array.isArray(pulls.json) ? pulls.json.length : 0;
279  const release = await ghJson(env, owner, name, `/repos/${owner}/${name}/releases/latest`);
280  if (!release.ok && release.status !== 404) return { state: "error", reason: release.reason };
281  const rel = release.ok ? (release.json as { tag_name?: unknown; published_at?: unknown }) : null;
282  const openIssuesAndPrs = num(info.open_issues_count) ?? 0;
283  return {
284    state: "ok",
285    repo,
286    stars: num(info.stargazers_count) ?? 0,
287    // GitHub's open_issues_count includes open pull requests.
288    open_issues: Math.max(0, openIssuesAndPrs - openPrs),
289    open_prs: openPrs,
290    open_prs_capped: openPrs >= 100,
291    latest_release: rel && typeof rel.tag_name === "string" ? { tag: rel.tag_name, published_at: typeof rel.published_at === "string" ? rel.published_at : null } : null,
292  };
293}
294
295/** One package, as one watcher pass reads it: nine requests at most, sequential, each
296 *  failing on its own so one unreachable source does not blank the others. */
297export async function readPackage(env: Env, cfg: OpsPackageConfig, fetchImpl: FetchLike, now: Date): Promise<PackageSnapshot> {
298  return {
299    name: cfg.name,
300    registry: "npm",
301    at: now.toISOString(),
302    npm: await readNpm(fetchImpl, cfg.name),
303    downloads: await readDownloads(fetchImpl, cfg.name),
304    dependents: await readDependents(fetchImpl, cfg.name),
305    github: await readGithub(env, cfg.repo),
306  };
307}
308
309/** "2026-W40": the ISO 8601 week `d` falls in. */
310export function isoWeek(d: Date): string {
311  const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
312  const day = t.getUTCDay() || 7;
313  t.setUTCDate(t.getUTCDate() + 4 - day);
314  const yearStart = Date.UTC(t.getUTCFullYear(), 0, 1);
315  const week = Math.ceil(((t.getTime() - yearStart) / DAY_MS + 1) / 7);
316  return `${t.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
317}
318
319/** The week's GitHub numbers, written once: the first pass of each ISO week that read
320 *  the repository keeps its row, and later passes that week change nothing. */
321export function weekStatement(db: D1Database, snap: PackageSnapshot, now: Date): D1PreparedStatement | null {
322  const g = snap.github;
323  if (g.state !== "ok") return null;
324  return db
325    .prepare(
326      `INSERT INTO ops_package_weeks (name, week, repo, stars, open_issues, open_prs, latest_release)
327       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) ON CONFLICT (name, week) DO NOTHING`
328    )
329    .bind(snap.name, isoWeek(now), g.repo, g.stars, g.open_issues, g.open_prs, g.latest_release?.tag ?? null);
330}
331
332// ---- The daily history, on demand ------------------------------------------------------
333
334const dayOf = (d: Date) => d.toISOString().slice(0, 10);
335
336/** When npm first published `name`, from the full document's time.created (the
337 *  abbreviated one has no time object). An unpublished package keeps its document and
338 *  its created time, so a former name still has a start. */
339async function firstPublished(fetchImpl: FetchLike, name: string): Promise<string | null> {
340  const got = await getJson(fetchImpl, `https://registry.npmjs.org/${pathName(name)}`);
341  if (!got.ok) return null;
342  const created = (got.json as { time?: { created?: unknown } }).time?.created;
343  return typeof created === "string" ? created.slice(0, 10) : null;
344}
345
346/** The ranges, oldest first, that cover `from` to `to` in chunks npm will not shorten. */
347export function historyRanges(from: string, to: string): Array<[string, string]> {
348  const out: Array<[string, string]> = [];
349  let start = new Date(`${from}T00:00:00Z`);
350  const end = new Date(`${to}T00:00:00Z`);
351  while (start <= end) {
352    const chunkEnd = new Date(Math.min(start.getTime() + (RANGE_CHUNK_DAYS - 1) * DAY_MS, end.getTime()));
353    out.push([dayOf(start), dayOf(chunkEnd)]);
354    start = new Date(chunkEnd.getTime() + DAY_MS);
355  }
356  return out;
357}
358
359async function dailyDownloads(fetchImpl: FetchLike, name: string, now: Date, notes: string[]): Promise<Array<{ day: string; downloads: number; name: string }>> {
360  const first = await firstPublished(fetchImpl, name);
361  if (!first) notes.push(`npm did not say when ${name} was first published, so its history is read from ${NPM_FIRST_DAY}, the first day npm counted.`);
362  const from = first && first > NPM_FIRST_DAY ? first : NPM_FIRST_DAY;
363  // npm counts each day after UTC midnight; yesterday is the newest it may have.
364  const to = dayOf(new Date(now.getTime() - DAY_MS));
365  const days: Array<{ day: string; downloads: number; name: string }> = [];
366  for (const [a, b] of historyRanges(from, to)) {
367    const got = await getJson(fetchImpl, `https://api.npmjs.org/downloads/range/${a}:${b}/${name}`);
368    if (!got.ok) {
369      if (got.status !== 404) notes.push(`${name}, ${a} to ${b}: ${got.reason}; those days are missing, not zero.`);
370      continue;
371    }
372    for (const d of (got.json as { downloads?: Array<{ day?: unknown; downloads?: unknown }> }).downloads ?? []) {
373      const n = num(d.downloads);
374      if (typeof d.day === "string" && n !== null && n > 0) days.push({ day: d.day, downloads: n, name });
375    }
376  }
377  return days;
378}
379
380/** The package's daily downloads, and its former name's, oldest first, with its weekly
381 *  GitHub rows. Cached for HISTORY_TTL_SECONDS under historyKey. */
382export async function packageHistory(env: Env, cfg: OpsPackageConfig, fetchImpl: FetchLike, now: Date): Promise<PortalPackageHistory> {
383  const weeks = await env.DB.prepare(
384    "SELECT week, stars, open_issues, open_prs, latest_release FROM ops_package_weeks WHERE name = ?1 ORDER BY week DESC LIMIT 104"
385  )
386    .bind(cfg.name)
387    .all<PortalPackageHistory["weeks"][number]>();
388  const key = historyKey(cfg.name);
389  let cached: { formerly: string | null; fetched_at: string; days: PortalPackageHistory["days"]; notes: string[] } | null = null;
390  try {
391    const raw = await env.APP_KV.get(key);
392    cached = raw ? JSON.parse(raw) : null;
393  } catch (err) {
394    logEvent("warn", "PACKAGES_HISTORY_CACHE_UNREADABLE", { message: `PACKAGES_HISTORY_CACHE_UNREADABLE ${key}: ${err instanceof Error ? err.message : String(err)}` });
395  }
396  // A cache written before the former name changed is not this package's history.
397  if (!cached || cached.formerly !== cfg.formerly) {
398    const notes: string[] = [];
399    const days = [...(cfg.formerly ? await dailyDownloads(fetchImpl, cfg.formerly, now, notes) : []), ...(await dailyDownloads(fetchImpl, cfg.name, now, notes))];
400    days.sort((a, b) => (a.day === b.day ? a.name.localeCompare(b.name) : a.day < b.day ? -1 : 1));
401    cached = { formerly: cfg.formerly, fetched_at: now.toISOString(), days, notes };
402    await env.APP_KV.put(key, JSON.stringify(cached), { expirationTtl: HISTORY_TTL_SECONDS });
403  }
404  return {
405    name: cfg.name,
406    formerly: cfg.formerly,
407    generated: now.toISOString(),
408    fetched_at: cached.fetched_at,
409    days: cached.days,
410    first_day: cached.days[0]?.day ?? null,
411    last_day: cached.days[cached.days.length - 1]?.day ?? null,
412    notes: cached.notes,
413    weeks: weeks.results ?? [],
414  };
415}
416