// src/errors/api-error.js

/**
 * The API's domain error.
 *
 * It carries the information needed to build the response, but it is thrown
 * from the services without them knowing anything about Express: 'status' is
 * a number, not a call to res.status().
 */
export class ApiError extends Error {
  /**
   * @param {number} status    HTTP code (404, 409, ...)
   * @param {string} code      Code from the catalogue of 02-04 ('coffee_not_found')
   * @param {string} message   Human-readable message for the consumer
   * @param {object[]} details List of specific problems; ALWAYS present
   */
  constructor(status, code, message, details = []) {
    super(message);

    // Without this, error.name would be 'Error' and the logs would lose information.
    this.name = 'ApiError';
    this.status = status;
    this.code = code;
    this.details = details;

    // An explicit marker: the middleware uses it to tell an expected
    // catalogue error from an unexpected program failure.
    this.isApiError = true;

    // Trims the stack so it starts where it was thrown, not in the constructor.
    Error.captureStackTrace?.(this, ApiError);
  }
}

// src/errors/api-error.js  (continued)

export const errors = {
  // --- 400 ---
  invalidData(details = []) {
    return new ApiError(
      400,
      'invalid_data',
      'The request body contains validation errors.',
      details
    );
  },

  invalidParameter(details = []) {
    return new ApiError(
      400,
      'invalid_parameter',
      'The request parameters contain errors.',
      details
    );
  },

  // --- 401 ---
  notAuthenticated(message = 'This operation requires authentication.') {
    return new ApiError(401, 'not_authenticated', message);
  },

  tokenExpired() {
    return new ApiError(401, 'token_expired', 'The token has expired. Sign in again.');
  },

  // --- 403 ---
  permissionDenied(allowedRoles = []) {
    const detail =
      allowedRoles.length > 0
        ? ` One of these roles is required: ${allowedRoles.join(', ')}.`
        : '';
    return new ApiError(403, 'insufficient_permissions', `You do not have permission.${detail}`);
  },

  // --- 404 ---
  notFound(type, id) {
    // Entity → catalogue code map. A new type is added here.
    const codes = {
      coffee: 'coffee_not_found',
      customer: 'customer_not_found',
      order: 'order_not_found',
      review: 'review_not_found',
      cart: 'cart_not_found',
    };
    return new ApiError(
      404,
      codes[type] ?? 'route_not_found',
      `There is no ${type} with the identifier '${id}'.`
    );
  },

  routeNotFound(method, url) {
    return new ApiError(404, 'route_not_found', `The resource ${method} ${url} does not exist.`);
  },

  // --- 405 / 409 / 413 / 415 ---
  methodNotAllowed(method, path) {
    return new ApiError(405, 'method_not_allowed', `${method} is not allowed on ${path}.`);
  },

  conflict(code, message, details = []) {
    return new ApiError(409, code, message, details);
  },

  bodyTooLarge() {
    return new ApiError(413, 'body_too_large', 'The body exceeds the maximum size (100 kB).');
  },

  unsupportedFormat(type) {
    return new ApiError(
      415,
      'unsupported_format',
      `The content type '${type}' is not accepted on this operation.`
    );
  },

  // --- 500 ---
  internalError() {
    return new ApiError(500, 'internal_error', 'An unexpected error has occurred.');
  },
};

// BEFORE: ad hoc conventions the controller had to know about
get(id) {
  return coffeeRepository.findById(id);   // undefined if it does not exist
},

// src/services/coffees.js  (modified)
import { errors } from '../errors/api-error.js';

export const coffeeService = {
  /** Returns a coffee. Throws if it does not exist. */
  get(id) {
    const coffee = coffeeRepository.findById(id);
    if (!coffee) throw errors.notFound('coffee', id);
    return coffee;
  },

  replace(id, data) {
    this.get(id);   // throws 404 if it does not exist: no duplicated message
    return coffeeRepository.update(id, { /* ...fields... */ });
  },

  remove(id) {
    if (!coffeeRepository.remove(id)) throw errors.notFound('coffee', id);
  },
};

// src/services/orders.js  (modified)
import { errors } from '../errors/api-error.js';
import { createOrderAtomically } from '../repositories/orders-sqlite.js';

export const orderService = {
  getFor(id, user) {
    const order = orderRepository.findById(id);
    const isStaff = ['employee', 'administrator'].includes(user.role);

    // A nonexistent order and somebody else's order give EXACTLY the same
    // error, so as not to leak existence (03-06, section 14).
    if (!order || (order.customerId !== user.id && !isStaff)) {
      throw errors.notFound('order', id);
    }
    return order;
  },

  create({ customerId, items }) {
    try {
      const id = createOrderAtomically({ customerId, items });
      return orderRepository.findById(id);
    } catch (error) {
      // The repository throws errors carrying 'domainCode' (03-05); here they
      // become ApiError. The translation lives in the service because it is
      // the service that decides that insufficient stock is a 409.
      if (error.domainCode === 'insufficient_stock') {
        throw errors.conflict('insufficient_stock', error.message);
      }
      if (error.domainCode === 'coffee_not_found') {
        throw errors.notFound('coffee', 'in one of the order items');
      }
      throw error;   // not ours: let the middleware treat it as a 500
    }
  },

  pay(id, user) {
    const order = this.getFor(id, user);
    if (order.status === 'paid') {
      throw errors.conflict('order_already_paid', `Order '${id}' has already been paid.`);
    }
    // ...mark as paid...
  },
};

// src/controllers/coffees.js  (modified)
get(req, res) {
  const coffee = coffeeService.get(req.params.id);   // if it fails, it throws
  res.status(200).json(project(coffeeToRepresentation(coffee), req.query.fields));
},

// src/middleware/async-handler.js

/**
 * Wraps a handler so that any promise rejection ends up in next(error) and
 * therefore in the error middleware.
 *
 * Promise.resolve() works the same whether fn is synchronous (it returns an
 * already-resolved promise) or asynchronous, so you can wrap EVERYTHING
 * without thinking about it.
 */
export function asyncHandler(fn) {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

// src/routes/coffees.js  (modified)
import { asyncHandler } from '../middleware/async-handler.js';

coffeeRoutes.get('/', validate(coffeeQuerySchema, 'query'), asyncHandler(coffeeController.list));
coffeeRoutes.get('/:id', validate(coffeeIdParamsSchema, 'params'), asyncHandler(coffeeController.get));
coffeeRoutes.post(
  '/',
  authenticate,
  requireRole('employee', 'administrator'),
  validate(createCoffeeSchema),
  asyncHandler(coffeeController.create)
);
// ...and so on for all of them

// src/middleware/errors.js
import { ZodError } from 'zod';
import { ApiError, errors } from '../errors/api-error.js';
import { environment } from '../config/environment.js';

/**
 * Error middleware.
 *
 * THE FOUR-ARGUMENT SIGNATURE IS MANDATORY. Express tells an error
 * middleware from a normal one by counting the function's parameters:
 * three means normal, four means error. That is why 'next' must be
 * declared even when it is unused, and why ESLint needed the
 * argsIgnorePattern: '^_' rule we configured in 03-01.
 */
// eslint-disable-next-line no-unused-vars
export function errorHandler(err, req, res, next) {
  const apiError = translate(err);

  // --- Logging for the team ---
  if (apiError.status >= 500) {
    // 5xx are OUR failures: they are logged in full, with a stack trace.
    console.error(
      JSON.stringify({
        level: 'error',
        traceId: req.traceId,
        method: req.method,
        path: req.originalUrl,
        user: req.user?.id ?? null,
        message: err.message,
        stack: err.stack,
      })
    );
  } else {
    // 4xx are the client's failures: one informative line is enough.
    console.warn(
      JSON.stringify({
        level: 'warn',
        traceId: req.traceId,
        method: req.method,
        path: req.originalUrl,
        code: apiError.code,
      })
    );
  }

  // --- Headers the contract demands in each case ---
  if (apiError.status === 401) {
    res.set('WWW-Authenticate', 'Bearer realm="api.aromastore.example"');
  }
  if (apiError.status === 405 && err.allowedMethods) {
    res.set('Allow', err.allowedMethods.join(', '));
  }
  if (apiError.code === 'unsupported_format' && req.method === 'PATCH') {
    res.set('Accept-Patch', 'application/merge-patch+json');
  }

  // --- The contract's body (02-04) ---
  const body = {
    error: {
      code: apiError.code,
      message: apiError.message,
      details: apiError.details ?? [],
    },
  };

  // traceId ONLY on 5xx, as we decided in 02-04.
  if (apiError.status >= 500) {
    body.error.traceId = req.traceId;

    // In development it helps to see the cause; in production, NEVER.
    if (environment.nodeEnv !== 'production') {
      body.error.debug = err.message;
    }
  }

  res.status(apiError.status).json(body);
}

// src/middleware/errors.js  (continued)

/** Turns any exception into an ApiError from the catalogue. */
function translate(err) {
  // 1. It is already ours: used as it is.
  if (err?.isApiError) return err;

  // 2. A Zod validation error that escaped the validation middleware.
  if (err instanceof ZodError) {
    return errors.invalidData(
      err.issues.map((i) => ({
        field: i.path.join('.') || '(body)',
        code: 'invalid_value',
        message: i.message,
      }))
    );
  }

  // 3. Malformed JSON, detected by express.json().
  if (err instanceof SyntaxError && 'body' in err) {
    return new ApiError(400, 'invalid_data', 'The body is not valid JSON.', [
      { field: '(body)', code: 'malformed_json', message: err.message },
    ]);
  }

  // 4. Body too large (express.json's limit).
  if (err?.type === 'entity.too.large') return errors.bodyTooLarge();

  // 5. SQLite errors.
  const fromSqlite = translateSqlite(err);
  if (fromSqlite) return fromSqlite;

  // 6. Anything else is a bug of ours: a 500 leaking nothing.
  return errors.internalError();
}

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error has occurred.",
    "details": [],
    "traceId": "trc_8f4a1c92"
  }
}

// src/middleware/trace.js
import { randomBytes } from 'node:crypto';

/**
 * Assigns a unique identifier to every request.
 * If it comes from a proxy or gateway that already generated one, it is
 * respected: that way the trace is continuous across the whole system (04-07).
 */
export function assignTraceId(req, res, next) {
  const inherited = req.get('Aroma-Trace-Id');
  req.traceId = inherited ?? `trc_${randomBytes(4).toString('hex')}`;

  // It is always returned, not only on errors: it lets the client refer to
  // any request when opening a support ticket.
  res.set('Aroma-Trace-Id', req.traceId);
  next();
}

// src/middleware/validation.js  (modified)
import { errors } from '../errors/api-error.js';

export function validate(schema, source = 'body') {
  return (req, res, next) => {
    const result = schema.safeParse(req[source]);

    if (!result.success) {
      const details = toDetails(result.error);
      // The error middleware takes care of the format and the logging.
      return next(
        source === 'body' ? errors.invalidData(details) : errors.invalidParameter(details)
      );
    }

    req[source] = result.data;
    next();
  };
}

// src/middleware/errors.js  (continued)

/** SQLite errors → catalogue errors. Returns null if it is not one. */
function translateSqlite(err) {
  const code = err?.code;
  if (typeof code !== 'string' || !code.startsWith('SQLITE_')) return null;

  switch (code) {
    case 'SQLITE_CONSTRAINT_UNIQUE':
    case 'SQLITE_CONSTRAINT_PRIMARYKEY':
      // Somebody tried to duplicate a unique value (an email, for instance).
      return new ApiError(409, 'duplicate_resource', 'A resource with that unique value already exists.');

    case 'SQLITE_CONSTRAINT_FOREIGNKEY':
      // Something nonexistent is referenced: an order for a nonexistent customer.
      return new ApiError(
        409,
        'invalid_reference',
        'The operation references a resource that does not exist.'
      );

    case 'SQLITE_CONSTRAINT_CHECK':
      // A schema CHECK (invalid roast, negative stock). If it gets here, the
      // validation of 03-04 has a gap: it is logged as a 5xx so the team sees
      // it, even though the blame seems to lie with the client.
      return new ApiError(400, 'invalid_data', 'The data breaks a constraint of the model.');

    case 'SQLITE_BUSY':
      return new ApiError(503, 'service_unavailable', 'The database is busy. Please retry.');

    default:
      return null;   // unknown: let it be a 500 with its full log
  }
}

# Malformed JSON: a quote is missing
curl -s -X POST http://localhost:3000/v1/coffees \
  -H "Content-Type: application/json" \
  -d '{"name": "Kenya, "origin": "Kenya"}' | jq

{
  "error": {
    "code": "invalid_data",
    "message": "The body is not valid JSON.",
    "details": [
      {
        "field": "(body)",
        "code": "malformed_json",
        "message": "Unexpected token o in JSON at position 20"
      }
    ]
  }
}

# A 2 MB body against a 100 kB limit
curl -s -X POST http://localhost:3000/v1/coffees \
  -H "Content-Type: application/json" \
  --data-binary @huge.json | jq .error.code

"body_too_large"

// src/middleware/not-found.js
import { errors } from '../errors/api-error.js';

/** No route matched: 404 route_not_found. */
export function notFoundHandler(req, res, next) {
  next(errors.routeNotFound(req.method, req.originalUrl));
}

// src/middleware/not-found.js  (continued)
import { ApiError } from '../errors/api-error.js';

/**
 * Returns a handler that responds 405 with Allow.
 * It is registered with router.all() at the end of each group of routes, so
 * it is only reached if the URI matched but no method did.
 */
export function methodNotAllowed(...allowedMethods) {
  return (req, res, next) => {
    const error = new ApiError(
      405,
      'method_not_allowed',
      `${req.method} is not allowed on ${req.baseUrl}${req.path}.`
    );
    // The error middleware will read this property to set Allow.
    error.allowedMethods = [...allowedMethods, 'OPTIONS'];
    next(error);
  };
}

// src/routes/coffees.js  (at the end of the file, after all the routes)
import { methodNotAllowed } from '../middleware/not-found.js';

coffeeRoutes.all('/', methodNotAllowed('GET', 'POST'));
coffeeRoutes.all('/:id', methodNotAllowed('GET', 'PUT', 'PATCH', 'DELETE'));

curl -i -s -X DELETE http://localhost:3000/v1/coffees | head -5

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST, OPTIONS
Content-Type: application/json; charset=utf-8

{"error":{"code":"method_not_allowed","message":"DELETE is not allowed on /v1/coffees.","details":[]}}

// src/app.js  (the module's final version)
import express from 'express';
import { v1Routes } from './routes/index.js';
import { assignTraceId } from './middleware/trace.js';
import { notFoundHandler } from './middleware/not-found.js';
import { errorHandler } from './middleware/errors.js';

export const app = express();

app.disable('x-powered-by');

// --- 1. Request identity: FIRST of all, so everything else can use it ---
app.use(assignTraceId);

// --- 2. Request logging (04-07 will replace it with structured logs) ---
app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    console.log(`${req.method} ${req.originalUrl} → ${res.statusCode} (${Date.now() - start} ms)`);
  });
  next();
});

// --- 3. Body parsers ---
app.use(
  express.json({
    limit: '100kb',
    type: ['application/json', 'application/merge-patch+json'],
  })
);
app.use(express.urlencoded({ extended: false, limit: '10kb' }));

// --- 4. Health (outside /v1: not part of the contract) ---
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', version: '1.0.0', timestamp: new Date().toISOString() });
});

// --- 5. Versioned API ---
app.use('/v1', v1Routes);

// --- 6. No route matched ---
app.use(notFoundHandler);

// --- 7. Error middleware: ALWAYS LAST ---
app.use(errorHandler);

// src/server.js  (the module's final version)
import { app } from './app.js';
import { environment } from './config/environment.js';
import { closeDatabase } from './config/database.js';

const server = app.listen(environment.port, () => {
  console.log(`Aroma Store API listening on ${environment.baseUrl}/v1`);
});

let shuttingDown = false;

function shutdownGracefully(reason, exitCode = 0) {
  if (shuttingDown) return;   // two signals in a row must not duplicate the shutdown
  shuttingDown = true;

  console.log(`Shutting down because of: ${reason}`);

  server.close(() => {
    closeDatabase();
    console.log('Server and database closed.');
    process.exit(exitCode);
  });

  // Safety net: if it has not finished within 10 s, the exit is forced.
  // Without this, one open connection can block the shutdown forever.
  setTimeout(() => {
    console.error('Shutdown forced after the timeout.');
    process.exit(1);
  }, 10000).unref();
}

process.on('SIGINT', () => shutdownGracefully('SIGINT'));
process.on('SIGTERM', () => shutdownGracefully('SIGTERM'));

/**
 * An uncaught exception: the process is in an UNKNOWN state.
 * It is logged and we exit. Trying to carry on is worse: there may be
 * half-finished transactions, open files and corrupt state.
 */
process.on('uncaughtException', (error) => {
  console.error(
    JSON.stringify({ level: 'fatal', type: 'uncaughtException', message: error.message, stack: error.stack })
  );
  shutdownGracefully('uncaughtException', 1);
});

/** A promise rejected with no catch. Since Node 15, it also ends the process. */
process.on('unhandledRejection', (reason) => {
  console.error(
    JSON.stringify({ level: 'fatal', type: 'unhandledRejection', message: String(reason) })
  );
  shutdownGracefully('unhandledRejection', 1);
});

{
  "type": "https://api.aromastore.example/errors/insufficient-stock",
  "title": "Insufficient stock",
  "status": 409,
  "detail": "Only 3 units of 'Ethiopia Yirgacheffe' remain and 5 were requested.",
  "instance": "/v1/orders"
}

orderRoutes.post('/', authenticate, async (req, res) => {
  try {
    const order = await orderService.create(req.body);
    res.status(201).json(orderToRepresentation(order));
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// src/middleware/idempotency.js
import { createHash } from 'node:crypto';
import { ApiError, errors } from '../errors/api-error.js';
import { database } from '../config/database.js';

// Table required (migration 003):
//   CREATE TABLE idempotency_keys (
//     key TEXT PRIMARY KEY, fingerprint TEXT NOT NULL,
//     response TEXT, created_at TEXT NOT NULL
//   );

const findKey = database.prepare('SELECT * FROM idempotency_keys WHERE key = ?');
const saveKey = database.prepare(
  'INSERT INTO idempotency_keys (key, fingerprint, created_at) VALUES (?, ?, ?)'
);

export function requireIdempotencyKey(req, res, next) {
  const key = req.get('Idempotency-Key');

  if (!key) {
    return next(
      new ApiError(
        400,
        'idempotency_key_required',
        'This operation requires the Idempotency-Key header.'
      )
    );
  }

  // A fingerprint of the body: it identifies "the same request".
  const fingerprint = createHash('sha256').update(JSON.stringify(req.body ?? {})).digest('hex');
  const record = findKey.get(key);

  if (record) {
    if (record.fingerprint !== fingerprint) {
      // Same key, different body: the client is contradicting itself.
      return next(
        new ApiError(
          422,
          'idempotency_key_reused',
          'That Idempotency-Key was already used with a different body.'
        )
      );
    }
    if (record.response) {
      // A legitimate retry: the original response is returned.
      return res.status(200).json(JSON.parse(record.response));
    }
    return next(
      new ApiError(409, 'operation_in_progress', 'An identical request is being processed.')
    );
  }

  saveKey.run(key, fingerprint, new Date().toISOString());
  req.idempotencyKey = key;
  next();
}

orderRoutes.post(
  '/',
  authenticate,
  requireRole('customer', 'employee', 'administrator'),
  requireIdempotencyKey,
  validate(createOrderSchema),
  asyncHandler(orderController.create)
);

// src/controllers/orders.js
create: async (req, res) => {
  const order = await orderService.create({
    customerId: req.user.id,        // from the token, NEVER from the body (03-06)
    items: req.body.items,
  });
  res.set('Location', `/v1/orders/${order.id}`);
  res.status(201).json(orderToRepresentation(order));
},

// src/routes/orders.js
orderRoutes.post(
  '/',
  authenticate,
  requireIdempotencyKey,
  validate(createOrderSchema),
  asyncHandler(orderController.create)
);

HTTP/1.1 415 Unsupported Media Type
Accept-Patch: application/merge-patch+json
Aroma-Trace-Id: trc_1a2b3c4d

{"error":{"code":"unsupported_format","message":"The content type 'application/json-patch+json' is not accepted on this operation.","details":[]}}

HTTP/1.1 404 Not Found
Aroma-Trace-Id: trc_5e6f7a8b

{"error":{"code":"order_not_found","message":"There is no order with the identifier 'ord_5001'.","details":[]}}

HTTP/1.1 403 Forbidden
Aroma-Trace-Id: trc_9c0d1e2f

{"error":{"code":"insufficient_permissions","message":"You do not have permission. One of these roles is required: employee, administrator.","details":[]}}

HTTP/1.1 500 Internal Server Error
Aroma-Trace-Id: trc_3a4b5c6d

{"error":{"code":"internal_error","message":"An unexpected error has occurred.","details":[],"traceId":"trc_3a4b5c6d"}}

{"level":"error","traceId":"trc_3a4b5c6d","method":"GET","path":"/v1/coffees/cof_007","user":null,
 "message":"Cannot read properties of null (reading 'map')",
 "stack":"TypeError: ... at coffeeToRepresentation (/app/src/services/mappers.js:31:29) ..."}