# schemas/routes/session

## Purpose

Response schema for `GET /auth/session`. Returns the current
authenticated `Principal` and the matching Better-Auth session row, or
`null` for both fields when the request is anonymous. The endpoint is
the canonical "who am I" call for client SDKs and SSR hydration.

## Features

- `GetSessionResponseSchema` — `{ user: PrincipalSchema | null;
  session: SessionSchema | null }` so the response carries the exact
  same wire shape as `c.get("user")` plus the session row.
- Anonymous callers see `{ user: null, session: null }` — a 200 with
  null fields rather than a 401, so client SDKs can probe identity
  without error handling.

## Usage: Basic

```ts
import { GetSessionResponseSchema } from "@suaveplan/api-plugin-auth/schemas/routes";

const parsed = GetSessionResponseSchema.parse({ user: null, session: null });
```

## Usage: Advanced

Pair the schema with a route definition that lists both anonymous and
authenticated cases in the OpenAPI document so consumers know the
endpoint never 401s:

```ts
import { GET, successResponse } from "@suaveplan/api-openapi";
import {
    GetSessionResponseSchema,
} from "@suaveplan/api-plugin-auth/schemas/routes";

const sessionRoute = GET("/auth/session")
    .tags("auth")
    .summary("Resolve the current session, if any")
    .response(successResponse(GetSessionResponseSchema))
    .build();
```

## API Reference

### `GetSessionResponseSchema`

`{ user: PrincipalSchema | null; session: SessionSchema | null }`.
Inferred type `GetSessionResponse`.

## Implementation Notes

- Returning `null` for the anonymous case keeps the endpoint cacheable
  per cookie — a 401 response would force the CDN to either skip caching
  or treat the page as private. Some host setups place this endpoint
  behind a Service-Worker cache.
- The schema mirrors the runtime shape installed by the session
  middleware so consumers can use the same type to read either the HTTP
  response body or `c.get("user")` / `c.get("session")`.
- Better-Auth's session row carries plugin-extended fields (org
  membership, impersonation) — those are tolerated via the loose schema
  shape on `SessionSchema` so the API is forward-compatible.