# @suaveplan/slack-client - Typed deterministic Slack client — Slack Web API + incoming-webhook surface, Zod-validated boundaries, OpenTelemetry-instrumented hot paths, injectable Clock/Rng/Logger/FetchLike, stable defineCodes('SLACK', [...]) error registry. Universal: runs unchanged in Bun, Node, and the browser.

Typed, deterministic Slack client — Web API + incoming-webhook surface — with Zod-validated boundaries, OpenTelemetry-instrumented hot paths, injectable `Clock` / `Rng` / `LoggerLike` / `FetchLike`, and a stable `defineCodes("SLACK", […])` error registry.

Universal: runs unchanged in Bun, Node, and the browser.

<!-- begin:auto-docs -->
## Documentation tree

- [classify](./src/client/classify.md) — `classify.ts` exports two pure mapping functions that fold transport-level failure signals into the stable `SLACK_CODES…
- [retry-after](./src/client/retry-after.md) — `retry-after.ts` exports a single pure function `parseRetryAfterMs(response, clock?)` that converts an HTTP `Retry-Afte…
- [slack-api-client](./src/client/slack-api-client.md) — `SlackApiClient` is the typed transport for the Slack Web API. It exposes the six methods downstream packages rely on —…
- [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` is the single source of truth for every error the `@suaveplan/slack-client` package can throw. It regi…
  - [error-codes](./src/error-codes/error-codes.md) — `error-codes.ts` is the single source of truth for every error the `@suaveplan/slack-client` package can throw. It regi…
- [fakes](./src/fakes/fake-fetch.md) — `fake-fetch.ts` exports `FakeFetch`, the deterministic test double the package's own unit tests use to exercise every t…
  - [fake-fetch](./src/fakes/fake-fetch.md) — `fake-fetch.ts` exports `FakeFetch`, the deterministic test double the package's own unit tests use to exercise every t…
- [otel](./src/otel/metrics.md) — `metrics.ts` registers four OpenTelemetry instruments under the meter name `@suaveplan/slack-client` and exports the he…
  - [metrics](./src/otel/metrics.md) — `metrics.ts` registers four OpenTelemetry instruments under the meter name `@suaveplan/slack-client` and exports the he…
- [schemas](./src/schemas/schemas.md) — `schemas.ts` exports the Zod schemas that validate every public option bag and every Slack Web API request payload that…
  - [schemas](./src/schemas/schemas.md) — `schemas.ts` exports the Zod schemas that validate every public option bag and every Slack Web API request payload that…
- [webhook](./src/webhook/slack-webhook.md) — `SlackWebhook` is the simpler half of the package — a typed wrapper around Slack's incoming-webhook URLs. Where `SlackA…
  - [slack-webhook](./src/webhook/slack-webhook.md) — `SlackWebhook` is the simpler half of the package — a typed wrapper around Slack's incoming-webhook URLs. Where `SlackA…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/slack-client
```

## Two clients

- `SlackApiClient` — Slack Web API. Token-authenticated. Supports `sendMessage`, `updateMessage`, `deleteMessage`, `listChannels`, `getChannelInfo`, `listUsers`, `getStatus`.
- `SlackWebhook` — Slack incoming webhooks. URL-authenticated. Supports `send` and `sendText`.

## Quickstart

```ts
import { SlackApiClient, SlackWebhook } from "@suaveplan/slack-client";

const api = new SlackApiClient({ token: process.env["SLACK_TOKEN"]! });
await api.sendMessage({ channel: "C0123", text: "Deploy succeeded." });

const hook = new SlackWebhook({
    webhookUrl: "https://hooks.slack.com/services/T/B/X",
});
await hook.sendText("Build broken on main.");
```

## Modules

- [`error-codes`](./src/error-codes.md) — `SLACK_CODES` registry + 8 typed error subclasses.
- [`types/slack-client`](./src/types/slack-client.types.ts) — public shapes.
- [`schemas/schemas`](./src/schemas/schemas.md) — Zod boundary schemas.
- [`client/slack-api-client`](./src/client/slack-api-client.md) — Slack Web API client.
- [`client/retry-after`](./src/client/retry-after.md) — `Retry-After` / `x-ratelimit-reset` parser.
- [`client/classify`](./src/client/classify.md) — HTTP-status + Slack-error string classifier.
- [`webhook/slack-webhook`](./src/webhook/slack-webhook.md) — incoming-webhook client.
- [`otel/metrics`](./src/otel/metrics.md) — four OpenTelemetry instruments.
- [`fakes/fake-fetch`](./src/fakes/fake-fetch.md) — deterministic `FetchLike` test double.

## Error codes

All eight reasons land under the `SLACK.*` namespace:

- `SLACK.API_ERROR` — generic non-ok response from the Slack API.
- `SLACK.AUTH_ERROR` — token rejected (HTTP 401/403, `invalid_auth`, `token_revoked`, `account_inactive`).
- `SLACK.RATE_LIMITED` — HTTP 429; `context.retryAfterMs` carries parsed delay.
- `SLACK.CHANNEL_NOT_FOUND` — HTTP 404 or `channel_not_found` / `is_archived` / `not_in_channel`.
- `SLACK.WORKSPACE_NOT_FOUND` — `team_not_found` / `no_workspace`.
- `SLACK.CONFIG_MISSING` — empty/invalid token or webhook URL at construct time.
- `SLACK.WEBHOOK_FAILED` — webhook POST returned non-2xx (non-auth).
- `SLACK.TIMEOUT` — internal `timeoutMs` fired OR caller `AbortSignal` aborted OR network failure.

## OpenTelemetry

Four instruments under meter `@suaveplan/slack-client@0.1.0`:

- `slack.requests` (counter) — `{ method, outcome }`
- `slack.errors` (counter) — `{ method, code }`
- `slack.latency_ms` (histogram, unit `ms`) — `{ method, outcome }`
- `slack.webhook_sends` (counter) — `{ outcome }`

## License

MIT