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

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:

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.

2.2 KiB Raw Blame History