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