first commit

docs/api-stack/api/api-schemas/src/auth/logout.md

@@ -0,0 +1,65 @@
+# logout
+
+## Purpose
+
+Provides Zod schemas for the logout request and response shapes used by Suaveplan's `POST /auth/logout` endpoint. Logout is a server-side operation: the client sends its refresh token so the server can revoke it, preventing silent background re-authentication after the user has explicitly signed out. These schemas are shared between the server route handler, React logout mutation hooks, and OpenAPI document generation.
+
+## Features
+
+- `LogoutInput` schema — accepts a `refreshToken` string (non-empty) for server-side revocation
+- `LogoutOutput` schema — returns `{success: true}` as a typed literal, making the success state unambiguous in TypeScript
+- `success` field uses `z.literal(true)` rather than `z.boolean()` so TypeScript narrows the type to `true` rather than `boolean`
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { LogoutInput, LogoutOutput } from "@suaveplan/api-schemas/auth";
+
+// Validate the request body
+const input = LogoutInput.parse(req.body);
+// → { refreshToken: "rt_abc123" }
+
+// Validate the response
+const output = LogoutOutput.parse({ success: true });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { LogoutInput, LogoutOutput } from "@suaveplan/api-schemas/auth";
+
+async function handleLogout(rawBody: unknown): Promise<LogoutOutput> {
+  const { refreshToken } = LogoutInput.parse(rawBody);
+  await sessionStore.revoke(refreshToken);
+  // Also clear access token from an allowlist if using stateful tokens
+  return LogoutOutput.parse({ success: true });
+}
+```
+
+## API Reference
+
+### `LogoutInput`
+
+Zod object schema — logout request body.
+
+| Field          | Type             | Description                                       |
+|----------------|------------------|---------------------------------------------------|
+| `refreshToken` | `string` (min 1) | Refresh token to revoke on the server             |
+
+**Type export:** `type LogoutInput = z.infer<typeof LogoutInput>`
+
+### `LogoutOutput`
+
+Zod object schema — logout success response.
+
+| Field     | Type           | Description                                    |
+|-----------|----------------|------------------------------------------------|
+| `success` | `true` (literal)| Always `true` on a successful logout           |
+
+**Type export:** `type LogoutOutput = z.infer<typeof LogoutOutput>`
+
+## Implementation Notes
+
+Using `z.literal(true)` rather than `z.boolean()` means TypeScript will infer `success: true` rather than `success: boolean`, enabling exhaustiveness checks in client code that branches on the success field. Logout endpoints conventionally return 204 No Content with no body, but Suaveplan uses a 200 with a JSON body to accommodate clients (such as React hooks) that expect a typed response. Clients that receive a 401 or 404 should still clear local tokens regardless of the server response.