# Add @suaveplan/slack-client

**Package**: `@suaveplan/slack-client`
**Status**: PROPOSED
**Type**: new-package

## Why

Genesis needs a typed, deterministic, OpenTelemetry-instrumented Slack client for transactional messaging (alerting, notifications, ops bots). The upstream `@suaveplan/slack-client@1.0.1` at `../suaveplan/packages/universal/slack-client/` works but does not meet genesis enterprise-quality bar — it monkey-patches `globalThis.fetch` in tests (`vi.stubGlobal`), has no Zod boundary validation, no OTel meters, no injectable `Clock`/`Rng`/`Logger`, leaks `as unknown` casts, and registers codes through the legacy `ErrorCodes.registerMany` runtime registry instead of `defineCodes`. This change ships a fresh build at enterprise quality with full functional parity.

## What changes

- ADDED: `@suaveplan/slack-client@0.1.0` under `packages/messaging/slack-client/`
- ADDED: `SlackApiClient` — Slack Web API: `sendMessage`, `updateMessage`, `deleteMessage`, `listChannels`, `getChannelInfo`, `listUsers`, `getStatus`
- ADDED: `SlackWebhook` — Slack incoming-webhook client: `send`, `sendText`
- ADDED: `SLACK_CODES` registry (`defineCodes("SLACK", [...])`) with 8 reasons: `API_ERROR`, `AUTH_ERROR`, `RATE_LIMITED`, `CHANNEL_NOT_FOUND`, `WORKSPACE_NOT_FOUND`, `CONFIG_MISSING`, `WEBHOOK_FAILED`, `TIMEOUT`
- ADDED: 8 typed error subclasses extending `SuaveplanError<SlackErrorCode>` (one per reason)
- ADDED: Zod schemas at every public boundary: `SlackApiClientOptionsSchema`, `SlackWebhookOptionsSchema`, `SlackMessageSchema`, `SlackBlockSchema`, `SlackBlockElementSchema`, `SlackTextObjectSchema`
- ADDED: OTel meter instruments — `slack.requests`, `slack.errors`, `slack.latency_ms`, `slack.webhook_sends` — emitted from every production hot path
- ADDED: Injectable transport bag — `Clock`, `Rng`, `FetchLike`, `LoggerLike` — all from `@suaveplan/types`
- ADDED: Deterministic `FakeFetch` test double under `src/fakes/` for parity tests (no `vi.mock` anywhere)
- ADDED: Retry-After parser supporting delay-seconds, HTTP-date, and `x-ratelimit-reset` epoch/ISO
- ADDED: Slack-error string classifier (`invalid_auth` / `channel_not_found` / `team_not_found` families)

## Out of scope

None. The package ships at full functional parity with the upstream package plus the enterprise upgrades demanded by `enterprise/slack-client.md` §3.

## Source mapping

This change derives from `../suaveplan/enterprise/slack-client.md` and the working implementation at `../suaveplan/packages/universal/slack-client/src/`.

| Requirement | Source lines | Notes |
|---|---|---|
| Generic Slack API client + webhook surface | enterprise/slack-client.md L10-L13 | verbatim |
| Zero browser/Node/React deps (universal tier) | enterprise/slack-client.md L37 | verbatim |
| Zod schemas at every boundary | enterprise/slack-client.md L38 | verbatim |
| Deterministic — no module-scope `Math.random` / `Date.now`, injectable clock/RNG | enterprise/slack-client.md L40 | verbatim |
| OpenTelemetry instrumentation via `@opentelemetry/api` | enterprise/slack-client.md L41 | verbatim |
| Structured errors extending `@suaveplan/error` with stable codes | enterprise/slack-client.md L42, L61 | verbatim |
| AbortSignal cancellation everywhere async | enterprise/slack-client.md L43 | verbatim |
| Idempotency + retry primitives wired | enterprise/slack-client.md L44 | applied to Retry-After / rate-limit; cooperative retry left to caller's `@suaveplan/retry` (no double-wrap) |
| i18n-ready (no hard-coded user-visible strings) | enterprise/slack-client.md L46 | every thrown error carries a stable code + structured context; messages are templated |
| Test coverage 100% statement/branch/function/line (istanbul) | enterprise/slack-client.md L50 + genesis CLAUDE.md "Quality" | genesis policy is 100%, stricter than the 95% in the source |
| File-size budget 250/300 soft/hard, 500 test | enterprise/slack-client.md L52 + CLAUDE.md | enforced by manual split |
| No mocks — injectable fakes only | enterprise/slack-client.md L53 + CLAUDE.md rule 2 | verbatim |
| `sideEffects: false` | enterprise/slack-client.md L55 | verbatim |
| Biome clean, zero suppressions | enterprise/slack-client.md L58 + CLAUDE.md rule 9 | verbatim |
| TypeScript strict, no `any` / `ts-ignore` | enterprise/slack-client.md L59 | verbatim |
| Error hierarchy with typed discriminants | enterprise/slack-client.md L61 | verbatim |
| `chat.postMessage`, `chat.update`, `chat.delete`, `conversations.list`, `conversations.info`, `users.list` | upstream packages/universal/slack-client/src/core/slack-api-client/slack-api-client.ts L52-L138 | parity |
| Webhook POST with text + blocks | upstream packages/universal/slack-client/src/core/slack-webhook/slack-webhook.ts L41-L105 | parity |
| HTTP 429 Retry-After / x-ratelimit-reset parsing | upstream slack-api-client.ts L259-L284 | parity |
| Slack-error → code classifier (`invalid_auth`, `channel_not_found`, `team_not_found`) | upstream slack-api-client.ts L286-L313 | parity |

### Requirements with no source line

| Requirement | Justification |
|---|---|
| 100% coverage threshold (vs. 95% in source) | Genesis-wide policy — `CLAUDE.md` Quality section |
| Test runner imports MUST go through `@suaveplan/testing/runner` | Genesis rule 11 — not applicable to upstream which predates the rule |
| `defineCodes("SLACK", […])` registry style | Genesis-wide error-codes convention — upstream used the legacy `ErrorCodes.registerMany` API |
| `FakeFetch` test double + setup polyfills wiring real `MeterProvider` | Genesis pre-archive checklist row 5 (OTel asserted with real `MeterProvider`, not `vi.mock`) |

## Verification approach

- `src/client/slack-api-client.test.ts` — pins every `SlackApiClient` method scenario with `FakeFetch`
- `src/webhook/slack-webhook.test.ts` — pins every `SlackWebhook` scenario with `FakeFetch`
- `src/errors/errors.test.ts` — pins error-code identity and message keys for all 8 codes
- `src/schemas/schemas.test.ts` — Zod boundary parse + safeParse assertions for every public schema
- `src/client/retry-after.test.ts` — pins every Retry-After header form (delay-seconds, HTTP-date, x-ratelimit-reset epoch + ISO, missing)
- `src/client/classify.test.ts` — pins HTTP-status and slack-error-string classifiers
- `src/otel/metrics.test.ts` — asserts the four OTel instruments emit on every production path, via real in-memory `MeterProvider`
- `src/fakes/fake-fetch.test.ts` — pins the deterministic test double itself
- `src/index.test.ts` — pins the public-surface barrel

## Migration impact

None — additive. No existing consumer of `@suaveplan/slack-client` exists in genesis.