Initial Commit

packages/api-stack/api/api-schemas/src/admin/ping.md

@@ -0,0 +1,63 @@
+# ping
+
+## Purpose
+
+Provides Zod schemas for the admin ping endpoint (`GET /admin/ping`). The ping endpoint is the simplest possible health indicator — it verifies that the server is alive, the request pipeline is functional, and the clock is ticking. These schemas are used by server route handlers, monitoring systems, and the OpenAPI generator to define the contract for this sentinel endpoint.
+
+## Features
+
+- `AdminPingInput` schema — empty object (no input required); useful as a typed placeholder for framework plugins that require a body schema
+- `AdminPingOutput` schema — `{pong: true, timestamp}` where `pong` is a typed literal and `timestamp` is an ISO 8601 string with timezone offset
+- `pong: z.literal(true)` ensures TypeScript narrows the field to `true`, not `boolean`
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { AdminPingOutput } from "@suaveplan/api-schemas/admin";
+
+const response = AdminPingOutput.parse({
+  pong: true,
+  timestamp: new Date().toISOString(),
+});
+// → { pong: true, timestamp: "2024-06-01T12:00:00.000Z" }
+```
+
+## Usage: Advanced Example
+
+```ts
+import { AdminPingInput, AdminPingOutput } from "@suaveplan/api-schemas/admin";
+
+// Route handler using both input and output schemas
+async function handlePing(_rawBody: unknown): Promise<AdminPingOutput> {
+  AdminPingInput.parse(_rawBody); // no-op for empty body, ensures shape check
+  return AdminPingOutput.parse({
+    pong: true,
+    timestamp: new Date().toISOString(),
+  });
+}
+```
+
+## API Reference
+
+### `AdminPingInput`
+
+Zod object schema — empty input (no fields).
+
+**Type export:** `type AdminPingInput = z.infer<typeof AdminPingInput>`
+
+### `AdminPingOutput`
+
+Zod object schema — ping response.
+
+| Field       | Type                            | Description                              |
+|-------------|----------------------------------|------------------------------------------|
+| `pong`      | `true` (literal)                | Confirms endpoint reachability           |
+| `timestamp` | `string` (ISO 8601 with offset) | Server clock time at request processing  |
+
+**Type export:** `type AdminPingOutput = z.infer<typeof AdminPingOutput>`
+
+## Implementation Notes
+
+The `pong` field uses `z.literal(true)` rather than `z.boolean()` to make the success state an unambiguous type-level fact — TypeScript will infer `pong: true` not `pong: boolean`, enabling exhaustiveness checks. The `timestamp` is included so monitoring tools can detect clock skew between the client and server without an additional round-trip to a time endpoint. The `AdminPingInput` empty-object schema exists to keep route plugin signatures uniform: every endpoint has both an input and an output schema.