suaveplan/openspec/changes/enterprise-slack-client/tasks.md

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