feat: Add Zod-based typing for API responses across frontend and backend (#1892)

## Summary

Define API response Zod schemas in common-utils for alerts, webhooks, team, installation, and me endpoints. Apply Response<T> typing on backend route handlers with explicit Mongoose-to-JSON serialization (ObjectId, Date, Map). Replace all `any` types and `as Promise<T>` casts in frontend TanStack Query hooks with proper generics.

### How to test locally or on Vercel

1. `yarn dev`
2. Interact with app, ensuring nothing is broken

### References

- Linear Issue: HDX-3464

Author: knudtty

.changeset/slow-insects-travel.md

@@ -0,0 +1,7 @@
+---
+'@hyperdx/common-utils': patch
+'@hyperdx/api': patch
+'@hyperdx/app': patch
+---
+
+fix: add explicit api typing to all api routes and frontend hooks

packages/api/src/routers/api/alerts.ts

@@ -1,5 +1,5 @@
+import type { AlertsApiResponse } from '@hyperdx/common-utils/dist/types';
 import express from 'express';
-import _ from 'lodash';
 import { ObjectId } from 'mongodb';
 import { z } from 'zod';
 import { processRequest, validateRequest } from 'zod-express-middleware';
@@ -17,7 +17,8 @@ import { alertSchema, objectIdSchema } from '@/utils/zod';
 
 const router = express.Router();
 
-router.get('/', async (req, res, next) => {
+type AlertsExpRes = express.Response<AlertsApiResponse>;
+router.get('/', async (req, res: AlertsExpRes, next) => {
   try {
     const teamId = req.user?.team;
     if (teamId == null) {
@@ -26,58 +27,87 @@ router.get('/', async (req, res, next) => {
 
     const alerts = await getAlertsEnhanced(teamId);
 
-    const data = await Promise.all(
+    const data: AlertsApiResponse['data'] = await Promise.all(
       alerts.map(async alert => {
         const history = await getRecentAlertHistories({
           alertId: new ObjectId(alert._id),
           limit: 20,
         });
 
         return {
-          history,
+          _id: alert._id.toString(),
+          interval: alert.interval,
+          scheduleOffsetMinutes: alert.scheduleOffsetMinutes,
+          scheduleStartAt: alert.scheduleStartAt?.toISOString() ?? undefined,
+          threshold: alert.threshold,
+          thresholdType: alert.thresholdType,
+          channel: { type: alert.channel.type ?? undefined },
+          state: alert.state,
+          source: alert.source,
+          tileId: alert.tileId,
+          name: alert.name,
+          message: alert.message,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          createdAt: (alert as any).createdAt?.toISOString?.() ?? '',
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          updatedAt: (alert as any).updatedAt?.toISOString?.() ?? '',
+          history: history.map(h => ({
+            counts: h.counts,
+            createdAt: h.createdAt.toISOString(),
+            state: h.state,
+            lastValues: h.lastValues.map(lv => ({
+              startTime: lv.startTime.toISOString(),
+              count: lv.count,
+            })),
+          })),
           silenced: alert.silenced
             ? {
-                by: alert.silenced.by?.email,
-                at: alert.silenced.at,
-                until: alert.silenced.until,
+                by: alert.silenced.by?.email ?? '',
+                at: alert.silenced.at.toISOString(),
+                until: alert.silenced.until.toISOString(),
               }
             : undefined,
           createdBy: alert.createdBy
-            ? _.pick(alert.createdBy, ['email', 'name'])
+            ? {
+                email: alert.createdBy.email,
+                name: alert.createdBy.name,
+              }
+            : undefined,
+          dashboardId: alert.dashboard
+            ? alert.dashboard._id.toString()
+            : undefined,
+          savedSearchId: alert.savedSearch
+            ? alert.savedSearch._id.toString()
+            : undefined,
+          dashboard: alert.dashboard
+            ? {
+                _id: alert.dashboard._id.toString(),
+                name: alert.dashboard.name,
+                updatedAt:
+                  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                  (alert as any).dashboard?.updatedAt?.toISOString?.() ?? '',
+                tags: alert.dashboard.tags,
+                tiles: alert.dashboard.tiles
+                  .filter(tile => tile.id === alert.tileId)
+                  .map(tile => ({
+                    id: tile.id,
+                    config: { name: tile.config.name },
+                  })),
+              }
+            : undefined,
+          savedSearch: alert.savedSearch
+            ? {
+                _id: alert.savedSearch._id.toString(),
+                createdAt:
+                  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                  (alert as any).savedSearch?.createdAt?.toISOString?.() ?? '',
+                name: alert.savedSearch.name,
+                updatedAt:
+                  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+                  (alert as any).savedSearch?.updatedAt?.toISOString?.() ?? '',
+                tags: alert.savedSearch.tags,
+              }
             : undefined,
-          channel: _.pick(alert.channel, ['type']),
-          ...(alert.dashboard && {
-            dashboardId: alert.dashboard._id,
-            dashboard: {
-              tiles: alert.dashboard.tiles
-                .filter(tile => tile.id === alert.tileId)
-                .map(tile => _.pick(tile, ['id', 'config.name'])),
-              ..._.pick(alert.dashboard, ['_id', 'name', 'updatedAt', 'tags']),
-            },
-          }),
-          ...(alert.savedSearch && {
-            savedSearchId: alert.savedSearch._id,
-            savedSearch: _.pick(alert.savedSearch, [
-              '_id',
-              'createdAt',
-              'name',
-              'updatedAt',
-              'tags',
-            ]),
-          }),
-          ..._.pick(alert, [
-            '_id',
-            'interval',
-            'scheduleOffsetMinutes',
-            'scheduleStartAt',
-            'threshold',
-            'thresholdType',
-            'state',
-            'source',
-            'tileId',
-            'createdAt',
-            'updatedAt',
-          ]),
         };
       }),
     );

packages/api/src/routers/api/me.ts

@@ -1,3 +1,7 @@
+import {
+  type MeApiResponse,
+  MeApiResponseSchema,
+} from '@hyperdx/common-utils/dist/types';
 import express from 'express';
 
 import { AI_API_KEY, ANTHROPIC_API_KEY, USAGE_STATS_ENABLED } from '@/config';
@@ -6,7 +10,7 @@ import { Api404Error } from '@/utils/errors';
 
 const router = express.Router();
 
-router.get('/', async (req, res, next) => {
+router.get('/', async (req, res: express.Response<MeApiResponse>, next) => {
   try {
     if (req.user == null) {
       throw new Api404Error('Request without user found');
@@ -22,14 +26,17 @@ router.get('/', async (req, res, next) => {
     } = req.user;
 
     const team = await getTeam(teamId);
+    if (team == null) {
+      throw new Api404Error(`Team not found for user ${id}`);
+    }
 
     return res.json({
       accessKey,
-      createdAt,
+      createdAt: createdAt.toISOString(),
       email,
-      id,
+      id: id.toString(),
       name,
-      team,
+      team: MeApiResponseSchema.shape.team.parse(team.toJSON()),
       usageStatsEnabled: USAGE_STATS_ENABLED,
       aiAssistantEnabled: !!(AI_API_KEY || ANTHROPIC_API_KEY),
     });

packages/api/src/routers/api/root.ts

@@ -1,3 +1,4 @@
+import type { InstallationApiResponse } from '@hyperdx/common-utils/dist/types';
 import express from 'express';
 import { serializeError } from 'serialize-error';
 import { z } from 'zod';
@@ -53,7 +54,8 @@ router.get('/health', async (req, res) => {
   });
 });
 
-router.get('/installation', async (req, res, next) => {
+type InstallationEspRes = express.Response<InstallationApiResponse>;
+router.get('/installation', async (_, res: InstallationEspRes, next) => {
   try {
     const _isTeamExisting = await isTeamExisting();
     return res.json({

packages/api/src/routers/api/team.ts

@@ -1,3 +1,11 @@
+import type {
+  RotateApiKeyApiResponse,
+  TeamApiResponse,
+  TeamInvitationsApiResponse,
+  TeamMembersApiResponse,
+  TeamTagsApiResponse,
+  UpdateClickHouseSettingsApiResponse,
+} from '@hyperdx/common-utils/dist/types';
 import { TeamClickHouseSettingsSchema } from '@hyperdx/common-utils/dist/types';
 import crypto from 'crypto';
 import express from 'express';
@@ -23,7 +31,8 @@ import { objectIdSchema } from '@/utils/zod';
 
 const router = express.Router();
 
-router.get('/', async (req, res, next) => {
+type TeamApiExpRes = express.Response<TeamApiResponse>;
+router.get('/', async (req, res: TeamApiExpRes, next) => {
   try {
     const teamId = req.user?.team;
     const userId = req.user?._id;
@@ -46,20 +55,37 @@ router.get('/', async (req, res, next) => {
       throw new Error(`Team ${teamId} not found for user ${userId}`);
     }
 
-    res.json(team.toJSON());
+    // createdAt comes from Mongoose timestamps but is not on the ITeam interface
+    const createdAt =
+      'createdAt' in team && team.createdAt instanceof Date
+        ? team.createdAt.toISOString()
+        : '';
+
+    res.json({
+      _id: team._id.toString(),
+      allowedAuthMethods:
+        'allowedAuthMethods' in team ? team.allowedAuthMethods : undefined,
+      apiKey: team.apiKey,
+      name: team.name,
+      createdAt,
+    });
   } catch (e) {
     next(e);
   }
 });
 
-router.patch('/apiKey', async (req, res, next) => {
+type RotateApiKeyExpRes = express.Response<RotateApiKeyApiResponse>;
+router.patch('/apiKey', async (req, res: RotateApiKeyExpRes, next) => {
   try {
     const teamId = req.user?.team;
     if (teamId == null) {
       throw new Error(`User ${req.user?._id} not associated with a team`);
     }
     const team = await rotateTeamApiKey(teamId);
-    res.json({ newApiKey: team?.apiKey });
+    if (team?.apiKey == null) {
+      throw new Error(`Failed to rotate API key for team ${teamId}`);
+    }
+    res.json({ newApiKey: team.apiKey });
   } catch (e) {
     next(e);
   }
@@ -92,7 +118,11 @@ router.patch(
   processRequest({
     body: TeamClickHouseSettingsSchema,
   }),
-  async (req, res, next) => {
+  async (
+    req,
+    res: express.Response<UpdateClickHouseSettingsApiResponse>,
+    next,
+  ) => {
     try {
       const teamId = req.user?.team;
       if (teamId == null) {
@@ -105,14 +135,7 @@ router.patch(
 
       const team = await updateTeamClickhouseSettings(teamId, req.body);
 
-      res.json(
-        Object.entries(req.body).reduce((acc, cur) => {
-          return {
-            ...acc,
-            [cur[0]]: team?.[cur[0]],
-          };
-        }, {} as any),
-      );
+      res.json(pick(team, Object.keys(req.body)));
     } catch (e) {
       next(e);
     }
@@ -176,7 +199,8 @@ router.post(
   },
 );
 
-router.get('/invitations', async (req, res, next) => {
+type TeamInviteExpressRes = express.Response<TeamInvitationsApiResponse>;
+router.get('/invitations', async (req, res: TeamInviteExpressRes, next) => {
   try {
     const teamId = req.user?.team;
     if (teamId == null) {
@@ -193,8 +217,8 @@ router.get('/invitations', async (req, res, next) => {
     );
     res.json({
       data: teamInvites.map(ti => ({
-        _id: ti._id,
-        createdAt: ti.createdAt,
+        _id: ti._id.toString(),
+        createdAt: ti.createdAt.toISOString(),
         email: ti.email,
         name: ti.name,
         url: `${config.FRONTEND_URL}/join-team?token=${ti.token}`,
@@ -225,7 +249,8 @@ router.delete(
   },
 );
 
-router.get('/members', async (req, res, next) => {
+type TeamMembersExpRes = express.Response<TeamMembersApiResponse>;
+router.get('/members', async (req, res: TeamMembersExpRes, next) => {
   try {
     const teamId = req.user?.team;
     const userId = req.user?._id;
@@ -281,7 +306,8 @@ router.delete(
   },
 );
 
-router.get('/tags', async (req, res, next) => {
+type TeamTagsExpRes = express.Response<TeamTagsApiResponse>;
+router.get('/tags', async (req, res: TeamTagsExpRes, next) => {
   try {
     const teamId = req.user?.team;
     if (teamId == null) {