Initial Commit

packages/api-stack/api/api-schemas/src/auth/register.md

@@ -0,0 +1,74 @@
+# register
+
+## Purpose
+
+Provides Zod schemas for the user registration request and response shapes used by Suaveplan's `POST /auth/register` endpoint. These schemas are the single source of truth for the server route validator, the React registration mutation hook, and the OpenAPI document generator, ensuring that field names, length constraints, and TypeScript types are consistent across every layer without duplication.
+
+## Features
+
+- `RegisterInput` schema — validates email (RFC 5322), password (min 8 chars), and display name (1–200 chars)
+- `RegisterOutput` schema — returns the new user's `id`, `email`, and ISO 8601 `createdAt` timestamp
+- Password minimum-length policy applied at schema layer (8 characters)
+- Name length capped at 200 characters to prevent database overflow
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { RegisterInput } from "@suaveplan/api-schemas/auth";
+
+const input = RegisterInput.parse({
+  email: "alice@example.com",
+  password: "securePassword1",
+  name: "Alice Smith",
+});
+// → { email: "alice@example.com", password: "securePassword1", name: "Alice Smith" }
+```
+
+## Usage: Advanced Example
+
+```ts
+import { RegisterInput, RegisterOutput } from "@suaveplan/api-schemas/auth";
+
+async function handleRegister(rawBody: unknown): Promise<RegisterOutput> {
+  const { email, password, name } = RegisterInput.parse(rawBody);
+  const hashedPassword = await crypto.hashPassword(password);
+  const user = await db.user.create({ data: { email, passwordHash: hashedPassword, name } });
+  return RegisterOutput.parse({
+    id: user.id,
+    email: user.email,
+    createdAt: user.createdAt.toISOString(),
+  });
+}
+```
+
+## API Reference
+
+### `RegisterInput`
+
+Zod object schema — registration request body.
+
+| Field      | Type                      | Description                                  |
+|------------|---------------------------|----------------------------------------------|
+| `email`    | `string` (email)          | RFC 5322 valid email address                 |
+| `password` | `string` (min 8)          | Plaintext password; minimum 8 characters     |
+| `name`     | `string` (min 1, max 200) | Display name for the new user                |
+
+**Type export:** `type RegisterInput = z.infer<typeof RegisterInput>`
+
+### `RegisterOutput`
+
+Zod object schema — successful registration response.
+
+| Field       | Type                            | Description                            |
+|-------------|----------------------------------|----------------------------------------|
+| `id`        | `string` (min 1)                | Newly created user identifier           |
+| `email`     | `string` (email)                | Email address of the new user           |
+| `createdAt` | `string` (ISO 8601 with offset) | Account creation timestamp              |
+
+**Type export:** `type RegisterOutput = z.infer<typeof RegisterOutput>`
+
+## Implementation Notes
+
+The 8-character minimum on `password` is a deliberate schema-level policy choice for Suaveplan, aligning with NIST SP 800-63B guidance. Password complexity (uppercase, digits, special chars) is not enforced here — entropy-based policies are the responsibility of the auth service. The `createdAt` field uses `z.string().datetime({ offset: true })` rather than `z.date()` because JSON serialisation produces strings, not `Date` objects, and the schema layer should validate what actually travels over the wire.