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

Documentation tree

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

Install

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

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 — SLACK_CODES registry + 8 typed error subclasses.
types/slack-client — public shapes.
schemas/schemas — Zod boundary schemas.
client/slack-api-client — Slack Web API client.
client/retry-after — Retry-After / x-ratelimit-reset parser.
client/classify — HTTP-status + Slack-error string classifier.
webhook/slack-webhook — incoming-webhook client.
otel/metrics — four OpenTelemetry instruments.
fakes/fake-fetch — 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