# 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.