// Un servidor de pagos mínimo: POST /charges no tiene una regla que frene un
// duplicado, como sí la tiene una cancha ocupada. Sirve para ver el reintento
// que cobra dos veces y lo que cambia con una clave de idempotencia.
import http from 'node:http';
import type { AddressInfo } from 'node:net';
import { withIdempotency, type IdempotencyEntry, type OperationResponse } from './idempotency.ts';

export type Charge = { id: number; memberId: number; cents: number };

export type ChargesServer = { url: string; charges: Charge[]; close(): Promise<void> };

const DAY_MS = 24 * 60 * 60 * 1000;

export async function startChargesServer(options: { requireKey: boolean }): Promise<ChargesServer> {
  const charges: Charge[] = [];
  const operation = async (request: Omit<Charge, 'id'>): Promise<OperationResponse> => {
    const charge = { id: charges.length + 1, ...request };
    charges.push(charge);
    return { status: 201, body: { charge } };
  };
  const store = new Map<string, IdempotencyEntry>();
  const idempotent = withIdempotency(store, operation, { now: Date.now, ttlMs: DAY_MS });

  const server = http.createServer(async (req, res) => {
    const chunks: Buffer[] = [];
    for await (const chunk of req) chunks.push(chunk as Buffer);
    const request = JSON.parse(Buffer.concat(chunks).toString('utf8')) as Omit<Charge, 'id'>;
    const key = req.headers['idempotency-key'];
    const result = options.requireKey
      ? await idempotent(typeof key === 'string' ? key : undefined, request)
      : await operation(request);
    res.writeHead(result.status, { 'content-type': 'application/json' });
    res.end(JSON.stringify(result.body));
  });
  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
  const { port } = server.address() as AddressInfo;
  return {
    url: `http://127.0.0.1:${port}`,
    charges,
    close: () =>
      new Promise<void>((resolve, reject) => {
        server.closeAllConnections();
        server.close((error) => (error ? reject(error) : resolve()));
      }),
  };
}

// Ilustración escrita para la clase: un cliente HTTP como los que suele
// proponer un agente cuando no tiene a la vista la especificación. Compila,
// corre y no lanza ningún error, pero dos de sus campos no existen.
export const FIELDS_USED = ['courts[].courtName', 'courts[].sportType'];

export async function courtLabels(baseUrl: string): Promise<string[]> {
  const response = await fetch(`${baseUrl}/api/courts`);
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const data: any = await response.json();
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  return data.courts.map((court: any) => `${court.courtName} (${court.sportType})`);
}

// Un validador mínimo de JSON Schema, solo con lo que usa la especificación de
// Kallpa, para comparar respuestas reales con openapi.yaml ya empaquetado como
// JSON (make: redocly bundle). No reemplaza a una biblioteca de validación.
export type Schema = {
  $ref?: string;
  type?: string | string[];
  required?: string[];
  properties?: Record<string, Schema>;
  items?: Schema;
  enum?: unknown[];
  minimum?: number;
  maximum?: number;
  maxLength?: number;
  minLength?: number;
};

export type OpenApi = {
  paths: Record<string, Record<string, Operation>>;
  components?: { schemas?: Record<string, Schema>; responses?: Record<string, ResponseSpec> };
};
type ResponseSpec = { $ref?: string; content?: Record<string, { schema: Schema }> };
type Operation = { responses: Record<string, ResponseSpec> };

function resolve(spec: OpenApi, schema: Schema): Schema {
  if (schema.$ref === undefined) return schema;
  const name = schema.$ref.replace('#/components/schemas/', '');
  const target = spec.components?.schemas?.[name];
  if (!target) throw new Error(`$ref sin destino: ${schema.$ref}`);
  return target;
}

function typeOf(value: unknown): string {
  if (value === null) return 'null';
  if (Array.isArray(value)) return 'array';
  if (Number.isInteger(value)) return 'integer';
  return typeof value;
}

// Devuelve la lista de discrepancias: vacía si el valor cumple el esquema.
export function validate(spec: OpenApi, value: unknown, rawSchema: Schema, path = '$'): string[] {
  const schema = resolve(spec, rawSchema);
  const problems: string[] = [];
  if (schema.type !== undefined) {
    const allowed = Array.isArray(schema.type) ? schema.type : [schema.type];
    const actual = typeOf(value);
    if (!allowed.includes(actual) && !(actual === 'integer' && allowed.includes('number'))) {
      return [`${path}: se esperaba ${allowed.join(' o ')} y llegó ${actual}`];
    }
  }
  if (schema.enum && !schema.enum.includes(value)) problems.push(`${path}: ${JSON.stringify(value)} no está en el enum`);
  if (typeof value === 'number') {
    if (schema.minimum !== undefined && value < schema.minimum) problems.push(`${path}: menor que ${schema.minimum}`);
    if (schema.maximum !== undefined && value > schema.maximum) problems.push(`${path}: mayor que ${schema.maximum}`);
  }
  if (typeof value === 'string') {
    if (schema.maxLength !== undefined && value.length > schema.maxLength) problems.push(`${path}: más largo que ${schema.maxLength}`);
    if (schema.minLength !== undefined && value.length < schema.minLength) problems.push(`${path}: más corto que ${schema.minLength}`);
  }
  if (Array.isArray(value) && schema.items) {
    value.forEach((item, i) => problems.push(...validate(spec, item, schema.items!, `${path}[${i}]`)));
  }
  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
    const fields = value as Record<string, unknown>;
    for (const name of schema.required ?? []) {
      if (!(name in fields)) problems.push(`${path}.${name}: falta`);
    }
    for (const [name, property] of Object.entries(schema.properties ?? {})) {
      if (name in fields) problems.push(...validate(spec, fields[name], property, `${path}.${name}`));
    }
  }
  return problems;
}

// El esquema de una respuesta: responseSchema(spec, '/api/courts', 'get', '200').
export function responseSchema(spec: OpenApi, path: string, method: string, status: string): Schema {
  const declared = spec.paths[path]?.[method]?.responses?.[status];
  if (!declared) throw new Error(`la especificación no declara ${method} ${path} ${status}`);
  const response = declared.$ref
    ? spec.components?.responses?.[declared.$ref.replace('#/components/responses/', '')]
    : declared;
  const schema = response?.content?.['application/json']?.schema;
  if (!schema) throw new Error(`${method} ${path} ${status} no declara un cuerpo JSON`);
  return schema;
}

// ¿Existe este campo en el esquema? 'courts[].name' recorre objetos y arreglos.
export function fieldExists(spec: OpenApi, rawSchema: Schema, fieldPath: string): boolean {
  let schema = resolve(spec, rawSchema);
  for (const part of fieldPath.split('.')) {
    const isArray = part.endsWith('[]');
    const name = isArray ? part.slice(0, -2) : part;
    const next = schema.properties?.[name];
    if (!next) return false;
    schema = resolve(spec, next);
    if (isArray) {
      if (!schema.items) return false;
      schema = resolve(spec, schema.items);
    }
  }
  return true;
}

diff --git a/src/http/server.ts b/src/http/server.ts
index 251064b..09ac4b5 100644
--- a/src/http/server.ts
+++ b/src/http/server.ts
@@ -1,4 +1,4 @@
-import http from 'node:http';
+import http, { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { DatabaseSync } from 'node:sqlite';
 import { systemClock, type Clock } from '../domain/clock.ts';
 import { consoleNotifier, type Notifier } from '../notifications/notifier.ts';
@@ -36,27 +36,13 @@ export function buildRouter(deps: AppDependencies): Router {
   return router;
 }
 
-export function createServer(options: ServerOptions): http.Server {
-  const deps: AppDependencies = {
-    service: new BookingService(options.db),
-    clock: options.clock ?? systemClock,
-    notifier: options.notifier ?? consoleNotifier,
-  };
-  const log = options.log ?? console.log;
-  const router = buildRouter(deps);
+type RawHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 
-  return http.createServer(async (req, res) => {
-    const url = new URL(req.url ?? '/', 'http://localhost');
+// Convierte cualquier error en una respuesta JSON.
+function withErrors(next: RawHandler): RawHandler {
+  return async (req, res) => {
     try {
-      if (req.method === 'GET' && (await serveStatic(url.pathname, res))) return;
-      const match = router.match(req.method ?? 'GET', url.pathname);
-      if (match.kind === 'not-found') {
-        throw new HttpError(404, 'NOT_FOUND', `No existe la ruta ${url.pathname}.`);
-      }
-      if (match.kind === 'method-not-allowed') {
-        throw new HttpError(405, 'METHOD_NOT_ALLOWED', `${req.method} no está permitido en ${url.pathname}.`);
-      }
-      await match.handler({ req, res, url, params: match.params });
+      await next(req, res);
     } catch (error) {
       if (error instanceof HttpError) {
         sendError(res, error);
@@ -64,8 +50,45 @@ export function createServer(options: ServerOptions): http.Server {
         console.error(error);
         sendError(res, new HttpError(500, 'INTERNAL_ERROR', 'Ocurrió un error inesperado.'));
       }
+    }
+  };
+}
+
+// Escribe una línea de log al terminar, pase lo que pase. Va por fuera de
+// withErrors para ver el código de estado que de verdad se respondió.
+function withLog(log: (line: string) => void, next: RawHandler): RawHandler {
+  return async (req, res) => {
+    try {
+      await next(req, res);
     } finally {
       log(`${req.method} ${req.url} ${res.statusCode}`);
     }
-  });
+  };
+}
+
+function dispatcher(router: Router): RawHandler {
+  return async (req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (req.method === 'GET' && (await serveStatic(url.pathname, res))) return;
+    const match = router.match(req.method ?? 'GET', url.pathname);
+    if (match.kind === 'not-found') {
+      throw new HttpError(404, 'NOT_FOUND', `No existe la ruta ${url.pathname}.`);
+    }
+    if (match.kind === 'method-not-allowed') {
+      throw new HttpError(405, 'METHOD_NOT_ALLOWED', `${req.method} no está permitido en ${url.pathname}.`);
+    }
+    await match.handler({ req, res, url, params: match.params });
+  };
+}
+
+export function createServer(options: ServerOptions): http.Server {
+  const deps: AppDependencies = {
+    service: new BookingService(options.db),
+    clock: options.clock ?? systemClock,
+    notifier: options.notifier ?? consoleNotifier,
+  };
+  const log = options.log ?? console.log;
+  const router = buildRouter(deps);
+
+  return http.createServer(withLog(log, withErrors(dispatcher(router))));
 }

// Las mismas reglas que Kallpa: las recomendadas de JavaScript y de
// typescript-eslint.
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import { defineConfig } from 'eslint/config';

export default defineConfig(
  { ignores: ['build/', 'solution/'] },
  js.configs.recommended,
  tseslint.configs.recommended,
);

// Tres clientes HTTP de la misma respuesta de disponibilidad, y los cambios de
// la API que cada uno aguanta. Los cambios se simulan sobre la respuesta real.
export type Slot = { hour: number; available: boolean; teamName?: string };
export type Availability = { courtId: number; date: string; slots: Slot[] };

// Lee solo lo que necesita e ignora lo demás.
export function freeHoursTolerant(body: Availability): number[] {
  return body.slots.filter((slot) => slot.available).map((slot) => slot.hour);
}

// Exige exactamente los campos que vio el día que lo escribieron.
export function freeHoursStrict(body: Availability): number[] {
  for (const slot of body.slots) {
    const allowed = ['hour', 'available', 'teamName'];
    const unknown = Object.keys(slot).filter((key) => !allowed.includes(key));
    if (unknown.length > 0) throw new Error(`campo desconocido: ${unknown.join(', ')}`);
  }
  return freeHoursTolerant(body);
}

// Lee el arreglo suelto de GET /api/members/:id/bookings.
export function countConfirmed(body: { status: string }[]): number {
  return body.filter((booking) => booking.status === 'confirmed').length;
}

// Decide qué mostrar según el código de estado.
export function errorKind(status: number): 'revise-el-formulario' | 'no-se-puede' | 'desconocido' {
  if (status === 400) return 'revise-el-formulario';
  if (status === 409) return 'no-se-puede';
  return 'desconocido';
}

// Los cambios que clasifica el capítulo.
export function addPriceField(body: Availability): unknown {
  return { ...body, slots: body.slots.map((slot) => ({ ...slot, priceCents: 9000 })) };
}

export function renameHourField(body: Availability): unknown {
  return {
    ...body,
    slots: body.slots.map(({ hour, ...rest }) => ({ startHour: hour, ...rest })),
  };
}

// Una clave de idempotencia como decorator de una operación: la operación no
// sabe nada de claves. La memoria es un Map para mostrar la lógica; en un
// sistema real la clave se guarda en la misma transacción que el efecto.
import { createHash } from 'node:crypto';

export type OperationResponse = { status: number; body: unknown };

export type IdempotencyEntry =
  | { state: 'in-progress'; fingerprint: string; storedAt: number }
  | { state: 'done'; fingerprint: string; storedAt: number; response: OperationResponse };

export type IdempotencyOptions = {
  now: () => number; // milisegundos; se inyecta para probar el vencimiento
  ttlMs: number;
};

export type Replayable = OperationResponse & { replayed: boolean };

// El mismo contenido da la misma huella, en cualquier orden de campos.
export function fingerprint(request: unknown): string {
  return createHash('sha256').update(canonicalJson(request)).digest('hex');
}

export function canonicalJson(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
  if (typeof value === 'object' && value !== null) {
    const fields = Object.entries(value)
      .sort(([a], [b]) => (a < b ? -1 : 1))
      .map(([key, field]) => `${JSON.stringify(key)}:${canonicalJson(field)}`);
    return `{${fields.join(',')}}`;
  }
  return JSON.stringify(value);
}

function errorResponse(status: number, code: string, message: string): Replayable {
  return { status, body: { error: { code, message } }, replayed: false };
}

export function withIdempotency<Request>(
  store: Map<string, IdempotencyEntry>,
  operation: (request: Request) => Promise<OperationResponse>,
  options: IdempotencyOptions,
) {
  return async (key: string | undefined, request: Request): Promise<Replayable> => {
    if (key === undefined) {
      return errorResponse(400, 'IDEMPOTENCY_KEY_MISSING', 'Esta operación pide la cabecera Idempotency-Key.');
    }
    const print = fingerprint(request);
    const now = options.now();
    const existing = store.get(key);
    if (existing && now - existing.storedAt < options.ttlMs) {
      if (existing.fingerprint !== print) {
        return errorResponse(422, 'IDEMPOTENCY_KEY_REUSED', 'Esa clave ya se usó con otro cuerpo.');
      }
      if (existing.state === 'in-progress') {
        return errorResponse(409, 'REQUEST_IN_PROGRESS', 'La primera solicitud con esa clave todavía se procesa.');
      }
      return { ...existing.response, replayed: true };
    }
    // Se marca antes del primer await: un reintento concurrente ya ve la clave.
    store.set(key, { state: 'in-progress', fingerprint: print, storedAt: now });
    try {
      const response = await operation(request);
      store.set(key, { state: 'done', fingerprint: print, storedAt: now, response });
      return { ...response, replayed: false };
    } catch (error) {
      // No se sabe qué pasó: se libera la clave para que un reintento pueda
      // volver a correr la operación.
      store.delete(key);
      throw error;
    }
  };
}

// Una red que falla en el peor momento: el servidor recibe la solicitud y la
// procesa, pero quien llama nunca ve la respuesta porque la conexión se corta.
import http from 'node:http';
import type { AddressInfo } from 'node:net';

export type FlakyProxy = { url: string; close(): Promise<void> };

// Reenvía todo al servidor real. Las primeras `drops` respuestas no llegan.
export async function startFlakyProxy(target: string, drops = 1): Promise<FlakyProxy> {
  let remaining = drops;
  const server = http.createServer(async (req, res) => {
    const chunks: Buffer[] = [];
    for await (const chunk of req) chunks.push(chunk as Buffer);
    const headers = new Headers();
    for (const [name, value] of Object.entries(req.headers)) {
      if (typeof value === 'string' && name !== 'host' && name !== 'connection') headers.set(name, value);
    }
    const upstream = await fetch(`${target}${req.url}`, {
      method: req.method,
      headers,
      body: chunks.length > 0 ? Buffer.concat(chunks) : undefined,
    });
    const text = await upstream.text();
    if (remaining > 0) {
      remaining--;
      req.socket.destroy(); // el servidor ya hizo su trabajo; la respuesta se pierde
      return;
    }
    res.writeHead(upstream.status, { 'content-type': 'application/json' });
    res.end(text);
  });
  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
  const { port } = server.address() as AddressInfo;
  return {
    url: `http://127.0.0.1:${port}`,
    close: () =>
      new Promise<void>((resolve, reject) => {
        server.closeAllConnections();
        server.close((error) => (error ? reject(error) : resolve()));
      }),
  };
}

export type Attempt =
  | { kind: 'response'; status: number; body: unknown }
  | { kind: 'connection-lost'; message: string };

// Lo que hace una app al reintentar: POST, y si se corta, otra vez lo mismo.
export async function postWithRetry(
  url: string,
  body: unknown,
  headers: Record<string, string> = {},
  maxAttempts = 2,
): Promise<Attempt[]> {
  const attempts: Attempt[] = [];
  for (let i = 0; i < maxAttempts; i++) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: { 'content-type': 'application/json', ...headers },
        body: JSON.stringify(body),
      });
      attempts.push({ kind: 'response', status: response.status, body: await response.json() });
      return attempts;
    } catch (error) {
      attempts.push({ kind: 'connection-lost', message: (error as Error).message });
    }
  }
  return attempts;
}

openapi: 3.1.0
info:
  title: Kallpa API
  version: 1.0.0
  description: Reservas de canchas.
security: []
servers:
  - url: http://localhost:3000
paths:
  /api/courts:
    get:
      operationId: listCourts
      summary: Lista las canchas
      responses:
        '200':
          description: Las canchas
          content:
            application/json:
              schema:
                type: object
                required: [courts]
                properties:
                  courts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Court'
components:
  schemas:
    Court:
      type: object
      required: [id, name, sport]
      properties:
        id: { type: integer }
        name: { type: string }
        sport: { type: string, enum: [fulbito, voley, basquet] }
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string }
            message: { type: string }

#!/usr/bin/env bash
# Las dos versiones conviviendo, en la copia de Kallpa que deja make v2.
set -euo pipefail

export PORT="${PORT:-3101}"
cd build/v2
rm -f data/kallpa.db data/kallpa.db-*
make --no-print-directory seed > /dev/null
node src/main.ts > /tmp/kallpa-v2.log 2>&1 &
SERVER=$!
trap 'kill "$SERVER"' EXIT
sleep 1

for path in members/5/bookings v2/members/5/bookings; do
  echo "\$ curl -s -i localhost:$PORT/api/$path"
  curl -s -i "localhost:$PORT/api/$path" | tr -d '\r' \
    | grep -v -i -E '^(date|connection|keep-alive|content-length|content-type):' \
    | grep -v '^$' | cut -c1-90
  echo
done
tail -2 /tmp/kallpa-v2.log

#!/usr/bin/env bash
# Reserva, reintenta y cancela dos veces en una copia de Kallpa, como el paso 2
# del laboratorio. Las fechas dependen del día en que se corre.
set -euo pipefail

export PORT="${PORT:-3100}"
cd build/kallpa
rm -f data/kallpa.db data/kallpa.db-*
make --no-print-directory seed
node src/main.ts > /tmp/kallpa-recorrido.log 2>&1 &
SERVER=$!
trap 'kill "$SERVER"' EXIT
sleep 1

API="localhost:$PORT"
D=$(date -d '+8 days' +%F)
BODY="{\"courtId\":2,\"memberId\":2,\"date\":\"$D\",\"startHour\":10,\"teamName\":\"Los Halcones\"}"
JSON='content-type: application/json'

# Muestra la línea de estado, las cabeceras que importan aquí y el cuerpo.
show() {
  echo "\$ curl $*"
  curl -s -i "$@" | tr -d '\r' \
    | grep -v -i -E '^(date|connection|keep-alive|content-length|content-type):' \
    | grep -v '^$' | cut -c1-200
  echo
}

echo "--- reservar y reintentar"
show -X POST "$API/api/bookings" -H "$JSON" -d "$BODY"
show -X POST "$API/api/bookings" -H "$JSON" -d "$BODY"

ID=$(curl -s "$API/api/members/2/bookings" | jq 'map(select(.teamName == "Los Halcones"))[0].id')

echo "--- cancelar dos veces"
show -X POST "$API/api/bookings/$ID/cancel"
show -X POST "$API/api/bookings/$ID/cancel"

echo "--- dos errores: la frase de estado la pone Node"
show -X POST "$API/api/bookings" -H "$JSON" -d "{\"courtId\":2,\"memberId\":2,\"date\":\"$D\",\"startHour\":10,\"hours\":4,\"teamName\":\"X\"}"
node -e 'console.log(JSON.stringify({ teamName: "x".repeat(17000) }))' > /tmp/kallpa-grande.json
show -X POST "$API/api/bookings" -H "$JSON" --data @/tmp/kallpa-grande.json

// make retry: lo que ve quien llama cuando la primera respuesta se pierde.
import { startTestServer } from './build/kallpa/test/helpers.ts';
import { startChargesServer } from './charges-server.ts';
import { postWithRetry, startFlakyProxy, type Attempt } from './lost-response.ts';

function print(title: string, attempts: Attempt[]): void {
  console.log(title);
  attempts.forEach((attempt, i) => {
    const seen =
      attempt.kind === 'response'
        ? `${attempt.status} ${JSON.stringify(attempt.body)}`
        : `se cortó la conexión (${attempt.message})`;
    console.log(`  intento ${i + 1}: ${seen}`);
  });
}

const kallpa = await startTestServer();
const proxyK = await startFlakyProxy(kallpa.url);
const booking = { courtId: 2, memberId: 2, date: '2026-03-17', startHour: 10, teamName: 'Los Halcones' };
print('Kallpa, POST /api/bookings', await postWithRetry(`${proxyK.url}/api/bookings`, booking));
const list = await (await fetch(`${kallpa.url}/api/members/2/bookings`)).json();
console.log(`  reservas del vecino 2 en la base de datos: ${list.length}\n`);
await proxyK.close();
await kallpa.close();

const plain = await startChargesServer({ requireKey: false });
const proxyP = await startFlakyProxy(plain.url);
print('Pagos sin clave, POST /charges', await postWithRetry(`${proxyP.url}/charges`, { memberId: 2, cents: 8100 }));
console.log(`  cobros en la base de datos: ${plain.charges.length}\n`);
await proxyP.close();
await plain.close();

const keyed = await startChargesServer({ requireKey: true });
const proxyI = await startFlakyProxy(keyed.url);
const key = { 'idempotency-key': '"8e03978e-40d5-43e8-bc93-6894a57f9324"' };
print('Pagos con clave, POST /charges', await postWithRetry(`${proxyI.url}/charges`, { memberId: 2, cents: 8100 }, key));
console.log(`  cobros en la base de datos: ${keyed.charges.length}`);
await proxyI.close();
await keyed.close();

diff --git a/src/http/handlers.ts b/src/http/handlers.ts
index 4f1354a..ec3043e 100644
--- a/src/http/handlers.ts
+++ b/src/http/handlers.ts
@@ -143,12 +143,30 @@ export function cancelBooking(deps: AppDependencies): Handler {
   };
 }
 
-// GET /api/members/:id/bookings
+// La v1 sigue respondiendo igual: solo se anuncia su fin (RFC 9745 y RFC 8594).
+export const MEMBER_BOOKINGS_V1_DEPRECATED_AT = 1798761600; // 1 de enero de 2027, 00:00 UTC
+export const MEMBER_BOOKINGS_V1_SUNSET = 'Sat, 01 Jan 2028 00:00:00 GMT';
+
+function bookingsOfMember(deps: AppDependencies, id: string): Booking[] {
+  const member = deps.service.findMember(Number(id));
+  if (!member) throw new HttpError(404, 'MEMBER_NOT_FOUND', `No existe el miembro ${id}.`);
+  return deps.service.bookingsForMember(member.id).map(toBookingJson);
+}
+
+// GET /api/members/:id/bookings: arreglo suelto, deprecado.
 export function memberBookings(deps: AppDependencies): Handler {
   return ({ res, params }) => {
-    const member = deps.service.findMember(Number(params.id));
-    if (!member) throw new HttpError(404, 'MEMBER_NOT_FOUND', `No existe el miembro ${params.id}.`);
-    sendJson(res, 200, deps.service.bookingsForMember(member.id).map(toBookingJson));
+    res.setHeader('Deprecation', `@${MEMBER_BOOKINGS_V1_DEPRECATED_AT}`);
+    res.setHeader('Sunset', MEMBER_BOOKINGS_V1_SUNSET);
+    res.setHeader('Link', `</api/v2/members/${params.id}/bookings>; rel="successor-version"`);
+    sendJson(res, 200, bookingsOfMember(deps, params.id));
+  };
+}
+
+// GET /api/v2/members/:id/bookings: un objeto, que puede crecer.
+export function memberBookingsV2(deps: AppDependencies): Handler {
+  return ({ res, params }) => {
+    sendJson(res, 200, { bookings: bookingsOfMember(deps, params.id) });
   };
 }
 
diff --git a/src/http/server.ts b/src/http/server.ts
index 251064b..5820ff3 100644
--- a/src/http/server.ts
+++ b/src/http/server.ts
@@ -11,6 +11,7 @@ import {
   listCourts,
   listMembers,
   memberBookings,
+  memberBookingsV2,
   type AppDependencies,
 } from './handlers.ts';
 import { HttpError, sendError } from './json.ts';
@@ -30,6 +31,7 @@ export function buildRouter(deps: AppDependencies): Router {
   router.get('/api/courts/:id/availability', courtAvailability(deps));
   router.get('/api/members', listMembers(deps));
   router.get('/api/members/:id/bookings', memberBookings(deps));
+  router.get('/api/v2/members/:id/bookings', memberBookingsV2(deps));
   router.post('/api/bookings', createBooking(deps));
   router.post('/api/bookings/:id/cancel', cancelBooking(deps));
   router.get('/api/reports/daily', dailyReport(deps));
diff --git a/test/v2.test.ts b/test/v2.test.ts
new file mode 100644
index 0000000..e4f764a
--- /dev/null
+++ b/test/v2.test.ts
@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import { after, before, describe, test } from 'node:test';
+import { postJson, startTestServer, type TestServer } from './helpers.ts';
+
+// El reloj de las pruebas marca el lunes 9 de marzo de 2026 a las 10:00.
+describe('las reservas de un vecino, en v1 y en v2', () => {
+  let server: TestServer;
+
+  before(async () => {
+    server = await startTestServer();
+    await postJson(`${server.url}/api/bookings`, { courtId: 1, memberId: 2, date: '2026-03-11', startHour: 10, teamName: 'Real Barranco' });
+  });
+
+  after(async () => {
+    await server.close();
+  });
+
+  test('v1 responde lo mismo que antes y anuncia su fin', async () => {
+    const response = await fetch(`${server.url}/api/members/2/bookings`);
+    const body = await response.json();
+    assert.equal(response.status, 200);
+    assert.ok(Array.isArray(body));
+    assert.equal(response.headers.get('deprecation'), '@1798761600');
+    assert.equal(response.headers.get('sunset'), 'Sat, 01 Jan 2028 00:00:00 GMT');
+    assert.equal(response.headers.get('link'), '</api/v2/members/2/bookings>; rel="successor-version"');
+  });
+
+  test('el fin no es anterior a la deprecación', async () => {
+    const response = await fetch(`${server.url}/api/members/2/bookings`);
+    const deprecation = Number(response.headers.get('deprecation')!.slice(1)) * 1000;
+    assert.ok(Date.parse(response.headers.get('sunset')!) >= deprecation);
+  });
+
+  test('v2 devuelve las mismas reservas dentro de un objeto y sin aviso', async () => {
+    const v1 = await (await fetch(`${server.url}/api/members/2/bookings`)).json();
+    const response = await fetch(`${server.url}/api/v2/members/2/bookings`);
+    assert.deepEqual(await response.json(), { bookings: v1 });
+    assert.equal(response.headers.get('deprecation'), null);
+  });
+
+  test('los errores no cambian entre versiones', async () => {
+    const response = await fetch(`${server.url}/api/v2/members/99/bookings`);
+    assert.equal(response.status, 404);
+    assert.equal(((await response.json()) as { error: { code: string } }).error.code, 'MEMBER_NOT_FOUND');
+  });
+});

# Un error que Redocly sí encuentra: el $ref apunta a un esquema que no existe.
openapi: 3.1.0
info:
  title: Kallpa API
  version: 1.0.0
security: []
servers:
  - url: http://localhost:3000
paths:
  /api/courts:
    get:
      operationId: listCourts
      summary: Lista las canchas
      responses:
        '200':
          description: Las canchas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Courts'
components:
  schemas:
    Court:
      type: object
      properties:
        id: { type: integer }

# Un error que Redocly no puede encontrar: el documento es válido, pero Kallpa
# responde 200 con { booking }, no 201 con { id }. Lint compara la especificación
# con las reglas de OpenAPI, no con el servidor.
openapi: 3.1.0
info:
  title: Kallpa API
  version: 1.0.0
security: []
servers:
  - url: http://localhost:3000
paths:
  /api/bookings:
    post:
      operationId: createBooking
      summary: Reserva una cancha
      responses:
        '201':
          description: La reserva creada
          content:
            application/json:
              schema:
                type: object
                required: [id]
                properties:
                  id: { type: integer }
        '409':
          description: La cancha está ocupada

// Adapter: el proveedor tiene su interfaz y Kallpa espera otra. El proveedor de
// este archivo es inventado para la clase: la forma de sus mensajes no copia la
// API de ninguna empresa.
import type { BookingConfirmation, Notifier } from '../build/kallpa/src/notifications/notifier.ts';

export type TemplateMessage = {
  to: string; // con código de país: +51987654321
  template: string;
  params: string[];
};

export type MessagingProvider = {
  sendTemplate(message: TemplateMessage): void;
};

// Lo único que sabe de los dos lados: traduce una llamada en la otra.
export function messagingNotifier(provider: MessagingProvider): Notifier {
  return {
    bookingConfirmed(c: BookingConfirmation) {
      provider.sendTemplate({
        to: `+51${c.phone}`,
        template: 'reserva_confirmada',
        params: [c.memberName, c.courtName, c.date, `${c.startHour}:00`, String(c.hours), String(c.priceCents)],
      });
    },
  };
}

// Decorator: una función envuelve a otra de la misma forma y agrega algo antes
// o después, sin que la de adentro se entere. Es lo que hace decorator-server.diff
// con el try/catch/finally de src/http/server.ts.
import type { IncomingMessage, ServerResponse } from 'node:http';
import { HttpError, sendError } from '../build/kallpa/src/http/json.ts';

export type RawHandler = (req: IncomingMessage, res: ServerResponse) => Promise<void>;

export function withErrors(next: RawHandler): RawHandler {
  return async (req, res) => {
    try {
      await next(req, res);
    } catch (error) {
      if (error instanceof HttpError) {
        sendError(res, error);
      } else {
        sendError(res, new HttpError(500, 'INTERNAL_ERROR', 'Ocurrió un error inesperado.'));
      }
    }
  };
}

export function withLog(log: (line: string) => void, next: RawHandler): RawHandler {
  return async (req, res) => {
    try {
      await next(req, res);
    } finally {
      log(`${req.method} ${req.url} ${res.statusCode}`);
    }
  };
}

// Observer con EventEmitter: la reserva avisa que se confirmó y no sabe quién
// escucha. Los eventos están tipados para que tsc revise el nombre y el dato.
import { EventEmitter } from 'node:events';

export type BookingConfirmedEvent = { bookingId: number; courtId: number; priceCents: number };

type BookingEvents = {
  'booking-confirmed': [BookingConfirmedEvent];
};

export function createBookingEvents(): EventEmitter<BookingEvents> {
  return new EventEmitter<BookingEvents>();
}

// Quien produce el evento: guarda y emite. No importa a nadie de los que reaccionan.
export function confirmBooking(
  events: EventEmitter<BookingEvents>,
  saved: BookingConfirmedEvent[],
  booking: BookingConfirmedEvent,
): void {
  saved.push(booking);
  events.emit('booking-confirmed', booking);
}

// Lo que un patrón no debería hacer: dos ejemplos escritos para discutir en una
// revisión de código.
import { consoleNotifier, type Notifier } from '../build/kallpa/src/notifications/notifier.ts';
import type { Clock } from '../build/kallpa/src/domain/clock.ts';

// Una fábrica con una sola implementación. Ilustración de la ceremonia que a
// veces proponen un agente o un programador con el libro recién leído.
export interface NotifierFactory {
  create(): Notifier;
}

export class ConsoleNotifierFactory implements NotifierFactory {
  create(): Notifier {
    return consoleNotifier;
  }
}

export class NotifierFactoryProvider {
  getFactory(): NotifierFactory {
    return new ConsoleNotifierFactory();
  }
}

// Una factory function que sí hace algo: elige la implementación según un dato.
export function notifierFor(channel: 'console' | 'silent'): Notifier {
  return channel === 'console' ? consoleNotifier : { bookingConfirmed() {} };
}

// Un Singleton: estado global con otro nombre. Quien lo cambia afecta a todos.
export class GlobalClock implements Clock {
  static #instance: GlobalClock | undefined;
  #fixed: Date | undefined;

  static getInstance(): GlobalClock {
    GlobalClock.#instance ??= new GlobalClock();
    return GlobalClock.#instance;
  }

  fix(instant: string): void {
    this.#fixed = new Date(instant);
  }

  now(): Date {
    return this.#fixed ?? new Date();
  }
}

// El código que depende del Singleton no lo dice en su firma.
export function isMorningWithSingleton(): boolean {
  return GlobalClock.getInstance().now().getUTCHours() < 17; // 12:00 en Lima
}

// El mismo código con el reloj como parámetro.
export function isMorning(clock: Clock): boolean {
  return clock.now().getUTCHours() < 17;
}

// Strategy: el algoritmo que ordena las horas libres se cambia sin tocar a
// quien lo usa. Primero como lo escribiría el libro, con una interfaz y clases;
// después como función, que en TypeScript hace lo mismo.
export type Slot = { hour: number; available: boolean };

// Con interfaz y clases.
export interface HourRanker {
  compare(a: number, b: number): number;
}

export class EarliestFirst implements HourRanker {
  compare(a: number, b: number): number {
    return a - b;
  }
}

export class ClosestTo implements HourRanker {
  #target: number;

  constructor(target: number) {
    this.#target = target;
  }

  compare(a: number, b: number): number {
    return Math.abs(a - this.#target) - Math.abs(b - this.#target) || a - b;
  }
}

export function suggestWithRanker(slots: Slot[], ranker: HourRanker): number[] {
  return slots
    .filter((slot) => slot.available)
    .map((slot) => slot.hour)
    .sort((a, b) => ranker.compare(a, b));
}

// Con una función: el tipo de la estrategia es el de un comparador.
export type Rank = (a: number, b: number) => number;

export const earliestFirst: Rank = (a, b) => a - b;
export const closestTo =
  (target: number): Rank =>
  (a, b) =>
    Math.abs(a - target) - Math.abs(b - target) || a - b;

export function suggest(slots: Slot[], rank: Rank): number[] {
  return slots
    .filter((slot) => slot.available)
    .map((slot) => slot.hour)
    .sort(rank);
}

// Lo que el apunte dice de la API publicada de Kallpa, comprobado contra un
// servidor de prueba: base de datos en memoria y reloj fijo (lunes 9 de marzo
// de 2026, 10:00 en Lima).
import assert from 'node:assert/strict';
import { after, before, describe, test } from 'node:test';
import { startTestServer, type TestServer } from './build/kallpa/test/helpers.ts';

const request = { courtId: 2, memberId: 2, date: '2026-03-17', startHour: 10, teamName: 'Los Halcones' };

async function call(url: string, method = 'GET', body?: unknown) {
  const response = await fetch(url, {
    method,
    headers: body === undefined ? {} : { 'content-type': 'application/json' },
    body: body === undefined ? undefined : typeof body === 'string' ? body : JSON.stringify(body),
  });
  return { status: response.status, body: await response.json() };
}

describe('la API de Kallpa como es hoy', () => {
  let server: TestServer;

  before(async () => {
    server = await startTestServer();
  });

  after(async () => {
    await server.close();
  });

  test('la primera reserva se confirma', async () => {
    const { status, body } = await call(`${server.url}/api/bookings`, 'POST', request);
    assert.equal(status, 200);
    assert.equal(body.booking.status, 'confirmed');
  });

  test('un reintento de la misma reserva responde 409 SLOT_TAKEN, sin decir de quién es', async () => {
    const { status, body } = await call(`${server.url}/api/bookings`, 'POST', request);
    assert.equal(status, 409);
    assert.equal(body.error.code, 'SLOT_TAKEN');
    assert.equal(JSON.stringify(body).includes('booking"'), false);
  });

  test('el reintento no crea una segunda reserva', async () => {
    const { body } = await call(`${server.url}/api/members/2/bookings`);
    assert.equal(body.length, 1);
    assert.equal(server.sent.length, 1);
  });

  test('cancelar dos veces: el estado queda igual y la respuesta cambia', async () => {
    const list = await call(`${server.url}/api/members/2/bookings`);
    const id = list.body[0].id;
    const first = await call(`${server.url}/api/bookings/${id}/cancel`, 'POST');
    assert.equal(first.status, 200);
    assert.equal(first.body.booking.status, 'cancelled');
    const second = await call(`${server.url}/api/bookings/${id}/cancel`, 'POST');
    assert.equal(second.status, 409);
    assert.equal(second.body.error.code, 'ALREADY_CANCELLED');
    const after = await call(`${server.url}/api/members/2/bookings`);
    assert.deepEqual(after.body[0], first.body.booking);
  });

  test('reservar no es idempotente: si la reserva se canceló en el medio, el reintento crea otra', async () => {
    const date = '2026-03-18';
    const slot = { ...request, date };
    const first = await call(`${server.url}/api/bookings`, 'POST', slot);
    await call(`${server.url}/api/bookings/${first.body.booking.id}/cancel`, 'POST');
    const retry = await call(`${server.url}/api/bookings`, 'POST', slot);
    assert.equal(retry.status, 200);
    assert.notEqual(retry.body.booking.id, first.body.booking.id);
    const list = await call(`${server.url}/api/members/2/bookings`);
    const sameSlot = list.body.filter((b: { date: string }) => b.date === date);
    assert.equal(sameSlot.length, 2);
  });

  test('las listas tienen dos formas: objeto en canchas y miembros, arreglo suelto en las reservas de un vecino', async () => {
    assert.ok(Array.isArray((await call(`${server.url}/api/courts`)).body.courts));
    assert.ok(Array.isArray((await call(`${server.url}/api/members`)).body.members));
    assert.ok(Array.isArray((await call(`${server.url}/api/members/2/bookings`)).body));
  });

  test('todos los errores tienen la misma forma: error.code y error.message', async () => {
    const responses = [
      await call(`${server.url}/api/getCourts`),
      await call(`${server.url}/api/courts`, 'DELETE'),
      await call(`${server.url}/api/bookings`, 'POST', '{mal'),
      await call(`${server.url}/api/bookings/9999/cancel`, 'POST'),
      await call(`${server.url}/api/members/99/bookings`),
      await call(`${server.url}/api/reports/daily`),
    ];
    for (const { body } of responses) {
      assert.deepEqual(Object.keys(body), ['error']);
      assert.deepEqual(Object.keys(body.error), ['code', 'message']);
    }
    assert.deepEqual(
      responses.map((r) => r.status),
      [404, 405, 400, 404, 404, 400],
    );
  });

  test('un cuerpo de más de 16 KiB responde 413 BODY_TOO_LARGE', async () => {
    const big = JSON.stringify({ teamName: 'x'.repeat(17 * 1024) });
    const { status, body } = await call(`${server.url}/api/bookings`, 'POST', big);
    assert.equal(status, 413);
    assert.equal(body.error.code, 'BODY_TOO_LARGE');
  });
});

import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { after, before, describe, test } from 'node:test';
import { startTestServer, type TestServer } from './build/kallpa/test/helpers.ts';
import { courtLabels, FIELDS_USED } from './client-example.ts';
import { fieldExists, responseSchema, validate, type OpenApi } from './contract.ts';

const spec = JSON.parse(readFileSync('build/openapi.json', 'utf8')) as OpenApi;
const courts = responseSchema(spec, '/api/courts', 'get', '200');

describe('el esqueleto openapi.yaml contra Kallpa', () => {
  let server: TestServer;

  before(async () => {
    server = await startTestServer();
  });

  after(async () => {
    await server.close();
  });

  test('GET /api/courts responde lo que dice la especificación', async () => {
    const body = await (await fetch(`${server.url}/api/courts`)).json();
    assert.deepEqual(validate(spec, body, courts), []);
  });

  test('el validador encuentra un campo que falta y un valor fuera del enum', () => {
    const broken = { courts: [{ id: 1, name: 'Fulbito 1', sport: 'tenis' }, { id: 2, sport: 'voley' }] };
    assert.deepEqual(validate(spec, broken, courts), [
      '$.courts[0].sport: "tenis" no está en el enum',
      '$.courts[1].name: falta',
    ]);
  });

  test('el cliente de ejemplo corre sin errores y muestra basura', async () => {
    const labels = await courtLabels(server.url);
    assert.equal(labels.length, 4);
    assert.ok(labels.every((label) => label === 'undefined (undefined)'));
  });

  test('la especificación detecta los campos inventados sin correr el cliente', () => {
    assert.deepEqual(
      FIELDS_USED.filter((field) => !fieldExists(spec, courts, field)),
      ['courts[].courtName', 'courts[].sportType'],
    );
    assert.equal(fieldExists(spec, courts, 'courts[].name'), true);
    assert.equal(fieldExists(spec, courts, 'courts[].sport'), true);
  });

  test('el esqueleto declara security: [] y un esquema Error con code y message', () => {
    const raw = spec as unknown as { security: unknown[]; components: { schemas: Record<string, unknown> } };
    assert.deepEqual(raw.security, []);
    assert.ok(raw.components.schemas.Error);
  });
});