suaveplan/openspec/changes/archive/2026-05-04-enterprise-network-superseded/tasks.md

Tasks: enterprise-network

Change ID: enterprise-network Package: @suaveplan/network Target path: universal/network/network Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/retry, @suaveplan/serialize

---

1. Scaffold

• Create directory universal/network/network/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, deps: @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/retry workspace:^, @suaveplan/serialize workspace:^, zod catalog:forms, @opentelemetry/api catalog:observability.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• Write src/types/common.ts — HttpMethod, HttpRequest, HttpResponse, HttpMiddleware, HttpClientOptions, WsReadyState, WsMessage, WebSocketClientOptions.
• Write src/types/common.md.
• Write src/error-codes.ts — NetworkErrorCode, NETWORK_ERROR_METADATA, registerNetworkErrorCodes().
• Write Zod schemas: HttpRequestSchema, HttpClientOptionsSchema, WebSocketClientOptionsSchema.

---

3. URL utilities

• Implement buildUrl, parseQueryString, serializeQueryString, isAbsoluteUrl, joinPaths in src/utils/url.ts.
• Write url.test.ts (≤500 lines): each function, edge cases (empty params, absolute URLs, path joining).
• Write url.md.

---

4. Middleware

Logging middleware

• Implement loggingMiddleware(logger): HttpMiddleware — logs method, URL, status, duration.
• Write logging.test.ts and logging.md.

Retry middleware

• Implement retryMiddleware(options?): HttpMiddleware — wraps @suaveplan/retry; retries on 429/5xx and network errors; uses exponential backoff.
• Write retry.test.ts and retry.md.

Auth middleware

• Implement authMiddleware(token): HttpMiddleware — adds Authorization: Bearer <token> header; token may be a function for dynamic tokens.
• Write auth.test.ts and auth.md.

Rate-limit middleware

• Implement rateLimitMiddleware(options): HttpMiddleware — sliding-window request rate limiting using injectable Clock; queues excess requests.
• Write rate-limit.test.ts and rate-limit.md.

---

5. HttpClient

• Implement HttpClient — middleware chain dispatch, injectable fetch, body serialisation via @suaveplan/serialize, timeout via AbortSignal.timeout-compatible wrapper, response body deserialisation, use().
• Wire OTel: span http.request, counter http_request_total, histogram http_request_duration_ms.
• Write http-client.test.ts (≤500 lines): GET/POST/PUT/DELETE with stub fetch, timeout, abort, 4xx throws NETWORK_BAD_STATUS, middleware chain order.
• Write http-client.md.

---

6. WebSocketClient

• Implement WebSocketClient — injectable WebSocket, auto-reconnect with @suaveplan/retry backoff, ping/pong keepalive using injectable Clock, on() event listener registry, send(), connect(), disconnect().
• Wire OTel: counter ws.reconnect_total.
• Write websocket-client.test.ts (≤500 lines): connect, message, reconnect, max reconnects exceeded throws, abort on disconnect.
• Write websocket-client.md.

---

7. Benchmarks

• Write src/__benchmarks__/network.bench.ts — buildUrl with 10 params, middleware chain dispatch 5 middlewares no-op stub fetch.

---

8. Tests

• Write tests/integration.test.ts — HttpClient + middleware stack end-to-end with stub fetch.
• Write tests/property.test.ts (fast-check) — buildUrl round-trip, parseQueryString(serializeQueryString(p)) deep equals p.

---

9. Docs + verify + publish

• All co-located .md files (≥200 words each).
• Write README.md at package root.
• bunx turbo lint typecheck test --filter=@suaveplan/network — green.
• bunx turbo test:coverage --filter=@suaveplan/network — 100%.
• bun scripts/publish.ts --package @suaveplan/network.
• Archive to openspec/archive/2026-04-24-enterprise-network/.