first commit

docs/api-stack/api/api-plugin-auth/src/schemas/routes/sign-out.md

@@ -0,0 +1,65 @@
+# schemas/routes/sign-out
+
+## Purpose
+
+Schemas for `POST /auth/sign-out`. The body is optional (Better-Auth
+identifies the session from the cookie or `Authorization` header) and
+the response is a single `{ success: true }` literal so client code
+can branch on success without parsing additional fields.
+
+## Features
+
+- `SignOutBodySchema` — optional empty object; accepts both `undefined`
+  and `{}` so clients can send a body or skip it.
+- `SignOutResponseSchema` — `{ success: literal(true) }` so the
+  response type is `{ success: true }` rather than `{ success: boolean }`.
+- Inferred companion `SignOutResponse`.
+
+## Usage: Basic
+
+```ts
+import { SignOutResponseSchema } from "@suaveplan/api-plugin-auth/schemas/routes";
+
+const parsed = SignOutResponseSchema.parse({ success: true });
+```
+
+## Usage: Advanced
+
+Pair the schema with the `requireAuth` middleware so the OpenAPI
+document advertises a 401 response for anonymous callers and a 200
+response with the typed body for authenticated ones:
+
+```ts
+import { POST, successResponse } from "@suaveplan/api-openapi";
+import {
+    SignOutResponseSchema,
+} from "@suaveplan/api-plugin-auth/schemas/routes";
+
+const signOutRoute = POST("/auth/sign-out")
+    .tags("auth")
+    .summary("End the current session")
+    .response(successResponse(SignOutResponseSchema))
+    .build();
+```
+
+## API Reference
+
+### `SignOutBodySchema`
+
+Optional empty object. Accepts `undefined` or `{}`.
+
+### `SignOutResponseSchema`
+
+`{ success: true }` literal. Inferred type `SignOutResponse`.
+
+## Implementation Notes
+
+- The body schema is `optional` rather than absent so the OpenAPI
+  document still advertises the route as accepting a JSON body. Clients
+  may send `{}` to follow the route shape or omit the body entirely.
+- The response is a literal `true` rather than `boolean` so the typed
+  return value at the client side narrows correctly — `if
+  (response.success) { … }` is statically known to execute.
+- Better-Auth's downstream cookie clearing is a side effect of the
+  handler, not part of the schema. The response only describes the JSON
+  body so the schema stays orthogonal to the cookie machinery.