first commit

docs/api-stack/api/api-schemas/src/admin/status.md

@@ -0,0 +1,60 @@
+# 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
+
+```ts
+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
+
+```ts
+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.