# @loma-portal/api-contracts

Single source of truth for request / response shapes shared across frontends and backends. Zod schemas double as runtime validators (used by Next.js Server Actions, NestJS pipes, Angular `BaseApiService` typings).

| Surface | Schema                                                                   | Why                                   |
| ------- | ------------------------------------------------------------------------ | ------------------------------------- |
| Auth    | `loginRequestSchema`, `loginResponseSchema`, `authTokensSchema`          | Both frontends call `/api/auth/login` |
| User    | `userListItemSchema`, `userQuerySchema`                                  | Admin user list page                  |
| Common  | `apiResponseSchema(T)`, `pagedResponseSchema(T)`, `problemDetailsSchema` | RFC 7807 + envelope                   |

## Why hand-written Zod over generated OpenAPI types

- One source of truth for **runtime validation** + types.
- The .NET API emits OpenAPI (Phase 4); we will generate **types** from it in Phase 8 (`pnpm generate:openapi`) but keep Zod as the validator layer.
- Angular's `BaseApiService` accepts a Zod schema to validate responses in dev mode.

## Conventions

- Use `cuidSchema` for IDs.
- ISO 8601 strings for timestamps (`z.string().datetime()`).
- Pagination via `paginationParamsSchema.extend({ ... })`.
- Don't import server-only modules here — this package runs in the browser too.
