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

/**
 * OpenAPI route table for person-defined symptoms (`/api/symptoms`, v1.40).
 *
 * Part of the OpenAPI route table; aggregated in `./index.ts`. Request bodies
 * and queries reuse the runtime Zod schemas from `@/lib/symptoms/shared` so the
 * wire contract stays single-source; response shapes mirror the DTOs the
 * routes serialise (decrypted label and note, the 30-day summary).
 *
 * Every route rides the illness module: an account that turned it off (or an
 * operator-disabled instance) answers 403 `illness.disabled` even to a valid
 * Bearer token.
 */
import type { ZodOpenApiObject } from "zod-openapi";
import { z } from "zod/v4";

import {
  symptomDefinitionCreateSchema,
  symptomDefinitionUpdateSchema,
  symptomEventCreateSchema,
  symptomEventListQuerySchema,
  symptomEventUpdateSchema,
} from "@/lib/symptoms/shared";

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

const MODULE_OFF =
  "`illness.disabled`: the record has the illness module switched off (or the operator turned it off server-wide); symptoms ride that module.";

const createSymptomDefinitionRequest = symptomDefinitionCreateSchema.meta({
  id: "CreateSymptomDefinitionRequest",
  description:
    "Define a symptom of your own. `label` (1-40 characters) is encrypted at rest; `icon` is one of the cycle custom-symptom icon names, null for the default glyph. At most eight active definitions per account (422 `symptoms.definition.limitReached`).",
});

const updateSymptomDefinitionRequest = symptomDefinitionUpdateSchema.meta({
  id: "UpdateSymptomDefinitionRequest",
  description:
    "Partial edit; an omitted key leaves the column untouched. `isActive: false` hides the symptom (history kept, slot freed); `isActive: true` shows it again and re-checks the cap.",
});

const createSymptomEventRequest = symptomEventCreateSchema.meta({
  id: "CreateSymptomEventRequest",
  description:
    "Log one occurrence. `intensity` is 0-10 (0 none, 10 the worst imaginable). `occurredAt` defaults to now and may not lie in the future beyond five minutes. `episodeId`, when given, must name one of the record's own illness episodes that is still open (422 `symptoms.episode.notOpen` otherwise). The note is encrypted at rest.",
});

const updateSymptomEventRequest = symptomEventUpdateSchema.meta({
  id: "UpdateSymptomEventRequest",
  description:
    "Partial edit of one occurrence. `note: null` clears the note, `episodeId: null` drops the link. A changed `episodeId` must name an open episode; an unchanged link to an episode that has since resolved is kept.",
});

const listSymptomEventsQuery = symptomEventListQuerySchema.meta({
  id: "ListSymptomEventsQuery",
  description:
    "Optional `from` / `to` (ISO instants, inclusive), `definitionId`, `episodeId`, and `limit` (1-500, default 200). Newest first.",
});

const symptomDefinition = z
  .object({
    id: z.string(),
    label: z.string().nullable(),
    icon: z.string().nullable(),
    sortOrder: z.number().int(),
    isActive: z.boolean(),
    recent: z.object({
      count30d: z.number().int(),
      maxIntensity30d: z.number().int().nullable(),
      lastOccurredAt: z.string().nullable(),
    }),
  })
  .meta({
    id: "SymptomDefinition",
    description:
      "A symptom the person defined. `label` is decrypted (null only on an unreadable value). `recent` is computed server-side: occurrences and the highest intensity over the last 30 days, and the last occurrence ever. Each active definition is also the correlation channel `SYMPTOM:<id>`.",
  });

const symptomDefinitionList = z
  .object({
    definitions: z.array(symptomDefinition),
    limit: z.number().int(),
  })
  .meta({
    id: "SymptomDefinitionList",
    description:
      "The record's symptom definitions in display order, and the active-definition cap.",
  });

const symptomEvent = z
  .object({
    id: z.string(),
    definitionId: z.string(),
    occurredAt: z.string(),
    intensity: z.number().int(),
    note: z.string().nullable(),
    episodeId: z.string().nullable(),
    createdAt: z.string(),
    updatedAt: z.string(),
  })
  .meta({
    id: "SymptomEvent",
    description:
      "One occurrence of a defined symptom: when, how strong (0-10), the decrypted note, and the illness episode it was filed against (null when none).",
  });

const symptomEventList = z
  .object({
    events: z.array(symptomEvent),
    limit: z.number().int(),
    hasMore: z.boolean(),
  })
  .meta({
    id: "SymptomEventList",
    description:
      "A page of occurrences, newest first. `hasMore` is true when the page is full; page on with `to` set to the oldest `occurredAt` seen.",
  });

const deletedResponse = z
  .object({
    deleted: z.literal(true),
    purged: z.boolean(),
    eventsDeleted: z.number().int(),
  })
  .meta({
    id: "SymptomDefinitionDeleted",
    description:
      "`purged: false` means the definition was hidden and its history kept; `purged: true` means it and `eventsDeleted` occurrences were removed.",
  });

const pathId = { path: z.object({ id: z.string() }) };

const definitionNotFound = {
  "404": {
    description:
      "`symptoms.definition.notFound`: no definition with this id on the record.",
    content: { "application/json": { schema: errorEnvelope } },
  },
} as const;

const eventNotFound = {
  "404": {
    description:
      "`symptoms.event.notFound`: no occurrence with this id on the record.",
    content: { "application/json": { schema: errorEnvelope } },
  },
} as const;

export const symptomPaths: NonNullable<ZodOpenApiObject["paths"]> = {
  "/api/symptoms/definitions": {
    get: {
      tags: ["Symptoms"],
      summary: "List your own symptoms (v1.40)",
      description:
        "The record's active symptom definitions with their 30-day summary; `includeHidden=true` adds the hidden ones. Rides the illness module.",
      requestParams: {
        query: z.object({
          includeHidden: z.enum(["true", "false"]).optional(),
        }),
      },
      responses: {
        ...recordRefusal(MODULE_OFF),
        "200": {
          description: "The definitions.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                symptomDefinitionList,
                "ListSymptomDefinitionsEnvelope",
              ),
            },
          },
        },
        ...stdResponses,
      },
    },
    post: {
      tags: ["Symptoms"],
      summary: "Define a symptom (v1.40)",
      description:
        "Creates one definition. Idempotent under `Idempotency-Key`. Audits as `symptoms.definition.create` without the label. Rate-limited to 30 a minute.",
      parameters: [idempotencyKeyParameter],
      requestBody: {
        required: true,
        content: {
          "application/json": { schema: createSymptomDefinitionRequest },
        },
      },
      responses: {
        ...idempotentWrite(),
        ...recordRefusal(MODULE_OFF),
        "201": {
          description: "Definition created.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                symptomDefinition,
                "CreateSymptomDefinitionEnvelope",
              ),
            },
          },
        },
        ...stdResponses,
      },
    },
  },
  "/api/symptoms/definitions/{id}": {
    patch: {
      tags: ["Symptoms"],
      summary: "Edit, hide or show a symptom (v1.40)",
      description:
        "Partial edit. Audits as `symptoms.definition.update`, naming a label change without quoting it.",
      requestParams: pathId,
      requestBody: {
        required: true,
        content: {
          "application/json": { schema: updateSymptomDefinitionRequest },
        },
      },
      responses: {
        ...recordRefusal(MODULE_OFF),
        "200": {
          description: "Definition updated.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                symptomDefinition,
                "UpdateSymptomDefinitionEnvelope",
              ),
            },
          },
        },
        ...definitionNotFound,
        ...stdResponses,
      },
    },
    delete: {
      tags: ["Symptoms"],
      summary: "Hide or delete a symptom (v1.40)",
      description:
        "Hides the definition and keeps its history. `?purge=true` deletes it and every occurrence of it.",
      requestParams: {
        ...pathId,
        query: z.object({ purge: z.enum(["true", "false"]).optional() }),
      },
      responses: {
        ...recordRefusal(MODULE_OFF),
        "200": {
          description: "Hidden or deleted.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                deletedResponse,
                "DeleteSymptomDefinitionEnvelope",
              ),
            },
          },
        },
        ...definitionNotFound,
        ...stdResponses,
      },
    },
  },
  "/api/symptoms/events": {
    get: {
      tags: ["Symptoms"],
      summary: "List symptom occurrences (v1.40)",
      description:
        "Occurrences of the record's symptoms, newest first, narrowed by the optional query.",
      requestParams: { query: listSymptomEventsQuery },
      responses: {
        ...recordRefusal(MODULE_OFF),
        "200": {
          description: "A page of occurrences.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                symptomEventList,
                "ListSymptomEventsEnvelope",
              ),
            },
          },
        },
        ...stdResponses,
      },
    },
    post: {
      tags: ["Symptoms"],
      summary: "Log a symptom occurrence (v1.40)",
      description:
        "Creates one occurrence. Idempotent under `Idempotency-Key`. A hidden definition can still be logged against; another record's definition 404s (`symptoms.definition.notFound`). Audits as `symptoms.event.create` without the note.",
      parameters: [idempotencyKeyParameter],
      requestBody: {
        required: true,
        content: {
          "application/json": { schema: createSymptomEventRequest },
        },
      },
      responses: {
        ...idempotentWrite(),
        ...recordRefusal(MODULE_OFF),
        "201": {
          description: "Occurrence logged.",
          content: {
            "application/json": {
              schema: dataEnvelope(symptomEvent, "CreateSymptomEventEnvelope"),
            },
          },
        },
        ...definitionNotFound,
        ...stdResponses,
      },
    },
  },
  "/api/symptoms/events/{id}": {
    patch: {
      tags: ["Symptoms"],
      summary: "Edit a symptom occurrence (v1.40)",
      description:
        "Partial edit. Audits as `symptoms.event.update`, naming a note change without quoting it.",
      requestParams: pathId,
      requestBody: {
        required: true,
        content: {
          "application/json": { schema: updateSymptomEventRequest },
        },
      },
      responses: {
        ...recordRefusal(MODULE_OFF),
        "200": {
          description: "Occurrence updated.",
          content: {
            "application/json": {
              schema: dataEnvelope(symptomEvent, "UpdateSymptomEventEnvelope"),
            },
          },
        },
        ...eventNotFound,
        ...stdResponses,
      },
    },
    delete: {
      tags: ["Symptoms"],
      summary: "Delete a symptom occurrence (v1.40)",
      description: "Removes the occurrence. Audits as `symptoms.event.delete`.",
      requestParams: pathId,
      responses: {
        ...recordRefusal(MODULE_OFF),
        "200": {
          description: "Deleted.",
          content: {
            "application/json": {
              schema: dataEnvelope(
                z.object({ deleted: z.literal(true) }),
                "DeleteSymptomEventEnvelope",
              ),
            },
          },
        },
        ...eventNotFound,
        ...stdResponses,
      },
    },
  },
};