mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-15 23:12:04 +00:00
Stale-served insights responses now carry a revalidating flag; the advisor and comprehensive queries poll on a bounded 25 s cadence until the background warm lands, so an open session converges instead of pinning yesterday's briefing for an hour. Interactive measurement writes (single create, edit, delete, bulk-delete, restore) hard-evict the analytics cache so a manually entered value is reflected on the next read; background batch sync keeps the mark-stale path. The visit-triggered force warm collapses to one job per user instead of one per locale, and the umami script proxy failure now annotates a named action with the failure reason instead of a bare flag.
337 lines
14 KiB
TypeScript
337 lines
14 KiB
TypeScript
"use client";
|
|
|
|
import { useCallback } from "react";
|
|
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
|
|
import type { InsightResult } from "@/lib/ai/types";
|
|
// Type-only — the runtime schemas load lazily inside `fetchAdvisor` so
|
|
// the zod module graph (`@/lib/ai/schema` is ~550 lines of zod builders)
|
|
// stays out of the insights route-entry chunk. This hook is imported
|
|
// eagerly by BOTH the insights page and the layout shell, so a value
|
|
// import here landed zod in the chunk every insights visit downloads
|
|
// before first paint; the schemas are only needed once a payload has
|
|
// actually arrived, which is by definition after the network hop.
|
|
import type {
|
|
DailyBriefing as DailyBriefingPayload,
|
|
TrendAnnotations,
|
|
} from "@/lib/ai/schema";
|
|
import { queryKeys } from "@/lib/query-keys";
|
|
import { apiFetchRaw } from "@/lib/api/api-fetch";
|
|
|
|
/**
|
|
* v1.4.16 phase D reconcile (CRITICAL C1 + C2) — shared TanStack Query
|
|
* helper that reads the rich advisor payload from `/api/insights/generate`.
|
|
*
|
|
* Why a POST under a `useQuery` rather than a dedicated GET endpoint:
|
|
* the route already cache-returns the most recent generation (24h TTL on
|
|
* `User.insightsCachedAt` / `User.insightsCachedText`) without burning a
|
|
* rate-limit token, so a single POST-without-`force` is functionally a
|
|
* GET-or-generate. Adding a separate GET would duplicate the cache-read
|
|
* branch and split the audit-log surface; the reconcile report deferred
|
|
* C1+C2 specifically because it assumed that duplication was required,
|
|
* but the route already supports the cache-aware path.
|
|
*
|
|
* Every surface that mounts the query under the same key shares the
|
|
* cache, so a regenerate from one surface refreshes the others without
|
|
* a second LLM call.
|
|
*/
|
|
export interface InsightAdvisorPayload {
|
|
insights: InsightResult;
|
|
cached: boolean;
|
|
cachedAt?: string | null;
|
|
legacyPayload?: boolean;
|
|
/**
|
|
* v1.4.20 phase B1 — Daily Briefing block surfaced for the new hero
|
|
* strip + briefing card. Lives on the cached payload alongside the
|
|
* legacy `insights` shape (see `aiInsightResponseSchema` — the
|
|
* `.passthrough()` lets the field round-trip through any provider).
|
|
* Validated client-side via the schema's `safeParse` to keep a
|
|
* malformed payload from poisoning the briefing card.
|
|
*/
|
|
dailyBriefing?: DailyBriefingPayload | null;
|
|
/**
|
|
* v1.4.20 phase B3 — optional trend annotations for the Trends row.
|
|
* Same lift-pattern as `dailyBriefing` — validated client-side and
|
|
* left null when the cached payload predates PROMPT_VERSION 4.20.1.
|
|
*/
|
|
trendAnnotations?: TrendAnnotations | null;
|
|
/**
|
|
* v1.16.7 — true when the GET served a stale / missing briefing AND
|
|
* enqueued an out-of-band warm. The query polls (bounded) while this
|
|
* is set so the fresh briefing reaches the open page in-session
|
|
* instead of waiting for the next mount.
|
|
*/
|
|
revalidating?: boolean;
|
|
}
|
|
|
|
/**
|
|
* v1.4.31 — bound the advisor READ (GET) with an 8-second
|
|
* `AbortController` so a cache-miss path (server still warming out of
|
|
* band) does not pin the mother-page main thread. The strip stays
|
|
* interactive in the DOM; dropping the worst case from 30 s to 8 s
|
|
* eliminates the mobile-tap-block window per
|
|
* `.planning/research/v15-insights-blocking-bug.md` fix 1.
|
|
*/
|
|
const ADVISOR_TIMEOUT_MS = 8_000;
|
|
|
|
/**
|
|
* v1.15.18 — the user-initiated regenerate (`force`) POSTs an INLINE
|
|
* generation: a ~1500-token warm completion that routinely runs longer
|
|
* than the 8 s read budget. Bounding the force branch at 8 s silently
|
|
* discarded a slow-but-successful generation — the abort returned a null
|
|
* payload, the mutation only invalidated (re-reading the OLD cache), yet
|
|
* the server had often already written the fresh briefing. Give the force
|
|
* branch the same 45 s budget the out-of-band warm job uses
|
|
* (`COMPREHENSIVE_WARM_TIMEOUT_MS`) so a slow success is kept, not
|
|
* dropped. The READ path stays fast at 8 s — only the explicit user tap
|
|
* may wait. Per `.planning/v1.15.18-daily-briefing-audit.md` Fix 1b.
|
|
*/
|
|
const FORCE_ADVISOR_TIMEOUT_MS = 45_000;
|
|
|
|
/**
|
|
* v1.16.7 — poll cadence + ceiling while the server reports
|
|
* `revalidating: true` (stale briefing served, out-of-band warm in
|
|
* flight). The query's 1 h `staleTime` plus the app-default
|
|
* `refetchOnWindowFocus: false` means a stale-served briefing would
|
|
* otherwise never refresh in-session. 25 s comfortably covers the warm
|
|
* job's 45 s budget within two polls; the attempt ceiling stops a
|
|
* persistently failing generation from polling an open page forever.
|
|
* Same bounded-poll shape as `nextStatusPollInterval`
|
|
* (`src/hooks/use-insight-status.ts`).
|
|
*/
|
|
export const ADVISOR_REVALIDATE_POLL_MS = 25_000;
|
|
export const ADVISOR_REVALIDATE_POLL_MAX_ATTEMPTS = 10;
|
|
|
|
/**
|
|
* Decide whether the advisor query schedules its next poll. Pure so the
|
|
* ceiling + stop conditions are unit-testable: returns the interval
|
|
* while the last payload carries `revalidating: true`, `false` once a
|
|
* response comes back with the flag falsy OR the attempt cap is hit.
|
|
*/
|
|
export function nextAdvisorPollInterval(
|
|
revalidating: boolean | undefined,
|
|
dataUpdateCount: number,
|
|
): number | false {
|
|
if (!revalidating) return false;
|
|
if (dataUpdateCount >= ADVISOR_REVALIDATE_POLL_MAX_ATTEMPTS) return false;
|
|
return ADVISOR_REVALIDATE_POLL_MS;
|
|
}
|
|
|
|
/**
|
|
* v1.15.18 — the outcome of a force regenerate, so the UI can be HONEST:
|
|
* only a `fresh` outcome should toast "refreshed". A `timeout` (slow gen
|
|
* the client gave up on) and a `no-provider` (422) are distinct failure
|
|
* modes.
|
|
*
|
|
* v1.15.20 — `rate-limited` (429) splits off from `empty`: the user's
|
|
* regenerate quota is exhausted, which deserves a "try again later"
|
|
* hint rather than the success toast the old lump produced. `empty` now
|
|
* means only the transient 503 surface (provider chain unavailable).
|
|
*/
|
|
export type AdvisorFetchOutcome =
|
|
| "fresh"
|
|
| "empty"
|
|
| "rate-limited"
|
|
| "timeout"
|
|
| "no-provider";
|
|
|
|
interface AdvisorFetchResult {
|
|
payload: InsightAdvisorPayload | null;
|
|
outcome: AdvisorFetchOutcome;
|
|
}
|
|
|
|
async function fetchAdvisor(
|
|
options: { force?: boolean } = {},
|
|
): Promise<AdvisorFetchResult> {
|
|
const controller = new AbortController();
|
|
const timeoutHandle = setTimeout(
|
|
() => controller.abort(),
|
|
options.force ? FORCE_ADVISOR_TIMEOUT_MS : ADVISOR_TIMEOUT_MS,
|
|
);
|
|
let res: Response;
|
|
try {
|
|
// Read path (no `force`): the GET serves the cached briefing read-only
|
|
// and enqueues an out-of-band warm on a stale / missing cache — it
|
|
// never blocks the page-load path on the provider chain. Only the
|
|
// user-initiated regenerate (`force`) POSTs to generate inline.
|
|
// apiFetchRaw: this path branches on raw status codes (422 / 429 /
|
|
// 503 are expected, non-throwing surfaces) — the unwrap helpers
|
|
// would turn them into thrown ApiErrors.
|
|
res = options.force
|
|
? await apiFetchRaw("/api/insights/generate", {
|
|
method: "POST",
|
|
headers: { "Content-Type": "application/json" },
|
|
body: JSON.stringify({ force: true }),
|
|
signal: controller.signal,
|
|
})
|
|
: await apiFetchRaw("/api/insights/generate", {
|
|
method: "GET",
|
|
signal: controller.signal,
|
|
});
|
|
} catch (err) {
|
|
if (err instanceof DOMException && err.name === "AbortError") {
|
|
// Graceful empty payload — the UI surfaces the empty / regen
|
|
// CTA exactly as it does for the 422 / 429 / 503 paths below.
|
|
// `timeout` lets the regenerate path avoid claiming success.
|
|
return { payload: null, outcome: "timeout" };
|
|
}
|
|
throw err;
|
|
} finally {
|
|
clearTimeout(timeoutHandle);
|
|
}
|
|
if (!res.ok) {
|
|
// 422 (no provider configured), 429 (rate-limited), and 503
|
|
// (provider chain unavailable) are expected surfaces — return null
|
|
// so the consuming UI shows the empty / error state without the
|
|
// query slipping into an `isError` retry loop. Each gets its own
|
|
// outcome tag so the regenerate toast can be honest about WHY no
|
|
// fresh payload arrived.
|
|
if (res.status === 422) {
|
|
return { payload: null, outcome: "no-provider" };
|
|
}
|
|
if (res.status === 429) {
|
|
return { payload: null, outcome: "rate-limited" };
|
|
}
|
|
if (res.status === 503) {
|
|
return { payload: null, outcome: "empty" };
|
|
}
|
|
throw new Error(`HTTP ${res.status}`);
|
|
}
|
|
const json = await res.json();
|
|
const payload = json.data as InsightAdvisorPayload;
|
|
// Lazy schema load — see the type-only import note at the top. The
|
|
// module is cached after the first call, so this await is free from
|
|
// the second fetch on.
|
|
const { dailyBriefingSchema, trendAnnotationsSchema } = await import(
|
|
"@/lib/ai/schema"
|
|
);
|
|
// The cached `insights` blob may carry a `dailyBriefing` from a fresh
|
|
// PROMPT_VERSION 4.20.x generation. Lift it onto the payload so
|
|
// consumers don't have to know the legacy shape.
|
|
const briefingCandidate = (payload?.insights as Record<string, unknown>)
|
|
?.dailyBriefing;
|
|
if (briefingCandidate != null) {
|
|
const parsed = dailyBriefingSchema.safeParse(briefingCandidate);
|
|
if (parsed.success) {
|
|
payload.dailyBriefing = parsed.data;
|
|
} else {
|
|
// Malformed cached briefing — keep null so the UI shows the
|
|
// empty-state CTA instead of a half-rendered card.
|
|
payload.dailyBriefing = null;
|
|
}
|
|
} else {
|
|
payload.dailyBriefing = null;
|
|
}
|
|
|
|
// v1.4.20 phase B3 — same lift for `trendAnnotations`. Cached payloads
|
|
// from the 4.20.0 line predate the field, so null is the expected
|
|
// default. A malformed candidate also resolves to null so the UI
|
|
// surfaces the per-metric empty hint instead of a half-rendered card.
|
|
const annotationsCandidate = (payload?.insights as Record<string, unknown>)
|
|
?.trendAnnotations;
|
|
if (annotationsCandidate != null) {
|
|
const parsed = trendAnnotationsSchema.safeParse(annotationsCandidate);
|
|
payload.trendAnnotations = parsed.success ? parsed.data : null;
|
|
} else {
|
|
payload.trendAnnotations = null;
|
|
}
|
|
return { payload, outcome: "fresh" };
|
|
}
|
|
|
|
export interface UseInsightsAdvisorResult {
|
|
payload: InsightAdvisorPayload | null;
|
|
isLoading: boolean;
|
|
isError: boolean;
|
|
error: Error | null;
|
|
regenerate: () => void;
|
|
isRegenerating: boolean;
|
|
regenerateError: Error | null;
|
|
/**
|
|
* v1.15.18 — the outcome of the LAST settled regenerate. The tab strip
|
|
* fires the "refreshed" toast only when this is `"fresh"`, so a slow gen
|
|
* the client gave up on (`"timeout"`) or a missing provider
|
|
* (`"no-provider"`) never reads as "done".
|
|
*/
|
|
regenerateOutcome: AdvisorFetchOutcome | null;
|
|
/**
|
|
* v1.15.20 — the outcome of the last settled READ. Lets surfaces
|
|
* distinguish "no briefing yet, a generate could help" (`empty` /
|
|
* `timeout`) from "no provider configured, generating is futile"
|
|
* (`no-provider`) and render a connect-AI hint instead of a dead
|
|
* regenerate CTA.
|
|
*/
|
|
readOutcome: AdvisorFetchOutcome | null;
|
|
}
|
|
|
|
/**
|
|
* Read-only consumer for the advisor payload. Use this on surfaces that
|
|
* just want to render the cached insight (e.g. dashboard preview).
|
|
*/
|
|
export function useInsightsAdvisorQuery(
|
|
enabled: boolean,
|
|
): UseInsightsAdvisorResult {
|
|
const queryClient = useQueryClient();
|
|
const query = useQuery({
|
|
queryKey: queryKeys.insightsAdvisor(),
|
|
// v1.15.20 — the cache stores the full tagged result (payload +
|
|
// outcome) so the read path can surface WHY a payload is missing
|
|
// (`no-provider` → connect-AI hint instead of a dead regenerate CTA).
|
|
queryFn: () => fetchAdvisor(),
|
|
enabled,
|
|
// 24h cache window matches the server-side `insightsCachedAt` TTL.
|
|
staleTime: 60 * 60 * 1000,
|
|
retry: false,
|
|
// v1.16.7 — converge a stale-served briefing in-session: while the
|
|
// last GET reported `revalidating: true` (warm enqueued), poll on a
|
|
// bounded interval until a response comes back with the flag falsy.
|
|
refetchInterval: (query) =>
|
|
nextAdvisorPollInterval(
|
|
query.state.data?.payload?.revalidating,
|
|
query.state.dataUpdateCount,
|
|
),
|
|
});
|
|
|
|
const mutation = useMutation({
|
|
mutationFn: () => fetchAdvisor({ force: true }),
|
|
onSuccess: (result) => {
|
|
if (result.payload) {
|
|
// A genuinely fresh generation landed — write it into the shared
|
|
// cache so the hero subtitle + briefing card repaint immediately.
|
|
queryClient.setQueryData(queryKeys.insightsAdvisor(), result);
|
|
} else {
|
|
// No fresh payload (timeout / no-provider / transient). The server's
|
|
// inline POST may STILL have written a fresh briefing after the
|
|
// client gave up at 45 s, so re-read the GET to converge — but the
|
|
// honest toast is gated on `regenerateOutcome` below, not on this
|
|
// invalidate.
|
|
queryClient.invalidateQueries({
|
|
queryKey: queryKeys.insightsAdvisor(),
|
|
});
|
|
}
|
|
// Per-status caches are evicted server-side on regenerate; refresh
|
|
// their query subtree so the per-section text below the advisor card
|
|
// re-fetches.
|
|
queryClient.invalidateQueries({ queryKey: queryKeys.insightsRoot() });
|
|
},
|
|
});
|
|
|
|
// v1.8.3 — stabilise the `regenerate` callback so the memoised
|
|
// `<InsightsTabStrip>` (which receives it as `onRegenerate`) is not
|
|
// re-rendered on every shell render by a fresh arrow reference. A
|
|
// status-query flip on a sub-page that re-renders the shell would
|
|
// otherwise re-reconcile the whole strip mid-gesture and eat taps.
|
|
const { mutate } = mutation;
|
|
const regenerate = useCallback(() => mutate(), [mutate]);
|
|
|
|
return {
|
|
payload: query.data?.payload ?? null,
|
|
isLoading: query.isLoading,
|
|
isError: query.isError,
|
|
error: (query.error as Error | null) ?? null,
|
|
regenerate,
|
|
isRegenerating: mutation.isPending,
|
|
regenerateError: (mutation.error as Error | null) ?? null,
|
|
regenerateOutcome: mutation.data?.outcome ?? null,
|
|
readOutcome: query.data?.outcome ?? null,
|
|
};
|
|
}
|