suaveplan/openspec/changes/enterprise-api-shared/tasks.md

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/.