HealthLog/src/lib/openapi/routes/day.ts

/**
 * OpenAPI route table for the day view, the timeline and life events
 * (`/api/day`, `/api/timeline`, `/api/life-events`, v1.42, #613).
 *
 * Part of the OpenAPI route table; aggregated in `./index.ts`. The request
 * and response schemas are the runtime ones from `@/lib/day/wire-schemas`, so
 * the published contract is the parser's own.
 */
import type { ZodOpenApiObject } from "zod-openapi";

import {
  dayIndexQuerySchema,
  dayIndexResponseSchema,
  dayNotableQuerySchema,
  dayNotableResponseSchema,
  dayPathSchema,
  dayResponseSchema,
  lifeEventCreateSchema,
  lifeEventIdPathSchema,
  lifeEventListResponseSchema,
  lifeEventSchema,
  lifeEventUpdateSchema,
  timelineQuerySchema,
  timelineReadinessResponseSchema,
  timelineResponseSchema,
} from "@/lib/day/wire-schemas";

import {
  dataEnvelope,
  errorEnvelope,
  idempotencyKeyParameter,
  idempotentWrite,
  recordRefusal,
  recordWriteRateLimitResponse,
  SHARING_NOT_PERMITTED_DESCRIPTION,
  stdResponses,
} from "./shared";

const LIFE_EVENTS_OWNER_ONLY =
  "Owner-only in v1.42: no share reaches life events, not a `profile` share, a whole-record share or MANAGE, and not a guardian acting for a managed profile.";

/** The 403 of an owner-only life-event route. */
const lifeEventRefusal = {
  "403": {
    description: `${LIFE_EVENTS_OWNER_ONLY}\n\n${SHARING_NOT_PERMITTED_DESCRIPTION}`,
    content: { "application/json": { schema: errorEnvelope } },
  },
};

const TIMELINE_OFF =
  "`module.disabled` with `meta.module = timeline`: the record has the timeline switched off (it is opt-in), or the operator turned it off server-wide.";

const lifeEventNotFound = {
  "404": {
    description: "No such life event on this account.",
    content: { "application/json": { schema: errorEnvelope } },
  },
};

export const dayPaths: NonNullable<ZodOpenApiObject["paths"]> = {
  "/api/day/index": {
    get: {
      tags: ["Records"],
      summary: "Days with entries",
      description:
        "Which local days in a window hold anything, by section, and which carry a notable observation. At most 366 days per call. Days are cut in the record's own time zone.",
      requestParams: { query: dayIndexQuerySchema },
      responses: {
        "200": {
          description: "The days in the window that hold entries.",
          content: {
            "application/json": {
              schema: dataEnvelope(dayIndexResponseSchema, "DayIndexEnvelope"),
            },
          },
        },
        ...stdResponses,
        ...recordRefusal(),
      },
    },
  },
  "/api/day/notable": {
    get: {
      tags: ["Records"],
      summary: "Since the last visit",
      description:
        "What stood out and what changed in a window, for the preparation of the next visit: deterministic observations (a value highest or lowest for at least three months, a first reading, a regular reading that stopped for two weeks or more) and context changes (dose changes, medication and course starts and ends, pauses, illness onsets and recoveries, vaccinations, procedures, lab days). Without `from` the window is the one the next planned visit prepares (its `preparation.from` on `GET /api/encounters`, `anchor: nextVisit`); with nothing booked it starts at the last completed visit the caller may see (else 90 days back); without `to` it ends today; at most 1096 days. Keys and the record's own names only, no judgement. Days are cut in the record's own time zone. Sections the caller's grant does not cover are left out.",
      requestParams: { query: dayNotableQuerySchema },
      responses: {
        "200": {
          description: "The window, its observations and its changes.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                dayNotableResponseSchema,
                "DayNotableWindowEnvelope",
              ),
            },
          },
        },
        ...stdResponses,
        ...recordRefusal(),
      },
    },
  },
  "/api/day/{date}": {
    get: {
      tags: ["Records"],
      summary: "One day across the record",
      description:
        "Everything on one local calendar day: what ran through it (medications, an illness, a cycle phase, a trip), the readings in its window with the person's usual range, what happened on it, and deterministic notable observations as keys with parameters. Sections of a switched-off module are left out; sections the caller's grant does not cover are named in `sections`. Life events and the environment are the owner's only: for a delegate at any level they are named `not_shared`. Read live from the record, never from the UTC rollups. A date that is not a real calendar date answers 422.",
      requestParams: { path: dayPathSchema },
      responses: {
        "200": {
          description: "The day.",
          content: {
            "application/json": {
              schema: dataEnvelope(dayResponseSchema, "DayEnvelope"),
            },
          },
        },
        ...stdResponses,
        ...recordRefusal(),
      },
    },
  },
  "/api/timeline": {
    get: {
      tags: ["Records"],
      summary: "The record over the years",
      description:
        "Lanes of conditions, allergies, medications, vaccinations, visits, lab days, documents and life events, the standing items without a start, and monthly (or finer, by zoom) value series, among them the lab markers (`labSeries`, single readings) and the person-defined symptoms (`symptomSeries`, the day's highest intensity averaged over logged days, on a fixed 0 to 10 scale; read only with the illness module on and the illness section visible) named in `values`. Empty lanes are not sent; lanes of a switched-off module never are. The `life` lane (life events and travel periods) is the owner's only and is never sent to a delegate. Requires the opt-in `timeline` module.",
      requestParams: { query: timelineQuerySchema },
      responses: {
        "200": {
          description: "The timeline for the requested zoom and window.",
          content: {
            "application/json": {
              schema: dataEnvelope(timelineResponseSchema, "TimelineEnvelope"),
            },
          },
        },
        ...stdResponses,
        ...recordRefusal(TIMELINE_OFF),
      },
    },
  },
  "/api/timeline/readiness": {
    get: {
      tags: ["Records"],
      summary: "What the timeline can show",
      description:
        "One row per lane: carries, thin or empty, a count, a detail as a message key with parameters, and the gaps with one in-app link each. The verdict is one of two words, never a score. The `life` lane is reported to the owner only. Requires the opt-in `timeline` module.",
      responses: {
        "200": {
          description: "The readiness inventory.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                timelineReadinessResponseSchema,
                "TimelineReadinessEnvelope",
              ),
            },
          },
        },
        ...stdResponses,
        ...recordRefusal(TIMELINE_OFF),
      },
    },
  },
  "/api/life-events": {
    get: {
      tags: ["Records"],
      summary: "List life events",
      description:
        "The account's own life events, oldest first; soft-deleted ones are excluded. Title and note are decrypted for the caller. Owner-only: no delegate reads them at any share level. Life events are never sent to a model.",
      responses: {
        "200": {
          description: "The life events.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                lifeEventListResponseSchema,
                "LifeEventListEnvelope",
              ),
            },
          },
        },
        ...stdResponses,
        ...lifeEventRefusal,
      },
    },
    post: {
      parameters: [idempotencyKeyParameter],
      tags: ["Records"],
      summary: "Add a life event",
      description:
        "A dated anchor in the person's life. `precision` says how much of the date is known and applies to both ends: at MONTH a date is the first of its month, at YEAR the first of its year. `endDate`, when given, is not before `startDate`. Title (1-120 characters) and note (up to 2000) are encrypted at rest. Owner-only, like every life-event route.",
      requestBody: {
        required: true,
        content: { "application/json": { schema: lifeEventCreateSchema } },
      },
      responses: {
        "201": {
          description: "Created.",
          content: {
            "application/json": {
              schema: dataEnvelope(lifeEventSchema, "CreateLifeEventEnvelope"),
            },
          },
        },
        ...stdResponses,
        ...lifeEventRefusal,
        ...recordWriteRateLimitResponse,
        ...idempotentWrite(),
      },
    },
  },
  "/api/life-events/{id}": {
    patch: {
      tags: ["Records"],
      summary: "Edit a life event",
      description:
        "A partial edit; an omitted key leaves the column untouched. The merged event must still satisfy the create rules (dates aligned to the precision, end not before start).",
      requestParams: { path: lifeEventIdPathSchema },
      requestBody: {
        required: true,
        content: { "application/json": { schema: lifeEventUpdateSchema } },
      },
      responses: {
        "200": {
          description: "Updated.",
          content: {
            "application/json": {
              schema: dataEnvelope(lifeEventSchema, "UpdateLifeEventEnvelope"),
            },
          },
        },
        ...lifeEventNotFound,
        ...stdResponses,
        ...lifeEventRefusal,
      },
    },
    delete: {
      tags: ["Records"],
      summary: "Delete a life event",
      description: "Soft-deletes one life event.",
      requestParams: { path: lifeEventIdPathSchema },
      responses: {
        "200": {
          description: "Deleted.",
          content: {
            "application/json": {
              schema: dataEnvelope(lifeEventSchema, "DeleteLifeEventEnvelope"),
            },
          },
        },
        ...lifeEventNotFound,
        ...stdResponses,
        ...lifeEventRefusal,
      },
    },
  },
};