# Tasks: enterprise-slack-client

**Change ID**: enterprise-slack-client
**Package**: `@suaveplan/slack-client`
**Target path**: `universal/social/slack-client`
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`, `@suaveplan/crypto`

---

## 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 `universal/social/slack-client/` 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`, correct `exports` map, `dependencies`, and `devDependencies`.
- [ ] 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

- [ ] `src/types/common.ts` — `SlackClientOptions`, `PostMessageOptions`, `UpdateMessageOptions`, `ListConversationsOptions`, `FileUploadOptions`, `WebhookPayload`, `SlackMessageResponse`, `SlackChannel`, `SlackUser`, `SlackFile`, `SlackEvent`, `SlashCommand`, `InteractivePayload`, `SlackBlocks`, `ActionElement`, `ContextElement`.
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
- [ ] `src/error-codes.ts` — `SlackErrorCode` (7 codes), metadata, register, eager call.
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.

---

## 3. Core modules

- [ ] **`src/core/api-caller/`** — `ApiCaller`: wraps `fetch` calls to `https://slack.com/api/`; sets `Authorization: Bearer` header; parses JSON response; throws `SLACK_API_ERROR` on `ok:false`; throws `SLACK_RATE_LIMITED` on 429 and includes `retry_after`; wraps calls with `@suaveplan/retry` circuit breaker. Tests: success, api error (ok:false), rate-limit (429), circuit breaker opens after 5 failures.
- [ ] **`src/core/slack-client/`** — `SlackClient`: implements all public methods via `ApiCaller`. `listConversations` uses cursor pagination (returns `AsyncGenerator`). Tests: `postMessage` happy path, `updateMessage`, `deleteMessage`, `getUserByEmail`, `uploadFile`, `postToWebhook`.
- [ ] **`src/blocks/message-builder/`** — `createMessage(text)`: fluent builder; `build()` returns `SlackBlocks`. Tests: section, divider, image, actions, context; chaining; empty message.
- [ ] **`src/events/signature-verifier/`** — `verifySlackSignature(body, timestamp, signature, signingSecret, options)`: HMAC-SHA256 via `@suaveplan/crypto`; constant-time comparison; reject if `|now - ts| > maxAgeSeconds` (default 300). Tests: valid, tampered body, expired, missing timestamp.
- [ ] **`src/events/event-parser/`** — `parseSlackEvent`, `parseSlashCommand`, `parseInteractivePayload`: Zod validation. Tests: each payload type, invalid payload throws.

---

## 4. OTel instrumentation

- [ ] Span `slack.api_call` with attribute `slack.method` on every API call; counter `slack.api_total`; histogram `slack.api_duration_ms`.

---

## 5. Property-based tests (`tests/property.test.ts`)

- [ ] Block Kit builder: for arbitrary sequences of `section`/`divider`/`image` calls, `build()` always returns a valid `SlackBlocks` object with correct `type` fields.

---

## 6. Benchmarks (`src/__benchmarks__/slack-client.bench.ts`)

- [ ] `createMessage` builder chain (10 sections) 100 000 times.

---

## 7. Docs + verify

- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/slack-client` — green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/slack-client` — 100%.
- [ ] `bun scripts/publish.ts --package @suaveplan/slack-client`.
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-slack-client/`.