121 lines
5.3 KiB
Markdown
121 lines
5.3 KiB
Markdown
# Tasks: enterprise-api-shared
|
|
|
|
**Change ID**: enterprise-api-shared
|
|
**Package**: `@suaveplan/api-shared`
|
|
**Target path**: `api/framework/api-shared`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/logger`, `@suaveplan/api`, `@suaveplan/api-schemas`
|
|
|
|
---
|
|
|
|
## 0. Pre-flight (non-negotiable)
|
|
|
|
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
|
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
|
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
|
|
|
## 1. Scaffold
|
|
|
|
- [ ] Create `api/framework/api-shared/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories.
|
|
- [ ] Write `package.json` at version `0.1.0`: `"type": "module"`, `"sideEffects": false`, exports map with `"."` barrel + per-feature subpaths.
|
|
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library-node.json`.
|
|
- [ ] Write `vitest.config.ts` using `createTestConfig()`.
|
|
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check`, `bench` scripts.
|
|
|
|
---
|
|
|
|
## 2. Types and errors
|
|
|
|
- [ ] Define shared TS interfaces in `src/types/common.ts`: `ApiSuccessResponse`, `ApiErrorResponse`, `ApiPaginatedResponse`, `PaginationMeta`, `PaginationQuery`, `SortQuery`, `FilterQuery`, `ResponseMeta`.
|
|
- [ ] Write `src/types/common.md`.
|
|
- [ ] Implement `src/errors/api-shared-errors.ts`: 4-code `ApiSharedErrorCode` union, metadata, `registerApiSharedErrorCodes()`.
|
|
- [ ] Write `api-shared-errors.test.ts` and `api-shared-errors.md`.
|
|
|
|
---
|
|
|
|
## 3. Response helpers
|
|
|
|
- [ ] Implement `successResponse<T>`, `errorResponse`, `paginatedResponse`, `noContentResponse`.
|
|
- [ ] `errorResponse` converts `SuaveplanError` to RFC 7807 `application/problem+json` body.
|
|
- [ ] Write `response-helpers.test.ts` (success envelope shape, error problem+json, paginated shape, 204 status).
|
|
- [ ] Write `response-helpers.md`.
|
|
|
|
---
|
|
|
|
## 4. Middleware: request-id
|
|
|
|
- [ ] Read `X-Request-ID` header; generate UUID v4 via `crypto.randomUUID()` if absent; set on response headers and Hono context variable `c.set('requestId', ...)`.
|
|
- [ ] Write `request-id.test.ts`: header forwarded, generated if missing.
|
|
- [ ] Write `request-id.md`.
|
|
|
|
---
|
|
|
|
## 5. Middleware: correlation-id
|
|
|
|
- [ ] Read `X-Correlation-ID`; propagate to response + context + OTel span attribute `correlation_id`.
|
|
- [ ] Write `correlation-id.test.ts` and `correlation-id.md`.
|
|
|
|
---
|
|
|
|
## 6. Middleware: tenant-context
|
|
|
|
- [ ] Extract `X-Tenant-ID` header; set `c.set('tenantId', ...)`. If missing and `required: true` option set, return 400 via `ApiSharedError(API_SHARED_MISSING_TENANT)`.
|
|
- [ ] Write `tenant-context.test.ts`: header present, absent (pass-through), absent (required throws).
|
|
- [ ] Write `tenant-context.md`.
|
|
|
|
---
|
|
|
|
## 7. Middleware: request-logging
|
|
|
|
- [ ] On request start: log method, path, requestId at `debug`.
|
|
- [ ] On response: log status, duration (ms), requestId at `info`.
|
|
- [ ] Record `http.request_duration_ms` histogram with `http.method` + `http.status_code` attributes.
|
|
- [ ] Write `request-logging.test.ts` (log entries emitted, duration recorded).
|
|
- [ ] Write `request-logging.md`.
|
|
|
|
---
|
|
|
|
## 8. Middleware: error-handler
|
|
|
|
- [ ] Catch unhandled errors in Hono; if `SuaveplanError`, call `errorResponse`; else wrap in a generic 500 problem detail.
|
|
- [ ] Never leak stack traces in production (`NODE_ENV !== 'development'`).
|
|
- [ ] Write `error-handler.test.ts`: SuaveplanError → problem+json, unknown error → 500.
|
|
- [ ] Write `error-handler.md`.
|
|
|
|
---
|
|
|
|
## 9. Schema utilities
|
|
|
|
- [ ] `parsePaginationQuery` — wraps `@suaveplan/api-schemas` `PaginationQuerySchema`; throws `ApiSharedError(API_SHARED_INVALID_PAGINATION)` on failure.
|
|
- [ ] `parseSortQuery` — validates `sortBy` against `allowedFields`; throws `ApiSharedError(API_SHARED_INVALID_SORT)`.
|
|
- [ ] `parseFilterQuery` — validates operator keys against `allowedFields`; throws `ApiSharedError(API_SHARED_INVALID_FILTER)`.
|
|
- [ ] Write tests (valid, invalid, unknown field) and `.md` for each.
|
|
|
|
---
|
|
|
|
## 10. Benchmarks (`src/__benchmarks__/middleware.bench.ts`)
|
|
|
|
- [ ] Benchmark 5-middleware chain (requestId + correlationId + tenantContext + requestLogging + errorHandler) on a Hono test app.
|
|
|
|
---
|
|
|
|
## 11. Integration tests (`tests/integration.test.ts`)
|
|
|
|
- [ ] Mount all middleware on a test Hono app; verify request-id/correlation-id headers in response, tenant missing → 400, SuaveplanError → problem+json body.
|
|
|
|
---
|
|
|
|
## 12. Docs
|
|
|
|
- [ ] All co-located `.md` files (≥200 words, both examples, full API reference).
|
|
- [ ] Root `README.md`.
|
|
- [ ] `docs:check` passes.
|
|
|
|
---
|
|
|
|
## 13. Verify and publish
|
|
|
|
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/api-shared` — green.
|
|
- [ ] `bunx turbo test:coverage --filter=@suaveplan/api-shared` — 100%.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/api-shared`.
|
|
- [ ] Archive change → `openspec/archive/2026-04-24-enterprise-api-shared/`.
|