status

Purpose

Defines the Zod schema for the admin status endpoint (GET /admin/status), which exposes static deployment metadata for debugging, support, and operational dashboards. Unlike the health endpoint, the status endpoint does not probe live dependencies — it reports the deployed application version, process uptime, environment name, and Node.js runtime version. These schemas ensure the response is consistently structured across all environments.

Features

AdminStatusOutput schema — {version, uptime, environment, nodeVersion} with strict Zod validation
uptime validated as a non-negative number representing seconds since process start
All string fields validated as non-empty to prevent blank deployment metadata
Full TypeScript inference via z.infer<> — no manual interface duplication
Zod v4 compatible

Usage: Basic Example

import { AdminStatusOutput } from "@suaveplan/api-schemas/admin";

const status = AdminStatusOutput.parse({
  version: "1.0.0",
  uptime: 86400,
  environment: "production",
  nodeVersion: "v22.0.0",
});

Usage: Advanced Example

import { AdminStatusOutput } from "@suaveplan/api-schemas/admin";

function buildStatus(startTime: number): AdminStatusOutput {
  return AdminStatusOutput.parse({
    version: process.env["APP_VERSION"] ?? "unknown",
    uptime: Math.floor((Date.now() - startTime) / 1000),
    environment: process.env["NODE_ENV"] ?? "development",
    nodeVersion: process.version,
  });
}

API Reference

`AdminStatusOutput`

Zod object schema — status endpoint response.

Field	Type	Description
`version`	`string` (min 1)	Semantic version of the deployed application
`uptime`	`number` (≥ 0)	Seconds the process has been running
`environment`	`string` (min 1)	Deployment environment (production, staging, etc.)
`nodeVersion`	`string` (min 1)	Node.js runtime version string

Type export: type AdminStatusOutput = z.infer<typeof AdminStatusOutput>

Implementation Notes

The uptime field uses floating-point seconds rather than milliseconds for human readability — 86400 (one day) is far more legible than 86400000. The nodeVersion field is included so support engineers can quickly confirm whether a production issue is related to a known Node.js version bug without needing shell access. In Bun environments, process.version still reports the Node.js compatibility version rather than the Bun version; populate nodeVersion accordingly.

2.7 KiB Raw Blame History