Merge branch 'main' into feat/compute-price-change-helper

Author: Godfrey-Delight

.env.example

@@ -53,3 +53,9 @@ OWNERSHIP_SNAPSHOT_CLEANUP_DRY_RUN=true
 OWNERSHIP_SNAPSHOT_RETENTION_DAYS=30
 OWNERSHIP_SNAPSHOT_CLEANUP_ENABLED=false
 OWNERSHIP_SNAPSHOT_CLEANUP_INTERVAL_MINUTES=60
+
+# Request body size limits (see docs/body-size-limits.md)
+BODY_SIZE_LIMIT_DEFAULT=10mb
+# BODY_SIZE_LIMIT_AUTH=100kb
+# BODY_SIZE_LIMIT_ADMIN=10mb
+# BODY_SIZE_LIMIT_CREATORS=10mb

docs/api-endpoints.md

@@ -0,0 +1,276 @@
+# API Endpoint Reference
+
+Base URL: `http://localhost:3000/api/v1`
+
+## Health Endpoints
+
+### GET /health
+
+Simple health check for load balancers.
+
+- **Auth:** None
+- **Response:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "OK",
+  "timestamp": "2025-01-15T10:30:00.000Z"
+}
+```
+
+### GET /health/ready
+
+Readiness check with dependency probes.
+
+- **Auth:** None
+- **Response:** `200 OK` or `503 Service Unavailable`
+
+```json
+{
+  "ready": true,
+  "timestamp": "2025-01-15T10:30:00.000Z",
+  "checks": [
+    { "name": "database", "status": "ok", "latencyMs": 12 },
+    { "name": "cache", "status": "ok" }
+  ]
+}
+```
+
+### GET /health/detailed
+
+Full diagnostics including memory and system info.
+
+- **Auth:** None
+- **Response:** `200 OK`
+
+```json
+{
+  "success": true,
+  "message": "Access Layer server is running",
+  "timestamp": "2025-01-15T10:30:00.000Z",
+  "version": "1.0.0",
+  "environment": "development",
+  "uptime": 12345.67,
+  "memory": { "used": 45.23, "total": 128.5 },
+  "system": { "platform": "darwin", "nodeVersion": "v20.10.0" },
+  "database": { "status": "connected", "responseTime": 12 },
+  "services": [
+    { "name": "API Server", "status": "healthy" },
+    { "name": "Database", "status": "healthy" }
+  ]
+}
+```
+
+---
+
+## Auth Endpoints
+
+### POST /auth/login
+
+Authenticate a user.
+
+- **Auth:** None
+- **Body:**
+
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword"
+}
+```
+
+- **Response:** `200 OK`
+
+### POST /auth/register
+
+Register a new user.
+
+- **Auth:** None
+- **Body:**
+
+```json
+{
+  "email": "user@example.com",
+  "password": "securepassword",
+  "name": "User Name"
+}
+```
+
+- **Response:** `201 Created`
+
+---
+
+## Config Endpoints
+
+### GET /config
+
+Get protocol bootstrap configuration.
+
+- **Auth:** None
+- **Response:** `200 OK`
+
+```json
+{
+  "network": "testnet",
+  "contractAddress": "..."
+}
+```
+
+---
+
+## Creators Endpoints
+
+### GET /creators
+
+List all creators with pagination.
+
+- **Auth:** None
+- **Query Params:**
+  - `page` (number, default: 1)
+  - `limit` (number, default: 10)
+- **Response:** `200 OK`
+
+```json
+{
+  "creators": [...],
+  "pagination": {
+    "page": 1,
+    "limit": 10,
+    "total": 100
+  }
+}
+```
+
+### GET /creators/:id/stats
+
+Get public stats for a specific creator.
+
+- **Auth:** None
+- **Response:** `200 OK`
+
+```json
+{
+  "creatorId": "...",
+  "totalSales": 150,
+  "totalEarnings": 12500.50
+}
+```
+
+---
+
+## Creator Profile Endpoints
+
+### GET /creators/:creatorId/profile
+
+Get creator profile scaffold payload.
+
+- **Auth:** None
+- **Response:** `200 OK`
+
+```json
+{
+  "creatorId": "...",
+  "displayName": "Creator Name",
+  "bio": "...",
+  "avatarUrl": "..."
+}
+```
+
+### PUT /creators/:creatorId/profile
+
+Upsert creator profile.
+
+- **Auth:** Wallet ownership required
+- **Headers:**
+  - `x-wallet-address: <wallet_address>` (must match creator)
+- **Body:**
+
+```json
+{
+  "displayName": "New Name",
+  "bio": "Updated bio",
+  "avatarUrl": "https://..."
+}
+```
+
+- **Response:** `200 OK`
+
+---
+
+## Metrics Endpoints
+
+### GET /metrics/queues
+
+Queue depth metrics for indexer workers.
+
+- **Auth:** None
+- **Response:** `200 OK`
+
+```json
+{
+  "queues": {
+    "indexer": { "depth": 42, "processing": 5 },
+    "notifications": { "depth": 10, "processing": 2 }
+  }
+}
+```
+
+---
+
+## Admin Endpoints
+
+### PATCH /admin/creators/:id/metadata
+
+Update creator metadata.
+
+- **Auth:** Admin required
+- **Body:**
+
+```json
+{
+  "metadata": { "key": "value" }
+}
+```
+
+- **Response:** `200 OK`
+
+### POST /admin/indexer/replay
+
+Replay indexer events.
+
+- **Auth:** Admin required
+- **Response:** `200 OK`
+
+---
+
+## Common Headers
+
+| Header | Description |
+|--------|-------------|
+| `x-wallet-address` | Wallet address for ownership verification |
+| `Authorization` | Bearer token for authenticated requests |
+| `Content-Type` | `application/json` |
+
+## Error Responses
+
+```json
+{
+  "success": false,
+  "message": "Error description",
+  "error": "Detailed error (dev only)"
+}
+```
+
+| Status | Description |
+|--------|-------------|
+| 400 | Bad request / validation error |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not found |
+| 429 | Rate limit exceeded |
+| 500 | Internal server error |
+
+---
+
+See [Local Setup](./local-setup.md) for development environment configuration.

docs/body-size-limits.md

@@ -0,0 +1,79 @@
+# Request Body Size Limits
+
+This document describes how JSON request body size limits are configured per route group, their defaults, and how a client is notified when a request exceeds its limit.
+
+## Overview
+
+Every route group mounted in [modules/index.ts](../src/modules/index.ts) gets its own `express.json()` parser via `routeBodySizeLimit(group)`, instead of a single limit applied globally to every endpoint. This lets a group with a legitimate need for a larger (or smaller) payload be tuned independently, without changing the ceiling for the rest of the API.
+
+- **Middleware:** [body-size-limit.middleware.ts](../src/middlewares/body-size-limit.middleware.ts)
+- **Applied in:** [modules/index.ts](../src/modules/index.ts) — one `routeBodySizeLimit(group)` call per router mount
+- **Error handling:** [body-parse-error.middleware.ts](../src/middlewares/body-parse-error.middleware.ts), mounted after the router in [app.ts](../src/app.ts)
+
+## Default and Overrides
+
+| Group        | Env Var                    | Default (if unset)        |
+| :----------- | :------------------------- | :------------------------ |
+| _(fallback)_ | `BODY_SIZE_LIMIT_DEFAULT`  | `10mb`                    |
+| `auth`       | `BODY_SIZE_LIMIT_AUTH`     | `BODY_SIZE_LIMIT_DEFAULT` |
+| `admin`      | `BODY_SIZE_LIMIT_ADMIN`    | `BODY_SIZE_LIMIT_DEFAULT` |
+| `creators`   | `BODY_SIZE_LIMIT_CREATORS` | `BODY_SIZE_LIMIT_DEFAULT` |
+
+All other route groups (`health`, `config`, `metrics`, `ledger`, `activity`, `ownership`, `wallets`, `alerts`) always use `BODY_SIZE_LIMIT_DEFAULT` — they don't currently have a dedicated override, since none of their payloads differ meaningfully from the default ceiling.
+
+Limit values accept any size string understood by the [`bytes`](https://www.npmjs.com/package/bytes) package (used internally by `body-parser`), e.g. `'100kb'`, `'1mb'`, `'10mb'`.
+
+`BODY_SIZE_LIMIT_DEFAULT` itself defaults to `10mb`, matching the single global limit this replaced — existing deployments see no behavior change unless they explicitly set new overrides.
+
+## Adding an Override for a New Group
+
+1. Add the env var to `envSchema` in [config.schema.ts](../src/config.schema.ts):
+   ```typescript
+   BODY_SIZE_LIMIT_METRICS: optionalNonEmptyString,
+   ```
+2. Add the group to `BodySizeLimitGroup` and `GROUP_OVERRIDES` in [body-size-limit.middleware.ts](../src/middlewares/body-size-limit.middleware.ts):
+
+   ```typescript
+   export type BodySizeLimitGroup =
+      | 'auth'
+      | 'admin'
+      | 'creators'
+      | 'metrics'
+      | 'default';
+
+   const GROUP_OVERRIDES: Record<
+      Exclude<BodySizeLimitGroup, 'default'>,
+      string | undefined
+   > = {
+      auth: envConfig.BODY_SIZE_LIMIT_AUTH,
+      admin: envConfig.BODY_SIZE_LIMIT_ADMIN,
+      creators: envConfig.BODY_SIZE_LIMIT_CREATORS,
+      metrics: envConfig.BODY_SIZE_LIMIT_METRICS,
+   };
+   ```
+
+3. Pass the group name at the mount point in `modules/index.ts`:
+   ```typescript
+   router.use('/metrics', routeBodySizeLimit('metrics'), metricsRouter);
+   ```
+4. Document the new var's default in the table above and in `.env.example`.
+
+## Fail-Fast Behavior
+
+When a request body exceeds its group's limit, `express.json()` never calls the route handler — it raises a body-parser error (`type: 'entity.too.large'`, `status: 413`) before any controller or database code runs. `bodyParseErrorMiddleware` catches this (for mutation methods — `POST`/`PUT`/`PATCH`/`DELETE`) and returns:
+
+```json
+{
+   "success": false,
+   "code": "BAD_REQUEST",
+   "message": "Request payload too large"
+}
+```
+
+with HTTP status `413`. The same error path also logs a structured `body_parse_failure` entry (method, path, request ID, client IP — never the raw body) for observability. This behavior is identical across every route group regardless of its configured limit — only the threshold that triggers it differs.
+
+## Related Documentation
+
+- [Configuration Guide](./configuration.md) — loading environment configuration.
+- [Error Code Registry](./ERROR_CODE_REGISTRY.md) — standard API error shapes.
+- [Rate Limiting](./rate-limiting.md) — the sibling per-route-group mechanism for request rate, following the same override pattern.

docs/indexer/EVENT_PROCESSING.md

@@ -56,6 +56,24 @@ The log includes:
 
 Use `processIndexerChainEvents` to dedupe a batch and log once per unique event.
 
+## 5. Structured batch logging
+
+In addition to the per-event log above, `processIndexerChainEvents` emits
+exactly two logs per batch — never per individual ledger:
+
+| Log                       | Level | Fields                                                                              |
+| :------------------------ | :---- | :---------------------------------------------------------------------------------- |
+| `indexer_batch_started`   | info  | `from_ledger`, `to_ledger`, `batch_size` (raw batch size, before dedup)             |
+| `indexer_batch_completed` | debug | `from_ledger`, `to_ledger`, `events_processed` (unique, after dedup), `duration_ms` |
+
+`from_ledger`/`to_ledger` are the min/max `ledger` values across the events
+in the batch (`undefined` if no event in the batch carries a `ledger`).
+`duration_ms` is measured with the same monotonic clock used for per-event
+timing, from the start of the batch to the completion of the last event.
+
+These logs give operators batch throughput and size at a glance without
+requiring per-ledger database queries.
+
 ## 3. Error Handling
 
 If an event fails to process after multiple retries, it is moved to the [Dead-Letter Queue (DLQ)](./DLQ_WORKFLOW.md) for manual investigation.