88 lines
5.4 KiB
Markdown
88 lines
5.4 KiB
Markdown
# @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
|
|
|